@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/idp-fetch.ts

@@ -1,170 +1,170 @@
-import { NextRequest } from 'next/server';
-import { getTokenTestAware } from './test-aware-get-token';
-import { getSession } from './session-store';
-import { internalRefresh } from './internal-api';
-import { assertAbsoluteIdpUrl } from './idp-url-guard';
-import { parseRetryAfterSeconds } from './retry-after';
-
-// Re-exported so `idp-fetch` remains the single obvious import for IDP calling
-// concerns; the implementation lives in a dependency-free leaf so the three
-// direct-fetch callers (auth/jwks.ts, auth/passkey-signin.ts x2) do not have to
-// pull this module's server-only chain in for one regex.
-export { assertAbsoluteIdpUrl, parseRetryAfterSeconds };
-
-/**
- * Centralized IDP fetch helper
- * - Injects Bearer from Redis session
- * - If access token is expired/near-expiry, triggers one refresh and retries fetch once
- * - Returns parsed JSON and HTTP status
- */
-export interface IdpFetchResult<T = any> {
-  ok: boolean;
-  status: number;
-  json: T | null;
-  attemptedRefresh: boolean;
-  /**
-   * PAY-1608: the upstream Retry-After in whole seconds, when the IDP sent a usable one. Core sends it on every
-   * 2FA lock (MfaController.SecondFactorLocked: 429 + Retry-After 900; VerifyTotp: what is left of the lock).
-   * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
-   */
-  retryAfterSeconds?: number;
-}
-
-function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
-  const headers: Record<string, string> = {
-    Accept: 'application/json',
-    'Content-Type': 'application/json',
-    ...extra,
-  };
-  /**
-   * 269334 / R21: forward the FULL X-Forwarded-For chain, do NOT collapse to [0].
-   *
-   * `.split(',')[0]` took the LEFT-most entry - the value the ORIGINAL client
-   * supplied, which is forgeable - and discarded the rest of the chain. That both
-   * (a) forwards the attacker-controlled value and (b) destroys the chain the
-   * receiving side needs to identify the real client by counting trusted hops from
-   * the right. This app cannot itself observe the TCP peer (Next 16.2.12 route
-   * handler, no socket), so the correct division of labour is: the IDP's ingress
-   * (Envoy, use_remote_address:true) APPENDS the real observed peer, the IDP counts
-   * xff_num_trusted_hops from the right, and THIS layer's only job is to not throw
-   * the chain away. Forwarding the full value is byte-identical to today for any
-   * consumer reading [0], so it cannot regress current behaviour; it only stops
-   * discarding the entries the trusted-hop logic will need.
-   */
-  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
-  if (xfwd) headers['X-Forwarded-For'] = xfwd;
-  const ua = req.headers.get('user-agent');
-  if (ua) headers['User-Agent'] = ua;
-  if (bearer) headers['Authorization'] = `Bearer ${bearer}`;
-  return headers;
-}
-
-async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?: string; accessToken?: string; hasRefreshToken?: boolean }> {
-  const token = await getTokenTestAware(req);
-  // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
-  const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
-  console.log('[IDP_FETCH] ensureFreshAccessToken:', {
-    hasToken: !!token,
-    hasSessionToken: !!sessionToken, // PAY-1427 / BAPert 58829: no token material in logs, not even a stub (was a 20-char prefix)
-    pathname: req.nextUrl.pathname
-  });
-  if (!sessionToken) {
-    console.warn('[IDP_FETCH] No sessionToken found in JWT - Bearer token will NOT be sent!');
-    return {};
-  }
-  let session = await getSession(sessionToken);
-  // Fall back to Better Auth Redis key when app session is missing/stale
-  if (!session || !session.idpAccessToken) {
-    const { getBetterAuthSession } = await import('./session-store');
-    const baSession = await getBetterAuthSession(sessionToken);
-    if (baSession?.idpAccessToken) {
-      session = baSession;
-    }
-  }
-  // Fall back to Better Auth: decode session from cookies to get IDP tokens
-  if (!session?.idpAccessToken) {
-    try {
-      const { decodeSession } = await import('../server/decode-session');
-      const decoded = await decodeSession(req.cookies);
-      if (decoded?.sessionData?.idpAccessToken) {
-        session = decoded.sessionData;
-      }
-    } catch { /* decodeSession unavailable in edge */ }
-  }
-  console.log('[IDP_FETCH] Redis session lookup:', {
-    hasSession: !!session,
-    hasAccessToken: !!session?.idpAccessToken,
-    hasRefreshToken: !!session?.idpRefreshToken,
-    bearerKeyId: session?.bearerKeyId || 'NOT_SET',
-    idpClientId: session?.idpClientId || 'NOT_SET',
-  });
-  if (!session?.idpAccessToken) return { sessionToken };
-  const hasRefreshToken = !!session.idpRefreshToken;
-  const now = Date.now();
-  const timeLeft = (session.idpAccessTokenExpires ?? now) - now;
-  // Treat tokens as effectively expired if within 5 minutes of expiry
-  if (timeLeft > 5 * 60 * 1000) {
-    return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
-  }
-  // Only attempt refresh when we actually have a refresh token to use.
-  // Provisional tokens (issued before 2FA completion) have no refresh token.
-  if (hasRefreshToken) {
-    try {
-      await internalRefresh(req.headers.get('cookie') || '', sessionToken);
-    } catch {}
-    session = await getSession(sessionToken);
-    return { sessionToken, accessToken: session?.idpAccessToken, hasRefreshToken: !!session?.idpRefreshToken };
-  }
-  return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
-}
-
-export async function idpFetchJSON<T = any>(
-  req: NextRequest,
-  targetUrl: string,
-  init: RequestInit = {}
-): Promise<IdpFetchResult<T>> {
-  let attemptedRefresh = false;
-  let { accessToken, sessionToken, hasRefreshToken } = await ensureFreshAccessToken(req);
-
-  assertAbsoluteIdpUrl(targetUrl);
-
-  const makeCall = async (bearer?: string) => {
-    // NOTE (307290): this fetch is UNGUARDED, and so is the first call to it at
-    // the "First attempt" below. Only the JSON PARSE (try/catch immediately
-    // after) and the RETRY are guarded. A transport-level failure - DNS, refused,
-    // TLS, timeout - therefore throws straight out of idpFetchJSON, past the thin
-    // route handlers that call it, and Next answers 500. This is long-standing and
-    // NOT introduced by 307290; but 307290's middleware carve-out lets expired-token
-    // /api/ requests reach these handlers where middleware previously redirected
-    // them away, so it routes a NEW POPULATION at this pre-existing risk. If IDP
-    // reachability blips after that change, suspect this line before suspecting the
-    // carve-out. Correcting b4b8ffae's message, which wrongly said every risky
-    // branch here is try/caught.
-    const res = await fetch(targetUrl, {
-      ...init,
-      headers: buildHeaders(req, bearer, init.headers as any),
-    });
-    let json: any = null;
-    try { json = await res.json(); } catch { json = null; }
-    return { res, json } as const;
-  };
-
-  // First attempt
-  let { res, json } = await makeCall(accessToken);
-  // Only attempt refresh on 401/403 if we actually have a refresh token.
-  // Provisional tokens (pre-2FA) have no refresh token — refreshing is futile.
-  if ((res.status === 401 || res.status === 403) && sessionToken && hasRefreshToken && !attemptedRefresh) {
-    attemptedRefresh = true;
-    try {
-      // Use centralized internal API helper for server-to-server calls
-      const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
-      if (rf.ok) {
-        const fresh = await getSession(sessionToken);
-        ({ res, json } = await makeCall(fresh?.idpAccessToken));
-      }
-    } catch {}
-  }
-
-  const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.('Retry-After'));
-  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
+import { NextRequest } from 'next/server';
+import { getTokenTestAware } from './test-aware-get-token';
+import { getSession } from './session-store';
+import { internalRefresh } from './internal-api';
+import { assertAbsoluteIdpUrl } from './idp-url-guard';
+import { parseRetryAfterSeconds } from './retry-after';
+
+// Re-exported so `idp-fetch` remains the single obvious import for IDP calling
+// concerns; the implementation lives in a dependency-free leaf so the three
+// direct-fetch callers (auth/jwks.ts, auth/passkey-signin.ts x2) do not have to
+// pull this module's server-only chain in for one regex.
+export { assertAbsoluteIdpUrl, parseRetryAfterSeconds };
+
+/**
+ * Centralized IDP fetch helper
+ * - Injects Bearer from Redis session
+ * - If access token is expired/near-expiry, triggers one refresh and retries fetch once
+ * - Returns parsed JSON and HTTP status
+ */
+export interface IdpFetchResult<T = any> {
+  ok: boolean;
+  status: number;
+  json: T | null;
+  attemptedRefresh: boolean;
+  /**
+   * PAY-1608: the upstream Retry-After in whole seconds, when the IDP sent a usable one. Core sends it on every
+   * 2FA lock (MfaController.SecondFactorLocked: 429 + Retry-After 900; VerifyTotp: what is left of the lock).
+   * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
+   */
+  retryAfterSeconds?: number;
+}
+
+function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    ...extra,
+  };
+  /**
+   * 269334 / R21: forward the FULL X-Forwarded-For chain, do NOT collapse to [0].
+   *
+   * `.split(',')[0]` took the LEFT-most entry - the value the ORIGINAL client
+   * supplied, which is forgeable - and discarded the rest of the chain. That both
+   * (a) forwards the attacker-controlled value and (b) destroys the chain the
+   * receiving side needs to identify the real client by counting trusted hops from
+   * the right. This app cannot itself observe the TCP peer (Next 16.2.12 route
+   * handler, no socket), so the correct division of labour is: the IDP's ingress
+   * (Envoy, use_remote_address:true) APPENDS the real observed peer, the IDP counts
+   * xff_num_trusted_hops from the right, and THIS layer's only job is to not throw
+   * the chain away. Forwarding the full value is byte-identical to today for any
+   * consumer reading [0], so it cannot regress current behaviour; it only stops
+   * discarding the entries the trusted-hop logic will need.
+   */
+  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
+  if (xfwd) headers['X-Forwarded-For'] = xfwd;
+  const ua = req.headers.get('user-agent');
+  if (ua) headers['User-Agent'] = ua;
+  if (bearer) headers['Authorization'] = `Bearer ${bearer}`;
+  return headers;
+}
+
+async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?: string; accessToken?: string; hasRefreshToken?: boolean }> {
+  const token = await getTokenTestAware(req);
+  // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+  const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
+  console.log('[IDP_FETCH] ensureFreshAccessToken:', {
+    hasToken: !!token,
+    hasSessionToken: !!sessionToken, // PAY-1427 / BAPert 58829: no token material in logs, not even a stub (was a 20-char prefix)
+    pathname: req.nextUrl.pathname
+  });
+  if (!sessionToken) {
+    console.warn('[IDP_FETCH] No sessionToken found in JWT - Bearer token will NOT be sent!');
+    return {};
+  }
+  let session = await getSession(sessionToken);
+  // Fall back to Better Auth Redis key when app session is missing/stale
+  if (!session || !session.idpAccessToken) {
+    const { getBetterAuthSession } = await import('./session-store');
+    const baSession = await getBetterAuthSession(sessionToken);
+    if (baSession?.idpAccessToken) {
+      session = baSession;
+    }
+  }
+  // Fall back to Better Auth: decode session from cookies to get IDP tokens
+  if (!session?.idpAccessToken) {
+    try {
+      const { decodeSession } = await import('../server/decode-session');
+      const decoded = await decodeSession(req.cookies);
+      if (decoded?.sessionData?.idpAccessToken) {
+        session = decoded.sessionData;
+      }
+    } catch { /* decodeSession unavailable in edge */ }
+  }
+  console.log('[IDP_FETCH] Redis session lookup:', {
+    hasSession: !!session,
+    hasAccessToken: !!session?.idpAccessToken,
+    hasRefreshToken: !!session?.idpRefreshToken,
+    bearerKeyId: session?.bearerKeyId || 'NOT_SET',
+    idpClientId: session?.idpClientId || 'NOT_SET',
+  });
+  if (!session?.idpAccessToken) return { sessionToken };
+  const hasRefreshToken = !!session.idpRefreshToken;
+  const now = Date.now();
+  const timeLeft = (session.idpAccessTokenExpires ?? now) - now;
+  // Treat tokens as effectively expired if within 5 minutes of expiry
+  if (timeLeft > 5 * 60 * 1000) {
+    return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
+  }
+  // Only attempt refresh when we actually have a refresh token to use.
+  // Provisional tokens (issued before 2FA completion) have no refresh token.
+  if (hasRefreshToken) {
+    try {
+      await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+    } catch {}
+    session = await getSession(sessionToken);
+    return { sessionToken, accessToken: session?.idpAccessToken, hasRefreshToken: !!session?.idpRefreshToken };
+  }
+  return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
+}
+
+export async function idpFetchJSON<T = any>(
+  req: NextRequest,
+  targetUrl: string,
+  init: RequestInit = {}
+): Promise<IdpFetchResult<T>> {
+  let attemptedRefresh = false;
+  let { accessToken, sessionToken, hasRefreshToken } = await ensureFreshAccessToken(req);
+
+  assertAbsoluteIdpUrl(targetUrl);
+
+  const makeCall = async (bearer?: string) => {
+    // NOTE (307290): this fetch is UNGUARDED, and so is the first call to it at
+    // the "First attempt" below. Only the JSON PARSE (try/catch immediately
+    // after) and the RETRY are guarded. A transport-level failure - DNS, refused,
+    // TLS, timeout - therefore throws straight out of idpFetchJSON, past the thin
+    // route handlers that call it, and Next answers 500. This is long-standing and
+    // NOT introduced by 307290; but 307290's middleware carve-out lets expired-token
+    // /api/ requests reach these handlers where middleware previously redirected
+    // them away, so it routes a NEW POPULATION at this pre-existing risk. If IDP
+    // reachability blips after that change, suspect this line before suspecting the
+    // carve-out. Correcting b4b8ffae's message, which wrongly said every risky
+    // branch here is try/caught.
+    const res = await fetch(targetUrl, {
+      ...init,
+      headers: buildHeaders(req, bearer, init.headers as any),
+    });
+    let json: any = null;
+    try { json = await res.json(); } catch { json = null; }
+    return { res, json } as const;
+  };
+
+  // First attempt
+  let { res, json } = await makeCall(accessToken);
+  // Only attempt refresh on 401/403 if we actually have a refresh token.
+  // Provisional tokens (pre-2FA) have no refresh token — refreshing is futile.
+  if ((res.status === 401 || res.status === 403) && sessionToken && hasRefreshToken && !attemptedRefresh) {
+    attemptedRefresh = true;
+    try {
+      // Use centralized internal API helper for server-to-server calls
+      const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+      if (rf.ok) {
+        const fresh = await getSession(sessionToken);
+        ({ res, json } = await makeCall(fresh?.idpAccessToken));
+      }
+    } catch {}
+  }
+
+  const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.('Retry-After'));
+  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/src/lib/idp-url-guard.ts

@@ -1,37 +1,37 @@
-/**
- * Name the missing variable instead of letting undici say "Failed to parse URL".
- *
- * Every caller builds its target as `${ENV_CONFIG.IDP_URL}/api/...`. IDP_URL is a
- * BARE PASSTHROUGH in src/config/env.ts - no fallback, no validation - so when it
- * is missing the interpolation yields a url that is not absolute. BOTH spellings
- * of "missing" are caught here, which is why this tests for an absolute url
- * rather than for a leading slash:
- *   IDP_URL=      (empty, as the quickstart now ships) -> "/api/Account/profile"
- *   IDP_URL unset (absent from the env entirely)       -> "undefined/api/Account/profile"
- * A leading-slash test would have caught only the first.
- *
- * This already fails CLOSED: undici rejects a relative url, so the guard changes
- * no outcome - it only makes the existing failure self-describing. It does NOT
- * silently retarget the app's own origin. (QAPert tested that hypothesis and
- * reported it disproved, mail 48139.)
- *
- * WHY THIS IS A LEAF MODULE WITH NO IMPORTS, AND NOT A THROW IN env.ts:
- *   - env.ts is the wrong home: ENV_CONFIG is imported by 26 modules and
- *     re-exported from the package index, so a module-load throw would crash
- *     consumers that only render components and never call the IDP. QAPert
- *     proposed exactly that (48139); it is the one shape this cannot take.
- *   - idp-fetch.ts is the wrong home for the SHARED copy: importing it pulls
- *     server-only, the session store and the logger, so the three direct-fetch
- *     callers would drag that whole chain in for one regex - and the predicate
- *     could not be unit-tested without a live server environment.
- * Keep this file dependency-free so both stay true.
- */
-export function assertAbsoluteIdpUrl(targetUrl: string): void {
-  if (!/^https?:\/\//i.test(targetUrl)) {
-    throw new Error(
-      `IDP_URL is not set. Refusing to call the IDP with the non-absolute URL "${targetUrl}". ` +
-      `Set IDP_URL in your environment (dev: http://10.0.0.93:32785). ` +
-      `Never set it to a production host in a development worktree.`
-    );
-  }
-}
+/**
+ * Name the missing variable instead of letting undici say "Failed to parse URL".
+ *
+ * Every caller builds its target as `${ENV_CONFIG.IDP_URL}/api/...`. IDP_URL is a
+ * BARE PASSTHROUGH in src/config/env.ts - no fallback, no validation - so when it
+ * is missing the interpolation yields a url that is not absolute. BOTH spellings
+ * of "missing" are caught here, which is why this tests for an absolute url
+ * rather than for a leading slash:
+ *   IDP_URL=      (empty, as the quickstart now ships) -> "/api/Account/profile"
+ *   IDP_URL unset (absent from the env entirely)       -> "undefined/api/Account/profile"
+ * A leading-slash test would have caught only the first.
+ *
+ * This already fails CLOSED: undici rejects a relative url, so the guard changes
+ * no outcome - it only makes the existing failure self-describing. It does NOT
+ * silently retarget the app's own origin. (QAPert tested that hypothesis and
+ * reported it disproved, mail 48139.)
+ *
+ * WHY THIS IS A LEAF MODULE WITH NO IMPORTS, AND NOT A THROW IN env.ts:
+ *   - env.ts is the wrong home: ENV_CONFIG is imported by 26 modules and
+ *     re-exported from the package index, so a module-load throw would crash
+ *     consumers that only render components and never call the IDP. QAPert
+ *     proposed exactly that (48139); it is the one shape this cannot take.
+ *   - idp-fetch.ts is the wrong home for the SHARED copy: importing it pulls
+ *     server-only, the session store and the logger, so the three direct-fetch
+ *     callers would drag that whole chain in for one regex - and the predicate
+ *     could not be unit-tested without a live server environment.
+ * Keep this file dependency-free so both stay true.
+ */
+export function assertAbsoluteIdpUrl(targetUrl: string): void {
+  if (!/^https?:\/\//i.test(targetUrl)) {
+    throw new Error(
+      `IDP_URL is not set. Refusing to call the IDP with the non-absolute URL "${targetUrl}". ` +
+      `Set IDP_URL in your environment (dev: http://10.0.0.93:32785). ` +
+      `Never set it to a production host in a development worktree.`
+    );
+  }
+}