@molecule/app-auth 1.2.0 → 1.2.1

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-15T09:33:35.638Z
+Generated: 2026-10-16T00:48:55.816Z
 -->
 
 # @molecule/app-auth
@@ -50,6 +50,203 @@ npm install @molecule/app-auth @molecule/app-bond @molecule/app-i18n @molecule/a
 
 ### Interfaces
 
+#### `UserProfile`
+
+User profile information.
+
+```typescript
+interface UserProfile {
+  /**
+   * Unique user identifier.
+   */
+  id: string
+
+  /**
+   * User's email address.
+   */
+  email?: string
+
+  /**
+   * User's display name.
+   */
+  name?: string
+
+  /**
+   * User's avatar/profile image URL.
+   */
+  avatar?: string
+
+  /**
+   * User's roles or permissions.
+   */
+  roles?: string[]
+
+  /**
+   * Additional metadata.
+   */
+  metadata?: Record<string, unknown>
+}
+```
+
+#### `LoginCredentials`
+
+Email/password login credentials with optional "remember me" flag.
+
+```typescript
+interface LoginCredentials {
+  /**
+   * Email or username.
+   */
+  email: string
+
+  /**
+   * Password.
+   */
+  password: string
+
+  /**
+   * Whether to remember the session.
+   */
+  remember?: boolean
+
+  /**
+   * Time-based one-time password (TOTP) from the user's authenticator app.
+   * Required when the account has two-factor auth enabled — the server
+   * answers `{ twoFactorRequired: true }` (HTTP 206) until a valid token
+   * is supplied.
+   */
+  twoFactorToken?: string
+}
+```
+
+#### `RegisterData`
+
+New user registration payload (email, password, optional name and metadata).
+
+```typescript
+interface RegisterData {
+  /**
+   * Email address.
+   */
+  email: string
+
+  /**
+   * Password.
+   */
+  password: string
+
+  /**
+   * Display name.
+   */
+  name?: string
+
+  /**
+   * Additional registration fields.
+   */
+  metadata?: Record<string, unknown>
+}
+```
+
+#### `AuthResult`
+
+Successful authentication result containing the user, access/refresh tokens, and expiration.
+
+```typescript
+interface AuthResult<T = UserProfile> {
+  /**
+   * Authenticated user.
+   */
+  user: T
+
+  /**
+   * Access token (for token-based auth).
+   */
+  accessToken?: string
+
+  /**
+   * Refresh token (for token-based auth).
+   */
+  refreshToken?: string
+
+  /**
+   * Token expiration time (Unix timestamp).
+   */
+  expiresAt?: number
+
+  /**
+   * Set (with HTTP 206) when the account has two-factor auth enabled and the
+   * login did not include a valid `twoFactorToken`. No tokens or user are
+   * issued until login is retried with the TOTP — callers must check this
+   * flag BEFORE treating the result as a successful authentication.
+   */
+  twoFactorRequired?: boolean
+}
+```
+
+#### `PasswordResetRequest`
+
+Password reset request data.
+
+```typescript
+interface PasswordResetRequest {
+  /**
+   * Email address.
+   */
+  email: string
+}
+```
+
+#### `PasswordResetConfirm`
+
+Password reset confirmation data.
+
+```typescript
+interface PasswordResetConfirm {
+  /**
+   * Reset token.
+   */
+  token: string
+
+  /**
+   * New password.
+   */
+  password: string
+}
+```
+
+#### `AuthState`
+
+Reactive authentication state snapshot (initialized, authenticated, user, loading, and error).
+
+```typescript
+interface AuthState<T = UserProfile> {
+  /**
+   * Whether auth state has been initialized.
+   */
+  initialized: boolean
+
+  /**
+   * Whether the user is authenticated.
+   */
+  authenticated: boolean
+
+  /**
+   * Current user (if authenticated).
+   */
+  user: T | null
+
+  /**
+   * Whether an auth operation is in progress.
+   */
+  loading: boolean
+
+  /**
+   * Last auth error (if any).
+   */
+  error: string | null
+}
+```
+
 #### `AuthClient`
 
 Auth client interface that all auth bond packages must implement.
@@ -172,6 +369,19 @@ interface AuthClient<T = UserProfile> {
 }
 ```
 
+#### `StorageAdapter`
+
+Minimal key-value storage adapter used by the auth client for
+persisting tokens and user data.
+
+```typescript
+interface StorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+```
+
 #### `AuthClientConfig`
 
 Configuration options for creating an auth client, including API
@@ -323,236 +533,26 @@ interface AuthClientConfig {
 }
 ````
 
-#### `AuthResult`
+#### `TokenStorage`
 
-Successful authentication result containing the user, access/refresh tokens, and expiration.
+Internal token storage interface for reading and writing access/refresh
+tokens and user profile data.
 
 ```typescript
-interface AuthResult<T = UserProfile> {
-  /**
-   * Authenticated user.
-   */
-  user: T
-
-  /**
-   * Access token (for token-based auth).
-   */
-  accessToken?: string
-
-  /**
-   * Refresh token (for token-based auth).
-   */
-  refreshToken?: string
-
-  /**
-   * Token expiration time (Unix timestamp).
-   */
-  expiresAt?: number
-
-  /**
-   * Set (with HTTP 206) when the account has two-factor auth enabled and the
-   * login did not include a valid `twoFactorToken`. No tokens or user are
-   * issued until login is retried with the TOTP — callers must check this
-   * flag BEFORE treating the result as a successful authentication.
-   */
-  twoFactorRequired?: boolean
+interface TokenStorage {
+  getAccessToken(): string | null
+  setAccessToken(token: string | null): void
+  getRefreshToken(): string | null
+  setRefreshToken(token: string | null): void
+  getUser<T = UserProfile>(): T | null
+  setUser<T = UserProfile>(user: T | null): void
+  clear(): void
 }
 ```
 
-#### `AuthState`
+### Types
 
-Reactive authentication state snapshot (initialized, authenticated, user, loading, and error).
-
-```typescript
-interface AuthState<T = UserProfile> {
-  /**
-   * Whether auth state has been initialized.
-   */
-  initialized: boolean
-
-  /**
-   * Whether the user is authenticated.
-   */
-  authenticated: boolean
-
-  /**
-   * Current user (if authenticated).
-   */
-  user: T | null
-
-  /**
-   * Whether an auth operation is in progress.
-   */
-  loading: boolean
-
-  /**
-   * Last auth error (if any).
-   */
-  error: string | null
-}
-```
-
-#### `LoginCredentials`
-
-Email/password login credentials with optional "remember me" flag.
-
-```typescript
-interface LoginCredentials {
-  /**
-   * Email or username.
-   */
-  email: string
-
-  /**
-   * Password.
-   */
-  password: string
-
-  /**
-   * Whether to remember the session.
-   */
-  remember?: boolean
-
-  /**
-   * Time-based one-time password (TOTP) from the user's authenticator app.
-   * Required when the account has two-factor auth enabled — the server
-   * answers `{ twoFactorRequired: true }` (HTTP 206) until a valid token
-   * is supplied.
-   */
-  twoFactorToken?: string
-}
-```
-
-#### `PasswordResetConfirm`
-
-Password reset confirmation data.
-
-```typescript
-interface PasswordResetConfirm {
-  /**
-   * Reset token.
-   */
-  token: string
-
-  /**
-   * New password.
-   */
-  password: string
-}
-```
-
-#### `PasswordResetRequest`
-
-Password reset request data.
-
-```typescript
-interface PasswordResetRequest {
-  /**
-   * Email address.
-   */
-  email: string
-}
-```
-
-#### `RegisterData`
-
-New user registration payload (email, password, optional name and metadata).
-
-```typescript
-interface RegisterData {
-  /**
-   * Email address.
-   */
-  email: string
-
-  /**
-   * Password.
-   */
-  password: string
-
-  /**
-   * Display name.
-   */
-  name?: string
-
-  /**
-   * Additional registration fields.
-   */
-  metadata?: Record<string, unknown>
-}
-```
-
-#### `StorageAdapter`
-
-Minimal key-value storage adapter used by the auth client for
-persisting tokens and user data.
-
-```typescript
-interface StorageAdapter {
-  getItem(key: string): string | null
-  setItem(key: string, value: string): void
-  removeItem(key: string): void
-}
-```
-
-#### `TokenStorage`
-
-Internal token storage interface for reading and writing access/refresh
-tokens and user profile data.
-
-```typescript
-interface TokenStorage {
-  getAccessToken(): string | null
-  setAccessToken(token: string | null): void
-  getRefreshToken(): string | null
-  setRefreshToken(token: string | null): void
-  getUser<T = UserProfile>(): T | null
-  setUser<T = UserProfile>(user: T | null): void
-  clear(): void
-}
-```
-
-#### `UserProfile`
-
-User profile information.
-
-```typescript
-interface UserProfile {
-  /**
-   * Unique user identifier.
-   */
-  id: string
-
-  /**
-   * User's email address.
-   */
-  email?: string
-
-  /**
-   * User's display name.
-   */
-  name?: string
-
-  /**
-   * User's avatar/profile image URL.
-   */
-  avatar?: string
-
-  /**
-   * User's roles or permissions.
-   */
-  roles?: string[]
-
-  /**
-   * Additional metadata.
-   */
-  metadata?: Record<string, unknown>
-}
-```
-
-### Types
-
-#### `AuthEvent`
+#### `AuthEvent`
 
 Auth event types.
 
@@ -590,19 +590,16 @@ function createJWTAuthClient(config?: AuthClientConfig): AuthClient<T>
 
 **Returns:** A fully configured `AuthClient` instance.
 
-#### `createTokenStorage(storage, prefix)`
+#### `setClient(client)`
 
-Creates a token storage implementation backed by either in-memory
-storage or a custom `StorageAdapter`.
+Registers an auth client as the active singleton. Called by bond
+packages during application startup.
 
 ```typescript
-function createTokenStorage(storage?: 'memory' | StorageAdapter, prefix?: string): TokenStorage
+function setClient(client: AuthClient<UserProfile>): void
 ```
 
-- `storage` — `'memory'` for in-memory storage (lost on refresh), or a `StorageAdapter` for persistent storage.
-- `prefix` — Key prefix for storage items (default: `'molecule:auth:'`).
-
-**Returns:** A `TokenStorage` instance.
+- `client` — The auth client implementation to bond.
 
 #### `getClient()`
 
@@ -614,37 +611,67 @@ function getClient(): AuthClient<T>
 
 **Returns:** The bonded auth client.
 
-#### `getTokenExpiration(token)`
+#### `hasClient()`
 
-Returns the expiration timestamp of a JWT token in milliseconds.
+Checks whether an auth client is currently bonded.
 
 ```typescript
-function getTokenExpiration(token: string): number | null
+function hasClient(): boolean
 ```
 
-- `token` — The raw JWT string.
+**Returns:** `true` if an auth client is bonded.
 
-**Returns:** The expiration time in ms since epoch, or `null` if the token has no `exp` claim.
+#### `createTokenStorage(storage, prefix)`
 
-#### `getUser()`
+Creates a token storage implementation backed by either in-memory
+storage or a custom `StorageAdapter`.
 
-Returns the current user profile, or `null` if not authenticated.
+```typescript
+function createTokenStorage(storage?: 'memory' | StorageAdapter, prefix?: string): TokenStorage
+```
+
+- `storage` — `'memory'` for in-memory storage (lost on refresh), or a `StorageAdapter` for persistent storage.
+- `prefix` — Key prefix for storage items (default: `'molecule:auth:'`).
+
+**Returns:** A `TokenStorage` instance.
+
+#### `parseJWT(token)`
+
+Parses a JWT token payload without verification (base64-decodes
+the payload segment).
 
 ```typescript
-function getUser(): T | null
+function parseJWT(token: string): T | null
 ```
 
-**Returns:** The user profile, or `null` if not authenticated.
+- `token` — The raw JWT string (header.payload.signature).
 
-#### `hasClient()`
+**Returns:** The decoded payload object, or `null` if parsing fails.
 
-Checks whether an auth client is currently bonded.
+#### `isTokenExpired(token, bufferSeconds)`
+
+Checks if a JWT token is expired (or will expire within the buffer window).
 
 ```typescript
-function hasClient(): boolean
+function isTokenExpired(token: string, bufferSeconds?: number): boolean
 ```
 
-**Returns:** `true` if an auth client is bonded.
+- `token` — The raw JWT string.
+- `bufferSeconds` — Seconds before actual expiry to consider the token expired (default: 0).
+
+**Returns:** `true` if the token is expired or lacks an `exp` claim.
+
+#### `getTokenExpiration(token)`
+
+Returns the expiration timestamp of a JWT token in milliseconds.
+
+```typescript
+function getTokenExpiration(token: string): number | null
+```
+
+- `token` — The raw JWT string.
+
+**Returns:** The expiration time in ms since epoch, or `null` if the token has no `exp` claim.
 
 #### `isAuthenticated()`
 
@@ -656,18 +683,15 @@ function isAuthenticated(): boolean
 
 **Returns:** `true` if the user has an active session.
 
-#### `isTokenExpired(token, bufferSeconds)`
+#### `getUser()`
 
-Checks if a JWT token is expired (or will expire within the buffer window).
+Returns the current user profile, or `null` if not authenticated.
 
 ```typescript
-function isTokenExpired(token: string, bufferSeconds?: number): boolean
+function getUser(): T | null
 ```
 
-- `token` — The raw JWT string.
-- `bufferSeconds` — Seconds before actual expiry to consider the token expired (default: 0).
-
-**Returns:** `true` if the token is expired or lacks an `exp` claim.
+**Returns:** The user profile, or `null` if not authenticated.
 
 #### `login(credentials)`
 
@@ -691,19 +715,6 @@ function logout(): Promise<void>
 
 **Returns:** A promise that resolves when logout completes.
 
-#### `parseJWT(token)`
-
-Parses a JWT token payload without verification (base64-decodes
-the payload segment).
-
-```typescript
-function parseJWT(token: string): T | null
-```
-
-- `token` — The raw JWT string (header.payload.signature).
-
-**Returns:** The decoded payload object, or `null` if parsing fails.
-
 #### `register(data)`
 
 Registers a new user account.
@@ -716,17 +727,6 @@ function register(data: RegisterData): Promise<AuthResult<UserProfile>>
 
 **Returns:** The auth result containing tokens and user profile.
 
-#### `setClient(client)`
-
-Registers an auth client as the active singleton. Called by bond
-packages during application startup.
-
-```typescript
-function setClient(client: AuthClient<UserProfile>): void
-```
-
-- `client` — The auth client implementation to bond.
-
 ## Injection Notes
 
 ### Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-auth",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Client-side authentication interface for molecule.dev",
   "type": "module",
   "main": "dist/index.js",