@ultimat3/auth 30.9.0 → 31.0.0

package/src/identity-provider-oidc.ts

@@ -0,0 +1,142 @@
+// Single responsibility: a registered OAuth2/OIDC provider as an `IdentityProvider` — the existing
+// handshake (`beginOAuth`), exchange (`exchangeOAuthCode`) and profile read (`readOAuthProfile`)
+// behind the port, no protocol of its own. The port adds one thing: the handshake's `state` is
+// claimed ONCE in the shared replay store, keyed on when it was issued, before the code is spent.
+
+import { timingSafeEqual } from '@ultimat3/core';
+import {
+  type IdentityProvider,
+  type IdentityRedirect,
+  replayStepFor,
+  type VerifiedIdentity,
+} from './identity-provider';
+import { isRecord } from './json';
+import type { IdTokenKeys } from './jwks';
+import {
+  assertOAuthCallback,
+  beginOAuth,
+  type OAuthHandshake,
+  type OAuthProviderId,
+} from './oauth';
+import { DEFAULT_HANDSHAKE_TTL_MS } from './oauth-cookie';
+import { oauthDenied, oauthStateInvalid } from './oauth-errors';
+import {
+  exchangeOAuthCode,
+  type OAuthClientCredentials,
+  type OAuthFetch,
+  oauthCredentials,
+} from './oauth-exchange';
+import { oauthGrantContext } from './oauth-grant-context';
+import { readOAuthProfile } from './oauth-profile';
+
+export interface OidcIdentityProviderConfig {
+  /** A registered `OAuthProvider` id (`registerOAuthProvider`, or a built-in). */
+  readonly provider: OAuthProviderId;
+  /** Default: the provider's two env vars, read per call, never at import. */
+  readonly credentials?: OAuthClientCredentials | undefined;
+  readonly scopes?: readonly string[] | undefined;
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly idTokenKeys?: IdTokenKeys | undefined;
+}
+
+const FIELDS = ['state', 'nonce', 'verifier', 'redirectUri', 'authorizeUrl'] as const;
+
+/** The handshake, and when it was issued — the instant its single-use claim is keyed on. */
+interface StoredHandshake {
+  readonly handshake: OAuthHandshake;
+  readonly issuedAt: number;
+}
+
+function readHandshake(provider: OAuthProviderId, state: string): StoredHandshake {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(state);
+  } catch {
+    parsed = null;
+  }
+  if (
+    !isRecord(parsed) ||
+    !FIELDS.every((field) => typeof parsed[field] === 'string') ||
+    typeof parsed['issuedAt'] !== 'number' ||
+    !Number.isFinite(parsed['issuedAt'])
+  ) {
+    throw oauthStateInvalid(provider, 'the stored handshake is not a handshake');
+  }
+  const field = (name: (typeof FIELDS)[number]): string => String(parsed[name]);
+  return {
+    issuedAt: parsed['issuedAt'],
+    handshake: {
+      provider,
+      state: field('state'),
+      nonce: field('nonce'),
+      verifier: field('verifier'),
+      redirectUri: field('redirectUri'),
+      authorizeUrl: field('authorizeUrl'),
+    },
+  };
+}
+
+export function oidcIdentityProvider(config: OidcIdentityProviderConfig): IdentityProvider {
+  const id = config.provider;
+  const credentials = (): OAuthClientCredentials => config.credentials ?? oauthCredentials(id);
+  const provider: IdentityProvider = {
+    id,
+    protocol: 'oidc',
+    callbackMethod: 'GET',
+    async begin({ callbackUrl, clock }): Promise<IdentityRedirect> {
+      const handshake = beginOAuth({
+        provider: id,
+        clientId: credentials().clientId,
+        redirectUri: callbackUrl,
+        scopes: config.scopes,
+      });
+      const state = {
+        ...Object.fromEntries(FIELDS.map((field) => [field, handshake[field]])),
+        issuedAt: clock.now().getTime(),
+      };
+      return { location: handshake.authorizeUrl, state: JSON.stringify(state) };
+    },
+    answers(state, params) {
+      try {
+        return timingSafeEqual(readHandshake(id, state).handshake.state, params['state'] ?? '');
+      } catch {
+        return false;
+      }
+    },
+    async complete({ state, params, callbackUrl, clock, replay }): Promise<VerifiedIdentity> {
+      const { handshake, issuedAt } = readHandshake(id, state);
+      if (handshake.redirectUri !== callbackUrl) {
+        throw oauthStateInvalid(id, 'the handshake was started for another callback URL');
+      }
+      const declined = params['error'];
+      if (declined !== undefined && declined !== '') {
+        throw oauthDenied(id, declined, params['error_description'] ?? null);
+      }
+      const callback = { state: params['state'] ?? '', code: params['code'] ?? '' };
+      // The state check first, so a forged callback cannot spend the real browser's handshake.
+      assertOAuthCallback(handshake, callback);
+      const now = clock.now();
+      // Keyed on when the handshake was ISSUED, the way SAML's claim is keyed on NotOnOrAfter: a
+      // horizon read off `now` moved with every retry, so each 30 s step was a fresh claim row.
+      const horizon = new Date(issuedAt + DEFAULT_HANDSHAKE_TTL_MS);
+      if (horizon.getTime() < now.getTime()) {
+        throw oauthStateInvalid(id, 'the handshake expired before the provider answered');
+      }
+      if (!(await replay.claim(`oidc:${id}:${handshake.state}`, replayStepFor(horizon), now))) {
+        throw oauthStateInvalid(id, 'this handshake was already completed');
+      }
+      const options = { fetch: config.fetch, timeoutMs: config.timeoutMs };
+      const tokens = await exchangeOAuthCode(handshake, callback, {
+        credentials: credentials(),
+        clock,
+        ...options,
+        keys: config.idTokenKeys,
+      });
+      const { profile, userinfo } = await readOAuthProfile(id, tokens, options);
+      const oauth = oauthGrantContext(profile, tokens, options, userinfo);
+      return { profile, expiresAt: tokens.expiresAt, claims: oauth.idTokenClaims ?? {}, oauth };
+    },
+  };
+  return Object.freeze(provider);
+}

package/src/identity-provider-route-core.ts

@@ -0,0 +1,253 @@
+// Single responsibility: the ONE implementation of the two sign-in legs over any `IdentityProvider`
+// — start (`begin`, seal the state, 302) and callback (open it, `complete`, `signInWithIdentity`,
+// 303; coded JSON on refusal). `identityProviderRoutes` and `oauthLogin` are this function with two
+// policies, so the state cookie, the refusal body and the redirect rules cannot drift apart.
+
+import {
+  EnvMissingError,
+  isUltimateError,
+  logger,
+  renderFixShellArg,
+  type UltimateError,
+} from '@ultimat3/core';
+import type { Auth } from './auth';
+import {
+  type IdentityProvider,
+  signInWithIdentity,
+  type VerifiedIdentity,
+} from './identity-provider';
+import {
+  clearIdentityStateCookie,
+  identityStateCookie,
+  readIdentityState,
+} from './identity-provider-cookie';
+import { oauthRouteStatus } from './identity-provider-status';
+import { oauthStateInvalid } from './oauth-errors';
+import type { OAuthGrants } from './oauth-login';
+import {
+  OAUTH_CALLBACK_ROUTE_PATH,
+  OAUTH_START_ROUTE_PATH,
+  oauthCallbackPath,
+} from './oauth-paths';
+import { samlResponseInvalid } from './saml-errors';
+
+export interface SignInRouteDescriptor {
+  readonly method: 'GET' | 'POST';
+  /** The mount pattern, `:provider` included. The handler re-reads it off the request itself. */
+  readonly path: string;
+  readonly name: string;
+  /** Both legs are public by definition — they are how an anonymous visitor stops being one. */
+  readonly auth: 'public';
+  /** What a router mounts as the route's `meta`, verbatim: `meta: leg.meta`. */
+  readonly meta: SignInRouteMeta;
+  handle(request: Request): Promise<Response>;
+}
+
+/**
+ * The route meta, structurally `@ultimat3/http`'s (`Route['meta']`): this package is its tier and
+ * cannot import it. The POST leg — SAML's ACS — is `csrf: 'cookieless'` with its own
+ * `authenticate: () => null`: the IdP answers with an auto-submitted CROSS-SITE form, which the csrf
+ * stage refuses on any other route. CSRF is still defended there, by the protocol: the answer must
+ * carry this browser's RelayState (`answers()`, timing-safe against the HMAC-sealed state cookie)
+ * and its assertion must name this request's ID as InResponseTo — an attacker's form has neither.
+ * And no session cookie decides anything on it.
+ */
+export interface SignInRouteMeta {
+  readonly name: string;
+  readonly auth: 'public';
+  // No `| undefined`: http's `Route['meta']` takes these absent or set, never `undefined`.
+  readonly csrf?: 'cookieless';
+  readonly authenticate?: () => null;
+}
+
+/** What both front doors accept. */
+export interface SignInRouteOptions {
+  /** The origin the IdP answers to. Defaults to `APP_URL`; never the request's `Host`. */
+  readonly baseUrl?: string | undefined;
+  /** Defaults to `SESSION_SECRET`. Seals the state across the two requests. */
+  readonly secret?: string | undefined;
+  /** A fixed landing path, never `?next=`: `nextAfterSignIn` in `@ultimat3/http` is the one check. */
+  readonly successPath?: string | undefined;
+  /** The client address recorded on the session; `@ultimat3/http` knows the proxy chain. */
+  readonly clientIp?: ((request: Request) => string | null | undefined) | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/** What differs between the two front doors. */
+export interface SignInRoutePolicy {
+  /** The provider a URL segment names and this app enabled, or `unknown(segment)` for both. */
+  resolve(segment: string, leg: 'start' | 'callback'): IdentityProvider;
+  /** The one 404: unknown, not enabled, or answered by the wrong method — never told apart. */
+  unknown(segment: string): UltimateError;
+  /** `auth.sso` / `auth.oauth`: the log event prefix (`<prefix>.refused`). */
+  readonly event: string;
+  readonly names: { readonly start: string; readonly callback: string; readonly acs: string };
+  /** A throw with no code, logged and turned into the refusal served. Its text never is. */
+  uncoded(error: unknown): UltimateError;
+  grants(identity: VerifiedIdentity): Promise<OAuthGrants | undefined> | OAuthGrants | undefined;
+}
+
+export interface SignInRoutes {
+  readonly start: SignInRouteDescriptor;
+  /** OIDC's redirect back. */
+  readonly callback: SignInRouteDescriptor;
+  /** SAML's Assertion Consumer Service: the same path, POSTed. */
+  readonly acs: SignInRouteDescriptor;
+}
+
+const MAX_FORM_BYTES = 512 * 1024;
+const FRAMEWORK_CODE = /^X_[A-Z0-9_]+$/;
+
+function problem(policy: SignInRoutePolicy, error: unknown, cookies: readonly string[]): Response {
+  const refusal = isUltimateError(error) ? error : policy.uncoded(error);
+  const status = oauthRouteStatus(refusal.code);
+  const fields = { code: refusal.code, status, cause: refusal.cause, fix: refusal.fix };
+  if (status >= 500) logger.error(`${policy.event}.refused`, fields);
+  else logger.info(`${policy.event}.refused`, fields);
+  const headers = new Headers({ 'content-type': 'application/json; charset=utf-8' });
+  for (const cookie of cookies) headers.append('set-cookie', cookie);
+  // An anonymous caller reads the code, its title and docs, and one fixed sentence; the authored
+  // cause and fix name env vars and what an IdP answered, so they go to the log only.
+  const body = {
+    code: refusal.code,
+    title: refusal.title,
+    cause: `the sign-in was refused; its cause and its fix are in this server’s log under ${policy.event}.refused`,
+    fix: FRAMEWORK_CODE.test(refusal.code)
+      ? `x errors explain ${renderFixShellArg(refusal.code, '<CODE>')} --json`
+      : 'x errors list --json',
+    docs: refusal.docs,
+  };
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+function segmentOf(request: Request, leg: 'start' | 'callback'): string {
+  const parts = new URL(request.url).pathname.split('/').filter((part) => part !== '');
+  return parts[leg === 'start' ? parts.length - 1 : parts.length - 2] ?? '';
+}
+
+function origin(options: SignInRouteOptions): string {
+  const declared = (options.baseUrl ?? (options.env ?? Bun.env)['APP_URL'] ?? '').trim();
+  if (declared === '') {
+    throw new EnvMissingError({
+      cause:
+        'APP_URL is not set and the sign-in routes were given no baseUrl, so there is no declared origin to build the IdP callback URL from',
+      fix: 'export APP_URL=http://localhost:3000   # the origin this app is served from',
+      meta: { key: 'APP_URL' },
+    });
+  }
+  return declared.replace(/\/+$/, '');
+}
+
+/**
+ * The form body, never more than `MAX_FORM_BYTES` of it: a declared length over the cap refuses
+ * before one byte is read, and an undeclared or lying one is cut off at the cap as it streams.
+ */
+async function formParams(request: Request, provider: string): Promise<Record<string, string>> {
+  const tooLarge = () => samlResponseInvalid(provider, 'encoding', 'the posted form is too large');
+  const declared = Number(request.headers.get('content-length') ?? '0');
+  if (!Number.isFinite(declared) || declared > MAX_FORM_BYTES) throw tooLarge();
+  const decoder = new TextDecoder();
+  let text = '';
+  let size = 0;
+  const reader = request.body?.getReader();
+  for (;;) {
+    const next = await reader?.read();
+    if (next === undefined || next.done) break;
+    size += next.value.byteLength;
+    if (size > MAX_FORM_BYTES) {
+      await reader?.cancel();
+      throw tooLarge();
+    }
+    text += decoder.decode(next.value, { stream: true });
+  }
+  text += decoder.decode();
+  return Object.fromEntries(new URLSearchParams(text));
+}
+
+export function signInRoutes(
+  auth: Auth,
+  options: SignInRouteOptions,
+  policy: SignInRoutePolicy,
+): SignInRoutes {
+  const seal = {
+    clock: auth.clock,
+    ...(options.secret === undefined ? {} : { secret: options.secret }),
+  };
+
+  const start = async (request: Request): Promise<Response> => {
+    try {
+      // Before the provider: asked after, a missing origin answered 500 for an enabled provider
+      // and 404 for one that is not — an oracle for the app's configuration.
+      const base = origin(options);
+      const provider = policy.resolve(segmentOf(request, 'start'), 'start');
+      const callbackUrl = `${base}${oauthCallbackPath(provider.id)}`;
+      const redirect = await provider.begin({ callbackUrl, clock: auth.clock });
+      const headers = new Headers({ location: redirect.location });
+      headers.append('set-cookie', identityStateCookie(provider, redirect.state, seal));
+      return new Response(null, { status: 302, headers });
+    } catch (error) {
+      return problem(policy, error, []);
+    }
+  };
+
+  const callback = async (request: Request): Promise<Response> => {
+    const segment = segmentOf(request, 'callback');
+    // Set only once the answer is bound to this browser's state; then cleared on every outcome,
+    // since that answer is spent either way. An unbound answer — a junk cross-site POST riding the
+    // SameSite=None cookie — clears nothing, so it cannot end a sign-in in flight.
+    const clear: string[] = [];
+    try {
+      const base = origin(options);
+      const provider = policy.resolve(segment, 'callback');
+      // A provider answers by one method: SAML's POST binding, or OIDC's redirect.
+      if (request.method !== provider.callbackMethod) throw policy.unknown(provider.id);
+      const params =
+        request.method === 'POST'
+          ? await formParams(request, provider.id)
+          : Object.fromEntries(new URL(request.url).searchParams);
+      const state = readIdentityState(request, provider, seal);
+      if (!provider.answers(state, params)) {
+        throw oauthStateInvalid(provider.id, 'the answer does not carry this browser\u2019s state');
+      }
+      clear.push(clearIdentityStateCookie(provider.id, provider.callbackMethod));
+      const identity = await provider.complete({
+        state,
+        params,
+        callbackUrl: `${base}${oauthCallbackPath(provider.id)}`,
+        clock: auth.clock,
+        replay: auth.totpReplay,
+      });
+      const grants = await policy.grants(identity);
+      const result = await signInWithIdentity(auth, identity, {
+        ...(grants === undefined ? {} : { grants }),
+        ip: options.clientIp?.(request) ?? null,
+        userAgent: request.headers.get('user-agent'),
+      });
+      const headers = new Headers({ location: options.successPath ?? '/' });
+      headers.append('set-cookie', result.cookie);
+      for (const cookie of clear) headers.append('set-cookie', cookie);
+      // 303: the answer may arrive as a POST, and the destination is a GET either way.
+      return new Response(null, { status: 303, headers });
+    } catch (error) {
+      return problem(policy, error, clear);
+    }
+  };
+
+  const route = (
+    method: 'GET' | 'POST',
+    path: string,
+    name: string,
+    handle: (request: Request) => Promise<Response>,
+  ): SignInRouteDescriptor => {
+    const meta: SignInRouteMeta =
+      method === 'POST'
+        ? { name, auth: 'public', csrf: 'cookieless', authenticate: () => null }
+        : { name, auth: 'public' };
+    return Object.freeze({ method, path, name, auth: 'public', meta: Object.freeze(meta), handle });
+  };
+  return Object.freeze({
+    start: route('GET', OAUTH_START_ROUTE_PATH, policy.names.start, start),
+    callback: route('GET', OAUTH_CALLBACK_ROUTE_PATH, policy.names.callback, callback),
+    acs: route('POST', OAUTH_CALLBACK_ROUTE_PATH, policy.names.acs, callback),
+  });
+}

package/src/identity-provider-routes.ts

@@ -0,0 +1,78 @@
+// Single responsibility: `identityProviderRoutes(auth, { providers })` — the sign-in routes over a
+// fixed list of `IdentityProvider`s (SAML, OIDC, an app's own). The legs themselves are
+// `identity-provider-route-core.ts`, shared with `oauthLogin`; this file is the list, its one 404,
+// and the grant seam over a `VerifiedIdentity`.
+
+import {
+  ConfigInvalidError,
+  logger,
+  renderCauseValue,
+  renderThrowable,
+  type UltimateError,
+} from '@ultimat3/core';
+import type { Auth } from './auth';
+import { AuthError } from './errors';
+import type { IdentityProvider, ResolveIdentityGrants } from './identity-provider';
+import {
+  type SignInRouteDescriptor,
+  type SignInRouteOptions,
+  type SignInRoutes,
+  signInRoutes,
+} from './identity-provider-route-core';
+
+export type IdentityRouteDescriptor = SignInRouteDescriptor;
+export type IdentityProviderRoutes = SignInRoutes;
+
+export interface IdentityProviderRoutesOptions extends SignInRouteOptions {
+  readonly providers: readonly IdentityProvider[];
+  /** What a verified identity is entitled to — business convention, never shipped (axiom 8). */
+  readonly resolveGrants?: ResolveIdentityGrants | undefined;
+}
+
+export const identityProviderUnknown = (segment: string): AuthError =>
+  new AuthError({
+    code: 'X_IDENTITY_PROVIDER_UNKNOWN',
+    cause: `no identity provider ${renderCauseValue(segment)} is served by these routes`,
+    fix: 'identityProviderRoutes(auth, { providers: [samlIdentityProvider({ id, … })] })  // and add the id to defineAuth({ providers }), or correct the id in the link',
+  });
+
+/** An uncoded throw's text goes to the log only — never into a public body. */
+function uncoded(error: unknown): UltimateError {
+  logger.error('auth.sso.uncoded_failure', { detail: renderThrowable(error) });
+  return new ConfigInvalidError({
+    cause:
+      'a provider, adapter or fetch this package does not own threw a value with no error code',
+    fix: 'new AuthError({ code, cause, fix })  // throw it from the provider or adapter that threw; its value is logged as auth.sso.uncoded_failure',
+  });
+}
+
+export function identityProviderRoutes(
+  auth: Auth,
+  options: IdentityProviderRoutesOptions,
+): IdentityProviderRoutes {
+  const byId = new Map<string, IdentityProvider>();
+  for (const provider of options.providers) {
+    if (byId.has(provider.id)) {
+      throw new ConfigInvalidError({
+        cause: `two identity providers claim the id ${renderCauseValue(provider.id)}`,
+        fix: 'identityProviderRoutes(auth, { providers: [first, second] })  // each with its own id',
+      });
+    }
+    byId.set(provider.id, provider);
+  }
+  return signInRoutes(auth, options, {
+    // Unknown and not-enabled are one 404, so the routes describe no configuration.
+    resolve(segment) {
+      const provider = byId.get(segment);
+      if (provider === undefined || !auth.providers.includes(segment)) {
+        throw identityProviderUnknown(segment);
+      }
+      return provider;
+    },
+    unknown: identityProviderUnknown,
+    event: 'auth.sso',
+    names: { start: 'auth.sso.start', callback: 'auth.sso.callback', acs: 'auth.sso.acs' },
+    uncoded,
+    grants: (identity) => options.resolveGrants?.(identity),
+  });
+}

package/src/identity-provider-status.ts

@@ -0,0 +1,45 @@
+// Single responsibility: the code → HTTP status table the sign-in route descriptors answer with
+// when driven outside a pipeline — one table for every IdentityProvider route, OIDC and SAML alike,
+// pinned to `@ultimat3/http`'s `statusFor` by `scripts/oauth-route-status.test.ts` and
+// `scripts/identity-route-status.test.ts`.
+
+/**
+ * HTTP status per code for the sign-in descriptors (`identityProviderRoutes`, and `oauthLogin` over
+ * it), driven OUTSIDE a pipeline — a bare `Request` in, a
+ * `Response` out, which is the whole point of a descriptor. `@ultimat3/http`'s `error-map.ts` OWNS
+ * these numbers and is where a new one is declared; this package is the same tier and can never
+ * import it, so the table is a copy the pin `scripts/oauth-route-status.test.ts` holds identical to
+ * `statusFor()`. Everything absent is the provider's fault until proven otherwise: 502.
+ */
+export const OAUTH_ROUTE_STATUS: Readonly<Record<string, number>> = {
+  X_OAUTH_PROVIDER_UNKNOWN: 404,
+  X_OAUTH_DENIED: 403,
+  X_OAUTH_STATE_INVALID: 400,
+  X_OAUTH_TOKEN_INVALID: 400,
+  X_UNAUTHENTICATED: 401,
+  X_MFA_REQUIRED: 401,
+  X_ACCOUNT_LOCKED: 429,
+  X_ENV_MISSING: 500,
+  X_CONFIG_INVALID: 500,
+  X_SAML_RESPONSE_INVALID: 400,
+  X_SAML_METADATA_INVALID: 500,
+  X_IDENTITY_PROVIDER_UNKNOWN: 404,
+};
+
+/**
+ * The status for a code, read as an OWN key of the table above.
+ *
+ * `OAUTH_ROUTE_STATUS[code] ?? 502` is an index read on a plain object, so `Object.prototype`
+ * answered for `toString`, `constructor`, `hasOwnProperty` and `__proto__` — and `toString`
+ * yields a FUNCTION, which was handed straight to `ResponseInit.status`. `code` is a plain
+ * `string` on every `UltimateError`, so no cast makes that unreachable. Fourth instance of the
+ * class in the framework, after i18n's catalog lookup, schema's `coerce` and mcp's `validate-args`.
+ *
+ * Exported so a test can drive it without building a `Response`; `OAUTH_ROUTE_STATUS` stays
+ * exported unchanged, because `scripts/oauth-route-status.test.ts` pins it against
+ * `@ultimat3/http`'s `statusFor`.
+ */
+export function oauthRouteStatus(code: string): number {
+  // 502 is the default: an uncoded throw on this path came out of the provider conversation.
+  return Object.hasOwn(OAUTH_ROUTE_STATUS, code) ? (OAUTH_ROUTE_STATUS[code] ?? 502) : 502;
+}

package/src/identity-provider.ts

@@ -0,0 +1,112 @@
+// Single responsibility: the IdentityProvider port — the one shape every federated sign-in
+// protocol takes: send the browser out (`begin`), take its answer back (`complete`), hand over one
+// proven `OAuthProfile`. OIDC (`oidcIdentityProvider`) and SAML (`samlIdentityProvider`) are its two
+// adapters; `signInWithIdentity` is the one way either becomes a session.
+
+import type { Clock } from '@ultimat3/core';
+import type { Auth, LoginResult } from './auth';
+import { type TotpReplayGuard, totpStep } from './mfa';
+import type { OAuthGrantContext } from './oauth-grant-context';
+import { type OAuthGrants, signInWithOAuth } from './oauth-login';
+import type { OAuthProfile } from './oauth-profile';
+
+export interface IdentityBeginInput {
+  /** The absolute URL the IdP answers to: the callback route for this provider. */
+  readonly callbackUrl: string;
+  readonly clock: Clock;
+}
+
+export interface IdentityRedirect {
+  /** Where the browser is sent. */
+  readonly location: string;
+  /**
+   * What the second leg must be handed back, opaque to the caller. Not secret from the browser
+   * that started the flow, but it must not be FORGEABLE: the routes seal it in a signed cookie.
+   */
+  readonly state: string;
+}
+
+export interface IdentityCompleteInput {
+  /** `IdentityRedirect.state`, as the caller sealed and re-opened it. */
+  readonly state: string;
+  /** The IdP's answer: the callback's query (GET) or form body (POST). */
+  readonly params: Readonly<Record<string, string>>;
+  /** The same URL `begin` was given. */
+  readonly callbackUrl: string;
+  readonly clock: Clock;
+  /**
+   * The single-use claim store: an answer completes ONCE. The routes pass `auth.totpReplay`,
+   * the store a framework boot installs shared across replicas (`installTotpReplay`).
+   */
+  readonly replay: TotpReplayGuard;
+}
+
+export interface VerifiedIdentity {
+  readonly profile: OAuthProfile;
+  /** When the IdP says the federated session ends, if it says. */
+  readonly expiresAt: Date | null;
+  /** Everything else the IdP asserted — id-token claims or SAML attributes — for the grant seam. */
+  readonly claims: Readonly<Record<string, unknown>>;
+  /** OIDC only: the token set and a lazy, subject-checked `userinfo()` (`oauthLogin`'s grant seam). */
+  readonly oauth?: OAuthGrantContext | undefined;
+}
+
+export interface IdentityProvider {
+  /** Stable id: the route segment, `OAuthProfile.provider`, and the `x_accounts.provider` value. */
+  readonly id: string;
+  readonly protocol: 'oidc' | 'saml';
+  /** How the IdP returns: SAML's HTTP-POST binding is a cross-site POST, OIDC's a GET. */
+  readonly callbackMethod: 'GET' | 'POST';
+  begin(input: IdentityBeginInput): Promise<IdentityRedirect>;
+  /**
+   * Whether `params` answer THIS state — RelayState for SAML, `state` for OIDC — compared in
+   * constant time, nothing verified beyond it. The routes clear a browser's state cookie only on an
+   * answer bound to it: the ACS cookie rides any cross-site POST, so clearing on every outcome let
+   * any site end a sign-in in flight with one junk form.
+   */
+  answers(state: string, params: Readonly<Record<string, string>>): boolean;
+  /** Every refusal is a coded `AuthError`; nothing here creates a session. */
+  complete(input: IdentityCompleteInput): Promise<VerifiedIdentity>;
+}
+
+/** The app's grant seam over a verified identity — business convention, never shipped (axiom 8). */
+export type ResolveIdentityGrants = (
+  identity: VerifiedIdentity,
+) => Promise<OAuthGrants> | OAuthGrants;
+
+export interface IdentitySignInOptions {
+  readonly grants?: OAuthGrants | undefined;
+  readonly ip?: string | null | undefined;
+  readonly userAgent?: string | null | undefined;
+}
+
+/**
+ * A verified identity → a session, through the same account-link, MFA and session rules an OAuth
+ * login runs (`signInWithOAuth`). The provider id must be in `defineAuth({ providers })`.
+ */
+export async function signInWithIdentity(
+  auth: Auth,
+  identity: VerifiedIdentity,
+  options: IdentitySignInOptions = {},
+): Promise<LoginResult> {
+  return await signInWithOAuth(auth, {
+    profile: identity.profile,
+    // The framework stores no provider credential (`accountFor`); only the expiry is carried.
+    tokens: {
+      accessToken: '',
+      refreshToken: null,
+      expiresAt: identity.expiresAt,
+      idToken: null,
+      claims: null,
+    },
+    ip: options.ip,
+    userAgent: options.userAgent,
+    ...(options.grants === undefined ? {} : { grants: options.grants }),
+  });
+}
+
+/**
+ * The replay store forgets a claim once its step falls behind the clock, so a claim is filed
+ * under the step of the LAST instant the answer is acceptable: it outlives its own window.
+ */
+export const replayStepFor = (until: Date): number => totpStep(until);