@molecule/app-auth 3.2.3 → 3.2.4

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-11-03T17:06:00.004Z
+Generated: 2026-11-04T14:20:03.859Z
 -->
 
 # @molecule/app-auth
@@ -706,189 +706,85 @@ interface AuthClient<
   T = UserProfile,
   TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
 > {
-  /**
-   * Returns the current authentication state snapshot.
-   *
-   * READING the state starts the client's one session restore when nobody has called
-   * {@link initialize} yet — lazily and exactly once, sharing the promise an explicit
-   * `initialize()` returns. A hook (`useAuth()`), a subscriber, `isAuthenticated()` and
-   * `getUser()` are reads too, so a client whose entry file dropped the template's
-   * `authClient.initialize()` line still restores instead of reporting `'loading'`
-   * forever.
-   */
+  /** Returns the current authentication state snapshot. */
   getState(): AuthState<T>
 
-  /**
-   * Returns whether the user is currently authenticated.
-   */
+  /** Returns whether the user is currently authenticated. */
   isAuthenticated(): boolean
 
-  /**
-   * Gets the current user.
-   */
+  /** Gets the current user. */
   getUser(): T | null
 
-  /**
-   * Optional ownership marker for the current session. Compare values only within
-   * this client: replacing or ending a session changes it, including re-adopting
-   * the same token and user. Profile updates and same-session refreshes keep it.
-   * Consumers can use it to discard stale async work without treating editable
-   * user fields as an immutable account identifier. Providers without this
-   * capability require the consumer's own stable identity check.
-   */
+  /** Optional ownership marker for the current session. */
   getSessionRevision?(): number
 
-  /**
-   * Updates the cached user object (state + persistent storage) without
-   * hitting the network. Intended for local refreshes after a per-app
-   * mutation (e.g., the user just PATCHed their own profile and the
-   * server returned the canonical row). A non-null profile does NOT change
-   * tokens or sign the client in: `authenticated` and `status` are unchanged,
-   * so an anonymous client stays anonymous. Use {@link login} /
-   * {@link register} for a credential exchange, or {@link setSession} when
-   * the token was issued outside the client.
-   *
-   * Passing `null` on a signed-in client, or while any session operation is
-   * pending, ends the local session: it clears the access token, refresh token
-   * and cached user, stops automatic refresh, and settles `authenticated: false`
-   * with `status: 'unauthenticated'` in one notification. Every older operation
-   * loses session ownership, and a persistent sign-out marker prevents a reload
-   * from restoring its credentials or a late cookie. A late credential exchange
-   * is revoked best-effort when a logout endpoint is configured, without blocking
-   * the caller. This method does not otherwise call the server for a settled
-   * session; use {@link logout} for explicit server revocation. On a settled
-   * anonymous client, `null` only clears the cached profile and leaves tokens
-   * and auth state unchanged.
-   */
+  /** Updates the cached user object (state + persistent storage) without hitting the network. */
   setUser(user: T | null): void
 
-  /**
-   * Gets the current access token.
-   */
+  /** Gets the current access token. */
   getAccessToken(): string | null
 
-  /**
-   * Stores the access token in the configured token storage adapter (in a
-   * browser, Web Storage; `'memory'` where no browser store exists). Use this
-   * to seed the token after an out-of-band exchange (e.g. the OAuth
-   * code→token redirect) instead of writing to `localStorage` directly,
-   * which would violate the storage contract and make a stored bearer token
-   * JS-readable (XSS-exfiltratable). Pass `null` to clear it.
-   *
-   * This changes token storage only: passing `null` does not by itself sign a
-   * signed-in client out, and a non-null token does not sign an anonymous
-   * client in (`authenticated` and `status` are unchanged). Use {@link logout}
-   * to end a session, or {@link setUser} with `null` for local-only sign-out.
-   * Use {@link login} / {@link register} for a credential exchange, or call
-   * {@link setSession} with the token and user to establish an already-issued
-   * session.
-   */
+  /** Stores the access token in the configured token storage adapter (in a browser, Web Storage; `'memory'` where no browser store exists). */
   setAccessToken(token: string | null): void
 
-  /**
-   * Adopts a session an out-of-band exchange already established: stores the
-   * access token (and the refresh token when given), caches the user, and
-   * sets the COMPLETE state — `initialized`, `authenticated`, `status:
-   * 'authenticated'`, no error — in one update, with one subscriber
-   * notification. Every hook reading the shared client sees the user as
-   * signed in immediately.
-   *
-   * This is the way to seed an OAuth/custom sign-in. Calling
-   * {@link setAccessToken} and {@link setUser} instead does NOT sign the
-   * client in.
-   */
+  /** Adopts a session an out-of-band exchange already established: stores the access token (and the refresh token when given), caches the user, and sets the COMPLET… */
   setSession(session: AuthSessionSeed<T>): void
 
-  /**
-   * Gets the refresh token.
-   */
+  /** Gets the refresh token. */
   getRefreshToken(): string | null
 
-  /**
-   * Logs in with credentials.
-   */
+  /** Logs in with credentials. */
   login(credentials: LoginCredentials): Promise<AuthResult<T>>
 
-  /**
-   * Logs out the current user. The server request is best-effort: a missing
-   * logout route (404), any other HTTP failure, or a network error never makes
-   * this method reject. It always clears the access token, refresh token and
-   * cached user, stops automatic refresh, and publishes one settled
-   * `authenticated: false`, `status: 'unauthenticated'` transition. Every pending
-   * session operation loses ownership; a persistent marker prevents reload from
-   * restoring an older session, and late credentials are revoked best-effort.
-   *
-   * When the API has no logout route, set {@link AuthClientConfigOptions.logoutEndpoint}
-   * to `null` (or `''`) to skip the request. Local sign-out still happens.
-   */
+  /** Logs out the current user. */
   logout(): Promise<void>
 
-  /**
-   * Registers a new user. Accepts the base fields plus the app's own fields
-   * (`TRegister`) at the top level — see {@link RegisterData}.
-   */
+  /** Registers a new user. */
   register(data: RegisterData<TRegister>): Promise<AuthResult<T>>
 
-  /**
-   * Refreshes the access token.
-   */
+  /** Refreshes the access token. */
   refresh(): Promise<AuthResult<T>>
 
-  /**
-   * Requests a password reset.
-   */
+  /** Requests a password reset. */
   requestPasswordReset(data: PasswordResetRequest): Promise<void>
 
-  /**
-   * Confirms a password reset.
-   */
+  /** Confirms a password reset. */
   confirmPasswordReset(data: PasswordResetConfirm): Promise<void>
 
-  /**
-   * Updates the current user's profile.
-   * Returns the saved profile: the answer applied onto the signed-in user field
-   * by field, with or without an `id` — a field it carries replaces the value
-   * (`null` clears it), one it omits or leaves `undefined` is kept, so a field
-   * cleared by omission must arrive as `null`. A non-object answer is returned
-   * as it came. An answer for a replaced or ended session leaves the current one
-   * untouched.
-   */
+  /** Updates the current user's profile. */
   updateProfile(data: Partial<T>): Promise<T>
 
-  /**
-   * Changes the current user's password.
-   */
+  /** Changes the current user's password. */
   changePassword(oldPassword: string, newPassword: string): Promise<void>
 
-  /**
-   * Initializes auth state (e.g., from stored tokens).
-   *
-   * LAZY and IDEMPOTENT: the first read of the state ({@link getState},
-   * {@link subscribe}, `useAuth()`) starts this same restore when nobody has called
-   * `initialize()`, and every later call shares the one promise instead of sending a
-   * second request. An app that keeps the template's explicit call behaves exactly as
-   * before; an app that loses that line still restores its session.
-   *
-   * With a stored token AND a stored user it marks the session `'authenticated'`
-   * SYNCHRONOUSLY — before its first `await` — so the first render is the
-   * signed-in UI and no page waits on a verification round trip. Any check
-   * (a refresh, the cookie-restore probe) settles behind that render, and only an
-   * explicit 401/403 ends the session; a network/5xx/404 failure keeps it and
-   * reports `'unavailable'`. With no stored user the client stays `'loading'`
-   * until the cookie restore decides.
-   *
-   * Do not put this call (or a `/me` request of your own) in front of the first
-   * render, and do not render a loading screen over a session it just restored:
-   * `whenRestored()` already resolves as soon as the restore has settled, and the
-   * HTTP gate built on it holds requests for exactly that window.
-   */
+  /** Initializes auth state (e.g., from stored tokens). */
   initialize(): Promise<void>
 
-  /**
-   * Re-checks a restored session against the server, in the background — the
-// … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
+  /** Re-checks a restored session against the server, in the background — the boot-time validation an app with a stored token needs when a revoked or expired token… */
+  validateSession?(): Promise<void>
+
+  /** Resolves when the session restore started by `initialize()` has settled — the point after which the client knows whether this visitor is signed in. */
+  whenRestored?(): Promise<void>
+
+  /** Subscribes to auth state changes. */
+  subscribe(callback: (state: AuthState<T>) => void): () => void
+
+  /** Subscribes to auth state changes (alias for subscribe). */
+  onAuthChange(callback: (state: AuthState<T>) => void): () => void
+
+  /** Gets the current access token (alias for getAccessToken). */
+  getToken?(): string | null
+
+  /** Adds an auth event listener. */
+  addEventListener(listener: AuthEventListener<T>): () => void
+
+  /** Destroys the auth client. */
+  destroy(): void
+}
 ```
 
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/app-auth/dist/types.d.ts`.)_
+
 #### `StorageAdapter`
 
 Minimal key-value storage adapter used by the auth client for
@@ -909,43 +805,24 @@ Every option {@link AuthClientConfig} accepts, typed by the profile.
 Use `AuthClientConfig<T>` rather than this type: it adds the profile-shape
 check. This interface exists so each member's documentation is addressable.
 
-````typescript
+```typescript
 interface AuthClientConfigOptions<T extends object = UserProfile> {
-  /**
-   * API base URL.
-   */
+  /** API base URL. */
   baseURL?: string
 
-  /**
-   * Login endpoint.
-   */
+  /** Login endpoint. */
   loginEndpoint?: string
 
-  /**
-   * Logout endpoint. Defaults to `/users/logout`. Set to `null` (or `''`) when
-   * the API has no logout route: {@link AuthClient.logout} skips the request
-   * and still clears the local session.
-   */
+  /** Logout endpoint. */
   logoutEndpoint?: string | null
 
-  /**
-   * Register endpoint.
-   */
+  /** Register endpoint. */
   registerEndpoint?: string
 
-  /**
-   * Refresh endpoint.
-   */
+  /** Refresh endpoint. */
   refreshEndpoint?: string
 
-  /**
-   * The write route used by `updateProfile`, independently of `currentUserEndpoint`.
-   * Defaults to `/auth/profile`. A resource route with an account id can resolve
-   * from the signed-in user, e.g. `(user) => '/accounts/' + encodeURIComponent(user.id)`.
-   * A profile with no `id` resolves from a field it does have, e.g.
-   * `(user) => '/people/' + encodeURIComponent(user.username)`.
-   * The resolver sees the current user before the patch, never caller-submitted identity.
-   */
+  /** The write route used by `updateProfile`, independently of `currentUserEndpoint`. */
   profileEndpoint?: string | ((user: Readonly<T>) => string)
 
   /** HTTP method for `updateProfile()` (default `'PATCH'`; `'PUT'` for a `PUT /api/user` route). */
@@ -954,149 +831,63 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
   /** Request-body adapter for `updateProfile()` — default the `Partial<T>` as given, e.g. `(data) => ({ user: data })`; see the module docs. */
   profileRequestBody?: (data: Partial<T>) => unknown
 
-  /**
-   * The API route that returns the signed-in user (default `/users/me`). Called
-   * with credentials by `initialize()` to re-establish the session after a full
-   * page load when the token did not survive the reload itself — i.e. when
-   * `storage` is `'memory'` and the API sets an httpOnly session cookie — and by
-   * {@link AuthClient.validateSession} on every reload to confirm a stored token
-   * is still valid. Must return the user (as `user` or `props`).
-   *
-   * Set it whenever the app serves its own current-user route: a wrong value
-   * answers 404, which `validateSession` reports as `'unavailable'` and keeps the
-   * stored token instead of signing the user out — but the session then stays
-   * unconfirmed.
-   */
+  /** The API route that returns the signed-in user (default `/users/me`). */
   currentUserEndpoint?: string
 
-  /**
-   * When to probe {@link currentUserEndpoint} for an HttpOnly cookie session.
-   * The default `'hint'` probes only when the readable `mol_auth=1` cookie is
-   * present or this client already holds a cookie-session candidate. The API
-   * must set that presence hint alongside its HttpOnly cookie for automatic
-   * restoration after a full page load.
-   *
-   * Choose `'always'` for an external cookie API without that hint. Pair it with
-   * `storage: 'memory'` and the API's current-user endpoint; the request includes
-   * credentials. An anonymous load then makes a probe too. A local sign-out
-   * suppresses probes until a successful sign-in establishes another session.
-   * Network/5xx/404 failures leave a retryable candidate; 401/403 ends it.
-   */
+  /** When to probe {@link currentUserEndpoint} for an HttpOnly cookie session. */
   cookieRestore?: 'hint' | 'always'
 
-  /**
-   * Maximum duration of an auth request, including reading its response body, in
-   * milliseconds (default `10000`). Must be finite, positive, and below `2147483648`.
-   * A restore timeout settles as `'unavailable'` and preserves the session for retry,
-   * so initial-session render holds cannot wait forever on an unresponsive server.
-   */
+  /** Maximum duration of an auth request, including reading its response body, in milliseconds (default `10000`). */
   requestTimeout?: number
 
-  /**
-   * Storage key prefix.
-   */
+  /** Storage key prefix. */
   storagePrefix?: string
 
-  /**
-   * The EXACT `StorageAdapter` key the access token is written under (default
-   * `${storagePrefix}accessToken`).
-   *
-   * Set it when something outside this package reads the token at its own key —
-   * an e2e suite's contract (for example, `localStorage.getItem('app.jwt')`), a
-   * second library, a host page — instead of mirroring the token into
-   * `localStorage` beside the client. The refresh token and the cached user keep
-   * the prefix.
-   *
-   * In a browser the client's storage default is {@link createBrowserStorageAdapter},
-   * so `tokenKey` alone writes the token to exactly that key and a reload keeps
-   * the session. An EXPLICIT `storage: 'memory'` beside it warns at construction:
-   * the value then lives in a process-local Map nothing outside this client can
-   * read, and a reload signs the user out.
-   */
+  /** The EXACT `StorageAdapter` key the access token is written under (default `${storagePrefix}accessToken`). */
   tokenKey?: string
 
-  /**
-   * Scheme of the `Authorization` header the access token is sent with:
-   * `Bearer` (default), or e.g. `Token` for an API that reads
-   * `Authorization: Token <jwt>`.
-   */
+  /** Scheme of the `Authorization` header the access token is sent with: `Bearer` (default), or e.g. `Token` for an API that reads `Authorization: Token <jwt>`. */
   authScheme?: string
 
-  /**
-   * Shape the login/register request body for an API that expects another
-   * envelope (default: the payload as given). `register()` hands this callback
-   * exactly what the caller passed — including the app's own fields, typed
-   * through `createJWTAuthClient<UserProfile, { username: string }>` — so the
-   * body can be sent as-is under the envelope the API wants.
-   *
-   * A nested-account API, for example, nests the payload under `user` and registers
-   * with `{ user: { username, email, password } }`:
-   *
-   * ```typescript
-   * const client = createJWTAuthClient<UserProfile, { username: string }>({
-   *   requestBody: (kind, payload) => ({ user: payload }),
-   *   // …
-   * })
-   * await client.register({ username, email, password })
-   * ```
-   *
-   * A caller that keeps the untyped payload can map the base fields instead:
-   * `(kind, p) => ({ user: { username: p.name, email: p.email, password: p.password } })`
-   * with `register({ email, password, name: username })`.
-   *
-   * @param kind - Which request.
-   * @param payload - The credentials or registration data.
-   * @returns The JSON body to send.
-   */
+  /** Shape the login/register request body for an API that expects another envelope (default: the payload as given). */
   requestBody?: (kind: 'login' | 'register', payload: Record<string, unknown>) => unknown
 
-  /**
-   * Turn an answer that carries a user into the client's
-   * `{ accessToken, refreshToken?, user }` (default: the answer as given).
-   * For a nested user answer, keep the wire bearer OUT of the profile, because
-   * the client caches `user` in Web Storage where a token copy is readable by
-   * any script on the origin:
-   *
-   * ```typescript
-   * (data) => {
-   *   const { token, ...user } = data.user
-   *   return { accessToken: token, user }
-   * }
-   * ```
-   *
-   * It is the ONE user-shape adapter, and the client applies it on EVERY path
-   * that adopts a user from an API answer — `login()`, `register()`,
-   * `validateSession()`, the cookie restore `initialize()`/`refresh()` run, the
-   * token-refresh answer, and `updateProfile()`. Those answers carry the raw wire
-   * user (a current-user route typically answers a bare `{ user }`), so applying
-   * the same mapping is what keeps the adapted profile after a reload instead of
-   * replacing it with the unadapted one. A mapper that
-   * cannot read a given answer (it throws, or returns no `user`) leaves that
-   * answer's user as it came.
-   *
-   * It is NOT applied to `setSession()` or `setUser()`: those receive a profile
-   * the caller already built in this client's shape, not a wire answer.
-   *
-   * The return type does NOT infer the profile: an untyped
-   * `createJWTAuthClient({ mapAuthResponse })` stays `UserProfile`, so a mapper
-   * that returns a no-id profile fails to compile there instead of silently
-   * replacing the default with whatever the mapper happened to return. The same
-   * rule holds for every config member below (`profileEndpoint`,
-   * `profileRequestBody`, `shouldRestoreUser`): none of them supplies the
-   * profile. Name the profile at the call
-   * (`createJWTAuthClient<MyUser>({ mapAuthResponse })`) to use a custom one.
-   *
-   * @param data - The parsed response body.
-   * @returns The auth result.
-   */
+  /** Turn an answer that carries a user into the client's `{ accessToken, refreshToken?, user }` (default: the answer as given). */
   mapAuthResponse?: (data: unknown) => AuthResult<NoInfer<T>> | AuthChallenge
 
-  /**
-   * Where the access/refresh token and the cached user are kept — the field that
-   * decides whether a page reload keeps the user signed in.
-   *
-// … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
-````
+  /** Where the access/refresh token and the cached user are kept — the field that decides whether a page reload keeps the user signed in. **In a browser the default… */
+  storage?: 'memory' | StorageAdapter
+
+  /** Decide whether a user returned by the cookie-restore probe (`currentUserEndpoint`) constitutes a signed-in CLIENT session. */
+  shouldRestoreUser?: (user: T) => boolean
+
+  /** Refresh the access token before it expires. */
+  autoRefresh?: boolean
+
+  /** Refresh tokens this many seconds before expiry. */
+  refreshBuffer?: number
+
+  /** Forgot password / password reset request endpoint. */
+  forgotPasswordEndpoint?: string
+
+  /** Password reset confirmation endpoint. */
+  resetPasswordEndpoint?: string
+
+  /** Change password endpoint. */
+  changePasswordEndpoint?: string | ((user: Readonly<T>) => string)
+
+  /** HTTP method for `changePassword()` (default `'POST'`). */
+  changePasswordMethod?: 'POST' | 'PATCH'
+
+  /** Available OAuth providers (e.g., ['github', 'google', 'gitlab']). */
+  oauthProviders?: string[]
+
+  /** OAuth endpoint path (default: '/oauth'). */
+  oauthEndpoint?: string
+}
+```
+
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/app-auth/dist/types.d.ts`.)_
 
 #### `TokenStorage`
 
@@ -1385,8 +1176,30 @@ rejected; see {@link AuthProfileShape} for the persistence contract behind
 that list.
 
 The type argument is NEVER inferred from the config: not from
-
-_(description truncated — read the full text in `node_modules/@molecule/app-auth/dist/types.d.ts`.)_
+`mapAuthResponse`, `profileEndpoint`, `profileRequestBody` or
+`shouldRestoreUser`, and not from a config variable the caller annotated as
+`AuthClientConfig<MyUser>`. An untyped call stays typed `UserProfile`, so the
+default configuration keeps requiring `id: string`. Name the profile at the
+call (`createJWTAuthClient<MyUser>(config)`) — which also checks this config
+against `MyUser`.
+
+**Callers upgrading from 1.8 — three shapes now need the profile at the call.**
+Each was accepted by 1.8 and is a type error here; each has a one-line fix:
+
+1. A mapper that supplied the profile
+   (`createJWTAuthClient({ mapAuthResponse: (d): AuthResult<MyUser> => … })`)
+   is now typed `UserProfile`. Name it on the factory:
+   `createJWTAuthClient<MyUser>({ mapAuthResponse })`.
+2. A config variable annotated `AuthClientConfig<MyUser>` with a profile that
+   extends `UserProfile` used to supply the type argument. Pass it:
+   `createJWTAuthClient<MyUser>(config)`. (A no-id profile was already
+   rejected by 1.8's `T extends UserProfile`.)
+3. Generic forwarding written `function make<T extends UserProfile>(config: AuthClientConfig<T>)`
+   no longer satisfies the factory's constraint. Copy the named constraint:
+   `function make<T extends AuthProfileConstraint<T>>(config: AuthClientConfig<T>)`.
+
+`any` is accepted at every entrypoint (`createJWTAuthClient<any>()`,
+`getClient<any>()`), so a caller that deliberately opted out keeps compiling.
 
 ```typescript
 type AuthClientConfig<T extends object = UserProfile> = AuthClientConfigOptions<T> &
@@ -1426,10 +1239,10 @@ reload out of the box; each of these replaces that default:
 
 ```ts
 storage: 'memory' // memory only: pair it with an httpOnly cookie session
+storage: createBrowserStorageAdapter({ kind: 'session' }) // survives a reload, dies with the tab
+storage: { getItem: (k) => …, setItem: (k, v) => …, removeItem: (k) => … } // your own
 ```
 
-_(description truncated — read the full text in `node_modules/@molecule/app-auth/dist/browser-storage.d.ts`.)_
-
 ```typescript
 function createBrowserStorageAdapter(options?: BrowserStorageAdapterOptions): StorageAdapter
 ```

package/package.json

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