@zudojs/auth-oauth 1.1.0

package/dist/oauthClient/oauthHttp.core.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The one place this package talks to a provider.
+ *
+ * @module oauthClient/oauthHttp
+ *
+ * An OAuth provider is an untrusted remote. Every request made here is
+ * bounded three ways:
+ *
+ * - **Time** — `AbortSignal.timeout(config.timeoutMs)`, default 10s.
+ * - **Size** — the body is streamed and abandoned the moment it exceeds
+ *   `config.maxResponseBytes` (default 256 KiB), and a `Content-Length` over
+ *   the cap is refused before reading at all.
+ * - **Reach** — `redirect: "manual"`, so a 3xx cannot walk the request to a
+ *   host that never passed the SSRF guard.
+ */
+import type { ResolvedOAuthConfig } from "./oauthConfig.resolve.js";
+/** One request to a provider endpoint. */
+export interface ProviderRequest {
+    readonly url: URL;
+    readonly method: "GET" | "POST";
+    readonly headers: Record<string, string>;
+    readonly body?: string;
+    /** Endpoint name for error messages. Never contains a secret. */
+    readonly label: string;
+}
+/**
+ * Perform a bounded request and return the parsed, sanitized JSON object.
+ *
+ * A non-2xx status, a 3xx, or a payload carrying an OAuth `error` member all
+ * raise {@link OAuthProviderError}. Only the provider's `error` code reaches
+ * the message, and only after passing a strict character filter — an
+ * `error_description` is never interpolated, so a hostile or misconfigured
+ * provider cannot echo request material into your logs.
+ */
+export declare function requestProviderJson(resolved: ResolvedOAuthConfig, request: ProviderRequest): Promise<Record<string, unknown>>;
+/**
+ * As {@link requestProviderJson}, but allows a top-level JSON array (GitHub's
+ * `/user/emails`). Same time, size and redirect bounds.
+ */
+export declare function requestProviderValue(resolved: ResolvedOAuthConfig, request: ProviderRequest): Promise<unknown>;
+/** Build the `Authorization: Basic` header for client authentication. */
+export declare function basicAuthHeader(clientId: string, clientSecret: string): string;
+//# sourceMappingURL=oauthHttp.core.d.ts.map

package/dist/oauthClient/oauthHttp.core.js

@@ -0,0 +1,137 @@
+/**
+ * The one place this package talks to a provider.
+ *
+ * @module oauthClient/oauthHttp
+ *
+ * An OAuth provider is an untrusted remote. Every request made here is
+ * bounded three ways:
+ *
+ * - **Time** — `AbortSignal.timeout(config.timeoutMs)`, default 10s.
+ * - **Size** — the body is streamed and abandoned the moment it exceeds
+ *   `config.maxResponseBytes` (default 256 KiB), and a `Content-Length` over
+ *   the cap is refused before reading at all.
+ * - **Reach** — `redirect: "manual"`, so a 3xx cannot walk the request to a
+ *   host that never passed the SSRF guard.
+ */
+import { OAuthNetworkError, OAuthProviderError, OAuthResponseError, OAuthResponseTooLargeError, } from "../oauthErrors/index.js";
+import { parseJsonObject, parseJsonValue } from "../oauthSecurity/index.js";
+/** Provider `error` codes are echoed only if they look like OAuth error codes. */
+const SAFE_ERROR_CODE = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** Read a response body, refusing to buffer more than `maxBytes`. */
+async function readCappedText(response, maxBytes) {
+    const declared = response.headers.get("content-length");
+    if (declared !== null && /^\d+$/.test(declared) && Number(declared) > maxBytes) {
+        throw new OAuthResponseTooLargeError(maxBytes);
+    }
+    const body = response.body;
+    if (body === null) {
+        const text = await response.text();
+        if (Buffer.byteLength(text, "utf8") > maxBytes) {
+            throw new OAuthResponseTooLargeError(maxBytes);
+        }
+        return text;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done)
+            break;
+        const value = chunk.value;
+        if (value === undefined)
+            continue;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw new OAuthResponseTooLargeError(maxBytes);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** Extract a provider `error` code that is safe to put in a message. */
+function safeProviderError(payload) {
+    const value = payload?.["error"];
+    if (typeof value === "string" && SAFE_ERROR_CODE.test(value))
+        return value;
+    if (value !== null && typeof value === "object") {
+        const nested = value["code"];
+        if (typeof nested === "string" && SAFE_ERROR_CODE.test(nested))
+            return nested;
+    }
+    return undefined;
+}
+/**
+ * Perform a bounded request and return the parsed, sanitized JSON object.
+ *
+ * A non-2xx status, a 3xx, or a payload carrying an OAuth `error` member all
+ * raise {@link OAuthProviderError}. Only the provider's `error` code reaches
+ * the message, and only after passing a strict character filter — an
+ * `error_description` is never interpolated, so a hostile or misconfigured
+ * provider cannot echo request material into your logs.
+ */
+export async function requestProviderJson(resolved, request) {
+    const value = await requestProviderValue(resolved, request);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new OAuthResponseError(`The ${request.label} endpoint did not return a JSON object.`);
+    }
+    return value;
+}
+/**
+ * As {@link requestProviderJson}, but allows a top-level JSON array (GitHub's
+ * `/user/emails`). Same time, size and redirect bounds.
+ */
+export async function requestProviderValue(resolved, request) {
+    let response;
+    try {
+        response = await resolved.fetchImpl(request.url.toString(), {
+            method: request.method,
+            headers: request.headers,
+            ...(request.body !== undefined ? { body: request.body } : {}),
+            redirect: "manual",
+            signal: AbortSignal.timeout(resolved.timeoutMs),
+        });
+    }
+    catch (cause) {
+        const name = cause instanceof Error ? cause.name : "";
+        const timedOut = name === "TimeoutError" || name === "AbortError";
+        throw new OAuthNetworkError(timedOut
+            ? `The ${request.label} request timed out after ${resolved.timeoutMs}ms.`
+            : `The ${request.label} request could not be completed.`, { cause });
+    }
+    if (response.status >= 300 && response.status < 400) {
+        throw new OAuthProviderError(`The ${request.label} endpoint returned an unexpected redirect.`, { providerStatus: response.status });
+    }
+    const text = await readCappedText(response, resolved.maxResponseBytes);
+    if (!response.ok) {
+        let code;
+        try {
+            code = safeProviderError(parseJsonObject(text, request.label));
+        }
+        catch {
+            code = undefined;
+        }
+        throw new OAuthProviderError(code === undefined
+            ? `The ${request.label} endpoint returned HTTP ${response.status}.`
+            : `The ${request.label} endpoint returned HTTP ${response.status} (${code}).`, {
+            providerStatus: response.status,
+            ...(code !== undefined ? { providerError: code } : {}),
+        });
+    }
+    const payload = parseJsonValue(text, request.label);
+    const code = safeProviderError(payload !== null && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : undefined);
+    if (code !== undefined) {
+        throw new OAuthProviderError(`The ${request.label} endpoint returned an OAuth error (${code}).`, { providerError: code, providerStatus: response.status });
+    }
+    return payload;
+}
+/** Build the `Authorization: Basic` header for client authentication. */
+export function basicAuthHeader(clientId, clientSecret) {
+    // RFC 6749 §2.3.1: both halves are form-urlencoded before base64.
+    const encoded = Buffer.from(`${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`, "utf8").toString("base64");
+    return `Basic ${encoded}`;
+}
+//# sourceMappingURL=oauthHttp.core.js.map

package/dist/oauthClient/oauthToken.core.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Token exchange, token-response validation, and refresh.
+ *
+ * @module oauthClient/oauthToken
+ */
+import type { CodeExchangeOptions, OAuthConfig, OAuthTokenSet } from "../oauthTypes/index.js";
+/**
+ * Validate a token-endpoint payload into an {@link OAuthTokenSet}.
+ *
+ * Rejects: a non-object body (caught earlier by the JSON parser), a missing,
+ * non-string or blank `access_token`, a non-numeric `expires_in`, and a
+ * non-string `refresh_token` / `id_token` / `scope`. Prototype-polluting keys
+ * were already stripped by {@link parseJsonObject}.
+ *
+ * Exported for the response-validation tests; also useful if you have a token
+ * payload from elsewhere.
+ *
+ * @throws {OAuthResponseError} On any malformed field. The message never
+ *   contains the payload.
+ */
+export declare function parseTokenResponse(payload: Record<string, unknown>): OAuthTokenSet;
+/**
+ * Exchange an authorization code for tokens.
+ *
+ * POSTs `application/x-www-form-urlencoded` with
+ * `grant_type=authorization_code`, the `code`, the allowlisted `redirect_uri`
+ * and the PKCE `code_verifier`. The client secret travels either in the
+ * `Authorization: Basic` header or in the body, whichever the provider
+ * expects — never in the URL, where it would land in access logs.
+ *
+ * @throws {OAuthRedirectUriError} If `redirectUri` is not allowlisted.
+ * @throws {OAuthProviderError} If the provider rejects the exchange.
+ * @throws {OAuthResponseError} If the token payload is malformed.
+ * @throws {OAuthNetworkError} On timeout or transport failure.
+ */
+export declare function exchangeCodeForToken(config: OAuthConfig, options: CodeExchangeOptions): Promise<OAuthTokenSet>;
+/**
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Refused for providers that do not issue refresh tokens on this flow —
+ * classic GitHub OAuth App tokens do not expire and GitHub issues none, so
+ * calling this for `github` throws rather than making a pointless request.
+ *
+ * Note that most providers do not return a new `refresh_token`; keep using
+ * the old one unless the response carries a replacement.
+ *
+ * @throws {OAuthConfigurationError} If the provider has no refresh support.
+ */
+export declare function refreshAccessToken(config: OAuthConfig, refreshToken: string): Promise<OAuthTokenSet>;
+//# sourceMappingURL=oauthToken.core.d.ts.map

package/dist/oauthClient/oauthToken.core.js

@@ -0,0 +1,171 @@
+/**
+ * Token exchange, token-response validation, and refresh.
+ *
+ * @module oauthClient/oauthToken
+ */
+import { OAuthConfigurationError, OAuthResponseError, } from "../oauthErrors/index.js";
+import { assertValidCodeVerifier } from "../oauthSecurity/index.js";
+import { assertRedirectUriAllowed, resolveConfig, resolveTokenUrl, } from "./oauthConfig.resolve.js";
+import { basicAuthHeader, requestProviderJson } from "./oauthHttp.core.js";
+/** Coerce a provider `expires_in` to seconds, or reject it. */
+function readExpiresIn(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+            throw new OAuthResponseError("The token endpoint returned a non-numeric expires_in.");
+        }
+        return value;
+    }
+    if (typeof value === "string" && /^\d{1,15}$/.test(value)) {
+        return Number(value);
+    }
+    throw new OAuthResponseError("The token endpoint returned a non-numeric expires_in.");
+}
+function optionalString(payload, key) {
+    const value = payload[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0) {
+        throw new OAuthResponseError(`The token endpoint returned a malformed ${key}.`);
+    }
+    return value;
+}
+/**
+ * Validate a token-endpoint payload into an {@link OAuthTokenSet}.
+ *
+ * Rejects: a non-object body (caught earlier by the JSON parser), a missing,
+ * non-string or blank `access_token`, a non-numeric `expires_in`, and a
+ * non-string `refresh_token` / `id_token` / `scope`. Prototype-polluting keys
+ * were already stripped by {@link parseJsonObject}.
+ *
+ * Exported for the response-validation tests; also useful if you have a token
+ * payload from elsewhere.
+ *
+ * @throws {OAuthResponseError} On any malformed field. The message never
+ *   contains the payload.
+ */
+export function parseTokenResponse(payload) {
+    const accessToken = payload["access_token"];
+    if (typeof accessToken !== "string" || accessToken.trim().length === 0) {
+        throw new OAuthResponseError("The token endpoint returned no usable access_token.");
+    }
+    const tokenTypeRaw = payload["token_type"];
+    if (tokenTypeRaw !== undefined && typeof tokenTypeRaw !== "string") {
+        throw new OAuthResponseError("The token endpoint returned a malformed token_type.");
+    }
+    const expiresIn = readExpiresIn(payload["expires_in"]);
+    const refreshToken = optionalString(payload, "refresh_token");
+    const idToken = optionalString(payload, "id_token");
+    const scopeRaw = payload["scope"];
+    let scope;
+    if (scopeRaw !== undefined && scopeRaw !== null) {
+        if (typeof scopeRaw !== "string") {
+            throw new OAuthResponseError("The token endpoint returned a malformed scope.");
+        }
+        const parts = scopeRaw.split(/[\s,]+/).filter((part) => part.length > 0);
+        if (parts.length > 0)
+            scope = parts;
+    }
+    return {
+        accessToken,
+        tokenType: tokenTypeRaw !== undefined && tokenTypeRaw.length > 0
+            ? tokenTypeRaw
+            : "Bearer",
+        ...(expiresIn !== undefined ? { expiresIn } : {}),
+        ...(refreshToken !== undefined ? { refreshToken } : {}),
+        ...(scope !== undefined ? { scope } : {}),
+        ...(idToken !== undefined ? { idToken } : {}),
+        raw: payload,
+    };
+}
+/** Build the token-request body and headers for the configured client auth. */
+function tokenRequestParts(resolved, form) {
+    const headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+    };
+    if (resolved.clientAuth === "basic") {
+        headers["Authorization"] = basicAuthHeader(resolved.clientId, resolved.clientSecret);
+        form.set("client_id", resolved.clientId);
+    }
+    else {
+        form.set("client_id", resolved.clientId);
+        form.set("client_secret", resolved.clientSecret);
+    }
+    return { headers, body: form.toString() };
+}
+/**
+ * Exchange an authorization code for tokens.
+ *
+ * POSTs `application/x-www-form-urlencoded` with
+ * `grant_type=authorization_code`, the `code`, the allowlisted `redirect_uri`
+ * and the PKCE `code_verifier`. The client secret travels either in the
+ * `Authorization: Basic` header or in the body, whichever the provider
+ * expects — never in the URL, where it would land in access logs.
+ *
+ * @throws {OAuthRedirectUriError} If `redirectUri` is not allowlisted.
+ * @throws {OAuthProviderError} If the provider rejects the exchange.
+ * @throws {OAuthResponseError} If the token payload is malformed.
+ * @throws {OAuthNetworkError} On timeout or transport failure.
+ */
+export async function exchangeCodeForToken(config, options) {
+    const resolved = resolveConfig(config);
+    if (typeof options.code !== "string" || options.code.trim().length === 0) {
+        throw new OAuthConfigurationError("An authorization code is required.");
+    }
+    assertValidCodeVerifier(options.codeVerifier);
+    const redirectUri = assertRedirectUriAllowed(resolved, options.redirectUri);
+    const url = resolveTokenUrl(resolved);
+    const form = new URLSearchParams();
+    form.set("grant_type", "authorization_code");
+    form.set("code", options.code);
+    form.set("redirect_uri", redirectUri);
+    form.set("code_verifier", options.codeVerifier);
+    const { headers, body } = tokenRequestParts(resolved, form);
+    const payload = await requestProviderJson(resolved, {
+        url,
+        method: "POST",
+        headers,
+        body,
+        label: "token",
+    });
+    return parseTokenResponse(payload);
+}
+/**
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Refused for providers that do not issue refresh tokens on this flow —
+ * classic GitHub OAuth App tokens do not expire and GitHub issues none, so
+ * calling this for `github` throws rather than making a pointless request.
+ *
+ * Note that most providers do not return a new `refresh_token`; keep using
+ * the old one unless the response carries a replacement.
+ *
+ * @throws {OAuthConfigurationError} If the provider has no refresh support.
+ */
+export async function refreshAccessToken(config, refreshToken) {
+    const resolved = resolveConfig(config);
+    if (!resolved.preset.supportsRefresh) {
+        throw new OAuthConfigurationError("This provider does not issue refresh tokens for the authorization-code flow.");
+    }
+    if (typeof refreshToken !== "string" || refreshToken.trim().length === 0) {
+        throw new OAuthConfigurationError("A refresh token is required.");
+    }
+    const url = resolveTokenUrl(resolved);
+    const form = new URLSearchParams();
+    form.set("grant_type", "refresh_token");
+    form.set("refresh_token", refreshToken);
+    if (resolved.scopes.length > 0)
+        form.set("scope", resolved.scopes.join(" "));
+    const { headers, body } = tokenRequestParts(resolved, form);
+    const payload = await requestProviderJson(resolved, {
+        url,
+        method: "POST",
+        headers,
+        body,
+        label: "token",
+    });
+    return parseTokenResponse(payload);
+}
+//# sourceMappingURL=oauthToken.core.js.map

package/dist/oauthClient/oauthUserInfo.core.d.ts

@@ -0,0 +1,27 @@
+/**
+ * User-info retrieval and normalisation.
+ *
+ * @module oauthClient/oauthUserInfo
+ */
+import type { OAuthConfig, OAuthUserInfo } from "../oauthTypes/index.js";
+/**
+ * Fetch and normalise the authenticated user's profile.
+ *
+ * The access token is sent as `Authorization: Bearer` — never as a query
+ * parameter, where it would be captured by proxy and server logs.
+ *
+ * `email` is optional in the result on purpose: GitHub omits it for private
+ * addresses (this function then tries `/user/emails`, which needs the
+ * `user:email` scope) and Discord omits it without the `email` scope. If you
+ * key accounts by email, check for its absence and tell the user to grant the
+ * scope — do not fall back to a synthesised address.
+ *
+ * Apple has no user-info endpoint at all; for `apple` this throws an
+ * `OAuthConfigurationError` pointing you at the `id_token`.
+ *
+ * @throws {OAuthConfigurationError} If the provider has no user-info endpoint.
+ * @throws {OAuthProviderError} If the provider rejects the request.
+ * @throws {OAuthResponseError} If the payload has no usable user id.
+ */
+export declare function fetchUserInfo(config: OAuthConfig, accessToken: string): Promise<OAuthUserInfo>;
+//# sourceMappingURL=oauthUserInfo.core.d.ts.map

package/dist/oauthClient/oauthUserInfo.core.js

@@ -0,0 +1,104 @@
+/**
+ * User-info retrieval and normalisation.
+ *
+ * @module oauthClient/oauthUserInfo
+ */
+import { OAuthResponseError } from "../oauthErrors/index.js";
+import { normalizeUserInfo } from "../oauthProviders/index.js";
+import { assertSafeUrl } from "../oauthSecurity/index.js";
+import { resolveConfig, resolveUserInfoUrl, } from "./oauthConfig.resolve.js";
+import { requestProviderJson, requestProviderValue, } from "./oauthHttp.core.js";
+/**
+ * GitHub's `/user` omits `email` whenever the address is private — which is
+ * the default for new accounts. When `user:email` was granted we ask
+ * `/user/emails` for the primary, verified address; otherwise the profile
+ * comes back without an email and the caller decides what to do. No address
+ * is ever synthesised from the login name.
+ */
+async function fetchGithubPrimaryEmail(resolved, userInfoUrl, accessToken) {
+    const emailsUrl = assertSafeUrl(new URL("/user/emails", userInfoUrl.origin).toString(), "userInfoUrl", "fetch");
+    let payload;
+    try {
+        payload = await requestProviderValue(resolved, {
+            url: emailsUrl,
+            method: "GET",
+            headers: userInfoHeaders(resolved, accessToken),
+            label: "user-info",
+        });
+    }
+    catch {
+        // The scope may not have been granted; that is not an auth failure.
+        return undefined;
+    }
+    return readEmailArray(payload);
+}
+function readEmailArray(payload) {
+    if (!Array.isArray(payload))
+        return undefined;
+    for (const entry of payload) {
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const record = entry;
+        const email = record["email"];
+        if (typeof email !== "string" || email.length === 0)
+            continue;
+        if (record["primary"] === true && record["verified"] === true) {
+            return { email, verified: true };
+        }
+    }
+    return undefined;
+}
+function userInfoHeaders(resolved, accessToken) {
+    return {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+        "User-Agent": "zudojs-auth-oauth",
+        ...(resolved.preset.userInfoHeaders ?? {}),
+    };
+}
+/**
+ * Fetch and normalise the authenticated user's profile.
+ *
+ * The access token is sent as `Authorization: Bearer` — never as a query
+ * parameter, where it would be captured by proxy and server logs.
+ *
+ * `email` is optional in the result on purpose: GitHub omits it for private
+ * addresses (this function then tries `/user/emails`, which needs the
+ * `user:email` scope) and Discord omits it without the `email` scope. If you
+ * key accounts by email, check for its absence and tell the user to grant the
+ * scope — do not fall back to a synthesised address.
+ *
+ * Apple has no user-info endpoint at all; for `apple` this throws an
+ * `OAuthConfigurationError` pointing you at the `id_token`.
+ *
+ * @throws {OAuthConfigurationError} If the provider has no user-info endpoint.
+ * @throws {OAuthProviderError} If the provider rejects the request.
+ * @throws {OAuthResponseError} If the payload has no usable user id.
+ */
+export async function fetchUserInfo(config, accessToken) {
+    const resolved = resolveConfig(config);
+    if (typeof accessToken !== "string" || accessToken.trim().length === 0) {
+        throw new OAuthResponseError("An access token is required.");
+    }
+    const url = resolveUserInfoUrl(resolved);
+    const payload = await requestProviderJson(resolved, {
+        url,
+        method: "GET",
+        headers: userInfoHeaders(resolved, accessToken),
+        label: "user-info",
+    });
+    const info = normalizeUserInfo(resolved.provider, payload);
+    if (info === undefined) {
+        throw new OAuthResponseError("The user-info endpoint returned no stable user identifier.");
+    }
+    if (resolved.provider === "github" &&
+        info.email === undefined &&
+        resolved.scopes.includes("user:email")) {
+        const primary = await fetchGithubPrimaryEmail(resolved, url, accessToken);
+        if (primary !== undefined) {
+            return { ...info, email: primary.email, emailVerified: primary.verified };
+        }
+    }
+    return info;
+}
+//# sourceMappingURL=oauthUserInfo.core.js.map

package/dist/oauthErrors/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * OAuth2 error classes and codes.
+ *
+ * @module oauthErrors
+ */
+export { OAuthErrorCode, type OAuthErrorOptions, OAuthError, OAuthConfigurationError, OAuthEndpointNotAllowedError, OAuthRedirectUriError, OAuthStateMismatchError, OAuthProviderError, OAuthResponseError, OAuthResponseTooLargeError, OAuthNetworkError, } from "./oauthError.base.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/oauthErrors/index.js

@@ -0,0 +1,7 @@
+/**
+ * OAuth2 error classes and codes.
+ *
+ * @module oauthErrors
+ */
+export { OAuthErrorCode, OAuthError, OAuthConfigurationError, OAuthEndpointNotAllowedError, OAuthRedirectUriError, OAuthStateMismatchError, OAuthProviderError, OAuthResponseError, OAuthResponseTooLargeError, OAuthNetworkError, } from "./oauthError.base.js";
+//# sourceMappingURL=index.js.map

package/dist/oauthErrors/oauthError.base.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 declare const OAuthErrorCode: {
+    /** The config is unusable: missing field, bad URL, unsupported operation. */
+    readonly CONFIGURATION_INVALID: "OAUTH_CONFIGURATION_INVALID";
+    /** A URL failed the scheme / credential / SSRF guard. */
+    readonly ENDPOINT_NOT_ALLOWED: "OAUTH_ENDPOINT_NOT_ALLOWED";
+    /** The redirect URI is not in the caller's allowlist. */
+    readonly REDIRECT_URI_NOT_ALLOWED: "OAUTH_REDIRECT_URI_NOT_ALLOWED";
+    /** `state` did not match, was absent, or was malformed. */
+    readonly STATE_MISMATCH: "OAUTH_STATE_MISMATCH";
+    /** A PKCE verifier was malformed. */
+    readonly PKCE_INVALID: "OAUTH_PKCE_INVALID";
+    /** The provider returned a non-2xx or an OAuth `error` payload. */
+    readonly PROVIDER_REJECTED: "OAUTH_PROVIDER_REJECTED";
+    /** The provider's response was unparseable or structurally invalid. */
+    readonly PROVIDER_RESPONSE_INVALID: "OAUTH_PROVIDER_RESPONSE_INVALID";
+    /** The response body exceeded the configured cap. */
+    readonly RESPONSE_TOO_LARGE: "OAUTH_RESPONSE_TOO_LARGE";
+    /** The request timed out or the transport failed. */
+    readonly NETWORK: "OAUTH_NETWORK";
+};
+/** Union of {@link OAuthErrorCode} values. */
+export type OAuthErrorCode = (typeof OAuthErrorCode)[keyof typeof OAuthErrorCode];
+/** Options accepted by {@link OAuthError} and every subclass. */
+export interface OAuthErrorOptions {
+    readonly code?: OAuthErrorCode;
+    readonly statusCode?: number;
+    readonly expose?: boolean;
+    readonly cause?: unknown;
+}
+/**
+ * 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 declare class OAuthError extends Error {
+    readonly name: string;
+    /** Machine-readable code. */
+    readonly code: OAuthErrorCode;
+    /** Suggested HTTP status for a handler that surfaces this. */
+    readonly statusCode: number;
+    /** Whether `message` is safe to return to a client verbatim. */
+    readonly expose: boolean;
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+/** The configuration is missing something or is structurally unusable. */
+export declare class OAuthConfigurationError extends OAuthError {
+    readonly name: string;
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+/**
+ * An endpoint URL is not an acceptable target: wrong scheme, embedded
+ * credentials, or a private / loopback / link-local / metadata host.
+ */
+export declare class OAuthEndpointNotAllowedError extends OAuthError {
+    readonly name: string;
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+/** The requested redirect URI is not in `config.allowedRedirectUris`. */
+export declare class OAuthRedirectUriError extends OAuthError {
+    readonly name: string;
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+/** The callback's `state` did not match the one that was issued. */
+export declare class OAuthStateMismatchError extends OAuthError {
+    readonly name: string;
+    constructor(message?: string, options?: OAuthErrorOptions);
+}
+/** The provider refused the request. */
+export declare class OAuthProviderError extends OAuthError {
+    readonly name: string;
+    /** The provider's OAuth `error` code, if it sent a well-formed one. */
+    readonly providerError?: string;
+    /** The provider's HTTP status, if the exchange got that far. */
+    readonly providerStatus?: number;
+    constructor(message: string, options?: OAuthErrorOptions & {
+        readonly providerError?: string;
+        readonly providerStatus?: number;
+    });
+}
+/** The provider's response was not a usable OAuth2 payload. */
+export declare class OAuthResponseError extends OAuthError {
+    readonly name: string;
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+/** The provider's response body exceeded `maxResponseBytes`. */
+export declare class OAuthResponseTooLargeError extends OAuthError {
+    readonly name: string;
+    constructor(limitBytes: number, options?: OAuthErrorOptions);
+}
+/** The request timed out or the transport failed. */
+export declare class OAuthNetworkError extends OAuthError {
+    readonly name: string;
+    constructor(message: string, options?: OAuthErrorOptions);
+}
+//# sourceMappingURL=oauthError.base.d.ts.map