@ultimat3/auth 1.0.0

package/src/oauth-exchange.ts

@@ -0,0 +1,244 @@
+// Single responsibility: the authorization-code leg — the client credentials it needs and the
+// one POST to the provider's token endpoint. `fetch` is the whole client; no SDK, no provider
+// branch beyond the data in `oauth.ts`. The tokens this returns are already trustworthy: an id
+// token is verified here, so no caller downstream can forget to.
+
+import type { Clock } from '@ultimat3/core';
+import { EnvMissingError, systemClock } from '@ultimat3/core';
+import { oauthExchangeFailed } from './errors';
+import { type IdTokenClaims, verifyIdToken } from './id-token';
+import {
+  assertOAuthCallback,
+  OAUTH_PROVIDERS,
+  type OAuthCallback,
+  type OAuthHandshake,
+  type OAuthProviderId,
+} from './oauth';
+
+/** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
+export type OAuthFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** GitHub answers 403 to a request with no user agent, so every call this package makes has one. */
+export const OAUTH_USER_AGENT = 'ultimate-auth';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_DETAIL_LENGTH = 200;
+
+export interface OAuthClientCredentials {
+  readonly clientId: string;
+  readonly clientSecret: string;
+}
+
+export interface OAuthTokens {
+  readonly accessToken: string;
+  readonly refreshToken: string | null;
+  readonly expiresAt: Date | null;
+  readonly idToken: string | null;
+  /** Verified claims of `idToken`. `null` when the provider issues no id token. */
+  readonly claims: IdTokenClaims | null;
+}
+
+export interface OAuthExchangeOptions {
+  readonly credentials: OAuthClientCredentials;
+  /** No `Date.now()` in this package: the token expiry is measured against this. */
+  readonly clock?: Clock | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+}
+
+/**
+ * Reads the two env vars the provider table names. Kept out of module scope on purpose —
+ * importing `oauth.ts` still reads no env and touches no network.
+ */
+export function oauthCredentials(
+  provider: OAuthProviderId,
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+): OAuthClientCredentials {
+  const { clientIdEnv, clientSecretEnv } = OAUTH_PROVIDERS[provider];
+  const clientId = env[clientIdEnv]?.trim() ?? '';
+  const clientSecret = env[clientSecretEnv]?.trim() ?? '';
+  const missing = [
+    ...(clientId === '' ? [clientIdEnv] : []),
+    ...(clientSecret === '' ? [clientSecretEnv] : []),
+  ];
+  if (missing.length > 0) {
+    throw new EnvMissingError({
+      cause: `${provider} oauth is enabled but ${missing.join(' and ')} ${missing.length === 1 ? 'is' : 'are'} not set`,
+      fix: `add ${missing.join(' and ')} to .env from the ${provider} app's credentials, then run: x doctor --json`,
+      meta: { provider, missing },
+    });
+  }
+  return { clientId, clientSecret };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Prefers the provider's own words; falls back to raw text, capped so a login page can't flood logs. */
+export async function providerDetail(response: Response): Promise<string> {
+  const text = await response.text().catch(() => '');
+  if (text === '') return 'the response body was empty';
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (isRecord(parsed)) {
+      const description = parsed['error_description'] ?? parsed['error'] ?? parsed['message'];
+      if (typeof description === 'string' && description !== '') return description;
+    }
+  } catch {
+    // Not JSON — fall through to the truncated raw text below.
+  }
+  return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text;
+}
+
+function fixForStatus(provider: OAuthProviderId, status: number): string {
+  const { clientIdEnv, clientSecretEnv } = OAUTH_PROVIDERS[provider];
+  if (status === 401 || status === 403) {
+    return `set ${clientIdEnv} and ${clientSecretEnv} to the current values in the ${provider} app settings`;
+  }
+  if (status === 400) {
+    return `register this exact redirect_uri in the ${provider} app settings, then restart the flow`;
+  }
+  return `retry; if it persists, check the ${provider} status page before changing anything`;
+}
+
+async function postForm(
+  provider: OAuthProviderId,
+  body: URLSearchParams,
+  options: OAuthExchangeOptions,
+): Promise<Record<string, unknown>> {
+  const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const url = OAUTH_PROVIDERS[provider].tokenUrl;
+
+  let response: Response;
+  try {
+    response = await doFetch(url, {
+      method: 'POST',
+      headers: {
+        // GitHub answers `application/x-www-form-urlencoded` unless asked for JSON.
+        Accept: 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'User-Agent': OAUTH_USER_AGENT,
+      },
+      body: body.toString(),
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'the request failed before a response';
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'token',
+      detail:
+        `${reason} — nothing left this host for ${url} (egress, DNS or TLS); restart the ` +
+        'flow once it does, since the code is already spent',
+      fix: `curl -sS -m 5 -o /dev/null ${url}`,
+    });
+  }
+
+  if (!response.ok) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'token',
+      detail: await providerDetail(response),
+      status: response.status,
+      fix: fixForStatus(provider, response.status),
+    });
+  }
+
+  const parsed: unknown = await response.json().catch(() => undefined);
+  if (!isRecord(parsed)) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'token',
+      detail: 'the token endpoint answered 200 with a body that is not a JSON object',
+      fix: `confirm ${url} is the provider's real token endpoint and not a proxy`,
+    });
+  }
+
+  // GitHub reports a bad code, a reused code and a wrong secret as HTTP 200 with an `error`
+  // field. Trusting the status alone here mints a session from a failed exchange.
+  const error = parsed['error'];
+  if (typeof error === 'string' && error !== '') {
+    const description = parsed['error_description'];
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'token',
+      detail: typeof description === 'string' && description !== '' ? description : error,
+      fix:
+        error === 'bad_verification_code' || error === 'invalid_grant'
+          ? 'restart the flow — an authorization code is single-use and short-lived'
+          : fixForStatus(provider, 400),
+    });
+  }
+  return parsed;
+}
+
+/**
+ * Validates the callback, then trades the code for tokens. PKCE's verifier travels here and
+ * nowhere else — it is what proves this exchange belongs to the browser that started the flow.
+ */
+export async function exchangeOAuthCode(
+  handshake: OAuthHandshake,
+  callback: OAuthCallback,
+  options: OAuthExchangeOptions,
+): Promise<OAuthTokens> {
+  assertOAuthCallback(handshake, callback);
+  const provider = OAUTH_PROVIDERS[handshake.provider];
+  const clock = options.clock ?? systemClock;
+
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: callback.code,
+    redirect_uri: handshake.redirectUri,
+    client_id: options.credentials.clientId,
+    client_secret: options.credentials.clientSecret,
+  });
+  if (provider.usesPkce) body.set('code_verifier', handshake.verifier);
+
+  const payload = await postForm(handshake.provider, body, options);
+  const accessToken = payload['access_token'];
+  if (typeof accessToken !== 'string' || accessToken === '') {
+    throw oauthExchangeFailed({
+      provider: provider.id,
+      stage: 'token',
+      detail: 'the response carried no access_token',
+      fix: `confirm the ${provider.id} app grants the scopes in OAUTH_PROVIDERS.${provider.id}.scopes`,
+    });
+  }
+
+  const refreshToken = payload['refresh_token'];
+  const expiresIn = payload['expires_in'];
+  const rawIdToken = payload['id_token'];
+  const idToken = typeof rawIdToken === 'string' && rawIdToken !== '' ? rawIdToken : null;
+
+  // An OIDC provider that answers without an id token has not identified anyone, and the
+  // access token alone cannot be bound to this handshake's nonce.
+  if (provider.usesNonce && idToken === null) {
+    throw oauthExchangeFailed({
+      provider: provider.id,
+      stage: 'token',
+      detail: 'the response carried no id_token',
+      fix: `include "openid" in the scopes passed to beginOAuth() for ${provider.id}`,
+    });
+  }
+
+  return {
+    accessToken,
+    refreshToken: typeof refreshToken === 'string' && refreshToken !== '' ? refreshToken : null,
+    expiresAt:
+      typeof expiresIn === 'number' && Number.isFinite(expiresIn)
+        ? new Date(clock.now().getTime() + expiresIn * 1000)
+        : null,
+    idToken,
+    claims:
+      idToken === null
+        ? null
+        : verifyIdToken({
+            provider: handshake.provider,
+            idToken,
+            clientId: options.credentials.clientId,
+            nonce: handshake.nonce,
+            clock,
+          }),
+  };
+}

package/src/oauth-login.ts

@@ -0,0 +1,193 @@
+// Single responsibility: the last leg — a verified provider identity becomes the same
+// `LoginResult` a password login produces. One session shape, one `Actor`, one MFA rule, no
+// matter which door the user came through. `completeOAuthLogin` is the blessed entry point;
+// the three steps under it are exported because a custom flow needs the seams, not a second path.
+
+import { ConfigInvalidError, uuid } from '@ultimat3/core';
+import type { AuthAccount, AuthUser } from './adapter';
+import type { Auth, LoginResult } from './auth';
+import {
+  emailVerifiedNotStored,
+  mfaRequired,
+  oauthAccountNotLinked,
+  oauthExchangeFailed,
+} from './errors';
+import type { OAuthCallback, OAuthHandshake } from './oauth';
+import {
+  exchangeOAuthCode,
+  type OAuthClientCredentials,
+  type OAuthFetch,
+  type OAuthTokens,
+  oauthCredentials,
+} from './oauth-exchange';
+import { type OAuthProfile, oauthProfile } from './oauth-profile';
+import { resolveActor } from './policy-bridge';
+import { loginFailed } from './rate-limit';
+import { createSession, sessionCookie } from './session';
+
+export interface OAuthSignInInput {
+  readonly profile: OAuthProfile;
+  readonly tokens: OAuthTokens;
+  readonly ip?: string | null | undefined;
+  readonly userAgent?: string | null | undefined;
+  /** Granted to a user this flow creates. An existing user's roles are never rewritten here. */
+  readonly roles?: readonly string[] | undefined;
+  readonly orgId?: string | null | undefined;
+}
+
+async function userForAccount(auth: Auth, account: AuthAccount): Promise<AuthUser> {
+  const user = await auth.adapter.findUserById(account.userId);
+  if (user === null || user.disabledAt !== null) throw loginFailed();
+  return user;
+}
+
+async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthUser> {
+  const email = input.profile.email;
+  // The provider authenticated somebody and told us no address. There is nothing to create an
+  // account from, and saying "wrong password" here would send the developer hunting the wrong bug.
+  if (email === null) {
+    throw oauthExchangeFailed({
+      provider: input.profile.provider,
+      stage: 'userinfo',
+      detail: 'the provider returned an identity with no email address',
+      fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then restart the flow`,
+    });
+  }
+  const created = await auth.adapter.createUser({
+    id: uuid(auth.clock),
+    email,
+    // An OAuth-only account has no password to store, and must never be given a random one:
+    // a hash nobody knows the input to is still a credential a reset flow could hand over.
+    passwordHash: null,
+    orgId: input.orgId ?? null,
+    roles: input.roles ?? [],
+    createdAt: auth.clock.now(),
+  });
+  if (!input.profile.emailVerified) return created;
+  // `CreateUserInput` has no `emailVerifiedAt`, so the stamp is a required second write. Returning
+  // `created` when it does not land would sign in a user whose row says unverified — and the next
+  // login through this same provider would then refuse to link it at all.
+  const stamped = await auth.adapter.updateUser(created.id, { emailVerifiedAt: auth.clock.now() });
+  if (stamped === null) throw emailVerifiedNotStored(input.profile.provider, created.id);
+  return stamped;
+}
+
+/**
+ * Resolve the identity to a user: an already-linked account first, then an existing account
+ * with the same address, then a fresh user.
+ *
+ * An address alone is not proof of ownership on either side. Attaching a provider identity to a
+ * local account that never verified its own email hands the login to whoever registered that
+ * address first, so both halves must have proven it before they are treated as one person.
+ */
+async function resolveUser(
+  auth: Auth,
+  input: OAuthSignInInput,
+  linked: AuthAccount | null,
+): Promise<AuthUser> {
+  const { provider, email, emailVerified } = input.profile;
+  if (linked !== null) return await userForAccount(auth, linked);
+
+  if (email === null) return await createUserFor(auth, input);
+  const existing = await auth.adapter.findUserByEmail(email);
+  if (existing === null) return await createUserFor(auth, input);
+  if (existing.disabledAt !== null) throw loginFailed();
+  // The provider did not vouch for the address, so nothing here proves the two are one person.
+  if (!emailVerified) throw loginFailed();
+  // It did vouch, and the local account never did: say so, because this caller owns the address.
+  if (existing.emailVerifiedAt === null) throw oauthAccountNotLinked(provider, email);
+  return existing;
+}
+
+function accountFor(auth: Auth, user: AuthUser, input: OAuthSignInInput): AuthAccount {
+  return {
+    id: uuid(auth.clock),
+    userId: user.id,
+    provider: input.profile.provider,
+    providerAccountId: input.profile.providerAccountId,
+    accessToken: input.tokens.accessToken,
+    refreshToken: input.tokens.refreshToken,
+    expiresAt: input.tokens.expiresAt,
+    createdAt: auth.clock.now(),
+  };
+}
+
+/**
+ * Mints the session for an identity the provider has already proven. MFA still applies: an
+ * enrolled second factor is the user's rule, not the password path's rule.
+ */
+export async function signInWithOAuth(auth: Auth, input: OAuthSignInInput): Promise<LoginResult> {
+  const provider = input.profile.provider;
+  if (!auth.providers.includes(provider)) {
+    throw new ConfigInvalidError({
+      cause: `${provider} is not in defineAuth({ providers }), so a ${provider} identity cannot sign in`,
+      fix: `add '${provider}' to defineAuth({ providers: [...] }), or stop offering the ${provider} button`,
+      meta: { provider, enabled: [...auth.providers] },
+    });
+  }
+
+  const linked = await auth.adapter.findAccount(provider, input.profile.providerAccountId);
+  const user = await resolveUser(auth, input, linked);
+  // Linked before the MFA gate on purpose: the second factor is finished on another request,
+  // and that request must find the identity already attached. A re-link refreshes the tokens
+  // and keeps the row's own identity — the provider account never changes hands.
+  const account = accountFor(auth, user, input);
+  await auth.adapter.linkAccount(
+    linked === null ? account : { ...account, id: linked.id, createdAt: linked.createdAt },
+  );
+
+  if (user.mfaSecret !== null) throw mfaRequired(user.id);
+
+  const issued = await createSession(auth.sessions, {
+    userId: user.id,
+    ip: input.ip ?? null,
+    userAgent: input.userAgent,
+    mfaSatisfied: true,
+  });
+  return {
+    actor: resolveActor({ kind: 'user', user, session: issued.session }),
+    session: issued.session,
+    token: issued.token,
+    cookie: sessionCookie(issued.token, auth.sessions.policy),
+  };
+}
+
+export interface CompleteOAuthLoginInput {
+  readonly handshake: OAuthHandshake;
+  readonly callback: OAuthCallback;
+  /** Defaults to the two env vars named in the provider table. */
+  readonly credentials?: OAuthClientCredentials | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly ip?: string | null | undefined;
+  readonly userAgent?: string | null | undefined;
+  readonly roles?: readonly string[] | undefined;
+  readonly orgId?: string | null | undefined;
+}
+
+/** Callback → session, in one call: exchange, identify, sign in. */
+export async function completeOAuthLogin(
+  auth: Auth,
+  input: CompleteOAuthLoginInput,
+): Promise<LoginResult> {
+  const provider = input.handshake.provider;
+  const tokens = await exchangeOAuthCode(input.handshake, input.callback, {
+    credentials: input.credentials ?? oauthCredentials(provider),
+    clock: auth.clock,
+    fetch: input.fetch,
+    timeoutMs: input.timeoutMs,
+  });
+  const profile = await oauthProfile(provider, tokens, {
+    fetch: input.fetch,
+    timeoutMs: input.timeoutMs,
+  });
+  return await signInWithOAuth(auth, {
+    profile,
+    tokens,
+    ip: input.ip,
+    userAgent: input.userAgent,
+    roles: input.roles,
+    orgId: input.orgId,
+  });
+}

package/src/oauth-profile.ts

@@ -0,0 +1,213 @@
+// Single responsibility: one normalised identity out of whichever surface the provider offers.
+// The rule is single: claims from a verified id token when there is one, the userinfo endpoint
+// when there is not. `emailVerified` is carried honestly rather than assumed — it is what
+// decides whether this login may attach itself to an existing account by address.
+
+import { logger } from '@ultimat3/core';
+import { oauthExchangeFailed } from './errors';
+import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
+import { OAUTH_PROVIDERS, type OAuthProviderId } from './oauth';
+import {
+  OAUTH_USER_AGENT,
+  type OAuthFetch,
+  type OAuthTokens,
+  providerDetail,
+} from './oauth-exchange';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export interface OAuthProfile {
+  readonly provider: OAuthProviderId;
+  /** The provider's own stable id (`sub`, or GitHub's numeric id). Never the email. */
+  readonly providerAccountId: string;
+  readonly email: string | null;
+  /** Only a provider-asserted verification counts. Defaults to false, never to true. */
+  readonly emailVerified: boolean;
+  readonly name: string | null;
+}
+
+export interface OAuthProfileOptions {
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+}
+
+interface GithubEmail {
+  readonly email: string;
+  readonly primary: boolean;
+  readonly verified: boolean;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const stringOrNull = (value: unknown): string | null =>
+  typeof value === 'string' && value !== '' ? value : null;
+
+async function getJson(
+  provider: OAuthProviderId,
+  url: string,
+  accessToken: string,
+  options: OAuthProfileOptions,
+): Promise<{ ok: true; body: unknown } | { ok: false; status: number; detail: string }> {
+  const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  let response: Response;
+  try {
+    response = await doFetch(url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${accessToken}`,
+        'User-Agent': OAUTH_USER_AGENT,
+      },
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'the request failed before a response';
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail:
+        `${reason} — nothing left this host for ${url} (egress, DNS or TLS); restart the ` +
+        'flow once it does',
+      fix: `curl -sS -m 5 -o /dev/null ${url}`,
+    });
+  }
+  if (!response.ok) {
+    return { ok: false, status: response.status, detail: await providerDetail(response) };
+  }
+  return { ok: true, body: await response.json().catch(() => undefined) };
+}
+
+/** GitHub keeps a private primary address off the profile; this is where it actually lives. */
+async function githubPrimaryEmail(
+  url: string,
+  accessToken: string,
+  options: OAuthProfileOptions,
+): Promise<GithubEmail | null> {
+  const result = await getJson('github', url, accessToken, options);
+  if (!result.ok) {
+    logger.warn('auth.oauth.github_emails_unavailable', {
+      status: result.status,
+      detail: result.detail,
+    });
+    return null;
+  }
+  const entries = Array.isArray(result.body) ? result.body : [];
+  const verified = entries.filter(
+    (entry): entry is GithubEmail =>
+      isRecord(entry) &&
+      typeof entry['email'] === 'string' &&
+      entry['verified'] === true &&
+      typeof entry['primary'] === 'boolean',
+  );
+  return verified.find((entry) => entry.primary) ?? verified[0] ?? null;
+}
+
+async function fromUserInfo(
+  provider: OAuthProviderId,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+): Promise<OAuthProfile> {
+  const config = OAUTH_PROVIDERS[provider];
+  const url = config.userInfoUrl;
+  if (url === null) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: `${provider} publishes no userinfo endpoint and its id token carried no identity`,
+      fix: `request the "email" scope for ${provider} in beginOAuth(), then restart the flow`,
+    });
+  }
+
+  const result = await getJson(provider, url, tokens.accessToken, options);
+  if (!result.ok) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: result.detail,
+      status: result.status,
+      fix: `confirm the ${provider} app still grants ${config.scopes.join(' ')}, then restart the flow`,
+    });
+  }
+  if (!isRecord(result.body)) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: 'the userinfo endpoint answered 200 with a body that is not a JSON object',
+      fix: `confirm ${url} is the provider's real userinfo endpoint and not a proxy`,
+    });
+  }
+
+  const body = result.body;
+  // GitHub's id is a number; OIDC's `sub` is a string. Both are stable, so both are accepted.
+  const rawId = body['sub'] ?? body['id'];
+  const providerAccountId =
+    typeof rawId === 'number' ? String(rawId) : typeof rawId === 'string' ? rawId : '';
+  if (providerAccountId === '') {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: 'the profile carried no stable account id',
+      fix: `confirm the ${provider} app requests ${config.scopes.join(' ')} and restart the flow`,
+    });
+  }
+
+  let email = stringOrNull(body['email']);
+  let emailVerified = isVerifiedFlag(body['email_verified']);
+
+  if (config.userEmailsUrl !== null) {
+    const primary = await githubPrimaryEmail(config.userEmailsUrl, tokens.accessToken, options);
+    if (primary !== null) {
+      email = primary.email;
+      emailVerified = true;
+    }
+  }
+
+  return {
+    provider,
+    providerAccountId,
+    email,
+    emailVerified,
+    name: stringOrNull(body['name']) ?? stringOrNull(body['login']),
+  };
+}
+
+/**
+ * The id token is preferred because it was verified during the exchange and costs no round
+ * trip. Userinfo is the fallback for a provider that issues no id token (GitHub) and for the
+ * narrowed-scope case where the token identifies a subject but carries no address.
+ */
+export async function oauthProfile(
+  provider: OAuthProviderId,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions = {},
+): Promise<OAuthProfile> {
+  const claims = tokens.claims;
+  if (claims === null) return await fromUserInfo(provider, tokens, options);
+
+  const email = stringOrNull(claims.email);
+  const userInfoUrl = OAUTH_PROVIDERS[provider].userInfoUrl;
+  if (email === null && userInfoUrl !== null) {
+    const profile = await fromUserInfo(provider, tokens, options);
+    // Two surfaces, one identity — or this is not that identity. Overwriting the subject and
+    // keeping the address would link the account on an address belonging to whoever the second
+    // call described, so a disagreement ends the handshake instead of being reconciled.
+    if (profile.providerAccountId !== claims.sub) {
+      throw oauthExchangeFailed({
+        provider,
+        stage: 'userinfo',
+        detail: 'the userinfo subject is not the subject of the verified id token',
+        fix: `confirm ${userInfoUrl} is ${provider}'s own userinfo endpoint and not a proxy that rewrites sub`,
+      });
+    }
+    return profile;
+  }
+
+  return {
+    provider,
+    providerAccountId: claims.sub,
+    email,
+    emailVerified: email !== null && idTokenEmailVerified(claims),
+    name: stringOrNull(claims.name),
+  };
+}