iron-session 8.0.3 → 9.0.0-beta.0

package/MIGRATION.md

@@ -0,0 +1,123 @@
+# Migration guide
+
+## v8 to v9
+
+Most apps need two changes: Node 22 and one line if you store a `Date` in the
+session. Everything else below is either a type error TypeScript will point at,
+or a bug fix you want.
+
+### Requirements
+
+- **Node 22.12 or later.** Node 20 reached end of life in April 2026.
+- **The package is ESM-only.** There is no CommonJS build. `require()` still
+  works on Node 22.12+, which supports `require()` of an ES module, so most CJS
+  code keeps working. If you are bundling for an older target, keep v8.
+
+### Do this
+
+**1. Store timestamps, not `Date` objects.**
+
+```diff
+- session.lastSeen = new Date();
++ session.lastSeen = Date.now();
+```
+
+v8 quietly turned a `Date` into an ISO string when sealing and handed you back a
+string when reading, so the type you wrote out was not the type you got back.
+v9 throws with a message naming the fix instead.
+
+**2. Check for missing session data.**
+
+`IronSession<T>` properties are optional on read now, so this stops compiling:
+
+```diff
+- const userId = session.user.id;
++ const userId = session.user?.id;
+```
+
+A session that does not exist yet is an empty object. The old type claimed
+otherwise, so `session.user.id` compiled and threw on a first visit, on an
+expired cookie, and after `destroy()`.
+
+**3. Do not `save()` after `destroy()`.**
+
+`destroy()` is terminal now, and `save()` after it throws. Before, the save
+re-sealed the session and the browser kept the last `Set-Cookie`, so the logout
+silently did not happen.
+
+**4. Pass a real password to `updateConfig()`.**
+
+`updateConfig()` now rebuilds the whole configuration, including the password,
+and validates it. Before, a new password passed here was ignored: it kept
+sealing with the old one and skipped the 32-character check. If you were
+relying on that, you were not rotating anything.
+
+### Nothing to do
+
+- **`getIronSession(req, res, options)` still works.** Express, Connect, plain
+  Node and pages-router API routes need no change.
+- **`getIronSession(await cookies(), options)` still works**, and now typechecks
+  without a cast. If you had `as any` or
+  `as unknown as CookieStore` there, delete it.
+- **Cookies stay valid.** v9 reads v8 cookies, and v8 reads v9 cookies, so you
+  can roll back a deploy without signing everyone out.
+
+### Removed
+
+- **Pre-v8 cookies (iron-session v6 and earlier) are no longer read.** Those
+  users sign in once more. The format was selected by a version marker that sat
+  outside the seal's signature, which meant an attacker could flip it and
+  reshape the session without knowing the password.
+- **`createSealData`, `createUnsealData` and `createGetIronSession` are gone.**
+  They existed to inject a `crypto` implementation, which is no longer a thing
+  anyone needs to pass. Import `sealData`, `unsealData` and `getIronSession`
+  directly.
+- **`uncrypto` is no longer a dependency.** If you were pinning or aliasing it to
+  work around bundler problems, most notably `getRandomValues is not a function`
+  under Turbopack, you can drop that.
+
+### New
+
+- **`onUnsealError(reason, error)`** tells you when a cookie could not be read
+  and why (`"expired"`, `"invalid"`, `"unknown-password"`). Worth wiring to your
+  logger: a burst of `"unknown-password"` means a broken password rotation, and
+  a burst of `"invalid"` can mean someone is probing your cookies.
+- **`chunk: true`** splits a session that does not fit in one cookie across
+  several. Read the size warnings in the README first.
+- **Adapters** for the runtimes that needed them:
+  - `nextProxyCookies(request, response)` for Next.js `proxy.ts` (called
+    `middleware.ts` before Next 16). This is the fix if saving a session in
+    middleware never seemed to take effect.
+  - `nodeCookies(req, res)` and `webCookies(request, responseOrHeaders)` if you
+    want to be explicit instead of relying on the `(req, res, options)` form.
+
+### Rotating a session in Next.js middleware
+
+This did not work before. A cookie written in middleware only reaches the
+current render when it goes through `response.cookies.set()`, so `session.save()`
+appeared to succeed and then vanished.
+
+```ts
+// proxy.ts (middleware.ts before Next 16)
+import { NextResponse, type NextRequest } from "next/server";
+import { getIronSession, nextProxyCookies } from "iron-session";
+
+export async function proxy(request: NextRequest) {
+  const response = NextResponse.next();
+  const session = await getIronSession(nextProxyCookies(request, response), options);
+
+  session.lastSeen = Date.now();
+  await session.save();
+
+  return response;
+}
+```
+
+## v6 to v8
+
+See the [v8 release notes](https://github.com/vvo/iron-session/releases/tag/v8.0.0).
+The short version: `withIronSessionApiRoute` and `withIronSessionSsr` are gone,
+call `getIronSession(req, res, options)` directly instead.
+
+Going from v6 straight to v9 works, but those cookies are not readable by v9, so
+plan for everyone to sign in once.

package/README.md

@@ -2,32 +2,13 @@
 
 **`iron-session` is a secure, stateless, and cookie-based session library for JavaScript.**
 
-<div align="right"><sub><i>our sponsor:</i></sup></div>
-
----
-<div align="center">
-  <a href="https://clerk.com">
-    <picture>
-      <source width="200px" media="(prefers-color-scheme: dark)" srcset="./sponsor/clerk-light.svg">
-      <source width="200px" media="(prefers-color-scheme: light)" srcset="./sponsor/clerk-dark.svg">
-      <img width="200px" src="./sponsor/clerk-dark.svg" />
-    </picture>
-  </a>
-   <p align="center">Clerk is a complete suite of embeddable UIs, flexible APIs, and admin dashboards to authenticate and manage your users.</p>
-   <p align="center">
-      <a href="https://go.clerk.com/198WZf0">
-        <b>Add authentication in 7 minutes 👉</b>
-      </a>
-   </p>
-</div>
-
 ---
 
 The session data is stored in signed and encrypted cookies which are decoded by your server code in a stateless fashion (= no network involved). This is the same technique used by frameworks like
 [Ruby On Rails](https://guides.rubyonrails.org/security.html#session-storage).
 
 <p align="center"><i>Online demo and examples: <a href="https://get-iron-session.vercel.app/">https://get-iron-session.vercel.app</a></i> 👀 <br/>
- <i>Featured in the <a href="https://nextjs.org/docs/authentication">Next.js documentation</a></i> ⭐️</p>
+ <i>Featured in the <a href="https://nextjs.org/docs/app/guides/authentication">Next.js documentation</a></i> ⭐️</p>
 
 ## Table of Contents
 
@@ -35,6 +16,10 @@ The session data is stored in signed and encrypted cookies which are decoded by
 - [Installation](#installation)
 - [Usage](#usage)
 - [Examples](#examples)
+- [Runtimes](#runtimes)
+- [Session size](#session-size)
+- [Watching for unreadable cookies](#watching-for-unreadable-cookies)
+- [Validating session data](#validating-session-data)
 - [Project status](#project-status)
 - [Session options](#session-options)
 - [API](#api)
@@ -61,13 +46,13 @@ pnpm add iron-session
 
 ## Usage
 
-*We have extensive examples here too: https://get-iron-session.vercel.app/.*
+_We have extensive examples here too: https://get-iron-session.vercel.app/._
 
 To get a session, there's a single method to know: `getIronSession`.
 
 ```ts
 // Next.js API Routes and Node.js/Express/Connect.
-import { getIronSession } from 'iron-session';
+import { getIronSession } from "iron-session";
 
 export async function get(req, res) {
   const session = await getIronSession(req, res, { password: "...", cookieName: "..." });
@@ -83,16 +68,16 @@ export async function post(req, res) {
 
 ```ts
 // Next.js Route Handlers (App Router)
-import { cookies } from 'next/headers';
-import { getIronSession } from 'iron-session';
+import { cookies } from "next/headers";
+import { getIronSession } from "iron-session";
 
 export async function GET() {
-  const session = await getIronSession(cookies(), { password: "...", cookieName: "..." });
+  const session = await getIronSession(await cookies(), { password: "...", cookieName: "..." });
   return session;
 }
 
 export async function POST() {
-  const session = await getIronSession(cookies(), { password: "...", cookieName: "..." });
+  const session = await getIronSession(await cookies(), { password: "...", cookieName: "..." });
   session.username = "Alison";
   await session.save();
 }
@@ -100,12 +85,12 @@ export async function POST() {
 
 ```tsx
 // Next.js Server Components and Server Actions (App Router)
-import { cookies } from 'next/headers';
-import { getIronSession } from 'iron-session';
+import { cookies } from "next/headers";
+import { getIronSession } from "iron-session";
 
 async function getIronSessionData() {
-  const session = await getIronSession(cookies(), { password: "...", cookieName: "..." });
-  return session
+  const session = await getIronSession(await cookies(), { password: "...", cookieName: "..." });
+  return session;
 }
 
 async function Profile() {
@@ -115,22 +100,134 @@ async function Profile() {
 }
 ```
 
+```ts
+// Next.js proxy.ts (middleware.ts before Next 16)
+import { NextResponse, type NextRequest } from "next/server";
+import { getIronSession, nextProxyCookies } from "iron-session";
+
+export async function proxy(request: NextRequest) {
+  const response = NextResponse.next();
+  const session = await getIronSession(nextProxyCookies(request, response), options);
+
+  session.lastSeen = Date.now();
+  await session.save();
+
+  return response;
+}
+```
+
+Middleware needs the adapter because Next only merges a cookie into the current
+render when it goes through `response.cookies.set()`. Writing a raw `Set-Cookie`
+header there looks like it works and then has no effect.
+
 ## Examples
 
 We have many different patterns and examples on the online demo, have a look: https://get-iron-session.vercel.app/.
 
+## Runtimes
+
+`getIronSession(req, res, options)` covers Node, Express, Connect and Next.js
+API routes, and `getIronSession(await cookies(), options)` covers the Next.js App
+Router. When you want to be explicit, or when your framework hands you something
+else, pass an adapter instead:
+
+| Adapter                                  | For                                                                        |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| `nodeCookies(req, res)`                  | Node `http`, Express, Connect, Next.js API routes                          |
+| `webCookies(request, responseOrHeaders)` | Anything web-standard: Hono, Bun, Deno, Cloudflare Workers, Route Handlers |
+| `nextProxyCookies(request, response)`    | Next.js `proxy.ts` / `middleware.ts`                                       |
+
+Anything with `get(name)` and `set(name, value, options)`, like Next's
+`cookies()`, can be passed directly. If your framework has neither, a cookie jar
+is two functions:
+
+```ts
+const session = await getIronSession(
+  {
+    read: (name) => myFramework.getCookie(name),
+    write: (name, value, options) => myFramework.setCookie(name, value, options),
+  },
+  options,
+);
+```
+
+## Session size
+
+A browser refuses a cookie over 4096 bytes, and iron-session throws rather than
+letting one be silently dropped. Encryption adds overhead, so plan for roughly
+3KB of actual data.
+
+If you need more, `chunk: true` splits the session across several cookies. Before
+you reach for it, know what the real limit is: every cookie is sent on **every
+request**, and proxies cap the whole `Cookie` header well below what a few
+chunks produce. nginx allows 8KB by default and a CDN in front of it may allow
+less. Going over returns a 400 or 431 at the edge, before your code runs.
+iron-session refuses more than 4 chunks for that reason.
+
+The scalable answer is to keep an id in the session and the data in your
+database:
+
+```ts
+session.userId = user.id; // small, stateless
+const user = await db.user.findUnique({ where: { id: session.userId } });
+```
+
+## Watching for unreadable cookies
+
+When a cookie cannot be read, iron-session starts a new empty session instead of
+throwing. It has to: it cannot tell a tampered cookie from a password you
+rotated out or a seal that simply expired, and a 500 on every request would be
+worse. That makes real problems invisible, so log them:
+
+```ts
+const options = {
+  cookieName: "session",
+  password: process.env.SESSION_PASSWORD,
+  onUnsealError: (reason, error) => {
+    // "expired" is normal, that is how sessions end.
+    if (reason !== "expired") {
+      logger.warn({ reason, error }, "session cookie rejected");
+    }
+  },
+};
+```
+
+A burst of `"unknown-password"` usually means a password rotation went wrong. A
+burst of `"invalid"` can mean someone is probing your cookies.
+
+## Validating session data
+
+There is no `validate` option, on purpose. If you change the shape of your
+session, old cookies still decrypt into the old shape, and the place to handle
+that is the wrapper you already have:
+
+```ts
+// lib/session.ts
+export async function getSession() {
+  const session = await getIronSession<Session>(await cookies(), options);
+
+  if (session.user && !SessionSchema.safeParse({ ...session }).success) {
+    session.destroy();
+  }
+
+  return session;
+}
+```
+
 ## Project status
 
 ✅ Production ready and maintained.
 
 ## Session options
 
-Two options are required: `password` and `cookieName`. Everything else is automatically computed and usually doesn't need to be changed.****
+Two options are required: `password` and `cookieName`. Everything else is automatically computed and usually doesn't need to be changed.
 
-- `password`, **required**: Private key used to encrypt the cookie. It has to be at least 32 characters long. Use <https://1password.com/password-generator/> to generate strong passwords. `password` can be either a `string` or an `object` with incrementing keys like this: `{2: "...", 1: "..."}` to allow for password rotation.  iron-session will use the highest numbered key for new cookies.
+- `password`, **required**: Private key used to encrypt the cookie. It has to be at least 32 characters long. Use <https://1password.com/password-generator/> to generate strong passwords. `password` can be either a `string` or an `object` with incrementing keys like this: `{2: "...", 1: "..."}` to allow for password rotation. iron-session will use the highest numbered key for new cookies.
 - `cookieName`, **required**: Name of the cookie to be stored
-- `ttl`, _optional_: In seconds. Default to the equivalent of 14 days. You can set this to `0` and iron-session will compute the maximum allowed value by cookies.
-- `cookieOptions`, _optional_: Any option available from [jshttp/cookie#serialize](https://github.com/jshttp/cookie#cookieserializename-value-options) except for `encode` which is not a Set-Cookie Attribute. See [Mozilla Set-Cookie Attributes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes) and [Chrome Cookie Fields](https://developer.chrome.com/docs/devtools/application/cookies/#fields). Default to:
+- `ttl`, _optional_: In seconds. Default to the equivalent of 14 days. Setting it to `0` means the seal never expires, which also means it can never be revoked: do not use `0` for authentication.
+- `chunk`, _optional_: Split a session that does not fit in one cookie across several cookies. Defaults to `false`. See [Session size](#session-size) before turning it on.
+- `onUnsealError`, _optional_: Called when an existing cookie could not be read, with a reason of `"expired"`, `"invalid"` or `"unknown-password"`. The session is reset to empty either way, so this is for logging. See [Watching for unreadable cookies](#watching-for-unreadable-cookies).
+- `cookieOptions`, _optional_: Any [Set-Cookie attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes) supported by [jshttp/cookie](https://github.com/jshttp/cookie). Default to:
 
   ```js
   {
@@ -149,7 +246,7 @@ Two options are required: `password` and `cookieName`. Everything else is automa
 ```ts
 type SessionData = {
   // Your data
-}
+};
 
 const session = await getIronSession<SessionData>(req, res, sessionOptions);
 ```
@@ -159,7 +256,7 @@ const session = await getIronSession<SessionData>(req, res, sessionOptions);
 ```ts
 type SessionData = {
   // Your data
-}
+};
 
 const session = await getIronSession<SessionData>(cookies(), sessionOptions);
 ```
@@ -169,7 +266,7 @@ const session = await getIronSession<SessionData>(cookies(), sessionOptions);
 Saves the session. This is an asynchronous operation. It must be done and awaited before headers are sent to the client.
 
 ```ts
-await session.save()
+await session.save();
 ```
 
 ### `session.destroy(): void`
@@ -177,7 +274,7 @@ await session.save()
 Destroys the session. This is a synchronous operation as it only removes the cookie. It must be done before headers are sent to the client.
 
 ```ts
-session.destroy()
+session.destroy();
 ```
 
 ### `session.updateConfig(sessionOptions: SessionOptions): void`