@blamejs/core 0.18.40 → 0.18.41

package/CHANGELOG.md

@@ -8,6 +8,24 @@ upgrading across more than a few patches at a time.
 
 ## v0.18.x
 
+- v0.18.41 (2026-08-20) — **Logout can now clear the session cookie on a plain-HTTP origin, and every Set-Cookie the framework writes goes through one validating writer.** `b.session.logout` built its expiry cookie by string concatenation with `Secure` hardcoded. A browser refuses a `Secure` cookie that arrives over plain HTTP, so on a cleartext deployment the header was discarded and the session cookie the logout existed to clear stayed in the jar. `b.middleware.csrfProtect` had its own cookie formatter with the same shape and a different consequence: it interpolated the configured `cookie.path` into the response header with no CRLF scrub. Both now compose `b.cookies`, which is the framework's single Set-Cookie writer. **Added:** *`b.cookies.assertAppendable(res)`* — Throws unless a response can carry an appended `Set-Cookie` — the same check `appendSetCookie` performs, exposed so a caller can run it before doing something it cannot undo. A response has to be readable as well as writable to be appended to: without `appendHeader` the merge happens in the framework and needs to see what is already queued, and a response carrying only `setHeader` would have its existing cookies silently replaced. `b.session.logout` calls it up front, because it revokes the session row before queueing the expiry cookie — a refusal at queue time would leave the session destroyed, the browser still holding its cookie, and the request failing. · *`b.cookies.appendSetCookie(res, header)`* — Queues one `Set-Cookie` header without discarding the ones already queued. `res.setHeader("Set-Cookie", value)` replaces the header, so a route that issues a session cookie and then a CSRF cookie sends only the second; `Set-Cookie` is the one response header that is legitimately repeated. The appender uses `res.appendHeader` where the runtime offers it and array-merges where it does not.
+
+It pairs with `b.cookies.serialize`, which validates and builds the header string. `b.cookies.create().write()` and `.clear()` compose both; reach for the two separately when you need to build the header at one point in a flow and queue it at another — validating early, emitting only once the side effect it accompanies has succeeded, which is what `b.session.logout` does with the session row. **Changed:** *`b.session.logout` queues its expiry cookie rather than overwriting the header* — It called `res.setHeader("Set-Cookie", ...)`, which discarded any cookie the route had already queued — a rotated CSRF token, a locale. It now appends. Code reading `res.getHeader("Set-Cookie")` after a logout sees an array of header strings rather than a single string; Node accepts either form on the way out.
+
+`logout` also validates its options object, so a misspelled key is reported instead of silently ignored, and the expiry cookie is now built before the session row is revoked. Building it can fail — a `__Host-` name without `Secure` is refused — and a failure after the revoke would leave the session destroyed with the browser still holding its cookie. · *esbuild 0.28.1 to 0.28.2 (build tooling only)* — esbuild builds the single-file executable the bundler-output gate checks; it is a devDependency and does not ship. The published tarballs differ only in version strings, one new documented API option (`logStyle`), and the refreshed per-platform binary hash map, with a byte-identical `install.js` and an unchanged `postinstall` script. The reviewed SHA-256 for the two platforms the build runs on — CI's `linux-x64` and the maintainer host's `win32-x64` — are recorded in `scripts/esbuild-binary-pin.json` and verified against the binaries npm actually served. **Security:** *`b.session.logout` resolves the `Secure` attribute instead of hardcoding it* — The expiry cookie was emitted as `sid=; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=0`, with `Secure` present unconditionally. A user agent rejects a `Secure` cookie set from a non-secure origin, so on a plain-HTTP deployment neither this header nor the `Clear-Site-Data` queued beside it (also gated on a secure context) could clear the session cookie. The server-side row was already destroyed, so the revoked token was never usable — what remained was a cookie the user could not get rid of by logging out, sent on every later request.
+
+`logout` now takes the transport as input. Pass `req` and the scheme is resolved through `b.requestHelpers.trustedProtocol`, which honours a forwarded scheme only from a peer you have declared trusted; pass `secure` to state it outright. With neither, the cookie is `Secure` — the previous behaviour, and still the default.
+
+The cookie's scope is now describable too. A browser matches an expiry cookie on name, path and domain, so a session cookie written with `Domain=example.com` or `Path=/app` could not be cleared by an expiry cookie that named neither. `logout` accepts `path`, `domain` and `sameSite`. · *A configured CSRF cookie path can no longer split the response header* — `b.middleware.csrfProtect` formatted its own `Set-Cookie` and interpolated `cookie.path` into it directly. A configured path containing a bare CR or LF ended the header there and let whatever followed be read as a header of its own. The attributes now pass through `b.cookies.serialize`, which scrubs CR and NUL from `Domain` and `Path` before they reach the wire, validates the cookie name as an RFC 6265 token, and refuses CRLF, NUL, semicolon or comma in the value.
+
+One further consequence of routing through it: a CSRF cookie configured `sameSite: "None"` now always carries `Secure`, which the SameSite specification requires and which the middleware's own formatter did not add. A `SameSite=None` cookie without `Secure` is rejected by browsers, so this affects a configuration that could not have been working. · *A `__Host-` or `__Secure-` CSRF cookie name now requires an explicit `cookie.secure: true`* — Those prefixes are a promise to the browser that the cookie is always `Secure`, and RFC 6265bis §4.1.3 has user agents drop a cookie that carries the prefix without it. Leaving `cookie.secure` to per-request auto-detection breaks that promise on any cleartext request: the cookie went out prefixed and without `Secure`, the browser discarded it, and the double-submit token silently never persisted — every request then looked like a first visit. The existing boot check could not see this, because the decision was made per request rather than at configuration time.
+
+Configuring a prefixed name now fails at boot unless `cookie.secure: true` is set. A cookie name with no prefix keeps auto-detection, so the default configuration is unchanged. **Detectors:** *`Set-Cookie` may only be written by `b.cookies`* — A `codebase-patterns` entry refuses `setHeader`/`appendHeader` for `Set-Cookie` anywhere outside `lib/cookies.js`. Both defects above came from a file building the header itself and each losing a different guarantee, and one of them carried a comment recording that it did not route through `b.cookies.serialize`. · *A local may not reuse the name of a required module binding* — An eslint rule using scope analysis reports a `var`, `let` or `const` that takes the name of a module the file requires. `var` hoists, so such a local owns the name for the whole enclosing function — including the lines above its own declaration — and a call further down reads the local with no clue nearby that it is no longer the module. This is not hypothetical: it happened while making the change above, and surfaced as `cookies.serialize is not a function` where `cookies` was a parsed request jar.
+
+Parameters are deliberately out of scope. They shadow the same way but are part of the signature the reader has just read, and naming a SQL-string parameter `sql` or a connection-handle parameter `db` is the clearest name available.
+
+Seventeen further instances across `lib/` are resolved with it. Six were an inline `require` of a module the file already required at the top, and are removed rather than renamed. **References:** [RFC 6265bis §4.1.3 — Cookie Name Prefixes](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis) · [W3C Clear-Site-Data](https://www.w3.org/TR/clear-site-data/)
+
 - v0.18.40 (2026-08-19) — **DMARC policy discovery now walks the DNS tree, so a policy at an intermediate label is no longer missed.** `b.mailAuth` resolved DMARC policy with a two-step lookup — the Author Domain, then the organizational domain from the Public Suffix List. RFC 9989 §4.10 specifies a tree walk that queries every ancestor in turn, and the difference is not academic: for `a.b.example.com` a `p=reject` published at `_dmarc.b.example.com` was never queried, evaluated as `none`, and mail the domain owner intended to reject was delivered.
 
 The walk is now implemented, including the spec's denial-of-service bound and its rules for choosing the Organizational Domain.

package/README.md

@@ -88,7 +88,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
   - Opaque-userId anonymous sessions via `create({ anonymous: true })`
   - Idle / absolute timeouts, fingerprint drift detection + anomaly scoring, brute-force lockout
   - Session-fixation rotation (`b.session.rotate`) re-keys the sid-bound device fingerprint to the new id — pass the same `{ req, fingerprintFields }` used at `create` (a fingerprint-bound session rotated without `req` is refused, so the binding can never silently break or false-drift)
-  - One-call secure logout (`b.session.logout(res, token)`) destroys the session AND wipes client-side state — emits an W3C Clear-Site-Data header (cookies + storage + cache) and expires the session cookie before deleting the row
+  - One-call secure logout (`b.session.logout(res, token, { req })`) destroys the session AND wipes client-side state — revokes the row first, then emits a W3C Clear-Site-Data header (cookies + storage + cache) and an expiry cookie beside it. Pass `req` and the `Secure` attribute follows the request's scheme through `b.requestHelpers.trustedProtocol`, so the expiry cookie is not discarded by a browser on a plain-HTTP origin; `path` / `domain` / `sameSite` describe the cookie being cleared when it was written with a narrower scope
 - **Authorization** — RBAC + per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`)
 - **Workflow gates** — break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule m-of-n approval with cooling-off lock + cancellation (`b.dualControl`)
 - **Financial / Open Banking** — FAPI 2.0 Final composite posture (PAR + PKCE-S256 + DPoP-or-mTLS + RFC 9207); runtime enforcement helpers `b.fapi2.assertCallback` (refuses missing iss + bare-param under message-signing) and `b.fapi2.assertAuthzRequest` (refuses non-JAR); CFPB §1033 / FDX 6.0 consumer-financial-data-sharing wrapper (`b.fdx`)

package/lib/acme.js

@@ -100,16 +100,16 @@ function _publicJwkFromKeyObject(keyObject) {
   if (!keyObject || typeof keyObject.export !== "function") {
     throw _err("acme/bad-account-key", "accountKey must expose a Node KeyObject (export)", true);
   }
-  var jwk;
-  try { jwk = keyObject.export({ format: "jwk" }); }
+  var exported;
+  try { exported = keyObject.export({ format: "jwk" }); }
   catch (e) { throw _err("acme/bad-account-key", "accountKey export(jwk) failed: " + e.message, true); }
-  if (!jwk || jwk.kty !== "EC" || jwk.crv !== "P-256") {
+  if (!exported || exported.kty !== "EC" || exported.crv !== "P-256") {
     throw _err("acme/bad-account-key",
       "accountKey must be a P-256 EC keypair (RFC 8555 §6.2 ES256); got kty=" +
-      (jwk && jwk.kty) + " crv=" + (jwk && jwk.crv), true);
+      (exported && exported.kty) + " crv=" + (exported && exported.crv), true);
   }
   // RFC 7638 thumbprint inputs MUST be sorted alphabetically + minimal-JSON.
-  return Object.freeze({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y });
+  return Object.freeze({ crv: exported.crv, kty: exported.kty, x: exported.x, y: exported.y });
 }
 
 function _jwkThumbprint(publicJwk) {
@@ -1247,7 +1247,6 @@ function create(opts) {
       throw _err("acme/bad-token", "tlsAlpn01KeyAuthorization: token must be a non-empty string", true);
     }
     var keyAuth = token + "." + _jwkThumbprint(publicJwk);
-    var nodeCrypto  = require("node:crypto");
     return nodeCrypto.createHash("sha256").update(keyAuth, "utf8").digest();
   }
 
@@ -1348,7 +1347,6 @@ function create(opts) {
       throw _err("acme/bad-ttl",
         "dnsAccount01ChallengeRecord: ttl must be a positive integer <= 86400 seconds", true);
     }
-    var nodeCrypto = require("node:crypto");
     // Account label: lowercase base32 of first 10 bytes of SHA-256(accountUrl)
     // (per draft-ietf-acme-dns-account-label §3.1 — 80-bit truncated label).
     var hash = nodeCrypto.createHash("sha256").update(state.accountUrl, "utf8").digest();

package/lib/audit.js

@@ -1963,8 +1963,8 @@ function generateActorBindingTriggerSql(opts) {
  */
 async function assertSegregation(opts) {
   opts = opts || {};
-  var db = opts.db || null;
-  if (!db || typeof db.query !== "function") {
+  var externalDb = opts.db || null;
+  if (!externalDb || typeof externalDb.query !== "function") {
     throw new AuditSegregationError("audit/segregation-no-db",
       "audit.assertSegregation: opts.db with a query() method is required");
   }
@@ -1976,11 +1976,11 @@ async function assertSegregation(opts) {
   // Operator-DB system-catalog introspection (Postgres pg_proc / pg_trigger,
   // $N-native, against the operator-supplied db.query) — not a framework
   // table, so b.sql's verb builders don't apply.
-  var fnRes = await db.query(
+  var fnRes = await externalDb.query(
     "SELECT 1 FROM pg_proc WHERE proname = $1 LIMIT 1", [fnName]             // allow:hand-rolled-sql
   );
   var fnPresent = !!(fnRes && fnRes.rows && fnRes.rows.length > 0);
-  var trigRes = await db.query(
+  var trigRes = await externalDb.query(
     "SELECT 1 FROM pg_trigger WHERE tgname = $1 LIMIT 1", [trigName]         // allow:hand-rolled-sql
   );
   var trigPresent = !!(trigRes && trigRes.rows && trigRes.rows.length > 0);

package/lib/auth/dpop.js

@@ -219,16 +219,16 @@ async function buildProof(opts) {
       "alg '" + alg + "' is not supported by DPoP");
   }
 
-  var jwk = opts.jwk || _publicJwkFromPrivate(key);
+  var proofKey = opts.jwk || _publicJwkFromPrivate(key);
   // Strip private parts from the embedded jwk if the operator passed a
   // private JWK by accident — ONLY public components belong in the proof.
   var pubJwk;
-  if (jwk.kty === "EC") pubJwk = { kty: "EC", crv: jwk.crv, x: jwk.x, y: jwk.y };
-  else if (jwk.kty === "OKP") pubJwk = { kty: "OKP", crv: jwk.crv, x: jwk.x };
-  else if (jwk.kty === "RSA") pubJwk = { kty: "RSA", e: jwk.e, n: jwk.n };
-  else if (jwk.kty === "AKP") pubJwk = { kty: "AKP", alg: jwk.alg, pub: jwk.pub };
+  if (proofKey.kty === "EC") pubJwk = { kty: "EC", crv: proofKey.crv, x: proofKey.x, y: proofKey.y };
+  else if (proofKey.kty === "OKP") pubJwk = { kty: "OKP", crv: proofKey.crv, x: proofKey.x };
+  else if (proofKey.kty === "RSA") pubJwk = { kty: "RSA", e: proofKey.e, n: proofKey.n };
+  else if (proofKey.kty === "AKP") pubJwk = { kty: "AKP", alg: proofKey.alg, pub: proofKey.pub };
   else throw new AuthError("auth-dpop/refused-kty",
-    "jwk.kty='" + jwk.kty + "' is not allowed");
+    "jwk.kty='" + proofKey.kty + "' is not allowed");
 
   var jti = opts.jti || _b64urlEncode(nodeCrypto.randomBytes(C.BYTES.bytes(16)));
   var nowMs = (typeof opts.iat === "number" ? opts.iat * C.TIME.seconds(1) : Date.now());

package/lib/cert.js

@@ -514,22 +514,22 @@ function create(opts) {
   }
 
   async function _issueCert(certManifest) {
-    var acme = _bootAcme();
+    var acmeClient = _bootAcme();
     // 1. Fetch directory + ensure ACME account exists.
-    await acme.fetchDirectory();
-    await acme.newAccount({
+    await acmeClient.fetchDirectory();
+    await acmeClient.newAccount({
       contact:              opts.acme.contactEmail ? ["mailto:" + opts.acme.contactEmail] : undefined,
       termsOfServiceAgreed: true,
     });
     // 2. Create the order.
-    var order = await acme.newOrder({
+    var order = await acmeClient.newOrder({
       identifiers: certManifest.domains.map(function (d) {
         return { type: "dns", value: d };
       }),
     });
     // 3. For each authorization, solve the operator-supplied challenge.
     for (var ai = 0; ai < order.authorizations.length; ai += 1) {
-      var auth = await acme.fetchAuthorization(order.authorizations[ai]);
+      var auth = await acmeClient.fetchAuthorization(order.authorizations[ai]);
       if (auth.status === "valid") continue;
       var challenge = auth.challenges.find(function (ch) {
         return ch.type === certManifest.challenge.type;
@@ -541,8 +541,8 @@ function create(opts) {
       }
       // tls-alpn-01 has a different key-authorization shape (RFC 8737).
       var keyAuth = certManifest.challenge.type === "tls-alpn-01"
-        ? acme.tlsAlpn01KeyAuthorization(challenge.token)
-        : acme.keyAuthorization(challenge.token);
+        ? acmeClient.tlsAlpn01KeyAuthorization(challenge.token)
+        : acmeClient.keyAuthorization(challenge.token);
       var provisionParams = {
         domain:           auth.identifier.value,
         type:             challenge.type,
@@ -551,8 +551,8 @@ function create(opts) {
       };
       await certManifest.challenge.provision(provisionParams);
       try {
-        await acme.notifyChallengeReady(challenge.url);
-        await acme.waitForAuthorization(order.authorizations[ai]);
+        await acmeClient.notifyChallengeReady(challenge.url);
+        await acmeClient.waitForAuthorization(order.authorizations[ai]);
       } finally {
         try { await certManifest.challenge.cleanup(provisionParams); }
         catch (cleanupErr) {
@@ -568,13 +568,13 @@ function create(opts) {
     }
     // 4. Generate leaf keypair + CSR + finalize.
     var leafPair = _generateLeafKeypair(certManifest.keyAlg);
-    var csrPem = acme.buildCsr({
+    var csrPem = acmeClient.buildCsr({
       privateKey: leafPair.privateKey,
       publicKey:  leafPair.publicKey,
       domains:    certManifest.domains,
     });
-    var finalized = await acme.finalize(order, csrPem);
-    var certPem = await acme.retrieveCert(finalized);
+    var finalized = await acmeClient.finalize(order, csrPem);
+    var certPem = await acmeClient.retrieveCert(finalized);
     var privPem = leafPair.privateKey.export({ type: "pkcs8", format: "pem" });
     return { certPem: certPem, keyPem: privPem };
   }

package/lib/compliance-sanctions.js

@@ -200,15 +200,15 @@ function parseUn1267Entry(entry) {
   if (!entry || typeof entry !== "object") return null;
   var name = entry.NAME || entry.name || entry.FIRST_NAME || "";
   if (!name) return null;
-  var aliases = [];
-  if (Array.isArray(entry.ALIASES)) aliases = entry.ALIASES.slice();
+  var entryAliases = [];
+  if (Array.isArray(entry.ALIASES)) entryAliases = entry.ALIASES.slice();
   else if (typeof entry.ALIAS_NAMES === "string") {
-    aliases = entry.ALIAS_NAMES.split(";").map(function (s) { return s.trim(); }).filter(Boolean);
+    entryAliases = entry.ALIAS_NAMES.split(";").map(function (s) { return s.trim(); }).filter(Boolean);
   }
   return {
     id:          "UN-1267-" + String(entry.REFERENCE_NUMBER || entry.DATAID || ""),
     primaryName: String(name).trim(),
-    aliases:     aliases,
+    aliases:     entryAliases,
     type:        entry.NAME_TYPE === "Entity" ? "entity" : "individual",
     programs:    ["UN-1267"],
     country:     entry.COUNTRY || entry.NATIONALITY || null,

package/lib/cookies.js

@@ -324,18 +324,100 @@ function serialize(name, value, attrs) {
   return parts.join("; ");
 }
 
-// Append a Set-Cookie header preserving any already on the response.
-function _appendSetCookie(res, header) {
+/**
+ * @primitive b.cookies.appendSetCookie
+ * @signature b.cookies.appendSetCookie(res, header)
+ * @since     0.18.41
+ * @status    stable
+ * @related   b.cookies.serialize, b.cookies.create
+ *
+ * Queue one Set-Cookie header on a response without discarding the ones
+ * already queued. `res.setHeader("Set-Cookie", value)` REPLACES the header,
+ * so a second cookie written that way silently drops the first — a route
+ * that issues a session cookie and then a CSRF cookie ends up sending only
+ * the CSRF one. Set-Cookie is the one response header that is legitimately
+ * repeated, and this is the framework's single appender for it: it uses
+ * `res.appendHeader` where the runtime offers it, and falls back to reading
+ * the current value and array-merging where it doesn't.
+ *
+ * The header string must already be serialized — pair it with
+ * `b.cookies.serialize`, which validates the name, value and attributes.
+ * `b.cookies.create().write()` / `.clear()` compose both for you; reach for
+ * this directly when you need to build the header at one point in a flow and
+ * queue it at another (validating early, emitting only after the side effect
+ * it accompanies has succeeded).
+ *
+ * @example
+ *   var header = b.cookies.serialize("sid", "", {
+ *     httpOnly: true, secure: true, sameSite: "Strict", path: "/", maxAge: 0,
+ *   });
+ *   b.cookies.appendSetCookie(res, header);
+ *   // → res now carries this expiry cookie alongside any already queued
+ */
+/**
+ * @primitive b.cookies.assertAppendable
+ * @signature b.cookies.assertAppendable(res)
+ * @since     0.18.41
+ * @status    stable
+ * @related   b.cookies.appendSetCookie, b.session.logout
+ *
+ * Throw unless `res` can carry an appended `Set-Cookie`. This is the same
+ * check `b.cookies.appendSetCookie` performs, exposed so a caller can run it
+ * BEFORE doing something it cannot undo.
+ *
+ * A response has to be readable as well as writable to be appended to: without
+ * `appendHeader`, the merge is done here and needs to see what is already
+ * queued. Discovering that late is the problem this exists to prevent —
+ * `b.session.logout` revokes the session row before it queues the expiry
+ * cookie, so a throw at queue time would leave the session destroyed, the
+ * client still holding its cookie, and the request failing. The response's
+ * shape is fixed for the life of the process and owned by the caller, not by
+ * the request, so it can and should be asserted up front.
+ *
+ * @example
+ *   b.cookies.assertAppendable(res);   // throws on a write-only response
+ *   await doSomethingIrreversible();
+ *   b.cookies.appendSetCookie(res, header);
+ *   // → the append cannot fail for a reason that was knowable earlier
+ */
+function assertAppendable(res) {
   if (!res || typeof res.setHeader !== "function") {
     throw new CookieError("cookies/no-set-header",
       "response object has no setHeader (not a Node http.ServerResponse?)");
   }
-  var existing;
-  if (typeof res.getHeader === "function") existing = res.getHeader("Set-Cookie");
+  // Without appendHeader the merge has to be done here, which means reading
+  // what is already queued. A response that can be written but not READ — a
+  // thin adapter or a test double carrying only setHeader — cannot be appended
+  // to at all: treating the unreadable value as absent would overwrite a cookie
+  // the route had already queued, which is the precise loss the appender exists
+  // to prevent. Refuse instead of silently doing the damage.
+  if (typeof res.appendHeader !== "function" && typeof res.getHeader !== "function") {
+    throw new CookieError("cookies/unreadable-response",
+      "response exposes setHeader but neither appendHeader nor getHeader, so an " +
+      "already-queued Set-Cookie cannot be read and would be replaced. Give the " +
+      "response a getHeader (or appendHeader) implementation.");
+  }
+}
+
+function appendSetCookie(res, header) {
+  assertAppendable(res);
+  if (typeof header !== "string" || header.length === 0) {
+    throw new CookieError("cookies/invalid-header",
+      "appendSetCookie: header must be a non-empty serialized Set-Cookie string");
+  }
+  // Node >= 18 exposes appendHeader, which handles the multi-value merge
+  // itself; prefer it so the response's own bookkeeping stays authoritative.
+  if (typeof res.appendHeader === "function") {
+    res.appendHeader("Set-Cookie", header);
+    return;
+  }
+  // assertAppendable has already established that getHeader exists when
+  // appendHeader does not, so the merge below can read the response.
+  var existing = res.getHeader("Set-Cookie");
   var arr;
-  if (Array.isArray(existing))      arr = existing.slice();
-  else if (existing !== undefined)  arr = [existing];
-  else                              arr = [];
+  if (Array.isArray(existing))                        arr = existing.slice();
+  else if (existing !== undefined && existing !== null) arr = [existing];
+  else                                                arr = [];
   arr.push(header);
   res.setHeader("Set-Cookie", arr);
 }
@@ -402,7 +484,7 @@ function create(opts) {
 
   function read(req, name)               { return _readCookieFromReq(req, name); }
   function write(res, name, value, attrs) {
-    _appendSetCookie(res, serialize(name, value, _mergeAttrs(attrs)));
+    appendSetCookie(res, serialize(name, value, _mergeAttrs(attrs)));
   }
   function clear(res, name, attrs) {
     // Expire-now cookie. Domain + Path must match the original write
@@ -410,7 +492,7 @@ function create(opts) {
     // attrs they used on write (or rely on the same defaults).
     var attrsExp = Object.assign({}, _mergeAttrs(attrs), { maxAge: 0 });
     delete attrsExp.expires;
-    _appendSetCookie(res, serialize(name, "", attrsExp));
+    appendSetCookie(res, serialize(name, "", attrsExp));
   }
 
   function _requireVault() {
@@ -575,9 +657,11 @@ function parseSafe(cookieHeader, opts) {
 }
 
 module.exports = {
-  create:       create,
-  parse:        parse,
-  parseSafe:    parseSafe,
-  serialize:    serialize,
-  CookieError:  CookieError,
+  create:           create,
+  parse:            parse,
+  parseSafe:        parseSafe,
+  serialize:        serialize,
+  appendSetCookie:  appendSetCookie,
+  assertAppendable: assertAppendable,
+  CookieError:      CookieError,
 };

package/lib/http-client.js

@@ -851,9 +851,7 @@ function _attachJarCookie(headers, jar, url) {
 function _buildMultipartBody(spec) {
   var boundary = "----blamejs-mp-" + bCrypto.generateToken(C.BYTES.bytes(16));
   var CRLF = "\r\n";
-  var nodeFs = require("node:fs");                                             // allow:inline-require — only on multipart paths that touch the filesystem
-  var path = require("node:path");                                         // allow:inline-require — same
-  var nodeStream = require("node:stream");                                 // allow:inline-require — Readable subclass only when streaming
+  var path = require("node:path");                                         // allow:inline-require — only on multipart paths that touch the filesystem
 
   // Each entry is { headerBytes, source } where source is one of:
   //   { kind: "buffer", buf: Buffer }

package/lib/mail-auth.js

@@ -334,11 +334,11 @@ function _ipv6Expand(ip) {
 
 function _ipv6InCidr(ip, cidr) {
   var slash = cidr.indexOf("/");
-  var net = slash === -1 ? cidr : cidr.slice(0, slash);
+  var networkAddr = slash === -1 ? cidr : cidr.slice(0, slash);
   var mask = slash === -1 ? 128 : parseInt(cidr.slice(slash + 1), 10);                        // IPv6 max prefix
   if (!isFinite(mask) || mask < 0 || mask > 128) return false;                                // IPv6 max prefix
   var ipGroups  = _ipv6Expand(ip);
-  var netGroups = _ipv6Expand(net);
+  var netGroups = _ipv6Expand(networkAddr);
   if (!ipGroups || !netGroups) return false;
   if (mask === 0) return true;
   // Compare group-by-group up to the prefix boundary.
@@ -356,11 +356,11 @@ function _ipv6InCidr(ip, cidr) {
 
 function _ipv4InCidr(ip, cidr) {
   var slash = cidr.indexOf("/");
-  var net = slash === -1 ? cidr : cidr.slice(0, slash);
+  var networkAddr = slash === -1 ? cidr : cidr.slice(0, slash);
   var mask = slash === -1 ? 32 : parseInt(cidr.slice(slash + 1), 10);             // IPv4 max prefix
   if (!isFinite(mask) || mask < 0 || mask > 32) return false;                     // IPv4 max prefix
   var ipInt = _ipv4ToInt(ip);
-  var netInt = _ipv4ToInt(net);
+  var netInt = _ipv4ToInt(networkAddr);
   if (ipInt === null || netInt === null) return false;
   if (mask === 0) return true;
   var bits = 32 - mask;                                                          // IPv4 max prefix
@@ -2395,7 +2395,6 @@ function _pemFromB64KeyMaterial(b64) {
 }
 
 function _runVerify(signedString, sigB64, algorithm, keyB64, label) {
-  var nodeCrypto = require("node:crypto");
   var pem = _pemFromB64KeyMaterial(keyB64);
   var keyObj;
   try { keyObj = nodeCrypto.createPublicKey(pem); }

package/lib/mail.js

@@ -248,10 +248,9 @@ async function reverseDns(ip) {
   // the original input. RFC 8601 §3 says the forward query must use
   // the same family as the source; mismatched families don't count
   // as confirmation.
-  var net = require("node:net");
   var forwardAddrs = [];
   try {
-    if (net.isIPv6(ip)) {
+    if (net().isIPv6(ip)) {
       forwardAddrs = await dns.resolveAaaa(ptrName);
     } else {
       forwardAddrs = await dns.resolve4(ptrName);

package/lib/middleware/csrf-protect.js

@@ -69,6 +69,7 @@
  *   }
  */
 var C = require("../constants");
+var cookies = require("../cookies");
 var lazyRequire = require("../lazy-require");
 var pick = require("../pick");
 var forms = require("../forms");
@@ -130,33 +131,6 @@ function _parseCookieHeader(header) {
   return Object.assign(Object.create(null), Object.fromEntries(pairs));
 }
 
-function _formatSetCookie(name, value, opts) {
-  var parts = [name + "=" + value];
-  parts.push("Path=" + (opts.path || "/"));
-  parts.push("SameSite=" + (opts.sameSite || "Lax"));
-  if (opts.httpOnly) parts.push("HttpOnly");
-  if (opts.secure)   parts.push("Secure");
-  if (opts.maxAge != null) parts.push("Max-Age=" + opts.maxAge);
-  return parts.join("; ");
-}
-
-function _appendSetCookie(res, value) {
-  // Don't clobber other Set-Cookie headers the route may have already
-  // queued (login session cookie, etc.). Use res.appendHeader when
-  // available; else array-merge manually.
-  if (typeof res.appendHeader === "function") {
-    res.appendHeader("Set-Cookie", value);
-    return;
-  }
-  var existing = typeof res.getHeader === "function" ? res.getHeader("Set-Cookie") : undefined;
-  if (existing == null) {
-    res.setHeader("Set-Cookie", value);
-  } else if (Array.isArray(existing)) {
-    res.setHeader("Set-Cookie", existing.concat(value));
-  } else {
-    res.setHeader("Set-Cookie", [existing, value]);
-  }
-}
 
 // csrf-protect does NOT buffer or parse the request body itself.
 // Operators who use form-urlencoded POSTs MUST register
@@ -431,30 +405,44 @@ function create(opts) {
     if (["Lax", "Strict", "None"].indexOf(cookieCfg.sameSite) === -1) {
       throw new Error("middleware.csrfProtect: opts.cookie.sameSite must be Lax|Strict|None");
     }
-    // Cookie name-prefix safety (RFC 6265bis §4.1.3). csrf-protect builds its
-    // own Set-Cookie header rather than routing through b.cookies.serialize, so
-    // this boot check is the only enforcement point. §5.4 requires user agents
-    // to apply the prefix test case-INSENSITIVELY (the server-side §4.1.3
-    // description reads "case-sensitive", but the UA is what drops the cookie),
-    // so `__host-`/`__SECURE-` get the same browser enforcement as
-    // `__Host-`/`__Secure-` -- case-sensitive matching was itself CVE-2024-5699.
-    // Compare a lowercased copy so a case-variant name can't dodge the invariant
-    // here and then be silently rejected by the browser. Catch typos at boot.
+    // Cookie name-prefix safety (RFC 6265bis §4.1.3). b.cookies.serialize
+    // enforces the same invariants when the header is built, but that is a
+    // per-request throw inside the middleware; catching the bad configuration
+    // at boot turns it into a startup error the operator can read. §5.4
+    // requires user agents to apply the prefix test case-INSENSITIVELY (the
+    // server-side §4.1.3 description reads "case-sensitive", but the UA is what
+    // drops the cookie), so `__host-`/`__SECURE-` get the same browser
+    // enforcement as `__Host-`/`__Secure-` -- case-sensitive matching was itself
+    // CVE-2024-5699. Compare a lowercased copy so a case-variant name can't
+    // dodge the invariant here and then be silently rejected by the browser.
     //   __Host-*   — Path must be "/", no Domain (we never set one), Secure.
     //   __Secure-* — Secure.
     if (cookieCfg.name) {
       var lowerCookieName = cookieCfg.name.toLowerCase();
-      if (lowerCookieName.indexOf("__host-") === 0) {
-        if (cookieCfg.path !== "/") {
-          throw new Error("middleware.csrfProtect: __Host-* cookie name requires path='/'");
-        }
-        if (cookieCfg.secure === false) {
-          throw new Error("middleware.csrfProtect: __Host-* cookie name requires secure (cannot be explicit false)");
-        }
-      } else if (lowerCookieName.indexOf("__secure-") === 0) {
-        if (cookieCfg.secure === false) {
-          throw new Error("middleware.csrfProtect: __Secure-* cookie name requires secure (cannot be explicit false)");
-        }
+      var isHostPrefix   = lowerCookieName.indexOf("__host-") === 0;
+      var isSecurePrefix = lowerCookieName.indexOf("__secure-") === 0;
+      if (isHostPrefix && cookieCfg.path !== "/") {
+        throw new Error("middleware.csrfProtect: __Host-* cookie name requires path='/'");
+      }
+      if (isHostPrefix && cookieCfg.secure === false) {
+        throw new Error("middleware.csrfProtect: __Host-* cookie name requires secure (cannot be explicit false)");
+      }
+      if (isSecurePrefix && cookieCfg.secure === false) {
+        throw new Error("middleware.csrfProtect: __Secure-* cookie name requires secure (cannot be explicit false)");
+      }
+      // A prefixed name is a promise to the browser that the cookie is always
+      // Secure. Leaving `secure` to per-request auto-detection breaks that
+      // promise on any cleartext request: the cookie goes out prefixed and
+      // WITHOUT Secure, the browser drops it, and the double-submit token
+      // silently never persists. The name and the auto-detect cannot both
+      // stand — the operator picking the prefix is the one asserting HTTPS,
+      // so make them say it.
+      if ((isHostPrefix || isSecurePrefix) && cookieCfg.secure == null) {
+        throw new Error("middleware.csrfProtect: " +
+          (isHostPrefix ? "__Host-*" : "__Secure-*") +
+          " cookie name requires an explicit cookie.secure: true — " +
+          "auto-detected secure emits the prefix without Secure on a plain-HTTP " +
+          "request, which browsers reject");
       }
     }
   }
@@ -485,8 +473,8 @@ function create(opts) {
   function _issueIfNeeded(req, res) {
     if (!cookieCfg) return null;
     var cookieName = _resolveCookieName(req);
-    var cookies = _parseCookieHeader(req.headers && req.headers.cookie);
-    var existing = cookies[cookieName];
+    var requestCookies = _parseCookieHeader(req.headers && req.headers.cookie);
+    var existing = requestCookies[cookieName];
     // Strict 64-hex-char check matches the byte-length of every token
     // forms.generateCsrfToken() produces (CSRF_TOKEN_BYTES = 32 bytes
     // → 64 hex chars). The previous {2,} floor accepted any 2-char
@@ -522,14 +510,20 @@ function create(opts) {
       } catch (_e) { /* drop-silent */ }
     }
     var fresh = forms.generateCsrfToken();
-    var setCookie = _formatSetCookie(cookieName, fresh, {
+    // b.cookies owns Set-Cookie: it validates the name as an RFC 6265 token,
+    // refuses CRLF / NUL in the value, scrubs the Path and Domain attributes
+    // before they reach a response header, and enforces the RFC 6265bis
+    // prefix invariants. The token is 64 hex characters, so the percent-
+    // encoding serialize applies to the value is a no-op on it and the cookie
+    // the browser echoes back still matches the double-submit compare.
+    var setCookie = cookies.serialize(cookieName, fresh, {
       path:     cookieCfg.path,
       sameSite: cookieCfg.sameSite,
       secure:   cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure,
       httpOnly: cookieCfg.httpOnly,
       maxAge:   cookieCfg.maxAge,
     });
-    _appendSetCookie(res, setCookie);
+    cookies.appendSetCookie(res, setCookie);
     req._csrfIssuedCookies[cookieName] = fresh;
     req.csrfToken = fresh;
     return fresh;

package/lib/migrations.js

@@ -297,12 +297,12 @@ function create(opts) {
   var dir = opts.dir;
 
   function _appliedRows() {
-    var db = _resolveDb(opts);
-    _ensureTable(db);
-    var q = sql.select(_migrationsTable(), _sqlOpts(db))
+    var conn = _resolveDb(opts);
+    _ensureTable(conn);
+    var q = sql.select(_migrationsTable(), _sqlOpts(conn))
       .columns(["name", "description", "appliedAt"])
       .orderBy("appliedAt", "asc").orderBy("name", "asc").toSql();
-    var stmt = db.prepare(q.sql);
+    var stmt = conn.prepare(q.sql);
     return stmt.all.apply(stmt, q.params);
   }
 
@@ -319,11 +319,11 @@ function create(opts) {
   }
 
   function up() {
-    var db = _resolveDb(opts);
-    _ensureTable(db);
-    return _withLock(db, opts, function () {
-      var namesQ = sql.select(_migrationsTable(), _sqlOpts(db)).columns(["name"]).toSql();
-      var namesStmt = db.prepare(namesQ.sql);
+    var conn = _resolveDb(opts);
+    _ensureTable(conn);
+    return _withLock(conn, opts, function () {
+      var namesQ = sql.select(_migrationsTable(), _sqlOpts(conn)).columns(["name"]).toSql();
+      var namesStmt = conn.prepare(namesQ.sql);
       var appliedSet = new Set(
         namesStmt.all.apply(namesStmt, namesQ.params)
           .map(function (r) { return r.name; })
@@ -336,12 +336,12 @@ function create(opts) {
         if (appliedSet.has(file)) { skipped.push(file); continue; }
         var mod = _loadMigration(file, dir);
         try {
-          _txn(db, function () {
-            mod.up(db);
-            var insQ = sql.insert(_migrationsTable(), _sqlOpts(db))
+          _txn(conn, function () {
+            mod.up(conn);
+            var insQ = sql.insert(_migrationsTable(), _sqlOpts(conn))
               .values({ name: file, description: mod.description || "",
                         appliedAt: new Date().toISOString() }).toSql();
-            var insStmt = db.prepare(insQ.sql);
+            var insStmt = conn.prepare(insQ.sql);
             insStmt.run.apply(insStmt, insQ.params);
           });
         } catch (e) {
@@ -363,16 +363,16 @@ function create(opts) {
         "down: steps must be a positive integer (got " + opts2.steps + ")",
         true);
     }
-    var db = _resolveDb(opts);
-    _ensureTable(db);
-    return _withLock(db, opts, function () {
+    var conn = _resolveDb(opts);
+    _ensureTable(conn);
+    return _withLock(conn, opts, function () {
       // Most-recent applied first (reverse chronological by appliedAt
       // then by name as a stable tiebreaker for fixtures with identical
       // timestamps). steps is a validated positive integer, so b.sql
       // inlines the LIMIT.
-      var downQ = sql.select(_migrationsTable(), _sqlOpts(db)).columns(["name"])
+      var downQ = sql.select(_migrationsTable(), _sqlOpts(conn)).columns(["name"])
         .orderBy("appliedAt", "desc").orderBy("name", "desc").limit(steps).toSql();
-      var downStmt = db.prepare(downQ.sql);
+      var downStmt = conn.prepare(downQ.sql);
       var rows = downStmt.all.apply(downStmt, downQ.params);
 
       var reverted = [];
@@ -386,10 +386,10 @@ function create(opts) {
             true);
         }
         try {
-          _txn(db, function () {
-            mod.down(db);
-            var delQ = sql.delete(_migrationsTable(), _sqlOpts(db)).where("name", file).toSql();
-            var delStmt = db.prepare(delQ.sql);
+          _txn(conn, function () {
+            mod.down(conn);
+            var delQ = sql.delete(_migrationsTable(), _sqlOpts(conn)).where("name", file).toSql();
+            var delStmt = conn.prepare(delQ.sql);
             delStmt.run.apply(delStmt, delQ.params);
           });
         } catch (e) {

package/lib/seeders.js

@@ -452,11 +452,11 @@ function create(opts) {
   function status(callerOpts) {
     callerOpts = callerOpts || {};
     _validateEnv("seeders.status: env", callerOpts.env);
-    var db = _resolveDb(opts);
-    _ensureTables(db);
+    var conn = _resolveDb(opts);
+    _ensureTables(conn);
     var env = callerOpts.env;
     var loaded = _loadAllForEnv(dir, env);
-    var applied = _appliedRows(db, env);
+    var applied = _appliedRows(conn, env);
     var appliedNames = new Set(applied.map(function (r) { return r.name; }));
     var pending = loaded.ordered.filter(function (n) {
       var mod = loaded.modByName[n];
@@ -491,8 +491,8 @@ function create(opts) {
       }
     }
 
-    var db = _resolveDb(opts);
-    _ensureTables(db);
+    var conn = _resolveDb(opts);
+    _ensureTables(conn);
 
     var loaded = _loadAllForEnv(dir, env);
 
@@ -504,11 +504,11 @@ function create(opts) {
     var startedAt = clock();
     observability().safeEvent("seeders.run.start", 1, { env: env, count: loaded.ordered.length });
 
-    var holder = _acquireLock(db, lockStaleAfterMs, clock);
+    var holder = _acquireLock(conn, lockStaleAfterMs, clock);
     try {
-      var appliedSelBuilt = sql.select(_seedersTable(), _sqlOpts(db))
+      var appliedSelBuilt = sql.select(_seedersTable(), _sqlOpts(conn))
         .columns(["name"]).where("env", env).toSql();
-      var appliedSelStmt = db.prepare(appliedSelBuilt.sql);
+      var appliedSelStmt = conn.prepare(appliedSelBuilt.sql);
       var appliedSet = new Set(
         appliedSelStmt.all.apply(appliedSelStmt, appliedSelBuilt.params)
           .map(function (r) { return r.name; })
@@ -539,26 +539,26 @@ function create(opts) {
           // Per-seed transaction: SQLite txns are sync, but the seed's
           // run() may be async — runInTransactionAsync wraps BEGIN/COMMIT
           // around the awaited body and rolls back this seed only on failure.
-          await dbSchema.runInTransactionAsync(db, async function () {
-            await mod.run(db, ctx);
+          await dbSchema.runInTransactionAsync(conn, async function () {
+            await mod.run(conn, ctx);
             var nowIso = new Date(clock()).toISOString();
             var writeBuilt;
             if (alreadyApplied && mod.rerunnable) {
-              writeBuilt = sql.update(_seedersTable(), _sqlOpts(db))
+              writeBuilt = sql.update(_seedersTable(), _sqlOpts(conn))
                 .set({ appliedAt: nowIso, description: mod.description || "",
                        rerunnable: mod.rerunnable ? 1 : 0 })
                 .where("env", env).where("name", name).toSql();
             } else if (alreadyApplied && force) {
-              writeBuilt = sql.update(_seedersTable(), _sqlOpts(db))
+              writeBuilt = sql.update(_seedersTable(), _sqlOpts(conn))
                 .set({ appliedAt: nowIso, description: mod.description || "" })
                 .where("env", env).where("name", name).toSql();
             } else {
-              writeBuilt = sql.insert(_seedersTable(), _sqlOpts(db))
+              writeBuilt = sql.insert(_seedersTable(), _sqlOpts(conn))
                 .values({ env: env, name: name, description: mod.description || "",
                           appliedAt: nowIso, rerunnable: mod.rerunnable ? 1 : 0 })
                 .toSql();
             }
-            var writeStmt = db.prepare(writeBuilt.sql);
+            var writeStmt = conn.prepare(writeBuilt.sql);
             writeStmt.run.apply(writeStmt, writeBuilt.params);
           }, {
             onRollbackFail: function (rollbackErr) {
@@ -629,7 +629,7 @@ function create(opts) {
       }
       return result;
     } finally {
-      _releaseLock(db, holder);
+      _releaseLock(conn, holder);
     }
   }
 

package/lib/session.js

@@ -54,6 +54,7 @@ var validateOpts = require("./validate-opts");
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
+var cookies = require("./cookies");
 var { generateToken, sha3Hash } = require("./crypto");
 var cryptoField = require("./crypto-field");
 var frameworkSchema = require("./framework-schema");
@@ -410,7 +411,9 @@ function _hashFingerprint(sid, inputs) {
  *     data:   { roles: ["admin"] },
  *     ttlMs:  b.constants.TIME.hours(8),
  *   });
- *   res.setHeader("Set-Cookie", "sid=" + s.token + "; HttpOnly; Secure; SameSite=Strict");
+ *   b.cookies.appendSetCookie(res, b.cookies.serialize("sid", s.token, {
+ *     httpOnly: true, secure: true, sameSite: "Strict", path: "/",
+ *   }));
  *   // → { token: "9f2c…", expiresAt: 1735689600000 }
  */
 // Anonymous-session prefix. b.session.create({ anonymous: true })
@@ -770,7 +773,9 @@ async function verify(token, verifyOpts) {
  *
  * @example
  *   await b.session.destroy(req.cookies.sid);
- *   res.setHeader("Set-Cookie", "sid=; HttpOnly; Max-Age=0");
+ *   b.cookies.appendSetCookie(res, b.cookies.serialize("sid", "", {
+ *     httpOnly: true, sameSite: "Strict", path: "/", maxAge: 0,
+ *   }));
  *   res.end("logged out");
  *   // → true
  */
@@ -798,13 +803,29 @@ async function destroy(token) {
  * this composes the secure-default logout the middleware otherwise had to be
  * mounted by hand. Returns whether a session was destroyed. Leader-only.
  *
+ * A browser deletes a cookie by MATCHING the expiry cookie's name, path and
+ * domain against the one in its jar, and it refuses a `Secure` cookie
+ * altogether when the response came over plain HTTP. So the expiry cookie has
+ * to describe the same scope the session cookie was written with, or the
+ * logout leaves it in place. Pass the `req` and the scheme is resolved through
+ * `b.requestHelpers.trustedProtocol` (a forwarded scheme counts only from a
+ * peer you declared trusted); pass `secure` to state it outright. With neither,
+ * the cookie is `Secure` — the secure default, unchanged.
+ *
  * @opts
- *   cookieName: string,    // default: "sid" — the session cookie to expire
- *   types:      string[],  // default: the W3C Clear-Site-Data directive set
+ *   cookieName:       string,   // default: "sid" — the session cookie to expire
+ *   types:            string[], // default: the W3C Clear-Site-Data directive set
+ *   req:              object,   // resolve Secure from this request's scheme
+ *   secure:           boolean,  // default: true — state the scheme outright
+ *   sameSite:         string,   // default: "Strict" — Strict / Lax / None
+ *   path:             string,   // default: "/" — must match the cookie's Path
+ *   domain:           string,   // must match the cookie's Domain, if it had one
+ *   trustedProxies:   string | string[],   // CIDRs, for the `req` scheme resolve
+ *   protocolResolver: function(req),       // own the scheme decision instead
  *
  * @example
  *   app.post("/logout", async function (req, res) {
- *     await b.session.logout(res, req.cookies.sid);
+ *     await b.session.logout(res, req.cookies.sid, { req: req });
  *     res.end("logged out");
  *   });
  *   // → emits Clear-Site-Data + expires the sid cookie + destroys the session
@@ -814,7 +835,19 @@ async function logout(res, token, opts) {
     throw new SessionError("session/bad-res",
       "b.session.logout: res must be an HTTP response with setHeader()");
   }
+  // The expiry cookie is queued with b.cookies.appendSetCookie, which needs to
+  // READ the response as well as write it. Assert that contract here, with the
+  // other validation, rather than discovering it at queue time: the queue
+  // happens after destroy(), so a throw there would leave the session revoked,
+  // Clear-Site-Data queued, no expiry cookie and a failed request. The
+  // response's shape is the caller's and fixed for the process, so it is
+  // knowable before any of that.
+  cookies.assertAppendable(res);
   opts = opts || {};
+  validateOpts(opts, [
+    "cookieName", "types", "req", "secure", "sameSite", "path", "domain",
+    "trustedProxies", "protocolResolver",
+  ], "b.session.logout");
   var cookieName = opts.cookieName === undefined ? "sid" : opts.cookieName;
   if (typeof cookieName !== "string" || cookieName.length === 0) {
     throw new SessionError("session/bad-cookie-name",
@@ -826,6 +859,19 @@ async function logout(res, token, opts) {
   // unknown directive throws here, queuing nothing.
   var clearSiteDataValue = csd.headerValue(types, "b.session.logout");
 
+  // Same ordering for the cookie: b.cookies.serialize validates the name, the
+  // attributes and the RFC 6265bis prefix invariants, so it is a throwing call
+  // and must run before the row is revoked — otherwise a `__Host-` typo leaves
+  // the session destroyed and the browser still holding its cookie.
+  var expiryCookie = cookies.serialize(cookieName, "", {
+    httpOnly: true,
+    secure:   _logoutCookieSecure(opts, cookieName),
+    sameSite: opts.sameSite === undefined ? "Strict" : opts.sameSite,
+    path:     opts.path === undefined ? "/" : opts.path,
+    domain:   opts.domain,
+    maxAge:   0,
+  });
+
   // Revoke the server-side session FIRST. If destroy() throws (a follower
   // failing cluster.requireLeader(), or a store/DB error), no client-wipe
   // headers have been queued — an error response can't then expire the
@@ -836,12 +882,55 @@ async function logout(res, token, opts) {
   // Now wipe the client-side state: W3C Clear-Site-Data (cookies /
   // storage / cache) + expire the session cookie (belt-and-suspenders with the
   // "cookies" directive, and effective even if the client ignores the header).
+  // Append rather than set: a route that already queued a cookie of its own
+  // (a rotated CSRF token, a locale) keeps it.
   res.setHeader("Clear-Site-Data", clearSiteDataValue);
-  res.setHeader("Set-Cookie",
-    cookieName + "=; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=0");
+  cookies.appendSetCookie(res, expiryCookie);
   return destroyed;
 }
 
+// Whether logout's expiry cookie carries Secure. Explicit `secure` wins; a
+// `req` resolves through the peer-gated protocol helper; with neither the
+// answer is the secure default. A browser drops a Secure cookie arriving over
+// plain HTTP, so answering "true" for an HTTP deployment does not fail safe —
+// it fails to clear the cookie at all.
+function _logoutCookieSecure(opts, cookieName) {
+  if (opts.secure !== undefined) {
+    if (typeof opts.secure !== "boolean") {
+      throw new SessionError("session/bad-secure",
+        "b.session.logout: opts.secure must be a boolean");
+    }
+    // An explicit `false` against a `__Host-`/`__Secure-` name is a
+    // contradiction, and serialize() refuses it. That is deliberate: the
+    // operator stated both halves, it fails on the first logout in every
+    // environment, and no request can provoke or avoid it.
+    return opts.secure;
+  }
+  // A `__Host-` / `__Secure-` name is a statement about the COOKIE, not about
+  // this request: a browser will only ever have stored such a cookie on a
+  // secure origin, so on a cleartext request there is nothing of that name to
+  // clear. Letting the request's scheme resolve `secure` to false here would
+  // make serialize() refuse the name — and the cookie is built BEFORE the row
+  // is revoked, so that refusal would abort the logout entirely and whoever
+  // chose the scheme would decide whether the session died. The prefix wins.
+  var lowerName = cookieName.toLowerCase();
+  if (lowerName.indexOf("__host-") === 0 || lowerName.indexOf("__secure-") === 0) {
+    return true;
+  }
+  if (opts.req === undefined) return true;
+  if (opts.req === null || typeof opts.req !== "object") {
+    // trustedProtocol answers "http" for a non-request rather than throwing, so
+    // a mistyped `req` would quietly drop Secure. Refuse it instead.
+    throw new SessionError("session/bad-req",
+      "b.session.logout: opts.req must be an HTTP request object");
+  }
+  var resolver = requestHelpers.trustedProtocol({
+    trustedProxies:   opts.trustedProxies,
+    protocolResolver: opts.protocolResolver,
+  });
+  return resolver.resolve(opts.req) === "https";
+}
+
 async function _deleteBySidHash(sidHash) {
   var built = sql.delete(_sessionSqlTable(), _sessionSqlOpts())
     .where("sidHash", sidHash)
@@ -1057,7 +1146,9 @@ async function touch(token, opts) {
  *     reason: "mfa",
  *   });
  *   if (rotated) {
- *     res.setHeader("Set-Cookie", "sid=" + rotated.token + "; HttpOnly; Secure; SameSite=Strict");
+ *     b.cookies.appendSetCookie(res, b.cookies.serialize("sid", rotated.token, {
+ *       httpOnly: true, secure: true, sameSite: "Strict", path: "/",
+ *     }));
  *   }
  *   // → { token: "7a1e…", expiresAt: 1735689600000 }
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.18.40",
+  "version": "0.18.41",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -75,7 +75,7 @@
     "check:vendor-currency": "node scripts/check-vendor-currency.js"
   },
   "devDependencies": {
-    "esbuild": "0.28.1",
+    "esbuild": "0.28.2",
     "postject": "1.0.0-alpha.6"
   }
 }

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:8dddced8-3851-4a88-aefd-92c81c340d6b",
+  "serialNumber": "urn:uuid:a9c950dd-01b0-4088-b83e-2dfd36c75675",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-20T12:00:46.802Z",
+    "timestamp": "2026-08-20T14:26:30.885Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.18.40",
+      "bom-ref": "@blamejs/core@0.18.41",
       "type": "application",
       "name": "blamejs",
-      "version": "0.18.40",
+      "version": "0.18.41",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.18.40",
+      "purl": "pkg:npm/%40blamejs/core@0.18.41",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.18.40",
+      "ref": "@blamejs/core@0.18.41",
       "dependsOn": []
     }
   ]