feat(nextjs): add firebase-cookie-middleware with security hardening

Introduces the firebase-cookie-middleware package (v0.0.1) for
Next.js 14/15/16, taking over from PR #640 (James Daniels).

Security fixes applied during takeover review:
- Emulator explicit opt-in only (env var not auto-detected)
- JWT signature failure sets refreshable=false to prevent bypass
- Verify refreshed token before accepting it
- SSRF: loopback validation on emulator host
- CSRF: Origin check on POST/DELETE to /__cookies__
- CHIPS: SameSite=None on partitioned cookies
- JWKS eviction lock released in finally block
- Falsy-zero TTL: require ttlSeconds > 0 before caching
- Proxy targets validated; return 400 instead of throwing
- Optional chaining on JWT payload access
- Removed duplex: 'half' workaround (unnecessary in Node.js)

Next.js 16: adds proxy export (proxy.ts replaces middleware.ts
in Next.js 16 projects). proxy.ts runs on Node.js runtime only;
middleware.ts remains available for Edge Runtime (deprecated).

Also fixes pre-existing TypeScript strict-mode errors surfaced
by upgrading moduleResolution from node to bundler.

Ref: #640
Original work by: James Daniels (jamesdaniels@google.com)

Author: tyler-reitz

src/firestore.tsx

@@ -65,7 +65,7 @@ export function useFirestoreDocData<T = unknown>(ref: DocumentReference<T>, opti
   const observableId = `firestore:docData:${ref.firestore.app.name}:${ref.path}:idField=${idField}`;
   const observable = docData(ref, { idField });
 
-  return useObservable(observableId, observable, options);
+  return useObservable(observableId, observable, options) as ObservableStatus<T>;
 }
 
 /**
@@ -77,7 +77,7 @@ export function useFirestoreDocDataOnce<T = unknown>(ref: DocumentReference<T>,
   const observableId = `firestore:docDataOnce:${ref.firestore.app.name}:${ref.path}:idField=${idField}`;
   const observable$ = docData(ref, { idField }).pipe(first());
 
-  return useObservable(observableId, observable$, options);
+  return useObservable(observableId, observable$, options) as ObservableStatus<T>;
 }
 
 /**

src/nextjs/README.md

@@ -8,15 +8,15 @@ Enables **hybrid & Server-Side Rendered (SSR)** authentication in Next.js applic
 
 ## Why this exists
 
-Standard Single Page Applications (SPAs) store Firebase ID and refresh tokens inside browser `indexedDB` or `localStorage`. Because these storage mechanisms are inaccessible during HTTP requests, Next.js Server Components, API routes, Server Actions, and Middleware cannot read the user's authentication state on the first request—causing layout shifts, client-side redirect flashes, or insecure server routes.
+Standard Single Page Applications (SPAs) store Firebase ID and refresh tokens inside browser `indexedDB` or `localStorage`. Because these storage mechanisms are inaccessible during HTTP requests, Next.js Server Components, API routes, Server Actions, and Middleware cannot read the user's authentication state on the first request, causing layout shifts, client-side redirect flashes, or insecure server routes.
 
 `firebase-cookie-middleware` acts as the server-side companion to [`browserCookiePersistence`](https://firebase.google.com/docs/reference/js/auth#browsercookiepersistence). It proxies Firebase Auth token requests through `/_\_cookies_\_` on your app's domain, intercepts authentication exchanges, securely stores ID tokens and `httpOnly` refresh tokens in standard HTTP cookies, and strips sensitive refresh credentials from browser-facing payloads.
 
 ---
 
 ## Features
 
-- **⚡ 100% Edge Runtime Compatible**: Engineered specifically for Next.js 14 & 15 Edge Runtimes (Vercel Edge, Cloudflare Workers). Built on `jose` and Web APIs (`atob`, `fetch`) with zero reliance on Node.js `Buffer`.
+- **⚡ Next.js 14, 15, and 16 Compatible**: Built on `jose` and Web APIs (`atob`, `fetch`). Runs in the Edge Runtime via `middleware.ts` (Next.js 14/15, and Next.js 16 users keeping the deprecated Edge path) and the Node.js runtime via `proxy.ts` (Next.js 16 recommended).
 - **🛡️ Seamless Route Protection & Role Checking**: Intercept and verify Firebase ID tokens at the Edge before rendering pages or API routes. Access standard claims (`email`, `sub`) and arbitrary custom claims directly in your middleware.
 - **🚀 Distributed Caching (Memorystore / Redis)**: Optional distributed caching for Google's public JWKS signing keys and verified token payloads (`jwt:<idToken>`). Prevents unnecessary CPU verification and network requests on every navigation.
 - **🔒 Anti-DDoS Rotation Protection**: Distributed Redis locking (`firebase:jwks_eviction_lock`) ensures that during signing key rotations, only one Edge worker re-fetches Google's JWKS endpoints, preventing rate-limiting cascades.
@@ -33,11 +33,29 @@ npm install firebase-cookie-middleware jose lru-cache
 
 ---
 
+## Next.js 16 Migration
+
+Next.js 16 deprecates `middleware.ts` in favor of `proxy.ts`. The named export also changes from `middleware` to `proxy`.
+
+**Next.js 15 and earlier** (`src/middleware.ts`, Edge Runtime):
+```typescript
+export { middleware } from "firebase-cookie-middleware";
+```
+
+**Next.js 16+** (`src/proxy.ts`, Node.js runtime):
+```typescript
+export { proxy } from "firebase-cookie-middleware";
+```
+
+`proxy.ts` runs on the Node.js runtime only; the `runtime` config option is not available and will throw if set. If you need the Edge Runtime in Next.js 16, you can keep using `middleware.ts` with the `middleware` export (deprecated by Next.js but still functional). All middleware logic is identical between the two exports; only the file name and export name change.
+
+---
+
 ## Quickstart
 
-### 1. Create your Middleware (`src/middleware.ts`)
+### 1. Create your Middleware (`src/middleware.ts` for Next.js 15, `src/proxy.ts` for Next.js 16)
 
-Create or update your `middleware.ts` file in the root of your Next.js application:
+Create or update the file in the root of your Next.js application:
 
 ```typescript
 import { NextResponse, type NextRequest } from "next/server";
@@ -210,10 +228,23 @@ The middleware maintains two distinct cookies per app configuration (`appName`):
 
 When testing locally on `http://localhost`, Chrome and Safari reject secure host-prefixed cookies (`__HOST-`). The middleware automatically detects insecure local protocols and falls back to prefixed development cookies (`__dev_FIREBASE_[DEFAULT]`) with appropriate security flags.
 
-To connect with the Firebase Auth Emulator, export your emulator environment variable:
+To connect with the Firebase Auth Emulator, set `emulator: true` in your config and export the emulator host:
 
 ```bash
 export FIREBASE_AUTH_EMULATOR_HOST="localhost:9099"
 ```
 
-The middleware automatically accepts unsigned emulator tokens (`alg: "none"`) and proxies token refresh attempts directly to your local emulator instance.
+```typescript
+export const middleware = composeMiddleware(callback, {
+  options: firebaseConfig,
+  emulator: true, // reads FIREBASE_AUTH_EMULATOR_HOST; required to accept unsigned tokens
+});
+```
+
+You can also pass the host directly as a string instead of relying on the env var:
+
+```typescript
+emulator: "localhost:9099"
+```
+
+Emulator mode accepts unsigned tokens (`alg: "none"`) and proxies token refresh requests to your local emulator. The explicit opt-in is required: the env var alone does not activate emulator mode, preventing accidental acceptance of unsigned tokens if the variable leaks into a production environment.

src/nextjs/index.ts

@@ -25,6 +25,19 @@ export type FirebaseJWTPayload = JWTPayload & {
   [key: string]: unknown;
 };
 
+/**
+ * Cache abstraction used by this middleware.
+ *
+ * If you want to use a Redis client (ioredis, node-redis, Upstash, etc.) you
+ * must wrap it in an adapter that maps this interface to the client's own API.
+ * The options object uses lowercase `ex` / `nx` keys which do NOT match the
+ * native signatures of ioredis or node-redis v4 — pass them through with the
+ * appropriate translation in your adapter's `set()` implementation.
+ *
+ * The options object uses lowercase `ex` / `nx` keys, which do NOT match the
+ * native signatures of ioredis or node-redis v4; pass them through with the
+ * appropriate translation in your adapter's `set()` implementation.
+ */
 export interface CacheProvider {
   get<T = unknown>(key: string): Promise<T | null | undefined> | T | null | undefined;
   set(
@@ -46,7 +59,8 @@ export class MemoryCacheProvider implements CacheProvider {
   set(key: string, value: any, options?: { ex?: number; ttl?: number; nx?: boolean }): any {
     if (options?.nx && this.cache.has(key)) return null;
     const ttlSeconds = options?.ex ?? (options?.ttl ? Math.floor(options.ttl / 1000) : undefined);
-    const ttlMs = ttlSeconds ? ttlSeconds * 1000 : undefined;
+    // Treat 0 as "do not cache" (e.g. a max-age=0 from a server response).
+    const ttlMs = ttlSeconds !== undefined && ttlSeconds > 0 ? ttlSeconds * 1000 : undefined;
     this.cache.set(key, value, { ttl: ttlMs });
     return "OK";
   }
@@ -154,7 +168,9 @@ async function getFirebaseAuthJwks(
     }
 
     const jwks = (await response.json()) as JSONWebKeySet;
-    await cacheSetEx(cache, "firebase:jwks", maxAge, jwks);
+    if (maxAge > 0) {
+      await cacheSetEx(cache, "firebase:jwks", maxAge, jwks);
+    }
     return createLocalJWKSet(jwks);
   } catch (e) {
     console.error("Failed to fetch Firebase JWKS:", e);
@@ -197,7 +213,7 @@ export async function verifyFirebaseIdToken(
   if (
     jwtHeader?.typ !== "JWT" ||
     jwtPayload?.iss !== `https://securetoken.google.com/${projectId}` ||
-    jwtPayload.aud !== projectId ||
+    jwtPayload?.aud !== projectId ||
     jwtPayload?.firebase?.tenant !== tenantId
   ) {
     console.error("JWT Validation Mismatch", { jwtHeader, jwtPayload, projectId, tenantId });
@@ -237,9 +253,8 @@ export async function verifyFirebaseIdToken(
                   // Fetch fresh keys directly, skipping cache read
                   jwks = await getFirebaseAuthJwks(cache, true);
                   await jwtVerify(idToken, jwks);
-                } catch (fetchErr) {
+                } finally {
                   await cacheDelete(cache, "firebase:jwks_eviction_lock");
-                  throw fetchErr;
                 }
               } else {
                 throw verifyErr;
@@ -256,6 +271,7 @@ export async function verifyFirebaseIdToken(
           return [jwtPayload, isEmulatedCredential, true];
         } catch (e) {
           console.error("JWT Verification failed:", e);
+          refreshable = false;
         }
       }
     }
@@ -316,16 +332,19 @@ export async function runMiddleware(
   const REFRESH_TOKEN_COOKIE_NAME = isDevMode
     ? `__dev_FIREBASEID_${appName}`
     : `__HOST-FIREBASEID_${appName}`;
+  // CHIPS (Partitioned cookies) requires SameSite=None; Secure. When running
+  // on localhost with insecure cookies we fall back to SameSite=Lax (no partitioning).
+  const sameSite = useInsecureCookies ? ("lax" as const) : ("none" as const);
   const ID_TOKEN_COOKIE = {
-    path: "/",
+    path: "/" as const,
     secure: !useInsecureCookies,
-    httpOnly: false,
-    sameSite: "lax",
+    httpOnly: false as const,
+    sameSite,
     partitioned: !useInsecureCookies,
     name: ID_TOKEN_COOKIE_NAME,
     maxAge: MAX_MAX_AGE,
-    priority: "high",
-  } as const;
+    priority: "high" as const,
+  };
   const REFRESH_TOKEN_COOKIE = {
     ...ID_TOKEN_COOKIE,
     httpOnly: true,
@@ -339,6 +358,18 @@ export async function runMiddleware(
     }
 
     const method = request.method;
+
+    // CSRF guard: reject cross-origin state-changing requests.
+    // Browsers send the Origin header on cross-origin requests; same-origin
+    // requests from the Firebase JS SDK either omit Origin (safe) or send the
+    // correct same-site value.
+    if (method === "POST" || method === "DELETE") {
+      const origin = request.headers.get("origin");
+      if (origin && origin !== request.nextUrl.origin) {
+        return [new NextResponse("Cross-origin request denied", { status: 403 })];
+      }
+    }
+
     if (method === "DELETE") {
       const response = new NextResponse("");
       response.cookies.delete({ ...ID_TOKEN_COOKIE, maxAge: 0 });
@@ -376,14 +407,14 @@ export async function runMiddleware(
 
     if (options.emulatorHost) {
       if (url.host !== options.emulatorHost) {
-        throw new Error(`Emulator mismatch: ${url.host} vs ${options.emulatorHost}`);
+        return [new NextResponse("Proxy target does not match configured emulator host", { status: 400 })];
       }
     } else {
       if (
         url.host !== "securetoken.googleapis.com" &&
         url.host !== "identitytoolkit.googleapis.com"
       ) {
-        throw new Error(`Unauthorized proxy target host: ${url.host}`);
+        return [new NextResponse("Unauthorized proxy target host", { status: 400 })];
       }
     }
 
@@ -393,7 +424,7 @@ export async function runMiddleware(
     );
 
     if (!isTokenRequest && !isSignInRequest)
-      throw new Error("Could not determine the request type to proxy");
+      return [new NextResponse("Unsupported request type", { status: 400 })];
 
     if (isTokenRequest) {
       body = await request.text();
@@ -405,10 +436,13 @@ export async function runMiddleware(
           body = bodyParams.toString();
         }
       }
+    } else if (isSignInRequest) {
+      // Materialize body to a string so we never pass a ReadableStream to fetch,
+      // which is rejected by Vercel Edge and stricter undici configurations.
+      body = await request.text();
     }
 
-    // Duplex half, isn't NextJS fun?
-    const response = await fetch(url, { method, body, headers, duplex: "half" } as RequestInit);
+    const response = await fetch(url, { method, body, headers });
 
     const json = (await response.json()) as TokenResponse | SignInResponse;
     const status = response.status;
@@ -482,6 +516,14 @@ export async function runMiddleware(
     return logout();
   }
 
+  if (isEmulatedCredential && options.emulatorHost) {
+    const emulatorHostname = options.emulatorHost.split(":")[0];
+    if (emulatorHostname !== "localhost" && emulatorHostname !== "127.0.0.1" && emulatorHostname !== "::1") {
+      console.error("Emulator host must be localhost or loopback:", emulatorHostname);
+      return logout();
+    }
+  }
+
   const refreshUrl = new URL(
     isEmulatedCredential ? `http://${options.emulatorHost}` : `https://securetoken.googleapis.com`,
   );
@@ -511,14 +553,19 @@ export async function runMiddleware(
   const newRefreshToken = json.refresh_token;
   const newIdToken = json.id_token;
   if (!newIdToken) throw new Error("Missing id_token in refresh response");
-  // FIXED: Use jose decodeJwt for robust Edge support instead of Buffer/base64
-  const decodedPayload = decodeJwt(newIdToken) as FirebaseJWTPayload;
-  jwtPayload = decodedPayload;
-  const ttlMs = jwtPayload.exp! * 1000 - Date.now();
-  const ttlSeconds = Math.floor(ttlMs / 1000);
-  if (ttlSeconds > 0) {
-    await cacheSetEx(cache, `jwt:${newIdToken}`, ttlSeconds, jwtPayload);
+  // Full signature + claims verification on the refreshed token. Caching is
+  // handled inside verifyFirebaseIdToken, so no separate cacheSetEx needed.
+  const [verifiedNewPayload] = await verifyFirebaseIdToken(
+    newIdToken,
+    options.projectId,
+    options.tenantId,
+    cache,
+  );
+  if (!verifiedNewPayload) {
+    console.error("Refreshed token failed verification");
+    return logout();
   }
+  jwtPayload = verifiedNewPayload;
   const decorateNextResponse = (response: NextResponse) => {
     if (newIdToken) response.cookies.set({ ...ID_TOKEN_COOKIE, value: newIdToken });
     if (newRefreshToken) response.cookies.set({ ...REFRESH_TOKEN_COOKIE, value: newRefreshToken });
@@ -567,9 +614,11 @@ export const normalizeConfig = (
   };
   if (typeof config.emulator === "string") {
     normalizedConfig.emulatorHost = config.emulator;
-  } else if (config.emulator !== false) {
-    const emulatorHost = process.env.FIREBASE_AUTH_EMULATOR_HOST;
-    normalizedConfig.emulatorHost = emulatorHost;
+  } else if (config.emulator === true) {
+    // Explicit opt-in only: reading FIREBASE_AUTH_EMULATOR_HOST when emulator
+    // is not explicitly requested would accept alg:none tokens if that env var
+    // ever leaked into a production environment.
+    normalizedConfig.emulatorHost = process.env.FIREBASE_AUTH_EMULATOR_HOST;
   }
   return normalizedConfig;
 };
@@ -598,7 +647,6 @@ export const composeMiddleware =
       normalizedConfigurations.push({
         appName: "[DEFAULT]",
         firebaseOptions: defaultAppOptions,
-        emulatorHost: process.env.FIREBASE_AUTH_EMULATOR_HOST,
         cache: defaultMemoryCache,
       });
     }
@@ -625,7 +673,15 @@ export const composeMiddleware =
       const [response, decorateResponse, idTokenPayload] = result;
       if (idTokenPayload) allUsers[appName] = idTokenPayload;
       if (idTokenPayload && appName === defaultAppName) defaultUser = idTokenPayload;
-      if (response) finalResponse ||= response;
+      if (response) {
+        if (finalResponse) {
+          console.warn(
+            `firebase-cookie-middleware: app "${appName}" returned a direct response but an earlier app already claimed the response. The earlier response takes precedence.`,
+          );
+        } else {
+          finalResponse = response;
+        }
+      }
       if (decorateResponse) decorators.push(decorateResponse);
     }
     if (!finalResponse)
@@ -636,4 +692,23 @@ export const composeMiddleware =
     );
   };
 
-export const middleware = composeMiddleware(() => {});
+// Zero-config convenience export. Works only when a Firebase app has been
+// initialized before the middleware runs (e.g. via getApps() in firebase.ts).
+// If no Firebase config is discoverable the request passes through with a
+// console warning rather than throwing a 500.
+const _safeDefaultMiddleware = async (request: NextRequest): Promise<NextResponse> => {
+  const defaultAppOptions = getDefaultAppConfig() as FirebaseOptions | undefined;
+  if (!defaultAppOptions) {
+    console.warn(
+      "firebase-cookie-middleware: no Firebase config found; pass a Config to composeMiddleware.",
+    );
+    return NextResponse.next();
+  }
+  return composeMiddleware(() => {})(request);
+};
+
+// Next.js 16+: proxy.ts expects a named `proxy` export.
+export const proxy = _safeDefaultMiddleware;
+// Next.js 15 and earlier: middleware.ts expects a named `middleware` export.
+// @deprecated Use proxy in Next.js 16+.
+export const middleware = _safeDefaultMiddleware;

src/nextjs/middleware_cache.node.test.ts

@@ -43,7 +43,7 @@ describe("CacheProvider plugin paths", () => {
       get: mockCacheGet,
       set: mockCacheSet,
       setex: mockCacheSetex,
-    };
+    } as unknown as CacheProvider;
   });
 
   it("should return cached payload from CacheProvider during verifyFirebaseIdToken", async () => {

src/nextjs/middleware_config.node.test.ts

@@ -89,10 +89,17 @@ describe("normalizeConfig", () => {
     expect(normalized.tenantId).toBe("acme");
   });
 
-  it("should read emulator from env when emulator is undefined (not false)", () => {
+  it("should NOT read emulator from env when emulator is undefined (explicit opt-in required)", () => {
     process.env.FIREBASE_AUTH_EMULATOR_HOST = "localhost:9099";
     const config: Config = { options: mockFirebaseOptions };
     const normalized = normalizeConfig(config, undefined);
+    expect(normalized.emulatorHost).toBeUndefined();
+  });
+
+  it("should read emulator from env when emulator is explicitly true", () => {
+    process.env.FIREBASE_AUTH_EMULATOR_HOST = "localhost:9099";
+    const config: Config = { options: mockFirebaseOptions, emulator: true };
+    const normalized = normalizeConfig(config, undefined);
     expect(normalized.emulatorHost).toBe("localhost:9099");
   });