@payez/next-mvp 4.8.0 → 4.8.2

package/src/api-handlers/test/force-expire.ts

@@ -1,167 +1,167 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession as getBetterAuthSession } from '../../server/auth';
-import { getSession, updateSession } from '../../lib/session-store';
-import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
-import { tokenLogId } from '../../lib/token-log-id';
-
-/**
- * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
- *
- * Force-expire access token for testing refresh flow. Sets the access token
- * expiry to 2 minutes in the past, which will trigger a refresh on the next
- * API call.
- *
- * THIS MUTATES SESSION STATE. It is a test affordance, not a product feature.
- *
- * ── WHY THIS WARNING EXISTS (QAPert 34983) ────────────────────────────────
- * The usage block below is not decoration: THIS DOCSTRING IS THE SPREAD
- * MECHANISM. It ships compiled into dist and into the .d.ts, so it reaches
- * every consumer's editor as hover text, and it is a one-line copy-paste that
- * mounts a destructive endpoint. Every one of the three surfaces this route
- * ended up on followed exactly these instructions.
- *
- * The handler itself was fixed (244877: default-deny behind ENABLE_TEST_ROUTES,
- * plus the caller-supplied-token IDOR removed). But a fixed handler shipped
- * with unqualified mounting instructions still spreads: the guidance was never
- * corrected alongside the code, and a package that documents a dangerous route
- * as a plain convenience is instructing the weaker configuration.
- *
- * ── IF YOU MOUNT IT, MOUNT IT LIKE THIS ───────────────────────────────────
- * Required: set ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY. Absent, empty
- * or any other value default-DENIES (404). Never set it in production.
- *
- * ```typescript
- * // app/api/test/force-expire/route.ts   — TEST/DEV ENVIRONMENTS ONLY
- * // Requires ENABLE_TEST_ROUTES=true in that environment; 404s otherwise.
- * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
- * ```
- *
- * If you do not need to exercise the refresh flow, DO NOT MOUNT THIS AT ALL.
- * The safest configuration is the absence of the route.
- */
-export const POST = async (req: NextRequest) => {
-  // 244877 (package-level): DEFAULT DENY behind ENABLE_TEST_ROUTES.
-  //
-  // This handler MUTATES session state — it rewrites idpAccessTokenExpires two
-  // minutes into the past — and was gated on nothing but "any signed-in
-  // session": no role check, no env kill-switch. Because consuming apps mount
-  // it with a one-line re-export, EVERY consumer inherited that, including
-  // deployments on production hosts.
-  //
-  // The card was raised against one app's local copy. Sweeping the pattern
-  // rather than the instance found the same route in three places — a local
-  // copy in the graft, a local copy in idealvibe.online, and idealresume.online
-  // re-exporting THIS handler — so the fix belongs here, at the source all
-  // three ultimately derive from, not only in whichever copy was noticed first.
-  //
-  // The gate is the FIRST statement, before any session decode, so a disabled
-  // build does not reveal that the route is live. Absent, empty, or any value
-  // other than 'true' disables it. Distinguishable body on purpose: a bare 404
-  // reads as "route missing / build broken" and sends someone debugging
-  // deployment instead of reading a flag.
-  //
-  // A consumer that genuinely needs this in a test environment sets
-  // ENABLE_TEST_ROUTES=true there, which is the same posture the token
-  // inspector already uses for a strictly LESS dangerous, read-only route.
-  if (process.env.ENABLE_TEST_ROUTES !== 'true') {
-    // DISCLOSURE IS CONDITIONAL ON ENVIRONMENT (QAPert-NightHawk 34539, after
-    // QAPert caught that my first version shipped the very leak we had just
-    // criticised elsewhere).
-    //
-    // My original body named the flag: "Set ENABLE_TEST_ROUTES=true...". That
-    // is the same class of disclosure as TOKEN_INSPECTOR_DISABLED — it confirms
-    // the route exists, names the capability, and hands a prober the exact
-    // switch that turns it on. Having argued against that pattern one directory
-    // over, shipping it here would have been incoherent.
-    //
-    // Deleting the message outright is also wrong: it is what stops a developer
-    // losing an hour deciding whether their build is broken. The tension
-    // resolves by AUDIENCE, not by picking a side:
-    //   production      -> 404, EMPTY body. Nothing about the capability, the
-    //                      flag, or even that a handler is here.
-    //   non-production  -> 404 + the helpful message naming the flag.
-    //
-    // The operator affordance survives in production too, via the log line
-    // below: logs are visible to operators and not to probers, which is exactly
-    // the split the response body cannot make.
-    console.warn(
-      '[FORCE-EXPIRE] blocked: ENABLE_TEST_ROUTES is not "true" (test routes default-deny).',
-    );
-
-    if (process.env.NODE_ENV === 'production') {
-      return new NextResponse(null, { status: 404 });
-    }
-
-    return NextResponse.json(
-      {
-        error: 'TEST_ROUTES_DISABLED',
-        message:
-          'Test routes are disabled in this build. Set ENABLE_TEST_ROUTES=true to enable them (development only).',
-      },
-      { status: 404 },
-    );
-  }
-
-  try {
-    const betterAuthSession = await getBetterAuthSession(req);
-
-    // ACCESS CONTROL (QAPert 34553). This handler previously fell back to a
-    // CALLER-SUPPLIED `X-Session-Token` header when the request carried no
-    // session of its own, and then force-expired whatever token that header
-    // named — with NO check that the token belonged to the caller. The 401
-    // fired only when a caller supplied NEITHER a session NOR the header. So
-    // an UNAUTHENTICATED caller who presented any valid session token could
-    // expire ANOTHER USER'S session: an unauthenticated cross-session write.
-    //
-    // The fallback is removed rather than ownership-checked, because an
-    // ownership check would make it exactly equivalent to reading the caller's
-    // own session — the header could then never name anything else, so it
-    // would be a parameter that cannot legally vary. The session to expire is
-    // now ALWAYS the caller's own, which is also what the graft's local copy
-    // has always done.
-    //
-    // This is defence in depth, not the only control: the ENABLE_TEST_ROUTES
-    // gate above already 404s this handler by default. But the gate is
-    // switched ON in test environments, and "unauthenticated users can expire
-    // each other's sessions" is not acceptable there either — a control that
-    // only holds while a feature is switched off is not an access control.
-    //
-    // Corrects NextPert's own scope claim on card 244877 ("a caller could only
-    // ever expire their OWN session"): that was read off the graft's LOCAL
-    // copy, which derives the token from the caller's JWT. It was never true
-    // of THIS handler, which is the one consumers actually mount.
-    const sessionToken = betterAuthSession?.session?.token as string | undefined;
-    if (!sessionToken) {
-      console.warn('[TEST_EXPIRE] No session on the request');
-      return NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
-    }
-
-    const session = await getSession(sessionToken);
-    if (!session) {
-      return NextResponse.json({ success: false, error: 'Session not found' }, { status: 404 });
-    }
-
-    const now = Date.now();
-    const forced = now - (2 * 60 * 1000); // two minutes ago
-    const prev = session.idpAccessTokenExpires || null;
-
-    await updateSession(sessionToken, { idpAccessTokenExpires: forced });
-
-    console.log('[TEST_EXPIRE] Forced access token expiry for session', {
-      sessionToken: tokenLogId(sessionToken),
-      previous: prev ? new Date(prev).toISOString() : null,
-      newExpiry: new Date(forced).toISOString()
-    });
-
-    return NextResponse.json({
-      success: true,
-      previous: prev,
-      previousIso: prev ? new Date(prev).toISOString() : null,
-      newExpiry: forced,
-      newExpiryIso: new Date(forced).toISOString()
-    });
-  } catch (e) {
-    const correlationId = logExceptionWithCorrelation('[TEST_EXPIRE] Error:', e);
-    return NextResponse.json({ success: false, error: 'Failed to force expiry', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
-  }
-};
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession as getBetterAuthSession } from '../../server/auth';
+import { getSession, updateSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+import { tokenLogId } from '../../lib/token-log-id';
+
+/**
+ * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
+ *
+ * Force-expire access token for testing refresh flow. Sets the access token
+ * expiry to 2 minutes in the past, which will trigger a refresh on the next
+ * API call.
+ *
+ * THIS MUTATES SESSION STATE. It is a test affordance, not a product feature.
+ *
+ * ── WHY THIS WARNING EXISTS (QAPert 34983) ────────────────────────────────
+ * The usage block below is not decoration: THIS DOCSTRING IS THE SPREAD
+ * MECHANISM. It ships compiled into dist and into the .d.ts, so it reaches
+ * every consumer's editor as hover text, and it is a one-line copy-paste that
+ * mounts a destructive endpoint. Every one of the three surfaces this route
+ * ended up on followed exactly these instructions.
+ *
+ * The handler itself was fixed (244877: default-deny behind ENABLE_TEST_ROUTES,
+ * plus the caller-supplied-token IDOR removed). But a fixed handler shipped
+ * with unqualified mounting instructions still spreads: the guidance was never
+ * corrected alongside the code, and a package that documents a dangerous route
+ * as a plain convenience is instructing the weaker configuration.
+ *
+ * ── IF YOU MOUNT IT, MOUNT IT LIKE THIS ───────────────────────────────────
+ * Required: set ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY. Absent, empty
+ * or any other value default-DENIES (404). Never set it in production.
+ *
+ * ```typescript
+ * // app/api/test/force-expire/route.ts   — TEST/DEV ENVIRONMENTS ONLY
+ * // Requires ENABLE_TEST_ROUTES=true in that environment; 404s otherwise.
+ * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
+ * ```
+ *
+ * If you do not need to exercise the refresh flow, DO NOT MOUNT THIS AT ALL.
+ * The safest configuration is the absence of the route.
+ */
+export const POST = async (req: NextRequest) => {
+  // 244877 (package-level): DEFAULT DENY behind ENABLE_TEST_ROUTES.
+  //
+  // This handler MUTATES session state — it rewrites idpAccessTokenExpires two
+  // minutes into the past — and was gated on nothing but "any signed-in
+  // session": no role check, no env kill-switch. Because consuming apps mount
+  // it with a one-line re-export, EVERY consumer inherited that, including
+  // deployments on production hosts.
+  //
+  // The card was raised against one app's local copy. Sweeping the pattern
+  // rather than the instance found the same route in three places — a local
+  // copy in the graft, a local copy in idealvibe.online, and idealresume.online
+  // re-exporting THIS handler — so the fix belongs here, at the source all
+  // three ultimately derive from, not only in whichever copy was noticed first.
+  //
+  // The gate is the FIRST statement, before any session decode, so a disabled
+  // build does not reveal that the route is live. Absent, empty, or any value
+  // other than 'true' disables it. Distinguishable body on purpose: a bare 404
+  // reads as "route missing / build broken" and sends someone debugging
+  // deployment instead of reading a flag.
+  //
+  // A consumer that genuinely needs this in a test environment sets
+  // ENABLE_TEST_ROUTES=true there, which is the same posture the token
+  // inspector already uses for a strictly LESS dangerous, read-only route.
+  if (process.env.ENABLE_TEST_ROUTES !== 'true') {
+    // DISCLOSURE IS CONDITIONAL ON ENVIRONMENT (QAPert-NightHawk 34539, after
+    // QAPert caught that my first version shipped the very leak we had just
+    // criticised elsewhere).
+    //
+    // My original body named the flag: "Set ENABLE_TEST_ROUTES=true...". That
+    // is the same class of disclosure as TOKEN_INSPECTOR_DISABLED — it confirms
+    // the route exists, names the capability, and hands a prober the exact
+    // switch that turns it on. Having argued against that pattern one directory
+    // over, shipping it here would have been incoherent.
+    //
+    // Deleting the message outright is also wrong: it is what stops a developer
+    // losing an hour deciding whether their build is broken. The tension
+    // resolves by AUDIENCE, not by picking a side:
+    //   production      -> 404, EMPTY body. Nothing about the capability, the
+    //                      flag, or even that a handler is here.
+    //   non-production  -> 404 + the helpful message naming the flag.
+    //
+    // The operator affordance survives in production too, via the log line
+    // below: logs are visible to operators and not to probers, which is exactly
+    // the split the response body cannot make.
+    console.warn(
+      '[FORCE-EXPIRE] blocked: ENABLE_TEST_ROUTES is not "true" (test routes default-deny).',
+    );
+
+    if (process.env.NODE_ENV === 'production') {
+      return new NextResponse(null, { status: 404 });
+    }
+
+    return NextResponse.json(
+      {
+        error: 'TEST_ROUTES_DISABLED',
+        message:
+          'Test routes are disabled in this build. Set ENABLE_TEST_ROUTES=true to enable them (development only).',
+      },
+      { status: 404 },
+    );
+  }
+
+  try {
+    const betterAuthSession = await getBetterAuthSession(req);
+
+    // ACCESS CONTROL (QAPert 34553). This handler previously fell back to a
+    // CALLER-SUPPLIED `X-Session-Token` header when the request carried no
+    // session of its own, and then force-expired whatever token that header
+    // named — with NO check that the token belonged to the caller. The 401
+    // fired only when a caller supplied NEITHER a session NOR the header. So
+    // an UNAUTHENTICATED caller who presented any valid session token could
+    // expire ANOTHER USER'S session: an unauthenticated cross-session write.
+    //
+    // The fallback is removed rather than ownership-checked, because an
+    // ownership check would make it exactly equivalent to reading the caller's
+    // own session — the header could then never name anything else, so it
+    // would be a parameter that cannot legally vary. The session to expire is
+    // now ALWAYS the caller's own, which is also what the graft's local copy
+    // has always done.
+    //
+    // This is defence in depth, not the only control: the ENABLE_TEST_ROUTES
+    // gate above already 404s this handler by default. But the gate is
+    // switched ON in test environments, and "unauthenticated users can expire
+    // each other's sessions" is not acceptable there either — a control that
+    // only holds while a feature is switched off is not an access control.
+    //
+    // Corrects NextPert's own scope claim on card 244877 ("a caller could only
+    // ever expire their OWN session"): that was read off the graft's LOCAL
+    // copy, which derives the token from the caller's JWT. It was never true
+    // of THIS handler, which is the one consumers actually mount.
+    const sessionToken = betterAuthSession?.session?.token as string | undefined;
+    if (!sessionToken) {
+      console.warn('[TEST_EXPIRE] No session on the request');
+      return NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
+    }
+
+    const session = await getSession(sessionToken);
+    if (!session) {
+      return NextResponse.json({ success: false, error: 'Session not found' }, { status: 404 });
+    }
+
+    const now = Date.now();
+    const forced = now - (2 * 60 * 1000); // two minutes ago
+    const prev = session.idpAccessTokenExpires || null;
+
+    await updateSession(sessionToken, { idpAccessTokenExpires: forced });
+
+    console.log('[TEST_EXPIRE] Forced access token expiry for session', {
+      sessionToken: tokenLogId(sessionToken),
+      previous: prev ? new Date(prev).toISOString() : null,
+      newExpiry: new Date(forced).toISOString()
+    });
+
+    return NextResponse.json({
+      success: true,
+      previous: prev,
+      previousIso: prev ? new Date(prev).toISOString() : null,
+      newExpiry: forced,
+      newExpiryIso: new Date(forced).toISOString()
+    });
+  } catch (e) {
+    const correlationId = logExceptionWithCorrelation('[TEST_EXPIRE] Error:', e);
+    return NextResponse.json({ success: false, error: 'Failed to force expiry', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
+  }
+};