@payez/next-mvp 4.1.20 → 4.4.0

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

@@ -3,30 +3,135 @@ import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession, updateSession } from '../../lib/session-store';
 
 /**
- * Force-expire access token for testing refresh flow.
+ * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
  *
- * Sets the access token expiry to 2 minutes in the past,
- * which will trigger a refresh on the next API call.
+ * 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.
  *
- * Usage in consuming app:
  * ```typescript
- * // app/api/test/force-expire/route.ts
+ * // 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);
 
-    let sessionToken = betterAuthSession?.session?.token as string | undefined;
+    // 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) {
-      const headerSessionToken = req.headers.get('x-session-token') || req.headers.get('X-Session-Token');
-      if (headerSessionToken) {
-        sessionToken = headerSessionToken;
-      } else {
-        console.warn('[TEST_EXPIRE] No session token or X-Session-Token header');
-        return NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
-      }
+      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);