@payez/next-mvp 4.8.0 → 4.8.2

package/src/auth/idp-oauth.ts

@@ -1,310 +1,310 @@
-/**
- * PAY-2305 (next-mvp 4.7.4): the two hooks that let better-auth's genericOAuth talk to THIS IdP.
- *
- * WHY THEY EXIST (source read, PayEz-Core master d53f192af, BAPert 74014):
- *   - POST /api/oauth/token takes a JSON body (snake_case), not better-auth's default form body, and answers with the
- *     Core response envelope { success, data: { access_token, refresh_token, token_type, expires_in, user } }.
- *     better-auth's default exchange reads top-level fields and would find nothing.
- *   - There is NO id_token and NO userinfo endpoint (deliberate, PAY-1585). The only proof of who signed in is the
- *     access token itself: an RS-family bearer JWT (RS512 on dev-93's JWKS, measured) signed by the IdP bearer key (jwks_uri in discovery) with sub, email,
- *     roles, amr, token_type.
- *
- * TRUST RULE: a claim is read ONLY from a token whose signature, issuer, expiry and token_type were verified here.
- * Never base64-decode and believe. Only RSA signatures are accepted (the RS and PS families; the JWKS key's own declared alg is binding), so a token
- * re-signed with HS256 using the public key as the secret, or alg none, is refused. The `aud` of an IdP bearer is the IdP's public constant, not this client, so it is not a
- * binding; the binding to THIS client is the authorization code + PKCE verifier + exact redirect_uri that Core checks.
- *
- * The redirect_uri sent here MUST be byte-identical at the authorize step and the token step (Core compares it
- * Ordinal at the token step) and equal to the registered {site_url}/api/auth/callback (Core compares it exactly,
- * case-insensitively, at the authorize step). Both come from ONE value: the `redirectURI` of the provider config.
- */
-import { createRemoteJWKSet, decodeProtectedHeader, jwtVerify, type JWTVerifyGetKey } from 'jose';
-
-export interface IdpTokenGrant {
-  accessToken: string;
-  refreshToken?: string;
-  /** epoch ms */
-  accessTokenExpires?: number;
-  tokenType?: string;
-  /** The `user` object of the IdP response, passed through untouched (shape not contractually fixed). */
-  user?: Record<string, unknown>;
-}
-
-export interface IdpVerifiedClaims {
-  sub: string;
-  email: string;
-  name: string;
-  userId?: string;
-  roles: string[];
-  /**
-   * true ONLY when the verified token asserts email_verified === true (or "true"). Never assumed: better-auth links by email
-   * from what getUserInfo returns, so an unasserted value must not let an IdP email attach to an existing local account.
-   */
-  emailVerified: boolean;
-  /** true only when the VERIFIED access token's amr contains "mfa" (Core's HasSecondFactor rule). */
-  mfaVerified: boolean;
-}
-
-export interface IdpOAuthHookDeps {
-  fetch?: typeof fetch;
-  /** Key resolver for a jwks_uri. Default: jose createRemoteJWKSet. Tests inject a local key set. */
-  getKeySet?: (jwksUri: string) => JWTVerifyGetKey;
-  now?: () => number;
-}
-
-export interface IdpOAuthHookOptions {
-  discoveryUrl: string;
-  clientId: string;
-  redirectURI: string;
-  /** Override for the expected `iss`. Default: the discovery document's `issuer`. */
-  issuer?: string;
-  /**
-   * Extra origins the discovery document may point token_endpoint / jwks_uri at. By default both MUST share the origin of
-   * `discoveryUrl`, so a document cannot send the code exchange or the key fetch to another host. Set this only for a
-   * split-host deployment (internal discovery URL, public endpoints). Comma-separated env: IDP_OAUTH_TRUSTED_ORIGINS.
-   */
-  trustedOrigins?: string[];
-  onTokens?: (grant: IdpTokenGrant) => void;
-  onClaims?: (claims: IdpVerifiedClaims) => void;
-  deps?: IdpOAuthHookDeps;
-}
-
-const DISCOVERY_TTL_MS = 10 * 60 * 1000;
-const HTTP_TIMEOUT_MS = 10_000;
-
-/** The URI sent at authorize AND token time. Explicit env wins; else the registered {app}/api/auth/callback form. */
-export function resolveIdpRedirectUri(appBaseUrl: string, env: NodeJS.ProcessEnv = process.env): string {
-  const explicit = env.IDP_OAUTH_REDIRECT_URI?.trim();
-  if (explicit) return explicit;
-  return appBaseUrl.replace(/\/+$/, '') + '/api/auth/callback';
-}
-
-/** amr arrives as an array, a JSON-array string, or a delimited string (Core's own reader accepts all three). */
-export function amrIncludesMfa(amr: unknown): boolean {
-  let values: unknown[] = [];
-  if (Array.isArray(amr)) values = amr;
-  else if (typeof amr === 'string') {
-    const t = amr.trim();
-    if (t.startsWith('[')) {
-      try {
-        const parsed = JSON.parse(t);
-        if (Array.isArray(parsed)) values = parsed;
-      } catch {
-        values = [];
-      }
-    } else {
-      values = t.split(/[\s,]+/);
-    }
-  }
-  return values.some((v) => typeof v === 'string' && v.trim().toLowerCase() === 'mfa');
-}
-
-/** Max skew accepted on nbf/exp/iat when verifying the IdP access token. */
-export const CLOCK_TOLERANCE_SECONDS = 30;
-
-/**
- * Address shape, a POSITIVE character rule (PAY-2337, Scout 74285): the local part may contain only [A-Za-z0-9] and . _ % + - ' ; the domain only
- * [A-Za-z0-9-] labels joined by dots; one @, <= 254 total, local <= 64, no leading/trailing/double dot in the local part, a dotted domain.
- * Everything else is NOT an address, and in particular a MASK: Core masks data.user.email on purpose (MaskedEmailJsonConverter), today with '*',
- * tomorrow maybe a bullet, an ellipsis or an 'x' run; a blacklist of one glyph would pass the next mask. Not a deliverability check.
- */
-export function isAddressShaped(v: unknown): v is string {
-  if (typeof v !== 'string' || v.length === 0 || v.length > 254) return false;
-  if (!/^[A-Za-z0-9._%+'-]+@[A-Za-z0-9.-]+$/.test(v)) return false;
-  const [local, domain] = v.split('@');
-  if (local.length > 64 || local.startsWith('.') || local.endsWith('.') || local.includes('..')) return false;
-  return /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/.test(domain) && !domain.startsWith('-') && !domain.endsWith('-');
-}
-
-/**
- * The account address (BAPert 74193 / 74196, 4.7.8). Core's code-flow access token has NO email claim; its sub and ws-identity name claim are
- * both user.UserName, which is a LOGIN, not the mailbox: it may be address-shaped and still differ from the account's Email (4.7.7 vetoed on that
- * and refused every such sign-in, NightHawk 74189). Sources: the token RESPONSE's data.user.email (token endpoint, TLS) and/or the signed token's
- * own email claim; if both are present they must be equal. sub / the name claim are NEITHER a source NOR a veto. Not trimmed. Returns '' on any doubt.
- */
-export function resolveEmail(payload: Record<string, unknown>, responseEmail?: unknown): string {
-  // NOT trimmed: padding or a trailing newline is a malformed address (refused by the shape check), never silently repaired.
-  const raw = (v: unknown) => (typeof v === 'string' ? v : '');
-  const sources = [raw(payload.email), raw(responseEmail)].filter((v) => v.trim() !== '');
-  if (sources.length === 0 || !sources.every(isAddressShaped)) return '';
-  const chosen = sources[0];
-  const same = (a: string) => a.toLowerCase() === chosen.toLowerCase();
-  if (!sources.every(same)) return '';
-  return chosen;
-}
-
-function rolesOf(claim: unknown): string[] {
-  if (Array.isArray(claim)) return claim.filter((r): r is string => typeof r === 'string' && r.length > 0);
-  if (typeof claim === 'string' && claim.trim()) {
-    const t = claim.trim();
-    if (t.startsWith('[')) {
-      try {
-        const parsed = JSON.parse(t);
-        if (Array.isArray(parsed)) return parsed.filter((r): r is string => typeof r === 'string' && r.length > 0);
-      } catch {
-        return [];
-      }
-    }
-    return t.split(/[\s,]+/).filter(Boolean);
-  }
-  return [];
-}
-
-export function createIdpOAuthHooks(opts: IdpOAuthHookOptions) {
-  const fetchFn = opts.deps?.fetch ?? fetch;
-  const now = opts.deps?.now ?? (() => Date.now());
-  const getKeySet = opts.deps?.getKeySet ?? ((uri: string) => createRemoteJWKSet(new URL(uri)));
-
-  let discovery: { doc: Record<string, unknown>; at: number } | null = null;
-  const keySets = new Map<string, JWTVerifyGetKey>();
-  /** access token -> data.user.email / user_name from the token response, consumed by getUserInfo for THAT token (bounded; never keyed by anything shared). */
-  const responseUsers = new Map<string, { email: string; userName: string }>();
-
-  async function loadDiscovery(): Promise<Record<string, unknown>> {
-    if (discovery && now() - discovery.at < DISCOVERY_TTL_MS) return discovery.doc;
-    const res = await fetchFn(opts.discoveryUrl, {
-      headers: { Accept: 'application/json' },
-      redirect: 'error',
-      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
-    });
-    if (!res.ok) throw new Error(`IdP discovery returned ${res.status}`);
-    const doc = (await res.json()) as Record<string, unknown>;
-    if (typeof doc?.token_endpoint !== 'string' || typeof doc?.jwks_uri !== 'string' || typeof doc?.issuer !== 'string') {
-      throw new Error('IdP discovery document is missing token_endpoint, jwks_uri or issuer');
-    }
-    const allowed = new Set([new URL(opts.discoveryUrl).origin, ...(opts.trustedOrigins ?? []).map((o) => o.replace(/\/+$/, ''))]);
-    for (const field of ['token_endpoint', 'jwks_uri'] as const) {
-      const origin = new URL(doc[field] as string).origin;
-      if (!allowed.has(origin)) throw new Error(`IdP discovery ${field} points at an untrusted origin (${origin})`);
-    }
-    discovery = { doc, at: now() }; // only a good document is cached
-    return doc;
-  }
-
-  /** better-auth `getToken`: JSON body, envelope unwrapped, no data.access_token => refused. */
-  async function getToken(data: { code: string; codeVerifier?: string }) {
-    const doc = await loadDiscovery();
-    if (!data.codeVerifier) throw new Error('IdP token exchange refused: no PKCE code_verifier');
-    const res = await fetchFn(doc.token_endpoint as string, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-      redirect: 'error',
-      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
-      body: JSON.stringify({
-        grant_type: 'authorization_code',
-        code: data.code,
-        code_verifier: data.codeVerifier,
-        // Deliberately NOT data.redirectURI: that is better-auth's own computed callback, not the registered URI.
-        redirect_uri: opts.redirectURI,
-        client_id: opts.clientId,
-      }),
-    });
-    let body: any;
-    try {
-      body = await res.json();
-    } catch {
-      throw new Error(`IdP token response (${res.status}) was not JSON`);
-    }
-    if (!res.ok) {
-      const code = body?.error?.code ?? body?.error ?? body?.code ?? 'unknown';
-      throw new Error(`IdP token exchange refused (${res.status}, ${typeof code === 'string' ? code : 'unknown'})`);
-    }
-    const d = body?.data;
-    if (!d || typeof d.access_token !== 'string' || !d.access_token) {
-      throw new Error('IdP token response has no data.access_token (envelope not as expected)');
-    }
-    const expiresIn = typeof d.expires_in === 'number' && d.expires_in > 0 ? d.expires_in : undefined;
-    const expires = expiresIn ? now() + expiresIn * 1000 : undefined;
-    if (d.user && typeof d.user === 'object' && typeof d.user.email === 'string') {
-      if (responseUsers.size >= 64) responseUsers.delete(responseUsers.keys().next().value as string);
-      responseUsers.set(d.access_token, { email: d.user.email, userName: typeof d.user.user_name === 'string' ? d.user.user_name : '' });
-    }
-    opts.onTokens?.({
-      accessToken: d.access_token,
-      refreshToken: typeof d.refresh_token === 'string' ? d.refresh_token : undefined,
-      accessTokenExpires: expires,
-      tokenType: typeof d.token_type === 'string' ? d.token_type : undefined,
-      user: d.user && typeof d.user === 'object' ? d.user : undefined,
-    });
-    return {
-      tokenType: typeof d.token_type === 'string' ? d.token_type : 'Bearer',
-      accessToken: d.access_token,
-      refreshToken: typeof d.refresh_token === 'string' ? d.refresh_token : undefined,
-      accessTokenExpiresAt: expires ? new Date(expires) : undefined,
-      scopes: [] as string[],
-    };
-  }
-
-  /** better-auth `getUserInfo`: the user comes from the VERIFIED access token. Returns null (never a guess) on any doubt. */
-  async function getUserInfo(tokens: { accessToken?: string }) {
-    try {
-      if (!tokens?.accessToken) return null;
-      const doc = await loadDiscovery();
-      // A token without a kid is refused: no "first key" fallback. (A kid that is not in the key set is refused by jose.)
-      const kid = decodeProtectedHeader(tokens.accessToken).kid;
-      if (typeof kid !== 'string' || !kid) throw new Error('token header has no kid');
-      const jwksUri = doc.jwks_uri as string;
-      let keys = keySets.get(jwksUri);
-      if (!keys) {
-        keys = getKeySet(jwksUri);
-        keySets.set(jwksUri, keys);
-      }
-      const { payload } = await jwtVerify(tokens.accessToken, keys, {
-        // RSA signatures ONLY (RS256/384/512, PS256/384/512; BAPert 74117): never HS* (a token "signed" with the public key as an HMAC
-        // secret), never none, never ES. 4.7.4/4.7.5 pinned RS256 from a source read; the live IdP's JWKS (dev-93, kid 46) declares alg RS512
-        // and every real access token was refused (NightHawk 74114). Which RS alg is binding is the JWKS KEY's own declared
-        // `alg`: jose only offers a JWK to a token whose header alg equals that JWK's `alg`, so a token cannot choose a
-        // weaker/other algorithm than the published key says. A JWK with no `alg` accepts any listed RSA alg; a symmetric (oct) key is never usable for these algorithms.
-        algorithms: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512'],
-        issuer: opts.issuer ?? (doc.issuer as string),
-        currentDate: new Date(now()),
-        // The IdP stamps nbf = issue time with no skew and the token is verified in the same second it is minted (NightHawk 74151:
-        // "nbf claim timestamp check failed"). 30 s, bounded. jose applies it to exp too: a token is accepted up to 30 s after exp.
-        clockTolerance: CLOCK_TOLERANCE_SECONDS,
-      });
-      if (payload.token_type !== 'bearer_token') throw new Error('token_type is not bearer_token');
-      if (typeof payload.sub !== 'string' || !payload.sub) throw new Error('no sub');
-      const hasEmailClaim = typeof payload.email === 'string' && payload.email.trim() !== '';
-      const responseUser = responseUsers.get(tokens.accessToken);
-      responseUsers.delete(tokens.accessToken);
-      // The response user object (UNSIGNED body) must be the TOKEN's user (Scout 74198, DotNetPert-Scout 74202): Core fills data.user.user_name and the
-      // signed sub from the same loaded user in one mint, so WHENEVER a response user exists (even if a signed email claim is also present), user_name MUST be present
-      // and equal sub (case-insensitive). A different or missing user_name means the address may belong to someone else -> refuse. Does not constrain email == sub.
-      if (responseUser && responseUser.userName.trim().toLowerCase() !== payload.sub.trim().toLowerCase()) {
-        throw new Error('token response user is missing or does not match the token subject');
-      }
-      // A MASKED / unusable response address is ABSENT (PAY-2337), not "a different address": a valid signed claim still signs in, and with no claim
-      // there is no source. NEVER repaired or unmasked (no prefix match against sub or the claim). Log names only the fact, no value, no length.
-      const responseEmailRaw = responseUser?.email ?? '';
-      const responseEmailUsable = isAddressShaped(responseEmailRaw);
-      const responseMasked = responseEmailRaw.trim() !== '' && !responseEmailUsable;
-      if (responseMasked) console.warn('[BETTER_AUTH] payez-idp token response address is masked or unusable; ignored');
-      const email = resolveEmail(payload as Record<string, unknown>, responseEmailUsable ? responseEmailRaw : undefined);
-      if (!email) {
-        throw new Error(responseMasked ? 'response address is masked' : 'no usable email (needs data.user.email or an email claim, address-shaped, equal when both are present)');
-      }
-      const name =
-        (typeof payload.name === 'string' && payload.name.trim()) ||
-        (typeof payload.full_name === 'string' && payload.full_name.trim()) ||
-        email.split('@')[0];
-      const claims: IdpVerifiedClaims = {
-        sub: payload.sub,
-        email,
-        name,
-        userId: typeof payload.user_id === 'string' || typeof payload.user_id === 'number' ? String(payload.user_id) : undefined,
-        roles: rolesOf(payload.roles),
-        mfaVerified: amrIncludesMfa(payload.amr),
-        // Only the signed token's own email CLAIM can be verified; an address that came from the token response (data.user.email) never asserts it.
-        emailVerified: hasEmailClaim && (payload.email_verified === true || payload.email_verified === 'true'),
-      };
-      opts.onClaims?.(claims);
-      return { id: claims.sub, email: claims.email, name: claims.name, emailVerified: claims.emailVerified };
-    } catch (err) {
-      // Reason only, never the token.
-      console.warn('[BETTER_AUTH] payez-idp access token refused:', err instanceof Error ? err.message : String(err));
-      return null;
-    }
-  }
-
-  return { getToken, getUserInfo };
-}
+/**
+ * PAY-2305 (next-mvp 4.7.4): the two hooks that let better-auth's genericOAuth talk to THIS IdP.
+ *
+ * WHY THEY EXIST (source read, PayEz-Core master d53f192af, BAPert 74014):
+ *   - POST /api/oauth/token takes a JSON body (snake_case), not better-auth's default form body, and answers with the
+ *     Core response envelope { success, data: { access_token, refresh_token, token_type, expires_in, user } }.
+ *     better-auth's default exchange reads top-level fields and would find nothing.
+ *   - There is NO id_token and NO userinfo endpoint (deliberate, PAY-1585). The only proof of who signed in is the
+ *     access token itself: an RS-family bearer JWT (RS512 on dev-93's JWKS, measured) signed by the IdP bearer key (jwks_uri in discovery) with sub, email,
+ *     roles, amr, token_type.
+ *
+ * TRUST RULE: a claim is read ONLY from a token whose signature, issuer, expiry and token_type were verified here.
+ * Never base64-decode and believe. Only RSA signatures are accepted (the RS and PS families; the JWKS key's own declared alg is binding), so a token
+ * re-signed with HS256 using the public key as the secret, or alg none, is refused. The `aud` of an IdP bearer is the IdP's public constant, not this client, so it is not a
+ * binding; the binding to THIS client is the authorization code + PKCE verifier + exact redirect_uri that Core checks.
+ *
+ * The redirect_uri sent here MUST be byte-identical at the authorize step and the token step (Core compares it
+ * Ordinal at the token step) and equal to the registered {site_url}/api/auth/callback (Core compares it exactly,
+ * case-insensitively, at the authorize step). Both come from ONE value: the `redirectURI` of the provider config.
+ */
+import { createRemoteJWKSet, decodeProtectedHeader, jwtVerify, type JWTVerifyGetKey } from 'jose';
+
+export interface IdpTokenGrant {
+  accessToken: string;
+  refreshToken?: string;
+  /** epoch ms */
+  accessTokenExpires?: number;
+  tokenType?: string;
+  /** The `user` object of the IdP response, passed through untouched (shape not contractually fixed). */
+  user?: Record<string, unknown>;
+}
+
+export interface IdpVerifiedClaims {
+  sub: string;
+  email: string;
+  name: string;
+  userId?: string;
+  roles: string[];
+  /**
+   * true ONLY when the verified token asserts email_verified === true (or "true"). Never assumed: better-auth links by email
+   * from what getUserInfo returns, so an unasserted value must not let an IdP email attach to an existing local account.
+   */
+  emailVerified: boolean;
+  /** true only when the VERIFIED access token's amr contains "mfa" (Core's HasSecondFactor rule). */
+  mfaVerified: boolean;
+}
+
+export interface IdpOAuthHookDeps {
+  fetch?: typeof fetch;
+  /** Key resolver for a jwks_uri. Default: jose createRemoteJWKSet. Tests inject a local key set. */
+  getKeySet?: (jwksUri: string) => JWTVerifyGetKey;
+  now?: () => number;
+}
+
+export interface IdpOAuthHookOptions {
+  discoveryUrl: string;
+  clientId: string;
+  redirectURI: string;
+  /** Override for the expected `iss`. Default: the discovery document's `issuer`. */
+  issuer?: string;
+  /**
+   * Extra origins the discovery document may point token_endpoint / jwks_uri at. By default both MUST share the origin of
+   * `discoveryUrl`, so a document cannot send the code exchange or the key fetch to another host. Set this only for a
+   * split-host deployment (internal discovery URL, public endpoints). Comma-separated env: IDP_OAUTH_TRUSTED_ORIGINS.
+   */
+  trustedOrigins?: string[];
+  onTokens?: (grant: IdpTokenGrant) => void;
+  onClaims?: (claims: IdpVerifiedClaims) => void;
+  deps?: IdpOAuthHookDeps;
+}
+
+const DISCOVERY_TTL_MS = 10 * 60 * 1000;
+const HTTP_TIMEOUT_MS = 10_000;
+
+/** The URI sent at authorize AND token time. Explicit env wins; else the registered {app}/api/auth/callback form. */
+export function resolveIdpRedirectUri(appBaseUrl: string, env: NodeJS.ProcessEnv = process.env): string {
+  const explicit = env.IDP_OAUTH_REDIRECT_URI?.trim();
+  if (explicit) return explicit;
+  return appBaseUrl.replace(/\/+$/, '') + '/api/auth/callback';
+}
+
+/** amr arrives as an array, a JSON-array string, or a delimited string (Core's own reader accepts all three). */
+export function amrIncludesMfa(amr: unknown): boolean {
+  let values: unknown[] = [];
+  if (Array.isArray(amr)) values = amr;
+  else if (typeof amr === 'string') {
+    const t = amr.trim();
+    if (t.startsWith('[')) {
+      try {
+        const parsed = JSON.parse(t);
+        if (Array.isArray(parsed)) values = parsed;
+      } catch {
+        values = [];
+      }
+    } else {
+      values = t.split(/[\s,]+/);
+    }
+  }
+  return values.some((v) => typeof v === 'string' && v.trim().toLowerCase() === 'mfa');
+}
+
+/** Max skew accepted on nbf/exp/iat when verifying the IdP access token. */
+export const CLOCK_TOLERANCE_SECONDS = 30;
+
+/**
+ * Address shape, a POSITIVE character rule (PAY-2337, Scout 74285): the local part may contain only [A-Za-z0-9] and . _ % + - ' ; the domain only
+ * [A-Za-z0-9-] labels joined by dots; one @, <= 254 total, local <= 64, no leading/trailing/double dot in the local part, a dotted domain.
+ * Everything else is NOT an address, and in particular a MASK: Core masks data.user.email on purpose (MaskedEmailJsonConverter), today with '*',
+ * tomorrow maybe a bullet, an ellipsis or an 'x' run; a blacklist of one glyph would pass the next mask. Not a deliverability check.
+ */
+export function isAddressShaped(v: unknown): v is string {
+  if (typeof v !== 'string' || v.length === 0 || v.length > 254) return false;
+  if (!/^[A-Za-z0-9._%+'-]+@[A-Za-z0-9.-]+$/.test(v)) return false;
+  const [local, domain] = v.split('@');
+  if (local.length > 64 || local.startsWith('.') || local.endsWith('.') || local.includes('..')) return false;
+  return /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/.test(domain) && !domain.startsWith('-') && !domain.endsWith('-');
+}
+
+/**
+ * The account address (BAPert 74193 / 74196, 4.7.8). Core's code-flow access token has NO email claim; its sub and ws-identity name claim are
+ * both user.UserName, which is a LOGIN, not the mailbox: it may be address-shaped and still differ from the account's Email (4.7.7 vetoed on that
+ * and refused every such sign-in, NightHawk 74189). Sources: the token RESPONSE's data.user.email (token endpoint, TLS) and/or the signed token's
+ * own email claim; if both are present they must be equal. sub / the name claim are NEITHER a source NOR a veto. Not trimmed. Returns '' on any doubt.
+ */
+export function resolveEmail(payload: Record<string, unknown>, responseEmail?: unknown): string {
+  // NOT trimmed: padding or a trailing newline is a malformed address (refused by the shape check), never silently repaired.
+  const raw = (v: unknown) => (typeof v === 'string' ? v : '');
+  const sources = [raw(payload.email), raw(responseEmail)].filter((v) => v.trim() !== '');
+  if (sources.length === 0 || !sources.every(isAddressShaped)) return '';
+  const chosen = sources[0];
+  const same = (a: string) => a.toLowerCase() === chosen.toLowerCase();
+  if (!sources.every(same)) return '';
+  return chosen;
+}
+
+function rolesOf(claim: unknown): string[] {
+  if (Array.isArray(claim)) return claim.filter((r): r is string => typeof r === 'string' && r.length > 0);
+  if (typeof claim === 'string' && claim.trim()) {
+    const t = claim.trim();
+    if (t.startsWith('[')) {
+      try {
+        const parsed = JSON.parse(t);
+        if (Array.isArray(parsed)) return parsed.filter((r): r is string => typeof r === 'string' && r.length > 0);
+      } catch {
+        return [];
+      }
+    }
+    return t.split(/[\s,]+/).filter(Boolean);
+  }
+  return [];
+}
+
+export function createIdpOAuthHooks(opts: IdpOAuthHookOptions) {
+  const fetchFn = opts.deps?.fetch ?? fetch;
+  const now = opts.deps?.now ?? (() => Date.now());
+  const getKeySet = opts.deps?.getKeySet ?? ((uri: string) => createRemoteJWKSet(new URL(uri)));
+
+  let discovery: { doc: Record<string, unknown>; at: number } | null = null;
+  const keySets = new Map<string, JWTVerifyGetKey>();
+  /** access token -> data.user.email / user_name from the token response, consumed by getUserInfo for THAT token (bounded; never keyed by anything shared). */
+  const responseUsers = new Map<string, { email: string; userName: string }>();
+
+  async function loadDiscovery(): Promise<Record<string, unknown>> {
+    if (discovery && now() - discovery.at < DISCOVERY_TTL_MS) return discovery.doc;
+    const res = await fetchFn(opts.discoveryUrl, {
+      headers: { Accept: 'application/json' },
+      redirect: 'error',
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    });
+    if (!res.ok) throw new Error(`IdP discovery returned ${res.status}`);
+    const doc = (await res.json()) as Record<string, unknown>;
+    if (typeof doc?.token_endpoint !== 'string' || typeof doc?.jwks_uri !== 'string' || typeof doc?.issuer !== 'string') {
+      throw new Error('IdP discovery document is missing token_endpoint, jwks_uri or issuer');
+    }
+    const allowed = new Set([new URL(opts.discoveryUrl).origin, ...(opts.trustedOrigins ?? []).map((o) => o.replace(/\/+$/, ''))]);
+    for (const field of ['token_endpoint', 'jwks_uri'] as const) {
+      const origin = new URL(doc[field] as string).origin;
+      if (!allowed.has(origin)) throw new Error(`IdP discovery ${field} points at an untrusted origin (${origin})`);
+    }
+    discovery = { doc, at: now() }; // only a good document is cached
+    return doc;
+  }
+
+  /** better-auth `getToken`: JSON body, envelope unwrapped, no data.access_token => refused. */
+  async function getToken(data: { code: string; codeVerifier?: string }) {
+    const doc = await loadDiscovery();
+    if (!data.codeVerifier) throw new Error('IdP token exchange refused: no PKCE code_verifier');
+    const res = await fetchFn(doc.token_endpoint as string, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      redirect: 'error',
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+      body: JSON.stringify({
+        grant_type: 'authorization_code',
+        code: data.code,
+        code_verifier: data.codeVerifier,
+        // Deliberately NOT data.redirectURI: that is better-auth's own computed callback, not the registered URI.
+        redirect_uri: opts.redirectURI,
+        client_id: opts.clientId,
+      }),
+    });
+    let body: any;
+    try {
+      body = await res.json();
+    } catch {
+      throw new Error(`IdP token response (${res.status}) was not JSON`);
+    }
+    if (!res.ok) {
+      const code = body?.error?.code ?? body?.error ?? body?.code ?? 'unknown';
+      throw new Error(`IdP token exchange refused (${res.status}, ${typeof code === 'string' ? code : 'unknown'})`);
+    }
+    const d = body?.data;
+    if (!d || typeof d.access_token !== 'string' || !d.access_token) {
+      throw new Error('IdP token response has no data.access_token (envelope not as expected)');
+    }
+    const expiresIn = typeof d.expires_in === 'number' && d.expires_in > 0 ? d.expires_in : undefined;
+    const expires = expiresIn ? now() + expiresIn * 1000 : undefined;
+    if (d.user && typeof d.user === 'object' && typeof d.user.email === 'string') {
+      if (responseUsers.size >= 64) responseUsers.delete(responseUsers.keys().next().value as string);
+      responseUsers.set(d.access_token, { email: d.user.email, userName: typeof d.user.user_name === 'string' ? d.user.user_name : '' });
+    }
+    opts.onTokens?.({
+      accessToken: d.access_token,
+      refreshToken: typeof d.refresh_token === 'string' ? d.refresh_token : undefined,
+      accessTokenExpires: expires,
+      tokenType: typeof d.token_type === 'string' ? d.token_type : undefined,
+      user: d.user && typeof d.user === 'object' ? d.user : undefined,
+    });
+    return {
+      tokenType: typeof d.token_type === 'string' ? d.token_type : 'Bearer',
+      accessToken: d.access_token,
+      refreshToken: typeof d.refresh_token === 'string' ? d.refresh_token : undefined,
+      accessTokenExpiresAt: expires ? new Date(expires) : undefined,
+      scopes: [] as string[],
+    };
+  }
+
+  /** better-auth `getUserInfo`: the user comes from the VERIFIED access token. Returns null (never a guess) on any doubt. */
+  async function getUserInfo(tokens: { accessToken?: string }) {
+    try {
+      if (!tokens?.accessToken) return null;
+      const doc = await loadDiscovery();
+      // A token without a kid is refused: no "first key" fallback. (A kid that is not in the key set is refused by jose.)
+      const kid = decodeProtectedHeader(tokens.accessToken).kid;
+      if (typeof kid !== 'string' || !kid) throw new Error('token header has no kid');
+      const jwksUri = doc.jwks_uri as string;
+      let keys = keySets.get(jwksUri);
+      if (!keys) {
+        keys = getKeySet(jwksUri);
+        keySets.set(jwksUri, keys);
+      }
+      const { payload } = await jwtVerify(tokens.accessToken, keys, {
+        // RSA signatures ONLY (RS256/384/512, PS256/384/512; BAPert 74117): never HS* (a token "signed" with the public key as an HMAC
+        // secret), never none, never ES. 4.7.4/4.7.5 pinned RS256 from a source read; the live IdP's JWKS (dev-93, kid 46) declares alg RS512
+        // and every real access token was refused (NightHawk 74114). Which RS alg is binding is the JWKS KEY's own declared
+        // `alg`: jose only offers a JWK to a token whose header alg equals that JWK's `alg`, so a token cannot choose a
+        // weaker/other algorithm than the published key says. A JWK with no `alg` accepts any listed RSA alg; a symmetric (oct) key is never usable for these algorithms.
+        algorithms: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512'],
+        issuer: opts.issuer ?? (doc.issuer as string),
+        currentDate: new Date(now()),
+        // The IdP stamps nbf = issue time with no skew and the token is verified in the same second it is minted (NightHawk 74151:
+        // "nbf claim timestamp check failed"). 30 s, bounded. jose applies it to exp too: a token is accepted up to 30 s after exp.
+        clockTolerance: CLOCK_TOLERANCE_SECONDS,
+      });
+      if (payload.token_type !== 'bearer_token') throw new Error('token_type is not bearer_token');
+      if (typeof payload.sub !== 'string' || !payload.sub) throw new Error('no sub');
+      const hasEmailClaim = typeof payload.email === 'string' && payload.email.trim() !== '';
+      const responseUser = responseUsers.get(tokens.accessToken);
+      responseUsers.delete(tokens.accessToken);
+      // The response user object (UNSIGNED body) must be the TOKEN's user (Scout 74198, DotNetPert-Scout 74202): Core fills data.user.user_name and the
+      // signed sub from the same loaded user in one mint, so WHENEVER a response user exists (even if a signed email claim is also present), user_name MUST be present
+      // and equal sub (case-insensitive). A different or missing user_name means the address may belong to someone else -> refuse. Does not constrain email == sub.
+      if (responseUser && responseUser.userName.trim().toLowerCase() !== payload.sub.trim().toLowerCase()) {
+        throw new Error('token response user is missing or does not match the token subject');
+      }
+      // A MASKED / unusable response address is ABSENT (PAY-2337), not "a different address": a valid signed claim still signs in, and with no claim
+      // there is no source. NEVER repaired or unmasked (no prefix match against sub or the claim). Log names only the fact, no value, no length.
+      const responseEmailRaw = responseUser?.email ?? '';
+      const responseEmailUsable = isAddressShaped(responseEmailRaw);
+      const responseMasked = responseEmailRaw.trim() !== '' && !responseEmailUsable;
+      if (responseMasked) console.warn('[BETTER_AUTH] payez-idp token response address is masked or unusable; ignored');
+      const email = resolveEmail(payload as Record<string, unknown>, responseEmailUsable ? responseEmailRaw : undefined);
+      if (!email) {
+        throw new Error(responseMasked ? 'response address is masked' : 'no usable email (needs data.user.email or an email claim, address-shaped, equal when both are present)');
+      }
+      const name =
+        (typeof payload.name === 'string' && payload.name.trim()) ||
+        (typeof payload.full_name === 'string' && payload.full_name.trim()) ||
+        email.split('@')[0];
+      const claims: IdpVerifiedClaims = {
+        sub: payload.sub,
+        email,
+        name,
+        userId: typeof payload.user_id === 'string' || typeof payload.user_id === 'number' ? String(payload.user_id) : undefined,
+        roles: rolesOf(payload.roles),
+        mfaVerified: amrIncludesMfa(payload.amr),
+        // Only the signed token's own email CLAIM can be verified; an address that came from the token response (data.user.email) never asserts it.
+        emailVerified: hasEmailClaim && (payload.email_verified === true || payload.email_verified === 'true'),
+      };
+      opts.onClaims?.(claims);
+      return { id: claims.sub, email: claims.email, name: claims.name, emailVerified: claims.emailVerified };
+    } catch (err) {
+      // Reason only, never the token.
+      console.warn('[BETTER_AUTH] payez-idp access token refused:', err instanceof Error ? err.message : String(err));
+      return null;
+    }
+  }
+
+  return { getToken, getUserInfo };
+}