@payez/next-mvp 4.5.7 → 4.7.9

package/dist/api-handlers/oauth/resume.d.ts

@@ -0,0 +1,16 @@
+export declare 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;
+}
+export declare function createOAuthResumeHandler(options?: OAuthResumeOptions): (request: Request) => Promise<Response>;
+export declare const GET: (request: Request) => Promise<Response>;

package/dist/api-handlers/oauth/resume.js

@@ -0,0 +1,207 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = exports.DEFAULT_REFUSAL_LOCATION = void 0;
+exports.createOAuthResumeHandler = createOAuthResumeHandler;
+/**
+ * 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.
+ */
+const authorize_resume_1 = require("../../lib/authorize-resume");
+const idp_oauth_1 = require("../../auth/idp-oauth");
+exports.DEFAULT_REFUSAL_LOCATION = '/account-auth/login?error=AUTHORIZE_RESUME_REFUSED';
+/** A relative, same-origin location only: the refusal must never itself become an open redirect. */
+function assertRelativeLocation(loc) {
+    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) {
+    const map = new Map();
+    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) {
+    const { decodeSession } = await Promise.resolve().then(() => __importStar(require('../../server/decode-session')));
+    const decoded = await decodeSession(cookieJar(request.headers.get('cookie')));
+    const sessionToken = (decoded?.jwtPayload?.sessionToken || decoded?.jwtPayload?.redisSessionId);
+    if (!sessionToken)
+        return null;
+    const { ensureFreshAccessToken } = await Promise.resolve().then(() => __importStar(require('../../lib/ensure-fresh-access-token')));
+    const fresh = await ensureFreshAccessToken(sessionToken, {
+        idpBaseUrl: process.env.IDP_URL,
+        clientId: process.env.CLIENT_ID,
+    });
+    return fresh.ok ? fresh.accessToken : null;
+}
+async function defaultAppBaseUrl() {
+    if (process.env.BETTER_AUTH_URL)
+        return process.env.BETTER_AUTH_URL;
+    try {
+        const { getIDPClientConfig } = await Promise.resolve().then(() => __importStar(require('../../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'}`;
+}
+function createOAuthResumeHandler(options = {}) {
+    const refusalLocation = assertRelativeLocation(options.refusalLocation ?? exports.DEFAULT_REFUSAL_LOCATION);
+    const fetchFn = options.deps?.fetch ?? ((...a) => 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) => {
+        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) {
+        const idpBase = process.env.IDP_URL;
+        const clientId = process.env.CLIENT_ID;
+        if (!idpBase || !clientId)
+            return refuse('not-configured');
+        let redirectUri;
+        try {
+            redirectUri = (0, idp_oauth_1.resolveIdpRedirectUri)(await appBaseUrl());
+        }
+        catch {
+            return refuse('no-app-base');
+        }
+        const built = (0, authorize_resume_1.buildServerAuthorizeRequest)(new URL(request.url).searchParams.get('return_url'), {
+            idpBaseUrl: idpBase,
+            clientId,
+            redirectUri,
+        });
+        if (!built)
+            return refuse('return_url');
+        let appOrigin;
+        try {
+            appOrigin = new URL(redirectUri).origin;
+        }
+        catch {
+            return refuse('bad-redirect-uri');
+        }
+        if (!(0, authorize_resume_1.isSameSiteResume)(request.headers, appOrigin))
+            return refuse('not-same-site');
+        if (!(0, authorize_resume_1.hasOAuthStateCookie)(request.headers.get('cookie')))
+            return refuse('no-oauth-state'); // this browser never started the flow
+        let accessToken = null;
+        try {
+            accessToken = await resolveAccessToken(request);
+        }
+        catch {
+            accessToken = null;
+        }
+        if (!accessToken)
+            return refuse('no-session');
+        const forwarded = {};
+        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;
+        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 = (0, authorize_resume_1.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' } });
+    };
+}
+exports.GET = createOAuthResumeHandler();

package/dist/auth/better-auth.d.ts

@@ -11,6 +11,7 @@
 import 'server-only';
 import { betterAuth } from 'better-auth';
 import { type MagicLinkOptions } from 'better-auth/plugins/magic-link';
+import { createIdpOAuthHooks } from './idp-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
@@ -67,13 +68,18 @@ export interface BetterAuthSocialProvider {
  * exchange must verify signature/iss/aud/exp itself and preserve those four, or
  * they are lost silently.
  */
-export declare 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 declare function buildIdpOAuthProviderConfig(appBaseUrl?: string): IdpOAuthProviderConfig | null;
 export declare function buildBetterAuthProviders(config: IDPClientConfig): Record<string, BetterAuthSocialProvider>;
 /**
  * Optional configuration for `createBetterAuthInstance`.
@@ -594,6 +600,12 @@ export declare function storeIdpTokensInSession(sessionToken: string, idpTokenDa
  * Try again or use another method." The cause stays in the server log, never on the page.
  */
 export declare 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 declare function storePayezIdpSession(sessionToken: string): Promise<boolean>;
 /**
  * The ONLY IdP refusal codes the package forwards to the login page (PAY-2005 (b), BAPert 67897).
  *

package/dist/auth/better-auth.js

@@ -55,6 +55,7 @@ exports.getBetterAuthInstance = getBetterAuthInstance;
 exports.getBetterAuthHandler = getBetterAuthHandler;
 exports.exchangeOAuthForIdpTokens = exchangeOAuthForIdpTokens;
 exports.storeIdpTokensInSession = storeIdpTokensInSession;
+exports.storePayezIdpSession = storePayezIdpSession;
 exports.expireSetCookies = expireSetCookies;
 exports.createAuthGetHandler = createAuthGetHandler;
 require("server-only");
@@ -68,6 +69,7 @@ const session_response_sanitizer_1 = require("./session-response-sanitizer");
 const magic_link_1 = require("better-auth/plugins/magic-link");
 const client_key_1 = require("../lib/client-key");
 const generic_oauth_1 = require("better-auth/plugins/generic-oauth");
+const idp_oauth_1 = require("./idp-oauth");
 const idp_client_config_1 = require("../lib/idp-client-config");
 const app_slug_1 = require("../lib/app-slug");
 const redis_1 = require("../lib/redis");
@@ -170,46 +172,38 @@ const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
 const gScope = globalThis;
 gScope[ID_TOKEN_SCOPE_KEY] ??= new node_async_hooks_1.AsyncLocalStorage();
 const idTokenScope = gScope[ID_TOKEN_SCOPE_KEY];
-/**
- * EXCHANGE-MOVE (175047): route OAuth through OUR IDP instead of holding
- * provider credentials in the app.
- *
- * ARCHITECTURE LOCKED (BAPert 21318): genericOAuth pointed at the IDP - NOT at
- * Google - which is simultaneously pkce + no-secret AND route-through-IDP, and
- * is uniform with the ratified desktop leg. The IDP holds the provider secret
- * and performs the provider exchange server-side.
- *
- * ── CUSTOM SHAPE, NEVER A PROVIDER PRESET ───────────────────────────────────
- * QAPert-NightHawk 21304: better-auth's provider-PRESET shape makes
- * clientSecret REQUIRED again. Same plugin, two config shapes, opposite answers
- * on whether we need a secret. This builds the generic/custom shape
- * deliberately; reaching for a preset because it looks tidier would silently
- * kill keyless-on-web and nobody would connect the two changes.
- *
- * ── OPT-IN, AND NOT A FALLBACK ──────────────────────────────────────────────
- * Returns null unless the IDP's OAuth endpoints are explicitly configured. That
- * makes this ADDITIVE: the existing socialProviders path keeps working until an
- * operator turns this on. It is NOT a runtime failover - nothing silently
- * chooses between them, because a silent chooser is how a migration ends up
- * half-applied and undetectable.
- *
- * ⚠ WHAT MUST MOVE TO THE IDP WITH THIS (flagged in 21317, not solvable here):
- * the app stops talking to Google, so it can no longer capture the raw
- * id_token that oauth-callback verifies today, and the per-provider settings
- * below stop being ours to set - profile scope, prompt=select_account,
- * accessType, and hd (hosted-domain, a SECURITY control). The IDP's own
- * exchange must verify signature/iss/aud/exp itself and preserve those four, or
- * they are lost silently.
- */
-function buildIdpOAuthProviderConfig() {
+function buildIdpOAuthProviderConfig(appBaseUrl) {
     const discoveryUrl = process.env.IDP_OAUTH_DISCOVERY_URL;
     const clientId = process.env.CLIENT_ID;
     if (!discoveryUrl || !clientId)
         return null;
+    const redirectURI = (0, idp_oauth_1.resolveIdpRedirectUri)(appBaseUrl || process.env.BETTER_AUTH_URL || process.env.APP_URL || `http://localhost:${process.env.PORT || '3000'}`);
+    const hooks = (0, idp_oauth_1.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'],
@@ -507,7 +501,7 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
         || idpConfig.baseClientUrl
         || `http://localhost:${process.env.PORT || '3000'}`;
     const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
-    const idpOAuth = buildIdpOAuthProviderConfig();
+    const idpOAuth = buildIdpOAuthProviderConfig(rawBaseURL);
     return (0, better_auth_1.betterAuth)({
         baseURL,
         secret: idpConfig.authSecret,
@@ -1286,6 +1280,33 @@ async function storeIdpTokensInSession(sessionToken, idpTokenData, authProvider)
  * Try again or use another method." The cause stays in the server log, never on the page.
  */
 exports.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.
+ */
+async function storePayezIdpSession(sessionToken) {
+    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).
  *
@@ -1451,7 +1472,11 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
                         if (session?.session?.token) {
                             sessionToken = session.session.token;
                             console.log('[BETTER_AUTH] Got session token from callback:', (0, token_log_id_1.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/dist/auth/idp-oauth.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 { 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;
+}
+/** The URI sent at authorize AND token time. Explicit env wins; else the registered {app}/api/auth/callback form. */
+export declare function resolveIdpRedirectUri(appBaseUrl: string, env?: NodeJS.ProcessEnv): string;
+/** amr arrives as an array, a JSON-array string, or a delimited string (Core's own reader accepts all three). */
+export declare function amrIncludesMfa(amr: unknown): boolean;
+/** Max skew accepted on nbf/exp/iat when verifying the IdP access token. */
+export declare 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 declare function isAddressShaped(v: unknown): v is string;
+/**
+ * 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 declare function resolveEmail(payload: Record<string, unknown>, responseEmail?: unknown): string;
+export declare function createIdpOAuthHooks(opts: IdpOAuthHookOptions): {
+    getToken: (data: {
+        code: string;
+        codeVerifier?: string;
+    }) => Promise<{
+        tokenType: any;
+        accessToken: any;
+        refreshToken: any;
+        accessTokenExpiresAt: Date | undefined;
+        scopes: string[];
+    }>;
+    getUserInfo: (tokens: {
+        accessToken?: string;
+    }) => Promise<{
+        id: string;
+        email: string;
+        name: string;
+        emailVerified: boolean;
+    } | null>;
+};