@payez/next-mvp 4.4.7 → 4.4.9

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(
     );
   }
 }
+

package/src/routes/auth/viability.ts

@@ -23,6 +23,7 @@ import {
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 import { tokenLogId } from '../../lib/token-log-id';
+import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
 
 /**
  * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
@@ -262,6 +263,40 @@ export async function GET(req: NextRequest) {
       session?.mfaVerified === false &&
       !(session.idpRefreshToken || (session as any)?.refreshToken);
 
+    // --- Session revocation status (PAY-1882 step 4 producer half) ---
+    /*
+     * Resolve the four-state revocation status for this user (BAPert 66320).
+     * Read it HERE, above every authenticated return, so all three responses
+     * carry the SAME value - the same discipline as nextStep above.
+     *
+     * 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 - so shipping this changes nothing for them until they opt in.
+     */
+    let revocationStatus: RevocationStatus = 'not_configured';
+    if (session) {
+      // 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(session, (session as any).idpAccessToken);
+      if (revocationUserId > 0) {
+        try {
+          revocationStatus = await getRevocationStatus(revocationUserId, sessionToken);
+        } catch {
+          // getRevocationStatus does not throw by contract, but never let a
+          // revocation probe take down the viability answer: fail closed.
+          revocationStatus = 'unknown';
+        }
+      } else {
+        // N1 (NightHawk 66392): a session exists but carries no usable numeric
+        // IdP id, so the check could not run -> 'unknown' (could not determine),
+        // NOT 'not_configured' (no revocation source).
+        // BAPert 66480 condition 1: emit ONE WARN (shape only) so a non-numeric
+        // id surfaces as a log line, not an unexplained sign-out.
+        revocationStatus = warnNonNumericUserId(sessionToken, session.userId);
+      }
+    }
+
     // Check access token expiry
     const now = Math.floor(Date.now() / 1000);
     // 240654 addendum 2: fall back to the Redis session's own expiry.
@@ -312,6 +347,11 @@ export async function GET(req: NextRequest) {
         needsRefresh: true,
         authenticated: true,
         sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
+        // 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',
         // Clear names for middleware decision-making
         tenantRequiresTwoFactor,
         userHasCompletedTenantTwoFactorRequirements,
@@ -393,6 +433,10 @@ export async function GET(req: NextRequest) {
         twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
         accessTokenExpired: true,
         reason: 'Token expired',
+        // Session revocation (PAY-1882 step 4) - same value on every return.
+        revocationStatus,
+        forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
+        revoked: revocationStatus === 'revoked',
         // RBAC fields
         roles: session?.roles || [],
         clientId: resolveClientId(session?.idpClientId),
@@ -406,6 +450,10 @@ export async function GET(req: NextRequest) {
       hasRefreshToken,
       authenticated: true,
       sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
+      // Session revocation (PAY-1882 step 4) - same value on every return.
+      revocationStatus,
+      forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
+      revoked: revocationStatus === 'revoked',
       // Clear names
       tenantRequiresTwoFactor,
       userHasCompletedTenantTwoFactorRequirements,
@@ -428,6 +476,10 @@ export async function GET(req: NextRequest) {
       viable: false,
       needsRefresh: false,
       authenticated: false,
+      // PAY-1882 step 4: an exception here means the status could not be read.
+      // Report 'unknown' (not a bare 500 with no revocation signal) so the
+      // middleware's fail-closed default applies rather than reading it as viable.
+      revocationStatus: 'unknown' as RevocationStatus,
       error: 'Failed to check session',
       code: 'INTERNAL_ERROR',
       correlationId

package/src/utils/api.ts

@@ -107,6 +107,13 @@ export const RECOVERY_EXPIRED_TEXT = 'This reset link has expired or was already
 
 export const RESET_NEUTRAL_TEXT = "We couldn't set that password. Check it meets the requirements shown and try again.";
 
+/**
+ * PAY-2103 (AUTH-009): the IdP refuses a password found in a breach corpus; the route projects a
+ * `password_breached: true` boolean, and the user reads this. Distinct from the policy sentence,
+ * which would wrongly tell them to re-read the requirements.
+ */
+export const RESET_BREACHED_TEXT = 'This password appears in a known data breach. Choose a different one.';
+
 /**
  * Three tiers for a 400/422 from reset (rigpert 60822, QAPert 60820), decided ONLY on codes the IdP actually sends:
  *   policy        details.code password_policy (projected by the handler as password_policy) -> the rule sentences
@@ -233,7 +240,9 @@ export class AccountApi {
             const policy = !!body?.password_policy;
             const rules = knownPasswordRules(body?.password_policy?.rules);
             const tokenInvalid = body?.reset_token_invalid === true;
-            const err = new Error(resetFailureText(res.status, rules, policy, tokenInvalid)) as Error & { rules?: string[]; code?: string };
+            // PAY-2103: a breached password is its own outcome, not a policy refusal.
+            const breached = body?.password_breached === true;
+            const err = new Error(breached ? RESET_BREACHED_TEXT : resetFailureText(res.status, rules, policy, tokenInvalid)) as Error & { rules?: string[]; code?: string };
             if (rules.length) err.rules = rules;
             if ((res.status === 400 || res.status === 422) && tokenInvalid && !policy) err.code = 'RECOVERY_EXPIRED';
             throw err;

package/src/vibe/sessions.ts

@@ -33,6 +33,7 @@ import crypto from 'crypto';
 import type { IVibeLoginSession, SessionStatus } from './types';
 import type { LocationInfo } from '../lib/geolocation';
 import type { DeviceInfo } from '../lib/user-agent-parser';
+import { decodeIdpAccessToken } from '../auth/utils/token-utils';
 
 // -----------------------------------------------------------------------------
 // CONFIGURATION
@@ -74,7 +75,7 @@ function generateHmacSignature(
  */
 async function vibeProxyRequest<T>(
   endpoint: string,
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
   accessToken: string,
   body?: unknown
 ): Promise<T | null> {
@@ -262,7 +263,9 @@ export async function getUserSessions(
     'POST',
     accessToken,
     {
-      filter: [{ field: 'idp_user_id', operator: 'eq', value: idpUserId }],
+      // PAY-2037: a flat VibeFilterNode OBJECT, as idealresume sends it (vibe-sessions.ts:220). Core binds
+      // QueryRequest.Filter as an object (VibeQueryBuilder.cs IsFlatFilterFormat); an ARRAY does not bind.
+      filter: { field: 'idp_user_id', operator: 'eq', value: idpUserId },
       pageSize: 100,
     }
   );
@@ -288,12 +291,13 @@ export async function getAllSessions(
   const query: Record<string, unknown> = {
     page,
     pageSize,
-    orderBy: 'created_at',
-    orderDir: 'desc',
+    // PAY-2037: Vibe's QueryRequest.OrderBy is an OBJECT; a string is a 400 and vibeProxyRequest
+    // turned that into an empty list. There is no `orderDir` (QAPert 69149).
+    orderBy: { created_at: 'desc' },
   };
 
   if (options.status) {
-    query.filter = [{ field: 'status', operator: 'eq', value: options.status }];
+    query.filter = { field: 'status', operator: 'eq', value: options.status };
   }
 
   const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
@@ -345,11 +349,11 @@ export async function revokeSession(
   reason?: string
 ): Promise<IVibeLoginSession | null> {
   const now = new Date().toISOString();
-
+  // PAY-2037: PATCH, not PUT - a PUT replaces the row and this body carries 4 of its fields.
   const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/${sessionId}`;
   const session = await vibeProxyRequest<IVibeLoginSession>(
     endpoint,
-    'PUT',
+    'PATCH',
     accessToken,
     {
       status: 'revoked',
@@ -414,7 +418,7 @@ export async function updateSessionActivity(
   const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/${sessionId}`;
   const result = await vibeProxyRequest<IVibeLoginSession>(
     endpoint,
-    'PUT',
+    'PATCH',
     accessToken,
     { last_activity: new Date().toISOString() }
   );
@@ -460,33 +464,296 @@ export async function isSessionValid(
  * @param accessToken - Access token for auth
  * @param sessionTokenHash - Optional token hash to check specific session
  * @returns Revoked session info if enforcement needed, null otherwise
+ *
+ * @deprecated PAY-2037 step 1 (BAPert 69153): kept so no consumer breaks. It is a thin call into the
+ * same hash-first decision as getRevocationStatus; prefer getRevocationStatus, which distinguishes
+ * a failed read ('unknown') from 'active' instead of throwing.
  */
 export async function checkSessionRevocation(
   idpUserId: number,
-  accessToken: string,
+  _accessToken: string,
   sessionTokenHash?: string
 ): Promise<IVibeLoginSession | null> {
-  const sessions = await getUserSessions(idpUserId, accessToken);
+  // PAY-2037 step 1: same decision as getRevocationStatus, same HMAC-only read. The bearer is
+  // accepted for signature compatibility and never sent. A FAILED read throws - it must not read
+  // as "no revoked session" (that is the PAY-1880 fail-open this replaces).
+  const { ok, sessions } = await readSessionRevocationHmac(idpUserId);
+  if (!ok) {
+    throw new Error('[vibe-sessions] session revocation read failed (fail closed)');
+  }
+  return findRevokingSession(sessions, sessionTokenHash);
+}
 
-  // If we have a specific token hash, check that session
-  if (sessionTokenHash) {
-    const matchingSession = sessions.find(s => s.session_token_hash === sessionTokenHash);
-    if (matchingSession && matchingSession.status === 'revoked') {
-      return matchingSession;
+// -----------------------------------------------------------------------------
+// REVOCATION STATUS (PAY-1882 step 4 producer half)
+// -----------------------------------------------------------------------------
+
+/** The four states a viability producer can report (BAPert 66320). */
+export type RevocationStatus = 'active' | 'revoked' | 'unknown' | 'not_configured';
+
+// BAPert 66320: log 'not_configured' ONCE, not per request - a Vibe-less
+// deployment would otherwise emit a warn line on every viability check.
+let warnedNotConfigured = false;
+
+/**
+ * Hash a session token the same way record-login stores it.
+ * SHA256 hex, 64 chars. This must stay byte-identical to
+ * `hashSessionToken` in the consumers (idealresume.online/lib/session-token-hash.ts)
+ * or per-session matching silently falls back to the user-wide path.
+ */
+export function hashSessionToken(token: string): string {
+  return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+/**
+ * BAPert 66480 condition 2 (ruling (ii), 66700; corrected per QAPert 66729):
+ * resolve the NUMERIC IdP user id the Vibe query filters on.
+ *
+ * *** DO NOT READ `sub` FOR THE USER ID. *** In the IdP's bearer token `sub` is the
+ * USERNAME, not the id: AESGCM_Encryption.cs:815 writes `{ "sub", payload.Username }`
+ * and :822 writes `{ "user_id", payload.UserId.ToString() }`. A username is commonly
+ * an email, so reading `sub` yields 0 for the common case - and for a username that
+ * happens to be all digits it yields the WRONG id, which getRevocationStatus answers
+ * 'active' for a user with no rows: a fail-OPEN.
+ *
+ * Resolution order:
+ *   1. the token's `user_id` claim, when it is all digits;
+ *   2. a digits-only session.userId / session.user.id;
+ *   3. otherwise 0 (unresolvable), which the caller reports as 'unknown' (fail closed).
+ *
+ * session.userId is not a safe source on its own either: session-store.ts:143 falls
+ * back to user.email, and better-auth.ts stringifies whichever id it finds.
+ */
+export function resolveNumericIdpUserId(session: unknown, accessToken?: string): number {
+  const isDigits = (v: unknown) => /^[0-9]+$/.test(String(v ?? ''));
+  if (accessToken) {
+    // The raw payload (jwtDecode returns every claim, typed or not); user_id, never sub.
+    const payload = decodeIdpAccessToken(accessToken) as Record<string, unknown> | null;
+    const claim = payload?.user_id;
+    if (isDigits(claim)) return Number(claim);
+  }
+  const s = (session ?? {}) as Record<string, any>;
+  const fromSession = s.userId ?? s.user?.id;
+  return isDigits(fromSession) ? Number(fromSession) : 0;
+}
+
+/**
+ * BAPert 66480 condition 1: WARN once per session when the numeric IdP user id
+ * could not be resolved (userId is email-shaped, empty, or otherwise not all
+ * digits). A non-numeric id must show up as a log line, not as an unexplained
+ * sign-out. Shape only - NEVER the value.
+ *
+ * Keyed on a hash of the session token, so one WARN per session; the set is
+ * bounded so a long-lived process cannot grow it without limit.
+ */
+const warnedNonNumericUserIds = new Set<string>();
+
+function shapeOfUserId(v: unknown): string {
+  const str = String(v ?? '');
+  if (!str) return 'empty:0';
+  const kind = /^[0-9]+$/.test(str) ? 'digits' : str.includes('@') ? 'email' : 'other';
+  return `${kind}:${str.length}`;
+}
+
+function warnNonNumericUserIdOnce(sessionToken: string | undefined, rawUserId: unknown): void {
+  const key = sessionToken ? hashSessionToken(sessionToken).slice(0, 16) : `nosession:${shapeOfUserId(rawUserId)}`;
+  if (warnedNonNumericUserIds.has(key)) return;
+  if (warnedNonNumericUserIds.size > 5000) warnedNonNumericUserIds.clear();
+  warnedNonNumericUserIds.add(key);
+  console.warn('[REVOCATION] non-numeric userId, failing closed', { shape: shapeOfUserId(rawUserId) });
+}
+
+/**
+ * Public entry point for the twins: call this when a session exists but its
+ * userId is not a usable numeric IdP id. Returns 'unknown' (fail closed) and
+ * emits the once-per-session WARN. Shape only, never the value.
+ */
+export function warnNonNumericUserId(sessionToken: string | undefined, rawUserId: unknown): 'unknown' {
+  warnNonNumericUserIdOnce(sessionToken, rawUserId);
+  return 'unknown';
+}
+
+/**
+ * HMAC-ONLY session read for the revocation check (PAY-1882 step 4).
+ *
+ * *** DO NOT "SIMPLIFY" THIS ONTO vibeProxyRequest/getUserSessions. ***
+ * It is deliberately separate and deliberately sends NO Authorization header.
+ *
+ * WHY: the twin this must match is idealresume.online's checkSessionRevocation
+ * read. That repo's vibe-client adds `Authorization: Bearer` ONLY for member
+ * paths (`path.startsWith('/v1/my/')`) - see idealresume.online/lib/vibe-client.ts
+ * :207-210 - so its /v1/collections/.../query for this check goes out HMAC-only.
+ * The comment at vibe-client.ts:188-206 there records why: a bearer on the
+ * collections path caused USER_REQUIRED and broke signups. getUserSessions()
+ * here ALWAYS sends the bearer, so it cannot stand in for this read without
+ * changing the credential the two twins are supposed to share.
+ *
+ * BAPert 66344 (option a): match the twin, HMAC-only.
+ *
+ * Also distinguishes a FAILED read from an EMPTY one - getUserSessions()
+ * collapses a proxy outage and "user has no sessions" to `[]`, which is
+ * fail-OPEN for a revocation decision. Returns `ok:false` on an outage so the
+ * caller fails closed, and `ok:true, sessions:[]` only for a healthy empty.
+ */
+export async function readSessionRevocationHmac(
+  idpUserId: number
+): Promise<{ ok: boolean; sessions: IVibeLoginSession[] }> {
+  const idpUrl = getEnv('IDP_URL');
+  const clientId = getEnv('VIBE_CLIENT_ID');
+  const signingKey = getEnv('VIBE_HMAC_KEY');
+
+  if (!idpUrl || !clientId || !signingKey) {
+    // Caller distinguishes this from a read failure; report ok:false, not [].
+    return { ok: false, sessions: [] };
+  }
+
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
+  const proxyUrl = `${idpUrl}/api/vibe/proxy`;
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signature = generateHmacSignature(signingKey, timestamp, 'POST', endpoint);
+
+  // NOTE the absence of Authorization. This is the twin's credential.
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-Vibe-Client-Id': clientId,
+    'X-Vibe-Timestamp': String(timestamp),
+    'X-Vibe-Signature': signature,
+  };
+
+  try {
+    const response = await fetch(proxyUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        endpoint,
+        method: 'POST',
+        data: {
+          // PAY-2037: a flat VibeFilterNode OBJECT, as idealresume sends it (vibe-sessions.ts:220). Core binds
+      // QueryRequest.Filter as an object (VibeQueryBuilder.cs IsFlatFilterFormat); an ARRAY does not bind.
+      filter: { field: 'idp_user_id', operator: 'eq', value: idpUserId },
+          pageSize: 100,
+        },
+      }),
+    });
+
+    if (!response.ok) {
+      // PAY-1427: never the raw proxy body - an error page can echo the request.
+      console.error(`[vibe-sessions] Revocation read proxy error ${response.status}`);
+      return { ok: false, sessions: [] };
     }
+
+    const data = await response.json();
+    const unwrapped = (data?.data ?? data) as { data?: IVibeLoginSession[]; items?: IVibeLoginSession[] };
+    return { ok: true, sessions: unwrapped?.data || unwrapped?.items || [] };
+  } catch (error) {
+    console.error('[vibe-sessions] Revocation read failed:', error);
+    return { ok: false, sessions: [] };
+  }
+}
+
+/**
+ * THE one revocation decision (PAY-2037 step 1, BAPert 69150): hash-first, per session.
+ * Returns the row that revokes THIS session, or null when it is not revoked.
+ *
+ * A session whose own token hash matches a row is decided by that row ALONE. A matched ACTIVE
+ * session is never logged out because another device was revoked (idealresume PAY-1882 F3).
+ * Only when no row carries the hash (a legacy row minted before hashing) does the user-wide
+ * rule apply: no active row -> the most recently revoked (none revoked: not revoked); else any revoked inside 2h.
+ */
+function findRevokingSession(
+  sessions: IVibeLoginSession[],
+  sessionTokenHash?: string
+): IVibeLoginSession | null {
+  if (sessions.length === 0) return null;
+
+  if (sessionTokenHash) {
+    const matching = sessions.find(s => s.session_token_hash === sessionTokenHash);
+    if (matching) return matching.status === 'revoked' ? matching : null;
+  }
+
+  // Hash not found (a legacy row minted before hashing) or no hash given: idealresume's user-wide
+  // rules, lib/vibe-sessions.ts:594-651 (BAPert 69189).
+  const revokedAt = (s: IVibeLoginSession) => (s.revoked_at ? new Date(s.revoked_at).getTime() : 0);
+  const newestFirst = (x: IVibeLoginSession, y: IVibeLoginSession) => revokedAt(y) - revokedAt(x);
+
+  // Check 1: no active row. The most recently revoked row (whenever it was revoked) is the verdict.
+  // All rows expired and none revoked is NOT revoked: expiry is not revocation.
+  if (!sessions.some(s => s.status === 'active')) {
+    const revoked = sessions.filter(s => s.status === 'revoked' && s.revoked_at).sort(newestFirst);
+    if (revoked.length > 0) return revoked[0];
   }
 
-  // Otherwise, check if there are any recently revoked sessions
-  // (revoked within the last hour - gives time for enforcement)
-  const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
-  const recentlyRevoked = sessions.find(
-    s =>
-      s.status === 'revoked' &&
-      s.revoked_at &&
-      new Date(s.revoked_at) > oneHourAgo
+  // Check 2: any row revoked in the last TWO hours (idealresume's window; 5-minute polling needs the time).
+  const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
+  return (
+    sessions.filter(s => s.status === 'revoked' && revokedAt(s) > twoHoursAgo).sort(newestFirst)[0] ?? null
   );
+}
+
+/**
+ * Determine whether a session is revoked, with an explicit UNKNOWN state
+ * (PAY-1882 step 4 producer half).
+ *
+ * States:
+ *   'not_configured' - this deployment has no revocation source (IDP_URL /
+ *                      VIBE_CLIENT_ID / VIBE_HMAC_KEY absent). Viable; today's
+ *                      behaviour. Logged once, not per request.
+ *   'unknown'        - revocation IS configured but the read FAILED (non-OK,
+ *                      timeout, throw). Enforcing middleware fails this CLOSED
+ *                      by default (revocationFailMode 'closed'); a Vibe-less
+ *                      consumer is 'not_configured', not 'unknown', so it is not
+ *                      signed out.
+ *   'revoked'        - the session's own token hash matches a revoked row, or
+ *                      the user has no active session at all.
+ *   'active'         - read OK and the session is not revoked.
+ *
+ * @param idpUserId - The user's IDP ID
+ * @param sessionToken - The live session token; hashed to match the stored row.
+ *                       When absent, the user-wide check applies (legacy path).
+ */
+export async function getRevocationStatus(
+  idpUserId: number,
+  sessionToken?: string
+): Promise<RevocationStatus> {
+  const idpUrl = getEnv('IDP_URL');
+  const clientId = getEnv('VIBE_CLIENT_ID');
+  const signingKey = getEnv('VIBE_HMAC_KEY');
+
+  // 'not_configured' is reserved for an app with NO revocation source at all:
+  // no VIBE_CLIENT_ID. BAPert 66320 - "the app has no revocation source
+  // (VIBE_CLIENT_ID absent / revocation not enabled)". Such a consumer stays
+  // viable, or a Vibe-less app would sign everyone out on every request.
+  if (!clientId) {
+    if (!warnedNotConfigured) {
+      warnedNotConfigured = true;
+      console.warn(
+        '[vibe-sessions] Revocation check not configured (VIBE_CLIENT_ID absent) - reporting not_configured (logged once)'
+      );
+    }
+    return 'not_configured';
+  }
+
+  // A client id IS present, so this app is a Vibe consumer that intends the
+  // revocation check - but the read is MISCONFIGURED (IDP_URL or VIBE_HMAC_KEY
+  // missing). BAPert 66344 condition 2: FAIL CLOSED. Do NOT fall back to bearer,
+  // do NOT report "no sessions". 'unknown' is the fail-closed state.
+  if (!idpUrl || !signingKey) {
+    console.warn(
+      '[vibe-sessions] Revocation check MISCONFIGURED (VIBE_CLIENT_ID set but IDP_URL/VIBE_HMAC_KEY missing) - reporting unknown (fail closed)'
+    );
+    return 'unknown';
+  }
+
+  const { ok, sessions } = await readSessionRevocationHmac(idpUserId);
+
+  if (!ok) {
+    console.warn('[vibe-sessions] Revocation read failed - reporting unknown');
+    return 'unknown';
+  }
 
-  return recentlyRevoked || null;
+  return findRevokingSession(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined)
+    ? 'revoked'
+    : 'active';
 }
 
 // -----------------------------------------------------------------------------