@payez/next-mvp 4.1.21 → 4.4.1

package/src/api-handlers/account/recovery/send-code.ts

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../../config/env';
+import { getIDPClientConfig } from '../../../lib/idp-client-config';
+import { resolveClientKey } from '../../../lib/client-key';
 
 /**
  * Account recovery — send-code
@@ -36,6 +38,36 @@ import { ENV_CONFIG } from '../../../config/env';
  * @package @payez/next-mvp
  */
 
+/**
+ * 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/send-code').key;
+  } catch (e) {
+    console.error('[account/recovery/send-code] could not resolve IDP client config for client_id:', e);
+    return null;
+  }
+}
+
 export async function POST(req: NextRequest) {
   let payload: unknown = {};
   try {
@@ -47,13 +79,15 @@ export async function POST(req: NextRequest) {
     );
   }
 
+  const clientKey = await recoveryClientKey();
+
   const result = await idpFetchJSON(
     req,
     `${ENV_CONFIG.IDP_URL}/api/Account/recovery/send-code`,
     {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
+      headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+      body: JSON.stringify({ ...(payload as Record<string, unknown>), ...(clientKey ? { client_id: clientKey } : {}) }),
     }
   );
 

package/src/api-handlers/account/recovery/verify-code.ts

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../../config/env';
+import { getIDPClientConfig } from '../../../lib/idp-client-config';
+import { resolveClientKey } from '../../../lib/client-key';
 
 /**
  * Account recovery — verify-code
@@ -36,6 +38,36 @@ import { ENV_CONFIG } from '../../../config/env';
  * @package @payez/next-mvp
  */
 
+/**
+ * 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/verify-code').key;
+  } catch (e) {
+    console.error('[account/recovery/verify-code] could not resolve IDP client config for client_id:', e);
+    return null;
+  }
+}
+
 export async function POST(req: NextRequest) {
   let payload: unknown = {};
   try {
@@ -47,13 +79,15 @@ export async function POST(req: NextRequest) {
     );
   }
 
+  const clientKey = await recoveryClientKey();
+
   const result = await idpFetchJSON(
     req,
     `${ENV_CONFIG.IDP_URL}/api/Account/recovery/verify-code`,
     {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
+      headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+      body: JSON.stringify({ ...(payload as Record<string, unknown>), ...(clientKey ? { client_id: clientKey } : {}) }),
     }
   );
 

package/src/api-handlers/account/reset-password.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/reset-password').key;
+  } catch (e) {
+    console.error('[account/reset-password] could not resolve IDP client config for client_id:', e);
+    return null;
+  }
+}
+
 export async function POST(req: NextRequest) {
   const IDP_URL = getIdpUrl();
   try {
     const payload = await req.json();
+    const clientKey = await recoveryClientKey();
     const upstream = await fetch(`${IDP_URL}/api/Account/reset-password`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
+      headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+      body: JSON.stringify({ ...payload, ...(clientKey ? { client_id: clientKey } : {}) }),
     });
     const data = await upstream.json().catch(() => ({}));
     return NextResponse.json(data, { status: upstream.status });

package/src/api-handlers/account/validate-password.ts

@@ -43,7 +43,7 @@ export async function POST(req: NextRequest) {
     // Get IDP base URL and client ID from environment
     const idpBaseUrl = process.env.IDP_URL;
 
-    const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_CLIENT_ID;
+    const clientId = process.env.CLIENT_ID;
 
     if (!idpBaseUrl) {
       console.error('[VALIDATE_PASSWORD] IDP_URL not configured');
@@ -96,8 +96,27 @@ export async function POST(req: NextRequest) {
       );
     }
 
-    // Return the IDP response with proper structure
-    return NextResponse.json(responseData as ValidatePasswordResponse, {
+    /**
+     * 283211 - UNWRAP THE IDP ENVELOPE. Approved by BAPert 2026-08-30.
+     *
+     * The IDP answers this endpoint with an ENVELOPE - { success, data: { is_valid, score,
+     * failed_requirements, policy } } - and this line used to hand that straight back. The
+     * `as ValidatePasswordResponse` is a COMPILE-TIME ASSERTION AND PERFORMS NO RUNTIME
+     * TRANSFORMATION, so nothing ever reshaped it and the type told us it was fine.
+     *
+     * The consumer is usePasswordValidation, which reads `data.is_valid` at the top level and
+     * calls setIsValid with it. Against an envelope that is `undefined`, so isValid never
+     * became true; and EVERY error path in this file returns a FLAT { is_valid: false }. So the
+     * success shape was unreadable and the failure shape was readable-and-false: setIsValid(true)
+     * was UNREACHABLE, and the Change Password button's `canSubmit` could never enable.
+     *
+     * `responseData?.data ?? responseData` is defensive in both directions BY DESIGN: it unwraps
+     * the envelope we get today and passes a flat body through unchanged, so it does not break
+     * if the IDP is later made consistent with this file's own declared response type.
+     */
+    const unwrapped = (responseData as any)?.data ?? responseData;
+
+    return NextResponse.json(unwrapped as ValidatePasswordResponse, {
       status: 200,
       headers: { 'Cache-Control': 'no-store' },
     });

package/src/api-handlers/admin/analytics.ts

@@ -11,6 +11,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getStartupIDPConfig } from '../../lib/startup-init';
+import { resolveClientKey } from '../../lib/client-key';
 import { ADMIN_ROLES, hasAnyRole } from '../../lib/roles';
 
 interface VibeRequestOptions {
@@ -66,7 +67,7 @@ async function vibeServiceRequest<T = unknown>(
 
   // Get the client slug from startup config for multi-client admin support
   const idpConfig = getStartupIDPConfig();
-  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+  const idpClientId = resolveClientKey(idpConfig, 'admin/analytics').key;
 
   try {
     const res = await fetch(proxyUrl, {

package/src/api-handlers/admin/audit.ts

@@ -10,6 +10,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getStartupIDPConfig } from '../../lib/startup-init';
+import { resolveClientKey } from '../../lib/client-key';
 import { ADMIN_ROLES, hasAnyRole } from '../../lib/roles';
 
 interface VibeRequestOptions {
@@ -65,7 +66,7 @@ async function vibeServiceRequest<T = unknown>(
 
   // Get the client slug from startup config for multi-client admin support
   const idpConfig = getStartupIDPConfig();
-  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+  const idpClientId = resolveClientKey(idpConfig, 'admin/audit').key;
 
   try {
     const res = await fetch(proxyUrl, {

package/src/api-handlers/admin/sessions.ts

@@ -11,6 +11,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getStartupIDPConfig } from '../../lib/startup-init';
+import { resolveClientKey } from '../../lib/client-key';
 import { ADMIN_ROLES, hasAnyRole } from '../../lib/roles';
 
 interface VibeRequestOptions {
@@ -78,7 +79,7 @@ async function vibeServiceRequest<T = unknown>(
 
   // Get the client slug from startup config for multi-client admin support
   const idpConfig = getStartupIDPConfig();
-  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+  const idpClientId = resolveClientKey(idpConfig, 'admin/sessions').key;
 
   try {
     const res = await fetch(proxyUrl, {

package/src/api-handlers/admin/stats.ts

@@ -11,6 +11,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getStartupIDPConfig } from '../../lib/startup-init';
+import { resolveClientKey } from '../../lib/client-key';
 import { getRedis } from '../../lib/redis';
 import { ADMIN_ROLES } from '../../lib/roles';
 
@@ -66,7 +67,7 @@ async function vibeServiceRequest<T = unknown>(
   const proxyUrl = `${idpUrl}/api/vibe/proxy`;
 
   const idpConfig = getStartupIDPConfig();
-  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+  const idpClientId = resolveClientKey(idpConfig, 'admin/stats').key;
 
   try {
     const res = await fetch(proxyUrl, {

package/src/api-handlers/admin/users.ts

@@ -10,6 +10,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getStartupIDPConfig } from '../../lib/startup-init';
+import { resolveClientKey } from '../../lib/client-key';
 import { ADMIN_ROLES, hasAnyRole } from '../../lib/roles';
 
 interface VibeRequestOptions {
@@ -65,7 +66,7 @@ async function vibeServiceRequest<T = unknown>(
 
   // Get the client slug from startup config for multi-client admin support
   const idpConfig = getStartupIDPConfig();
-  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+  const idpClientId = resolveClientKey(idpConfig, 'admin/users').key;
 
   try {
     const res = await fetch(proxyUrl, {

package/src/api-handlers/admin/vibe-data.ts

@@ -11,6 +11,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getStartupIDPConfig } from '../../lib/startup-init';
+import { resolveClientKey } from '../../lib/client-key';
 import { ADMIN_ROLES, hasAnyRole } from '../../lib/roles';
 
 interface VibeRequestOptions {
@@ -80,7 +81,7 @@ async function vibeServiceRequest<T = unknown>(
 
   // Get the client slug from startup config for multi-client admin support
   const idpConfig = getStartupIDPConfig();
-  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+  const idpClientId = resolveClientKey(idpConfig, 'admin/vibe-data').key;
 
   try {
     const res = await fetch(proxyUrl, {

package/src/api-handlers/auth/jwks.ts

@@ -1,10 +1,13 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ENV_CONFIG, API_ENDPOINTS } from '../../config/env';
 import { logger } from '../../config/logger';
+import { assertAbsoluteIdpUrl } from '../../lib/idp-url-guard';
 
 export async function GET(_req: NextRequest) {
   try {
     const url = `${ENV_CONFIG.IDP_URL}${API_ENDPOINTS.externalAuth.jwks}`;
+    // Direct fetch - the idpFetchJSON guard is not on this path.
+    assertAbsoluteIdpUrl(url);
     const res = await fetch(url, { headers: { 'Accept': 'application/json' } });
     const bodyText = await res.text();
     try {
@@ -15,6 +18,13 @@ export async function GET(_req: NextRequest) {
       return NextResponse.json({ error: 'Invalid JWKS response' }, { status: 502 });
     }
   } catch (error) {
+    // This catch DISCARDED `error` entirely and answered a bare 502, so a config
+    // fault and a dead upstream were indistinguishable - and the guard's named
+    // message above would have been swallowed with them. The 502 body is left
+    // unchanged (it is a public response shape); the cause now reaches the log.
+    logger.error('[AUTH_JWKS] Failed to fetch JWKS', {
+      message: error instanceof Error ? error.message : String(error),
+    });
     return NextResponse.json({ error: 'Failed to fetch JWKS' }, { status: 502 });
   }
 }

package/src/api-handlers/auth/login.ts

@@ -127,10 +127,13 @@ export function createLoginHandler(config: LoginConfig) {
     // Extract client headers for forwarding to IDP
     const clientHeaders: Record<string, string> = {};
 
-    // Forward client IP if available
+    // Forward client IP if available.
+    // 269334 / R21: forward the FULL chain, do NOT collapse to [0] - see the same
+    // change in lib/idp-fetch.ts. [0] is the forgeable client-supplied entry and
+    // collapsing to it destroys the chain the IDP's trusted-hop logic reads.
     const clientIp = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
     if (clientIp) {
-      clientHeaders['X-Forwarded-For'] = clientIp.split(',')[0].trim();
+      clientHeaders['X-Forwarded-For'] = clientIp;
     }
 
     // Forward user agent if available

package/src/api-handlers/auth/passkey-signin.ts

@@ -1,98 +1,112 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { ENV_CONFIG } from '../../config/env';
-import { getIDPClientConfig } from '../../lib/idp-client-config';
-
-/**
- * Passkey SIGN-IN ceremony (ANONYMOUS — no session exists yet):
- *   optionsPOST -> POST /api/ExternalAuth/passwordless/passkey/options
- *   verifyPOST  -> POST /api/ExternalAuth/passwordless/passkey/verify
- *
- * Anon idiom copied from auth/better-auth.ts (exchangeOAuthForIdpTokens):
- * direct fetch to the IDP, client identified by client_id from the resolved
- * IDP client config (slug preferred, numeric id fallback) — sent BOTH as the
- * X-Client-Id header (the probe-verified routing key) and merged into the
- * body when the caller did not supply one.
- *
- * The verify response is passed through WITHOUT unwrapping: this is a
- * sign-in, its payload carries the grant the caller's session layer consumes.
- */
-
-async function clientKey(): Promise<string> {
-  const config = await getIDPClientConfig();
-  return config.clientSlug || String(config.clientId);
-}
-
-async function anonCall(req: NextRequest, path: string) {
-  let parsed: Record<string, unknown> = {};
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) parsed = JSON.parse(raw);
-  } catch {}
-
-  const key = await clientKey();
-  const res = await fetch(`${ENV_CONFIG.IDP_URL}${path}`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
-    body: JSON.stringify({ client_id: key, ...parsed }),
-    cache: 'no-store',
-  });
-  const json = await res.json().catch(() => null);
-  return { res, json };
-}
-
-export async function optionsPOST(req: NextRequest) {
-  const { res, json } = await anonCall(req, '/api/ExternalAuth/passwordless/passkey/options');
-  return NextResponse.json(json ?? { success: false, message: 'Empty upstream response' }, { status: res.status });
-}
-
-/**
- * VERIFY DOES NOT USE anonCall — IT MUST RESHAPE, NOT SPREAD.
- *
- * The IDP contract is three fields (PasskeyModels.cs:36 PasskeyAuthVerifyRequest):
- *     assertion_id : string
- *     response     : the WHOLE AuthenticatorAssertionRawResponse from
- *                    navigator.credentials.get()
- *     client_id    : string
- *
- * anonCall SPREADS the caller's body (`{ client_id, ...parsed }`). For options
- * that is harmless. For verify it is fatal: spreading an assertion hoists
- * id/rawId/type to the top level and leaves `response` holding only the INNER
- * {clientDataJSON, authenticatorData, signature, userHandle}. The IDP's guard
- * then answers "response is required" in 4-12ms WITHOUT REACHING THE CRYPTO —
- * a timing signature DotNetPert used to prove the caller was still spreading
- * long after the graft-side plugin had been fixed.
- *
- * This route and the Better Auth plugin endpoint are TWO PATHS to the same IDP
- * endpoint. Fixing only the plugin left this one live, spreading, and reachable
- * on a URL one segment away from the correct one — which is what kept the
- * sign-in leg red across several runs.
- *
- * Accepts the assertion either already nested (`{ assertion_id, response }`) or
- * flat (`{ assertion_id, id, rawId, type, response }`) and normalises both, so a
- * caller written against either shape works.
- */
-export async function verifyPOST(req: NextRequest) {
-  let parsed: Record<string, unknown> = {};
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) parsed = JSON.parse(raw);
-  } catch { /* empty body -> the IDP's own validation answers */ }
-
-  const { assertion_id: assertionId, response, ...rest } = parsed;
-
-  // Already-nested callers send `response` holding a full assertion (it has an
-  // `id`). Flat callers send the assertion's own fields alongside assertion_id,
-  // and their `response` is the inner attestation half — not a whole assertion.
-  const nested = response && typeof response === 'object' && 'id' in (response as object);
-  const assertion = nested ? response : { ...rest, response };
-
-  const key = await clientKey();
-  const res = await fetch(`${ENV_CONFIG.IDP_URL}/api/ExternalAuth/passwordless/passkey/verify`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
-    body: JSON.stringify({ client_id: key, assertion_id: assertionId, response: assertion }),
-    cache: 'no-store',
-  });
-  const json = await res.json().catch(() => null);
-  return NextResponse.json(json ?? { success: false, message: 'Empty upstream response' }, { status: res.status });
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../../config/env';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { resolveClientKey } from '../../lib/client-key';
+import { assertAbsoluteIdpUrl } from '../../lib/idp-url-guard';
+
+/**
+ * Passkey SIGN-IN ceremony (ANONYMOUS — no session exists yet):
+ *   optionsPOST -> POST /api/ExternalAuth/passwordless/passkey/options
+ *   verifyPOST  -> POST /api/ExternalAuth/passwordless/passkey/verify
+ *
+ * Anon idiom copied from auth/better-auth.ts (exchangeOAuthForIdpTokens):
+ * direct fetch to the IDP, client identified by client_id from the resolved
+ * IDP client config (slug preferred, numeric id fallback) — sent BOTH as the
+ * X-Client-Id header (the probe-verified routing key) and merged into the
+ * body when the caller did not supply one.
+ *
+ * The verify response is passed through WITHOUT unwrapping: this is a
+ * sign-in, its payload carries the grant the caller's session layer consumes.
+ */
+
+async function clientKey(): Promise<string> {
+  const config = await getIDPClientConfig();
+  const { key } = resolveClientKey(config, 'auth/passkey-signin');
+  // Refuse rather than send an empty client_id. Card 268410: the graft's own
+  // copy of this path learned this the hard way — `|| ''` made an unset config
+  // look like a valid value and the IDP answered "client_id is required" in
+  // 7-9ms, which read as a request-shape bug for hours.
+  if (!key) throw new Error('[passkey-signin] no IDP client slug or id resolved - refusing to send an empty client_id');
+  return key;
+}
+
+async function anonCall(req: NextRequest, path: string) {
+  let parsed: Record<string, unknown> = {};
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) parsed = JSON.parse(raw);
+  } catch {}
+
+  const key = await clientKey();
+  // This route calls fetch directly, so it does NOT reach the guard inside
+  // idpFetchJSON. Same reasoning as the clientKey() throw above: name the missing
+  // config rather than sending a request built from it.
+  assertAbsoluteIdpUrl(`${ENV_CONFIG.IDP_URL}${path}`);
+  const res = await fetch(`${ENV_CONFIG.IDP_URL}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
+    body: JSON.stringify({ client_id: key, ...parsed }),
+    cache: 'no-store',
+  });
+  const json = await res.json().catch(() => null);
+  return { res, json };
+}
+
+export async function optionsPOST(req: NextRequest) {
+  const { res, json } = await anonCall(req, '/api/ExternalAuth/passwordless/passkey/options');
+  return NextResponse.json(json ?? { success: false, message: 'Empty upstream response' }, { status: res.status });
+}
+
+/**
+ * VERIFY DOES NOT USE anonCall — IT MUST RESHAPE, NOT SPREAD.
+ *
+ * The IDP contract is three fields (PasskeyModels.cs:36 PasskeyAuthVerifyRequest):
+ *     assertion_id : string
+ *     response     : the WHOLE AuthenticatorAssertionRawResponse from
+ *                    navigator.credentials.get()
+ *     client_id    : string
+ *
+ * anonCall SPREADS the caller's body (`{ client_id, ...parsed }`). For options
+ * that is harmless. For verify it is fatal: spreading an assertion hoists
+ * id/rawId/type to the top level and leaves `response` holding only the INNER
+ * {clientDataJSON, authenticatorData, signature, userHandle}. The IDP's guard
+ * then answers "response is required" in 4-12ms WITHOUT REACHING THE CRYPTO —
+ * a timing signature DotNetPert used to prove the caller was still spreading
+ * long after the graft-side plugin had been fixed.
+ *
+ * This route and the Better Auth plugin endpoint are TWO PATHS to the same IDP
+ * endpoint. Fixing only the plugin left this one live, spreading, and reachable
+ * on a URL one segment away from the correct one — which is what kept the
+ * sign-in leg red across several runs.
+ *
+ * Accepts the assertion either already nested (`{ assertion_id, response }`) or
+ * flat (`{ assertion_id, id, rawId, type, response }`) and normalises both, so a
+ * caller written against either shape works.
+ */
+export async function verifyPOST(req: NextRequest) {
+  let parsed: Record<string, unknown> = {};
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) parsed = JSON.parse(raw);
+  } catch { /* empty body -> the IDP's own validation answers */ }
+
+  const { assertion_id: assertionId, response, ...rest } = parsed;
+
+  // Already-nested callers send `response` holding a full assertion (it has an
+  // `id`). Flat callers send the assertion's own fields alongside assertion_id,
+  // and their `response` is the inner attestation half — not a whole assertion.
+  const nested = response && typeof response === 'object' && 'id' in (response as object);
+  const assertion = nested ? response : { ...rest, response };
+
+  const key = await clientKey();
+  // Direct fetch - see the note in anonCall; the idpFetchJSON guard is not on this path.
+  assertAbsoluteIdpUrl(`${ENV_CONFIG.IDP_URL}/api/ExternalAuth/passwordless/passkey/verify`);
+  const res = await fetch(`${ENV_CONFIG.IDP_URL}/api/ExternalAuth/passwordless/passkey/verify`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
+    body: JSON.stringify({ client_id: key, assertion_id: assertionId, response: assertion }),
+    cache: 'no-store',
+  });
+  const json = await res.json().catch(() => null);
+  return NextResponse.json(json ?? { success: false, message: 'Empty upstream response' }, { status: res.status });
+}