@aooth/idp 0.1.8

package/dist/index.mjs

@@ -0,0 +1,943 @@
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import { defaultClock } from "@aooth/auth";
+import { SignJWT, createRemoteJWKSet, errors, importPKCS8, jwtVerify } from "jose";
+import { UserAuthError, pickDefinedProfile } from "@aooth/user";
+//#region src/errors.ts
+const defaultMessages = {
+	UNKNOWN_PROVIDER: "Unknown identity provider",
+	INVALID_CONFIG: "Invalid OAuth provider configuration",
+	STATE_INVALID: "Sign-in could not be verified",
+	STATE_EXPIRED: "Sign-in expired — please try again",
+	PROVIDER_DENIED: "Sign-in was cancelled",
+	EXCHANGE_FAILED: "Could not complete sign-in with the provider",
+	JWKS_FAILED: "Could not verify the provider's signing keys",
+	ID_TOKEN_INVALID: "The provider's identity token could not be validated",
+	EMAIL_UNAVAILABLE: "The provider did not supply a usable email address"
+};
+var OAuthError = class extends Error {
+	type;
+	details;
+	name = "OAuthError";
+	constructor(type, message, details) {
+		super(message ?? defaultMessages[type]);
+		this.type = type;
+		this.details = details;
+	}
+};
+//#endregion
+//#region src/types.ts
+/** Structural check used by the registry to feature-detect `applyDefaults`. */
+function isConfigurableProvider(p) {
+	return typeof p.applyDefaults === "function";
+}
+/** Default username strategy: the verified email, else the stable `provider:subject`. */
+function defaultUsernameStrategy(p) {
+	return p.email ?? `${p.provider}:${p.subject}`;
+}
+/** Apply RFC §4 safe defaults over a partial policy. */
+function resolveFederatedPolicy(policy = {}) {
+	return {
+		emailMatch: policy.emailMatch ?? "require-interactive-link",
+		allowSignup: policy.allowSignup ?? true,
+		usernameStrategy: policy.usernameStrategy ?? defaultUsernameStrategy,
+		trustEmailVerifiedFrom: policy.trustEmailVerifiedFrom ?? []
+	};
+}
+//#endregion
+//#region src/pkce.ts
+/**
+* PKCE / CSRF primitives (RFC 7636 + OIDC nonce). All values are URL-safe
+* base64url with no padding, so they ride in query params and cookies without
+* escaping. Pure `node:crypto` — no I/O, fully deterministic-testable by
+* stubbing nothing (only the randomness varies).
+*/
+function base64url(buf) {
+	return buf.toString("base64url");
+}
+/**
+* Mint a fresh PKCE pair. The 32-byte verifier base64url-encodes to 43 chars,
+* comfortably inside RFC 7636's 43–128 range.
+*/
+function createPkcePair() {
+	const verifier = base64url(randomBytes(32));
+	return {
+		verifier,
+		challenge: pkceChallengeFor(verifier),
+		method: "S256"
+	};
+}
+/** Recompute the S256 challenge for a known verifier (verification side). */
+function pkceChallengeFor(verifier) {
+	return base64url(createHash("sha256").update(verifier).digest());
+}
+/** OIDC `nonce` — minted at `/start`, bound into state, asserted in `exchange()`. */
+function generateNonce(bytes = 32) {
+	return base64url(randomBytes(bytes));
+}
+/** Random component bound into the signed `state` (anti-CSRF / anti-replay). */
+function generateRandomState(bytes = 32) {
+	return base64url(randomBytes(bytes));
+}
+/**
+* STATELESS PKCE: deterministically DERIVE the code verifier + OIDC nonce from
+* a non-secret `seed` and the server's HMAC `secret`, instead of minting them
+* with {@link createPkcePair}/{@link generateNonce} and persisting the secret
+* half server-side.
+*
+* The `seed` is the same high-entropy value carried (in the clear) by the
+* signed-state `random` and the double-submit CSRF cookie — so the round-trip
+* needs NO server-side flow store: `/start` derives `{ verifier, nonce }` to
+* build the authorize request, and the callback re-derives the identical pair
+* from `state.random` to redeem the `code`. Because the verifier is
+* `HMAC(secret, seed)` and the secret never leaves the server, exposing the
+* seed in the URL discloses nothing — an attacker cannot recover the verifier.
+* Distinct domain-separation prefixes keep the verifier and the nonce
+* independent (neither is recoverable from the other).
+*
+* Same output range as {@link createPkcePair}: a 32-byte HMAC-SHA256 digest →
+* a 43-char base64url verifier, inside RFC 7636's 43–128.
+*/
+function deriveSeededPkce(secret, seed) {
+	const verifier = base64url(createHmac("sha256", secret).update(`aooth/pkce-verifier:${seed}`).digest());
+	return {
+		verifier,
+		nonce: base64url(createHmac("sha256", secret).update(`aooth/oidc-nonce:${seed}`).digest()),
+		challenge: pkceChallengeFor(verifier),
+		method: "S256"
+	};
+}
+//#endregion
+//#region src/state.ts
+const DEFAULT_TTL_SEC = 600;
+function toKey(secret) {
+	return typeof secret === "string" ? new TextEncoder().encode(secret) : secret;
+}
+/**
+* Sign the binding into a compact HS256 JWT. Field names are abbreviated to
+* keep the URL `state` short; {@link verifyState} maps them back.
+*/
+async function signState(payload, secret, opts = {}) {
+	const clock = opts.clock ?? defaultClock;
+	const nowSec = Math.floor(clock.now() / 1e3);
+	const claims = {
+		rnd: payload.random,
+		prv: payload.provider,
+		rdr: payload.redirect
+	};
+	if (payload.verifier !== void 0) claims.vrf = payload.verifier;
+	if (payload.nonce !== void 0) claims.non = payload.nonce;
+	if (payload.handle !== void 0) claims.hdl = payload.handle;
+	if (payload.userId !== void 0) claims.uid = payload.userId;
+	return new SignJWT(claims).setProtectedHeader({ alg: "HS256" }).setIssuedAt(nowSec).setExpirationTime(nowSec + (opts.ttlSec ?? DEFAULT_TTL_SEC)).sign(toKey(secret));
+}
+/**
+* Verify + decode the signed state. Pins `HS256` (rejects `alg:none` / key
+* confusion). Throws {@link OAuthError} `STATE_EXPIRED` past TTL,
+* `STATE_INVALID` on any other signature/shape failure.
+*/
+async function verifyState(token, secret, opts = {}) {
+	const clock = opts.clock ?? defaultClock;
+	let payload;
+	try {
+		payload = (await jwtVerify(token, toKey(secret), {
+			algorithms: ["HS256"],
+			currentDate: new Date(clock.now())
+		})).payload;
+	} catch (err) {
+		if (err instanceof errors.JWTExpired) throw new OAuthError("STATE_EXPIRED");
+		throw new OAuthError("STATE_INVALID");
+	}
+	const random = payload.rnd;
+	const provider = payload.prv;
+	const redirect = payload.rdr;
+	if (typeof random !== "string" || typeof provider !== "string" || typeof redirect !== "string") throw new OAuthError("STATE_INVALID", "Malformed state payload");
+	const out = {
+		random,
+		provider,
+		redirect
+	};
+	if (typeof payload.vrf === "string") out.verifier = payload.vrf;
+	if (typeof payload.non === "string") out.nonce = payload.non;
+	if (typeof payload.hdl === "string") out.handle = payload.hdl;
+	if (typeof payload.uid === "string") out.userId = payload.uid;
+	return out;
+}
+//#endregion
+//#region src/providers/oauth2-shared.ts
+/** Resolve the effective `fetch`: an injected impl, else the global `fetch`. */
+function resolveFetch(impl) {
+	return impl ?? globalThis.fetch;
+}
+/**
+* `fetch` a JSON endpoint, failing CLOSED as an {@link OAuthError} on a network
+* error, a non-2xx status, or a non-JSON body. `label` names the call in the
+* thrown message; `errorType` selects the error class — token / provider-API
+* failures are `EXCHANGE_FAILED`, OIDC discovery fails as `JWKS_FAILED`.
+*
+* Returns the parsed body as `unknown` — the caller narrows / applies any
+* provider-specific post-checks (GitHub's HTTP-200 `{ error }`, an
+* `access_token` presence guard, the OIDC discovery issuer match, …).
+*/
+async function fetchJson(fetchFn, url, init, opts) {
+	const errorType = opts.errorType ?? "EXCHANGE_FAILED";
+	let res;
+	try {
+		res = await fetchFn(url, init);
+	} catch (err) {
+		throw new OAuthError(errorType, `${opts.label} request failed`, { cause: String(err) });
+	}
+	if (!res.ok) throw new OAuthError(errorType, `${opts.label} returned ${res.status}`, { status: res.status });
+	try {
+		return await res.json();
+	} catch {
+		throw new OAuthError(errorType, `${opts.label} returned a non-JSON body`);
+	}
+}
+/**
+* Build the `302`-target authorization URL shared by every provider:
+* `redirect_uri` + `state` + the PKCE S256 `code_challenge`. The OAuth2/OIDC
+* extras (`response_type`, `client_id`, `scope`, `nonce`, provider params) are
+* layered on via {@link BuildAuthorizeUrlOptions}.
+*/
+function buildAuthorizeUrl(endpoint, args, opts = {}) {
+	const url = new URL(endpoint);
+	if (opts.responseType) url.searchParams.set("response_type", "code");
+	if (opts.clientId) url.searchParams.set("client_id", opts.clientId);
+	url.searchParams.set("redirect_uri", args.redirectUri);
+	if (opts.scopes) url.searchParams.set("scope", (args.scopes ?? opts.scopes).join(" "));
+	url.searchParams.set("state", args.state);
+	url.searchParams.set("code_challenge", args.codeChallenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	if (opts.nonce && args.nonce) url.searchParams.set("nonce", args.nonce);
+	for (const [k, v] of Object.entries(opts.extraParams ?? {})) url.searchParams.set(k, v);
+	return url.toString();
+}
+//#endregion
+//#region src/providers/oidc.ts
+const DEFAULT_SCOPES$1 = [
+	"openid",
+	"email",
+	"profile"
+];
+const DEFAULT_SIGNING_ALGS = ["RS256", "ES256"];
+const DEFAULT_CLOCK_TOLERANCE_SEC = 5;
+const DEFAULT_JWKS_CACHE_MS = 36e5;
+/**
+* Generic OpenID Connect provider: authorization-code + PKCE, full discovery,
+* remote JWKS, and the OIDC Core 3.1.3.7 ID-token validation list (RFC §7).
+* Verification fails CLOSED — a JWKS/discovery fetch failure is an
+* `OAuthError('JWKS_FAILED')`, never a silent accept.
+*
+* `GoogleProvider` is a thin subclass pinning the issuer + algs.
+*/
+var OidcProvider = class {
+	id;
+	issuer;
+	clientId;
+	clientSecret;
+	scopes;
+	signingAlgs;
+	explicitEndpoints;
+	injectedDiscovery;
+	injectedJwks;
+	clockToleranceSec;
+	jwksCacheTtlMs;
+	clockImpl;
+	fetchImpl;
+	discoveryCache;
+	jwksCache;
+	constructor(opts) {
+		if (!opts.issuer) throw new OAuthError("INVALID_CONFIG", "OIDC provider requires an 'issuer'");
+		if (!opts.clientId) throw new OAuthError("INVALID_CONFIG", "OIDC provider requires a 'clientId'");
+		if (!opts.clientSecret) throw new OAuthError("INVALID_CONFIG", "OIDC provider requires a 'clientSecret'");
+		this.id = opts.id ?? `oidc:${opts.issuer}`;
+		this.issuer = opts.issuer;
+		this.clientId = opts.clientId;
+		this.clientSecret = opts.clientSecret;
+		this.scopes = opts.scopes ?? DEFAULT_SCOPES$1;
+		this.signingAlgs = opts.idTokenSigningAlgs ?? DEFAULT_SIGNING_ALGS;
+		if (opts.authorizationEndpoint && opts.tokenEndpoint && opts.jwksUri) this.explicitEndpoints = {
+			issuer: opts.issuer,
+			authorization_endpoint: opts.authorizationEndpoint,
+			token_endpoint: opts.tokenEndpoint,
+			jwks_uri: opts.jwksUri
+		};
+		this.injectedDiscovery = opts.discovery;
+		this.injectedJwks = opts.jwks;
+		this.clockToleranceSec = opts.clockToleranceSec;
+		this.jwksCacheTtlMs = opts.jwksCacheTtlMs;
+		this.clockImpl = opts.clock;
+		this.fetchImpl = opts.fetch;
+	}
+	/** Registry-injected shared config; a ctor value always wins (decision #2). */
+	applyDefaults(shared) {
+		this.clockToleranceSec ??= shared.clockToleranceSec;
+		this.jwksCacheTtlMs ??= shared.jwks?.cacheTtlMs;
+		this.clockImpl ??= shared.clock;
+		this.fetchImpl ??= shared.fetch;
+	}
+	get clock() {
+		return this.clockImpl ?? defaultClock;
+	}
+	get fetchFn() {
+		return resolveFetch(this.fetchImpl);
+	}
+	/**
+	* The `client_secret` sent to the token endpoint: a static string as-is, or a
+	* {@link ClientSecretFactory}'s per-request value (Apple's minted ES256 JWT).
+	* Resolved lazily here so a factory sees the registry-injected clock.
+	*/
+	resolveClientSecret() {
+		return typeof this.clientSecret === "function" ? this.clientSecret({ clock: this.clock }) : this.clientSecret;
+	}
+	/**
+	* Extra authorization-request query params merged into {@link authorizationUrl}.
+	* Default none; AppleProvider returns `{ response_mode: 'form_post' }` (required
+	* by Apple whenever `email`/`name` scope is requested).
+	*/
+	extraAuthorizationParams(_args) {
+		return {};
+	}
+	async authorizationUrl(args) {
+		const { authorization_endpoint } = await this.resolveEndpoints();
+		return buildAuthorizeUrl(authorization_endpoint, args, {
+			responseType: true,
+			clientId: this.clientId,
+			scopes: this.scopes,
+			nonce: true,
+			extraParams: this.extraAuthorizationParams(args)
+		});
+	}
+	async exchange(args) {
+		const { token_endpoint, jwks_uri } = await this.resolveEndpoints();
+		const tokens = await this.postToken(token_endpoint, args);
+		const idToken = tokens.id_token;
+		if (typeof idToken !== "string") throw new OAuthError("ID_TOKEN_INVALID", "Token response carried no id_token");
+		const accessToken = typeof tokens.access_token === "string" ? tokens.access_token : void 0;
+		return this.verifyIdToken(idToken, accessToken, jwks_uri, args.expectedNonce);
+	}
+	async postToken(tokenEndpoint, args) {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code: args.code,
+			redirect_uri: args.redirectUri,
+			client_id: this.clientId,
+			client_secret: await this.resolveClientSecret(),
+			code_verifier: args.codeVerifier
+		});
+		return await fetchJson(this.fetchFn, tokenEndpoint, {
+			method: "POST",
+			headers: {
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json"
+			},
+			body: body.toString()
+		}, { label: "Token endpoint" });
+	}
+	async verifyIdToken(idToken, accessToken, jwksUri, expectedNonce) {
+		const keyResolver = await this.getJwks(jwksUri);
+		let payload;
+		let alg;
+		try {
+			const result = await jwtVerify(idToken, keyResolver, {
+				issuer: this.issuer,
+				audience: this.clientId,
+				algorithms: this.signingAlgs,
+				clockTolerance: this.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC,
+				currentDate: new Date(this.clock.now())
+			});
+			payload = result.payload;
+			alg = result.protectedHeader.alg;
+		} catch (err) {
+			const code = err?.code ?? "";
+			if (code.startsWith("ERR_JWKS")) throw new OAuthError("JWKS_FAILED", "Could not resolve the provider's signing key", { code });
+			throw new OAuthError("ID_TOKEN_INVALID", "ID token failed verification", { code });
+		}
+		if (typeof payload.sub !== "string" || payload.sub.length === 0) throw new OAuthError("ID_TOKEN_INVALID", "ID token has no subject");
+		if (expectedNonce !== void 0 && payload.nonce !== expectedNonce) throw new OAuthError("ID_TOKEN_INVALID", "ID token nonce mismatch");
+		if (Array.isArray(payload.aud) && payload.aud.length > 1 && payload.azp !== this.clientId) throw new OAuthError("ID_TOKEN_INVALID", "ID token azp does not match client");
+		if (accessToken !== void 0 && typeof payload.at_hash === "string") {
+			if (payload.at_hash !== atHash(accessToken, alg)) throw new OAuthError("ID_TOKEN_INVALID", "ID token at_hash mismatch");
+		}
+		return this.normalize(payload);
+	}
+	/**
+	* Map verified claims → {@link NormalizedProfile}. `protected` so a provider
+	* (Apple) can post-process — e.g. coerce Apple's spec-violating STRING
+	* `email_verified` after the base has applied the strict boolean-only rule.
+	*/
+	normalize(payload) {
+		const profile = {
+			provider: this.id,
+			subject: payload.sub,
+			raw: payload
+		};
+		if (typeof payload.email === "string") profile.email = payload.email;
+		if (typeof payload.email_verified === "boolean") profile.emailVerified = payload.email_verified;
+		if (typeof payload.name === "string") profile.displayName = payload.name;
+		if (typeof payload.picture === "string") profile.avatarUrl = payload.picture;
+		return profile;
+	}
+	async resolveEndpoints() {
+		if (this.explicitEndpoints) return this.explicitEndpoints;
+		if (this.injectedDiscovery) return this.validateDiscovery(this.injectedDiscovery);
+		if (this.discoveryCache) return this.discoveryCache;
+		const wellKnown = `${this.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+		const doc = await fetchJson(this.fetchFn, wellKnown, { headers: { accept: "application/json" } }, {
+			label: "OIDC discovery",
+			errorType: "JWKS_FAILED"
+		});
+		this.discoveryCache = this.validateDiscovery(doc);
+		return this.discoveryCache;
+	}
+	/** OIDC discovery MUST echo the requested issuer (guards a swapped doc). */
+	validateDiscovery(doc) {
+		if (doc.issuer !== this.issuer) throw new OAuthError("INVALID_CONFIG", "Discovery issuer does not match configured issuer", {
+			expected: this.issuer,
+			got: doc.issuer
+		});
+		if (!doc.authorization_endpoint || !doc.token_endpoint || !doc.jwks_uri) throw new OAuthError("INVALID_CONFIG", "Discovery document is missing required endpoints");
+		return doc;
+	}
+	async getJwks(jwksUri) {
+		if (this.injectedJwks) return this.injectedJwks;
+		if (this.jwksCache?.uri === jwksUri) return this.jwksCache.resolver;
+		const resolver = createRemoteJWKSet(new URL(jwksUri), { cacheMaxAge: this.jwksCacheTtlMs ?? DEFAULT_JWKS_CACHE_MS });
+		this.jwksCache = {
+			uri: jwksUri,
+			resolver
+		};
+		return resolver;
+	}
+};
+/**
+* OIDC at_hash (Core 3.1.3.6): base64url of the left-most half of the access
+* token's hash, the hash chosen by the id_token's `alg` (RS256 → SHA-256).
+*/
+function atHash(accessToken, alg) {
+	const digest = createHash(alg.endsWith("384") ? "sha384" : alg.endsWith("512") ? "sha512" : "sha256").update(accessToken).digest();
+	return digest.subarray(0, digest.length / 2).toString("base64url");
+}
+//#endregion
+//#region src/providers/google.ts
+/** Google's stable OIDC issuer — endpoints + JWKS are discovered from it. */
+const GOOGLE_ISSUER = "https://accounts.google.com";
+/**
+* Google Sign-In (OIDC). Pins `id: 'google'`, the Google issuer, and `RS256`
+* (Google's only ID-token alg). Everything else — discovery, JWKS rotation,
+* the full §7 validation — is inherited from {@link OidcProvider}.
+*/
+var GoogleProvider = class extends OidcProvider {
+	constructor(opts) {
+		super({
+			...opts,
+			id: "google",
+			issuer: GOOGLE_ISSUER,
+			idTokenSigningAlgs: opts.idTokenSigningAlgs ?? ["RS256"]
+		});
+	}
+};
+//#endregion
+//#region src/providers/github.ts
+const GITHUB_AUTHORIZE = "https://github.com/login/oauth/authorize";
+const GITHUB_TOKEN = "https://github.com/login/oauth/access_token";
+const GITHUB_USER = "https://api.github.com/user";
+const GITHUB_EMAILS = "https://api.github.com/user/emails";
+const DEFAULT_SCOPES = ["read:user", "user:email"];
+const DEFAULT_USER_AGENT = "aoothjs";
+/**
+* Sign in with GitHub — pure **OAuth2** (no OpenID Connect): there is no
+* `id_token`, no JWKS, and no nonce. After the authorization-code + PKCE
+* exchange yields an access token, the profile is read from GitHub's REST API
+* (`GET /user` + `GET /user/emails`).
+*
+* **`emailVerified` is strict** (RFC IDP.md §3.4): it is `true` ONLY when the
+* user's PRIMARY email is GitHub-verified. A non-primary or unverified address
+* yields `false` — never trust a GitHub email as proof-of-control unless it is
+* the verified primary.
+*
+* Implements {@link ConfigurableProvider} so the registry can inject a shared
+* `fetch` (deterministic tests) / `clock`; a constructor value always wins.
+*/
+var GithubProvider = class {
+	id;
+	clientId;
+	clientSecret;
+	scopes;
+	userAgent;
+	authorizationEndpoint;
+	tokenEndpoint;
+	userEndpoint;
+	emailsEndpoint;
+	fetchImpl;
+	constructor(opts) {
+		if (!opts.clientId || !opts.clientSecret) throw new OAuthError("INVALID_CONFIG", "GithubProvider requires 'clientId' and 'clientSecret'");
+		this.id = opts.id ?? "github";
+		this.clientId = opts.clientId;
+		this.clientSecret = opts.clientSecret;
+		this.scopes = opts.scopes ?? DEFAULT_SCOPES;
+		this.userAgent = opts.userAgent ?? DEFAULT_USER_AGENT;
+		this.authorizationEndpoint = opts.authorizationEndpoint ?? GITHUB_AUTHORIZE;
+		this.tokenEndpoint = opts.tokenEndpoint ?? GITHUB_TOKEN;
+		this.userEndpoint = opts.userEndpoint ?? GITHUB_USER;
+		this.emailsEndpoint = opts.emailsEndpoint ?? GITHUB_EMAILS;
+		this.fetchImpl = opts.fetch;
+	}
+	/** Registry-injected shared config; a ctor value always wins (decision #2). */
+	applyDefaults(shared) {
+		this.fetchImpl ??= shared.fetch;
+	}
+	get fetchFn() {
+		return resolveFetch(this.fetchImpl);
+	}
+	authorizationUrl(args) {
+		return Promise.resolve(buildAuthorizeUrl(this.authorizationEndpoint, args, {
+			responseType: true,
+			clientId: this.clientId,
+			scopes: this.scopes
+		}));
+	}
+	async exchange(args) {
+		const accessToken = await this.redeemCode(args);
+		const [user, primary] = await Promise.all([this.fetchUser(accessToken), this.fetchPrimaryEmail(accessToken)]);
+		const { email, emailVerified } = primary ?? (user.email ? {
+			email: user.email,
+			emailVerified: false
+		} : {});
+		const profile = {
+			provider: this.id,
+			subject: String(user.id),
+			raw: user
+		};
+		if (email !== void 0) profile.email = email;
+		if (emailVerified !== void 0) profile.emailVerified = emailVerified;
+		const displayName = user.name ?? user.login;
+		if (displayName) profile.displayName = displayName;
+		if (user.avatar_url) profile.avatarUrl = user.avatar_url;
+		return profile;
+	}
+	/** POST the authorization `code` → access token (GitHub returns JSON when asked). */
+	async redeemCode(args) {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code: args.code,
+			redirect_uri: args.redirectUri,
+			client_id: this.clientId,
+			client_secret: this.clientSecret,
+			code_verifier: args.codeVerifier
+		});
+		const json = await fetchJson(this.fetchFn, this.tokenEndpoint, {
+			method: "POST",
+			headers: {
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json",
+				"user-agent": this.userAgent
+			},
+			body: body.toString()
+		}, { label: "GitHub token endpoint" });
+		if (typeof json.error === "string") throw new OAuthError("EXCHANGE_FAILED", "GitHub rejected the authorization code", { error: json.error });
+		if (typeof json.access_token !== "string" || json.access_token.length === 0) throw new OAuthError("EXCHANGE_FAILED", "GitHub token response carried no access_token");
+		return json.access_token;
+	}
+	async fetchUser(accessToken) {
+		const user = await this.apiGet(this.userEndpoint, accessToken);
+		if (user.id === void 0 || user.id === null || typeof user.login !== "string") throw new OAuthError("EXCHANGE_FAILED", "GitHub /user response was missing id/login");
+		return user;
+	}
+	/**
+	* Resolve the verified PRIMARY `/user/emails` entry, `emailVerified` strictly
+	* from its `verified` flag. Returns `undefined` when the `user:email` scope is
+	* absent (call fails), the body isn't an array, or there's no primary entry —
+	* the caller then degrades to the public `/user` email (unverified).
+	*/
+	async fetchPrimaryEmail(accessToken) {
+		let entries;
+		try {
+			entries = await this.apiGet(this.emailsEndpoint, accessToken);
+		} catch {
+			return;
+		}
+		if (!Array.isArray(entries)) return void 0;
+		const primary = entries.find((e) => e && e.primary);
+		if (primary && typeof primary.email === "string") return {
+			email: primary.email,
+			emailVerified: primary.verified
+		};
+	}
+	apiGet(url, accessToken) {
+		return fetchJson(this.fetchFn, url, {
+			method: "GET",
+			headers: {
+				authorization: `Bearer ${accessToken}`,
+				accept: "application/vnd.github+json",
+				"user-agent": this.userAgent
+			}
+		}, { label: `GitHub API (${url})` });
+	}
+};
+//#endregion
+//#region src/providers/apple.ts
+/** Apple's stable OIDC issuer — endpoints + JWKS are discovered from it. */
+const APPLE_ISSUER = "https://appleid.apple.com";
+/** Apple ID tokens are always ES256. */
+const APPLE_SIGNING_ALGS = ["ES256"];
+/** Default scope — `openid email`; `name` is omitted (Apple sends it once, out-of-band; deferred). */
+const DEFAULT_APPLE_SCOPES = ["openid", "email"];
+/** Default client-secret JWT lifetime (1h). Apple's hard ceiling is ~6 months (15777000s). */
+const DEFAULT_SECRET_TTL_SEC = 3600;
+/** A minute of slack so a cached secret is never served right at its expiry. */
+const SECRET_RENEW_SLACK_SEC = 60;
+/**
+* Build Apple's dynamic `client_secret` source: a closure that mints — and
+* caches — a short-lived ES256 JWT signed with the `.p8` key. Header
+* `{ alg: 'ES256', kid }`, claims `{ iss: teamId, iat, exp, aud: APPLE_ISSUER,
+* sub: clientId }`. The signed JWT is reused until shortly before its `exp`, and
+* the (comparatively costly) `.p8` import is memoized — so a burst of exchanges
+* shares one signature and parses the key at most once. The clock comes from the
+* per-call context, so a registry-injected clock still drives `iat`/`exp`.
+*/
+function makeAppleClientSecretFactory(cfg) {
+	let cachedSecret;
+	let importedKey;
+	return async ({ clock }) => {
+		const nowSec = Math.floor(clock.now() / 1e3);
+		if (cachedSecret && cachedSecret.expSec - nowSec > SECRET_RENEW_SLACK_SEC) return cachedSecret.jwt;
+		let key;
+		try {
+			importedKey ??= importPKCS8(cfg.privateKey, "ES256");
+			key = await importedKey;
+		} catch (err) {
+			importedKey = void 0;
+			throw new OAuthError("INVALID_CONFIG", "AppleProvider could not import the '.p8' private key", { cause: String(err) });
+		}
+		const expSec = nowSec + cfg.ttlSec;
+		const jwt = await new SignJWT({}).setProtectedHeader({
+			alg: "ES256",
+			kid: cfg.keyId
+		}).setIssuer(cfg.teamId).setIssuedAt(nowSec).setExpirationTime(expSec).setAudience(APPLE_ISSUER).setSubject(cfg.clientId).sign(key);
+		cachedSecret = {
+			jwt,
+			expSec
+		};
+		return jwt;
+	};
+}
+/**
+* Sign in with Apple (OIDC). A thin subclass of {@link OidcProvider} — Apple IS
+* an OpenID Connect provider (issuer `https://appleid.apple.com`, discoverable
+* endpoints + JWKS), so the whole §7 ID-token validation, JWKS rotation, PKCE,
+* and discovery are inherited. Only the things Apple does differently are
+* wired/overridden here:
+*
+* 1. **No static client secret.** Apple's `client_secret` is a short-lived
+*    **ES256 JWT** signed with the developer's `.p8` key. The constructor wires
+*    a {@link ClientSecretFactory} ({@link makeAppleClientSecretFactory}) that
+*    mints + caches it per token exchange — no base seam to override.
+* 2. **`response_mode=form_post`.** Apple requires it whenever `email`/`name`
+*    scope is requested, so the callback is a cross-site **POST**. The
+*    `@aooth/auth-moost` `OAuthController` bounces that POST back to the normal
+*    GET callback path, so everything downstream (state, CSRF, exchange) is
+*    byte-identical to Google/GitHub.
+* 3. **String `email_verified`.** Apple violates OIDC by sending
+*    `email_verified` (and `is_private_email`) as the STRING `"true"`/`"false"`;
+*    {@link normalize} coerces it after the base's strict boolean-only pass.
+*
+* NOTE: the user's NAME arrives only on the FIRST authorization, in the
+* form_post `user` field (never in the id_token) — v1 deliberately does not
+* capture it, so `displayName` is undefined for Apple. Collect a display name
+* post-signup if you need one.
+*/
+var AppleProvider = class extends OidcProvider {
+	constructor(opts) {
+		if (!opts.teamId || !opts.keyId || !opts.privateKey) throw new OAuthError("INVALID_CONFIG", "AppleProvider requires 'teamId', 'keyId', and 'privateKey'");
+		super({
+			...opts,
+			id: "apple",
+			issuer: APPLE_ISSUER,
+			clientSecret: makeAppleClientSecretFactory({
+				clientId: opts.clientId,
+				teamId: opts.teamId,
+				keyId: opts.keyId,
+				privateKey: opts.privateKey,
+				ttlSec: opts.clientSecretTtlSec ?? DEFAULT_SECRET_TTL_SEC
+			}),
+			idTokenSigningAlgs: APPLE_SIGNING_ALGS,
+			scopes: opts.scopes ?? DEFAULT_APPLE_SCOPES
+		});
+	}
+	/** `email`/`name` scope makes Apple POST the callback — declare `form_post`. */
+	extraAuthorizationParams(_args) {
+		return { response_mode: "form_post" };
+	}
+	/** Coerce Apple's STRING `email_verified` (the base sets only a real boolean). */
+	normalize(payload) {
+		const profile = super.normalize(payload);
+		if (profile.emailVerified === void 0) {
+			const ev = payload.email_verified;
+			if (ev === "true") profile.emailVerified = true;
+			else if (ev === "false") profile.emailVerified = false;
+		}
+		return profile;
+	}
+};
+//#endregion
+//#region src/providers/fake.ts
+/**
+* Deterministic, network-free {@link IdentityProvider} for unit tests and the
+* `DEMO_MODE=test` fake-IdP e2e route (RFC §9). `exchange` resolves a `code`
+* to a pre-registered profile (or the default), so the whole
+* `start → callback → resolveUser → gates` round trip runs offline.
+*
+* It does NOT verify a nonce — it is the trusted test double; the real §7
+* nonce/JWKS assertions are exercised against {@link OidcProvider} with `jose`.
+*/
+var FakeIdentityProvider = class {
+	id;
+	authorizationEndpoint;
+	defaultProfile;
+	profiles = /* @__PURE__ */ new Map();
+	constructor(opts = {}) {
+		this.id = opts.id ?? "fake";
+		this.authorizationEndpoint = opts.authorizationEndpoint ?? "https://fake-idp.test/authorize";
+		this.defaultProfile = opts.defaultProfile;
+	}
+	/** Register the profile a given `code` resolves to. Returns `this` for chaining. */
+	setProfile(code, profile) {
+		this.profiles.set(code, profile);
+		return this;
+	}
+	authorizationUrl(args) {
+		return Promise.resolve(buildAuthorizeUrl(this.authorizationEndpoint, args, { nonce: true }));
+	}
+	exchange(args) {
+		const base = this.profiles.get(args.code) ?? this.defaultProfile;
+		if (!base) return Promise.reject(new OAuthError("EXCHANGE_FAILED", `Fake IdP has no profile for code '${args.code}'`));
+		return Promise.resolve({
+			...base,
+			provider: this.id
+		});
+	}
+};
+//#endregion
+//#region src/registry.ts
+const DEFAULT_CALLBACK_TEMPLATE = "/auth/oauth/:provider/callback";
+/**
+* Holds the configured {@link IdentityProvider}s + {@link FederatedPolicy} +
+* the shared signing/verification config (decision #2). Framework-agnostic —
+* phase 3 only DI-binds it. On construction it injects the shared config into
+* each provider that implements `applyDefaults`, and builds the per-provider
+* fixed redirect URIs.
+*/
+var OAuthProviderRegistry = class {
+	baseUrl;
+	stateSecret;
+	policy;
+	providers = /* @__PURE__ */ new Map();
+	callbackPathTemplate;
+	constructor(opts) {
+		if (!opts.baseUrl) throw new OAuthError("INVALID_CONFIG", "OAuthProviderRegistry requires a 'baseUrl'");
+		if (!opts.stateSecret) throw new OAuthError("INVALID_CONFIG", "OAuthProviderRegistry requires a 'stateSecret'");
+		this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+		this.stateSecret = opts.stateSecret;
+		this.policy = resolveFederatedPolicy(opts.policy);
+		this.callbackPathTemplate = opts.callbackPathTemplate ?? DEFAULT_CALLBACK_TEMPLATE;
+		const shared = {
+			clockToleranceSec: opts.clockToleranceSec,
+			jwks: opts.jwks,
+			clock: opts.clock,
+			fetch: opts.fetch
+		};
+		for (const p of opts.providers) {
+			if (this.providers.has(p.id)) throw new OAuthError("INVALID_CONFIG", `Duplicate provider id '${p.id}'`);
+			if (isConfigurableProvider(p)) p.applyDefaults(shared);
+			this.providers.set(p.id, p);
+		}
+	}
+	/** Is a provider with this id registered? */
+	has(id) {
+		return this.providers.has(id);
+	}
+	/** Resolve a provider, or `undefined`. */
+	get(id) {
+		return this.providers.get(id);
+	}
+	/** Resolve a provider, or throw `OAuthError('UNKNOWN_PROVIDER')` (→ HTTP 404 in phase 3). */
+	require(id) {
+		const p = this.providers.get(id);
+		if (!p) throw new OAuthError("UNKNOWN_PROVIDER", void 0, { provider: id });
+		return p;
+	}
+	/** Registered provider ids, in insertion order. */
+	ids() {
+		return [...this.providers.keys()];
+	}
+	/** All registered providers, in insertion order. */
+	list() {
+		return [...this.providers.values()];
+	}
+	/** The callback path for a provider (template with `:provider` substituted). */
+	callbackPath(providerId) {
+		return this.callbackPathTemplate.replace(":provider", encodeURIComponent(providerId));
+	}
+	/** The FIXED, exact-match-registered `redirect_uri` for a provider (`baseUrl` + callback path). */
+	redirectUri(providerId) {
+		return `${this.baseUrl}${this.callbackPath(providerId)}`;
+	}
+	/** Sign a state payload with the registry's `stateSecret`. */
+	signState(payload, opts) {
+		return signState(payload, this.stateSecret, opts);
+	}
+	/** Verify + decode a state token against the registry's `stateSecret`. */
+	verifyState(token, opts) {
+		return verifyState(token, this.stateSecret, opts);
+	}
+	/**
+	* Derive the stateless PKCE verifier + OIDC nonce from the signed-state
+	* `random` seed, using the registry's `stateSecret`. `/start` and the
+	* callback call this with the SAME seed to obtain the SAME pair without any
+	* server-side flow store. See {@link deriveSeededPkce}.
+	*/
+	deriveSeededPkce(seed) {
+		return deriveSeededPkce(this.stateSecret, seed);
+	}
+};
+//#endregion
+//#region src/federated-login-service.ts
+/**
+* The core federated-login logic (RFC §3.5): map a verified provider profile to
+* an aooth user id. Pure orchestration over `UserService` + `FederatedIdentityStore`
+* — no HTTP, no workflow, no token issuance (those are phase 3). Account-state
+* gating, MFA, and consent are NOT done here; they run as the existing login
+* workflow tail after the phase-3 `oauth-exchange` step sets the subject.
+*
+* Generic over the user shape `T` so a consumer's `UserService<DemoUser>` plugs
+* in directly; `resolveUser` only reads base `UserCredentials` fields.
+*/
+var FederatedLoginService = class {
+	users;
+	federated;
+	policy;
+	constructor(deps) {
+		this.users = deps.users;
+		this.federated = deps.federated;
+		this.policy = resolveFederatedPolicy(deps.policy);
+	}
+	/**
+	* Resolve a verified {@link NormalizedProfile} to an outcome (decision #1):
+	*
+	* 1. **Known** `(provider, subject)` → `linked`.
+	* 2. **Email match** (fresh verified email via `findByHandle`):
+	*    - `auto-link-if-verified` + trusted + verified → link → `auto-linked`;
+	*    - otherwise (incl. `require-interactive-link`, or auto-link conditions
+	*      unmet) → `needs-link` (caller completes via {@link linkIdentity}).
+	*    - `create-separate` ignores the match and falls to (3).
+	* 3. **New** → `denied` if `allowSignup === false`; else create + activate +
+	*    link → `created`.
+	*
+	* Every resolved outcome (`linked`/`auto-linked`/`created`) stamps
+	* `lastLoginAt` + refreshes the row's display snapshot via `touchLogin`.
+	*/
+	async resolveUser(profile) {
+		const known = await this.federated.find(profile.provider, profile.subject);
+		if (known) {
+			await this.touch(profile);
+			return {
+				kind: "linked",
+				userId: known.userId,
+				isNew: false
+			};
+		}
+		if (profile.email && this.policy.emailMatch !== "create-separate") {
+			const candidate = await this.users.findByHandle(profile.email);
+			if (candidate) {
+				if (this.policy.emailMatch === "auto-link-if-verified" && this.canAutoLink(profile)) {
+					await this.federated.link(this.newIdentity(profile, candidate.id));
+					await this.touch(profile);
+					return {
+						kind: "auto-linked",
+						userId: candidate.id,
+						isNew: false
+					};
+				}
+				return {
+					kind: "needs-link",
+					candidateUserId: candidate.id
+				};
+			}
+		}
+		if (!this.policy.allowSignup) return {
+			kind: "denied",
+			reason: "signup-disabled"
+		};
+		const userId = await this.createFederatedUser(profile);
+		await this.users.activateAccount(userId);
+		await this.federated.link(this.newIdentity(profile, userId));
+		await this.touch(profile);
+		return {
+			kind: "created",
+			userId,
+			isNew: true
+		};
+	}
+	/**
+	* Complete an interactive link (the `needs-link` outcome): attach
+	* `(provider, subject)` to an **already-authenticated** `userId`. Idempotent
+	* when it is already that user's. Throws `UserAuthError('ALREADY_EXISTS')`
+	* when the identity is already linked to a DIFFERENT user — the
+	* confused-deputy / account-injection guard (RFC §4).
+	*
+	* The CSRF / state↔session-userId binding that proves the request truly
+	* speaks for `userId` is the phase-3 controller's responsibility.
+	*/
+	async linkIdentity(params) {
+		const existing = await this.federated.find(params.provider, params.subject);
+		if (existing) {
+			if (existing.userId === params.userId) {
+				await this.federated.touchLogin(params.provider, params.subject, params.profile ? pickDefinedProfile(params.profile) : void 0);
+				return existing;
+			}
+			throw new UserAuthError("ALREADY_EXISTS", "This provider account is linked to a different user");
+		}
+		const rec = {
+			provider: params.provider,
+			subject: params.subject,
+			userId: params.userId,
+			...params.profile ? pickDefinedProfile(params.profile) : {}
+		};
+		return this.federated.link(rec);
+	}
+	/** Email-verified AND the provider is explicitly trusted (RFC §4). */
+	canAutoLink(profile) {
+		return profile.emailVerified === true && this.policy.trustEmailVerifiedFrom.includes(profile.provider);
+	}
+	/**
+	* Create a fresh user for an unmatched identity. Tries the policy username;
+	* on an `ALREADY_EXISTS` conflict falls back to the federated-unique
+	* `${provider}:${subject}`. Deliberately does NOT set the account `email`
+	* handle — promoting a provider email to the unique login handle is a gated
+	* phase-3 concern; the verified email is kept on the federated row instead.
+	*/
+	async createFederatedUser(profile) {
+		const desired = this.policy.usernameStrategy(profile);
+		const fallback = `${profile.provider}:${profile.subject}`;
+		try {
+			return (await this.users.createUser(desired)).id;
+		} catch (err) {
+			if (err instanceof UserAuthError && err.type === "ALREADY_EXISTS" && desired !== fallback) return (await this.users.createUser(fallback)).id;
+			throw err;
+		}
+	}
+	newIdentity(profile, userId) {
+		return {
+			provider: profile.provider,
+			subject: profile.subject,
+			userId,
+			...pickDefinedProfile(profile)
+		};
+	}
+	touch(profile) {
+		return this.federated.touchLogin(profile.provider, profile.subject, pickDefinedProfile(profile));
+	}
+};
+//#endregion
+export { AppleProvider, FakeIdentityProvider, FederatedLoginService, GithubProvider, GoogleProvider, OAuthError, OAuthProviderRegistry, OidcProvider, createPkcePair, defaultUsernameStrategy, deriveSeededPkce, generateNonce, generateRandomState, isConfigurableProvider, pkceChallengeFor, resolveFederatedPolicy, signState, verifyState };