@payez/next-mvp 4.1.21 → 4.4.1

package/scripts/check-internal-url-usage.sh

@@ -1,73 +1,73 @@
-#!/bin/bash
-#
-# CI Check: Detect incorrect internal API URL patterns
-#
-# This script fails if code is using req.url or req.nextUrl.origin to construct
-# URLs for internal API calls. These patterns cause 403 errors in Kubernetes
-# because they use the external HTTPS URL instead of INTERNAL_API_URL.
-#
-# CORRECT:   Use internalFetch() or internalRefresh() from @payez/next-mvp/lib/internal-api
-# INCORRECT: new URL('/api/...', req.url) or fetch(`${req.nextUrl.origin}/api/...`)
-#
-# NOTE: new URL(req.url) alone is FINE - it just parses the incoming request URL.
-#       The problem is when you construct a NEW path using req.url as the base.
-#
-
-set -e
-
-SEARCH_PATH="${1:-.}"
-ERRORS_FOUND=0
-
-echo "Checking for incorrect internal URL patterns in: $SEARCH_PATH"
-echo "========================================================================"
-
-# Pattern 1: new URL('/api/...', req.url) - constructing internal API URL from request
-# This catches: new URL('/api/...', req.url) and new URL("/api/...", req.url)
-# But NOT: new URL(req.url) which is just parsing the request
-echo ""
-echo "Checking for: new URL('/api/...', req.url) pattern"
-if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\(['\"][^'\"]*['\"],\s*req\.url" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
-    echo "ERROR: Found 'new URL(path, req.url)' pattern. Use internalFetch() instead."
-    ERRORS_FOUND=1
-fi
-
-# Pattern 2: new URL('/api/...', req.nextUrl) or new URL(..., req.nextUrl.origin)
-echo ""
-echo "Checking for: new URL(..., req.nextUrl) pattern"
-if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\([^)]+,\s*req\.nextUrl" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
-    echo "ERROR: Found 'new URL(..., req.nextUrl)' pattern. Use internalFetch() instead."
-    ERRORS_FOUND=1
-fi
-
-# Pattern 3: fetch with req.nextUrl.origin and /api/
-echo ""
-echo "Checking for: fetch with req.nextUrl.origin and /api/"
-if grep -rn --include="*.ts" --include="*.tsx" "req\.nextUrl\.origin.*\/api\/" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
-    echo "ERROR: Found 'req.nextUrl.origin' used with internal API route. Use internalFetch() instead."
-    ERRORS_FOUND=1
-fi
-
-# Pattern 4: Direct fetch to /api/auth/refresh without using internalRefresh (warning only)
-echo ""
-echo "Checking for: Direct fetch to /api/auth/refresh (should use internalRefresh)"
-if grep -rn --include="*.ts" --include="*.tsx" "fetch.*\/api\/auth\/refresh" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts" | grep -v "internal-api\.ts"; then
-    echo "WARNING: Found direct fetch to /api/auth/refresh. Consider using internalRefresh() helper."
-    # Not failing on this one as it might be intentional in some cases (client-side refresh)
-fi
-
-echo ""
-echo "========================================================================"
-
-if [ $ERRORS_FOUND -eq 1 ]; then
-    echo "FAILED: Dangerous internal URL patterns detected!"
-    echo ""
-    echo "Fix: Import and use helpers from @payez/next-mvp/lib/internal-api:"
-    echo "  import { internalFetch, internalRefresh } from '@payez/next-mvp/lib/internal-api';"
-    echo ""
-    echo "Why: Server-to-server calls must use INTERNAL_API_URL (http://service.namespace.svc.cluster.local)"
-    echo "     not the external URL from the request (https://api.example.com) which fails in Kubernetes."
-    exit 1
-else
-    echo "PASSED: No dangerous internal URL patterns found."
-    exit 0
-fi
+#!/bin/bash
+#
+# CI Check: Detect incorrect internal API URL patterns
+#
+# This script fails if code is using req.url or req.nextUrl.origin to construct
+# URLs for internal API calls. These patterns cause 403 errors in Kubernetes
+# because they use the external HTTPS URL instead of INTERNAL_API_URL.
+#
+# CORRECT:   Use internalFetch() or internalRefresh() from @payez/next-mvp/lib/internal-api
+# INCORRECT: new URL('/api/...', req.url) or fetch(`${req.nextUrl.origin}/api/...`)
+#
+# NOTE: new URL(req.url) alone is FINE - it just parses the incoming request URL.
+#       The problem is when you construct a NEW path using req.url as the base.
+#
+
+set -e
+
+SEARCH_PATH="${1:-.}"
+ERRORS_FOUND=0
+
+echo "Checking for incorrect internal URL patterns in: $SEARCH_PATH"
+echo "========================================================================"
+
+# Pattern 1: new URL('/api/...', req.url) - constructing internal API URL from request
+# This catches: new URL('/api/...', req.url) and new URL("/api/...", req.url)
+# But NOT: new URL(req.url) which is just parsing the request
+echo ""
+echo "Checking for: new URL('/api/...', req.url) pattern"
+if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\(['\"][^'\"]*['\"],\s*req\.url" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
+    echo "ERROR: Found 'new URL(path, req.url)' pattern. Use internalFetch() instead."
+    ERRORS_FOUND=1
+fi
+
+# Pattern 2: new URL('/api/...', req.nextUrl) or new URL(..., req.nextUrl.origin)
+echo ""
+echo "Checking for: new URL(..., req.nextUrl) pattern"
+if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\([^)]+,\s*req\.nextUrl" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
+    echo "ERROR: Found 'new URL(..., req.nextUrl)' pattern. Use internalFetch() instead."
+    ERRORS_FOUND=1
+fi
+
+# Pattern 3: fetch with req.nextUrl.origin and /api/
+echo ""
+echo "Checking for: fetch with req.nextUrl.origin and /api/"
+if grep -rn --include="*.ts" --include="*.tsx" "req\.nextUrl\.origin.*\/api\/" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
+    echo "ERROR: Found 'req.nextUrl.origin' used with internal API route. Use internalFetch() instead."
+    ERRORS_FOUND=1
+fi
+
+# Pattern 4: Direct fetch to /api/auth/refresh without using internalRefresh (warning only)
+echo ""
+echo "Checking for: Direct fetch to /api/auth/refresh (should use internalRefresh)"
+if grep -rn --include="*.ts" --include="*.tsx" "fetch.*\/api\/auth\/refresh" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts" | grep -v "internal-api\.ts"; then
+    echo "WARNING: Found direct fetch to /api/auth/refresh. Consider using internalRefresh() helper."
+    # Not failing on this one as it might be intentional in some cases (client-side refresh)
+fi
+
+echo ""
+echo "========================================================================"
+
+if [ $ERRORS_FOUND -eq 1 ]; then
+    echo "FAILED: Dangerous internal URL patterns detected!"
+    echo ""
+    echo "Fix: Import and use helpers from @payez/next-mvp/lib/internal-api:"
+    echo "  import { internalFetch, internalRefresh } from '@payez/next-mvp/lib/internal-api';"
+    echo ""
+    echo "Why: Server-to-server calls must use INTERNAL_API_URL (http://service.namespace.svc.cluster.local)"
+    echo "     not the external URL from the request (https://api.example.com) which fails in Kubernetes."
+    exit 1
+else
+    echo "PASSED: No dangerous internal URL patterns found."
+    exit 0
+fi

package/scripts/check-publish-health.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * 171900 item (2) — PUBLISH-HEALTH CHECK.
+ *
+ * WHY THIS EXISTS. The npm token for @payez/next-mvp expired 2026-06-14 and was
+ * never replaced. Nine versions went unpublished for ~7 weeks and NOBODY NOTICED,
+ * because everyone installs from local tarballs — so npm was never a consumer and
+ * nothing ever failed. The one-off fix (re-auth, publish 4.1.20) was applied and the
+ * drift RESUMED IMMEDIATELY: as of 2026-08-08 the registry still says 4.1.20 while
+ * local is 4.1.25, and `npm whoami` returns ENEEDAUTH again.
+ *
+ * A re-auth is not a fix. The fix is a consumer that FAILS when npm lags — which is
+ * this script. Without it, the next silent expiry is invisible for another 7 weeks.
+ *
+ * DESIGN NOTES (deliberate, do not "helpfully" soften these):
+ *   - It EXITS NON-ZERO on lag. A check that warns is a check that gets ignored;
+ *     that is precisely how the original outage survived 7 weeks.
+ *   - It is NOT wired into prepack/prepublishOnly. Packing must not require the
+ *     network, and a build that breaks when npm is unreachable trades one outage
+ *     for another. Run it in CI/release, or by hand before a release.
+ *   - Missing auth is reported as its OWN outcome, not folded into "lagging".
+ *     Those are different failures with different fixes (credential vs publish).
+ *
+ * Usage:  node scripts/check-publish-health.mjs
+ * Exit:   0 = registry is at or ahead of local
+ *         1 = registry LAGS local (unpublished versions exist)
+ *         2 = could not determine (network/registry/parse) — inconclusive, NOT a pass
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(here, '..', 'package.json');
+
+function run(args) {
+  return execFileSync('npm', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: process.platform === 'win32',
+  }).trim();
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Numeric-aware semver compare. Returns >0 if a > b, 0 if equal, <0 if a < b. */
+function compareVersions(a, b) {
+  const norm = (v) => String(v).split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [norm(a), norm(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+let local;
+try {
+  local = JSON.parse(readFileSync(pkgPath, 'utf8'));
+} catch (err) {
+  console.error(`[publish-health] INCONCLUSIVE: cannot read ${pkgPath}: ${err.message}`);
+  process.exit(2);
+}
+
+const name = local.name;
+const localVersion = local.version;
+
+// 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;
+try {
+  authUser = run(['whoami']);
+} catch {
+  authUser = null;
+}
+
+// READ THE REGISTRY, NOT npm's CACHE (measured 2026-09-10, Nextpert-Scout).
+//
+// This script is wired as `postpublish` in package.json. postpublish runs ONLY after
+// a SUCCESSFUL upload — so the one moment it is guaranteed to run is the one moment
+// npm's metadata cache is guaranteed to be stale. Publishing 4.4.0 produced:
+//
+//     [publish-health] FAIL: the registry LAGS local by at least one version.
+//     [publish-health] 4.4.0 is built locally but the registry serves 4.1.21.
+//     npm error code 1
+//
+// 4.4.0 was already live. THE HONEST REACTION TO THAT OUTPUT IS TO PUBLISH AGAIN,
+// which is the dangerous action — and against a registry that refuses republication
+// it burns a version number, which is how a version string ends up naming two trees.
+//
+// `--prefer-online` forces revalidation. The bounded retry covers real propagation
+// delay, which is seconds, not weeks.
+//
+// THIS DOES NOT SOFTEN THE CHECK, and it must not be "helpfully" turned into a warning:
+// a genuine lag (the 171900 failure mode — a dead credential leaving versions
+// unpublished for WEEKS) still exhausts every attempt and still exits non-zero. The
+// retry changes how accurately we read the registry, never what counts as a failure.
+const REGISTRY_ATTEMPTS = 4;
+const REGISTRY_RETRY_MS = 2000;
+
+let registryVersion = null;
+for (let attempt = 1; attempt <= REGISTRY_ATTEMPTS; attempt++) {
+  try {
+    registryVersion = run(['view', name, '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] local=${localVersion} registry=<absent>`);
+      process.exit(1);
+    }
+    console.error(`[publish-health] INCONCLUSIVE: could not query the registry: ${msg.split('\n')[0]}`);
+    console.error('[publish-health] Treat as UNKNOWN, not as a pass.');
+    process.exit(2);
+  }
+
+  // Stop as soon as the registry is at or ahead of local. Only an apparent lag is
+  // worth re-reading, and only because THIS script's own hook makes a stale read likely.
+  if (compareVersions(localVersion, registryVersion) <= 0) break;
+
+  if (attempt < REGISTRY_ATTEMPTS) {
+    console.log(
+      `[publish-health] registry says ${registryVersion}, local is ${localVersion} — ` +
+      `re-reading (${attempt}/${REGISTRY_ATTEMPTS - 1}) in case this is post-publish propagation lag.`,
+    );
+    sleepSync(REGISTRY_RETRY_MS);
+  }
+}
+
+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] npm auth : ${authUser ? `logged in as ${authUser}` : 'NOT AUTHENTICATED (npm whoami failed)'}`);
+
+if (delta > 0) {
+  console.error('');
+  console.error(`[publish-health] FAIL: the registry LAGS local by at least one version.`);
+  console.error(`[publish-health] ${localVersion} is built locally but the registry serves ${registryVersion}.`);
+  if (!authUser) {
+    console.error('[publish-health] ROOT CAUSE LIKELY: npm is not authenticated on this machine.');
+    console.error('[publish-health] This is the 171900 failure mode — a silent credential expiry.');
+  }
+  console.error('[publish-health] Unpublished versions are invisible to every consumer that is not');
+  console.error('[publish-health] installing from a local tarball. See cards 171900 / 185177.');
+  process.exit(1);
+}
+
+if (!authUser) {
+  console.error('');
+  console.error('[publish-health] FAIL: registry is current, but npm is NOT AUTHENTICATED here.');
+  console.error('[publish-health] The next publish will fail silently in exactly the 171900 way.');
+  process.exit(1);
+}
+
+console.log('[publish-health] OK: registry is at or ahead of local, and auth is live.');
+process.exit(0);

package/scripts/dev-broker.ps1

@@ -1,15 +1,34 @@
 # Dev profile: prod-like broker bootstrap via KV-signed client_assertion
 # Usage: powershell -File dev-broker.ps1 -ClientId "my_app" -Port 3000 -AppName "MyApp"
-# This script enables broker mode for PayEz MVP authentication
 #
-# IMPORTANT: Broker mode provides production-like OAuth/OIDC authentication
+# IMPORTANT: Broker mode provides production-like OAuth/OIDC authentication.
+#
+# THIS SCRIPT PRINTS WHICH IDP IT IS TALKING TO AND WHAT THAT IDP SAYS ABOUT THE
+# CLIENT. Jon 2026-08-26: "make sure the broker script returns the idp client
+# details into the log, it's important for devs to see that."
+#
+# WHY IT MATTERS: the same app can be pointed at different IDP hosts, and the only
+# difference visible in a terminal used to be a port number. Printing the host and
+# what that host says about this client makes it impossible to mistake.
 
 param(
-  [string]$ClientId = "2",
+  [string]$ClientId = "",
   [int]$Port = 3000,
   [string]$AppName = "PayEz MVP"
 )
 
+# NO NUMERIC DEFAULT. This used to default to "2" - a numeric id, on a system that
+# identifies clients BY SLUG (card 268410: the login door was numeric-only at five
+# sites). A silent numeric default means a dev who forgets the flag authenticates
+# against whatever client 2 happens to be, and the failure looks like a config bug.
+if ([string]::IsNullOrWhiteSpace($ClientId)) {
+  Write-Host "ERROR: -ClientId is required and must be the client SLUG, e.g. umi_browser_website" -ForegroundColor Red
+  Write-Host "       (there is deliberately no default - a numeric fallback authenticates you" -ForegroundColor Red
+  Write-Host "        against the wrong tenant and reads as a config bug)" -ForegroundColor Red
+  exit 1
+}
+
+Write-Host ""
 Write-Host "Starting $AppName in BROKER mode..." -ForegroundColor Cyan
 
 # Kill any existing process on the specified port
@@ -24,11 +43,57 @@ if ($connections) {
 }
 
 # Set required environment variables for broker mode
-$env:NEXT_CLIENT_ID = "$ClientId"
+# MEASURED 2026-08-26: this script set ONLY $env:NEXT_CLIENT_ID, and NOTHING on the
+# auth path reads that name - grep of the shipped dist finds it in demo-mode.js alone.
+# getIDPClientConfig() reads CLIENT_ID or NEXT_PUBLIC_CLIENT_ID and threw
+# "CLIENT_ID or NEXT_PUBLIC_CLIENT_ID must be set" the moment anything actually called
+# it. Three names for one value, and the script was setting the one that does not count.
+# All three are set here so no consumer is left guessing; the duplication is the bug,
+# and collapsing the names is a package change, not a script change.
+$env:CLIENT_ID = "$ClientId"
+$env:NEXT_PUBLIC_CLIENT_ID = "$ClientId"
+$env:NEXT_CLIENT_ID = "$ClientId"   # legacy: demo-mode.js only
 $env:USE_BROKER_MODE = "true"
 
-Write-Host "Client ID: $ClientId" -ForegroundColor Green
-Write-Host "Broker mode: ENABLED" -ForegroundColor Green
+# ── WHICH IDP ARE WE ACTUALLY TALKING TO? ────────────────────────────────────
+# Read it, never guess it. An unset IDP_URL is reported as UNSET rather than
+# quietly substituted, because a substituted host is the whole problem.
+# MEASURED 2026-08-26: reading only $env: reported "<UNSET>" on UMI while
+# .env.development held https://idp.payez.net. Next.js loads the .env files ITSELF
+# at startup, so the shell that runs this script never sees them - and a banner that
+# confidently prints the wrong leg is worse than printing nothing. Read the files in
+# the SAME PRECEDENCE Next uses, then let a real shell variable win (it does there too).
+function Get-EnvValue([string]$Name) {
+  # NOT `$env:$Name` - PowerShell cannot interpolate a variable into an env lookup
+  # that way; it parses as $env: followed by $Name and silently yields nothing.
+  $fromShell = [Environment]::GetEnvironmentVariable($Name)
+  if (-not [string]::IsNullOrWhiteSpace($fromShell)) { return $fromShell }
+  foreach ($f in @('.env.local', ".env.$($env:NODE_ENV)", '.env.development', '.env')) {
+    if ([string]::IsNullOrWhiteSpace($f)) { continue }
+    if (-not (Test-Path $f)) { continue }
+    foreach ($line in (Get-Content $f -ErrorAction SilentlyContinue)) {
+      if ($line -match "^\s*$([regex]::Escape($Name))\s*=\s*(.+?)\s*$") {
+        return $matches[1].Trim("'").Trim('"')
+      }
+    }
+  }
+  return $null
+}
+
+$idpUrl = Get-EnvValue 'IDP_URL'
+if ([string]::IsNullOrWhiteSpace($idpUrl)) { $idpUrl = "<UNSET>" }
+
+# NO BANNER HERE. The real readout is logStartupStatus() + ensureInitialized(), printed
+# by the app's own instrumentation.ts hook when Next boots - client id, slug, secret
+# length, OAuth providers, require2FA, cache TTL, base URL. That is the report devs read.
+#
+# A second banner in this script was a REIMPLEMENTATION of it, and it drifted immediately:
+# it read .env directly, reported <UNSET> for a value the app had, and claimed things about
+# provisioning it had not established. One reporter, at the point the app actually connects.
+#
+# If nothing prints below, the app has no instrumentation.ts wired - copy
+# node_modules/@payez/next-mvp/src/templates/instrumentation.ts to the project root.
+
 Write-Host "Starting Next.js dev server on port $Port..." -ForegroundColor Cyan
 
 # Use npx directly to avoid npm batch job nesting issues

package/scripts/print-client-config.mjs

@@ -0,0 +1,162 @@
+/**
+ * Print what the IDP says about THIS client, using the real broker handshake.
+ *
+ * Jon 2026-08-26: "the main thing I am looking for is the response from the IDP about
+ * the tenant app - does it require 2fa, does it do google oauth. I could give a shit
+ * about the .env.development that I just set before starting the site."
+ *
+ * So this does NOT print local configuration. It performs the same two-step the app
+ * performs -- POST /api/ExternalAuth/sign-client-assertion, then POST
+ * /api/ExternalAuth/client-config with that assertion -- by calling the package's OWN
+ * getIDPClientConfig(). Reimplementing the handshake here would be a second copy of
+ * the one thing that must not drift.
+ *
+ * HOW IT LOADS THE MODULE, AND WHY IT LOOKS LIKE THIS:
+ * The package is CommonJS (no "type": "module", main: dist/index.js) and its
+ * package.json `exports` map does NOT list ./dist/lib/*, so a subpath import is
+ * BLOCKED by Node's exports resolution. Requiring the file by ABSOLUTE PATH bypasses
+ * the map, which is the only route to a module the package does not publish.
+ *
+ * An earlier version wrapped the import in .catch(() => import('@payez/next-mvp')) and
+ * reported "not exported" -- a fallback that replaced a precise error (ERR_PACKAGE_PATH_
+ * NOT_EXPORTED) with a wrong one. There are no fallbacks here now: each step fails with
+ * its own reason.
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pad = (k) => String(k).padEnd(24);
+const line = () => console.log('-'.repeat(62));
+
+function fail(msg) {
+  loud();
+  line();
+  // FIRST LINE ONLY. A stack trace buries the sentence the reader needs, and the
+  // file:line is already in the raw stderr above for anyone who wants it.
+  const m = String(msg).split(String.fromCharCode(10))[0].replace(/^Error:\s*/, '');
+
+  // DISTINGUISH THE TWO FAILURES. "The IDP never answered" and "the IDP answered and
+  // this client is barely provisioned" are different facts, and the second is the one
+  // a dev can act on. Jon 2026-08-26: "that is fine if they are not there, it's the
+  // clearly knowing that or not knowing that that is the issue."
+  const answered = /authSecret is empty|missing client_assertion|after parsing/i.test(m);
+
+  if (answered) {
+    // SPECIFIC, NOT GENERAL. Report the fields the IDP actually returned and name the
+    // one that is absent. Jon 2026-08-26: a vague "not provisioned" was wrong - the
+    // client record is fully configured. State the fact, not a conclusion drawn from it.
+    const rawKeys = (captured.find((l) => l.includes('raw keys:')) || '')
+      .split('raw keys:')[1]?.trim() ?? '(not reported)';
+
+    console.log(' IDP ANSWERED - RESPONSE INCOMPLETE FOR BROKER MODE');
+    line();
+    console.log('  Fields the IDP returned : ' + rawKeys);
+    console.log('  Field broker mode needs : authSecret   <- ABSENT');
+    console.log('');
+    console.log('  The client record exists and is active. The broker secret is');
+    console.log('  provisioned separately from it, and is not present here.');
+    console.log('');
+    console.log('  NOT DETERMINED by this run - the handshake stopped before reading them:');
+    console.log('    require 2FA, allowed 2FA methods, federated OAuth providers,');
+    console.log('    public registration, password reset.');
+    console.log('  Do not infer any of those from this message.');
+    console.log('');
+    console.log('  IDP said: ' + m);
+    console.log('');
+    console.log('  TO FIX: provision the broker secret for this client, then rerun.');
+    console.log('  The app still starts - it just cannot read its sign-in policy yet.');
+  } else {
+    console.log(' IDP CLIENT CONFIG: HANDSHAKE FAILED');
+    line();
+    console.log('  ' + m);
+    console.log('  The IDP could not be reached, or refused the assertion. You do NOT');
+    console.log('  know what this tenant requires.');
+  }
+  line();
+  process.exitCode = 1;
+}
+
+// The package logs its own fetch-failure object to console.error. This script is a
+// BANNER, not the app: keep stderr for real faults so the box below is the answer.
+const _err = console.error, _log = console.log;
+const captured = [];
+const quiet = () => {
+  console.error = (...a) => captured.push(a.map(String).join(' '));
+  console.log   = (...a) => captured.push(a.map(String).join(' '));
+};
+const loud  = () => { console.error = _err; console.log = _log; };
+quiet();
+
+try {
+  const require = createRequire(path.join(process.cwd(), 'noop.js'));
+
+  // Resolve the package ROOT via its main entry, then reach the unexported module by
+  // absolute path. require.resolve on the bare name honours `exports`; on an absolute
+  // path it does not.
+  const mainEntry = require.resolve('@payez/next-mvp');           // <root>/dist/index.js
+  const distDir = path.dirname(mainEntry);                        // <root>/dist
+  const target = path.join(distDir, 'lib', 'idp-client-config.js');
+
+  // `server-only` is a MARKER package: importing it from a client bundle is meant to
+  // throw. It has no runtime behaviour on the server, and it is not always hoisted into
+  // a consumer's node_modules. This script IS a server context, so the marker is
+  // satisfied explicitly with an empty module rather than the require being wrapped in
+  // a catch that would hide a genuinely missing dependency.
+  const Module = require('node:module');
+  const origResolve = Module._resolveFilename;
+  Module._resolveFilename = function (request, ...rest) {
+    if (request === 'server-only' || request === 'client-only') {
+      // must be a REAL FILE PATH. fileURLToPath, not manual URL parsing: this folder
+      // is "UMI - Website" and a raw import.meta.url keeps the space as %20, which
+      // then ENOENTs on a path that looks correct in the error message.
+      return path.join(path.dirname(fileURLToPath(import.meta.url)), 'server-only-stub.cjs');
+    }
+    return origResolve.call(this, request, ...rest);
+  };
+
+  let mod;
+  try {
+    mod = require(target);
+  } catch (e) {
+    fail(`could not load ${target}\n  ${e.message}`);
+  }
+
+  const getCfg = mod.getIDPClientConfig ?? mod.default?.getIDPClientConfig;
+  if (typeof getCfg !== 'function') {
+    fail(`getIDPClientConfig missing from ${target}. Exports present: ` +
+         Object.keys(mod).join(', '));
+  }
+
+  const cfg = await getCfg(true);
+  console.error = _err; // forceRefresh: never report a cached answer
+
+  line();
+  console.log(' AS REPORTED BY THE IDP  (broker handshake, signed client_assertion)');
+  line();
+
+  console.log(pad('  require 2FA') + ': ' + cfg.require2FA);
+  console.log(pad('  allowed 2FA methods') + ': ' +
+    ((cfg.allowed2FAMethods ?? []).join(', ') || '(none)'));
+  console.log(pad('  MFA grace period') + ': ' + cfg.mfaGracePeriodHours + 'h');
+  console.log(pad('  remember device') + ': ' + cfg.mfaRememberDeviceDays + 'd');
+
+  const provs = cfg.oauthProviders ?? [];
+  const on = provs.filter((p) => p.enabled).map((p) => p.provider ?? p.name ?? '?');
+  const off = provs.filter((p) => !p.enabled).map((p) => p.provider ?? p.name ?? '?');
+  console.log(pad('  OAuth providers ON') + ': ' + (on.join(', ') || '(none)'));
+  if (off.length) console.log(pad('  OAuth providers off') + ': ' + off.join(', '));
+
+  for (const [label, key] of [
+    ['social login', 'allowSocialLogin'],
+    ['public registration', 'allowPublicRegistration'],
+    ['password reset', 'enablePasswordReset'],
+    ['remember me', 'allowRememberMe'],
+  ]) {
+    if (cfg[key] !== undefined) console.log(pad('  ' + label) + ': ' + cfg[key]);
+  }
+  line();
+  process.exitCode = 0;
+} catch (err) {
+  fail(err?.stack ?? err?.message ?? String(err));
+}

package/scripts/server-only-stub.cjs

@@ -0,0 +1,4 @@
+// Empty stand-in for the `server-only` / `client-only` MARKER packages.
+// They have no runtime behaviour; they exist so a bundler can fail a bad import.
+// A node script running server-side satisfies the marker by definition.
+module.exports = {};

package/src/api-handlers/account/recovery/initiate.ts

@@ -1,4 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
+import { getIDPClientConfig } from '../../../lib/idp-client-config';
+import { resolveClientKey } from '../../../lib/client-key';
 
 function getIdpUrl(): string {
   const url = process.env.IDP_URL;
@@ -6,14 +8,45 @@ function getIdpUrl(): string {
   return url;
 }
 
+/**
+ * RECOVERY CLIENT KEY — cards 268012 (S12) and 268410.
+ *
+ * These four proxies populated NONE of PayEzClientIdResolver's six slots, so
+ * RequirePayEzUnAuthorized 404'd the request BEFORE the action ran and no
+ * recovery token was ever minted. That is why S12 failed at step 1.
+ *
+ * NOT `ENV_CONFIG.CLIENT_ID`, which is what card 268012 originally prescribed.
+ * That variable is the ENVIRONMENT-SPECIFIC NUMERIC id, and the IDP accepts a
+ * numeric with NO existence check (RequirePayEzUnAuthorizedAttribute.cs:31-33)
+ * while it VALIDATES a slug (:41-47). Hardcoding the numeric here would have
+ * added four more sites to the 268410 family and made a stale id answer for
+ * the WRONG TENANT on a password-reset path, silently. Slug-preferring, with
+ * the numeric fallback logged, is the same resolver the other nine sites use.
+ *
+ * SERVER VALUE WINS: client_id is applied AFTER the caller's payload spread.
+ * These are unauthenticated recovery endpoints, so a browser-supplied
+ * client_id would be a tenant-targeting lever. The caller does not get to
+ * choose which tenant their password reset is addressed to.
+ */
+async function recoveryClientKey(): Promise<string | null> {
+  try {
+    const config = await getIDPClientConfig();
+    return resolveClientKey(config, 'account/recovery/initiate').key;
+  } catch (e) {
+    console.error('[account/recovery/initiate] could not resolve IDP client config for client_id:', e);
+    return null;
+  }
+}
+
 export async function POST(req: NextRequest) {
   const IDP_URL = getIdpUrl();
   try {
     const { email } = await req.json();
+    const clientKey = await recoveryClientKey();
     const upstream = await fetch(`${IDP_URL}/api/Account/recovery/initiate`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email }),
+      headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+      body: JSON.stringify({ email, ...(clientKey ? { client_id: clientKey } : {}) }),
     });
     const data = await upstream.json().catch(() => ({}));
     return NextResponse.json(data, { status: upstream.status });