@udibo/oauth2 0.1.0

package/esm/utils/_buffer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal buffer conversion shared by the modules that call Web Crypto.
+ *
+ * @module
+ */
+/**
+ * Copy to a standalone `ArrayBuffer` to satisfy `BufferSource` on runtimes that
+ * narrow `Uint8Array<ArrayBufferLike>` away from `ArrayBuffer`.
+ */
+export declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;

package/esm/utils/_buffer.js

@@ -0,0 +1,12 @@
+/**
+ * Internal buffer conversion shared by the modules that call Web Crypto.
+ *
+ * @module
+ */
+/**
+ * Copy to a standalone `ArrayBuffer` to satisfy `BufferSource` on runtimes that
+ * narrow `Uint8Array<ArrayBufferLike>` away from `ArrayBuffer`.
+ */
+export function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Internal constant-time matching shared by the MFA and BFF code paths.
+ *
+ * @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.
+ */
+export declare function timingSafeMatchIndex(candidates: string[], target: string): number | undefined;

package/esm/utils/_timing-safe.js

@@ -0,0 +1,22 @@
+/**
+ * Internal constant-time matching shared by the MFA and BFF code paths.
+ *
+ * @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.
+ */
+export function timingSafeMatchIndex(candidates, target) {
+    let index;
+    for (let i = 0; i < candidates.length; i++) {
+        if (timingSafeEqualString(candidates[i], target)) {
+            index = i;
+        }
+    }
+    return index;
+}

package/esm/utils/authentication-context.d.ts

@@ -0,0 +1,3 @@
+import type { AuthenticationContext } from "../models/authentication.js";
+/** Copies verified event claims without sharing mutable method arrays. */
+export declare function snapshotAuthenticationContext(context: AuthenticationContext | undefined): AuthenticationContext | undefined;

package/esm/utils/authentication-context.js

@@ -0,0 +1,14 @@
+/** Copies verified event claims without sharing mutable method arrays. */
+export function snapshotAuthenticationContext(context) {
+    if (context === undefined)
+        return undefined;
+    return Object.freeze({
+        ...(context.auth_time === undefined
+            ? {}
+            : { auth_time: context.auth_time }),
+        ...(context.acr === undefined ? {} : { acr: context.acr }),
+        ...(context.amr === undefined
+            ? {}
+            : { amr: Object.freeze([...context.amr]) }),
+    });
+}

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

@@ -0,0 +1,50 @@
+/**
+ * HTTP Basic Authentication utilities.
+ * @module
+ */
+/** Parsed basic authentication credentials. */
+export interface BasicAuth {
+    /** Username portion (the segment before the first colon). */
+    name: string;
+    /** Password portion (everything after the first colon). */
+    pass: string;
+}
+/**
+ * Parses basic authentication credentials from an Authorization header.
+ *
+ * Both segments are decoded from `application/x-www-form-urlencoded` form, as
+ * RFC 6749 section 2.3.1 requires of client credentials, so a client id or
+ * secret containing `+`, a space, `%`, `:`, or non-ASCII survives the round
+ * 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
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+ */
+export declare function parseBasicAuth(authorization: string | null): BasicAuth;
+/**
+ * Encodes client credentials for HTTP Basic Authentication.
+ *
+ * Both values are `application/x-www-form-urlencoded` before base64, as RFC
+ * 6749 section 2.3.1 requires: that keeps `+`, spaces, `%`, and `:` unambiguous
+ * on the wire and makes a non-ASCII secret encodable at all. Credentials made
+ * 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
+ * @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
+ */
+export declare function tryParseBasicAuth(authorization: string | null): BasicAuth | undefined;

package/esm/utils/basic-auth.js

@@ -0,0 +1,106 @@
+/**
+ * HTTP Basic Authentication utilities.
+ * @module
+ */
+import { InvalidClientError } from "../errors.js";
+const CREDENTIALS = /^ *(?:[Bb][Aa][Ss][Ii][Cc]) +([\w-.~+/]+=*) *$/;
+const NAME_PASS = /^([^:]+):(.*)$/;
+const NOT_FORM_SAFE = /[!'()~]/g;
+const ENCODED_SPACE = /%20/g;
+const PLUS = /\+/g;
+function formUrlEncode(value) {
+    return encodeURIComponent(value)
+        .replace(NOT_FORM_SAFE, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(ENCODED_SPACE, "+");
+}
+function formUrlDecode(value) {
+    try {
+        return decodeURIComponent(value.replace(PLUS, " "));
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Parses basic authentication credentials from an Authorization header.
+ *
+ * Both segments are decoded from `application/x-www-form-urlencoded` form, as
+ * RFC 6749 section 2.3.1 requires of client credentials, so a client id or
+ * secret containing `+`, a space, `%`, `:`, or non-ASCII survives the round
+ * 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
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+ */
+export function parseBasicAuth(authorization) {
+    if (!authorization) {
+        throw new InvalidClientError("authorization header required");
+    }
+    let match = CREDENTIALS.exec(authorization);
+    if (!match) {
+        throw new InvalidClientError("unsupported authorization header");
+    }
+    let value;
+    try {
+        value = atob(match[1]);
+    }
+    catch {
+        throw new InvalidClientError("authorization header is not correctly encoded");
+    }
+    match = NAME_PASS.exec(value);
+    if (!match) {
+        throw new InvalidClientError("authorization header is malformed");
+    }
+    return {
+        name: formUrlDecode(match[1]),
+        pass: formUrlDecode(match[2]),
+    };
+}
+/**
+ * Encodes client credentials for HTTP Basic Authentication.
+ *
+ * Both values are `application/x-www-form-urlencoded` before base64, as RFC
+ * 6749 section 2.3.1 requires: that keeps `+`, spaces, `%`, and `:` unambiguous
+ * on the wire and makes a non-ASCII secret encodable at all. Credentials made
+ * 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
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+ */
+export function encodeBasicAuth(clientId, clientSecret) {
+    return `Basic ${btoa(`${formUrlEncode(clientId)}:${formUrlEncode(clientSecret)}`)}`;
+}
+/**
+ * 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
+ */
+export function tryParseBasicAuth(authorization) {
+    if (!authorization)
+        return undefined;
+    const match = CREDENTIALS.exec(authorization);
+    if (!match)
+        return undefined;
+    try {
+        const value = atob(match[1]);
+        const namePass = NAME_PASS.exec(value);
+        if (!namePass)
+            return undefined;
+        return {
+            name: formUrlDecode(namePass[1]),
+            pass: formUrlDecode(namePass[2]),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/esm/utils/crypto.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Authenticated-encryption (AES-256-GCM) and key-derivation helpers for sealing
+ * session and token data at rest or in a cookie.
+ *
+ * Two key-derivation paths, for two different threat models:
+ *
+ * - {@link deriveAesKey} hashes a single **server-held** secret (SHA-256) into
+ *   an AES-256-GCM key. Use this for a stateless cookie sealed under one
+ *   configured secret (see `EncryptedCookieSessionStore`), where the secret is
+ *   never persisted.
+ *
+ * - {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so
+ *   a high-entropy *per-session* secret yields an encryption key that is
+ *   independent of any other value derived from the same secret. This is what
+ *   makes "the cookie value is both the lookup credential **and** the decryption
+ *   key" safe: a database can store `sha256(secret)` as a lookup hash while the
+ *   sealing key is `HKDF(secret, info)`, and knowing the stored hash never
+ *   reveals the key. Always pass a distinct `info` per purpose.
+ *
+ * {@link seal}/{@link unseal} use AES-256-GCM (an AEAD), so tampered ciphertext
+ * fails to unseal (returns `null`) rather than decrypting to garbage.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import { sha256Hash } from "../server/utils/hash.js";
+import { toArrayBuffer } from "./_buffer.js";
+export { sha256Hash };
+export { toArrayBuffer };
+/** Constant-time string equality (length difference short-circuits to false). */
+export declare function timingSafeEqualString(a: string, b: string): boolean;
+/** URL-safe base64 encode (no padding). */
+export declare function base64urlEncode(bytes: Uint8Array): string;
+/**
+ * URL-safe base64 decode. Padding is optional, so JWS/JWT segments — which
+ * carry none — decode as-is. Only the URL-safe alphabet is accepted.
+ *
+ * @throws {TypeError} on a character outside the URL-safe alphabet — including
+ * the standard alphabet's `+` and `/`, and whitespace.
+ * @throws {RangeError} on a truncated value (a length that leaves a remainder
+ * of 1 when divided by 4, which no encoding can produce).
+ */
+export declare function base64urlDecode(value: string): Uint8Array;
+/**
+ * Mint a cryptographically random, URL-safe token: `base64url` of `bytes`
+ * random bytes, unpadded, so it drops into a URL, a link in an email, or a
+ * cookie value with no further escaping.
+ *
+ * This is the primitive behind session secrets, verification / password-reset
+ * links, and download tokens. The token is a bearer credential: hand it out
+ * once and persist only a hash of it ({@link sha256Hash}, from this module).
+ * The default 32 bytes (256 bits, 43 characters) is what every such credential
+ * should use; shrink it only for values that don't authorize anything.
+ *
+ * @param bytes How many random bytes to draw. Defaults to 32.
+ * @returns The unpadded base64url encoding of those bytes.
+ *
+ * @example
+ * ```ts
+ * randomToken();    // 43 chars, e.g. "kQ7…" — a reset-link token
+ * randomToken(16);  // 22 chars — a non-credential correlation id
+ * ```
+ */
+export declare function randomToken(bytes?: number): string;
+/**
+ * Derive an AES-256-GCM key from a single server-held secret via SHA-256.
+ *
+ * Suitable when the secret is a long-lived configuration value that is never
+ * stored alongside the ciphertext. Do **not** use this when a hash of the same
+ * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
+ * sealing key is independent of that stored hash.
+ *
+ * @throws if the secret has fewer than 16 bytes of entropy (32+ recommended).
+ */
+export declare function deriveAesKey(secret: string | Uint8Array): Promise<CryptoKey>;
+/**
+ * Derive an AES-256-GCM sealing key from a high-entropy secret via HKDF-SHA-256
+ * with a domain-separating `info` label.
+ *
+ * Keys derived with different `info` values (or different from `sha256(secret)`)
+ * are independent, so the same secret can safely back both a stored lookup hash
+ * and a never-stored sealing key. Pass a stable, unique `info` per purpose, e.g.
+ * `"udibo:bff-session-tokens:v1"`.
+ */
+export declare function deriveSealKey(secret: string | Uint8Array, info: string): Promise<CryptoKey>;
+/** Seal bytes with AES-256-GCM; returns `base64url(iv ‖ ciphertext+tag)`. */
+export declare function seal(key: CryptoKey, plaintext: Uint8Array): Promise<string>;
+/**
+ * Unseal an AES-256-GCM value produced by {@link seal}. Returns `null` on a
+ * malformed input, a wrong key, or tampering (the AEAD tag fails); it never
+ * throws.
+ */
+export declare function unseal(key: CryptoKey, sealed: string): Promise<Uint8Array | null>;
+/** Seal a JSON-serializable value. */
+export declare function sealJson(key: CryptoKey, value: unknown): Promise<string>;
+/** Unseal a value sealed by {@link sealJson}, or `null` if it can't be unsealed. */
+export declare function unsealJson<T>(key: CryptoKey, sealed: string): Promise<T | null>;

package/esm/utils/crypto.js

@@ -0,0 +1,162 @@
+/**
+ * Authenticated-encryption (AES-256-GCM) and key-derivation helpers for sealing
+ * session and token data at rest or in a cookie.
+ *
+ * Two key-derivation paths, for two different threat models:
+ *
+ * - {@link deriveAesKey} hashes a single **server-held** secret (SHA-256) into
+ *   an AES-256-GCM key. Use this for a stateless cookie sealed under one
+ *   configured secret (see `EncryptedCookieSessionStore`), where the secret is
+ *   never persisted.
+ *
+ * - {@link deriveSealKey} uses **HKDF** with a domain-separating `info` label so
+ *   a high-entropy *per-session* secret yields an encryption key that is
+ *   independent of any other value derived from the same secret. This is what
+ *   makes "the cookie value is both the lookup credential **and** the decryption
+ *   key" safe: a database can store `sha256(secret)` as a lookup hash while the
+ *   sealing key is `HKDF(secret, info)`, and knowing the stored hash never
+ *   reveals the key. Always pass a distinct `info` per purpose.
+ *
+ * {@link seal}/{@link unseal} use AES-256-GCM (an AEAD), so tampered ciphertext
+ * fails to unseal (returns `null`) rather than decrypting to garbage.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import { timingSafeEqual } from "../deps/jsr.io/@std/crypto/1.1.0/timing_safe_equal.js";
+import { decodeBase64Url, encodeBase64Url } from "../deps/jsr.io/@std/encoding/1.0.11/base64url.js";
+import { sha256Hash } from "../server/utils/hash.js";
+import { toArrayBuffer } from "./_buffer.js";
+export { sha256Hash };
+export { toArrayBuffer };
+function toBytes(secret) {
+    return typeof secret === "string" ? new TextEncoder().encode(secret) : secret;
+}
+/** Constant-time string equality (length difference short-circuits to false). */
+export function timingSafeEqualString(a, b) {
+    const encoder = new TextEncoder();
+    const aBytes = encoder.encode(a);
+    const bBytes = encoder.encode(b);
+    if (aBytes.byteLength !== bBytes.byteLength)
+        return false;
+    return timingSafeEqual(aBytes, bBytes);
+}
+/** URL-safe base64 encode (no padding). */
+export function base64urlEncode(bytes) {
+    return encodeBase64Url(bytes);
+}
+/**
+ * URL-safe base64 decode. Padding is optional, so JWS/JWT segments — which
+ * carry none — decode as-is. Only the URL-safe alphabet is accepted.
+ *
+ * @throws {TypeError} on a character outside the URL-safe alphabet — including
+ * the standard alphabet's `+` and `/`, and whitespace.
+ * @throws {RangeError} on a truncated value (a length that leaves a remainder
+ * of 1 when divided by 4, which no encoding can produce).
+ */
+export function base64urlDecode(value) {
+    return decodeBase64Url(value);
+}
+/**
+ * Mint a cryptographically random, URL-safe token: `base64url` of `bytes`
+ * random bytes, unpadded, so it drops into a URL, a link in an email, or a
+ * cookie value with no further escaping.
+ *
+ * This is the primitive behind session secrets, verification / password-reset
+ * links, and download tokens. The token is a bearer credential: hand it out
+ * once and persist only a hash of it ({@link sha256Hash}, from this module).
+ * The default 32 bytes (256 bits, 43 characters) is what every such credential
+ * should use; shrink it only for values that don't authorize anything.
+ *
+ * @param bytes How many random bytes to draw. Defaults to 32.
+ * @returns The unpadded base64url encoding of those bytes.
+ *
+ * @example
+ * ```ts
+ * randomToken();    // 43 chars, e.g. "kQ7…" — a reset-link token
+ * randomToken(16);  // 22 chars — a non-credential correlation id
+ * ```
+ */
+export function randomToken(bytes = 32) {
+    return base64urlEncode(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+/**
+ * Derive an AES-256-GCM key from a single server-held secret via SHA-256.
+ *
+ * Suitable when the secret is a long-lived configuration value that is never
+ * stored alongside the ciphertext. Do **not** use this when a hash of the same
+ * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
+ * sealing key is independent of that stored hash.
+ *
+ * @throws if the secret has fewer than 16 bytes of entropy (32+ recommended).
+ */
+export async function deriveAesKey(secret) {
+    const raw = toBytes(secret);
+    if (raw.byteLength < 16) {
+        throw new Error("secret must be at least 16 bytes; 32+ bytes of entropy is recommended.");
+    }
+    const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(raw));
+    return await crypto.subtle.importKey("raw", digest, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+/**
+ * Derive an AES-256-GCM sealing key from a high-entropy secret via HKDF-SHA-256
+ * with a domain-separating `info` label.
+ *
+ * Keys derived with different `info` values (or different from `sha256(secret)`)
+ * are independent, so the same secret can safely back both a stored lookup hash
+ * and a never-stored sealing key. Pass a stable, unique `info` per purpose, e.g.
+ * `"udibo:bff-session-tokens:v1"`.
+ */
+export async function deriveSealKey(secret, info) {
+    const base = await crypto.subtle.importKey("raw", toArrayBuffer(toBytes(secret)), "HKDF", false, ["deriveKey"]);
+    return await crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(0),
+        info: new TextEncoder().encode(info),
+    }, base, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+/** Seal bytes with AES-256-GCM; returns `base64url(iv ‖ ciphertext+tag)`. */
+export async function seal(key, plaintext) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, toArrayBuffer(plaintext)));
+    const packed = new Uint8Array(iv.length + ciphertext.length);
+    packed.set(iv, 0);
+    packed.set(ciphertext, iv.length);
+    return base64urlEncode(packed);
+}
+/**
+ * Unseal an AES-256-GCM value produced by {@link seal}. Returns `null` on a
+ * malformed input, a wrong key, or tampering (the AEAD tag fails); it never
+ * throws.
+ */
+export async function unseal(key, sealed) {
+    try {
+        const bytes = base64urlDecode(sealed);
+        if (bytes.length < 13)
+            return null;
+        const iv = bytes.slice(0, 12);
+        const ciphertext = bytes.slice(12);
+        const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, toArrayBuffer(ciphertext));
+        return new Uint8Array(plaintext);
+    }
+    catch {
+        return null;
+    }
+}
+/** Seal a JSON-serializable value. */
+export async function sealJson(key, value) {
+    return await seal(key, new TextEncoder().encode(JSON.stringify(value)));
+}
+/** Unseal a value sealed by {@link sealJson}, or `null` if it can't be unsealed. */
+export async function unsealJson(key, sealed) {
+    const bytes = await unseal(key, sealed);
+    if (!bytes)
+        return null;
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return null;
+    }
+}

package/esm/utils/pkce.d.ts

@@ -0,0 +1,151 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth2.
+ *
+ * Implements RFC 7636 for preventing authorization code interception attacks.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636
+ * @module
+ */
+/**
+ * A challenge method used for PKCE.
+ * Transforms a verifier into a challenge.
+ */
+export type ChallengeMethod = (verifier: string) => Promise<string>;
+/** The allowed PKCE code challenge methods. */
+export interface ChallengeMethods {
+    /** Maps a `code_challenge_method` name (e.g. `"S256"`) to its transform. */
+    [key: string]: ChallengeMethod;
+}
+/**
+ * Minimum length for code verifier per RFC 7636 Section 4.1.
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export declare const CODE_VERIFIER_MIN_LENGTH = 43;
+/**
+ * Maximum length for code verifier per RFC 7636 Section 4.1.
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export declare const CODE_VERIFIER_MAX_LENGTH = 128;
+/**
+ * Pattern for valid code verifier characters per RFC 7636 Section 4.1.
+ * Allowed characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export declare const CODE_VERIFIER_PATTERN: RegExp;
+/**
+ * The default allowed PKCE code challenge methods.
+ *
+ * Per RFC 7636 and OAuth 2.1, clients SHOULD use the S256 method.
+ * The "plain" method is NOT included by default as it provides
+ * weaker security guarantees.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.1.1
+ */
+export declare const challengeMethods: ChallengeMethods;
+/**
+ * Validates a code verifier per RFC 7636 Section 4.1.
+ *
+ * The code verifier must:
+ * - Be between 43 and 128 characters long
+ * - Contain only unreserved characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ *
+ * @param verifier The code verifier to validate
+ * @returns true if the verifier is valid
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export declare function validateCodeVerifier(verifier: string): boolean;
+/**
+ * Generates a random code verifier with a minimum of 256 bits of entropy.
+ *
+ * This is done by generating a random 32-octet sequence then base64url encoding it
+ * to produce a 43 character URL-safe string.
+ *
+ * @returns A cryptographically random code verifier
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-7.1
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generates a code challenge from a code verifier using the S256 method.
+ *
+ * The S256 challenge is: BASE64URL(SHA256(ASCII(code_verifier)))
+ *
+ * @param verifier The code verifier to transform
+ * @returns The code challenge
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ */
+export declare function generateCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Validates a `code_challenge` per RFC 7636 Section 4.2, for the challenge
+ * methods whose output shape that section fixes.
+ *
+ * `S256` and `plain` are the only methods the PKCE registry defines, and both
+ * produce a challenge drawn from the same 43-128 unreserved characters as a
+ * code verifier, so an authorization endpoint can reject a malformed challenge
+ * before it is ever stored. Any other `method` — one a server registered in its
+ * own {@link ChallengeMethods} map — may legitimately produce any shape, so
+ * this returns `true` for it rather than imposing a format its author never
+ * agreed to. Check the name is allowed with {@linkcode getChallengeMethod}
+ * first; this answers only for the format.
+ *
+ * @param challenge The client-supplied `code_challenge`
+ * @param method The client-supplied `code_challenge_method`; defaults to `S256`
+ * @returns true when the challenge is acceptable for that method
+ * @example
+ * ```ts
+ * validateCodeChallenge("a".repeat(43));                 // → true
+ * validateCodeChallenge("short");                        // → false
+ * validateCodeChallenge("short", "custom-method");       // → true
+ * ```
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ */
+export declare function validateCodeChallenge(challenge: string, method?: string | null): boolean;
+/**
+ * Resolves a client-supplied `code_challenge_method` name against the methods
+ * a server allows.
+ *
+ * Reach for this instead of indexing a {@link ChallengeMethods} map directly.
+ * The name comes off the wire, and a map written as a plain object literal
+ * also inherits `toString`, `valueOf`, `constructor` and friends from
+ * `Object.prototype` — a bare lookup hands those back as if the server had
+ * allowed them, which downgrades PKCE to a value any verifier satisfies. Only
+ * own, callable properties of `methods` resolve here; every other name is
+ * `undefined`, including names inherited from a prototype.
+ *
+ * @param methods The challenge methods the server allows
+ * @param method The client-supplied method name; defaults to `S256`
+ * @returns The transform for that method, or `undefined` when it is not allowed
+ * @example
+ * ```ts
+ * getChallengeMethod(challengeMethods, "S256");       // → the S256 transform
+ * getChallengeMethod(challengeMethods);               // → the S256 transform
+ * getChallengeMethod(challengeMethods, "toString");   // → undefined
+ * getChallengeMethod(challengeMethods, "__proto__");  // → undefined
+ * ```
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.3
+ */
+export declare function getChallengeMethod(methods: ChallengeMethods, method?: string | null): ChallengeMethod | undefined;
+/**
+ * Verifies that a code verifier matches a code challenge.
+ *
+ * Fails closed against the default {@link challengeMethods} map only: a
+ * `method` that map does not hold — `"plain"`, a name inherited from
+ * `Object.prototype` such as `"toString"`, or one registered on a grant via
+ * its own `challengeMethods` — resolves `false` rather than throwing, so it is
+ * indistinguishable from a mismatched verifier.
+ *
+ * @param verifier The code verifier provided by the client
+ * @param challenge The code challenge stored from the authorization request
+ * @param method The challenge method used (defaults to S256)
+ * @returns true if the verifier matches the challenge
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.6
+ */
+export declare function verifyCodeChallenge(verifier: string, challenge: string, method?: string): Promise<boolean>;
+/**
+ * Generates a random state parameter for CSRF protection.
+ *
+ * @returns A random UUID to use as the state parameter
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-10.12
+ */
+export declare function generateState(): string;