@payez/next-mvp 4.5.0 → 4.5.2

package/scripts/check-publish-health.mjs

@@ -31,6 +31,7 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { resolvePublishTag } from './publish-health-tag.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkgPath = join(here, '..', 'package.json');
@@ -69,6 +70,14 @@ try {
 const name = local.name;
 const localVersion = local.version;
 
+// PAY-2136: compare against the dist-tag being published (`npm publish --tag next` -> `next`), not always `latest`.
+const tag = resolvePublishTag(process.argv.slice(2), process.env);
+if (tag === null) {
+  console.error('[publish-health] INCONCLUSIVE: the requested dist-tag is not a plain tag name.');
+  process.exit(2);
+}
+const registrySpec = tag === 'latest' ? name : `${name}@${tag}`;
+
 // Auth is reported separately: a dead credential is the ROOT of 171900, and folding
 // it into "lagging" would hide which of the two things is actually broken.
 let authUser = null;
@@ -105,11 +114,11 @@ const REGISTRY_RETRY_MS = 2000;
 let registryVersion = null;
 for (let attempt = 1; attempt <= REGISTRY_ATTEMPTS; attempt++) {
   try {
-    registryVersion = run(['view', name, 'version', '--prefer-online']);
+    registryVersion = run(['view', registrySpec, 'version', '--prefer-online']);
   } catch (err) {
     const msg = String(err.stderr || err.message || '');
     if (/E404|404 Not Found/.test(msg)) {
-      console.error(`[publish-health] FAIL: ${name} has NEVER been published to the registry.`);
+      console.error(`[publish-health] FAIL: ${registrySpec} has NEVER been published to the registry.`);
       console.error(`[publish-health] local=${localVersion} registry=<absent>`);
       process.exit(1);
     }
@@ -135,7 +144,7 @@ const delta = compareVersions(localVersion, registryVersion);
 
 console.log(`[publish-health] package  : ${name}`);
 console.log(`[publish-health] local    : ${localVersion}`);
-console.log(`[publish-health] registry : ${registryVersion}`);
+console.log(`[publish-health] registry : ${registryVersion} (dist-tag ${tag})`);
 console.log(`[publish-health] npm auth : ${authUser ? `logged in as ${authUser}` : 'NOT AUTHENTICATED (npm whoami failed)'}`);
 
 if (delta > 0) {

package/scripts/publish-health-tag.mjs

@@ -0,0 +1,27 @@
+/**
+ * Which dist-tag should the publish-health check compare the local version against?
+ *
+ * PAY-2136 (BAPert 71043): `npm publish --tag next` runs this check as `postpublish`, and it compared local against
+ * the `latest` tag, so a CORRECT next-tag publish printed "registry LAGS local" and exited 1 - noise nobody should
+ * learn to ignore. Resolution order: `--tag <x>` / `--tag=<x>` argument, then npm_config_tag (npm sets it inside
+ * lifecycle scripts from `--tag`), then `latest`. A tag that is not a plain word is rejected (null), never guessed.
+ */
+const TAG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function resolvePublishTag(argv = [], env = {}) {
+  let raw;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tag') {
+      raw = argv[i + 1];
+      break;
+    }
+    if (a.startsWith('--tag=')) {
+      raw = a.slice('--tag='.length);
+      break;
+    }
+  }
+  if (raw === undefined) raw = env.npm_config_tag;
+  if (raw === undefined || raw === '') return 'latest';
+  return TAG.test(raw) ? raw : null;
+}

package/src/auth/auth-decision.ts

@@ -26,6 +26,8 @@ export interface AuthContext {
     twoFactorComplete: boolean;
   };
   circuitBreakerOpen: boolean;
+  /** PAY-2136: the request is a router prefetch. A prefetch never clears cookies (see isPrefetchRequest). */
+  isPrefetch?: boolean;
 }
 
 // Output types for the decision engine
@@ -34,10 +36,36 @@ export type AuthAction =
   | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
   | { type: 'service_error'; reason: string };
 
+/** PAY-2180: warn once per process, not per request. */
+let deprecationWarned = false;
+
 /**
- * Main decision function - pure, testable, deterministic
+ * Main decision function - pure, testable, deterministic.
+ * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
+ * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
  */
 export function makeAuthDecision(context: AuthContext): AuthAction {
+  if (!deprecationWarned) {
+    deprecationWarned = true;
+    console.warn(
+      '[next-mvp] makeAuthDecision (auth/auth-decision) is deprecated (PAY-2180) and will be removed in the next major: ' +
+        'createMvpMiddleware does not use it. Use createMvpMiddleware.'
+    );
+  }
+  const action = decide(context);
+  if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
+    const { clearCookies: _dropped, ...rest } = action;
+    return rest;
+  }
+  return action;
+}
+
+function decide(context: AuthContext): AuthAction {
   const {
     pathname,
     isPublicRoute,

package/src/edge/middleware.ts

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

package/src/index.ts

@@ -27,7 +27,7 @@ export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from '.
 // The ONE callback-target guard (N7 / PAY-1989): apps import this instead of
 // copying it. Exposed from the main index AND as the subpath ./auth/safe-callback.
 export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
-export { createMvpMiddleware } from './middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest } from './middleware/create-middleware';
 
 // Account Components
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';

package/src/lib/idp-fetch.ts

@@ -3,12 +3,13 @@ import { getTokenTestAware } from './test-aware-get-token';
 import { getSession } from './session-store';
 import { internalRefresh } from './internal-api';
 import { assertAbsoluteIdpUrl } from './idp-url-guard';
+import { parseRetryAfterSeconds } from './retry-after';
 
 // Re-exported so `idp-fetch` remains the single obvious import for IDP calling
 // concerns; the implementation lives in a dependency-free leaf so the three
 // direct-fetch callers (auth/jwks.ts, auth/passkey-signin.ts x2) do not have to
 // pull this module's server-only chain in for one regex.
-export { assertAbsoluteIdpUrl };
+export { assertAbsoluteIdpUrl, parseRetryAfterSeconds };
 
 /**
  * Centralized IDP fetch helper
@@ -21,6 +22,12 @@ export interface IdpFetchResult<T = any> {
   status: number;
   json: T | null;
   attemptedRefresh: boolean;
+  /**
+   * PAY-1608: the upstream Retry-After in whole seconds, when the IDP sent a usable one. Core sends it on every
+   * 2FA lock (MfaController.SecondFactorLocked: 429 + Retry-After 900; VerifyTotp: what is left of the lock).
+   * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
+   */
+  retryAfterSeconds?: number;
 }
 
 function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
@@ -158,5 +165,6 @@ export async function idpFetchJSON<T = any>(
     } catch {}
   }
 
-  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh };
+  const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.('Retry-After'));
+  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/src/lib/retry-after.ts

@@ -0,0 +1,24 @@
+/**
+ * PAY-1608: parse an HTTP Retry-After header to whole seconds.
+ *
+ * Accepts delta-seconds ("900") and an HTTP date in the future. Answers undefined for absent, zero, negative,
+ * fractional, past or malformed values - a caller that gets undefined states no window rather than a guessed one.
+ *
+ * A dependency-free leaf on purpose: idp-fetch re-exports it, but a test can load it without the session/redis
+ * graph idp-fetch pulls in.
+ */
+export function parseRetryAfterSeconds(value: string | null | undefined, nowMs: number = Date.now()): number | undefined {
+  if (typeof value !== 'string') return undefined;
+  const v = value.trim();
+  if (/^\d+$/.test(v)) {
+    const n = parseInt(v, 10);
+    return n > 0 ? n : undefined;
+  }
+  // Only something that looks like an HTTP date (it has letters: "Sat, 10 Oct 2026 12:01:30 GMT") is parsed as
+  // one; "-5" and "1.5" must not reach Date.parse, which would read them as years.
+  if (!/[a-z]/i.test(v)) return undefined;
+  const at = Date.parse(v);
+  if (!Number.isFinite(at)) return undefined;
+  const secs = Math.ceil((at - nowMs) / 1000);
+  return secs > 0 ? secs : undefined;
+}

package/src/lib/session-store.ts

@@ -1048,3 +1048,45 @@ export async function cleanupRefreshLocks(): Promise<number> {
   console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
   return 0;
 }
+
+/**
+ * PAY-2136 DIAGNOSTIC (BAPert 70873): which of the session keys EXIST for a token, right now.
+ *
+ * Names/presence only - this returns booleans and the key PREFIX (an app slug, not a secret), never a value and
+ * never any part of the token. It exists so a NO_SESSION can be read for what it was: canonical row gone with the
+ * ba: record alive (the :330 asymmetry), both gone (expired/deleted), or the store could not be asked ('error').
+ *
+ * EXISTS, not GET: it cannot parse, cannot throw on a malformed blob, and cannot return a credential. Each key is
+ * asked separately so one timeout does not hide the other two. Never throws.
+ */
+export type KeyPresence = boolean | 'error';
+export async function describeSessionKeyPresence(
+  sessionToken: string
+): Promise<{ prefix: string; canonical: KeyPresence; ba: KeyPresence; ver: KeyPresence }> {
+  const ask = async (key: string): Promise<KeyPresence> => {
+    try {
+      return (await redis.exists(key)) > 0;
+    } catch {
+      return 'error';
+    }
+  };
+  let prefix = '';
+  try {
+    prefix = getSessionPrefix();
+  } catch {
+    prefix = '';
+  }
+  if (!sessionToken) return { prefix, canonical: false, ba: false, ver: false };
+  let canonicalKey = '';
+  let baKey = '';
+  let verKey = '';
+  try {
+    canonicalKey = getSessionKey(sessionToken);
+    baKey = getBetterAuthSessionKey(sessionToken, getAppSlug());
+    verKey = getSessionVersionKey(sessionToken);
+  } catch {
+    return { prefix, canonical: 'error', ba: 'error', ver: 'error' };
+  }
+  const [canonical, ba, ver] = await Promise.all([ask(canonicalKey), ask(baKey), ask(verKey)]);
+  return { prefix, canonical, ba, ver };
+}