@molecule/app-auth 1.8.2 → 3.0.0

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-23T18:55:10.568Z
+Generated: 2026-10-25T20:03:32.020Z
 -->
 
 # @molecule/app-auth
@@ -44,8 +44,8 @@ The first read of the client (`getState()`, `subscribe()`/`onAuthChange()`, a
 and an explicit `initialize()` returns the same promise, so a second call asks the
 server nothing. Keep the template's explicit call (it makes the first render
 deterministic); an entry file that drops it still restores instead of reporting
-`'loading'` forever (xr-molecule-flash-m192: a `main.tsx` rewrite dropped the line
-and 18 tests timed out on pages that never left their loading branch).
+`'loading'` forever (a `main.tsx` rewrite can drop the line, and every page
+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
@@ -71,12 +71,12 @@ 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 (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'` — that status means "no decision yet", so an
-auth request in flight (`state.loading`) keeps the decided status and does not
-unmount a Login/Register page mid-request (xr-molecule-flash-m380).
+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
+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
+Login/Register page mid-request.
 `validateSession()` is the background re-check that produces the last two: call
 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`
@@ -121,18 +121,18 @@ redirect or the app's own sign-in endpoint has already issued the token and retu
 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
+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`.
 
 **A custom user profile is typed once and used everywhere: `AuthClientConfig<MyUser>`,
 `createJWTAuthClient<MyUser>` and `useAuth<MyUser>()`.** The config's generic makes
 `mapAuthResponse` return `AuthResult<MyUser>`, so a mapper that omits a required custom
 field fails at the factory call instead of shipping a signed-in page whose navbar reads
-`undefined` (xr-molecule-flash-m255: the mapper kept `id`/`name`/`avatar` but dropped
-`username`, and the signed-in controls never rendered although login succeeded). Keep the
-wire user's fields and ADD the base identity fields; do not rebuild the profile field by
-field, and never hide a mismatch with `as unknown as MyUser`:
+`undefined` — a mapper that keeps `id`/`name`/`avatar` but drops `username` leaves the
+signed-in controls unrendered although login succeeded. The
+wire user carries the base fields too, `id` included — spread it, do not rebuild it
+field by field, and never hide a mismatch with `as unknown as MyUser`:
 
 ```typescript
 import type { AuthClientConfig, UserProfile } from '@molecule/app-auth'
@@ -145,18 +145,12 @@ interface MyUser extends UserProfile {
 
 const config: AuthClientConfig<MyUser> = {
   mapAuthResponse: (data) => {
-    const { user: wire } = data as { user: { token: string } & Omit<MyUser, 'id'> }
-    return {
-      accessToken: wire.token,
-      user: {
-        // Every wire field the pages read (`username`, `image`, …) survives…
-        ...wire,
-        // …plus the base fields the client derives its identity from.
-        id: wire.username,
-        name: wire.name ?? wire.username,
-        avatar: wire.image,
-      },
-    }
+    // The wire is the app's profile plus the bearer; `id` is the server's.
+    const { user: wire } = data as { user: { token: string } & MyUser }
+    // The bearer stays OUT of the profile: the client caches `user` in Web
+    // Storage, where a token copy is readable by any script on the origin.
+    const { token, ...profile } = wire
+    return { accessToken: token, user: profile }
   },
 }
 
@@ -164,11 +158,55 @@ const client = createJWTAuthClient<MyUser>(config)
 // React: `useAuth<MyUser>()` reads the same profile.
 ```
 
-A username-derived `id` can change during a profile save. It is not an immutable
-session identifier: `getSessionRevision()` tracks session ownership independently
-of profile fields, remains unchanged for profile updates and same-session
-refreshes, and changes when a session is replaced or ended. Compare revisions
-only within one client. React's `useProfileForm` uses this capability by default.
+That `id` is the API's account identifier. Do not derive one from a display field
+(`id: wire.username`) to borrow `UserProfile` for an API that has no id: the field
+changes, the fabricated id changes with it, and the value then reaches storage,
+`getUser()` and every page as if the server had said it.
+
+A profile does not have to extend `UserProfile` and does not need an `id`: the client
+stores and patches the object it is given and reads no field of it. Name the API's own
+shape, pass it to the factory and the config, and have the mapper return it complete —
+every configuration adapter is typed by the same `T` (`mapAuthResponse`, the
+`profileEndpoint`/`profileUpdateMethod`/`profileRequestBody` write transport,
+`shouldRestoreUser`, and `setSession`):
+
+```typescript
+import type { AuthClientConfig } from '@molecule/app-auth'
+import { createJWTAuthClient } from '@molecule/app-auth'
+
+interface SessionUser {
+  username: string
+  email: string
+  bio: string
+  image: string
+}
+
+const config: AuthClientConfig<SessionUser> = {
+  mapAuthResponse: (data) => {
+    const { user: wire } = data as { user: { token: string } & SessionUser }
+    // The bearer stays OUT of the profile: the client caches `user` in Web
+    // Storage, where a token copy is readable by any script on the origin.
+    const { token, ...profile } = wire
+    return { accessToken: token, user: profile }
+  },
+  profileEndpoint: (user) => '/people/' + encodeURIComponent(user.username),
+}
+
+const client = createJWTAuthClient<SessionUser>(config)
+// `client.getUser()` has `bio`/`image`; there is no `id` to fabricate.
+```
+
+The profile is named at the factory, never inferred from the mapper: an untyped
+`createJWTAuthClient({ mapAuthResponse })` stays `UserProfile`, whose required
+`id: string` is the default configuration's contract. An array, a function or a
+`Date` is not a profile the client can persist — see `AuthProfileShape`.
+
+A profile field can change during a profile save — a handle, or a username an app
+once derived an `id` from. It is not an immutable session identifier:
+`getSessionRevision()` tracks session ownership independently of profile fields,
+remains unchanged for profile updates and same-session refreshes, and changes when
+a session is replaced or ended. Compare revisions only within one client. React's
+`useProfileForm` uses this capability by default.
 
 **A profile-update transport that is not `PATCH` with bare JSON is a CONFIG field, not a
 hand-written client.** `updateProfile()` sends to `profileEndpoint` with `PATCH` and the
@@ -203,7 +241,11 @@ the client to change a method or an envelope also replaces the lifecycle that ke
 coherent, and hand-written adapters have had to repair those callbacks repeatedly.
 A pending profile response is published only to the session that sent it:
 signing out or explicitly adopting/signing in another session prevents the old
-response from replacing the active user's stored profile.
+response from changing the active user's stored profile. The answer is applied onto the
+stored profile field by field: a field it carries replaces the stored value (`null` clears
+it) and one it leaves out — or that `mapAuthResponse` leaves `undefined` — is kept, so a
+field the API clears by leaving it out must reach the client as `null`, answered by the API
+or mapped by `mapAuthResponse`.
 
 **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
@@ -257,16 +299,26 @@ fields with the factory's second generic, and `requestBody` receives exactly wha
 the form passed — `{ user: { username, email, password } }` goes out as-is.
 
 ```typescript
-import type { UserProfile } from '@molecule/app-auth'
 import { createJWTAuthClient } from '@molecule/app-auth'
 
-const realWorldAuth = createJWTAuthClient<UserProfile, { username: string }>({
+// RealWorld'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 {
+  username: string
+  email: string
+  bio: string
+  image: string
+}
+
+const realWorldAuth = createJWTAuthClient<RealWorldUser, { username: string }>({
   baseURL: '/api',
   authScheme: 'Token',
   requestBody: (_kind, payload) => ({ user: payload }),
   mapAuthResponse: (data) => {
-    const { user } = data as { user: { token: string; username: string; email: string } }
-    return { accessToken: user.token, user: { id: user.username, email: user.email } }
+    const { user: wire } = data as { user: { token: string } & RealWorldUser }
+    // Keep every wire field; the bearer stays out of the cached profile.
+    const { token, ...profile } = wire
+    return { accessToken: token, user: profile }
   },
 })
 
@@ -676,9 +728,12 @@ interface AuthClient<
 
   /**
    * Updates the current user's profile.
-   * Returns the saved response. If the session is explicitly replaced or ended
-   * while the request is pending, that response does not replace the current
-   * session's user or persisted cache.
+   * 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.
    */
   updateProfile(data: Partial<T>): Promise<T>
 
@@ -742,9 +797,6 @@ interface AuthClient<
    * 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
-   * fetches viewer-dependent data on mount waits here instead of going out anonymously
-   * (see `setAuthGate` in `@molecule/app-http`).
-   *
 // … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
 ```
 
@@ -761,23 +813,15 @@ interface StorageAdapter {
 }
 ```
 
-#### `AuthClientConfig`
+#### `AuthClientConfigOptions`
 
-Configuration options for creating an auth client, including API
-endpoints, storage strategy, token refresh, and OAuth providers.
+Every option {@link AuthClientConfig} accepts, typed by the profile.
 
-Type it with the app's user — `AuthClientConfig<MyUser>` — the same type
-`createJWTAuthClient<MyUser>` returns and `useAuth<MyUser>()` reads. That
-makes {@link mapAuthResponse} return `AuthResult<MyUser>`, so a mapper that
-omits a required custom field is a type error instead of a signed-in page
-reading `undefined` (xr-molecule-flash-m255). Keep every wire field the pages
-read (spread the wire user and add `id`/`name`/`avatar`); mapping a field to a
-different name does not preserve the original, and a `as unknown as MyUser`
-assertion hides the loss. See the module docs for the wire-preserving
-adapter.
+Use `AuthClientConfig<T>` rather than this type: it adds the profile-shape
+check. This interface exists so each member's documentation is addressable.
 
 ````typescript
-interface AuthClientConfig<T extends UserProfile = UserProfile> {
+interface AuthClientConfigOptions<T extends object = UserProfile> {
   /**
    * API base URL.
    */
@@ -807,6 +851,8 @@ interface AuthClientConfig<T extends UserProfile = UserProfile> {
    * 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.
    */
   profileEndpoint?: string | ((user: Readonly<T>) => string)
@@ -893,7 +939,16 @@ interface AuthClientConfig<T extends UserProfile = UserProfile> {
   /**
    * 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 })`.
+   * RealWorld, for example — 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()`,
@@ -901,17 +956,26 @@ interface AuthClientConfig<T extends UserProfile = UserProfile> {
    * 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
+   * 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.
    */
-  mapAuthResponse?: (data: unknown) => AuthResult<T>
+  mapAuthResponse?: (data: unknown) => AuthResult<NoInfer<T>>
 
   /**
    * Where the access/refresh token and the cached user are kept — the field that
@@ -936,25 +1000,6 @@ interface AuthClientConfig<T extends UserProfile = UserProfile> {
    * 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
-   * second store or a restore script beside this client — that races the client's
-   * own restore, and either side's 401 signs the user out for good.
-   *
-   * Any adapter with `getItem`/`setItem`/`removeItem` works — the methods are
-   * SYNCHRONOUS, so the async `@molecule/app-storage` provider
-   * (`getProvider()`, whose `get()` returns a Promise) is NOT one: wrap the
-   * `Storage` object it was built on (`createBrowserStorageAdapter({ storage })`),
-   * or store a different way.
-   *
-   * @example
-   * ```typescript
-   * import { createBrowserStorageAdapter } from '@molecule/app-auth'
-   *
-   * // 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'
-   * // Only this tab's lifetime, at a narrower exposure than localStorage:
-   * storage: createBrowserStorageAdapter({ kind: 'session' })
 // … truncated — the full declaration is in node_modules/@molecule/app-auth/dist/types.d.ts
 ````
 
@@ -987,6 +1032,86 @@ Which Web Storage area {@link createBrowserStorageAdapter} persists to:
 type BrowserStorageKind = 'local' | 'session'
 ```
 
+#### `AuthProfileShape`
+
+The profile shapes the auth client accepts: a JSON object type of named
+fields, and nothing else.
+
+The client does not read a field of the profile, but it does persist it:
+`tokenStorage.setUser` writes it with `JSON.stringify` and `getUser` restores
+it with `JSON.parse`, and `updateProfile(data: Partial<T>)` patches it
+field-wise. An array has no named fields to read or patch, `JSON.stringify`
+drops a function entirely, and a `Date` comes back from `JSON.parse` as a
+string while still typed as a `Date` — so those three types are rejected on
+every entrypoint that takes a profile type (`createJWTAuthClient`,
+the default-auth factories, `AuthClientConfig`).
+
+The check is on the TOP-LEVEL shape only: a class instance, or a `Date` in a
+nested field, is the app's own persistence contract, not this validator's.
+A named `interface`, a type literal, an intersection and the empty object
+type all satisfy it — `{}` compiles because it is a JSON object that
+round-trips unchanged, not an invalid form.
+
+A union is checked member by member: `ExistingUser | ExistingUser[]` contains
+an array, so it is not an object-only profile either, and the shared
+rejection test (`AuthProfileIsRejected`, used by
+{@link AuthProfileConstraint} and {@link AuthProfileGuard}) rejects it as a
+whole.
+
+```typescript
+type AuthProfileShape<T> = T extends readonly unknown[] | ((...args: never[]) => unknown) | Date
+  ? AuthProfileRejection
+  : object
+```
+
+#### `AuthProfileGuard`
+
+Requires a profile type to satisfy {@link AuthProfileShape}: an invalid
+profile makes {@link AuthClientConfig} impossible to populate, so the
+annotation itself is the error. It shares the entrypoints' rejection test,
+so a union with an invalid member is rejected here too.
+
+```typescript
+type AuthProfileGuard<T> =
+  AuthProfileIsRejected<T> extends true
+    ? { readonly [K in AuthProfileRejection]: never }
+    : Record<never, never>
+```
+
+#### `AuthProfileConstraint`
+
+The constraint every entrypoint puts on a profile type: a JSON object type of
+named fields ({@link AuthProfileShape}), and `object` for `any`.
+
+`any` is the caller's explicit opt-out of profile typing, not an invalid JSON
+shape: `createJWTAuthClient<any>()`, `getClient<any>()` and
+`AuthClientConfig<any>` name it deliberately. It is detected explicitly
+(`0 extends 1 & T`) and accepted. Every other type is measured against
+{@link AuthProfileShape}, member by member when it is a union: a union that
+holds an array, a function or a `Date` is rejected as a whole, so
+`createJWTAuthClient<ExistingUser | ExistingUser[]>()` is the same type error
+as `createJWTAuthClient<ExistingUser[]>()`.
+
+Forwarding a profile through your own generic copies this constraint, so the
+profile keeps being checked:
+
+```typescript
+import type { AuthClientConfig, AuthProfileConstraint } from '@molecule/app-auth'
+import { createJWTAuthClient } from '@molecule/app-auth'
+
+export function makeAuth<T extends AuthProfileConstraint<T>>(config: AuthClientConfig<T>) {
+  return createJWTAuthClient<T>(config)
+}
+```
+
+`T extends object` is not enough: the factory rejects arrays, functions and
+`Date` at its own constraint, so a forwarder written that way does not
+compile. Copy this type instead.
+
+```typescript
+type AuthProfileConstraint<T> = AuthProfileIsRejected<T> extends true ? never : object
+```
+
 #### `RegisterExtraShape`
 
 The shape an app's own registration fields (`TRegister`) must satisfy.
@@ -1091,11 +1216,15 @@ type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'unavailable
 
 Auth event types.
 
+A sign-in event carries the client's own profile type, so a listener on a
+client typed with the app's profile reads that profile — including one that
+does not extend {@link UserProfile}. The default is {@link UserProfile}.
+
 ```typescript
-type AuthEvent =
-  | { type: 'login'; user: UserProfile }
+type AuthEvent<T = UserProfile> =
+  | { type: 'login'; user: T }
   | { type: 'logout' }
-  | { type: 'register'; user: UserProfile }
+  | { type: 'register'; user: T }
   | { type: 'refresh' }
   | { type: 'error'; error: string }
 ```
@@ -1104,8 +1233,63 @@ type AuthEvent =
 
 Callback invoked when an authentication event occurs (login, logout, etc.).
 
+A listener is typed by the client's profile: `AuthEventListener<MyUser>`
+receives `AuthEvent<MyUser>`, so a sign-in event's `user` is the app's own
+shape — including a profile that does not extend {@link UserProfile}. The
+default is {@link UserProfile}.
+
+An inline arrow is contextually typed, so its `event` parameter needs no
+annotation. Because listener parameters are contravariant, a client whose
+profile extends {@link UserProfile} also accepts a listener written against
+the default `AuthEventListener` (those events carry every `UserProfile`
+field). A client whose profile does NOT extend `UserProfile` — an API user
+with no `id` — accepts only `AuthEventListener<T>`: a default listener would
+read an `id` the runtime user does not have.
+
+**Migration to 2.0.** External providers that implement {@link AuthClient}
+declare their listener parameter as `AuthEventListener<T>`
+(`addEventListener(listener: AuthEventListener<T>): () => void`). The
+previous `addEventListener(listener: AuthEventListener)` declaration, which
+claimed every client's events carry a `UserProfile`, is no longer assignable
+once the client's profile is a custom one.
+
+```typescript
+type AuthEventListener<T = UserProfile> = (event: AuthEvent<T>) => void
+```
+
+#### `AuthClientConfig`
+
+Configuration options for creating an auth client, including API
+endpoints, storage strategy, token refresh, and OAuth providers.
+
+Type it with the app's user — `AuthClientConfig<MyUser>` — the same type
+`createJWTAuthClient<MyUser>` returns and `useAuth<MyUser>()` reads. That
+makes {@link AuthClientConfigOptions.mapAuthResponse} return
+`AuthResult<MyUser>`, so a mapper that omits a required custom field is a type
+error instead of a signed-in page reading `undefined`. Keep every wire field the pages
+read by spreading the
+wire user — the base fields (`id`, `name`, `avatar`) come from the server like
+any other, never re-derived from a mutable display field such as a username;
+mapping a field to a different name does not preserve the original, and an
+`as unknown as MyUser` assertion hides the loss. See the module docs for the
+wire-preserving adapter.
+
+`T` is the app's OWN profile shape and need not extend {@link UserProfile}:
+the client stores and patches the object it is given and reads no field of
+it, so an API whose user has no `id` — `{ username, email, bio, image }` —
+is typed by its own `interface` directly, with no fabricated `id`. The
+default, {@link UserProfile}, still requires `id: string`. A primitive,
+`null`, an array, a function or a `Date` — or a union containing one — is
+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`.)_
+
 ```typescript
-type AuthEventListener = (event: AuthEvent) => void
+type AuthClientConfig<T extends object = UserProfile> = AuthClientConfigOptions<T> &
+  AuthProfileGuard<T>
 ```
 
 ### Functions
@@ -1118,8 +1302,8 @@ The auth client's `StorageAdapter` over the browser's Web Storage.
 token AND the user in the store, `initialize()` restores the authenticated state synchronously
 (`whenRestored()` is already resolved on the first render); render from it, and validate the
 token as a background request — never in front of the first render. A page that waits on its
-own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
-window, eight `waitForURL` timeouts).
+own `/me` call pays a round trip on EVERY navigation: a 1–5 s restore window is enough to
+time out a navigation that expects the signed-in UI.
 
 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
@@ -1160,8 +1344,25 @@ Creates a simple JWT-based auth client.
 This is a basic implementation that can be extended or replaced
 with more sophisticated auth providers.
 
+`T` is the profile the API returns. The default, `UserProfile`, requires
+`id: string`, and an untyped call — `createJWTAuthClient({ mapAuthResponse })`
+— KEEPS that default: the profile is never inferred from the config (no
+member of it, and not from an annotated config variable), so a mapper that
+returns a user without `id` fails to compile instead of quietly becoming the
+client's profile. To use the app's own profile, name it here,
+`createJWTAuthClient<SessionUser>(config)`; a profile with no `id`
+(`{ username, email, bio, image }`) is then used as-is. Pass the same type to
+the config (`AuthClientConfig<SessionUser>`), so `mapAuthResponse` and the
+write transport are checked against the profile the client and the React
+hooks hand to your pages.
+
+`any` is accepted (`createJWTAuthClient<any>()`) as the caller's explicit
+opt-out; array, function and `Date` profiles are rejected. A wrapper that
+forwards a profile type copies `AuthProfileConstraint` (see
+{@link AuthClientConfig}'s migration note).
+
 ```typescript
-function createJWTAuthClient(config?: AuthClientConfig<T>): AuthClient<T, TRegister>
+function createJWTAuthClient(config?: NoInfer<AuthClientConfigOptions<T>>): AuthClient<T, TRegister>
 ```
 
 - `config` — Auth client configuration including endpoints, storage, and refresh settings.
@@ -1281,7 +1482,7 @@ function getUser(): T | null
 Logs in with the given credentials (email/username + password).
 
 ```typescript
-function login(credentials: LoginCredentials): Promise<AuthResult<UserProfile>>
+function login(credentials: LoginCredentials): Promise<AuthResult<T>>
 ```
 
 - `credentials` — Email/username and password.
@@ -1302,8 +1503,12 @@ function logout(): Promise<void>
 
 Registers a new user account.
 
+The registration extra fields stay the FIRST type argument, exactly as before
+(`register<{ username: string }>(data)` keeps compiling); the profile is the
+second one (`register<{ username: string }, SessionUser>(data)`).
+
 ```typescript
-function register(data: RegisterData<TExtra>): Promise<AuthResult<UserProfile>>
+function register(data: RegisterData<TExtra>): Promise<AuthResult<T>>
 ```
 
 - `data` — Registration data (email, password, and any `TExtra` fields).
@@ -1328,7 +1533,8 @@ 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 })`),
+  token and user out of the answer — keeping the wire bearer OUT of the profile,
+  because the client caches `user` in Web Storage (see the mapper example below) —
   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
@@ -1349,6 +1555,16 @@ Peer dependencies:
 - Client-side auth state is UX only — the server enforces authorization on
   every request; hiding a screen is not protection.
 
+The mapper for such an envelope, with the wire token kept out of the cached
+profile (`d` is the parsed answer):
+
+```typescript
+;(d) => {
+  const { token, ...user } = d.user
+  return { accessToken: token, user }
+}
+```
+
 ## E2E Tests
 
 Integration checklist — drive the real UI (live preview, no mocks), adapt

package/dist/browser-storage.d.ts

@@ -35,8 +35,8 @@ export interface BrowserStorageAdapterOptions {
  * token AND the user in the store, `initialize()` restores the authenticated state synchronously
  * (`whenRestored()` is already resolved on the first render); render from it, and validate the
  * token as a background request — never in front of the first render. A page that waits on its
- * own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
- * window, eight `waitForURL` timeouts).
+ * own `/me` call pays a round trip on EVERY navigation: a 1–5 s restore window is enough to
+ * time out a navigation that expects the signed-in UI.
  *
  * 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

package/dist/browser-storage.js

@@ -26,8 +26,8 @@ const warn = (message, error) => {
  * token AND the user in the store, `initialize()` restores the authenticated state synchronously
  * (`whenRestored()` is already resolved on the first render); render from it, and validate the
  * token as a background request — never in front of the first render. A page that waits on its
- * own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
- * window, eight `waitForURL` timeouts).
+ * own `/me` call pays a round trip on EVERY navigation: a 1–5 s restore window is enough to
+ * time out a navigation that expects the signed-in UI.
  *
  * 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

package/dist/client.d.ts

@@ -5,21 +5,38 @@
  *
  * @module
  */
-import type { AuthClient, AuthClientConfig, RegisterExtraShape, UserProfile } from './types.js';
+import type { AuthClient, AuthClientConfigOptions, AuthProfileConstraint, RegisterExtraShape, UserProfile } from './types.js';
 /**
  * Creates a simple JWT-based auth client.
  *
  * This is a basic implementation that can be extended or replaced
  * with more sophisticated auth providers.
  *
- * @template T - The user profile the API returns. Pass it to the config too
- *   (`AuthClientConfig<T>`), so `mapAuthResponse` is checked against the same
- *   profile the client and the React hook hand to your pages.
+ * `T` is the profile the API returns. The default, `UserProfile`, requires
+ * `id: string`, and an untyped call — `createJWTAuthClient({ mapAuthResponse })`
+ * — KEEPS that default: the profile is never inferred from the config (no
+ * member of it, and not from an annotated config variable), so a mapper that
+ * returns a user without `id` fails to compile instead of quietly becoming the
+ * client's profile. To use the app's own profile, name it here,
+ * `createJWTAuthClient<SessionUser>(config)`; a profile with no `id`
+ * (`{ username, email, bio, image }`) is then used as-is. Pass the same type to
+ * the config (`AuthClientConfig<SessionUser>`), so `mapAuthResponse` and the
+ * write transport are checked against the profile the client and the React
+ * hooks hand to your pages.
+ *
+ * `any` is accepted (`createJWTAuthClient<any>()`) as the caller's explicit
+ * opt-out; array, function and `Date` profiles are rejected. A wrapper that
+ * forwards a profile type copies `AuthProfileConstraint` (see
+ * {@link AuthClientConfig}'s migration note).
+ *
+ * @template T - The user profile the API returns: a JSON object type of named
+ *   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).
  *   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.
  */
-export declare const createJWTAuthClient: <T extends UserProfile = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>>(config?: AuthClientConfig<T>) => AuthClient<T, TRegister>;
+export declare const createJWTAuthClient: <T extends AuthProfileConstraint<T> = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>>(config?: NoInfer<AuthClientConfigOptions<T>>) => AuthClient<T, TRegister>;
 //# sourceMappingURL=client.d.ts.map