@molecule/app-auth 3.0.2 → 3.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-26T04:14:38.335Z
+Generated: 2026-11-02T07:28:20.788Z
 -->
 
 # @molecule/app-auth
@@ -17,19 +17,54 @@ client; `setClient`/`getClient` bond it; `login`/`logout`/`register`/
 bindings (e.g. `AuthProvider`/`useAuth` in `@molecule/app-react`) wrap the
 same client.
 
-**In a scaffolded app, wire it by hand — the sandbox cannot run `mlcl add`.**
-The package is already installed; create the client once at startup with
+**What this client already handles**
+
+- `getAccessToken()` returns a stored token immediately, even while restore is pending.
+- Only 401/403 ends a session; network and 5xx restore failures retain it.
+- `tokenKey`/`storagePrefix`, `authScheme`, `mapAuthResponse`,
+  `currentUserEndpoint`, and `profileEndpoint`/`profileUpdateMethod` adapt the API.
+- `logout()` clears the local session even if revocation fails; `refresh()` and
+  optional auto-refresh use a stored refresh token.
+- `AuthProvider` renders children immediately and gates nothing; only a route guard
+  chooses to wait for `status === 'loading'`.
+
+A token nested in the user, a custom key and current-user route, a PUT update,
+and `Authorization: Token <jwt>` need configuration, not another session layer:
+
+```typescript
+import { createJWTAuthClient } from '@molecule/app-auth'
+const client = createJWTAuthClient({
+  tokenKey: 'app.jwt',
+  authScheme: 'Token',
+  currentUserEndpoint: '/user',
+  profileEndpoint: '/user',
+  profileUpdateMethod: 'PUT',
+  mapAuthResponse: (data) => {
+    const { token, ...user } = (data as { user: { token: string; id: string } }).user
+    return { accessToken: token, user }
+  },
+})
+```
+
+**In a scaffolded app, keep the generated auth bond.** It already creates and
+bonds one client from `authConfig`; adapt that config and read the session through
+`MoleculeProvider`/`useAuth()` instead of adding another session layer. In an existing
+app without that bond, create the client once at startup with
 `setClient(createJWTAuthClient({ baseURL, authScheme: 'Token', storage:
 createBrowserStorageAdapter() }))`, or `createDefaultAuthClient(authConfig)`
-from `@molecule/app-bonds-default-react` (which also registers
-`whenRestored()` as the HTTP gate), call `initialize()`, and read the session
-through `MoleculeProvider`/`useAuth()` in a React app.
-
-**`initialize()` restores the session BEFORE the first render, and no
-hand-rolled token store may replace it.** With the token AND user in the
-store the restore is synchronous and costs no request; with an httpOnly
-session cookie the API sets at login it restores through
-`currentUserEndpoint` (default `/users/me`). With only an access token,
+from `@molecule/app-bonds-default-react`, then call `initialize()`. The bond's
+HTTP-sync variants also register `whenRestored()` as the request gate.
+
+**`initialize()` restores a cached token AND user BEFORE the first render.**
+That restore is synchronous and costs no request. Cookie-only and token-only
+restoration need an asynchronous current-user request. An HttpOnly
+session cookie restores through `currentUserEndpoint` (default `/users/me`).
+The default `cookieRestore: 'hint'` requires a readable `mol_auth=1` cookie
+set by the API alongside the HttpOnly cookie. For an external cookie API
+without that convention, configure `storage: 'memory'`,
+`cookieRestore: 'always'`, and its `currentUserEndpoint`. Keep the HTTP
+client's `withCredentials: true`. This explicit policy also probes anonymous
+loads; a local sign-out suppresses further probes until sign-in succeeds. With only an access token,
 it loads and maps the profile from that endpoint once before deciding the
 session: 401/403 clears the token; network/5xx failures retain it as
 `unavailable`. `AuthClientConfig.storage` is
@@ -50,8 +85,8 @@ then stays on its loading branch).
 **Never fetch viewer-dependent data before the restore settles.** A
 component effect that runs on mount fires while `initialize()` is still
 restoring, so its request leaves without the `Authorization` header and the
-server answers for an anonymous viewer — a followed user renders "Follow", a
-saved item renders unsaved. On localhost the restore usually wins this race;
+server answers for an anonymous viewer — saved preferences appear unset and
+account-specific controls show anonymous defaults. On localhost the restore usually wins this race;
 over the network it does not, so the bug appears only on the deployed URL.
 Gate the fetch on the auth state being settled (`state.initialized`), or let
 the HTTP client do it: `@molecule/app-bonds-default-react` registers
@@ -71,8 +106,7 @@ mirrors the token into the bonded client.
 `initialize()` sets that state synchronously, before any request, and every
 verification settles behind that render. Never hold the first paint on
 `validateSession()` or a `/me` request of your own — a protected page then pays
-an API round trip on every navigation (~30 full page loads in one pagination
-spec put four tests at 15.0–15.9 s of a 15 s budget, and two timed out). Route
+an API round trip on every navigation. Route
 guards read this same `status`: wait only while it is `'loading'` — that
 status means "no decision yet", so an auth request in flight
 (`state.loading`) keeps the decided status and does not unmount a
@@ -86,8 +120,9 @@ KEEPS the token and the user (`'unavailable'`, retryable; the 404 error names
 plus its own listener set is a second session store, and it drifts from the
 client's.
 
-**Only a 401/403 ENDS a session; no response at all never does.** Every path that
-clears the stored session (`validateSession`, the cookie restore, the initial
+**Only a server 401/403 rejects a credential; no response never does.** Explicit
+sign-out and an application restore predicate can also end the local session.
+Every server-failure path that clears the stored session (`validateSession`, the cookie restore, the initial
 refresh, the background refresh timer) keys on the server REJECTING the
 credential. An aborted request, a dropped connection, or a 5xx arrives with no
 HTTP status (or `status: 0` from `@molecule/app-http`) and says nothing about the
@@ -105,10 +140,12 @@ whole parsed body is preserved, nested maps and arrays included, not just the
 `error`/`message` the message is built from, so a login form can render the
 API's own validation payload (`{ errors: { credentials: ['is invalid'] } }`)
 instead of re-implementing the call. A body that is not JSON arrives as `{}`;
-the key, message, fallback and rejection are unchanged.
+the key, message, fallback and rejection are unchanged. That same rejection also
+satisfies `isHttpError(err)` from `@molecule/app-http`, with
+`response.data === body`, so an app-http error reader works without changing the
+`I18nError` contract.
 
-**`autoRefresh` does nothing without a refresh token — and must never log the
-user out.** The client schedules a refresh only when `refresh()` could actually
+**`autoRefresh` does nothing without a refresh token.** The client schedules a refresh only when `refresh()` could actually
 succeed, i.e. when a refresh token is stored. An API that issues none (the
 `@molecule/api-resource-user` model: login/register return `{ accessToken,
 user }` and the durable session is an httpOnly cookie the SERVER refreshes)
@@ -123,7 +160,8 @@ user, `setSession({ accessToken, user })` stores both and flips the client to
 (a form's own sign-in code wrote the token and the user with `setAccessToken`/`setUser`,
 which change their field only — the UI stays signed out and the browser assertions that
 expect it time out). `setAccessToken()` and `setUser()` are field setters, not a
-sign-in: neither sets `authenticated`.
+sign-in: neither establishes an authenticated session. On a signed-in client,
+`setUser(null)` instead ends the local session and clears its stored credentials.
 
 **A custom user profile is typed once and used everywhere: `AuthClientConfig<MyUser>`,
 `createJWTAuthClient<MyUser>` and `useAuth<MyUser>()`.** The config's generic makes
@@ -257,8 +295,8 @@ submission, the saved baseline and cache propagation. Use that composition
 for editable account forms instead of resetting every field on `user` changes.
 
 **A token another tool reads at its own key is a CONFIG field, not a mirror.**
-An e2e suite or host page that expects `localStorage.jwtToken` (the RealWorld
-specs do) is satisfied by `tokenKey: 'jwtToken'` — in a browser the client's
+An e2e suite or host page that expects `localStorage.getItem('app.jwt')` is
+satisfied by `tokenKey: 'app.jwt'` — in a browser the client's
 storage default is already `createBrowserStorageAdapter()`, so with an explicit
 `'memory'` store you must also pass
 `storage: createBrowserStorageAdapter()`. Writing the token into that key from a
@@ -294,35 +332,35 @@ await login({ email, password })
 if (isAuthenticated()) console.log(getUser()?.email)
 ```
 
-An API that wraps the payload and registers extra fields (RealWorld): type those
+An API that wraps the payload and registers extra fields: type those
 fields with the factory's second generic, and `requestBody` receives exactly what
 the form passed — `{ user: { username, email, password } }` goes out as-is.
 
 ```typescript
 import { createJWTAuthClient } from '@molecule/app-auth'
 
-// RealWorld's user has no `id`. Name the shape the wire actually sends; the
+// This account API's user has no `id`. Name the shape the wire actually sends; the
 // client reads no field of it, so nothing has to be invented for a base profile.
-interface RealWorldUser {
+interface AccountProfile {
   username: string
   email: string
   bio: string
   image: string
 }
 
-const realWorldAuth = createJWTAuthClient<RealWorldUser, { username: string }>({
+const accountAuth = createJWTAuthClient<AccountProfile, { username: string }>({
   baseURL: '/api',
   authScheme: 'Token',
   requestBody: (_kind, payload) => ({ user: payload }),
   mapAuthResponse: (data) => {
-    const { user: wire } = data as { user: { token: string } & RealWorldUser }
+    const { user: wire } = data as { user: { token: string } & AccountProfile }
     // Keep every wire field; the bearer stays out of the cached profile.
     const { token, ...profile } = wire
     return { accessToken: token, user: profile }
   },
 })
 
-await realWorldAuth.register({ username: 'alice', email: 'alice@example.com', password: 's3cret' })
+await accountAuth.register({ username: 'alice', email: 'alice@example.com', password: 's3cret' })
 ```
 
 ## Type
@@ -332,7 +370,7 @@ await realWorldAuth.register({ username: 'alice', email: 'alice@example.com', pa
 ## Installation
 
 ```bash
-npm install @molecule/app-auth @molecule/app-bond @molecule/app-i18n @molecule/app-logger
+npm install @molecule/app-auth @molecule/app-bond @molecule/app-http @molecule/app-i18n @molecule/app-logger
 ```
 
 ## API
@@ -468,6 +506,21 @@ interface AuthResult<T = UserProfile> {
 }
 ```
 
+#### `AuthChallenge`
+
+A 206 challenge: control fields survive, but no authenticated session exists.
+
+```typescript
+interface AuthChallenge {
+  twoFactorRequired: true
+  user?: never
+  accessToken?: never
+  refreshToken?: never
+  expiresAt?: never
+  [controlField: string]: unknown
+}
+```
+
 #### `PasswordResetRequest`
 
 Password reset request data.
@@ -507,7 +560,10 @@ Reactive authentication state snapshot (initialized, authenticated, user, loadin
 interface AuthState<T = UserProfile> {
   /**
    * The session's state as one value — render from this instead of combining
-   * `initialized`/`authenticated`/`loading`. See {@link AuthStatus}.
+   * `initialized`/`authenticated`/`loading`. `'loading'` is undecided, so wait
+   * and redirect only on `'unauthenticated'`; `'unavailable'` keeps the candidate
+   * for retry and can have a null profile. A restore failure other than 401/403
+   * never signs out. See {@link AuthStatus}.
    */
   status: AuthStatus
 
@@ -517,12 +573,15 @@ interface AuthState<T = UserProfile> {
   initialized: boolean
 
   /**
-   * Whether the user is authenticated.
+   * Whether the client has an authenticated session. This is not a server
+   * confirmation flag: during `'unavailable'` it can be false for a retained
+   * token/cookie-only candidate with no cached profile. Use `status` for redirects.
    */
   authenticated: boolean
 
   /**
-   * Current user (if authenticated).
+   * Current user, or null when none is cached. In particular, an `'unavailable'`
+   * token/cookie-only restore has a retained candidate but no profile yet.
    */
   user: T | null
 
@@ -555,6 +614,9 @@ to react to the server's own answer:
   map, a field map with arrays, or a top-level array of messages — without
   re-implementing the login call. A body that is not JSON (an HTML error
   page, an empty body) arrives as `{}`.
+- `response`: the same failed-response view as `@molecule/app-http`, with
+  `response.data === body`, so `isHttpError` and `response.data` readers work
+  on this rejection too.
 
 ```typescript
 import { I18nError } from '@molecule/app-i18n'
@@ -580,6 +642,29 @@ interface AuthError extends I18nError {
    * maps and arrays included. `{}` when the body is not JSON.
    */
   body: unknown
+
+  /** The app-http-compatible view of the failed response. */
+  response: {
+    /** The same parsed value as {@link AuthError.body}. */
+    data: unknown
+    /** The same HTTP status as {@link AuthError.status}. */
+    status: number
+    /** HTTP status text supplied by the server or fetch implementation. */
+    statusText: string
+    /** Response headers as a plain object, with credential headers omitted. */
+    headers: Record<string, string>
+    /** Method and credential-redacted URL only; request bodies and headers are never retained. */
+    config: {
+      method: string
+      url: string
+    }
+  }
+
+  /** The same translation key as {@link I18nError.i18nKey}. */
+  errorKey: string
+
+  /** A server response was received, so a non-ok response is never an abort. */
+  aborted: false
 }
 ```
 
@@ -647,12 +732,23 @@ interface AuthClient<
    * 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). Does NOT change tokens.
+   * 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.
    *
-   * This does not 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.
    */
   setUser(user: T | null): void
 
@@ -669,10 +765,13 @@ interface AuthClient<
    * 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; it does not sign the client in
-   * (`authenticated` and `status` are unchanged). Use {@link login} /
-   * {@link register} for a credential exchange, or call {@link setSession}
-   * with the token and the user to establish an already-issued session.
+   * 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.
    */
   setAccessToken(token: string | null): void
 
@@ -701,7 +800,16 @@ interface AuthClient<
   login(credentials: LoginCredentials): Promise<AuthResult<T>>
 
   /**
-   * Logs out the current user.
+   * 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.
    */
   logout(): Promise<void>
 
@@ -768,35 +876,6 @@ interface AuthClient<
 
   /**
    * 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 must sign the user out. Call it AFTER the first render
-   * (`initialize()` restores synchronously from storage; this costs one request).
-   *
-   * - The server confirms the user: the session is refreshed and {@link AuthState.status}
-   *   stays `'authenticated'`.
-   * - The server answers 401 or 403: the token is dead — the stored session is
-   *   cleared and the status becomes `'unauthenticated'`.
-   * - The server cannot confirm the session — a network failure, a 5xx, or a 404
-   *   from a misconfigured {@link AuthClientConfig.currentUserEndpoint}: the
-   *   session (token AND user) is KEPT and the status becomes `'unavailable'`, so
-   *   the app can retry instead of signing the user out over a bad connection or a
-   *   route that does not exist. The 404 error names `currentUserEndpoint`.
-   *
-   * Do not hand-write this beside the client: a parallel token/user store for a
-   * "validating"/"unavailable" flag is the race this method removes.
-   *
-   * Optional: a provider with no restorable session has nothing to validate.
-   */
-  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.
-   *
-   * Resolves IMMEDIATELY when no restore is in flight: before `initialize()` is ever
-   * called, and after it has finished. A restore that failed resolves too (it settled the
-   * question), so an HTTP client can await this before every request without risking one
-   * held forever. That is what makes the fetch-before-restore race impossible: a page that
 // … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
 ```
 
@@ -833,9 +912,11 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
   loginEndpoint?: string
 
   /**
-   * Logout endpoint.
+   * 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.
    */
-  logoutEndpoint?: string
+  logoutEndpoint?: string | null
 
   /**
    * Register endpoint.
@@ -878,6 +959,21 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
    */
   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.
+   */
+  cookieRestore?: 'hint' | 'always'
+
   /**
    * Storage key prefix.
    */
@@ -888,7 +984,7 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
    * `${storagePrefix}accessToken`).
    *
    * Set it when something outside this package reads the token at its own key —
-   * an e2e suite's contract (RealWorld's specs read `localStorage.jwtToken`), a
+   * 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.
@@ -915,8 +1011,8 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
    * through `createJWTAuthClient<UserProfile, { username: string }>` — so the
    * body can be sent as-is under the envelope the API wants.
    *
-   * RealWorld, for example, nests the payload under `user` and registers with
-   * `{ user: { username, email, password } }`:
+   * 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 }>({
@@ -939,7 +1035,7 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
   /**
    * Turn an answer that carries a user into the client's
    * `{ accessToken, refreshToken?, user }` (default: the answer as given).
-   * RealWorld, for example — keep the wire bearer OUT of the profile, because
+   * 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:
    *
@@ -975,7 +1071,7 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
    * @param data - The parsed response body.
    * @returns The auth result.
    */
-  mapAuthResponse?: (data: unknown) => AuthResult<NoInfer<T>>
+  mapAuthResponse?: (data: unknown) => AuthResult<NoInfer<T>> | AuthChallenge
 
   /**
    * Where the access/refresh token and the cached user are kept — the field that
@@ -986,20 +1082,6 @@ interface AuthClientConfigOptions<T extends object = UserProfile> {
    * (SSR, a Node test) the default is `'memory'`. Pass `'memory'` EXPLICITLY when
    * the API sets an httpOnly session cookie and you do not want a script-readable
    * copy: `'memory'` is a process-local store, and `initialize()` then restores
-   * through {@link AuthClientConfig.currentUserEndpoint} — the strongest
-   * configuration, because no script can read the cookie.
-   *
-   * **An app whose external contract requires the token at a specific key** — a
-   * supplied e2e suite (the RealWorld specs read `localStorage.jwtToken` in
-   * `SELECTORS.md`), a host page, a second library — sets `tokenKey: 'jwtToken'`;
-   * in a browser that is enough, because the default store is Web Storage. The
-   * session (token AND user) is then restored synchronously in `initialize()` —
-   * with no store of your own. `tokenKey` places the access token at that exact
-   * key; the refresh token and the cached user keep `storagePrefix`.
-   *
-   * A bearer token in Web Storage is readable by any script on the origin, so an
-   * XSS can steal it; see {@link createBrowserStorageAdapter}'s `@remarks` for the
-   * trade and for the cookie alternative. Never answer a suite's storage key with a
 // … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
 ````
 
@@ -1160,8 +1242,8 @@ constraint is structural, so the app can name its own fields once and pass
 that type whole:
 
 ```typescript
-interface RealWorldRegister { username: string }
-const client = createJWTAuthClient<UserProfile, RealWorldRegister>({ … })
+interface RegistrationFields { username: string }
+const client = createJWTAuthClient<UserProfile, RegistrationFields>({ … })
 ```
 
 A custom field may not change a built-in field's type: `email` and
@@ -1198,15 +1280,21 @@ The single value an app renders the session from — the four states every auth
 UI needs, derived from {@link AuthState} so no caller has to combine
 `initialized`/`authenticated`/`loading`/`error` itself.
 
+`status === 'loading'` is undecided: wait for it and redirect only on
+`status === 'unauthenticated'`. `'unavailable'` keeps the session candidate
+for retry; its profile can still be null. A restore failure other than
+401/403 never signs out.
+
 - `'loading'`: no decision yet (before `initialize()` settles). An auth
   operation in flight is {@link AuthState.loading} and KEEPS the decided
   status, so a page guarded on `'loading'` stays mounted while a Login or
   Register request runs.
 - `'authenticated'`: a session exists.
 - `'unauthenticated'`: the client settled the question and nobody is signed in.
-- `'unavailable'`: a stored session exists but the server could not confirm it
-  (a network or 5xx failure in {@link AuthClient.validateSession}); the session
-  is KEPT and the app can say "reconnecting" instead of signing the user out.
+- `'unavailable'`: a stored token or cookie-session candidate exists but the
+  server could not confirm it (for example a network, 404, or 5xx failure);
+  the candidate is KEPT and the app can say "reconnecting" instead of signing
+  the user out.
 
 ```typescript
 type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'unavailable'
@@ -1536,15 +1624,36 @@ function register<
 Peer dependencies:
 
 - `@molecule/app-bond` ^1.0.1
+- `@molecule/app-http` ^1.5.2
 - `@molecule/app-i18n` ^1.0.1
-- `@molecule/app-logger` ^1.0.1
+- `@molecule/app-logger` ^1.0.4
 
 ### Runtime Dependencies
 
 - `@molecule/app-bond`
+- `@molecule/app-http`
 - `@molecule/app-i18n`
 - `@molecule/app-logger`
 
+**Synchronous getters for application integrations.** Read the shared client
+synchronously when an integration needs the raw token, auth state and current user.
+These reads create no second store: `getAccessToken()`
+returns the token, `getState().status` includes `unavailable`, and `getUser()` reads
+the mapped profile. The configured `tokenKey` also applies to these getters.
+Keep an integration's response shape local; do not persist another token or user.
+
+```typescript
+import { getClient } from '@molecule/app-auth'
+const readSession = () => {
+  const client = getClient()
+  return {
+    status: client.getState().status,
+    user: client.getUser(),
+    accessToken: client.getAccessToken(),
+  }
+}
+```
+
 - **An API with its own auth envelope keeps this client.** `requestBody` wraps the
   login/register payload (`(kind, p) => ({ user: p })`), `mapAuthResponse` reads the
   token and user out of the answer — keeping the wire bearer OUT of the profile,
@@ -1557,7 +1666,7 @@ Peer dependencies:
   `AuthClientConfig` the client is CONSTRUCTED with
   (`setClient(createJWTAuthClient({ authScheme: 'Token', … }))` in the auth bond), not
   properties of a client that already exists. Do not hand-write an auth client for a spec
-  like RealWorld. **Registration fields the base payload lacks (`username`, …) are the
+  like this one. **Registration fields the base payload lacks (`username`, …) are the
   factory's second generic** — `createJWTAuthClient<UserProfile, { username: string }>(…)` —
   so `register({ username, email, password })` type-checks and the body goes out as
   `{ user: { username, email, password } }`. Do not pass them as `name`/`metadata` or

package/dist/browser-storage.d.ts

@@ -66,15 +66,16 @@ export interface BrowserStorageAdapterOptions {
  * - **The trade, stated plainly.** A bearer token in Web Storage is readable by
  *   any script on the origin, so one XSS is one token theft — an account takeover
  *   for the token's whole lifetime, and `localStorage` keeps the copy after the
- *   tab closes. This is the model the RealWorld suite's own specs write
- *   (`localStorage.setItem('jwtToken', …)` before a reload) and the reason this
- *   adapter exists.
+ *   tab closes. Use this adapter when a host integration requires a stored
+ *   bearer, and configure its key through `tokenKey` instead of a second store.
  * - **An httpOnly cookie session is STRONGER, and is the first choice wherever
  *   your API supports it.** Script cannot read an httpOnly cookie, so an XSS
  *   cannot exfiltrate the credential; the token stays in memory and
  *   `initialize()` restores the session through `currentUserEndpoint`
  *   (`@molecule/api-resource-user` issues exactly this cookie — pass
- *   `storage: 'memory'` when it does). `'memory'` is then the strongest
+ *   `storage: 'memory'` when it does). The default restore requires its readable
+ *   `mol_auth=1` presence hint. An external API without that convention uses
+ *   `cookieRestore: 'always'` with its `currentUserEndpoint`. `'memory'` is then the strongest
  *   configuration. If the API sets no such cookie and you cannot change that,
  *   this adapter is the alternative — keep the token's lifetime short and rotate
  *   it on refresh.

package/dist/browser-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-storage.d.ts","sourceRoot":"","sources":["../src/browser-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAA;AAEpD,4EAA4E;AAC5E,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,4BAAiC,KACzC,cA6EF,CAAA"}
+{"version":3,"file":"browser-storage.d.ts","sourceRoot":"","sources":["../src/browser-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAA;AAEpD,4EAA4E;AAC5E,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,4BAAiC,KACzC,cA6EF,CAAA"}

package/dist/browser-storage.js

@@ -57,15 +57,16 @@ const warn = (message, error) => {
  * - **The trade, stated plainly.** A bearer token in Web Storage is readable by
  *   any script on the origin, so one XSS is one token theft — an account takeover
  *   for the token's whole lifetime, and `localStorage` keeps the copy after the
- *   tab closes. This is the model the RealWorld suite's own specs write
- *   (`localStorage.setItem('jwtToken', …)` before a reload) and the reason this
- *   adapter exists.
+ *   tab closes. Use this adapter when a host integration requires a stored
+ *   bearer, and configure its key through `tokenKey` instead of a second store.
  * - **An httpOnly cookie session is STRONGER, and is the first choice wherever
  *   your API supports it.** Script cannot read an httpOnly cookie, so an XSS
  *   cannot exfiltrate the credential; the token stays in memory and
  *   `initialize()` restores the session through `currentUserEndpoint`
  *   (`@molecule/api-resource-user` issues exactly this cookie — pass
- *   `storage: 'memory'` when it does). `'memory'` is then the strongest
+ *   `storage: 'memory'` when it does). The default restore requires its readable
+ *   `mol_auth=1` presence hint. An external API without that convention uses
+ *   `cookieRestore: 'always'` with its `currentUserEndpoint`. `'memory'` is then the strongest
  *   configuration. If the API sets no such cookie and you cannot change that,
  *   this adapter is the alternative — keep the token's lifetime short and rotate
  *   it on refresh.

package/dist/browser-storage.js.map

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

package/dist/client.d.ts

@@ -33,7 +33,7 @@ import type { AuthClient, AuthClientConfigOptions, AuthProfileConstraint, Regist
  *   fields (see {@link AuthProfileConstraint}), including a profile with no `id`.
  *   The default, `UserProfile`, requires `id: string`.
  * @template TRegister - The app's own registration fields, accepted at the top
- *   level of `register()` (e.g. `{ username: string }` for a RealWorld-shaped API).
+ *   level of `register()` (e.g. `{ username: string }` for an account API).
  *   An interface and a type alias are equally valid.
  * @param config - Auth client configuration including endpoints, storage, and refresh settings.
  * @returns A fully configured `AuthClient` instance.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EAIvB,qBAAqB,EAQrB,kBAAkB,EAClB,WAAW,EACZ,MAAM,YAAY,CAAA;AAmJnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,mBAAmB,GAC9B,CAAC,SAAS,qBAAqB,CAAC,CAAC,CAAC,GAAG,WAAW,EAChD,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAEtE,SAAQ,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAM,KAC/C,UAAU,CAAC,CAAC,EAAE,SAAS,CAw/BzB,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EAIvB,qBAAqB,EAQrB,kBAAkB,EAClB,WAAW,EACZ,MAAM,YAAY,CAAA;AA+RnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,mBAAmB,GAC9B,CAAC,SAAS,qBAAqB,CAAC,CAAC,CAAC,GAAG,WAAW,EAChD,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAEtE,SAAQ,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAM,KAC/C,UAAU,CAAC,CAAC,EAAE,SAAS,CAmwCzB,CAAA"}