getSession() always persists a new empty session cookie with no opt-out

[MILLERMARRU]

Describe the bug

getSession() always creates and persists a brand new session (writes a Set-Cookie) whenever no existing session is found, with no way to opt out of just that side effect.

In src/utils/session.ts:

// New session store in response cookies
if (!session.id) {
  session.id = config.generateId?.() ?? (config.crypto || crypto).randomUUID();
  session.createdAt = Date.now();
  await updateSession(event, config);
}

Any call to getSession(event, config) for a request that doesn't already carry a valid session cookie/header falls into this branch and immediately calls updateSession, which seals and sets the cookie. This happens even when the caller is just checking "is there a session" (e.g. auth middleware peeking at whether a user is logged in) rather than intending to start one, since getSession's name and most other usages in the codebase read as a read-only accessor.

I checked SessionConfig for something to opt out of just this behavior. cookie?: false | (...) does gate the Set-Cookie write inside updateSession (if (config.cookie !== false && ...)), but it's all-or-nothing, setting it disables cookie persistence for every updateSession call, including legitimate ones with real session data, not just the eager empty-session case from getSession. There's no config option scoped to "don't auto-create and persist an empty session just from calling getSession."

Steps to reproduce

import { getSession } from "h3";

app.use(async (event) => {
  // Just checking whether a session exists, not intending to create one
  const session = await getSession(event, { password: "...".repeat(4) });
  console.log(session.data); // {}
});

Any request without an existing session cookie/header will receive a Set-Cookie in the response from this handler, even though nothing was ever written to session.data.

Expected behavior

getSession should be able to read/lazily-initialize a session in memory for the current request without necessarily persisting an empty session to the client, at least optionally, since callers who only read session state shouldn't be forced to also start issuing session cookies for anonymous visitors.

Actual behavior

getSession unconditionally persists a newly created empty session via updateSession whenever no session previously existed, regardless of whether the caller goes on to write any data to it.

[anneheartrecord]

Reproduced on main (502c59f). A read-only handler does emit the cookie:

app.get("/", async (event) => {
  const s = await getSession(event, { password });
  return s.data; // {}
});
// -> 1 Set-Cookie: h3=Fe26.2**...; Path=/; HttpOnly; Secure; SameSite=Lax

And cookie: false is not a workaround: with it, updateSession(event, config, { user: "alice" }) emits zero cookies too, so real writes stop persisting as well.

There is a second cost that is easy to miss. Because updateSession falls back to getSession when the context has no session yet, a plain login handler seals twice in one request. Counting crypto.subtle.deriveBits calls (2 per seal):

handler	derivations
await updateSession(event, cfg, { user })	4
await getSession(event, cfg), anonymous	2

The first seal's cookie value is overwritten later in the same response, so with seal.integrity.iterations at 8192 since #1457 that is a wasted PBKDF2 pass on every request that starts a session.

I tried the minimal lazy variant, keeping the id/createdAt assignment in the new-session branch and dropping the await updateSession(event, config):

• anonymous GET: 0 Set-Cookie, 0 derivations
• POST calling session.update({ foo: "bar" }): 1 Set-Cookie, 2 derivations
• GET back with that cookie: same id, data intact, no cookie rewrite

test/session.test.ts goes 12/20 red under it, but only three assertions are really affected. initiates session, sets SameSite=Lax by default and allows overriding SameSite via config.cookie all read getSetCookie()[0] off a read-only GET; the other nine cascade from the cookie variable shared across the tests. The actual behavioral change is that an anonymous visitor no longer keeps a stable id across requests, since nothing is written until something is stored.

Three shapes seem plausible:

1. lazy by default, and update those three tests. One line, but breaking for anyone relying on the anonymous id.
2. a SessionConfig opt-out, e.g. persistNew?: boolean.
3. an option on getSession only, leaving useSession eager.

Happy to send a PR for whichever you prefer. Following your note on #1507 I would rather not guess the API here. The analysis above is agent-assisted; every number in it was measured locally against 502c59f.

[MILLERMARRU]

This is a much more thorough reproduction than what I had, appreciate the follow-through, especially catching the double-seal cost on updateSession's fallback path, that wasn't in my original report at all.

Of the three shapes, I'd lean toward 3 (scope it to getSession, leave useSession eager).

Checked session.ts on main: useSession already calls getSession with the comment // Force init right there in its own source:

export async function useSession<T extends SessionData = SessionData>(
  event: HTTPEvent,
  config: SessionConfig,
): Promise<SessionManager<T>> {
  const sessionName = config.name || DEFAULT_SESSION_NAME;
  await getSession(event, config); // Force init
  ...

So the "eager" behavior isn't incidental, useSession is documented, in its own implementation, as the thing that forces a session to exist. That's a real signal about intent: useSession is presumably what most people reach for when they actually want a stable session identity across requests (auth flows, carts, anything that should persist), and changing its default would be a behavior change for that whole population for the sake of fixing a function whose name is literally getSession, read semantics, not write semantics.

Option 1 (lazy everywhere) fixes the report but takes that same breaking change to useSession callers who are relying on anonymous id stability, which is probably a much larger blast radius than "someone called getSession in a read-only handler." Option 2 (a SessionConfig opt-out) works but adds a public config surface for something that's arguably just getSession not honoring what its own name promises, once getSession stops writing on a bare read, there's nothing left needing an opt-out.

The awkward part of 3 is threading it through: useSession needs to force-persist while a bare getSession call doesn't, and today useSession just calls getSession with no way to say "and mean it." An internal-only parameter (not part of the public SessionConfig) that useSession passes and everyone else doesn't seems like the minimal-surface way to do that, keeps getSession's public signature unchanged, just makes it lazy by default the way its name suggests it already should be.

[anneheartrecord]

Went with 3, per your reasoning above (it matches useSession's own "Force init" comment as a signal of intent, and keeps the change scoped to getSession reading, not useSession's write-oriented default).

Implementation: getSession now only assigns id/createdAt in memory on a new session and defers the actual cookie write until something is stored via updateSession. useSession passes an internal-only flag (not part of SessionConfig) to force the eager persist it already documents, so its behavior and the public getSession/useSession signatures are unchanged.

That fallback path also turned out to double-seal: updateSession's own internal getSession() call was eagerly persisting the new session before updateSession sealed it again with the real write, i.e. two PBKDF2 derivations for one request. With getSession lazy, that fallback no longer persists early, so it's back to one seal.

Tests added (test/session.test.ts):

• a bare getSession read-only call emits zero Set-Cookie headers (confirmed this fails on current main, passes with the fix)
• updateSession creating a brand-new session calls crypto.subtle.deriveBits exactly twice, not four times (confirmed same red→green)

All 22 existing session tests are untouched and still pass, since they all go through useSession. Full pnpm test (lint + typecheck + full vitest + coverage) is green.

Branch on my fork if you want to look before I open a PR: anneheartrecord/h3@h3js:main...anneheartrecord:fix/getsession-lazy-cookie

@pi0 following your note on #1507 about checking before attempting a PR — @MILLERMARRU picked the shape above as the issue reporter, but I'd rather have your nod too before opening a PR. Happy to open it as soon as either of you says go.

[ShreeBohara]

Reproduced on main (1892ee9), a handler that only reads emits a cookie:

app.get("/", async (event) => {
  const s = await getSession(event, { password });
  return s.data;   // {}
});
// -> 1 Set-Cookie

Two things I measured while checking it. cookie: false isn't a workaround:
with it, updateSession(event, cfg, { user: "alice" }) emits zero cookies, so
real writes stop persisting as well.

And a plain login handler seals twice. Counting crypto.subtle.deriveBits
(2 per seal), updateSession(event, cfg, { user }) on its own costs 4, because
updateSession falls back to getSession, which persists the empty session
before the real write seals it again. Same numbers @anneheartrecord posted
above, arrived at separately.

@anneheartrecord you said on 12 Aug you had option 3 implemented. Are you still
planning to open that? Happy to leave it with you. If you've moved on I can
pick it up.

@pi0 flagging per your note on #1507: the analysis was agent-assisted, and I ran
the repro and the suite on this machine. Wanted to confirm option 3 is the shape
you want before anyone writes the PR.