@molecule/app-auth 1.5.2 → 1.5.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-10-18T09:07:53.544Z
+Generated: 2026-10-18T20:35:23.952Z
 -->
 
 # @molecule/app-auth
@@ -55,9 +55,19 @@ mirrors the token into the bonded client.
 **`getState().status` is the session state to render, in one value.**
 `'loading'` (no decision yet) → `'authenticated'` / `'unauthenticated'`, and
 `'unavailable'` when a stored session exists but the server could not confirm it.
+**A stored token AND a stored user make the FIRST render `'authenticated'`**:
+`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 (xr-molecule-flash-m177: ~30 full page
+loads in one pagination spec; its four tests sat at 15.0–15.9 s of a 15 s
+budget and the grader timed two out). Route guards read this same `status`:
+wait only while it is `'loading'`.
 `validateSession()` is the background re-check that produces the last two: call
-it after the first render — a 4xx clears the token (`'unauthenticated'`), a
-network failure or 5xx KEEPS it (`'unavailable'`, retryable). Do not build a
+it after the first render — a 401 or 403 clears the token (`'unauthenticated'`),
+while a network failure, a 5xx, or a 404 from a wrong `currentUserEndpoint`
+KEEPS the token and the user (`'unavailable'`, retryable; the 404 error names
+`currentUserEndpoint`). Do not build a
 `validating`/`unavailable` flag beside the client: a second module-level state
 plus its own listener set is a second session store, and it drifts from the
 client's.
@@ -71,10 +81,27 @@ therefore schedules nothing: the session stays until the API answers 401
 (`validateSession()` clears it) or the user logs out. `autoRefresh: true`
 against such an API is harmless but pointless — leave it `false`.
 
+**Seeding a session from an exchange the app runs itself: `setSession()`.** When an OAuth
+redirect or the app's own sign-in endpoint has already issued the token and returned the
+user, `setSession({ accessToken, user })` stores both and flips the client to
+`authenticated` in one update, so every hook reading the shared client is signed in at once
+(a form's own sign-in code wrote the token and the user with `setAccessToken`/`setUser`,
+which change their field only — the UI stayed signed out and nine browser assertions timed
+out, xr-molecule-flash-m178). `setAccessToken()` and `setUser()` are field setters, not a
+sign-in: neither sets `authenticated`.
+
+**A background verification that returns an unchanged user changes nothing.** When
+`validateSession()` (or a reload's restore) answers with the same profile data the client
+already holds, the client keeps the SAME user object and does not notify subscribers — so an
+effect seeded from `user` does not re-run, and a form it fills keeps what has been typed.
+Seed such a form once (on its first load), never on every `user` identity.
+
 **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'` with
-`storage: createBrowserStorageAdapter()`; writing the token into that key from a
+specs do) is satisfied by `tokenKey: 'jwtToken'` — 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
 subscription beside the client is a second store. In React, `useAuth()` from
 `@molecule/app-react` returns the client's `state` (with `status`), `user` and
 `isAuthenticated`; the token is `useAuthClient().getAccessToken()`.
@@ -341,6 +368,23 @@ interface AuthState<T = UserProfile> {
 }
 ```
 
+#### `AuthSessionSeed`
+
+A complete session an exchange outside the client has already established — an OAuth
+code→token redirect, or the app's own sign-in endpoint. {@link AuthClient.setSession} adopts
+it in one update: the token and the user are stored and the client becomes `authenticated`.
+
+```typescript
+interface AuthSessionSeed<T = UserProfile> {
+  /** The access token the exchange issued. */
+  accessToken: string
+  /** The profile that token belongs to, as the API returned it. */
+  user: T
+  /** A refresh token, when the exchange issued one; omitted leaves the stored one untouched. */
+  refreshToken?: string | null
+}
+```
+
 #### `AuthClient`
 
 Auth client interface that all auth bond packages must implement.
@@ -372,6 +416,11 @@ interface AuthClient<
    * 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.
+   *
+   * 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.
    */
   setUser(user: T | null): void
 
@@ -381,14 +430,34 @@ interface AuthClient<
   getAccessToken(): string | null
 
   /**
-   * Stores the access token in the configured token storage adapter (in-memory
-   * by default). 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 in-memory-default storage contract and make the bearer
-   * token JS-readable (XSS-exfiltratable). Pass `null` to clear it.
+   * 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; 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.
    */
   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.
+   */
+  setSession(session: AuthSessionSeed<T>): void
+
   /**
    * Gets the refresh token.
    */
@@ -437,6 +506,19 @@ interface AuthClient<
 
   /**
    * Initializes auth state (e.g., from stored tokens).
+   *
+   * 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.
    */
   initialize(): Promise<void>
 
@@ -448,11 +530,13 @@ interface AuthClient<
    *
    * - The server confirms the user: the session is refreshed and {@link AuthState.status}
    *   stays `'authenticated'`.
-   * - The server answers 4xx: the token is dead — the stored session is cleared and
-   *   the status becomes `'unauthenticated'`.
-   * - The server cannot answer (network failure or 5xx): the session is KEPT and the
-   *   status becomes `'unavailable'`, so the app can retry instead of signing the
-   *   user out over a bad connection.
+   * - 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.
@@ -561,11 +645,17 @@ interface AuthClientConfig {
   profileEndpoint?: string
 
   /**
-   * Current-user endpoint for session restore (default `/users/me`). Called by
-   * `initialize()` with credentials 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. Must return the user
-   * (as `user` or `props`).
+   * 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.
    */
   currentUserEndpoint?: string
 
@@ -583,6 +673,12 @@ interface AuthClientConfig {
    * 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.
    */
   tokenKey?: string
 
@@ -622,9 +718,23 @@ interface AuthClientConfig {
   requestBody?: (kind: 'login' | 'register', payload: Record<string, unknown>) => unknown
 
   /**
-   * Turn the API's login/register answer into the client's
+   * Turn an answer that carries a user into the client's
    * `{ accessToken, refreshToken?, user }` (default: the answer as given).
    * RealWorld, for example: `(data) => ({ accessToken: data.user.token, user: data.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 (xr-molecule-flash-m184). 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.
+   *
    * @param data - The parsed response body.
    * @returns The auth result.
    */
@@ -634,19 +744,21 @@ interface AuthClientConfig {
    * 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-memory is the secure default.** `'memory'` is a process-local store, lost
-   * on reload. It is correct when the API sets an httpOnly session cookie, which
-   * `initialize()` then restores through {@link AuthClientConfig.currentUserEndpoint}
-   * — the strongest configuration, because no script can read the cookie.
+   * **In a browser the default is `createBrowserStorageAdapter()` (Web Storage)**,
+   * so a reload keeps the session with no wiring of its own; outside a browser
+   * (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 a token in storage opts in
-   * EXPLICITLY, with these two fields together.** A supplied e2e suite (the
-   * RealWorld specs read `localStorage.jwtToken` in `SELECTORS.md`), a host page
-   * or a second library can require the token at its own key: then set
-   * `storage: createBrowserStorageAdapter()` and `tokenKey: 'jwtToken'`, and the
-   * session (token AND user) is 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`.
+   * **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
@@ -664,14 +776,13 @@ interface AuthClientConfig {
    * ```typescript
    * import { createBrowserStorageAdapter } from '@molecule/app-auth'
    *
-   * // A suite/host page reads the token at its own key — the opt-in:
+   * // A suite/host page reads the token at its own key (the browser default
+   * // already stores it; `storage` is shown for an explicit choice):
    * storage: createBrowserStorageAdapter()
    * tokenKey: 'jwtToken'
-   * // A reload keeps the session at this client's own keys:
-   * storage: createBrowserStorageAdapter()
    * // Only this tab's lifetime, at a narrower exposure than localStorage:
    * storage: createBrowserStorageAdapter({ kind: 'session' })
-   * // An httpOnly cookie session instead — memory only, the stronger route:
+   * // An httpOnly cookie session — keep the bearer out of script-reachable storage:
    * storage: 'memory'
    * ```
    */
@@ -686,50 +797,7 @@ interface AuthClientConfig {
    * Use this when the server also issues sessions that must never appear
    * signed-in client-side — e.g. an anonymous/guest session whose user row
    * (`isAnonymous`) would otherwise hydrate as a logged-in user. Defaults to
-   * accepting every restored user.
-   * @param user - The user returned by the restore probe.
-   * @returns Whether to establish the client session from this user.
-   */
-  shouldRestoreUser?: (user: UserProfile) => boolean
-
-  /**
-   * Refresh the access token before it expires. A no-op unless the API issued a
-   * refresh token at login/register — with none stored, nothing is scheduled and
-   * the session is never ended by the refresh timer; an API that rejects the
-   * access token (401) or an explicit logout ends it instead. Defaults to `true`.
-   */
-  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
-
-  /**
-   * Available OAuth providers (e.g., ['github', 'google', 'gitlab']).
-   */
-  oauthProviders?: string[]
-
-  /**
-   * OAuth endpoint path (default: '/oauth').
-   */
-  oauthEndpoint?: string
-}
+// … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
 ````
 
 #### `TokenStorage`
@@ -857,10 +925,11 @@ token as a background request — never in front of the first render. A page tha
 own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
 window, eight `waitForURL` timeouts).
 
-Pass it as `AuthClientConfig.storage` to keep the session across a page reload:
-the client's default (`'memory'`) is lost on reload, and re-establishing the
-session then needs a credential that survived — this adapter, or an httpOnly
-session cookie the API sets (see the security note below).
+In a browser this IS the auth client's default `AuthClientConfig.storage`, so a scaffolded
+app keeps its session across a page reload with no extra wiring. Outside a browser (SSR, a Node
+test) the client defaults to `'memory'` instead, because there is no Web Storage to use. Pass
+`'memory'` explicitly to keep the bearer token out of script-reachable storage when the API sets
+an httpOnly session cookie (see the security note below).
 
 ```ts
 import { createJWTAuthClient, createBrowserStorageAdapter } from '@molecule/app-auth'
@@ -871,18 +940,18 @@ const authClient = createJWTAuthClient({
 })
 ```
 
-The scaffold's `authConfig` already passes it, so a scaffolded app survives a
+The browser client already defaults to it, so a scaffolded app survives a
 reload out of the box; each of these replaces that default:
 
-````ts
+```ts
 storage: 'memory' // memory only: pair it with an httpOnly cookie session
-storage: createBrowserStorageAdapter({ kind: 'session' }) // survives a reload, dies with the tab
+```
 
-*(description truncated — read the full text in `node_modules/@molecule/app-auth/dist/browser-storage.d.ts`.)*
+_(description truncated — read the full text in `node_modules/@molecule/app-auth/dist/browser-storage.d.ts`.)_
 
 ```typescript
 function createBrowserStorageAdapter(options?: BrowserStorageAdapterOptions): StorageAdapter
-````
+```
 
 - `options` — Which Web Storage area to use, or a store to use directly.
 
@@ -1064,7 +1133,11 @@ Peer dependencies:
 - **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 (`(d) => ({ accessToken: d.user.token, user: d.user })`),
-  and `authScheme: 'Token'` sends `Authorization: Token <jwt>` — both are fields of the
+  and `authScheme: 'Token'` sends `Authorization: Token <jwt>`. `mapAuthResponse` is the
+  ONE user-shape adapter: the client applies it to every answer that carries a user (login,
+  register, `validateSession()`, the cookie restore, a token refresh, `updateProfile()`), so
+  the adapted profile survives a reload instead of being replaced by the raw wire user.
+  Both are fields of the
   `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
@@ -1109,12 +1182,12 @@ by one. A box you can't check is an integration bug to fix — not a skip:
 - [ ] The session survives a FULL page reload: after login, hard-reload → you
       stay signed in (the profile/sign-out UI a signed-in visitor sees is still
       there), and you are NOT bounced to login. Which route does it is the app's
-      `AuthClientConfig.storage`: the scaffold's `createBrowserStorageAdapter()` keeps
-      the token in the browser, an httpOnly session cookie is restored by
-      `initialize()` through `currentUserEndpoint` (default `/users/me`). If the
-      app has neither — `storage` left at `'memory'` against an API that sets no
-      cookie — this box cannot be checked, and the fix is the config, not a token
-      store written beside the client.
+      `AuthClientConfig.storage`: in a browser the client defaults to
+      `createBrowserStorageAdapter()`, which keeps the token there; an httpOnly
+      session cookie is restored by `initialize()` through `currentUserEndpoint`
+      (default `/users/me`). If the app sets `storage: 'memory'` explicitly against
+      an API that sets no cookie, this box cannot be checked, and the fix is the
+      config, not a token store written beside the client.
 - [ ] 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

package/dist/browser-storage.d.ts

@@ -38,10 +38,11 @@ export interface BrowserStorageAdapterOptions {
  * own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
  * window, eight `waitForURL` timeouts).
  *
- * Pass it as `AuthClientConfig.storage` to keep the session across a page reload:
- * the client's default (`'memory'`) is lost on reload, and re-establishing the
- * session then needs a credential that survived — this adapter, or an httpOnly
- * session cookie the API sets (see the security note below).
+ * In a browser this IS the auth client's default `AuthClientConfig.storage`, so a scaffolded
+ * app keeps its session across a page reload with no extra wiring. Outside a browser (SSR, a Node
+ * test) the client defaults to `'memory'` instead, because there is no Web Storage to use. Pass
+ * `'memory'` explicitly to keep the bearer token out of script-reachable storage when the API sets
+ * an httpOnly session cookie (see the security note below).
  *
  * ```ts
  * import { createJWTAuthClient, createBrowserStorageAdapter } from '@molecule/app-auth'
@@ -52,7 +53,7 @@ export interface BrowserStorageAdapterOptions {
  * })
  * ```
  *
- * The scaffold's `authConfig` already passes it, so a scaffolded app survives a
+ * The browser client already defaults to it, so a scaffolded app survives a
  * reload out of the box; each of these replaces that default:
  *
  * ```ts
@@ -72,10 +73,11 @@ export interface BrowserStorageAdapterOptions {
  *   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 — that is why the
- *   client's default is `'memory'`). If the API sets one, `storage: 'memory'` is
- *   the strongest configuration. If it does not and you cannot change it, keep
- *   the token's lifetime short and rotate it on refresh.
+ *   (`@molecule/api-resource-user` issues exactly this cookie — pass
+ *   `storage: 'memory'` when it does). `'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.
  * - **`kind: 'session'` narrows the window** to the tab's lifetime at the cost of
  *   losing the session in a new tab; `'local'` is the default because a reload is
  *   the requirement it exists for, and a fresh tab is the same person.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,4BAAiC,KACzC,cA6EF,CAAA"}

package/dist/browser-storage.js

@@ -29,10 +29,11 @@ const warn = (message, error) => {
  * own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
  * window, eight `waitForURL` timeouts).
  *
- * Pass it as `AuthClientConfig.storage` to keep the session across a page reload:
- * the client's default (`'memory'`) is lost on reload, and re-establishing the
- * session then needs a credential that survived — this adapter, or an httpOnly
- * session cookie the API sets (see the security note below).
+ * In a browser this IS the auth client's default `AuthClientConfig.storage`, so a scaffolded
+ * app keeps its session across a page reload with no extra wiring. Outside a browser (SSR, a Node
+ * test) the client defaults to `'memory'` instead, because there is no Web Storage to use. Pass
+ * `'memory'` explicitly to keep the bearer token out of script-reachable storage when the API sets
+ * an httpOnly session cookie (see the security note below).
  *
  * ```ts
  * import { createJWTAuthClient, createBrowserStorageAdapter } from '@molecule/app-auth'
@@ -43,7 +44,7 @@ const warn = (message, error) => {
  * })
  * ```
  *
- * The scaffold's `authConfig` already passes it, so a scaffolded app survives a
+ * The browser client already defaults to it, so a scaffolded app survives a
  * reload out of the box; each of these replaces that default:
  *
  * ```ts
@@ -63,10 +64,11 @@ const warn = (message, error) => {
  *   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 — that is why the
- *   client's default is `'memory'`). If the API sets one, `storage: 'memory'` is
- *   the strongest configuration. If it does not and you cannot change it, keep
- *   the token's lifetime short and rotate it on refresh.
+ *   (`@molecule/api-resource-user` issues exactly this cookie — pass
+ *   `storage: 'memory'` when it does). `'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.
  * - **`kind: 'session'` narrows the window** to the tab's lifetime at the cost of
  *   losing the session in a new tab; `'local'` is the default because a reload is
  *   the requirement it exists for, and a fresh tab is the same person.

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.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAUhB,WAAW,EACZ,MAAM,YAAY,CAAA;AA4CnB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,CAAC,SAAS,WAAW,GAAG,WAAW,EACnC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAEhE,SAAQ,gBAAqB,KAC5B,UAAU,CAAC,CAAC,EAAE,SAAS,CAokBzB,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAUhB,WAAW,EACZ,MAAM,YAAY,CAAA;AAmHnB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,CAAC,SAAS,WAAW,GAAG,WAAW,EACnC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAEhE,SAAQ,gBAAqB,KAC5B,UAAU,CAAC,CAAC,EAAE,SAAS,CA+wBzB,CAAA"}