Merge branch 'main' into fix/dpop-nonce-retry-race

Author: nandan-bhat

EXAMPLES.md

@@ -929,6 +929,43 @@ export async function GET() {
 }
 ```
 
+**App Router Route Handlers — Refresh + Custom Response Headers/Cookies:**
+
+If your Route Handler needs to both refresh the session **and** return a `NextResponse` you fully control (e.g., to set additional cookies with a `Domain` or `SameSite` attribute), use the explicit `getAccessToken(req, res, options)` signature. This writes the refreshed session directly onto the `NextResponse` you pass, so all `Set-Cookie` headers — session and custom — are consolidated on the one response object you return.
+
+```typescript
+// app/api/refresh/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+import { auth0 } from "@/lib/auth0";
+
+export async function POST(req: NextRequest) {
+  // 1. Create the response object you will return.
+  const res = new NextResponse();
+
+  // 2. Pass req + res explicitly so the SDK writes the refreshed session
+  //    cookies directly onto `res` rather than into Next.js's internal
+  //    AsyncLocalStorage store. This makes the Set-Cookie headers (including
+  //    Domain, SameSite, Secure, etc. from your session.cookie config)
+  //    available on the response object you control.
+  const { token } = await auth0.getAccessToken(req, res, { refresh: true });
+
+  // 3. Set any additional cookies on the same response object.
+  res.cookies.set("my-cookie", "value", {
+    domain: ".example.com",
+    secure: true,
+    sameSite: "lax"
+  });
+
+  // 4. Return the single response — it now carries both the refreshed
+  //    session Set-Cookie headers and your custom cookie.
+  return res;
+}
+```
+
+> [!IMPORTANT]
+> Calling `getAccessToken({ refresh: true })` (without `req`/`res`) in a Route Handler writes the refreshed session through Next.js's internal cookie store, **not** onto a `NextResponse` you construct. If you then build a `new NextResponse()` and add cookies to it, that response will be missing the refreshed session cookies. Always pass `req` and `res` explicitly when you need all cookies on the same response object.
+
 **Pages Router (getServerSideProps, API Routes):**
 
 When calling `getAccessToken` with request and response objects (from `getServerSideProps` context or an API route), the options object is passed as the third argument.

src/server/cookies.test.ts

@@ -43,6 +43,20 @@ describe("encrypt/decrypt", async () => {
     expect(decrypted).toBeNull();
   });
 
+  it("should fail to decrypt a tampered payload", async () => {
+    const payload = { key: "value" };
+    const maxAge = 60 * 60; // 1 hour in seconds
+    const expiration = Math.floor(Date.now() / 1000 + maxAge);
+    const encrypted = await encrypt(payload, secret, expiration);
+
+    // Tamper with the encrypted payload by shifting the first character
+    const tampered =
+      String.fromCharCode(encrypted.charCodeAt(0) + 1) + encrypted.slice(1);
+
+    const decrypted = await decrypt(tampered, secret);
+    expect(decrypted).toBeNull();
+  });
+
   it("should fail to encrypt if a secret is not provided", async () => {
     const payload = { key: "value" };
     const maxAge = 60 * 60; // 1 hour in seconds

src/server/cookies.ts

@@ -68,7 +68,8 @@ export async function decrypt<T>(
     // When the JWE can not be decrypted or has expired, return null to indicate an invalid cookie and treat it as non-existent.
     if (
       e.code === "ERR_JWE_DECRYPTION_FAILED" ||
-      e.code === "ERR_JWT_EXPIRED"
+      e.code === "ERR_JWT_EXPIRED" ||
+      e.code === "ERR_JWE_INVALID"
     ) {
       return null;
     }

src/server/session/stateful-session-store.ts

@@ -74,7 +74,9 @@ export class StatefulSessionStore extends AbstractSessionStore {
     try {
       const sessionCookie = await cookies.decrypt<SessionCookieValue>(
         cookie.value,
-        this.secret
+        this.secret,
+        undefined,
+        true // throwOnJWEErrors: allow catching ERR_JWE_INVALID to handle legacy sessions
       );
 
       if (sessionCookie === null) {