@blamejs/core 0.7.4 → 0.7.19

package/lib/guard-all.js

@@ -0,0 +1,405 @@
+"use strict";
+/**
+ * guard-all — registry + aggregator for the guard-* content-safety
+ * family.
+ *
+ * The framework thesis applied to content safety: every shipped guard
+ * is ON by default; operators opt OUT explicitly with an audited reason
+ * per guard. New guards added in future slices auto-register and
+ * operators get the new coverage without re-wiring.
+ *
+ *   var b = require("@blamejs/core");
+ *
+ *   // Every shipped guard, every threat, strict profile, one line.
+ *   var safety = b.guardAll.gate({ profile: "strict", audit: b.audit });
+ *
+ *   // Opt-out is explicit, named, and audited.
+ *   var safety = b.guardAll.gate({
+ *     profile: "strict",
+ *     exceptFor: {
+ *       html: { reason: "every HTML response is server-rendered + CSP-locked" },
+ *       pdf:  { reason: "no PDF uploads in this app" },
+ *     },
+ *     override: {
+ *       csv: { profile: "email-attachment" },
+ *     },
+ *     audit:         b.audit,
+ *     observability: b.observability,
+ *   });
+ *
+ *   // Drop straight into the existing composition points.
+ *   b.staticServe.create({
+ *     contentSafety: b.guardAll.byExtension({ profile: "strict" }),
+ *   });
+ *   b.fileUpload.create({
+ *     contentSafety: b.guardAll.gate({ profile: "strict" }),
+ *   });
+ *
+ * Registry contract — every primitive registered into guard-all MUST
+ * export:
+ *   - NAME              — short string identifier ("csv", "html", ...)
+ *   - MIME_TYPES        — array of canonical mime types it owns
+ *   - EXTENSIONS        — array of file extensions it owns (.csv, ...)
+ *   - PROFILES          — object map; must include the SHARED_PROFILES
+ *                         vocabulary (strict / balanced / permissive)
+ *   - COMPLIANCE_POSTURES — object map; must include the SHARED_POSTURES
+ *                         vocabulary (hipaa / pci-dss / gdpr / soc2-cc7)
+ *   - gate(opts)        — returns a b.gateContract-shaped gate
+ *
+ * The parity check at module load throws GuardAllError if a registered
+ * guard is missing any of the above — this is the registry gate that
+ * keeps every future guard slice conformant.
+ *
+ * Per-guard extension profiles (e.g. csv's "email-attachment") work
+ * via direct b.guardCsv.gate({ profile: "email-attachment" }) but are
+ * NOT accepted by b.guardAll.gate({ profile: ... }) — the aggregator
+ * only takes the shared vocabulary so the same string applies cleanly
+ * across every member. Operators reach for guard-specific profiles via
+ * the override map.
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var gateContract = require("./gate-contract");
+var { GuardAllError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardAllError.factory;
+
+// Registered guards. Ordering is the order they get walked by list();
+// dispatch via gateContract.contentTypeMux is O(1) regardless.
+var GUARDS = [
+  require("./guard-csv"),
+  require("./guard-html"),
+  require("./guard-svg"),
+  require("./guard-archive"),
+  require("./guard-json"),
+  require("./guard-yaml"),
+  require("./guard-xml"),
+  require("./guard-markdown"),
+  require("./guard-email"),
+];
+
+// STANDALONE_GUARDS — guard-* primitives that don't fit content-type
+// routing. They participate in the family (NAME / KIND / INTEGRATION_
+// FIXTURES exports + shared profiles + postures) but operate on a
+// non-content axis (filename string, future identifier types). The
+// adaptive integration harness iterates `allGuards()` to pick them up.
+var STANDALONE_GUARDS = [
+  require("./guard-filename"),
+];
+
+// Framework-wide profile + posture vocabulary that every guard MUST
+// support. Adding a new shared profile / posture is a coordinated
+// cross-guard change — every member must implement it.
+var SHARED_PROFILES = Object.freeze(["strict", "balanced", "permissive"]);
+var SHARED_POSTURES = Object.freeze(["hipaa", "pci-dss", "gdpr", "soc2-cc7"]);
+
+// ---- Registry parity check (runs at module load) ----
+
+function _verifyParity() {
+  var failures = [];
+  for (var i = 0; i < GUARDS.length; i += 1) {
+    var g = GUARDS[i];
+    if (!g || typeof g !== "object") {
+      failures.push("guard at index " + i + " is not an exported module object");
+      continue;
+    }
+    if (typeof g.NAME !== "string" || g.NAME.length === 0) {
+      failures.push("guard at index " + i + ": missing NAME export");
+      continue;
+    }
+    if (!Array.isArray(g.MIME_TYPES) || g.MIME_TYPES.length === 0) {
+      failures.push(g.NAME + ": missing or empty MIME_TYPES export");
+    }
+    if (!Array.isArray(g.EXTENSIONS) || g.EXTENSIONS.length === 0) {
+      failures.push(g.NAME + ": missing or empty EXTENSIONS export");
+    }
+    if (typeof g.gate !== "function") {
+      failures.push(g.NAME + ": missing gate(opts) function");
+    }
+    SHARED_PROFILES.forEach(function (p) {
+      if (!g.PROFILES || !g.PROFILES[p]) {
+        failures.push(g.NAME + ": does not declare shared profile " + JSON.stringify(p));
+      }
+    });
+    SHARED_POSTURES.forEach(function (p) {
+      if (!g.COMPLIANCE_POSTURES || !g.COMPLIANCE_POSTURES[p]) {
+        failures.push(g.NAME + ": does not declare shared compliance posture " + JSON.stringify(p));
+      }
+    });
+  }
+  // Detect duplicate NAMEs / MIME_TYPES / EXTENSIONS — would cause silent
+  // override in the aggregated gate map; surface at boot instead.
+  var nameSeen = Object.create(null);
+  var mimeSeen = Object.create(null);
+  var extSeen  = Object.create(null);
+  for (var j = 0; j < GUARDS.length; j += 1) {
+    var gg = GUARDS[j];
+    if (gg && gg.NAME) {
+      if (nameSeen[gg.NAME]) failures.push("duplicate NAME " + JSON.stringify(gg.NAME));
+      nameSeen[gg.NAME] = true;
+    }
+    if (gg && Array.isArray(gg.MIME_TYPES)) {
+      gg.MIME_TYPES.forEach(function (m) {
+        var k = String(m).toLowerCase();
+        if (mimeSeen[k]) failures.push("duplicate MIME_TYPE " + JSON.stringify(k) +
+                                       " across multiple guards");
+        mimeSeen[k] = true;
+      });
+    }
+    if (gg && Array.isArray(gg.EXTENSIONS)) {
+      gg.EXTENSIONS.forEach(function (e) {
+        var k = String(e).toLowerCase();
+        if (extSeen[k]) failures.push("duplicate EXTENSION " + JSON.stringify(k) +
+                                      " across multiple guards");
+        extSeen[k] = true;
+      });
+    }
+  }
+  if (failures.length) {
+    throw _err("guard-all/parity-fail",
+      "guardAll registry parity check failed:\n  " + failures.join("\n  "));
+  }
+}
+_verifyParity();
+
+// ---- Internal helpers ----
+
+function _byName(name) {
+  for (var i = 0; i < GUARDS.length; i += 1) {
+    if (GUARDS[i].NAME === name) return GUARDS[i];
+  }
+  return null;
+}
+
+function _validateExceptFor(exceptFor) {
+  if (exceptFor == null) return {};
+  validateOpts.optionalPlainObject(exceptFor,
+    "guardAll: exceptFor", GuardAllError, "guard-all/bad-opt",
+    "must be a plain object keyed by guard NAME");
+  var keys = Object.keys(exceptFor);
+  for (var i = 0; i < keys.length; i += 1) {
+    var name = keys[i];
+    if (!_byName(name)) {
+      throw _err("guard-all/unknown-guard",
+        "exceptFor refers to unknown guard " + JSON.stringify(name) +
+        "; registered: " + GUARDS.map(function (g) { return g.NAME; }).join(", "));
+    }
+    var entry = exceptFor[name];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw _err("guard-all/bad-opt",
+        "exceptFor[" + JSON.stringify(name) + "] must be a plain object " +
+        "with a non-empty reason string");
+    }
+    if (typeof entry.reason !== "string" || entry.reason.trim().length === 0) {
+      throw _err("guard-all/missing-reason",
+        "exceptFor[" + JSON.stringify(name) + "] requires a non-empty " +
+        "reason string — opting a guard out is auditable");
+    }
+  }
+  return exceptFor;
+}
+
+function _validateOverride(override) {
+  if (override == null) return {};
+  validateOpts.optionalPlainObject(override,
+    "guardAll: override", GuardAllError, "guard-all/bad-opt",
+    "must be a plain object keyed by guard NAME");
+  var keys = Object.keys(override);
+  for (var i = 0; i < keys.length; i += 1) {
+    var name = keys[i];
+    if (!_byName(name)) {
+      throw _err("guard-all/unknown-guard",
+        "override refers to unknown guard " + JSON.stringify(name));
+    }
+    var entry = override[name];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw _err("guard-all/bad-opt",
+        "override[" + JSON.stringify(name) + "] must be a plain object " +
+        "of opts to merge into the guard's gate(opts)");
+    }
+  }
+  return override;
+}
+
+function _validateProfileAndPosture(opts) {
+  if (opts.profile != null) {
+    if (typeof opts.profile !== "string") {
+      throw _err("guard-all/bad-opt",
+        "profile must be a string; got " + typeof opts.profile);
+    }
+    if (SHARED_PROFILES.indexOf(opts.profile) === -1) {
+      throw _err("guard-all/bad-profile",
+        "profile " + JSON.stringify(opts.profile) +
+        " is not in the shared vocabulary; allowed: " +
+        SHARED_PROFILES.join(", ") +
+        ". Per-guard extension profiles (e.g. csv's email-attachment) " +
+        "are reachable via the override map.");
+    }
+  }
+  if (opts.compliancePosture != null) {
+    if (typeof opts.compliancePosture !== "string") {
+      throw _err("guard-all/bad-opt",
+        "compliancePosture must be a string; got " + typeof opts.compliancePosture);
+    }
+    if (SHARED_POSTURES.indexOf(opts.compliancePosture) === -1) {
+      throw _err("guard-all/bad-posture",
+        "compliancePosture " + JSON.stringify(opts.compliancePosture) +
+        " is not in the shared vocabulary; allowed: " + SHARED_POSTURES.join(", "));
+    }
+  }
+}
+
+// _resolveActiveGuards — returns the set of (guard, mergedOpts) pairs
+// that are NOT in exceptFor. Each entry's opts are the base opts +
+// override entry merged in.
+function _resolveActiveGuards(opts) {
+  var exceptFor = _validateExceptFor(opts.exceptFor);
+  var override  = _validateOverride(opts.override);
+  _validateProfileAndPosture(opts);
+
+  var baseOpts = {
+    profile:               opts.profile,
+    compliancePosture:     opts.compliancePosture,
+    mode:                  opts.mode,
+    audit:                 opts.audit,
+    observability:         opts.observability,
+    forensicEvidenceStore: opts.forensicEvidenceStore,
+    forensicSnippetBytes:  opts.forensicSnippetBytes,
+    cache:                 opts.cache,
+    cacheTtlMs:            opts.cacheTtlMs,
+    maxRuntimeMs:          opts.maxRuntimeMs,
+    beforeCheck:           opts.beforeCheck,
+    afterCheck:            opts.afterCheck,
+    onIssue:               opts.onIssue,
+    onSanitize:            opts.onSanitize,
+    onRefuse:              opts.onRefuse,
+    onAudit:               opts.onAudit,
+  };
+
+  var active = [];
+  var skipped = [];
+  for (var i = 0; i < GUARDS.length; i += 1) {
+    var g = GUARDS[i];
+    if (Object.prototype.hasOwnProperty.call(exceptFor, g.NAME)) {
+      skipped.push({ name: g.NAME, reason: exceptFor[g.NAME].reason });
+      continue;
+    }
+    var merged = Object.assign({}, baseOpts);
+    if (Object.prototype.hasOwnProperty.call(override, g.NAME)) {
+      merged = Object.assign(merged, override[g.NAME]);
+    }
+    active.push({ guard: g, opts: merged });
+  }
+  return { active: active, skipped: skipped };
+}
+
+// _emitCreationAudit — fires once per gate creation, recording the full
+// active + skipped roster so a security review can reconstruct what
+// this deploy did and didn't defend against.
+function _emitCreationAudit(opts, resolved) {
+  if (!opts.audit || typeof opts.audit.emit !== "function") return;
+  try {
+    opts.audit.emit({
+      event:    "guardAll.gate.created",
+      outcome:  "success",
+      metadata: {
+        profile:           opts.profile || null,
+        compliancePosture: opts.compliancePosture || null,
+        mode:              opts.mode || "enforce",
+        active:            resolved.active.map(function (e) { return e.guard.NAME; }),
+        skipped:           resolved.skipped,
+      },
+    });
+  } catch (_e) {
+    // best-effort audit emission; never fails the gate creation.
+  }
+}
+
+// ---- Public surface ----
+
+function gate(opts) {
+  opts = opts || {};
+  var resolved = _resolveActiveGuards(opts);
+  _emitCreationAudit(opts, resolved);
+
+  var byMime = Object.create(null);
+  for (var i = 0; i < resolved.active.length; i += 1) {
+    var entry = resolved.active[i];
+    var entryGate = entry.guard.gate(entry.opts);
+    entry.guard.MIME_TYPES.forEach(function (m) {
+      byMime[m.toLowerCase()] = entryGate;
+    });
+  }
+  return gateContract.contentTypeMux(byMime, {
+    name: "guardAll:" + (opts.profile || opts.compliancePosture || "default"),
+  });
+}
+
+function byExtension(opts) {
+  opts = opts || {};
+  var resolved = _resolveActiveGuards(opts);
+  _emitCreationAudit(opts, resolved);
+
+  var map = Object.create(null);
+  for (var i = 0; i < resolved.active.length; i += 1) {
+    var entry = resolved.active[i];
+    var entryGate = entry.guard.gate(entry.opts);
+    entry.guard.EXTENSIONS.forEach(function (e) {
+      map[e.toLowerCase()] = entryGate;
+    });
+  }
+  return map;
+}
+
+function byContentType(opts) {
+  opts = opts || {};
+  var resolved = _resolveActiveGuards(opts);
+  _emitCreationAudit(opts, resolved);
+
+  var map = Object.create(null);
+  for (var i = 0; i < resolved.active.length; i += 1) {
+    var entry = resolved.active[i];
+    var entryGate = entry.guard.gate(entry.opts);
+    entry.guard.MIME_TYPES.forEach(function (m) {
+      map[m.toLowerCase()] = entryGate;
+    });
+  }
+  return map;
+}
+
+function list() {
+  return GUARDS.map(function (g) {
+    return {
+      name:       g.NAME,
+      mimeTypes:  g.MIME_TYPES.slice(),
+      extensions: g.EXTENSIONS.slice(),
+      profiles:   Object.keys(g.PROFILES),
+      postures:   Object.keys(g.COMPLIANCE_POSTURES),
+    };
+  });
+}
+
+// allGuards — every guard primitive in the family, registered AND
+// standalone. Used by the adaptive integration harness to iterate
+// the full family without hardcoding the list. Future guards added
+// to either GUARDS or STANDALONE_GUARDS pick up automatically.
+function allGuards() {
+  return GUARDS.concat(STANDALONE_GUARDS);
+}
+
+module.exports = {
+  gate:              gate,
+  byExtension:       byExtension,
+  byContentType:     byContentType,
+  list:              list,
+  allGuards:         allGuards,
+  GUARDS:            Object.freeze(GUARDS.slice()),
+  STANDALONE_GUARDS: Object.freeze(STANDALONE_GUARDS.slice()),
+  SHARED_PROFILES:   SHARED_PROFILES,
+  SHARED_POSTURES:   SHARED_POSTURES,
+  GuardAllError:     GuardAllError,
+};