Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/auth-store.ts
• src/auth-client.ts
• src/auth-api.ts
• src/types.ts
• src/react/login-form.tsx
• src/react/register-form.tsx
• src/auth-guard.ts
• src/extract-token.ts

@cellarnode/auth is a comprehensive authentication library designed for CellarNode dashboards. It provides a shared OTP-based (One-Time Password) authentication system comprising a framework-agnostic core (token store and API client) and a set of React UI components. The system is built to handle user registration, secure login via email-delivered codes, and automated token management including background refreshes.

Sources: README.md:1-5, package.json:3-5

System Architecture

The project is structured into three primary layers: the Auth Store for state management, the Auth Client for network communication, and the Auth API for high-level business logic. React components sit atop these layers to provide user interfaces for login, registration, and access control.

Core Component Relationships

The following diagram illustrates how the core modules interact to provide authentication services.

Authentication Flow

The authentication process relies on a two-step OTP verification. Users first request a code via email and then submit that code to receive a JSON Web Token (JWT).

OTP Verification Sequence

This sequence shows the interaction between the UI, the API wrapper, and the underlying storage during a login attempt.

Core Modules

Auth Store (src/auth-store.ts)

The store manages the lifecycle of the access token in memory. It includes a proactive refresh mechanism that automatically attempts to renew the token before it expires, using a configurable buffer.

• Token Deduplication: Concurrent calls to ensureAccessToken are deduplicated to prevent multiple simultaneous refresh requests.
• Refresh Timer: Uses setTimeout to trigger a refresh request based on the expiresIn value returned by the server.

Sources: src/auth-store.ts:13-21, src/auth-store.ts:71-77

Auth Client (src/auth-client.ts)

A wrapper around the native fetch API that automatically injects Authorization headers.

• Automatic Retry: If a request fails with a 401 status, the client attempts to refresh the token once via the store and retries the original request.
• Error Handling: Transforms failed responses into structured AuthError objects containing server-provided codes (e.g., OTP_INVALID).

Sources: src/auth-client.ts:47-75, src/types.ts:42-53

Auth API (src/auth-api.ts)

Provides high-level methods for authentication actions. It uses extractAccessToken to handle various response formats from the backend, ensuring compatibility with different API implementations.

Sources: src/auth-api.ts:35-48, src/extract-token.ts:1-20

React Components

The library exports several specialized React components for building authentication interfaces.

Component	Purpose	Key Props
LoginForm	Handles OTP login flow with email and code steps.	userType, authApi, onLoginSuccess
RegisterForm	User registration for importers or producers.	userType, onRegistered, authApi
UnauthorizedPage	Portal-aware access denied view.	expectedRole, dashboardLinks
SquircleShift	Animated 3D background for login screens.	theme, className

Sources: src/react/login-form.tsx:32-65, src/react/register-form.tsx:10-15, src/react/unauthorized.tsx:6-11

Login Logic

The LoginForm component manages internal state for countdown timers (resend availability and code expiry) and visual feedback like shaking animations on invalid codes.

Data Models

User and Registration

Field	Type	Description
id	string	Unique user identifier.
email	string	Registered email address.
userType	importer | producer | admin	Defines access level and dashboard routing.
orgId	string | null	Associated organization ID.
roles	string[]	Specific permissions or roles.

Sources: src/types.ts:1-11

Access Control

The library provides a validateUserType utility used to ensure users are accessing the correct portal. The UnauthorizedPage component leverages this by showing a "Wrong Portal" message if a user is authenticated but lacks the expectedRole, providing links to the correct dashboard.

Sources: src/auth-guard.ts:3-5, src/react/unauthorized.tsx:23-45

Conclusion

The CellarNode Auth system provides a robust foundation for secure, OTP-based authentication. By separating the logic of token management (Store), network communication (Client), and business operations (API), it offers a flexible architecture that supports both framework-agnostic integrations and specialized React-based dashboard workflows.