@blamejs/core 0.14.26 → 0.15.0

package/lib/guard-shell.js

@@ -342,181 +342,51 @@ function sanitize(input, opts) {
   // Shell args can't be repaired — sanitize either passes through
   // valid input or throws.
   var issues = _detectIssues(input, opts);
-  for (var i = 0; i < issues.length; i += 1) {
-    if (issues[i].severity === "critical" || issues[i].severity === "high") {
-      throw _err(issues[i].ruleId || "shell.refused",
-        "guardShell.sanitize: " + issues[i].snippet);
-    }
-  }
+  gateContract.throwOnRefusalSeverity(issues, {
+    errorClass: GuardShellError, codePrefix: "shell",
+  });
   return input;
 }
 
-/**
- * @primitive  b.guardShell.gate
- * @signature  b.guardShell.gate(opts)
- * @since      0.7.13
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardShell.validate, b.guardShell.sanitize, b.processSpawn
- *
- * Build a `b.gateContract` gate that screens `ctx.identifier` (or
- * `ctx.arg`) before each spawn. Action chain: `serve` (no issues)
- * → `audit-only` (warn-only) → `refuse` (any `critical` or `high`).
- * No `sanitize` action — shell args cannot be repaired. Compose
- * with `b.processSpawn` so each argv slot is gated before reaching
- * the OS (the spawn primitive itself enforces `shell: false`; the
- * gate enforces metacharacter cleanliness).
- *
- * @opts
- *   profile:           "strict"|"balanced"|"permissive",
- *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
- *   name:              string,        // override gate name in audit emissions
- *   posixMetaPolicy:   "reject"|"audit"|"allow",
- *   cmdMetaPolicy:     "reject"|"audit"|"allow",
- *   dollarSubstPolicy: "reject"|"audit"|"allow",
- *   processSubstPolicy:"reject"|"audit"|"allow",
- *   backtickPolicy:    "reject"|"audit"|"allow",
- *   newlinePolicy:     "reject"|"audit"|"allow",
- *   argHyphenPolicy:   "reject"|"audit"|"allow",
- *   maxBytes:          number,
- *
- * @example
- *   var gate = b.guardShell.gate({ profile: "strict" });
- *
- *   // Hostile arg — gate refuses before spawn.
- *   gate({ identifier: "safe; rm -rf /" }).then(function (rv) {
- *     rv.ok;                                           // → false
- *     rv.action;                                       // → "refuse"
- *   });
- *
- *   // Benign arg — gate serves.
- *   gate({ identifier: "safe-arg-value" }).then(function (rv) {
- *     rv.action;                                       // → "serve"
- *   });
- */
-function gate(opts) {
-  opts = _resolveOpts(opts);
-  return gateContract.buildGuardGate(
-    opts.name || "guardShell:" + (opts.profile || "default"),
-    opts,
-    async function (ctx) {
-      var arg = ctx && (ctx.identifier || ctx.arg);
-      if (arg === undefined || arg === null) return { ok: true, action: "serve" };
-      var rv = validate(arg, opts);
-      if (rv.issues.length === 0) return { ok: true, action: "serve" };
-      var hasCritical = rv.issues.some(function (i) {
-        return i.severity === "critical";
-      });
-      var hasHigh = rv.issues.some(function (i) {
-        return i.severity === "high";
-      });
-      if (!hasCritical && !hasHigh) {
-        return { ok: true, action: "audit-only", issues: rv.issues };
-      }
-      return { ok: false, action: "refuse", issues: rv.issues };
-    });
-}
-
-/**
- * @primitive  b.guardShell.buildProfile
- * @signature  b.guardShell.buildProfile(opts)
- * @since      0.7.13
- * @status     stable
- * @related    b.guardShell.gate, b.guardShell.compliancePosture
- *
- * Compose a derived guardShell profile from one or more named bases
- * plus inline overrides. `opts.extends` is a profile name
- * (`"strict"` / `"balanced"` / `"permissive"`) or an array of
- * names; later entries shadow earlier ones. Inline `opts` keys win
- * last. Used to keep operator-defined profiles traceable to a
- * baseline rather than re-typing every key.
- *
- * @opts
- *   extends: string|string[],   // base profile name(s) to compose
- *   ...:     any guardShell key, // inline override of resolved keys
- *
- * @example
- *   var custom = b.guardShell.buildProfile({
- *     extends: "balanced",
- *     argHyphenPolicy: "reject",
- *   });
- *   custom.argHyphenPolicy;                            // → "reject"
- *   custom.dollarSubstPolicy;                          // → "reject"
- */
-var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+// The request-boundary gate is the gate-contract factory default: it reads
+// `ctx.identifier` (or `ctx.arg`), runs `validate`, and maps severity to
+// action — `serve` (no issue) / `audit-only` (info / warn) / `refuse` (any
+// high / critical). No `sanitize` action — shell args cannot be repaired.
+// Compose with `b.processSpawn` so each argv slot is gated before reaching
+// the OS (the spawn primitive itself enforces `shell: false`; the gate
+// enforces metacharacter cleanliness). Its wiki section renders from the
+// single-sourced `@abiTemplate gate` block in gate-contract.js.
 
-/**
- * @primitive  b.guardShell.compliancePosture
- * @signature  b.guardShell.compliancePosture(name)
- * @since      0.7.13
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardShell.gate, b.guardShell.buildProfile
- *
- * Look up a compliance-posture overlay by name (`"hipaa"` /
- * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of
- * the posture object — the caller may mutate freely. Throws
- * `GuardShellError("shell.bad-posture")` on unknown name.
- *
- * @example
- *   var posture = b.guardShell.compliancePosture("hipaa");
- *   posture.posixMetaPolicy;                           // → "reject"
- *   posture.forensicSnippetBytes;                      // → 256
- */
-function compliancePosture(name) {
-  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
-    _err, "shell");
-}
+// buildProfile / compliancePosture / loadRulePack are assembled by
+// gateContract.defineGuard below (makeProfileBuilder(PROFILES) /
+// lookupCompliancePosture(_, COMPLIANCE_POSTURES) / makeRulePackLoader).
+// Their wiki sections render from the single-sourced @abiTemplate blocks
+// in gate-contract.js, instantiated per guard by the page generator.
 
-var _shellRulePacks = gateContract.makeRulePackLoader(GuardShellError, "shell");
-/**
- * @primitive  b.guardShell.loadRulePack
- * @signature  b.guardShell.loadRulePack(pack)
- * @since      0.7.13
- * @status     stable
- * @related    b.guardShell.gate
- *
- * Register an operator-supplied rule pack with the guardShell
- * registry. The pack is identified by `pack.id` (non-empty string)
- * and stored for later inspection / dispatch by gates that opt in
- * via `opts.rulePackId`. Returns the pack object unchanged on
- * success; throws `GuardShellError("shell.bad-opt")` when `pack`
- * is missing or `pack.id` is not a non-empty string.
- *
- * @example
- *   var pack = b.guardShell.loadRulePack({
- *     id: "no-leading-dash",
- *     rules: [
- *       { id: "leading-dash", severity: "high",
- *         detect: function (arg) { return arg.charAt(0) === "-"; },
- *         reason: "argument starts with `-` flag prefix" },
- *     ],
- *   });
- *   pack.id;                                           // → "no-leading-dash"
- */
-var loadRulePack = _shellRulePacks.load;
+// ---- adaptive integration-test fixtures (consumed by layer-5 host harness) ----
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:              "identifier",
+  benignBytes:       Buffer.from("safe-arg-value", "utf8"),
+  hostileBytes:      Buffer.from("safe; rm -rf /", "utf8"),
+  benignIdentifier:  "safe-arg-value",
+  // Hostile: command-injection via metacharacter chain.
+  hostileIdentifier: "safe; rm -rf /",
+});
 
-module.exports = {
-  // ---- guard-* family registry exports ----
-  NAME:                "shell",
-  KIND:                "identifier",
-  INTEGRATION_FIXTURES: Object.freeze({
-    kind:              "identifier",
-    benignBytes:       Buffer.from("safe-arg-value", "utf8"),
-    hostileBytes:      Buffer.from("safe; rm -rf /", "utf8"),
-    benignIdentifier:  "safe-arg-value",
-    // Hostile: command-injection via metacharacter chain.
-    hostileIdentifier: "safe; rm -rf /",
-  }),
-  // ---- primitive surface ----
-  validate:            validate,
-  sanitize:            sanitize,
-  gate:                gate,
-  buildProfile:        buildProfile,
-  compliancePosture:   compliancePosture,
-  loadRulePack:        loadRulePack,
-  PROFILES:            PROFILES,
-  DEFAULTS:            DEFAULTS,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  GuardShellError:     GuardShellError,
-};
+// Assembled from the gate-contract guard factory: error class, registry
+// exports (NAME / KIND / INTEGRATION_FIXTURES), buildProfile /
+// compliancePosture / loadRulePack wiring, plus the per-guard inspection
+// surface (validate / sanitize). The gate is the factory default chain,
+// dispatched to `ctx.identifier` / `ctx.arg` via ctxFields.
+module.exports = gateContract.defineGuard({
+  name:        "shell",
+  kind:        "identifier",
+  errorClass:  GuardShellError,
+  profiles:    PROFILES,
+  defaults:    DEFAULTS,
+  postures:    COMPLIANCE_POSTURES,
+  integrationFixtures: INTEGRATION_FIXTURES,
+  validate:    validate,
+  sanitize:    sanitize,
+  ctxFields:   ["identifier", "arg"],
+});

package/lib/guard-smtp-command.js

@@ -103,11 +103,15 @@ var PROFILES = Object.freeze({
   permissive: { maxLineBytes: 4096, maxMailbox: 512, maxLocalPart: 64, maxDomain: 255, allowBareLf: true,  allowSmtpUtf8: true },                                                                          // permissive cap for legacy peers
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
+
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: GuardSmtpCommandError,
+  codePrefix: "guard-smtp-command",
+  byObject:   true,
 });
 
 // Verbs we know — anything else is refused under strict, accepted as
@@ -237,21 +241,10 @@ function validate(line, opts) {
   }
 }
 
-/**
- * @primitive b.guardSmtpCommand.compliancePosture
- * @signature b.guardSmtpCommand.compliancePosture(posture)
- * @since     0.9.32
- * @status    stable
- *
- * Return the effective profile name for a compliance posture, or
- * `null` for unknown posture names.
- *
- * @example
- *   b.guardSmtpCommand.compliancePosture("hipaa");   // → "strict"
- */
-function compliancePosture(posture) {
-  return COMPLIANCE_POSTURES[posture] || null;
-}
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
 
 function _validateGreeting(verb, rest, caps) {
   if (rest.length === 0) {
@@ -420,18 +413,6 @@ function _parseAuthCommandSyntax(rest) {
   };
 }
 
-function _resolveProfile(opts) {
-  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
-    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
-  }
-  var p = opts.profile || DEFAULT_PROFILE;
-  if (!PROFILES[p]) {
-    throw new GuardSmtpCommandError("guard-smtp-command/bad-profile",
-      "guardSmtpCommand: unknown profile '" + p + "'");
-  }
-  return PROFILES[p];
-}
-
 /**
  * @primitive b.guardSmtpCommand.gate
  * @signature b.guardSmtpCommand.gate(opts?)
@@ -569,25 +550,38 @@ function detectBodySmuggling(buf) {
   return false;
 }
 
-module.exports = {
-  validate:                  validate,
-  detectBodySmuggling:       detectBodySmuggling,
-  gate:                      gate,
-  compliancePosture:         compliancePosture,
-  PROFILES:                  PROFILES,
-  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
-  KNOWN_VERBS:               KNOWN_VERBS,
-  GuardSmtpCommandError:     GuardSmtpCommandError,
-  NAME:                      "smtpCommand",
-  KIND:                      "identifier",
-  INTEGRATION_FIXTURES:      Object.freeze({
-    kind:        "identifier",
-    // Benign: standard EHLO greeting.
-    benignBytes: Buffer.from("EHLO mail.example.com", "ascii"),
-    // Hostile: CRLF smuggling attempt — bare CR inside a command line
-    // (CVE-2023-51764 / 51765 / 51766 class).
-    hostileBytes: Buffer.from("MAIL FROM:<a@b.com>\r\n.\r\nMAIL FROM:<evil@x.com>", "ascii"),
-    benignIdentifier:  "EHLO mail.example.com",
-    hostileIdentifier: "MAIL FROM:<a@b.com>\r\n.\r\nMAIL FROM:<evil@x.com>",
-  }),
-};
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:        "identifier",
+  // Benign: standard EHLO greeting.
+  benignBytes: Buffer.from("EHLO mail.example.com", "ascii"),
+  // Hostile: CRLF smuggling attempt — bare CR inside a command line
+  // (CVE-2023-51764 / 51765 / 51766 class).
+  hostileBytes: Buffer.from("MAIL FROM:<a@b.com>\r\n.\r\nMAIL FROM:<evil@x.com>", "ascii"),
+  benignIdentifier:  "EHLO mail.example.com",
+  hostileIdentifier: "MAIL FROM:<a@b.com>\r\n.\r\nMAIL FROM:<evil@x.com>",
+});
+
+// Assembled from the gate-contract parser factory: error class,
+// compliancePosture wiring, PROFILES / COMPLIANCE_POSTURES, the `validate`
+// entry, plus this guard's registry exports (NAME / KIND /
+// INTEGRATION_FIXTURES), bespoke `gate`, `detectBodySmuggling`, and the
+// KNOWN_VERBS table passed through verbatim. defineParser is the right
+// shape here — the guard's four postures all resolve to `strict`
+// (ALL_STRICT_POSTURES) and it carries no buildProfile / loadRulePack.
+// The bespoke `gate` and `detectBodySmuggling` keep their own @primitive
+// blocks; only the factory-generated compliancePosture block is removed.
+module.exports = gateContract.defineParser({
+  name:       "smtp-command",
+  entry:      validate,
+  errorClass: GuardSmtpCommandError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    NAME:                "smtpCommand",
+    KIND:                "identifier",
+    INTEGRATION_FIXTURES: INTEGRATION_FIXTURES,
+    gate:                gate,
+    detectBodySmuggling: detectBodySmuggling,
+    KNOWN_VERBS:         KNOWN_VERBS,
+  },
+});

package/lib/guard-snapshot-envelope.js

@@ -29,6 +29,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var gateContract = require("./gate-contract");
 
 var GuardSnapshotEnvelopeError = defineClass("GuardSnapshotEnvelopeError", { alwaysPermanent: true });
 
@@ -40,11 +41,14 @@ var PROFILES = Object.freeze({
   permissive: { maxBytes: 1073741824, maxInFlight: 1048576 },                                         // 1 GiB
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
+
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: GuardSnapshotEnvelopeError,
+  codePrefix: "snapshot-envelope",
 });
 
 /**
@@ -128,41 +132,19 @@ function validate(envelope, opts) {
   return envelope;
 }
 
-/**
- * @primitive b.guardSnapshotEnvelope.compliancePosture
- * @signature b.guardSnapshotEnvelope.compliancePosture(posture)
- * @since     0.9.30
- * @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.guardSnapshotEnvelope.compliancePosture("hipaa");   // returns "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 GuardSnapshotEnvelopeError("snapshot-envelope/bad-profile",
-      "guardSnapshotEnvelope: unknown profile '" + p + "'");
-  }
-  return p;
-}
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
 
-module.exports = {
-  validate:                    validate,
-  compliancePosture:           compliancePosture,
-  PROFILES:                    PROFILES,
-  COMPLIANCE_POSTURES:         COMPLIANCE_POSTURES,
-  GuardSnapshotEnvelopeError:  GuardSnapshotEnvelopeError,
-  NAME:                        "snapshotEnvelope",
-  KIND:                        "snapshot-envelope",
-};
+module.exports = gateContract.defineParser({
+  name:       "snapshot-envelope",
+  entry:      validate,
+  errorClass: GuardSnapshotEnvelopeError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    NAME: "snapshotEnvelope",
+    KIND: "snapshot-envelope",
+  },
+});