feat(nextjs): support Next.js 15 async cookies() in getSessionFromCookies

Next.js 15 made cookies() async (returns a Promise). The helper duck-typed
on .get, missed it on the Promise, and returned null — a silent 'not logged
in'. It now resolves a thenable store and returns a Promise; a non-thenable
store still returns synchronously, so existing Next.js <=14 callers that did
not await keep working (non-breaking). Also documents a middleware.ts / Edge
example (NextRequest.cookies) and the returnTo-in-redirectTo, non-HttpOnly,
and chunked-cookie caveats.

Author: boyander

README.md

@@ -314,25 +314,71 @@ createClient({ domain, clientId, storage: memoryStorage })
 
 ## Next.js / server-side
 
-Use cookie storage on the client, then read the session from `next/headers` on
-the server:
+Use `storage: 'cookie'` on the client, then read the session on the server with
+`getSessionFromCookies`. It returns the full `Session` (`access_token`,
+`refresh_token`, `expires_at`, `user`) or `null`, and accepts the `cookies()`
+object from `next/headers`, a `NextRequest.cookies` object, or a plain
+`{ name: value }` map.
+
+`getSessionFromCookies` is **async** — always `await` it. In Next.js 15+,
+`cookies()` is also async, so `await` that too:
 
 ```ts
-// app/page.tsx
+// app/page.tsx (Next.js 15+)
 import { cookies } from 'next/headers'
 import { getSessionFromCookies } from '@faable/auth-js'
 
 export default async function Page() {
-  const session = getSessionFromCookies(cookies(), { clientId: '<client_id>' })
+  const session = await getSessionFromCookies(await cookies(), {
+    clientId: '<client_id>'
+  })
   if (!session) return <SignIn />
   return <Dashboard user={session.user} />
 }
 ```
 
+On Next.js 14 and earlier `cookies()` is synchronous — drop the inner `await`
+(`await getSessionFromCookies(cookies(), …)`).
+
+### Gating routes in middleware (Edge)
+
+To keep protected content from ever reaching the browser without a session, gate
+it in `middleware.ts`. Pass `req.cookies` (a `NextRequest.cookies` object)
+directly:
+
+```ts
+// middleware.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { getSessionFromCookies } from '@faable/auth-js'
+
+export async function middleware(req: NextRequest) {
+  const session = await getSessionFromCookies(req.cookies, {
+    clientId: '<client_id>'
+  })
+  if (!session) return NextResponse.redirect(new URL('/login', req.url))
+  return NextResponse.next()
+}
+
+export const config = { matcher: ['/((?!login|_next|favicon.ico).*)'] }
+```
+
 Pass the same `clientId` you used in `createClient`. If you also passed a custom
 `storageKey` to `createClient`, mirror it here as `{ clientId, storageKey }` so
 the helper looks at the same cookie.
 
+> **Security note.** This library writes the session cookie from JavaScript, so
+> it **cannot** be `HttpOnly` — an XSS can read the `access_token`. Treat XSS
+> prevention (CSP, escaping) as a hard requirement. The cookie may also be
+> **chunked** across `faableauth-<clientId>.0`, `.1`, … when large;
+> `getSessionFromCookies` reassembles the chunks for you, but any code that
+> reads the cookie by hand (another backend, an edge worker) must rejoin them.
+
+> **`returnTo` vs `redirectTo`.** Don't embed `returnTo` inside the `redirectTo`
+> query (e.g. `redirectTo: '/callback?returnTo=/x'`) — pass `returnTo` as its
+> own option (`signInWith…({ returnTo: '/x' })`). The SDK stores it locally next
+> to the PKCE verifier and round-trips it back to you; keep `redirectTo` a clean
+> URL with no query.
+
 ## Documentation
 
 For the full guides, API reference, and dashboard setup walkthroughs visit

src/lib/nextjs.ts

@@ -10,31 +10,75 @@ import { Session } from './types'
  * adapter builds the storage key and reassembles chunked cookies, so no
  * extra wiring is required.
  *
- * @param cookiesStore Either the result of `cookies()` from `next/headers`,
- *   or any plain `{ name: value }` map. Adapters with a `get(name)` method
- *   are detected automatically.
+ * @param cookiesStore The result of `cookies()` from `next/headers`
+ *   (Next.js 15+ returns a Promise — pass it directly or pre-awaited, both
+ *   work), a `NextRequest.cookies` object (for `middleware.ts` / Edge), or any
+ *   plain `{ name: value }` map. Adapters with a `get(name)` method are
+ *   detected automatically.
  * @param options `{ clientId, storageKey? }`. `storageKey` defaults to the
  *   library's built-in prefix — only set it when you customized
  *   `storageKey` in `createClient`.
- * @returns The decoded {@link Session} or `null` when the cookie is absent
- *   or malformed.
+ * @returns The decoded {@link Session} or `null` when the cookie is absent or
+ *   malformed. When `cookiesStore` is a Promise (Next.js 15 `cookies()`) the
+ *   result is a Promise that resolves to the same; otherwise it is returned
+ *   synchronously (Next.js ≤14). `await` works either way, so always `await`.
  * @example
  * ```ts
- * // app/page.tsx
+ * // app/page.tsx (Next.js 15 — cookies() is async)
  * import { cookies } from 'next/headers'
  * import { getSessionFromCookies } from '@faable/auth-js'
  *
  * export default async function Page() {
- *   const session = getSessionFromCookies(cookies(), {
+ *   const session = await getSessionFromCookies(await cookies(), {
  *     clientId: '<client_id>'
  *   })
  *   if (!session) return <SignIn />
  *   return <Dashboard user={session.user} />
  * }
  * ```
+ * @example
+ * ```ts
+ * // middleware.ts — gate routes at the edge before any HTML is sent
+ * import { NextRequest, NextResponse } from 'next/server'
+ * import { getSessionFromCookies } from '@faable/auth-js'
+ *
+ * export async function middleware(req: NextRequest) {
+ *   const session = await getSessionFromCookies(req.cookies, {
+ *     clientId: '<client_id>'
+ *   })
+ *   if (!session) return NextResponse.redirect(new URL('/login', req.url))
+ *   return NextResponse.next()
+ * }
+ * ```
  * @see {@link https://faable.com/docs/auth/quickstart/nextjs | Next.js Quickstart}
  */
-export const getSessionFromCookies = (
+export function getSessionFromCookies(
+  cookiesStore: Promise<unknown>,
+  options: { clientId: string; storageKey?: string }
+): Promise<Session | null>
+export function getSessionFromCookies(
+  cookiesStore: unknown,
+  options: { clientId: string; storageKey?: string }
+): Session | null
+export function getSessionFromCookies(
+  cookiesStore: any,
+  options: { clientId: string; storageKey?: string }
+): Session | null | Promise<Session | null> {
+  // Next.js 15 made `cookies()` async: it returns a Promise, so callers may
+  // pass it un-awaited. When given a thenable we resolve it and return a
+  // Promise; otherwise we stay synchronous so existing Next.js ≤14 callers
+  // (which relied on the sync return) keep working unchanged. `await` works
+  // on both shapes, so the recommended `await getSessionFromCookies(...)` is
+  // always correct.
+  if (cookiesStore && typeof cookiesStore.then === 'function') {
+    return (cookiesStore as Promise<unknown>).then(store =>
+      parseSession(store, options)
+    )
+  }
+  return parseSession(cookiesStore, options)
+}
+
+const parseSession = (
   cookiesStore: any,
   options: { clientId: string; storageKey?: string }
 ): Session | null => {

tests/unit/getSessionFromCookies.test.ts

@@ -17,49 +17,99 @@ const DEFAULT_KEY = `${STORAGE_KEY}-${CLIENT_ID}`
 const encoded = encodeURIComponent(JSON.stringify(validSession))
 
 describe('getSessionFromCookies', () => {
-  it('parses a session from a Next.js cookies() store using clientId', () => {
+  it('parses a session from a Next.js cookies() store using clientId', async () => {
     const cookiesStore = {
       get(name: string) {
         return name === DEFAULT_KEY ? { name, value: encoded } : undefined
       }
     }
     expect(
-      getSessionFromCookies(cookiesStore, { clientId: CLIENT_ID })
+      await getSessionFromCookies(cookiesStore, { clientId: CLIENT_ID })
     ).toEqual(validSession)
   })
 
-  it('parses a session from a plain object map using clientId', () => {
+  it('parses a session from a plain object map using clientId', async () => {
     const cookiesStore = { [DEFAULT_KEY]: encoded }
     expect(
-      getSessionFromCookies(cookiesStore, { clientId: CLIENT_ID })
+      await getSessionFromCookies(cookiesStore, { clientId: CLIENT_ID })
     ).toEqual(validSession)
   })
 
-  it('honours a custom storageKey override', () => {
+  it('honours a custom storageKey override', async () => {
     const customKey = `mi-prefix-${CLIENT_ID}`
     const cookiesStore = { [customKey]: encoded }
     expect(
-      getSessionFromCookies(cookiesStore, {
+      await getSessionFromCookies(cookiesStore, {
         clientId: CLIENT_ID,
         storageKey: 'mi-prefix'
       })
     ).toEqual(validSession)
   })
 
-  it('returns null when the cookie is absent', () => {
+  it('returns null when the cookie is absent', async () => {
     expect(
-      getSessionFromCookies({ get: () => undefined }, { clientId: CLIENT_ID })
+      await getSessionFromCookies(
+        { get: () => undefined },
+        {
+          clientId: CLIENT_ID
+        }
+      )
     ).toBeNull()
-    expect(getSessionFromCookies({}, { clientId: CLIENT_ID })).toBeNull()
+    expect(await getSessionFromCookies({}, { clientId: CLIENT_ID })).toBeNull()
   })
 
-  it('returns null when the cookie value is malformed JSON', () => {
+  it('returns null when the cookie value is malformed JSON', async () => {
     const cookiesStore = { [DEFAULT_KEY]: encodeURIComponent('{not-json') }
     expect(
-      getSessionFromCookies(cookiesStore, { clientId: CLIENT_ID })
+      await getSessionFromCookies(cookiesStore, { clientId: CLIENT_ID })
     ).toBeNull()
   })
 
+  // Next.js 15 made `cookies()` async — callers may pass the un-awaited
+  // Promise. Before this was async-aware the duck-typing missed `.get` on the
+  // Promise and returned null silently.
+  describe('Next.js 15 async cookies()', () => {
+    it('awaits a Promise-wrapped cookies() store', async () => {
+      const cookiesStore = {
+        get(name: string) {
+          return name === DEFAULT_KEY ? { name, value: encoded } : undefined
+        }
+      }
+      expect(
+        await getSessionFromCookies(Promise.resolve(cookiesStore), {
+          clientId: CLIENT_ID
+        })
+      ).toEqual(validSession)
+    })
+
+    it('awaits a Promise-wrapped plain object map', async () => {
+      const store = { [DEFAULT_KEY]: encoded }
+      expect(
+        await getSessionFromCookies(Promise.resolve(store), {
+          clientId: CLIENT_ID
+        })
+      ).toEqual(validSession)
+    })
+
+    it('returns null for a Promise resolving to no session', async () => {
+      expect(
+        await getSessionFromCookies(Promise.resolve({}), {
+          clientId: CLIENT_ID
+        })
+      ).toBeNull()
+    })
+
+    // Backward compatibility: a non-thenable store must still return
+    // synchronously so existing Next.js ≤14 callers that don't `await` keep
+    // working (a Promise here would be truthy and silently "always logged in").
+    it('stays synchronous for a non-Promise store', () => {
+      const store = { [DEFAULT_KEY]: encoded }
+      const result = getSessionFromCookies(store, { clientId: CLIENT_ID })
+      expect(result).not.toBeInstanceOf(Promise)
+      expect(result).toEqual(validSession)
+    })
+  })
+
   describe('chunked cookies', () => {
     const split = (str: string, size: number): string[] => {
       const out: string[] = []
@@ -68,7 +118,7 @@ describe('getSessionFromCookies', () => {
       return out
     }
 
-    it('reassembles `key.0`, `key.1`, … from a Next.js cookies() store', () => {
+    it('reassembles `key.0`, `key.1`, … from a Next.js cookies() store', async () => {
       const chunks = split(encoded, 50)
       const store = {
         get(name: string) {
@@ -78,30 +128,30 @@ describe('getSessionFromCookies', () => {
           return idx < chunks.length ? { name, value: chunks[idx] } : undefined
         }
       }
-      expect(getSessionFromCookies(store, { clientId: CLIENT_ID })).toEqual(
-        validSession
-      )
+      expect(
+        await getSessionFromCookies(store, { clientId: CLIENT_ID })
+      ).toEqual(validSession)
     })
 
-    it('reassembles chunks from a plain object map', () => {
+    it('reassembles chunks from a plain object map', async () => {
       const chunks = split(encoded, 50)
       const store: Record<string, string> = {}
       chunks.forEach((c, i) => {
         store[`${DEFAULT_KEY}.${i}`] = c
       })
-      expect(getSessionFromCookies(store, { clientId: CLIENT_ID })).toEqual(
-        validSession
-      )
+      expect(
+        await getSessionFromCookies(store, { clientId: CLIENT_ID })
+      ).toEqual(validSession)
     })
 
-    it('prefers a single un-chunked cookie when both shapes are present', () => {
+    it('prefers a single un-chunked cookie when both shapes are present', async () => {
       const store = {
         [DEFAULT_KEY]: encoded,
         [`${DEFAULT_KEY}.0`]: 'stale-garbage'
       }
-      expect(getSessionFromCookies(store, { clientId: CLIENT_ID })).toEqual(
-        validSession
-      )
+      expect(
+        await getSessionFromCookies(store, { clientId: CLIENT_ID })
+      ).toEqual(validSession)
     })
   })
 })