@payez/next-mvp 4.4.8 → 4.5.0

package/src/api-handlers/session/viability.ts

@@ -10,6 +10,7 @@ import { getSession } from '../../server/auth';
 import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { tokenLogId } from '../../lib/token-log-id';
+import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
 
 export async function GET(req: NextRequest) {
   try {
@@ -140,12 +141,42 @@ export async function GET(req: NextRequest) {
           });
         }
 
+        // --- Session revocation status (PAY-1882 step 4 producer half) ---
+        // The four-state status (BAPert 66320). The middleware fails CLOSED by
+        // default on 'unknown' (a failed Vibe read) and always on 'revoked';
+        // 'active' and 'not_configured' stay viable. A consumer that does not
+        // read revocationStatus is unaffected - absent is not revoked.
+        let revocationStatus: RevocationStatus = 'not_configured';
+        // BAPert 66480 condition 2 / ruling (ii) 66700: the numeric IdP id comes from
+        // the token's own `sub` claim FIRST (session.userId can be an email).
+        const revocationUserId = resolveNumericIdpUserId(sessionData, (sessionData as any).idpAccessToken);
+        if (revocationUserId > 0) {
+          try {
+            revocationStatus = await getRevocationStatus(revocationUserId, sessionToken);
+          } catch {
+            // getRevocationStatus does not throw by contract; fail closed if it ever does.
+            revocationStatus = 'unknown';
+          }
+        } else {
+          // N1 (NightHawk 66392): a session EXISTS but its userId is not a usable
+          // numeric IdP id, so the check could not be run. That is 'unknown'
+          // (could not determine), NOT 'not_configured' (no revocation source) -
+          // the two must not be conflated.
+          // BAPert 66480 condition 1: emit ONE WARN (shape only) per session.
+          revocationStatus = warnNonNumericUserId(sessionToken, sessionData.userId);
+        }
+
         const response = {
           authenticated: true,
           sessionTokenId: tokenLogId(sessionToken), // PAY-1481: correlation id for middleware tracking, never the token
           // 2FA fields - critical for middleware redirect logic
           requires2FA, // From cached client config (client-wide setting)
           twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+          // Session revocation (PAY-1882 step 4): the four-state status, plus the
+          // boolean the middleware's existing force-invalid branch already reads.
+          revocationStatus,
+          forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
+          revoked: revocationStatus === 'revoked',
           // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
           //
           // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is

package/src/auth/password-reset-bridge.ts

@@ -0,0 +1,98 @@
+/**
+ * PAY-2121: the fragment bridge on `/`.
+ *
+ * The IdP's post-verify redirect for a passwordless account lands on
+ *   ORIGIN/#password_reset_required=true&reset_token=<token>&email=<addr>
+ * - a FRAGMENT, never a query (ProgressiveAuthController.cs:1204-1222). A fresh
+ * @payez/next-mvp app has no fragment handling at all, so the user lands on `/`
+ * and nothing happens; their reset is lost.
+ *
+ * This is the PURE half (data in, data out) so a test can execute it without a
+ * DOM. The client component (PasswordResetBridge) calls it on mount with
+ * `window.location.hash`. The kit's reset surface is the existing
+ * `/account-auth/recovery` page, which reads `?email=` and a reset token - so the
+ * bridge rewrites the fragment into that surface's OWN query shape and navigates
+ * once. It invents no new reset flow.
+ *
+ * CONTRACT:
+ *   '#password_reset_required=true&reset_token=T&email=a%40b.co' -> '/account-auth/recovery?token=T&email=a%40b.co'
+ *   any other fragment (no flag, flag != true, no token) -> null (leave `/` alone)
+ */
+
+/** The reset surface the bridge hands off to, by its existing path. */
+export const RECOVERY_PATH = '/account-auth/recovery';
+
+/**
+ * PAY-2121 (BAPert 70576): the recovery page's ENTRY decision, as a pure function.
+ *
+ * The bridge now sends a VERIFIED passwordless user to
+ *   /account-auth/recovery?token=<reset_token>&email=<addr>
+ * with a REAL reset token in hand. If the page then showed its request-a-code
+ * step, it would throw that token away and the flow would still dead-end - just
+ * one page later. So when a token is present the page must start at the
+ * set-password step and submit straight through resetPasswordWithToken.
+ *
+ *   token present      -> { step: 'set-password', resetToken: <token> }
+ *   no token           -> { step: 'initiate',    resetToken: null }   (today's behaviour)
+ */
+export function recoveryEntry(
+  token: string | null | undefined,
+  email: string | null | undefined,
+): { step: 'set-password' | 'initiate'; resetToken: string | null; email: string } {
+  const tok = (token ?? '').trim();
+  return {
+    step: tok ? 'set-password' : 'initiate',
+    resetToken: tok || null,
+    email: (email ?? '').trim(),
+  };
+}
+
+/**
+ * PAY-2121 (BAPert 70582): the set-password SUBMIT precondition, as a pure
+ * function. The old guard was `if (!passwordResetToken || !recoverySession) return;`.
+ * Removing the session half (so a deep-linked reset can submit) must NOT let a
+ * submit with NO token reach the API carrying an empty token - which is exactly
+ * what a guard-less submit would do. This decides it, in one testable place:
+ *
+ *   resetSubmitTarget(resetToken, sessionEmail, queryEmail):
+ *     - no token (after trim)          -> null   (REFUSE: never call the API with an empty token)
+ *     - token, session email present   -> { token, email: sessionEmail }
+ *     - token, only a query email      -> { token, email: queryEmail }  (the deep-link case)
+ *     - token, but NO email anywhere    -> null   (REFUSE: nothing to reset)
+ *
+ * Returns the exact { token, email } the caller must pass to
+ * accountApi.resetPasswordWithToken, or null to refuse BEFORE any request.
+ */
+export function resetSubmitTarget(
+  resetToken: string | null | undefined,
+  sessionEmail: string | null | undefined,
+  queryEmail: string | null | undefined,
+): { token: string; email: string } | null {
+  const tok = (resetToken ?? '').trim();
+  if (!tok) return null;
+  const email = ((sessionEmail ?? '').trim() || (queryEmail ?? '').trim());
+  if (!email) return null;
+  return { token: tok, email };
+}
+
+/**
+ * The redirect the fragment asks for, or null when the fragment is not a reset
+ * request. `hash` is `window.location.hash` (leading '#' optional).
+ *
+ * Returns null - leaves `/` untouched - when:
+ *   - the fragment is empty;
+ *   - `password_reset_required` is absent or not exactly 'true';
+ *   - no `reset_token` is present (nothing to reset with; not a real link).
+ */
+export function passwordResetRedirect(hash: string | null | undefined): string | null {
+  const raw = (hash ?? '').replace(/^#/, '');
+  if (!raw) return null;
+  const params = new URLSearchParams(raw);
+  if (params.get('password_reset_required') !== 'true') return null;
+  const token = params.get('reset_token') ?? '';
+  if (!token) return null;
+  const email = params.get('email') ?? '';
+  const qs = new URLSearchParams({ token });
+  if (email) qs.set('email', email);
+  return `${RECOVERY_PATH}?${qs.toString()}`;
+}

package/src/auth/route-config.ts

@@ -63,6 +63,23 @@ const defaultUnauthenticatedRoutes: UnauthenticatedRouteConfig[] = [
     allowDuringCircuitBreakerOpen: true,
     requiresRateLimit: false
   },
+  // PAY-2121: the IdP emails an invite link to /account-auth/onboarding and a
+  // post-verify reset FRAGMENT on '/'. Both must be reachable unauthenticated -
+  // the invitee has no session (the onboard_token IS the credential), and the
+  // fragment lands on the already-public root. Listed explicitly, not left to
+  // the /account-auth/* wildcard, so the two conventional paths are visible here.
+  {
+    pattern: '/account-auth/onboarding',
+    description: 'IdP invite/onboarding landing page (token-driven, no session)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/api/onboarding/*',
+    description: 'Onboarding API (token-driven, no session)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: true
+  },
   {
     pattern: '/api/auth/*',
     description: 'Authentication API endpoints',

package/src/components/auth/FederatedAuthSection.tsx

@@ -9,12 +9,44 @@ interface Props {
   isLoading?: boolean;
 }
 
-const providerIcons: Record<FederatedProvider, { label: string; svg: React.ReactNode; color: string }> = {
+/**
+ * PAY-2104 — PER-PROVIDER BRAND TREATMENT, NOT ONE GENERIC BUTTON.
+ *
+ * Apple and Facebook both publish binding rules for their sign-in buttons and
+ * neither is satisfied by the generic "Continue with X" control this section
+ * used to render for every provider:
+ *   - APPLE (App Store Review Guidelines 4.8 / "Sign in with Apple" HIG): the
+ *     button MUST carry the Apple logo and one of Apple's own wordings. The
+ *     approved primary wording is "Sign in with Apple" ("Continue with Apple"
+ *     is the permitted alternative). "Continue with Apple" with no logo, which
+ *     is what the generic path produced, is non-compliant and is what App Store
+ *     review rejects. Black or white only.
+ *   - FACEBOOK (Meta Platform Terms / brand guidelines): "Continue with
+ *     Facebook", the Facebook "f" mark, and the brand blue (#1877F2) or white
+ *     are the sanctioned treatments.
+ * Google/Microsoft/GitHub keep the neutral control — they impose no such rule,
+ * and inventing brand colours for them would be a change nobody asked for.
+ *
+ * The mark inherits `currentColor` so it is legible on both the white neutral
+ * buttons and the black/blue branded ones without a second SVG per provider.
+ */
+const PROVIDER_BRAND: Record<
+  FederatedProvider,
+  { label: string; background: string; color: string; border: string }
+> = {
+  google: { label: 'Continue with Google', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+  microsoft: { label: 'Continue with Microsoft', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+  github: { label: 'Continue with GitHub', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+  // Meta brand blue; white mark on blue, per the brand guidelines.
+  facebook: { label: 'Continue with Facebook', background: '#1877F2', color: '#ffffff', border: '#1877F2' },
+  // Apple HIG: black (or white) field, "Sign in with Apple", Apple logo.
+  apple: { label: 'Sign in with Apple', background: '#000000', color: '#ffffff', border: '#000000' },
+};
+
+const providerIcons: Record<FederatedProvider, { svg: React.ReactNode }> = {
   google: {
-    label: 'Google',
-    color: '#4285F4',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" fill="#4285F4"/>
         <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" fill="#34A853"/>
         <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" fill="#FBBC05"/>
@@ -23,10 +55,8 @@ const providerIcons: Record<FederatedProvider, { label: string; svg: React.React
     ),
   },
   microsoft: {
-    label: 'Microsoft',
-    color: '#0078D4',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <rect x="1" y="1" width="9" height="9" fill="#F25022"/>
         <rect x="12" y="1" width="9" height="9" fill="#7FBA00"/>
         <rect x="1" y="12" width="9" height="9" fill="#00A4EF"/>
@@ -35,28 +65,25 @@ const providerIcons: Record<FederatedProvider, { label: string; svg: React.React
     ),
   },
   facebook: {
-    label: 'Facebook',
-    color: '#1877F2',
+    // currentColor: white on the Meta-blue button. A hardcoded #1877F2 fill on a
+    // #1877F2 field is an invisible mark — the exact way a branded button ships
+    // looking like a blank one.
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="#1877F2">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
       </svg>
     ),
   },
   github: {
-    label: 'GitHub',
-    color: '#000000',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
       </svg>
     ),
   },
   apple: {
-    label: 'Apple',
-    color: '#000000',
     svg: (
-      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
         <path d="M17.05 20.28c-.98.95-2.05.8-3.08.35-1.09-.46-2.09-.48-3.24 0-1.44.62-2.2.44-3.06-.35C2.79 15.25 3.51 7.59 9.05 7.31c1.35.07 2.29.74 3.08.8 1.18-.24 2.31-.93 3.57-.84 1.51.12 2.65.72 3.4 1.8-3.12 1.87-2.38 5.98.48 7.13-.57 1.5-1.31 2.99-2.54 4.09l.01-.01zM12.03 7.25c-.15-2.23 1.66-4.07 3.74-4.25.29 2.58-2.34 4.5-3.74 4.25z"/>
       </svg>
     ),
@@ -71,22 +98,29 @@ export function FederatedAuthSection({ providers, onProviderClick, isLoading }:
   return (
     <div className="space-y-3">
       {providers.map((provider) => {
-        const config = providerIcons[provider];
+        const icon = providerIcons[provider];
+        const brand = PROVIDER_BRAND[provider] ?? {
+          label: `Continue with ${provider}`,
+          background: 'var(--bg-default, #ffffff)',
+          color: 'var(--text-primary, #111827)',
+          border: 'var(--border-default, #e5e7eb)',
+        };
         return (
           <button
             key={provider}
             type="button"
             onClick={() => onProviderClick(provider)}
             disabled={isLoading}
+            data-provider={provider}
             className={`w-full px-4 py-3 rounded-lg border-2 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed`}
             style={{
-              border: '1px solid var(--border-default)',
-              color: 'var(--text-primary)',
-              background: 'var(--bg-default)',
+              border: `1px solid ${brand.border}`,
+              color: brand.color,
+              background: brand.background,
             }}
           >
-            {config.svg}
-            Continue with {config.label}
+            {icon.svg}
+            {brand.label}
           </button>
         );
       })}

package/src/components/auth/PasswordResetBridge.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useEffect } from 'react';
+import { passwordResetRedirect } from '../../auth/password-reset-bridge';
+
+/**
+ * PAY-2121: mount this once on your app's `/` page. When the IdP's post-verify
+ * redirect lands on `/#password_reset_required=true&reset_token=<t>&email=<e>`
+ * (a FRAGMENT), this performs ONE replace to the kit's reset surface and clears
+ * the hash. With any other fragment it renders nothing and leaves `/` alone.
+ *
+ * It renders nothing and reads no user data - it only inspects the fragment.
+ *
+ * @example
+ * // app/page.tsx
+ * import { PasswordResetBridge } from '@payez/next-mvp/components/auth/PasswordResetBridge';
+ * export default function Home() {
+ *   return (&lt;&gt;&lt;PasswordResetBridge /&gt;&lt;/&gt;);
+ * }
+ */
+export function PasswordResetBridge() {
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const target = passwordResetRedirect(window.location.hash);
+    if (target) window.location.replace(target);
+  }, []);
+  return null;
+}
+
+export default PasswordResetBridge;

package/src/hooks/useAvailableProviders.ts

@@ -62,35 +62,58 @@ export function useAvailableProviders(): UseAvailableProvidersResult {
 
         async function fetchProviders() {
             try {
-                // Fetch available providers from Better Auth
-                // Better Auth doesn't have a getProviders equivalent, so we use a static list
-                // based on configured social providers
-                const result: Record<string, { id: string; name: string }> = {
-                    google: { id: 'google', name: 'Google' },
-                };
+                // PAY-2104: THIS USED TO BE A HARDCODED GOOGLE LITERAL.
+                //
+                //   const result = { google: { id: 'google', name: 'Google' } };
+                //
+                // under a comment claiming providers were "loaded dynamically". It
+                // returned Google for EVERY client whatever the tenant had enabled -
+                // a config-shaped constant, so Apple/Facebook (PAY-2104) could never
+                // appear and a client that had DISABLED Google would still see its
+                // button. The real answer is served by /api/auth/settings (the same
+                // route routes/auth/settings.ts builds from the IDP's oauthProviders).
+                const response = await fetch('/api/auth/settings', { cache: 'no-store' });
 
                 if (!mounted) return;
 
-                setRawProviders(result);
-
-                if (result) {
-                    // Filter to OAuth providers only (exclude credentials)
-                    // Map to our FederatedProvider type
-                    const oauthProviders = Object.keys(result)
-                        .filter(id => OAUTH_PROVIDERS.includes(id))
-                        .map(id => PROVIDER_MAP[id])
-                        .filter((p): p is FederatedProvider => p !== undefined);
+                if (!response.ok) {
+                    // FAIL CLOSED. An unreadable policy is not an empty provider list
+                    // that we may then pad with a guess - it is "we do not know". See
+                    // the PAY-1243 rule: never fabricate a provider list.
+                    throw new Error(`Failed to fetch auth settings: ${response.status}`);
+                }
 
-                    setProviders(oauthProviders);
-                } else {
-                    setProviders([]);
+                const body = await response.json().catch(() => null);
+                const settings = body?.data ?? body;
+                if (body?.success === false || !settings) {
+                    throw new Error(body?.error?.code ?? 'POLICY_UNAVAILABLE');
                 }
 
+                // Keep the raw provider rows (id -> the settings row) for callers that
+                // want more than the mapped union type, exactly as before.
+                const enabledIds: string[] = Array.isArray(settings.enabledProviders)
+                    ? settings.enabledProviders.filter((p: unknown): p is string => typeof p === 'string')
+                    : [];
+                const raw: Record<string, { id: string; name: string }> = {};
+                for (const id of enabledIds) raw[id] = { id, name: id };
+
+                if (!mounted) return;
+                setRawProviders(raw);
+
+                // Filter to OAuth providers only (exclude credentials) and map to our
+                // FederatedProvider union, in the IDP's order.
+                const oauthProviders = enabledIds
+                    .filter(id => OAUTH_PROVIDERS.includes(id))
+                    .map(id => PROVIDER_MAP[id])
+                    .filter((p): p is FederatedProvider => p !== undefined);
+
+                setProviders(oauthProviders);
                 setError(null);
             } catch (err) {
                 if (!mounted) return;
                 setError(err instanceof Error ? err : new Error(String(err)));
                 setProviders([]);
+                setRawProviders(null);   // never leave a stale list behind a failure
             } finally {
                 if (mounted) {
                     setIsLoading(false);

package/src/lib/onboarding-proxy.ts

@@ -0,0 +1,57 @@
+/**
+ * PAY-2121: shared anonymous IDP proxy for the /api/onboarding/* handlers.
+ *
+ * The onboarding flow is TOKEN-DRIVEN: the invitee has no account or session
+ * yet, and the onboard_token IS the credential. So these calls must NOT go
+ * through idpFetchJSON (which injects a Bearer from a Redis session) - there is
+ * no session. They are plain server-to-server POSTs to the IdP, exactly as the
+ * VibeID portal's hand-built /api/onboarding/* routes do (card 182611).
+ *
+ * WHY A SERVER ROUTE AT ALL, AND NOT A BROWSER CALL: the IdP URL is not exposed
+ * to the browser, and the route is the one place that owns that. The token is
+ * forwarded, never the IdP's host.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../config/env';
+import { assertAbsoluteIdpUrl } from './idp-url-guard';
+
+/** A typed refusal in the kit's error envelope - used for a missing field, BEFORE any IdP call. */
+export function onboardingBadRequest(code: string, message: string) {
+  return NextResponse.json({ success: false, message, error: { code } }, { status: 400 });
+}
+
+/**
+ * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * IdP's status and body verbatim (the page acts on what the IdP actually
+ * returns, not on a shape this layer guesses). Never relays the IdP error TEXT
+ * for a non-2xx is NOT done here: the onboarding endpoints answer structured
+ * envelopes the page reads; the page owns the copy.
+ */
+export async function onboardingProxy(req: NextRequest, idpPath: string): Promise<NextResponse> {
+  const idpBase = ENV_CONFIG.IDP_URL;
+  if (!idpBase) {
+    return NextResponse.json({ success: false, message: 'IDP_URL is not configured', error: { code: 'NO_IDP_URL' } }, { status: 500 });
+  }
+  const url = `${idpBase}${idpPath}`;
+  assertAbsoluteIdpUrl(url);
+  let bodyText = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) bodyText = raw;
+  } catch { /* empty body is fine */ }
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
+  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
+  if (xfwd) headers['X-Forwarded-For'] = xfwd;
+  const ua = req.headers.get('user-agent');
+  if (ua) headers['User-Agent'] = ua;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { method: 'POST', headers, body: bodyText, cache: 'no-store' });
+  } catch {
+    return NextResponse.json({ success: false, message: 'The identity service is unreachable.', error: { code: 'UPSTREAM_UNREACHABLE' } }, { status: 502 });
+  }
+  const json = await res.json().catch(() => null);
+  return NextResponse.json(json ?? { success: res.ok }, { status: res.status });
+}

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

@@ -124,3 +124,26 @@ export function projectPasswordPolicyRules(json: unknown): string[] | undefined
   if (!details || details.code !== 'password_policy') return undefined;
   return knownPasswordRules(details.rules);
 }
+
+/**
+ * PAY-2103 (AUTH-009 breached-password check): the IdP refuses a password found in a breach corpus with
+ * the typed code `password_breached` in its 400 validation envelope (error.code, or error.details.code,
+ * or a value[] entry while it settles). The reset-password route is ANONYMOUS, so only a BOOLEAN crosses
+ * (`password_breached: true`), never the code text: the page maps the boolean to its own sentence. Reads
+ * only the code, never IdP text.
+ */
+export function projectPasswordBreached(json: unknown): boolean {
+  if (!json || typeof json !== 'object') return false;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const direct = str(err.code) ?? str(top.code) ?? str(top.error_code);
+  if (direct?.toLowerCase() === 'password_breached') return true;
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (str(details?.code)?.toLowerCase() === 'password_breached') return true;
+  // THE SHAPE THE IdP ACTUALLY SENDS (DotNetPert-Scout, PAY-2103 PR 850caa07a): error.details =
+  // { field:'new_password', code:'password_policy', rules:['password_breached'], requirements:[...] }.
+  // The breach is a member of rules[], not a code - the house envelope carries every password rule
+  // that way. Reading only a code would MISS the real refusal.
+  if (Array.isArray(details?.rules) && (details!.rules as unknown[]).some((r) => typeof r === 'string' && r.toLowerCase() === 'password_breached')) return true;
+  return Array.isArray(details?.value) && (details!.value as unknown[]).some((v) => !!v && typeof v === 'object' && str((v as Record<string, unknown>).code)?.toLowerCase() === 'password_breached');
+}

package/src/middleware/create-middleware.ts

@@ -113,6 +113,30 @@ export interface MvpMiddlewareOptions {
   bypassPaths?: string[];
   /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
   rbacExemptPaths?: string[];
+  /**
+   * PAY-1882 step 4 - how this app treats a producer that reports the session's
+   * revocation status as `'unknown'` (a Vibe read that FAILED: non-OK, timeout,
+   * throw - the status could not be determined).
+   *
+   *   'closed' (DEFAULT) - an unknown revocation status is NOT viable; the
+   *                        session is force-invalidated and the user re-auths.
+   *                        This is Jon's PAY-1880 ruling (option A, fail closed),
+   *                        2026-09-27, and BAPert 66316/66320 restates it for
+   *                        step 4. Consequence, accepted explicitly: a Vibe
+   *                        outage signs this app's users out. 'not_configured'
+   *                        also fails closed here - both live consumers ARE
+   *                        configured (BAPert 66356), so for them it means a
+   *                        misconfiguration, not "no revocation source".
+   *   'open'             - an unknown OR not-configured status stays viable
+   *                        (availability over fail-closed). Per-app opt-out for a
+   *                        deployment with no revocation source, or the two live
+   *                        consumers while Jon decides.
+   *
+   * Neither mode changes `'revoked'` (always force-invalid) or an ABSENT
+   * `revocationStatus` (an older producer - unchanged behaviour, so no consumer
+   * is signed out for not implementing the check).
+   */
+  revocationFailMode?: 'closed' | 'open';
 }
 
 // =============================================================================
@@ -436,6 +460,8 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   const refreshEndpoint = options.refreshEndpoint || '/api/auth/refresh';
   const bypassPaths = options.bypassPaths || [];
   const rbacExemptPaths = options.rbacExemptPaths || [];
+  // PAY-1882 step 4: default 'closed' (Jon's option A / BAPert 66316).
+  const revocationFailMode = options.revocationFailMode || 'closed';
 
   return async function middleware(request: NextRequest): Promise<NextResponse> {
     const { pathname, searchParams } = request.nextUrl;
@@ -472,7 +498,12 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
     }
 
     // --- Fetch session viability from internal API ---
-    const { sessionStatus, sessionPointer } = await checkViability(request, viabilityEndpoint, log);
+    const { sessionStatus, sessionPointer } = await checkViability(
+      request,
+      viabilityEndpoint,
+      log,
+      revocationFailMode
+    );
 
     // --- Stale session (cookie exists but session doesn't): OBSERVE ONLY, DO NOT DECIDE ---
     //
@@ -538,11 +569,43 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   };
 }
 
+/**
+ * The revocation decision, as a pure function (PAY-1882 step 4, NightHawk 66392).
+ *
+ * Separate + exported so the B1 defect is testable with a REAL mutant: the bug was
+ * that `data.forceInvalid === true` was read BEFORE revocationFailMode, so a
+ * producer that folds 'unknown' into forceInvalid made the 'open' lever dead.
+ *
+ * RULE: when the producer supplies `revocationStatus`, it is AUTHORITATIVE - the
+ * decision is made from it plus failMode, and the folded booleans are ignored for
+ * 'unknown'/'not_configured'. The booleans are read ONLY when revocationStatus is
+ * absent (idealresume.online's older boolean-only route).
+ */
+export function decideForceInvalid(
+  data: { revocationStatus?: unknown; forceInvalid?: unknown; revoked?: unknown },
+  revocationFailMode: 'closed' | 'open',
+): boolean {
+  const status = data.revocationStatus;
+  if (typeof status === 'string') {
+    if (status === 'revoked') return true;
+    if (status === 'active') return false;
+    // S1 (NightHawk 66409): ANY other string - 'unknown', 'not_configured', a
+    // typo like 'Revoked', 'error', or '' - is treated as 'unknown' (fail mode
+    // applies), NEVER as 'active'. Returning false here would let the first
+    // producer that emits an unexpected state silently switch revocation OFF -
+    // the exact PAY-1880 fail-open class. Only an explicit 'active' is viable.
+    return revocationFailMode === 'closed';
+  }
+  // No revocationStatus: an older boolean producer. Absence of both stays false.
+  return data.forceInvalid === true || data.revoked === true;
+}
+
 /** Check session viability via internal API */
 async function checkViability(
   request: NextRequest,
   endpoint: string,
-  log: MiddlewareLogger
+  log: MiddlewareLogger,
+  revocationFailMode: 'closed' | 'open'
 ): Promise<{
   sessionStatus: SessionStatus;
   sessionPointer: SessionPointer;
@@ -581,6 +644,46 @@ async function checkViability(
       sessionStatus.exists = data.authenticated ?? (!!data.sessionTokenId && data.reason !== 'session_not_found');
       sessionStatus.requires2FA = data.requires2FA || false;
       sessionStatus.twoFactorComplete = data.twoFactorComplete || false;
+      // --- Session revocation (PAY-1882 Step 4) ---
+      // Two producer spellings are honoured, because both exist on the wire:
+      //   - boolean `forceInvalid` / `revoked` (idealresume.online's route today)
+      //   - the three-state `revocationStatus` the package's own viability
+      //     handlers now emit (PAY-1882 step 4).
+      //
+      // RULING (Jon, via BAPert 66316): 'revoked' ALWAYS fails closed. 'unknown'
+      // (a FAILED Vibe read) fails closed by default and is the ONLY state that
+      // the per-app `revocationFailMode` option can relax to viable.
+      //
+      // Four producer states (BAPert 66320), with the fail-closed ruling for
+      // 'not_configured' added by BAPert 66356:
+      //   'active'         - Vibe read OK, not revoked  -> viable
+      //   'revoked'        - Vibe says revoked          -> force-invalid, ALWAYS
+      //   'unknown'        - read FAILED                -> force-invalid if 'closed'
+      //   'not_configured' - no revocation source       -> force-invalid if 'closed'
+      //
+      // WHY 'not_configured' FAILS CLOSED WHEN 'closed': both live consumers of
+      // this middleware (portal.keelauth.com / keelauth-portal, idealvibe.online)
+      // DO set IDP_URL + VIBE_CLIENT_ID + VIBE_HMAC_KEY (BAPert 66356, measured in
+      // their committed manifests + the graft pipeline's own secret check), so for
+      // them 'not_configured' can only mean a MISCONFIGURATION - revocation
+      // silently switched off is exactly the PAY-1880 fail-open bug. An app with
+      // no revocation source that genuinely wants availability sets
+      // revocationFailMode 'open'.
+      //
+      // A MISSING revocationStatus (an older producer) keeps today's behaviour,
+      // i.e. NOT force-invalid: absence must never sign out a population that
+      // never opted into the check.
+      //
+      // *** revocationStatus IS AUTHORITATIVE WHEN PRESENT (NightHawk 66392). ***
+      // The package's own producers emit `forceInvalid: revocationStatus ===
+      // 'revoked' || revocationStatus === 'unknown'`. If the boolean were read
+      // FIRST, `forceInvalid: true` would short-circuit before revocationFailMode
+      // was consulted, so `'open'` could never keep an 'unknown' session viable -
+      // the opt-out lever would be DEAD. So: when a producer supplies a
+      // revocations status, decide from it + failMode and ignore the folded
+      // booleans for unknown/not_configured. The booleans are read ONLY when
+      // revocationStatus is ABSENT (idealresume.online's older boolean route).
+      sessionStatus.forceInvalid = decideForceInvalid(data, revocationFailMode);
       sessionPointer.exists = sessionStatus.exists ?? false;
       sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
       sessionPointer.expired = data.accessTokenExpired || false;
@@ -792,3 +895,4 @@ async function handleRefresh(
     );
   }
 }
+