@udibo/oauth2 0.1.0

package/esm/identity/external/apple.js

@@ -0,0 +1,248 @@
+/**
+ * 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 { toArrayBuffer } from "../../utils/_buffer.js";
+import { base64urlDecode } from "../../utils/crypto.js";
+import { assertIdTokenClaims, describeError } from "./_shared.js";
+import { runTokenExchange } from "./_token-exchange.js";
+import { createAppleClientSecretFactory, } from "./apple-client-secret.js";
+import { ExternalAuthError } from "./errors.js";
+const APPLE_ISSUER = "https://appleid.apple.com";
+const APPLE_AUTHORIZE_URL = "https://appleid.apple.com/auth/authorize";
+const APPLE_TOKEN_URL = "https://appleid.apple.com/auth/token";
+const APPLE_JWKS_URL = "https://appleid.apple.com/auth/keys";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const JWKS_CACHE_TTL_MS = 60 * 60 * 1000;
+const SIGNATURE_NOT_VERIFIED = `Apple id_token signature did not verify against Apple's JWKS — the ` +
+    `token is forged, corrupted, or signed by an unpublished key.`;
+/**
+ * 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 function appleProvider(options) {
+    const id = "apple";
+    const fetchImpl = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+    const clientSecretFactory = options.clientSecret ??
+        createAppleClientSecretFactory({
+            providerId: id,
+            teamId: options.teamId,
+            keyId: options.keyId,
+            clientId: options.clientId,
+            privateKey: options.privateKey,
+            expiresInSeconds: options.expiresInSeconds,
+        });
+    let jwksCache = null;
+    async function exchangeCode(input) {
+        const clientSecret = await clientSecretFactory();
+        const { value } = await runTokenExchange({
+            provider: id,
+            displayName: "Apple",
+            endpoint: APPLE_TOKEN_URL,
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code: input.code,
+                redirect_uri: input.redirectUri,
+                client_id: options.clientId,
+                client_secret: clientSecret,
+            }),
+            requiredField: "id_token",
+            fetch: fetchImpl,
+            httpErrorHint: `An "invalid_client" here means the client-secret JWT ` +
+                `is wrong — check the team id, key id, and Services ID (client id).`,
+            tokenErrorHint: appleTokenErrorHint,
+        });
+        return value;
+    }
+    async function loadJwks() {
+        if (jwksCache && Date.now() - jwksCache.fetchedAt < JWKS_CACHE_TTL_MS) {
+            return jwksCache.keys;
+        }
+        let res;
+        try {
+            res = await fetchImpl(APPLE_JWKS_URL, {
+                headers: { Accept: "application/json" },
+            });
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `could not reach Apple's JWKS endpoint (${describeError(error)}).`, { cause: error });
+        }
+        if (!res.ok) {
+            await res.body?.cancel();
+            throw new ExternalAuthError(id, "provider_error", `Apple's JWKS endpoint responded with HTTP ${res.status}.`);
+        }
+        let doc;
+        try {
+            doc = (await res.json());
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `Apple's JWKS endpoint returned invalid JSON (${describeError(error)}).`, { cause: error });
+        }
+        if (!Array.isArray(doc.keys)) {
+            throw new ExternalAuthError(id, "provider_error", `Apple's JWKS endpoint returned no "keys" array.`);
+        }
+        const keys = doc.keys;
+        jwksCache = { keys, fetchedAt: Date.now() };
+        return keys;
+    }
+    async function verifyIdToken(idToken, expectedNonce) {
+        const parts = idToken.split(".");
+        if (parts.length !== 3) {
+            throw new ExternalAuthError(id, "provider_error", `Apple returned a malformed id_token (expected three segments).`);
+        }
+        const header = decodeJson(id, parts[0], "id_token header");
+        const kid = typeof header.kid === "string" ? header.kid : undefined;
+        if (header.alg !== "RS256") {
+            throw new ExternalAuthError(id, "provider_error", `Apple id_token is signed with "${String(header.alg)}", expected ` +
+                `RS256.`);
+        }
+        if (!kid) {
+            throw new ExternalAuthError(id, "provider_error", `Apple id_token header has no "kid" — refusing to bind it to an ` +
+                `arbitrary JWKS key. Apple always sets "kid" on a real token.`);
+        }
+        const jwk = await resolveVerificationKey(kid);
+        let key;
+        try {
+            key = await crypto.subtle.importKey("jwk", jwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `Apple's signing key could not be imported (${describeError(error)}).`, { cause: error });
+        }
+        let signature;
+        try {
+            signature = base64urlDecode(parts[2]);
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", SIGNATURE_NOT_VERIFIED, {
+                cause: error,
+            });
+        }
+        const valid = await crypto.subtle.verify({ name: "RSASSA-PKCS1-v1_5" }, key, toArrayBuffer(signature), encoder.encode(`${parts[0]}.${parts[1]}`));
+        if (!valid) {
+            throw new ExternalAuthError(id, "provider_error", SIGNATURE_NOT_VERIFIED);
+        }
+        const claims = decodeJson(id, parts[1], "id_token payload");
+        assertIdTokenClaims({
+            provider: id,
+            claims,
+            issuer: APPLE_ISSUER,
+            clientId: options.clientId,
+            expectedNonce,
+        });
+        return claims;
+    }
+    async function resolveVerificationKey(kid) {
+        const pick = (keys) => keys.find((key) => key.kid === kid);
+        let match = pick(await loadJwks());
+        if (!match) {
+            jwksCache = null;
+            match = pick(await loadJwks());
+        }
+        if (!match) {
+            throw new ExternalAuthError(id, "provider_error", `Apple's JWKS has no key with kid "${String(kid)}" — the id_token was ` +
+                `signed by a key Apple no longer publishes.`);
+        }
+        return match;
+    }
+    return {
+        id,
+        displayName: "Apple",
+        defaultScopes: options.scopes ?? ["name", "email"],
+        usesPkce: false,
+        usesNonce: true,
+        buildAuthorizationUrl(input) {
+            const url = new URL(APPLE_AUTHORIZE_URL);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("client_id", options.clientId);
+            url.searchParams.set("redirect_uri", input.redirectUri);
+            url.searchParams.set("scope", input.scopes.join(" "));
+            url.searchParams.set("state", input.state);
+            if (input.nonce)
+                url.searchParams.set("nonce", input.nonce);
+            if (input.scopes.length > 0) {
+                url.searchParams.set("response_mode", "form_post");
+            }
+            return Promise.resolve(url.toString());
+        },
+        async fetchProfile(input) {
+            const idToken = await exchangeCode(input);
+            const claims = await verifyIdToken(idToken, input.nonce);
+            return profileFromClaims(claims);
+        },
+    };
+}
+function profileFromClaims(claims) {
+    const subject = claims.sub;
+    if (typeof subject !== "string" || subject.length === 0) {
+        throw new ExternalAuthError("apple", "provider_error", `Apple id_token is missing the required "sub" claim.`);
+    }
+    return {
+        provider: "apple",
+        subject,
+        email: typeof claims.email === "string" ? claims.email : undefined,
+        emailVerified: isAppleTrue(claims.email_verified),
+        raw: claims,
+    };
+}
+function isAppleTrue(value) {
+    return value === true || value === "true";
+}
+function appleTokenErrorHint(error) {
+    if (error === undefined) {
+        return `Ensure the sign-in requested the "openid" flow scopes.`;
+    }
+    if (error === "invalid_client") {
+        return `The client-secret JWT is wrong — check the team id, key id, and ` +
+            `Services ID (client id).`;
+    }
+    if (error === "invalid_grant") {
+        return `Apple rejected the code — it expired, was already used, or the ` +
+            `redirect URI does not match the Services ID configuration. Ask the ` +
+            `user to start again.`;
+    }
+    return `See Apple's "Generate and validate tokens" documentation for the ` +
+        `error's meaning.`;
+}
+function decodeJson(providerId, segment, what) {
+    try {
+        return JSON.parse(decoder.decode(base64urlDecode(segment)));
+    }
+    catch (error) {
+        throw new ExternalAuthError(providerId, "provider_error", `Apple ${what} was not valid base64url JSON (${describeError(error)}).`, { cause: error });
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Discord sign-in preset over the generic {@link oauth2Provider} connector.
+ *
+ * @module
+ */
+import type { ExternalProvider } from "./provider.js";
+/** Options for {@link discordProvider}. */
+export interface DiscordProviderOptions {
+    /** Client ID of the Discord application (OAuth2 tab). */
+    clientId: string;
+    /** The matching client secret. */
+    clientSecret: string;
+    /** Scopes requested by default. Defaults to `["identify", "email"]`. */
+    scopes?: string[];
+    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Creates a Discord connector with id `"discord"`.
+ *
+ * Discord speaks plain OAuth2 (no discovery, no id_token), so this is a preset
+ * over {@link oauth2Provider} pinned to Discord's fixed endpoints. The profile
+ * is read from `GET /users/@me`: the subject is the Discord user id,
+ * `emailVerified` reflects Discord's `verified` flag for the account email, and
+ * the display name prefers the global display name over the legacy username.
+ * The `/users/@me` payload is available on {@link ExternalProfile.raw}.
+ *
+ * @example
+ * ```ts
+ * const flow = new ExternalAuthFlow({
+ *   provider: discordProvider({
+ *     clientId: Deno.env.get("DISCORD_CLIENT_ID")!,
+ *     clientSecret: Deno.env.get("DISCORD_CLIENT_SECRET")!,
+ *   }),
+ * });
+ * ```
+ */
+export declare function discordProvider(options: DiscordProviderOptions): ExternalProvider;

package/esm/identity/external/discord.js

@@ -0,0 +1,62 @@
+/**
+ * Discord sign-in preset over the generic {@link oauth2Provider} connector.
+ *
+ * @module
+ */
+import { oauth2Provider } from "./oauth2.js";
+const DISCORD_AUTHORIZE_URL = "https://discord.com/oauth2/authorize";
+const DISCORD_TOKEN_URL = "https://discord.com/api/oauth2/token";
+const DISCORD_USER_URL = "https://discord.com/api/users/@me";
+function avatarUrl(user) {
+    const id = user.id;
+    const avatar = user.avatar;
+    if (typeof id === "string" && typeof avatar === "string" && avatar) {
+        const ext = avatar.startsWith("a_") ? "gif" : "png";
+        return `https://cdn.discordapp.com/avatars/${id}/${avatar}.${ext}`;
+    }
+    return undefined;
+}
+/**
+ * Creates a Discord connector with id `"discord"`.
+ *
+ * Discord speaks plain OAuth2 (no discovery, no id_token), so this is a preset
+ * over {@link oauth2Provider} pinned to Discord's fixed endpoints. The profile
+ * is read from `GET /users/@me`: the subject is the Discord user id,
+ * `emailVerified` reflects Discord's `verified` flag for the account email, and
+ * the display name prefers the global display name over the legacy username.
+ * The `/users/@me` payload is available on {@link ExternalProfile.raw}.
+ *
+ * @example
+ * ```ts
+ * const flow = new ExternalAuthFlow({
+ *   provider: discordProvider({
+ *     clientId: Deno.env.get("DISCORD_CLIENT_ID")!,
+ *     clientSecret: Deno.env.get("DISCORD_CLIENT_SECRET")!,
+ *   }),
+ * });
+ * ```
+ */
+export function discordProvider(options) {
+    return oauth2Provider({
+        id: "discord",
+        displayName: "Discord",
+        authorizationEndpoint: DISCORD_AUTHORIZE_URL,
+        tokenEndpoint: DISCORD_TOKEN_URL,
+        userInfoEndpoint: DISCORD_USER_URL,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        defaultScopes: options.scopes ?? ["identify", "email"],
+        fetch: options.fetch,
+        mapProfile: ({ profile }) => ({
+            subject: typeof profile.id === "string" ? profile.id : "",
+            email: typeof profile.email === "string" ? profile.email : undefined,
+            emailVerified: profile.verified === true,
+            name: typeof profile.global_name === "string" && profile.global_name
+                ? profile.global_name
+                : typeof profile.username === "string"
+                    ? profile.username
+                    : undefined,
+            picture: avatarUrl(profile),
+        }),
+    });
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The error contract for external-provider (social login) flows.
+ *
+ * Every failure in the external connector layer is thrown as an
+ * {@link ExternalAuthError} whose message names the provider, what failed, and
+ * the likely fix — misconfiguration is meant to be diagnosable from the
+ * message alone. The {@link ExternalAuthErrorCode} tells app code how to
+ * respond: `configuration` is a deploy-time bug to fix, everything else is a
+ * per-attempt failure to surface to the user (usually "sign in again").
+ *
+ * @module
+ */
+/**
+ * Machine-readable causes for an {@link ExternalAuthError}.
+ *
+ * - `configuration` — the connector is miswired (bad issuer, failed
+ *   discovery, missing endpoint, provider/transient mismatch). Fix the
+ *   deployment; retrying the sign-in will not help.
+ * - `provider_error` — the provider rejected the request (callback `error`
+ *   param, token-endpoint error, profile-endpoint failure, malformed
+ *   response). The message carries the provider's error code/description.
+ * - `invalid_callback` — the callback URL is missing `code` or `state`.
+ * - `state_mismatch` — the callback `state` does not match the transient
+ *   (possible CSRF or a stale/mixed-up sign-in attempt).
+ * - `transient_expired` — the sign-in attempt outlived the configured max
+ *   transient age; the user should start again.
+ * - `nonce_mismatch` — the id_token `nonce` claim does not match the
+ *   transient (possible token replay); the user should start again.
+ */
+export type ExternalAuthErrorCode = "configuration" | "provider_error" | "invalid_callback" | "state_mismatch" | "transient_expired" | "nonce_mismatch";
+/**
+ * A diagnosable error from an external-provider flow. The message is always
+ * prefixed with the provider id (e.g. `[google] …`) and states what failed
+ * plus the likely fix; switch on {@link ExternalAuthError.code} to decide
+ * whether to alert an operator (`configuration`) or restart the sign-in.
+ */
+export declare class ExternalAuthError extends Error {
+    /** Always `"ExternalAuthError"`, so instances are recognizable across realms. */
+    readonly name = "ExternalAuthError";
+    /** The machine-readable failure cause. */
+    readonly code: ExternalAuthErrorCode;
+    /** The id of the provider the failure belongs to (e.g. `"google"`). */
+    readonly provider: string;
+    /** Builds the error; `message` is prefixed with `[provider]` automatically. */
+    constructor(provider: string, code: ExternalAuthErrorCode, message: string, options?: ErrorOptions);
+}
+/** Type guard for {@link ExternalAuthError}. */
+export declare function isExternalAuthError(value: unknown): value is ExternalAuthError;

package/esm/identity/external/errors.js

@@ -0,0 +1,36 @@
+/**
+ * The error contract for external-provider (social login) flows.
+ *
+ * Every failure in the external connector layer is thrown as an
+ * {@link ExternalAuthError} whose message names the provider, what failed, and
+ * the likely fix — misconfiguration is meant to be diagnosable from the
+ * message alone. The {@link ExternalAuthErrorCode} tells app code how to
+ * respond: `configuration` is a deploy-time bug to fix, everything else is a
+ * per-attempt failure to surface to the user (usually "sign in again").
+ *
+ * @module
+ */
+/**
+ * A diagnosable error from an external-provider flow. The message is always
+ * prefixed with the provider id (e.g. `[google] …`) and states what failed
+ * plus the likely fix; switch on {@link ExternalAuthError.code} to decide
+ * whether to alert an operator (`configuration`) or restart the sign-in.
+ */
+export class ExternalAuthError extends Error {
+    /** Always `"ExternalAuthError"`, so instances are recognizable across realms. */
+    name = "ExternalAuthError";
+    /** The machine-readable failure cause. */
+    code;
+    /** The id of the provider the failure belongs to (e.g. `"google"`). */
+    provider;
+    /** Builds the error; `message` is prefixed with `[provider]` automatically. */
+    constructor(provider, code, message, options) {
+        super(`[${provider}] ${message}`, options);
+        this.provider = provider;
+        this.code = code;
+    }
+}
+/** Type guard for {@link ExternalAuthError}. */
+export function isExternalAuthError(value) {
+    return value instanceof ExternalAuthError;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * The provider-agnostic two-step flow for external (social) sign-in:
+ * {@link ExternalAuthFlow.start} builds the redirect and hands back a
+ * serializable transient; {@link ExternalAuthFlow.finish} verifies the
+ * callback and returns the normalized profile.
+ *
+ * @module
+ */
+import type { ExternalAuthTransient, ExternalProfile, ExternalProvider } from "./provider.js";
+/** Default {@link ExternalAuthFlowOptions.maxTransientAgeMs}: 10 minutes. */
+export declare const DEFAULT_MAX_TRANSIENT_AGE_MS: number;
+/** Options for {@link ExternalAuthFlow}. */
+export interface ExternalAuthFlowOptions {
+    /** The connector to drive (e.g. `googleProvider(…)`). */
+    provider: ExternalProvider;
+    /**
+     * Max age of a transient before {@link ExternalAuthFlow.finish} rejects the
+     * attempt as expired, in ms. Bounds the window in which a stolen transient
+     * or callback URL stays usable. Defaults to
+     * {@link DEFAULT_MAX_TRANSIENT_AGE_MS}.
+     */
+    maxTransientAgeMs?: number;
+}
+/** Input to {@link ExternalAuthFlow.start}. */
+export interface ExternalAuthStartInput {
+    /** The callback URL registered with the provider for this app. */
+    redirectUri: string;
+    /** Override the provider's default scopes. */
+    scopes?: string[];
+    /** OIDC `prompt` parameter (e.g. `"select_account"`). */
+    prompt?: string;
+}
+/** Result of {@link ExternalAuthFlow.start}. */
+export interface ExternalAuthStartResult {
+    /** The provider authorization URL to redirect the user's browser to. */
+    url: string;
+    /**
+     * Per-attempt state to persist in a cookie/session and hand back to
+     * {@link ExternalAuthFlow.finish}. JSON-serializable; contains no tokens.
+     */
+    transient: ExternalAuthTransient;
+}
+/** Input to {@link ExternalAuthFlow.finish}. */
+export interface ExternalAuthFinishInput {
+    /** The callback URL's search params (or the full URL / query string). */
+    params: URL | URLSearchParams | string;
+    /** The transient produced by the matching {@link ExternalAuthFlow.start}. */
+    transient: ExternalAuthTransient;
+}
+/**
+ * Drives one external provider through the authorization-code redirect dance
+ * without the library storing anything: {@link start} returns the redirect URL
+ * plus a JSON-serializable {@link ExternalAuthTransient} for the caller to keep
+ * (sealed cookie or session), and {@link finish} takes the callback params and
+ * that transient back and returns the verified {@link ExternalProfile}.
+ *
+ * The flow itself performs no network I/O — inject `fetch` on the provider to
+ * stub the network in tests. Create one flow per configured provider.
+ *
+ * @example
+ * ```ts
+ * const flow = new ExternalAuthFlow({
+ *   provider: googleProvider({ clientId, clientSecret }),
+ * });
+ *
+ * // GET /auth/social/google — redirect to Google, transient into a cookie.
+ * const { url, transient } = await flow.start({
+ *   redirectUri: "https://app.example.com/auth/social/google/callback",
+ * });
+ *
+ * // GET /auth/social/google/callback — verify and normalize.
+ * const profile = await flow.finish({
+ *   params: new URL(request.url).searchParams,
+ *   transient,
+ * });
+ * // App code decides: look up (profile.provider, profile.subject), create
+ * // or link a user, then start your own session.
+ * ```
+ */
+export declare class ExternalAuthFlow {
+    #private;
+    /** The connector this flow drives. */
+    readonly provider: ExternalProvider;
+    /** Creates a flow for one configured provider. */
+    constructor(options: ExternalAuthFlowOptions);
+    /**
+     * Begins a sign-in attempt: generates the per-attempt `state` (plus a PKCE
+     * verifier and OIDC nonce when the provider uses them), builds the
+     * provider's authorization URL, and returns both. Persist the transient
+     * (e.g. sealed cookie) and redirect the browser to `url`.
+     *
+     * @throws {ExternalAuthError} `configuration` when the provider cannot
+     *   resolve its endpoints (e.g. OIDC discovery failed).
+     */
+    start(input: ExternalAuthStartInput): Promise<ExternalAuthStartResult>;
+    /**
+     * Completes a sign-in attempt from the provider callback: enforces the max
+     * transient age, surfaces provider `error` callback params, verifies
+     * `state` with a timing-safe compare, exchanges the code, and (for OIDC
+     * providers) validates the id_token nonce — then returns the normalized
+     * profile.
+     *
+     * @throws {ExternalAuthError} with a code describing the failure — see
+     *   {@link ExternalAuthErrorCode} for how app code should respond to each.
+     */
+    finish(input: ExternalAuthFinishInput): Promise<ExternalProfile>;
+}