@web-ts-toolkit/oidc-vault-dpop-client 0.50.0 → 0.52.0

package/index.d.mts

@@ -1,26 +1,26 @@
-/**
- * Browser-only DPoP client (CLIENT-02 port of apps/oidc-vault-dpop-example/src/auth/*).
- * No `node:*` or `express` imports. Browser globals (crypto.subtle, indexedDB,
- * sessionStorage, navigator.locks, BroadcastChannel) only behind
- * assertDpopBrowserFeatures / lazy factory calls, never at module top-level.
- */
-
+/** Public-only P-256 JWK carried in proof headers. */
 interface PublicDpopJwk {
     kty: 'EC';
     crv: 'P-256';
     x: string;
     y: string;
 }
+/** Validated persistent signing key and its canonical RFC 7638 thumbprint. */
 interface DpopKey {
+    /** Non-extractable ES256 signing key; possession does not itself imply a live session. */
     readonly privateKey: CryptoKey;
     readonly publicJwk: Readonly<PublicDpopJwk>;
     readonly jkt: string;
     readonly scopeId: string;
 }
 
+/** Persistent key identity; use the same public origins/mount as the session and backend. */
 interface DpopKeyScope {
+    /** Browser location.origin, HTTPS or loopback HTTP. */
     frontendOrigin: string;
+    /** Public vault origin, HTTPS or loopback HTTP, with no path/query/fragment. */
     backendOrigin: string;
+    /** Absolute public mount; unreserved escapes, dot segments and trailing slashes normalize. */
     basePath: string;
 }
 
@@ -31,8 +31,9 @@ interface DpopKeyScope {
  * Call with the default `create=true` ONLY at fresh login (`session.login()`
  * does this for you). All credential-bearing operations use `create=false`,
  * so losing IndexedDB cannot silently rebind a login: a missing or changed
- * key throws `DPOP_KEY_LOST` and the caller must start a fresh login. There is
- * no ephemeral-key or Bearer fallback.
+ * key throws `DPOP_KEY_LOST` and the caller must start a fresh login. An
+ * unusable existing record needs explicit `session.resetKey()` before login;
+ * this helper never deletes or replaces it. No ephemeral-key or Bearer fallback.
  *
  * Candidate crypto work happens outside the readwrite transaction. IndexedDB
  * serializes the final read/add across tabs, making exactly one candidate win.
@@ -44,44 +45,39 @@ declare const getOrCreateDpopKey: (input: DpopKeyScope, options?: {
     create?: boolean;
 }) => Promise<DpopKey>;
 
+/** Inputs for one fresh ES256 request proof; the caller owns the HTTP request and retry policy. */
 interface DpopProofInput {
+    /** Exact uppercase HTTP method. */
     method: string;
+    /** Absolute HTTP(S) target. Proof normalization omits query/fragment and preserves reserved path escapes. */
     url: string | URL;
     /** API only. Vault login/exchange/refresh/logout present no access token. */
     accessToken?: string;
+    /** Optional server-issued value; reuse only within the trusted protection space and signing key. */
     nonce?: string;
+    /** Epoch-millisecond clock; default Date.now. Proof iat is integer epoch seconds. */
     now?: () => number;
+    /** Reject with signal.reason before/after hashing and while signing; already-started Web Crypto may still finish. */
+    signal?: AbortSignal;
 }
 /**
  * Mint a fresh DPoP proof for exactly one request attempt with the scoped key.
  *
  * Every invocation signs a new proof: exact uppercase `htm`, canonical absolute
- * `htu` without query/fragment (see `normalizeDpopTarget`), current integer
+ * `htu` without query/fragment, current integer
  * `iat`, fresh 128-bit random `jti`, API-only `ath`, and the optional server
  * `nonce`. The protected header is `{ typ: 'dpop+jwt', alg: 'ES256', jwk:
  * <public P-256 JWK> }`. Call again — with a new `jti`/`iat`/signature — for
  * every nonce or refresh retry; never reuse a proof across attempts.
+ * Unreserved path escapes and dot segments normalize; reserved escapes stay
+ * encoded. This helper signs only: it does not send HTTP or enforce API scopes.
  *
  * Canonical import: `import { createDpopProof } from
  * '@web-ts-toolkit/oidc-vault-dpop-client'` (named root import).
  */
 declare const createDpopProof: (key: DpopKey, input: DpopProofInput) => Promise<string>;
 
-/** DPoP proof algorithms, independent of the app-local access token's signing algorithm. */
-type OidcVaultDpopAlgorithm = 'ES256' | 'PS256' | 'RS256';
-/**
- * Immutable persisted sender constraint. `jkt` is the canonical RFC 7638
- * SHA-256 JWK thumbprint (43 base64url characters). Store no JWK, private key,
- * proof algorithm, or historical enforcement mode in this record.
- */
-interface OidcVaultDpopBinding {
-    type: 'dpop';
-    jkt: string;
-}
-/** Verified request context; `alg` is checked against the current proof policy. */
-interface OidcVaultVerifiedDpopBinding extends OidcVaultDpopBinding {
-    alg: OidcVaultDpopAlgorithm;
-}
+/** Public JSON profile returned by exchange/refresh. */
 interface OidcVaultUserProfile {
     sub: string;
     email?: string;
@@ -89,46 +85,23 @@ interface OidcVaultUserProfile {
     preferredUsername?: string;
     [key: string]: unknown;
 }
-interface OidcVaultAccessTokenValidationResult {
-    subject: string;
-    sessionId?: string;
-    scope?: string;
-    claims?: Record<string, unknown>;
-    /** Verified sender constraint. Legacy adapters may omit it only for genuinely unbound credentials. */
-    confirmation?: OidcVaultAccessTokenConfirmation | null;
-}
-/** Canonical RFC 7638 SHA-256 thumbprint derived from verified token/introspection data, never from a proof alone. */
-interface OidcVaultAccessTokenConfirmation {
-    jkt: string;
-}
-interface OidcVaultAuthContext extends OidcVaultAccessTokenValidationResult {
-    token: string;
-    /** Present only after original-key proof, API ath, nonce and shared replay admission all pass. */
-    deviceBinding?: Readonly<OidcVaultVerifiedDpopBinding>;
-}
-declare module 'express-serve-static-core' {
-    interface Request {
-        auth?: OidcVaultAuthContext;
-    }
-}
+/** Vault handle transport; independent of DPoP mode. Default: body. */
 type OidcVaultSessionTransport = 'body' | 'cookie';
 
+/** Contract-checked browser credential. Decoding does not authenticate the JWT; the API must verify it. */
 interface DpopAccessToken {
     readonly accessToken: string;
     readonly tokenType: 'DPoP';
+    /** Safe epoch milliseconds, capped by JWT exp and response/peer lifetime. May already be expired (e.g. expiresIn: 0); check before reuse. */
     readonly expiresAt: number;
+    /** Exact canonical RFC 7638 SHA-256 thumbprint from the one-field cnf object, matching the persistent browser key. */
     readonly jkt: string;
+    /** Opaque response generation for cookie-peer coordination, not a server session handle. */
     readonly generation: string;
     readonly user?: OidcVaultUserProfile;
 }
 
-/**
- * Browser-only DPoP client (CLIENT-02 port of apps/oidc-vault-dpop-example/src/auth/*).
- * No `node:*` or `express` imports. Browser globals (crypto.subtle, indexedDB,
- * sessionStorage, navigator.locks, BroadcastChannel) only behind
- * assertDpopBrowserFeatures / lazy factory calls, never at module top-level.
- */
-/** Copyable private example helper. Recognition is NOT proof of possession or an API sender constraint. */
+/** Current opt-in recognition signal source. Recognition is not proof of possession or an API sender constraint. */
 type DeviceFingerprintSignalSource = () => Promise<string | undefined>;
 interface DeviceFingerprintOptions {
     /** Must match the backend's fingerprintRecognition.headerName; default X-Device-Fingerprint. */
@@ -161,30 +134,88 @@ interface FingerprintJsAgent {
  */
 declare const fingerprintJsSignalSource: (load: () => Promise<FingerprintJsAgent>) => DeviceFingerprintSignalSource;
 
+/** Configuration for one browser context and public vault mount. */
 interface OidcVaultDpopSessionOptions {
+    /** Pinned public scheme/host/port, HTTPS or loopback HTTP; no path/query/fragment. */
     backendOrigin: string;
+    /** Exact public vault mount; default /auth/oidc. Trailing slashes normalize away. */
     basePath?: string;
+    /** Default body (tab-local handle). Cookie additionally requires Web Locks and BroadcastChannel. */
     sessionTransport?: OidcVaultSessionTransport;
     /** Current signal on login/exchange/refresh only; optional recognition, never PoP. */
     fingerprint?: DeviceFingerprint;
+    /**
+     * Per-attempt vault HTTP deadline in milliseconds, including headers, streamed
+     * body and JSON parsing. Default 15,000; integer 1..2,147,483,647. Starts at
+     * fetch, not queue/key/proof work. Timeout never automatically retries a mutation.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum actual vault response bytes read from the decoded HTTP body stream,
+     * independent of Content-Length. Default 1,048,576 (1 MiB); positive safe integer.
+     */
+    maxResponseBytes?: number;
+    /** Default global fetch. Injected responses must expose a standard streaming body. */
     fetch?: typeof globalThis.fetch;
+    /** Login redirect after authoritative initiation; default location.assign. */
     navigate?: (authorizationUrl: string) => void;
+    /** Epoch-millisecond clock; default Date.now. Credential deadline arithmetic must remain safe. */
     now?: () => number;
 }
+/** One tab's session. Both transports serialize lifecycle mutations; access JWTs stay in memory. */
 interface OidcVaultDpopSession {
+    /** Opaque persistent-key scope for this frontend origin, backend origin and normalized mount. */
     readonly scopeId: string;
     readonly sessionTransport: OidcVaultSessionTransport;
+    /** FIFO with exchange/refresh/logout. Clears frontend auth, creates a missing key and navigates after POST initiation. */
     login(returnTo?: string): Promise<void>;
+    /** FIFO. Exchanges the one-time callback code using the initiating key and temporary cookie. */
     exchange(code: string): Promise<DpopAccessToken>;
-    /** Single-flight; no Authorization/ath even if the old JWT expired. */
+    /**
+     * Same Promise for concurrent callers until login/exchange/logout/clear/resetKey
+     * intervenes; the first caller's rejectedToken owns that batch. FIFO with
+     * other lifecycle mutations. No Authorization/ath, even with an expired JWT.
+     */
     refresh(options?: {
         rejectedToken?: string;
     }): Promise<DpopAccessToken>;
+    /** FIFO: an earlier refresh publishes its rotated handle before logout uses it. Revokes server refresh state. */
     logout(): Promise<void>;
+    /** Memory snapshot only; may already be expired, including a valid expiresIn: 0 response. */
     getAccessToken(): DpopAccessToken | undefined;
-    /** Existing key only. Missing/changed persistence clears auth and requires login. */
+    /**
+     * Existing-key read alongside the lifecycle FIFO. A still-current
+     * missing/changed key clears auth; superseded reads cannot clear a newer
+     * login. Absence of credentials preserves an in-progress login marker.
+     */
     getKey(): Promise<DpopKey>;
+    /**
+     * Immediately invalidates local work/auth and pending login. Cookie mode
+     * resolves after inactive metadata/peer notification under the shared lock,
+     * which can wait for other lock owners. Aborts this context's vault HTTP.
+     * Keeps the key; no server logout.
+     */
     clear(): Promise<void>;
+    /**
+     * Explicit local key recovery, including corrupt/mismatched persisted keys.
+     * Immediately invalidates local auth/pending login and aborts owned vault HTTP;
+     * then atomically deletes only this scope's key AND cookie-session metadata,
+     * under the shared lock in cookie mode. Repeating on absent records is harmless;
+     * concurrent resets share removal until another lifecycle mutation intervenes.
+     * Await completion before login() creates a new non-extractable key through
+     * atomic first-key-wins. Never creates a key, calls the backend, removes an
+     * HttpOnly cookie, or revokes server sessions/JWTs. Other sessions using the old
+     * key need fresh login; old server sessions remain until revocation/expiry.
+     * Already-started API/crypto work and retained key references cannot be undone.
+     * Storage/other lock owners may delay completion. Disposed contexts reject.
+     */
+    resetKey(): Promise<void>;
+    /**
+     * Closes this context and peer waits immediately, preserving committed
+     * handles/key/metadata and pending login for reload. Aborts owned vault HTTP;
+     * does not log out, cancel caller-owned API requests, or undo server mutations.
+     * Await clear()/resetKey() first if their persistence work must finish. Later calls reject.
+     */
     dispose(): void;
 }
 /**
@@ -193,72 +224,142 @@ interface OidcVaultDpopSession {
  * '@web-ts-toolkit/oidc-vault-dpop-client'` (named root import, no default export).
  * Lifecycle: `login` → `exchange(code)` → `getAccessToken`/`fetchWithDpop` →
  * `refresh` → `logout`. Cookie transport additionally needs Web Locks +
- * `BroadcastChannel` at runtime (see `assertDpopBrowserFeatures`).
- * Copyable app helper. It is not an export of the Express package.
+ * `BroadcastChannel` at runtime, in addition to secure-context Web Crypto,
+ * sessionStorage and IndexedDB CryptoKey persistence.
+ * Mutating calls are ordered per instance in both transports; cookie mutations
+ * also hold the same-origin/scope Web Lock. clear/resetKey/dispose invalidate entry-time
+ * authority immediately. Superseded work rejects with non-terminal
+ * DPOP_OPERATION_SUPERSEDED (or DPOP_SESSION_DISPOSED after disposal).
+ * Vault HTTP has a per-attempt deadline/byte bound and aborts on invalidation.
+ * Valid response nonces are learned for this vault/key, including on success.
+ * Vault nonce challenges permit one retry with a fresh proof; a second yields
+ * non-terminal DPOP_NONCE_RETRY_EXHAUSTED. Only explicit terminal session,
+ * browser/device-binding or recognition errors clear auth, not generic 401s.
+ * Peer coordination failures are advisory and cannot clear auth. A new login
+ * intent supersedes older peer callbacks even while queued; validated current-key
+ * failures and explicit terminal operations retain their own failure cleanup.
+ * A lost response leaves server commit/cookie application uncertain: local
+ * cancellation cannot roll it back or coordinate across frontend origins.
  */
 declare const createOidcVaultDpopSession: (options: OidcVaultDpopSessionOptions) => OidcVaultDpopSession;
 
 /**
- * Browser-only DPoP client (CLIENT-02 port of apps/oidc-vault-dpop-example/src/auth/*).
- * No `node:*` or `express` imports. Browser globals (crypto.subtle, indexedDB,
- * sessionStorage, navigator.locks, BroadcastChannel) only behind
- * assertDpopBrowserFeatures / lazy factory calls, never at module top-level.
+ * In-memory opaque nonces, isolated by the caller's trusted protection space and
+ * signing-key thumbprint. At most 64 tuples: a successful remember renews write
+ * order; insertion at capacity evicts the oldest remembered tuple. Reads do not
+ * promote entries. No TTL or server-specific nonce decoding is performed.
  */
 declare class DpopNonceCache {
     private readonly nonces;
     get(space: string, jkt: string): string | undefined;
+    /**
+     * Accept one 1..512-character visible-ASCII value, excluding whitespace,
+     * double quotes, backslashes and commas (including coalesced duplicate header
+     * values). Invalid input returns false without overwriting or changing order.
+     */
     remember(space: string, jkt: string, nonce: string | null): boolean;
+    /** Forget every tuple in this cache; does not invalidate credentials or server nonce state. */
     clear(): void;
 }
 
 /**
- * Browser-only DPoP client (CLIENT-02 port of apps/oidc-vault-dpop-example/src/auth/*).
- * No `node:*` or `express` imports. Browser globals (crypto.subtle, indexedDB,
- * sessionStorage, navigator.locks, BroadcastChannel) only behind
- * assertDpopBrowserFeatures / lazy factory calls, never at module top-level.
+ * Credential/nonce policy for a public API subtree, selected by `fetchWithDpop`.
+ * @example
+ * const apis: DpopApi[] = [
+ *   { origin: 'https://gateway.example.com', pathPrefix: '/orders', replayNamespace: 'orders-api' },
+ *   { origin: 'https://gateway.example.com', pathPrefix: '/billing', replayNamespace: 'billing-api' },
+ * ];
  */
-
 interface DpopApi {
-    /** Exact origin receiving the proof/Authorization. No wildcard or redirects. */
+    /**
+     * Exact public scheme/host/port receiving auth, with an optional root slash.
+     * HTTPS or loopback HTTP; no path, query, fragment, wildcard or redirects.
+     */
     origin: string;
-    /** Backend API replayNamespace (the nonce protection space), not a route. */
+    /**
+     * Absolute path subtree. Omission or `/` permits the entire origin. Matches
+     * segment boundaries (`/orders` or `/orders/...`, never `/orders-evil`);
+     * the longest normalized matching prefix wins, independent of array order.
+     * Trailing slashes are removed; unreserved percent escapes and dot segments
+     * normalize as in the proof/outbound path. A prefix normalizing to `/` is
+     * origin-wide too. Reserved escapes remain encoded.
+     * No URL, `//` authority-like prefix, query, fragment, whitespace, backslash,
+     * or malformed escape. Duplicate normalized origin/path scopes are rejected,
+     * even if their namespace/credential policies are identical.
+     */
+    pathPrefix?: string;
+    /**
+     * Backend API replayNamespace: 1–128 printable ASCII characters. Nonces use
+     * the selected `['api', normalizedOrigin, replayNamespace]` plus signing jkt;
+     * paths with the same origin/namespace intentionally share that nonce space.
+     */
     replayNamespace: string;
-    /** Usually omit for JWT APIs; include only for an explicitly cookie-using API. */
+    /** Default `omit`. Use `include` only for a cookie-using API. Snapshotted before auth awaits. */
     credentials?: 'omit' | 'include';
 }
 interface DpopFetchContext {
     session: OidcVaultDpopSession;
+    /** All scopes are validated on each invocation, including entries that do not match its target. */
     apis: readonly DpopApi[];
     fetch?: typeof globalThis.fetch;
+    /** Optional shared cache; each instance holds at most 64 protection-space/key tuples. */
     nonces?: DpopNonceCache;
     now?: () => number;
 }
 interface DpopFetchOptions extends Omit<RequestInit, 'redirect' | 'credentials'> {
+    /**
+     * Abort this caller's wait before/through auth, proof and HTTP work. Pre-aborted
+     * calls do no auth work. Shared refresh/key work continues for other waiters;
+     * already-started Web Crypto/server mutations cannot be undone.
+     */
+    signal?: AbortSignal | null;
     /**
      * GET/HEAD/OPTIONS may retry. All other methods default to one attempt.
      * Explicitly authorize idempotent retries only for a server operation whose
      * contract supports them (e.g. PUT or POST with a server idempotency key).
+     * Nonce learning still occurs on single-attempt and success responses, so a
+     * later explicit invocation can use the nonce without resubmitting this call.
      */
     retry?: 'never' | 'idempotent';
 }
 /**
- * Scoped DPoP `fetch` for one configured API origin: mints a fresh proof per
- * attempt, sends `Authorization: DPoP`, then retries once on a DPoP nonce
- * challenge and at most once via `session.refresh()` on `invalid_token`.
+ * Scoped DPoP `fetch` for a configured API origin/path: mints a fresh proof per
+ * attempt and sends `Authorization: DPoP`. When the retry policy permits it,
+ * retries once on a DPoP nonce challenge and at most once via `session.refresh()`
+ * on `invalid_token`. Learns valid response nonces even on single-attempt,
+ * success and final challenge responses, isolated by protection space/key.
+ * Only an unambiguous HTTP-401 DPoP challenge authorizes recovery; parameter
+ * order is flexible, but malformed/duplicate challenges and fields over 8,192
+ * characters do not trigger retries. Final API responses belong to the caller.
  * Canonical import: `import { fetchWithDpop } from
- * '@web-ts-toolkit/oidc-vault-dpop-client'` (named root import). Only origins
- * listed in `context.apis` are called; authentication headers are owned by the
- * helper and must not be set by callers.
+ * '@web-ts-toolkit/oidc-vault-dpop-client'` (named root import). Selects the
+ * longest normalized segment-prefix match in `context.apis`; omission/root is
+ * origin-wide. Validates all scopes and snapshots the target and selected
+ * origin/path/namespace/credentials before auth awaits. A missing match rejects
+ * with DPOP_API_OUT_OF_SCOPE before credential/key/refresh/network work. Bad
+ * policies or duplicate normalized scopes reject with INVALID_DPOP_API_CONFIG;
+ * malformed paths/origins retain INVALID_DPOP_TARGET / INSECURE_DPOP_ORIGIN.
+ * All are non-terminal. Authentication headers are owned by the helper.
+ * Outbound path normalization matches the proof: unreserved escapes and dot
+ * segments normalize, reserved escapes stay encoded, and query/fragment data
+ * is preserved for fetch (HTTP omits fragments). Neither enters the proof.
+ * The uppercase method is the same on the proof and every outbound attempt.
+ * A nonlive deadline (including an expiresIn: 0 refresh result) stops the
+ * attempt with DPOP_ACCESS_TOKEN_EXPIRED, requiresLogin: false. The rotated
+ * session handle is retained; no additional refresh loop is started.
+ * Caller cancellation rejects with signal.reason, including while waiting on
+ * shared refresh/key work, without cancelling that shared work. Discarded retry
+ * responses are cancelled best effort; cleanup never delays or replaces a result.
  */
 declare const fetchWithDpop: (context: DpopFetchContext, input: string | URL, options?: DpopFetchOptions) => Promise<Response>;
 
 /**
- * Browser-only DPoP client (CLIENT-02 port of apps/oidc-vault-dpop-example/src/auth/*).
- * No `node:*` or `express` imports. Browser globals (crypto.subtle, indexedDB,
- * sessionStorage, navigator.locks, BroadcastChannel) only behind
- * assertDpopBrowserFeatures / lazy factory calls, never at module top-level.
+ * Built-in failures use fixed codes/messages, never server text or credentials.
+ * requiresLogin identifies terminal session/binding/recognition or local key
+ * failures, not every HTTP 401. Non-terminal errors retain auth and do not by
+ * themselves authorize an automatic retry. Unknown vault codes are sanitized to
+ * OIDC_REQUEST_FAILED with requiresLogin: false; status remains available.
  */
-/** Fixed local failures; never include keys, credentials, fingerprints or URLs. */
 declare class OidcVaultDpopClientError extends Error {
     readonly code: string;
     readonly requiresLogin: boolean;