@payez/next-mvp 4.8.0 → 4.8.2

package/src/api-handlers/account/profile.ts

@@ -1,99 +1,99 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG } from '../../config/env';
-
-/**
- * Account Profile API Handler
- *
- * GET /api/account/profile  - Get user profile
- * PUT /api/account/profile  - Update user profile
- *
- * WHY THIS WAS REWRITTEN (2026-08-02, QAPert defect #7)
- * Reported as "/api/account/profile 401s on the same cookie masked-info
- * accepts (200)". Two endpoints disagreeing about one cookie meant two auth
- * implementations, and they were:
- *
- *   masked-info.ts  idpFetchJSON(req, ...)           resolves the caller's token
- *                                                    from the server-side session
- *   profile.ts      req.headers.get('authorization') required an INBOUND bearer
- *
- * A browser sends a session COOKIE and no Authorization header, so the old
- * profile.ts 401'd EVERY browser request by construction. Nothing was revoked
- * and no token was stale — the handler demanded a credential the app does not
- * use.
- *
- * THE OLD AUTH CHECK WAS A VENEER. It tested that the header was PRESENT, never
- * that it was valid, then forwarded it upstream unexamined. Any string at all
- * got past it and the IDP did the real work. It looked like enforcement and
- * enforced nothing.
- *
- * WHAT THE WORKAROUND COST US: consumers could not call this with a cookie, so
- * the graft's useProfile hook fetched the raw IDP access token from
- * /api/session/idp-token INTO BROWSER JAVASCRIPT and re-sent it as a bearer.
- * That defeats the reason idpFetchJSON exists — it keeps the token server-side
- * precisely so client-side script can never hold it. The bearer-only handler
- * did not merely fail; it pushed its callers into exposing the token.
- *
- * Switching to idpFetchJSON makes the cookie work, so the hook's token round
- * trip can be deleted and /api/session/idp-token drops to a single deliberate
- * caller: the jwt-inspect debug page.
- *
- * @package @payez/next-mvp
- */
-
-export async function GET(req: NextRequest) {
-  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/profile`, {
-    method: 'GET',
-    headers: { 'Content-Type': 'application/json' },
-  });
-
-  if (!result.ok) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: {
-          code: 'UPSTREAM_SERVICE_ERROR',
-          message: result.json?.message || 'Failed to fetch profile',
-          status: result.status,
-        },
-        meta: { attemptedRefresh: result.attemptedRefresh },
-      },
-      { status: result.status }
-    );
-  }
-
-  return NextResponse.json(result.json, { status: 200 });
-}
-
-export async function PUT(req: NextRequest) {
-  let body = '{}';
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) body = raw;
-  } catch {
-    // Empty body is valid here; the IDP validates the payload.
-  }
-
-  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/profile`, {
-    method: 'PUT',
-    headers: { 'Content-Type': 'application/json' },
-    body,
-  });
-
-  if (!result.ok) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: {
-          code: 'UPSTREAM_SERVICE_ERROR',
-          message: result.json?.message || 'Failed to update profile',
-          status: result.status,
-        },
-        meta: { attemptedRefresh: result.attemptedRefresh },
-      },
-      { status: result.status }
-    );
-  }
-
-  return NextResponse.json(result.json, { status: 200 });
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Account Profile API Handler
+ *
+ * GET /api/account/profile  - Get user profile
+ * PUT /api/account/profile  - Update user profile
+ *
+ * WHY THIS WAS REWRITTEN (2026-08-02, QAPert defect #7)
+ * Reported as "/api/account/profile 401s on the same cookie masked-info
+ * accepts (200)". Two endpoints disagreeing about one cookie meant two auth
+ * implementations, and they were:
+ *
+ *   masked-info.ts  idpFetchJSON(req, ...)           resolves the caller's token
+ *                                                    from the server-side session
+ *   profile.ts      req.headers.get('authorization') required an INBOUND bearer
+ *
+ * A browser sends a session COOKIE and no Authorization header, so the old
+ * profile.ts 401'd EVERY browser request by construction. Nothing was revoked
+ * and no token was stale — the handler demanded a credential the app does not
+ * use.
+ *
+ * THE OLD AUTH CHECK WAS A VENEER. It tested that the header was PRESENT, never
+ * that it was valid, then forwarded it upstream unexamined. Any string at all
+ * got past it and the IDP did the real work. It looked like enforcement and
+ * enforced nothing.
+ *
+ * WHAT THE WORKAROUND COST US: consumers could not call this with a cookie, so
+ * the graft's useProfile hook fetched the raw IDP access token from
+ * /api/session/idp-token INTO BROWSER JAVASCRIPT and re-sent it as a bearer.
+ * That defeats the reason idpFetchJSON exists — it keeps the token server-side
+ * precisely so client-side script can never hold it. The bearer-only handler
+ * did not merely fail; it pushed its callers into exposing the token.
+ *
+ * Switching to idpFetchJSON makes the cookie work, so the hook's token round
+ * trip can be deleted and /api/session/idp-token drops to a single deliberate
+ * caller: the jwt-inspect debug page.
+ *
+ * @package @payez/next-mvp
+ */
+
+export async function GET(req: NextRequest) {
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/profile`, {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: {
+          code: 'UPSTREAM_SERVICE_ERROR',
+          message: result.json?.message || 'Failed to fetch profile',
+          status: result.status,
+        },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status }
+    );
+  }
+
+  return NextResponse.json(result.json, { status: 200 });
+}
+
+export async function PUT(req: NextRequest) {
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {
+    // Empty body is valid here; the IDP validates the payload.
+  }
+
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/profile`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: {
+          code: 'UPSTREAM_SERVICE_ERROR',
+          message: result.json?.message || 'Failed to update profile',
+          status: result.status,
+        },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status }
+    );
+  }
+
+  return NextResponse.json(result.json, { status: 200 });
+}

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

@@ -1,117 +1,117 @@
-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 { idpErrorEnvelope } from '../../../lib/safe-error-response';
-
-/**
- * Account recovery - the ONE forwarder behind /recovery/send-code and /recovery/verify-code (PAY-1588).
- *
- * THE DEFECT (QAPert, W1 walk on :4797 -> dev-93 IdP 90f766bd0, 2026-09-19): portal /account-auth/recovery,
- * initiate -> 200, send-code -> 401 "Upstream error". The browser sends `Authorization: Bearer <recovery session
- * token>` (the token `initiate` minted); these handlers went through idpFetchJSON, which sets Authorization ONLY from
- * the server-side SESSION and never forwards the inbound header, so the IdP got no Bearer at all
- * (AccountController.cs:872-885 = 401 MISSING_TOKEN). Positive control direct to the IdP: without Authorization 401,
- * with it 200 and the email is sent.
- *
- * WHY THE 2026-08-02 REWRITE GOT IT WRONG. It reasoned "browsers send a session COOKIE and no Authorization header"
- * and moved both handlers onto idpFetchJSON. That is true of every OTHER authenticated route. It is false of this
- * flow: the caller is LOCKED OUT, so there is no session to resolve - the recovery session token IS the credential,
- * and the browser is the only party that holds it. Resolving a token from a session that does not exist is why the
- * entire recovery path, both halves, has been dead: it fails exactly when it is the only thing left that could help.
- *
- * WHAT THIS DOES INSTEAD
- *   - Forwards the inbound `Authorization: Bearer <token>` to the IdP and nothing else from the caller's headers.
- *   - Uses a direct fetch, NOT idpFetchJSON: a stray session belonging to someone else on the same browser must not
- *     be able to override the recovery credential with its own bearer (idpFetchJSON's session bearer wins over any
- *     caller-supplied Authorization).
- *   - FAILS LOUD when there is no usable bearer: 401 `missing_recovery_token`, without calling upstream. The old
- *     behaviour returned the IdP's opaque rejection, so the user saw recovery "not working" and the log showed an
- *     upstream error rather than the auth fault it was.
- *   - Shape-checks the token (a bearer scheme, one opaque token, sane length) before forwarding, so the header cannot
- *     be used to smuggle anything but a credential to the IdP. It is never logged.
- *   - Anonymous route (PAY-1438): on failure only the whitelisted envelope, never the IdP body.
- *
- * SERVER VALUE WINS for client_id (cards 268012 / 268410): applied AFTER the caller's payload spread, because these are
- * unauthenticated endpoints and a browser-supplied client_id would be a tenant-targeting lever on a password-reset path.
- *
- * @package @payez/next-mvp
- */
-
-/** One opaque token: JWT / base64url / opaque-hex alphabet, no whitespace or control characters, bounded length. */
-const TOKEN_SHAPE = /^[A-Za-z0-9\-._~+/]+=*$/;
-
-/** The recovery bearer from the inbound request, or null when absent / malformed. Never throws. */
-export function inboundRecoveryBearer(req: Pick<NextRequest, 'headers'>): string | null {
-  const raw = req.headers.get('authorization');
-  if (!raw) return null;
-  const m = /^Bearer[ ]+(\S+)$/i.exec(raw.trim());
-  if (!m) return null;
-  const token = m[1];
-  if (token.length < 16 || token.length > 4096) return null;
-  return TOKEN_SHAPE.test(token) ? token : null;
-}
-
-async function recoveryClientKey(where: string): Promise<string | null> {
-  try {
-    const config = await getIDPClientConfig();
-    return resolveClientKey(config, where).key;
-  } catch (e) {
-    console.error(`[${where}] could not resolve IDP client config for client_id:`, e);
-    return null;
-  }
-}
-
-export interface RecoveryForward {
-  /** IdP path after the host, e.g. /api/Account/recovery/send-code */
-  upstreamPath: string;
-  /** log/route label used for the client-key resolver */
-  where: string;
-  /** stable `error` code for an upstream that could not be reached */
-  failureCode: string;
-  /** user-facing fallback when the IdP gave no message */
-  fallbackMessage: string;
-}
-
-export async function forwardRecoveryCall(req: NextRequest, spec: RecoveryForward): Promise<NextResponse> {
-  let payload: unknown = {};
-  try {
-    payload = await req.json();
-  } catch {
-    return NextResponse.json({ success: false, error: 'invalid_request', message: 'A JSON body is required' }, { status: 400 });
-  }
-
-  const bearer = inboundRecoveryBearer(req);
-  if (!bearer) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: 'missing_recovery_token',
-        message: 'Your recovery session could not be found. Start the recovery again from the beginning.',
-      },
-      { status: 401 },
-    );
-  }
-
-  const clientKey = await recoveryClientKey(spec.where);
-
-  let upstream: Response;
-  try {
-    upstream = await fetch(`${ENV_CONFIG.IDP_URL}${spec.upstreamPath}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        Authorization: `Bearer ${bearer}`,
-        ...(clientKey ? { 'X-Client-Id': clientKey } : {}),
-      },
-      body: JSON.stringify({ ...(payload as Record<string, unknown>), ...(clientKey ? { client_id: clientKey } : {}) }),
-    });
-  } catch {
-    return NextResponse.json({ success: false, error: spec.failureCode }, { status: 502 });
-  }
-
-  const data = await upstream.json().catch(() => ({}));
-  if (!upstream.ok) return NextResponse.json(idpErrorEnvelope(data, spec.fallbackMessage), { status: upstream.status });
-  return NextResponse.json(data, { status: 200 });
-}
+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 { idpErrorEnvelope } from '../../../lib/safe-error-response';
+
+/**
+ * Account recovery - the ONE forwarder behind /recovery/send-code and /recovery/verify-code (PAY-1588).
+ *
+ * THE DEFECT (QAPert, W1 walk on :4797 -> dev-93 IdP 90f766bd0, 2026-09-19): portal /account-auth/recovery,
+ * initiate -> 200, send-code -> 401 "Upstream error". The browser sends `Authorization: Bearer <recovery session
+ * token>` (the token `initiate` minted); these handlers went through idpFetchJSON, which sets Authorization ONLY from
+ * the server-side SESSION and never forwards the inbound header, so the IdP got no Bearer at all
+ * (AccountController.cs:872-885 = 401 MISSING_TOKEN). Positive control direct to the IdP: without Authorization 401,
+ * with it 200 and the email is sent.
+ *
+ * WHY THE 2026-08-02 REWRITE GOT IT WRONG. It reasoned "browsers send a session COOKIE and no Authorization header"
+ * and moved both handlers onto idpFetchJSON. That is true of every OTHER authenticated route. It is false of this
+ * flow: the caller is LOCKED OUT, so there is no session to resolve - the recovery session token IS the credential,
+ * and the browser is the only party that holds it. Resolving a token from a session that does not exist is why the
+ * entire recovery path, both halves, has been dead: it fails exactly when it is the only thing left that could help.
+ *
+ * WHAT THIS DOES INSTEAD
+ *   - Forwards the inbound `Authorization: Bearer <token>` to the IdP and nothing else from the caller's headers.
+ *   - Uses a direct fetch, NOT idpFetchJSON: a stray session belonging to someone else on the same browser must not
+ *     be able to override the recovery credential with its own bearer (idpFetchJSON's session bearer wins over any
+ *     caller-supplied Authorization).
+ *   - FAILS LOUD when there is no usable bearer: 401 `missing_recovery_token`, without calling upstream. The old
+ *     behaviour returned the IdP's opaque rejection, so the user saw recovery "not working" and the log showed an
+ *     upstream error rather than the auth fault it was.
+ *   - Shape-checks the token (a bearer scheme, one opaque token, sane length) before forwarding, so the header cannot
+ *     be used to smuggle anything but a credential to the IdP. It is never logged.
+ *   - Anonymous route (PAY-1438): on failure only the whitelisted envelope, never the IdP body.
+ *
+ * SERVER VALUE WINS for client_id (cards 268012 / 268410): applied AFTER the caller's payload spread, because these are
+ * unauthenticated endpoints and a browser-supplied client_id would be a tenant-targeting lever on a password-reset path.
+ *
+ * @package @payez/next-mvp
+ */
+
+/** One opaque token: JWT / base64url / opaque-hex alphabet, no whitespace or control characters, bounded length. */
+const TOKEN_SHAPE = /^[A-Za-z0-9\-._~+/]+=*$/;
+
+/** The recovery bearer from the inbound request, or null when absent / malformed. Never throws. */
+export function inboundRecoveryBearer(req: Pick<NextRequest, 'headers'>): string | null {
+  const raw = req.headers.get('authorization');
+  if (!raw) return null;
+  const m = /^Bearer[ ]+(\S+)$/i.exec(raw.trim());
+  if (!m) return null;
+  const token = m[1];
+  if (token.length < 16 || token.length > 4096) return null;
+  return TOKEN_SHAPE.test(token) ? token : null;
+}
+
+async function recoveryClientKey(where: string): Promise<string | null> {
+  try {
+    const config = await getIDPClientConfig();
+    return resolveClientKey(config, where).key;
+  } catch (e) {
+    console.error(`[${where}] could not resolve IDP client config for client_id:`, e);
+    return null;
+  }
+}
+
+export interface RecoveryForward {
+  /** IdP path after the host, e.g. /api/Account/recovery/send-code */
+  upstreamPath: string;
+  /** log/route label used for the client-key resolver */
+  where: string;
+  /** stable `error` code for an upstream that could not be reached */
+  failureCode: string;
+  /** user-facing fallback when the IdP gave no message */
+  fallbackMessage: string;
+}
+
+export async function forwardRecoveryCall(req: NextRequest, spec: RecoveryForward): Promise<NextResponse> {
+  let payload: unknown = {};
+  try {
+    payload = await req.json();
+  } catch {
+    return NextResponse.json({ success: false, error: 'invalid_request', message: 'A JSON body is required' }, { status: 400 });
+  }
+
+  const bearer = inboundRecoveryBearer(req);
+  if (!bearer) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'missing_recovery_token',
+        message: 'Your recovery session could not be found. Start the recovery again from the beginning.',
+      },
+      { status: 401 },
+    );
+  }
+
+  const clientKey = await recoveryClientKey(spec.where);
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(`${ENV_CONFIG.IDP_URL}${spec.upstreamPath}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        Authorization: `Bearer ${bearer}`,
+        ...(clientKey ? { 'X-Client-Id': clientKey } : {}),
+      },
+      body: JSON.stringify({ ...(payload as Record<string, unknown>), ...(clientKey ? { client_id: clientKey } : {}) }),
+    });
+  } catch {
+    return NextResponse.json({ success: false, error: spec.failureCode }, { status: 502 });
+  }
+
+  const data = await upstream.json().catch(() => ({}));
+  if (!upstream.ok) return NextResponse.json(idpErrorEnvelope(data, spec.fallbackMessage), { status: upstream.status });
+  return NextResponse.json(data, { status: 200 });
+}

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

@@ -1,59 +1,59 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { getIDPClientConfig } from '../../../lib/idp-client-config';
-import { resolveClientKey } from '../../../lib/client-key';
-import { idpErrorEnvelope } from '../../../lib/safe-error-response';
-
-function getIdpUrl(): string {
-  const url = process.env.IDP_URL;
-  if (!url) throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
-  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', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
-      body: JSON.stringify({ email, ...(clientKey ? { client_id: clientKey } : {}) }),
-    });
-    const data = await upstream.json().catch(() => ({}));
-    // PAY-1438: anonymous route - on failure only the whitelisted envelope, never the IDP body.
-    if (!upstream.ok) return NextResponse.json(idpErrorEnvelope(data, 'Failed to initiate recovery'), { status: upstream.status });
-    return NextResponse.json(data, { status: upstream.status });
-  } catch (e) {
-    return NextResponse.json({ success: false, error: 'initiate_failed' }, { status: 500 });
-  }
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { getIDPClientConfig } from '../../../lib/idp-client-config';
+import { resolveClientKey } from '../../../lib/client-key';
+import { idpErrorEnvelope } from '../../../lib/safe-error-response';
+
+function getIdpUrl(): string {
+  const url = process.env.IDP_URL;
+  if (!url) throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
+  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', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+      body: JSON.stringify({ email, ...(clientKey ? { client_id: clientKey } : {}) }),
+    });
+    const data = await upstream.json().catch(() => ({}));
+    // PAY-1438: anonymous route - on failure only the whitelisted envelope, never the IDP body.
+    if (!upstream.ok) return NextResponse.json(idpErrorEnvelope(data, 'Failed to initiate recovery'), { status: upstream.status });
+    return NextResponse.json(data, { status: upstream.status });
+  } catch (e) {
+    return NextResponse.json({ success: false, error: 'initiate_failed' }, { status: 500 });
+  }
+}

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

@@ -1,21 +1,21 @@
-import { NextRequest } from 'next/server';
-import { forwardRecoveryCall } from './forward';
-
-/**
- * Account recovery - send-code.
- *
- * PAY-1588: the recovery session token minted by `initiate` is the caller's only credential (they are locked out; there is
- * no session), so this forwards the inbound `Authorization: Bearer <token>` to the IdP and fails loud (401
- * `missing_recovery_token`) when it is absent. The whole reasoning, and why the 2026-08-02 idpFetchJSON rewrite killed
- * this flow, is in ./forward.ts. send-code and verify-code share that ONE forwarder so they cannot drift apart again.
- *
- * @package @payez/next-mvp
- */
-export async function POST(req: NextRequest) {
-  return forwardRecoveryCall(req, {
-    upstreamPath: '/api/Account/recovery/send-code',
-    where: 'account/recovery/send-code',
-    failureCode: 'send_code_failed',
-    fallbackMessage: 'Failed to send the verification code',
-  });
-}
+import { NextRequest } from 'next/server';
+import { forwardRecoveryCall } from './forward';
+
+/**
+ * Account recovery - send-code.
+ *
+ * PAY-1588: the recovery session token minted by `initiate` is the caller's only credential (they are locked out; there is
+ * no session), so this forwards the inbound `Authorization: Bearer <token>` to the IdP and fails loud (401
+ * `missing_recovery_token`) when it is absent. The whole reasoning, and why the 2026-08-02 idpFetchJSON rewrite killed
+ * this flow, is in ./forward.ts. send-code and verify-code share that ONE forwarder so they cannot drift apart again.
+ *
+ * @package @payez/next-mvp
+ */
+export async function POST(req: NextRequest) {
+  return forwardRecoveryCall(req, {
+    upstreamPath: '/api/Account/recovery/send-code',
+    where: 'account/recovery/send-code',
+    failureCode: 'send_code_failed',
+    fallbackMessage: 'Failed to send the verification code',
+  });
+}

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

@@ -1,20 +1,20 @@
-import { NextRequest } from 'next/server';
-import { forwardRecoveryCall } from './forward';
-
-/**
- * Account recovery - verify-code.
- *
- * PAY-1588: forwards the inbound recovery `Authorization: Bearer <token>` to the IdP and fails loud (401
- * `missing_recovery_token`) when it is absent. See ./forward.ts for the full reasoning; send-code and verify-code share
- * that ONE forwarder so they cannot drift apart again.
- *
- * @package @payez/next-mvp
- */
-export async function POST(req: NextRequest) {
-  return forwardRecoveryCall(req, {
-    upstreamPath: '/api/Account/recovery/verify-code',
-    where: 'account/recovery/verify-code',
-    failureCode: 'verify_code_failed',
-    fallbackMessage: 'Failed to verify the code',
-  });
-}
+import { NextRequest } from 'next/server';
+import { forwardRecoveryCall } from './forward';
+
+/**
+ * Account recovery - verify-code.
+ *
+ * PAY-1588: forwards the inbound recovery `Authorization: Bearer <token>` to the IdP and fails loud (401
+ * `missing_recovery_token`) when it is absent. See ./forward.ts for the full reasoning; send-code and verify-code share
+ * that ONE forwarder so they cannot drift apart again.
+ *
+ * @package @payez/next-mvp
+ */
+export async function POST(req: NextRequest) {
+  return forwardRecoveryCall(req, {
+    upstreamPath: '/api/Account/recovery/verify-code',
+    where: 'account/recovery/verify-code',
+    failureCode: 'verify_code_failed',
+    fallbackMessage: 'Failed to verify the code',
+  });
+}