Getting Started

Relevant source files

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

• README.md
• package.json
• src/auth-store.ts
• src/auth-client.ts
• src/auth-api.ts
• src/types.ts
• src/react/index.ts

The @cellarnode/auth package provides a shared authentication infrastructure specifically designed for CellarNode dashboards. It encompasses an OTP-based authentication flow, a managed token store with automatic background refreshing, a specialized API client for authenticated requests, and a suite of React UI components for login, registration, and access control.

The system is architected into two primary layers: a framework-agnostic core (Store, Client, and API) and a React-specific UI layer. This allows developers to manage authentication logic independently of the view while utilizing pre-built components for standard user flows like OTP verification.
Sources: package.json:3-5, README.md:3-5

Installation and Environment Setup

To begin using the library, install it via npm along with its required peer dependencies. The package requires Node.js version 20.19.0 or higher.

npm install @cellarnode/auth

Sources: README.md:9-11, package.json:59-61

Tailwind CSS Integration

If using the React components, you must ensure your Tailwind CSS configuration scans the package for utility classes to render the UI correctly.

@source "../node_modules/@cellarnode/auth/dist/**/*.js";

Sources: README.md:34-36

Core Architecture

The authentication system relies on three interconnected modules that handle token persistence, request interception, and API communication.

Module Relationship

The diagram below illustrates how the Store, Client, and API modules interact to handle authenticated requests and token lifecycle management.

The Auth Store manages the JWT in memory, the Auth Client wraps the native fetch API to inject credentials, and the Auth API provides high-level methods for specific authentication actions like requestOtp or verifyOtp.
Sources: src/auth-store.ts:7, src/auth-client.ts:6, src/auth-api.ts:16

1. Initialization

Initialization involves creating the store first, then passing it to the client, and finally wrapping both in the API factory.

Component	Function	Key Configuration
Auth Store	createAuthStore	baseUrl, refreshPath, refreshBuffer
Auth Client	createAuthClient	baseUrl, store, onAuthFailure
Auth API	createAuthApi	client, store

Sources: src/types.ts:54-75, src/auth-store.ts:7, src/auth-client.ts:6, src/auth-api.ts:16

Data Flow: OTP Authentication

The primary authentication method is a two-step One-Time Password (OTP) flow.

Token Lifecycle & Refresh

The AuthStore automatically schedules a background refresh of the access token. This occurs refreshBuffer seconds (default: 60) before the token expires to ensure uninterrupted session validity.

• Automatic Refresh: Managed via setTimeout based on the expiresIn value returned by the server.
• Retry Logic: The AuthClient will attempt to refresh the token exactly once if a 401 Unauthorized error is encountered on a request that requires authentication.
  Sources: src/auth-store.ts:14-20, src/auth-client.ts:60-70

React Integration

The package exports high-level React components that are pre-configured to work with the core modules.

Available Components

• LoginForm: Handles the email entry and OTP verification steps, including countdown timers for code expiration.
• RegisterForm: Provides a standard registration interface for "importer" or "producer" user types.
• UnauthorizedPage: A portal-aware guard page that redirects users if they attempt to access a dashboard not associated with their userType.
• SquircleShift: A background visual component used in the login/registration layouts.
  Sources: src/react/index.ts:5-17, src/react/unauthorized.tsx:15-30

Example React Usage

import { LoginForm } from "@cellarnode/auth/react";

<LoginForm
  userType="producer"
  brandName="CellarNode"
  authApi={authApi}
  authStore={authStore}
  onLoginSuccess={() => window.location.assign("/dashboard")}
/>

Sources: src/react/login-form.tsx:32-50, README.md:27-29

Authentication Guards

User access control is managed via the userType property on the AuthUser object. The system supports three distinct roles: importer, producer, and admin.

User Type	Description
importer	Standard importer account dashboard access.
producer	Standard producer account dashboard access.
admin	Administrative access across platforms.

Validation is typically performed using the validateUserType helper:

import { validateUserType } from "@cellarnode/auth";

const isAllowed = validateUserType(user, "producer");

Sources: src/types.ts:1-10, src/auth-guard.ts:3-5

Conclusion

The @cellarnode/auth system provides a robust, type-safe foundation for managing user sessions within the CellarNode ecosystem. By combining a centralized token store with automated refresh logic and standardized React UI components, it ensures a consistent and secure authentication experience across multiple dashboard applications.