@payez/next-mvp 4.8.1 → 4.8.3

package/src/auth/better-auth.ts

@@ -1,1688 +1,1688 @@
-/**
- * Better Auth Configuration
- *
- * Primary auth configuration. Replaces the former NextAuth auth-options.ts.
- *
- * Architecture: No database adapter — Better Auth runs in stateless mode
- * with JWE cookie cache. User management stays on IDP, sessions on Redis.
- *
- * @see BETTER-AUTH-MIGRATION-SPEC.md
- */
-
-import 'server-only';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { createHash } from 'crypto';
-import { decodeJwt } from 'jose';   // better-auth's own JWT dependency
-import { betterAuth } from 'better-auth';
-import { nextCookies } from 'better-auth/next-js';
-import { toNextJsHandler } from 'better-auth/next-js';
-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';
-import { getRedis } from '../lib/redis';
-import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
-import { SESSION_TTL } from '../lib/session-store';
-import { tokenLogId } from '../lib/token-log-id';
-
-/**
- * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
- * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
- * = 48 bits; collision-tellable across a deployment, useless as a credential.
- */
-export function secretFingerprint(value: string): string {
-  return createHash('sha256').update(value).digest('hex').slice(0, 12);
-}
-
-/**
- * 273183: keys written onto the `ba:{slug}:{token}` record by an author OTHER
- * than Better Auth, which must survive a Better Auth session write.
- *
- * Today this is exactly `idpTokens`, written by `storeIdpTokensInSession`. The
- * list is a named constant rather than a hardcoded check because the shape of
- * the bug is "a second author appeared and the adapter did not know" — the next
- * enrichment key should be added here, not rediscovered as a strip.
- */
-const PRESERVED_SESSION_KEYS = ['idpTokens'] as const;
-
-/**
- * True for a JSON object we can safely merge into — not null, not an array.
- * `typeof null === 'object'` and arrays are objects, and merging into either
- * would corrupt the record rather than preserve it.
- */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * Better Auth social provider config shape.
- */
-export interface BetterAuthSocialProvider {
-  clientId: string;
-  clientSecret: string;
-  scope?: string[];
-  prompt?: string;
-  accessType?: 'offline' | 'online';
-  hd?: string;
-  /**
-   * 260419: better-auth's ONLY guard against OAuth auto-provisioning
-   * (oauth2/link-account.mjs handleOAuthUserInfo: `if (disableSignUp) return
-   * {error:"signup disabled"}`). Unset means ANY unknown Google identity gets a
-   * local account created at callback. We wire it from the tenant's own policy.
-   */
-  disableSignUp?: boolean;
-}
-
-/**
- * Build Better Auth social providers from IDP config.
- */
-/**
- * REQUEST-SCOPED carrier for the provider's raw id_token. Card 138635.
- *
- * WHY THIS EXISTS: /api/ExternalAuth/oauth-callback mints an IDP bearer for any
- * ASSERTED email — we send {provider, email} and nothing verifiable. The fix is
- * for the IDP to require a provider-signed id_token and verify it itself. This
- * is the client half: capture the token Better Auth already receives, and
- * forward it. Additive — the IDP ignores it until its gate flips.
- *
- * WHY AsyncLocalStorage AND NOT REDIS (BAPert's ruling: forward, do not persist):
- * an id_token is credential material. Writing it to the session record would put
- * it one allow-list edit away from leaking out of /api/internal/session-data,
- * and it would outlive the request that needed it. ALS scopes it to the single
- * request, and it is gone when the request ends — nothing to expire, nothing to
- * scrub, nothing to leak.
- *
- * SAFE BY CONSTRUCTION: getUserInfo (which fills this) and the post-callback
- * exchange (which reads it) both run inside createAuthGetHandler's own request.
- * VERIFIED, not assumed: better-auth.ts:452 awaits ba.GET(request) — the call
- * that invokes getUserInfo — and the exchange follows at :465 in the SAME
- * function. Outside that scope the store is undefined and the body simply omits
- * id_token, which is the correct additive behaviour.
- */
-/**
- * ON globalThis FOR THE SAME REASON THE BETTER AUTH INSTANCE IS (181814, see STATE_KEY
- * below) — and it was NOT, which is the whole defect.
- *
- * This module is loaded more than once per process: instrumentation and the auth route
- * are different chunks with their own module registries. `state` was moved to globalThis
- * so both copies share the Better Auth INSTANCE. This AsyncLocalStorage was left in
- * module scope, so each copy got its own.
- *
- * The result, measured on UMI 2026-08-26 against idp.payez.net:
- *
- *   copy A builds the instance   -> the getUserInfo closure captures A's idTokenScope
- *   copy B serves the callback   -> createAuthGetHandler runs .run({}) on B's
- *   getUserInfo fires, reads A   -> getStore() is undefined, `if (scope)` skips
- *   the exchange reads B         -> empty, so id_token is omitted from the body
- *
- * Sign-in SUCCEEDS at every visible step. The user gets a session, an avatar, an email.
- * The IDP then answers 401 UNVERIFIED_ASSERTION with reason="id_token missing"
- * (confirmed in its own logs, correlationId 0HNO2755RESR1) — so the client half of 138635
- * has been shipping as a no-op wherever the module double-loads, and the security fix it
- * exists to deliver never arrived. A shared instance plus a per-copy scope is the worst
- * combination: everything looks wired, and the one field that proves identity is dropped.
- *
- * globalThis is per-process and per-runtime, which is exactly the lifetime a request-scoped
- * carrier needs to be reachable from every copy that might run inside the request.
- */
-/**
- * THE KEY STAYS '__payezIdTokenScope' EVEN THOUGH THE SCOPE NOW CARRIES TWO
- * THINGS. Renaming it would give a copy on the old name and a copy on the new
- * name two DIFFERENT stores in the same process — which is precisely the
- * double-load failure documented above, reintroduced by a cosmetic rename. The
- * name is a wire contract between copies, not a description.
- *
- * accessToken is here for providers that do NOT issue an id_token. GitHub is
- * not an OIDC provider: it has no id_token, no JWKS and no discovery document,
- * so `id_token` can never be the field that proves a GitHub identity. The IDP
- * re-derives that identity by calling GitHub itself with this access token
- * (GitHubIdentityVerifier), which keeps the same rule google follows — the IDP
- * verifies for itself and never trusts an asserted email.
- */
-const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
-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
->;
-gScope[ID_TOKEN_SCOPE_KEY] ??= new AsyncLocalStorage<ProviderTokenScope>();
-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.
- */
-export interface IdpOAuthProviderConfig {
-  providerId: string;
-  discoveryUrl: string;
-  clientId: string;
-  pkce: true;
-  scopes: string[];
-  /** 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'],
-
-    /**
-     * ⚠ DO NOT ADD `authentication: 'basic'` HERE. IT SILENTLY BREAKS KEYLESS.
-     *
-     * Found by QAPert-NightHawk (21348) — the second config trap in this plugin
-     * after the preset one, and the same shape: a field that looks like a
-     * harmless transport detail and quietly changes whether we are a public
-     * client at all.
-     *
-     * @better-auth/core validate-authorization-code.mjs:
-     *     if (authentication === "basic") {
-     *       headers.authorization = `Basic ${base64(`${clientId}:${clientSecret ?? ""}`)}`;
-     *     } else {
-     *       body.set("client_id", clientId);
-     *       if (options.clientSecret) body.set("client_secret", options.clientSecret);
-     *     }
-     *
-     * Note what the 'basic' branch does with NO secret: it sends an EMPTY
-     * password, `Basic base64("<clientId>:")`. That is not "no authentication",
-     * it is WRONG authentication — we would be presenting ourselves as a
-     * confidential client with a blank credential. The default branch is the
-     * one that produces a genuine public-client PKCE request.
-     *
-     * Leaving this field UNSET is load-bearing, which is exactly why it needs a
-     * comment: nothing about an absent field advertises that its absence is a
-     * decision.
-     */
-  };
-}
-
-export function buildBetterAuthProviders(
-  config: IDPClientConfig
-): Record<string, BetterAuthSocialProvider> {
-  const providers: Record<string, BetterAuthSocialProvider> = {};
-
-  for (const oauth of config.oauthProviders || []) {
-    if (!oauth.enabled) continue;
-    const name = oauth.provider.toLowerCase();
-    const additionalParams = oauth.additionalParams ?? {};
-    const rawPrompt = additionalParams.prompt;
-    const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;
-    const rawHostedDomain = additionalParams.hd;
-
-    // Ensure profile scope is present for Google so avatar image is returned
-    const scopes = oauth.scopes?.split(' ') || [];
-    if (name === 'google' && !scopes.includes('profile')) {
-      scopes.push('profile');
-    }
-
-    /**
-     * 224721: better-auth's google provider UNCONDITIONALLY seeds its default
-     * scopes ['email','profile','openid'] and then pushes our `scope` verbatim
-     * (@better-auth/core social-providers/google.mjs createAuthorizationURL) —
-     * the row's "openid email profile" reached Google as
-     * "email profile openid openid email profile". Semantically harmless
-     * (Google dedupes) but sloppy on a URL a demo audience can read. Hand over
-     * only what the defaults do not already cover; undefined when nothing
-     * remains, so the provider emits exactly its default set.
-     */
-    const GOOGLE_DEFAULT_SCOPES = ['email', 'profile', 'openid'];
-    /**
-     * Same defect, same fix, different provider: github's createAuthorizationURL
-     * also seeds ['read:user','user:email'] unconditionally and then pushes ours
-     * on top (@better-auth/core social-providers/github.ts), so the stored row
-     * "read:user user:email" reached GitHub as
-     * "read:user user:email read:user user:email". Measured on :4799, not
-     * assumed. GitHub dedupes, so this is legibility rather than function — but
-     * a scope list is the first thing a security reviewer reads off that URL.
-     */
-    const GITHUB_DEFAULT_SCOPES = ['read:user', 'user:email'];
-    const wireScopes =
-      name === 'google'
-        ? scopes.filter((s) => !GOOGLE_DEFAULT_SCOPES.includes(s))
-        : name === 'github'
-          ? scopes.filter((s) => !GITHUB_DEFAULT_SCOPES.includes(s))
-          : scopes;
-
-    providers[name] = {
-      clientId: oauth.clientId,
-      clientSecret: oauth.clientSecret,
-      scope: wireScopes.length > 0 ? wireScopes : undefined,
-      /**
-       * PAY-2005 — DISABLE-SIGN-UP IS REMOVED, DELIBERATELY. DO NOT RE-ADD IT.
-       *
-       * 260419 wired this from `config.authSettings?.allowPublicRegistration` to
-       * close a client-side self-serve provisioning door. It cannot do that job
-       * correctly, and it BREAKS SIGN-IN:
-       *
-       *   - This app runs better-auth in STATELESS mode (no DB adapter — see the
-       *     file header). better-auth therefore has NO user store, so at the OAuth
-       *     callback it cannot tell an EXISTING user from a NEW one. Its
-       *     handleOAuthUserInfo consults `disableSignUp` for BOTH, so
-       *     `disableSignUp: true` refuses a returning user exactly like a
-       *     stranger. Measured live 2026-09-30 (PAY-2005): portal.keelauth.com
-       *     Google sign-in bounced to /sign-in with Better Auth `signup_disabled`
-       *     once client 12's allow_public_registration reported false.
-       *
-       *   - The REAL registration gate already exists and is correct, at the IDP:
-       *     PayEz.External.Id.Api ExternalAuthController.oauth-callback looks the
-       *     user up by verified email (:799); an existing user logs in UNTOUCHED
-       *     (:811); only the isNewUser branch (:853) calls INewUserRegistrar,
-       *     which refuses fail-closed when the client forbids public registration
-       *     (NewUserRegistrar.cs:65, `SecurityFlags.AllowPublicRegistration != true`).
-       *     Its own comment states the contract: "existing federated users ...
-       *     log in untouched, so gating here never blocks login."
-       *
-       * So this flag was a DUPLICATE gate that could only ever misfire — it cannot
-       * distinguish new from existing, and the IDP already refuses new identities.
-       * Removing it restores sign-in for existing users WITHOUT reopening
-       * self-serve: a NEW identity that completes the better-auth leg still gets
-       * REFUSED at the IDP exchange and never receives IDP tokens, which is the
-       * portal's actual authorization gate.
-       *
-       * WHERE "no self-serve sign-up" IS ENFORCED NOW: the IDP's NewUserRegistrar
-       * (above) as the backstop, and each app's own front-door sign-up gate
-       * (e.g. the portal's signup-gate.ts / SignUpCard) for the UI affordance.
-       * Both are correct and neither is this flag.
-       */
-      // Google is overly eager to reuse the last account unless we
-      // explicitly ask for account selection on each social login.
-      prompt: typeof rawPrompt === 'string'
-        ? rawPrompt
-        : name === 'google'
-          ? 'select_account'
-          : undefined,
-      accessType: rawAccessType === 'online' ? 'online' : rawAccessType === 'offline' ? 'offline' : undefined,
-      hd: typeof rawHostedDomain === 'string' ? rawHostedDomain : undefined,
-    };
-
-    /**
-     * CAPTURE THE RAW id_token — card 138635, client half.
-     *
-     * getUserInfo is the ONLY provider hook that receives the token set.
-     * mapProfileToUser cannot do this: it is handed the DECODED claims, and a
-     * signed JWT cannot be reconstructed from them. We need the raw token
-     * because the IDP must verify the signature ITSELF — a client-decoded
-     * claim is just another assertable field, which is the defect restated.
-     *
-     * ⚠ THIS REPLACES THE DEFAULT google getUserInfo ENTIRELY. Upstream calls
-     * `if (options.getUserInfo) return options.getUserInfo(token)` FIRST and
-     * returns our result verbatim, so everything the default did is now ours to
-     * do — including the `hd` hosted-domain restriction.
-     *
-     * `hd` IS NOT HYPOTHETICAL: it is wired from additionalParams.hd four lines
-     * above, so a client can restrict sign-in to a Google Workspace domain.
-     * Silently dropping it would let ANY Google account into a client that had
-     * restricted itself — a security regression introduced by a security fix.
-     * (Measured on 93: zero clients set it today. That is a reason to be
-     * careful, not a reason to skip it — it is configurable and unused, which
-     * is exactly the state in which a regression goes unnoticed.)
-     *
-     * SO WE DO NOT OVERRIDE AT ALL WHEN `hd` IS SET. We take the hook over
-     * ONLY where upstream's check is PROVABLY VACUOUS — its own first line is
-     * `if (!configuredHostedDomain) return true`. With no hd configured the
-     * default would return true unconditionally, so omitting it is equivalent
-     * by the library's own definition rather than by our judgement.
-     *
-     * A client that DOES set hd keeps the stock provider, keeps its domain
-     * restriction, and simply does not contribute an id_token yet. Losing a
-     * capability is an acceptable cost; silently losing a security control is
-     * not. (better-auth does not re-export the predicate through its public
-     * types, and reimplementing a security check is how two copies drift — so
-     * the honest move is to not need it.)
-     */
-    if (name === 'google' && !providers[name].hd) {
-      (providers[name] as unknown as Record<string, unknown>).getUserInfo = async (token: { idToken?: string }) => {
-        if (!token?.idToken) return null;
-
-        // The only new behaviour: hand the raw token to this request's scope.
-        const scope = idTokenScope.getStore();
-        if (scope) {
-          scope.idToken = token.idToken;
-        } else {
-          // NOT a silent skip. A missing scope here means 138635 degrades to a no-op:
-          // the login still succeeds, and the IDP rejects the exchange with
-          // reason="id_token missing" a second later, with nothing connecting the two.
-          // That cost a day on UMI. If this fires, the OAuth callback is running outside
-          // createAuthGetHandler — either the route mounts the bare
-          // `routes/auth/nextauth` re-export instead of createAuthGetHandler, or this
-          // module has double-loaded and the scope is not shared (see 181814 above).
-          console.warn(
-            '[BETTER_AUTH] id_token captured but NO REQUEST SCOPE to put it in — it will ' +
-              'NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
-              'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.',
-          );
-        }
-
-        // Mirrors the upstream default (google.mjs) verbatim, minus the hd
-        // branch that cannot fire here — so overriding the hook changes WHAT WE
-        // KEEP, never what we ACCEPT.
-        const claims = decodeJwt(token.idToken) as Record<string, any>;
-        return {
-          user: {
-            id: claims.sub,
-            name: claims.name,
-            email: claims.email,
-            image: claims.picture,
-            emailVerified: claims.email_verified,
-          },
-          data: claims,
-        };
-      };
-    }
-
-    /**
-     * GITHUB: THE SAME CAPTURE, A DIFFERENT TOKEN.
-     *
-     * GitHub is not an OIDC provider — it issues no id_token — so the google
-     * branch above can never fire for it and the exchange would post an
-     * assertion with nothing that proves identity. That is exactly the
-     * 401 UNVERIFIED_ASSERTION measured on :4799, whose diagnostics read
-     * `id_token_forwarded: false, id_token_length: 0` with `response_time_ms: 0`:
-     * the IDP rejected it instantly, without ever calling GitHub.
-     *
-     * getUserInfo is the ONLY provider hook that receives the token set (see the
-     * google note above), and @better-auth/core's github provider calls
-     * `options.getUserInfo(token)` BEFORE its own body — so installing this
-     * REPLACES the default rather than wrapping it, and the default's work has
-     * to be reproduced here or the sign-in loses its profile entirely.
-     *
-     * Mirrored verbatim from @better-auth/core/src/social-providers/github.ts at
-     * the version the container actually runs (better-auth 1.5.6 — the graft's
-     * node_modules says 1.6.29 and is NOT what executes). Kept deliberately
-     * dumb: it must not "improve" on upstream, because every divergence here is
-     * a behaviour change disguised as a token capture.
-     *
-     * This is NOT the identity check. The IDP re-derives the GitHub identity
-     * itself from this access token and enforces primary && verified server-side
-     * (GitHubIdentityVerifier); what we return here only shapes the local
-     * better-auth user record.
-     */
-    if (name === 'github') {
-      (providers[name] as unknown as Record<string, unknown>).getUserInfo = async (token: {
-        accessToken?: string;
-      }) => {
-        const store = idTokenScope.getStore();
-        if (store) {
-          store.accessToken = token?.accessToken;
-        } else {
-          console.warn(
-            '[BETTER_AUTH] github access_token captured but NO REQUEST SCOPE to put it in — ' +
-              'it will NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
-              'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.',
-          );
-        }
-
-        const ghHeaders = {
-          'User-Agent': 'better-auth',
-          Authorization: `Bearer ${token?.accessToken}`,
-        };
-
-        const profileRes = await fetch('https://api.github.com/user', {
-          headers: ghHeaders,
-        });
-        // Upstream returns null on profile error, which fails the sign-in
-        // closed. Preserved rather than softened.
-        if (!profileRes.ok) {
-          console.warn(
-            `[BETTER_AUTH] github getUserInfo: /user returned ${profileRes.status}`,
-          );
-          return null;
-        }
-        const profile = (await profileRes.json()) as Record<string, any>;
-
-        const emailsRes = await fetch('https://api.github.com/user/emails', {
-          headers: ghHeaders,
-        });
-        const emails = emailsRes.ok
-          ? ((await emailsRes.json()) as Array<{
-              email: string;
-              primary: boolean;
-              verified: boolean;
-            }>)
-          : undefined;
-
-        // A GitHub account with a private email returns profile.email = null;
-        // upstream falls back to the primary address here.
-        if (!profile.email && emails) {
-          profile.email = (emails.find((e) => e.primary) ?? emails[0])?.email;
-        }
-        const emailVerified =
-          emails?.find((e) => e.email === profile.email)?.verified ?? false;
-
-        return {
-          user: {
-            id: profile.id,
-            name: profile.name || profile.login || '',
-            email: profile.email,
-            image: profile.avatar_url,
-            emailVerified,
-          },
-          data: profile,
-        };
-      };
-    }
-  }
-
-  return providers;
-}
-
-/**
- * Optional configuration for `createBetterAuthInstance`.
- *
- * - `magicLink`: if provided, registers Better Auth's magic-link plugin.
- *   The host app supplies its own `sendMagicLink` callback — typically a
- *   fetch to its email service (e.g. ACP's `/v1/auth/magic-link/email`).
- *   Omit the `magicLink` key entirely to skip the plugin; the consuming
- *   app will not have a magic-link flow.
- */
-export interface CreateBetterAuthInstanceOptions {
-  magicLink?: MagicLinkOptions;
-  /**
-   * Extra Better Auth plugins supplied by the consuming app.
-   *
-   * WHY THIS EXISTS — session minting is not delegable any other way. BA's
-   * `setSessionCookie` requires a `GenericEndpointContext`, which only BA's own
-   * endpoint machinery constructs, so an app that must mint a session for an
-   * identity established OUTSIDE BA's built-in providers (passkey sign-in being
-   * the first) cannot do it from a route handler. It needs a real BA endpoint,
-   * and endpoints only arrive via plugins.
-   *
-   * Deliberately GENERIC. The package gains "an app may supply plugins" rather
-   * than any knowledge of passkeys — the alternative was teaching this file
-   * about a specific auth method, which is how a package accumulates a consumer's
-   * feature list.
-   *
-   * The alternative to this option is an app hand-rolling the session cookie
-   * (`{token}.{base64(hmac)}`, standard padding, runtime `authSecret` from
-   * Redis). That fails as a session which DECODES BUT DOES NOT AUTHENTICATE —
-   * so this option exists specifically to make that shortcut unnecessary.
-   */
-  plugins?: Parameters<typeof betterAuth>[0]['plugins'];
-}
-
-/**
- * Create Better Auth instance from IDP config.
- *
- * No database — runs in stateless mode with JWE cookie cache.
- * Call after getIDPClientConfig() resolves.
- */
-export function createBetterAuthInstance(
-  idpConfig: IDPClientConfig,
-  opts: CreateBetterAuthInstanceOptions = {}
-) {
-  assertAppSlugMatchesIdp(idpConfig.clientSlug);
-  const appSlug = idpConfig.clientSlug || getAppSlug();
-
-  // 185121 line 1: name the secret this instance PINNED, as a hash, never the
-  // secret. 183047's surviving fork is HMAC-fail vs record-miss; an HMAC-fail
-  // caused by a divergent secret is only diagnosable if every instance
-  // creation logged WHICH secret it bound. Both init paths (this module's
-  // getBetterAuthInstance and server/auth.ts getAuthInstance) funnel through
-  // here, so this one line covers both; getAuthInstance adds its own line
-  // naming the path, because it previously created an instance INVISIBLY.
-  console.log(
-    `[BETTER_AUTH] createBetterAuthInstance: slug=${appSlug} authSecret ${idpConfig.authSecret ? `sha256:${secretFingerprint(idpConfig.authSecret as string)}` : 'ABSENT'}`
-  );
-
-  // Resolve base URL: BETTER_AUTH_URL env > IDP config > localhost fallback
-  // Must include /api/auth since that's where the catch-all route is mounted
-  const rawBaseURL = process.env.BETTER_AUTH_URL
-    || idpConfig.baseClientUrl
-    || `http://localhost:${process.env.PORT || '3000'}`;
-  const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
-
-  const idpOAuth = buildIdpOAuthProviderConfig(rawBaseURL);
-
-  return betterAuth({
-    baseURL,
-    secret: idpConfig.authSecret as string,
-
-    socialProviders: buildBetterAuthProviders(idpConfig),
-
-    // Trust the app's own origin + any configured base URL
-    trustedOrigins: [
-      rawBaseURL,
-      baseURL,
-      ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
-      // MEASURED 2026-08-26: this list ended with the literals localhost:3000, :3400
-      // and :3600. payez_idp_admin_web runs on :3200 - correctly configured, with
-      // BETTER_AUTH_URL=http://localhost:3200 - and every GET /api/auth/get-session
-      // returned 400, because the port it actually runs on was not one of the three
-      // someone had typed in. A config-shaped constant is not configuration.
-      //
-      // The app's own origin is already covered by rawBaseURL/baseURL above; the dev
-      // origin is DERIVED from PORT, and anything genuinely external comes from
-      // BETTER_AUTH_TRUSTED_ORIGINS (comma-separated).
-      `http://localhost:${process.env.PORT || '3000'}`,
-      ...(process.env.BETTER_AUTH_TRUSTED_ORIGINS
-        ? process.env.BETTER_AUTH_TRUSTED_ORIGINS.split(',').map((o) => o.trim()).filter(Boolean)
-        : []),
-    ],
-
-    // Redis-backed session storage via secondaryStorage
-    secondaryStorage: {
-      /**
-       * 170033 (QAPert 22654, load-bearing precondition for 183483): DO NOT
-       * swallow a Redis failure into `null` here.
-       *
-       * `null` from `get` is Better Auth's OWN signal for "no session at this
-       * key" (see node_modules/better-auth db/internal-adapter.mjs
-       * `findSession`: `if (!sessionStringified ...) return null`). Catching
-       * a Redis error and returning `null` therefore told better-auth "this
-       * session does not exist" when the true state was "the store could not
-       * be asked" — indistinguishable from a genuine sign-out. With
-       * `cookieCache` disabled (session.cookieCache.enabled above), EVERY
-       * `getSession()` call hits this path for real, so a Redis blip
-       * manufactured a `200 { session: null }` for every live session at
-       * once — the exact channel 183483's client-side guard (verify-code
-       * page's session-liveness check) was built to survive, and the one it
-       * could not survive while this swallow stood: a fabricated "no
-       * session" 200 is not distinguishable from a real one by any client.
-       *
-       * Letting the error propagate is safe: better-auth's own router
-       * (better-call/dist/router.mjs) wraps every endpoint handler in a
-       * top-level try/catch and converts an uncaught throw to a genuine
-       * `500`, not a crash. A `500` IS the "inconclusive" signal 183483's
-       * corrected client guard already knows how to hold a session through —
-       * so a Redis outage now surfaces as "couldn't check" instead of
-       * silently lying "confirmed logged out".
-       */
-      get: async (key: string) => {
-        const value = await getRedis().get(`ba:${appSlug}:${key}`);
-        // 185121 line 2: the 183047 discriminator. A null here means
-        // RECORD-MISS — the store was reachable and the key is absent. If the
-        // record IS present but BA still rejects the session, this line does
-        // NOT fire and the failure is upstream of storage (HMAC/secret gate).
-        // BA-primary logs nothing on failure, so without this line the two
-        // surviving forks are indistinguishable in the artifact. Key is
-        // fingerprinted: it embeds the session token.
-        if (value === null) {
-          console.warn(
-            `[BETTER_AUTH] secondaryStorage.get MISS ba:${appSlug}:sha256:${secretFingerprint(key)} — record absent, store reachable`
-          );
-        }
-        return value;
-      },
-      /**
-       * 170033 fix 1 — DO NOT SWALLOW A FAILED WRITE. A SESSION THAT WAS NOT
-       * PERSISTED IS NOT A SESSION.
-       *
-       * This previously caught every Redis error and returned normally, so
-       * better-auth was told the session had been stored when nothing had been
-       * written. The user got a successful login, a session cookie, and a
-       * rendered signed-in shell on top of a store that holds no session — and
-       * the very next `getSession()` reads `null` and signs them straight back
-       * out. Nothing logged, nothing thrown, no banner: a login that "worked"
-       * and a sign-out nobody can explain.
-       *
-       * Letting it propagate is the same contract `get` above already relies on:
-       * better-auth's router (better-call/dist/router.mjs) wraps every endpoint
-       * handler and converts an uncaught throw into a genuine 500. A 500 on the
-       * login write is honest — "we could not store your session" — and it is
-       * distinguishable by any client from a successful login, which a swallowed
-       * failure is not.
-       *
-       * THE COMMENT THIS REPLACES SAID "Redis unavailable — cookie cache still
-       * works". It does not: `session.cookieCache.enabled` is FALSE (see below).
-       * The comment described a safety net that had been removed, which is why
-       * this swallow looked survivable to every reader who trusted it (170033
-       * fix 3).
-       */
-      set: async (key: string, value: string, ttl?: number) => {
-        const redis = getRedis();
-        const redisKey = `ba:${appSlug}:${key}`;
-
-        /**
-         * 273183 — READ-MODIFY-WRITE, BECAUSE THIS RECORD HAS TWO AUTHORS.
-         * (Found by DotNetPert-Scout; handed over as Cluster-B root-cause
-         * evidence under BAPert's R920(a). Reproduced here before fixing.)
-         *
-         * Better Auth owns `{session, user}` and serialises exactly that. But
-         * `storeIdpTokensInSession` (below, ~:1010) ENRICHES the same key with
-         * `idpTokens` via its own read-modify-write. This setter did a blind
-         * `setex` of Better Auth's payload, so every write it makes — including
-         * each routine `updateAge` session rewrite, not merely an expiry —
-         * STRIPPED `idpTokens` back off the record.
-         *
-         * The consumer then falls back to an identity husk: `mfaVerified:false`,
-         * `roles:[]`. It fails CLOSED, so it is not a 369782-class bypass — but
-         * per BAPert it is a public-test blocker on its own terms, because a
-         * tester who trips the `updateAge` cadence gets a spurious 2FA re-prompt
-         * AND SILENTLY LOSES THEIR ROLES mid-session. That is a visible product
-         * failure regardless of which direction it fails in.
-         *
-         * WHY MERGE HERE RATHER THAN MOVE THE DATA. The enriching writer already
-         * does a read-modify-write; it was correct. The bug is that ONE of the
-         * two authors of this key wrote as though it were the only one. Fixing
-         * the adapter fixes it for every future enrichment key, whereas moving
-         * `idpTokens` elsewhere would leave the next one to rediscover this.
-         *
-         * ONLY keys in PRESERVED_KEYS are carried, and ONLY when the incoming
-         * payload does not set them — so Better Auth still wins on everything it
-         * owns, and an explicit incoming value is never overridden by a stale one.
-         *
-         * NOT ATOMIC, and deliberately not: an enrichment landing between this
-         * read and this write is still lost. Closing that needs a WATCH/MULTI or
-         * a Lua script, which is a larger change than tonight allows. This
-         * narrows the window from "every single write" to "a genuine race", and
-         * the residual is recorded here rather than left to be re-found.
-         */
-        let payload = value;
-        try {
-          const existingRaw = await redis.get(redisKey);
-          if (existingRaw) {
-            const existing = JSON.parse(existingRaw);
-            const incoming = JSON.parse(value);
-            if (isPlainObject(existing) && isPlainObject(incoming)) {
-              let carried = false;
-              for (const preserved of PRESERVED_SESSION_KEYS) {
-                if (preserved in existing && !(preserved in incoming)) {
-                  incoming[preserved] = existing[preserved];
-                  carried = true;
-                }
-              }
-              if (carried) payload = JSON.stringify(incoming);
-            }
-          }
-        } catch (mergeErr) {
-          /**
-           * This adapter also stores `verification:*` and `active-sessions-*`
-           * records, which are not necessarily session-shaped JSON. A record we
-           * cannot parse is not a session to enrich, so writing through unchanged
-           * is correct rather than merely tolerable.
-           *
-           * WARNED, NOT THROWN, and the asymmetry is the point: this block is an
-           * ENRICHMENT-PRESERVING read. Letting it fail the write would convert a
-           * degraded read into a lost session — the precise inversion 170033 fix 1
-           * above exists to prevent. The `setex` below is outside this try and is
-           * still unswallowed, so a genuine write failure still propagates.
-           */
-          console.warn(
-            `[BETTER_AUTH] secondaryStorage.set: could not preserve enrichment keys on ` +
-            `ba:${appSlug}:sha256:${secretFingerprint(key)} — writing Better Auth's payload ` +
-            `as-is. If this record held idpTokens they are now gone (273183):`,
-            mergeErr instanceof Error ? mergeErr.message : String(mergeErr)
-          );
-        }
-
-        /**
-         * QA 6952 / R913 - CLAMP, DO NOT DEFER.
-         *
-         * This was `ttl ?? SESSION_TTL`, which READS as "SESSION_TTL is the single
-         * source of session TTL" - what session-store.ts claims, and the mechanism
-         * by which the 7d-vs-3d zombie window was supposedly closed for good.
-         *
-         * IT WAS DEAD CODE. Better Auth ALWAYS supplies a ttl: every one of the
-         * eight secondaryStorage.set call sites in
-         * better-auth/dist/db/internal-adapter.mjs passes one explicitly (:36,
-         * :180, :189, :309, :320, :344, :553, :622). `??` fires only on
-         * null/undefined, so the fallback NEVER RAN. Every `ba:` record took Better
-         * Auth's 7d default - `session.expiresIn` is not configured in this file -
-         * while the canonical store stayed at SESSION_TTL (3d). That 4-day drift IS
-         * the zombie window the constant exists to prevent: the guard was bypassed
-         * by the very parameter written to defer to it.
-         *
-         * `Math.min`, NOT a hard SESSION_TTL: this same adapter also stores
-         * `verification:*` (:553, :622) and `active-sessions-*` (:180, :320, :344)
-         * records whose TTLs are legitimately SHORTER than 3d. Overwriting those
-         * would EXTEND them - turning a fix for over-long sessions into a bug that
-         * keeps verification codes alive for three days. Clamp DOWN, never up.
-         *
-         * Clamped down to 3d rather than raising the canonical store to 7d because
-         * SESSION_TTL matches the IDP refresh-token lifetime: a session outliving
-         * the refresh token sustaining it cannot be refreshed, so the extra days are
-         * a husk that reads as authenticated. Fail-closed beats ambiguous.
-         *
-         * DO NOT "fix" this by making storeIdpTokensInSession preserve Better
-         * Auth's 7d. That deletes the last remnant of QA 6952 and makes the drift
-         * universal. See test/ba-session-ttl-clamp.test.cjs.
-         */
-        await redis.setex(redisKey, Math.min(ttl ?? SESSION_TTL, SESSION_TTL), payload);
-      },
-      delete: async (key: string) => {
-        try {
-          await getRedis().del(`ba:${appSlug}:${key}`);
-        } catch (err) {
-          /**
-           * 170033 fix 2 — a failed delete must be VISIBLE, not `/* ignore *\/`.
-           *
-           * Deliberately logged rather than thrown, and the distinction is not
-           * timidity: the CANONICAL store is what decides session liveness (see
-           * 181922 below), and its delete runs immediately after this one and is
-           * NOT swallowed. So a BA record that outlives its canonical twin does
-           * not authenticate anyone — throwing here would fail a sign-out that
-           * actually succeeded where it counts.
-           *
-           * What was unacceptable is that it happened SILENTLY. A revocation
-           * that half-failed left no trace anywhere, so the leftover key could
-           * only ever be found by someone already reading the keyspace for
-           * another reason. `error`, not `warn`: this is a revocation that did
-           * not complete, not a retryable blip.
-           */
-          console.error(
-            `[BETTER_AUTH] secondary delete FAILED for ba:${appSlug}:${key} — ` +
-            `the better-auth session record may still exist. Canonical delete ` +
-            `below is what governs liveness; if it also failed, the session is ` +
-            `NOT revoked:`,
-            err
-          );
-        }
-        /**
-         * 181922 — teardown is BOTH stores. BA's sign-out deletes only its
-         * secondary record; the canonical {slug}:sess:{token} would survive
-         * and keep the session alive (a replayed cookie still authenticates).
-         * `key` here IS the session token (the ba: prefix is applied above),
-         * so the canonical delete is one call. This also fires on session
-         * rotation/expiry deletions, which is correct: a session BA drops
-         * must not live on in the canonical store.
-         */
-        try {
-          const { deleteSession } = await import('../lib/session-store');
-          await deleteSession(key);
-        } catch (err) {
-          console.warn('[BETTER_AUTH] secondary delete: canonical store cleanup failed:', err);
-        }
-      },
-    },
-
-    session: {
-      // Cookie cache DISABLED — Redis is canonical for session liveness.
-      //
-      // Previously: enabled with maxAge 300 + refreshCache false. That cached
-      // a decoded session in process memory for 5 minutes, bypassing Redis
-      // reads during the window. Consequence: if the canonical app session
-      // at `{slug}:{token}` was evicted, refreshed, or rotated mid-window,
-      // Better Auth's in-memory copy stayed alive — and callers got
-      // contradictory answers depending on whether they consulted Better
-      // Auth (alive per cache) or Redis (dead/rotated). Documented contradiction
-      // visible in production traces: viability 200 + idp-token 200 +
-      // getFreshIdpToken NO_SESSION terminal within milliseconds.
-      //
-      // Trade-off: every Better Auth getSession() call now incurs one Redis
-      // read on the secondary-storage path. Latency cost is acceptable
-      // (sub-ms in-region) and the alternative is duplicate Layer-1
-      // workarounds in every consumer app — already shipped in idealvibe.online
-      // at b6a91f6.
-      cookieCache: {
-        enabled: false,
-        maxAge: 300,
-        refreshCache: false,
-      },
-    },
-
-    // PAY-1781 B: KEEP OAUTH STATE IN THE ENCRYPTED COOKIE, as it was on better-auth 1.5.6.
-    // 1.5.6 resolved the default as `options.database ? 'database' : 'cookie'` - we have no
-    // database, so: cookie. 1.6.13+ resolves it as `(database || secondaryStorage) ? 'database'
-    // : 'cookie'`, and we DO have secondaryStorage, so the upgrade alone would silently move every
-    // OAuth state record into Redis through the adapter above (its enrichment read-modify-write
-    // and key handling were built for session records, not state). Pinned so the upgrade changes
-    // the version, not the design. The cookie branch is where GHSA-wxw3-q3m9-c3jr lived; 1.6.2+
-    // compares the returned `state` with the nonce sealed in the cookie, and our provider is also
-    // pkce:true, which the advisory required to be false. Test: oauth-state-strategy-cookie.
-    account: {
-      storeStateStrategy: 'cookie',
-    },
-
-    // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
-    advanced: {
-      cookiePrefix: appSlug,
-      cookies: {
-        session_token: {
-          name: `${appSlug}.session-token`,
-        },
-      },
-    },
-
-    plugins: [
-      nextCookies(),
-      // Exchange-move: present ONLY when the IDP's OAuth endpoints are
-      // configured. Absent otherwise, so this cannot alter existing behaviour.
-      ...(idpOAuth ? [genericOAuth({ config: [idpOAuth] })] : []),
-      ...(opts.magicLink ? [magicLink(opts.magicLink)] : []),
-      // App-supplied plugins last: they may depend on the built-ins above, and
-      // ordering is BA's own concern once they are in the array.
-      ...(opts.plugins ?? []),
-    ],
-  });
-}
-
-/**
- * Better Auth is always enabled (NextAuth removed in 4.0).
- */
-export function isBetterAuthEnabled(): boolean {
-  return true;
-}
-
-/**
- * Get Better Auth Next.js route handlers (GET, POST).
- * Initializes Better Auth from IDP config on first call, caches the instance.
- *
- * STATE LIVES ON globalThis, NOT IN MODULE SCOPE (181814, measured 2026-08-07):
- * under Turbopack, instrumentation.ts and the /api/auth/[...all] route are
- * different chunks and each loads its OWN copy of this module. Module-level
- * `configuredOpts` set by configureBetterAuth() in instrumentation never
- * reached the copy getBetterAuthInstance() read in the route — measured
- * identity probe: sameInstance=false, route-side plugins=["next-cookies"]
- * while the instrumentation-side instance carried every configured plugin.
- * No throw anywhere (the double-init guard never sees the other copy), core
- * auth green, plugin routes 404. globalThis is per-process, per-runtime —
- * exactly the scope this state must have.
- */
-interface BetterAuthModuleState {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  cachedInstance: any;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  initPromise: Promise<any> | null;
-  // PAY-642: the init attempt, single-flighted so a REJECTED attempt clears itself (see getBetterAuthInstance).
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  initFlight?: SingleFlight<any>;
-  configuredOpts: CreateBetterAuthInstanceOptions;
-}
-
-const STATE_KEY = '__payezBetterAuthState';
-const g = globalThis as unknown as Record<string, BetterAuthModuleState | undefined>;
-g[STATE_KEY] ??= { cachedInstance: null, initPromise: null, configuredOpts: {} };
-const state = g[STATE_KEY];
-
-// Expose for server-side session access (decode-session.ts). A getter so the
-// export tracks the SHARED state, not a chunk-local snapshot.
-export function __getBetterAuthInstance(): unknown {
-  return state.cachedInstance;
-}
-
-/**
- * Configure Better Auth instance options for this process.
- *
- * Must be called before the first auth request — before
- * `getBetterAuthInstance()` caches an instance. Typically called once at
- * app startup, e.g. from Next.js `instrumentation.ts` or an equivalent
- * server bootstrap hook.
- *
- * Throws if called after the instance has already been resolved: options
- * cannot be applied retroactively.
- */
-export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void {
-  if (state.cachedInstance) {
-    throw new Error(
-      '[BETTER_AUTH] configureBetterAuth() must run before the instance is first resolved. ' +
-      'Call it in Next.js instrumentation.ts or an equivalent startup hook.'
-    );
-  }
-  state.configuredOpts = opts;
-}
-
-/**
- * PAY-642 (card 338215): the init attempt no longer LATCHES A FAILURE.
- *
- * This used to be `state.initPromise ??= getIDPClientConfig(true).then(...)` with no .catch and no reset. One
- * auth request against a cold process while the IdP was unreachable stored a rejected promise, and every later
- * caller replayed it until the process restarted, even after the IdP recovered. This funnel backs every
- * /api/auth/* route, the login GET handler and withAuth. server/auth.ts getAuthInstance() already used
- * createSingleFlight for this exact bug; this sibling funnel was missed.
- *
- * Now the attempt runs through the same helper: concurrent callers share one attempt, a failure still rejects
- * for every caller of THAT attempt (loud), the next call starts a fresh attempt, and a success is cached in
- * state.cachedInstance as before. The flight lives on the globalThis state for the same reason the instance
- * does (duplicated route chunks must share one init).
- */
-export async function getBetterAuthInstance() {
-  if (state.cachedInstance) return state.cachedInstance;
-
-  state.initFlight ??= createSingleFlight(() =>
-    getIDPClientConfig(true).then(config => {
-      const instance = createBetterAuthInstance(config, state.configuredOpts);
-      state.cachedInstance = instance;
-      console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
-      return instance;
-    })
-  );
-
-  const attempt = state.initFlight.get();
-  // Kept for callers that inspect it; it always points at the CURRENT attempt, never a settled failure.
-  state.initPromise = attempt;
-  return attempt;
-}
-
-/**
- * Get flag-gated auth handler for Next.js route.
- *
- * When USE_BETTER_AUTH=true, returns Better Auth handlers.
- * Otherwise returns null (auth disabled).
- *
- * Usage in host app route:
- * ```ts
- * import { getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
- *
- * export async function GET(req: Request) {
- *   const ba = await getBetterAuthHandler();
- *   if (ba) return ba.GET(req);
- * }
- * ```
- */
-export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> } | null> {
-  if (!isBetterAuthEnabled()) return null;
-
-  const auth = await getBetterAuthInstance();
-  // PAY-2217: Better Auth's native endpoints (get-session, list-sessions, sign-in/*, sign-up/*) put the session
-  // token in the body. Strip it at the HTTP boundary here, so every consumer that mounts this handler gets it;
-  // auth.api (server-side) is untouched and still sees the token. See session-response-sanitizer.ts.
-  return wrapBetterAuthHandler(auth as any, toNextJsHandler(auth));
-}
-
-/**
- * Exchange OAuth identity for IDP tokens and store in the BA Redis session.
- *
- * Call this from the OAuth callback route AFTER better-auth has processed the
- * callback and created the session. Reads the session token from the Set-Cookie
- * header of the response to find the BA Redis key.
- *
- * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
- *
- * RETURNS the IdP's own error code on an IDP refusal, or null otherwise
- * (PAY-2005 scenario (b), BAPert ruling 67897). It used to return a bare
- * boolean, so `REGISTRATION_NOT_ALLOWED` was indistinguishable from a network
- * blip and every cause collapsed to one generic login-page code — a NEW user
- * refused registration bounced silently, which is the failure Jon named.
- */
-export async function exchangeOAuthForIdpTokens(
-  sessionToken: string,
-  provider: string = 'google'
-): Promise<boolean | string> {
-  try {
-    const config = await getIDPClientConfig();
-    const appSlug = config.clientSlug || getAppSlug();
-    const baKey = `ba:${appSlug}:${sessionToken}`;
-
-    // Read the BA session from Redis
-    const baRaw = await getRedis().get(baKey).catch(() => null);
-    if (!baRaw) {
-      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', tokenLogId(sessionToken));
-      return false;
-    }
-
-    const baData = JSON.parse(baRaw);
-    const email = baData?.user?.email;
-    const name = baData?.user?.name;
-    const image = baData?.user?.image;
-    const baUserId = baData?.session?.userId || baData?.user?.id;
-
-    if (!email) {
-      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: no email in session');
-      return false;
-    }
-
-    // Call IDP oauth-callback
-    const idpUrl = process.env.IDP_URL || '';
-    if (!idpUrl) {
-      console.warn('[BETTER_AUTH] No IDP_URL configured, skipping token exchange');
-      return false;
-    }
-
-    console.log('[BETTER_AUTH] Exchanging OAuth identity for IDP tokens:', email);
-
-    const oauthRes = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        provider,
-        provider_account_id: email,  // Cross-System Identity Standard v1.1: always use verified email, never opaque session IDs
-        email,
-        name,
-        image,
-        client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? '',
-        /**
-         * Card 138635 — the RAW provider id_token, forwarded verbatim.
-         *
-         * Every other field in this body is an ASSERTION. The endpoint mints an
-         * IDP bearer from them today with no cryptographic check of any kind,
-         * which is why it is a complete authentication bypass and why it has
-         * been publicly reachable for 488 days.
-         *
-         * This field is the only one the IDP can VERIFY: signature against
-         * Google's JWKS, plus iss / exp / aud, and then read email_verified
-         * from the verified claims. Additive — the IDP ignores it until its
-         * gate flips, so this cannot break a login on its own.
-         *
-         * RAW, AND NOTHING DERIVED FROM IT (BAPert's ruling). We do NOT send a
-         * decoded email_verified. A client-computed verification flag is a body
-         * field with a better story: an attacker posts email_verified:true and
-         * the defect is rebuilt one layer up. The IDP verifies for itself or
-         * the fix is theatre.
-         *
-         * Absent when this runs outside the OAuth callback scope — the key is
-         * simply omitted rather than sent null, so "we never captured one" stays
-         * distinguishable from "the provider issued none".
-         */
-        ...(idTokenScope.getStore()?.idToken ? { id_token: idTokenScope.getStore()!.idToken } : {}),
-        /**
-         * The same field for providers that have no id_token to give.
-         *
-         * Identical doctrine to the id_token above: RAW, forwarded verbatim,
-         * NOTHING DERIVED FROM IT, and omitted entirely rather than sent null so
-         * "never captured" stays distinguishable from "provider issued none".
-         * The IDP verifies for itself by calling GitHub with this token and
-         * enforcing primary && verified; we assert nothing about the identity.
-         *
-         * Scoped to the provider access token captured during THIS callback, so
-         * a google login continues to send id_token only and is unaffected.
-         */
-        ...(idTokenScope.getStore()?.accessToken
-          ? { access_token: idTokenScope.getStore()!.accessToken }
-          : {}),
-      }),
-    });
-
-    const oauthResText = await oauthRes.text();
-    // PAY-1427 (QAPert, PR 154 thread 326): this printed the first 500 chars of the oauth-callback TOKEN
-    // envelope on EVERY successful OAuth login (it runs before the !ok check). Status + length only.
-    console.log('[BETTER_AUTH] IDP oauth-callback response:', { status: oauthRes.status, bodyLength: oauthResText.length });
-
-    if (!oauthRes.ok) {
-      console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
-
-      /**
-       * PAY-2005 scenario (b) — RETURN THE IDP'S ERROR CODE (BAPert ruling 67897).
-       *
-       * Every refusal used to return a bare `false`, so the abort collapsed ALL
-       * causes to one generic `OAUTH_SIGN_IN_FAILED`: a NEW user refused
-       * registration (`REGISTRATION_NOT_ALLOWED`, ExternalAuthController.cs:908)
-       * bounced silently, indistinguishable from a network blip. Jon named the
-       * clear message explicitly (67856): "(b) a brand-new Google user with
-       * registration OFF is refused by the IDP with a clear message, not a
-       * silent bounce."
-       *
-       * The envelope is `{ error: { code, message } }` (PayEzControllerBase.Error).
-       * We read ONLY `error.code` and return it VERBATIM — the abort puts it in
-       * the `?error=` param, and the HOST's allowlist decides whether to render
-       * it. The package does NOT interpret the code and does NOT add a message
-       * (that would be a second allowlist). No code in the body -> null (the
-       * generic host code), exactly as before.
-       */
-      let idpErrorCode: string | null = null;
-      try {
-        const parsed = JSON.parse(oauthResText);
-        // FORWARD ONLY AN ALLOWLISTED CODE. Every other refusal keeps PAY-1733's single neutral code — an
-        // unlisted code would render nothing on the host page, which is the silent bounce this exists to end.
-        if (typeof parsed?.error?.code === 'string' && IDP_ERROR_CODES_TO_FORWARD.has(parsed.error.code)) {
-          idpErrorCode = parsed.error.code;
-        }
-      } catch {
-        /* non-JSON refusal body -> no code (generic abort) */
-      }
-
-      /**
-       * WHY THIS LOGS ONLY ON FAILURE, AND WHY IT LOGS THESE FIELDS.
-       *
-       * UNVERIFIED_ASSERTION has exactly two causes and the response body cannot tell
-       * them apart: we sent no id_token for the IDP to verify, or we sent one whose
-       * signature/aud/iss the IDP rejected. Without this line the operator sees a 401 on
-       * a login that visibly succeeded and has nowhere to go — which is where UMI sat on
-       * 2026-08-26.
-       *
-       * NEVER THE TOKEN ITSELF. An id_token is credential material and this whole code
-       * path exists to keep it out of anything persistent; a log file is persistent. We
-       * print presence, length, and the three claims that decide verification. `aud` is
-       * the Google client id — not a secret, and the single most likely mismatch, since
-       * the IDP checks it against what IT has registered for this client.
-       */
-      const forwarded = idTokenScope.getStore()?.idToken;
-      let claims: Record<string, unknown> = {};
-      if (forwarded) {
-        try {
-          claims = decodeJwt(forwarded) as Record<string, unknown>;
-        } catch {
-          claims = { decode: 'FAILED — not a well-formed JWT' };
-        }
-      }
-      const forwardedAccess = idTokenScope.getStore()?.accessToken;
-      console.error('[BETTER_AUTH] exchange diagnostics:', {
-        id_token_forwarded: !!forwarded,
-        id_token_length: forwarded ? forwarded.length : 0,
-        /**
-         * Read these two for github, and IGNORE the id_token pair above: github
-         * issues no id_token, so `id_token_forwarded: false` is its NORMAL state
-         * and not the fault. Presence and length only — an access token is
-         * credential material and this log is persistent. A github failure with
-         * access_token_forwarded:true means the IDP called GitHub and refused
-         * the answer (unverified or non-primary email, or app not installed);
-         * false means the capture hook never ran and the IDP never called out.
-         */
-        access_token_forwarded: !!forwardedAccess,
-        access_token_length: forwardedAccess ? forwardedAccess.length : 0,
-        // Absent id_token => the IDP had nothing to verify. Present => compare these
-        // against the client's registered Google credentials on the IDP.
-        aud: claims.aud ?? null,
-        iss: claims.iss ?? null,
-        email_verified: claims.email_verified ?? null,
-        sent_client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? null,
-        idp_url: idpUrl,
-      });
-      return idpErrorCode ?? false;
-    }
-
-    let idpData: any;
-    try { idpData = JSON.parse(oauthResText); } catch { return false; }
-    const result = idpData?.data?.result || idpData?.data || idpData;
-
-    if (!result?.access_token) {
-      console.warn('[BETTER_AUTH] IDP oauth-callback returned no access_token. Keys:', Object.keys(result || {}));
-      return false;
-
-    }
-
-    // Build IDP token data
-    //
-    // 170007 CONTRACT (BAPert ruling on 121350, agreed with DotNetPert
-    // 2026-08-08 — see mail thread, not re-derived here):
-    //   1. The IDP emits `requires_two_factor` (snake_case, both serializers,
-    //      per the estate law) as a NON-NULLABLE bool on OAuthCallbackResponse
-    //      (PayEz.DTOs OAuthCallbackResponse.cs) — ALWAYS present. No IDP
-    //      change needed or wanted: emitting a second, camelCase name for the
-    //      same fact would be the dialect problem the estate law exists to
-    //      prevent, not a fix.
-    //   2. Read requires_two_factor (snake) ONLY. CORRECTED mid-review:
-    //      BAPert's first draft of this contract said "read both casings,
-    //      defensively" — DotNetPert rejected that: a dual-casing client-side
-    //      read gives one fact two wire names just as surely as a dual-casing
-    //      IDP emit would, and it is the exact audience-dialect mistake
-    //      (186443) made deliberately instead of by accident. This package
-    //      previously read camel ONLY (card 170083, now corrected — it must
-    //      NOT record "emit both casings" as the IDP-side fix), which is why
-    //      this line silently fell through to the heuristic below on every
-    //      real call. The fix is reading the one name the IDP actually sends,
-    //      not tolerating both.
-    //   3. The old !hasRefreshToken fallback (IDP-2FA-BUG below) is RETIRED,
-    //      not patched. DotNetPert traced ExternalAuthController's
-    //      oauth-callback: IssueRefreshToken and RequiresTwoFactor both derive
-    //      from the SAME isFullyAuthenticated variable, so they cannot
-    //      disagree on this path — the divergence this fallback existed for
-    //      is not present here. Worse, the heuristic would currently produce
-    //      the RIGHT answer by coincidence, which hides the day it stops
-    //      being derived from one variable.
-    //   4. requires_two_factor is non-nullable, so reaching the `true`
-    //      default below means the response ISN'T an OAuthCallbackResponse at
-    //      all (wrong endpoint / error body / failed parse) — logged as that,
-    //      not as "2FA status unknown". Fail-closed to requiresTwoFactor=true
-    //      either way (rule 3).
-    //   5. mfaVerified = !requiresTwoFactor, computed fresh from THIS
-    //      response — no hardcoding, no carrying a prior session value
-    //      forward (that half of the monotonic-OR defect lived in
-    //      refresh.ts / ensure-fresh-access-token.ts, fixed separately).
-    //
-    // PRIOR STATE, for the record: this used to hardcode mfaVerified=false on
-    // every OAuth exchange as a blunt workaround for a since-disproven IDP
-    // bug, which itself caused every Google user to be sent to /mfa even on
-    // require_2fa=FALSE tenants (NextPert 13450's blocker, failing T4 on the
-    // demo tenant). That workaround is removed along with the bug it worked
-    // around.
-    const requiresTwoFactor: boolean = (() => {
-      // SNAKE ONLY (BAPert's corrected ruling, 2026-08-08): reading camel as
-      // a "defensive" secondary would give one fact two wire names — exactly
-      // the audience-dialect mistake (186443) being made deliberately. The
-      // estate law is explicit-snake-per-field-both-serializers; the IDP
-      // already complies (OAuthCallbackResponse.cs, both System.Text.Json
-      // and Newtonsoft). No IDP change, no camel read, no dual-casing.
-      const v = result.requires_two_factor ?? result.user?.requires_two_factor;
-      if (v === undefined) {
-        console.warn(
-          '[BETTER_AUTH] oauth-callback response has no requires_two_factor field at all — ' +
-            'unexpected response shape (requires_two_factor is non-nullable on OAuthCallbackResponse; ' +
-            'this is not "2FA status unknown", it means we are not looking at an oauth-callback response). ' +
-            'Defaulting requiresTwoFactor=true (fail closed).',
-        );
-        return true;
-      }
-      return !!v;
-    })();
-    const idpTokenData = {
-      idpAccessToken: result.access_token,
-      idpRefreshToken: result.refresh_token,
-      idpAccessTokenExpires: result.expires_in
-        ? Date.now() + result.expires_in * 1000
-        : Date.now() + 15 * 60 * 1000,
-      userId: String(result.user?.user_id || result.user?.id || result.user_id || baUserId),
-      email: result.user?.email || result.email || email,
-      name: result.user?.full_name || result.user?.name || result.name || name,
-      image: image,
-      roles: result.user?.roles || result.roles || [],
-      mfaVerified: !requiresTwoFactor, // re-derived fresh — see 170007 contract above
-      // Cards 141688/141741 — RELAYED, NOT DERIVED.
-      //
-      // The IDP already decides this (ExternalAuthController:943 and :2024,
-      // WO 113023): "enroll_mfa" = no CONFIRMED method, "mfa_verify" = a
-      // confirmed method exists, null = fully authenticated. It was emitted
-      // here and dropped on this line — `idpTokenData` is built field-by-field,
-      // so anything not named is silently discarded. Both downstream consumers
-      // (the middleware gate and the verify-code page) then reasoned in its
-      // absence and sent zero-method users to a page they cannot act on.
-      //
-      // WIRE NAME IS SNAKE: `next_step`, per [JsonPropertyName("next_step")] on
-      // BOTH OAuthCallbackResponse and ExternalTokenResponse. Reading
-      // `result.nextStep` here would be `undefined` forever and fail silently —
-      // the same camel/snake break `requires_two_factor` already cost us once.
-      //
-      // Do NOT recompute this from a method query. The IDP owns the fact; it is
-      // already usable-aware (confirmed and not revoked, per DotNetPert), which
-      // is the distinction that decides correctness: a revoked-TOTP user has
-      // count>0 but usable=0, and deriving it locally would let through exactly
-      // the users we must challenge.
-      // No `?? null`: if the response has no `next_step` at all (older IDP
-      // build, or a path that does not set it), that is UNKNOWN, not "fully
-      // authenticated". Defaulting it to null here would manufacture a
-      // clean-bill-of-health the IDP never gave and fail open at the gate.
-      nextStep: result.next_step,
-      idpClientId: result.client_id ? String(result.client_id) : undefined,
-      merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
-    };
-
-    // Storage is shared with the passkey sign-in path — see storeIdpTokensInSession.
-    const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
-    if (stored) console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
-    // true = success (tokens stored). false = a non-IdP failure with no specific code (generic abort).
-    return stored;
-  } catch (err) {
-    console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
-    return false;
-  }
-}
-
-
-/**
- * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
- * function never acquires tokens and never decides who the caller is.
- *
- * ── WHY THIS IS SPLIT OUT (BAPert ruling, 2026-08-04) ────────────────────────
- *
- * `exchangeOAuthForIdpTokens` above does TWO things: it ACQUIRES tokens by
- * POSTing to `/api/ExternalAuth/oauth-callback`, and then it STORES them. Only
- * the second half is reusable, and the first half is actively dangerous to
- * reuse:
- *
- *   oauth-callback mints an IDP bearer from an ASSERTED EMAIL with no
- *   cryptographic verification of any kind (card 138635).
- *
- * Passkey sign-in already holds something strictly better — a grant issued by
- * `/api/ExternalAuth/passwordless/passkey/verify`, which checked a real
- * signature against a registered credential. Routing that through
- * oauth-callback to obtain a session would DOWNGRADE a cryptographically
- * verified assertion into an unverified one, make passkey sign-in weaker than
- * its own ceremony, and inherit 138635 wholesale.
- *
- * That is not hypothetical: "do what the OAuth path does" is the obvious
- * implementation and it is the wrong one. Splitting acquisition from storage is
- * what makes the wrong one hard to write by accident.
- *
- * ── WHAT CALLERS MUST HAVE DONE FIRST ───────────────────────────────────────
- *
- * A Better Auth session must ALREADY EXIST for `sessionToken`. This function
- * enriches; it does not create. Better Auth owns session creation and cookie
- * signing, and nothing in this package should replicate either — the cookie is
- * `{token}.{base64(hmac)}` with standard padding, signed with the runtime
- * `authSecret` from Redis, and hand-rolling that produces a session which
- * decodes but does not authenticate.
- *
- * @param sessionToken  the Better Auth session token (from its Set-Cookie)
- * @param idpTokenData  tokens + identity, already obtained by the CALLER'S OWN
- *                      verified route. Built field-by-field by the caller so an
- *                      unnamed field cannot ride along silently.
- * @param authProvider  provenance label recorded on the canonical row. Written
- *                      to the historical `oauthProvider` key, which predates
- *                      non-OAuth callers; the NAME is legacy, the VALUE should
- *                      state what actually authenticated ('passkey', 'google').
- */
-export async function storeIdpTokensInSession(
-  sessionToken: string,
-  idpTokenData: Record<string, unknown>,
-  authProvider: string,
-): Promise<boolean> {
-  try {
-    const config = await getIDPClientConfig();
-    const appSlug = config.clientSlug || getAppSlug();
-    const baKey = `ba:${appSlug}:${sessionToken}`;
-
-    const baRaw = await getRedis().get(baKey).catch(() => null);
-    if (!baRaw) {
-      // No session to enrich. Do NOT create one as a fallback: a session
-      // conjured here would carry no Better Auth cookie, so it would be
-      // unreachable by the browser and invisible to every other consumer —
-      // failing as "silently signed out" rather than as an error.
-      console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', tokenLogId(sessionToken));
-      return false;
-    }
-
-    const baData = JSON.parse(baRaw);
-    baData.idpTokens = idpTokenData;
-    await getRedis().setex(baKey, SESSION_TTL, JSON.stringify(baData));
-
-    // Canonical store — the key getSession() reads, used by the refresh handler
-    // and token lifecycle. A failure here leaves the BA session correct and the
-    // canonical row missing, so it is warned and not fatal: the user is signed
-    // in, and refresh degrades rather than the sign-in failing outright.
-    try {
-      const { getSessionPrefix } = await import('../lib/app-slug');
-      const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
-      await getRedis().setex(canonicalKey, SESSION_TTL, JSON.stringify({
-        ...idpTokenData,
-        oauthProvider: authProvider,
-      }));
-    } catch (canonicalErr) {
-      console.warn('[BETTER_AUTH] Failed to write canonical session:', canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr));
-    }
-
-    return true;
-  } catch (err) {
-    console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
-    return false;
-  }
-}
-
-/**
- * The `?error=` code the login page receives when an OAuth sign-in is ABORTED because the IdP exchange did not
- * store tokens (PAY-1733). Hosts map it to ONE neutral line; the card's words are "That sign-in didn't work.
- * Try again or use another method." The cause stays in the server log, never on the page.
- */
-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).
- *
- * Default stays PAY-1733's ONE neutral code: the cause of an ordinary failed exchange lives in the server
- * log, never on the page. A code is forwarded ONLY when it earns a distinct user-facing message — today just
- * the registration refusal, so a NEW Google user with registration OFF sees a clear "not open to sign-up"
- * line instead of a silent bounce. Adding a code here REQUIRES a matching entry in the host allowlist
- * (portal: src/lib/auth/magic-link-outcome.ts); an unlisted code renders nothing, which is a silent bounce
- * wearing a different number. Add them together, never one alone.
- */
-export const IDP_ERROR_CODES_TO_FORWARD: ReadonlySet<string> = new Set(['REGISTRATION_NOT_ALLOWED']);
-
-
-/**
- * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
- * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only
- * accepted with Secure) and dropping Expires/Max-Age in favour of Max-Age=0.
- */
-export function expireSetCookies(setCookies: readonly string[]): string[] {
-  const out: string[] = [];
-  for (const sc of setCookies) {
-    const [pair, ...attrs] = sc.split(';').map((s) => s.trim());
-    const eq = pair.indexOf('=');
-    const name = eq > 0 ? pair.slice(0, eq) : '';
-    if (!name) continue;
-    const kept = attrs.filter((a) => /^(path|domain|secure|samesite|httponly)\b/i.test(a));
-    out.push([`${name}=`, ...kept, 'Max-Age=0'].join('; '));
-  }
-  return out;
-}
-
-/**
- * PAY-1733 (Jon, live on :4797): ABORT an OAuth sign-in whose IdP exchange did not store tokens.
- *
- * Before this, a failed exchange was a console.error and the user kept the Better Auth session the callback had
- * just created: signed in, holding NO IdP tokens. The host then routed that session to 2FA, which painted the
- * user's email and failed every call - a red "sign in again" screen about an account the app could no longer
- * authenticate. The IdP's 401 was CORRECT (it fail-closes unverified assertions); keeping the session was the bug.
- *
- * So: no session without IdP tokens. The Better Auth session is destroyed (its own signOut, best effort, then the
- * `ba:<slug>:<token>` record directly - that record is what makes it resolvable), every cookie the callback set is
- * expired, and the user goes to the login page with OAUTH_SIGN_IN_FAILED. Relative Location, as for the state-error
- * branch above (328439: an absolute URL built from request.url is a dead tab in a container).
- */
-async function abortOAuthSignIn(
-  callbackResponse: Response,
-  sessionToken: string | null,
-  cookieHeader: string,
-  loginPath: string,
-  errorCode: string = OAUTH_SIGN_IN_FAILED_ERROR,
-): Promise<Response> {
-  const headers = new Headers();
-  if (sessionToken) {
-    try {
-      const auth = await getBetterAuthInstance();
-      const out = await auth?.api?.signOut?.({ headers: new Headers({ cookie: cookieHeader }), asResponse: true });
-      for (const sc of (out as Response | undefined)?.headers?.getSetCookie?.() ?? []) headers.append('set-cookie', sc);
-    } catch (err) {
-      console.warn('[BETTER_AUTH] abort: Better Auth signOut failed, deleting the record directly:', err instanceof Error ? err.message : String(err));
-    }
-    try {
-      const config = await getIDPClientConfig();
-      await getRedis().del(`ba:${config.clientSlug || getAppSlug()}:${sessionToken}`);
-    } catch (err) {
-      console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', tokenLogId(sessionToken), err instanceof Error ? err.message : String(err));
-    }
-  }
-  for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? [])) headers.append('set-cookie', sc);
-  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${errorCode}`);
-  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)', 'code=' + errorCode);
-  return new Response(null, { status: 302, headers });
-}
-
-/**
- * Create a production-ready GET handler for the auth catch-all route.
- *
- * Wraps better-auth's GET handler with:
- * - OAuth state error recovery (redirects to login instead of error page)
- * - IDP token exchange after successful OAuth callback - and, when it stores no tokens, the sign-in is ABORTED
- *   (session destroyed, cookies expired, login page with OAUTH_SIGN_IN_FAILED; PAY-1733)
- *
- * Usage in host app:
- * ```ts
- * import { createAuthGetHandler, getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
- * export const GET = createAuthGetHandler('/account-auth/login');
- * export async function POST(req: Request) {
- *   const ba = await getBetterAuthHandler();
- *   return ba!.POST(req);
- * }
- * ```
- */
-export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
-  return async function GET(request: Request): Promise<Response> {
-    // Card 138635: establish the request-scoped carrier for the provider's raw
-    // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
-    // hook that sees the token) and the exchange below (which forwards it).
-    // Wrapping the whole handler is what makes "never persisted" achievable —
-    // the token exists only for the life of this request.
-    return idTokenScope.run({}, async () => {
-    const ba = await getBetterAuthHandler();
-    if (!ba) {
-      return new Response('Auth handler not configured', { status: 500 });
-    }
-
-    const response = await ba.GET(request);
-
-    // Intercept auth errors (state mismatch, expired cookies) — redirect to login cleanly
-    if (response.status === 302) {
-      const location = response.headers.get('location') || '';
-      if (location.includes('/api/auth/error') || location.includes('please_restart')) {
-        console.warn('[BETTER_AUTH] OAuth state error, redirecting to login');
-        // *** DO NOT "TIDY" THIS BACK TO Response.redirect(). IT THROWS. (328439) ***
-        // Response.redirect() REQUIRES an absolute URL — measured, on the leg's own
-        // runtime and again on node 24:
-        //     Response.redirect('/account-auth/login', 302)
-        //       -> TypeError: Failed to parse URL from /account-auth/login
-        // That requirement is the whole cause of the bug this replaces. The old line
-        // was:
-        //     return Response.redirect(new URL(loginPath, request.url), 302);
-        // `request.url` inside a containerised Next standalone server carries the
-        // LISTEN address, not the address the browser used, so a container bound to
-        // 0.0.0.0:8080 handed the browser `http://0.0.0.0:8080/sign-in` — an address
-        // that can NEVER load (net::ERR_ADDRESS_INVALID, confirmed in a real browser
-        // by QAPert). Reload cannot recover it, because the address is invalid rather
-        // than down. It fired on the ORDINARY path: the oauth_state cookie is
-        // Max-Age=600, so anyone spending >10 minutes at Google's account chooser
-        // landed on a dead tab.
-        //
-        // A RELATIVE Location header is legal (RFC 7231 §7.1.2) and the browser
-        // resolves it against the origin it is ACTUALLY on, so no origin has to be
-        // guessed, configured, or derived from a header. This is the same shape the
-        // app's own middleware already emits successfully (307 + relative), which is
-        // why page redirects survived while this one did not.
-        //
-        // WHY NOT REBUILD FROM BETTER_AUTH_URL / rawBaseURL, the other proposal:
-        //   (a) rawBaseURL is NOT in scope here — it is a local inside
-        //       createBetterAuthInstance (~:397), a different function ~676 lines up.
-        //       Reaching it means recomputing the env precedence or exporting a
-        //       helper, i.e. more moving parts for a strictly worse result.
-        //   (b) It would reintroduce a guessed origin and make this path depend on
-        //       BETTER_AUTH_URL being set correctly per leg. Relative needs no env.
-        //   (c) Anything Host-derived would open host-header injection on a redirect
-        //       that is currently host-INVARIANT. Relative keeps that property.
-        //
-        // Works whether loginPath is relative (package default '/account-auth/login',
-        // and the graft passes '/sign-in') or absolute — an absolute Location is also
-        // legal, so a consumer passing a full URL still behaves.
-        return new Response(null, { status: 302, headers: { location: loginPath } });
-      }
-    }
-
-    // After the OAuth callback: exchange the provider identity for IDP tokens. If that does NOT store tokens - the
-    // IdP refused (401), no session was found, or anything threw - the sign-in is ABORTED (PAY-1733). A session is
-    // kept only when it holds IdP tokens.
-    const url = new URL(request.url);
-    if (url.pathname.includes('/callback/') && response.status === 302) {
-      const setCookies = response.headers.getSetCookie?.() || [];
-      const cookieHeader = setCookies
-        .map((c: string) => c.split(';')[0])
-        .join('; ');
-      let sessionToken: string | null = null;
-      // true = tokens stored; false = no specific IdP code (generic abort); a string = the IdP's own refusal code
-      // (PAY-2005 (b): REGISTRATION_NOT_ALLOWED, etc.), forwarded so the host can show a clear message.
-      let exchange: boolean | string = false;
-      try {
-        const auth = await getBetterAuthInstance();
-        if (auth?.api?.getSession) {
-          const headers = new Headers();
-          headers.set('cookie', cookieHeader);
-
-          const session = await auth.api.getSession({ headers });
-          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);
-            // 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');
-          }
-        }
-      } catch (err: any) {
-        console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
-      }
-      if (exchange !== true) {
-        // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.
-        const errorCode = typeof exchange === 'string' ? exchange : OAUTH_SIGN_IN_FAILED_ERROR;
-        return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath, errorCode);
-      }
-    }
-
-    return response;
-    });
-  };
-}
+/**
+ * Better Auth Configuration
+ *
+ * Primary auth configuration. Replaces the former NextAuth auth-options.ts.
+ *
+ * Architecture: No database adapter — Better Auth runs in stateless mode
+ * with JWE cookie cache. User management stays on IDP, sessions on Redis.
+ *
+ * @see BETTER-AUTH-MIGRATION-SPEC.md
+ */
+
+import 'server-only';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'crypto';
+import { decodeJwt } from 'jose';   // better-auth's own JWT dependency
+import { betterAuth } from 'better-auth';
+import { nextCookies } from 'better-auth/next-js';
+import { toNextJsHandler } from 'better-auth/next-js';
+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';
+import { getRedis } from '../lib/redis';
+import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
+import { SESSION_TTL } from '../lib/session-store';
+import { tokenLogId } from '../lib/token-log-id';
+
+/**
+ * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
+ * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
+ * = 48 bits; collision-tellable across a deployment, useless as a credential.
+ */
+export function secretFingerprint(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 12);
+}
+
+/**
+ * 273183: keys written onto the `ba:{slug}:{token}` record by an author OTHER
+ * than Better Auth, which must survive a Better Auth session write.
+ *
+ * Today this is exactly `idpTokens`, written by `storeIdpTokensInSession`. The
+ * list is a named constant rather than a hardcoded check because the shape of
+ * the bug is "a second author appeared and the adapter did not know" — the next
+ * enrichment key should be added here, not rediscovered as a strip.
+ */
+const PRESERVED_SESSION_KEYS = ['idpTokens'] as const;
+
+/**
+ * True for a JSON object we can safely merge into — not null, not an array.
+ * `typeof null === 'object'` and arrays are objects, and merging into either
+ * would corrupt the record rather than preserve it.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Better Auth social provider config shape.
+ */
+export interface BetterAuthSocialProvider {
+  clientId: string;
+  clientSecret: string;
+  scope?: string[];
+  prompt?: string;
+  accessType?: 'offline' | 'online';
+  hd?: string;
+  /**
+   * 260419: better-auth's ONLY guard against OAuth auto-provisioning
+   * (oauth2/link-account.mjs handleOAuthUserInfo: `if (disableSignUp) return
+   * {error:"signup disabled"}`). Unset means ANY unknown Google identity gets a
+   * local account created at callback. We wire it from the tenant's own policy.
+   */
+  disableSignUp?: boolean;
+}
+
+/**
+ * Build Better Auth social providers from IDP config.
+ */
+/**
+ * REQUEST-SCOPED carrier for the provider's raw id_token. Card 138635.
+ *
+ * WHY THIS EXISTS: /api/ExternalAuth/oauth-callback mints an IDP bearer for any
+ * ASSERTED email — we send {provider, email} and nothing verifiable. The fix is
+ * for the IDP to require a provider-signed id_token and verify it itself. This
+ * is the client half: capture the token Better Auth already receives, and
+ * forward it. Additive — the IDP ignores it until its gate flips.
+ *
+ * WHY AsyncLocalStorage AND NOT REDIS (BAPert's ruling: forward, do not persist):
+ * an id_token is credential material. Writing it to the session record would put
+ * it one allow-list edit away from leaking out of /api/internal/session-data,
+ * and it would outlive the request that needed it. ALS scopes it to the single
+ * request, and it is gone when the request ends — nothing to expire, nothing to
+ * scrub, nothing to leak.
+ *
+ * SAFE BY CONSTRUCTION: getUserInfo (which fills this) and the post-callback
+ * exchange (which reads it) both run inside createAuthGetHandler's own request.
+ * VERIFIED, not assumed: better-auth.ts:452 awaits ba.GET(request) — the call
+ * that invokes getUserInfo — and the exchange follows at :465 in the SAME
+ * function. Outside that scope the store is undefined and the body simply omits
+ * id_token, which is the correct additive behaviour.
+ */
+/**
+ * ON globalThis FOR THE SAME REASON THE BETTER AUTH INSTANCE IS (181814, see STATE_KEY
+ * below) — and it was NOT, which is the whole defect.
+ *
+ * This module is loaded more than once per process: instrumentation and the auth route
+ * are different chunks with their own module registries. `state` was moved to globalThis
+ * so both copies share the Better Auth INSTANCE. This AsyncLocalStorage was left in
+ * module scope, so each copy got its own.
+ *
+ * The result, measured on UMI 2026-08-26 against idp.payez.net:
+ *
+ *   copy A builds the instance   -> the getUserInfo closure captures A's idTokenScope
+ *   copy B serves the callback   -> createAuthGetHandler runs .run({}) on B's
+ *   getUserInfo fires, reads A   -> getStore() is undefined, `if (scope)` skips
+ *   the exchange reads B         -> empty, so id_token is omitted from the body
+ *
+ * Sign-in SUCCEEDS at every visible step. The user gets a session, an avatar, an email.
+ * The IDP then answers 401 UNVERIFIED_ASSERTION with reason="id_token missing"
+ * (confirmed in its own logs, correlationId 0HNO2755RESR1) — so the client half of 138635
+ * has been shipping as a no-op wherever the module double-loads, and the security fix it
+ * exists to deliver never arrived. A shared instance plus a per-copy scope is the worst
+ * combination: everything looks wired, and the one field that proves identity is dropped.
+ *
+ * globalThis is per-process and per-runtime, which is exactly the lifetime a request-scoped
+ * carrier needs to be reachable from every copy that might run inside the request.
+ */
+/**
+ * THE KEY STAYS '__payezIdTokenScope' EVEN THOUGH THE SCOPE NOW CARRIES TWO
+ * THINGS. Renaming it would give a copy on the old name and a copy on the new
+ * name two DIFFERENT stores in the same process — which is precisely the
+ * double-load failure documented above, reintroduced by a cosmetic rename. The
+ * name is a wire contract between copies, not a description.
+ *
+ * accessToken is here for providers that do NOT issue an id_token. GitHub is
+ * not an OIDC provider: it has no id_token, no JWKS and no discovery document,
+ * so `id_token` can never be the field that proves a GitHub identity. The IDP
+ * re-derives that identity by calling GitHub itself with this access token
+ * (GitHubIdentityVerifier), which keeps the same rule google follows — the IDP
+ * verifies for itself and never trusts an asserted email.
+ */
+const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
+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
+>;
+gScope[ID_TOKEN_SCOPE_KEY] ??= new AsyncLocalStorage<ProviderTokenScope>();
+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.
+ */
+export interface IdpOAuthProviderConfig {
+  providerId: string;
+  discoveryUrl: string;
+  clientId: string;
+  pkce: true;
+  scopes: string[];
+  /** 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'],
+
+    /**
+     * ⚠ DO NOT ADD `authentication: 'basic'` HERE. IT SILENTLY BREAKS KEYLESS.
+     *
+     * Found by QAPert-NightHawk (21348) — the second config trap in this plugin
+     * after the preset one, and the same shape: a field that looks like a
+     * harmless transport detail and quietly changes whether we are a public
+     * client at all.
+     *
+     * @better-auth/core validate-authorization-code.mjs:
+     *     if (authentication === "basic") {
+     *       headers.authorization = `Basic ${base64(`${clientId}:${clientSecret ?? ""}`)}`;
+     *     } else {
+     *       body.set("client_id", clientId);
+     *       if (options.clientSecret) body.set("client_secret", options.clientSecret);
+     *     }
+     *
+     * Note what the 'basic' branch does with NO secret: it sends an EMPTY
+     * password, `Basic base64("<clientId>:")`. That is not "no authentication",
+     * it is WRONG authentication — we would be presenting ourselves as a
+     * confidential client with a blank credential. The default branch is the
+     * one that produces a genuine public-client PKCE request.
+     *
+     * Leaving this field UNSET is load-bearing, which is exactly why it needs a
+     * comment: nothing about an absent field advertises that its absence is a
+     * decision.
+     */
+  };
+}
+
+export function buildBetterAuthProviders(
+  config: IDPClientConfig
+): Record<string, BetterAuthSocialProvider> {
+  const providers: Record<string, BetterAuthSocialProvider> = {};
+
+  for (const oauth of config.oauthProviders || []) {
+    if (!oauth.enabled) continue;
+    const name = oauth.provider.toLowerCase();
+    const additionalParams = oauth.additionalParams ?? {};
+    const rawPrompt = additionalParams.prompt;
+    const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;
+    const rawHostedDomain = additionalParams.hd;
+
+    // Ensure profile scope is present for Google so avatar image is returned
+    const scopes = oauth.scopes?.split(' ') || [];
+    if (name === 'google' && !scopes.includes('profile')) {
+      scopes.push('profile');
+    }
+
+    /**
+     * 224721: better-auth's google provider UNCONDITIONALLY seeds its default
+     * scopes ['email','profile','openid'] and then pushes our `scope` verbatim
+     * (@better-auth/core social-providers/google.mjs createAuthorizationURL) —
+     * the row's "openid email profile" reached Google as
+     * "email profile openid openid email profile". Semantically harmless
+     * (Google dedupes) but sloppy on a URL a demo audience can read. Hand over
+     * only what the defaults do not already cover; undefined when nothing
+     * remains, so the provider emits exactly its default set.
+     */
+    const GOOGLE_DEFAULT_SCOPES = ['email', 'profile', 'openid'];
+    /**
+     * Same defect, same fix, different provider: github's createAuthorizationURL
+     * also seeds ['read:user','user:email'] unconditionally and then pushes ours
+     * on top (@better-auth/core social-providers/github.ts), so the stored row
+     * "read:user user:email" reached GitHub as
+     * "read:user user:email read:user user:email". Measured on :4799, not
+     * assumed. GitHub dedupes, so this is legibility rather than function — but
+     * a scope list is the first thing a security reviewer reads off that URL.
+     */
+    const GITHUB_DEFAULT_SCOPES = ['read:user', 'user:email'];
+    const wireScopes =
+      name === 'google'
+        ? scopes.filter((s) => !GOOGLE_DEFAULT_SCOPES.includes(s))
+        : name === 'github'
+          ? scopes.filter((s) => !GITHUB_DEFAULT_SCOPES.includes(s))
+          : scopes;
+
+    providers[name] = {
+      clientId: oauth.clientId,
+      clientSecret: oauth.clientSecret,
+      scope: wireScopes.length > 0 ? wireScopes : undefined,
+      /**
+       * PAY-2005 — DISABLE-SIGN-UP IS REMOVED, DELIBERATELY. DO NOT RE-ADD IT.
+       *
+       * 260419 wired this from `config.authSettings?.allowPublicRegistration` to
+       * close a client-side self-serve provisioning door. It cannot do that job
+       * correctly, and it BREAKS SIGN-IN:
+       *
+       *   - This app runs better-auth in STATELESS mode (no DB adapter — see the
+       *     file header). better-auth therefore has NO user store, so at the OAuth
+       *     callback it cannot tell an EXISTING user from a NEW one. Its
+       *     handleOAuthUserInfo consults `disableSignUp` for BOTH, so
+       *     `disableSignUp: true` refuses a returning user exactly like a
+       *     stranger. Measured live 2026-09-30 (PAY-2005): portal.keelauth.com
+       *     Google sign-in bounced to /sign-in with Better Auth `signup_disabled`
+       *     once client 12's allow_public_registration reported false.
+       *
+       *   - The REAL registration gate already exists and is correct, at the IDP:
+       *     PayEz.External.Id.Api ExternalAuthController.oauth-callback looks the
+       *     user up by verified email (:799); an existing user logs in UNTOUCHED
+       *     (:811); only the isNewUser branch (:853) calls INewUserRegistrar,
+       *     which refuses fail-closed when the client forbids public registration
+       *     (NewUserRegistrar.cs:65, `SecurityFlags.AllowPublicRegistration != true`).
+       *     Its own comment states the contract: "existing federated users ...
+       *     log in untouched, so gating here never blocks login."
+       *
+       * So this flag was a DUPLICATE gate that could only ever misfire — it cannot
+       * distinguish new from existing, and the IDP already refuses new identities.
+       * Removing it restores sign-in for existing users WITHOUT reopening
+       * self-serve: a NEW identity that completes the better-auth leg still gets
+       * REFUSED at the IDP exchange and never receives IDP tokens, which is the
+       * portal's actual authorization gate.
+       *
+       * WHERE "no self-serve sign-up" IS ENFORCED NOW: the IDP's NewUserRegistrar
+       * (above) as the backstop, and each app's own front-door sign-up gate
+       * (e.g. the portal's signup-gate.ts / SignUpCard) for the UI affordance.
+       * Both are correct and neither is this flag.
+       */
+      // Google is overly eager to reuse the last account unless we
+      // explicitly ask for account selection on each social login.
+      prompt: typeof rawPrompt === 'string'
+        ? rawPrompt
+        : name === 'google'
+          ? 'select_account'
+          : undefined,
+      accessType: rawAccessType === 'online' ? 'online' : rawAccessType === 'offline' ? 'offline' : undefined,
+      hd: typeof rawHostedDomain === 'string' ? rawHostedDomain : undefined,
+    };
+
+    /**
+     * CAPTURE THE RAW id_token — card 138635, client half.
+     *
+     * getUserInfo is the ONLY provider hook that receives the token set.
+     * mapProfileToUser cannot do this: it is handed the DECODED claims, and a
+     * signed JWT cannot be reconstructed from them. We need the raw token
+     * because the IDP must verify the signature ITSELF — a client-decoded
+     * claim is just another assertable field, which is the defect restated.
+     *
+     * ⚠ THIS REPLACES THE DEFAULT google getUserInfo ENTIRELY. Upstream calls
+     * `if (options.getUserInfo) return options.getUserInfo(token)` FIRST and
+     * returns our result verbatim, so everything the default did is now ours to
+     * do — including the `hd` hosted-domain restriction.
+     *
+     * `hd` IS NOT HYPOTHETICAL: it is wired from additionalParams.hd four lines
+     * above, so a client can restrict sign-in to a Google Workspace domain.
+     * Silently dropping it would let ANY Google account into a client that had
+     * restricted itself — a security regression introduced by a security fix.
+     * (Measured on 93: zero clients set it today. That is a reason to be
+     * careful, not a reason to skip it — it is configurable and unused, which
+     * is exactly the state in which a regression goes unnoticed.)
+     *
+     * SO WE DO NOT OVERRIDE AT ALL WHEN `hd` IS SET. We take the hook over
+     * ONLY where upstream's check is PROVABLY VACUOUS — its own first line is
+     * `if (!configuredHostedDomain) return true`. With no hd configured the
+     * default would return true unconditionally, so omitting it is equivalent
+     * by the library's own definition rather than by our judgement.
+     *
+     * A client that DOES set hd keeps the stock provider, keeps its domain
+     * restriction, and simply does not contribute an id_token yet. Losing a
+     * capability is an acceptable cost; silently losing a security control is
+     * not. (better-auth does not re-export the predicate through its public
+     * types, and reimplementing a security check is how two copies drift — so
+     * the honest move is to not need it.)
+     */
+    if (name === 'google' && !providers[name].hd) {
+      (providers[name] as unknown as Record<string, unknown>).getUserInfo = async (token: { idToken?: string }) => {
+        if (!token?.idToken) return null;
+
+        // The only new behaviour: hand the raw token to this request's scope.
+        const scope = idTokenScope.getStore();
+        if (scope) {
+          scope.idToken = token.idToken;
+        } else {
+          // NOT a silent skip. A missing scope here means 138635 degrades to a no-op:
+          // the login still succeeds, and the IDP rejects the exchange with
+          // reason="id_token missing" a second later, with nothing connecting the two.
+          // That cost a day on UMI. If this fires, the OAuth callback is running outside
+          // createAuthGetHandler — either the route mounts the bare
+          // `routes/auth/nextauth` re-export instead of createAuthGetHandler, or this
+          // module has double-loaded and the scope is not shared (see 181814 above).
+          console.warn(
+            '[BETTER_AUTH] id_token captured but NO REQUEST SCOPE to put it in — it will ' +
+              'NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
+              'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.',
+          );
+        }
+
+        // Mirrors the upstream default (google.mjs) verbatim, minus the hd
+        // branch that cannot fire here — so overriding the hook changes WHAT WE
+        // KEEP, never what we ACCEPT.
+        const claims = decodeJwt(token.idToken) as Record<string, any>;
+        return {
+          user: {
+            id: claims.sub,
+            name: claims.name,
+            email: claims.email,
+            image: claims.picture,
+            emailVerified: claims.email_verified,
+          },
+          data: claims,
+        };
+      };
+    }
+
+    /**
+     * GITHUB: THE SAME CAPTURE, A DIFFERENT TOKEN.
+     *
+     * GitHub is not an OIDC provider — it issues no id_token — so the google
+     * branch above can never fire for it and the exchange would post an
+     * assertion with nothing that proves identity. That is exactly the
+     * 401 UNVERIFIED_ASSERTION measured on :4799, whose diagnostics read
+     * `id_token_forwarded: false, id_token_length: 0` with `response_time_ms: 0`:
+     * the IDP rejected it instantly, without ever calling GitHub.
+     *
+     * getUserInfo is the ONLY provider hook that receives the token set (see the
+     * google note above), and @better-auth/core's github provider calls
+     * `options.getUserInfo(token)` BEFORE its own body — so installing this
+     * REPLACES the default rather than wrapping it, and the default's work has
+     * to be reproduced here or the sign-in loses its profile entirely.
+     *
+     * Mirrored verbatim from @better-auth/core/src/social-providers/github.ts at
+     * the version the container actually runs (better-auth 1.5.6 — the graft's
+     * node_modules says 1.6.29 and is NOT what executes). Kept deliberately
+     * dumb: it must not "improve" on upstream, because every divergence here is
+     * a behaviour change disguised as a token capture.
+     *
+     * This is NOT the identity check. The IDP re-derives the GitHub identity
+     * itself from this access token and enforces primary && verified server-side
+     * (GitHubIdentityVerifier); what we return here only shapes the local
+     * better-auth user record.
+     */
+    if (name === 'github') {
+      (providers[name] as unknown as Record<string, unknown>).getUserInfo = async (token: {
+        accessToken?: string;
+      }) => {
+        const store = idTokenScope.getStore();
+        if (store) {
+          store.accessToken = token?.accessToken;
+        } else {
+          console.warn(
+            '[BETTER_AUTH] github access_token captured but NO REQUEST SCOPE to put it in — ' +
+              'it will NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
+              'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.',
+          );
+        }
+
+        const ghHeaders = {
+          'User-Agent': 'better-auth',
+          Authorization: `Bearer ${token?.accessToken}`,
+        };
+
+        const profileRes = await fetch('https://api.github.com/user', {
+          headers: ghHeaders,
+        });
+        // Upstream returns null on profile error, which fails the sign-in
+        // closed. Preserved rather than softened.
+        if (!profileRes.ok) {
+          console.warn(
+            `[BETTER_AUTH] github getUserInfo: /user returned ${profileRes.status}`,
+          );
+          return null;
+        }
+        const profile = (await profileRes.json()) as Record<string, any>;
+
+        const emailsRes = await fetch('https://api.github.com/user/emails', {
+          headers: ghHeaders,
+        });
+        const emails = emailsRes.ok
+          ? ((await emailsRes.json()) as Array<{
+              email: string;
+              primary: boolean;
+              verified: boolean;
+            }>)
+          : undefined;
+
+        // A GitHub account with a private email returns profile.email = null;
+        // upstream falls back to the primary address here.
+        if (!profile.email && emails) {
+          profile.email = (emails.find((e) => e.primary) ?? emails[0])?.email;
+        }
+        const emailVerified =
+          emails?.find((e) => e.email === profile.email)?.verified ?? false;
+
+        return {
+          user: {
+            id: profile.id,
+            name: profile.name || profile.login || '',
+            email: profile.email,
+            image: profile.avatar_url,
+            emailVerified,
+          },
+          data: profile,
+        };
+      };
+    }
+  }
+
+  return providers;
+}
+
+/**
+ * Optional configuration for `createBetterAuthInstance`.
+ *
+ * - `magicLink`: if provided, registers Better Auth's magic-link plugin.
+ *   The host app supplies its own `sendMagicLink` callback — typically a
+ *   fetch to its email service (e.g. ACP's `/v1/auth/magic-link/email`).
+ *   Omit the `magicLink` key entirely to skip the plugin; the consuming
+ *   app will not have a magic-link flow.
+ */
+export interface CreateBetterAuthInstanceOptions {
+  magicLink?: MagicLinkOptions;
+  /**
+   * Extra Better Auth plugins supplied by the consuming app.
+   *
+   * WHY THIS EXISTS — session minting is not delegable any other way. BA's
+   * `setSessionCookie` requires a `GenericEndpointContext`, which only BA's own
+   * endpoint machinery constructs, so an app that must mint a session for an
+   * identity established OUTSIDE BA's built-in providers (passkey sign-in being
+   * the first) cannot do it from a route handler. It needs a real BA endpoint,
+   * and endpoints only arrive via plugins.
+   *
+   * Deliberately GENERIC. The package gains "an app may supply plugins" rather
+   * than any knowledge of passkeys — the alternative was teaching this file
+   * about a specific auth method, which is how a package accumulates a consumer's
+   * feature list.
+   *
+   * The alternative to this option is an app hand-rolling the session cookie
+   * (`{token}.{base64(hmac)}`, standard padding, runtime `authSecret` from
+   * Redis). That fails as a session which DECODES BUT DOES NOT AUTHENTICATE —
+   * so this option exists specifically to make that shortcut unnecessary.
+   */
+  plugins?: Parameters<typeof betterAuth>[0]['plugins'];
+}
+
+/**
+ * Create Better Auth instance from IDP config.
+ *
+ * No database — runs in stateless mode with JWE cookie cache.
+ * Call after getIDPClientConfig() resolves.
+ */
+export function createBetterAuthInstance(
+  idpConfig: IDPClientConfig,
+  opts: CreateBetterAuthInstanceOptions = {}
+) {
+  assertAppSlugMatchesIdp(idpConfig.clientSlug);
+  const appSlug = idpConfig.clientSlug || getAppSlug();
+
+  // 185121 line 1: name the secret this instance PINNED, as a hash, never the
+  // secret. 183047's surviving fork is HMAC-fail vs record-miss; an HMAC-fail
+  // caused by a divergent secret is only diagnosable if every instance
+  // creation logged WHICH secret it bound. Both init paths (this module's
+  // getBetterAuthInstance and server/auth.ts getAuthInstance) funnel through
+  // here, so this one line covers both; getAuthInstance adds its own line
+  // naming the path, because it previously created an instance INVISIBLY.
+  console.log(
+    `[BETTER_AUTH] createBetterAuthInstance: slug=${appSlug} authSecret ${idpConfig.authSecret ? `sha256:${secretFingerprint(idpConfig.authSecret as string)}` : 'ABSENT'}`
+  );
+
+  // Resolve base URL: BETTER_AUTH_URL env > IDP config > localhost fallback
+  // Must include /api/auth since that's where the catch-all route is mounted
+  const rawBaseURL = process.env.BETTER_AUTH_URL
+    || idpConfig.baseClientUrl
+    || `http://localhost:${process.env.PORT || '3000'}`;
+  const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
+
+  const idpOAuth = buildIdpOAuthProviderConfig(rawBaseURL);
+
+  return betterAuth({
+    baseURL,
+    secret: idpConfig.authSecret as string,
+
+    socialProviders: buildBetterAuthProviders(idpConfig),
+
+    // Trust the app's own origin + any configured base URL
+    trustedOrigins: [
+      rawBaseURL,
+      baseURL,
+      ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
+      // MEASURED 2026-08-26: this list ended with the literals localhost:3000, :3400
+      // and :3600. payez_idp_admin_web runs on :3200 - correctly configured, with
+      // BETTER_AUTH_URL=http://localhost:3200 - and every GET /api/auth/get-session
+      // returned 400, because the port it actually runs on was not one of the three
+      // someone had typed in. A config-shaped constant is not configuration.
+      //
+      // The app's own origin is already covered by rawBaseURL/baseURL above; the dev
+      // origin is DERIVED from PORT, and anything genuinely external comes from
+      // BETTER_AUTH_TRUSTED_ORIGINS (comma-separated).
+      `http://localhost:${process.env.PORT || '3000'}`,
+      ...(process.env.BETTER_AUTH_TRUSTED_ORIGINS
+        ? process.env.BETTER_AUTH_TRUSTED_ORIGINS.split(',').map((o) => o.trim()).filter(Boolean)
+        : []),
+    ],
+
+    // Redis-backed session storage via secondaryStorage
+    secondaryStorage: {
+      /**
+       * 170033 (QAPert 22654, load-bearing precondition for 183483): DO NOT
+       * swallow a Redis failure into `null` here.
+       *
+       * `null` from `get` is Better Auth's OWN signal for "no session at this
+       * key" (see node_modules/better-auth db/internal-adapter.mjs
+       * `findSession`: `if (!sessionStringified ...) return null`). Catching
+       * a Redis error and returning `null` therefore told better-auth "this
+       * session does not exist" when the true state was "the store could not
+       * be asked" — indistinguishable from a genuine sign-out. With
+       * `cookieCache` disabled (session.cookieCache.enabled above), EVERY
+       * `getSession()` call hits this path for real, so a Redis blip
+       * manufactured a `200 { session: null }` for every live session at
+       * once — the exact channel 183483's client-side guard (verify-code
+       * page's session-liveness check) was built to survive, and the one it
+       * could not survive while this swallow stood: a fabricated "no
+       * session" 200 is not distinguishable from a real one by any client.
+       *
+       * Letting the error propagate is safe: better-auth's own router
+       * (better-call/dist/router.mjs) wraps every endpoint handler in a
+       * top-level try/catch and converts an uncaught throw to a genuine
+       * `500`, not a crash. A `500` IS the "inconclusive" signal 183483's
+       * corrected client guard already knows how to hold a session through —
+       * so a Redis outage now surfaces as "couldn't check" instead of
+       * silently lying "confirmed logged out".
+       */
+      get: async (key: string) => {
+        const value = await getRedis().get(`ba:${appSlug}:${key}`);
+        // 185121 line 2: the 183047 discriminator. A null here means
+        // RECORD-MISS — the store was reachable and the key is absent. If the
+        // record IS present but BA still rejects the session, this line does
+        // NOT fire and the failure is upstream of storage (HMAC/secret gate).
+        // BA-primary logs nothing on failure, so without this line the two
+        // surviving forks are indistinguishable in the artifact. Key is
+        // fingerprinted: it embeds the session token.
+        if (value === null) {
+          console.warn(
+            `[BETTER_AUTH] secondaryStorage.get MISS ba:${appSlug}:sha256:${secretFingerprint(key)} — record absent, store reachable`
+          );
+        }
+        return value;
+      },
+      /**
+       * 170033 fix 1 — DO NOT SWALLOW A FAILED WRITE. A SESSION THAT WAS NOT
+       * PERSISTED IS NOT A SESSION.
+       *
+       * This previously caught every Redis error and returned normally, so
+       * better-auth was told the session had been stored when nothing had been
+       * written. The user got a successful login, a session cookie, and a
+       * rendered signed-in shell on top of a store that holds no session — and
+       * the very next `getSession()` reads `null` and signs them straight back
+       * out. Nothing logged, nothing thrown, no banner: a login that "worked"
+       * and a sign-out nobody can explain.
+       *
+       * Letting it propagate is the same contract `get` above already relies on:
+       * better-auth's router (better-call/dist/router.mjs) wraps every endpoint
+       * handler and converts an uncaught throw into a genuine 500. A 500 on the
+       * login write is honest — "we could not store your session" — and it is
+       * distinguishable by any client from a successful login, which a swallowed
+       * failure is not.
+       *
+       * THE COMMENT THIS REPLACES SAID "Redis unavailable — cookie cache still
+       * works". It does not: `session.cookieCache.enabled` is FALSE (see below).
+       * The comment described a safety net that had been removed, which is why
+       * this swallow looked survivable to every reader who trusted it (170033
+       * fix 3).
+       */
+      set: async (key: string, value: string, ttl?: number) => {
+        const redis = getRedis();
+        const redisKey = `ba:${appSlug}:${key}`;
+
+        /**
+         * 273183 — READ-MODIFY-WRITE, BECAUSE THIS RECORD HAS TWO AUTHORS.
+         * (Found by DotNetPert-Scout; handed over as Cluster-B root-cause
+         * evidence under BAPert's R920(a). Reproduced here before fixing.)
+         *
+         * Better Auth owns `{session, user}` and serialises exactly that. But
+         * `storeIdpTokensInSession` (below, ~:1010) ENRICHES the same key with
+         * `idpTokens` via its own read-modify-write. This setter did a blind
+         * `setex` of Better Auth's payload, so every write it makes — including
+         * each routine `updateAge` session rewrite, not merely an expiry —
+         * STRIPPED `idpTokens` back off the record.
+         *
+         * The consumer then falls back to an identity husk: `mfaVerified:false`,
+         * `roles:[]`. It fails CLOSED, so it is not a 369782-class bypass — but
+         * per BAPert it is a public-test blocker on its own terms, because a
+         * tester who trips the `updateAge` cadence gets a spurious 2FA re-prompt
+         * AND SILENTLY LOSES THEIR ROLES mid-session. That is a visible product
+         * failure regardless of which direction it fails in.
+         *
+         * WHY MERGE HERE RATHER THAN MOVE THE DATA. The enriching writer already
+         * does a read-modify-write; it was correct. The bug is that ONE of the
+         * two authors of this key wrote as though it were the only one. Fixing
+         * the adapter fixes it for every future enrichment key, whereas moving
+         * `idpTokens` elsewhere would leave the next one to rediscover this.
+         *
+         * ONLY keys in PRESERVED_KEYS are carried, and ONLY when the incoming
+         * payload does not set them — so Better Auth still wins on everything it
+         * owns, and an explicit incoming value is never overridden by a stale one.
+         *
+         * NOT ATOMIC, and deliberately not: an enrichment landing between this
+         * read and this write is still lost. Closing that needs a WATCH/MULTI or
+         * a Lua script, which is a larger change than tonight allows. This
+         * narrows the window from "every single write" to "a genuine race", and
+         * the residual is recorded here rather than left to be re-found.
+         */
+        let payload = value;
+        try {
+          const existingRaw = await redis.get(redisKey);
+          if (existingRaw) {
+            const existing = JSON.parse(existingRaw);
+            const incoming = JSON.parse(value);
+            if (isPlainObject(existing) && isPlainObject(incoming)) {
+              let carried = false;
+              for (const preserved of PRESERVED_SESSION_KEYS) {
+                if (preserved in existing && !(preserved in incoming)) {
+                  incoming[preserved] = existing[preserved];
+                  carried = true;
+                }
+              }
+              if (carried) payload = JSON.stringify(incoming);
+            }
+          }
+        } catch (mergeErr) {
+          /**
+           * This adapter also stores `verification:*` and `active-sessions-*`
+           * records, which are not necessarily session-shaped JSON. A record we
+           * cannot parse is not a session to enrich, so writing through unchanged
+           * is correct rather than merely tolerable.
+           *
+           * WARNED, NOT THROWN, and the asymmetry is the point: this block is an
+           * ENRICHMENT-PRESERVING read. Letting it fail the write would convert a
+           * degraded read into a lost session — the precise inversion 170033 fix 1
+           * above exists to prevent. The `setex` below is outside this try and is
+           * still unswallowed, so a genuine write failure still propagates.
+           */
+          console.warn(
+            `[BETTER_AUTH] secondaryStorage.set: could not preserve enrichment keys on ` +
+            `ba:${appSlug}:sha256:${secretFingerprint(key)} — writing Better Auth's payload ` +
+            `as-is. If this record held idpTokens they are now gone (273183):`,
+            mergeErr instanceof Error ? mergeErr.message : String(mergeErr)
+          );
+        }
+
+        /**
+         * QA 6952 / R913 - CLAMP, DO NOT DEFER.
+         *
+         * This was `ttl ?? SESSION_TTL`, which READS as "SESSION_TTL is the single
+         * source of session TTL" - what session-store.ts claims, and the mechanism
+         * by which the 7d-vs-3d zombie window was supposedly closed for good.
+         *
+         * IT WAS DEAD CODE. Better Auth ALWAYS supplies a ttl: every one of the
+         * eight secondaryStorage.set call sites in
+         * better-auth/dist/db/internal-adapter.mjs passes one explicitly (:36,
+         * :180, :189, :309, :320, :344, :553, :622). `??` fires only on
+         * null/undefined, so the fallback NEVER RAN. Every `ba:` record took Better
+         * Auth's 7d default - `session.expiresIn` is not configured in this file -
+         * while the canonical store stayed at SESSION_TTL (3d). That 4-day drift IS
+         * the zombie window the constant exists to prevent: the guard was bypassed
+         * by the very parameter written to defer to it.
+         *
+         * `Math.min`, NOT a hard SESSION_TTL: this same adapter also stores
+         * `verification:*` (:553, :622) and `active-sessions-*` (:180, :320, :344)
+         * records whose TTLs are legitimately SHORTER than 3d. Overwriting those
+         * would EXTEND them - turning a fix for over-long sessions into a bug that
+         * keeps verification codes alive for three days. Clamp DOWN, never up.
+         *
+         * Clamped down to 3d rather than raising the canonical store to 7d because
+         * SESSION_TTL matches the IDP refresh-token lifetime: a session outliving
+         * the refresh token sustaining it cannot be refreshed, so the extra days are
+         * a husk that reads as authenticated. Fail-closed beats ambiguous.
+         *
+         * DO NOT "fix" this by making storeIdpTokensInSession preserve Better
+         * Auth's 7d. That deletes the last remnant of QA 6952 and makes the drift
+         * universal. See test/ba-session-ttl-clamp.test.cjs.
+         */
+        await redis.setex(redisKey, Math.min(ttl ?? SESSION_TTL, SESSION_TTL), payload);
+      },
+      delete: async (key: string) => {
+        try {
+          await getRedis().del(`ba:${appSlug}:${key}`);
+        } catch (err) {
+          /**
+           * 170033 fix 2 — a failed delete must be VISIBLE, not `/* ignore *\/`.
+           *
+           * Deliberately logged rather than thrown, and the distinction is not
+           * timidity: the CANONICAL store is what decides session liveness (see
+           * 181922 below), and its delete runs immediately after this one and is
+           * NOT swallowed. So a BA record that outlives its canonical twin does
+           * not authenticate anyone — throwing here would fail a sign-out that
+           * actually succeeded where it counts.
+           *
+           * What was unacceptable is that it happened SILENTLY. A revocation
+           * that half-failed left no trace anywhere, so the leftover key could
+           * only ever be found by someone already reading the keyspace for
+           * another reason. `error`, not `warn`: this is a revocation that did
+           * not complete, not a retryable blip.
+           */
+          console.error(
+            `[BETTER_AUTH] secondary delete FAILED for ba:${appSlug}:${key} — ` +
+            `the better-auth session record may still exist. Canonical delete ` +
+            `below is what governs liveness; if it also failed, the session is ` +
+            `NOT revoked:`,
+            err
+          );
+        }
+        /**
+         * 181922 — teardown is BOTH stores. BA's sign-out deletes only its
+         * secondary record; the canonical {slug}:sess:{token} would survive
+         * and keep the session alive (a replayed cookie still authenticates).
+         * `key` here IS the session token (the ba: prefix is applied above),
+         * so the canonical delete is one call. This also fires on session
+         * rotation/expiry deletions, which is correct: a session BA drops
+         * must not live on in the canonical store.
+         */
+        try {
+          const { deleteSession } = await import('../lib/session-store');
+          await deleteSession(key);
+        } catch (err) {
+          console.warn('[BETTER_AUTH] secondary delete: canonical store cleanup failed:', err);
+        }
+      },
+    },
+
+    session: {
+      // Cookie cache DISABLED — Redis is canonical for session liveness.
+      //
+      // Previously: enabled with maxAge 300 + refreshCache false. That cached
+      // a decoded session in process memory for 5 minutes, bypassing Redis
+      // reads during the window. Consequence: if the canonical app session
+      // at `{slug}:{token}` was evicted, refreshed, or rotated mid-window,
+      // Better Auth's in-memory copy stayed alive — and callers got
+      // contradictory answers depending on whether they consulted Better
+      // Auth (alive per cache) or Redis (dead/rotated). Documented contradiction
+      // visible in production traces: viability 200 + idp-token 200 +
+      // getFreshIdpToken NO_SESSION terminal within milliseconds.
+      //
+      // Trade-off: every Better Auth getSession() call now incurs one Redis
+      // read on the secondary-storage path. Latency cost is acceptable
+      // (sub-ms in-region) and the alternative is duplicate Layer-1
+      // workarounds in every consumer app — already shipped in idealvibe.online
+      // at b6a91f6.
+      cookieCache: {
+        enabled: false,
+        maxAge: 300,
+        refreshCache: false,
+      },
+    },
+
+    // PAY-1781 B: KEEP OAUTH STATE IN THE ENCRYPTED COOKIE, as it was on better-auth 1.5.6.
+    // 1.5.6 resolved the default as `options.database ? 'database' : 'cookie'` - we have no
+    // database, so: cookie. 1.6.13+ resolves it as `(database || secondaryStorage) ? 'database'
+    // : 'cookie'`, and we DO have secondaryStorage, so the upgrade alone would silently move every
+    // OAuth state record into Redis through the adapter above (its enrichment read-modify-write
+    // and key handling were built for session records, not state). Pinned so the upgrade changes
+    // the version, not the design. The cookie branch is where GHSA-wxw3-q3m9-c3jr lived; 1.6.2+
+    // compares the returned `state` with the nonce sealed in the cookie, and our provider is also
+    // pkce:true, which the advisory required to be false. Test: oauth-state-strategy-cookie.
+    account: {
+      storeStateStrategy: 'cookie',
+    },
+
+    // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
+    advanced: {
+      cookiePrefix: appSlug,
+      cookies: {
+        session_token: {
+          name: `${appSlug}.session-token`,
+        },
+      },
+    },
+
+    plugins: [
+      nextCookies(),
+      // Exchange-move: present ONLY when the IDP's OAuth endpoints are
+      // configured. Absent otherwise, so this cannot alter existing behaviour.
+      ...(idpOAuth ? [genericOAuth({ config: [idpOAuth] })] : []),
+      ...(opts.magicLink ? [magicLink(opts.magicLink)] : []),
+      // App-supplied plugins last: they may depend on the built-ins above, and
+      // ordering is BA's own concern once they are in the array.
+      ...(opts.plugins ?? []),
+    ],
+  });
+}
+
+/**
+ * Better Auth is always enabled (NextAuth removed in 4.0).
+ */
+export function isBetterAuthEnabled(): boolean {
+  return true;
+}
+
+/**
+ * Get Better Auth Next.js route handlers (GET, POST).
+ * Initializes Better Auth from IDP config on first call, caches the instance.
+ *
+ * STATE LIVES ON globalThis, NOT IN MODULE SCOPE (181814, measured 2026-08-07):
+ * under Turbopack, instrumentation.ts and the /api/auth/[...all] route are
+ * different chunks and each loads its OWN copy of this module. Module-level
+ * `configuredOpts` set by configureBetterAuth() in instrumentation never
+ * reached the copy getBetterAuthInstance() read in the route — measured
+ * identity probe: sameInstance=false, route-side plugins=["next-cookies"]
+ * while the instrumentation-side instance carried every configured plugin.
+ * No throw anywhere (the double-init guard never sees the other copy), core
+ * auth green, plugin routes 404. globalThis is per-process, per-runtime —
+ * exactly the scope this state must have.
+ */
+interface BetterAuthModuleState {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  cachedInstance: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initPromise: Promise<any> | null;
+  // PAY-642: the init attempt, single-flighted so a REJECTED attempt clears itself (see getBetterAuthInstance).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initFlight?: SingleFlight<any>;
+  configuredOpts: CreateBetterAuthInstanceOptions;
+}
+
+const STATE_KEY = '__payezBetterAuthState';
+const g = globalThis as unknown as Record<string, BetterAuthModuleState | undefined>;
+g[STATE_KEY] ??= { cachedInstance: null, initPromise: null, configuredOpts: {} };
+const state = g[STATE_KEY];
+
+// Expose for server-side session access (decode-session.ts). A getter so the
+// export tracks the SHARED state, not a chunk-local snapshot.
+export function __getBetterAuthInstance(): unknown {
+  return state.cachedInstance;
+}
+
+/**
+ * Configure Better Auth instance options for this process.
+ *
+ * Must be called before the first auth request — before
+ * `getBetterAuthInstance()` caches an instance. Typically called once at
+ * app startup, e.g. from Next.js `instrumentation.ts` or an equivalent
+ * server bootstrap hook.
+ *
+ * Throws if called after the instance has already been resolved: options
+ * cannot be applied retroactively.
+ */
+export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void {
+  if (state.cachedInstance) {
+    throw new Error(
+      '[BETTER_AUTH] configureBetterAuth() must run before the instance is first resolved. ' +
+      'Call it in Next.js instrumentation.ts or an equivalent startup hook.'
+    );
+  }
+  state.configuredOpts = opts;
+}
+
+/**
+ * PAY-642 (card 338215): the init attempt no longer LATCHES A FAILURE.
+ *
+ * This used to be `state.initPromise ??= getIDPClientConfig(true).then(...)` with no .catch and no reset. One
+ * auth request against a cold process while the IdP was unreachable stored a rejected promise, and every later
+ * caller replayed it until the process restarted, even after the IdP recovered. This funnel backs every
+ * /api/auth/* route, the login GET handler and withAuth. server/auth.ts getAuthInstance() already used
+ * createSingleFlight for this exact bug; this sibling funnel was missed.
+ *
+ * Now the attempt runs through the same helper: concurrent callers share one attempt, a failure still rejects
+ * for every caller of THAT attempt (loud), the next call starts a fresh attempt, and a success is cached in
+ * state.cachedInstance as before. The flight lives on the globalThis state for the same reason the instance
+ * does (duplicated route chunks must share one init).
+ */
+export async function getBetterAuthInstance() {
+  if (state.cachedInstance) return state.cachedInstance;
+
+  state.initFlight ??= createSingleFlight(() =>
+    getIDPClientConfig(true).then(config => {
+      const instance = createBetterAuthInstance(config, state.configuredOpts);
+      state.cachedInstance = instance;
+      console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
+      return instance;
+    })
+  );
+
+  const attempt = state.initFlight.get();
+  // Kept for callers that inspect it; it always points at the CURRENT attempt, never a settled failure.
+  state.initPromise = attempt;
+  return attempt;
+}
+
+/**
+ * Get flag-gated auth handler for Next.js route.
+ *
+ * When USE_BETTER_AUTH=true, returns Better Auth handlers.
+ * Otherwise returns null (auth disabled).
+ *
+ * Usage in host app route:
+ * ```ts
+ * import { getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
+ *
+ * export async function GET(req: Request) {
+ *   const ba = await getBetterAuthHandler();
+ *   if (ba) return ba.GET(req);
+ * }
+ * ```
+ */
+export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> } | null> {
+  if (!isBetterAuthEnabled()) return null;
+
+  const auth = await getBetterAuthInstance();
+  // PAY-2217: Better Auth's native endpoints (get-session, list-sessions, sign-in/*, sign-up/*) put the session
+  // token in the body. Strip it at the HTTP boundary here, so every consumer that mounts this handler gets it;
+  // auth.api (server-side) is untouched and still sees the token. See session-response-sanitizer.ts.
+  return wrapBetterAuthHandler(auth as any, toNextJsHandler(auth));
+}
+
+/**
+ * Exchange OAuth identity for IDP tokens and store in the BA Redis session.
+ *
+ * Call this from the OAuth callback route AFTER better-auth has processed the
+ * callback and created the session. Reads the session token from the Set-Cookie
+ * header of the response to find the BA Redis key.
+ *
+ * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
+ *
+ * RETURNS the IdP's own error code on an IDP refusal, or null otherwise
+ * (PAY-2005 scenario (b), BAPert ruling 67897). It used to return a bare
+ * boolean, so `REGISTRATION_NOT_ALLOWED` was indistinguishable from a network
+ * blip and every cause collapsed to one generic login-page code — a NEW user
+ * refused registration bounced silently, which is the failure Jon named.
+ */
+export async function exchangeOAuthForIdpTokens(
+  sessionToken: string,
+  provider: string = 'google'
+): Promise<boolean | string> {
+  try {
+    const config = await getIDPClientConfig();
+    const appSlug = config.clientSlug || getAppSlug();
+    const baKey = `ba:${appSlug}:${sessionToken}`;
+
+    // Read the BA session from Redis
+    const baRaw = await getRedis().get(baKey).catch(() => null);
+    if (!baRaw) {
+      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', tokenLogId(sessionToken));
+      return false;
+    }
+
+    const baData = JSON.parse(baRaw);
+    const email = baData?.user?.email;
+    const name = baData?.user?.name;
+    const image = baData?.user?.image;
+    const baUserId = baData?.session?.userId || baData?.user?.id;
+
+    if (!email) {
+      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: no email in session');
+      return false;
+    }
+
+    // Call IDP oauth-callback
+    const idpUrl = process.env.IDP_URL || '';
+    if (!idpUrl) {
+      console.warn('[BETTER_AUTH] No IDP_URL configured, skipping token exchange');
+      return false;
+    }
+
+    console.log('[BETTER_AUTH] Exchanging OAuth identity for IDP tokens:', email);
+
+    const oauthRes = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        provider,
+        provider_account_id: email,  // Cross-System Identity Standard v1.1: always use verified email, never opaque session IDs
+        email,
+        name,
+        image,
+        client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? '',
+        /**
+         * Card 138635 — the RAW provider id_token, forwarded verbatim.
+         *
+         * Every other field in this body is an ASSERTION. The endpoint mints an
+         * IDP bearer from them today with no cryptographic check of any kind,
+         * which is why it is a complete authentication bypass and why it has
+         * been publicly reachable for 488 days.
+         *
+         * This field is the only one the IDP can VERIFY: signature against
+         * Google's JWKS, plus iss / exp / aud, and then read email_verified
+         * from the verified claims. Additive — the IDP ignores it until its
+         * gate flips, so this cannot break a login on its own.
+         *
+         * RAW, AND NOTHING DERIVED FROM IT (BAPert's ruling). We do NOT send a
+         * decoded email_verified. A client-computed verification flag is a body
+         * field with a better story: an attacker posts email_verified:true and
+         * the defect is rebuilt one layer up. The IDP verifies for itself or
+         * the fix is theatre.
+         *
+         * Absent when this runs outside the OAuth callback scope — the key is
+         * simply omitted rather than sent null, so "we never captured one" stays
+         * distinguishable from "the provider issued none".
+         */
+        ...(idTokenScope.getStore()?.idToken ? { id_token: idTokenScope.getStore()!.idToken } : {}),
+        /**
+         * The same field for providers that have no id_token to give.
+         *
+         * Identical doctrine to the id_token above: RAW, forwarded verbatim,
+         * NOTHING DERIVED FROM IT, and omitted entirely rather than sent null so
+         * "never captured" stays distinguishable from "provider issued none".
+         * The IDP verifies for itself by calling GitHub with this token and
+         * enforcing primary && verified; we assert nothing about the identity.
+         *
+         * Scoped to the provider access token captured during THIS callback, so
+         * a google login continues to send id_token only and is unaffected.
+         */
+        ...(idTokenScope.getStore()?.accessToken
+          ? { access_token: idTokenScope.getStore()!.accessToken }
+          : {}),
+      }),
+    });
+
+    const oauthResText = await oauthRes.text();
+    // PAY-1427 (QAPert, PR 154 thread 326): this printed the first 500 chars of the oauth-callback TOKEN
+    // envelope on EVERY successful OAuth login (it runs before the !ok check). Status + length only.
+    console.log('[BETTER_AUTH] IDP oauth-callback response:', { status: oauthRes.status, bodyLength: oauthResText.length });
+
+    if (!oauthRes.ok) {
+      console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
+
+      /**
+       * PAY-2005 scenario (b) — RETURN THE IDP'S ERROR CODE (BAPert ruling 67897).
+       *
+       * Every refusal used to return a bare `false`, so the abort collapsed ALL
+       * causes to one generic `OAUTH_SIGN_IN_FAILED`: a NEW user refused
+       * registration (`REGISTRATION_NOT_ALLOWED`, ExternalAuthController.cs:908)
+       * bounced silently, indistinguishable from a network blip. Jon named the
+       * clear message explicitly (67856): "(b) a brand-new Google user with
+       * registration OFF is refused by the IDP with a clear message, not a
+       * silent bounce."
+       *
+       * The envelope is `{ error: { code, message } }` (PayEzControllerBase.Error).
+       * We read ONLY `error.code` and return it VERBATIM — the abort puts it in
+       * the `?error=` param, and the HOST's allowlist decides whether to render
+       * it. The package does NOT interpret the code and does NOT add a message
+       * (that would be a second allowlist). No code in the body -> null (the
+       * generic host code), exactly as before.
+       */
+      let idpErrorCode: string | null = null;
+      try {
+        const parsed = JSON.parse(oauthResText);
+        // FORWARD ONLY AN ALLOWLISTED CODE. Every other refusal keeps PAY-1733's single neutral code — an
+        // unlisted code would render nothing on the host page, which is the silent bounce this exists to end.
+        if (typeof parsed?.error?.code === 'string' && IDP_ERROR_CODES_TO_FORWARD.has(parsed.error.code)) {
+          idpErrorCode = parsed.error.code;
+        }
+      } catch {
+        /* non-JSON refusal body -> no code (generic abort) */
+      }
+
+      /**
+       * WHY THIS LOGS ONLY ON FAILURE, AND WHY IT LOGS THESE FIELDS.
+       *
+       * UNVERIFIED_ASSERTION has exactly two causes and the response body cannot tell
+       * them apart: we sent no id_token for the IDP to verify, or we sent one whose
+       * signature/aud/iss the IDP rejected. Without this line the operator sees a 401 on
+       * a login that visibly succeeded and has nowhere to go — which is where UMI sat on
+       * 2026-08-26.
+       *
+       * NEVER THE TOKEN ITSELF. An id_token is credential material and this whole code
+       * path exists to keep it out of anything persistent; a log file is persistent. We
+       * print presence, length, and the three claims that decide verification. `aud` is
+       * the Google client id — not a secret, and the single most likely mismatch, since
+       * the IDP checks it against what IT has registered for this client.
+       */
+      const forwarded = idTokenScope.getStore()?.idToken;
+      let claims: Record<string, unknown> = {};
+      if (forwarded) {
+        try {
+          claims = decodeJwt(forwarded) as Record<string, unknown>;
+        } catch {
+          claims = { decode: 'FAILED — not a well-formed JWT' };
+        }
+      }
+      const forwardedAccess = idTokenScope.getStore()?.accessToken;
+      console.error('[BETTER_AUTH] exchange diagnostics:', {
+        id_token_forwarded: !!forwarded,
+        id_token_length: forwarded ? forwarded.length : 0,
+        /**
+         * Read these two for github, and IGNORE the id_token pair above: github
+         * issues no id_token, so `id_token_forwarded: false` is its NORMAL state
+         * and not the fault. Presence and length only — an access token is
+         * credential material and this log is persistent. A github failure with
+         * access_token_forwarded:true means the IDP called GitHub and refused
+         * the answer (unverified or non-primary email, or app not installed);
+         * false means the capture hook never ran and the IDP never called out.
+         */
+        access_token_forwarded: !!forwardedAccess,
+        access_token_length: forwardedAccess ? forwardedAccess.length : 0,
+        // Absent id_token => the IDP had nothing to verify. Present => compare these
+        // against the client's registered Google credentials on the IDP.
+        aud: claims.aud ?? null,
+        iss: claims.iss ?? null,
+        email_verified: claims.email_verified ?? null,
+        sent_client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? null,
+        idp_url: idpUrl,
+      });
+      return idpErrorCode ?? false;
+    }
+
+    let idpData: any;
+    try { idpData = JSON.parse(oauthResText); } catch { return false; }
+    const result = idpData?.data?.result || idpData?.data || idpData;
+
+    if (!result?.access_token) {
+      console.warn('[BETTER_AUTH] IDP oauth-callback returned no access_token. Keys:', Object.keys(result || {}));
+      return false;
+
+    }
+
+    // Build IDP token data
+    //
+    // 170007 CONTRACT (BAPert ruling on 121350, agreed with DotNetPert
+    // 2026-08-08 — see mail thread, not re-derived here):
+    //   1. The IDP emits `requires_two_factor` (snake_case, both serializers,
+    //      per the estate law) as a NON-NULLABLE bool on OAuthCallbackResponse
+    //      (PayEz.DTOs OAuthCallbackResponse.cs) — ALWAYS present. No IDP
+    //      change needed or wanted: emitting a second, camelCase name for the
+    //      same fact would be the dialect problem the estate law exists to
+    //      prevent, not a fix.
+    //   2. Read requires_two_factor (snake) ONLY. CORRECTED mid-review:
+    //      BAPert's first draft of this contract said "read both casings,
+    //      defensively" — DotNetPert rejected that: a dual-casing client-side
+    //      read gives one fact two wire names just as surely as a dual-casing
+    //      IDP emit would, and it is the exact audience-dialect mistake
+    //      (186443) made deliberately instead of by accident. This package
+    //      previously read camel ONLY (card 170083, now corrected — it must
+    //      NOT record "emit both casings" as the IDP-side fix), which is why
+    //      this line silently fell through to the heuristic below on every
+    //      real call. The fix is reading the one name the IDP actually sends,
+    //      not tolerating both.
+    //   3. The old !hasRefreshToken fallback (IDP-2FA-BUG below) is RETIRED,
+    //      not patched. DotNetPert traced ExternalAuthController's
+    //      oauth-callback: IssueRefreshToken and RequiresTwoFactor both derive
+    //      from the SAME isFullyAuthenticated variable, so they cannot
+    //      disagree on this path — the divergence this fallback existed for
+    //      is not present here. Worse, the heuristic would currently produce
+    //      the RIGHT answer by coincidence, which hides the day it stops
+    //      being derived from one variable.
+    //   4. requires_two_factor is non-nullable, so reaching the `true`
+    //      default below means the response ISN'T an OAuthCallbackResponse at
+    //      all (wrong endpoint / error body / failed parse) — logged as that,
+    //      not as "2FA status unknown". Fail-closed to requiresTwoFactor=true
+    //      either way (rule 3).
+    //   5. mfaVerified = !requiresTwoFactor, computed fresh from THIS
+    //      response — no hardcoding, no carrying a prior session value
+    //      forward (that half of the monotonic-OR defect lived in
+    //      refresh.ts / ensure-fresh-access-token.ts, fixed separately).
+    //
+    // PRIOR STATE, for the record: this used to hardcode mfaVerified=false on
+    // every OAuth exchange as a blunt workaround for a since-disproven IDP
+    // bug, which itself caused every Google user to be sent to /mfa even on
+    // require_2fa=FALSE tenants (NextPert 13450's blocker, failing T4 on the
+    // demo tenant). That workaround is removed along with the bug it worked
+    // around.
+    const requiresTwoFactor: boolean = (() => {
+      // SNAKE ONLY (BAPert's corrected ruling, 2026-08-08): reading camel as
+      // a "defensive" secondary would give one fact two wire names — exactly
+      // the audience-dialect mistake (186443) being made deliberately. The
+      // estate law is explicit-snake-per-field-both-serializers; the IDP
+      // already complies (OAuthCallbackResponse.cs, both System.Text.Json
+      // and Newtonsoft). No IDP change, no camel read, no dual-casing.
+      const v = result.requires_two_factor ?? result.user?.requires_two_factor;
+      if (v === undefined) {
+        console.warn(
+          '[BETTER_AUTH] oauth-callback response has no requires_two_factor field at all — ' +
+            'unexpected response shape (requires_two_factor is non-nullable on OAuthCallbackResponse; ' +
+            'this is not "2FA status unknown", it means we are not looking at an oauth-callback response). ' +
+            'Defaulting requiresTwoFactor=true (fail closed).',
+        );
+        return true;
+      }
+      return !!v;
+    })();
+    const idpTokenData = {
+      idpAccessToken: result.access_token,
+      idpRefreshToken: result.refresh_token,
+      idpAccessTokenExpires: result.expires_in
+        ? Date.now() + result.expires_in * 1000
+        : Date.now() + 15 * 60 * 1000,
+      userId: String(result.user?.user_id || result.user?.id || result.user_id || baUserId),
+      email: result.user?.email || result.email || email,
+      name: result.user?.full_name || result.user?.name || result.name || name,
+      image: image,
+      roles: result.user?.roles || result.roles || [],
+      mfaVerified: !requiresTwoFactor, // re-derived fresh — see 170007 contract above
+      // Cards 141688/141741 — RELAYED, NOT DERIVED.
+      //
+      // The IDP already decides this (ExternalAuthController:943 and :2024,
+      // WO 113023): "enroll_mfa" = no CONFIRMED method, "mfa_verify" = a
+      // confirmed method exists, null = fully authenticated. It was emitted
+      // here and dropped on this line — `idpTokenData` is built field-by-field,
+      // so anything not named is silently discarded. Both downstream consumers
+      // (the middleware gate and the verify-code page) then reasoned in its
+      // absence and sent zero-method users to a page they cannot act on.
+      //
+      // WIRE NAME IS SNAKE: `next_step`, per [JsonPropertyName("next_step")] on
+      // BOTH OAuthCallbackResponse and ExternalTokenResponse. Reading
+      // `result.nextStep` here would be `undefined` forever and fail silently —
+      // the same camel/snake break `requires_two_factor` already cost us once.
+      //
+      // Do NOT recompute this from a method query. The IDP owns the fact; it is
+      // already usable-aware (confirmed and not revoked, per DotNetPert), which
+      // is the distinction that decides correctness: a revoked-TOTP user has
+      // count>0 but usable=0, and deriving it locally would let through exactly
+      // the users we must challenge.
+      // No `?? null`: if the response has no `next_step` at all (older IDP
+      // build, or a path that does not set it), that is UNKNOWN, not "fully
+      // authenticated". Defaulting it to null here would manufacture a
+      // clean-bill-of-health the IDP never gave and fail open at the gate.
+      nextStep: result.next_step,
+      idpClientId: result.client_id ? String(result.client_id) : undefined,
+      merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
+    };
+
+    // Storage is shared with the passkey sign-in path — see storeIdpTokensInSession.
+    const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
+    if (stored) console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
+    // true = success (tokens stored). false = a non-IdP failure with no specific code (generic abort).
+    return stored;
+  } catch (err) {
+    console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
+    return false;
+  }
+}
+
+
+/**
+ * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
+ * function never acquires tokens and never decides who the caller is.
+ *
+ * ── WHY THIS IS SPLIT OUT (BAPert ruling, 2026-08-04) ────────────────────────
+ *
+ * `exchangeOAuthForIdpTokens` above does TWO things: it ACQUIRES tokens by
+ * POSTing to `/api/ExternalAuth/oauth-callback`, and then it STORES them. Only
+ * the second half is reusable, and the first half is actively dangerous to
+ * reuse:
+ *
+ *   oauth-callback mints an IDP bearer from an ASSERTED EMAIL with no
+ *   cryptographic verification of any kind (card 138635).
+ *
+ * Passkey sign-in already holds something strictly better — a grant issued by
+ * `/api/ExternalAuth/passwordless/passkey/verify`, which checked a real
+ * signature against a registered credential. Routing that through
+ * oauth-callback to obtain a session would DOWNGRADE a cryptographically
+ * verified assertion into an unverified one, make passkey sign-in weaker than
+ * its own ceremony, and inherit 138635 wholesale.
+ *
+ * That is not hypothetical: "do what the OAuth path does" is the obvious
+ * implementation and it is the wrong one. Splitting acquisition from storage is
+ * what makes the wrong one hard to write by accident.
+ *
+ * ── WHAT CALLERS MUST HAVE DONE FIRST ───────────────────────────────────────
+ *
+ * A Better Auth session must ALREADY EXIST for `sessionToken`. This function
+ * enriches; it does not create. Better Auth owns session creation and cookie
+ * signing, and nothing in this package should replicate either — the cookie is
+ * `{token}.{base64(hmac)}` with standard padding, signed with the runtime
+ * `authSecret` from Redis, and hand-rolling that produces a session which
+ * decodes but does not authenticate.
+ *
+ * @param sessionToken  the Better Auth session token (from its Set-Cookie)
+ * @param idpTokenData  tokens + identity, already obtained by the CALLER'S OWN
+ *                      verified route. Built field-by-field by the caller so an
+ *                      unnamed field cannot ride along silently.
+ * @param authProvider  provenance label recorded on the canonical row. Written
+ *                      to the historical `oauthProvider` key, which predates
+ *                      non-OAuth callers; the NAME is legacy, the VALUE should
+ *                      state what actually authenticated ('passkey', 'google').
+ */
+export async function storeIdpTokensInSession(
+  sessionToken: string,
+  idpTokenData: Record<string, unknown>,
+  authProvider: string,
+): Promise<boolean> {
+  try {
+    const config = await getIDPClientConfig();
+    const appSlug = config.clientSlug || getAppSlug();
+    const baKey = `ba:${appSlug}:${sessionToken}`;
+
+    const baRaw = await getRedis().get(baKey).catch(() => null);
+    if (!baRaw) {
+      // No session to enrich. Do NOT create one as a fallback: a session
+      // conjured here would carry no Better Auth cookie, so it would be
+      // unreachable by the browser and invisible to every other consumer —
+      // failing as "silently signed out" rather than as an error.
+      console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', tokenLogId(sessionToken));
+      return false;
+    }
+
+    const baData = JSON.parse(baRaw);
+    baData.idpTokens = idpTokenData;
+    await getRedis().setex(baKey, SESSION_TTL, JSON.stringify(baData));
+
+    // Canonical store — the key getSession() reads, used by the refresh handler
+    // and token lifecycle. A failure here leaves the BA session correct and the
+    // canonical row missing, so it is warned and not fatal: the user is signed
+    // in, and refresh degrades rather than the sign-in failing outright.
+    try {
+      const { getSessionPrefix } = await import('../lib/app-slug');
+      const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
+      await getRedis().setex(canonicalKey, SESSION_TTL, JSON.stringify({
+        ...idpTokenData,
+        oauthProvider: authProvider,
+      }));
+    } catch (canonicalErr) {
+      console.warn('[BETTER_AUTH] Failed to write canonical session:', canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr));
+    }
+
+    return true;
+  } catch (err) {
+    console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
+    return false;
+  }
+}
+
+/**
+ * The `?error=` code the login page receives when an OAuth sign-in is ABORTED because the IdP exchange did not
+ * store tokens (PAY-1733). Hosts map it to ONE neutral line; the card's words are "That sign-in didn't work.
+ * Try again or use another method." The cause stays in the server log, never on the page.
+ */
+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).
+ *
+ * Default stays PAY-1733's ONE neutral code: the cause of an ordinary failed exchange lives in the server
+ * log, never on the page. A code is forwarded ONLY when it earns a distinct user-facing message — today just
+ * the registration refusal, so a NEW Google user with registration OFF sees a clear "not open to sign-up"
+ * line instead of a silent bounce. Adding a code here REQUIRES a matching entry in the host allowlist
+ * (portal: src/lib/auth/magic-link-outcome.ts); an unlisted code renders nothing, which is a silent bounce
+ * wearing a different number. Add them together, never one alone.
+ */
+export const IDP_ERROR_CODES_TO_FORWARD: ReadonlySet<string> = new Set(['REGISTRATION_NOT_ALLOWED']);
+
+
+/**
+ * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
+ * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only
+ * accepted with Secure) and dropping Expires/Max-Age in favour of Max-Age=0.
+ */
+export function expireSetCookies(setCookies: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const sc of setCookies) {
+    const [pair, ...attrs] = sc.split(';').map((s) => s.trim());
+    const eq = pair.indexOf('=');
+    const name = eq > 0 ? pair.slice(0, eq) : '';
+    if (!name) continue;
+    const kept = attrs.filter((a) => /^(path|domain|secure|samesite|httponly)\b/i.test(a));
+    out.push([`${name}=`, ...kept, 'Max-Age=0'].join('; '));
+  }
+  return out;
+}
+
+/**
+ * PAY-1733 (Jon, live on :4797): ABORT an OAuth sign-in whose IdP exchange did not store tokens.
+ *
+ * Before this, a failed exchange was a console.error and the user kept the Better Auth session the callback had
+ * just created: signed in, holding NO IdP tokens. The host then routed that session to 2FA, which painted the
+ * user's email and failed every call - a red "sign in again" screen about an account the app could no longer
+ * authenticate. The IdP's 401 was CORRECT (it fail-closes unverified assertions); keeping the session was the bug.
+ *
+ * So: no session without IdP tokens. The Better Auth session is destroyed (its own signOut, best effort, then the
+ * `ba:<slug>:<token>` record directly - that record is what makes it resolvable), every cookie the callback set is
+ * expired, and the user goes to the login page with OAUTH_SIGN_IN_FAILED. Relative Location, as for the state-error
+ * branch above (328439: an absolute URL built from request.url is a dead tab in a container).
+ */
+async function abortOAuthSignIn(
+  callbackResponse: Response,
+  sessionToken: string | null,
+  cookieHeader: string,
+  loginPath: string,
+  errorCode: string = OAUTH_SIGN_IN_FAILED_ERROR,
+): Promise<Response> {
+  const headers = new Headers();
+  if (sessionToken) {
+    try {
+      const auth = await getBetterAuthInstance();
+      const out = await auth?.api?.signOut?.({ headers: new Headers({ cookie: cookieHeader }), asResponse: true });
+      for (const sc of (out as Response | undefined)?.headers?.getSetCookie?.() ?? []) headers.append('set-cookie', sc);
+    } catch (err) {
+      console.warn('[BETTER_AUTH] abort: Better Auth signOut failed, deleting the record directly:', err instanceof Error ? err.message : String(err));
+    }
+    try {
+      const config = await getIDPClientConfig();
+      await getRedis().del(`ba:${config.clientSlug || getAppSlug()}:${sessionToken}`);
+    } catch (err) {
+      console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', tokenLogId(sessionToken), err instanceof Error ? err.message : String(err));
+    }
+  }
+  for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? [])) headers.append('set-cookie', sc);
+  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${errorCode}`);
+  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)', 'code=' + errorCode);
+  return new Response(null, { status: 302, headers });
+}
+
+/**
+ * Create a production-ready GET handler for the auth catch-all route.
+ *
+ * Wraps better-auth's GET handler with:
+ * - OAuth state error recovery (redirects to login instead of error page)
+ * - IDP token exchange after successful OAuth callback - and, when it stores no tokens, the sign-in is ABORTED
+ *   (session destroyed, cookies expired, login page with OAUTH_SIGN_IN_FAILED; PAY-1733)
+ *
+ * Usage in host app:
+ * ```ts
+ * import { createAuthGetHandler, getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
+ * export const GET = createAuthGetHandler('/account-auth/login');
+ * export async function POST(req: Request) {
+ *   const ba = await getBetterAuthHandler();
+ *   return ba!.POST(req);
+ * }
+ * ```
+ */
+export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
+  return async function GET(request: Request): Promise<Response> {
+    // Card 138635: establish the request-scoped carrier for the provider's raw
+    // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
+    // hook that sees the token) and the exchange below (which forwards it).
+    // Wrapping the whole handler is what makes "never persisted" achievable —
+    // the token exists only for the life of this request.
+    return idTokenScope.run({}, async () => {
+    const ba = await getBetterAuthHandler();
+    if (!ba) {
+      return new Response('Auth handler not configured', { status: 500 });
+    }
+
+    const response = await ba.GET(request);
+
+    // Intercept auth errors (state mismatch, expired cookies) — redirect to login cleanly
+    if (response.status === 302) {
+      const location = response.headers.get('location') || '';
+      if (location.includes('/api/auth/error') || location.includes('please_restart')) {
+        console.warn('[BETTER_AUTH] OAuth state error, redirecting to login');
+        // *** DO NOT "TIDY" THIS BACK TO Response.redirect(). IT THROWS. (328439) ***
+        // Response.redirect() REQUIRES an absolute URL — measured, on the leg's own
+        // runtime and again on node 24:
+        //     Response.redirect('/account-auth/login', 302)
+        //       -> TypeError: Failed to parse URL from /account-auth/login
+        // That requirement is the whole cause of the bug this replaces. The old line
+        // was:
+        //     return Response.redirect(new URL(loginPath, request.url), 302);
+        // `request.url` inside a containerised Next standalone server carries the
+        // LISTEN address, not the address the browser used, so a container bound to
+        // 0.0.0.0:8080 handed the browser `http://0.0.0.0:8080/sign-in` — an address
+        // that can NEVER load (net::ERR_ADDRESS_INVALID, confirmed in a real browser
+        // by QAPert). Reload cannot recover it, because the address is invalid rather
+        // than down. It fired on the ORDINARY path: the oauth_state cookie is
+        // Max-Age=600, so anyone spending >10 minutes at Google's account chooser
+        // landed on a dead tab.
+        //
+        // A RELATIVE Location header is legal (RFC 7231 §7.1.2) and the browser
+        // resolves it against the origin it is ACTUALLY on, so no origin has to be
+        // guessed, configured, or derived from a header. This is the same shape the
+        // app's own middleware already emits successfully (307 + relative), which is
+        // why page redirects survived while this one did not.
+        //
+        // WHY NOT REBUILD FROM BETTER_AUTH_URL / rawBaseURL, the other proposal:
+        //   (a) rawBaseURL is NOT in scope here — it is a local inside
+        //       createBetterAuthInstance (~:397), a different function ~676 lines up.
+        //       Reaching it means recomputing the env precedence or exporting a
+        //       helper, i.e. more moving parts for a strictly worse result.
+        //   (b) It would reintroduce a guessed origin and make this path depend on
+        //       BETTER_AUTH_URL being set correctly per leg. Relative needs no env.
+        //   (c) Anything Host-derived would open host-header injection on a redirect
+        //       that is currently host-INVARIANT. Relative keeps that property.
+        //
+        // Works whether loginPath is relative (package default '/account-auth/login',
+        // and the graft passes '/sign-in') or absolute — an absolute Location is also
+        // legal, so a consumer passing a full URL still behaves.
+        return new Response(null, { status: 302, headers: { location: loginPath } });
+      }
+    }
+
+    // After the OAuth callback: exchange the provider identity for IDP tokens. If that does NOT store tokens - the
+    // IdP refused (401), no session was found, or anything threw - the sign-in is ABORTED (PAY-1733). A session is
+    // kept only when it holds IdP tokens.
+    const url = new URL(request.url);
+    if (url.pathname.includes('/callback/') && response.status === 302) {
+      const setCookies = response.headers.getSetCookie?.() || [];
+      const cookieHeader = setCookies
+        .map((c: string) => c.split(';')[0])
+        .join('; ');
+      let sessionToken: string | null = null;
+      // true = tokens stored; false = no specific IdP code (generic abort); a string = the IdP's own refusal code
+      // (PAY-2005 (b): REGISTRATION_NOT_ALLOWED, etc.), forwarded so the host can show a clear message.
+      let exchange: boolean | string = false;
+      try {
+        const auth = await getBetterAuthInstance();
+        if (auth?.api?.getSession) {
+          const headers = new Headers();
+          headers.set('cookie', cookieHeader);
+
+          const session = await auth.api.getSession({ headers });
+          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);
+            // 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');
+          }
+        }
+      } catch (err: any) {
+        console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
+      }
+      if (exchange !== true) {
+        // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.
+        const errorCode = typeof exchange === 'string' ? exchange : OAUTH_SIGN_IN_FAILED_ERROR;
+        return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath, errorCode);
+      }
+    }
+
+    return response;
+    });
+  };
+}