@payez/next-mvp 4.5.0 → 4.5.1

package/src/vibe/document-unwrap.ts

@@ -1,103 +1,103 @@
-/**
- * Vibe document wrapper + unwrapping.
- *
- * PAY-1767: extracted from generic.ts into its own module so the typed client (client.ts) can unwrap
- * reads WITHOUT importing generic.ts - generic.ts imports client.ts, so a shared helper there would be
- * a cycle. This module imports nothing from the vibe client.
- *
- * Vibe stores a row's own fields as a JSON STRING under the wrapper's `data` field, alongside storage
- * columns (document_id, owner, timestamps). A caller that renders `response.data` directly sees the
- * wrapper, so `row.name` is undefined. unwrapVibeDocument flattens the row out and keeps the storage
- * document_id as `_vibe_doc_id` for update/delete paths.
- */
-
-/** Vibe document wrapper structure. Vibe stores actual table data as a JSON string in the 'data' field. */
-export interface VibeDocumentWrapper {
-  document_id: number;
-  client_id?: number;
-  user_id?: number;
-  collection?: string;
-  table_name?: string;
-  data: string | Record<string, unknown>;
-  collection_schema_id?: number;
-  created_at?: string;
-  created_by?: number;
-  updated_at?: string | null;
-  updated_by?: number | null;
-  deleted_at?: string | null;
-}
-
-/**
- * Unwrap a Vibe document response.
- *
- * @param doc - Raw Vibe document (wrapper format)
- * @returns Unwrapped document with schema fields only; storage document_id preserved as `_vibe_doc_id`
- *          for update/delete paths. See PayEz-Core/docs/vibe-primary-key-standard.md
- *
- * @example
- * const raw = { document_id: 123, data: '{"user_id":15,"name":"John"}' };
- * unwrapVibeDocument(raw); // => { user_id: 15, name: 'John', _vibe_doc_id: 123 }
- */
-export function unwrapVibeDocument<T extends object = Record<string, unknown>>(
-  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
-): (T & { _vibe_doc_id?: number }) | null {
-  if (!doc) return null;
-
-  // Handle case where doc is already unwrapped (has schema fields directly)
-  if (!('document_id' in doc) && !('data' in doc)) {
-    return doc as T & { _vibe_doc_id?: number };
-  }
-
-  const wrapper = doc as VibeDocumentWrapper;
-  let parsedData: Record<string, unknown> = {};
-
-  if (typeof wrapper.data === 'string') {
-    try {
-      parsedData = JSON.parse(wrapper.data);
-    } catch {
-      console.warn('[vibe-document] Failed to parse document data JSON:', wrapper.data);
-      parsedData = {};
-    }
-  } else if (typeof wrapper.data === 'object' && wrapper.data !== null) {
-    parsedData = wrapper.data;
-  }
-
-  // Preserve document_id as _vibe_doc_id for Vibe API update/delete paths only
-  const documentId = wrapper.document_id ?? (doc as { document_id?: number }).document_id;
-  if (documentId != null) {
-    parsedData._vibe_doc_id = documentId;
-  }
-
-  return parsedData as T & { _vibe_doc_id?: number };
-}
-
-/**
- * Extract and unwrap an array of documents from a Vibe response.
- *
- * @param responseData - Raw Vibe API response ({ data: [...] }, { items: [...] }, { documents: [...] } or a bare array)
- * @returns Array of unwrapped documents
- */
-export function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(
-  responseData: unknown
-): Array<T & { _vibe_doc_id?: number }> {
-  if (!responseData || typeof responseData !== 'object') {
-    return [];
-  }
-
-  const data = responseData as Record<string, unknown>;
-
-  // Try common response shapes
-  const docs =
-    data.data ??
-    data.items ??
-    data.documents ??
-    (Array.isArray(responseData) ? responseData : null);
-
-  if (!Array.isArray(docs)) {
-    return [];
-  }
-
-  return docs
-    .map((doc) => unwrapVibeDocument<T>(doc))
-    .filter((d): d is T & { _vibe_doc_id?: number } => d !== null);
-}
+/**
+ * Vibe document wrapper + unwrapping.
+ *
+ * PAY-1767: extracted from generic.ts into its own module so the typed client (client.ts) can unwrap
+ * reads WITHOUT importing generic.ts - generic.ts imports client.ts, so a shared helper there would be
+ * a cycle. This module imports nothing from the vibe client.
+ *
+ * Vibe stores a row's own fields as a JSON STRING under the wrapper's `data` field, alongside storage
+ * columns (document_id, owner, timestamps). A caller that renders `response.data` directly sees the
+ * wrapper, so `row.name` is undefined. unwrapVibeDocument flattens the row out and keeps the storage
+ * document_id as `_vibe_doc_id` for update/delete paths.
+ */
+
+/** Vibe document wrapper structure. Vibe stores actual table data as a JSON string in the 'data' field. */
+export interface VibeDocumentWrapper {
+  document_id: number;
+  client_id?: number;
+  user_id?: number;
+  collection?: string;
+  table_name?: string;
+  data: string | Record<string, unknown>;
+  collection_schema_id?: number;
+  created_at?: string;
+  created_by?: number;
+  updated_at?: string | null;
+  updated_by?: number | null;
+  deleted_at?: string | null;
+}
+
+/**
+ * Unwrap a Vibe document response.
+ *
+ * @param doc - Raw Vibe document (wrapper format)
+ * @returns Unwrapped document with schema fields only; storage document_id preserved as `_vibe_doc_id`
+ *          for update/delete paths. See PayEz-Core/docs/vibe-primary-key-standard.md
+ *
+ * @example
+ * const raw = { document_id: 123, data: '{"user_id":15,"name":"John"}' };
+ * unwrapVibeDocument(raw); // => { user_id: 15, name: 'John', _vibe_doc_id: 123 }
+ */
+export function unwrapVibeDocument<T extends object = Record<string, unknown>>(
+  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
+): (T & { _vibe_doc_id?: number }) | null {
+  if (!doc) return null;
+
+  // Handle case where doc is already unwrapped (has schema fields directly)
+  if (!('document_id' in doc) && !('data' in doc)) {
+    return doc as T & { _vibe_doc_id?: number };
+  }
+
+  const wrapper = doc as VibeDocumentWrapper;
+  let parsedData: Record<string, unknown> = {};
+
+  if (typeof wrapper.data === 'string') {
+    try {
+      parsedData = JSON.parse(wrapper.data);
+    } catch {
+      console.warn('[vibe-document] Failed to parse document data JSON:', wrapper.data);
+      parsedData = {};
+    }
+  } else if (typeof wrapper.data === 'object' && wrapper.data !== null) {
+    parsedData = wrapper.data;
+  }
+
+  // Preserve document_id as _vibe_doc_id for Vibe API update/delete paths only
+  const documentId = wrapper.document_id ?? (doc as { document_id?: number }).document_id;
+  if (documentId != null) {
+    parsedData._vibe_doc_id = documentId;
+  }
+
+  return parsedData as T & { _vibe_doc_id?: number };
+}
+
+/**
+ * Extract and unwrap an array of documents from a Vibe response.
+ *
+ * @param responseData - Raw Vibe API response ({ data: [...] }, { items: [...] }, { documents: [...] } or a bare array)
+ * @returns Array of unwrapped documents
+ */
+export function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(
+  responseData: unknown
+): Array<T & { _vibe_doc_id?: number }> {
+  if (!responseData || typeof responseData !== 'object') {
+    return [];
+  }
+
+  const data = responseData as Record<string, unknown>;
+
+  // Try common response shapes
+  const docs =
+    data.data ??
+    data.items ??
+    data.documents ??
+    (Array.isArray(responseData) ? responseData : null);
+
+  if (!Array.isArray(docs)) {
+    return [];
+  }
+
+  return docs
+    .map((doc) => unwrapVibeDocument<T>(doc))
+    .filter((d): d is T & { _vibe_doc_id?: number } => d !== null);
+}

package/src/vibe/sessions.ts

@@ -34,6 +34,7 @@ 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';
+import { tokenLogId } from '../lib/token-log-id';
 
 // -----------------------------------------------------------------------------
 // CONFIGURATION
@@ -597,31 +598,31 @@ export function warnNonNumericUserId(sessionToken: string | undefined, rawUserId
  */
 export async function readSessionRevocationHmac(
   idpUserId: number
-): Promise<{ ok: boolean; sessions: IVibeLoginSession[] }> {
+): Promise<{ ok: boolean; sessions: IVibeLoginSession[]; failure?: string }> {
   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: [] };
+    return { ok: false, sessions: [], failure: 'misconfigured' };
   }
 
   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, {
+  // Signed per ATTEMPT: the retry below must not reuse a timestamp that has aged.
+  const send = (): Promise<Response> => {
+    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,
+    };
+    return fetch(proxyUrl, {
       method: 'POST',
       headers,
       body: JSON.stringify({
@@ -635,11 +636,24 @@ export async function readSessionRevocationHmac(
         },
       }),
     });
+  };
+
+  try {
+    let response = await send();
+
+    // PAY-2136: ONE retry, and only for the transient class. The portal's own prefetch burst exceeds the free
+    // tier's concurrency (CONCURRENT_LIMIT, HTTP 429). Keyed on the BODY code, never on Retry-After: the IdP proxy
+    // relays body and status but drops that header (PAY-2143). AUTH_BLOCKED / other 429s and every 5xx are NOT
+    // retried (a block is not transient; a retry only adds a counted failure).
+    if (response.status === 429 && isConcurrentLimitBody(await safeBodyText(response))) {
+      await new Promise((resolve) => setTimeout(resolve, revocationRetryDelayMs(response)));
+      response = await send();
+    }
 
     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: [] };
+      return { ok: false, sessions: [], failure: String(response.status) }; // PAY-2136: status only, for the reason log
     }
 
     const data = await response.json();
@@ -647,10 +661,39 @@ export async function readSessionRevocationHmac(
     return { ok: true, sessions: unwrapped?.data || unwrapped?.items || [] };
   } catch (error) {
     console.error('[vibe-sessions] Revocation read failed:', error);
-    return { ok: false, sessions: [] };
+    return { ok: false, sessions: [], failure: 'exception' };
+  }
+}
+
+/** Body text of a response WITHOUT consuming the caller's copy; '' on any failure. */
+async function safeBodyText(response: Response): Promise<string> {
+  try {
+    return await response.clone().text();
+  } catch {
+    return '';
+  }
+}
+
+/** True only for the exact code CONCURRENT_LIMIT (nested error.code, top-level code/errorCode); a non-JSON body falls back to the literal. */
+export function isConcurrentLimitBody(bodyText: string): boolean {
+  try {
+    const b = JSON.parse(bodyText) as Record<string, unknown>;
+    const nested = (b?.error as Record<string, unknown> | undefined)?.code;
+    const code = [nested, b?.code, b?.errorCode].find((c) => typeof c === 'string');
+    if (typeof code === 'string') return code === 'CONCURRENT_LIMIT';
+    return false;
+  } catch {
+    return /CONCURRENT_LIMIT/.test(bodyText);
   }
 }
 
+/** Retry-After seconds when the proxy kept it (capped at 2 s: this runs in the request path), else 200-400 ms jitter. */
+export function revocationRetryDelayMs(response: Response): number {
+  const ra = Number(response.headers?.get?.('retry-after'));
+  if (Number.isFinite(ra) && ra > 0) return Math.min(ra * 1000, 2000);
+  return 200 + Math.floor(Math.random() * 200);
+}
+
 /**
  * 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.
@@ -664,11 +707,21 @@ function findRevokingSession(
   sessions: IVibeLoginSession[],
   sessionTokenHash?: string
 ): IVibeLoginSession | null {
-  if (sessions.length === 0) return null;
+  return findRevokingSessionWithRule(sessions, sessionTokenHash).row;
+}
+
+/** Which branch of the revocation decision produced the verdict (PAY-2136 reason log; never a value). */
+export type RevocationRule = 'own_row_revoked' | 'legacy_no_active' | 'legacy_recent_2h' | 'none';
+
+function findRevokingSessionWithRule(
+  sessions: IVibeLoginSession[],
+  sessionTokenHash?: string
+): { row: IVibeLoginSession | null; rule: RevocationRule } {
+  if (sessions.length === 0) return { row: null, rule: 'none' };
 
   if (sessionTokenHash) {
     const matching = sessions.find(s => s.session_token_hash === sessionTokenHash);
-    if (matching) return matching.status === 'revoked' ? matching : null;
+    if (matching) return matching.status === 'revoked' ? { row: matching, rule: 'own_row_revoked' } : { row: null, rule: 'none' };
   }
 
   // Hash not found (a legacy row minted before hashing) or no hash given: idealresume's user-wide
@@ -680,14 +733,36 @@ function findRevokingSession(
   // 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];
+    if (revoked.length > 0) return { row: revoked[0], rule: 'legacy_no_active' };
   }
 
   // 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
-  );
+  const recent = sessions.filter(s => s.status === 'revoked' && revokedAt(s) > twoHoursAgo).sort(newestFirst)[0] ?? null;
+  return recent ? { row: recent, rule: 'legacy_recent_2h' } : { row: null, rule: 'none' };
+}
+
+/**
+ * PAY-2136: one shape-only line per NON-viable revocation verdict, naming WHICH rule fired. Never a token, userId,
+ * hash, or row content: the rule label, a read-failure status code, a row COUNT and the session's tokenLogId.
+ * Must never throw into the viability path.
+ */
+function logRevocationReason(
+  verdict: 'revoked' | 'unknown',
+  reason: string,
+  sessionToken: string | undefined,
+  extra: Record<string, number> = {}
+): void {
+  try {
+    console.warn('[REVOCATION] verdict', {
+      verdict,
+      reason,
+      sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
+      ...extra,
+    });
+  } catch {
+    /* diagnostic only */
+  }
 }
 
 /**
@@ -711,7 +786,7 @@ function findRevokingSession(
  * @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(
+async function readRevocationStatus(
   idpUserId: number,
   sessionToken?: string
 ): Promise<RevocationStatus> {
@@ -741,19 +816,24 @@ export async function getRevocationStatus(
     console.warn(
       '[vibe-sessions] Revocation check MISCONFIGURED (VIBE_CLIENT_ID set but IDP_URL/VIBE_HMAC_KEY missing) - reporting unknown (fail closed)'
     );
+    logRevocationReason('unknown', 'misconfigured', sessionToken);
     return 'unknown';
   }
 
-  const { ok, sessions } = await readSessionRevocationHmac(idpUserId);
+  const { ok, sessions, failure } = await readSessionRevocationHmac(idpUserId);
 
   if (!ok) {
     console.warn('[vibe-sessions] Revocation read failed - reporting unknown');
+    logRevocationReason('unknown', `read_failed:${failure ?? 'unknown'}`, sessionToken);
     return 'unknown';
   }
 
-  return findRevokingSession(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined)
-    ? 'revoked'
-    : 'active';
+  const { row, rule } = findRevokingSessionWithRule(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined);
+  if (row) {
+    logRevocationReason('revoked', rule, sessionToken, { rows: sessions.length });
+    return 'revoked';
+  }
+  return 'active';
 }
 
 // -----------------------------------------------------------------------------
@@ -817,3 +897,68 @@ export async function getSessionStats(accessToken: string): Promise<{
     recentLogins: stats.recentLogins,
   };
 }
+
+// -----------------------------------------------------------------------------
+// PAY-2136: SINGLE-FLIGHT + SHORT RESULT CACHE for the revocation read
+// -----------------------------------------------------------------------------
+// Every middleware viability check does one revocation read through the IdP proxy for the SAME Vibe client. A page
+// whose chrome prefetches ~4 links makes ~8 checks inside a second; the free tier allows 2 concurrent queries, so
+// the 3rd+ read was a 429 CONCURRENT_LIMIT and (before this change) signed the user out. Now concurrent callers for
+// ONE session share ONE in-flight read, and a CONFIRMED verdict is reused for a few seconds.
+//   - keyed by userId + the token HASH: never shared across sessions or users;
+//   - only 'active' / 'revoked' are cached: a failure ('unknown') is shared while in flight but never remembered, so
+//     the next request reads again; a revoked session is honoured at most REVOCATION_CACHE_MS late;
+//   - REVOCATION_CACHE_MS=0 disables the cache (single-flight still applies).
+const DEFAULT_REVOCATION_CACHE_MS = 5000;
+const MAX_REVOCATION_CACHE_ENTRIES = 2000;
+const revocationInflight = new Map<string, Promise<RevocationStatus>>();
+const revocationVerdicts = new Map<string, { status: RevocationStatus; at: number }>();
+
+function revocationCacheMs(): number {
+  const raw = process.env.REVOCATION_CACHE_MS;
+  if (raw === undefined || raw === '') return DEFAULT_REVOCATION_CACHE_MS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.min(n, 30_000) : DEFAULT_REVOCATION_CACHE_MS;
+}
+
+/** Test/ops hook: forget every cached verdict and in-flight read. */
+export function resetRevocationCache(): void {
+  revocationInflight.clear();
+  revocationVerdicts.clear();
+}
+
+export async function getRevocationStatus(
+  idpUserId: number,
+  sessionToken?: string
+): Promise<RevocationStatus> {
+  // No token = the user-wide legacy path: nothing session-specific to key on, so no sharing.
+  if (!sessionToken) return readRevocationStatus(idpUserId, sessionToken);
+
+  const key = `${idpUserId}:${hashSessionToken(sessionToken)}`;
+  const ttl = revocationCacheMs();
+  const now = Date.now();
+
+  const hit = revocationVerdicts.get(key);
+  if (hit && ttl > 0 && now - hit.at < ttl) return hit.status;
+  if (hit) revocationVerdicts.delete(key);
+
+  const existing = revocationInflight.get(key);
+  if (existing) return existing;
+
+  const read = readRevocationStatus(idpUserId, sessionToken)
+    .then((status) => {
+      if (ttl > 0 && (status === 'active' || status === 'revoked')) {
+        if (revocationVerdicts.size >= MAX_REVOCATION_CACHE_ENTRIES) {
+          for (const [k, v] of revocationVerdicts) if (now - v.at >= ttl) revocationVerdicts.delete(k);
+          if (revocationVerdicts.size >= MAX_REVOCATION_CACHE_ENTRIES) revocationVerdicts.clear();
+        }
+        revocationVerdicts.set(key, { status, at: Date.now() });
+      }
+      return status;
+    })
+    .finally(() => {
+      revocationInflight.delete(key);
+    });
+  revocationInflight.set(key, read);
+  return read;
+}