@zudojs/auth-oauth 1.1.0

package/dist/oauthErrors/oauthError.base.js

@@ -0,0 +1,168 @@
+/**
+ * Error classes for the OAuth2 client.
+ *
+ * @module oauthErrors/oauthError
+ *
+ * These are defined locally rather than extending `@zudojs/errors` so the
+ * package has no `@zudojs/*` dependency at all.
+ *
+ * **Secret hygiene.** No constructor here ever interpolates a client secret,
+ * an access token, a refresh token or a code verifier into `message`. The
+ * only provider-supplied text that reaches a message is an OAuth `error`
+ * code, and it is passed through a strict `[a-z0-9_.-]{1,64}` filter first,
+ * so a provider cannot echo a secret back into your logs. `message` is the
+ * first line of `stack`, so keeping it clean keeps the stack clean.
+ */
+/** Stable, machine-readable error codes. */
+export const OAuthErrorCode = {
+    /** The config is unusable: missing field, bad URL, unsupported operation. */
+    CONFIGURATION_INVALID: "OAUTH_CONFIGURATION_INVALID",
+    /** A URL failed the scheme / credential / SSRF guard. */
+    ENDPOINT_NOT_ALLOWED: "OAUTH_ENDPOINT_NOT_ALLOWED",
+    /** The redirect URI is not in the caller's allowlist. */
+    REDIRECT_URI_NOT_ALLOWED: "OAUTH_REDIRECT_URI_NOT_ALLOWED",
+    /** `state` did not match, was absent, or was malformed. */
+    STATE_MISMATCH: "OAUTH_STATE_MISMATCH",
+    /** A PKCE verifier was malformed. */
+    PKCE_INVALID: "OAUTH_PKCE_INVALID",
+    /** The provider returned a non-2xx or an OAuth `error` payload. */
+    PROVIDER_REJECTED: "OAUTH_PROVIDER_REJECTED",
+    /** The provider's response was unparseable or structurally invalid. */
+    PROVIDER_RESPONSE_INVALID: "OAUTH_PROVIDER_RESPONSE_INVALID",
+    /** The response body exceeded the configured cap. */
+    RESPONSE_TOO_LARGE: "OAUTH_RESPONSE_TOO_LARGE",
+    /** The request timed out or the transport failed. */
+    NETWORK: "OAUTH_NETWORK",
+};
+/**
+ * Base error for every OAuth2 failure.
+ *
+ * `expose` says whether the message is safe to hand to an end user; it is
+ * `true` for request-caused failures and `false` for configuration ones
+ * (which describe your deployment, not the request).
+ */
+export class OAuthError extends Error {
+    name = "OAuthError";
+    /** Machine-readable code. */
+    code;
+    /** Suggested HTTP status for a handler that surfaces this. */
+    statusCode;
+    /** Whether `message` is safe to return to a client verbatim. */
+    expose;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : {});
+        this.code = options?.code ?? OAuthErrorCode.PROVIDER_REJECTED;
+        this.statusCode = options?.statusCode ?? 400;
+        this.expose = options?.expose ?? true;
+    }
+}
+/** The configuration is missing something or is structurally unusable. */
+export class OAuthConfigurationError extends OAuthError {
+    name = "OAuthConfigurationError";
+    constructor(message, options) {
+        super(message, {
+            code: OAuthErrorCode.CONFIGURATION_INVALID,
+            statusCode: 500,
+            expose: false,
+            ...options,
+        });
+    }
+}
+/**
+ * An endpoint URL is not an acceptable target: wrong scheme, embedded
+ * credentials, or a private / loopback / link-local / metadata host.
+ */
+export class OAuthEndpointNotAllowedError extends OAuthError {
+    name = "OAuthEndpointNotAllowedError";
+    constructor(message, options) {
+        super(message, {
+            code: OAuthErrorCode.ENDPOINT_NOT_ALLOWED,
+            statusCode: 500,
+            expose: false,
+            ...options,
+        });
+    }
+}
+/** The requested redirect URI is not in `config.allowedRedirectUris`. */
+export class OAuthRedirectUriError extends OAuthError {
+    name = "OAuthRedirectUriError";
+    constructor(message, options) {
+        super(message, {
+            code: OAuthErrorCode.REDIRECT_URI_NOT_ALLOWED,
+            statusCode: 400,
+            expose: true,
+            ...options,
+        });
+    }
+}
+/** The callback's `state` did not match the one that was issued. */
+export class OAuthStateMismatchError extends OAuthError {
+    name = "OAuthStateMismatchError";
+    constructor(message = "OAuth state verification failed.", options) {
+        super(message, {
+            code: OAuthErrorCode.STATE_MISMATCH,
+            statusCode: 400,
+            expose: true,
+            ...options,
+        });
+    }
+}
+/** The provider refused the request. */
+export class OAuthProviderError extends OAuthError {
+    name = "OAuthProviderError";
+    /** The provider's OAuth `error` code, if it sent a well-formed one. */
+    providerError;
+    /** The provider's HTTP status, if the exchange got that far. */
+    providerStatus;
+    constructor(message, options) {
+        super(message, {
+            code: OAuthErrorCode.PROVIDER_REJECTED,
+            statusCode: 502,
+            expose: true,
+            ...options,
+        });
+        if (options?.providerError !== undefined) {
+            this.providerError = options.providerError;
+        }
+        if (options?.providerStatus !== undefined) {
+            this.providerStatus = options.providerStatus;
+        }
+    }
+}
+/** The provider's response was not a usable OAuth2 payload. */
+export class OAuthResponseError extends OAuthError {
+    name = "OAuthResponseError";
+    constructor(message, options) {
+        super(message, {
+            code: OAuthErrorCode.PROVIDER_RESPONSE_INVALID,
+            statusCode: 502,
+            expose: true,
+            ...options,
+        });
+    }
+}
+/** The provider's response body exceeded `maxResponseBytes`. */
+export class OAuthResponseTooLargeError extends OAuthError {
+    name = "OAuthResponseTooLargeError";
+    constructor(limitBytes, options) {
+        super(`OAuth provider response exceeded the ${limitBytes}-byte limit.`, {
+            code: OAuthErrorCode.RESPONSE_TOO_LARGE,
+            statusCode: 502,
+            expose: true,
+            ...options,
+        });
+    }
+}
+/** The request timed out or the transport failed. */
+export class OAuthNetworkError extends OAuthError {
+    name = "OAuthNetworkError";
+    constructor(message, options) {
+        super(message, {
+            code: OAuthErrorCode.NETWORK,
+            statusCode: 504,
+            expose: true,
+            ...options,
+        });
+    }
+}
+//# sourceMappingURL=oauthError.base.js.map

package/dist/oauthProviders/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Provider presets and profile normalisation.
+ *
+ * @module oauthProviders
+ */
+export { type OAuthProviderPreset, PROVIDER_PRESETS, normalizeUserInfo, } from "./oauthProvider.presets.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/oauthProviders/index.js

@@ -0,0 +1,7 @@
+/**
+ * Provider presets and profile normalisation.
+ *
+ * @module oauthProviders
+ */
+export { PROVIDER_PRESETS, normalizeUserInfo, } from "./oauthProvider.presets.js";
+//# sourceMappingURL=index.js.map

package/dist/oauthProviders/oauthProvider.presets.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Endpoint presets and profile normalisation for the supported providers.
+ *
+ * @module oauthProviders/oauthProvider
+ *
+ * A preset only supplies defaults. Anything set on the `OAuthConfig` wins, so
+ * a tenanted Microsoft install or a self-hosted GitLab can override the URLs
+ * without leaving the `custom` provider behind.
+ */
+import type { ClientAuthMethod, OAuthProvider, OAuthUserInfo } from "../oauthTypes/index.js";
+/** Everything the client needs to know about one provider. */
+export interface OAuthProviderPreset {
+    /** Default authorization endpoint. */
+    readonly authorizeUrl?: string;
+    /** Default token endpoint. */
+    readonly tokenUrl?: string;
+    /**
+     * Default user-info endpoint. Absent for providers that have none — Apple
+     * returns the profile in the `id_token` on the first authorization only.
+     */
+    readonly userInfoUrl?: string;
+    /** Scopes requested when the caller does not specify any. */
+    readonly defaultScopes: readonly string[];
+    /** How this provider expects the client to authenticate at the token endpoint. */
+    readonly clientAuth: ClientAuthMethod;
+    /**
+     * Whether the provider issues refresh tokens on the standard flow.
+     *
+     * `false` for GitHub: classic OAuth App tokens do not expire and no refresh
+     * token is issued. (GitHub Apps with expiring tokens do — override the
+     * endpoints via `custom` if that is your setup.)
+     */
+    readonly supportsRefresh: boolean;
+    /** Extra parameters appended to every authorization request. */
+    readonly authorizeParams?: Readonly<Record<string, string>>;
+    /** Extra headers sent to the user-info endpoint. */
+    readonly userInfoHeaders?: Readonly<Record<string, string>>;
+}
+/** Endpoint presets, keyed by provider. */
+export declare const PROVIDER_PRESETS: Readonly<Record<OAuthProvider, OAuthProviderPreset>>;
+/**
+ * Normalise a provider's user-info payload into {@link OAuthUserInfo}.
+ *
+ * No field is invented. Where a provider does not return an email — GitHub
+ * with a private address, Discord without the `email` scope — the result
+ * simply has no `email`, and the caller decides what to do about it.
+ *
+ * @param provider - Which provider produced the payload.
+ * @param payload - The sanitized JSON object from the user-info endpoint.
+ * @returns The normalised profile, or `undefined` if no stable id was found.
+ */
+export declare function normalizeUserInfo(provider: OAuthProvider, payload: Record<string, unknown>): OAuthUserInfo | undefined;
+//# sourceMappingURL=oauthProvider.presets.d.ts.map

package/dist/oauthProviders/oauthProvider.presets.js

@@ -0,0 +1,190 @@
+/**
+ * Endpoint presets and profile normalisation for the supported providers.
+ *
+ * @module oauthProviders/oauthProvider
+ *
+ * A preset only supplies defaults. Anything set on the `OAuthConfig` wins, so
+ * a tenanted Microsoft install or a self-hosted GitLab can override the URLs
+ * without leaving the `custom` provider behind.
+ */
+/** Read a string field from a sanitized provider payload. */
+function str(payload, key) {
+    const value = payload[key];
+    if (typeof value === "string" && value.trim().length > 0)
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+/** Read a boolean field from a sanitized provider payload. */
+function bool(payload, key) {
+    const value = payload[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+/** Assemble an {@link OAuthUserInfo} without emitting `undefined` fields. */
+function profile(providerId, fields, raw) {
+    return {
+        providerId,
+        ...(fields.email !== undefined ? { email: fields.email } : {}),
+        ...(fields.emailVerified !== undefined
+            ? { emailVerified: fields.emailVerified }
+            : {}),
+        ...(fields.name !== undefined ? { name: fields.name } : {}),
+        ...(fields.avatarUrl !== undefined ? { avatarUrl: fields.avatarUrl } : {}),
+        raw,
+    };
+}
+/** Endpoint presets, keyed by provider. */
+export const PROVIDER_PRESETS = {
+    google: {
+        authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+        tokenUrl: "https://oauth2.googleapis.com/token",
+        userInfoUrl: "https://openidconnect.googleapis.com/v1/userinfo",
+        defaultScopes: ["openid", "email", "profile"],
+        clientAuth: "body",
+        supportsRefresh: true,
+        // Google only returns a refresh token when both are set.
+        authorizeParams: { access_type: "offline", prompt: "consent" },
+    },
+    github: {
+        authorizeUrl: "https://github.com/login/oauth/authorize",
+        tokenUrl: "https://github.com/login/oauth/access_token",
+        userInfoUrl: "https://api.github.com/user",
+        defaultScopes: ["read:user", "user:email"],
+        clientAuth: "body",
+        supportsRefresh: false,
+        userInfoHeaders: {
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    },
+    microsoft: {
+        authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+        tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+        userInfoUrl: "https://graph.microsoft.com/v1.0/me",
+        defaultScopes: ["openid", "email", "profile", "offline_access", "User.Read"],
+        clientAuth: "body",
+        supportsRefresh: true,
+    },
+    apple: {
+        authorizeUrl: "https://appleid.apple.com/auth/authorize",
+        tokenUrl: "https://appleid.apple.com/auth/token",
+        // Apple has no user-info endpoint; the profile arrives in the id_token.
+        defaultScopes: ["name", "email"],
+        clientAuth: "body",
+        supportsRefresh: true,
+        // Apple requires form_post when name/email scopes are requested.
+        authorizeParams: { response_mode: "form_post" },
+    },
+    discord: {
+        authorizeUrl: "https://discord.com/oauth2/authorize",
+        tokenUrl: "https://discord.com/api/oauth2/token",
+        userInfoUrl: "https://discord.com/api/v10/users/@me",
+        defaultScopes: ["identify", "email"],
+        clientAuth: "basic",
+        supportsRefresh: true,
+    },
+    custom: {
+        defaultScopes: [],
+        clientAuth: "body",
+        supportsRefresh: true,
+    },
+};
+/**
+ * Normalise a provider's user-info payload into {@link OAuthUserInfo}.
+ *
+ * No field is invented. Where a provider does not return an email — GitHub
+ * with a private address, Discord without the `email` scope — the result
+ * simply has no `email`, and the caller decides what to do about it.
+ *
+ * @param provider - Which provider produced the payload.
+ * @param payload - The sanitized JSON object from the user-info endpoint.
+ * @returns The normalised profile, or `undefined` if no stable id was found.
+ */
+export function normalizeUserInfo(provider, payload) {
+    switch (provider) {
+        case "google": {
+            const id = str(payload, "sub");
+            if (id === undefined)
+                return undefined;
+            return profile(id, {
+                ...(str(payload, "email") !== undefined
+                    ? { email: str(payload, "email") }
+                    : {}),
+                ...(bool(payload, "email_verified") !== undefined
+                    ? { emailVerified: bool(payload, "email_verified") }
+                    : {}),
+                ...(str(payload, "name") !== undefined
+                    ? { name: str(payload, "name") }
+                    : {}),
+                ...(str(payload, "picture") !== undefined
+                    ? { avatarUrl: str(payload, "picture") }
+                    : {}),
+            }, payload);
+        }
+        case "github": {
+            const id = str(payload, "id");
+            if (id === undefined)
+                return undefined;
+            const email = str(payload, "email");
+            const name = str(payload, "name") ?? str(payload, "login");
+            return profile(id, {
+                ...(email !== undefined ? { email } : {}),
+                ...(name !== undefined ? { name } : {}),
+                ...(str(payload, "avatar_url") !== undefined
+                    ? { avatarUrl: str(payload, "avatar_url") }
+                    : {}),
+            }, payload);
+        }
+        case "microsoft": {
+            const id = str(payload, "id") ?? str(payload, "sub");
+            if (id === undefined)
+                return undefined;
+            const email = str(payload, "mail") ?? str(payload, "userPrincipalName");
+            const name = str(payload, "displayName") ?? str(payload, "name");
+            return profile(id, {
+                ...(email !== undefined ? { email } : {}),
+                ...(name !== undefined ? { name } : {}),
+            }, payload);
+        }
+        case "discord": {
+            const id = str(payload, "id");
+            if (id === undefined)
+                return undefined;
+            const email = str(payload, "email");
+            const verified = bool(payload, "verified");
+            const name = str(payload, "global_name") ?? str(payload, "username");
+            const avatarHash = str(payload, "avatar");
+            const avatarUrl = avatarHash === undefined
+                ? undefined
+                : `https://cdn.discordapp.com/avatars/${encodeURIComponent(id)}/${encodeURIComponent(avatarHash)}.png`;
+            return profile(id, {
+                ...(email !== undefined ? { email } : {}),
+                ...(email !== undefined && verified !== undefined
+                    ? { emailVerified: verified }
+                    : {}),
+                ...(name !== undefined ? { name } : {}),
+                ...(avatarUrl !== undefined ? { avatarUrl } : {}),
+            }, payload);
+        }
+        case "apple":
+        case "custom": {
+            const id = str(payload, "sub") ?? str(payload, "id");
+            if (id === undefined)
+                return undefined;
+            const name = str(payload, "name") ?? str(payload, "displayName");
+            const avatarUrl = str(payload, "picture") ?? str(payload, "avatar_url");
+            return profile(id, {
+                ...(str(payload, "email") !== undefined
+                    ? { email: str(payload, "email") }
+                    : {}),
+                ...(bool(payload, "email_verified") !== undefined
+                    ? { emailVerified: bool(payload, "email_verified") }
+                    : {}),
+                ...(name !== undefined ? { name } : {}),
+                ...(avatarUrl !== undefined ? { avatarUrl } : {}),
+            }, payload);
+        }
+    }
+}
+//# sourceMappingURL=oauthProvider.presets.js.map

package/dist/oauthSecurity/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Security primitives: PKCE, state, URL guards, defensive JSON parsing.
+ *
+ * @module oauthSecurity
+ */
+export { generateCodeVerifier, assertValidCodeVerifier, deriveCodeChallenge, } from "./oauthPkce.core.js";
+export { generateState, verifyState } from "./oauthState.core.js";
+export { isBlockedFetchHost, assertSafeUrl, type UrlUse, } from "./oauthUrl.guard.js";
+export { sanitizeJsonValue, parseJsonObject, parseJsonValue, } from "./oauthJson.sanitize.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/oauthSecurity/index.js

@@ -0,0 +1,10 @@
+/**
+ * Security primitives: PKCE, state, URL guards, defensive JSON parsing.
+ *
+ * @module oauthSecurity
+ */
+export { generateCodeVerifier, assertValidCodeVerifier, deriveCodeChallenge, } from "./oauthPkce.core.js";
+export { generateState, verifyState } from "./oauthState.core.js";
+export { isBlockedFetchHost, assertSafeUrl, } from "./oauthUrl.guard.js";
+export { sanitizeJsonValue, parseJsonObject, parseJsonValue, } from "./oauthJson.sanitize.js";
+//# sourceMappingURL=index.js.map

package/dist/oauthSecurity/oauthJson.sanitize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Defensive parsing of JSON that came from a provider.
+ *
+ * @module oauthSecurity/oauthJson
+ *
+ * A provider response is untrusted input. `JSON.parse` itself is safe, but
+ * anything that later merges or spreads the result can be steered by
+ * `__proto__`, `constructor` or `prototype` keys, so those keys are stripped
+ * from every object before the payload is handed on. Depth and breadth are
+ * also bounded, so a deeply nested body cannot exhaust the stack.
+ */
+/**
+ * Strip prototype-polluting keys from a JSON-derived object graph.
+ *
+ * @param value - Any value produced by `JSON.parse`.
+ * @returns A structurally identical value with the forbidden keys removed.
+ */
+export declare function sanitizeJsonValue(value: unknown): unknown;
+/**
+ * Parse a provider body as a JSON object and sanitize it.
+ *
+ * @param text - The (already size-capped) response body.
+ * @param label - Endpoint name for the error message. Never a secret.
+ * @returns A plain object with prototype-polluting keys removed.
+ * @throws {OAuthResponseError} If the body is not JSON, or is not an object
+ *   (a top-level array, string, number or `null` is rejected).
+ */
+export declare function parseJsonObject(text: string, label: string): Record<string, unknown>;
+/**
+ * Parse any JSON body and sanitize it, allowing a top-level array.
+ *
+ * Needed for endpoints that legitimately return a list — GitHub's
+ * `/user/emails`, for one.
+ *
+ * @throws {OAuthResponseError} If the body is not valid JSON.
+ */
+export declare function parseJsonValue(text: string, label: string): unknown;
+//# sourceMappingURL=oauthJson.sanitize.d.ts.map

package/dist/oauthSecurity/oauthJson.sanitize.js

@@ -0,0 +1,85 @@
+/**
+ * Defensive parsing of JSON that came from a provider.
+ *
+ * @module oauthSecurity/oauthJson
+ *
+ * A provider response is untrusted input. `JSON.parse` itself is safe, but
+ * anything that later merges or spreads the result can be steered by
+ * `__proto__`, `constructor` or `prototype` keys, so those keys are stripped
+ * from every object before the payload is handed on. Depth and breadth are
+ * also bounded, so a deeply nested body cannot exhaust the stack.
+ */
+import { OAuthResponseError } from "../oauthErrors/index.js";
+/** Keys removed from every object reconstructed from provider JSON. */
+const FORBIDDEN_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/** Maximum nesting depth kept from a provider payload. */
+const MAX_DEPTH = 12;
+function sanitizeValue(value, depth) {
+    if (depth > MAX_DEPTH)
+        return undefined;
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const item of value) {
+            out.push(sanitizeValue(item, depth + 1));
+        }
+        return out;
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (FORBIDDEN_KEYS.has(key))
+                continue;
+            out[key] = sanitizeValue(item, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Strip prototype-polluting keys from a JSON-derived object graph.
+ *
+ * @param value - Any value produced by `JSON.parse`.
+ * @returns A structurally identical value with the forbidden keys removed.
+ */
+export function sanitizeJsonValue(value) {
+    return sanitizeValue(value, 0);
+}
+/**
+ * Parse a provider body as a JSON object and sanitize it.
+ *
+ * @param text - The (already size-capped) response body.
+ * @param label - Endpoint name for the error message. Never a secret.
+ * @returns A plain object with prototype-polluting keys removed.
+ * @throws {OAuthResponseError} If the body is not JSON, or is not an object
+ *   (a top-level array, string, number or `null` is rejected).
+ */
+export function parseJsonObject(text, label) {
+    const sanitized = parseJsonValue(text, label);
+    if (sanitized === null || typeof sanitized !== "object" || Array.isArray(sanitized)) {
+        throw new OAuthResponseError(`${label} did not return a JSON object.`);
+    }
+    return sanitized;
+}
+/**
+ * Parse any JSON body and sanitize it, allowing a top-level array.
+ *
+ * Needed for endpoints that legitimately return a list — GitHub's
+ * `/user/emails`, for one.
+ *
+ * @throws {OAuthResponseError} If the body is not valid JSON.
+ */
+export function parseJsonValue(text, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new OAuthResponseError(`${label} did not return valid JSON.`);
+    }
+    return sanitizeValue(parsed, 0);
+}
+//# sourceMappingURL=oauthJson.sanitize.js.map

package/dist/oauthSecurity/oauthPkce.core.d.ts

@@ -0,0 +1,34 @@
+/**
+ * PKCE (RFC 7636) verifier and challenge handling.
+ *
+ * @module oauthSecurity/oauthPkce
+ *
+ * PKCE is always on and always `S256`. The `plain` method is not implemented
+ * and never will be: it offers no protection against an attacker who can read
+ * the authorization request, which is the threat PKCE exists to address.
+ */
+/**
+ * Generate a cryptographically random PKCE `code_verifier`.
+ *
+ * 48 random bytes rendered as base64url give 64 characters drawn only from
+ * the unreserved alphabet, with 384 bits of entropy and no modulo bias.
+ *
+ * @returns A verifier that satisfies {@link assertValidCodeVerifier}.
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Throw unless `verifier` is a syntactically valid RFC 7636 code verifier.
+ *
+ * @throws {OAuthError} With code `OAUTH_PKCE_INVALID`. The verifier itself is
+ *   a secret and never appears in the message.
+ */
+export declare function assertValidCodeVerifier(verifier: string): void;
+/**
+ * Derive the `S256` code challenge: `base64url(SHA-256(ASCII(verifier)))`.
+ *
+ * @param verifier - A valid code verifier.
+ * @returns The challenge to send as `code_challenge`.
+ * @throws {OAuthError} If the verifier is malformed.
+ */
+export declare function deriveCodeChallenge(verifier: string): string;
+//# sourceMappingURL=oauthPkce.core.d.ts.map

package/dist/oauthSecurity/oauthPkce.core.js

@@ -0,0 +1,47 @@
+/**
+ * PKCE (RFC 7636) verifier and challenge handling.
+ *
+ * @module oauthSecurity/oauthPkce
+ *
+ * PKCE is always on and always `S256`. The `plain` method is not implemented
+ * and never will be: it offers no protection against an attacker who can read
+ * the authorization request, which is the threat PKCE exists to address.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { OAuthError, OAuthErrorCode } from "../oauthErrors/index.js";
+/** RFC 7636 §4.1 — verifiers are 43-128 chars of the unreserved alphabet. */
+const VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]{43,128}$/;
+/**
+ * Generate a cryptographically random PKCE `code_verifier`.
+ *
+ * 48 random bytes rendered as base64url give 64 characters drawn only from
+ * the unreserved alphabet, with 384 bits of entropy and no modulo bias.
+ *
+ * @returns A verifier that satisfies {@link assertValidCodeVerifier}.
+ */
+export function generateCodeVerifier() {
+    return randomBytes(48).toString("base64url");
+}
+/**
+ * Throw unless `verifier` is a syntactically valid RFC 7636 code verifier.
+ *
+ * @throws {OAuthError} With code `OAUTH_PKCE_INVALID`. The verifier itself is
+ *   a secret and never appears in the message.
+ */
+export function assertValidCodeVerifier(verifier) {
+    if (typeof verifier !== "string" || !VERIFIER_PATTERN.test(verifier)) {
+        throw new OAuthError("PKCE code verifier must be 43-128 characters from the unreserved alphabet.", { code: OAuthErrorCode.PKCE_INVALID, statusCode: 400, expose: false });
+    }
+}
+/**
+ * Derive the `S256` code challenge: `base64url(SHA-256(ASCII(verifier)))`.
+ *
+ * @param verifier - A valid code verifier.
+ * @returns The challenge to send as `code_challenge`.
+ * @throws {OAuthError} If the verifier is malformed.
+ */
+export function deriveCodeChallenge(verifier) {
+    assertValidCodeVerifier(verifier);
+    return createHash("sha256").update(verifier, "ascii").digest("base64url");
+}
+//# sourceMappingURL=oauthPkce.core.js.map