@molecule/app-auth 1.8.2 → 3.0.0

package/dist/index.js

@@ -35,8 +35,8 @@
  * 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
@@ -62,12 +62,12 @@
  * `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`
@@ -112,18 +112,18 @@
  * 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'
@@ -136,18 +136,12 @@
  *
  * 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 }
  *   },
  * }
  *
@@ -155,11 +149,55 @@
  * // 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
@@ -194,7 +232,11 @@
  * 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
@@ -227,7 +269,8 @@
  * @remarks
  * - **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
@@ -248,6 +291,16 @@
  * - 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 }
+ * }
+ * ```
+ *
  * @example
  * ```typescript
  * import { createJWTAuthClient, setClient } from '@molecule/app-auth'
@@ -267,16 +320,26 @@
  * 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 }
  *   },
  * })
  *

package/dist/index.js.map

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

package/dist/provider.d.ts

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import type { AuthClient, RegisterExtraShape, UserProfile } from './types.js';
+import type { AuthClient, AuthProfileConstraint, RegisterExtraShape, UserProfile } from './types.js';
 /**
  * Registers an auth client as the active singleton. Called by bond
  * packages during application startup.
@@ -21,13 +21,16 @@ export declare const setClient: <T = UserProfile, TRegister extends RegisterExtr
 /**
  * Retrieves the bonded auth client, throwing if none is configured.
  *
- * @template T - The user profile the bonded client returns.
+ * @template T - The user profile the bonded client returns: a JSON object type
+ *   of named fields (see {@link AuthProfileConstraint}), including an app
+ *   profile with no `id`. Name it at the call (`getClient<SessionUser>()`); it
+ *   is never inferred from a config.
  * @template TRegister - The app's own registration fields, at the top level
  *   of `register()` (see `RegisterData`).
  * @returns The bonded auth client.
  * @throws {Error} If no auth client has been bonded.
  */
-export declare const getClient: <T extends UserProfile = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>>() => AuthClient<T, TRegister>;
+export declare const getClient: <T extends AuthProfileConstraint<T> = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>>() => AuthClient<T, TRegister>;
 /**
  * Checks whether an auth client is currently bonded.
  *

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAI7E;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,GAAG,WAAW,EACf,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAEtE,QAAQ,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,KAC/B,IAEF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,SAAS,WAAW,GAAG,WAAW,EACnC,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,OACnE,UAAU,CAAC,CAAC,EAAE,SAAS,CAE3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,OAE5B,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAIpG;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,GAAG,WAAW,EACf,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAEtE,QAAQ,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,KAC/B,IAEF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,SAAS,qBAAqB,CAAC,CAAC,CAAC,GAAG,WAAW,EAChD,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,OACnE,UAAU,CAAC,CAAC,EAAE,SAAS,CAE3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,OAE5B,CAAA"}

package/dist/provider.js

@@ -24,7 +24,10 @@ export const setClient = (client) => {
 /**
  * Retrieves the bonded auth client, throwing if none is configured.
  *
- * @template T - The user profile the bonded client returns.
+ * @template T - The user profile the bonded client returns: a JSON object type
+ *   of named fields (see {@link AuthProfileConstraint}), including an app
+ *   profile with no `id`. Name it at the call (`getClient<SessionUser>()`); it
+ *   is never inferred from a config.
  * @template TRegister - The app's own registration fields, at the top level
  *   of `register()` (see `RegisterData`).
  * @returns The bonded auth client.

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAI3E,MAAM,SAAS,GAAG,aAAa,CAAA;AAE/B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAIvB,MAAgC,EAC1B,EAAE;IACR,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;AACzB,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAGK,EAAE;IAC9B,OAAO,WAAW,CAA2B,SAAS,CAAC,CAAA;AACzD,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAY,EAAE;IACrC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAI3E,MAAM,SAAS,GAAG,aAAa,CAAA;AAE/B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAIvB,MAAgC,EAC1B,EAAE;IACR,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;AACzB,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAGK,EAAE;IAC9B,OAAO,WAAW,CAA2B,SAAS,CAAC,CAAA;AACzD,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAY,EAAE;IACrC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA"}

package/dist/types.d.ts

@@ -33,6 +33,117 @@ export interface UserProfile {
      */
     metadata?: Record<string, unknown>;
 }
+/**
+ * The sentence every invalid profile type is rejected with.
+ */
+type AuthProfileRejection = 'An auth profile must be a JSON object type of named fields, not an array, a function or a Date';
+/**
+ * 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.
+ *
+ * @template T - The candidate profile type.
+ */
+export type AuthProfileShape<T> = T extends readonly unknown[] | ((...args: never[]) => unknown) | Date ? AuthProfileRejection : object;
+/**
+ * Whether `T` is, or is a union containing, a shape the client cannot persist —
+ * an array, a function or a `Date` ({@link AuthProfileShape}).
+ *
+ * This is the ONE decision {@link AuthProfileConstraint} and
+ * {@link AuthProfileGuard} share, so the entrypoints and `AuthClientConfig`
+ * cannot drift apart.
+ *
+ * Three TypeScript behaviors shape it:
+ *
+ * - **No distribution.** `AuthProfileShape<T>` already distributes, so a union
+ *   `Good | Bad` yields `object | AuthProfileRejection`. Wrapping BOTH sides of
+ *   the test in tuples compares those unions as a whole, so one invalid member
+ *   rejects the whole union. The plain `AuthProfileShape<T> extends
+ *   AuthProfileRejection` form instead asks whether the ENTIRE union is the
+ *   rejection, which a valid sibling makes false — that is the union hole this
+ *   closes.
+ * - **`any` is checked first.** `any` is the caller's explicit opt-out of
+ *   profile typing, not an invalid member, but `AuthProfileShape<any>` resolves
+ *   to `AuthProfileRejection | object`, which the tuple test reads as "contains
+ *   a rejection". `0 extends 1 & T` detects `any` (and only `any` — `never`,
+ *   `unknown` and `object` are all false) and takes the accepted branch.
+ * - **Deferred at the outer edge.** `[T] extends [unknown]` keeps the whole
+ *   check deferred while `T` is an unresolved type parameter (it is always true
+ *   for a concrete type, and does not distribute over a union). Without it,
+ *   TypeScript resolves the inner `0 extends 1 & T` while checking a forwarder's
+ *   constraint `T extends AuthProfileConstraint<T>` and reports TS2313 ("Type
+ *   parameter 'T' has a circular constraint"); with it, the constraint checks at
+ *   the call site.
+ *
+ * `never`, `unknown` and the primitives are not this helper's job: each
+ * entrypoint's `extends object` requirement rejects them, unchanged.
+ *
+ * @template T - The candidate profile type.
+ */
+type AuthProfileIsRejected<T> = [T] extends [unknown] ? 0 extends 1 & T ? false : [AuthProfileRejection] extends [AuthProfileShape<T>] ? true : false : never;
+/**
+ * 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.
+ *
+ * @template T - The candidate profile type.
+ */
+export type AuthProfileGuard<T> = AuthProfileIsRejected<T> extends true ? {
+    readonly [K in AuthProfileRejection]: never;
+} : Record<never, never>;
+/**
+ * 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.
+ *
+ * @template T - The candidate profile type.
+ */
+export type AuthProfileConstraint<T> = AuthProfileIsRejected<T> extends true ? never : object;
 /**
  * Email/password login credentials with optional "remember me" flag.
  */
@@ -223,15 +334,21 @@ export interface AuthState<T = UserProfile> {
 }
 /**
  * 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}.
+ *
+ * @template T - The user profile the API returns.
  */
-export type AuthEvent = {
+export type AuthEvent<T = UserProfile> = {
     type: 'login';
-    user: UserProfile;
+    user: T;
 } | {
     type: 'logout';
 } | {
     type: 'register';
-    user: UserProfile;
+    user: T;
 } | {
     type: 'refresh';
 } | {
@@ -240,8 +357,30 @@ export 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.
+ *
+ * @template T - The user profile the API returns.
  */
-export type AuthEventListener = (event: AuthEvent) => void;
+export type AuthEventListener<T = UserProfile> = (event: AuthEvent<T>) => void;
 /**
  * The error an auth client rejects with when the API answers a non-ok HTTP
  * response. It is the {@link I18nError} the client throws — same `i18nKey`,
@@ -409,9 +548,12 @@ export interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShap
     confirmPasswordReset(data: PasswordResetConfirm): Promise<void>;
     /**
      * 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>;
     /**
@@ -498,8 +640,22 @@ export interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShap
     getToken?(): string | null;
     /**
      * Adds an auth event listener.
-     */
-    addEventListener(listener: AuthEventListener): () => void;
+     *
+     * The listener is typed by this client's profile: one signature,
+     * `AuthEventListener<T>`, so an inline arrow is contextually typed and `event`
+     * is never implicitly `any`. A client whose profile extends
+     * {@link UserProfile} also accepts a default {@link AuthEventListener}: when
+     * `T` extends `UserProfile`, `AuthEvent<T>` is assignable to
+     * `AuthEvent<UserProfile>`, so a listener that takes the wider default event
+     * accepts every event this client emits and keeps compiling. (`UserProfile`
+     * is the wider type here — it has fewer required fields — and the assignable
+     * direction runs from the client's `AuthEvent<T>` to the listener's
+     * `AuthEvent<UserProfile>`.) A profile that does not extend `UserProfile`
+     * (no `id`) rejects the default listener: an `AuthEvent<UserProfile>` would
+     * promise an `id` the runtime user does not have, and the narrower-typed
+     * event is not assignable to it.
+     */
+    addEventListener(listener: AuthEventListener<T>): () => void;
     /**
      * Destroys the auth client.
      */
@@ -520,18 +676,65 @@ export interface StorageAdapter {
  *
  * 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.
- *
- * @template T - The user profile the API returns. The default,
- *   {@link UserProfile}, keeps the untyped configuration working.
+ * 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
+ * `mapAuthResponse`, `profileEndpoint`, `profileRequestBody` or
+ * `shouldRestoreUser`, and not from a config variable the caller annotated as
+ * `AuthClientConfig<MyUser>`. An untyped call stays typed `UserProfile`, so the
+ * default configuration keeps requiring `id: string`. Name the profile at the
+ * call (`createJWTAuthClient<MyUser>(config)`) — which also checks this config
+ * against `MyUser`.
+ *
+ * **Callers upgrading from 1.8 — three shapes now need the profile at the call.**
+ * Each was accepted by 1.8 and is a type error here; each has a one-line fix:
+ *
+ * 1. A mapper that supplied the profile
+ *    (`createJWTAuthClient({ mapAuthResponse: (d): AuthResult<MyUser> => … })`)
+ *    is now typed `UserProfile`. Name it on the factory:
+ *    `createJWTAuthClient<MyUser>({ mapAuthResponse })`.
+ * 2. A config variable annotated `AuthClientConfig<MyUser>` with a profile that
+ *    extends `UserProfile` used to supply the type argument. Pass it:
+ *    `createJWTAuthClient<MyUser>(config)`. (A no-id profile was already
+ *    rejected by 1.8's `T extends UserProfile`.)
+ * 3. Generic forwarding written `function make<T extends UserProfile>(config: AuthClientConfig<T>)`
+ *    no longer satisfies the factory's constraint. Copy the named constraint:
+ *    `function make<T extends AuthProfileConstraint<T>>(config: AuthClientConfig<T>)`.
+ *
+ * `any` is accepted at every entrypoint (`createJWTAuthClient<any>()`,
+ * `getClient<any>()`), so a caller that deliberately opted out keeps compiling.
+ *
+ * @template T - The user profile the API returns: a JSON object type of named
+ *   fields. The default, {@link UserProfile}, keeps the untyped configuration
+ *   working.
+ */
+export type AuthClientConfig<T extends object = UserProfile> = AuthClientConfigOptions<T> & AuthProfileGuard<T>;
+/**
+ * Every option {@link AuthClientConfig} accepts, typed by the profile.
+ *
+ * Use `AuthClientConfig<T>` rather than this type: it adds the profile-shape
+ * check. This interface exists so each member's documentation is addressable.
+ *
+ * @template T - The user profile the API returns.
  */
-export interface AuthClientConfig<T extends UserProfile = UserProfile> {
+export interface AuthClientConfigOptions<T extends object = UserProfile> {
     /**
      * API base URL.
      */
@@ -556,6 +759,8 @@ export 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);
@@ -634,7 +839,16 @@ export 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()`,
@@ -642,17 +856,26 @@ export 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
      * decides whether a page reload keeps the user signed in.
@@ -760,4 +983,5 @@ export interface TokenStorage {
     setUser<T = UserProfile>(user: T | null): void;
     clear(): void;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map