@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/authorize-resume.ts

@@ -1,175 +1,175 @@
-/**
- * PAY-2302 cut 2: moved VERBATIM (logic unchanged) from VibeID-Customer-Portal src/lib/auth/authorize-resume.ts.
- * PAY-1500 (portal half of PAY-1479): resume the IdP OAuth authorize request after 2FA.
- *
- * The IdP sends an OAuth principal who still owes 2FA to the portal's /account-auth/verify-code with
- *   ?next_step=enroll_mfa|mfa_verify&callbackUrl=<absolute IdP authorize URL>&return_url=<same>
- * (OAuthController.Authorize; hotfix-2 66ca7a8eb routes BOTH cases to verify-code, /account/security is gone). safeCallbackPath rightly refuses that absolute URL,
- * so after 2FA the user used to land on the default page and sign-in never finished.
- *
- * This is NOT a relaxation of safeCallbackPath. The browser is sent to the portal's own
- * /api/oauth/resume, which checks return_url SERVER-SIDE against IDP_URL (origin + the authorize path)
- * and only then redirects. Anything else is refused. IDP_URL never reaches the client.
- */
-export const AUTHORIZE_RESUME_ROUTE = '/api/oauth/resume';
-const AUTHORIZE_PATH = '/api/oauth/authorize';
-
-/** True only for `<IDP_URL origin>/api/oauth/authorize` (path case-insensitive, as ASP.NET routes). */
-export function isIdpAuthorizeUrl(candidate: string | null | undefined, idpBaseUrl: string): boolean {
-  if (typeof candidate !== 'string' || candidate === '') return false;
-  try {
-    const u = new URL(candidate);
-    const idp = new URL(idpBaseUrl);
-    return (u.protocol === 'https:' || u.protocol === 'http:') && u.origin === idp.origin && u.pathname.toLowerCase() === AUTHORIZE_PATH;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Server side: the redirect target, REBUILT from trusted parts - IDP_URL's origin and the authorize path
- * are ours; only the query string comes from the request. Null unless isIdpAuthorizeUrl holds.
- */
-export function idpAuthorizeRedirect(candidate: string | null | undefined, idpBaseUrl: string): string | null {
-  if (!isIdpAuthorizeUrl(candidate, idpBaseUrl)) return null;
-  const query = new URL(candidate as string).search;
-  return `${new URL(idpBaseUrl).origin}/api/OAuth/authorize${query}`;
-}
-
-/**
- * Client side: the SAME-ORIGIN portal path that resumes authorize, or null when the IdP did not ask for one.
- * Callers still pass the result through safeCallbackPath before navigating.
- *
- * WHY THE ASTERISK IS RE-ENCODED (PAY-1547, measured by NextPert 59939, completeness measured here).
- * One consumer of this value is `authClient.signIn.social({ callbackURL })`, which POSTs to better-auth
- * and is validated by its own originCheckMiddleware BEFORE anything redirects. For a relative path that
- * check is decided entirely by one regex (better-auth 1.5.6, auth/trusted-origins.mjs:16 - the
- * `allowRelativePaths` branch, and api/middlewares/origin-check.mjs:51 passes
- * `allowRelativePaths: label !== 'origin'`, so it IS that branch for a callbackURL):
- *
- *     /^\/(?!\/|\\|%2f|%5c)[\w\-.\+\/@]*(?:\?[\w\-.\+\/=&%@]*)?$/
- *
- * A character this helper emits RAW and that charset rejects is a hard 403 INVALID_CALLBACK_URL on the
- * Google button - not a silent fallback. Measured exhaustively over printable ASCII by diffing what
- * `URLSearchParams` leaves raw against that charset: the raw set is alphanumerics plus `* - . _`, and
- * *** `*` IS THE ONLY REJECTED MEMBER *** (`%` is permitted, which is why every other special character
- * survives - URLSearchParams already percent-encoded it).
- *
- * `*` is reachable because `state` and `scope` are chosen by the OAuth CLIENT, not by us, so we cannot
- * decline to emit it. `%2A` is the same character to every parser: re-reading this query string returns
- * the byte-identical `return_url` (asserted in test/authorize-resume.test.cjs), so this is an encoding
- * change and NOT a value change. It is applied here, at the ONE computation, rather than at the sinks -
- * the two `window.location.href` sinks are browser navigations that touch no library and for which this
- * is a behavioural no-op, so there is no reason to make them each carry it.
- */
-export function authorizeResumeHref(returnUrl: string | null | undefined): string | null {
-  if (typeof returnUrl !== 'string' || returnUrl === '') return null;
-  const query = new URLSearchParams({ return_url: returnUrl }).toString().replace(/\*/g, '%2A');
-  return `${AUTHORIZE_RESUME_ROUTE}?${query}`;
-}
-
-// ───────────────────────── 4.7.5 (PAY-2305): the authorize call is made SERVER-SIDE ─────────────────────────
-//
-// WHY: Core's /api/oauth/authorize identifies a user ONLY from an `Authorization: Bearer` header (JwtMiddleware reads no cookie,
-// and a browser navigation cannot send a header), so the 4.7.0-4.7.4 behaviour - 302 the BROWSER to authorize - could never
-// produce a code for anyone. The resume route now calls authorize itself with the signed-in user's IdP access token and relays
-// only the verified outcome. These helpers are the pure, testable parts.
-
-export interface ServerAuthorizeParams {
-  idpBaseUrl: string;
-  /** This app's IdP client slug (CLIENT_ID). The request's client_id must equal it. */
-  clientId: string;
-  /** The app's REGISTERED redirect_uri, e.g. http://localhost:3000/api/auth/callback. The request's redirect_uri must equal it exactly. */
-  redirectUri: string;
-}
-
-export interface ServerAuthorizeRequest {
-  /** Built from constants + validated pieces only. This is what gets fetched. */
-  url: string;
-  state: string;
-}
-
-const CHALLENGE_RE = /^[A-Za-z0-9_-]{43,128}$/;
-const STATE_RE = /^[A-Za-z0-9._~-]{1,256}$/;
-const SCOPE_RE = /^[A-Za-z0-9:._ -]{1,200}$/;
-
-/**
- * Build the authorize URL to call, or null (refuse). Origin, path, response_type, client_id and redirect_uri are OURS; from
- * return_url only code_challenge (+ method, S256 only), state and scope are taken, each charset/length validated. A return_url for
- * another client or another redirect_uri is refused (no "someone else's client"). Unknown extra parameters are NOT forwarded.
- */
-export function buildServerAuthorizeRequest(returnUrl: string | null | undefined, p: ServerAuthorizeParams): ServerAuthorizeRequest | null {
-  if (!isIdpAuthorizeUrl(returnUrl, p.idpBaseUrl) || !p.clientId || !p.redirectUri) return null;
-  const q = new URL(returnUrl as string).searchParams;
-  const once = (name: string): string | null => {
-    const all = q.getAll(name);
-    return all.length === 1 ? all[0] : all.length === 0 ? null : '\u0000'; // a repeated parameter is ambiguous: refused below
-  };
-  const responseType = once('response_type');
-  if (responseType !== null && responseType !== 'code') return null;
-  if (once('client_id') !== p.clientId) return null;
-  if (once('redirect_uri') !== p.redirectUri) return null;
-  const challenge = once('code_challenge');
-  const method = once('code_challenge_method');
-  const state = once('state');
-  const scope = once('scope');
-  if (challenge === null || !CHALLENGE_RE.test(challenge)) return null;
-  if (method !== 'S256') return null;
-  if (state === null || !STATE_RE.test(state)) return null;
-  if (scope !== null && !SCOPE_RE.test(scope)) return null;
-
-  const out = new URLSearchParams();
-  out.set('response_type', 'code');
-  out.set('client_id', p.clientId);
-  out.set('redirect_uri', p.redirectUri);
-  if (scope !== null) out.set('scope', scope);
-  out.set('state', state);
-  out.set('code_challenge', challenge);
-  out.set('code_challenge_method', 'S256');
-  return { url: `${new URL(p.idpBaseUrl).origin}${AUTHORIZE_PATH}?${out.toString()}`, state };
-}
-
-/**
- * The IdP's answer to the server-side authorize call. Returns the RELATIVE path+query to send the browser to, or null (refuse).
- * Only a redirect whose Location is EXACTLY the registered redirect_uri (origin + path), with a code and the state we sent and no
- * error, qualifies. The relayed value is REBUILT from the validated code and state, never copied from the Location.
- */
-export function relayRegisteredCallback(status: number, location: string | null | undefined, redirectUri: string, sentState: string): string | null {
-  if (status < 300 || status > 399 || typeof location !== 'string' || location === '') return null;
-  let loc: URL;
-  let reg: URL;
-  try {
-    reg = new URL(redirectUri);
-    loc = new URL(location, reg.origin);
-  } catch {
-    return null;
-  }
-  if (loc.origin !== reg.origin || loc.pathname !== reg.pathname) return null;
-  if (loc.searchParams.has('error')) return null;
-  const codes = loc.searchParams.getAll('code');
-  const states = loc.searchParams.getAll('state');
-  if (codes.length !== 1 || !/^[A-Za-z0-9._~+/=-]{8,512}$/.test(codes[0])) return null;
-  if (states.length !== 1 || states[0] !== sentState) return null;
-  return `${reg.pathname}?${new URLSearchParams({ code: codes[0], state: sentState }).toString()}`;
-}
-
-/**
- * The resume must be a same-site navigation. Sec-Fetch-Site decides when the browser sends it; otherwise Referer must be this
- * app's own origin; with neither it is refused (a crafted cross-site link must not make the victim's browser trigger authorize
- * with the victim's token).
- */
-export function isSameSiteResume(headers: { get(name: string): string | null }, appOrigin: string): boolean {
-  const sfs = headers.get('sec-fetch-site');
-  // same-origin or none only: a sibling subdomain ('same-site') is not this app.
-  if (sfs !== null) return sfs === 'same-origin' || sfs === 'none';
-  const referer = headers.get('referer');
-  if (!referer) return false;
-  try {
-    return new URL(referer).origin === appOrigin;
-  } catch {
-    return false;
-  }
-}
+/**
+ * PAY-2302 cut 2: moved VERBATIM (logic unchanged) from VibeID-Customer-Portal src/lib/auth/authorize-resume.ts.
+ * PAY-1500 (portal half of PAY-1479): resume the IdP OAuth authorize request after 2FA.
+ *
+ * The IdP sends an OAuth principal who still owes 2FA to the portal's /account-auth/verify-code with
+ *   ?next_step=enroll_mfa|mfa_verify&callbackUrl=<absolute IdP authorize URL>&return_url=<same>
+ * (OAuthController.Authorize; hotfix-2 66ca7a8eb routes BOTH cases to verify-code, /account/security is gone). safeCallbackPath rightly refuses that absolute URL,
+ * so after 2FA the user used to land on the default page and sign-in never finished.
+ *
+ * This is NOT a relaxation of safeCallbackPath. The browser is sent to the portal's own
+ * /api/oauth/resume, which checks return_url SERVER-SIDE against IDP_URL (origin + the authorize path)
+ * and only then redirects. Anything else is refused. IDP_URL never reaches the client.
+ */
+export const AUTHORIZE_RESUME_ROUTE = '/api/oauth/resume';
+const AUTHORIZE_PATH = '/api/oauth/authorize';
+
+/** True only for `<IDP_URL origin>/api/oauth/authorize` (path case-insensitive, as ASP.NET routes). */
+export function isIdpAuthorizeUrl(candidate: string | null | undefined, idpBaseUrl: string): boolean {
+  if (typeof candidate !== 'string' || candidate === '') return false;
+  try {
+    const u = new URL(candidate);
+    const idp = new URL(idpBaseUrl);
+    return (u.protocol === 'https:' || u.protocol === 'http:') && u.origin === idp.origin && u.pathname.toLowerCase() === AUTHORIZE_PATH;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Server side: the redirect target, REBUILT from trusted parts - IDP_URL's origin and the authorize path
+ * are ours; only the query string comes from the request. Null unless isIdpAuthorizeUrl holds.
+ */
+export function idpAuthorizeRedirect(candidate: string | null | undefined, idpBaseUrl: string): string | null {
+  if (!isIdpAuthorizeUrl(candidate, idpBaseUrl)) return null;
+  const query = new URL(candidate as string).search;
+  return `${new URL(idpBaseUrl).origin}/api/OAuth/authorize${query}`;
+}
+
+/**
+ * Client side: the SAME-ORIGIN portal path that resumes authorize, or null when the IdP did not ask for one.
+ * Callers still pass the result through safeCallbackPath before navigating.
+ *
+ * WHY THE ASTERISK IS RE-ENCODED (PAY-1547, measured by NextPert 59939, completeness measured here).
+ * One consumer of this value is `authClient.signIn.social({ callbackURL })`, which POSTs to better-auth
+ * and is validated by its own originCheckMiddleware BEFORE anything redirects. For a relative path that
+ * check is decided entirely by one regex (better-auth 1.5.6, auth/trusted-origins.mjs:16 - the
+ * `allowRelativePaths` branch, and api/middlewares/origin-check.mjs:51 passes
+ * `allowRelativePaths: label !== 'origin'`, so it IS that branch for a callbackURL):
+ *
+ *     /^\/(?!\/|\\|%2f|%5c)[\w\-.\+\/@]*(?:\?[\w\-.\+\/=&%@]*)?$/
+ *
+ * A character this helper emits RAW and that charset rejects is a hard 403 INVALID_CALLBACK_URL on the
+ * Google button - not a silent fallback. Measured exhaustively over printable ASCII by diffing what
+ * `URLSearchParams` leaves raw against that charset: the raw set is alphanumerics plus `* - . _`, and
+ * *** `*` IS THE ONLY REJECTED MEMBER *** (`%` is permitted, which is why every other special character
+ * survives - URLSearchParams already percent-encoded it).
+ *
+ * `*` is reachable because `state` and `scope` are chosen by the OAuth CLIENT, not by us, so we cannot
+ * decline to emit it. `%2A` is the same character to every parser: re-reading this query string returns
+ * the byte-identical `return_url` (asserted in test/authorize-resume.test.cjs), so this is an encoding
+ * change and NOT a value change. It is applied here, at the ONE computation, rather than at the sinks -
+ * the two `window.location.href` sinks are browser navigations that touch no library and for which this
+ * is a behavioural no-op, so there is no reason to make them each carry it.
+ */
+export function authorizeResumeHref(returnUrl: string | null | undefined): string | null {
+  if (typeof returnUrl !== 'string' || returnUrl === '') return null;
+  const query = new URLSearchParams({ return_url: returnUrl }).toString().replace(/\*/g, '%2A');
+  return `${AUTHORIZE_RESUME_ROUTE}?${query}`;
+}
+
+// ───────────────────────── 4.7.5 (PAY-2305): the authorize call is made SERVER-SIDE ─────────────────────────
+//
+// WHY: Core's /api/oauth/authorize identifies a user ONLY from an `Authorization: Bearer` header (JwtMiddleware reads no cookie,
+// and a browser navigation cannot send a header), so the 4.7.0-4.7.4 behaviour - 302 the BROWSER to authorize - could never
+// produce a code for anyone. The resume route now calls authorize itself with the signed-in user's IdP access token and relays
+// only the verified outcome. These helpers are the pure, testable parts.
+
+export interface ServerAuthorizeParams {
+  idpBaseUrl: string;
+  /** This app's IdP client slug (CLIENT_ID). The request's client_id must equal it. */
+  clientId: string;
+  /** The app's REGISTERED redirect_uri, e.g. http://localhost:3000/api/auth/callback. The request's redirect_uri must equal it exactly. */
+  redirectUri: string;
+}
+
+export interface ServerAuthorizeRequest {
+  /** Built from constants + validated pieces only. This is what gets fetched. */
+  url: string;
+  state: string;
+}
+
+const CHALLENGE_RE = /^[A-Za-z0-9_-]{43,128}$/;
+const STATE_RE = /^[A-Za-z0-9._~-]{1,256}$/;
+const SCOPE_RE = /^[A-Za-z0-9:._ -]{1,200}$/;
+
+/**
+ * Build the authorize URL to call, or null (refuse). Origin, path, response_type, client_id and redirect_uri are OURS; from
+ * return_url only code_challenge (+ method, S256 only), state and scope are taken, each charset/length validated. A return_url for
+ * another client or another redirect_uri is refused (no "someone else's client"). Unknown extra parameters are NOT forwarded.
+ */
+export function buildServerAuthorizeRequest(returnUrl: string | null | undefined, p: ServerAuthorizeParams): ServerAuthorizeRequest | null {
+  if (!isIdpAuthorizeUrl(returnUrl, p.idpBaseUrl) || !p.clientId || !p.redirectUri) return null;
+  const q = new URL(returnUrl as string).searchParams;
+  const once = (name: string): string | null => {
+    const all = q.getAll(name);
+    return all.length === 1 ? all[0] : all.length === 0 ? null : '\u0000'; // a repeated parameter is ambiguous: refused below
+  };
+  const responseType = once('response_type');
+  if (responseType !== null && responseType !== 'code') return null;
+  if (once('client_id') !== p.clientId) return null;
+  if (once('redirect_uri') !== p.redirectUri) return null;
+  const challenge = once('code_challenge');
+  const method = once('code_challenge_method');
+  const state = once('state');
+  const scope = once('scope');
+  if (challenge === null || !CHALLENGE_RE.test(challenge)) return null;
+  if (method !== 'S256') return null;
+  if (state === null || !STATE_RE.test(state)) return null;
+  if (scope !== null && !SCOPE_RE.test(scope)) return null;
+
+  const out = new URLSearchParams();
+  out.set('response_type', 'code');
+  out.set('client_id', p.clientId);
+  out.set('redirect_uri', p.redirectUri);
+  if (scope !== null) out.set('scope', scope);
+  out.set('state', state);
+  out.set('code_challenge', challenge);
+  out.set('code_challenge_method', 'S256');
+  return { url: `${new URL(p.idpBaseUrl).origin}${AUTHORIZE_PATH}?${out.toString()}`, state };
+}
+
+/**
+ * The IdP's answer to the server-side authorize call. Returns the RELATIVE path+query to send the browser to, or null (refuse).
+ * Only a redirect whose Location is EXACTLY the registered redirect_uri (origin + path), with a code and the state we sent and no
+ * error, qualifies. The relayed value is REBUILT from the validated code and state, never copied from the Location.
+ */
+export function relayRegisteredCallback(status: number, location: string | null | undefined, redirectUri: string, sentState: string): string | null {
+  if (status < 300 || status > 399 || typeof location !== 'string' || location === '') return null;
+  let loc: URL;
+  let reg: URL;
+  try {
+    reg = new URL(redirectUri);
+    loc = new URL(location, reg.origin);
+  } catch {
+    return null;
+  }
+  if (loc.origin !== reg.origin || loc.pathname !== reg.pathname) return null;
+  if (loc.searchParams.has('error')) return null;
+  const codes = loc.searchParams.getAll('code');
+  const states = loc.searchParams.getAll('state');
+  if (codes.length !== 1 || !/^[A-Za-z0-9._~+/=-]{8,512}$/.test(codes[0])) return null;
+  if (states.length !== 1 || states[0] !== sentState) return null;
+  return `${reg.pathname}?${new URLSearchParams({ code: codes[0], state: sentState }).toString()}`;
+}
+
+/**
+ * The resume must be a same-site navigation. Sec-Fetch-Site decides when the browser sends it; otherwise Referer must be this
+ * app's own origin; with neither it is refused (a crafted cross-site link must not make the victim's browser trigger authorize
+ * with the victim's token).
+ */
+export function isSameSiteResume(headers: { get(name: string): string | null }, appOrigin: string): boolean {
+  const sfs = headers.get('sec-fetch-site');
+  // same-origin or none only: a sibling subdomain ('same-site') is not this app.
+  if (sfs !== null) return sfs === 'same-origin' || sfs === 'none';
+  const referer = headers.get('referer');
+  if (!referer) return false;
+  try {
+    return new URL(referer).origin === appOrigin;
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Binds the resume to a browser that STARTED this app's OAuth flow: better-auth (storeStateStrategy 'cookie') sets an

package/src/lib/bearer-fetch.ts

@@ -1,31 +1,31 @@
-/**
- * PAY-1777 item 5 (QAPert-NightHawk, PR 663 G4 thread 4395; coverage widened per BAPert 64034): THE way a server-side call
- * that carries a user's (or a provisional) bearer token talks to the identity service.
- *
- * A bearer must never follow a redirect. Modern fetch drops Authorization on a CROSS-origin hop, but a same-origin hop - or
- * an older runtime - does not, and we do not rely on that. So:
- *   - the request is always sent with redirect: 'manual' (set AFTER the caller's init, so no caller can switch it back);
- *   - any 3xx, or an opaque redirect, is never followed and never relayed: the caller receives a synthetic
- *     502 { success:false, error:{ code:'IDP_UNREACHABLE' } } Response instead, which every existing non-2xx branch at the
- *     call sites already handles. Every other response is returned untouched.
- *
- * Moved from VibeID-Customer-Portal (src/lib/idp/bearer-fetch.ts) into the package by PAY-2302; the portal's gate
- * (testing/qa/idp-bearer-no-redirect-gate.js) keeps inventorying its own Authorization-bearing fetches.
- */
-export const REDIRECT_REFUSED_CODE = 'IDP_UNREACHABLE';
-
-export function isRedirectResponse(res: Response): boolean {
-  return res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
-}
-
-export async function bearerFetch(input: string | URL, init: RequestInit = {}): Promise<Response> {
-  const res = await fetch(input, { ...init, redirect: 'manual' });
-  if (!isRedirectResponse(res)) return res;
-  return new Response(
-    JSON.stringify({
-      success: false,
-      error: { code: REDIRECT_REFUSED_CODE, message: 'The identity service answered with a redirect; the call was not followed' },
-    }),
-    { status: 502, headers: { 'Content-Type': 'application/json' } },
-  );
-}
+/**
+ * PAY-1777 item 5 (QAPert-NightHawk, PR 663 G4 thread 4395; coverage widened per BAPert 64034): THE way a server-side call
+ * that carries a user's (or a provisional) bearer token talks to the identity service.
+ *
+ * A bearer must never follow a redirect. Modern fetch drops Authorization on a CROSS-origin hop, but a same-origin hop - or
+ * an older runtime - does not, and we do not rely on that. So:
+ *   - the request is always sent with redirect: 'manual' (set AFTER the caller's init, so no caller can switch it back);
+ *   - any 3xx, or an opaque redirect, is never followed and never relayed: the caller receives a synthetic
+ *     502 { success:false, error:{ code:'IDP_UNREACHABLE' } } Response instead, which every existing non-2xx branch at the
+ *     call sites already handles. Every other response is returned untouched.
+ *
+ * Moved from VibeID-Customer-Portal (src/lib/idp/bearer-fetch.ts) into the package by PAY-2302; the portal's gate
+ * (testing/qa/idp-bearer-no-redirect-gate.js) keeps inventorying its own Authorization-bearing fetches.
+ */
+export const REDIRECT_REFUSED_CODE = 'IDP_UNREACHABLE';
+
+export function isRedirectResponse(res: Response): boolean {
+  return res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
+}
+
+export async function bearerFetch(input: string | URL, init: RequestInit = {}): Promise<Response> {
+  const res = await fetch(input, { ...init, redirect: 'manual' });
+  if (!isRedirectResponse(res)) return res;
+  return new Response(
+    JSON.stringify({
+      success: false,
+      error: { code: REDIRECT_REFUSED_CODE, message: 'The identity service answered with a redirect; the call was not followed' },
+    }),
+    { status: 502, headers: { 'Content-Type': 'application/json' } },
+  );
+}

package/src/lib/client-key.ts

@@ -1,88 +1,88 @@
-/**
- * ONE resolver for "which client is this request for?" — card 268410.
- *
- * THE ASYMMETRY THIS EXISTS TO SURVIVE (measured at source in the IDP,
- * RequirePayEzUnAuthorizedAttribute.cs):
- *
- *   :31-33  int.TryParse succeeds -> Items[PayEzClientId] = numericId; return;   NO existence check
- *   :41-47  slug -> GetClientIdByNameAsync; if null -> NotFoundResult()          VALIDATED
- *   :55     no client id at all -> NotFoundResult()
- *
- * So a WRONG SLUG 404s loudly. A WRONG NUMERIC is silently accepted and the
- * request is answered for whatever client that number happens to be. On a
- * multi-tenant identity service that is a WRONG-TENANT ANSWER, not merely a bug.
- *
- * And a stale numeric is the DOCUMENTED NORMAL CASE, not a hypothetical: numeric
- * ids are environment-specific (card 250596 — 79 was dev-93's id for the SAME
- * slug, and the merge collapsed 76 into 12), while the slug is stable across
- * environments.
- *
- * WHY THE FALLBACK WAS SILENT: idp-client-config.ts:462 and :669 resolve
- * `clientSlug: ... ?? ''`. Empty string is FALSY, so the idiom every call site
- * used —
- *
- *     config.clientSlug || String(config.clientId)
- *
- * — falls through to the numeric arm whenever the IDP config carries no slug,
- * with nothing emitted to say it happened. Absence collapsed into a
- * usable-looking default: the same class the graft's passkey plugin already
- * called out when `|| ''` made an unset env var look like a valid client_id.
- *
- * WHAT THIS DOES **NOT** DO: it does not flip precedence. Slug still wins, the
- * numeric fallback is still taken, and every deployment that works today keeps
- * working byte-for-byte. Blanket-flipping these to numeric-first is the
- * dangerous-looking-safe change the 268410 ruling explicitly holds.
- *
- * WHAT IT DOES: it makes the dangerous arm ATTRIBUTABLE. Taking the numeric
- * fallback now emits a warning naming the call site, so a wrong-tenant answer
- * is diagnosable in seconds instead of being indistinguishable from a correct
- * one. That ambiguity is what cost hours on S12.
- */
-
-export interface ClientKeySource {
-    clientSlug?: string | null;
-    clientId?: string | number | null;
-}
-
-export interface ResolvedClientKey {
-    /** The routing key to send as X-Client-Id / client_id, or null if none resolved. */
-    key: string | null;
-    /** True when the environment-specific numeric arm was taken. */
-    usedNumericFallback: boolean;
-}
-
-/**
- * Resolve the IDP routing key from a client config.
- *
- * `site` names the caller (e.g. 'admin/analytics') and appears verbatim in the
- * fallback warning — that string is the whole diagnostic value, so pass a real one.
- *
- * Pure and non-throwing: callers decide whether a null key is fatal (refuse) or
- * merely means "omit the header". Both shapes exist in this package and both
- * are correct for their path.
- */
-export function resolveClientKey(
-    config: ClientKeySource | null | undefined,
-    site: string
-): ResolvedClientKey {
-    const slug = typeof config?.clientSlug === 'string' ? config.clientSlug.trim() : '';
-    if (slug) return { key: slug, usedNumericFallback: false };
-
-    const rawNumeric = config?.clientId;
-    // Guard String(undefined) === 'undefined' — a 13-char string that is not a
-    // slug and not a number, so the IDP would 404 it with no hint as to why.
-    if (rawNumeric === null || rawNumeric === undefined) {
-        return { key: null, usedNumericFallback: false };
-    }
-    const numeric = String(rawNumeric).trim();
-    if (!numeric) return { key: null, usedNumericFallback: false };
-
-    console.warn(
-        `[client-key] ${site}: no clientSlug on the resolved IDP config — falling back to the ` +
-        `NUMERIC client id ${numeric}. Numeric ids are ENVIRONMENT-SPECIFIC and the IDP accepts ` +
-        `them with NO existence check, so if this number is stale for this environment the ` +
-        `request is being answered for the WRONG CLIENT, silently. Card 268410.`
-    );
-
-    return { key: numeric, usedNumericFallback: true };
-}
+/**
+ * ONE resolver for "which client is this request for?" — card 268410.
+ *
+ * THE ASYMMETRY THIS EXISTS TO SURVIVE (measured at source in the IDP,
+ * RequirePayEzUnAuthorizedAttribute.cs):
+ *
+ *   :31-33  int.TryParse succeeds -> Items[PayEzClientId] = numericId; return;   NO existence check
+ *   :41-47  slug -> GetClientIdByNameAsync; if null -> NotFoundResult()          VALIDATED
+ *   :55     no client id at all -> NotFoundResult()
+ *
+ * So a WRONG SLUG 404s loudly. A WRONG NUMERIC is silently accepted and the
+ * request is answered for whatever client that number happens to be. On a
+ * multi-tenant identity service that is a WRONG-TENANT ANSWER, not merely a bug.
+ *
+ * And a stale numeric is the DOCUMENTED NORMAL CASE, not a hypothetical: numeric
+ * ids are environment-specific (card 250596 — 79 was dev-93's id for the SAME
+ * slug, and the merge collapsed 76 into 12), while the slug is stable across
+ * environments.
+ *
+ * WHY THE FALLBACK WAS SILENT: idp-client-config.ts:462 and :669 resolve
+ * `clientSlug: ... ?? ''`. Empty string is FALSY, so the idiom every call site
+ * used —
+ *
+ *     config.clientSlug || String(config.clientId)
+ *
+ * — falls through to the numeric arm whenever the IDP config carries no slug,
+ * with nothing emitted to say it happened. Absence collapsed into a
+ * usable-looking default: the same class the graft's passkey plugin already
+ * called out when `|| ''` made an unset env var look like a valid client_id.
+ *
+ * WHAT THIS DOES **NOT** DO: it does not flip precedence. Slug still wins, the
+ * numeric fallback is still taken, and every deployment that works today keeps
+ * working byte-for-byte. Blanket-flipping these to numeric-first is the
+ * dangerous-looking-safe change the 268410 ruling explicitly holds.
+ *
+ * WHAT IT DOES: it makes the dangerous arm ATTRIBUTABLE. Taking the numeric
+ * fallback now emits a warning naming the call site, so a wrong-tenant answer
+ * is diagnosable in seconds instead of being indistinguishable from a correct
+ * one. That ambiguity is what cost hours on S12.
+ */
+
+export interface ClientKeySource {
+    clientSlug?: string | null;
+    clientId?: string | number | null;
+}
+
+export interface ResolvedClientKey {
+    /** The routing key to send as X-Client-Id / client_id, or null if none resolved. */
+    key: string | null;
+    /** True when the environment-specific numeric arm was taken. */
+    usedNumericFallback: boolean;
+}
+
+/**
+ * Resolve the IDP routing key from a client config.
+ *
+ * `site` names the caller (e.g. 'admin/analytics') and appears verbatim in the
+ * fallback warning — that string is the whole diagnostic value, so pass a real one.
+ *
+ * Pure and non-throwing: callers decide whether a null key is fatal (refuse) or
+ * merely means "omit the header". Both shapes exist in this package and both
+ * are correct for their path.
+ */
+export function resolveClientKey(
+    config: ClientKeySource | null | undefined,
+    site: string
+): ResolvedClientKey {
+    const slug = typeof config?.clientSlug === 'string' ? config.clientSlug.trim() : '';
+    if (slug) return { key: slug, usedNumericFallback: false };
+
+    const rawNumeric = config?.clientId;
+    // Guard String(undefined) === 'undefined' — a 13-char string that is not a
+    // slug and not a number, so the IDP would 404 it with no hint as to why.
+    if (rawNumeric === null || rawNumeric === undefined) {
+        return { key: null, usedNumericFallback: false };
+    }
+    const numeric = String(rawNumeric).trim();
+    if (!numeric) return { key: null, usedNumericFallback: false };
+
+    console.warn(
+        `[client-key] ${site}: no clientSlug on the resolved IDP config — falling back to the ` +
+        `NUMERIC client id ${numeric}. Numeric ids are ENVIRONMENT-SPECIFIC and the IDP accepts ` +
+        `them with NO existence check, so if this number is stale for this environment the ` +
+        `request is being answered for the WRONG CLIENT, silently. Card 268410.`
+    );
+
+    return { key: numeric, usedNumericFallback: true };
+}