@molecule/app-auth 1.0.0

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * Client-side authentication interface for molecule.dev.
+ *
+ * Provides a unified auth API that works across different auth strategies
+ * (JWT, session, OAuth, etc.): `createJWTAuthClient` builds a fetch-based
+ * client; `setClient`/`getClient` bond it; `login`/`logout`/`register`/
+ * `isAuthenticated`/`getUser` delegate to the bonded client. Framework
+ * bindings (e.g. `AuthProvider`/`useAuth` in `@molecule/app-react`) wrap the
+ * same client.
+ *
+ * @remarks
+ * - **A page reload "logging the user out" is the config default, not a bug.**
+ *   Token storage defaults to `'memory'` (the secure default — a localStorage
+ *   bearer token is XSS-exfiltratable). Staying signed in across reloads works
+ *   by calling `client.initialize()` once at startup: it re-fetches
+ *   `currentUserEndpoint` (default `/users/me`) with the httpOnly cookie the
+ *   API set at login. Wire `initialize()`; do NOT "fix" reload-logout by
+ *   copying tokens into localStorage.
+ * - **Endpoint defaults must match your API's real routes** (`/auth/login`,
+ *   `/auth/register`, `/auth/refresh`, `/users/logout`, `/users/me`, …).
+ *   Align them via `createJWTAuthClient({ baseURL, ...endpoints })` — never by
+ *   hand-editing fetch calls in components.
+ * - Client-side auth state is UX only — the server enforces authorization on
+ *   every request; hiding a screen is not protection.
+ *
+ * @example
+ * ```typescript
+ * import { createJWTAuthClient, setClient } from '@molecule/app-auth'
+ *
+ * const client = createJWTAuthClient({ baseURL: '/api' })
+ * setClient(client)
+ * await client.initialize() // restore the session from the httpOnly cookie
+ *
+ * // anywhere in the app
+ * import { getUser, isAuthenticated, login, logout } from '@molecule/app-auth'
+ * await login({ email, password })
+ * if (isAuthenticated()) console.log(getUser()?.email)
+ * ```
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] Logging in with VALID credentials on the real login screen resolves
+ *   `login()` and flips AuthState to `authenticated: true` with `getUser()`
+ *   returning the actual UserProfile — the UI shows that user's own `email` /
+ *   `name` / `avatar`, never a placeholder or a different account.
+ * - [ ] A WRONG password shows a visible error (AuthState `error` is set and
+ *   the promise rejects) and establishes NO session: `isAuthenticated()` stays
+ *   false and no protected screen becomes reachable.
+ * - [ ] Registering through the sign-up form calls `register()`, creates the
+ *   account, and lands authenticated (`authenticated: true`, `user` populated)
+ *   on the app's post-signup screen — not back on the login form. If the flow
+ *   shows an email-verification / "check your inbox" step, it must be genuinely
+ *   backed (this client's `register()` returns an authenticated session
+ *   directly and exposes no verify method) — never a dead screen the auth
+ *   contract cannot advance past.
+ * - [ ] Logout calls `logout()` and clears the session (`authenticated: false`,
+ *   `user: null`, tokens cleared); afterward every protected screen redirects
+ *   back to login.
+ * - [ ] Visiting a protected route while logged OUT redirects to login (the
+ *   guard reads `isAuthenticated()`), and after authenticating you land back on
+ *   the originally-requested screen rather than a generic home.
+ * - [ ] The session survives a FULL page reload: after login, hard-reload →
+ *   `initialize()` restores it from the httpOnly cookie (via
+ *   `currentUserEndpoint`, default `/users/me`) and you stay signed in — you are
+ *   NOT bounced to login. (The in-memory bearer token is dropped by design; the
+ *   cookie restore is what keeps you in — do not "fix" this by writing the token
+ *   to localStorage.)
+ * - [ ] Password reset round-trips: `requestPasswordReset({ email })` then
+ *   `confirmPasswordReset({ token, password })` with the emailed token, after
+ *   which `login()` with the NEW password succeeds and the OLD password no
+ *   longer works.
+ * - [ ] Authorization holds: a signed-in user only ever reads/edits their OWN
+ *   record (`getUser()` is the caller's profile, never another user's); the
+ *   bearer token lives in memory only — it is never written to
+ *   localStorage / sessionStorage where another script could read it; and an
+ *   expired/invalid token fails closed — the app re-authenticates (`refresh()`
+ *   or `logout()`), never silently serving another user's data.
+ *
+ * @module
+ */
+export * from './client.js';
+export * from './provider.js';
+export * from './token.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Auth client bond accessor.
+ *
+ * Bond packages call `setClient()` during setup. Application code uses
+ * `getClient()` to access login, logout, register, token management,
+ * and auth state subscription.
+ *
+ * @module
+ */
+import type { AuthClient, UserProfile } from './types.js';
+/**
+ * Registers an auth client as the active singleton. Called by bond
+ * packages during application startup.
+ *
+ * @param client - The auth client implementation to bond.
+ */
+export declare const setClient: (client: AuthClient) => void;
+/**
+ * Retrieves the bonded auth client, throwing if none is configured.
+ *
+ * @returns The bonded auth client.
+ * @throws {Error} If no auth client has been bonded.
+ */
+export declare const getClient: <T extends UserProfile = UserProfile>() => AuthClient<T>;
+/**
+ * Checks whether an auth client is currently bonded.
+ *
+ * @returns `true` if an auth client is bonded.
+ */
+export declare const hasClient: () => boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAIzD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,UAAU,KAAG,IAE9C,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,WAAW,GAAG,WAAW,OAAK,UAAU,CAAC,CAAC,CAE7E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,OAE5B,CAAA"}

package/dist/provider.js

@@ -0,0 +1,38 @@
+/**
+ * Auth client bond accessor.
+ *
+ * Bond packages call `setClient()` during setup. Application code uses
+ * `getClient()` to access login, logout, register, token management,
+ * and auth state subscription.
+ *
+ * @module
+ */
+import { bond, isBonded, require as bondRequire } from '@molecule/app-bond';
+const BOND_TYPE = 'auth-client';
+/**
+ * Registers an auth client as the active singleton. Called by bond
+ * packages during application startup.
+ *
+ * @param client - The auth client implementation to bond.
+ */
+export const setClient = (client) => {
+    bond(BOND_TYPE, client);
+};
+/**
+ * Retrieves the bonded auth client, throwing if none is configured.
+ *
+ * @returns The bonded auth client.
+ * @throws {Error} If no auth client has been bonded.
+ */
+export const getClient = () => {
+    return bondRequire(BOND_TYPE);
+};
+/**
+ * Checks whether an auth client is currently bonded.
+ *
+ * @returns `true` if an auth client is bonded.
+ */
+export const hasClient = () => {
+    return isBonded(BOND_TYPE);
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAI3E,MAAM,SAAS,GAAG,aAAa,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAkB,EAAQ,EAAE;IACpD,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;AACzB,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAuD,EAAE;IAChF,OAAO,WAAW,CAAgB,SAAS,CAAC,CAAA;AAC9C,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAY,EAAE;IACrC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA"}

package/dist/token.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Token management utilities for authentication.
+ *
+ * Provides token storage, JWT parsing, and expiration checking.
+ *
+ * @module
+ */
+import type { StorageAdapter, TokenStorage } from './types.js';
+/**
+ * Creates a token storage implementation backed by either in-memory
+ * storage or a custom `StorageAdapter`.
+ *
+ * @param storage - `'memory'` for in-memory storage (lost on refresh),
+ *   or a `StorageAdapter` for persistent storage.
+ * @param prefix - Key prefix for storage items (default: `'molecule:auth:'`).
+ * @returns A `TokenStorage` instance.
+ *
+ * @example
+ * ```typescript
+ * // In-memory storage (default)
+ * const storage = createTokenStorage('memory')
+ *
+ * // Custom storage adapter from @molecule/app-storage
+ * import { getProvider } from '@molecule/app-storage'
+ * const provider = getProvider()
+ * const storage = createTokenStorage({
+ *   getItem: (key) => provider.get(key),
+ *   setItem: (key, value) => provider.set(key, value),
+ *   removeItem: (key) => provider.remove(key),
+ * })
+ * ```
+ */
+export declare const createTokenStorage: (storage?: "memory" | StorageAdapter, prefix?: string) => TokenStorage;
+/**
+ * Parses a JWT token payload without verification (base64-decodes
+ * the payload segment).
+ *
+ * @param token - The raw JWT string (header.payload.signature).
+ * @returns The decoded payload object, or `null` if parsing fails.
+ */
+export declare const parseJWT: <T = Record<string, unknown>>(token: string) => T | null;
+/**
+ * Checks if a JWT token is expired (or will expire within the buffer window).
+ *
+ * @param token - The raw JWT string.
+ * @param bufferSeconds - Seconds before actual expiry to consider the token expired (default: 0).
+ * @returns `true` if the token is expired or lacks an `exp` claim.
+ */
+export declare const isTokenExpired: (token: string, bufferSeconds?: number) => boolean;
+/**
+ * Returns the expiration timestamp of a JWT token in milliseconds.
+ *
+ * @param token - The raw JWT string.
+ * @returns The expiration time in ms since epoch, or `null` if the token has no `exp` claim.
+ */
+export declare const getTokenExpiration: (token: string) => number | null;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAe,MAAM,YAAY,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAS,QAAQ,GAAG,cAAyB,EAC7C,SAAQ,MAAyB,KAChC,YAoDF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,MAAM,KAAG,CAAC,GAAG,IAWzE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,gBAAe,MAAU,KAAG,OAMzE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,IAI3D,CAAA"}

package/dist/token.js

@@ -0,0 +1,133 @@
+/**
+ * Token management utilities for authentication.
+ *
+ * Provides token storage, JWT parsing, and expiration checking.
+ *
+ * @module
+ */
+/**
+ * Creates a token storage implementation backed by either in-memory
+ * storage or a custom `StorageAdapter`.
+ *
+ * @param storage - `'memory'` for in-memory storage (lost on refresh),
+ *   or a `StorageAdapter` for persistent storage.
+ * @param prefix - Key prefix for storage items (default: `'molecule:auth:'`).
+ * @returns A `TokenStorage` instance.
+ *
+ * @example
+ * ```typescript
+ * // In-memory storage (default)
+ * const storage = createTokenStorage('memory')
+ *
+ * // Custom storage adapter from @molecule/app-storage
+ * import { getProvider } from '@molecule/app-storage'
+ * const provider = getProvider()
+ * const storage = createTokenStorage({
+ *   getItem: (key) => provider.get(key),
+ *   setItem: (key, value) => provider.set(key, value),
+ *   removeItem: (key) => provider.remove(key),
+ * })
+ * ```
+ */
+export const createTokenStorage = (storage = 'memory', prefix = 'molecule:auth:') => {
+    const memoryStore = {};
+    // Determine storage adapter
+    let adapter = null;
+    if (typeof storage === 'object') {
+        adapter = storage;
+    }
+    const get = (key) => {
+        if (adapter) {
+            return adapter.getItem(prefix + key);
+        }
+        return memoryStore[key] ?? null;
+    };
+    const set = (key, value) => {
+        if (adapter) {
+            if (value === null) {
+                adapter.removeItem(prefix + key);
+            }
+            else {
+                adapter.setItem(prefix + key, value);
+            }
+        }
+        else {
+            memoryStore[key] = value;
+        }
+    };
+    return {
+        getAccessToken: () => get('accessToken'),
+        setAccessToken: (token) => set('accessToken', token),
+        getRefreshToken: () => get('refreshToken'),
+        setRefreshToken: (token) => set('refreshToken', token),
+        getUser: () => {
+            const data = get('user');
+            if (!data)
+                return null;
+            try {
+                return JSON.parse(data);
+            }
+            catch (_error) {
+                // Stored value is not valid JSON (corrupted/stale); returning null is safe
+                return null;
+            }
+        },
+        setUser: (user) => {
+            set('user', user ? JSON.stringify(user) : null);
+        },
+        clear: () => {
+            set('accessToken', null);
+            set('refreshToken', null);
+            set('user', null);
+        },
+    };
+};
+/**
+ * Parses a JWT token payload without verification (base64-decodes
+ * the payload segment).
+ *
+ * @param token - The raw JWT string (header.payload.signature).
+ * @returns The decoded payload object, or `null` if parsing fails.
+ */
+export const parseJWT = (token) => {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = parts[1];
+        const decoded = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
+        return JSON.parse(decoded);
+    }
+    catch (_error) {
+        // Malformed base64 or invalid JSON payload; returning null is the documented contract
+        return null;
+    }
+};
+/**
+ * Checks if a JWT token is expired (or will expire within the buffer window).
+ *
+ * @param token - The raw JWT string.
+ * @param bufferSeconds - Seconds before actual expiry to consider the token expired (default: 0).
+ * @returns `true` if the token is expired or lacks an `exp` claim.
+ */
+export const isTokenExpired = (token, bufferSeconds = 0) => {
+    const payload = parseJWT(token);
+    if (!payload || !payload.exp)
+        return true;
+    const expiresAt = payload.exp * 1000;
+    const now = Date.now() + bufferSeconds * 1000;
+    return now >= expiresAt;
+};
+/**
+ * Returns the expiration timestamp of a JWT token in milliseconds.
+ *
+ * @param token - The raw JWT string.
+ * @returns The expiration time in ms since epoch, or `null` if the token has no `exp` claim.
+ */
+export const getTokenExpiration = (token) => {
+    const payload = parseJWT(token);
+    if (!payload || !payload.exp)
+        return null;
+    return payload.exp * 1000;
+};
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"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"}