Cookies

RFC 6265 cookie plumbing — parse, serialize, and sealed (vault- gated) cookies in one primitive. Replaces the ad-hoc Set-Cookie strings that used to live in middleware and route handlers.

Two surfaces:

1. Module-level (stateless): b.cookies.parse / b.cookies.serialize / b.cookies.parseSafe. Useful in test fixtures and code paths that don't have a vault wired.

2. Instance (b.cookies.create): bound defaults for cookie attributes, a wired vault for sealed reads/writes, and request/response helpers (read / write / clear / writeSealed / readSealed).

Defaults mirror modern browser expectations: HttpOnly on, Secure on, SameSite=Lax, Path=/. Operators developing locally over plain http opt out of Secure explicitly so the production posture isn't silently weakened.

Cookie-prefix invariants from RFC 6265bis §4.1.3 are enforced at serialize time: __Secure-* requires Secure; __Host-* requires Secure + Path=/ + no Domain. Operator typos (__Host- cookie without Path=/) throw at the source instead of silently failing on the browser side.

Header-injection defense: cookie names are RFC 6265 tokens; values reject CRLF / NUL / semicolon / comma pre-encoding, then percent- encode on write and percent-decode on read. Domain / Path attributes are CRLF/NUL-scrubbed before they reach Set-Cookie.

Sealed cookies wrap the value in a vault.seal envelope: without the framework's vault key no client can hand-craft a valid value, so curl-with-arbitrary-cookies (or any tool that hasn't been through the framework's crypto flow) can't reach a sealed-cookie- gated endpoint. The vault prefix is stripped on write and re-added on read so the cookie carries only the compact base64 envelope.

b.cookies.parse(cookieHeader) #

Lenient RFC 6265 Cookie-header parser. Returns a plain object { name: value } with last-write-wins semantics (matching every browser). Surrounding double-quotes are stripped per §5.2 and values are percent-decoded; malformed pairs are silently dropped because that's how browsers behave. For the threat-detecting variant that surfaces issues instead of dropping silently, use parseSafe.

var jar = b.cookies.parse("session=abc; theme=dark%20mode");
// → { session: "abc", theme: "dark mode" }   // percent-decoded

b.cookies.serialize(name, value, attrs) #

{
  maxAge:      3600,        // integer seconds; emits `Max-Age=`
  expires:     new Date(),  // Date or parseable date string
  domain:      "example.com",
  path:        "/",
  httpOnly:    true,
  secure:      true,
  sameSite:    "Lax",       // "Strict" / "Lax" / "None"
  partitioned: false,       // CHIPS partitioning
  priority:    "Medium",    // "Low" / "Medium" / "High"
}

Build a single Set-Cookie header value from a name, value, and attributes object. Validates the name as an RFC 6265 token, the value against CRLF / NUL / ; / ,, and enforces the __Secure- / __Host- prefix invariants from RFC 6265bis §4.1.3. SameSite is normalized to Strict / Lax / None, and SameSite=None implicitly turns Secure on so browsers don't silently drop the cookie. Throws CookieError on any invariant break — the operator sees the typo at the call site, not as a silently-missing cookie.

var header = b.cookies.serialize("__Host-sid", "abc", {
  httpOnly: true,
  secure:   true,
  sameSite: "Lax",
  path:     "/",
  maxAge:   3600,
});
// → "__Host-sid=abc; Max-Age=3600; Path=/; HttpOnly; SameSite=Lax; Secure"

b.cookies.create(opts) #

{
  vault:    b.vault,                 // required for sealed* methods
  defaults: {
    httpOnly: true,
    secure:   true,
    sameSite: "Lax",
    path:     "/",
    maxAge:   604800,                // seconds (7 days)
  },
}

Build a cookie helper bound to a default attribute set and an optional vault. Returned object exposes read(req, name), write(res, name, value, attrs), clear(res, name, attrs), and (when a vault is wired) writeSealed / readSealed for vault- gated cookie values. Per-call attrs merge over the bound defaults so callers override piecewise.

var cookies = b.cookies.create({
  vault:    b.vault,
  defaults: { httpOnly: true, secure: true, sameSite: "Lax", path: "/" },
});
cookies.write(res, "theme", "dark", { maxAge: 86400 });
cookies.writeSealed(res, "session", "u-1");
var sid = cookies.readSealed(req, "session");
// → "u-1" or null

b.cookies.parseSafe(cookieHeader, opts) #

{
  maxHeaderBytes: 8192,    // total Cookie-header byte cap
  maxNameBytes:   256,     // per-name byte cap
  maxValueBytes:  4096,    // per-value byte cap
}

Threat-detecting inbound-cookie parser. Returns { jar, issues } where every detected anomaly surfaces as an issue instead of being silently dropped (as the lenient parse does). Detected issues: oversized header / pair, duplicate cookie name (cookie-tossing class), malformed pair, CR / LF / NUL in the raw header (proxy-side injection vector), and non-string input. Issue shape: { kind, severity: "high" | "warn", snippet, name? }.

var result = b.cookies.parseSafe("session=abc; session=evil", {
  maxHeaderBytes: 8192,
});
// → { jar: { session: "evil" },
//     issues: [{ kind: "duplicate-name", severity: "high",
//                name: "session", snippet: "..." }] }

Last updated 2026-08-08T16:39:49.652Z by seeder.