@udibo/oauth2 0.1.0

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

@@ -0,0 +1,138 @@
+/**
+ * Discovery-metadata cache shared across `DirectClient` instances, for
+ * servers that build a short-lived client per request.
+ *
+ * @module
+ */
+import type { AuthorizationServerMetadata } from "../models/responses.js";
+/** Default entry lifetime for {@link MemoryDiscoveryCache}: one hour. */
+export declare const DEFAULT_DISCOVERY_TTL_MS: number;
+/** Default entry ceiling for {@link MemoryDiscoveryCache}. */
+export declare const DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES = 100;
+/**
+ * What {@link DiscoveryCache.resolve} answers with: the metadata document plus
+ * the moment it stops being fresh.
+ *
+ * A reader holds `metadata` without calling `resolve` again until `expiresAt`,
+ * so a cache that costs a round trip is read once per entry lifetime rather
+ * than once per endpoint lookup — which is why a remote implementation needs no
+ * memo of its own.
+ */
+export interface DiscoveryCacheEntry {
+    /** The metadata document for the issuer. */
+    metadata: AuthorizationServerMetadata;
+    /**
+     * Epoch ms at which {@link DiscoveryCacheEntry.metadata} stops being fresh.
+     *
+     * Report the entry's own expiry, never later: a value further out pins a
+     * stale document in every reader. `Infinity` never expires; a value in the
+     * past forces a `resolve` call on every lookup.
+     */
+    expiresAt: number;
+}
+/**
+ * A cache of authorization-server metadata keyed by issuer, shared by any
+ * number of `DirectClient` instances.
+ *
+ * Implement this to back discovery with something other than process memory
+ * (Redis, a file, a CDN edge cache). The single {@link DiscoveryCache.resolve}
+ * method is get-or-load rather than get/set so an implementation can also
+ * collapse concurrent misses into one `load` call — a get/set pair cannot.
+ *
+ * Metadata is issuer-scoped and public: it carries no client id, secret, or
+ * tenant data, so one cache may serve many tenants pointed at the same issuer.
+ * Do share a cache across clients that reach an issuer the same way; do not
+ * share one between a stubbed transport and live traffic.
+ *
+ * @example Backing discovery with a store of your own
+ * ```ts
+ * declare const store: Map<string, { json: string; expiresAt: number }>;
+ * const ttlMs = 60 * 60 * 1000;
+ *
+ * const discoveryCache: DiscoveryCache = {
+ *   async resolve(issuer, load) {
+ *     const hit = store.get(issuer);
+ *     if (hit && hit.expiresAt > Date.now()) {
+ *       return { metadata: JSON.parse(hit.json), expiresAt: hit.expiresAt };
+ *     }
+ *     const metadata = await load();
+ *     const expiresAt = Date.now() + ttlMs;
+ *     store.set(issuer, { json: JSON.stringify(metadata), expiresAt });
+ *     return { metadata, expiresAt };
+ *   },
+ * };
+ * ```
+ */
+export interface DiscoveryCache {
+    /**
+     * Returns the cached entry for `issuer`, or awaits `load` and caches it.
+     *
+     * `load` must not be called when a fresh entry exists, and concurrent calls
+     * for one issuer should share a single `load`. A rejected `load` must not be
+     * cached — the rejection propagates and the next call retries. The returned
+     * `expiresAt` is what lets a reader skip this call entirely while the
+     * document it already holds is still fresh, so it must not outlast the
+     * entry.
+     */
+    resolve(issuer: string, load: () => Promise<AuthorizationServerMetadata>): Promise<DiscoveryCacheEntry>;
+}
+/** Options for {@link MemoryDiscoveryCache}. */
+export interface MemoryDiscoveryCacheOptions {
+    /**
+     * How long an entry stays fresh, in ms. Defaults to
+     * {@link DEFAULT_DISCOVERY_TTL_MS}; `Infinity` never expires.
+     */
+    ttlMs?: number;
+    /**
+     * 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
+     * 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.
+ *
+ * Construct one per process (or per trust boundary) and hand it to every
+ * client that should share it.
+ *
+ * Because one document is handed to every client on that issuer, stored
+ * metadata is deep-frozen: a consumer that tries to patch a field it read
+ * throws rather than silently rewriting the entry every other client sees.
+ * Entries are evicted least-recently-used, so one issuer churning through the
+ * cache cannot evict a busier one.
+ *
+ * @example
+ * ```ts
+ * const discoveryCache = new MemoryDiscoveryCache();
+ *
+ * // Per request: a fresh client, but at most one discovery fetch per hour.
+ * const client = new DirectClient({
+ *   clientId,
+ *   clientSecret,
+ *   issuer: "https://sso.example",
+ *   discoveryCache,
+ * });
+ * ```
+ */
+export declare class MemoryDiscoveryCache implements DiscoveryCache {
+    #private;
+    /** Creates a cache with the given TTL and entry ceiling. */
+    constructor(options?: MemoryDiscoveryCacheOptions);
+    /**
+     * Returns the fresh cached entry for `issuer`, joins the in-flight `load`
+     * for it, or starts one. Trailing slashes on `issuer` are insignificant. A
+     * hit counts as a use, so a busy issuer outlives an idle one under
+     * {@link MemoryDiscoveryCacheOptions.maxEntries} pressure. The entry's
+     * `expiresAt` is when this cache would reload, so a reader holding it may
+     * skip the call until then.
+     */
+    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. */
+    clear(): void;
+}

package/esm/client/discovery-cache.js

@@ -0,0 +1,124 @@
+/**
+ * Discovery-metadata cache shared across `DirectClient` instances, for
+ * servers that build a short-lived client per request.
+ *
+ * @module
+ */
+/** Default entry lifetime for {@link MemoryDiscoveryCache}: one hour. */
+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.
+ *
+ * Construct one per process (or per trust boundary) and hand it to every
+ * client that should share it.
+ *
+ * Because one document is handed to every client on that issuer, stored
+ * metadata is deep-frozen: a consumer that tries to patch a field it read
+ * throws rather than silently rewriting the entry every other client sees.
+ * Entries are evicted least-recently-used, so one issuer churning through the
+ * cache cannot evict a busier one.
+ *
+ * @example
+ * ```ts
+ * const discoveryCache = new MemoryDiscoveryCache();
+ *
+ * // Per request: a fresh client, but at most one discovery fetch per hour.
+ * const client = new DirectClient({
+ *   clientId,
+ *   clientSecret,
+ *   issuer: "https://sso.example",
+ *   discoveryCache,
+ * });
+ * ```
+ */
+export class MemoryDiscoveryCache {
+    #ttlMs;
+    #maxEntries;
+    #entries = new Map();
+    #inFlight = new Map();
+    /** Creates a cache with the given TTL and entry ceiling. */
+    constructor(options = {}) {
+        this.#ttlMs = options.ttlMs ?? DEFAULT_DISCOVERY_TTL_MS;
+        this.#maxEntries = options.maxEntries ??
+            DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES;
+    }
+    /**
+     * Returns the fresh cached entry for `issuer`, joins the in-flight `load`
+     * for it, or starts one. Trailing slashes on `issuer` are insignificant. A
+     * hit counts as a use, so a busy issuer outlives an idle one under
+     * {@link MemoryDiscoveryCacheOptions.maxEntries} pressure. The entry's
+     * `expiresAt` is when this cache would reload, so a reader holding it may
+     * skip the call until then.
+     */
+    resolve(issuer, load) {
+        const key = normalizeIssuer(issuer);
+        const entry = this.#entries.get(key);
+        if (entry) {
+            if (entry.expiresAt > Date.now()) {
+                this.#entries.delete(key);
+                this.#entries.set(key, entry);
+                return Promise.resolve({ ...entry });
+            }
+            this.#entries.delete(key);
+        }
+        const pending = this.#inFlight.get(key);
+        if (pending)
+            return pending;
+        const promise = load().then((metadata) => this.#store(key, metadata));
+        this.#inFlight.set(key, promise);
+        const settle = () => {
+            if (this.#inFlight.get(key) === promise)
+                this.#inFlight.delete(key);
+        };
+        promise.then(settle, settle);
+        return promise;
+    }
+    /** Drops the entry for `issuer`, forcing the next resolve to re-fetch. */
+    delete(issuer) {
+        this.#entries.delete(normalizeIssuer(issuer));
+    }
+    /** Drops every entry. In-flight loads still settle for their callers. */
+    clear() {
+        this.#entries.clear();
+    }
+    #store(key, metadata) {
+        const entry = {
+            metadata: deepFreeze(metadata),
+            expiresAt: Date.now() + this.#ttlMs,
+        };
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        this.#prune();
+        return { ...entry };
+    }
+    #prune() {
+        const now = Date.now();
+        for (const [key, entry] of this.#entries) {
+            if (entry.expiresAt <= now)
+                this.#entries.delete(key);
+        }
+        while (this.#entries.size > this.#maxEntries) {
+            const leastRecentlyUsed = this.#entries.keys().next();
+            if (leastRecentlyUsed.done)
+                return;
+            this.#entries.delete(leastRecentlyUsed.value);
+        }
+    }
+}
+function normalizeIssuer(issuer) {
+    return issuer.replace(/\/+$/, "");
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const key of Object.getOwnPropertyNames(value)) {
+        deepFreeze(value[key]);
+    }
+    return value;
+}

package/esm/client/events.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Event types emitted by the OAuth2 clients.
+ *
+ * Framework adapters (React, Vue, etc.) subscribe to these to re-render on
+ * authentication state changes without having to poll the client for state.
+ *
+ * @module
+ */
+import type { TokenBundle } from "./storage.js";
+/** The authenticated user has been resolved or has changed. */
+export interface AuthenticatedEvent {
+    /** Discriminant tag for this event variant. */
+    type: "authenticated";
+    /** 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. */
+export interface LoggedOutEvent {
+    /** Discriminant tag for this event variant. */
+    type: "logged_out";
+    /** Why the session ended. */
+    reason: "user" | "refresh_failed" | "invalid_grant" | "session_expired";
+}
+/** A refresh has just completed; the access token has rotated. */
+export interface TokenRefreshedEvent {
+    /** Discriminant tag for this event variant. */
+    type: "token_refreshed";
+    /** The rotated token bundle now in effect. */
+    tokens: TokenBundle;
+}
+/** An operation failed. Subscribers can surface this to the user. */
+export interface ErrorEvent {
+    /** Discriminant tag for this event variant. */
+    type: "error";
+    /** The thrown value; an {@linkcode OAuth2Error} when the failure was protocol-level. */
+    error: unknown;
+}
+/** Every event type the client emits. */
+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. */
+export declare class EventBus {
+    #private;
+    /** Registers `listener` and returns a function that removes it. */
+    subscribe(listener: OAuth2ClientEventListener): () => void;
+    /**
+     * Delivers `event` to every subscriber. A listener that throws is isolated
+     * so delivery to the remaining subscribers still completes.
+     */
+    emit(event: OAuth2ClientEvent): void;
+    /** Removes all subscribers. */
+    clear(): void;
+}

package/esm/client/events.js

@@ -0,0 +1,37 @@
+/**
+ * Event types emitted by the OAuth2 clients.
+ *
+ * Framework adapters (React, Vue, etc.) subscribe to these to re-render on
+ * authentication state changes without having to poll the client for state.
+ *
+ * @module
+ */
+/** Minimal event bus for the client to avoid pulling in a dependency. */
+export class EventBus {
+    #listeners = new Set();
+    /** Registers `listener` and returns a function that removes it. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /**
+     * Delivers `event` to every subscriber. A listener that throws is isolated
+     * so delivery to the remaining subscribers still completes.
+     */
+    emit(event) {
+        for (const listener of this.#listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // One bad subscriber must not break delivery to others.
+            }
+        }
+    }
+    /** Removes all subscribers. */
+    clear() {
+        this.#listeners.clear();
+    }
+}

package/esm/client/mod.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OAuth2 clients for browsers, CLIs, servers, and framework adapters.
+ *
+ * Pick by who holds the tokens:
+ *
+ * - {@link BffClient} — a Backend-for-Frontend holds them. The browser only
+ *   talks to the BFF's `/auth/*` routes with the session cookie, and never
+ *   sees a token.
+ * - {@link DirectClient} — this process holds them. Drives the standard
+ *   grants (authorization code + PKCE, refresh, client credentials, device
+ *   authorization, introspection, revocation) against any RFC 6749-compliant
+ *   authorization server.
+ *
+ * Both extend {@link OAuth2ClientBase}, which is what code that shouldn't
+ * 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.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { type BaseLoginOptions, type BaseOptions, type LoginRedirect, type LogoutOptions, type LogoutRedirect, OAuth2ClientBase, type SessionState, SIGNED_OUT, type UserInfoClaims, } from "./base.js";
+export { BffClient, type BffClientOptions, type BffEndpoints, } from "./bff-client.js";
+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 { checkPermissions, type CheckPermissionsOptions, type CheckPermissionsResult, type CheckResource, } from "./check.js";
+export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
+export type { OrganizationContext } from "../models/authorization.js";
+export { isOAuth2Error, OAuth2Error } from "../errors.js";
+export { IndexedDBRefreshTokenStorage, type IndexedDBRefreshTokenStorageOptions, SessionStorageAuthRequestStorage, type SessionStorageAuthRequestStorageOptions, } from "./browser-storage.js";

package/esm/client/mod.js

@@ -0,0 +1,33 @@
+/**
+ * OAuth2 clients for browsers, CLIs, servers, and framework adapters.
+ *
+ * Pick by who holds the tokens:
+ *
+ * - {@link BffClient} — a Backend-for-Frontend holds them. The browser only
+ *   talks to the BFF's `/auth/*` routes with the session cookie, and never
+ *   sees a token.
+ * - {@link DirectClient} — this process holds them. Drives the standard
+ *   grants (authorization code + PKCE, refresh, client credentials, device
+ *   authorization, introspection, revocation) against any RFC 6749-compliant
+ *   authorization server.
+ *
+ * Both extend {@link OAuth2ClientBase}, which is what code that shouldn't
+ * 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.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { OAuth2ClientBase, SIGNED_OUT, } from "./base.js";
+export { BffClient, } from "./bff-client.js";
+export { DirectClient, } from "./direct-client.js";
+export { DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES, DEFAULT_DISCOVERY_TTL_MS, MemoryDiscoveryCache, } from "./discovery-cache.js";
+export { MemoryAuthRequestStorage, MemoryRefreshTokenStorage, MemoryTokenStorage, } from "./storage.js";
+export { checkPermissions, } from "./check.js";
+export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
+export { isOAuth2Error, OAuth2Error } from "../errors.js";
+export { IndexedDBRefreshTokenStorage, SessionStorageAuthRequestStorage, } from "./browser-storage.js";

package/esm/client/storage.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Storage interfaces used by `DirectClient`. A `BffClient` holds no
+ * 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),
+ * - 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.
+ *
+ * @module
+ */
+/** The set of fields the client persists as one logical unit. */
+export interface TokenBundle {
+    /** The current access token. */
+    accessToken: string;
+    /** When the access token expires (epoch ms). */
+    accessTokenExpiresAt?: number;
+    /** The scope granted to this token, space-delimited. */
+    scope?: string;
+    /** Token type — always "Bearer" in this client. */
+    tokenType: "Bearer";
+    /** Optional OIDC ID token string (not verified by the client). */
+    idToken?: string;
+}
+/** Persists the current token bundle (access token, expiry, scope, id_token). */
+export interface TokenStorage {
+    /** Returns the stored bundle, or `null` when none has been persisted. */
+    get(): Promise<TokenBundle | null> | TokenBundle | null;
+    /** Replaces the stored bundle with {@linkcode value}. */
+    set(value: TokenBundle): Promise<void> | void;
+    /** Discards the stored bundle. */
+    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.
+ */
+export interface RefreshTokenStorage {
+    /** Returns the stored refresh token, or `null` when none has been persisted. */
+    get(): Promise<string | null> | string | null;
+    /** Replaces the stored refresh token with {@linkcode value}. */
+    set(value: string): Promise<void> | void;
+    /** Discards the stored refresh token. */
+    clear(): Promise<void> | void;
+}
+/** Correlates an authorize redirect with its callback. */
+export interface AuthRequestRecord {
+    /** PKCE code verifier paired with the `code_challenge` sent to authorize. */
+    codeVerifier: string;
+    /** Application URL to navigate to after the callback completes. */
+    returnTo?: string;
+    /** Scope requested for this authorization, space-delimited. */
+    scope?: string;
+    /** When the request was created (epoch ms), used for TTL expiry. */
+    createdAt: number;
+}
+/**
+ * Short-lived map from the authorization request `state` parameter to the
+ * PKCE verifier / `returnTo` / scope it was built with. Must survive the
+ * authorize-redirect round-trip but must not outlive the tab, and must
+ * never contain access or refresh tokens.
+ */
+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.
+     */
+    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). */
+    delete(state: string): Promise<void> | void;
+    /** Removes every entry. Called on logout. */
+    clear(): Promise<void> | void;
+}
+/** Default in-memory {@link TokenStorage}. Data is lost when the process exits. */
+export declare class MemoryTokenStorage implements TokenStorage {
+    #private;
+    /** Returns the in-memory bundle, or `null` if none has been set. */
+    get(): TokenBundle | null;
+    /** Replaces the in-memory bundle with {@linkcode value}. */
+    set(value: TokenBundle): void;
+    /** Discards the in-memory bundle. */
+    clear(): void;
+}
+/**
+ * Default in-memory {@link RefreshTokenStorage}. Data is lost when the
+ * process exits.
+ */
+export declare class MemoryRefreshTokenStorage implements RefreshTokenStorage {
+    #private;
+    /** Returns the in-memory refresh token, or `null` if none has been set. */
+    get(): string | null;
+    /** Replaces the in-memory refresh token with {@linkcode value}. */
+    set(value: string): void;
+    /** Discards the in-memory refresh token. */
+    clear(): void;
+}
+/**
+ * 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.
+ */
+export declare class MemoryAuthRequestStorage implements AuthRequestStorage {
+    #private;
+    /** Returns the record for {@linkcode state}, or `null` if none is stored. */
+    get(state: string): AuthRequestRecord | null;
+    /** Stores {@linkcode value} under {@linkcode state}. */
+    set(state: string, value: AuthRequestRecord): void;
+    /** Removes the record for {@linkcode state}. */
+    delete(state: string): void;
+    /** Removes every stored record. */
+    clear(): void;
+}

package/esm/client/storage.js

@@ -0,0 +1,81 @@
+/**
+ * Storage interfaces used by `DirectClient`. A `BffClient` holds no
+ * 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),
+ * - 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.
+ *
+ * @module
+ */
+/** Default in-memory {@link TokenStorage}. Data is lost when the process exits. */
+export class MemoryTokenStorage {
+    #bundle = null;
+    /** Returns the in-memory bundle, or `null` if none has been set. */
+    get() {
+        return this.#bundle;
+    }
+    /** Replaces the in-memory bundle with {@linkcode value}. */
+    set(value) {
+        this.#bundle = value;
+    }
+    /** Discards the in-memory bundle. */
+    clear() {
+        this.#bundle = null;
+    }
+}
+/**
+ * Default in-memory {@link RefreshTokenStorage}. Data is lost when the
+ * process exits.
+ */
+export class MemoryRefreshTokenStorage {
+    #token = null;
+    /** Returns the in-memory refresh token, or `null` if none has been set. */
+    get() {
+        return this.#token;
+    }
+    /** Replaces the in-memory refresh token with {@linkcode value}. */
+    set(value) {
+        this.#token = value;
+    }
+    /** Discards the in-memory refresh token. */
+    clear() {
+        this.#token = null;
+    }
+}
+/**
+ * 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.
+ */
+export class MemoryAuthRequestStorage {
+    #records = new Map();
+    /** 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}. */
+    set(state, value) {
+        this.#records.set(state, value);
+    }
+    /** Removes the record for {@linkcode state}. */
+    delete(state) {
+        this.#records.delete(state);
+    }
+    /** Removes every stored record. */
+    clear() {
+        this.#records.clear();
+    }
+}

package/esm/deps/jsr.io/@std/assert/1.0.19/almost_equals.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Make an assertion that `actual` and `expected` are almost equal numbers
+ * through a given tolerance. It can be used to take into account IEEE-754
+ * double-precision floating-point representation limitations. If the values
+ * are not almost equal then throw.
+ *
+ * The default tolerance is one hundred thousandth of a percent of the
+ * expected value.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { assertAlmostEquals } from "@std/assert";
+ *
+ * assertAlmostEquals(0.01, 0.02); // Throws
+ * assertAlmostEquals(1e-8, 1e-9); // Throws
+ * assertAlmostEquals(1.000000001e-8, 1.000000002e-8); // Doesn't throw
+ * assertAlmostEquals(0.01, 0.02, 0.1); // Doesn't throw
+ * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-16); // Doesn't throw
+ * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-17); // Throws
+ * ```
+ *
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param tolerance The tolerance to consider the values almost equal. The
+ * default is one hundred thousandth of a percent of the expected value.
+ * @param msg The optional message to include in the error.
+ * @throws {AssertionError} If the values are not almost equal.
+ */
+export declare function assertAlmostEquals(actual: number, expected: number, tolerance?: number, msg?: string): void;