@payez/next-mvp 4.8.1 → 4.8.2

package/src/vibe/sessions.ts

@@ -1,902 +1,928 @@
-/**
- * =============================================================================
- * VIBE LOGIN SESSIONS
- * =============================================================================
- *
- * Server-side utilities for managing login sessions in Vibe.
- * Tracks user logins with location, device info, and allows session control.
- *
- * This module uses the MVP's vibe client with proper auth token handling
- * for member-to-vibe calls.
- *
- * USAGE:
- * ------
- * import { createLoginSession, getUserSessions, revokeSession } from '@payez/next-mvp/vibe/sessions';
- *
- * // On login (requires user's access token):
- * await createLoginSession({
- *   idpUserId: 22,
- *   email: 'user@example.com',
- *   ipAddress: '1.2.3.4',
- *   userAgent: '...',
- *   location: { city: 'NYC', ... },
- *   accessToken: userAccessToken,  // Required for member-to-vibe
- * });
- *
- * // Admin: revoke a session
- * await revokeSession(sessionId, 'admin@example.com', accessToken, 'Suspicious activity');
- *
- * =============================================================================
- */
-
-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';
-import { tokenLogId } from '../lib/token-log-id';
-
-// -----------------------------------------------------------------------------
-// CONFIGURATION
-// -----------------------------------------------------------------------------
-
-// Sessions expire after 30 days
-const SESSION_EXPIRY_DAYS = 30;
-
-// Table name in vibe_app collection
-const TABLE = 'login_sessions';
-const COLLECTION = 'vibe_app';
-
-// Environment variables
-const getEnv = (key: string): string => {
-  if (typeof process !== 'undefined' && process.env) {
-    return process.env[key] || '';
-  }
-  return '';
-};
-
-/**
- * Generate HMAC-SHA256 signature for proxy authentication
- */
-function generateHmacSignature(
-  signingKey: string,
-  timestamp: number,
-  method: string,
-  endpoint: string
-): string {
-  const stringToSign = `${timestamp}|${method}|${endpoint}`;
-  return crypto
-    .createHmac('sha256', Buffer.from(signingKey, 'base64'))
-    .update(stringToSign)
-    .digest('base64');
-}
-
-/**
- * Make a request through the IDP Vibe proxy
- */
-async function vibeProxyRequest<T>(
-  endpoint: string,
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  accessToken: string,
-  body?: unknown
-): Promise<T | null> {
-  const idpUrl = getEnv('IDP_URL');
-  const clientId = getEnv('VIBE_CLIENT_ID');
-  const signingKey = getEnv('VIBE_HMAC_KEY');
-
-  if (!idpUrl || !clientId || !signingKey) {
-    console.error('[vibe-sessions] Missing env vars: IDP_URL, VIBE_CLIENT_ID, or VIBE_HMAC_KEY');
-    return null;
-  }
-
-  const proxyUrl = `${idpUrl}/api/vibe/proxy`;
-  const timestamp = Math.floor(Date.now() / 1000);
-  const signature = generateHmacSignature(signingKey, timestamp, method, endpoint);
-
-  const headers: Record<string, string> = {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${accessToken}`,
-    '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,
-        data: body ?? null,
-      }),
-    });
-
-    if (response.status === 204) {
-      return null;
-    }
-
-    if (!response.ok) {
-      const errorText = await response.text();
-      // PAY-1427: never the raw proxy body - the request carried a Bearer token and an error page can echo it.
-      console.error(`[vibe-sessions] Proxy error ${response.status}:`, { bodyLength: errorText.length });
-      return null;
-    }
-
-    const data = await response.json();
-    // Unwrap IDP envelope if present
-    return (data?.data ?? data) as T;
-  } catch (error) {
-    console.error('[vibe-sessions] Proxy request failed:', error);
-    return null;
-  }
-}
-
-// -----------------------------------------------------------------------------
-// TYPES
-// -----------------------------------------------------------------------------
-
-export interface CreateSessionInput {
-  /** IDP user ID */
-  idpUserId: number;
-  /** User email */
-  email: string;
-  /** User's display name */
-  name?: string;
-  /** Client IP address */
-  ipAddress: string;
-  /** User agent string */
-  userAgent: string;
-  /** Location info from geolocation lookup */
-  location?: LocationInfo | null;
-  /** Parsed device info */
-  device?: DeviceInfo;
-  /** OAuth provider used for login */
-  oauthProvider?: string;
-  /** Hashed session token for lookup */
-  sessionTokenHash?: string;
-  /**
-   * User's access token - REQUIRED for member-to-vibe calls.
-   * Without this, the request will fail with 401.
-   */
-  accessToken: string;
-}
-
-export interface SessionQueryOptions {
-  status?: SessionStatus;
-  page?: number;
-  pageSize?: number;
-}
-
-// -----------------------------------------------------------------------------
-// CREATE SESSION
-// -----------------------------------------------------------------------------
-
-/**
- * Create a new login session record.
- * Called when a user successfully logs in.
- *
- * @param input - Session creation parameters including accessToken
- * @returns The created session, or null on failure
- */
-export async function createLoginSession(
-  input: CreateSessionInput
-): Promise<IVibeLoginSession | null> {
-  if (!input.accessToken) {
-    console.error('[vibe-sessions] accessToken is required for createLoginSession');
-    return null;
-  }
-
-  const now = new Date();
-  const expiresAt = new Date(now.getTime() + SESSION_EXPIRY_DAYS * 24 * 60 * 60 * 1000);
-
-  const sessionData = {
-    idp_user_id: input.idpUserId,
-    email: input.email,
-    name: input.name || null,
-
-    // Location
-    ip_address: input.ipAddress,
-    city: input.location?.city || null,
-    region: input.location?.region || null,
-    country: input.location?.country || null,
-    country_code: input.location?.countryCode || null,
-    latitude: input.location?.latitude || null,
-    longitude: input.location?.longitude || null,
-    timezone: input.location?.timezone || null,
-
-    // Device
-    user_agent: input.userAgent,
-    device_type: input.device?.deviceType || 'unknown',
-    browser: input.device?.browser || 'Unknown',
-    browser_version: input.device?.browserVersion || null,
-    os: input.device?.os || 'Unknown',
-    os_version: input.device?.osVersion || null,
-
-    // Auth
-    oauth_provider: input.oauthProvider || null,
-    session_token_hash: input.sessionTokenHash || null,
-
-    // Status
-    status: 'active' as SessionStatus,
-    revoked_by: null,
-    revoked_at: null,
-    revoke_reason: null,
-
-    // Timestamps
-    last_activity: now.toISOString(),
-    expires_at: expiresAt.toISOString(),
-  };
-
-  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}`;
-  const session = await vibeProxyRequest<IVibeLoginSession>(
-    endpoint,
-    'POST',
-    input.accessToken,
-    sessionData
-  );
-
-  if (session) {
-    console.log(`[vibe-sessions] Created session for ${input.email} from ${input.ipAddress}`);
-  }
-
-  return session;
-}
-
-// -----------------------------------------------------------------------------
-// GET SESSIONS
-// -----------------------------------------------------------------------------
-
-/**
- * Get all sessions for a specific user.
- *
- * @param idpUserId - The user's IDP ID
- * @param accessToken - User's access token for auth
- * @returns Array of sessions
- */
-export async function getUserSessions(
-  idpUserId: number,
-  accessToken: string
-): Promise<IVibeLoginSession[]> {
-  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
-  const result = await vibeProxyRequest<{ data?: IVibeLoginSession[]; items?: IVibeLoginSession[] }>(
-    endpoint,
-    'POST',
-    accessToken,
-    {
-      // 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,
-    }
-  );
-
-  return result?.data || result?.items || [];
-}
-
-/**
- * Get all sessions (admin only).
- * Returns sessions from all users, sorted by most recent first.
- *
- * @param options - Query options
- * @param accessToken - Admin's access token
- * @returns Array of sessions with total count
- */
-export async function getAllSessions(
-  options: SessionQueryOptions = {},
-  accessToken: string
-): Promise<{ sessions: IVibeLoginSession[]; total: number }> {
-  const page = options.page || 1;
-  const pageSize = options.pageSize || 50;
-
-  const query: Record<string, unknown> = {
-    page,
-    pageSize,
-    // 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 };
-  }
-
-  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
-  const result = await vibeProxyRequest<{
-    data?: IVibeLoginSession[];
-    items?: IVibeLoginSession[];
-    meta?: { total?: number; totalCount?: number };
-    totalCount?: number;
-  }>(endpoint, 'POST', accessToken, query);
-
-  const sessions = result?.data || result?.items || [];
-  const total = result?.meta?.total ?? result?.meta?.totalCount ?? result?.totalCount ?? sessions.length;
-
-  return { sessions, total };
-}
-
-/**
- * Get a single session by ID.
- *
- * @param sessionId - The session document ID
- * @param accessToken - Access token for auth
- */
-export async function getSessionById(
-  sessionId: number,
-  accessToken: string
-): Promise<IVibeLoginSession | null> {
-  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/${sessionId}`;
-  return vibeProxyRequest<IVibeLoginSession>(endpoint, 'GET', accessToken);
-}
-
-// -----------------------------------------------------------------------------
-// REVOKE SESSION
-// -----------------------------------------------------------------------------
-
-/**
- * Revoke a specific session.
- * The user will be logged out on their next request.
- *
- * @param sessionId - The session document ID
- * @param adminEmail - Email of the admin performing the revocation
- * @param accessToken - Admin's access token
- * @param reason - Optional reason for revocation
- * @returns The updated session, or null on failure
- */
-export async function revokeSession(
-  sessionId: number,
-  adminEmail: string,
-  accessToken: string,
-  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,
-    'PATCH',
-    accessToken,
-    {
-      status: 'revoked',
-      revoked_by: adminEmail,
-      revoked_at: now,
-      revoke_reason: reason || 'Revoked by administrator',
-    }
-  );
-
-  if (session) {
-    console.log(`[vibe-sessions] Session ${sessionId} revoked by ${adminEmail}`);
-  }
-
-  return session;
-}
-
-/**
- * Revoke all sessions for a specific user.
- * Useful when an account is compromised.
- *
- * @param idpUserId - The user's IDP ID
- * @param adminEmail - Email of the admin performing the revocation
- * @param accessToken - Admin's access token
- * @param reason - Optional reason for revocation
- * @returns Number of sessions revoked
- */
-export async function revokeAllUserSessions(
-  idpUserId: number,
-  adminEmail: string,
-  accessToken: string,
-  reason?: string
-): Promise<number> {
-  const sessions = await getUserSessions(idpUserId, accessToken);
-  const activeSessions = sessions.filter(s => s.status === 'active');
-
-  let revokedCount = 0;
-  for (const session of activeSessions) {
-    const result = await revokeSession(session.id, adminEmail, accessToken, reason);
-    if (result) revokedCount++;
-  }
-
-  console.log(`[vibe-sessions] Revoked ${revokedCount} sessions for user ${idpUserId}`);
-  return revokedCount;
-}
-
-// -----------------------------------------------------------------------------
-// UPDATE ACTIVITY
-// -----------------------------------------------------------------------------
-
-/**
- * Update the last_activity timestamp for a session.
- * Call this periodically during user activity.
- *
- * @param sessionId - The session document ID
- * @param accessToken - Access token for auth
- * @returns true if updated successfully
- */
-export async function updateSessionActivity(
-  sessionId: number,
-  accessToken: string
-): Promise<boolean> {
-  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/${sessionId}`;
-  const result = await vibeProxyRequest<IVibeLoginSession>(
-    endpoint,
-    'PATCH',
-    accessToken,
-    { last_activity: new Date().toISOString() }
-  );
-
-  return result !== null;
-}
-
-// -----------------------------------------------------------------------------
-// CHECK SESSION STATUS
-// -----------------------------------------------------------------------------
-
-/**
- * Check if a session is still valid (not revoked/expired).
- * Use this in middleware to enforce session revocation.
- *
- * @param sessionId - The session document ID
- * @param accessToken - Access token for auth
- * @returns true if session is active and not expired
- */
-export async function isSessionValid(
-  sessionId: number,
-  accessToken: string
-): Promise<boolean> {
-  const session = await getSessionById(sessionId, accessToken);
-
-  if (!session) return false;
-  if (session.status !== 'active') return false;
-
-  // Check expiry
-  const expiresAt = new Date(session.expires_at);
-  if (expiresAt < new Date()) {
-    return false;
-  }
-
-  return true;
-}
-
-/**
- * Check if a user has any revoked sessions that need enforcement.
- * Returns the most recently revoked session if found.
- *
- * @param idpUserId - The user's IDP ID
- * @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,
-  sessionTokenHash?: string
-): Promise<IVibeLoginSession | null> {
-  // 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);
-}
-
-// -----------------------------------------------------------------------------
-// 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[]; 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: [], failure: 'misconfigured' };
-  }
-
-  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
-  const proxyUrl = `${idpUrl}/api/vibe/proxy`;
-
-  // 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({
-        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,
-        },
-      }),
-    });
-  };
-
-  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: [], failure: String(response.status) }; // PAY-2136: status only, for the reason log
-    }
-
-    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: [], 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.
- *
- * 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 {
-  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' ? { 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
-  // 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 { 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;
-  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 */
-  }
-}
-
-/**
- * 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).
- */
-async function readRevocationStatus(
-  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)'
-    );
-    logRevocationReason('unknown', 'misconfigured', sessionToken);
-    return 'unknown';
-  }
-
-  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';
-  }
-
-  const { row, rule } = findRevokingSessionWithRule(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined);
-  if (row) {
-    logRevocationReason('revoked', rule, sessionToken, { rows: sessions.length });
-    return 'revoked';
-  }
-  return 'active';
-}
-
-// -----------------------------------------------------------------------------
-// STATISTICS
-// -----------------------------------------------------------------------------
-
-/**
- * Get session statistics for admin dashboard.
- *
- * @param accessToken - Admin's access token
- */
-export async function getSessionStats(accessToken: string): Promise<{
-  totalActive: number;
-  totalRevoked: number;
-  uniqueUsers: number;
-  byCountry: Record<string, number>;
-  byDevice: Record<string, number>;
-  recentLogins: number; // Last 24 hours
-}> {
-  const { sessions } = await getAllSessions({ pageSize: 1000 }, accessToken);
-
-  const stats = {
-    totalActive: 0,
-    totalRevoked: 0,
-    uniqueUsers: new Set<number>(),
-    byCountry: {} as Record<string, number>,
-    byDevice: {} as Record<string, number>,
-    recentLogins: 0,
-  };
-
-  const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
-
-  for (const session of sessions) {
-    // Status counts
-    if (session.status === 'active') stats.totalActive++;
-    if (session.status === 'revoked') stats.totalRevoked++;
-
-    // Unique users
-    stats.uniqueUsers.add(session.idp_user_id);
-
-    // By country
-    const country = session.country_code || 'Unknown';
-    stats.byCountry[country] = (stats.byCountry[country] || 0) + 1;
-
-    // By device type
-    const device = session.device_type || 'unknown';
-    stats.byDevice[device] = (stats.byDevice[device] || 0) + 1;
-
-    // Recent logins
-    if (new Date(session.created_at) > oneDayAgo) {
-      stats.recentLogins++;
-    }
-  }
-
-  return {
-    totalActive: stats.totalActive,
-    totalRevoked: stats.totalRevoked,
-    uniqueUsers: stats.uniqueUsers.size,
-    byCountry: stats.byCountry,
-    byDevice: stats.byDevice,
-    recentLogins: stats.recentLogins,
-  };
-}
+/**
+ * =============================================================================
+ * VIBE LOGIN SESSIONS
+ * =============================================================================
+ *
+ * Server-side utilities for managing login sessions in Vibe.
+ * Tracks user logins with location, device info, and allows session control.
+ *
+ * This module uses the MVP's vibe client with proper auth token handling
+ * for member-to-vibe calls.
+ *
+ * USAGE:
+ * ------
+ * import { createLoginSession, getUserSessions, revokeSession } from '@payez/next-mvp/vibe/sessions';
+ *
+ * // On login (requires user's access token):
+ * await createLoginSession({
+ *   idpUserId: 22,
+ *   email: 'user@example.com',
+ *   ipAddress: '1.2.3.4',
+ *   userAgent: '...',
+ *   location: { city: 'NYC', ... },
+ *   accessToken: userAccessToken,  // Required for member-to-vibe
+ * });
+ *
+ * // Admin: revoke a session
+ * await revokeSession(sessionId, 'admin@example.com', accessToken, 'Suspicious activity');
+ *
+ * =============================================================================
+ */
+
+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';
+import { tokenLogId } from '../lib/token-log-id';
+
+// -----------------------------------------------------------------------------
+// CONFIGURATION
+// -----------------------------------------------------------------------------
+
+// Sessions expire after 30 days
+const SESSION_EXPIRY_DAYS = 30;
+
+// Table name in vibe_app collection
+const TABLE = 'login_sessions';
+const COLLECTION = 'vibe_app';
+
+// Environment variables
+const getEnv = (key: string): string => {
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[key] || '';
+  }
+  return '';
+};
+
+/**
+ * Generate HMAC-SHA256 signature for proxy authentication
+ */
+function generateHmacSignature(
+  signingKey: string,
+  timestamp: number,
+  method: string,
+  endpoint: string
+): string {
+  const stringToSign = `${timestamp}|${method}|${endpoint}`;
+  return crypto
+    .createHmac('sha256', Buffer.from(signingKey, 'base64'))
+    .update(stringToSign)
+    .digest('base64');
+}
+
+/**
+ * Make a request through the IDP Vibe proxy
+ */
+async function vibeProxyRequest<T>(
+  endpoint: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  accessToken: string,
+  body?: unknown
+): Promise<T | null> {
+  const idpUrl = getEnv('IDP_URL');
+  const clientId = getEnv('VIBE_CLIENT_ID');
+  const signingKey = getEnv('VIBE_HMAC_KEY');
+
+  if (!idpUrl || !clientId || !signingKey) {
+    console.error('[vibe-sessions] Missing env vars: IDP_URL, VIBE_CLIENT_ID, or VIBE_HMAC_KEY');
+    return null;
+  }
+
+  const proxyUrl = `${idpUrl}/api/vibe/proxy`;
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signature = generateHmacSignature(signingKey, timestamp, method, endpoint);
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${accessToken}`,
+    '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,
+        data: body ?? null,
+      }),
+    });
+
+    if (response.status === 204) {
+      return null;
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      // PAY-1427: never the raw proxy body - the request carried a Bearer token and an error page can echo it.
+      console.error(`[vibe-sessions] Proxy error ${response.status}:`, { bodyLength: errorText.length });
+      return null;
+    }
+
+    const data = await response.json();
+    // Unwrap IDP envelope if present
+    return (data?.data ?? data) as T;
+  } catch (error) {
+    console.error('[vibe-sessions] Proxy request failed:', error);
+    return null;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// TYPES
+// -----------------------------------------------------------------------------
+
+export interface CreateSessionInput {
+  /** IDP user ID */
+  idpUserId: number;
+  /** User email */
+  email: string;
+  /** User's display name */
+  name?: string;
+  /** Client IP address */
+  ipAddress: string;
+  /** User agent string */
+  userAgent: string;
+  /** Location info from geolocation lookup */
+  location?: LocationInfo | null;
+  /** Parsed device info */
+  device?: DeviceInfo;
+  /** OAuth provider used for login */
+  oauthProvider?: string;
+  /** Hashed session token for lookup */
+  sessionTokenHash?: string;
+  /**
+   * User's access token - REQUIRED for member-to-vibe calls.
+   * Without this, the request will fail with 401.
+   */
+  accessToken: string;
+}
+
+export interface SessionQueryOptions {
+  status?: SessionStatus;
+  page?: number;
+  pageSize?: number;
+}
+
+// -----------------------------------------------------------------------------
+// CREATE SESSION
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a new login session record.
+ * Called when a user successfully logs in.
+ *
+ * @param input - Session creation parameters including accessToken
+ * @returns The created session, or null on failure
+ */
+export async function createLoginSession(
+  input: CreateSessionInput
+): Promise<IVibeLoginSession | null> {
+  if (!input.accessToken) {
+    console.error('[vibe-sessions] accessToken is required for createLoginSession');
+    return null;
+  }
+
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + SESSION_EXPIRY_DAYS * 24 * 60 * 60 * 1000);
+
+  // PAY-2362 (write side): ONE row per session hash. A second record-login for the same session (another tab, a cleared
+  // sessionStorage, every open session when an app first runs a version that changes its login-recording key) used to INSERT a second
+  // row with the SAME hash, and a revoke PATCHes ONE row by id. If a row for this hash already exists, PATCH last_activity on it (that
+  // one field only: it never touches status, so it cannot un-revoke) and return it. A failed lookup must never block a login: fall
+  // through to the insert, as before. The read side (findRevokingSession: revoked if ANY row for the hash is) covers duplicates that
+  // already exist.
+  if (input.sessionTokenHash) {
+    try {
+      const existingRows = (await getUserSessions(input.idpUserId, input.accessToken))
+        .filter(s => s.session_token_hash === input.sessionTokenHash);
+      if (existingRows.length > 0) {
+        const existing = existingRows.find(s => s.status === 'revoked') ?? existingRows[0];
+        await updateSessionActivity(existing.id, input.accessToken);
+        return existing;
+      }
+    } catch {
+      /* lookup failed: insert as before */
+    }
+  }
+
+  const sessionData = {
+    idp_user_id: input.idpUserId,
+    email: input.email,
+    name: input.name || null,
+
+    // Location
+    ip_address: input.ipAddress,
+    city: input.location?.city || null,
+    region: input.location?.region || null,
+    country: input.location?.country || null,
+    country_code: input.location?.countryCode || null,
+    latitude: input.location?.latitude || null,
+    longitude: input.location?.longitude || null,
+    timezone: input.location?.timezone || null,
+
+    // Device
+    user_agent: input.userAgent,
+    device_type: input.device?.deviceType || 'unknown',
+    browser: input.device?.browser || 'Unknown',
+    browser_version: input.device?.browserVersion || null,
+    os: input.device?.os || 'Unknown',
+    os_version: input.device?.osVersion || null,
+
+    // Auth
+    oauth_provider: input.oauthProvider || null,
+    session_token_hash: input.sessionTokenHash || null,
+
+    // Status
+    status: 'active' as SessionStatus,
+    revoked_by: null,
+    revoked_at: null,
+    revoke_reason: null,
+
+    // Timestamps
+    last_activity: now.toISOString(),
+    expires_at: expiresAt.toISOString(),
+  };
+
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}`;
+  const session = await vibeProxyRequest<IVibeLoginSession>(
+    endpoint,
+    'POST',
+    input.accessToken,
+    sessionData
+  );
+
+  if (session) {
+    console.log(`[vibe-sessions] Created session for ${input.email} from ${input.ipAddress}`);
+  }
+
+  return session;
+}
+
+// -----------------------------------------------------------------------------
+// GET SESSIONS
+// -----------------------------------------------------------------------------
+
+/**
+ * Get all sessions for a specific user.
+ *
+ * @param idpUserId - The user's IDP ID
+ * @param accessToken - User's access token for auth
+ * @returns Array of sessions
+ */
+export async function getUserSessions(
+  idpUserId: number,
+  accessToken: string
+): Promise<IVibeLoginSession[]> {
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
+  const result = await vibeProxyRequest<{ data?: IVibeLoginSession[]; items?: IVibeLoginSession[] }>(
+    endpoint,
+    'POST',
+    accessToken,
+    {
+      // 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,
+    }
+  );
+
+  return result?.data || result?.items || [];
+}
+
+/**
+ * Get all sessions (admin only).
+ * Returns sessions from all users, sorted by most recent first.
+ *
+ * @param options - Query options
+ * @param accessToken - Admin's access token
+ * @returns Array of sessions with total count
+ */
+export async function getAllSessions(
+  options: SessionQueryOptions = {},
+  accessToken: string
+): Promise<{ sessions: IVibeLoginSession[]; total: number }> {
+  const page = options.page || 1;
+  const pageSize = options.pageSize || 50;
+
+  const query: Record<string, unknown> = {
+    page,
+    pageSize,
+    // 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 };
+  }
+
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
+  const result = await vibeProxyRequest<{
+    data?: IVibeLoginSession[];
+    items?: IVibeLoginSession[];
+    meta?: { total?: number; totalCount?: number };
+    totalCount?: number;
+  }>(endpoint, 'POST', accessToken, query);
+
+  const sessions = result?.data || result?.items || [];
+  const total = result?.meta?.total ?? result?.meta?.totalCount ?? result?.totalCount ?? sessions.length;
+
+  return { sessions, total };
+}
+
+/**
+ * Get a single session by ID.
+ *
+ * @param sessionId - The session document ID
+ * @param accessToken - Access token for auth
+ */
+export async function getSessionById(
+  sessionId: number,
+  accessToken: string
+): Promise<IVibeLoginSession | null> {
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/${sessionId}`;
+  return vibeProxyRequest<IVibeLoginSession>(endpoint, 'GET', accessToken);
+}
+
+// -----------------------------------------------------------------------------
+// REVOKE SESSION
+// -----------------------------------------------------------------------------
+
+/**
+ * Revoke a specific session.
+ * The user will be logged out on their next request.
+ *
+ * @param sessionId - The session document ID
+ * @param adminEmail - Email of the admin performing the revocation
+ * @param accessToken - Admin's access token
+ * @param reason - Optional reason for revocation
+ * @returns The updated session, or null on failure
+ */
+export async function revokeSession(
+  sessionId: number,
+  adminEmail: string,
+  accessToken: string,
+  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,
+    'PATCH',
+    accessToken,
+    {
+      status: 'revoked',
+      revoked_by: adminEmail,
+      revoked_at: now,
+      revoke_reason: reason || 'Revoked by administrator',
+    }
+  );
+
+  if (session) {
+    console.log(`[vibe-sessions] Session ${sessionId} revoked by ${adminEmail}`);
+  }
+
+  return session;
+}
+
+/**
+ * Revoke all sessions for a specific user.
+ * Useful when an account is compromised.
+ *
+ * @param idpUserId - The user's IDP ID
+ * @param adminEmail - Email of the admin performing the revocation
+ * @param accessToken - Admin's access token
+ * @param reason - Optional reason for revocation
+ * @returns Number of sessions revoked
+ */
+export async function revokeAllUserSessions(
+  idpUserId: number,
+  adminEmail: string,
+  accessToken: string,
+  reason?: string
+): Promise<number> {
+  const sessions = await getUserSessions(idpUserId, accessToken);
+  const activeSessions = sessions.filter(s => s.status === 'active');
+
+  let revokedCount = 0;
+  for (const session of activeSessions) {
+    const result = await revokeSession(session.id, adminEmail, accessToken, reason);
+    if (result) revokedCount++;
+  }
+
+  console.log(`[vibe-sessions] Revoked ${revokedCount} sessions for user ${idpUserId}`);
+  return revokedCount;
+}
+
+// -----------------------------------------------------------------------------
+// UPDATE ACTIVITY
+// -----------------------------------------------------------------------------
+
+/**
+ * Update the last_activity timestamp for a session.
+ * Call this periodically during user activity.
+ *
+ * @param sessionId - The session document ID
+ * @param accessToken - Access token for auth
+ * @returns true if updated successfully
+ */
+export async function updateSessionActivity(
+  sessionId: number,
+  accessToken: string
+): Promise<boolean> {
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/${sessionId}`;
+  const result = await vibeProxyRequest<IVibeLoginSession>(
+    endpoint,
+    'PATCH',
+    accessToken,
+    { last_activity: new Date().toISOString() }
+  );
+
+  return result !== null;
+}
+
+// -----------------------------------------------------------------------------
+// CHECK SESSION STATUS
+// -----------------------------------------------------------------------------
+
+/**
+ * Check if a session is still valid (not revoked/expired).
+ * Use this in middleware to enforce session revocation.
+ *
+ * @param sessionId - The session document ID
+ * @param accessToken - Access token for auth
+ * @returns true if session is active and not expired
+ */
+export async function isSessionValid(
+  sessionId: number,
+  accessToken: string
+): Promise<boolean> {
+  const session = await getSessionById(sessionId, accessToken);
+
+  if (!session) return false;
+  if (session.status !== 'active') return false;
+
+  // Check expiry
+  const expiresAt = new Date(session.expires_at);
+  if (expiresAt < new Date()) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if a user has any revoked sessions that need enforcement.
+ * Returns the most recently revoked session if found.
+ *
+ * @param idpUserId - The user's IDP ID
+ * @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,
+  sessionTokenHash?: string
+): Promise<IVibeLoginSession | null> {
+  // 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);
+}
+
+// -----------------------------------------------------------------------------
+// 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[]; 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: [], failure: 'misconfigured' };
+  }
+
+  const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
+  const proxyUrl = `${idpUrl}/api/vibe/proxy`;
+
+  // 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({
+        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,
+        },
+      }),
+    });
+  };
+
+  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: [], failure: String(response.status) }; // PAY-2136: status only, for the reason log
+    }
+
+    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: [], 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.
+ *
+ * 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 {
+  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) {
+    // PAY-2362: EVERY row carrying this hash, not the first. A second record-login for the same session (another tab, a cleared
+    // sessionStorage, every open session at a package roll) writes a second row with the SAME hash, and a revoke PATCHes ONE row by id.
+    // `find` took the first row, so an active duplicate listed before the revoked one hid the revoke. Revoked if ANY of them is.
+    const matching = sessions.filter(s => s.session_token_hash === sessionTokenHash);
+    if (matching.length > 0) {
+      const revoked = matching.find(s => s.status === 'revoked');
+      return revoked ? { row: revoked, 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
+  // 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 { 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;
+  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 */
+  }
+}
+
+/**
+ * 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).
+ */
+async function readRevocationStatus(
+  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)'
+    );
+    logRevocationReason('unknown', 'misconfigured', sessionToken);
+    return 'unknown';
+  }
+
+  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';
+  }
+
+  const { row, rule } = findRevokingSessionWithRule(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined);
+  if (row) {
+    logRevocationReason('revoked', rule, sessionToken, { rows: sessions.length });
+    return 'revoked';
+  }
+  return 'active';
+}
+
+// -----------------------------------------------------------------------------
+// STATISTICS
+// -----------------------------------------------------------------------------
+
+/**
+ * Get session statistics for admin dashboard.
+ *
+ * @param accessToken - Admin's access token
+ */
+export async function getSessionStats(accessToken: string): Promise<{
+  totalActive: number;
+  totalRevoked: number;
+  uniqueUsers: number;
+  byCountry: Record<string, number>;
+  byDevice: Record<string, number>;
+  recentLogins: number; // Last 24 hours
+}> {
+  const { sessions } = await getAllSessions({ pageSize: 1000 }, accessToken);
+
+  const stats = {
+    totalActive: 0,
+    totalRevoked: 0,
+    uniqueUsers: new Set<number>(),
+    byCountry: {} as Record<string, number>,
+    byDevice: {} as Record<string, number>,
+    recentLogins: 0,
+  };
+
+  const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+
+  for (const session of sessions) {
+    // Status counts
+    if (session.status === 'active') stats.totalActive++;
+    if (session.status === 'revoked') stats.totalRevoked++;
+
+    // Unique users
+    stats.uniqueUsers.add(session.idp_user_id);
+
+    // By country
+    const country = session.country_code || 'Unknown';
+    stats.byCountry[country] = (stats.byCountry[country] || 0) + 1;
+
+    // By device type
+    const device = session.device_type || 'unknown';
+    stats.byDevice[device] = (stats.byDevice[device] || 0) + 1;
+
+    // Recent logins
+    if (new Date(session.created_at) > oneDayAgo) {
+      stats.recentLogins++;
+    }
+  }
+
+  return {
+    totalActive: stats.totalActive,
+    totalRevoked: stats.totalRevoked,
+    uniqueUsers: stats.uniqueUsers.size,
+    byCountry: stats.byCountry,
+    byDevice: stats.byDevice,
+    recentLogins: stats.recentLogins,
+  };
+}
 
 // -----------------------------------------------------------------------------
 // PAY-2136: SINGLE-FLIGHT + SHORT RESULT CACHE for the revocation read