@blamejs/core 0.8.52 → 0.8.58

package/lib/object-store/sigv4.js

@@ -673,6 +673,21 @@ function create(config) {
     );
   }
 
+  // S3 response-* override query parameters per AWS S3 GetObject docs:
+  // when present on a presigned GET, the named response headers are
+  // overridden by these values. The signing math is identical — the
+  // params just need to be in url.searchParams before canonicalRequest
+  // runs (canonicalQueryString sorts + URL-encodes them deterministically).
+  // Map operator-friendly camelCase to the wire-format query keys.
+  var RESPONSE_HEADER_QUERY_KEYS = {
+    contentDisposition: "response-content-disposition",
+    contentType:        "response-content-type",
+    contentLanguage:    "response-content-language",
+    contentEncoding:    "response-content-encoding",
+    cacheControl:       "response-cache-control",
+    expires:            "response-expires",
+  };
+
   function _presign(method, opts) {
     opts = opts || {};
     if (!opts.key || typeof opts.key !== "string") {
@@ -691,6 +706,37 @@ function create(config) {
         " (7 days, SigV4 hard cap)", true);
     }
 
+    // Validate opts.responseHeaders shape — operators pass camelCase
+    // keys; refuse unknown keys at config-time so a typo surfaces at
+    // boot. Reject CR/LF/NUL in any value as defense in depth (the
+    // values flow into URL query params + the signed canonical request,
+    // and a CR/LF could smuggle into a downstream proxy log).
+    var responseHeaders = opts.responseHeaders;
+    if (responseHeaders !== undefined && responseHeaders !== null) {
+      if (typeof responseHeaders !== "object") {
+        throw _err("INVALID_RESPONSE_HEADERS",
+          "presigned URL: responseHeaders must be an object", true);
+      }
+      var rhKeys = Object.keys(responseHeaders);
+      for (var rhi = 0; rhi < rhKeys.length; rhi += 1) {
+        var rhk = rhKeys[rhi];
+        if (!Object.prototype.hasOwnProperty.call(RESPONSE_HEADER_QUERY_KEYS, rhk)) {
+          throw _err("INVALID_RESPONSE_HEADERS",
+            "presigned URL: responseHeaders.'" + rhk + "' is not recognised " +
+            "(allowed: " + Object.keys(RESPONSE_HEADER_QUERY_KEYS).join(", ") + ")", true);
+        }
+        var rhv = responseHeaders[rhk];
+        if (typeof rhv !== "string" || rhv.length === 0) {
+          throw _err("INVALID_RESPONSE_HEADERS",
+            "presigned URL: responseHeaders.'" + rhk + "' must be a non-empty string", true);
+        }
+        if (/[\r\n\0]/.test(rhv)) {
+          throw _err("INVALID_RESPONSE_HEADERS",
+            "presigned URL: responseHeaders.'" + rhk + "' contains CR/LF/NUL — refused as a header-injection vector", true);
+        }
+      }
+    }
+
     var url = _keyToUrl(opts.key);
     var date = opts.date || new Date();
     var amzDate = _formatAmzDate(date);
@@ -721,6 +767,14 @@ function create(config) {
     if (config.sessionToken) {
       url.searchParams.set("X-Amz-Security-Token", config.sessionToken);
     }
+    // Response-header overrides — set BEFORE canonicalRequest so they
+    // become part of the signed query string.
+    if (responseHeaders) {
+      for (var rhk2 = 0; rhk2 < rhKeys.length; rhk2 += 1) {
+        var camel = rhKeys[rhk2];
+        url.searchParams.set(RESPONSE_HEADER_QUERY_KEYS[camel], responseHeaders[camel]);
+      }
+    }
 
     // Payload hash for query-string presigning is the literal string
     // "UNSIGNED-PAYLOAD" — the body is not part of the signature.

package/lib/public-suffix.js

@@ -0,0 +1,414 @@
+"use strict";
+/**
+ * @module     b.publicSuffix
+ * @nav        Validation
+ * @title      Public Suffix
+ * @order      140
+ * @card       Mozilla Public Suffix List substrate — exposes
+ *             `b.publicSuffix.publicSuffix(domain)` /
+ *             `b.publicSuffix.organizationalDomain(domain)` /
+ *             `b.publicSuffix.isPublicSuffix(domain)` for the
+ *             "registrable domain" derivation that DMARCbis,
+ *             BIMI, cookie-scope, and same-site policies all need.
+ *
+ * @intro
+ *   The Public Suffix List (PSL) is Mozilla's published catalog of
+ *   "effective top-level domains" — labels under which independent
+ *   parties can register names (`com`, `co.uk`, `s3.amazonaws.com`,
+ *   …). It is the canonical reference for deriving the
+ *   "organizational domain" of a hostname: the registrable label one
+ *   level below its public suffix. Several upstream specs lean on it
+ *   directly:
+ *
+ *     - DMARCbis (IETF DMARC WG) replaces RFC 7489's heuristic
+ *       organizational-domain derivation with a PSL lookup, including
+ *       new `psd=` (public-suffix-domain policy) and `np=`
+ *       (non-public-suffix policy) tags
+ *     - BIMI (RFC 9669 + draft) uses the same organizational-domain
+ *       logic to scope brand indicators
+ *     - Same-site cookie scoping (RFC 6265bis) refers to the PSL when
+ *       deciding whether `Domain=co.uk` is a "public suffix" attempt
+ *
+ *   This module ships the PSL as a vendored data file
+ *   (`lib/vendor/public-suffix-list.dat`) and parses it once at
+ *   module-load. The algorithm is the canonical one published at
+ *   https://publicsuffix.org/list/ (exact > exception > wildcard).
+ *
+ *   Surface:
+ *
+ *     b.publicSuffix.publicSuffix("example.co.uk")
+ *       // → "co.uk"
+ *
+ *     b.publicSuffix.organizationalDomain("foo.bar.example.co.uk")
+ *       // → "example.co.uk"
+ *
+ *     b.publicSuffix.isPublicSuffix("co.uk")
+ *       // → true
+ *
+ *     b.publicSuffix.lookupSource()
+ *       // → { vendoredAt: "2026-05-09", entries: <n>, sha256: "..." }
+ *
+ *   IDN inputs are punycode-normalized via Node's `url.domainToASCII`
+ *   before lookup. Bad inputs throw `PublicSuffixError`.
+ */
+
+var fs       = require("node:fs");
+var nodePath = require("node:path");
+var nodeCrypto = require("node:crypto");
+var nodeUrl  = require("node:url");
+var { PublicSuffixError } = require("./framework-error");
+
+// Vendored PSL data file. Per the framework's vendoring policy this
+// is checked in alongside the bundled npm-deps and tracked in
+// lib/vendor/MANIFEST.json. Loaded synchronously at module-init —
+// missing file is a packaging break operators must catch at boot,
+// not on first lookup at request time.
+var PSL_PATH = nodePath.join(__dirname, "vendor", "public-suffix-list.dat");
+
+function _err(code, message) {
+  return new PublicSuffixError(code, message);
+}
+
+// _normalizeInput — lowercase + IDN-normalize a candidate domain.
+// Returns a plain ASCII (punycode) string with no leading/trailing
+// dots and no empty labels. Throws PublicSuffixError on bad shape so
+// callers see a single error class for every reject path.
+function _normalizeInput(domain) {
+  if (typeof domain !== "string") {
+    throw _err("public-suffix/invalid-domain",
+      "publicSuffix: domain must be a string");
+  }
+  if (domain.length === 0) {
+    throw _err("public-suffix/invalid-domain",
+      "publicSuffix: domain must not be empty");
+  }
+  if (domain.length > 253) {
+    // RFC 1035 §2.3.4 — 253 octets max for the wire form (255 minus
+    // length-byte + null). Anything longer is structurally invalid.
+    throw _err("public-suffix/invalid-domain",
+      "publicSuffix: domain exceeds 253-octet RFC 1035 limit");
+  }
+  // Strip a single trailing dot (FQDN form). Multiple trailing dots,
+  // leading dots, or embedded empty labels remain rejected below.
+  var s = domain.toLowerCase();
+  if (s.charCodeAt(s.length - 1) === 46 /* "." */) {
+    s = s.slice(0, -1);
+    if (s.length === 0) {
+      throw _err("public-suffix/invalid-domain",
+        "publicSuffix: domain must not be a bare dot");
+    }
+  }
+  // Reject control / null / whitespace bytes outright. domainToASCII
+  // would silently rewrite some of them; we want hostile inputs to
+  // throw, not be coerced.
+  for (var i = 0; i < s.length; i += 1) {
+    var cp = s.charCodeAt(i);
+    if (cp < 0x21 || cp === 0x7f) {
+      throw _err("public-suffix/invalid-domain",
+        "publicSuffix: domain contains control / whitespace byte");
+    }
+  }
+  // IDN-normalize — non-ASCII labels become xn--… via Node's UTS #46
+  // implementation. Empty string back means the input was malformed
+  // beyond what UTS #46 will accept (e.g. starts with U+FFFD).
+  var ascii = nodeUrl.domainToASCII(s);
+  if (!ascii) {
+    throw _err("public-suffix/invalid-domain",
+      "publicSuffix: domain failed IDN normalization");
+  }
+  // No empty labels (`foo..bar`) and no leading dot.
+  if (ascii.indexOf("..") !== -1 || ascii.charCodeAt(0) === 46) {
+    throw _err("public-suffix/invalid-domain",
+      "publicSuffix: domain contains empty label");
+  }
+  return ascii;
+}
+
+// _parsePsl — walk the vendored .dat file once at load and produce
+// the lookup tables. The .dat format is:
+//   - blank lines: skip
+//   - lines starting with "//": comment / section marker
+//   - "*.suffix": wildcard rule (matches one extra label)
+//   - "!suffix":  exception rule (suppresses a parent wildcard)
+//   - "suffix":   exact rule
+//
+// Non-ASCII rule labels are punycode-encoded so they match
+// IDN-normalized input directly. The original PSL file already
+// contains them in punycode form; we still canonicalize defensively
+// in case a future revision changes shape.
+function _parsePsl(text) {
+  var exact     = Object.create(null); // suffix -> true
+  var wildcard  = Object.create(null); // parent  -> true (e.g. "ck" for "*.ck")
+  var exception = Object.create(null); // suffix -> true (full e.g. "www.ck")
+  var lines = text.split(/\r?\n/);
+  var entries = 0;
+
+  for (var i = 0; i < lines.length; i += 1) {
+    var line = lines[i];
+    if (!line) continue;
+    // A space within a line is the start of an inline comment /
+    // metadata note (Mozilla's convention); take the leading token.
+    var sp = line.indexOf(" ");
+    if (sp !== -1) line = line.slice(0, sp);
+    if (!line) continue;
+    if (line.charCodeAt(0) === 47 /* "/" */ &&
+        line.charCodeAt(1) === 47) continue;
+
+    var rule = line.toLowerCase();
+    // IDN-normalize each rule. domainToASCII returns "" on failure;
+    // we skip rather than throw — the PSL is curated and any
+    // failure here means a future format change rather than hostile
+    // input from a caller.
+    var asciiRule = nodeUrl.domainToASCII(rule);
+    if (!asciiRule) continue;
+
+    if (asciiRule.charCodeAt(0) === 33 /* "!" */) {
+      exception[asciiRule.slice(1)] = true;
+    } else if (asciiRule.charCodeAt(0) === 42 /* "*" */ &&
+               asciiRule.charCodeAt(1) === 46 /* "." */) {
+      wildcard[asciiRule.slice(2)] = true;
+    } else {
+      exact[asciiRule] = true;
+    }
+    entries += 1;
+  }
+
+  return { exact: exact, wildcard: wildcard, exception: exception, entries: entries };
+}
+
+// Initialize once at module load. Operators with a missing or
+// unreadable vendored file see a clear startup-time failure ("config-
+// time" tier — throw rather than silently fall back to a permissive
+// default that would let phishing-shaped hosts past).
+var _data;
+var _sourceMeta;
+(function _init() {
+  var raw;
+  try {
+    raw = fs.readFileSync(PSL_PATH);
+  } catch (e) {
+    throw _err("public-suffix/not-loaded",
+      "publicSuffix: vendored PSL data file missing at " + PSL_PATH +
+      " (" + (e && e.message ? e.message : "unknown error") + ")");
+  }
+  var sha256 = nodeCrypto.createHash("sha256").update(raw).digest("hex");
+  var parsed = _parsePsl(raw.toString("utf8"));
+  _data = parsed;
+  // Read vendoredAt from MANIFEST.json so the metadata stays in lock-
+  // step with the vendor refresh. Falls back to "unknown" if the
+  // manifest can't be read or doesn't carry the entry — the parsed
+  // sha256 still uniquely identifies the file content.
+  var vendoredAt = "unknown";
+  try {
+    var manifestPath = nodePath.join(__dirname, "vendor", "MANIFEST.json");
+    var manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));  // allow:bare-json-parse — MANIFEST.json is a framework-internal vendored file checked in alongside code; never from operator / network input
+    var entry = manifest && manifest.packages && manifest.packages["publicsuffix-list"];
+    if (entry && typeof entry.bundledAt === "string") vendoredAt = entry.bundledAt;
+  } catch (_e) {
+    // Manifest missing / malformed — continue with vendoredAt =
+    // "unknown". This is observability-only metadata; a request-path
+    // failure here would punish operators for a non-fatal drift.
+  }
+  _sourceMeta = Object.freeze({
+    vendoredAt: vendoredAt,
+    entries: parsed.entries,
+    sha256: sha256,
+  });
+})();
+
+// _lookupAscii — core algorithm against the parsed tables. Operates
+// on a normalized ASCII domain. Returns the longest matching public
+// suffix, or null if no rule matches and the implicit-* rule produces
+// a shorter result than the input (which only happens for single-
+// label inputs — those have no public suffix per the algorithm).
+function _lookupAscii(ascii) {
+  var labels = ascii.split(".");
+
+  // Walk longest-to-shortest. Per Mozilla's algorithm:
+  //   1. If an exception rule "!a.b.c" matches the input, the public
+  //      suffix is the parent of the matched rule (one label dropped).
+  //   2. Else if an exact rule matches, that's the suffix.
+  //   3. Else if a wildcard rule "*.b.c" matches (input ends in
+  //      ".b.c" with at least one extra label), the suffix is one
+  //      label deeper than the wildcard's parent.
+  //   4. Else the implicit "*" rule applies: suffix = the rightmost
+  //      label.
+  //
+  // Exception > exact > wildcard. We collect candidates per rule
+  // type and pick the precedence order at the end.
+  var exceptionMatch = null;
+  var exactMatch     = null;
+  var wildcardMatch  = null;
+
+  for (var i = 0; i < labels.length; i += 1) {
+    var candidate = labels.slice(i).join(".");
+    if (_data.exception[candidate]) {
+      // Exception rule's "public suffix" is the candidate with its
+      // leftmost label removed (the rule overrides a parent wildcard
+      // by saying "this exact name is registrable, suffix is below").
+      var parentLabels = labels.slice(i + 1);
+      if (parentLabels.length > 0) {
+        exceptionMatch = parentLabels.join(".");
+      } else {
+        exceptionMatch = "";
+      }
+      break;
+    }
+    if (!exactMatch && _data.exact[candidate]) {
+      exactMatch = candidate;
+    }
+    if (!wildcardMatch && i > 0) {
+      // For "*.b.c" to match input "a.b.c": the wildcard rule keys
+      // off the parent ("b.c"). We're at label-index i; the parent
+      // suffix is labels[i..]. The wildcard table indexes by parent,
+      // so a hit at "b.c" means input "a.b.c" matches the rule
+      // "*.b.c", and the public suffix is labels[i-1..] (one extra
+      // label included).
+      if (_data.wildcard[candidate]) {
+        wildcardMatch = labels.slice(i - 1).join(".");
+      }
+    }
+  }
+
+  if (exceptionMatch !== null) return exceptionMatch === "" ? null : exceptionMatch;
+  if (exactMatch    !== null) return exactMatch;
+  if (wildcardMatch !== null) return wildcardMatch;
+  // Implicit "*" rule — every TLD is its own public suffix even when
+  // the PSL doesn't list it. For a multi-label input, the suffix is
+  // the rightmost label. For a single-label input, there is no
+  // registrable parent (the input IS a TLD), return null so callers
+  // distinguish "is a public suffix" from "has a public suffix".
+  if (labels.length >= 2) return labels[labels.length - 1];
+  return null;
+}
+
+/**
+ * @primitive b.publicSuffix.publicSuffix
+ * @signature b.publicSuffix.publicSuffix(domain)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.publicSuffix.organizationalDomain, b.publicSuffix.isPublicSuffix
+ *
+ * Returns the longest matching public suffix for `domain`, per the
+ * Mozilla PSL algorithm (https://publicsuffix.org/list/). Exception
+ * rules outrank exact rules, exact rules outrank wildcards, wildcards
+ * outrank the implicit "*" rule. Input is lowercased and IDN-
+ * normalized (punycode) before lookup. Returns `null` for inputs that
+ * have no registrable parent (single-label TLDs, public-suffix-only
+ * inputs).
+ *
+ * Throws `PublicSuffixError` (`public-suffix/invalid-domain`) for
+ * non-string / empty / overlong / control-byte-bearing inputs.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   b.publicSuffix.publicSuffix("example.co.uk");
+ *   // → "co.uk"
+ *   b.publicSuffix.publicSuffix("foo.bar.example.com");
+ *   // → "com"
+ */
+function publicSuffix(domain) {
+  var ascii = _normalizeInput(domain);
+  return _lookupAscii(ascii);
+}
+
+/**
+ * @primitive b.publicSuffix.organizationalDomain
+ * @signature b.publicSuffix.organizationalDomain(domain)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.publicSuffix.publicSuffix, b.publicSuffix.isPublicSuffix
+ *
+ * Returns the registrable "organizational domain" — the public
+ * suffix plus exactly one label to its left. This is the value
+ * DMARCbis, BIMI, and cookie-scope policies operate on when they
+ * decide whether two hostnames belong to the same registered party.
+ *
+ * Returns `null` when `domain` IS a public suffix (no organizational
+ * parent exists — `co.uk` has no registrable owner, only the labels
+ * registered under it do).
+ *
+ * Throws `PublicSuffixError` (`public-suffix/invalid-domain`) on bad
+ * input shape.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   b.publicSuffix.organizationalDomain("foo.bar.example.co.uk");
+ *   // → "example.co.uk"
+ *   b.publicSuffix.organizationalDomain("example.com");
+ *   // → "example.com"
+ *   b.publicSuffix.organizationalDomain("co.uk");
+ *   // → null
+ */
+function organizationalDomain(domain) {
+  var ascii = _normalizeInput(domain);
+  var suffix = _lookupAscii(ascii);
+  if (suffix === null) return null;
+  if (suffix === ascii) return null; // input IS a public suffix
+  // Walk back one label from the suffix. ascii ends in "." + suffix
+  // by construction (exact / wildcard / implicit-* all guarantee it).
+  var suffixLabels = suffix.split(".").length;
+  var labels = ascii.split(".");
+  if (labels.length <= suffixLabels) return null;
+  return labels.slice(labels.length - suffixLabels - 1).join(".");
+}
+
+/**
+ * @primitive b.publicSuffix.isPublicSuffix
+ * @signature b.publicSuffix.isPublicSuffix(domain)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.publicSuffix.publicSuffix, b.publicSuffix.organizationalDomain
+ *
+ * Returns `true` when `domain` is itself a public suffix (e.g.
+ * `"co.uk"`, `"com"`, `"s3.amazonaws.com"`), `false` otherwise.
+ * DMARCbis uses this distinction for its `psd=` (public-suffix-
+ * domain) policy: a TLD operator publishing a record on `co.uk`
+ * itself is a different actor than `example.co.uk` publishing one.
+ *
+ * Throws `PublicSuffixError` (`public-suffix/invalid-domain`) on bad
+ * input shape.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   b.publicSuffix.isPublicSuffix("co.uk");
+ *   // → true
+ *   b.publicSuffix.isPublicSuffix("example.co.uk");
+ *   // → false
+ */
+function isPublicSuffix(domain) {
+  var ascii = _normalizeInput(domain);
+  var suffix = _lookupAscii(ascii);
+  return suffix !== null && suffix === ascii;
+}
+
+/**
+ * @primitive b.publicSuffix.lookupSource
+ * @signature b.publicSuffix.lookupSource()
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.publicSuffix.publicSuffix
+ *
+ * Returns transparency metadata for the loaded PSL: the date the
+ * file was vendored (`vendoredAt`, ISO 8601 from
+ * `lib/vendor/MANIFEST.json`), the parsed-rule count (`entries`),
+ * and the SHA-256 hash of the raw file contents (`sha256`, hex). Use
+ * to surface in operator dashboards / forensic logs so a snapshot of
+ * the PSL the framework was making decisions against is reproducible
+ * after the fact.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var src = b.publicSuffix.lookupSource();
+ *   // → { vendoredAt: "2026-05-09", entries: 9000, sha256: "a008..." }
+ */
+function lookupSource() {
+  return _sourceMeta;
+}
+
+module.exports = {
+  publicSuffix:         publicSuffix,
+  organizationalDomain: organizationalDomain,
+  isPublicSuffix:       isPublicSuffix,
+  lookupSource:         lookupSource,
+};

package/lib/safe-buffer.js

@@ -379,6 +379,12 @@ var BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
 var TRACE_ID_HEX_RE = /^[0-9a-f]{32}$/;                                            // allow:regex-no-length-cap — fixed 32 hex chars (W3C §3.2.2.3)
 var SPAN_ID_HEX_RE  = /^[0-9a-f]{16}$/;                                            // allow:regex-no-length-cap — fixed 16 hex chars (W3C §3.2.2.4)
 
+// IPv6 hextet predicate — 1..4 hex characters (case-insensitive).
+// Used by every IPv6 string-to-bytes parser that splits on `:` and
+// validates each group. Extracted from guard-cidr / safe-json /
+// network-tls so the shape lives in one place.
+var IPV6_HEXTET_RE = /^[0-9a-fA-F]{1,4}$/;                                         // allow:regex-no-length-cap — RFC 4291 §2.2 hextet width
+
 // RFC 7230 §3.2.6 / RFC 9110 §5.1 `tchar` grammar — used by HTTP
 // header tokens, MIME parameter names, W3C Baggage keys, etc.
 // Length-agnostic; callers cap per protocol.
@@ -546,6 +552,7 @@ module.exports = {
   stripTrailingHspace:   stripTrailingHspace,
   HEX_RE:                HEX_RE,
   BASE64URL_RE:          BASE64URL_RE,
+  IPV6_HEXTET_RE:        IPV6_HEXTET_RE,
   TRACE_ID_HEX_RE:       TRACE_ID_HEX_RE,
   SPAN_ID_HEX_RE:        SPAN_ID_HEX_RE,
   RFC7230_TCHAR_RE:      RFC7230_TCHAR_RE,

package/lib/safe-json.js

@@ -564,7 +564,7 @@ var formats = {
 
     var all = leftParts.concat(rightParts);
     for (var i = 0; i < all.length; i++) {
-      if (!/^[0-9a-fA-F]{1,4}$/.test(all[i])) return false;
+      if (!safeBuffer.IPV6_HEXTET_RE.test(all[i])) return false;
     }
     return true;
   },

package/lib/static.js

@@ -119,6 +119,20 @@ var DEFAULTS = Object.freeze({
   // serve event is the audit-worthy act, not a precursor.
   auditSuccess:                     true,
   auditFailures:                    true,
+  // forceAttachmentForNonText — stored-XSS defense for user-upload
+  // directories. Default OFF because operator-curated asset dirs
+  // (CSS / JS bundles / fonts) need inline render. Opt in for
+  // user-upload-backed mounts so HTML / JS / SVG without sanitizer
+  // / PDF / archives are forced to download. See
+  // `_shouldForceAttachment` below for the safe-render allowlist.
+  forceAttachmentForNonText:        false,
+  // Companion knobs — when forceAttachmentForNonText is on, allow
+  // image/svg+xml inline render IF an SVG sanitizer gate is wired
+  // (default true; the framework's default-on contentSafety wiring
+  // includes b.guardSvg). PDF inline render defaults OFF — operators
+  // who serve a trusted PDF library opt in explicitly.
+  safeRenderSvg:                    true,
+  safeRenderPdf:                    false,
 });
 
 // Module-level metadata cache. Entries hold:
@@ -240,6 +254,87 @@ function _isRiskyInlineMime(contentType) {
   return RISKY_INLINE_MIMES[bare] === true;
 }
 
+// Safe-render allowlist for `forceAttachmentForNonText`. When the
+// operator opts in, every served file whose Content-Type is NOT
+// `text/*` AND NOT in this allowlist is forced to download via
+// `Content-Disposition: attachment` plus `X-Content-Type-Options:
+// nosniff`. The list is intentionally narrow:
+//
+//   - image/png / jpeg / webp / gif: raster formats — browsers can't
+//     interpret as scripts, no inline-execution surface.
+//   - image/svg+xml: ONLY when an SVG-sanitizer is wired via
+//     `contentSafety` (the default-on `b.guardSvg` covers this) —
+//     SVG is XML and can carry `<script>` / event handlers; we
+//     refuse to render it inline without sanitization.
+//   - application/pdf: ONLY when `safeRenderPdf: true` is explicitly
+//     set. PDFs commonly carry JavaScript and can bypass the SOP via
+//     embedded forms; default is to force download.
+var SAFE_RENDER_RASTER_MIMES = {
+  "image/png":   true,
+  "image/jpeg":  true,
+  "image/webp":  true,
+  "image/gif":   true,
+};
+
+function _bareMime(contentType) {
+  if (typeof contentType !== "string" || contentType.length === 0) return "";
+  var semi = contentType.indexOf(";");
+  return (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase();
+}
+
+// _shouldForceAttachment — decide whether the operator's opt-in policy
+// forces this content type to download. Returns true when the
+// response should carry `Content-Disposition: attachment` +
+// `X-Content-Type-Options: nosniff`.
+//
+// Allowlist intent: text/plain / text/css / text/markdown render
+// inline (no execution surface), raster images render inline (no
+// execution surface), SVG renders inline ONLY when an SVG sanitizer
+// gate is wired AND `safeRenderSvg` is enabled, PDF renders inline
+// ONLY when `safeRenderPdf` is explicitly enabled. text/html and
+// text/javascript are inside `text/*` but the browser executes them
+// — they go through the risky path. Everything else (HTML, JS, MJS,
+// XML, executables, archives, fonts when served from a user-upload
+// directory) gets forced download to defeat stored-XSS via the
+// upload directory.
+function _shouldForceAttachment(contentType, ext, contentSafetyMap, allowSvgRender, allowPdfRender) {
+  var bare = _bareMime(contentType);
+  if (bare.length === 0) return true; // unknown MIME → safest path
+  // text/html / text/xml / text/javascript / xhtml are inside `text/*`
+  // but the browser executes them — risky path.
+  if (bare === "text/html" || bare === "text/xml" ||
+      bare === "text/javascript" || bare === "application/xhtml+xml") {
+    return true;
+  }
+  if (bare.indexOf("text/") === 0) return false;
+  if (SAFE_RENDER_RASTER_MIMES[bare]) return false;
+  if (bare === "image/svg+xml") {
+    if (!allowSvgRender) return true;
+    if (!contentSafetyMap || typeof contentSafetyMap !== "object") return true;
+    var svgGate = contentSafetyMap[".svg"];
+    if (!svgGate || typeof svgGate.check !== "function") return true;
+    return false;
+  }
+  if (bare === "application/pdf") {
+    return !allowPdfRender;
+  }
+  // Defense-in-depth: files served with .html / .htm / .xhtml / .js /
+  // .mjs / .svg / .xml / .pdf extensions but a generic
+  // application/octet-stream MIME still get forced download. The
+  // extension check catches misconfigured tables / sniffed-down MIMEs.
+  if (ext === ".html" || ext === ".htm" || ext === ".xhtml" ||
+      ext === ".js" || ext === ".mjs" || ext === ".svg" ||
+      ext === ".xml" || ext === ".pdf") {
+    if (ext === ".svg" && allowSvgRender) {
+      if (contentSafetyMap && contentSafetyMap[".svg"] &&
+          typeof contentSafetyMap[".svg"].check === "function") return false;
+    }
+    if (ext === ".pdf" && allowPdfRender) return false;
+    return true;
+  }
+  return true;
+}
+
 // Build a safe Content-Disposition value for an attachment. The
 // filename is RFC 5987-encoded so non-ASCII characters survive without
 // allowing CR/LF header injection.
@@ -379,6 +474,12 @@ function _validateCreateOpts(opts) {
   validateOpts.optionalBoolean(opts.auditFailures, "staticServe.create: auditFailures", StaticServeError);
   validateOpts.optionalBoolean(opts.safeAttachmentForRiskyMimes,
     "staticServe.create: safeAttachmentForRiskyMimes", StaticServeError);
+  validateOpts.optionalBoolean(opts.forceAttachmentForNonText,
+    "staticServe.create: forceAttachmentForNonText", StaticServeError);
+  validateOpts.optionalBoolean(opts.safeRenderSvg,
+    "staticServe.create: safeRenderSvg", StaticServeError);
+  validateOpts.optionalBoolean(opts.safeRenderPdf,
+    "staticServe.create: safeRenderPdf", StaticServeError);
   numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxBytesPerActorPerWindowMs,
     "staticServe.create: maxBytesPerActorPerWindowMs", StaticServeError, "BAD_OPT");
   numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxBytesAllActorsPerWindowMs,
@@ -504,6 +605,7 @@ function create(opts) {
     "maxBytesPerActorPerWindowMs", "maxBytesAllActorsPerWindowMs",
     "bandwidthWindowMs", "maxConcurrentDownloadsPerActor", "maxIdleMs",
     "contentSafety", "contentSafetyDisabledReason",
+    "forceAttachmentForNonText", "safeRenderSvg", "safeRenderPdf",
   ], "staticServe.create");
   _validateCreateOpts(opts);
   var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
@@ -556,6 +658,9 @@ function create(opts) {
   var auditFailures   = cfg.auditFailures;
   var acceptRanges    = cfg.acceptRanges;
   var safeAttachment  = !!cfg.safeAttachmentForRiskyMimes;
+  var forceAttachmentForNonText = !!cfg.forceAttachmentForNonText;
+  var allowSvgRender  = cfg.safeRenderSvg !== false;
+  var allowPdfRender  = !!cfg.safeRenderPdf;
   var perActorCap     = cfg.maxBytesPerActorPerWindowMs;
   var globalCap       = cfg.maxBytesAllActorsPerWindowMs;
   var bandwidthWindowMs = cfg.bandwidthWindowMs;
@@ -913,6 +1018,21 @@ function create(opts) {
     if (safeAttachment && _isRiskyInlineMime(headers["Content-Type"])) {
       headers["Content-Disposition"] = _attachmentDisposition(absPath);
     }
+    // Stored-XSS defense for user-upload directories: when
+    // forceAttachmentForNonText is on, force download for every MIME
+    // outside the safe-render allowlist (text/* except html/xml/js,
+    // image/png|jpeg|webp|gif, image/svg+xml only when an SVG sanitizer
+    // gate is wired, application/pdf only when safeRenderPdf is
+    // explicitly on). Pairs with X-Content-Type-Options: nosniff so
+    // browsers can't sniff the bytes back into an executable type.
+    if (forceAttachmentForNonText) {
+      var dispoExt = path.extname(absPath).toLowerCase();
+      if (_shouldForceAttachment(headers["Content-Type"], dispoExt, contentSafety,
+                                 allowSvgRender, allowPdfRender)) {
+        headers["Content-Disposition"] = _attachmentDisposition(absPath);
+        headers["X-Content-Type-Options"] = "nosniff";
+      }
+    }
     if (acceptRanges) headers["Accept-Ranges"] = "bytes";
     if (range) headers["Content-Range"] = "bytes " + range.start + "-" + range.end + "/" + meta.size;