feat(session): default session cookie to SameSite=Lax

pi0 · claude · pi0 · commit acf8d77bf15d · 2026-07-14T09:41:33.000Z
No SameSite attribute was set on the sealed session cookie. Chrome
defaults to Lax, but Firefox/Safari are inconsistent, leaving the
cookie attached to cross-site requests (CSRF surface). Overridable
via config.cookie (including sameSite: false to omit it).

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/docs/4.examples/handle-session.md b/docs/4.examples/handle-session.md
@@ -142,6 +142,9 @@ app.use(async (event) => {
 
 Every option is optional except `password`. The `name` option is worth calling out: it sets the cookie used to store the session and defaults to `h3`. H3 also reads the session from a request header derived from `name`, which it normalizes to lowercase as `x-${name.toLowerCase()}-session`, so the default name `h3` produces the `x-h3-session` header seen earlier. A mixed-case `name` like `MyApp` still resolves to a lowercase `x-myapp-session` header, while the cookie keeps the original casing. That default is why the earlier examples set a cookie named `h3`.
 
+> [!NOTE]
+> The session cookie defaults to `secure: true`, `httpOnly: true`, `sameSite: "lax"`, and `path: "/"`. Any of these can be overridden via `cookie`.
+
 > [!NOTE]
 > The `secure: true` option tells the browser to only store and send the cookie over HTTPS. When developing locally over plain HTTP, compliant browsers (notably Safari and iOS, and Chrome on some local domains) silently drop the cookie, so the session will not persist. Set `cookie: { secure: false }` during local development to work around this.
 
diff --git a/src/utils/internal/session.ts b/src/utils/internal/session.ts
@@ -12,4 +12,5 @@ export const DEFAULT_SESSION_COOKIE: SessionConfig["cookie"] = {
   path: "/",
   secure: true,
   httpOnly: true,
+  sameSite: "lax",
 };
diff --git a/src/utils/session.ts b/src/utils/session.ts
@@ -42,7 +42,7 @@ export interface SessionConfig {
   maxAge?: number;
   /** default is h3 */
   name?: string;
-  /** Default is secure, httpOnly, / */
+  /** Default is secure, httpOnly, sameSite lax, / */
   cookie?: false | (CookieSerializeOptions & { chunkMaxLength?: number });
   /** Default is x-h3-session / x-{name}-session */
   sessionHeader?: false | string;
diff --git a/test/session.test.ts b/test/session.test.ts
@@ -37,6 +37,33 @@ describeMatrix("session", (t, { it, expect }) => {
     });
   });
 
+  it("sets SameSite=Lax by default", async () => {
+    const result = await t.fetch("/");
+    expect(result.headers.getSetCookie()[0]).toContain("SameSite=Lax");
+  });
+
+  it("allows overriding SameSite via config.cookie", async () => {
+    t.app.get("/strict", async (event) => {
+      const session = await useSession(event, {
+        ...sessionConfig,
+        cookie: { sameSite: "strict" },
+      });
+      return { session };
+    });
+    const strict = await t.fetch("/strict");
+    expect(strict.headers.getSetCookie()[0]).toContain("SameSite=Strict");
+
+    t.app.get("/none", async (event) => {
+      const session = await useSession(event, {
+        ...sessionConfig,
+        cookie: { sameSite: false },
+      });
+      return { session };
+    });
+    const none = await t.fetch("/none");
+    expect(none.headers.getSetCookie()[0]).not.toContain("SameSite");
+  });
+
   it("gets same session back", async () => {
     const result = await t.fetch("/", { headers: { Cookie: cookie } });
     expect(await result.json()).toMatchObject({
