@payez/next-mvp 4.12.0 → 4.13.0

package/src/components/auth/EnrollAuthenticatorOffer.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import type { NextStep } from '../../lib/credential-sign-in-client';
+
+/**
+ * PAY-2630: the code step's offer to set up an authenticator.
+ *
+ * WHY. The IdP answers the first sign-in turn with next_step 'enroll_mfa' when the user has NO usable second factor on this
+ * client (factors are per client). The step used to ignore that and show only "enter the code we emailed you", so a user of a
+ * generated app could never enrol a factor on that client. Measured on the PAY-2305 walk (client 90662, user with a TOTP on
+ * client 12 only): requiresTwoFactor true, sentVia 'email', nextStep 'enroll_mfa', and a page with Verify / Back and nothing else.
+ *
+ * WHAT IT IS, AND IS NOT. It renders ONLY for 'enroll_mfa'. It names the lane the user is on (the emailed code) and offers to take
+ * them to the enrolment page right after they sign in with it. It does NOT enrol in place: the enrolment endpoints need a signed-in
+ * session and this step has none yet (the provisional bearer is parked server-side). For 'mfa_verify', null or anything else it
+ * renders nothing: a user who HAS a factor must not be told to set one up.
+ */
+export function EnrollAuthenticatorOffer({
+  nextStep,
+  checked,
+  onChange,
+  disabled,
+}: {
+  nextStep: NextStep;
+  checked: boolean;
+  onChange: (next: boolean) => void;
+  disabled?: boolean;
+}) {
+  if (nextStep !== 'enroll_mfa') return null;
+  return (
+    <div data-testid="enroll-authenticator-offer" className="mt-4 text-sm" style={{ color: 'var(--text-primary, #111827)' }}>
+      <p data-testid="enroll-authenticator-lane">
+        You have no authenticator set up for this app yet, so this time you sign in with the emailed code.
+      </p>
+      <label className="flex items-center gap-2 mt-2">
+        <input
+          type="checkbox"
+          data-testid="enroll-authenticator-checkbox"
+          checked={checked}
+          disabled={disabled}
+          onChange={(e) => onChange(e.target.checked)}
+        />
+        <span>Take me to set up an authenticator right after I sign in</span>
+      </label>
+    </div>
+  );
+}
+
+export default EnrollAuthenticatorOffer;

package/src/components/mfa/QrCode.tsx

@@ -0,0 +1,24 @@
+import React, { useMemo } from 'react';
+import { encodeQr, qrToSvgPath } from '../../lib/qrcode';
+
+/** PAY-2631: client-side QR from an otpauth:// URI. Inline SVG, quiet zone of 4 modules; no network, no library. */
+export function QrCode({ value, size = 168 }: { value: string; size?: number }) {
+  const qr = useMemo(() => encodeQr(value), [value]);
+  const path = useMemo(() => qrToSvgPath(qr), [qr]);
+  const modules = qr.size;
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox={`-4 -4 ${modules + 8} ${modules + 8}`}
+      role="img"
+      aria-label="QR code for authenticator setup"
+      data-testid="totp-qr"
+    >
+      <rect x={-4} y={-4} width={modules + 8} height={modules + 8} fill="#ffffff" />
+      <path d={path} fill="#212126" />
+    </svg>
+  );
+}
+
+export default QrCode;

package/src/components/mfa/TotpEnrollPanel.tsx

@@ -0,0 +1,203 @@
+'use client';
+
+import React, { useState } from 'react';
+import { QrCode } from './QrCode';
+import { stepUpRefusal } from '../../lib/two-factor-verify-failure';
+
+/**
+ * PAY-2631: the signed-in authenticator enrolment surface of a generated app.
+ *
+ * enrol (POST /api/mfa/totp/enroll) -> QR drawn here from otpauth_uri + the manual secret -> 6-digit confirm
+ * (POST /api/mfa/totp/confirm) -> done. Port of the portal's TotpEnrollPanel without its list / replace / remove.
+ *
+ * SECRET HANDLING. The secret and otpauth_uri live in component state ONLY: never a URL, storage, console or a third-party QR
+ * service. They die on reload (a pending enrolment can only be restarted, which is what "Start again" does).
+ * WHO MAY CALL. The browser sends its session cookie; the app attaches the IdP bearer. No session -> 401 -> "sign in first".
+ * A provisional (pre-MFA) session may enrol only while the account holds no confirmed factor (IdP rule, by design).
+ * COPY after a good confirm says the next sign-in asks for the code: the app session is not upgraded by confirm.
+ */
+
+type Enrollment = { secret: string; otpauth_uri: string; enrollment_id: number | string };
+type Stage = 'idle' | 'enrolling' | 'done' | 'signed-out';
+
+export const STEP_UP_SENTENCE =
+  'This session was signed in with an emailed or texted code only. Sign in with your current authenticator, then try again.';
+
+async function readJson(res: Response): Promise<unknown> {
+  return res.json().catch(() => null);
+}
+
+export function TotpEnrollPanel({ fetchImpl, onConfirmed }: { fetchImpl?: typeof fetch; onConfirmed?: () => void } = {}) {
+  const doFetch: typeof fetch = fetchImpl ?? ((...a) => fetch(...a));
+  const [stage, setStage] = useState<Stage>('idle');
+  const [enroll, setEnroll] = useState<Enrollment | null>(null);
+  const [code, setCode] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function begin() {
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await doFetch('/api/mfa/totp/enroll', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ friendly_name: 'This device' }),
+      });
+      if (res.ok) {
+        const body = (await readJson(res)) as Partial<Enrollment> | null;
+        if (!body || !body.secret || !body.otpauth_uri || body.enrollment_id === undefined) {
+          setError('Something went wrong on our end. Try again.');
+          return;
+        }
+        setEnroll({ secret: body.secret, otpauth_uri: body.otpauth_uri, enrollment_id: body.enrollment_id });
+        setCode('');
+        setStage('enrolling');
+        return;
+      }
+      if (res.status === 401) {
+        setStage('signed-out');
+        return;
+      }
+      const json = await readJson(res);
+      if (stepUpRefusal(res.status, json)) {
+        setError(STEP_UP_SENTENCE);
+        return;
+      }
+      if (res.status === 403) {
+        setError('This account already has a second factor set up, so an authenticator app cannot be added here. Sign in with your existing method.');
+        return;
+      }
+      setError('Something went wrong on our end. Try again.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function confirm() {
+    if (!enroll || !/^\d{6}$/.test(code)) {
+      setError('Enter the 6-digit code from your app.');
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await doFetch('/api/mfa/totp/confirm', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ enrollment_id: enroll.enrollment_id, code }),
+      });
+      if (res.ok) {
+        setEnroll(null);
+        setCode('');
+        setStage('done');
+        onConfirmed?.();
+        return;
+      }
+      if (res.status === 401) {
+        setStage('signed-out');
+        return;
+      }
+      const json = await readJson(res);
+      if (stepUpRefusal(res.status, json)) {
+        setError(STEP_UP_SENTENCE);
+        return;
+      }
+      setCode('');
+      setError(
+        res.status === 400 || res.status === 422
+          ? 'That code did not match. Check the time on your phone and try the next code.'
+          : 'Setup was not completed. Try again.',
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (stage === 'signed-out') {
+    return (
+      <div data-testid="totp-signed-out">
+        <a href="/account-auth/login">Sign in</a> to set up an authenticator app.
+      </div>
+    );
+  }
+
+  if (stage === 'done') {
+    return (
+      <div data-testid="totp-done" role="status">
+        <p>Authenticator app added.</p>
+        <p>The next time you sign in on this app, you will be asked for the 6-digit code from it.</p>
+      </div>
+    );
+  }
+
+  if (stage === 'enrolling' && enroll) {
+    return (
+      <div data-testid="totp-enrolling" style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+        <p>Open your authenticator app and scan this code. A phone camera works too.</p>
+        <QrCode value={enroll.otpauth_uri} />
+        <div>
+          <div>Can&apos;t scan? Enter this code manually:</div>
+          <code data-testid="totp-secret" style={{ wordBreak: 'break-all' }}>
+            {enroll.secret}
+          </code>
+        </div>
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            void confirm();
+          }}
+        >
+          <label htmlFor="totp-code">Enter the 6-digit code from your app:</label>
+          <br />
+          <input
+            id="totp-code"
+            data-testid="totp-code"
+            inputMode="numeric"
+            autoComplete="one-time-code"
+            maxLength={6}
+            value={code}
+            disabled={busy}
+            onChange={(e) => setCode(e.target.value.replace(/\D/g, '').slice(0, 6))}
+          />{' '}
+          <button type="submit" data-testid="totp-confirm" disabled={busy || code.length !== 6}>
+            Confirm
+          </button>
+        </form>
+        {error ? (
+          <p role="alert" data-testid="totp-error">
+            {error}
+          </p>
+        ) : null}
+        <button
+          type="button"
+          data-testid="totp-restart"
+          disabled={busy}
+          onClick={() => {
+            setEnroll(null);
+            setCode('');
+            setError(null);
+            setStage('idle');
+          }}
+        >
+          Start again
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div data-testid="totp-idle">
+      <button type="button" data-testid="totp-begin" disabled={busy} onClick={() => void begin()}>
+        {busy ? 'Starting…' : 'Add authenticator app'}
+      </button>
+      {error ? (
+        <p role="alert" data-testid="totp-error">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+export default TotpEnrollPanel;

package/src/edge/middleware.ts

@@ -16,7 +16,7 @@ export {
   get2FABypassConfig
 } from '../auth/route-config';
 export type { UnauthenticatedRouteConfig, ProtectedRouteConfig } from '../auth/route-config';
-export { createMvpMiddleware, isPrefetchRequest } from '../middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest, isKnownNonNavigationRequest } from '../middleware/create-middleware';
 export type {
   MvpMiddlewareOptions,
   CircuitBreakerProvider,

package/src/index.ts

@@ -27,7 +27,7 @@ export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from '.
 // 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, isPrefetchRequest } from './middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest, isKnownNonNavigationRequest } from './middleware/create-middleware';
 
 // Account Components
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';

package/src/lib/credential-sign-in-client.ts

@@ -14,6 +14,7 @@
  *     literally true (PAY-2284).
  */
 import { NO_CODE_REQUEST, readCodeRequest, type CodeRequest } from './code-step-copy';
+import { SIGN_IN_FAILURE_COPY, capPolicyDetail, isSignInFailureCode, signInFailureMessage, tooManyAttemptsMessage } from './sign-in-failure';
 
 export const CREDENTIAL_LOGIN_URL = '/api/auth/admin-login';
 export const CREDENTIAL_EMAIL_CODE_URL = '/api/auth/admin-login/email-code';
@@ -22,11 +23,18 @@ export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
 
 export type CredentialSignInResult =
   | { kind: 'success' }
-  | { kind: 'two_factor'; codeRequest: CodeRequest; devCode: string | null }
-  | { kind: 'rate_limited'; message: string }
-  | { kind: 'error'; message: string; offerEmailCode: boolean };
+  | { kind: 'two_factor'; codeRequest: CodeRequest; devCode: string | null; nextStep: NextStep }
+  | { kind: 'rate_limited'; message: string; code: ErrorCode }
+  | { kind: 'error'; message: string; code: ErrorCode; offerEmailCode: boolean };
 
-export const MSG_RATE_LIMITED = 'Too many attempts. Please try again later.';
+/**
+ * The stable machine code a rendered error carries (data-error-code). The three from the closed table in lib/sign-in-failure,
+ * plus 'policy_message' (an allowlisted SsoRequired / InvalidRequest refusal, whose detail the server may send) and
+ * 'sign_in_failed' (anything this client could not map: a 400/5xx, an unknown code, a thrown fetch).
+ */
+export type ErrorCode = keyof typeof SIGN_IN_FAILURE_COPY | 'policy_message' | 'sign_in_failed';
+
+export const MSG_RATE_LIMITED = SIGN_IN_FAILURE_COPY.too_many_attempts;
 export const MSG_CANNOT_SIGN_IN = 'Could not sign in. Check your details and try again.';
 export const MSG_UNEXPECTED = 'Something went wrong signing you in. Please try again.';
 
@@ -46,6 +54,29 @@ export function validateCredentials(email: string, password: string): { email?:
   return errors.email || errors.password ? errors : null;
 }
 
+/**
+ * PAY-2630: what the IdP says is outstanding for this user ON THIS CLIENT. The door (api-handlers/auth/credential-login)
+ * already relays the IdP's next_step as `nextStep`; this form used to read ZERO of it. 'enroll_mfa' = the user has no usable
+ * second factor on this client, so a code prompt alone is a trap; 'mfa_verify' = a factor exists, the prompt is right.
+ * Anything else (absent, null, an unknown string, wrong case) is null = "not told", never a guess.
+ */
+export type NextStep = 'enroll_mfa' | 'mfa_verify' | null;
+
+export function readNextStep(body: any): NextStep {
+  const v = body?.nextStep;
+  return v === 'enroll_mfa' || v === 'mfa_verify' ? v : null;
+}
+
+/**
+ * Where the browser goes after the code was accepted. A user the IdP told to enrol, who kept the offer ticked, goes to the
+ * enrolment page; everyone else goes where they were headed. The destination is never decided from anything but the IdP's
+ * answer and the user's own tick. With NO enrolHref (the host mounts no enrolment page) nobody is rerouted: there is no default, because
+ * a default that a host does not serve is a 404 after a successful sign-in (QAPert, PR 1687 read).
+ */
+export function postSignInDestination(destination: string, nextStep: NextStep, enrolAfter: boolean, enrolHref?: string): string {
+  return enrolHref && nextStep === 'enroll_mfa' && enrolAfter ? enrolHref : destination;
+}
+
 /** The dev echo: the door passes the IdP's DevVerificationCode through as `devVerificationCode`. Nothing else is ever a dev code. */
 function readDevCode(body: any): string | null {
   return typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null;
@@ -68,14 +99,23 @@ export async function credentialSignIn(
     });
     const body: any = await res.json().catch(() => null);
 
-    if (res.status === 429) return { kind: 'rate_limited', message: asString(body?.error) ?? MSG_RATE_LIMITED };
-    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body), devCode: readDevCode(body) };
+    // The sentence comes from the closed table, never from the body (BAPert 85415 rule 4).
+    if (res.status === 429) {
+      const code = body?.code === 'second_factor_rate_limited' ? 'second_factor_rate_limited' : 'too_many_attempts';
+      return { kind: 'rate_limited', message: tooManyAttemptsMessage(body?.retryAfter, code), code };
+    }
+    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body), devCode: readDevCode(body), nextStep: readNextStep(body) };
     if (!res.ok || body?.success !== true) {
-      return { kind: 'error', message: asString(body?.error) ?? MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
+      const offerEmailCode = body?.offerEmailCode === true;
+      if (isSignInFailureCode(body?.code)) return { kind: 'error', message: signInFailureMessage(body.code) as string, code: body.code, offerEmailCode };
+      // The one passthrough: an allowlisted policy refusal (SsoRequired / InvalidRequest), flagged by the server with this exact code.
+      const policy = body?.code === 'policy_message' ? capPolicyDetail(body?.error) : null;
+      if (policy) return { kind: 'error', message: policy, code: 'policy_message', offerEmailCode };
+      return { kind: 'error', message: MSG_CANNOT_SIGN_IN, code: 'sign_in_failed', offerEmailCode };
     }
     return { kind: 'success' };
   } catch {
-    return { kind: 'error', message: MSG_UNEXPECTED, offerEmailCode: false };
+    return { kind: 'error', message: MSG_UNEXPECTED, code: 'sign_in_failed', offerEmailCode: false };
   }
 }
 

package/src/lib/ensure-fresh-access-token.ts

@@ -349,19 +349,20 @@ export async function ensureFreshAccessToken(
     } else if (typeof session.authenticationMethods === 'string') {
       try { authMethods = JSON.parse(session.authenticationMethods); } catch { /* fall through */ }
     }
-    const isOAuthSession = !!session.oauthProvider;
-    if (authMethods.length === 0 && isOAuthSession) {
-      authMethods = ['pwd', 'mfa'];
-    }
+    // PAY-2425 (BAPert 77400, NightHawk 77401): THE CLIENT DOES NOT INFER AUTHENTICATION STRENGTH FROM SILENCE. This block used to answer an OAuth
+    // (Google) session whose stored methods were EMPTY with amr ['pwd','mfa'], a two-factor method of 'oauth' and an acr raised from '1' to '2' ("OAuth IS
+    // a form of multi-factor auth"). That is false: OAuth is federated sign-in, one factor typed at the provider. It fired exactly when the session
+    // could tell us nothing and answered with the strongest claim available; on prod (4.10.0) a Google user on a require2FA client was then counted
+    // 2FA-complete with no code (RigPert 77398). What the session does not attest, the refresh body does not assert: empty stays empty, the level stays
+    // the session's own, and no method is named unless one is recorded. The IdP computes the real amr/acr for the minted token (and mfaVerified is
+    // re-derived from THAT token below); a session that really attests 'mfa' still sends it. History: the fix existed on nextpert/375639-amr-fabrication
+    // (e6e3b6c3, e3b3bb12) and was never merged.
     const twoFactorMethod =
       authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
       session.mfaMethod ||
-      (isOAuthSession ? 'oauth' : null);
+      null;
 
-    let acrValue = String(session.authenticationLevel ?? '1');
-    if (isOAuthSession && session.mfaVerified && acrValue === '1') {
-      acrValue = '2';
-    }
+    const acrValue = String(session.authenticationLevel ?? '1');
 
     // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
     // `session` was read before we acquired the lock; a concurrent refresh that
@@ -397,7 +398,11 @@ export async function ensureFreshAccessToken(
       amr: authMethods,
       acr: acrValue,
     };
-    if (session.mfaVerified) body.two_factor_verified = true;
+    // PAY-2425 (NightHawk 77414): a STORED mfaVerified flag is only echoed when the session's own recorded methods back it. Sessions created while the
+    // bug was live carry mfaVerified:true that the bug itself wrote, with no 'mfa' (or sms/totp/email) in their methods; echoing that flag would carry the
+    // poison across the upgrade. A genuine second factor leaves 'mfa' and its method in the recorded methods, so it is still sent.
+    const methodsAttestSecondFactor = authMethods.some(m => m === 'mfa' || ['sms', 'totp', 'email'].includes(m));
+    if (session.mfaVerified && methodsAttestSecondFactor) body.two_factor_verified = true;
     if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
     if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
 

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

@@ -43,6 +43,7 @@
 import 'server-only';
 import { createHash, randomUUID } from 'crypto';
 import { markNeverInResponse } from './never-in-response';
+import { clientSecretBody, warnIfProviderSecretRedacted } from './payez-client-secret';
 import { errForLog } from './log-safe';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
@@ -816,6 +817,7 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
         subject: clientIdStr,
         audience: 'urn:payez:externalauth:clientconfig',
         expires_in: 60,
+        ...clientSecretBody(),
     };
 
     const signingResp = await fetch(signingUrl, {
@@ -866,7 +868,7 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
             'X-Client-Id': clientIdStr,
             'X-Correlation-Id': randomUUID().replace(/-/g, ''),
         },
-        body: JSON.stringify({ client_assertion }),
+        body: JSON.stringify({ client_assertion, ...clientSecretBody() }),
         cache: 'no-store'
     } as RequestInit);
 
@@ -988,6 +990,8 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
         throw new Error('[IDP_CONFIG] FATAL: authSecret is empty after parsing and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
     }
 
+    warnIfProviderSecretRedacted(configResp.headers?.get?.('X-PayEz-Secrets-Redacted'), config.oauthProviders ?? [], providerSecretEnvVar);
+
     // Success - reset failure tracking
     consecutiveFailures = 0;
     return config;

package/src/lib/login-error-message.ts

@@ -9,13 +9,20 @@
  * sentence; nothing from the URL is ever shown verbatim.
  */
 
+import { SIGN_IN_FAILURE_COPY, type SignInFailureCode } from './sign-in-failure';
+
 export const GENERIC_LOGIN_ERROR = 'We could not sign you in. Please try again.';
 
 const KNOWN: Record<string, string> = {
   TwoFactorTimeout: 'Your verification step timed out before the code was confirmed. Please sign in again.',
   AUTHORIZE_RESUME_REFUSED: 'That sign-in request could not be continued. Please sign in again.',
+  // PAY-2279 / PAY-2005(b): the one IdP refusal code the abort path forwards (IDP_ERROR_CODES_TO_FORWARD). Wording is the card's proposal.
+  // (OAUTH_SIGN_IN_FAILED has no sentence in THIS change: PR 1606 (PAY-2554) owns that code's redirect and its sentence; once both land the map carries both.)
+  REGISTRATION_NOT_ALLOWED: 'Registration is not open for this site. Ask your administrator for an invitation.',
   ServiceUnavailable: 'Authentication service is temporarily unavailable. Please try again in a few minutes.',
-  CredentialsSignin: 'Invalid email or password. Please try again.',
+  CredentialsSignin: SIGN_IN_FAILURE_COPY.invalid_credentials,
+  // PAY-2554: the neutral code the OAuth callback failure / state-error / aborted-exchange redirects carry (better-auth.ts OAUTH_SIGN_IN_FAILED_ERROR).
+  OAUTH_SIGN_IN_FAILED: "Sign-in didn't complete. Please try again, or use email.",
 };
 
 /**
@@ -39,3 +46,8 @@ export function oauthFailureMessage(provider: string | null | undefined): string
   if (!/^[a-z][a-z0-9_-]{0,31}$/i.test(provider)) return GENERIC_LOGIN_ERROR;
   return `${provider.charAt(0).toUpperCase()}${provider.slice(1)} sign-in did not complete. Please try again.`;
 }
+
+/** The machine code (data-error-code) for a `?error=` code, or null when it has none in the closed table. Nothing from the URL is echoed. */
+export function loginErrorCode(code: string | null | undefined): SignInFailureCode | null {
+  return code === 'CredentialsSignin' ? 'invalid_credentials' : null;
+}

package/src/lib/mfa-json-guard.ts

@@ -0,0 +1,19 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * PAY-2631: the TOTP enrol/confirm handlers forward the browser body verbatim, so a cross-site form post
+ * (Content-Type text/plain, application/x-www-form-urlencoded) could reach them. A browser cannot send
+ * application/json cross-site without a CORS preflight, so requiring it closes that path.
+ * The responses carry the shared secret and the otpauth URI, so they are never cached.
+ */
+export const NO_STORE = { 'Cache-Control': 'no-store' } as const;
+
+/** A 415 response when the request is not application/json, otherwise null. */
+export function refuseNonJson(req: NextRequest): NextResponse | null {
+  const ct = (req.headers.get('content-type') || '').toLowerCase();
+  if (ct.split(';')[0].trim() === 'application/json') return null;
+  return NextResponse.json(
+    { success: false, message: 'Content-Type must be application/json', error: { code: 'UNSUPPORTED_MEDIA_TYPE' } },
+    { status: 415, headers: NO_STORE },
+  );
+}

package/src/lib/nextauth-secret.ts

@@ -42,6 +42,7 @@
 import 'server-only';
 import { randomUUID } from 'node:crypto';
 import { validateAuthSecret } from './secret-validation';
+import { clientSecretBody } from './payez-client-secret';
 
 let cachedSecret: string | null = null;
 let lastFetchedAt = 0;
@@ -104,6 +105,7 @@ export async function resolveNextAuthSecret(): Promise<string> {
       subject: clientIdStr,
       audience: 'urn:payez:externalauth:nextauthsecret',
       expires_in: 60,
+      ...clientSecretBody(),
     }),
     cache: 'no-store',
   });
@@ -136,7 +138,7 @@ export async function resolveNextAuthSecret(): Promise<string> {
       'X-Client-Id': clientIdStr,
       'X-Correlation-Id': randomUUID().replace(/-/g, ''),
     },
-    body: JSON.stringify({ client_assertion: clientAssertion }),
+    body: JSON.stringify({ client_assertion: clientAssertion, ...clientSecretBody() }),
     cache: 'no-store',
   });
 

package/src/lib/payez-client-secret.ts

@@ -0,0 +1,39 @@
+/**
+ * PAY-1460 (BAPert 86061): the app's own client secret, so the IdP can tell this app from a caller that merely knows its
+ * client id. One env var per app, PAYEZ_CLIENT_SECRET, read at CALL time (not a module-load snapshot: the deployment may
+ * inject it late). Unset or blank: NOTHING is added to any request body, so an app that has no secret yet sends exactly
+ * what it sent before. The value is never logged and never leaves in a response (markNeverInResponse).
+ */
+import { markNeverInResponse } from './never-in-response';
+
+export const CLIENT_SECRET_ENV = 'PAYEZ_CLIENT_SECRET';
+
+/** `{ client_secret }` when the env var is set to a non-blank value, else `{}`. Spread it into a JSON body. */
+export function clientSecretBody(): { client_secret?: string } {
+    const v = process.env[CLIENT_SECRET_ENV];
+    if (typeof v !== 'string' || v.trim() === '') return {};
+    markNeverInResponse(v);
+    return { client_secret: v };
+}
+
+const warnedProviders = new Set<string>();
+
+/**
+ * The IdP marks a view whose secrets it withheld with the response header X-PayEz-Secrets-Redacted: true. An app with no
+ * <PROVIDER>_CLIENT_SECRET in env then boots and the provider fails at the code exchange. Say so, once per provider per
+ * process, naming the provider only.
+ */
+export function warnIfProviderSecretRedacted(
+    redactedHeader: string | null | undefined,
+    providers: ReadonlyArray<{ provider: string; enabled?: boolean }>,
+    envVarFor: (provider: string) => string,
+): void {
+    if (String(redactedHeader ?? '').trim().toLowerCase() !== 'true') return;
+    for (const p of providers) {
+        if (!p.enabled || !p.provider) continue;
+        if (process.env[envVarFor(p.provider)]) continue;
+        if (warnedProviders.has(p.provider)) continue;
+        warnedProviders.add(p.provider);
+        console.warn(`[IDP_CONFIG] PAYEZ_PROVIDER_SECRET_MISSING_REDACTED provider=${p.provider}`);
+    }
+}