@payez/next-mvp 4.5.7 → 4.7.9

package/src/api-handlers/oauth/resume.ts

@@ -0,0 +1,182 @@
+/**
+ * GET /api/oauth/resume?return_url=<IdP authorize request> - moved from VibeID-Customer-Portal src/app/api/oauth/resume/route.ts
+ * (PAY-1500), PAY-2302 cut 2.
+ *
+ * The only place an absolute post-2FA destination is followed, and only after checking it is this deployment's IdP
+ * authorize endpoint (lib/authorize-resume). Everything else is refused to a same-origin page: this route must never
+ * become an open redirect.
+ *
+ * The validation base is the app's configured IDP_URL, never anything derived from the request. If IDP_URL is unset
+ * or not a URL the answer is the refusal, not a throw and not a fallback to the request's own origin (fail closed).
+ * INTERNAL_IDP_URL is deliberately NOT used: the authorize URL is the PUBLIC IdP's (it is also what the registered client uses).
+ *
+ * PAY-2319 (4.7.1): WHERE a refusal goes is configurable and the default is the login page every generated app has
+ * (`/account-auth/login?error=AUTHORIZE_RESUME_REFUSED`). 4.7.0 hard-coded the portal's `/sign-in`, which a generated app does not
+ * have: the middleware forwarded it to the login page with the error code dropped and, after sign-in, to a 404.
+ * An app (the portal has /sign-in) passes its own location through createOAuthResumeHandler.
+ *
+ * 4.7.5 (PAY-2305): THE AUTHORIZE CALL IS MADE HERE, SERVER-SIDE. Core's /api/oauth/authorize identifies a user only from an
+ * `Authorization: Bearer` header (JwtMiddleware reads no cookie), so sending the BROWSER to it (4.7.0-4.7.4) could never produce a
+ * code. This route now
+ *   1. validates return_url and REBUILDS the authorize URL from constants (IDP_URL origin, fixed path, this app's CLIENT_ID and
+ *      registered redirect_uri); only code_challenge (S256), state and scope come from return_url, each validated;
+ *   2. requires a same-site navigation, a browser that STARTED the flow (better-auth's oauth_state cookie) and the signed-in app session;
+ *   3. calls authorize with the user's IdP access token (redirect: 'manual', timeout; the token goes only to the IDP_URL origin and
+ *      is never logged);
+ *   4. accepts ONLY a redirect to the registered redirect_uri carrying a code and the state it sent, and relays it to the browser
+ *      as a RELATIVE path+query rebuilt from those two values.
+ * Anything else (IdP sends the user to login / 2FA enrolment / an error, no session, refresh fails, IdP unreachable) is the
+ * refusal. Nothing is retried or followed.
+ */
+import { buildServerAuthorizeRequest, hasOAuthStateCookie, isSameSiteResume, relayRegisteredCallback } from '../../lib/authorize-resume';
+import { resolveIdpRedirectUri } from '../../auth/idp-oauth';
+
+export const DEFAULT_REFUSAL_LOCATION = '/account-auth/login?error=AUTHORIZE_RESUME_REFUSED';
+
+export interface OAuthResumeDeps {
+  /** Test seam. Default: global fetch. */
+  fetch?: typeof fetch;
+  /** Test seam. Default: the signed-in app session's IdP access token (one refresh attempt when near expiry), else null. */
+  resolveAccessToken?: (request: Request) => Promise<string | null>;
+  /** Test seam. Default: BETTER_AUTH_URL, else the IdP client config's baseClientUrl, else http://localhost:$PORT (the SAME chain the provider config uses). */
+  appBaseUrl?: () => Promise<string>;
+}
+
+export interface OAuthResumeOptions {
+  /** Same-origin location a refused request is sent to. Must start with a single "/" (no //host, no backslash, no scheme). */
+  refusalLocation?: string;
+  deps?: OAuthResumeDeps;
+}
+
+/** A relative, same-origin location only: the refusal must never itself become an open redirect. */
+function assertRelativeLocation(loc: string): string {
+  const ok = typeof loc === 'string' && loc.startsWith('/') && !loc.startsWith('//') && !loc.startsWith('/\\') && !/\s/.test(loc);
+  if (!ok) {
+    throw new TypeError(`createOAuthResumeHandler: refusalLocation must be a same-origin path starting with a single "/", got ${JSON.stringify(loc)}`);
+  }
+  return loc;
+}
+
+const AUTHORIZE_TIMEOUT_MS = 8000;
+
+/** Cookie header -> the `{ get(name) }` shape decodeSession wants (NextRequest.cookies). */
+function cookieJar(header: string | null): { get: (name: string) => { value: string } | undefined } {
+  const map = new Map<string, string>();
+  for (const part of (header ?? '').split(';')) {
+    const i = part.indexOf('=');
+    if (i < 1) continue;
+    const name = part.slice(0, i).trim();
+    let value = part.slice(i + 1).trim();
+    try {
+      value = decodeURIComponent(value);
+    } catch {
+      /* keep the raw value */
+    }
+    if (!map.has(name)) map.set(name, value);
+  }
+  return { get: (name) => (map.has(name) ? { value: map.get(name)! } : undefined) };
+}
+
+async function defaultResolveAccessToken(request: Request): Promise<string | null> {
+  const { decodeSession } = await import('../../server/decode-session');
+  const decoded = await decodeSession(cookieJar(request.headers.get('cookie')));
+  const sessionToken = (decoded?.jwtPayload?.sessionToken || decoded?.jwtPayload?.redisSessionId) as string | undefined;
+  if (!sessionToken) return null;
+  const { ensureFreshAccessToken } = await import('../../lib/ensure-fresh-access-token');
+  const fresh = await ensureFreshAccessToken(sessionToken, {
+    idpBaseUrl: process.env.IDP_URL as string,
+    clientId: process.env.CLIENT_ID as string,
+  });
+  return fresh.ok ? fresh.accessToken : null;
+}
+
+async function defaultAppBaseUrl(): Promise<string> {
+  if (process.env.BETTER_AUTH_URL) return process.env.BETTER_AUTH_URL;
+  try {
+    const { getIDPClientConfig } = await import('../../lib/idp-client-config');
+    const cfg = await getIDPClientConfig();
+    if (cfg?.baseClientUrl) return cfg.baseClientUrl;
+  } catch {
+    /* fall through to the local default, exactly as createBetterAuthInstance does */
+  }
+  return `http://localhost:${process.env.PORT || '3000'}`;
+}
+
+export function createOAuthResumeHandler(options: OAuthResumeOptions = {}): (request: Request) => Promise<Response> {
+  const refusalLocation = assertRelativeLocation(options.refusalLocation ?? DEFAULT_REFUSAL_LOCATION);
+  const fetchFn = options.deps?.fetch ?? ((...a: Parameters<typeof fetch>) => fetch(...a));
+  const resolveAccessToken = options.deps?.resolveAccessToken ?? defaultResolveAccessToken;
+  const appBaseUrl = options.deps?.appBaseUrl ?? defaultAppBaseUrl;
+
+  // RELATIVE Location on purpose: in a container request.url is the bind address (http://0.0.0.0:8080), so
+  // new URL(path, request.url) would send the browser to a dead host (kb 3463/5571; QAPert 59254 F1).
+  const refuse = (why: string): Response => {
+    console.warn(`[oauth-resume] AUTHORIZE_RESUME outcome=refused reason=${why}`);
+    return new Response(null, { status: 302, headers: { location: refusalLocation, 'cache-control': 'no-store' } });
+  };
+
+  return async function GET(request: Request): Promise<Response> {
+    const idpBase = process.env.IDP_URL;
+    const clientId = process.env.CLIENT_ID;
+    if (!idpBase || !clientId) return refuse('not-configured');
+
+    let redirectUri: string;
+    try {
+      redirectUri = resolveIdpRedirectUri(await appBaseUrl());
+    } catch {
+      return refuse('no-app-base');
+    }
+
+    const built = buildServerAuthorizeRequest(new URL(request.url).searchParams.get('return_url'), {
+      idpBaseUrl: idpBase,
+      clientId,
+      redirectUri,
+    });
+    if (!built) return refuse('return_url');
+
+    let appOrigin: string;
+    try {
+      appOrigin = new URL(redirectUri).origin;
+    } catch {
+      return refuse('bad-redirect-uri');
+    }
+    if (!isSameSiteResume(request.headers, appOrigin)) return refuse('not-same-site');
+    if (!hasOAuthStateCookie(request.headers.get('cookie'))) return refuse('no-oauth-state'); // this browser never started the flow
+
+    let accessToken: string | null = null;
+    try {
+      accessToken = await resolveAccessToken(request);
+    } catch {
+      accessToken = null;
+    }
+    if (!accessToken) return refuse('no-session');
+
+    const forwarded: Record<string, string> = {};
+    const ua = request.headers.get('user-agent');
+    if (ua) forwarded['User-Agent'] = ua;
+    const xff = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip');
+    if (xff) forwarded['X-Forwarded-For'] = xff;
+    const device = request.headers.get('x-device-id');
+    if (device) forwarded['X-Device-ID'] = device;
+
+    let res: Response;
+    try {
+      res = await fetchFn(built.url, {
+        method: 'GET',
+        headers: { ...forwarded, Accept: 'application/json', Authorization: `Bearer ${accessToken}` },
+        redirect: 'manual', // the Bearer header is never carried to a second URL
+        signal: AbortSignal.timeout(AUTHORIZE_TIMEOUT_MS),
+      });
+    } catch {
+      return refuse('idp-unreachable');
+    }
+
+    const relay = relayRegisteredCallback(res.status, res.headers.get('location'), redirectUri, built.state);
+    // Status only in the log: the Location can carry a code or a return_url.
+    if (!relay) return refuse(`idp-answered-${res.status}`);
+    console.log('[oauth-resume] AUTHORIZE_RESUME outcome=code-issued');
+    return new Response(null, { status: 302, headers: { location: relay, 'cache-control': 'no-store' } });
+  };
+}
+
+export const GET = createOAuthResumeHandler();

package/src/auth/better-auth.ts

@@ -20,6 +20,12 @@ import { wrapBetterAuthHandler } from './session-response-sanitizer';
 import { magicLink, type MagicLinkOptions } from 'better-auth/plugins/magic-link';
 import { resolveClientKey } from '../lib/client-key';
 import { genericOAuth } from 'better-auth/plugins/generic-oauth';
+import {
+  createIdpOAuthHooks,
+  resolveIdpRedirectUri,
+  type IdpTokenGrant,
+  type IdpVerifiedClaims,
+} from './idp-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import { getAppSlug, assertAppSlugMatchesIdp } from '../lib/app-slug';
@@ -143,7 +149,12 @@ export interface BetterAuthSocialProvider {
  * verifies for itself and never trusts an asserted email.
  */
 const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
-type ProviderTokenScope = { idToken?: string; accessToken?: string };
+type ProviderTokenScope = {
+  idToken?: string;
+  accessToken?: string;
+  /** PAY-2305: what the payez-idp getToken / getUserInfo hooks captured for THIS request (never persisted here). */
+  idp?: { tokens?: IdpTokenGrant; claims?: IdpVerifiedClaims };
+};
 const gScope = globalThis as unknown as Record<
   string,
   AsyncLocalStorage<ProviderTokenScope> | undefined
@@ -182,21 +193,51 @@ const idTokenScope = gScope[ID_TOKEN_SCOPE_KEY]!;
  * exchange must verify signature/iss/aud/exp itself and preserve those four, or
  * they are lost silently.
  */
-export function buildIdpOAuthProviderConfig(): {
+export interface IdpOAuthProviderConfig {
   providerId: string;
   discoveryUrl: string;
   clientId: string;
   pkce: true;
   scopes: string[];
-} | null {
+  /** PAY-2305: the REGISTERED {site_url}/api/auth/callback, sent identically at authorize and token time. */
+  redirectURI: string;
+  getToken: ReturnType<typeof createIdpOAuthHooks>['getToken'];
+  getUserInfo: ReturnType<typeof createIdpOAuthHooks>['getUserInfo'];
+}
+
+export function buildIdpOAuthProviderConfig(appBaseUrl?: string): IdpOAuthProviderConfig | null {
   const discoveryUrl = process.env.IDP_OAUTH_DISCOVERY_URL;
   const clientId = process.env.CLIENT_ID;
   if (!discoveryUrl || !clientId) return null;
 
+  const redirectURI = resolveIdpRedirectUri(
+    appBaseUrl || process.env.BETTER_AUTH_URL || process.env.APP_URL || `http://localhost:${process.env.PORT || '3000'}`,
+  );
+  const hooks = createIdpOAuthHooks({
+    discoveryUrl,
+    clientId,
+    redirectURI,
+    issuer: process.env.IDP_OAUTH_ISSUER || undefined,
+    trustedOrigins: process.env.IDP_OAUTH_TRUSTED_ORIGINS
+      ? process.env.IDP_OAUTH_TRUSTED_ORIGINS.split(',').map((x) => x.trim()).filter(Boolean)
+      : undefined,
+    onTokens: (tokens) => {
+      const store = idTokenScope.getStore();
+      if (store) (store.idp ??= {}).tokens = tokens;
+    },
+    onClaims: (claims) => {
+      const store = idTokenScope.getStore();
+      if (store) (store.idp ??= {}).claims = claims;
+    },
+  });
+
   return {
     providerId: 'payez-idp',
     discoveryUrl,
     clientId,
+    redirectURI,
+    getToken: hooks.getToken,
+    getUserInfo: hooks.getUserInfo,
     // NO clientSecret. The whole point: this app is not a credential holder.
     pkce: true,
     scopes: ['openid', 'email', 'profile'],
@@ -565,7 +606,7 @@ export function createBetterAuthInstance(
     || `http://localhost:${process.env.PORT || '3000'}`;
   const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
 
-  const idpOAuth = buildIdpOAuthProviderConfig();
+  const idpOAuth = buildIdpOAuthProviderConfig(rawBaseURL);
 
   return betterAuth({
     baseURL,
@@ -1417,6 +1458,37 @@ export async function storeIdpTokensInSession(
  */
 export const OAUTH_SIGN_IN_FAILED_ERROR = 'OAUTH_SIGN_IN_FAILED';
 
+/**
+ * PAY-2305: store the tokens the payez-idp provider hooks captured during THIS request. Fail closed: no captured tokens or no
+ * verified claims (getUserInfo refused the token) => false, and the caller aborts the sign-in. nextStep is left undefined on
+ * purpose (unknown is not "fully authenticated", see 141688); mfaVerified comes only from the verified token's amr.
+ */
+export async function storePayezIdpSession(sessionToken: string): Promise<boolean> {
+  const captured = idTokenScope.getStore()?.idp;
+  if (!captured?.tokens?.accessToken || !captured.claims) {
+    console.warn('[BETTER_AUTH] payez-idp callback: no verified IdP tokens captured for this request');
+    return false;
+  }
+  const { tokens, claims } = captured;
+  const stored = await storeIdpTokensInSession(
+    sessionToken,
+    {
+      idpAccessToken: tokens.accessToken,
+      idpRefreshToken: tokens.refreshToken,
+      idpAccessTokenExpires: tokens.accessTokenExpires ?? Date.now() + 15 * 60 * 1000,
+      userId: String(claims.userId ?? claims.sub),
+      email: claims.email,
+      name: claims.name,
+      roles: claims.roles,
+      mfaVerified: claims.mfaVerified,
+      nextStep: undefined,
+    },
+    'payez-idp',
+  );
+  if (stored) console.log('[BETTER_AUTH] IdP tokens stored in session for', claims.email);
+  return stored;
+}
+
 /**
  * The ONLY IdP refusal codes the package forwards to the login page (PAY-2005 (b), BAPert 67897).
  *
@@ -1591,7 +1663,11 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
           if (session?.session?.token) {
             sessionToken = session.session.token;
             console.log('[BETTER_AUTH] Got session token from callback:', tokenLogId(session.session.token), '| email:', session.user?.email);
-            exchange = await exchangeOAuthForIdpTokens(session.session.token);
+            // PAY-2305: the payez-idp callback already holds an IdP-ISSUED bearer (verified in getUserInfo). It must NOT go
+            // through oauth-callback, the asserted-email path (card 138635), and storing it is what the passkey path does.
+            exchange = url.pathname.endsWith('/callback/payez-idp')
+              ? await storePayezIdpSession(session.session.token)
+              : await exchangeOAuthForIdpTokens(session.session.token);
           } else {
             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
           }

package/src/auth/idp-oauth.ts

@@ -0,0 +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 };
+}

package/src/auth/safe-callback.ts

@@ -65,6 +65,15 @@ export const DEFAULT_CALLBACK = '/';
 /** The auth surface. A callback pointing back into it causes a redirect cycle. */
 const AUTH_PREFIX = '/account-auth/';
 
+/**
+ * PAY-2315 (4.7.1): the middleware now treats the public /login page like /account-auth/login (a signed-in user is sent
+ * on), so a callback or a resolved path that is /login itself must be refused here too - otherwise /login with no
+ * callbackUrl would resolve its own pathname as the destination and redirect to itself forever.
+ */
+function isAuthSurface(pathname: string): boolean {
+  return pathname.startsWith(AUTH_PREFIX) || pathname === '/login' || pathname.startsWith('/login/');
+}
+
 /**
  * Synthetic, unreachable base. Only ever used as the resolution origin for the
  * comparison below - never emitted, never navigated to. `.invalid` is reserved
@@ -93,7 +102,7 @@ export function safeCallbackPath(raw: unknown, fallback: string = DEFAULT_CALLBA
   if (url.origin !== BASE) return fallback;
 
   // Loopbacks into the auth surface cause redirect cycles.
-  if (url.pathname.startsWith(AUTH_PREFIX)) return fallback;
+  if (isAuthSurface(url.pathname)) return fallback;
 
   // PAY-2218: `_rsc` is Next's flight cache-buster. Once skipProxyUrlNormalize lets it reach middleware it leaks
   // into return targets (`callbackUrl=/overview?_rsc=abc12`, NightHawk 72013); it is never a meaningful part of a
@@ -140,7 +149,7 @@ export function safeCallbackPath(raw: unknown, fallback: string = DEFAULT_CALLBA
     return fallback;
   }
   if (echo.origin !== BASE) return fallback;
-  if (echo.pathname.startsWith(AUTH_PREFIX)) return fallback;
+  if (isAuthSurface(echo.pathname)) return fallback;
   if (echo.pathname + echo.search + echo.hash !== candidate) return fallback;
 
   return candidate;