@blamejs/core 0.9.24 → 0.9.38

package/lib/guard-posture-chain.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * @module     b.guardPostureChain
+ * @nav        Guards
+ * @title      Guard Posture Chain
+ * @order      442
+ *
+ * @intro
+ *   Validates cross-boundary posture-chain envelopes. The envelope
+ *   carries the set of compliance regimes the call is operating
+ *   under (`postureSet: ["hipaa", "pci-dss"]`), the hop trail
+ *   (`chainTrail: ["api-gateway", "mail-agent", "audit"]`), per-hop
+ *   timestamps, and hop count. Refuses:
+ *
+ *     - oversized trail (default hop cap = 16; defends infinite
+ *       recursion across agent delegation)
+ *     - non-ASCII hop names (operator-greppable in audit logs)
+ *     - duplicate hop in trail (recursion guard)
+ *     - missing or non-monotonic enteredAt timestamps
+ *     - posture set contains non-string entries OR duplicates
+ *
+ * @card
+ *   Validates cross-boundary posture envelopes. Hop trail caps,
+ *   ASCII-only hop names, monotonic timestamps, set-shape
+ *   posture-regime entries.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardPostureChainError = defineClass("GuardPostureChainError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxHops: 16,  maxHopBytes: 64,  maxRegimes: 8  },                                     // allow:raw-byte-literal
+  balanced:   { maxHops: 32,  maxHopBytes: 128, maxRegimes: 16 },                                     // allow:raw-byte-literal
+  permissive: { maxHops: 128, maxHopBytes: 256, maxRegimes: 64 },                                     // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardPostureChain.validate
+ * @signature b.guardPostureChain.validate(envelope, opts?)
+ * @since     0.9.28
+ * @status    stable
+ * @related   b.agent.postureChain.create
+ *
+ * Validate a posture-chain envelope. Returns the envelope on success;
+ * throws on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardPostureChain.validate({
+ *     postureSet: ["hipaa"],
+ *     chainTrail: ["api-gateway", "mail-agent"],
+ *     enteredAt:  [1700000000000, 1700000000100],
+ *     hopCount:   2,
+ *   });
+ */
+function validate(envelope, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!envelope || typeof envelope !== "object") {
+    throw new GuardPostureChainError("posture-chain/bad-input",
+      "guardPostureChain.validate: envelope required");
+  }
+  // postureSet — array of distinct ASCII regime names
+  if (!Array.isArray(envelope.postureSet)) {
+    throw new GuardPostureChainError("posture-chain/bad-posture-set",
+      "guardPostureChain.validate: postureSet must be an array");
+  }
+  if (envelope.postureSet.length > profile.maxRegimes) {
+    throw new GuardPostureChainError("posture-chain/too-many-regimes",
+      "guardPostureChain.validate: " + envelope.postureSet.length +
+      " regimes exceeds maxRegimes=" + profile.maxRegimes);
+  }
+  var regSeen = Object.create(null);
+  for (var r = 0; r < envelope.postureSet.length; r += 1) {
+    var regime = envelope.postureSet[r];
+    if (typeof regime !== "string" || regime.length === 0) {
+      throw new GuardPostureChainError("posture-chain/bad-regime",
+        "guardPostureChain.validate: postureSet[" + r + "] must be a non-empty string");
+    }
+    if (regSeen[regime]) {
+      throw new GuardPostureChainError("posture-chain/duplicate-regime",
+        "guardPostureChain.validate: duplicate regime '" + regime + "' in postureSet");
+    }
+    regSeen[regime] = true;
+  }
+  // chainTrail — bounded hop list
+  if (!Array.isArray(envelope.chainTrail)) {
+    throw new GuardPostureChainError("posture-chain/bad-trail",
+      "guardPostureChain.validate: chainTrail must be an array");
+  }
+  if (envelope.chainTrail.length > profile.maxHops) {
+    throw new GuardPostureChainError("posture-chain/hop-limit-exceeded",
+      "guardPostureChain.validate: " + envelope.chainTrail.length +
+      " hops exceeds maxHops=" + profile.maxHops);
+  }
+  var hopSeen = Object.create(null);
+  for (var h = 0; h < envelope.chainTrail.length; h += 1) {
+    var hop = envelope.chainTrail[h];
+    if (typeof hop !== "string" || hop.length === 0) {
+      throw new GuardPostureChainError("posture-chain/bad-hop",
+        "guardPostureChain.validate: chainTrail[" + h + "] must be a non-empty string");
+    }
+    if (Buffer.byteLength(hop, "utf8") > profile.maxHopBytes) {
+      throw new GuardPostureChainError("posture-chain/hop-name-too-long",
+        "guardPostureChain.validate: chainTrail[" + h + "] exceeds maxHopBytes=" + profile.maxHopBytes);
+    }
+    for (var hi = 0; hi < hop.length; hi += 1) {
+      var hc = hop.charCodeAt(hi);
+      if (hc > 0x7F) {                                                                                // allow:raw-byte-literal — ASCII-only
+        throw new GuardPostureChainError("posture-chain/non-ascii-hop",
+          "guardPostureChain.validate: chainTrail[" + h + "] has non-ASCII codepoint");
+      }
+      if (hc < 0x20 || hc === 0x7F) {                                                                 // allow:raw-byte-literal — C0/DEL
+        throw new GuardPostureChainError("posture-chain/bad-hop-char",
+          "guardPostureChain.validate: chainTrail[" + h + "] has forbidden char 0x" + hc.toString(16));
+      }
+    }
+    if (hopSeen[hop]) {
+      throw new GuardPostureChainError("posture-chain/duplicate-hop",
+        "guardPostureChain.validate: duplicate hop '" + hop + "' in chainTrail");
+    }
+    hopSeen[hop] = true;
+  }
+  // enteredAt timestamps (optional but if present must match length + be monotonic)
+  if (typeof envelope.enteredAt !== "undefined") {
+    if (!Array.isArray(envelope.enteredAt)) {
+      throw new GuardPostureChainError("posture-chain/bad-entered-at",
+        "guardPostureChain.validate: enteredAt must be an array of timestamps");
+    }
+    if (envelope.enteredAt.length !== envelope.chainTrail.length) {
+      throw new GuardPostureChainError("posture-chain/entered-at-length-mismatch",
+        "guardPostureChain.validate: enteredAt length must equal chainTrail length");
+    }
+    var prevT = -Infinity;
+    for (var t = 0; t < envelope.enteredAt.length; t += 1) {
+      var ts = envelope.enteredAt[t];
+      if (typeof ts !== "number" || !isFinite(ts) || ts < 0) {
+        throw new GuardPostureChainError("posture-chain/bad-timestamp",
+          "guardPostureChain.validate: enteredAt[" + t + "] must be a finite non-negative number");
+      }
+      if (ts < prevT) {
+        throw new GuardPostureChainError("posture-chain/non-monotonic-timestamps",
+          "guardPostureChain.validate: enteredAt[" + t + "] < enteredAt[" + (t - 1) + "]");
+      }
+      prevT = ts;
+    }
+  }
+  return envelope;
+}
+
+/**
+ * @primitive b.guardPostureChain.compliancePosture
+ * @signature b.guardPostureChain.compliancePosture(posture)
+ * @since     0.9.28
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardPostureChain.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardPostureChainError("posture-chain/bad-profile",
+      "guardPostureChain: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                  validate,
+  compliancePosture:         compliancePosture,
+  PROFILES:                  PROFILES,
+  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
+  GuardPostureChainError:    GuardPostureChainError,
+  NAME:                      "postureChain",
+  KIND:                      "posture-chain",
+};

package/lib/guard-saga-config.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * @module     b.guardSagaConfig
+ * @nav        Guards
+ * @title      Guard Saga Config
+ * @order      441
+ *
+ * @intro
+ *   Saga-creation config validator. Refuses empty steps array,
+ *   duplicate step names, non-ASCII saga name, non-async-function
+ *   run/compensate fields, oversized step count.
+ *
+ * @card
+ *   Validates `b.agent.saga.create()` opts. Step-list shape, name
+ *   uniqueness, run/compensate function checks.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardSagaConfigError = defineClass("GuardSagaConfigError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxSteps: 32,   maxNameBytes: 64  },                                                  // allow:raw-byte-literal
+  balanced:   { maxSteps: 128,  maxNameBytes: 128 },                                                  // allow:raw-byte-literal
+  permissive: { maxSteps: 512,  maxNameBytes: 256 },                                                  // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardSagaConfig.validate
+ * @signature b.guardSagaConfig.validate(config, opts?)
+ * @since     0.9.27
+ * @status    stable
+ * @related   b.agent.saga.create
+ *
+ * Validate saga config. Returns config on success; throws on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardSagaConfig.validate({
+ *     name: "mail.send",
+ *     steps: [
+ *       { name: "sign", run: async () => {}, compensate: async () => {} },
+ *     ],
+ *   });
+ */
+function validate(config, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!config || typeof config !== "object") {
+    throw new GuardSagaConfigError("saga-config/bad-input",
+      "guardSagaConfig.validate: config required");
+  }
+  if (typeof config.name !== "string" || config.name.length === 0) {
+    throw new GuardSagaConfigError("saga-config/bad-name",
+      "guardSagaConfig.validate: name required");
+  }
+  if (Buffer.byteLength(config.name, "utf8") > profile.maxNameBytes) {
+    throw new GuardSagaConfigError("saga-config/name-too-long",
+      "guardSagaConfig.validate: name exceeds maxNameBytes=" + profile.maxNameBytes);
+  }
+  for (var i = 0; i < config.name.length; i += 1) {
+    var c = config.name.charCodeAt(i);
+    if (c > 0x7F) {                                                                                   // allow:raw-byte-literal — ASCII-only
+      throw new GuardSagaConfigError("saga-config/non-ascii-name",
+        "guardSagaConfig.validate: name has non-ASCII codepoint at offset " + i);
+    }
+    if (c < 0x20 || c === 0x7F) {                                                                     // allow:raw-byte-literal — C0/DEL
+      throw new GuardSagaConfigError("saga-config/bad-name-char",
+        "guardSagaConfig.validate: name has forbidden char 0x" + c.toString(16));
+    }
+  }
+  if (!Array.isArray(config.steps) || config.steps.length === 0) {
+    throw new GuardSagaConfigError("saga-config/no-steps",
+      "guardSagaConfig.validate: steps must be a non-empty array");
+  }
+  if (config.steps.length > profile.maxSteps) {
+    throw new GuardSagaConfigError("saga-config/too-many-steps",
+      "guardSagaConfig.validate: " + config.steps.length + " steps exceeds " + profile.maxSteps);
+  }
+  var seenNames = Object.create(null);
+  for (var s = 0; s < config.steps.length; s += 1) {
+    var step = config.steps[s];
+    if (!step || typeof step !== "object") {
+      throw new GuardSagaConfigError("saga-config/bad-step",
+        "guardSagaConfig.validate: steps[" + s + "] must be an object");
+    }
+    if (typeof step.name !== "string" || step.name.length === 0) {
+      throw new GuardSagaConfigError("saga-config/bad-step-name",
+        "guardSagaConfig.validate: steps[" + s + "].name required");
+    }
+    if (seenNames[step.name]) {
+      throw new GuardSagaConfigError("saga-config/duplicate-step-name",
+        "guardSagaConfig.validate: duplicate step name '" + step.name + "'");
+    }
+    seenNames[step.name] = true;
+    if (typeof step.run !== "function") {
+      throw new GuardSagaConfigError("saga-config/bad-step-run",
+        "guardSagaConfig.validate: steps[" + s + "].run must be a function");
+    }
+    if (typeof step.compensate !== "undefined" && typeof step.compensate !== "function") {
+      throw new GuardSagaConfigError("saga-config/bad-step-compensate",
+        "guardSagaConfig.validate: steps[" + s + "].compensate must be a function (or omitted)");
+    }
+  }
+  return config;
+}
+
+/**
+ * @primitive b.guardSagaConfig.compliancePosture
+ * @signature b.guardSagaConfig.compliancePosture(posture)
+ * @since     0.9.27
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardSagaConfig.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardSagaConfigError("saga-config/bad-profile",
+      "guardSagaConfig: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                 validate,
+  compliancePosture:        compliancePosture,
+  PROFILES:                 PROFILES,
+  COMPLIANCE_POSTURES:      COMPLIANCE_POSTURES,
+  GuardSagaConfigError:     GuardSagaConfigError,
+  NAME:                     "sagaConfig",
+  KIND:                     "saga-config",
+};