@udibo/oauth2 0.1.0

package/esm/identity/external/_shared.js

@@ -0,0 +1,107 @@
+/**
+ * Internal helpers shared by the external-provider connectors.
+ *
+ * Not part of the public API — reach for a connector from
+ * `@udibo/oauth2/identity/external` instead, which re-exports the one type an
+ * adopter configures ({@link AzpPolicy}). These live here so the same failure
+ * reads the same way whichever connector hit it: one error renderer, one
+ * error-body reader, one provider-text sanitizer, and one id_token claim gate
+ * rather than a copy per provider. The token exchange itself is
+ * `_token-exchange.ts`.
+ *
+ * @module
+ */
+import { isOAuth2Error } from "../../errors.js";
+import { timingSafeEqualString } from "../../utils/crypto.js";
+import { PROVIDER_TEXT_MAX_LENGTH, sanitizeProviderText, } from "../../utils/text.js";
+import { ExternalAuthError } from "./errors.js";
+export { PROVIDER_TEXT_MAX_LENGTH, sanitizeProviderText };
+/**
+ * Clock-skew allowance, in seconds, when checking an id_token's `exp` claim.
+ * The default for {@link assertIdTokenClaims}.
+ */
+export const ID_TOKEN_EXPIRY_LEEWAY_SECONDS = 120;
+/**
+ * Renders a thrown value for an error message, unwrapping an OAuth2 error into
+ * its `error` / `error_description` extensions so a provider-reported failure
+ * is quoted rather than buried in a generic message. Every branch is
+ * {@link sanitizeProviderText}-bounded: the thrown value routinely carries
+ * provider bytes — a JSON parse error quotes the body it choked on, and an
+ * OAuth2 error carries a description the provider wrote.
+ */
+export function describeError(error) {
+    if (isOAuth2Error(error)) {
+        const code = sanitizeProviderText(error.extensions.error ?? "server_error");
+        const description = sanitizeProviderText(error.extensions.error_description ?? error.message);
+        return description && description !== code
+            ? `${code}: ${description}`
+            : code;
+    }
+    return sanitizeProviderText(error instanceof Error ? error.message : String(error));
+}
+/**
+ * Reads a failed response's body into a bounded, single-line `": <text>"`
+ * suffix to append to an error message, or `""` when the body is empty or
+ * unreadable. Consumes the body, so the caller must not read it again.
+ */
+export async function readErrorBody(res) {
+    try {
+        const snippet = sanitizeProviderText(await res.text());
+        return snippet ? `: ${snippet}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Drops one trailing `"/"` so issuer URLs compare and concatenate consistently
+ * (`"https://x/"` and `"https://x"` identify the same issuer).
+ */
+export function stripTrailingSlash(value) {
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+/**
+ * Enforces the id_token claim rules of OpenID Connect Core §3.1.3.7 that do not
+ * depend on the signature: `iss`, `aud`, `azp`, `exp`, and `nonce`, in that
+ * order. Callers verify the signature (or establish the token's provenance)
+ * themselves before calling this.
+ *
+ * Throws {@link ExternalAuthError} with code `nonce_mismatch` when the `nonce`
+ * claim does not match, and `provider_error` for every other rule.
+ */
+export function assertIdTokenClaims(input) {
+    const { provider, claims, issuer, clientId, expectedNonce } = input;
+    if (claims.iss !== issuer) {
+        throw new ExternalAuthError(provider, "provider_error", `id_token "iss" is "${String(claims.iss)}" but the expected issuer is ` +
+            `"${issuer}" — the token was issued by a different provider, or the ` +
+            `configured issuer points at a proxy or the wrong tenant.`);
+    }
+    const aud = claims.aud;
+    const audienceOk = aud === clientId ||
+        (Array.isArray(aud) && aud.includes(clientId));
+    if (!audienceOk) {
+        throw new ExternalAuthError(provider, "provider_error", `id_token "aud" (${JSON.stringify(aud)}) does not include clientId ` +
+            `"${clientId}" — the token was issued to a different client ` +
+            `registration.`);
+    }
+    const audienceCount = Array.isArray(aud) ? aud.length : 1;
+    if ((input.azp ?? "conditional") === "conditional" &&
+        (audienceCount > 1 || claims.azp !== undefined) &&
+        claims.azp !== clientId) {
+        throw new ExternalAuthError(provider, "provider_error", `id_token "azp" (${JSON.stringify(claims.azp)}) is not this clientId ` +
+            `"${clientId}" — the token's authorized party is a different client ` +
+            `(OpenID Connect Core §3.1.3.7).`);
+    }
+    const exp = claims.exp;
+    const leewaySeconds = input.leewaySeconds ?? ID_TOKEN_EXPIRY_LEEWAY_SECONDS;
+    if (typeof exp !== "number" || Date.now() / 1000 > exp + leewaySeconds) {
+        throw new ExternalAuthError(provider, "provider_error", `id_token is expired or has no "exp" claim (exp=${JSON.stringify(exp)}) — reject per OpenID Connect Core §3.1.3.7. Ask the user to start ` +
+            `again.`);
+    }
+    if (expectedNonce !== undefined &&
+        !(typeof claims.nonce === "string" &&
+            timingSafeEqualString(claims.nonce, expectedNonce))) {
+        throw new ExternalAuthError(provider, "nonce_mismatch", `id_token "nonce" does not match this sign-in attempt — possible token ` +
+            `replay or a mixed-up callback. Ask the user to start again.`);
+    }
+}

package/esm/identity/external/_token-exchange.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The `authorization_code` token exchange the plain-OAuth2 connectors post
+ * through — {@link githubProvider}, {@link oauth2Provider} (and its
+ * {@link discordProvider} preset), and {@link appleProvider}.
+ * {@link oidcProvider}, and {@link googleProvider} on top of it, exchange via
+ * `OAuth2Client` instead and do not reach this module.
+ *
+ * Not part of the public API. Split out of `_shared.ts` so the ladder — the one
+ * place a provider's bytes become an error message or a token — sits next to
+ * the tests that pin it.
+ *
+ * @module
+ */
+/** Response bytes accepted from a token endpoint before the exchange is refused. */
+export declare const MAX_TOKEN_RESPONSE_BYTES: number;
+/** Wall-clock budget for the exchange, covering the connect and the body read. */
+export declare const TOKEN_EXCHANGE_TIMEOUT_MS = 10000;
+/** Input for {@link runTokenExchange}. */
+export interface TokenExchangeInput {
+    /** Provider id carried on every thrown {@link ExternalAuthError}. */
+    provider: string;
+    /** Human-readable provider name used in the error messages. */
+    displayName: string;
+    /** The provider's token endpoint. */
+    endpoint: string;
+    /** The form body to POST; client authentication must already be in it. */
+    body: URLSearchParams;
+    /**
+     * The token-response field the connector cannot proceed without — usually
+     * `"access_token"`, or `"id_token"` for a connector that only reads claims.
+     */
+    requiredField: string;
+    /**
+     * Fetch implementation for the exchange. A wrapper **must forward the whole
+     * `RequestInit`** — `redirect` and `signal` in particular. They are the only
+     * channel the redirect refusal and the deadline reach the transport, so a
+     * wrapper that rebuilds `init` from scratch silently reopens the credential
+     * replay hole. `createGuardedFetch` forwards both.
+     */
+    fetch: typeof fetch;
+    /** Guidance appended when a failure carries no OAuth2 error code. */
+    httpErrorHint: string;
+    /** Guidance appended for the OAuth2 error code the provider reported. */
+    tokenErrorHint: (code: string | undefined) => string;
+    /** Exchange deadline. Defaults to {@link TOKEN_EXCHANGE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** A token response that cleared every step of {@link runTokenExchange}. */
+export interface TokenExchangeResult {
+    /** The value of {@link TokenExchangeInput.requiredField}, non-empty. */
+    value: string;
+    /** The full token-response body, for provider-specific fields. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Posts the authorization code and returns a token response known to be a JSON
+ * object carrying `requiredField`. Every failure throws
+ * {@link ExternalAuthError} `provider_error`; a redirect is refused rather than
+ * followed, so the client credentials are never replayed to another host.
+ */
+export declare function runTokenExchange(input: TokenExchangeInput): Promise<TokenExchangeResult>;

package/esm/identity/external/_token-exchange.js

@@ -0,0 +1,179 @@
+/**
+ * The `authorization_code` token exchange the plain-OAuth2 connectors post
+ * through — {@link githubProvider}, {@link oauth2Provider} (and its
+ * {@link discordProvider} preset), and {@link appleProvider}.
+ * {@link oidcProvider}, and {@link googleProvider} on top of it, exchange via
+ * `OAuth2Client` instead and do not reach this module.
+ *
+ * Not part of the public API. Split out of `_shared.ts` so the ladder — the one
+ * place a provider's bytes become an error message or a token — sits next to
+ * the tests that pin it.
+ *
+ * @module
+ */
+import { describeError, sanitizeProviderText } from "./_shared.js";
+import { ExternalAuthError } from "./errors.js";
+/** Response bytes accepted from a token endpoint before the exchange is refused. */
+export const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+/** Wall-clock budget for the exchange, covering the connect and the body read. */
+export const TOKEN_EXCHANGE_TIMEOUT_MS = 10_000;
+/**
+ * Posts the authorization code and returns a token response known to be a JSON
+ * object carrying `requiredField`. Every failure throws
+ * {@link ExternalAuthError} `provider_error`; a redirect is refused rather than
+ * followed, so the client credentials are never replayed to another host.
+ */
+export async function runTokenExchange(input) {
+    const { provider, displayName, requiredField } = input;
+    const fail = (message, options) => new ExternalAuthError(provider, "provider_error", message, options);
+    let res;
+    try {
+        res = await input.fetch(input.endpoint, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: input.body,
+            redirect: "manual",
+            signal: AbortSignal.timeout(input.timeoutMs ?? TOKEN_EXCHANGE_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw fail(`could not reach the ${displayName} token endpoint ` +
+            `(${describeError(error)}). Try again.`, { cause: error });
+    }
+    if (isRedirect(res)) {
+        await res.body?.cancel();
+        throw fail(`token endpoint answered with a redirect (HTTP ${res.status}), which ` +
+            `this exchange refuses to follow — replaying the client credentials ` +
+            `to another host would leak them. Point the connector at the ` +
+            `${displayName} token endpoint directly.`);
+    }
+    let body = { text: "", oversized: false };
+    let readError;
+    try {
+        body = await readBoundedBody(res);
+    }
+    catch (error) {
+        readError = error;
+    }
+    if (!res.ok) {
+        const reported = reportedOAuth2Error(safeParseJson(body.text));
+        if (reported) {
+            throw fail(`token endpoint responded with HTTP ${res.status}: ` +
+                `"${reported.code}"${reported.description}${reported.uri}. ` +
+                `${input.tokenErrorHint(reported.code)} ${input.httpErrorHint}`);
+        }
+        throw fail(`token endpoint responded with HTTP ${res.status}` +
+            `${errorBodySuffix(body.text)}${body.oversized ? " (truncated)" : ""}` +
+            `. ${input.httpErrorHint}`);
+    }
+    if (readError) {
+        throw fail(`the ${displayName} token endpoint response could not be read ` +
+            `(${describeError(readError)}).`, { cause: readError });
+    }
+    if (body.oversized) {
+        throw fail(`the ${displayName} token endpoint response exceeded ` +
+            `${MAX_TOKEN_RESPONSE_BYTES} bytes — refusing to parse a token ` +
+            `response this large.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body.text);
+    }
+    catch (error) {
+        throw fail(`the ${displayName} token endpoint returned ` +
+            `${describeMediaType(res)} that was not valid JSON ` +
+            `(${describeError(error)}).`, { cause: error });
+    }
+    if (!isJsonObject(parsed)) {
+        throw fail(`the ${displayName} token endpoint returned ` +
+            `${describeJsonValue(parsed)} where a JSON object was required.`);
+    }
+    const reported = reportedOAuth2Error(parsed);
+    const value = parsed[requiredField];
+    if (reported || typeof value !== "string" || value.length === 0) {
+        const code = reported?.code ?? `missing ${requiredField}`;
+        throw fail(`token exchange failed: "${code}"${reported?.description ?? ""}` +
+            `${reported?.uri ?? ""}. ${input.tokenErrorHint(reported?.code)}`);
+    }
+    return { value, raw: parsed };
+}
+async function readBoundedBody(res) {
+    if (!res.body)
+        return { text: "", oversized: false };
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    let oversized = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (size + value.byteLength > MAX_TOKEN_RESPONSE_BYTES) {
+                oversized = true;
+                break;
+            }
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const buffer = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        buffer.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { text: new TextDecoder().decode(buffer), oversized };
+}
+function reportedOAuth2Error(value) {
+    if (!isJsonObject(value))
+        return null;
+    const code = sanitizeProviderText(asString(value.error) ?? "");
+    if (!code)
+        return null;
+    const description = sanitizeProviderText(asString(value.error_description) ?? "");
+    const uri = sanitizeProviderText(asString(value.error_uri) ?? "");
+    return {
+        code,
+        description: description ? ` (${description})` : "",
+        uri: uri ? ` [${uri}]` : "",
+    };
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function errorBodySuffix(text) {
+    const snippet = sanitizeProviderText(text);
+    return snippet ? `: ${snippet}` : "";
+}
+function safeParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRedirect(res) {
+    return res.status >= 300 && res.status < 400;
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeJsonValue(value) {
+    if (value === null)
+        return "JSON null";
+    if (Array.isArray(value))
+        return "a JSON array";
+    return `a JSON ${typeof value}`;
+}
+function describeMediaType(res) {
+    const contentType = sanitizeProviderText(res.headers.get("content-type")?.split(";")[0] ?? "");
+    return contentType ? `a "${contentType}" response` : "a response";
+}

package/esm/identity/external/apple-client-secret.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Sign in with Apple client-secret generation. Apple's "client secret" is not a
+ * static string but a short-lived ES256 JWT the app signs from its `.p8`
+ * private key — {@link generateAppleClientSecret} builds one,
+ * {@link createAppleClientSecretFactory} caches and renews it before expiry.
+ *
+ * @module
+ */
+/** Apple's audience for the client-secret JWT. */
+export declare const APPLE_AUDIENCE = "https://appleid.apple.com";
+/** Apple's hard cap on the client secret's lifetime: 6 months, in seconds. */
+export declare const APPLE_CLIENT_SECRET_MAX_TTL_SECONDS = 15777000;
+/** Default client-secret lifetime: ~180 days, comfortably under Apple's cap. */
+export declare const DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS = 15552000;
+/** The Apple developer key material a client secret is signed from. */
+export interface AppleClientSecretOptions {
+    /**
+     * The 10-character Apple Team ID (`iss`). Found top-right in the Apple
+     * Developer account membership page — not the App ID.
+     */
+    teamId: string;
+    /**
+     * The Key ID (`kid`) of the `.p8` signing key, from Certificates,
+     * Identifiers & Profiles → Keys.
+     */
+    keyId: string;
+    /**
+     * The Services ID (`sub`), i.e. the client id the token is for — the
+     * identifier configured for "Sign in with Apple" on the web, not the app's
+     * bundle id.
+     */
+    clientId: string;
+    /**
+     * The PKCS#8 PEM contents of the `.p8` private key downloaded from Apple
+     * (downloadable once). Both the full `-----BEGIN PRIVATE KEY-----` block and
+     * the bare base64 body are accepted.
+     */
+    privateKey: string;
+    /**
+     * Lifetime of the generated secret in seconds. Defaults to
+     * {@link DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS}; must not exceed
+     * {@link APPLE_CLIENT_SECRET_MAX_TTL_SECONDS}.
+     */
+    expiresInSeconds?: number;
+    /** Provider id used in error messages. Defaults to `"apple"`. */
+    providerId?: string;
+}
+/**
+ * Generate a single Sign in with Apple client secret: an ES256 JWT with
+ * `iss` = team id, `sub` = client id (Services ID), `aud` = Apple, and an `exp`
+ * bounded by {@link APPLE_CLIENT_SECRET_MAX_TTL_SECONDS}. Prefer
+ * {@link createAppleClientSecretFactory} in a long-lived process so the secret
+ * is cached and renewed rather than re-signed on every sign-in.
+ *
+ * @throws {ExternalAuthError} `configuration` naming the offending input when
+ *   the team id / key id / client id is empty, the `.p8` is not a valid P-256
+ *   key, or the requested TTL exceeds Apple's cap.
+ *
+ * @example
+ * ```ts
+ * const secret = await generateAppleClientSecret({
+ *   teamId: "ABCDE12345",
+ *   keyId: "KEY1234567",
+ *   clientId: "com.example.web",
+ *   privateKey: Deno.env.get("APPLE_PRIVATE_KEY")!,
+ * });
+ * ```
+ */
+export declare function generateAppleClientSecret(options: AppleClientSecretOptions): Promise<string>;
+/** A cached client-secret source: returns a valid secret, re-signing lazily. */
+export type AppleClientSecretFactory = () => Promise<string>;
+/**
+ * Build a self-renewing Apple client-secret source. It signs a secret with
+ * {@link generateAppleClientSecret} on first call, caches it, and re-signs
+ * automatically once the cached secret is within `renewBeforeSeconds` of expiry
+ * — so a long-lived {@link appleProvider} never presents an expired assertion.
+ * The key material is validated on the first call, surfacing a misconfiguration
+ * as a `configuration` {@link ExternalAuthError}.
+ */
+export declare function createAppleClientSecretFactory(options: AppleClientSecretOptions & {
+    renewBeforeSeconds?: number;
+}): AppleClientSecretFactory;

package/esm/identity/external/apple-client-secret.js

@@ -0,0 +1,133 @@
+/**
+ * Sign in with Apple client-secret generation. Apple's "client secret" is not a
+ * static string but a short-lived ES256 JWT the app signs from its `.p8`
+ * private key — {@link generateAppleClientSecret} builds one,
+ * {@link createAppleClientSecretFactory} caches and renews it before expiry.
+ *
+ * @module
+ */
+import { decodeBase64 } from "../../deps/jsr.io/@std/encoding/1.0.11/base64.js";
+import { toArrayBuffer } from "../../utils/_buffer.js";
+import { base64urlEncode } from "../../utils/crypto.js";
+import { ExternalAuthError } from "./errors.js";
+/** Apple's audience for the client-secret JWT. */
+export const APPLE_AUDIENCE = "https://appleid.apple.com";
+/** Apple's hard cap on the client secret's lifetime: 6 months, in seconds. */
+export const APPLE_CLIENT_SECRET_MAX_TTL_SECONDS = 15777000;
+/** Default client-secret lifetime: ~180 days, comfortably under Apple's cap. */
+export const DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS = 15552000;
+const encoder = new TextEncoder();
+const ES256_IMPORT = { name: "ECDSA", namedCurve: "P-256" };
+const ES256_SIGN = { name: "ECDSA", hash: "SHA-256" };
+function configError(providerId, message) {
+    return new ExternalAuthError(providerId, "configuration", message);
+}
+function requireNonEmpty(providerId, value, field) {
+    const trimmed = value?.trim?.() ?? "";
+    if (!trimmed) {
+        throw configError(providerId, `Apple ${field} is empty — set it from the Apple Developer console.`);
+    }
+    return trimmed;
+}
+function pemToPkcs8(providerId, pem) {
+    const body = pem
+        .replace(/-----BEGIN [^-]+-----/g, "")
+        .replace(/-----END [^-]+-----/g, "")
+        .replace(/\s+/g, "");
+    if (!body) {
+        throw configError(providerId, `the Apple private key (.p8) is empty. Paste the PKCS#8 PEM contents ` +
+            `of the AuthKey_*.p8 file Apple lets you download once.`);
+    }
+    try {
+        return decodeBase64(body);
+    }
+    catch (error) {
+        throw configError(providerId, `the Apple private key (.p8) is not valid base64/PEM ` +
+            `(${error instanceof Error ? error.message : String(error)}).`);
+    }
+}
+async function importPrivateKey(providerId, pem) {
+    const der = pemToPkcs8(providerId, pem);
+    try {
+        return await crypto.subtle.importKey("pkcs8", toArrayBuffer(der), ES256_IMPORT, false, ["sign"]);
+    }
+    catch (error) {
+        throw configError(providerId, `the Apple private key (.p8) could not be imported as a P-256 (ES256) ` +
+            `key (${error instanceof Error ? error.message : String(error)}). ` +
+            `Confirm you downloaded a "Sign in with Apple" key and pasted it ` +
+            `unmodified.`);
+    }
+}
+/**
+ * Generate a single Sign in with Apple client secret: an ES256 JWT with
+ * `iss` = team id, `sub` = client id (Services ID), `aud` = Apple, and an `exp`
+ * bounded by {@link APPLE_CLIENT_SECRET_MAX_TTL_SECONDS}. Prefer
+ * {@link createAppleClientSecretFactory} in a long-lived process so the secret
+ * is cached and renewed rather than re-signed on every sign-in.
+ *
+ * @throws {ExternalAuthError} `configuration` naming the offending input when
+ *   the team id / key id / client id is empty, the `.p8` is not a valid P-256
+ *   key, or the requested TTL exceeds Apple's cap.
+ *
+ * @example
+ * ```ts
+ * const secret = await generateAppleClientSecret({
+ *   teamId: "ABCDE12345",
+ *   keyId: "KEY1234567",
+ *   clientId: "com.example.web",
+ *   privateKey: Deno.env.get("APPLE_PRIVATE_KEY")!,
+ * });
+ * ```
+ */
+export async function generateAppleClientSecret(options) {
+    const providerId = options.providerId ?? "apple";
+    const teamId = requireNonEmpty(providerId, options.teamId, "team id");
+    const keyId = requireNonEmpty(providerId, options.keyId, "key id");
+    const clientId = requireNonEmpty(providerId, options.clientId, "client id (Services ID)");
+    const ttl = options.expiresInSeconds ??
+        DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS;
+    if (ttl <= 0 || ttl > APPLE_CLIENT_SECRET_MAX_TTL_SECONDS) {
+        throw configError(providerId, `Apple client secret TTL must be between 1 and ` +
+            `${APPLE_CLIENT_SECRET_MAX_TTL_SECONDS} seconds (6 months); ` +
+            `got ${ttl}.`);
+    }
+    const privateKey = await importPrivateKey(providerId, options.privateKey);
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: "ES256", kid: keyId };
+    const payload = {
+        iss: teamId,
+        iat: now,
+        exp: now + ttl,
+        aud: APPLE_AUDIENCE,
+        sub: clientId,
+    };
+    const signingInput = `${encodeSegment(header)}.${encodeSegment(payload)}`;
+    const signature = await crypto.subtle.sign(ES256_SIGN, privateKey, encoder.encode(signingInput));
+    return `${signingInput}.${base64urlEncode(new Uint8Array(signature))}`;
+}
+function encodeSegment(value) {
+    return base64urlEncode(encoder.encode(JSON.stringify(value)));
+}
+/**
+ * Build a self-renewing Apple client-secret source. It signs a secret with
+ * {@link generateAppleClientSecret} on first call, caches it, and re-signs
+ * automatically once the cached secret is within `renewBeforeSeconds` of expiry
+ * — so a long-lived {@link appleProvider} never presents an expired assertion.
+ * The key material is validated on the first call, surfacing a misconfiguration
+ * as a `configuration` {@link ExternalAuthError}.
+ */
+export function createAppleClientSecretFactory(options) {
+    const ttl = options.expiresInSeconds ??
+        DEFAULT_APPLE_CLIENT_SECRET_TTL_SECONDS;
+    const renewBefore = options.renewBeforeSeconds ?? 60 * 60;
+    let cached = null;
+    return async () => {
+        const now = Math.floor(Date.now() / 1000);
+        if (cached && now < cached.expiresAt - renewBefore) {
+            return cached.secret;
+        }
+        const secret = await generateAppleClientSecret(options);
+        cached = { secret, expiresAt: now + ttl };
+        return secret;
+    };
+}

package/esm/identity/external/apple.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Sign in with Apple connector. Apple is OpenID-Connect-shaped but does not fit
+ * {@link oidcProvider}: its client secret is a signed ES256 JWT rather than a
+ * static string (see {@link generateAppleClientSecret}), it authenticates the
+ * client in the token body (`client_secret_post`), and it requires
+ * `response_mode=form_post` whenever profile scopes are requested. This is a
+ * dedicated {@link ExternalProvider} that exchanges the code, then verifies the
+ * `id_token` signature against Apple's JWKS.
+ *
+ * The user's name is returned by Apple **only** on the first authorization, in
+ * the `form_post` body's `user` field — never in the `id_token`. This connector
+ * returns what the `id_token` carries (stable subject, email); capturing the
+ * first-authorization name is the callback route's responsibility, since only
+ * it sees the form body.
+ *
+ * @module
+ */
+import { type AppleClientSecretFactory, type AppleClientSecretOptions } from "./apple-client-secret.js";
+import type { ExternalProvider } from "./provider.js";
+/** Options for {@link appleProvider}. */
+export interface AppleProviderOptions extends Pick<AppleClientSecretOptions, "teamId" | "keyId" | "privateKey"> {
+    /** The Services ID configured for web Sign in with Apple (the `client_id`). */
+    clientId: string;
+    /** Scopes requested by default. Defaults to `["name", "email"]`. */
+    scopes?: string[];
+    /**
+     * Client-secret lifetime in seconds. Defaults to Apple's practical maximum;
+     * see {@link AppleClientSecretOptions.expiresInSeconds}.
+     */
+    expiresInSeconds?: number;
+    /**
+     * Override the client-secret source — inject a stub in tests instead of real
+     * `.p8` key material. Defaults to a cached factory over the key material.
+     */
+    clientSecret?: AppleClientSecretFactory;
+    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Creates a Sign in with Apple connector with id `"apple"`.
+ *
+ * The flow requests `response_mode=form_post` (Apple's requirement when `name`
+ * or `email` scope is present), exchanges the code at Apple's token endpoint
+ * with a freshly-signed client-secret JWT, and verifies the returned
+ * `id_token`'s RS256 signature against Apple's published keys before trusting
+ * its claims (`iss`, `aud`, `azp`, `exp`, and the `nonce` when one was sent,
+ * checked exactly as {@link oidcProvider} checks them). Apple's
+ * private-relay addresses (`@privaterelay.appleid.com`) are ordinary verified
+ * emails and are returned as-is. The raw `id_token` claims — including
+ * `is_private_email` — stay on {@link ExternalProfile.raw}.
+ *
+ * @example
+ * ```ts
+ * const flow = new ExternalAuthFlow({
+ *   provider: appleProvider({
+ *     clientId: "com.example.web",
+ *     teamId: Deno.env.get("APPLE_TEAM_ID")!,
+ *     keyId: Deno.env.get("APPLE_KEY_ID")!,
+ *     privateKey: Deno.env.get("APPLE_PRIVATE_KEY")!,
+ *   }),
+ * });
+ * ```
+ */
+export declare function appleProvider(options: AppleProviderOptions): ExternalProvider;