@udibo/oauth2 0.4.1 → 0.5.1

package/esm/client/mod.d.ts

@@ -15,9 +15,11 @@
  * care — the React adapter's `<OAuth2Provider>`, a shared UI helper — should
  * accept.
  *
- * Storage interfaces (token / refresh-token / auth-request) default to
- * in-memory implementations suitable for servers and tests; browser
- * applications should substitute the appropriate persistent variants.
+ * A {@link DirectClient} keeps its token bundle and refresh token in memory
+ * by default, so they are lost on reload; a browser app that must survive one
+ * passes {@link IndexedDBRefreshTokenStorage}. The pending auth request
+ * defaults to {@link SessionStorageAuthRequestStorage} in a browser document
+ * and to memory everywhere else.
  *
  * @module
  */
@@ -27,7 +29,7 @@ export { BffClient, type BffClientOptions, type BffEndpoints, } from "./bff-clie
 export { type AuthorizationCallbackResult, type AuthorizationRedirect, type AuthorizationServerEndpoints, type DeviceAuthorizationOptions, DirectClient, type DirectClientOptions, type ExchangeOptions, type ExchangeResult, type IntrospectionResult, type LoginOptions, type PollDeviceTokenOptions, } from "./direct-client.js";
 export { DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES, DEFAULT_DISCOVERY_TTL_MS, type DiscoveryCache, type DiscoveryCacheEntry, MemoryDiscoveryCache, type MemoryDiscoveryCacheOptions, } from "./discovery-cache.js";
 export { type AuthenticatedEvent, type ErrorEvent, type LoggedOutEvent, type OAuth2ClientEvent, type OAuth2ClientEventListener, type TokenRefreshedEvent, } from "./events.js";
-export { type AuthRequestRecord, type AuthRequestStorage, MemoryAuthRequestStorage, MemoryRefreshTokenStorage, MemoryTokenStorage, type RefreshTokenStorage, type TokenBundle, type TokenStorage, } from "./storage.js";
+export { type AuthRequestRecord, type AuthRequestStorage, MemoryAuthRequestStorage, type MemoryAuthRequestStorageOptions, MemoryRefreshTokenStorage, MemoryTokenStorage, type RefreshTokenStorage, type TokenBundle, type TokenStorage, } from "./storage.js";
 export { checkPermissions, type CheckPermissionsOptions, type CheckPermissionsResult, type CheckResource, } from "./check.js";
 export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
 export type { OrganizationContext } from "../models/authorization.js";

package/esm/client/mod.js

@@ -15,9 +15,11 @@
  * care — the React adapter's `<OAuth2Provider>`, a shared UI helper — should
  * accept.
  *
- * Storage interfaces (token / refresh-token / auth-request) default to
- * in-memory implementations suitable for servers and tests; browser
- * applications should substitute the appropriate persistent variants.
+ * A {@link DirectClient} keeps its token bundle and refresh token in memory
+ * by default, so they are lost on reload; a browser app that must survive one
+ * passes {@link IndexedDBRefreshTokenStorage}. The pending auth request
+ * defaults to {@link SessionStorageAuthRequestStorage} in a browser document
+ * and to memory everywhere else.
  *
  * @module
  */

package/esm/client/storage.d.ts

@@ -3,19 +3,18 @@
  * tokens, so none of this applies to it.
  *
  * The client keeps three pieces of mutable state across calls:
- * - the current token bundle (access + refresh + expiry + id token),
- * - the refresh token specifically (may be split into a harder-to-exfiltrate
- *   store than the access token — e.g. IndexedDB or a Web Worker),
+ * - the current token bundle (access token, expiry, scope, id token),
+ * - the refresh token, in its own store so it can persist somewhere the
+ *   access token does not,
  * - a short-lived auth-request map (`state` → `{ codeVerifier, returnTo, … }`)
  *   used to correlate an authorize redirect with its callback.
  *
- * The defaults here are all in-memory and live only for the process / tab
- * lifetime. Browser applications that need persistence across reloads should
- * plug in the appropriate implementation — most commonly:
- * - `MemoryTokenStorage` for access tokens (always),
- * - an `IndexedDB`-backed `RefreshTokenStorage` for refresh tokens (so they
- *   are not readable via `document.cookie` or `localStorage`),
- * - `sessionStorage`-backed `AuthRequestStorage` for the redirect state map.
+ * The implementations here are in-memory and live only for the process / tab
+ * lifetime. `DirectClient` uses them by default, except that in a browser
+ * document its auth-request storage defaults to `sessionStorage`. A browser
+ * app that must stay signed in across reloads passes
+ * `IndexedDBRefreshTokenStorage` for the refresh token and keeps the access
+ * token in memory.
  *
  * @module
  */
@@ -42,10 +41,9 @@ export interface TokenStorage {
     clear(): Promise<void> | void;
 }
 /**
- * Persists the refresh token independently from the access token. Kept
- * separate so applications can harden refresh-token storage (IndexedDB,
- * Web Worker, or a server-side session cookie) without changing where
- * short-lived access tokens live.
+ * Persists the refresh token independently from the access token, so it can
+ * outlive a reload (IndexedDB, a Web Worker, a server-side session) while the
+ * short-lived access token stays wherever {@link TokenStorage} keeps it.
  */
 export interface RefreshTokenStorage {
     /** Returns the stored refresh token, or `null` when none has been persisted. */
@@ -74,15 +72,29 @@ export interface AuthRequestRecord {
  */
 export interface AuthRequestStorage {
     /**
-     * Returns the record for {@linkcode state}, or `null` if absent or expired.
-     * Implementations may prune the entry when returning `null` for an expired one.
+     * Returns the record for {@linkcode state}, or `null` if absent. An
+     * implementation may also return `null` for, and prune, a record it deems
+     * expired; `DirectClient` separately rejects one older than its
+     * `authRequestTtlMs`.
      */
     get(state: string): Promise<AuthRequestRecord | null> | AuthRequestRecord | null;
     /** Stores {@linkcode value} under {@linkcode state} before the authorize redirect. */
     set(state: string, value: AuthRequestRecord): Promise<void> | void;
-    /** Removes one entry (called after successful callback consumption). */
+    /**
+     * Returns the record for {@linkcode state} and removes it in one atomic
+     * step, or `null` if absent. `DirectClient` claims the record this way
+     * before it calls the token endpoint, so of two callbacks racing on one
+     * `state` only one reaches it. Optional for compatibility: without it the
+     * client falls back to `get` then `delete`, which still consumes the record
+     * before the token call but lets concurrent callers that both read it
+     * before either deletes it redeem it twice. Implement it with the backing
+     * store's own atomic primitive (`GETDEL`, `DELETE … RETURNING`) whenever
+     * the store is shared between processes or requests.
+     */
+    take?(state: string): Promise<AuthRequestRecord | null> | AuthRequestRecord | null;
+    /** Removes one entry — a claimed or stale one. */
     delete(state: string): Promise<void> | void;
-    /** Removes every entry. Called on logout. */
+    /** Removes every entry. Called when the client clears its session. */
     clear(): Promise<void> | void;
 }
 /** Default in-memory {@link TokenStorage}. Data is lost when the process exits. */
@@ -108,17 +120,35 @@ export declare class MemoryRefreshTokenStorage implements RefreshTokenStorage {
     /** Discards the in-memory refresh token. */
     clear(): void;
 }
+/** Options for {@link MemoryAuthRequestStorage}. */
+export interface MemoryAuthRequestStorageOptions {
+    /**
+     * Age past which a record is pruned the next time any record is written,
+     * in ms. Defaults to 10 minutes; `Infinity` never prunes.
+     */
+    ttlMs?: number;
+}
 /**
- * Default in-memory {@link AuthRequestStorage}. Data is lost when the
- * process exits — fine for server-side / CLI usage. Browser apps should
- * plug in a `sessionStorage`-backed implementation so the record survives
- * the authorize-redirect round-trip.
+ * In-memory {@link AuthRequestStorage}, `DirectClient`'s default outside a
+ * browser document. Data is lost when the process exits. Every write prunes
+ * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, so logins
+ * that never return to the callback do not accumulate in a long-running
+ * server.
  */
 export declare class MemoryAuthRequestStorage implements AuthRequestStorage {
     #private;
+    /** Configures the pruning TTL, 10 minutes by default. */
+    constructor(options?: MemoryAuthRequestStorageOptions);
     /** Returns the record for {@linkcode state}, or `null` if none is stored. */
     get(state: string): AuthRequestRecord | null;
-    /** Stores {@linkcode value} under {@linkcode state}. */
+    /** Returns and removes the record for {@linkcode state} in one step. */
+    take(state: string): AuthRequestRecord | null;
+    /**
+     * Stores {@linkcode value} under {@linkcode state}, first pruning records
+     * past the TTL. Pruning walks records oldest-write-first and stops at the
+     * first one inside the TTL, so it assumes each `createdAt` is the time of
+     * its write, as `DirectClient.login` sets it.
+     */
     set(state: string, value: AuthRequestRecord): void;
     /** Removes the record for {@linkcode state}. */
     delete(state: string): void;

package/esm/client/storage.js

@@ -3,19 +3,18 @@
  * tokens, so none of this applies to it.
  *
  * The client keeps three pieces of mutable state across calls:
- * - the current token bundle (access + refresh + expiry + id token),
- * - the refresh token specifically (may be split into a harder-to-exfiltrate
- *   store than the access token — e.g. IndexedDB or a Web Worker),
+ * - the current token bundle (access token, expiry, scope, id token),
+ * - the refresh token, in its own store so it can persist somewhere the
+ *   access token does not,
  * - a short-lived auth-request map (`state` → `{ codeVerifier, returnTo, … }`)
  *   used to correlate an authorize redirect with its callback.
  *
- * The defaults here are all in-memory and live only for the process / tab
- * lifetime. Browser applications that need persistence across reloads should
- * plug in the appropriate implementation — most commonly:
- * - `MemoryTokenStorage` for access tokens (always),
- * - an `IndexedDB`-backed `RefreshTokenStorage` for refresh tokens (so they
- *   are not readable via `document.cookie` or `localStorage`),
- * - `sessionStorage`-backed `AuthRequestStorage` for the redirect state map.
+ * The implementations here are in-memory and live only for the process / tab
+ * lifetime. `DirectClient` uses them by default, except that in a browser
+ * document its auth-request storage defaults to `sessionStorage`. A browser
+ * app that must stay signed in across reloads passes
+ * `IndexedDBRefreshTokenStorage` for the refresh token and keeps the access
+ * token in memory.
  *
  * @module
  */
@@ -55,19 +54,38 @@ export class MemoryRefreshTokenStorage {
     }
 }
 /**
- * Default in-memory {@link AuthRequestStorage}. Data is lost when the
- * process exits — fine for server-side / CLI usage. Browser apps should
- * plug in a `sessionStorage`-backed implementation so the record survives
- * the authorize-redirect round-trip.
+ * In-memory {@link AuthRequestStorage}, `DirectClient`'s default outside a
+ * browser document. Data is lost when the process exits. Every write prunes
+ * records older than {@link MemoryAuthRequestStorageOptions.ttlMs}, so logins
+ * that never return to the callback do not accumulate in a long-running
+ * server.
  */
 export class MemoryAuthRequestStorage {
     #records = new Map();
+    #ttlMs;
+    /** Configures the pruning TTL, 10 minutes by default. */
+    constructor(options = {}) {
+        this.#ttlMs = options.ttlMs ?? 10 * 60 * 1000;
+    }
     /** Returns the record for {@linkcode state}, or `null` if none is stored. */
     get(state) {
         return this.#records.get(state) ?? null;
     }
-    /** Stores {@linkcode value} under {@linkcode state}. */
+    /** Returns and removes the record for {@linkcode state} in one step. */
+    take(state) {
+        const record = this.#records.get(state) ?? null;
+        this.#records.delete(state);
+        return record;
+    }
+    /**
+     * Stores {@linkcode value} under {@linkcode state}, first pruning records
+     * past the TTL. Pruning walks records oldest-write-first and stops at the
+     * first one inside the TTL, so it assumes each `createdAt` is the time of
+     * its write, as `DirectClient.login` sets it.
+     */
     set(state, value) {
+        this.#pruneExpired();
+        this.#records.delete(state);
         this.#records.set(state, value);
     }
     /** Removes the record for {@linkcode state}. */
@@ -78,4 +96,14 @@ export class MemoryAuthRequestStorage {
     clear() {
         this.#records.clear();
     }
+    #pruneExpired() {
+        if (this.#ttlMs === Infinity)
+            return;
+        const cutoff = Date.now() - this.#ttlMs;
+        for (const [state, record] of this.#records) {
+            if (record.createdAt >= cutoff)
+                return;
+            this.#records.delete(state);
+        }
+    }
 }

package/esm/errors.d.ts

@@ -28,10 +28,9 @@ export interface OAuth2ProblemDetailsExtensions {
     error_uri?: string;
 }
 /**
- * Constructor type for OAuth2 error classes produced by
- * `createHttpErrorClass`. Declared explicitly so the exported error classes
- * have a JSR-fast public type (the inferred type spans multiple constructor
- * overloads and trips the `no-slow-types` rule).
+ * Constructor type shared by every OAuth2 error class in this module: each
+ * takes an optional status, message, and `HttpErrorOptions` (whose
+ * `extensions` carry the OAuth2 fields) and builds an {@linkcode OAuth2Error}.
  */
 export type OAuth2ErrorClass<Extensions extends OAuth2ProblemDetailsExtensions = OAuth2ProblemDetailsExtensions> = {
     new <E extends Extensions = Extensions>(status?: number, message?: string, options?: HttpErrorOptions<E>): HttpError<E>;
@@ -53,19 +52,23 @@ export type OAuth2Error = HttpError<OAuth2ProblemDetailsExtensions>;
  * (e.g. {@linkcode InvalidRequestError}) when the condition is known.
  */
 export declare const OAuth2Error: OAuth2ErrorClass;
-/** Type guard for OAuth2 errors. */
+/**
+ * Type guard for OAuth2 errors: true for any `HttpError` whose
+ * `extensions.error` is set, whichever class constructed it.
+ */
 export declare function isOAuth2Error(value: unknown): value is OAuth2Error;
 /**
  * Converts an arbitrary error into an {@link OAuth2Error}.
  *
- * If the input is already an OAuth2Error it is returned as-is; otherwise it is
- * wrapped in a {@link ServerError} with the original error attached as `cause`.
+ * An input that is already an OAuth2Error is returned as the same object;
+ * anything else is wrapped in a {@link ServerError} with the original error
+ * attached as `cause`.
  *
- * The returned error also has its `type` and `extensions.error_uri` synced so
- * that if one is set the other is too. This lets both the standard OAuth2
- * error format (which emits `error_uri`) and the RFC 9457 Problem Details
- * format (which emits `type`) carry the same URI without the handler having to
- * set both fields.
+ * Either way, `type` and `extensions.error_uri` are synced so that if one is
+ * set the other is too — **mutating an OAuth2Error input in place**. This lets
+ * both the standard OAuth2 error format (which emits `error_uri`) and the
+ * RFC 9457 Problem Details format (which emits `type`) carry the same URI
+ * without the handler having to set both fields.
  */
 export declare function toOAuth2Error(error: unknown): OAuth2Error;
 /**

package/esm/errors.js

@@ -24,21 +24,25 @@ export const OAuth2Error = createHttpErrorClass({
         error: "server_error",
     },
 });
-/** Type guard for OAuth2 errors. */
+/**
+ * Type guard for OAuth2 errors: true for any `HttpError` whose
+ * `extensions.error` is set, whichever class constructed it.
+ */
 export function isOAuth2Error(value) {
     return value instanceof HttpError && value.extensions.error !== undefined;
 }
 /**
  * Converts an arbitrary error into an {@link OAuth2Error}.
  *
- * If the input is already an OAuth2Error it is returned as-is; otherwise it is
- * wrapped in a {@link ServerError} with the original error attached as `cause`.
+ * An input that is already an OAuth2Error is returned as the same object;
+ * anything else is wrapped in a {@link ServerError} with the original error
+ * attached as `cause`.
  *
- * The returned error also has its `type` and `extensions.error_uri` synced so
- * that if one is set the other is too. This lets both the standard OAuth2
- * error format (which emits `error_uri`) and the RFC 9457 Problem Details
- * format (which emits `type`) carry the same URI without the handler having to
- * set both fields.
+ * Either way, `type` and `extensions.error_uri` are synced so that if one is
+ * set the other is too — **mutating an OAuth2Error input in place**. This lets
+ * both the standard OAuth2 error format (which emits `error_uri`) and the
+ * RFC 9457 Problem Details format (which emits `type`) carry the same URI
+ * without the handler having to set both fields.
  */
 export function toOAuth2Error(error) {
     const oauth2Error = isOAuth2Error(error)

package/esm/identity/delivery.d.ts

@@ -5,8 +5,7 @@
  * The library owns the **token lifecycle** ({@link TokenFlowService}); your app
  * owns **transport** — SMTP, SES, Resend, Twilio, etc. So delivery is a set of
  * app-supplied async hooks, and the package ships URL builders so apps stop
- * hand-assembling `${protocol}://${host}/verify-email?token=…` strings. This is
- * the Better Auth model (`sendVerificationEmail` / `sendResetPassword`).
+ * hand-assembling `${protocol}://${host}/verify-email?token=…` strings.
  *
  * @module
  */
@@ -15,9 +14,10 @@ export interface DeliveryMessage {
     /** Recipient — an email address or phone number. */
     to: string;
     /**
-     * The ready-to-use action link (already carrying the token), when the caller
-     * built one via {@link buildVerificationUrl} / {@link buildResetUrl}. Absent
-     * if you'd rather build the message body from `token` yourself.
+     * The ready-to-use action link (already carrying the token).
+     * `IdentityService` sets it only when configured with a `baseUrl`, building
+     * it with the matching `build*Url` helper at its default path; otherwise it
+     * is absent and you build the link from `token` yourself.
      */
     url?: string;
     /** The raw token, for apps that compose their own URL or message. */
@@ -47,8 +47,8 @@ export interface CodeDeliveryMessage {
 /** A delivery transport callback for one-time codes. */
 export type CodeDeliveryHook = (message: CodeDeliveryMessage) => Promise<void> | void;
 /**
- * App-supplied delivery transports. Omit a hook to disable that message type.
- * The package calls the relevant hook after minting the token; you send it.
+ * App-supplied delivery transports. Omit a hook and that message is never sent
+ * (the flow still mints and stores the token or code).
  *
  * Trigger point `delivery` (see `docs/trigger-points.md`). The package calls a
  * hook after minting the credential; a **throw** (e.g. a mailer outage) is

package/esm/identity/delivery.js

@@ -5,8 +5,7 @@
  * The library owns the **token lifecycle** ({@link TokenFlowService}); your app
  * owns **transport** — SMTP, SES, Resend, Twilio, etc. So delivery is a set of
  * app-supplied async hooks, and the package ships URL builders so apps stop
- * hand-assembling `${protocol}://${host}/verify-email?token=…` strings. This is
- * the Better Auth model (`sendVerificationEmail` / `sendResetPassword`).
+ * hand-assembling `${protocol}://${host}/verify-email?token=…` strings.
  *
  * @module
  */

package/esm/identity/errors.d.ts

@@ -6,9 +6,12 @@
  * @module
  */
 /**
- * Stable, machine-readable identity error codes. Most are raised by your store
- * or the service; `forbidden_origin` is raised by the Hono route factory's
- * same-origin guard before a handler runs.
+ * Stable, machine-readable identity error codes. The package raises
+ * `rate_limited`, `weak_password`, and the `mfa_*` codes, and the Hono route
+ * factory answers `forbidden_origin` (its same-origin guard, before a handler
+ * runs) and `invalid_credentials` / `invalid_token` (a failed sign-in or token
+ * check); the rest are for your store and routes to throw (e.g. `identifier_taken` on
+ * a duplicate sign-up, `captcha_failed` after `verifyCaptcha`).
  */
 export type IdentityErrorCode = "invalid_credentials" | "invalid_token" | "rate_limited" | "weak_password" | "identifier_taken" | "email_not_verified" | "mfa_not_enrolled" | "mfa_already_enrolled" | "captcha_failed" | "forbidden_origin";
 /** Options for {@link IdentityError}. */
@@ -31,7 +34,10 @@ export declare class IdentityError extends Error {
     /** Builds an identity error; `message` defaults to the `code` when omitted. */
     constructor(code: IdentityErrorCode, message?: string, options?: IdentityErrorOptions);
 }
-/** Type guard for {@link IdentityError}. */
+/**
+ * Type guard for {@link IdentityError}. An `instanceof` check, so an error from
+ * another realm or a second copy of the package fails it; compare `name` there.
+ */
 export declare function isIdentityError(value: unknown): value is IdentityError;
 /** The HTTP statuses an identity error maps to (a `ContentfulStatusCode` union). */
 export type IdentityErrorStatus = 400 | 401 | 403 | 409 | 422 | 429;

package/esm/identity/errors.js

@@ -24,7 +24,10 @@ export class IdentityError extends Error {
         this.retryAfterMs = options?.retryAfterMs;
     }
 }
-/** Type guard for {@link IdentityError}. */
+/**
+ * Type guard for {@link IdentityError}. An `instanceof` check, so an error from
+ * another realm or a second copy of the package fails it; compare `name` there.
+ */
 export function isIdentityError(value) {
     return value instanceof IdentityError;
 }

package/esm/identity/events.d.ts

@@ -13,8 +13,10 @@
  * Some outcomes are *only* visible here, because the flow that produced them
  * resolves uniformly by design: `delivery.failed` is the sole in-band signal
  * that a message never went out (and, when `invalidated` is `false`, that a
- * live credential the user never received is still outstanding). Treat this
- * hook as a monitored surface, not just an audit log.
+ * live credential the user never received is still outstanding), and
+ * `credential_mint.failed` the sole signal that a token or code store outage
+ * kept one from being minted at all. Treat this hook as a monitored surface,
+ * not just an audit log.
  *
  * Events describe internal outcomes (including whether an identifier resolved
  * to an account), so they are for server-side capture only — never surface
@@ -26,8 +28,9 @@ import type { DeliveryHooks } from "./delivery.js";
 /** Why a sign-in attempt failed. Internal detail — never shown to the user. */
 export type SignInFailureReason = "unknown_identifier" | "no_password" | "wrong_password";
 /**
- * Why a sign-in code verification failed. `unknown_email` is internal-only
- * detail — the caller-facing result reports it as `invalid`.
+ * Why a sign-in code verification failed. Internal detail — never shown to the
+ * user: `IdentityService.verifySignInCode` reports every one of these as
+ * `invalid`.
  */
 export type SignInCodeFailureReason = "invalid" | "expired" | "locked" | "unknown_email";
 /**
@@ -122,9 +125,22 @@ export type IdentityEvent = {
      * `"session_revocation_failed"` — the new password was set but the
      * configured {@link RevocableSessionService} threw before the user's other
      * sessions could be revoked, so the reset is reported failed (and rethrown)
-     * rather than trusted; retry it so the still-live sessions are cleared.
+     * rather than trusted. The reset token is already spent, so clear the
+     * still-live sessions by calling `revokeAllByUser` again from this event,
+     * or have the user complete a fresh reset link.
      */
     reason: "invalid_token" | "session_revocation_failed";
+} | {
+    type: "credential_mint.failed";
+    /**
+     * Which enumeration-safe request flow could not mint its credential
+     * because the token or code store threw. The call still resolved `void`,
+     * exactly as it does for an unknown email, so this event is the only
+     * signal that the user was never sent anything.
+     */
+    flow: "password_reset" | "signin_link" | "signin_code";
+    /** The store's failure message. */
+    error: string;
 } | {
     type: "email_verification.requested";
     userId: string;

package/esm/identity/events.js

@@ -13,8 +13,10 @@
  * Some outcomes are *only* visible here, because the flow that produced them
  * resolves uniformly by design: `delivery.failed` is the sole in-band signal
  * that a message never went out (and, when `invalidated` is `false`, that a
- * live credential the user never received is still outstanding). Treat this
- * hook as a monitored surface, not just an audit log.
+ * live credential the user never received is still outstanding), and
+ * `credential_mint.failed` the sole signal that a token or code store outage
+ * kept one from being minted at all. Treat this hook as a monitored surface,
+ * not just an audit log.
  *
  * Events describe internal outcomes (including whether an identifier resolved
  * to an account), so they are for server-side capture only — never surface

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

@@ -3,10 +3,7 @@
  *
  * Not part of the public API — reach for a connector from
  * `@udibo/oauth2/identity/external` instead, which re-exports the one type an
- * adopter configures ({@link AzpPolicy}). These live here so the same failure
- * reads the same way whichever connector hit it: one error renderer, one
- * error-body reader, one provider-text sanitizer, and one id_token claim gate
- * rather than a copy per provider. The token exchange itself is
+ * adopter configures ({@link AzpPolicy}). The token exchange is
  * `_token-exchange.ts`.
  *
  * @module
@@ -75,9 +72,10 @@ export interface IdTokenClaimsInput {
     leewaySeconds?: number;
 }
 /**
- * Enforces the id_token claim rules of OpenID Connect Core §3.1.3.7 that do not
- * depend on the signature: `iss`, `aud`, `azp`, `exp`, and `nonce`, in that
- * order. Callers verify the signature (or establish the token's provenance)
+ * Enforces these OpenID Connect Core §3.1.3.7 claim checks, in order: `iss`,
+ * `aud`, `azp`, `exp` (a missing `exp` fails), and `nonce` (only when
+ * `expectedNonce` is given). `iat`, `acr`, and `auth_time` are not checked.
+ * Callers verify the signature (or establish the token's provenance)
  * themselves before calling this.
  *
  * Throws {@link ExternalAuthError} with code `nonce_mismatch` when the `nonce`

package/esm/identity/external/_shared.js

@@ -3,10 +3,7 @@
  *
  * Not part of the public API — reach for a connector from
  * `@udibo/oauth2/identity/external` instead, which re-exports the one type an
- * adopter configures ({@link AzpPolicy}). These live here so the same failure
- * reads the same way whichever connector hit it: one error renderer, one
- * error-body reader, one provider-text sanitizer, and one id_token claim gate
- * rather than a copy per provider. The token exchange itself is
+ * adopter configures ({@link AzpPolicy}). The token exchange is
  * `_token-exchange.ts`.
  *
  * @module
@@ -61,9 +58,10 @@ export function stripTrailingSlash(value) {
     return value.endsWith("/") ? value.slice(0, -1) : value;
 }
 /**
- * Enforces the id_token claim rules of OpenID Connect Core §3.1.3.7 that do not
- * depend on the signature: `iss`, `aud`, `azp`, `exp`, and `nonce`, in that
- * order. Callers verify the signature (or establish the token's provenance)
+ * Enforces these OpenID Connect Core §3.1.3.7 claim checks, in order: `iss`,
+ * `aud`, `azp`, `exp` (a missing `exp` fails), and `nonce` (only when
+ * `expectedNonce` is given). `iat`, `acr`, and `auth_time` are not checked.
+ * Callers verify the signature (or establish the token's provenance)
  * themselves before calling this.
  *
  * Throws {@link ExternalAuthError} with code `nonce_mismatch` when the `nonce`

package/esm/identity/external/_token-exchange.d.ts

@@ -3,11 +3,8 @@
  * through — {@link githubProvider}, {@link oauth2Provider} (and its
  * {@link discordProvider} preset), and {@link appleProvider}.
  * {@link oidcProvider}, and {@link googleProvider} on top of it, exchange via
- * `OAuth2Client` instead and do not reach this module.
- *
- * Not part of the public API. Split out of `_shared.ts` so the ladder — the one
- * place a provider's bytes become an error message or a token — sits next to
- * the tests that pin it.
+ * `DirectClient` instead and do not reach this module. Not part of the public
+ * API.
  *
  * @module
  */
@@ -35,7 +32,7 @@ export interface TokenExchangeInput {
      * `RequestInit`** — `redirect` and `signal` in particular. They are the only
      * channel the redirect refusal and the deadline reach the transport, so a
      * wrapper that rebuilds `init` from scratch silently reopens the credential
-     * replay hole. `createGuardedFetch` forwards both.
+     * replay hole.
      */
     fetch: typeof fetch;
     /** Guidance appended when a failure carries no OAuth2 error code. */

package/esm/identity/external/_token-exchange.js

@@ -3,11 +3,8 @@
  * through — {@link githubProvider}, {@link oauth2Provider} (and its
  * {@link discordProvider} preset), and {@link appleProvider}.
  * {@link oidcProvider}, and {@link googleProvider} on top of it, exchange via
- * `OAuth2Client` instead and do not reach this module.
- *
- * Not part of the public API. Split out of `_shared.ts` so the ladder — the one
- * place a provider's bytes become an error message or a token — sits next to
- * the tests that pin it.
+ * `DirectClient` instead and do not reach this module. Not part of the public
+ * API.
  *
  * @module
  */

package/esm/identity/external/apple-client-secret.d.ts

@@ -38,8 +38,8 @@ export interface AppleClientSecretOptions {
     privateKey: string;
     /**
      * Lifetime of the generated secret in seconds. Defaults to
-     * {@link DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS}; must not exceed
-     * {@link APPLE_CLIENT_SECRET_MAX_TTL_SECONDS}.
+     * {@link DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS}; must be a finite number
+     * that does not exceed {@link APPLE_CLIENT_SECRET_MAX_TTL_SECONDS}.
      */
     expiresInSeconds?: number;
     /** Provider id used in error messages. Defaults to `"apple"`. */
@@ -54,7 +54,8 @@ export interface AppleClientSecretOptions {
  *
  * @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
@@ -67,15 +68,19 @@ export interface AppleClientSecretOptions {
  * ```
  */
 export declare function generateAppleClientSecret(options: AppleClientSecretOptions): Promise<string>;
-/** A cached client-secret source: returns a valid secret, re-signing lazily. */
+/**
+ * Returns the client-secret JWT to present on a token exchange; called once per
+ * exchange. {@link createAppleClientSecretFactory} builds the caching one.
+ */
 export type AppleClientSecretFactory = () => Promise<string>;
 /**
  * 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 declare function createAppleClientSecretFactory(options: AppleClientSecretOptions & {
     renewBeforeSeconds?: number;