@payez/next-mvp 4.4.6 → 4.4.8

package/src/auth/better-auth.ts

@@ -281,19 +281,42 @@ export function buildBetterAuthProviders(
       clientSecret: oauth.clientSecret,
       scope: wireScopes.length > 0 ? wireScopes : undefined,
       /**
-       * 260419 — CLOSE THE SECOND SELF-SERVE PROVISIONING DOOR. 259805 gated
-       * the signup BFF on allow_public_registration, but the social lane never
-       * touches that code: better-auth creates the user through its own
-       * internalAdapter at the OAuth callback, and its ONLY guard is this flag.
+       * PAY-2005 — DISABLE-SIGN-UP IS REMOVED, DELIBERATELY. DO NOT RE-ADD IT.
        *
-       * Wired from the tenant's own policy, explicit-true-opens: the IDP config
-       * keeps allowPublicRegistration UNDEFINED when the tenant never answered
-       * (idp-client-config.ts, the no-fabricated-default rule), and an
-       * unanswered policy question must not provision accounts. That matches
-       * the FE's silent-default-is-decline posture for the "Create account"
-       * affordance. A tenant that wants Google self-serve says so.
+       * 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.
        */
-      disableSignUp: config.authSettings?.allowPublicRegistration !== true,
       // Google is overly eager to reuse the last account unless we
       // explicitly ask for account selection on each social login.
       prompt: typeof rawPrompt === 'string'
@@ -820,6 +843,19 @@ export function createBetterAuthInstance(
       },
     },
 
+    // 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,
@@ -971,11 +1007,17 @@ export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => P
  * 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> {
+): Promise<boolean | string> {
   try {
     const config = await getIDPClientConfig();
     const appSlug = config.clientSlug || getAppSlug();
@@ -1068,6 +1110,36 @@ export async function exchangeOAuthForIdpTokens(
     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.
        *
@@ -1115,7 +1187,7 @@ export async function exchangeOAuthForIdpTokens(
         sent_client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? null,
         idp_url: idpUrl,
       });
-      return false;
+      return idpErrorCode ?? false;
     }
 
     let idpData: any;
@@ -1125,6 +1197,7 @@ export async function exchangeOAuthForIdpTokens(
     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
@@ -1235,6 +1308,7 @@ export async function exchangeOAuthForIdpTokens(
     // 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));
@@ -1242,6 +1316,7 @@ export async function exchangeOAuthForIdpTokens(
   }
 }
 
+
 /**
  * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
  * function never acquires tokens and never decides who the caller is.
@@ -1331,12 +1406,93 @@ export async function storeIdpTokensInSession(
   }
 }
 
+/**
+ * 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';
+
+/**
+ * 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
+ * - 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
@@ -1408,24 +1564,30 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       }
     }
 
-    // After successful OAuth callback: exchange Google identity for IDP tokens
+    // 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 setCookies = response.headers.getSetCookie?.() || [];
-          const cookieHeader = setCookies
-            .map((c: string) => c.split(';')[0])
-            .join('; ');
-
           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);
-            await exchangeOAuthForIdpTokens(session.session.token);
+            exchange = await exchangeOAuthForIdpTokens(session.session.token);
           } else {
             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
           }
@@ -1433,6 +1595,11 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       } 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;

package/src/config/env.ts

@@ -29,8 +29,6 @@ export const API_ENDPOINTS = {
     profile: '/api/account/profile',
     updateProfile: '/api/account/profile',
     maskedInfo: '/api/account/masked-info',
-    sendResetCode: '/api/account/send-reset-code',
-    verifyResetCode: '/api/account/verify-reset-code',
     resetPassword: '/api/account/reset-password',
     changePassword: '/api/account/change-password',
     validatePassword: '/api/account/validate-password'

package/src/index.ts

@@ -23,6 +23,10 @@ export type { AuthConfig } from './types/auth';
 // Route configuration (client-safe)
 export { makeAuthDecision } from './auth/auth-decision';
 export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
+
+// The ONE callback-target guard (N7 / PAY-1989): apps import this instead of
+// copying it. Exposed from the main index AND as the subpath ./auth/safe-callback.
+export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
 export { createMvpMiddleware } from './middleware/create-middleware';
 
 // Account Components

package/src/lib/idp-client-config.ts

@@ -42,6 +42,7 @@
 
 import 'server-only';
 import { createHash, randomUUID } from 'crypto';
+import { markNeverInResponse } from './never-in-response';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -211,6 +212,10 @@ function resolveAuthSecret(fromConfig: string | undefined): { value: string; sou
 function applyEnvSecrets(config: IDPClientConfig): IDPClientConfig {
     const auth = resolveAuthSecret(config.authSecret);
     logSecretSource('authSecret', auth.source);
+    // PAY-1529: every secret this module resolves is registered as never-in-response HERE, the one place
+    // both fetch paths and the Redis read pass through, so the runtime backstop knows the value whichever
+    // handler later tries to serialize it.
+    markNeverInResponse(auth.value);
     return {
         ...config,
         authSecret: auth.value,
@@ -219,7 +224,9 @@ function applyEnvSecrets(config: IDPClientConfig): IDPClientConfig {
             const fromEnv = process.env[envVar];
             const source: SecretSource = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
             logSecretSource(`${p.provider} clientSecret`, source);
-            return { ...p, clientSecret: fromEnv || p.clientSecret };
+            const clientSecret = fromEnv || p.clientSecret;
+            markNeverInResponse(clientSecret);
+            return { ...p, clientSecret };
         }),
     };
 }

package/src/lib/never-in-response.ts

@@ -0,0 +1,64 @@
+/**
+ * PAY-1529 runtime backstop: the signing secret and the OAuth provider client secrets must never be
+ * serialized into an HTTP response body.
+ *
+ * The build-time guard (test/secrets-never-in-response-source-guard.test.cjs) follows values through the
+ * source it can see. This is the layer for what it cannot see — a value that crosses a module boundary,
+ * a structuredClone / Object.assign copy, a helper in a consumer app. It tracks the secret by VALUE:
+ * the loader registers every resolved secret here at the moment it resolves it (applyEnvSecrets), and a
+ * response built with `secretSafeJson` / checked with `assertNoServerSecret` FAILS CLOSED — it throws,
+ * and the route answers 500 — if any registered value appears anywhere in the serialized body, under any
+ * key, at any depth, whatever the code that built it called it.
+ *
+ * Bounds, stated rather than implied:
+ *  - Values shorter than MIN_SECRET_LENGTH are not registered. A short string matches innocent bodies and
+ *    would turn this into an outage generator; real signing and provider secrets are far longer.
+ *  - It protects responses that go through it. Adoption is per handler; the build-time guard is what
+ *    covers the handlers that do not.
+ *  - Nothing here ever logs, returns or throws a secret value.
+ */
+import { NextResponse } from 'next/server';
+
+export const MIN_SECRET_LENGTH = 16;
+
+const registered = new Set<string>();
+
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+export function markNeverInResponse(value: unknown): void {
+    if (typeof value !== 'string' || value.length < MIN_SECRET_LENGTH) return;
+    registered.add(value);
+    // JSON escapes some characters, so the serialized form of a secret containing `"` or `\` differs from
+    // the raw value. Register that form too, or such a secret would pass through a JSON body unseen.
+    const escaped = JSON.stringify(value).slice(1, -1);
+    if (escaped !== value) registered.add(escaped);
+}
+
+export class SecretInResponseError extends Error {
+    constructor(where: string) {
+        // The message names the route, never the value.
+        super(`[PAY-1529] Refused to serialize a server secret into the response of ${where}`);
+        this.name = 'SecretInResponseError';
+    }
+}
+
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+export function assertNoServerSecret(body: unknown, where: string): void {
+    if (registered.size === 0 || body === undefined || body === null) return;
+    let text: string;
+    try {
+        text = typeof body === 'string' ? body : JSON.stringify(body);
+    } catch {
+        // Unserializable: NextResponse.json would throw on it anyway. Fail closed rather than guess.
+        throw new SecretInResponseError(where);
+    }
+    if (!text) return;
+    for (const secret of registered) {
+        if (text.includes(secret)) throw new SecretInResponseError(where);
+    }
+}
+
+/** NextResponse.json, refusing any body that carries a registered secret. */
+export function secretSafeJson<T>(body: T, init: ResponseInit | undefined, where: string): NextResponse<T> {
+    assertNoServerSecret(body, where);
+    return NextResponse.json(body, init);
+}

package/src/lib/nextauth-secret.ts

@@ -0,0 +1,168 @@
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+import 'server-only';
+import { randomUUID } from 'node:crypto';
+import { validateAuthSecret } from './secret-validation';
+
+let cachedSecret: string | null = null;
+let lastFetchedAt = 0;
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface SigningResponse {
+  data?: { client_assertion?: string; clientAssertion?: string; ClientAssertion?: string };
+  client_assertion?: string;
+  clientAssertion?: string;
+  ClientAssertion?: string;
+}
+
+interface SecretResponse {
+  data?: { secret?: string; configuration?: unknown };
+  secret?: string;
+  configuration?: unknown;
+}
+
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+export async function resolveNextAuthSecret(): Promise<string> {
+  // Check if already in environment
+  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+    return process.env.NEXTAUTH_SECRET;
+  }
+
+  // Check if cached and fresh (within 5 minutes)
+  if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
+    return cachedSecret;
+  }
+
+  // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
+  const base = process.env.IDP_URL;
+  if (!base) throw new Error('IDP_URL environment variable is required');
+
+  const clientIdStr = process.env.CLIENT_ID;
+  if (!clientIdStr || clientIdStr.trim() === '') {
+    throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+  }
+
+  // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
+  const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+  const signingResp = await fetch(signingUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({
+      issuer: clientIdStr,
+      subject: clientIdStr,
+      audience: 'urn:payez:externalauth:nextauthsecret',
+      expires_in: 60,
+    }),
+    cache: 'no-store',
+  });
+
+  if (!signingResp.ok) {
+    const txt = await signingResp.text().catch(() => 'Unknown error');
+    throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+  }
+
+  const signingBody = (await signingResp.json().catch(() => ({}))) as SigningResponse;
+  const clientAssertion =
+    signingBody?.data?.client_assertion ??
+    signingBody?.data?.clientAssertion ??
+    signingBody?.client_assertion ??
+    signingBody?.clientAssertion ??
+    signingBody?.data?.ClientAssertion ??
+    signingBody?.ClientAssertion;
+
+  if (!clientAssertion || typeof clientAssertion !== 'string') {
+    throw new Error('IDP did not return a valid signed client assertion');
+  }
+
+  // Step 2: use the signed assertion to fetch the NextAuth secret
+  const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
+  const proxyResp = await fetch(proxyUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({ client_assertion: clientAssertion }),
+    cache: 'no-store',
+  });
+
+  if (!proxyResp.ok) {
+    const txt = await proxyResp.text().catch(() => 'Unknown error');
+    throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+  }
+
+  const proxyBody = (await proxyResp.json().catch(() => ({}))) as SecretResponse;
+  const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
+  // `configuration` is available from the IDP but deliberately not logged.
+
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('Proxy did not return a valid NextAuth secret');
+  }
+
+  // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
+  const validation = validateAuthSecret(secret);
+  if (!validation.valid) {
+    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+  }
+
+  cachedSecret = secret;
+  lastFetchedAt = Date.now();
+  process.env.NEXTAUTH_SECRET = secret;
+
+  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+  return secret;
+}

package/src/lib/safe-error-response.ts

@@ -93,12 +93,6 @@ export function idpErrorEnvelope(json: unknown, fallbackMessage = 'Request faile
   return out;
 }
 
-/**
- * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
- * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
- * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
- * (the caller must be able to tell a refused password from a dead recovery session).
- */
 /**
  * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
  * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
@@ -116,6 +110,12 @@ export function projectResetTokenInvalid(json: unknown): boolean {
   return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && (v as Record<string, unknown>).code === 'InvalidToken');
 }
 
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
 export function projectPasswordPolicyRules(json: unknown): string[] | undefined {
   if (!json || typeof json !== 'object') return undefined;
   const top = json as Record<string, unknown>;