@aooth/idp 0.1.8

package/dist/index.d.mts

@@ -0,0 +1,671 @@
+import { Clock } from "@aooth/auth";
+import { JWTPayload, JWTVerifyGetKey } from "jose";
+import { FederatedIdentity, FederatedIdentityStore, FederatedProfileSnapshot, UserService } from "@aooth/user";
+
+//#region src/errors.d.ts
+/**
+ * Federated-login failure taxonomy (RFC IDP.md §8). Mirrors `AuthError` /
+ * `UserAuthError` — a typed `Error` with a stable `type` code, an optional
+ * override `message`, and structured `details`.
+ *
+ * The HTTP/redirect mapping (§8 "fail soft — 302, never 500") is the phase-3
+ * `OAuthController`'s job; this layer only classifies. Messages are deliberately
+ * benign so the controller can surface them without leaking CSRF-vs-expiry.
+ */
+type OAuthErrorType = /** `:provider` did not resolve in the registry (→ HTTP 404 in phase 3). */"UNKNOWN_PROVIDER" /** Misconfigured provider/registry (missing clientId, issuer, baseUrl, secret). */ | "INVALID_CONFIG" /** Signed `state` failed signature/binding verification (CSRF). */ | "STATE_INVALID" /** Signed `state` is well-formed but past its TTL — restart `/start`. */ | "STATE_EXPIRED" /** Provider returned `?error=` or the user denied consent. */ | "PROVIDER_DENIED" /** Token-endpoint exchange failed: network, 5xx, malformed body, or `code` reuse. */ | "EXCHANGE_FAILED" /** JWKS / discovery document fetch failed — verification fails CLOSED (§7). */ | "JWKS_FAILED" /** OIDC ID-token failed the OIDC Core 3.1.3.7 validation list (§7). */ | "ID_TOKEN_INVALID" /** Policy needed a verified email but the provider returned none. */ | "EMAIL_UNAVAILABLE";
+declare class OAuthError extends Error {
+  readonly type: OAuthErrorType;
+  readonly details?: Record<string, unknown> | undefined;
+  readonly name = "OAuthError";
+  constructor(type: OAuthErrorType, message?: string, details?: Record<string, unknown> | undefined);
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * A provider profile normalized to a single shape across Google / OIDC / etc.
+ * Structural superset of `@aooth/user`'s {@link FederatedProfileSnapshot} (the
+ * display fields stored on the federated row) plus the join keys and the
+ * transient `raw` claims.
+ */
+interface NormalizedProfile extends FederatedProfileSnapshot {
+  /** Provider id — `'google'`, `'oidc:<issuer>'`, … (matches `IdentityProvider.id`). */
+  provider: string;
+  /** The IdP's stable subject id (`sub`) — the durable join key. */
+  subject: string;
+  /**
+   * The raw verified claims / userinfo. **Transient** — handed to a (future)
+   * claims-mapper hook, NEVER persisted on the federated row (RFC §7). Typed
+   * `unknown` so consumers narrow it explicitly.
+   */
+  raw: unknown;
+}
+interface AuthorizationUrlArgs {
+  /**
+   * FIXED per provider (`baseUrl` + the constant callback path); exact-match
+   * registered at the provider. The `exchange()` `redirectUri` MUST byte-equal
+   * this value.
+   */
+  redirectUri: string;
+  /** Opaque CSRF/binding token (a signed-state JWT — see `signState`). */
+  state: string;
+  /** PKCE S256 code challenge (base64url of SHA-256(verifier)). */
+  codeChallenge: string;
+  /** OIDC nonce minted at `/start`, asserted in `exchange()`. Ignored by pure OAuth2. */
+  nonce?: string;
+  /** Override the provider's default scope set. */
+  scopes?: string[];
+}
+interface ExchangeArgs {
+  /** Authorization `code` returned on the callback. */
+  code: string;
+  /** MUST byte-equal the `redirectUri` used to build the authorization URL. */
+  redirectUri: string;
+  /** The PKCE code verifier matching the challenge sent at `/start`. */
+  codeVerifier: string;
+  /** OIDC: assert `id_token.nonce === expectedNonce`. Omit for pure OAuth2. */
+  expectedNonce?: string;
+}
+/**
+ * A pluggable identity provider. Three members (RFC §3.4); built-ins
+ * additionally implement {@link ConfigurableProvider.applyDefaults} so the
+ * registry can inject shared verification config.
+ */
+interface IdentityProvider {
+  /** Stable id used in `:provider` routes, the federated `provider` column, and state binding. */
+  readonly id: string;
+  /** Build the `302`-target authorization URL. Async because OIDC discovers its endpoints. */
+  authorizationUrl(args: AuthorizationUrlArgs): Promise<string>;
+  /**
+   * Exchange the `code` for tokens, fully verify them (OIDC: §7 list), and
+   * normalize. Throws {@link OAuthError} (`EXCHANGE_FAILED` / `ID_TOKEN_INVALID`
+   * / `JWKS_FAILED` / `EMAIL_UNAVAILABLE`) on failure.
+   */
+  exchange(args: ExchangeArgs): Promise<NormalizedProfile>;
+}
+/**
+ * Minimal structural `fetch` — the global `fetch` satisfies it, and tests
+ * inject a deterministic fake. Only the members the OIDC client uses are
+ * declared.
+ */
+type FetchLike = (url: string, init?: {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}) => Promise<FetchResponseLike>;
+interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+/**
+ * Verification config the {@link OAuthProviderRegistry} sets once and injects
+ * into each provider that opts in via {@link ConfigurableProvider.applyDefaults}
+ * (decision #2 — registry holds the shared config, providers stay standalone).
+ * A provider's own constructor value always wins over an injected default.
+ */
+interface SharedProviderConfig {
+  /** Bounded clock skew for OIDC `exp`/`iat`/`nbf`, seconds. Default `5`. */
+  clockToleranceSec?: number;
+  /** JWKS caching/rotation knobs. */
+  jwks?: {
+    cacheTtlMs?: number;
+    refreshOnUnknownKid?: boolean;
+  };
+  /** Shared injectable clock (deterministic tests). */
+  clock?: Clock;
+  /** Shared injectable fetch (deterministic tests / custom agent). */
+  fetch?: FetchLike;
+}
+/** A provider that accepts registry-injected {@link SharedProviderConfig}. */
+interface ConfigurableProvider extends IdentityProvider {
+  applyDefaults(shared: SharedProviderConfig): void;
+}
+/** Structural check used by the registry to feature-detect `applyDefaults`. */
+declare function isConfigurableProvider(p: IdentityProvider): p is ConfigurableProvider;
+/**
+ * How a federated login that matches an existing local account **by email**
+ * is handled (RFC §4 — the account-takeover-sensitive knob).
+ */
+type EmailMatchPolicy = /** Never match by email — always create a fresh account. */"create-separate"
+/**
+ * Auto-link only when the provider's `email_verified === true` AND the
+ * provider is in `trustEmailVerifiedFrom`. A deliberate security downgrade.
+ */
+| "auto-link-if-verified" /** Default & safest: surface the candidate; require interactive proof-of-control to link. */ | "require-interactive-link";
+interface FederatedPolicy {
+  /** Default `'require-interactive-link'`. */
+  emailMatch?: EmailMatchPolicy;
+  /** `false` → unknown subjects with no link are rejected (invite-only). Default `true`. */
+  allowSignup?: boolean;
+  /** Derives the new account's username. Default: `email`, else `${provider}:${subject}`. */
+  usernameStrategy?: (p: NormalizedProfile) => string;
+  /** Providers whose `email_verified` we trust for `auto-link-if-verified`. Default `[]`. */
+  trustEmailVerifiedFrom?: string[];
+}
+type ResolvedFederatedPolicy = Required<FederatedPolicy>;
+/** Default username strategy: the verified email, else the stable `provider:subject`. */
+declare function defaultUsernameStrategy(p: NormalizedProfile): string;
+/** Apply RFC §4 safe defaults over a partial policy. */
+declare function resolveFederatedPolicy(policy?: FederatedPolicy): ResolvedFederatedPolicy;
+/**
+ * The outcome of {@link FederatedLoginService.resolveUser} (decision #1). A
+ * discriminated union — richer than the RFC's `{ userId, isNew }` sketch — so
+ * the phase-3 `oauth-exchange` step can branch: proceed into the gates
+ * (`linked`/`created`/`auto-linked`), divert to an interactive link sub-flow
+ * (`needs-link`), or fail soft (`denied`).
+ */
+type ResolveOutcome = /** Known `(provider, subject)` → its owning user. */{
+  kind: "linked";
+  userId: string;
+  isNew: false;
+} /** No match → a fresh account was created and linked. */ | {
+  kind: "created";
+  userId: string;
+  isNew: true;
+} /** Email matched an existing account and policy auto-linked it. */ | {
+  kind: "auto-linked";
+  userId: string;
+  isNew: false;
+} /** Email matched an existing account; interactive proof-of-control required to link. */ | {
+  kind: "needs-link";
+  candidateUserId: string;
+} /** Refused: signup disabled with no match, or policy needed an email the provider lacked. */ | {
+  kind: "denied";
+  reason: "signup-disabled" | "email-unavailable";
+};
+//#endregion
+//#region src/pkce.d.ts
+interface PkcePair {
+  /** The high-entropy secret kept server-side (cookie / wf state). */
+  verifier: string;
+  /** `base64url(SHA-256(verifier))` — sent in the authorization request. */
+  challenge: string;
+  /** Always `S256` — the plain method is intentionally not offered. */
+  method: "S256";
+}
+interface SeededPkce {
+  /** PKCE code verifier — `HMAC(secret, "…verifier:" + seed)`, re-derivable, never stored. */
+  verifier: string;
+  /** OIDC nonce — `HMAC(secret, "…nonce:" + seed)`, independent of the verifier. */
+  nonce: string;
+  /** `base64url(SHA-256(verifier))` — sent in the authorization request. */
+  challenge: string;
+  /** Always `S256`. */
+  method: "S256";
+}
+/**
+ * Mint a fresh PKCE pair. The 32-byte verifier base64url-encodes to 43 chars,
+ * comfortably inside RFC 7636's 43–128 range.
+ */
+declare function createPkcePair(): PkcePair;
+/** Recompute the S256 challenge for a known verifier (verification side). */
+declare function pkceChallengeFor(verifier: string): string;
+/** OIDC `nonce` — minted at `/start`, bound into state, asserted in `exchange()`. */
+declare function generateNonce(bytes?: number): string;
+/** Random component bound into the signed `state` (anti-CSRF / anti-replay). */
+declare function generateRandomState(bytes?: number): string;
+/**
+ * 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.
+ */
+declare function deriveSeededPkce(secret: string | Uint8Array, seed: string): SeededPkce;
+//#endregion
+//#region src/state.d.ts
+/**
+ * The CSRF/replay binding carried across the OAuth bounce (RFC §7). Signed into
+ * a compact HS256 JWT by {@link signState} so it is tamper-evident in the URL
+ * `state` param. `verifier`/`nonce` are optional: a stateless deployment puts
+ * them inside the signed state; a server-side-store deployment (the RFC's
+ * chosen design, §3.6) keeps them server-side and binds only `handle` here.
+ */
+interface OAuthStatePayload {
+  /** High-entropy anti-CSRF random; also double-submitted in a cookie (phase 3). */
+  random: string;
+  /** Bound provider id — a `google` state can't be replayed against `github`. */
+  provider: string;
+  /** Post-login app redirect target (validated as a same-origin relative path in phase 3). */
+  redirect: string;
+  /** PKCE code verifier — present only in the stateless mode. */
+  verifier?: string;
+  /** OIDC nonce — present only in the stateless mode. */
+  nonce?: string;
+  /** Opaque server-side wf-state handle (`wfs`) — present in the server-store mode. */
+  handle?: string;
+  /** Initiating user id — bound for `/link` to defeat the confused deputy (§4). */
+  userId?: string;
+}
+interface SignStateOptions {
+  /** State lifetime in seconds. Default `600` (10 min) — OAuth round-trips are short. */
+  ttlSec?: number;
+  clock?: Clock;
+}
+interface VerifyStateOptions {
+  clock?: Clock;
+}
+/**
+ * Sign the binding into a compact HS256 JWT. Field names are abbreviated to
+ * keep the URL `state` short; {@link verifyState} maps them back.
+ */
+declare function signState(payload: OAuthStatePayload, secret: string | Uint8Array, opts?: SignStateOptions): Promise<string>;
+/**
+ * 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.
+ */
+declare function verifyState(token: string, secret: string | Uint8Array, opts?: VerifyStateOptions): Promise<OAuthStatePayload>;
+//#endregion
+//#region src/providers/oidc.d.ts
+/** The four endpoints the OIDC client needs — discovered or supplied explicitly. */
+interface OidcDiscoveryDocument {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+}
+/** Context handed to a {@link ClientSecretFactory} at exchange time. */
+interface ClientSecretContext {
+  /**
+   * The provider's resolved clock (honors a registry-injected clock). Time-based
+   * secrets — Apple's ES256 JWT — stamp `iat`/`exp` from it.
+   */
+  clock: Clock;
+}
+/**
+ * A dynamic `client_secret` source. Most IdPs use a static string; a provider
+ * whose secret is minted per request (Apple's short-lived ES256 `.p8` JWT)
+ * supplies a factory instead. Called lazily at each token exchange — after the
+ * registry's `applyDefaults` — so it sees the resolved {@link ClientSecretContext.clock}.
+ */
+type ClientSecretFactory = (ctx: ClientSecretContext) => string | Promise<string>;
+interface OidcProviderOptions {
+  /** Provider id. Default `oidc:<issuer>`; `GoogleProvider` pins `'google'`. */
+  id?: string;
+  /** The exact issuer — used for discovery AND `iss` validation (must match). */
+  issuer: string;
+  clientId: string;
+  /**
+   * The OAuth `client_secret`: a static string, or a {@link ClientSecretFactory}
+   * for providers (Apple) that mint a short-lived secret per request.
+   */
+  clientSecret: string | ClientSecretFactory;
+  /** Requested scopes. Default `['openid', 'email', 'profile']`. */
+  scopes?: string[];
+  /**
+   * ID-token signing algs to accept (RFC §7: pin to asymmetric, reject
+   * `none`/HMAC). Default `['RS256', 'ES256']`. `none`/HS* are rejected purely
+   * by never appearing in this list.
+   */
+  idTokenSigningAlgs?: string[];
+  authorizationEndpoint?: string;
+  tokenEndpoint?: string;
+  jwksUri?: string;
+  /** Inject a discovery document (skips the `.well-known` fetch). */
+  discovery?: OidcDiscoveryDocument;
+  /** Inject a JWKS key resolver (e.g. `createLocalJWKSet`) — skips the remote JWKS fetch. */
+  jwks?: JWTVerifyGetKey;
+  /** Bounded clock skew for `exp`/`iat`/`nbf`, seconds. Default `5`. */
+  clockToleranceSec?: number;
+  /** Remote-JWKS cache lifetime, ms. Default `3_600_000` (1h). */
+  jwksCacheTtlMs?: number;
+  clock?: Clock;
+  fetch?: FetchLike;
+}
+/**
+ * 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.
+ */
+declare class OidcProvider implements ConfigurableProvider {
+  readonly id: string;
+  protected readonly issuer: string;
+  protected readonly clientId: string;
+  protected readonly clientSecret: string | ClientSecretFactory;
+  protected readonly scopes: string[];
+  protected readonly signingAlgs: string[];
+  private readonly explicitEndpoints?;
+  private readonly injectedDiscovery?;
+  private readonly injectedJwks?;
+  private clockToleranceSec?;
+  private jwksCacheTtlMs?;
+  private clockImpl?;
+  private fetchImpl?;
+  private discoveryCache?;
+  private jwksCache?;
+  constructor(opts: OidcProviderOptions);
+  /** Registry-injected shared config; a ctor value always wins (decision #2). */
+  applyDefaults(shared: SharedProviderConfig): void;
+  private get clock();
+  private get fetchFn();
+  /**
+   * 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.
+   */
+  private resolveClientSecret;
+  /**
+   * 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).
+   */
+  protected extraAuthorizationParams(_args: AuthorizationUrlArgs): Record<string, string>;
+  authorizationUrl(args: AuthorizationUrlArgs): Promise<string>;
+  exchange(args: ExchangeArgs): Promise<NormalizedProfile>;
+  private postToken;
+  private verifyIdToken;
+  /**
+   * 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.
+   */
+  protected normalize(payload: JWTPayload): NormalizedProfile;
+  private resolveEndpoints;
+  /** OIDC discovery MUST echo the requested issuer (guards a swapped doc). */
+  private validateDiscovery;
+  private getJwks;
+}
+//#endregion
+//#region src/providers/google.d.ts
+/** Google options = OIDC options minus the pinned `id`/`issuer`. */
+type GoogleProviderOptions = Omit<OidcProviderOptions, "id" | "issuer">;
+/**
+ * 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}.
+ */
+declare class GoogleProvider extends OidcProvider {
+  constructor(opts: GoogleProviderOptions);
+}
+//#endregion
+//#region src/providers/github.d.ts
+interface GithubProviderOptions {
+  /** Provider id. Default `'github'`. */
+  id?: string;
+  clientId: string;
+  clientSecret: string;
+  /** Requested scopes. Default `['read:user', 'user:email']` (email needs `user:email`). */
+  scopes?: string[];
+  /** `User-Agent` sent on the GitHub API calls (GitHub REQUIRES one). Default `'aoothjs'`. */
+  userAgent?: string;
+  authorizationEndpoint?: string;
+  tokenEndpoint?: string;
+  userEndpoint?: string;
+  emailsEndpoint?: string;
+  /** OAuth2 only — no clock is needed (no token-time validation). */
+  fetch?: FetchLike;
+}
+/**
+ * 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.
+ */
+declare class GithubProvider implements ConfigurableProvider {
+  readonly id: string;
+  private readonly clientId;
+  private readonly clientSecret;
+  private readonly scopes;
+  private readonly userAgent;
+  private readonly authorizationEndpoint;
+  private readonly tokenEndpoint;
+  private readonly userEndpoint;
+  private readonly emailsEndpoint;
+  private fetchImpl?;
+  constructor(opts: GithubProviderOptions);
+  /** Registry-injected shared config; a ctor value always wins (decision #2). */
+  applyDefaults(shared: SharedProviderConfig): void;
+  private get fetchFn();
+  authorizationUrl(args: AuthorizationUrlArgs): Promise<string>;
+  exchange(args: ExchangeArgs): Promise<NormalizedProfile>;
+  /** POST the authorization `code` → access token (GitHub returns JSON when asked). */
+  private redeemCode;
+  private fetchUser;
+  /**
+   * 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).
+   */
+  private fetchPrimaryEmail;
+  private apiGet;
+}
+//#endregion
+//#region src/providers/apple.d.ts
+interface AppleProviderOptions extends Omit<OidcProviderOptions, "id" | "issuer" | "clientSecret" | "idTokenSigningAlgs" | "scopes"> {
+  /** The Services ID — Sign in with Apple's OAuth `client_id` (and the id_token `aud`). */
+  clientId: string;
+  /** Apple Developer Team ID (10 chars) — the client-secret JWT `iss`. */
+  teamId: string;
+  /** The `.p8` private key's Key ID — the client-secret JWT header `kid`. */
+  keyId: string;
+  /** The `.p8` EC P-256 private key in PKCS#8 PEM form — mints the ES256 client secret. */
+  privateKey: string;
+  /** Requested scopes. Default `['openid', 'email']`. */
+  scopes?: string[];
+  /** Client-secret JWT lifetime, seconds (Apple max ≈ 6 months). Default `3600`. */
+  clientSecretTtlSec?: number;
+}
+/**
+ * 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.
+ */
+declare class AppleProvider extends OidcProvider {
+  constructor(opts: AppleProviderOptions);
+  /** `email`/`name` scope makes Apple POST the callback — declare `form_post`. */
+  protected extraAuthorizationParams(_args: AuthorizationUrlArgs): Record<string, string>;
+  /** Coerce Apple's STRING `email_verified` (the base sets only a real boolean). */
+  protected normalize(payload: JWTPayload): NormalizedProfile;
+}
+//#endregion
+//#region src/providers/fake.d.ts
+interface FakeIdentityProviderOptions {
+  /** Provider id. Default `'fake'`. */
+  id?: string;
+  /** The fake authorization endpoint a phase-3 e2e route bounces through. */
+  authorizationEndpoint?: string;
+  /** Profile returned for any `code` with no specific registration. */
+  defaultProfile?: Omit<NormalizedProfile, "provider">;
+}
+/**
+ * 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`.
+ */
+declare class FakeIdentityProvider implements IdentityProvider {
+  readonly id: string;
+  private readonly authorizationEndpoint;
+  private readonly defaultProfile?;
+  private readonly profiles;
+  constructor(opts?: FakeIdentityProviderOptions);
+  /** Register the profile a given `code` resolves to. Returns `this` for chaining. */
+  setProfile(code: string, profile: Omit<NormalizedProfile, "provider">): this;
+  authorizationUrl(args: AuthorizationUrlArgs): Promise<string>;
+  exchange(args: ExchangeArgs): Promise<NormalizedProfile>;
+}
+//#endregion
+//#region src/registry.d.ts
+interface OAuthProviderRegistryOptions {
+  /** Public origin — `redirect_uri` is built as `baseUrl` + the callback path (§3.7). */
+  baseUrl: string;
+  /** HMAC secret that signs the `state` JWT (and, in phase 3, the Lax PKCE cookie). */
+  stateSecret: string;
+  /** The configured providers. Duplicate ids are rejected. */
+  providers: IdentityProvider[];
+  /** Account-matching policy (RFC §4). Safe defaults applied. */
+  policy?: FederatedPolicy;
+  /**
+   * Callback path template; `:provider` is substituted per provider. Default
+   * `/auth/oauth/:provider/callback` (matches the phase-3 `OAuthController`).
+   */
+  callbackPathTemplate?: string;
+  clockToleranceSec?: number;
+  jwks?: {
+    cacheTtlMs?: number;
+    refreshOnUnknownKid?: boolean;
+  };
+  clock?: Clock;
+  fetch?: FetchLike;
+}
+/**
+ * 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.
+ */
+declare class OAuthProviderRegistry {
+  readonly baseUrl: string;
+  readonly stateSecret: string;
+  readonly policy: ResolvedFederatedPolicy;
+  private readonly providers;
+  private readonly callbackPathTemplate;
+  constructor(opts: OAuthProviderRegistryOptions);
+  /** Is a provider with this id registered? */
+  has(id: string): boolean;
+  /** Resolve a provider, or `undefined`. */
+  get(id: string): IdentityProvider | undefined;
+  /** Resolve a provider, or throw `OAuthError('UNKNOWN_PROVIDER')` (→ HTTP 404 in phase 3). */
+  require(id: string): IdentityProvider;
+  /** Registered provider ids, in insertion order. */
+  ids(): string[];
+  /** All registered providers, in insertion order. */
+  list(): IdentityProvider[];
+  /** The callback path for a provider (template with `:provider` substituted). */
+  callbackPath(providerId: string): string;
+  /** The FIXED, exact-match-registered `redirect_uri` for a provider (`baseUrl` + callback path). */
+  redirectUri(providerId: string): string;
+  /** Sign a state payload with the registry's `stateSecret`. */
+  signState(payload: OAuthStatePayload, opts?: SignStateOptions): Promise<string>;
+  /** Verify + decode a state token against the registry's `stateSecret`. */
+  verifyState(token: string, opts?: VerifyStateOptions): Promise<OAuthStatePayload>;
+  /**
+   * 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: string): SeededPkce;
+}
+//#endregion
+//#region src/federated-login-service.d.ts
+interface FederatedLoginServiceDeps<T extends object = object> {
+  /** Concrete user orchestrator (RFC: idp depends on the concrete class). */
+  users: UserService<T>;
+  /** The account-linking store from `@aooth/user` (memory or atscript-db). */
+  federated: FederatedIdentityStore;
+  /** Account-matching policy (RFC §4). Safe defaults applied. */
+  policy?: FederatedPolicy;
+}
+/**
+ * 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.
+ */
+declare class FederatedLoginService<T extends object = object> {
+  private readonly users;
+  private readonly federated;
+  readonly policy: ResolvedFederatedPolicy;
+  constructor(deps: FederatedLoginServiceDeps<T>);
+  /**
+   * 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`.
+   */
+  resolveUser(profile: NormalizedProfile): Promise<ResolveOutcome>;
+  /**
+   * 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.
+   */
+  linkIdentity(params: {
+    provider: string;
+    subject: string;
+    userId: string;
+    profile?: FederatedProfileSnapshot;
+  }): Promise<FederatedIdentity>;
+  /** Email-verified AND the provider is explicitly trusted (RFC §4). */
+  private canAutoLink;
+  /**
+   * 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.
+   */
+  private createFederatedUser;
+  private newIdentity;
+  private touch;
+}
+//#endregion
+export { AppleProvider, type AppleProviderOptions, type AuthorizationUrlArgs, type ConfigurableProvider, type EmailMatchPolicy, type ExchangeArgs, FakeIdentityProvider, type FakeIdentityProviderOptions, FederatedLoginService, type FederatedLoginServiceDeps, type FederatedPolicy, type FetchLike, type FetchResponseLike, GithubProvider, type GithubProviderOptions, GoogleProvider, type GoogleProviderOptions, type IdentityProvider, type NormalizedProfile, OAuthError, type OAuthErrorType, OAuthProviderRegistry, type OAuthProviderRegistryOptions, type OAuthStatePayload, type OidcDiscoveryDocument, OidcProvider, type OidcProviderOptions, type PkcePair, type ResolveOutcome, type ResolvedFederatedPolicy, type SeededPkce, type SharedProviderConfig, type SignStateOptions, type VerifyStateOptions, createPkcePair, defaultUsernameStrategy, deriveSeededPkce, generateNonce, generateRandomState, isConfigurableProvider, pkceChallengeFor, resolveFederatedPolicy, signState, verifyState };