@blamejs/core 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.2** (2026-04-30) — b.breakGlass: passkey factor + service-account bypass + admin tools
+- **0.5.1** (2026-04-30) — b.breakGlass: per-cell encryption + context binding + migrate
 - **0.5.0** (2026-04-30) — b.breakGlass: column-policy / row-enforcement step-up auth
 
 ## v0.4.x

package/lib/break-glass.js

@@ -54,6 +54,7 @@ var { defineClass } = require("./framework-error");
 var vault = lazyRequire(function () { return require("./vault"); });
 
 var lockout = lazyRequire(function () { return require("./auth/lockout"); });
+var passkey = lazyRequire(function () { return require("./auth/passkey"); });
 
 // Errors — all 14 codes documented in the spec. `permanent: true`
 // means caller's input is bad (Tier-A); `permanent: false` means
@@ -67,7 +68,7 @@ var DEFAULT_MAX_ROWS        = 1;       // operator-locked: row-by-row auth
 var DEFAULT_REASON_MIN_LEN  = 12;
 var DEFAULT_LOCKED_BEHAVIOR = "throw"; // or "redact"
 var DEFAULT_AUDIT_REASON    = "cleartext";
-var ALLOWED_FACTORS         = ["totp"]; // passkey added in v0.5.2
+var ALLOWED_FACTORS         = ["totp", "passkey"];
 var ALLOWED_REASON_STORAGE  = ["cleartext", "hmac", "both"];
 
 // In-memory policy cache. Cluster-shared via the policies table; the
@@ -135,19 +136,18 @@ function _kCell(dek, table, rowId, column) {
 
 async function _ensureDek(table) {
   if (dekCache.has(table)) return dekCache.get(table);
-  // The DEK lives in the policy row's serviceAccountBypassJson slot
-  // (repurposed in Model A; v0.5.0 explicitly rejected the slot, so
-  // it's unused in Model A rows). For Model B rows, we vault-seal the
-  // DEK and store it there. Pre-v1 schema: clean and simple.
+  // DEK is vault-sealed and stored in the policy row's `dekSealed`
+  // column. Generated lazily on first use of cryptographic-mode for
+  // the table. Cached in-memory after first read.
   var rows = await clusterStorage.executeAll(
-    "SELECT serviceAccountBypassJson FROM _blamejs_break_glass_policies WHERE tableName = ?",
+    "SELECT dekSealed FROM _blamejs_break_glass_policies WHERE tableName = ?",
     [table]
   );
   if (!rows || rows.length === 0) {
     throw new BreakGlassError("breakglass/policy-not-set",
       "_ensureDek: no policy for table '" + table + "'", true);
   }
-  var sealed = rows[0].serviceAccountBypassJson;
+  var sealed = rows[0].dekSealed;
   var dek;
   if (sealed) {
     dek = Buffer.from(vault().unseal(sealed), "base64");
@@ -155,7 +155,7 @@ async function _ensureDek(table) {
     dek = generateBytes(32);
     var sealedDek = vault().seal(dek.toString("base64"));
     await clusterStorage.execute(
-      "UPDATE _blamejs_break_glass_policies SET serviceAccountBypassJson = ? WHERE tableName = ?",
+      "UPDATE _blamejs_break_glass_policies SET dekSealed = ? WHERE tableName = ?",
       [sealedDek, table]
     );
   }
@@ -399,9 +399,35 @@ function _validatePolicySet(table, opts) {
     throw new BreakGlassError("breakglass/bad-policy",
       "policy.set: auditReasonStorage must be one of " + ALLOWED_REASON_STORAGE.join("/"));
   }
+  // Service-account bypass: explicit opt-in per table. Operators
+  // declare the apiKey ids that may bypass + a required role; the
+  // framework requires BOTH to grant the bypass. Without this opt set,
+  // there is NO bypass path — every read of a glass-locked column
+  // requires a fresh grant.
+  var serviceAccountBypass = null;
   if (opts.serviceAccountBypass != null && opts.serviceAccountBypass !== false) {
-    throw new BreakGlassError("breakglass/bad-policy",
-      "policy.set: serviceAccountBypass ships in v0.5.2 — leave unset for v0.5.0");
+    var sab = opts.serviceAccountBypass;
+    if (!sab || typeof sab !== "object") {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass must be an object { enabled, apiKeyIds, requireRole }");
+    }
+    if (sab.enabled !== true) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass.enabled must be true (set serviceAccountBypass: false to disable)");
+    }
+    if (!Array.isArray(sab.apiKeyIds) || sab.apiKeyIds.length === 0) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass.apiKeyIds must be a non-empty array of apiKey ids");
+    }
+    if (typeof sab.requireRole !== "string" || sab.requireRole.length === 0) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass.requireRole must be a non-empty role / scope string");
+    }
+    serviceAccountBypass = {
+      enabled:     true,
+      apiKeyIds:   sab.apiKeyIds.slice(),
+      requireRole: sab.requireRole,
+    };
   }
   return {
     cryptographic:   opts.cryptographic === true,
@@ -414,6 +440,7 @@ function _validatePolicySet(table, opts) {
     onLockedAccess:  opts.onLockedAccess || DEFAULT_LOCKED_BEHAVIOR,
     requireScope:    opts.requireScope != null ? opts.requireScope : null,
     auditReasonStorage: opts.auditReasonStorage || DEFAULT_AUDIT_REASON,
+    serviceAccountBypass: serviceAccountBypass,
   };
 }
 
@@ -433,7 +460,9 @@ async function policySet(table, opts, callerOpts) {
     sessionPin:               validated.sessionPin ? 1 : 0,
     onLockedAccess:           validated.onLockedAccess,
     requireScope:             validated.requireScope,
-    serviceAccountBypassJson: null,
+    serviceAccountBypassJson: validated.serviceAccountBypass
+      ? JSON.stringify(validated.serviceAccountBypass)
+      : null,
     auditReasonStorage:       validated.auditReasonStorage,
     updatedAt:                Date.now(),
   };
@@ -492,6 +521,9 @@ async function policyGet(table) {
     sessionPin:         unsealed.sessionPin === 1,
     onLockedAccess:     unsealed.onLockedAccess,
     requireScope:       unsealed.requireScope,
+    serviceAccountBypass: unsealed.serviceAccountBypassJson
+      ? safeJson.parse(unsealed.serviceAccountBypassJson, { maxBytes: C.BYTES.kib(8) })
+      : null,
     auditReasonStorage: unsealed.auditReasonStorage,
     updatedAt:          Number(unsealed.updatedAt),
   };
@@ -542,6 +574,34 @@ function _verifyTotpFactor(factor) {
   return { ok: verified !== false, step: verified };
 }
 
+// Passkey factor — operator presents a WebAuthn assertion plus the
+// challenge/origin/RPID + the previously-enrolled credential record.
+// Phishing-resistant; the private key lives on the YubiKey, not in
+// the framework's vault. v0.5.2 uses passkey for identity verification
+// to gate grant issuance; PRF-derived per-policy DEK material (which
+// would give true vault-key-alone-doesn't-decrypt defense) is a
+// follow-up.
+async function _verifyPasskeyFactor(factor) {
+  if (!factor || typeof factor !== "object") return { ok: false };
+  if (!factor.response || !factor.expectedChallenge ||
+      !factor.expectedOrigin || !factor.expectedRPID || !factor.credential) {
+    return { ok: false };
+  }
+  try {
+    var result = await passkey().verifyAuthentication({
+      response:                factor.response,
+      expectedChallenge:       factor.expectedChallenge,
+      expectedOrigin:          factor.expectedOrigin,
+      expectedRPID:            factor.expectedRPID,
+      credential:              factor.credential,
+      requireUserVerification: factor.requireUserVerification !== false,
+    });
+    return { ok: result && result.verified === true };
+  } catch (_e) {
+    return { ok: false };
+  }
+}
+
 async function grant(opts) {
   _requireInit();
   if (!opts || typeof opts !== "object") {
@@ -613,6 +673,8 @@ async function grant(opts) {
   var factorOk = false;
   if (factorType === "totp") {
     factorOk = _verifyTotpFactor(opts.factor).ok;
+  } else if (factorType === "passkey") {
+    factorOk = (await _verifyPasskeyFactor(opts.factor)).ok;
   }
 
   if (!factorOk) {
@@ -937,6 +999,220 @@ async function listActive(opts) {
   return out;
 }
 
+// ---- Service-account bypass ----
+//
+// Some legitimate workloads (nightly de-identification, scheduled
+// compliance reports) need PHI access without a human at the
+// keyboard. The framework refuses to silently bypass — operators
+// declare explicit service-account bypasses per-table with an apiKey
+// allowlist + required role. Both must match (verified apiKey id is
+// in the allowlist AND the apiKey carries the required role/scope)
+// before the bypass is granted. Each bypass emits its own distinct
+// audit row so post-incident review can distinguish operator-initiated
+// from service-initiated reads.
+
+async function unsealRowAsService(req, table, rowId, opts) {
+  _requireInit();
+  opts = opts || {};
+  if (!req || typeof req !== "object") {
+    throw new BreakGlassError("breakglass/bad-grant-opts",
+      "unsealRowAsService: req is required (with verified req.apiKey)");
+  }
+  if (typeof table !== "string" || table.length === 0) {
+    throw new BreakGlassError("breakglass/bad-grant-opts",
+      "unsealRowAsService: table must be a non-empty string");
+  }
+  var policy = await policyGet(table);
+  if (!policy) {
+    throw new BreakGlassError("breakglass/policy-not-set",
+      "unsealRowAsService: no break-glass policy for table '" + table + "'", true);
+  }
+  if (!policy.serviceAccountBypass) {
+    throw new BreakGlassError("breakglass/bypass-not-configured",
+      "unsealRowAsService: serviceAccountBypass is not configured for '" + table + "'", true);
+  }
+  var apiKeyOnReq = req.apiKey;
+  if (!apiKeyOnReq || typeof apiKeyOnReq.id !== "string") {
+    throw new BreakGlassError("breakglass/bypass-no-apikey",
+      "unsealRowAsService: req.apiKey.id is required (operator must run b.middleware.requireApiKey before this path)", true);
+  }
+  if (policy.serviceAccountBypass.apiKeyIds.indexOf(apiKeyOnReq.id) === -1) {
+    audit.safeEmit({
+      action:   "breakglass.grant.bypass",
+      outcome:  "denied",
+      actor:    requestHelpers.extractActorContext(req),
+      reason:   "apikey-not-in-allowlist",
+      metadata: { table: table, rowId: String(rowId), apiKeyId: apiKeyOnReq.id },
+    });
+    throw new BreakGlassError("breakglass/bypass-unauthorized",
+      "unsealRowAsService: apiKey '" + apiKeyOnReq.id +
+      "' is not in the bypass allowlist for '" + table + "'", true);
+  }
+  // Role check — actor must carry policy.serviceAccountBypass.requireRole
+  // either as a direct scope or via b.permissions.check resolution.
+  var actorScopes = Array.isArray(apiKeyOnReq.scopes) ? apiKeyOnReq.scopes :
+                    Array.isArray(apiKeyOnReq.roles)  ? apiKeyOnReq.roles :
+                    [];
+  var requiredRole = policy.serviceAccountBypass.requireRole;
+  var hasRole = actorScopes.indexOf(requiredRole) !== -1;
+  if (!hasRole) {
+    audit.safeEmit({
+      action:   "breakglass.grant.bypass",
+      outcome:  "denied",
+      actor:    requestHelpers.extractActorContext(req),
+      reason:   "missing-role",
+      metadata: { table: table, rowId: String(rowId), apiKeyId: apiKeyOnReq.id, requiredRole: requiredRole },
+    });
+    throw new BreakGlassError("breakglass/bypass-unauthorized",
+      "unsealRowAsService: apiKey '" + apiKeyOnReq.id +
+      "' lacks required role '" + requiredRole + "'", true);
+  }
+
+  // Fetch + unseal the row (Model A or Model B path, same as
+  // operator-initiated unsealRow).
+  var rows = await clusterStorage.executeAll(
+    "SELECT * FROM " + table + " WHERE _id = ?",
+    [String(rowId)]
+  );
+  if (!rows || rows.length === 0) {
+    throw new BreakGlassError("breakglass/row-not-found",
+      "unsealRowAsService: " + table + "[" + rowId + "] not found", true);
+  }
+  var unsealedRow;
+  if (policy.cryptographic) {
+    var rawCipher = {};
+    for (var c = 0; c < policy.columns.length; c++) rawCipher[policy.columns[c]] = rows[0][policy.columns[c]];
+    var rowMinusLocked = Object.assign({}, rows[0]);
+    for (var c2 = 0; c2 < policy.columns.length; c2++) delete rowMinusLocked[policy.columns[c2]];
+    unsealedRow = cryptoField.unsealRow(table, rowMinusLocked);
+    for (var c3 = 0; c3 < policy.columns.length; c3++) {
+      var col = policy.columns[c3];
+      if (rawCipher[col] == null) continue;
+      unsealedRow[col] = await decryptCell(rawCipher[col],
+        { table: table, rowId: String(rowId), column: col });
+    }
+  } else {
+    unsealedRow = cryptoField.unsealRow(table, rows[0]);
+  }
+
+  audit.safeEmit({
+    action:   "breakglass.grant.bypass",
+    outcome:  "success",
+    actor:    requestHelpers.extractActorContext(req),
+    reason:   typeof opts.reason === "string" ? opts.reason : null,
+    metadata: {
+      table:        table,
+      rowId:        String(rowId),
+      apiKeyId:     apiKeyOnReq.id,
+      requiredRole: requiredRole,
+      columns:      policy.columns.slice(),
+    },
+  });
+  observability.event("breakglass.grant.bypass", { table: table });
+  return unsealedRow;
+}
+
+// ---- Admin tools ----
+//
+// `listActiveAll` returns every active grant (across all actors) —
+// for security-team dashboards and offboarding workflows.
+// `revokeAll` mass-revokes grants matching criteria — used by IR
+// teams when an account is suspected compromised. Both require
+// admin scope (operator wires via opts.requireScope or their own gate).
+
+async function listActiveAll(opts) {
+  _requireInit();
+  opts = opts || {};
+  var nowMs = Date.now();
+  var clauses = ["(revokedAt IS NULL)", "expiresAt > ?", "rowsConsumed < maxRowsPerGrant"];
+  var params = [nowMs];
+  if (opts.table) {
+    clauses.push("scopeTable = ?");
+    params.push(opts.table);
+  }
+  if (opts.since) {
+    clauses.push("issuedAt >= ?");
+    params.push(opts.since);
+  }
+  var rows = await clusterStorage.executeAll(
+    "SELECT * FROM _blamejs_break_glass_grants WHERE " + clauses.join(" AND ") +
+    " ORDER BY issuedAt DESC",
+    params
+  );
+  var out = [];
+  for (var i = 0; i < (rows || []).length; i++) {
+    var u = cryptoField.unsealRow("_blamejs_break_glass_grants", rows[i]);
+    out.push({
+      id:             u._id,
+      issuedToActorId: u.issuedToActorId,
+      scopeTable:     u.scopeTable,
+      scopeColumns:   safeJson.parse(u.scopeColumnsJson || "[]", { maxBytes: C.BYTES.kib(64) }),
+      factorType:     u.factorType,
+      issuedAt:       Number(u.issuedAt),
+      expiresAt:      Number(u.expiresAt),
+      rowsRemaining:  Number(u.maxRowsPerGrant) - Number(u.rowsConsumed),
+    });
+  }
+  audit.safeEmit({
+    action:   "breakglass.admin.listactiveall",
+    outcome:  "success",
+    actor:    requestHelpers.resolveActorWithOverride(opts.callerOpts),
+    metadata: { resultCount: out.length, filterTable: opts.table || null },
+  });
+  return out;
+}
+
+async function revokeAll(criteria, opts) {
+  _requireInit();
+  if (!criteria || typeof criteria !== "object") {
+    throw new BreakGlassError("breakglass/bad-revoke-criteria",
+      "revokeAll: criteria is required ({ actorId?, table? })");
+  }
+  if (!criteria.actorId && !criteria.table) {
+    throw new BreakGlassError("breakglass/bad-revoke-criteria",
+      "revokeAll: at least one of { actorId, table } is required (refusing to mass-revoke without scope)");
+  }
+  opts = opts || {};
+  var clauses = ["revokedAt IS NULL"];
+  var params = [];
+  if (criteria.actorId) {
+    var derived = cryptoField.computeDerived(
+      "_blamejs_break_glass_grants", "issuedToActorId", criteria.actorId
+    );
+    if (derived) {
+      clauses.push("issuedToActorHash = ?");
+      params.push(derived.value);
+    }
+  }
+  if (criteria.table) {
+    clauses.push("scopeTable = ?");
+    params.push(criteria.table);
+  }
+  // Snapshot the to-be-revoked grant ids first so audit captures specifics.
+  var ids = await clusterStorage.executeAll(
+    "SELECT _id FROM _blamejs_break_glass_grants WHERE " + clauses.join(" AND "),
+    params
+  );
+  var nowMs = Date.now();
+  await clusterStorage.execute(
+    "UPDATE _blamejs_break_glass_grants SET revokedAt = ? WHERE " + clauses.join(" AND "),
+    [nowMs].concat(params)
+  );
+  audit.safeEmit({
+    action:   "breakglass.admin.revokeall",
+    outcome:  "success",
+    actor:    requestHelpers.resolveActorWithOverride(opts.callerOpts),
+    reason:   typeof criteria.reason === "string" ? criteria.reason : null,
+    metadata: {
+      filterActorId: criteria.actorId || null,
+      filterTable:   criteria.table || null,
+      revokedCount:  (ids || []).length,
+      revokedIds:    (ids || []).map(function (r) { return r._id; }),
+    },
+  });
+  return { revokedCount: (ids || []).length };
+}
+
 // ---- Sweep (best-effort cleanup of expired grants) ----
 
 async function _sweepExpired(opts) {
@@ -984,6 +1260,14 @@ module.exports = {
   encryptCell:      encryptCell,
   decryptCell:      decryptCell,
   migrate:          migrate,
+  // Service-account bypass — operator-declared per-table, gated by
+  // (apiKey id in allowlist) AND (apiKey carries required role).
+  unsealRowAsService: unsealRowAsService,
+  // Admin tools — for security-team dashboards (listActiveAll) and
+  // incident-response offboarding (revokeAll). Operators wire their
+  // own gate (requireScope or middleware) on the calling routes.
+  listActiveAll:    listActiveAll,
+  revokeAll:        revokeAll,
   BreakGlassError:  BreakGlassError,
 
   // Test-only / sweep — operators with active grant volume wire this

package/lib/db.js

@@ -446,6 +446,7 @@ var FRAMEWORK_SCHEMA = [
       onLockedAccess:             "TEXT NOT NULL DEFAULT 'throw'",
       requireScope:               "TEXT",
       serviceAccountBypassJson:   "TEXT",
+      dekSealed:                  "TEXT",
       auditReasonStorage:         "TEXT NOT NULL DEFAULT 'cleartext'",
       updatedAt:                  "INTEGER NOT NULL",
     },

package/lib/framework-schema.js

@@ -584,6 +584,7 @@ function _breakGlassPoliciesDDL(dialect) {
       "  onLockedAccess             TEXT NOT NULL DEFAULT 'throw'," +
       "  requireScope               TEXT," +
       "  serviceAccountBypassJson   TEXT," +
+      "  dekSealed                  TEXT," +
       "  auditReasonStorage         TEXT NOT NULL DEFAULT 'cleartext'," +
       "  updatedAt                  " + t.INT + " NOT NULL" +
       ")",

package/lib/middleware/bot-guard.js

@@ -50,20 +50,25 @@ var validateOpts = require("../validate-opts");
 var audit = lazyRequire(function () { return require("../audit"); });
 
 // Bot-guard's "trust the proxy header" semantics for actor.ip — the
-// audit event records the apparent source even when behind a CDN.
-// extractActorContext defaults to socket.remoteAddress; we override.
-function _xffIp(req) {
-  var xff = req.headers && req.headers["x-forwarded-for"];
-  if (xff) return String(xff).split(",")[0].trim();
-  return (req.socket && req.socket.remoteAddress) || null;
+// audit event records the apparent source even when behind a CDN, but
+// only when the operator opts in to trustProxy. Without the opt, we
+// stick to socket.remoteAddress so an attacker-forged XFF can't
+// pollute audit attribution.
+function _xffIpFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.clientIp(req, { trustProxy: trustProxy });
+  };
 }
 
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "mode", "onlyForHtml", "allowedAgents", "blockedAgents",
-    "skipPaths", "statusOnBlock", "bodyOnBlock",
+    "skipPaths", "statusOnBlock", "bodyOnBlock", "trustProxy",
   ], "middleware.botGuard");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _xffIp = _xffIpFor(trustProxy);
   var mode = opts.mode || "block";
   var onlyForHtml = opts.onlyForHtml !== false;
   var allowedAgents = (opts.allowedAgents || []).map(function (r) { return r instanceof RegExp ? r : new RegExp(r); });

package/lib/middleware/cors.js

@@ -49,13 +49,13 @@ var safeUrl = require("../safe-url");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
-// CORS audit events trust the proxy header for actor.ip — same
-// semantics as bot-guard (the apparent origin is what matters when
-// blocking cross-origin attempts behind a CDN).
-function _xffIp(req) {
-  var xff = req.headers && req.headers["x-forwarded-for"];
-  if (xff) return String(xff).split(",")[0].trim();
-  return (req.socket && req.socket.remoteAddress) || null;
+// CORS audit events use the proxy-aware client IP only when the
+// operator opts in via `trustProxy`. Default refuses forwarded
+// headers — same boundary as the rest of the v0.5.3 trustProxy sweep.
+function _xffIpFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.clientIp(req, { trustProxy: trustProxy });
+  };
 }
 
 var CorsError = defineClass("CorsError", { alwaysPermanent: true });
@@ -94,26 +94,17 @@ function _canonicalOrigin(input) {
 // supplied. Works for direct deployments (no proxy); operators behind
 // a TLS-terminating proxy that doesn't forward correct Host should set
 // opts.siteOrigin explicitly.
-function _inferRequestOrigin(req) {
+function _inferRequestOrigin(req, trustProxy) {
   if (!req || !req.headers) return null;
   var host = req.headers.host;
   if (!host) return null;
-  // X-Forwarded-Proto wins when present (operator behind a TLS-
-  // terminator, intermediate set the header). Otherwise infer from
-  // the socket — req.socket.encrypted is set by node:tls.
-  var fwdProto = req.headers["x-forwarded-proto"];
-  var proto;
-  if (typeof fwdProto === "string" && fwdProto.length > 0) {
-    proto = fwdProto.split(",")[0].trim().toLowerCase();
-  } else if (req.socket && req.socket.encrypted) {
-    proto = "https";
-  } else {
-    proto = "http";
-  }
+  // Protocol resolution honors the operator's trustProxy opt — without
+  // it, X-Forwarded-Proto is ignored as attacker-forgeable.
+  var proto = requestHelpers.requestProtocol(req, { trustProxy: trustProxy });
   return _canonicalOrigin(proto + "://" + host);
 }
 
-function _isSameOrigin(req, originHeader, configuredSiteOrigins) {
+function _isSameOrigin(req, originHeader, configuredSiteOrigins, trustProxy) {
   // Origin: null + Sec-Fetch-Site: same-origin|none — browser opaqued
   // the Origin (typically because of Referrer-Policy: no-referrer on the
   // page) but is also explicitly telling us the request is same-origin.
@@ -133,8 +124,10 @@ function _isSameOrigin(req, originHeader, configuredSiteOrigins) {
     }
     return false;
   }
-  // Fall back to inferring from the request itself.
-  var reqOrigin = _inferRequestOrigin(req);
+  // Fall back to inferring from the request itself. trustProxy threads
+  // through so operators behind a TLS terminator with X-Forwarded-Proto
+  // can opt in to consult the header.
+  var reqOrigin = _inferRequestOrigin(req, trustProxy);
   return reqOrigin !== null && reqOrigin === canonOrigin;
 }
 
@@ -143,8 +136,11 @@ function create(opts) {
 
   validateOpts(opts, [
     "origins", "siteOrigin", "methods", "headers", "exposeHeaders",
-    "credentials", "maxAgeSeconds", "refuseUnknown",
+    "credentials", "maxAgeSeconds", "refuseUnknown", "trustProxy",
   ], "middleware.cors");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _xffIp = _xffIpFor(trustProxy);
 
   var origins = opts.origins || [];
 
@@ -191,7 +187,7 @@ function create(opts) {
     // Same-origin POST/PUT/etc. carry an Origin header per the Fetch
     // spec but should not be subject to CORS allow-listing — they're
     // the operator's own site talking to itself.
-    if (_isSameOrigin(req, origin, siteOrigins)) return next();
+    if (_isSameOrigin(req, origin, siteOrigins, trustProxy)) return next();
 
     var matched = _matchOrigin(origin, origins);
     if (!matched) {
@@ -217,13 +213,36 @@ function create(opts) {
 
     if (typeof res.setHeader === "function") {
       res.setHeader("Access-Control-Allow-Origin", matched);
-      res.setHeader("Vary", "Origin");
+      // Append "Origin" to Vary instead of overwriting — compression /
+      // auth helpers may have set their own Vary tokens that the cache
+      // layer needs to keep.
+      requestHelpers.appendVary(res, "Origin");
       if (credentials) res.setHeader("Access-Control-Allow-Credentials", "true");
       res.setHeader("Access-Control-Expose-Headers", exposeHeaders);
     }
 
     if (req.method === "OPTIONS" && req.headers["access-control-request-method"]) {
-      // Preflight
+      // Preflight. In refuseUnknown mode, validate the requested
+      // headers against the configured allow-list — refuse with 403
+      // if the client asks for a header we don't allow. Spec says
+      // browsers enforce, but server-side enforcement keeps the
+      // framework's strict-by-default posture consistent.
+      if (refuseUnknown) {
+        var requestedHdrs = req.headers["access-control-request-headers"];
+        if (requestedHdrs) {
+          var allowedSet = headers.toLowerCase().split(",").map(function (s) { return s.trim(); });
+          var asked = String(requestedHdrs).toLowerCase().split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+          for (var ah = 0; ah < asked.length; ah++) {
+            if (allowedSet.indexOf(asked[ah]) === -1) {
+              if (typeof res.writeHead === "function") {
+                res.writeHead(403, { "Content-Type": "text/plain" });
+                res.end("CORS: requested header '" + asked[ah] + "' not in allow-list");
+              }
+              return;
+            }
+          }
+        }
+      }
       if (typeof res.setHeader === "function") {
         res.setHeader("Access-Control-Allow-Methods", methods);
         res.setHeader("Access-Control-Allow-Headers", headers);

package/lib/middleware/csrf-protect.js

@@ -98,13 +98,15 @@ function _parseCookieHeader(header) {
   return out;
 }
 
-function _isHttps(req) {
-  if (req && req.socket && req.socket.encrypted) return true;
-  var fwd = req && req.headers && req.headers["x-forwarded-proto"];
-  if (typeof fwd === "string" && fwd.length > 0) {
-    return fwd.split(",")[0].trim().toLowerCase() === "https";
-  }
-  return false;
+// `_isHttps` defers to `requestHelpers.requestProtocol` so the
+// per-middleware `trustProxy` opt gates whether X-Forwarded-Proto is
+// consulted. Without trustProxy, an attacker could otherwise forge
+// the header to force the Secure cookie attribute (and inversely,
+// suppress it) on direct-to-server connections.
+function _isHttpsFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https";
+  };
 }
 
 function _formatSetCookie(name, value, opts) {
@@ -159,7 +161,11 @@ function create(opts) {
 
   validateOpts(opts, [
     "cookie", "tokenLookup", "fieldName", "headerName", "methods", "audit",
+    "trustProxy",
   ], "middleware.csrfProtect");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _isHttps = _isHttpsFor(trustProxy);
 
   // Tier A — exactly one issuance source.
   var hasCookie = opts.cookie != null && opts.cookie !== false;

package/lib/middleware/rate-limit.js

@@ -52,10 +52,15 @@ var clusterStorage = require("../cluster-storage");
 var audit  = lazyRequire(function () { return require("../audit"); });
 var logger = lazyRequire(function () { return require("../log").boot("rate-limit"); });
 
-function _clientIp(req) {
-  var fwd = req.headers && req.headers["x-forwarded-for"];
-  if (fwd) return String(fwd).split(",")[0].trim();
-  return (req.socket && req.socket.remoteAddress) || "unknown";
+// `_clientIp` defers to `requestHelpers.clientIp`, threading the
+// per-middleware `trustProxy` opt. Default refuses forwarded headers
+// (returning the socket address only) — operators behind a sanitizing
+// reverse proxy opt in via `trustProxy: true` (or a hop count).
+function _clientIpFor(trustProxy) {
+  return function (req) {
+    var ip = requestHelpers.clientIp(req, { trustProxy: trustProxy });
+    return ip || "unknown";
+  };
 }
 
 // ---- Memory backend (token bucket) ----
@@ -221,12 +226,15 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "keyFn", "statusOnLimit", "bodyOnLimit", "header", "skipPaths", "scope",
-    "backend",
+    "backend", "trustProxy",
     // memory backend
     "burst", "refillPerSecond",
     // cluster backend
     "limit", "windowMs", "pruneIntervalMs",
   ], "middleware.rateLimit");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _clientIp = _clientIpFor(trustProxy);
   var keyFn = opts.keyFn || _clientIp;
   var statusOnLimit = opts.statusOnLimit || 429;
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";

package/lib/middleware/security-headers.js

@@ -35,6 +35,7 @@
  *   }
  */
 
+var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
 
 var DEFAULT_PERMISSIONS = [
@@ -62,8 +63,10 @@ function create(opts) {
   validateOpts(opts, [
     "hsts", "contentTypeOptions", "frameOptions", "referrerPolicy",
     "permissionsPolicy", "coop", "coep", "corp",
-    "originAgentCluster", "dnsPrefetchControl", "csp",
+    "originAgentCluster", "dnsPrefetchControl", "csp", "trustProxy",
   ], "middleware.securityHeaders");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
   var hsts = opts.hsts === undefined ? "max-age=63072000; includeSubDomains; preload" : opts.hsts;
   var ctOpts = opts.contentTypeOptions === undefined ? "nosniff" : opts.contentTypeOptions;
   var frameOpts = opts.frameOptions === undefined ? "DENY" : opts.frameOptions;
@@ -78,7 +81,14 @@ function create(opts) {
 
   return function securityHeaders(req, res, next) {
     if (typeof res.setHeader !== "function") return next();
-    if (hsts)       res.setHeader("Strict-Transport-Security", hsts);
+    // RFC 6797 §7.2: HSTS over plain HTTP is meaningless (UAs ignore
+    // it). Skip the header on non-TLS requests so dev-over-HTTP doesn't
+    // surface confusing "Strict-Transport-Security on http://" lines.
+    // requestProtocol respects trustProxy — operators behind a TLS
+    // terminator opt in to read X-Forwarded-Proto.
+    if (hsts && requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https") {
+      res.setHeader("Strict-Transport-Security", hsts);
+    }
     if (ctOpts)     res.setHeader("X-Content-Type-Options", ctOpts);
     if (frameOpts)  res.setHeader("X-Frame-Options", frameOpts);
     if (refPolicy)  res.setHeader("Referrer-Policy", refPolicy);

package/lib/object-store/http-put.js

@@ -56,7 +56,13 @@ function _keyToUrl(baseUrl, key) {
   }
   var b = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   var k = key.startsWith("/") ? key.slice(1) : key;
-  return b + "/" + k;
+  // URL-encode each path segment so reserved characters (?, #, %, space,
+  // unicode, etc.) round-trip safely and don't cross-pollute keys
+  // (e.g. `a%2Fb` and `a/b` would otherwise collide on the wire).
+  // Slashes between segments stay literal (operators use them as a
+  // namespace separator, matching S3 / GCS / Azure conventions).
+  var encoded = k.split("/").map(encodeURIComponent).join("/");
+  return b + "/" + encoded;
 }
 
 function create(config) {

package/lib/request-helpers.js

@@ -112,6 +112,71 @@ function resolveActorWithOverride(callerOpts, baseOverride) {
   return extractActorContext(callerOpts && callerOpts.req, override);
 }
 
+// ---- Proxy-trust primitives (v0.5.3) ----
+//
+// `X-Forwarded-For` and `X-Forwarded-Proto` are operator-trust headers —
+// behind a sanitizing reverse proxy they carry the apparent origin /
+// scheme; without one they're attacker-forgeable. Default is to NOT
+// trust them; operators behind a proxy set `trustProxy: true` (or a
+// hop count for multi-hop chains) per-middleware to opt in.
+//
+//   clientIp(req, { trustProxy }) →  string | null
+//
+//     trustProxy false (default):  socket.remoteAddress only
+//     trustProxy true:             leftmost x-forwarded-for hop, else socket
+//     trustProxy <integer N>:      Nth-from-rightmost xff hop (skip-N-trusted-hops)
+//
+// Middleware accepts `trustProxy` as an opt and threads it through;
+// the framework refuses to silently pick up forwarded headers without
+// the operator's explicit acknowledgement.
+
+function clientIp(req, opts) {
+  if (!req) return null;
+  var trust = opts && opts.trustProxy;
+  if (trust && req.headers) {
+    var xff = req.headers["x-forwarded-for"];
+    if (xff) {
+      var hops = String(xff).split(",").map(function (s) { return s.trim(); });
+      if (trust === true) return hops[0];
+      if (typeof trust === "number" && trust >= 1 && hops.length >= trust) {
+        return hops[hops.length - trust];
+      }
+    }
+  }
+  if (req.socket && typeof req.socket.remoteAddress === "string") return req.socket.remoteAddress;
+  if (req.connection && typeof req.connection.remoteAddress === "string") return req.connection.remoteAddress;
+  return null;
+}
+
+function requestProtocol(req, opts) {
+  if (!req) return "http";
+  var trust = opts && opts.trustProxy;
+  if (trust && req.headers) {
+    var fwd = req.headers["x-forwarded-proto"];
+    if (typeof fwd === "string" && fwd.length > 0) {
+      return String(fwd).split(",")[0].trim().toLowerCase();
+    }
+  }
+  if (req.socket && req.socket.encrypted) return "https";
+  if (req.connection && req.connection.encrypted) return "https";
+  return "http";
+}
+
+// Append a token to a `Vary` response header without dropping prior
+// values (compression middleware sets `Vary: Accept-Encoding`, an
+// auth helper might set `Vary: Authorization`, etc.). Idempotent —
+// re-adding an existing token is a no-op.
+function appendVary(res, value) {
+  if (!res || typeof res.getHeader !== "function" || typeof res.setHeader !== "function") return;
+  var existing = res.getHeader("Vary");
+  if (existing == null || existing === "") { res.setHeader("Vary", value); return; }
+  var tokens = String(existing).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+  var lower = value.toLowerCase();
+  for (var i = 0; i < tokens.length; i++) if (tokens[i].toLowerCase() === lower) return;
+  tokens.push(value);
+  res.setHeader("Vary", tokens.join(", "));
+}
+
 function resolveRoute(req) {
   if (req && typeof req.routePattern === "string" && req.routePattern.length > 0) {
     return req.routePattern;
@@ -201,4 +266,8 @@ module.exports = {
   extractActorContext:       extractActorContext,
   resolveActorWithOverride:  resolveActorWithOverride,
   parseQualityList:          parseQualityList,
+  // v0.5.3 — proxy-trust primitives (default refuses forwarded headers)
+  clientIp:                  clientIp,
+  requestProtocol:           requestProtocol,
+  appendVary:                appendVary,
 };

package/lib/session.js

@@ -128,7 +128,23 @@ async function verify(token) {
   var unsealed = cryptoField.unsealRow("_blamejs_sessions", row);
   var data = null;
   if (unsealed.data) {
-    try { data = safeJson.parse(unsealed.data); } catch (_e) { data = null; }
+    try { data = safeJson.parse(unsealed.data); }
+    catch (e) {
+      // Decrypt-then-parse failure is rare but operationally important —
+      // it usually signals key-rotation skew, DB corruption, or
+      // tampering. Emit an audit event so ops can spot it before the
+      // operator notices empty-`data` flows. data stays null so the
+      // session remains usable for non-data flows.
+      data = null;
+      try {
+        audit.safeEmit({
+          action:   "auth.session.data_unparseable",
+          outcome:  "failure",
+          reason:   (e && e.message) || String(e),
+          metadata: { hasUserId: !!unsealed.userId },
+        });
+      } catch (_ignored) { /* audit best-effort */ }
+    }
   }
   return {
     userId:       unsealed.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",