@blamejs/core 0.7.4 → 0.7.18

package/lib/static.js

@@ -36,6 +36,7 @@ var fsp = require("node:fs/promises");
 var nodeCrypto = require("node:crypto");
 var path = require("node:path");
 var C = require("./constants");
+var gateContract = require("./gate-contract");
 var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var requestHelpers = require("./request-helpers");
@@ -47,6 +48,11 @@ var { StaticServeError } = require("./framework-error");
 // observability is ready.
 var observability = lazyRequire(function () { return require("./observability"); });
 
+// guard-* family is wired on by default; lazy-loaded to avoid eager
+// import cycles. Operators opt out via contentSafety: null (audited).
+var guardAll = lazyRequire(function () { return require("./guard-all"); });
+var guardFilename = lazyRequire(function () { return require("./guard-filename"); });
+
 var _err = StaticServeError.factory;
 
 var HTTP = requestHelpers.HTTP_STATUS;
@@ -159,6 +165,39 @@ function _resolveSafe(root, requestedPath) {
   var rootResolved = path.resolve(root);
   if (resolved !== rootResolved &&
       !resolved.startsWith(rootResolved + path.sep)) return null;
+
+  // Symlink-escape defense — the lexical resolve above only sees the
+  // requested path tokens; a symlink anywhere along `resolved` can
+  // still point outside `rootResolved` on disk. realpath every node
+  // (only when it exists; missing files are routed through the
+  // standard 404 path by the caller).
+  try {
+    var real = fs.realpathSync(resolved);
+    var rootReal = fs.realpathSync(rootResolved);
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) return null;
+    resolved = real;
+  } catch (_e) {
+    // Path doesn't exist (or is denied) — fall through with the lexical
+    // resolution so the caller's stat() returns the natural ENOENT and
+    // 404s. realpath failures from non-existence are NOT a smuggling
+    // signal.
+  }
+
+  // Filename safety — the basename gates against path-traversal /
+  // null-byte / NTFS ADS / UNC / RTLO bidi / overlong UTF-8 / Windows
+  // reserved device names. Uses balanced profile + explicit
+  // shellExecExtPolicy: "allow" because static-serve serves operator-
+  // deposited disk content: shell-exec extensions (.exe / .bin / .so /
+  // legitimate `<name>.<hash>.js` bundler output) are valid here. The
+  // other balanced checks still reject the traversal + smuggling
+  // surface the user surfaced.
+  var fname = path.basename(resolved);
+  var rv = guardFilename().validate(fname, {
+    profile:             "balanced",
+    shellExecExtPolicy:  "allow",
+  });
+  if (!rv.ok) return null;
+
   return resolved;
 }
 
@@ -236,10 +275,8 @@ function _validateCreateOpts(opts) {
     "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.optionalPlainObject(opts.contentTypes,
+    "staticServe.create: contentTypes", StaticServeError, "BAD_OPT");
   validateOpts.optionalObjectWithMethod(opts.permissions, "check",
     "staticServe.create: permissions", StaticServeError, "BAD_OPT",
     "must be a b.permissions instance (check fn)");
@@ -266,6 +303,29 @@ function _validateCreateOpts(opts) {
   validateOpts.auditShape(opts.audit, "staticServe.create", StaticServeError);
   validateOpts.observabilityShape(opts.observability, "staticServe.create", StaticServeError);
   validateOpts.optionalFunction(opts.onServe, "staticServe.create: onServe", StaticServeError);
+  // contentSafety — extension-keyed gate map. Default behaviour: when
+  // undefined, the framework wires b.guardAll.byExtension({ profile:
+  // "strict" }) automatically so every shipped guard is ON by default.
+  // Explicit opt-out: contentSafety: null (audited at create() time so
+  // a security review can reconstruct which deploys disabled the
+  // default-on protection).
+  // Example: contentSafety: { ".csv": b.guardCsv.gate({ profile: "strict" }) }
+  if (opts.contentSafety !== undefined && opts.contentSafety !== null) {
+    validateOpts.optionalPlainObject(opts.contentSafety,
+      "staticServe.create: contentSafety", StaticServeError, "BAD_OPT",
+      "must be a plain { ext: gate } object, null to opt out, or " +
+      "undefined for the default-on b.guardAll wiring");
+    var safetyKeys = Object.keys(opts.contentSafety);
+    for (var sk = 0; sk < safetyKeys.length; sk++) {
+      var ext = safetyKeys[sk];
+      var g = opts.contentSafety[ext];
+      if (!g || typeof g.check !== "function") {
+        throw _err("BAD_OPT",
+          "staticServe.create: contentSafety[" + JSON.stringify(ext) +
+          "] must be a gate (b.guardCsv.gate / b.guardHtml.gate / etc.)");
+      }
+    }
+  }
   validateOpts.optionalBoolean(opts.acceptRanges, "staticServe.create: acceptRanges", StaticServeError);
   validateOpts.optionalBoolean(opts.auditSuccess, "staticServe.create: auditSuccess", StaticServeError);
   validateOpts.optionalBoolean(opts.auditFailures, "staticServe.create: auditFailures", StaticServeError);
@@ -393,6 +453,7 @@ function create(opts) {
     "acceptRanges", "auditSuccess", "auditFailures",
     "maxBytesPerActorPerWindowMs", "maxBytesAllActorsPerWindowMs",
     "bandwidthWindowMs", "maxConcurrentDownloadsPerActor", "maxIdleMs",
+    "contentSafety", "contentSafetyDisabledReason",
   ], "staticServe.create");
   _validateCreateOpts(opts);
   var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
@@ -408,6 +469,37 @@ function create(opts) {
   var retention       = opts.retention || null;
   var revokeStore     = opts.revokeStore || null;
   var allowedFileTypes = Array.isArray(opts.allowedFileTypes) ? opts.allowedFileTypes.slice() : [];
+  // contentSafety: undefined → wire b.guardAll.byExtension({ profile: "strict" })
+  // contentSafety: null      → explicit opt-out, audit row emitted
+  // contentSafety: { ... }   → use operator-supplied map
+  var contentSafety;
+  if (opts.contentSafety === undefined) {
+    // Strict profile is the security-correct default. Operators who
+    // serve a broader content vocabulary opt up explicitly via
+    // contentSafety: b.guardAll.byExtension({ profile: "balanced" |
+    // "permissive" }).
+    contentSafety = guardAll().byExtension({
+      profile:       "strict",
+      audit:         opts.audit,
+      observability: opts.observability,
+    });
+  } else if (opts.contentSafety === null) {
+    if (opts.audit && typeof opts.audit.safeEmit === "function") {
+      try {
+        opts.audit.safeEmit({
+          action:   "staticServe.contentSafety.disabled",
+          actor:    {},
+          outcome:  "success",
+          metadata: {
+            reason: opts.contentSafetyDisabledReason || "operator-explicit-opt-out",
+          },
+        });
+      } catch (_e) { /* audit best-effort */ }
+    }
+    contentSafety = null;
+  } else {
+    contentSafety = opts.contentSafety;
+  }
   var onServe         = opts.onServe || null;
   var audit           = opts.audit || null;
   var auditSuccess    = cfg.auditSuccess;
@@ -573,6 +665,68 @@ function create(opts) {
       }
     }
 
+    // Content-safety gate — operator-supplied per-extension gate
+    // (b.guardCsv.gate / b.guardHtml.gate / etc.). Reads the file once
+    // up to maxRuntimeMs and routes the bytes through the gate's
+    // check() before serving. The gate's decision is honored:
+    //   - serve     → continue with the original bytes
+    //   - sanitize  → continue with decision.sanitized
+    //   - refuse    → 415 / opaque to clients
+    //   - audit-only / warn → continue (gate emits to audit)
+    var gateBytesOverride = null;
+    if (contentSafety) {
+      var ext = path.extname(absPath).toLowerCase();
+      var safetyGate = contentSafety[ext];
+      if (safetyGate && typeof safetyGate.check === "function") {
+        var gateBuf;
+        try { gateBuf = await fsp.readFile(absPath); }
+        catch (_e) {
+          stats.failures += 1;
+          return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
+            "read_failed", "Internal Server Error");
+        }
+        var gateDecision;
+        try {
+          gateDecision = await safetyGate.check({
+            bytes:       gateBuf,
+            contentType: _contentTypeFor(absPath, contentTypes),
+            filename:    path.basename(absPath),
+            actor:       actorCtx,
+            route:       urlPath,
+            direction:   "outbound",
+            req:         req,
+          });
+        } catch (gateErr) {
+          stats.failures += 1;
+          _emitObs("staticServe.content_safety_threw", 1, { route: urlPath });
+          if (auditFailures) {
+            emitAudit("staticServe.serve.failure", Object.assign({
+              outcome: "failure", reason: "content_safety_threw", resource: urlPath,
+              error: gateErr && gateErr.message,
+            }, actorCtx));
+          }
+          return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
+            "content_safety_threw", "Internal Server Error");
+        }
+        if (!gateDecision.ok || gateDecision.action === "refuse") {
+          stats.failures += 1;
+          _emitObs("staticServe.content_safety_refused", 1, { route: urlPath });
+          if (auditFailures) {
+            emitAudit("staticServe.serve.failure", Object.assign({
+              outcome: "failure", reason: "content_safety_refused",
+              resource: urlPath, ext: ext,
+              issues: gateContract.summarizeIssues(gateDecision.issues),
+            }, actorCtx));
+          }
+          return _writeError(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
+            "content_safety_refused", "Unsupported Media Type");
+        }
+        if (gateDecision.action === "sanitize" && gateDecision.sanitized) {
+          gateBytesOverride = gateDecision.sanitized;
+        }
+      }
+    }
+
     var cacheControl = _cacheControlFor(urlPath);
 
     var headersIn = req.headers || {};
@@ -734,6 +888,32 @@ function create(opts) {
       return;
     }
 
+    // Sanitized override path — content-safety gate replaced the
+    // bytes; emit them directly without re-reading the file. Bypasses
+    // range / idle-timer machinery (the override is already in memory
+    // and Range over a sanitized variant doesn't have a useful
+    // contract — sanitization changes byte offsets).
+    if (gateBytesOverride) {
+      var overrideHeaders = Object.assign({}, headers, {
+        "Content-Length": gateBytesOverride.length,
+      });
+      delete overrideHeaders["Content-Range"];
+      res.writeHead(HTTP.OK, overrideHeaders);
+      res.end(gateBytesOverride);
+      stats.requestsServed += 1;
+      stats.bytesServed += gateBytesOverride.length;
+      _emitObs("staticServe.requests_served", 1, { route: urlPath, method: "GET", sanitized: true });
+      _emitObs("staticServe.bytes_served", gateBytesOverride.length, { route: urlPath, sanitized: true });
+      if (auditSuccess) {
+        emitAudit("staticServe.serve.success", Object.assign({
+          outcome: "success", resource: urlPath, method: "GET",
+          size: gateBytesOverride.length, contentType: overrideHeaders["Content-Type"],
+          sanitized: true,
+        }, actorCtx));
+      }
+      return;
+    }
+
     res.writeHead(status, headers);
 
     // Acquire concurrency slot (released on stream end / error / abort).