@udibo/oauth2 0.4.1 → 0.5.1

package/esm/client/check.js

@@ -27,6 +27,8 @@
  * @module
  */
 import { ServerError, TemporarilyUnavailableError } from "../errors.js";
+import { receiveJson, sendGuarded } from "./_http.js";
+const CHECK_ENDPOINT = "check endpoint";
 /**
  * Ask a check endpoint whether the caller holds the named permissions.
  *
@@ -46,7 +48,11 @@ import { ServerError, TemporarilyUnavailableError } from "../errors.js";
  * tenant no longer resolves is a 404 and lands there too. Echoing an `org_id`
  * off a signed claim is how you meet it, because the organization can be
  * deleted after the signature, so catch it on that path rather than reading a
- * throw as a bug in your own setup.
+ * throw as a bug in your own setup. A redirect, or a `2xx` whose body is not a
+ * JSON object or exceeds the response-size cap, also throws
+ * {@linkcode ServerError}, and a request whose response headers do not
+ * arrive before the deadline throws {@linkcode TemporarilyUnavailableError}.
+ * The body's shape is not validated beyond being a JSON object.
  *
  * @example
  * ```ts
@@ -68,9 +74,19 @@ import { ServerError, TemporarilyUnavailableError } from "../errors.js";
  */
 export async function checkPermissions(options) {
     const fetchImpl = options.fetch ?? fetch;
+    const reportUnreachable = async (input, init) => {
+        try {
+            return await fetchImpl(input, init);
+        }
+        catch (cause) {
+            throw new TemporarilyUnavailableError("check endpoint unreachable", {
+                cause,
+            });
+        }
+    };
     let response;
     try {
-        response = await fetchImpl(options.endpoint, {
+        response = await sendGuarded(reportUnreachable, options.endpoint, {
             method: "POST",
             headers: {
                 authorization: `Bearer ${options.accessToken}`,
@@ -80,18 +96,22 @@ export async function checkPermissions(options) {
                 permissions: options.permissions,
                 ...(options.resource ? { resource: options.resource } : {}),
             }),
-        });
+        }, CHECK_ENDPOINT);
     }
-    catch (cause) {
-        throw new TemporarilyUnavailableError("check endpoint unreachable", {
-            cause,
-        });
+    catch (error) {
+        if (error instanceof Error &&
+            error.cause instanceof TemporarilyUnavailableError) {
+            throw error.cause;
+        }
+        throw error;
     }
     if (response.status >= 500) {
+        await response.body?.cancel();
         throw new TemporarilyUnavailableError(`check endpoint answered ${response.status}`);
     }
     if (!response.ok) {
+        await response.body?.cancel();
         throw new ServerError(`check request refused: ${response.status}`);
     }
-    return await response.json();
+    return await receiveJson(response, CHECK_ENDPOINT);
 }

package/esm/client/direct-client.d.ts

@@ -62,9 +62,9 @@ export interface DirectClientOptions extends BaseOptions {
     /** Default scope string to request when none is passed explicitly. */
     scope?: string;
     /**
-     * Issuer URL. If provided, endpoints are fetched from
-     * `${issuer}/.well-known/oauth-authorization-server` on first use.
-     * Mutually exclusive with an explicit `endpoints` record below.
+     * Issuer URL. If provided, endpoints come from the issuer's discovery
+     * document, fetched on first use and re-fetched once it expires (see
+     * {@link DirectClient.discover}). Mutually exclusive with `endpoints`.
      */
     issuer?: string;
     /** Explicit endpoint URLs, bypassing discovery. */
@@ -99,8 +99,9 @@ export interface DirectClientOptions extends BaseOptions {
     /**
      * Max age of a pending auth-request (`state`) record before
      * {@link DirectClient.exchangeAuthorizationCode} rejects it as stale, in ms.
-     * Bounds the callback replay window and unbounded growth of the in-memory
-     * store. Defaults to 10 minutes; set `Infinity` to disable the check.
+     * Bounds the callback replay window. Both default storages also expire
+     * records older than this; a storage you pass expires records by its own
+     * rules. Defaults to 10 minutes; set `Infinity` to disable the check.
      */
     authRequestTtlMs?: number;
 }
@@ -184,7 +185,7 @@ export interface ExchangeOptions {
 export interface ExchangeResult {
     /** The token bundle, not persisted to this client's storage. */
     tokens: TokenBundle;
-    /** The rotated refresh token, when the server issued one. */
+    /** The refresh token the server issued with this response, if any. */
     refreshToken?: string;
     /** `returnTo` recorded at authorize time, for the code exchange. */
     returnTo?: string;
@@ -268,8 +269,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      * this works against any compliant server. **Lazy + cached**: it only runs
      * on the first endpoint use of an `issuer`-configured client (never at
      * construction), so there is no startup cost and no per-request fetch.
-     * Concurrent calls share one in-flight request; a failure clears the cache
-     * so a later call can retry.
+     * Concurrent calls share one in-flight request; a failure is not cached, so
+     * a later call retries.
      *
      * **Re-resolution contract.** The document this client holds is never
      * permanent: every endpoint use re-resolves once the copy in hand is past
@@ -289,7 +290,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @returns The server's metadata document.
      * @throws {Error} when the client was configured with explicit `endpoints`
      * rather than an `issuer` — there is nothing to discover.
-     * @throws {ServerError} when both well-known paths fail.
+     * @throws {OAuth2Error} the last attempt's error when both well-known paths
+     * fail: the server is unreachable, answers non-OK or with something other
+     * than a JSON object, or reports an `issuer` other than the configured one.
      *
      * @example
      * ```ts
@@ -367,9 +370,10 @@ export declare class DirectClient extends OAuth2ClientBase {
      * URL, exchanges the code at the token endpoint, persists the token bundle,
      * and emits `authenticated`.
      *
-     * Idempotent on duplicate calls with the same `code` — React strict-mode
-     * double-mounts would otherwise double-redeem a single-use code and fail the
-     * second call, so the first in-flight promise is returned again.
+     * A duplicate call with the same `code` while the first is still in flight
+     * (a React strict-mode double mount) returns the first call's promise rather
+     * than redeeming the single-use code twice. A call after it settles redeems
+     * again, and fails.
      *
      * @param input The callback URL, its query string, or the parsed params.
      * @returns The persisted tokens and the `returnTo` recorded at login.
@@ -403,8 +407,12 @@ export declare class DirectClient extends OAuth2ClientBase {
      * token state across this client's storage and the caller's external store,
      * so refresh, revocation, and logout all stop working as expected.
      *
-     * The verifier and `returnTo` are looked up under `state`; on success the
-     * record is consumed. Emits nothing — the caller owns session semantics.
+     * The verifier and `returnTo` are claimed under `state` before the token
+     * call, so the record is consumed whether or not the exchange succeeds and
+     * two callbacks racing on one `state` reach the token endpoint at most once
+     * (atomically so for a storage that implements
+     * {@link AuthRequestStorage.take}). Emits nothing — the caller owns session
+     * semantics.
      *
      * @param code The authorization code from the callback.
      * @param state The `state` the callback echoed back.
@@ -523,7 +531,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * minimum interval and deadline, and `signal` to cancel.
      * @returns The persisted token bundle.
      * @throws {AccessDeniedError} when `signal` aborts, or the user declines.
-     * @throws {InvalidGrantError} when the device code expires before approval.
+     * @throws {InvalidGrantError} when `expiresAt` passes before approval. A
+     * server that reports the code expired first throws `ExpiredTokenError`
+     * instead.
      * @throws {OAuth2Error} on any other terminal error from the server.
      */
     pollDeviceToken(deviceCode: string, options?: PollDeviceTokenOptions): Promise<TokenBundle>;
@@ -561,18 +571,19 @@ export declare class DirectClient extends OAuth2ClientBase {
      *
      * @returns The claims the server returns.
      * @throws {Error} when no userinfo endpoint is configured or discoverable.
-     * @throws {AccessDeniedError} when no token is stored and none can be
-     * refreshed.
+     * @throws {InvalidGrantError} when no usable token is stored and there is no
+     * refresh token to mint one.
+     * @throws {OAuth2Error} when the refresh or the userinfo endpoint fails.
      */
     getUserInfo(): Promise<UserInfoClaims>;
     /**
      * Base64url-decodes an OIDC `id_token` payload and returns the claims.
      *
-     * **Does not verify the signature** — the token arrives from the token
-     * endpoint over TLS, so verification would only defend against a compromised
-     * TLS chain and is not a normal client concern. If you need verification
-     * (e.g. the token was obtained out-of-band), use a dedicated JWT library
-     * with your server's JWKS.
+     * **Validates nothing** — not the signature, `iss`, `aud`, `exp`, or
+     * `nonce`. Use it only on an `id_token` this client received from its own
+     * token endpoint (which is what {@link getUser} does); the client does not
+     * require that endpoint to be `https`. For a token obtained any other way,
+     * verify it with a JWT library against the server's JWKS.
      *
      * @param idToken A compact-serialized JWS.
      * @returns The decoded payload claims.
@@ -590,6 +601,11 @@ export declare class DirectClient extends OAuth2ClientBase {
      * A `401` without that challenge is returned as-is — it means "not allowed",
      * not "token stale", and re-minting would not help.
      *
+     * The stored access token is sent as-is, even when it has expired; recovery
+     * depends on the resource server answering with that challenge. It is
+     * attached to whatever URL you pass, so send only requests meant for the
+     * APIs this token is for.
+     *
      * @param input Request target, as for `fetch`. A `Request` keeps the headers
      * and body it was built with; it is cloned up front so the retry has an
      * unread body.
@@ -613,9 +629,10 @@ export declare class DirectClient extends OAuth2ClientBase {
      * state, emits `logged_out`, and returns the OIDC end-session URL when the
      * server advertises one.
      *
-     * Best effort covers the read too: a refresh-token store that cannot be read
-     * skips the revocation rather than failing the sign-out, because a client
-     * that stays signed in locally because its store broke is the worse outcome.
+     * Best effort covers the reads too: a refresh-token store that cannot be
+     * read skips the revocation, and a token store that cannot be read omits
+     * `id_token_hint`, rather than failing the sign-out, because a client that
+     * stays signed in locally because its store broke is the worse outcome.
      *
      * @param options `returnTo` becomes `post_logout_redirect_uri` on the
      * end-session URL.
@@ -643,7 +660,8 @@ export declare class DirectClient extends OAuth2ClientBase {
     getUser(): Promise<UserInfoClaims | null>;
     /**
      * The session as this client sees it, derived from stored tokens — no
-     * network call unless the claims come from a userinfo endpoint.
+     * network call unless the claims come from a userinfo endpoint, which may
+     * refresh the access token first.
      *
      * `isAuthenticated` requires a usable access token: a stored bundle whose
      * `accessToken` is non-empty and not past its expiry. A holder of a valid
@@ -699,9 +717,11 @@ export declare class DirectClient extends OAuth2ClientBase {
      * For ordinary HTTP calls prefer {@link fetch}, which attaches the token and
      * handles the 401/refresh dance for you.
      *
-     * @returns A non-expired access token.
-     * @throws {InvalidGrantError} when nothing is stored and no refresh token is
-     * available.
+     * @returns The stored access token when it has no recorded expiry or more
+     * than 30 seconds left, otherwise a freshly refreshed one.
+     * @throws {InvalidGrantError} when a refresh is needed and no refresh token
+     * is stored, or the stored one is dead.
+     * @throws {OAuth2Error} when a needed refresh fails for another reason.
      */
     getAccessToken(): Promise<string>;
 }

package/esm/client/direct-client.js

@@ -121,9 +121,9 @@ export class DirectClient extends OAuth2ClientBase {
         this.#tokenStorage = options.tokenStorage ?? new MemoryTokenStorage();
         this.#refreshTokenStorage = options.refreshTokenStorage ??
             new MemoryRefreshTokenStorage();
-        this.#authRequestStorage = options.authRequestStorage ??
-            defaultAuthRequestStorage();
         this.#authRequestTtlMs = options.authRequestTtlMs ?? 10 * 60 * 1000;
+        this.#authRequestStorage = options.authRequestStorage ??
+            defaultAuthRequestStorage(this.#authRequestTtlMs);
     }
     /** True when the client was given a secret and authenticates via Basic. */
     get isConfidential() {
@@ -138,8 +138,8 @@ export class DirectClient extends OAuth2ClientBase {
      * this works against any compliant server. **Lazy + cached**: it only runs
      * on the first endpoint use of an `issuer`-configured client (never at
      * construction), so there is no startup cost and no per-request fetch.
-     * Concurrent calls share one in-flight request; a failure clears the cache
-     * so a later call can retry.
+     * Concurrent calls share one in-flight request; a failure is not cached, so
+     * a later call retries.
      *
      * **Re-resolution contract.** The document this client holds is never
      * permanent: every endpoint use re-resolves once the copy in hand is past
@@ -159,7 +159,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @returns The server's metadata document.
      * @throws {Error} when the client was configured with explicit `endpoints`
      * rather than an `issuer` — there is nothing to discover.
-     * @throws {ServerError} when both well-known paths fail.
+     * @throws {OAuth2Error} the last attempt's error when both well-known paths
+     * fail: the server is unreachable, answers non-OK or with something other
+     * than a JSON object, or reports an `issuer` other than the configured one.
      *
      * @example
      * ```ts
@@ -359,9 +361,10 @@ export class DirectClient extends OAuth2ClientBase {
      * URL, exchanges the code at the token endpoint, persists the token bundle,
      * and emits `authenticated`.
      *
-     * Idempotent on duplicate calls with the same `code` — React strict-mode
-     * double-mounts would otherwise double-redeem a single-use code and fail the
-     * second call, so the first in-flight promise is returned again.
+     * A duplicate call with the same `code` while the first is still in flight
+     * (a React strict-mode double mount) returns the first call's promise rather
+     * than redeeming the single-use code twice. A call after it settles redeems
+     * again, and fails.
      *
      * @param input The callback URL, its query string, or the parsed params.
      * @returns The persisted tokens and the `returnTo` recorded at login.
@@ -433,8 +436,12 @@ export class DirectClient extends OAuth2ClientBase {
      * token state across this client's storage and the caller's external store,
      * so refresh, revocation, and logout all stop working as expected.
      *
-     * The verifier and `returnTo` are looked up under `state`; on success the
-     * record is consumed. Emits nothing — the caller owns session semantics.
+     * The verifier and `returnTo` are claimed under `state` before the token
+     * call, so the record is consumed whether or not the exchange succeeds and
+     * two callbacks racing on one `state` reach the token endpoint at most once
+     * (atomically so for a storage that implements
+     * {@link AuthRequestStorage.take}). Emits nothing — the caller owns session
+     * semantics.
      *
      * @param code The authorization code from the callback.
      * @param state The `state` the callback echoed back.
@@ -448,12 +455,11 @@ export class DirectClient extends OAuth2ClientBase {
     async exchangeAuthorizationCode(code, state, options = {}) {
         const authRequestStorage = options.authRequestStorage ??
             this.#authRequestStorage;
-        const record = await authRequestStorage.get(state);
+        const record = await claimAuthRequest(authRequestStorage, state);
         if (!record)
             throw new InvalidGrantError("unknown state parameter");
         if (this.#authRequestTtlMs !== Infinity &&
             Date.now() - record.createdAt > this.#authRequestTtlMs) {
-            await authRequestStorage.delete(state);
             throw new InvalidGrantError("authorization request expired");
         }
         const body = new URLSearchParams({
@@ -465,7 +471,6 @@ export class DirectClient extends OAuth2ClientBase {
         if (redirectUri)
             body.set("redirect_uri", redirectUri);
         const raw = await this.#postToken(body);
-        await authRequestStorage.delete(state);
         return {
             tokens: responseToBundle(raw),
             refreshToken: raw.refresh_token,
@@ -679,7 +684,9 @@ export class DirectClient extends OAuth2ClientBase {
      * minimum interval and deadline, and `signal` to cancel.
      * @returns The persisted token bundle.
      * @throws {AccessDeniedError} when `signal` aborts, or the user declines.
-     * @throws {InvalidGrantError} when the device code expires before approval.
+     * @throws {InvalidGrantError} when `expiresAt` passes before approval. A
+     * server that reports the code expired first throws `ExpiredTokenError`
+     * instead.
      * @throws {OAuth2Error} on any other terminal error from the server.
      */
     async pollDeviceToken(deviceCode, options = {}) {
@@ -776,8 +783,9 @@ export class DirectClient extends OAuth2ClientBase {
      *
      * @returns The claims the server returns.
      * @throws {Error} when no userinfo endpoint is configured or discoverable.
-     * @throws {AccessDeniedError} when no token is stored and none can be
-     * refreshed.
+     * @throws {InvalidGrantError} when no usable token is stored and there is no
+     * refresh token to mint one.
+     * @throws {OAuth2Error} when the refresh or the userinfo endpoint fails.
      */
     async getUserInfo() {
         return await this.#fetchUserInfo(false);
@@ -796,11 +804,11 @@ export class DirectClient extends OAuth2ClientBase {
     /**
      * Base64url-decodes an OIDC `id_token` payload and returns the claims.
      *
-     * **Does not verify the signature** — the token arrives from the token
-     * endpoint over TLS, so verification would only defend against a compromised
-     * TLS chain and is not a normal client concern. If you need verification
-     * (e.g. the token was obtained out-of-band), use a dedicated JWT library
-     * with your server's JWKS.
+     * **Validates nothing** — not the signature, `iss`, `aud`, `exp`, or
+     * `nonce`. Use it only on an `id_token` this client received from its own
+     * token endpoint (which is what {@link getUser} does); the client does not
+     * require that endpoint to be `https`. For a token obtained any other way,
+     * verify it with a JWT library against the server's JWKS.
      *
      * @param idToken A compact-serialized JWS.
      * @returns The decoded payload claims.
@@ -824,6 +832,11 @@ export class DirectClient extends OAuth2ClientBase {
      * A `401` without that challenge is returned as-is — it means "not allowed",
      * not "token stale", and re-minting would not help.
      *
+     * The stored access token is sent as-is, even when it has expired; recovery
+     * depends on the resource server answering with that challenge. It is
+     * attached to whatever URL you pass, so send only requests meant for the
+     * APIs this token is for.
+     *
      * @param input Request target, as for `fetch`. A `Request` keeps the headers
      * and body it was built with; it is cloned up front so the retry has an
      * unread body.
@@ -871,9 +884,10 @@ export class DirectClient extends OAuth2ClientBase {
      * state, emits `logged_out`, and returns the OIDC end-session URL when the
      * server advertises one.
      *
-     * Best effort covers the read too: a refresh-token store that cannot be read
-     * skips the revocation rather than failing the sign-out, because a client
-     * that stays signed in locally because its store broke is the worse outcome.
+     * Best effort covers the reads too: a refresh-token store that cannot be
+     * read skips the revocation, and a token store that cannot be read omits
+     * `id_token_hint`, rather than failing the sign-out, because a client that
+     * stays signed in locally because its store broke is the worse outcome.
      *
      * @param options `returnTo` becomes `post_logout_redirect_uri` on the
      * end-session URL.
@@ -893,7 +907,9 @@ export class DirectClient extends OAuth2ClientBase {
     async logout(options = {}) {
         const version = ++this.#sessionVersion;
         const refreshToken = await this.#readRefreshToken(false).catch(() => null);
-        const idToken = (await this.#tokenStorage.get())?.idToken;
+        const idToken = await Promise.resolve()
+            .then(() => this.#tokenStorage.get())
+            .then((tokens) => tokens?.idToken, () => undefined);
         if (version !== this.#sessionVersion)
             return {};
         await this.#clearSession();
@@ -945,7 +961,8 @@ export class DirectClient extends OAuth2ClientBase {
     }
     /**
      * The session as this client sees it, derived from stored tokens — no
-     * network call unless the claims come from a userinfo endpoint.
+     * network call unless the claims come from a userinfo endpoint, which may
+     * refresh the access token first.
      *
      * `isAuthenticated` requires a usable access token: a stored bundle whose
      * `accessToken` is non-empty and not past its expiry. A holder of a valid
@@ -1032,9 +1049,11 @@ export class DirectClient extends OAuth2ClientBase {
      * For ordinary HTTP calls prefer {@link fetch}, which attaches the token and
      * handles the 401/refresh dance for you.
      *
-     * @returns A non-expired access token.
-     * @throws {InvalidGrantError} when nothing is stored and no refresh token is
-     * available.
+     * @returns The stored access token when it has no recorded expiry or more
+     * than 30 seconds left, otherwise a freshly refreshed one.
+     * @throws {InvalidGrantError} when a refresh is needed and no refresh token
+     * is stored, or the stored one is dead.
+     * @throws {OAuth2Error} when a needed refresh fails for another reason.
      */
     async getAccessToken() {
         return await this.#accessTokenFor(false);
@@ -1051,11 +1070,6 @@ export class DirectClient extends OAuth2ClientBase {
     #basicAuth() {
         return encodeBasicAuth(this.#clientId, this.#clientSecret);
     }
-    /**
-     * Applies exactly one client authentication method (RFC 6749 §2.3.1):
-     * HTTP Basic for a confidential client — dropping any body `client_id` so
-     * credentials aren't sent twice — or a body `client_id` for a public one.
-     */
     #applyClientAuth(headers, body) {
         if (this.isConfidential) {
             headers.Authorization = this.#basicAuth();
@@ -1075,10 +1089,6 @@ export class DirectClient extends OAuth2ClientBase {
         assertTokenResponse(response, "token endpoint");
         return response;
     }
-    /**
-     * POSTs a form to a credentialed endpoint and returns its JSON object.
-     * Refuses a redirect rather than replaying the credentials in `body`.
-     */
     async #postForm(endpoint, headers, body, what) {
         const res = await sendGuarded((input, init) => this.fetchImpl(input, init), endpoint, {
             method: "POST",
@@ -1123,11 +1133,6 @@ export class DirectClient extends OAuth2ClientBase {
         });
     }
 }
-/**
- * Returns `urlStr` with its origin (scheme + host) replaced by `origin`'s,
- * preserving the path/query. Resolving against the new origin replaces
- * scheme/host/port cleanly; setting `.host` alone would keep a stale port.
- */
 function withOrigin(urlStr, origin) {
     const url = new URL(urlStr);
     return new URL(`${url.pathname}${url.search}${url.hash}`, origin).toString();
@@ -1176,12 +1181,20 @@ function toSearchParams(input) {
         return new URLSearchParams(input.startsWith("?") ? input.slice(1) : input);
     }
 }
-function defaultAuthRequestStorage() {
+function defaultAuthRequestStorage(ttlMs) {
     const inBrowserDocument = typeof document !== "undefined" &&
         typeof sessionStorage !== "undefined";
     return inBrowserDocument
-        ? new SessionStorageAuthRequestStorage()
-        : new MemoryAuthRequestStorage();
+        ? new SessionStorageAuthRequestStorage({ ttlMs })
+        : new MemoryAuthRequestStorage({ ttlMs });
+}
+async function claimAuthRequest(storage, state) {
+    if (storage.take)
+        return await storage.take(state);
+    const record = await storage.get(state);
+    if (record)
+        await storage.delete(state);
+    return record;
 }
 function assertUsableSecret(secret) {
     if (secret === undefined)
@@ -1199,12 +1212,6 @@ function assertUsableSecret(secret) {
             "exchange behind a BffClient.");
     }
 }
-/**
- * RFC 8414 §3.3 / OIDC Discovery §4.3: the `issuer` a metadata document
- * reports must be the issuer it was fetched from. Without this a document
- * served (or redirected to) from elsewhere could name another provider's
- * endpoints, which is the mix-up attack the requirement exists to stop.
- */
 function assertIssuer(meta, issuer) {
     const reported = meta.issuer;
     if (typeof reported !== "string" || reported.length === 0) {
@@ -1223,13 +1230,6 @@ function trimSlash(url) {
 function isOAuth2ErrorCode(error, code) {
     return isOAuth2Error(error) && error.extensions.error === code;
 }
-/**
- * Sleeps `ms`, or rejects with {@link AccessDeniedError} if `signal` aborts —
- * so cancelling a device-flow poll mid-wait surfaces as `access_denied`, the
- * same as the loop-top abort guard in {@link DirectClient.pollDeviceToken}.
- * The timer/abort plumbing is `@std/async/delay`; only the OAuth2 error
- * mapping is ours (`delay` rejects solely on abort).
- */
 function pollDelay(ms, signal) {
     return delay(ms, { signal }).catch(() => {
         throw new AccessDeniedError("aborted");

package/esm/client/discovery-cache.d.ts

@@ -5,7 +5,11 @@
  * @module
  */
 import type { AuthorizationServerMetadata } from "../models/responses.js";
-/** Default entry lifetime for {@link MemoryDiscoveryCache}: one hour. */
+/**
+ * Default discovery-document lifetime, one hour: the TTL of a
+ * {@link MemoryDiscoveryCache}, and how long a `DirectClient` without a
+ * `discoveryCache` keeps its own copy.
+ */
 export declare const DEFAULT_DISCOVERY_TTL_MS: number;
 /** Default entry ceiling for {@link MemoryDiscoveryCache}. */
 export declare const DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES = 100;
@@ -86,15 +90,15 @@ export interface MemoryDiscoveryCacheOptions {
     /**
      * Maximum number of issuers held. Defaults to
      * {@link DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES}. Expired entries are dropped
-     * first, then the least recently stored, so a multi-tenant server with an
+     * first, then the least recently used, so a multi-tenant server with an
      * unbounded issuer list cannot grow without limit.
      */
     maxEntries?: number;
 }
 /**
  * In-memory {@link DiscoveryCache}: TTL entries plus in-flight de-duplication,
- * so a burst of requests against a cold issuer triggers exactly one discovery
- * fetch. Failures are never cached.
+ * so a burst of requests against a cold issuer triggers one `load`. Failures
+ * are never cached.
  *
  * Construct one per process (or per trust boundary) and hand it to every
  * client that should share it.
@@ -133,6 +137,9 @@ export declare class MemoryDiscoveryCache implements DiscoveryCache {
     resolve(issuer: string, load: () => Promise<AuthorizationServerMetadata>): Promise<DiscoveryCacheEntry>;
     /** Drops the entry for `issuer`, forcing the next resolve to re-fetch. */
     delete(issuer: string): void;
-    /** Drops every entry. In-flight loads still settle for their callers. */
+    /**
+     * Drops every entry. A load already in flight still settles for its callers
+     * and stores its result.
+     */
     clear(): void;
 }

package/esm/client/discovery-cache.js

@@ -4,14 +4,18 @@
  *
  * @module
  */
-/** Default entry lifetime for {@link MemoryDiscoveryCache}: one hour. */
+/**
+ * Default discovery-document lifetime, one hour: the TTL of a
+ * {@link MemoryDiscoveryCache}, and how long a `DirectClient` without a
+ * `discoveryCache` keeps its own copy.
+ */
 export const DEFAULT_DISCOVERY_TTL_MS = 60 * 60 * 1000;
 /** Default entry ceiling for {@link MemoryDiscoveryCache}. */
 export const DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES = 100;
 /**
  * In-memory {@link DiscoveryCache}: TTL entries plus in-flight de-duplication,
- * so a burst of requests against a cold issuer triggers exactly one discovery
- * fetch. Failures are never cached.
+ * so a burst of requests against a cold issuer triggers one `load`. Failures
+ * are never cached.
  *
  * Construct one per process (or per trust boundary) and hand it to every
  * client that should share it.
@@ -81,7 +85,10 @@ export class MemoryDiscoveryCache {
     delete(issuer) {
         this.#entries.delete(normalizeIssuer(issuer));
     }
-    /** Drops every entry. In-flight loads still settle for their callers. */
+    /**
+     * Drops every entry. A load already in flight still settles for its callers
+     * and stores its result.
+     */
     clear() {
         this.#entries.clear();
     }

package/esm/client/events.d.ts

@@ -14,11 +14,19 @@ export interface AuthenticatedEvent {
     /** The token bundle that was just persisted for the session. */
     tokens: TokenBundle;
 }
-/** The client has cleared its session and the user is no longer authenticated. */
+/**
+ * The user is signed out, or is about to be: `BffClient.logout` emits it before
+ * the browser has navigated to the BFF's logout route.
+ */
 export interface LoggedOutEvent {
     /** Discriminant tag for this event variant. */
     type: "logged_out";
-    /** Why the session ended. */
+    /**
+     * Why the session ended: `user` when `logout` ran, `invalid_grant` when a
+     * `DirectClient` refresh found the grant dead (local tokens are already
+     * cleared), `session_expired` when a `BffClient.fetch` got a `401`.
+     * `refresh_failed` is never emitted by the shipped clients.
+     */
     reason: "user" | "refresh_failed" | "invalid_grant" | "session_expired";
 }
 /** A refresh has just completed; the access token has rotated. */
@@ -39,7 +47,7 @@ export interface ErrorEvent {
 export type OAuth2ClientEvent = AuthenticatedEvent | LoggedOutEvent | TokenRefreshedEvent | ErrorEvent;
 /** Subscriber callback. Return values are ignored. */
 export type OAuth2ClientEventListener = (event: OAuth2ClientEvent) => void;
-/** Minimal event bus for the client to avoid pulling in a dependency. */
+/** The clients' listener registry; one throwing listener never blocks the rest. */
 export declare class EventBus {
     #private;
     /** Registers `listener` and returns a function that removes it. */

package/esm/client/events.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-/** Minimal event bus for the client to avoid pulling in a dependency. */
+/** The clients' listener registry; one throwing listener never blocks the rest. */
 export class EventBus {
     #listeners = new Set();
     /** Registers `listener` and returns a function that removes it. */