@udibo/oauth2 0.4.0 → 0.5.0

package/esm/server/redirect-uri.d.ts

@@ -149,15 +149,12 @@ export declare function checkRedirectUriPattern(pattern: string, isPublicSuffix?
  * - A host label may never be empty, and a single trailing dot is treated as
  *   the same host, so `example.com.` cannot smuggle an extra label past the
  *   parent-domain rule.
- * - A requested URI containing `*` never matches anything, checked both on the
- *   raw string and on the percent-decoded host, so a pattern can never be
- *   replayed back as a literal redirect target.
- *
- * That last rule is a deliberate tightening: `*` is a legal host character, so
- * a registration containing one that was previously matched by exact string
- * comparison no longer matches at all. Such a registration cannot be created
- * any more — a `*` now makes the value a pattern, which must satisfy the rules
- * above — so this only affects rows written before patterns existed.
+ * - A requested URI containing a literal `*` never matches any registration,
+ *   so a pattern can never be replayed back as a redirect target. A requested
+ *   host that percent-decodes to one containing `*` never matches a pattern.
+ *
+ * Any registration containing `*` is a pattern, so a stored literal URI with a
+ * `*` in its host matches only if it also satisfies the pattern rules.
  *
  * @param registered The client's registered redirect URIs.
  * @param redirectUri The `redirect_uri` from the authorization request.

package/esm/server/redirect-uri.js

@@ -38,27 +38,8 @@
  *
  * @module
  */
-/**
- * A label used to ask whether the *children* of a parent domain are public
- * suffixes, which is a different question from whether the parent is one.
- *
- * `r.appspot.com` is a registrable domain by the list's reckoning, but the rule
- * `*.r.appspot.com` makes every one of its subdomains a public suffix belonging
- * to a different registrant — so a wildcard over it hands codes to strangers
- * even though the parent itself passes. Probing with a label no registry has
- * ever issued answers that in one lookup.
- */
+// A label no registry issues; a PSL hit on it catches `*.r.appspot.com` rules.
 const CHILD_PROBE_LABEL = "udibo-public-suffix-probe";
-/**
- * Split a hostname into labels, or `null` when it is not usable for matching.
- *
- * A single trailing dot is the DNS root and is dropped, so `example.com.` and
- * `example.com` are the same host — without this, the extra empty label would
- * shift every label the public-suffix check looks at and let `*.deno.net.`
- * through. Any *other* empty label (`a..b`, a leading `.`) is refused outright
- * rather than normalized: it cannot resolve, and an empty leftmost label would
- * otherwise satisfy any prefix/suffix test.
- */
 function hostLabels(hostname) {
     const normalized = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
     if (normalized.length === 0)
@@ -175,12 +156,7 @@ export function checkRedirectUriPattern(pattern, isPublicSuffix) {
     }
     return null;
 }
-/**
- * The loopback IP literals RFC 8252 §7.3 covers, in the form
- * `URL.hostname` normalizes them to. `localhost` is deliberately absent: RFC
- * 8252 §8.3 advises against it because its resolution depends on a host file
- * the authorization server does not control.
- */
+// RFC 8252 §7.3 IP literals only; `localhost` is excluded per RFC 8252 §8.3.
 const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "[::1]"]);
 function matchesLoopback(registration, redirectUri) {
     if (isRedirectUriPattern(registration))
@@ -275,15 +251,12 @@ function matchesPattern(pattern, redirectUri, isPublicSuffix) {
  * - A host label may never be empty, and a single trailing dot is treated as
  *   the same host, so `example.com.` cannot smuggle an extra label past the
  *   parent-domain rule.
- * - A requested URI containing `*` never matches anything, checked both on the
- *   raw string and on the percent-decoded host, so a pattern can never be
- *   replayed back as a literal redirect target.
+ * - A requested URI containing a literal `*` never matches any registration,
+ *   so a pattern can never be replayed back as a redirect target. A requested
+ *   host that percent-decodes to one containing `*` never matches a pattern.
  *
- * That last rule is a deliberate tightening: `*` is a legal host character, so
- * a registration containing one that was previously matched by exact string
- * comparison no longer matches at all. Such a registration cannot be created
- * any more — a `*` now makes the value a pattern, which must satisfy the rules
- * above — so this only affects rows written before patterns existed.
+ * Any registration containing `*` is a pattern, so a stored literal URI with a
+ * `*` in its host matches only if it also satisfies the pattern rules.
  *
  * @param registered The client's registered redirect URIs.
  * @param redirectUri The `redirect_uri` from the authorization request.

package/esm/server/resource-server.d.ts

@@ -231,10 +231,12 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
      *
      * The token's expiry is compared against now with {@linkcode
      * clockSkewSeconds} of leeway, so the same tolerance applies whichever
-     * token reader produced the token.
+     * token reader produced the token. A token without `accessTokenExpiresAt`
+     * is never refused as expired here. Revocation is the reader's to report,
+     * by resolving no token.
      *
-     * @throws {InvalidTokenError} If the token is invalid, expired beyond the
-     *   configured leeway, or revoked
+     * @throws {InvalidTokenError} If the reader resolves no token, or the token
+     *   has expired beyond the configured leeway
      * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
      */
     getToken(accessToken: string, services: ResourceServerServices<Client, User, S>): Promise<Token<Client, User, S>>;

package/esm/server/resource-server.js

@@ -258,10 +258,12 @@ export class ResourceServer {
      *
      * The token's expiry is compared against now with {@linkcode
      * clockSkewSeconds} of leeway, so the same tolerance applies whichever
-     * token reader produced the token.
+     * token reader produced the token. A token without `accessTokenExpiresAt`
+     * is never refused as expired here. Revocation is the reader's to report,
+     * by resolving no token.
      *
-     * @throws {InvalidTokenError} If the token is invalid, expired beyond the
-     *   configured leeway, or revoked
+     * @throws {InvalidTokenError} If the reader resolves no token, or the token
+     *   has expired beyond the configured leeway
      * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
      */
     async getToken(accessToken, services) {

package/esm/server/services/client.d.ts

@@ -30,6 +30,10 @@ export interface ClientServiceInterface<Client extends ClientInterface, User> {
      * carried none.
      */
     getAuthenticated(id: string, secret?: string): Promise<Client | undefined>;
-    /** Retrieves a user associated with a client (for client-credentials grant). */
+    /**
+     * Resolves the user a client-credentials token acts for. Resolving
+     * `undefined` is the conformant case and yields a user-less machine token;
+     * see `ClientCredentialsGrant` before mapping a client to a human user.
+     */
     getUser(client: Client | string): Promise<User | undefined>;
 }

package/esm/server/services/device-authorization.d.ts

@@ -34,15 +34,15 @@ import type { AbstractScope } from "../../models/scope.js";
  */
 export interface DeviceAuthorizationServiceInterface<Client extends ClientInterface, User, Scope extends AbstractScope> {
     /**
-     * Lifetime of device codes in seconds.
-     * RFC 8628 does not specify a default, but 15-30 minutes is common.
-     * @default 1800 (30 minutes)
+     * Lifetime of device codes in seconds. RFC 8628 sets no default; 15–30
+     * minutes is common.
      */
     lifetime: number;
     /**
-     * Minimum polling interval in seconds.
-     * Clients should not poll more frequently than this.
-     * @default 5
+     * Minimum polling interval in seconds, copied onto each new authorization
+     * and returned to the device as `interval`. The grant answers a faster poll
+     * with `slow_down` and adds 5 seconds to that authorization's interval
+     * (RFC 8628 §3.5).
      */
     interval: number;
     /**

package/esm/server/services/token.d.ts

@@ -24,9 +24,10 @@ export interface TokenReaderInterface<Client extends ClientInterface, User, Scop
  * its grant types.
  *
  * **A token need not have a user.** The client credentials grant (RFC 6749
- * §4.4) has no resource owner, so it calls `acceptedScope`,
- * `generateAccessToken`, and `accessTokenExpiresAt` with `user: undefined` and
- * saves a {@linkcode Token} whose `user` is unset. An implementation that
+ * §4.4) has no resource owner, so when `ClientServiceInterface.getUser`
+ * resolves none it calls `acceptedScope`, `generateAccessToken`, and
+ * `accessTokenExpiresAt` with `user: undefined` and saves a {@linkcode Token}
+ * whose `user` is unset. An implementation that
  * dereferences `user` without checking will throw on those requests, and a
  * store with a non-nullable user column cannot persist the result — decide
  * scope and lifetime from the client alone when it is absent.
@@ -53,8 +54,13 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * generator names the client as the subject then, per RFC 9068 §2.2.
      * Forward `authenticationContext` to a signed-token generator so it uses
      * the credential's event, including the original event on refresh.
+     * `expiresAt` is the expiry the grant will store for this token — already
+     * clamped to the refresh family's cap when one applies. Forward it too, so
+     * a signed token's `exp` never outlives what the server itself honors; the
+     * grants always pass it, and a wrapper that drops it leaves offline
+     * verifiers accepting the token past its stored expiry.
      */
-    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext): Promise<string>;
+    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext, expiresAt?: Date): Promise<string>;
     /** Generates a refresh token string. */
     generateRefreshToken(client: Client, user: User, scope?: Scope | null): Promise<string | undefined>;
     /**
@@ -71,7 +77,8 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      *
      * **This method is the whole cap.** The grants clamp a rotation's access and
      * refresh expiries to the date it returns and answer `invalid_grant` once
-     * that date has passed. Return `undefined` — or leave the method off
+     * that date has passed; a refresh-token record without `familyCreatedAt` is
+     * never capped. Return `undefined` — or leave the method off
      * entirely, which is the default — and the family is never capped, however
      * the service is otherwise configured. Implement it to cap per client (see
      * {@linkcode AbstractTokenService.refreshTokenMaxLifetime} for the
@@ -151,8 +158,8 @@ export interface AbstractTokenServiceOptions<Client extends ClientInterface, Use
     /**
      * Absolute lifetime of a refresh-token family in seconds, read by this
      * class's {@linkcode AbstractTokenService.refreshTokenFamilyExpiresAt}. Omit
-     * for the historical behavior, an uncapped sliding window. Must be at least
-     * `refreshTokenLifetime`.
+     * to leave families uncapped, so rotation extends a family indefinitely.
+     * Must be at least `refreshTokenLifetime`.
      */
     refreshTokenMaxLifetime?: number;
     /** Client service for hydrating tokens. */
@@ -202,7 +209,7 @@ export declare abstract class AbstractTokenService<Client extends ClientInterfac
      */
     acceptedScope(_client: Client, _user: User | undefined, scope?: Scope | null): Promise<Scope | null | undefined | false>;
     /** Generates an opaque access token string. Override to issue a different format. */
-    generateAccessToken(_client: Client, _user: User | undefined, _scope?: Scope | null, _authenticationContext?: AuthenticationContext): Promise<string>;
+    generateAccessToken(_client: Client, _user: User | undefined, _scope?: Scope | null, _authenticationContext?: AuthenticationContext, _expiresAt?: Date): Promise<string>;
     /** Generates an opaque refresh token string. Override to issue a different format. */
     generateRefreshToken(_client: Client, _user: User, _scope?: Scope | null): Promise<string | undefined>;
     /** Computes the access token expiry as now plus {@linkcode accessTokenLifetime}. */

package/esm/server/services/token.js

@@ -52,7 +52,7 @@ export class AbstractTokenService {
         return Promise.resolve(scope);
     }
     /** Generates an opaque access token string. Override to issue a different format. */
-    generateAccessToken(_client, _user, _scope, _authenticationContext) {
+    generateAccessToken(_client, _user, _scope, _authenticationContext, _expiresAt) {
         return Promise.resolve(crypto.randomUUID());
     }
     /** Generates an opaque refresh token string. Override to issue a different format. */

package/esm/server/signing-keys.d.ts

@@ -115,7 +115,11 @@ export declare function generateSigningKey(): Promise<SigningKey>;
 export declare function exportSigningKeyJwk(key: SigningKey): Promise<JsonWebKey & {
     kid: string;
 }>;
-/** Import a signing key previously exported with {@link exportSigningKeyJwk}. */
+/**
+ * Import a signing key previously exported with {@link exportSigningKeyJwk}.
+ * A JWK without a `kid` is given a random one, so every instance importing it
+ * would publish and stamp a different `kid` — persist the exported `kid`.
+ */
 export declare function importSigningKeyJwk(jwk: JsonWebKey & {
     kid?: string;
 }): Promise<SigningKey>;
@@ -139,10 +143,12 @@ export interface VerifyJwtOptions {
 }
 /**
  * Verify a compact JWS against a public JWK and return its payload, or
- * `undefined` when the signature (or shape) is invalid or the payload's `exp`
- * is in the past. Exported for tests and lightweight in-process verification;
- * production resource servers should verify against the JWKS endpoint with
- * their JOSE library of choice.
+ * `undefined` when the signature (or shape) is invalid or a numeric `exp` is
+ * not in the future. It verifies ES256 regardless of the header's `alg` and
+ * checks nothing else: a payload with no `exp` passes, and `iss`, `aud`, and
+ * `nbf` are the caller's to check. Exported for tests and lightweight
+ * in-process verification; production resource servers should verify against
+ * the JWKS endpoint with their JOSE library of choice.
  */
 export declare function verifyJwt(jwt: string, publicJwk: JsonWebKey, options?: VerifyJwtOptions): Promise<Record<string, unknown> | undefined>;
 /**
@@ -159,8 +165,10 @@ export declare function verifyJwt(jwt: string, publicJwk: JsonWebKey, options?:
  * }
  * ```
  *
- * The token store still persists the (hashed) JWT string, so revocation and
- * introspection keep working exactly as with opaque tokens.
+ * Your token store persists the JWT string like any access token, so
+ * revocation and introspection work as with opaque tokens for readers that
+ * consult the store. A resource server that verifies the JWT offline against
+ * JWKS does not see a revocation and accepts the token until its `exp`.
  */
 export declare function createJwtAccessTokenGenerator(options: {
     /** Keys the tokens are signed with (also served from JWKS). */
@@ -173,7 +181,14 @@ export declare function createJwtAccessTokenGenerator(options: {
      * the client id, which single-resource validators must then accept.
      */
     audience?: string;
-    /** Token lifetime in seconds for the `exp` claim. Defaults to 3600. */
+    /**
+     * Upper bound in seconds on the `exp` claim. Defaults to 3600. The claim
+     * is the earlier of this and the expiry the grant passes as the fifth
+     * argument — the token service's `accessTokenExpiresAt`, already clamped to
+     * any refresh-family cap — so an offline verifier never accepts the token
+     * past the server's own expiry. A wrapper that drops that argument falls
+     * back to this lifetime alone.
+     */
     lifetimeSeconds?: number;
     /** Maps a user to the `sub` claim. Defaults to the user's `id` property. */
     subjectOf?: (user: unknown) => string;
@@ -198,4 +213,4 @@ export declare function createJwtAccessTokenGenerator(options: {
     id: string;
 }, user: unknown, scope?: {
     toString(): string;
-} | null, authenticationContext?: AuthenticationContext) => Promise<string>;
+} | null, authenticationContext?: AuthenticationContext, expiresAt?: Date) => Promise<string>;

package/esm/server/signing-keys.js

@@ -128,7 +128,11 @@ export async function exportSigningKeyJwk(key) {
     const jwk = await crypto.subtle.exportKey("jwk", key.privateKey);
     return { ...jwk, kid: key.kid, alg: key.alg };
 }
-/** Import a signing key previously exported with {@link exportSigningKeyJwk}. */
+/**
+ * Import a signing key previously exported with {@link exportSigningKeyJwk}.
+ * A JWK without a `kid` is given a random one, so every instance importing it
+ * would publish and stamp a different `kid` — persist the exported `kid`.
+ */
 export async function importSigningKeyJwk(jwk) {
     const privateKey = await crypto.subtle.importKey("jwk", jwk, ES256_PARAMS, true, ["sign"]);
     const kid = jwk.kid ?? crypto.randomUUID();
@@ -150,10 +154,12 @@ export async function signJwt(key, payload, header = {}) {
 }
 /**
  * Verify a compact JWS against a public JWK and return its payload, or
- * `undefined` when the signature (or shape) is invalid or the payload's `exp`
- * is in the past. Exported for tests and lightweight in-process verification;
- * production resource servers should verify against the JWKS endpoint with
- * their JOSE library of choice.
+ * `undefined` when the signature (or shape) is invalid or a numeric `exp` is
+ * not in the future. It verifies ES256 regardless of the header's `alg` and
+ * checks nothing else: a payload with no `exp` passes, and `iss`, `aud`, and
+ * `nbf` are the caller's to check. Exported for tests and lightweight
+ * in-process verification; production resource servers should verify against
+ * the JWKS endpoint with their JOSE library of choice.
  */
 export async function verifyJwt(jwt, publicJwk, options = {}) {
     const parts = jwt.split(".");
@@ -190,13 +196,15 @@ export async function verifyJwt(jwt, publicJwk, options = {}) {
  * }
  * ```
  *
- * The token store still persists the (hashed) JWT string, so revocation and
- * introspection keep working exactly as with opaque tokens.
+ * Your token store persists the JWT string like any access token, so
+ * revocation and introspection work as with opaque tokens for readers that
+ * consult the store. A resource server that verifies the JWT offline against
+ * JWKS does not see a revocation and accepts the token until its `exp`.
  */
 export function createJwtAccessTokenGenerator(options) {
     const lifetime = options.lifetimeSeconds ?? 3600;
     const subjectOf = options.subjectOf ?? defaultSubjectOf;
-    return async (client, user, scope, authenticationContext) => {
+    return async (client, user, scope, authenticationContext, expiresAt) => {
         const event = user
             ? snapshotAuthenticationContext(authenticationContext)
             : undefined;
@@ -205,6 +213,9 @@ export function createJwtAccessTokenGenerator(options) {
         const extraClaims = user && options.userClaims
             ? await options.userClaims(user, scope, client, event)
             : undefined;
+        const storedExp = expiresAt
+            ? Math.floor(expiresAt.getTime() / 1000)
+            : now + lifetime;
         const payload = {
             ...extraClaims,
             iss: options.issuer,
@@ -212,7 +223,7 @@ export function createJwtAccessTokenGenerator(options) {
             client_id: client.id,
             aud: options.audience ?? client.id,
             iat: now,
-            exp: now + lifetime,
+            exp: Math.min(now + lifetime, storedExp),
             jti: crypto.randomUUID(),
         };
         const scopeText = scope?.toString();

package/esm/testing/contract/mod.d.ts

@@ -19,9 +19,9 @@
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
- * Each runner takes a factory + seed-helpers because `add` / `register`
- * methods aren't part of the public service interface — the consumer
- * tells the runner how to populate test data.
+ * The service runners take a factory plus seed helpers because `add` /
+ * `register` methods aren't part of the public service interfaces — the
+ * consumer tells the runner how to populate test data.
  *
  * @module
  */

package/esm/testing/contract/mod.js

@@ -19,9 +19,9 @@
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
- * Each runner takes a factory + seed-helpers because `add` / `register`
- * methods aren't part of the public service interface — the consumer
- * tells the runner how to populate test data.
+ * The service runners take a factory plus seed helpers because `add` /
+ * `register` methods aren't part of the public service interfaces — the
+ * consumer tells the runner how to populate test data.
  *
  * @module
  */

package/esm/testing/mod.d.ts

@@ -1,7 +1,7 @@
 /**
  * Testing helpers for apps that use `@udibo/oauth2`.
  *
- * Two layers ship:
+ * Three layers ship:
  *
  * - **Testing surface for the OAuth2 protocol.** The recommended pattern
  *   for testing apps that use the resource server is to expose your
@@ -20,7 +20,9 @@
  * - **In-memory service implementations.** `MemoryUserService`,
  *   `MemoryClientService`, `MemoryTokenService`,
  *   `MemoryAuthorizationCodeService`, and `MemoryDeviceAuthorizationService`
- *   satisfy every server-side service contract, generic over the consumer's
+ *   implement the authorization server's user, client, token,
+ *   authorization-code and device-authorization service interfaces, generic
+ *   over the consumer's
  *   user / client / scope types. Suitable for tests, examples, and
  *   prototypes — never for production.
  *

package/esm/testing/mod.js

@@ -1,7 +1,7 @@
 /**
  * Testing helpers for apps that use `@udibo/oauth2`.
  *
- * Two layers ship:
+ * Three layers ship:
  *
  * - **Testing surface for the OAuth2 protocol.** The recommended pattern
  *   for testing apps that use the resource server is to expose your
@@ -20,7 +20,9 @@
  * - **In-memory service implementations.** `MemoryUserService`,
  *   `MemoryClientService`, `MemoryTokenService`,
  *   `MemoryAuthorizationCodeService`, and `MemoryDeviceAuthorizationService`
- *   satisfy every server-side service contract, generic over the consumer's
+ *   implement the authorization server's user, client, token,
+ *   authorization-code and device-authorization service interfaces, generic
+ *   over the consumer's
  *   user / client / scope types. Suitable for tests, examples, and
  *   prototypes — never for production.
  *

package/esm/testing/services.d.ts

@@ -1,5 +1,5 @@
 /**
- * In-memory implementations of every OAuth2 service interface.
+ * In-memory implementations of the authorization server's service interfaces.
  *
  * The `Memory*Service` family is the public, generic version of the fixtures
  * the library uses for its own tests. They satisfy the

package/esm/testing/services.js

@@ -1,5 +1,5 @@
 /**
- * In-memory implementations of every OAuth2 service interface.
+ * In-memory implementations of the authorization server's service interfaces.
  *
  * The `Memory*Service` family is the public, generic version of the fixtures
  * the library uses for its own tests. They satisfy the

package/esm/testing/tenant.d.ts

@@ -124,9 +124,17 @@ export interface FakeTenant {
     addUser(user: FakeTenantUser): Promise<void>;
     /** Adds an organization. Throws on a duplicate id. */
     addOrganization(organization: FakeTenantOrganization): void;
-    /** Makes a person a member of an organization, replacing any earlier membership. */
+    /**
+     * Makes a person a member of an organization, replacing any earlier
+     * membership. Throws when the organization does not exist.
+     */
     addMember(organizationId: string, userId: string, membership?: FakeTenantMembership): void;
-    /** Ends a membership. Credentials issued in that organization stop answering for it. */
+    /**
+     * Ends a membership. From then on introspection and `/api/check` stop
+     * answering for that organization on credentials issued in it, and UserInfo
+     * drops its `org_*` claims; a JWT access token or id_token already minted
+     * keeps its claims until it expires.
+     */
     removeMember(organizationId: string, userId: string): void;
     /** Registers a resource type, so `/api/check` accepts it. */
     registerResourceType(type: string): void;
@@ -134,12 +142,13 @@ export interface FakeTenant {
     grant(grant: FakeTenantGrant): void;
     /**
      * Chooses who the next authorization requests authenticate as, until
-     * called again. With nobody chosen, authorize answers `login_required`.
+     * called again. With nobody chosen, authorize answers `access_denied`.
      */
     signInAs(userId: string | null, signIn?: FakeTenantSignIn): void;
     /**
      * Mints an access token without the browser flow, for testing an API
-     * directly. JWT or opaque as the client is registered.
+     * directly. JWT or opaque as the client is registered. Throws when the
+     * client or user does not exist.
      */
     issueAccessToken(request: FakeTenantTokenRequest): Promise<string>;
 }

package/esm/utils/_buffer.d.ts

@@ -4,7 +4,8 @@
  * @module
  */
 /**
- * Copy to a standalone `ArrayBuffer` to satisfy `BufferSource` on runtimes that
- * narrow `Uint8Array<ArrayBufferLike>` away from `ArrayBuffer`.
+ * Copies the viewed bytes into a standalone `ArrayBuffer`, for passing a
+ * `Uint8Array<ArrayBufferLike>` where Web Crypto's `BufferSource` type does not
+ * accept it.
  */
 export declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;

package/esm/utils/_buffer.js

@@ -4,8 +4,9 @@
  * @module
  */
 /**
- * Copy to a standalone `ArrayBuffer` to satisfy `BufferSource` on runtimes that
- * narrow `Uint8Array<ArrayBufferLike>` away from `ArrayBuffer`.
+ * Copies the viewed bytes into a standalone `ArrayBuffer`, for passing a
+ * `Uint8Array<ArrayBufferLike>` where Web Crypto's `BufferSource` type does not
+ * accept it.
  */
 export function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);

package/esm/utils/_timing-safe.d.ts

@@ -1,13 +1,15 @@
 /**
- * Internal constant-time matching shared by the MFA and BFF code paths.
+ * Internal timing-safe matching for secret candidates.
  *
  * @module
  */
 /**
- * Constant-time scan for `target` among `candidates`: every candidate is
- * compared (no early exit), so timing reveals neither whether nor where a
- * match occurred. Returns the index of the *last* matching candidate, or
- * `undefined` when none match — order candidates least- to most-preferred so
- * a duplicate resolves to the preferred entry.
+ * Compares `target` against every candidate with no early exit, so the scan's
+ * duration does not reveal where a match occurred. Each comparison is
+ * {@link timingSafeEqualString}, which returns early on a byte-length mismatch,
+ * so candidates of a different length than `target` are distinguishable by
+ * timing. Returns the index of the *last* matching candidate, or `undefined`
+ * when none match — order candidates least- to most-preferred so a duplicate
+ * resolves to the preferred entry.
  */
 export declare function timingSafeMatchIndex(candidates: string[], target: string): number | undefined;

package/esm/utils/_timing-safe.js

@@ -1,15 +1,17 @@
 /**
- * Internal constant-time matching shared by the MFA and BFF code paths.
+ * Internal timing-safe matching for secret candidates.
  *
  * @module
  */
 import { timingSafeEqualString } from "./crypto.js";
 /**
- * Constant-time scan for `target` among `candidates`: every candidate is
- * compared (no early exit), so timing reveals neither whether nor where a
- * match occurred. Returns the index of the *last* matching candidate, or
- * `undefined` when none match — order candidates least- to most-preferred so
- * a duplicate resolves to the preferred entry.
+ * Compares `target` against every candidate with no early exit, so the scan's
+ * duration does not reveal where a match occurred. Each comparison is
+ * {@link timingSafeEqualString}, which returns early on a byte-length mismatch,
+ * so candidates of a different length than `target` are distinguishable by
+ * timing. Returns the index of the *last* matching candidate, or `undefined`
+ * when none match — order candidates least- to most-preferred so a duplicate
+ * resolves to the preferred entry.
  */
 export function timingSafeMatchIndex(candidates, target) {
     let index;

package/esm/utils/basic-auth.d.ts

@@ -18,9 +18,8 @@ export interface BasicAuth {
  * trip. A segment that is not valid percent-encoding is taken verbatim, so a
  * client that sends such characters un-encoded still authenticates.
  *
- * @param authorization The Authorization header value
- * @returns The parsed credentials
- * @throws {InvalidClientError} If the header is missing or malformed
+ * @throws {InvalidClientError} If the header is missing, not `Basic`, not
+ * valid base64, or does not decode to `name:pass` with a non-empty name.
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
  */
 export declare function parseBasicAuth(authorization: string | null): BasicAuth;
@@ -33,18 +32,12 @@ export declare function parseBasicAuth(authorization: string | null): BasicAuth;
  * only of `A-Z`, `a-z`, `0-9`, `-`, `_`, `.` and `*` encode byte-identically to
  * their raw form; every other character, `~` included, is percent-encoded.
  *
- * @param clientId The client ID
- * @param clientSecret The client secret
- * @returns The encoded Authorization header value
+ * @returns The `Basic …` Authorization header value.
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
  */
 export declare function encodeBasicAuth(clientId: string, clientSecret: string): string;
 /**
- * Tries to parse basic authentication credentials from an Authorization header.
- * Returns undefined if the header is missing or not Basic auth. Decodes both
- * segments the same way {@link parseBasicAuth} does.
- *
- * @param authorization The Authorization header value
- * @returns The parsed credentials or undefined
+ * Non-throwing {@link parseBasicAuth}: returns `undefined` wherever that would
+ * throw — a missing, non-`Basic`, badly encoded or malformed header.
  */
 export declare function tryParseBasicAuth(authorization: string | null): BasicAuth | undefined;