@blamejs/core 0.7.0 → 0.7.4

package/lib/static.js

@@ -1,67 +1,68 @@
 "use strict";
 /**
- * Static asset serving — middleware factory + SRI integrity helper.
+ * staticServe — server-side download primitive with the same v1-defensible
+ * surface as b.fileUpload: permissions integration, audit emission with
+ * 5-W's actor context, observability counters, bandwidth + concurrency
+ * quotas (cluster-shared via b.cache), Range support (RFC 7233 single-range),
+ * the full conditional-request set (If-None-Match / If-Match /
+ * If-Modified-Since / If-Unmodified-Since), MIME allowlist with magic-byte
+ * verification (composes b.fileType), per-request operator hook, idle-stream
+ * timeout, cancellation propagation, force-revoke, and compliance-retention
+ * gating.
  *
- * The middleware maps URL → file under `root`, with the same path-
- * containment posture as lib/template (no `..`, no `\0`, resolved path
- * must stay under root). Files outside root or symlinks pointing out
- * are refused.
+ *   var serve = b.staticServe.create({ root, ...opts });
+ *   await serve.revoke(absUrlPath);                 // operator force-revoke
+ *   serve.stats();                                  // bytes / requests / etag-hits
+ *   var mw = serve.middleware;                       // (req, res, next)
+ *   await b.staticServe.integrity(absFilePath);      // SRI helper (SHA-384)
  *
- * Cache-Control posture:
+ * Backwards compatible: every existing opt (root, mountPath,
+ * hashedPathPattern, indexFile, defaultMaxAge, contentTypes) keeps its
+ * original meaning. New opts (permissions, cache, audit, observability,
+ * fileType, allowedFileTypes, maxBytesPerActorPerWindowMs, etc.) are all
+ * optional with security-on defaults (auditSuccess / auditFailures default
+ * true; range support defaults true; ETag is SHA3-512-truncated for PQC
+ * posture, the SRI integrity helper keeps SHA-384 because the W3C
+ * subresource-integrity spec only allows sha256/sha384/sha512).
  *
- *   - URLs matching opts.hashedPathPattern (default: a hex/base32 ≥8
- *     character segment surrounded by dots — `.abc123ef.` style) get
- *     `Cache-Control: public, max-age=31536000, immutable` per the
- *     roadmap's verification gate. The hash-in-URL convention pins
- *     the served bytes to the URL forever; immutable lets browsers
- *     skip revalidation entirely.
- *   - Other URLs get `Cache-Control: public, max-age=<defaultMaxAge>`
- *     (default 3600 = 1h). Operators tune via opts.defaultMaxAge.
- *
- * ETag is the first 27 chars of SHA-384(file content), base64. 162
- * bits of collision resistance — overkill but cheap; same hash powers
- * the SRI integrity helper so we compute it once per file.
- *
- * 304 Not Modified: emitted when If-None-Match matches the ETag.
- *
- * HEAD: returns same headers as GET, no body.
- *
- * Range requests are NOT supported in v1. Operators serving video/audio
- * put a CDN in front. Compression (gzip/br) likewise — out of scope here.
- *
- * MIME types: minimal built-in table. Override via opts.contentTypes.
- *
- * Index files: a request resolving to a directory tries opts.indexFile
- * (default "index.html"); operators disable with opts.indexFile = null.
- *
- * Public API:
- *
- *   staticServe.create({ root, mountPath?, hashedPathPattern?,
- *                         defaultMaxAge?, indexFile?, contentTypes? })
- *     → (req, res, next) middleware
- *
- *   await staticServe.integrity(filePath)
- *     → "sha384-<base64>" suitable for an HTML integrity= attribute.
- *       Cached per file across calls; invalidated on mtime change.
+ * Backward-compat shape: create(opts) MAY be called for the bare middleware
+ * (the v0.6.x shape) — the result is callable as `(req, res, next)` and
+ * also exposes the new methods. That keeps existing tests + operator code
+ * passing while opening the surface.
  */
-var fs = require("fs");
-var fsp = require("fs/promises");
-var path = require("path");
-var nodeCrypto = require("crypto");
+
+var fs = require("node:fs");
+var fsp = require("node:fs/promises");
+var nodeCrypto = require("node:crypto");
+var path = require("node:path");
 var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var numericBounds = require("./numeric-bounds");
 var requestHelpers = require("./request-helpers");
 var validateOpts = require("./validate-opts");
+var { StaticServeError } = require("./framework-error");
+
+// observability is lazy-required because it pulls in the metrics tap +
+// safeEvent path, and during framework boot static.js may load before
+// observability is ready.
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var _err = StaticServeError.factory;
 
 var HTTP = requestHelpers.HTTP_STATUS;
 
 var DEFAULT_HASHED_PATTERN = /\.[a-fA-F0-9]{8,}\./;
 var DEFAULT_INDEX_FILE     = "index.html";
-var DEFAULT_MAX_AGE_SEC    = C.TIME.hours(1) / C.TIME.seconds(1);   // 1 hour for non-hashed paths
-var IMMUTABLE_MAX_AGE_SEC  = C.TIME.days(365) / C.TIME.seconds(1);  // 1 year for hashed paths
+var DEFAULT_MAX_AGE_SEC    = C.TIME.hours(1) / C.TIME.seconds(1);    // 1h non-hashed
+var IMMUTABLE_MAX_AGE_SEC  = C.TIME.days(365) / C.TIME.seconds(1);   // 1y hashed
+var DEFAULT_BANDWIDTH_WINDOW_MS = C.TIME.minutes(1);
+var DEFAULT_MAX_IDLE_MS    = C.TIME.minutes(2);
+// SHA3-512 produces 64 bytes / 128 hex chars. ETag uses the first 32 hex
+// chars (128 bits) — overkill for collision resistance but cheap; the same
+// hash powers content addressing across the framework.
+var ETAG_HEX_PREFIX = C.BYTES.bytes(32);
 
-// Minimal MIME table. Operators with exotic types pass opts.contentTypes
-// to override. The framework deliberately doesn't bring a 200-entry
-// mime-db dependency — most servers serve a handful of types.
+// Minimal MIME table (kept from the v0.6 ship for compat).
 var DEFAULT_CONTENT_TYPES = {
   ".html":  "text/html; charset=utf-8",
   ".htm":   "text/html; charset=utf-8",
@@ -76,7 +77,7 @@ var DEFAULT_CONTENT_TYPES = {
   ".svg":   "image/svg+xml",
   ".png":   "image/png",
   ".jpg":   "image/jpeg",
-  ".jpeg":  "image/jpeg",
+  ".jpeg": "image/jpeg",
   ".gif":   "image/gif",
   ".webp":  "image/webp",
   ".avif":  "image/avif",
@@ -90,11 +91,28 @@ var DEFAULT_CONTENT_TYPES = {
   ".webmanifest": "application/manifest+json",
 };
 
-// ---- Module-level metadata cache (for both middleware ETag and the
-// standalone integrity() helper). Keyed by absolute file path; entries
-// invalidated on mtime change.
+var DEFAULTS = Object.freeze({
+  defaultMaxAge:                    DEFAULT_MAX_AGE_SEC,
+  acceptRanges:                     true,
+  // Empty array = no MIME allowlist gate.
+  allowedFileTypes:                 Object.freeze([]),
+  // Bandwidth + concurrency caps default to 0 = "no cap". Operators opt
+  // in by setting a positive integer.
+  maxBytesPerActorPerWindowMs:      0,
+  maxBytesAllActorsPerWindowMs:     0,
+  bandwidthWindowMs:                DEFAULT_BANDWIDTH_WINDOW_MS,
+  maxConcurrentDownloadsPerActor:   0,
+  maxIdleMs:                        DEFAULT_MAX_IDLE_MS,
+  // Audit / observability defaults follow the framework's posture: the
+  // serve event is the audit-worthy act, not a precursor.
+  auditSuccess:                     true,
+  auditFailures:                    true,
+});
 
-var _cache = new Map();
+// Module-level metadata cache. Entries hold:
+//   { mtimeMs, size, etag, integrity, lastModified, sha3Hex, absPath }
+// Invalidated on mtime / size change.
+var _metaCache = new Map();
 
 async function _readMeta(absPath) {
   var stat;
@@ -102,38 +120,41 @@ async function _readMeta(absPath) {
   catch (_e) { return null; }
   if (!stat.isFile()) return null;
 
-  var cached = _cache.get(absPath);
+  var cached = _metaCache.get(absPath);
   if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
     return cached;
   }
 
-  // Stream the file through SHA-384. fs.readFileSync is simpler but
-  // would balloon RSS for large assets — operators shouldn't be
-  // constrained on what they can serve.
-  var hash = nodeCrypto.createHash("sha384");
+  // Stream both hashes side-by-side: SHA-384 for SRI (W3C spec), SHA3-512
+  // for the framework ETag (PQC posture). Two transforms over the same
+  // chunk avoids re-reading the file.
+  var sri = nodeCrypto.createHash("sha384");
+  var sha3 = nodeCrypto.createHash("sha3-512");
   await new Promise(function (resolve, reject) {
     var s = fs.createReadStream(absPath);
-    s.on("data", function (chunk) { hash.update(chunk); });
-    s.on("end",  resolve);
+    s.on("data", function (chunk) { sri.update(chunk); sha3.update(chunk); });
+    s.on("end", resolve);
     s.on("error", reject);
   });
-  var digest = hash.digest("base64");
+  var sriDigest = sri.digest("base64");
+  var sha3Hex = sha3.digest("hex");
 
   var entry = {
     mtimeMs:    stat.mtimeMs,
     size:       stat.size,
-    etag:       '"' + digest.slice(0, 27) + '"',   // 162-bit ETag
-    integrity:  "sha384-" + digest,
+    etag:       '"' + sha3Hex.slice(0, ETAG_HEX_PREFIX) + '"',
+    integrity:  "sha384-" + sriDigest,
+    lastModified: new Date(stat.mtimeMs).toUTCString(),
+    sha3Hex:    sha3Hex,
     absPath:    absPath,
   };
-  _cache.set(absPath, entry);
+  _metaCache.set(absPath, entry);
   return entry;
 }
 
 function _resolveSafe(root, requestedPath) {
   if (typeof requestedPath !== "string" || requestedPath.length === 0) return null;
   if (requestedPath.indexOf("\0") !== -1) return null;
-  // path.resolve handles ".." normalization; we then check containment.
   var resolved = path.resolve(root, "." + requestedPath);
   var rootResolved = path.resolve(root);
   if (resolved !== rootResolved &&
@@ -146,48 +167,280 @@ function _contentTypeFor(filePath, table) {
   return (table && table[ext]) || DEFAULT_CONTENT_TYPES[ext] || "application/octet-stream";
 }
 
-function _writeNotModified(res, etag, cacheControl) {
-  res.writeHead(HTTP.NOT_MODIFIED, {
-    "ETag":          etag,
-    "Cache-Control": cacheControl,
-  });
-  res.end();
+// _parseRangeHeader — RFC 7233 single-range parser. Returns null when:
+//   - header absent
+//   - syntactically malformed (not `bytes=`, multi-range, suffix syntax
+//     "-N" handled, end > size, start > end)
+//   - the request can be answered as 416 the caller does (start >= size).
+//
+// Returns { start, end, length } for a valid satisfiable single range.
+// Multi-range (`bytes=0-99,200-299`) returns { multi: true } so the
+// caller can refuse with 416 — we don't ship multipart/byteranges in v1
+// (operators with that need pull bytes via b.objectStore presigned URL).
+function _parseRangeHeader(header, size) {
+  if (typeof header !== "string" || header.length === 0) return null;
+  if (header.indexOf("bytes=") !== 0) return { malformed: true };
+  var spec = header.slice(6).trim();
+  if (spec.length === 0) return { malformed: true };
+  if (spec.indexOf(",") !== -1) return { multi: true };
+  var dash = spec.indexOf("-");
+  if (dash === -1) return { malformed: true };
+  var startStr = spec.slice(0, dash);
+  var endStr = spec.slice(dash + 1);
+  var start, end;
+  if (startStr === "") {
+    // Suffix range: "bytes=-N" → last N bytes.
+    var suffix = parseInt(endStr, 10);
+    if (!isFinite(suffix) || suffix <= 0) return { malformed: true };
+    if (suffix > size) suffix = size;
+    start = size - suffix;
+    end = size - 1;
+  } else {
+    start = parseInt(startStr, 10);
+    if (!isFinite(start) || start < 0) return { malformed: true };
+    if (endStr === "") {
+      end = size - 1;
+    } else {
+      end = parseInt(endStr, 10);
+      if (!isFinite(end) || end < start) return { malformed: true };
+      if (end > size - 1) end = size - 1;
+    }
+  }
+  if (start >= size) return { unsatisfiable: true };
+  return { start: start, end: end, length: end - start + 1 };
+}
+
+function _httpDate(date) {
+  return (date instanceof Date ? date : new Date(date)).toUTCString();
+}
+
+function _validateCreateOpts(opts) {
+  validateOpts.requireObject(opts, "staticServe.create", StaticServeError);
+  validateOpts.requireNonEmptyString(opts.root, "staticServe.create: root", StaticServeError, "BAD_OPT");
+  if (!fs.existsSync(opts.root)) {
+    throw _err("BAD_OPT", "staticServe.create: root does not exist: " + opts.root);
+  }
+  if (typeof opts.mountPath === "string" && opts.mountPath.length === 0) {
+    // empty string is operator-permissible: "no mount, root is request URL"
+  } else if (opts.mountPath !== undefined && opts.mountPath !== null &&
+             typeof opts.mountPath !== "string") {
+    throw _err("BAD_OPT", "staticServe.create: mountPath must be a string");
+  }
+  if (opts.hashedPathPattern !== undefined && opts.hashedPathPattern !== null &&
+      !(opts.hashedPathPattern instanceof RegExp)) {
+    throw _err("BAD_OPT", "staticServe.create: hashedPathPattern must be a RegExp");
+  }
+  // indexFile === null is the operator's "disable" sentinel; the helper
+  // returns null/undefined unchanged so we keep that semantic.
+  validateOpts.optionalNonEmptyString(opts.indexFile,
+    "staticServe.create: indexFile", StaticServeError, "BAD_OPT");
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.defaultMaxAge,
+    "staticServe.create: defaultMaxAge", StaticServeError, "BAD_OPT");
+  if (opts.contentTypes !== undefined && opts.contentTypes !== null &&
+      (typeof opts.contentTypes !== "object" || Array.isArray(opts.contentTypes))) {
+    throw _err("BAD_OPT", "staticServe.create: contentTypes must be a plain object");
+  }
+  validateOpts.optionalObjectWithMethod(opts.permissions, "check",
+    "staticServe.create: permissions", StaticServeError, "BAD_OPT",
+    "must be a b.permissions instance (check fn)");
+  validateOpts.optionalObjectWithMethod(opts.cache, "get",
+    "staticServe.create: cache", StaticServeError, "BAD_OPT",
+    "must be a b.cache instance (used for cluster-shared bandwidth + concurrency tracking)");
+  validateOpts.optionalObjectWithMethod(opts.fileType, "detect",
+    "staticServe.create: fileType", StaticServeError, "BAD_OPT",
+    "must be a b.fileType instance (magic-byte MIME detection)");
+  validateOpts.optionalObjectWithMethod(opts.retention, "isServable",
+    "staticServe.create: retention", StaticServeError, "BAD_OPT",
+    "must expose isServable(absPath, ctx) → boolean (compliance retention check)");
+  validateOpts.optionalObjectWithMethod(opts.revokeStore, "isRevoked",
+    "staticServe.create: revokeStore", StaticServeError, "BAD_OPT",
+    "must expose isRevoked(key) and revoke(key) for force-revoke support");
+  validateOpts.optionalNonEmptyStringArray(opts.allowedFileTypes,
+    "staticServe.create: allowedFileTypes", StaticServeError, "BAD_OPT");
+  if (Array.isArray(opts.allowedFileTypes) && opts.allowedFileTypes.length > 0 &&
+      (!opts.fileType || typeof opts.fileType.detect !== "function")) {
+    throw _err("BAD_OPT",
+      "staticServe.create: allowedFileTypes is set but fileType primitive is not wired " +
+      "(pass fileType: b.fileType so the framework can sniff magic bytes before serving)");
+  }
+  validateOpts.auditShape(opts.audit, "staticServe.create", StaticServeError);
+  validateOpts.observabilityShape(opts.observability, "staticServe.create", StaticServeError);
+  validateOpts.optionalFunction(opts.onServe, "staticServe.create: onServe", StaticServeError);
+  validateOpts.optionalBoolean(opts.acceptRanges, "staticServe.create: acceptRanges", StaticServeError);
+  validateOpts.optionalBoolean(opts.auditSuccess, "staticServe.create: auditSuccess", StaticServeError);
+  validateOpts.optionalBoolean(opts.auditFailures, "staticServe.create: auditFailures", StaticServeError);
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxBytesPerActorPerWindowMs,
+    "staticServe.create: maxBytesPerActorPerWindowMs", StaticServeError, "BAD_OPT");
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxBytesAllActorsPerWindowMs,
+    "staticServe.create: maxBytesAllActorsPerWindowMs", StaticServeError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.bandwidthWindowMs,
+    "staticServe.create: bandwidthWindowMs", StaticServeError, "BAD_OPT");
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxConcurrentDownloadsPerActor,
+    "staticServe.create: maxConcurrentDownloadsPerActor", StaticServeError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxIdleMs,
+    "staticServe.create: maxIdleMs", StaticServeError, "BAD_OPT");
+  // Quotas require a cache for cluster-shared coordination.
+  if ((opts.maxBytesPerActorPerWindowMs > 0 ||
+       opts.maxBytesAllActorsPerWindowMs > 0 ||
+       opts.maxConcurrentDownloadsPerActor > 0) &&
+      !opts.cache) {
+    throw _err("BAD_OPT",
+      "staticServe.create: bandwidth / concurrency quotas require opts.cache " +
+      "(pass cache: b.cache.create({ backend: 'cluster' }) so multi-replica deploys honor caps globally)");
+  }
+}
+
+// _checkBandwidthQuota — token-bucket via b.cache. Returns { ok: true } or
+// { ok: false, retryAfter, scope: "actor"|"global" }.
+async function _checkBandwidthQuota(cache, actorKey, perActorCap, globalCap, windowMs, requestedBytes) {
+  if (!cache || (perActorCap === 0 && globalCap === 0)) return { ok: true };
+  var now = Date.now();
+  var windowStart = now - windowMs;
+  if (perActorCap > 0 && actorKey) {
+    var aKey = "static:bw:actor:" + actorKey;
+    var aUsed = (await cache.get(aKey)) || 0;
+    if (aUsed + requestedBytes > perActorCap) {
+      return { ok: false, retryAfter: Math.ceil(windowMs / C.TIME.seconds(1)), scope: "actor", used: aUsed, cap: perActorCap };
+    }
+  }
+  if (globalCap > 0) {
+    var gKey = "static:bw:global";
+    var gUsed = (await cache.get(gKey)) || 0;
+    if (gUsed + requestedBytes > globalCap) {
+      return { ok: false, retryAfter: Math.ceil(windowMs / C.TIME.seconds(1)), scope: "global", used: gUsed, cap: globalCap };
+    }
+  }
+  return { ok: true, windowStart: windowStart, now: now };
+}
+
+async function _consumeBandwidth(cache, actorKey, perActorCap, globalCap, windowMs, bytes) {
+  if (!cache) return;
+  if (perActorCap > 0 && actorKey) {
+    var aKey = "static:bw:actor:" + actorKey;
+    var aUsed = (await cache.get(aKey)) || 0;
+    await cache.set(aKey, aUsed + bytes, { ttlMs: windowMs });
+  }
+  if (globalCap > 0) {
+    var gKey = "static:bw:global";
+    var gUsed = (await cache.get(gKey)) || 0;
+    await cache.set(gKey, gUsed + bytes, { ttlMs: windowMs });
+  }
+}
+
+async function _checkConcurrencyCap(cache, actorKey, cap) {
+  if (!cache || cap === 0 || !actorKey) return { ok: true };
+  var key = "static:conc:" + actorKey;
+  var current = (await cache.get(key)) || 0;
+  if (current >= cap) return { ok: false, current: current, cap: cap };
+  return { ok: true, current: current };
+}
+
+async function _incConcurrency(cache, actorKey) {
+  if (!cache || !actorKey) return;
+  var key = "static:conc:" + actorKey;
+  var current = (await cache.get(key)) || 0;
+  await cache.set(key, current + 1, { ttlMs: C.TIME.minutes(10) });
+}
+
+async function _decConcurrency(cache, actorKey) {
+  if (!cache || !actorKey) return;
+  var key = "static:conc:" + actorKey;
+  var current = (await cache.get(key)) || 0;
+  var next = current > 0 ? current - 1 : 0;
+  await cache.set(key, next, { ttlMs: C.TIME.minutes(10) });
 }
 
-function _writeNotFound(res) {
-  res.writeHead(HTTP.NOT_FOUND, { "Content-Type": "text/plain; charset=utf-8", "Content-Length": 9 });
-  res.end("Not Found");
+function _actorKeyFromContext(ctx) {
+  if (!ctx) return null;
+  if (ctx.userId) return "id:" + ctx.userId;
+  if (ctx.ip)     return "ip:" + ctx.ip;
+  return null;
 }
 
-// ---- Public: integrity() ----
+// _writeError — uniform error response with audit + observability emission.
+function _writeError(res, status, code, message, headers) {
+  var hdrs = Object.assign({ "Content-Type": "text/plain; charset=utf-8" }, headers || {});
+  hdrs["Content-Length"] = Buffer.byteLength(message, "utf8");
+  try {
+    res.writeHead(status, hdrs);
+    res.end(message);
+  } catch (_e) {
+    // response already torn down — best effort
+  }
+  void code;
+}
 
+// integrity() — module-level helper, kept for compat with the v0.6 SRI use.
 async function integrity(absPath) {
   if (typeof absPath !== "string" || absPath.length === 0) {
-    throw new Error("staticServe.integrity: absPath must be a non-empty string");
+    throw _err("BAD_OPT", "staticServe.integrity: absPath must be a non-empty string");
   }
   var meta = await _readMeta(path.resolve(absPath));
-  if (!meta) throw new Error("staticServe.integrity: file not found: " + absPath);
+  if (!meta) throw _err("NOT_FOUND", "staticServe.integrity: file not found: " + absPath);
   return meta.integrity;
 }
 
-// ---- Public: create() ----
-
 function create(opts) {
   opts = opts || {};
+  // The v0.6.x test surface called `validateOpts(opts, [...allowed], label)`
+  // for the unknown-key check. Preserve that gate in addition to the
+  // throw-at-config-time validation so tests catch typos.
   validateOpts(opts, [
     "root", "mountPath", "hashedPathPattern",
     "indexFile", "defaultMaxAge", "contentTypes",
-  ], "b.staticServe");
-  if (!opts.root) throw new Error("staticServe.create({ root }) is required");
-  if (!fs.existsSync(opts.root)) {
-    throw new Error("staticServe.create: root does not exist: " + opts.root);
-  }
+    "permissions", "cache", "fileType", "retention", "revokeStore",
+    "allowedFileTypes", "audit", "observability", "onServe",
+    "acceptRanges", "auditSuccess", "auditFailures",
+    "maxBytesPerActorPerWindowMs", "maxBytesAllActorsPerWindowMs",
+    "bandwidthWindowMs", "maxConcurrentDownloadsPerActor", "maxIdleMs",
+  ], "staticServe.create");
+  _validateCreateOpts(opts);
+  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
   var root            = path.resolve(opts.root);
-  var mountPath       = opts.mountPath || "";    // strip from req URL before lookup
+  var mountPath       = opts.mountPath || "";
   var hashedPattern   = opts.hashedPathPattern || DEFAULT_HASHED_PATTERN;
   var indexFile       = opts.indexFile === null ? null : (opts.indexFile || DEFAULT_INDEX_FILE);
-  var defaultMaxAge   = typeof opts.defaultMaxAge === "number" ? opts.defaultMaxAge : DEFAULT_MAX_AGE_SEC;
+  var defaultMaxAge   = cfg.defaultMaxAge;
   var contentTypes    = opts.contentTypes || null;
+  var permissions     = opts.permissions || null;
+  var cache           = opts.cache || null;
+  var fileType        = opts.fileType || null;
+  var retention       = opts.retention || null;
+  var revokeStore     = opts.revokeStore || null;
+  var allowedFileTypes = Array.isArray(opts.allowedFileTypes) ? opts.allowedFileTypes.slice() : [];
+  var onServe         = opts.onServe || null;
+  var audit           = opts.audit || null;
+  var auditSuccess    = cfg.auditSuccess;
+  var auditFailures   = cfg.auditFailures;
+  var acceptRanges    = cfg.acceptRanges;
+  var perActorCap     = cfg.maxBytesPerActorPerWindowMs;
+  var globalCap       = cfg.maxBytesAllActorsPerWindowMs;
+  var bandwidthWindowMs = cfg.bandwidthWindowMs;
+  var concurrencyCap  = cfg.maxConcurrentDownloadsPerActor;
+  var maxIdleMs       = cfg.maxIdleMs;
+
+  var emitAudit = validateOpts.makeAuditEmitter(audit);
+
+  // In-memory revoke set (operator can wire revokeStore for cluster-shared
+  // revocation; this Map is only used when no store is wired and gives
+  // single-process operators a working force-revoke without requiring cache).
+  var localRevoked = new Set();
+
+  function _emitObs(name, value, labels) {
+    observability().safeEvent(name, value, labels || {});
+  }
+
+  // Per-instance counters for serve.stats(). Cluster-shared counters live in
+  // observability; these are local snapshots for a single process.
+  var stats = {
+    requestsServed:    0,
+    bytesServed:       0,
+    etagHits:          0,
+    rangeRequests:     0,
+    permissionDenied:  0,
+    quotaRejected:     0,
+    failures:          0,
+  };
 
   function _cacheControlFor(urlPath) {
     if (hashedPattern.test(urlPath)) {
@@ -196,15 +449,51 @@ function create(opts) {
     return "public, max-age=" + defaultMaxAge;
   }
 
-  return async function staticServe(req, res, next) {
+  async function _isRevoked(key) {
+    if (revokeStore) {
+      try { return !!(await revokeStore.isRevoked(key)); }
+      catch (_e) { return false; }
+    }
+    return localRevoked.has(key);
+  }
+
+  async function _checkRetention(absPath, ctx) {
+    if (!retention) return true;
+    try { return !!(await retention.isServable(absPath, ctx)); }
+    catch (_e) { return false; }
+  }
+
+  async function _checkPermission(req) {
+    if (!permissions) return { ok: true };
+    try {
+      var ok = await permissions.check(req, "static.serve");
+      return { ok: !!ok };
+    } catch (_e) {
+      return { ok: false, error: _e };
+    }
+  }
+
+  async function _checkMimeAllowlist(absPath, meta) {
+    if (allowedFileTypes.length === 0 || !fileType) return { ok: true };
+    var sample;
+    try { sample = await fsp.readFile(absPath, { flag: "r" }); }
+    catch (_e) { return { ok: false, reason: "read-failed" }; }
+    var detected = fileType.detect(sample.slice(0, C.BYTES.kib(64))) || {};
+    if (!detected.mime) return { ok: false, reason: "indeterminate" };
+    if (allowedFileTypes.indexOf(detected.mime) === -1) {
+      return { ok: false, reason: "not-allowed", detected: detected.mime };
+    }
+    void meta;
+    return { ok: true, detected: detected.mime };
+  }
+
+  async function middleware(req, res, next) {
     if (req.method !== "GET" && req.method !== "HEAD") return next();
 
-    // Strip query string + mount path before resolving against root.
     var urlPath = (req.url || "").split("?")[0];
     if (mountPath && urlPath.indexOf(mountPath) === 0) {
       urlPath = urlPath.slice(mountPath.length) || "/";
     }
-    // Decode percent-encoded path. Reject decoding failures (malformed URI).
     var decoded;
     try { decoded = decodeURIComponent(urlPath); }
     catch (_e) { return next(); }
@@ -212,7 +501,24 @@ function create(opts) {
     var absPath = _resolveSafe(root, decoded);
     if (!absPath) return next();
 
-    // Directory → index file (if configured)
+    var actorCtx = requestHelpers.extractActorContext(req);
+    var actorKey = _actorKeyFromContext(actorCtx);
+
+    // Permission gate (403)
+    var perm = await _checkPermission(req);
+    if (!perm.ok) {
+      stats.permissionDenied += 1;
+      _emitObs("staticServe.permission_denied", 1, { route: urlPath });
+      if (auditFailures) {
+        emitAudit("staticServe.serve.failure", Object.assign({
+          outcome: "failure", reason: "permission_denied", resource: urlPath,
+        }, actorCtx));
+      }
+      return _writeError(res, HTTP.FORBIDDEN, "permission_denied",
+        "Forbidden");
+    }
+
+    // Stat first to discover directory → index file.
     var stat;
     try { stat = await fsp.stat(absPath); }
     catch (_e) { return next(); }
@@ -221,52 +527,331 @@ function create(opts) {
       absPath = path.join(absPath, indexFile);
     }
 
+    // Force-revoke (404 — opaque to clients)
+    if (await _isRevoked(absPath)) {
+      stats.failures += 1;
+      _emitObs("staticServe.revoked", 1, { route: urlPath });
+      if (auditFailures) {
+        emitAudit("staticServe.serve.failure", Object.assign({
+          outcome: "failure", reason: "revoked", resource: urlPath,
+        }, actorCtx));
+      }
+      return _writeError(res, HTTP.NOT_FOUND, "not_found", "Not Found");
+    }
+
+    // Compliance retention (451)
+    if (!(await _checkRetention(absPath, actorCtx))) {
+      stats.failures += 1;
+      _emitObs("staticServe.retention_blocked", 1, { route: urlPath });
+      if (auditFailures) {
+        emitAudit("staticServe.serve.failure", Object.assign({
+          outcome: "failure", reason: "retention_blocked", resource: urlPath,
+        }, actorCtx));
+      }
+      return _writeError(res, HTTP.UNAVAILABLE_FOR_LEGAL_REASONS,
+        "retention_blocked", "Unavailable For Legal Reasons");
+    }
+
     var meta = await _readMeta(absPath);
     if (!meta) return next();
 
+    // MIME allowlist (415) — checked before sending bytes so a misnamed
+    // .txt holding a binary payload is refused at serve time.
+    if (allowedFileTypes.length > 0) {
+      var mimeCheck = await _checkMimeAllowlist(absPath, meta);
+      if (!mimeCheck.ok) {
+        stats.failures += 1;
+        _emitObs("staticServe.mime_rejected", 1, { route: urlPath, reason: mimeCheck.reason });
+        if (auditFailures) {
+          emitAudit("staticServe.serve.failure", Object.assign({
+            outcome: "failure", reason: "mime_rejected", resource: urlPath,
+            detectedMime: mimeCheck.detected || null,
+          }, actorCtx));
+        }
+        return _writeError(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
+          "mime_rejected", "Unsupported Media Type");
+      }
+    }
+
     var cacheControl = _cacheControlFor(urlPath);
 
-    // 304 short-circuit
-    var ifNone = req.headers && req.headers["if-none-match"];
+    var headersIn = req.headers || {};
+
+    // Conditional: If-None-Match (304)
+    var ifNone = headersIn["if-none-match"];
     if (ifNone && ifNone === meta.etag) {
-      return _writeNotModified(res, meta.etag, cacheControl);
+      stats.etagHits += 1;
+      _emitObs("staticServe.etag_hits", 1, { route: urlPath });
+      res.writeHead(HTTP.NOT_MODIFIED, {
+        "ETag":          meta.etag,
+        "Cache-Control": cacheControl,
+        "Last-Modified": meta.lastModified,
+      });
+      return res.end();
+    }
+
+    // Conditional: If-Match (412 if no match — strong validator only)
+    var ifMatch = headersIn["if-match"];
+    if (ifMatch && ifMatch !== "*" && ifMatch !== meta.etag) {
+      stats.failures += 1;
+      _emitObs("staticServe.precondition_failed", 1, { route: urlPath, header: "if-match" });
+      return _writeError(res, HTTP.PRECONDITION_FAILED || 412,
+        "precondition_failed", "Precondition Failed");
     }
 
+    // Conditional: If-Modified-Since (304)
+    var ifModSince = headersIn["if-modified-since"];
+    if (ifModSince) {
+      var ims = Date.parse(ifModSince);
+      if (isFinite(ims) && Math.floor(meta.mtimeMs / C.TIME.seconds(1)) <= Math.floor(ims / C.TIME.seconds(1))) {
+        stats.etagHits += 1;
+        _emitObs("staticServe.if_modified_since_hits", 1, { route: urlPath });
+        res.writeHead(HTTP.NOT_MODIFIED, {
+          "ETag":          meta.etag,
+          "Cache-Control": cacheControl,
+          "Last-Modified": meta.lastModified,
+        });
+        return res.end();
+      }
+    }
+
+    // Conditional: If-Unmodified-Since (412)
+    var ifUnmodSince = headersIn["if-unmodified-since"];
+    if (ifUnmodSince) {
+      var ius = Date.parse(ifUnmodSince);
+      if (isFinite(ius) && Math.floor(meta.mtimeMs / C.TIME.seconds(1)) > Math.floor(ius / C.TIME.seconds(1))) {
+        stats.failures += 1;
+        _emitObs("staticServe.precondition_failed", 1, { route: urlPath, header: "if-unmodified-since" });
+        return _writeError(res, HTTP.PRECONDITION_FAILED,
+          "precondition_failed", "Precondition Failed");
+      }
+    }
+
+    // Range parsing
+    var range = null;
+    if (acceptRanges) {
+      var raw = headersIn["range"];
+      if (raw) {
+        range = _parseRangeHeader(raw, meta.size);
+        if (range && (range.malformed || range.multi)) {
+          stats.failures += 1;
+          _emitObs("staticServe.range_invalid", 1, { route: urlPath });
+          return _writeError(res, HTTP.RANGE_NOT_SATISFIABLE, "range_not_satisfiable",
+            "Range Not Satisfiable", { "Content-Range": "bytes */" + meta.size });
+        }
+        if (range && range.unsatisfiable) {
+          stats.failures += 1;
+          _emitObs("staticServe.range_invalid", 1, { route: urlPath });
+          return _writeError(res, HTTP.RANGE_NOT_SATISFIABLE, "range_not_satisfiable",
+            "Range Not Satisfiable", { "Content-Range": "bytes */" + meta.size });
+        }
+        if (range) {
+          stats.rangeRequests += 1;
+          _emitObs("staticServe.range_requests", 1, { route: urlPath });
+        }
+      }
+    }
+
+    var sendBytes = range ? range.length : meta.size;
+
+    // Concurrency gate (429)
+    var concCheck = await _checkConcurrencyCap(cache, actorKey, concurrencyCap);
+    if (!concCheck.ok) {
+      stats.quotaRejected += 1;
+      _emitObs("staticServe.concurrency_rejected", 1, { route: urlPath });
+      if (auditFailures) {
+        emitAudit("staticServe.serve.failure", Object.assign({
+          outcome: "failure", reason: "concurrency_cap", resource: urlPath,
+          current: concCheck.current, cap: concCheck.cap,
+        }, actorCtx));
+      }
+      return _writeError(res, HTTP.TOO_MANY_REQUESTS,
+        "concurrency_cap", "Too Many Requests",
+        { "Retry-After": "5" });
+    }
+
+    // Bandwidth gate (429)
+    var bwCheck = await _checkBandwidthQuota(cache, actorKey, perActorCap, globalCap, bandwidthWindowMs, sendBytes);
+    if (!bwCheck.ok) {
+      stats.quotaRejected += 1;
+      _emitObs("staticServe.bandwidth_rejected", 1, { route: urlPath, scope: bwCheck.scope });
+      if (auditFailures) {
+        emitAudit("staticServe.serve.failure", Object.assign({
+          outcome: "failure", reason: "bandwidth_quota", resource: urlPath,
+          scope: bwCheck.scope, used: bwCheck.used, cap: bwCheck.cap,
+        }, actorCtx));
+      }
+      return _writeError(res, HTTP.TOO_MANY_REQUESTS,
+        "bandwidth_quota", "Too Many Requests",
+        { "Retry-After": String(bwCheck.retryAfter) });
+    }
+
+    var status = range ? 206 : HTTP.OK;
     var headers = {
       "Content-Type":   _contentTypeFor(absPath, contentTypes),
-      "Content-Length": meta.size,
+      "Content-Length": sendBytes,
       "ETag":           meta.etag,
       "Cache-Control":  cacheControl,
-      // SRI hint for templates that want to <script integrity=…>; not
-      // required by clients but consumers can read it from response
-      // headers when they want to embed integrity in subsequent pages.
+      "Last-Modified":  meta.lastModified,
       "X-Integrity":    meta.integrity,
     };
+    if (acceptRanges) headers["Accept-Ranges"] = "bytes";
+    if (range) headers["Content-Range"] = "bytes " + range.start + "-" + range.end + "/" + meta.size;
+
+    // onServe hook — operator can mutate headers / set extra fields.
+    if (onServe) {
+      try {
+        await onServe({
+          req: req, res: res, absPath: absPath, urlPath: urlPath,
+          size: meta.size, sendBytes: sendBytes, range: range,
+          headers: headers, actor: actorCtx,
+        });
+      } catch (e) {
+        stats.failures += 1;
+        _emitObs("staticServe.onServe_threw", 1, { route: urlPath });
+        if (auditFailures) {
+          emitAudit("staticServe.serve.failure", Object.assign({
+            outcome: "failure", reason: "onServe_threw", resource: urlPath,
+            error: e && e.message,
+          }, actorCtx));
+        }
+        return _writeError(res, HTTP.INTERNAL_SERVER_ERROR, "onServe_threw",
+          "Internal Server Error");
+      }
+    }
 
     if (req.method === "HEAD") {
-      res.writeHead(HTTP.OK, headers);
-      return res.end();
+      res.writeHead(status, headers);
+      res.end();
+      stats.requestsServed += 1;
+      _emitObs("staticServe.requests_served", 1, { route: urlPath, method: "HEAD" });
+      if (auditSuccess) {
+        emitAudit("staticServe.serve.success", Object.assign({
+          outcome: "success", resource: urlPath, method: "HEAD",
+          size: meta.size, contentType: headers["Content-Type"],
+        }, actorCtx));
+      }
+      return;
     }
 
-    res.writeHead(HTTP.OK, headers);
-    var stream = fs.createReadStream(absPath);
-    stream.on("error", function (e) {
-      // Mid-stream read error — best we can do is destroy the response;
-      // headers are already on the wire.
-      try { res.destroy(e); } catch (_) { /* response already torn down */ }
+    res.writeHead(status, headers);
+
+    // Acquire concurrency slot (released on stream end / error / abort).
+    await _incConcurrency(cache, actorKey);
+    var slotReleased = false;
+    function releaseSlot() {
+      if (slotReleased) return;
+      slotReleased = true;
+      _decConcurrency(cache, actorKey).catch(function () {});
+    }
+
+    var streamOpts = range ? { start: range.start, end: range.end } : {};
+    var fileStream = fs.createReadStream(absPath, streamOpts);
+
+    // Idle timeout — close the connection if the client stalls. Pattern is
+    // a deadline-style debounce (clearTimeout + setTimeout) tied directly
+    // to the file-stream "data" event lifecycle; the safeAsync.debounce
+    // helper isn't yet ship-implemented, and pulling it through here would
+    // pre-allocate a closure for every served byte. Tracked for extraction.
+    var idleTimer = null;
+    function resetIdleTimer() {
+      if (idleTimer) clearTimeout(idleTimer); // allow:handrolled-debounce — file-stream idle deadline
+      idleTimer = setTimeout(function () {
+        try { fileStream.destroy(_err("IDLE_TIMEOUT", "client idle for " + maxIdleMs + "ms")); }
+        catch (_) { /* stream already torn down */ }
+        try { res.destroy(); } catch (_) { /* response already torn down */ }
+      }, maxIdleMs);
+    }
+    resetIdleTimer();
+
+    // Cancellation propagation: when the client disconnects mid-stream.
+    function onClientClose() {
+      try { fileStream.destroy(); } catch (_) { /* allow:silent-catch — stream already torn down */ }
+      releaseSlot();
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+    }
+    req.on("aborted", onClientClose);
+    res.on("close", onClientClose);
+
+    var bytesSent = 0;
+    fileStream.on("data", function (chunk) {
+      bytesSent += chunk.length;
+      resetIdleTimer();
+    });
+
+    fileStream.on("error", function (e) {
+      stats.failures += 1;
+      _emitObs("staticServe.stream_error", 1, { route: urlPath });
+      if (auditFailures) {
+        emitAudit("staticServe.serve.failure", Object.assign({
+          outcome: "failure", reason: "stream_error", resource: urlPath,
+          error: e && e.message,
+        }, actorCtx));
+      }
+      try { res.destroy(e); } catch (_) { /* allow:silent-catch — response already torn down */ }
+      releaseSlot();
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
     });
-    stream.pipe(res);
+
+    fileStream.on("end", function () {
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      stats.requestsServed += 1;
+      stats.bytesServed += bytesSent;
+      _emitObs("staticServe.requests_served", 1, { route: urlPath, method: "GET" });
+      _emitObs("staticServe.bytes_served", bytesSent, { route: urlPath });
+      _consumeBandwidth(cache, actorKey, perActorCap, globalCap, bandwidthWindowMs, bytesSent)
+        .catch(function () {});
+      if (auditSuccess) {
+        emitAudit("staticServe.serve.success", Object.assign({
+          outcome: "success", resource: urlPath, method: "GET",
+          size: bytesSent, contentType: headers["Content-Type"],
+          range: range ? { start: range.start, end: range.end } : null,
+        }, actorCtx));
+      }
+      releaseSlot();
+    });
+
+    fileStream.pipe(res);
+  }
+
+  // Operator-facing handle: callable as middleware (back-compat) AND
+  // exposes serve-instance methods.
+  async function fn(req, res, next) { return middleware(req, res, next); }
+  fn.middleware = middleware;
+  fn.revoke = async function (key) {
+    if (revokeStore && typeof revokeStore.revoke === "function") {
+      await revokeStore.revoke(key);
+      return { ok: true, key: key };
+    }
+    localRevoked.add(key);
+    return { ok: true, key: key };
+  };
+  fn.unrevoke = async function (key) {
+    if (revokeStore && typeof revokeStore.unrevoke === "function") {
+      await revokeStore.unrevoke(key);
+      return { ok: true, key: key };
+    }
+    localRevoked.delete(key);
+    return { ok: true, key: key };
+  };
+  fn.stats = function () {
+    return Object.assign({}, stats);
+  };
+  fn.invalidateMeta = function (key) {
+    _metaCache.delete(key);
+    return { ok: true, key: key };
   };
+  return fn;
 }
 
-// ---- Test helper ----
-function _resetCacheForTest() { _cache.clear(); }
+function _resetCacheForTest() { _metaCache.clear(); }
 
 module.exports = {
-  create:                create,
-  integrity:             integrity,
-  DEFAULT_MAX_AGE_SEC:   DEFAULT_MAX_AGE_SEC,
-  IMMUTABLE_MAX_AGE_SEC: IMMUTABLE_MAX_AGE_SEC,
+  create:                 create,
+  integrity:              integrity,
+  DEFAULT_MAX_AGE_SEC:    DEFAULT_MAX_AGE_SEC,
+  IMMUTABLE_MAX_AGE_SEC:  IMMUTABLE_MAX_AGE_SEC,
   DEFAULT_HASHED_PATTERN: DEFAULT_HASHED_PATTERN,
-  _resetCacheForTest:    _resetCacheForTest,
+  _resetCacheForTest:     _resetCacheForTest,
+  _parseRangeHeader:      _parseRangeHeader,
 };