@udibo/oauth2 0.4.1 → 0.5.0

package/esm/identity/external/apple-client-secret.js

@@ -67,7 +67,8 @@ async function importPrivateKey(providerId, pem) {
  *
  * @throws {ExternalAuthError} `configuration` naming the offending input when
  *   the team id / key id / client id is empty, the `.p8` is not a valid P-256
- *   key, or the requested TTL exceeds Apple's cap.
+ *   key, or the requested TTL is not a finite number between 1 and Apple's
+ *   cap (`NaN` and `Infinity` are rejected, never signed into `exp`).
  *
  * @example
  * ```ts
@@ -86,7 +87,8 @@ export async function generateAppleClientSecret(options) {
     const clientId = requireNonEmpty(providerId, options.clientId, "client id (Services ID)");
     const ttl = options.expiresInSeconds ??
         DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS;
-    if (ttl <= 0 || ttl > APPLE_CLIENT_SECRET_MAX_TTL_SECONDS) {
+    if (!Number.isFinite(ttl) || ttl <= 0 ||
+        ttl > APPLE_CLIENT_SECRET_MAX_TTL_SECONDS) {
         throw configError(providerId, `Apple client secret TTL must be between 1 and ` +
             `${APPLE_CLIENT_SECRET_MAX_TTL_SECONDS} seconds (6 months); ` +
             `got ${ttl}.`);
@@ -111,10 +113,11 @@ function encodeSegment(value) {
 /**
  * Build a self-renewing Apple client-secret source. It signs a secret with
  * {@link generateAppleClientSecret} on first call, caches it, and re-signs
- * automatically once the cached secret is within `renewBeforeSeconds` of expiry
- * — so a long-lived {@link appleProvider} never presents an expired assertion.
- * The key material is validated on the first call, surfacing a misconfiguration
- * as a `configuration` {@link ExternalAuthError}.
+ * automatically once the cached secret is within `renewBeforeSeconds` (default
+ * one hour) of expiry — so a long-lived {@link appleProvider} never presents
+ * an expired assertion. The key material is validated on the first call, not
+ * at construction, surfacing a misconfiguration as a `configuration`
+ * {@link ExternalAuthError}; a failed call caches nothing.
  */
 export function createAppleClientSecretFactory(options) {
     const ttl = options.expiresInSeconds ??

package/esm/identity/external/apple.d.ts

@@ -3,9 +3,9 @@
  * {@link oidcProvider}: its client secret is a signed ES256 JWT rather than a
  * static string (see {@link generateAppleClientSecret}), it authenticates the
  * client in the token body (`client_secret_post`), and it requires
- * `response_mode=form_post` whenever profile scopes are requested. This is a
- * dedicated {@link ExternalProvider} that exchanges the code, then verifies the
- * `id_token` signature against Apple's JWKS.
+ * `response_mode=form_post` when the `name` or `email` scope is requested.
+ * This is a dedicated {@link ExternalProvider} that exchanges the code, then
+ * verifies the `id_token` signature against Apple's JWKS.
  *
  * The user's name is returned by Apple **only** on the first authorization, in
  * the `form_post` body's `user` field — never in the `id_token`. This connector
@@ -33,20 +33,27 @@ export interface AppleProviderOptions extends Pick<AppleClientSecretOptions, "te
      * `.p8` key material. Defaults to a cached factory over the key material.
      */
     clientSecret?: AppleClientSecretFactory;
-    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    /**
+     * Fetch implementation for all provider traffic. Defaults to
+     * `globalThis.fetch`. A wrapper must pass `init` through intact: its
+     * `redirect` and `signal` carry the connector's redirect refusal and timeout.
+     */
     fetch?: typeof fetch;
 }
 /**
  * Creates a Sign in with Apple connector with id `"apple"`.
  *
- * The flow requests `response_mode=form_post` (Apple's requirement when `name`
- * or `email` scope is present), exchanges the code at Apple's token endpoint
- * with a freshly-signed client-secret JWT, and verifies the returned
+ * The flow requests `response_mode=form_post` whenever any scope is requested
+ * (Apple requires it for `name` or `email`), exchanges the code at Apple's
+ * token endpoint with the client-secret JWT from the factory (by default
+ * cached and re-signed an hour before it expires), and verifies the returned
  * `id_token`'s RS256 signature against Apple's published keys before trusting
  * its claims (`iss`, `aud`, `azp`, `exp`, and the `nonce` when one was sent,
- * checked exactly as {@link oidcProvider} checks them). Apple's
- * private-relay addresses (`@privaterelay.appleid.com`) are ordinary verified
- * emails and are returned as-is. The raw `id_token` claims — including
+ * checked as {@link oidcProvider} checks them, with the default `azp` policy).
+ * `emailVerified` is `true` when Apple's `email_verified` claim is `true` or
+ * the string `"true"`; private-relay addresses
+ * (`@privaterelay.appleid.com`) are returned as-is. The raw `id_token`
+ * claims — including
  * `is_private_email` — stay on {@link ExternalProfile.raw}.
  *
  * @example

package/esm/identity/external/apple.js

@@ -3,9 +3,9 @@
  * {@link oidcProvider}: its client secret is a signed ES256 JWT rather than a
  * static string (see {@link generateAppleClientSecret}), it authenticates the
  * client in the token body (`client_secret_post`), and it requires
- * `response_mode=form_post` whenever profile scopes are requested. This is a
- * dedicated {@link ExternalProvider} that exchanges the code, then verifies the
- * `id_token` signature against Apple's JWKS.
+ * `response_mode=form_post` when the `name` or `email` scope is requested.
+ * This is a dedicated {@link ExternalProvider} that exchanges the code, then
+ * verifies the `id_token` signature against Apple's JWKS.
  *
  * The user's name is returned by Apple **only** on the first authorization, in
  * the `form_post` body's `user` field — never in the `id_token`. This connector
@@ -33,14 +33,17 @@ const SIGNATURE_NOT_VERIFIED = `Apple id_token signature did not verify against
 /**
  * Creates a Sign in with Apple connector with id `"apple"`.
  *
- * The flow requests `response_mode=form_post` (Apple's requirement when `name`
- * or `email` scope is present), exchanges the code at Apple's token endpoint
- * with a freshly-signed client-secret JWT, and verifies the returned
+ * The flow requests `response_mode=form_post` whenever any scope is requested
+ * (Apple requires it for `name` or `email`), exchanges the code at Apple's
+ * token endpoint with the client-secret JWT from the factory (by default
+ * cached and re-signed an hour before it expires), and verifies the returned
  * `id_token`'s RS256 signature against Apple's published keys before trusting
  * its claims (`iss`, `aud`, `azp`, `exp`, and the `nonce` when one was sent,
- * checked exactly as {@link oidcProvider} checks them). Apple's
- * private-relay addresses (`@privaterelay.appleid.com`) are ordinary verified
- * emails and are returned as-is. The raw `id_token` claims — including
+ * checked as {@link oidcProvider} checks them, with the default `azp` policy).
+ * `emailVerified` is `true` when Apple's `email_verified` claim is `true` or
+ * the string `"true"`; private-relay addresses
+ * (`@privaterelay.appleid.com`) are returned as-is. The raw `id_token`
+ * claims — including
  * `is_private_email` — stay on {@link ExternalProfile.raw}.
  *
  * @example

package/esm/identity/external/discord.d.ts

@@ -12,7 +12,11 @@ export interface DiscordProviderOptions {
     clientSecret: string;
     /** Scopes requested by default. Defaults to `["identify", "email"]`. */
     scopes?: string[];
-    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    /**
+     * Fetch implementation for all provider traffic. Defaults to
+     * `globalThis.fetch`. A wrapper must pass `init` through intact: its
+     * `redirect` and `signal` carry the connector's redirect refusal and timeout.
+     */
     fetch?: typeof fetch;
 }
 /**

package/esm/identity/external/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * The error contract for external-provider (social login) flows.
  *
- * Every failure in the external connector layer is thrown as an
+ * Failures the external connectors detect are thrown as an
  * {@link ExternalAuthError} whose message names the provider, what failed, and
  * the likely fix — misconfiguration is meant to be diagnosable from the
  * message alone. The {@link ExternalAuthErrorCode} tells app code how to
@@ -44,5 +44,9 @@ export declare class ExternalAuthError extends Error {
     /** Builds the error; `message` is prefixed with `[provider]` automatically. */
     constructor(provider: string, code: ExternalAuthErrorCode, message: string, options?: ErrorOptions);
 }
-/** Type guard for {@link ExternalAuthError}. */
+/**
+ * Type guard for {@link ExternalAuthError}. Uses `instanceof`, so an error from
+ * another realm or a second copy of the package fails it — check
+ * `name === "ExternalAuthError"` there.
+ */
 export declare function isExternalAuthError(value: unknown): value is ExternalAuthError;

package/esm/identity/external/errors.js

@@ -1,7 +1,7 @@
 /**
  * The error contract for external-provider (social login) flows.
  *
- * Every failure in the external connector layer is thrown as an
+ * Failures the external connectors detect are thrown as an
  * {@link ExternalAuthError} whose message names the provider, what failed, and
  * the likely fix — misconfiguration is meant to be diagnosable from the
  * message alone. The {@link ExternalAuthErrorCode} tells app code how to
@@ -30,7 +30,11 @@ export class ExternalAuthError extends Error {
         this.code = code;
     }
 }
-/** Type guard for {@link ExternalAuthError}. */
+/**
+ * Type guard for {@link ExternalAuthError}. Uses `instanceof`, so an error from
+ * another realm or a second copy of the package fails it — check
+ * `name === "ExternalAuthError"` there.
+ */
 export function isExternalAuthError(value) {
     return value instanceof ExternalAuthError;
 }

package/esm/identity/external/flow.d.ts

@@ -36,7 +36,9 @@ export interface ExternalAuthStartResult {
     url: string;
     /**
      * Per-attempt state to persist in a cookie/session and hand back to
-     * {@link ExternalAuthFlow.finish}. JSON-serializable; contains no tokens.
+     * {@link ExternalAuthFlow.finish}. JSON-serializable and contains no tokens,
+     * but the PKCE verifier and nonce are secrets — keep it sealed or
+     * server-side.
      */
     transient: ExternalAuthTransient;
 }
@@ -94,11 +96,12 @@ export declare class ExternalAuthFlow {
      */
     start(input: ExternalAuthStartInput): Promise<ExternalAuthStartResult>;
     /**
-     * Completes a sign-in attempt from the provider callback: enforces the max
-     * transient age, surfaces provider `error` callback params, verifies
-     * `state` with a timing-safe compare, exchanges the code, and (for OIDC
-     * providers) validates the id_token nonce — then returns the normalized
-     * profile.
+     * Completes a sign-in attempt from the provider callback: checks the
+     * transient belongs to this flow's provider, enforces the max transient
+     * age, verifies `state` with a timing-safe compare, and only then surfaces a
+     * provider `error` callback param; finally the provider exchanges the code
+     * and (for nonce-using providers) validates the id_token nonce, and the
+     * normalized profile is returned.
      *
      * @throws {ExternalAuthError} with a code describing the failure — see
      *   {@link ExternalAuthErrorCode} for how app code should respond to each.

package/esm/identity/external/flow.js

@@ -88,11 +88,12 @@ export class ExternalAuthFlow {
         };
     }
     /**
-     * Completes a sign-in attempt from the provider callback: enforces the max
-     * transient age, surfaces provider `error` callback params, verifies
-     * `state` with a timing-safe compare, exchanges the code, and (for OIDC
-     * providers) validates the id_token nonce — then returns the normalized
-     * profile.
+     * Completes a sign-in attempt from the provider callback: checks the
+     * transient belongs to this flow's provider, enforces the max transient
+     * age, verifies `state` with a timing-safe compare, and only then surfaces a
+     * provider `error` callback param; finally the provider exchanges the code
+     * and (for nonce-using providers) validates the id_token nonce, and the
+     * normalized profile is returned.
      *
      * @throws {ExternalAuthError} with a code describing the failure — see
      *   {@link ExternalAuthErrorCode} for how app code should respond to each.

package/esm/identity/external/github.d.ts

@@ -13,14 +13,18 @@ export interface GithubProviderOptions {
     clientSecret: string;
     /** Scopes requested by default. Defaults to `["read:user", "user:email"]`. */
     scopes?: string[];
-    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    /**
+     * Fetch implementation for all provider traffic. Defaults to
+     * `globalThis.fetch`. A wrapper must pass `init` through intact: its
+     * `redirect` and `signal` carry the connector's redirect refusal and timeout.
+     */
     fetch?: typeof fetch;
 }
 /**
  * Creates a GitHub connector with id `"github"`.
  *
- * GitHub speaks plain OAuth2 (no discovery, no id_token, no PKCE for OAuth
- * Apps), so the connector uses GitHub's fixed endpoints and builds the
+ * GitHub speaks plain OAuth2 (no discovery, no id_token), so the connector
+ * uses GitHub's fixed endpoints, sends no PKCE challenge, and builds the
  * profile from `GET /user` plus `GET /user/emails`: the primary email is used
  * (falling back to the first verified, then the first listed), and
  * `emailVerified` reflects GitHub's flag for whichever email was chosen. When

package/esm/identity/external/github.js

@@ -14,8 +14,8 @@ const GITHUB_EMAILS_URL = "https://api.github.com/user/emails";
 /**
  * Creates a GitHub connector with id `"github"`.
  *
- * GitHub speaks plain OAuth2 (no discovery, no id_token, no PKCE for OAuth
- * Apps), so the connector uses GitHub's fixed endpoints and builds the
+ * GitHub speaks plain OAuth2 (no discovery, no id_token), so the connector
+ * uses GitHub's fixed endpoints, sends no PKCE challenge, and builds the
  * profile from `GET /user` plus `GET /user/emails`: the primary email is used
  * (falling back to the first verified, then the first listed), and
  * `emailVerified` reflects GitHub's flag for whichever email was chosen. When

package/esm/identity/external/google.d.ts

@@ -21,7 +21,11 @@ export interface GoogleProviderOptions {
      * `aud` is this one. See {@link AzpPolicy}.
      */
     azp?: AzpPolicy;
-    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    /**
+     * Fetch implementation for all provider traffic. Defaults to
+     * `globalThis.fetch`. A wrapper must pass `init` through intact: its
+     * `redirect` and `signal` carry the connector's redirect refusal and timeout.
+     */
     fetch?: typeof fetch;
     /**
      * Cache Google's discovery document is read from and written to, shared with

package/esm/identity/external/oauth2.d.ts

@@ -76,9 +76,20 @@ export interface OAuth2ProviderOptions {
     scopeSeparator?: string;
     /** Whether to run PKCE (S256). Defaults to `false`. */
     usesPkce?: boolean;
-    /** Extra fixed query params to add to the authorize URL. */
+    /**
+     * Extra fixed query params to add to the authorize URL (an `audience`, a
+     * tenant hint). The protocol params always win: `response_type`,
+     * `client_id`, `redirect_uri`, `scope`, `state`, the PKCE `code_challenge`
+     * pair, and a `prompt` the flow passes are written after these, so a
+     * same-named key here cannot replace the connector's CSRF `state` or
+     * downgrade PKCE.
+     */
     authorizationParams?: Record<string, string>;
-    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    /**
+     * Fetch implementation for all provider traffic. Defaults to
+     * `globalThis.fetch`. A wrapper must pass `init` through intact: its
+     * `redirect` and `signal` carry the connector's redirect refusal and timeout.
+     */
     fetch?: typeof fetch;
 }
 /**

package/esm/identity/external/oauth2.js

@@ -100,14 +100,14 @@ export function oauth2Provider(options) {
         usesNonce: false,
         async buildAuthorizationUrl(input) {
             const url = new URL(options.authorizationEndpoint);
+            for (const [key, value] of Object.entries(options.authorizationParams ?? {})) {
+                url.searchParams.set(key, value);
+            }
             url.searchParams.set("response_type", "code");
             url.searchParams.set("client_id", options.clientId);
             url.searchParams.set("redirect_uri", input.redirectUri);
             url.searchParams.set("scope", input.scopes.join(scopeSeparator));
             url.searchParams.set("state", input.state);
-            for (const [key, value] of Object.entries(options.authorizationParams ?? {})) {
-                url.searchParams.set(key, value);
-            }
             if (input.codeVerifier) {
                 url.searchParams.set("code_challenge", await generateCodeChallenge(input.codeVerifier));
                 url.searchParams.set("code_challenge_method", "S256");

package/esm/identity/external/oidc.d.ts

@@ -14,9 +14,11 @@ export interface OidcProviderOptions {
     /** Human-readable name for buttons and logs. Defaults to `"OpenID Connect"`. */
     displayName?: string;
     /**
-     * The provider's issuer URL. Endpoints are resolved from
-     * `${issuer}/.well-known/openid-configuration` (with an RFC 8414 fallback)
-     * on first use and cached.
+     * The provider's issuer URL. Endpoints are resolved on first use from
+     * `${issuer}/.well-known/oauth-authorization-server` (RFC 8414), falling
+     * back to `${issuer}/.well-known/openid-configuration`, and cached. Must be
+     * `https` (plain `http` only for `localhost`, `127.0.0.1`, or `[::1]`), as
+     * must every endpoint the discovery document advertises.
      */
     issuer: string;
     /** The client id registered with the provider. */
@@ -36,7 +38,11 @@ export interface OidcProviderOptions {
      * see {@link AzpPolicy}.
      */
     azp?: AzpPolicy;
-    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    /**
+     * Fetch implementation for all provider traffic. Defaults to
+     * `globalThis.fetch`. A wrapper must pass `init` through intact: its
+     * `redirect` and `signal` carry the connector's redirect refusal and timeout.
+     */
     fetch?: typeof fetch;
     /**
      * Cache the discovery document is read from and written to, shared with any
@@ -53,18 +59,23 @@ export interface OidcProviderOptions {
  * The exchange reuses the package's `DirectClient` (discovery caching with
  * both well-known paths, Basic client auth, RFC 6749 error mapping) with PKCE
  * always on. The profile is built from the id_token claims, merged with the
- * UserInfo response when the provider advertises a `userinfo_endpoint` (the
- * UserInfo `sub` must match the id_token `sub` per OIDC Core §5.3.2, and a
- * UserInfo failure is non-fatal — the id_token claims already suffice).
+ * UserInfo response when the provider advertises a `userinfo_endpoint`;
+ * UserInfo values override id_token claims of the same name (including
+ * `email_verified`). A UserInfo response whose `sub` differs from the
+ * id_token `sub` (OIDC Core §5.3.2) is discarded, and a UserInfo failure is
+ * non-fatal — the profile then comes from the id_token claims alone.
  *
  * **id_token validation:** the `iss`, `aud`, `azp` (when the token has multiple
  * audiences or an `azp` claim, unless `azp: "ignore"` is configured), `exp`,
  * and `nonce` claims are checked per OpenID Connect Core §3.1.3.7. The
  * signature is deliberately **not** verified: the token arrives directly from
  * the token endpoint over TLS, where §3.1.3.7 permits relying on TLS server
- * validation instead of signature checks (rule 6). Every other rule —
- * including expiry (rule 9) — still applies. Do not feed this connector
- * id_tokens obtained out-of-band.
+ * validation instead of signature checks (rule 6). Only the claim checks
+ * listed above are made — not `iat`, `acr`, or `auth_time`. Do not feed this
+ * connector id_tokens obtained out-of-band.
+ *
+ * @throws {ExternalAuthError} `configuration` when `issuer` is not an absolute
+ *   `https` URL (see {@link OidcProviderOptions.issuer}).
  *
  * @example
  * ```ts

package/esm/identity/external/oidc.js

@@ -16,18 +16,23 @@ import { ExternalAuthError } from "./errors.js";
  * The exchange reuses the package's `DirectClient` (discovery caching with
  * both well-known paths, Basic client auth, RFC 6749 error mapping) with PKCE
  * always on. The profile is built from the id_token claims, merged with the
- * UserInfo response when the provider advertises a `userinfo_endpoint` (the
- * UserInfo `sub` must match the id_token `sub` per OIDC Core §5.3.2, and a
- * UserInfo failure is non-fatal — the id_token claims already suffice).
+ * UserInfo response when the provider advertises a `userinfo_endpoint`;
+ * UserInfo values override id_token claims of the same name (including
+ * `email_verified`). A UserInfo response whose `sub` differs from the
+ * id_token `sub` (OIDC Core §5.3.2) is discarded, and a UserInfo failure is
+ * non-fatal — the profile then comes from the id_token claims alone.
  *
  * **id_token validation:** the `iss`, `aud`, `azp` (when the token has multiple
  * audiences or an `azp` claim, unless `azp: "ignore"` is configured), `exp`,
  * and `nonce` claims are checked per OpenID Connect Core §3.1.3.7. The
  * signature is deliberately **not** verified: the token arrives directly from
  * the token endpoint over TLS, where §3.1.3.7 permits relying on TLS server
- * validation instead of signature checks (rule 6). Every other rule —
- * including expiry (rule 9) — still applies. Do not feed this connector
- * id_tokens obtained out-of-band.
+ * validation instead of signature checks (rule 6). Only the claim checks
+ * listed above are made — not `iat`, `acr`, or `auth_time`. Do not feed this
+ * connector id_tokens obtained out-of-band.
+ *
+ * @throws {ExternalAuthError} `configuration` when `issuer` is not an absolute
+ *   `https` URL (see {@link OidcProviderOptions.issuer}).
  *
  * @example
  * ```ts

package/esm/identity/external/provider.d.ts

@@ -27,7 +27,8 @@ export interface ExternalProfile {
     email?: string;
     /**
      * `true` only when the provider positively asserted the email is verified
-     * (OIDC `email_verified: true`, GitHub verified primary email). Defaults to
+     * (OIDC `email_verified: true`, GitHub's `verified` flag on the email the
+     * connector chose). Defaults to
      * `false` — treat unverified emails as attacker-controllable input and do
      * not auto-link accounts on them.
      */
@@ -100,7 +101,8 @@ export interface ExternalProfileInput {
  * verification, transient expiry, callback error surfacing); the provider
  * owns the wire protocol (authorize URL shape, code exchange, id_token nonce
  * validation, profile normalization). Implement this only for providers the
- * built-in {@link oidcProvider} / {@link githubProvider} cannot cover.
+ * built-in connectors, including the generic {@link oidcProvider} and
+ * {@link oauth2Provider}, cannot cover.
  */
 export interface ExternalProvider {
     /** Stable id used in {@link ExternalProfile.provider} and error messages. */

package/esm/identity/identifier.d.ts

@@ -13,8 +13,8 @@ export type IdentifierKind = "email" | "username" | "phone";
  * Classify a sign-in identifier as an email, phone number, or username.
  *
  * Heuristic: an `@` → `email`; otherwise a value made only of phone characters
- * (`+`, digits, spaces, `-`, `()`, `.`) with at least 7 digits → `phone`;
- * everything else → `username`. The value is trimmed first.
+ * (an optional leading `+`, then digits, spaces, `-`, `()`, `.`) with at least
+ * 7 digits → `phone`; everything else → `username`. The value is trimmed first.
  */
 export declare function classifyIdentifier(identifier: string): IdentifierKind;
 /** Per-kind user lookups supplied by the app. Omit a kind to disallow it. */
@@ -28,9 +28,10 @@ export interface IdentifierLookups<User> {
 }
 /**
  * Build a resolver that classifies an identifier ({@link classifyIdentifier})
- * and dispatches to the matching app-supplied lookup. Returns `undefined` when
- * no lookup is configured for the classified kind, or the user isn't found —
- * callers should treat both as "invalid credentials" without revealing which.
+ * and dispatches the trimmed value to the matching app-supplied lookup. Returns
+ * `undefined` when no lookup is configured for the classified kind, or the
+ * user isn't found — callers should treat both as "invalid credentials"
+ * without revealing which.
  *
  * @example
  * ```ts

package/esm/identity/identifier.js

@@ -11,8 +11,8 @@
  * Classify a sign-in identifier as an email, phone number, or username.
  *
  * Heuristic: an `@` → `email`; otherwise a value made only of phone characters
- * (`+`, digits, spaces, `-`, `()`, `.`) with at least 7 digits → `phone`;
- * everything else → `username`. The value is trimmed first.
+ * (an optional leading `+`, then digits, spaces, `-`, `()`, `.`) with at least
+ * 7 digits → `phone`; everything else → `username`. The value is trimmed first.
  */
 export function classifyIdentifier(identifier) {
     const value = identifier.trim();
@@ -25,9 +25,10 @@ export function classifyIdentifier(identifier) {
 }
 /**
  * Build a resolver that classifies an identifier ({@link classifyIdentifier})
- * and dispatches to the matching app-supplied lookup. Returns `undefined` when
- * no lookup is configured for the classified kind, or the user isn't found —
- * callers should treat both as "invalid credentials" without revealing which.
+ * and dispatches the trimmed value to the matching app-supplied lookup. Returns
+ * `undefined` when no lookup is configured for the classified kind, or the
+ * user isn't found — callers should treat both as "invalid credentials"
+ * without revealing which.
  *
  * @example
  * ```ts

package/esm/identity/lockout.d.ts

@@ -9,7 +9,7 @@
  * database to share state across instances — e.g. columns on your users table,
  * which also gives admins visibility).
  *
- * `AccountLockout` is a pure state machine: it never decides whether to block.
+ * `AccountLockout` only records state: it never decides whether to block.
  * `IdentityService` consults it and applies its `protectionMode`
  * (enforce vs log-only), so adopters can observe lockout behavior before
  * turning it on.
@@ -124,8 +124,9 @@ export interface AccountLockoutLike {
 /**
  * Consecutive-failure lockout with safe defaults (10 failures → 15-minute
  * lock) — the default {@link AccountLockoutLike}. Wire into
- * {@link IdentityService} via its `lockout` option; call {@link reset} from
- * your unlock flow.
+ * {@link IdentityService} via its `lockout` option, which resets it on a
+ * successful sign-in, password reset, or {@link IdentityService.unlockAccount};
+ * call {@link reset} yourself only from an unlock flow of your own.
  */
 export declare class AccountLockout implements AccountLockoutLike {
     #private;

package/esm/identity/lockout.js

@@ -9,7 +9,7 @@
  * database to share state across instances — e.g. columns on your users table,
  * which also gives admins visibility).
  *
- * `AccountLockout` is a pure state machine: it never decides whether to block.
+ * `AccountLockout` only records state: it never decides whether to block.
  * `IdentityService` consults it and applies its `protectionMode`
  * (enforce vs log-only), so adopters can observe lockout behavior before
  * turning it on.
@@ -21,8 +21,9 @@ const DEFAULT_LOCK_DURATION_MS = 15 * 60 * 1000;
 /**
  * Consecutive-failure lockout with safe defaults (10 failures → 15-minute
  * lock) — the default {@link AccountLockoutLike}. Wire into
- * {@link IdentityService} via its `lockout` option; call {@link reset} from
- * your unlock flow.
+ * {@link IdentityService} via its `lockout` option, which resets it on a
+ * successful sign-in, password reset, or {@link IdentityService.unlockAccount};
+ * call {@link reset} yourself only from an unlock flow of your own.
  */
 export class AccountLockout {
     #maxAttempts;

package/esm/identity/mfa/mod.d.ts

@@ -12,7 +12,8 @@
  *   {@link verifyRecoveryCode} — readable single-use fallback codes, hashed at
  *   rest.
  * - {@link MfaService} over an app-implemented {@link MfaStore} — enrollment
- *   (pending → confirmed), verification with atomic replay and burn handling,
+ *   (pending → confirmed), verification with replay rejection and
+ *   recovery-code burning through the store's atomic methods,
  *   regeneration, disable, plus the layer's usual seams (`rateLimiter`,
  *   `onEvent` for `mfa.*` audit events). {@link MemoryMfaStore} ships for
  *   dev/tests.

package/esm/identity/mfa/mod.js

@@ -12,7 +12,8 @@
  *   {@link verifyRecoveryCode} — readable single-use fallback codes, hashed at
  *   rest.
  * - {@link MfaService} over an app-implemented {@link MfaStore} — enrollment
- *   (pending → confirmed), verification with atomic replay and burn handling,
+ *   (pending → confirmed), verification with replay rejection and
+ *   recovery-code burning through the store's atomic methods,
  *   regeneration, disable, plus the layer's usual seams (`rateLimiter`,
  *   `onEvent` for `mfa.*` audit events). {@link MemoryMfaStore} ships for
  *   dev/tests.

package/esm/identity/mfa/recovery-codes.d.ts

@@ -83,7 +83,8 @@ export type RecoveryCodeVerification = {
      * The index of the matching hash. Burn it with an atomic delete-by-value
      * (a conditional `DELETE` on the hash, never read-filter-write) so the
      * code cannot be redeemed again — the library does not do this for you at
-     * this level ({@link MfaService} does, atomically).
+     * this level ({@link MfaService} does, through its store's
+     * `consumeRecoveryHash`).
      */
     index: number;
 };