refactor: drop cookie sealing with bidirectional migration

[nicknisi]

Closes #425

Summary

• Session cookies (wos-session) are now written as plain JSON instead of iron-sealed blobs
• Reader auto-detects format via Fe26. prefix — existing iron-sealed cookies are transparently unsealed
• On next token refresh, legacy cookies are rewritten as plain JSON (zero-downtime migration)
• PKCE state remains iron-sealed regardless — those values appear in OAuth state URL parameters
• Malformed cookie values are now gracefully handled (return no session instead of throwing)

Why this is safe

• Session cookies are httpOnly, secure, sameSite=lax — browser JS cannot read them
• PKCE verifier cookies remain iron-sealed — the sealed blob appears in URLs where plaintext would expose the codeVerifier
• Iron seals are unambiguously detectable via Fe26. prefix — no collision with JSON (JSON.stringify always starts with {, [, or ")

Migration behavior

Seamless. The adapter reads both formats, so existing users with iron-sealed cookies are never rejected. On next token refresh the cookie is rewritten as JSON. No re-auth, no downtime.

Mirrors the approach in workos/authkit-session#31.

---

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🔴 Raw JSON in Set-Cookie header breaks when session data contains semicolons

After the migration from sealData (which produces URL-safe base64) to JSON.stringify, the raw JSON output is placed directly into a Set-Cookie header at line 319 without URL-encoding. If any session field (e.g., user's firstName, lastName, email, or metadata) contains a semicolon (;), the browser's cookie parser will interpret it as a cookie attribute delimiter, truncating the cookie value. This produces malformed JSON that fails to parse on subsequent requests, causing session loss.

Demonstration of the truncation

For a user with firstName: "John; Drop", the Set-Cookie header becomes:

wos-session={"accessToken":"eyJ...","user":{"firstName":"John; Drop"}}; Path=/; HttpOnly; ...

The browser parses the value as {"accessToken":"eyJ...","user":{"firstName":"John — everything after the first ; in the JSON is treated as cookie attributes. The stored cookie is malformed JSON that decryptSession cannot parse.

Note that saveSession (src/session.ts:640) uses nextCookies.set() which internally URL-encodes the value via the cookie package's serialize function, so it is not affected. Only the middleware refresh path at line 319, which manually constructs the raw header string, is vulnerable.

(Refers to line 319)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[nicknisi]

Good catch — this was a real gap. The saveSession path was safe (nextCookies.set URL-encodes internally), but this middleware refresh path built the header string manually.

Fixed in 91654ee — the value is now wrapped in encodeURIComponent(). The cookie read side (request.cookies.get() / nextCookies.get()) auto-decodes, so decryptSession receives raw JSON as expected.

For reference, authkit-session was already safe here — its serializeCookie helper uses encodeURIComponent(value) at the serialization layer.