@blamejs/core 0.9.23 → 0.9.28

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",
+};

package/lib/guard-stream-args.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * @module     b.guardStreamArgs
+ * @nav        Guards
+ * @title      Guard Stream Args
+ * @order      437
+ *
+ * @intro
+ *   Validates `b.agent.stream.create` opts (and the operator-supplied
+ *   stream args). Refuses non-positive batch sizes, non-integer batch
+ *   sizes (silent shard-style routing drift class — same shape Codex
+ *   caught on v0.9.21), oversized batch sizes (back-pressure becomes
+ *   meaningless), and structured-clone-unsafe filter shapes (functions
+ *   / regex / Buffer in the cursor opts — same shape `b.guardMailQuery`
+ *   refuses).
+ *
+ * @card
+ *   Validates `b.agent.stream.create` opts + cursor args. Integer-only
+ *   batchSize, structured-clone-safe filter shapes, sensible caps.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardStreamArgsError = defineClass("GuardStreamArgsError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBatchSize: 1024,  minBatchSize: 1, maxOpenStreams: 4   },                          // allow:raw-byte-literal
+  balanced:   { maxBatchSize: 4096,  minBatchSize: 1, maxOpenStreams: 16  },                          // allow:raw-byte-literal
+  permissive: { maxBatchSize: 16384, minBatchSize: 1, maxOpenStreams: 64  },                          // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardStreamArgs.validate
+ * @signature b.guardStreamArgs.validate(args, opts?)
+ * @since     0.9.24
+ * @status    stable
+ * @related   b.agent.stream.create
+ *
+ * Validate `b.agent.stream.create` opts shape. Returns the input on
+ * success; throws `GuardStreamArgsError` on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardStreamArgs.validate({
+ *     batchSize: 256,
+ *     kind:      "search",
+ *   });
+ */
+function validate(args, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!args || typeof args !== "object") {
+    throw new GuardStreamArgsError("stream-args/bad-input",
+      "guardStreamArgs.validate: args required");
+  }
+  if (typeof args.batchSize !== "undefined") {
+    if (!Number.isInteger(args.batchSize)) {
+      throw new GuardStreamArgsError("stream-args/bad-batch-size",
+        "guardStreamArgs.validate: batchSize must be an integer");
+    }
+    if (args.batchSize < profile.minBatchSize || args.batchSize > profile.maxBatchSize) {
+      throw new GuardStreamArgsError("stream-args/batch-size-out-of-range",
+        "guardStreamArgs.validate: batchSize " + args.batchSize +
+        " not in [" + profile.minBatchSize + ", " + profile.maxBatchSize + "]");
+    }
+  }
+  if (typeof args.kind !== "undefined") {
+    if (typeof args.kind !== "string" || args.kind.length === 0) {
+      throw new GuardStreamArgsError("stream-args/bad-kind",
+        "guardStreamArgs.validate: kind must be a non-empty string");
+    }
+  }
+  // Cursor opts can't carry function / regex / Buffer — they must
+  // cross the structured-clone boundary into a worker thread.
+  if (typeof args.cursorOpts !== "undefined") {
+    _checkCursorOpts(args.cursorOpts);
+  }
+  return args;
+}
+
+/**
+ * @primitive b.guardStreamArgs.compliancePosture
+ * @signature b.guardStreamArgs.compliancePosture(posture)
+ * @since     0.9.24
+ * @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.guardStreamArgs.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _checkCursorOpts(cursorOpts, depth) {
+  depth = depth || 0;
+  if (depth > 8) {                                                                                    // allow:raw-byte-literal — recursion depth cap
+    throw new GuardStreamArgsError("stream-args/cursor-opts-too-deep",
+      "guardStreamArgs.validate: cursorOpts nesting depth exceeds 8");
+  }
+  // Function check FIRST — `typeof function === "function"` not
+  // "object", so a function value would silently skip the non-object
+  // early-return below.
+  if (typeof cursorOpts === "function") {
+    throw new GuardStreamArgsError("stream-args/function-not-allowed",
+      "guardStreamArgs.validate: functions refused in cursorOpts (structured-clone-unsafe)");
+  }
+  if (cursorOpts === null || typeof cursorOpts !== "object") return;
+  if (cursorOpts instanceof RegExp) {
+    throw new GuardStreamArgsError("stream-args/regex-not-allowed",
+      "guardStreamArgs.validate: RegExp refused in cursorOpts");
+  }
+  if (Buffer.isBuffer(cursorOpts)) {
+    throw new GuardStreamArgsError("stream-args/buffer-not-allowed",
+      "guardStreamArgs.validate: Buffer refused in cursorOpts");
+  }
+  if (Array.isArray(cursorOpts)) {
+    for (var i = 0; i < cursorOpts.length; i += 1) _checkCursorOpts(cursorOpts[i], depth + 1);
+    return;
+  }
+  var keys = Object.keys(cursorOpts);
+  for (var k = 0; k < keys.length; k += 1) {
+    if (keys[k] === "__proto__" || keys[k] === "constructor" || keys[k] === "prototype") {
+      throw new GuardStreamArgsError("stream-args/proto-key",
+        "guardStreamArgs.validate: forbidden key '" + keys[k] + "' in cursorOpts");
+    }
+    _checkCursorOpts(cursorOpts[keys[k]], depth + 1);
+  }
+}
+
+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 GuardStreamArgsError("stream-args/bad-profile",
+      "guardStreamArgs: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:              validate,
+  compliancePosture:     compliancePosture,
+  PROFILES:              PROFILES,
+  COMPLIANCE_POSTURES:   COMPLIANCE_POSTURES,
+  GuardStreamArgsError:  GuardStreamArgsError,
+  NAME:                  "streamArgs",
+  KIND:                  "stream-args",
+};

package/lib/guard-tenant-id.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * @module     b.guardTenantId
+ * @nav        Guards
+ * @title      Guard Tenant Id
+ * @order      440
+ *
+ * @intro
+ *   Tenant-id shape validator. Tenant ids surface in audit log lines,
+ *   sealed registry rows, derived-key context labels, and routing
+ *   keys — they have to be ASCII-greppable across the whole framework
+ *   stack. Refuses:
+ *
+ *     - non-ASCII (NFC + ASCII-only)
+ *     - path-traversal shapes (`..` / `/` / `\` / NUL / C0 / DEL)
+ *     - oversized (default 64 bytes)
+ *     - reserved `ROOT` / `FRAMEWORK` / `*` / empty
+ *     - leading `.` (hidden-folder shape)
+ *
+ * @card
+ *   Validates tenant-id strings. ASCII-only, bounded, no path-
+ *   traversal, no reserved names.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardTenantIdError = defineClass("GuardTenantIdError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: 64  },                                                                      // allow:raw-byte-literal
+  balanced:   { maxBytes: 128 },                                                                      // allow:raw-byte-literal
+  permissive: { maxBytes: 512 },                                                                      // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var RESERVED = Object.freeze({ "ROOT": true, "FRAMEWORK": true, "*": true });
+
+/**
+ * @primitive b.guardTenantId.validate
+ * @signature b.guardTenantId.validate(tenantId, opts?)
+ * @since     0.9.26
+ * @status    stable
+ * @related   b.agent.tenant.create
+ *
+ * Validate a tenant-id string. Returns the id on success; throws
+ * `GuardTenantIdError` on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardTenantId.validate("acme-clinic");
+ */
+function validate(tenantId, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (typeof tenantId !== "string" || tenantId.length === 0) {
+    throw new GuardTenantIdError("tenant-id/bad-input",
+      "guardTenantId.validate: tenantId must be a non-empty string");
+  }
+  if (Buffer.byteLength(tenantId, "utf8") > profile.maxBytes) {
+    throw new GuardTenantIdError("tenant-id/oversize",
+      "guardTenantId.validate: tenantId exceeds maxBytes=" + profile.maxBytes);
+  }
+  if (RESERVED[tenantId]) {
+    throw new GuardTenantIdError("tenant-id/reserved",
+      "guardTenantId.validate: tenantId '" + tenantId + "' is framework-reserved");
+  }
+  if (tenantId.charAt(0) === ".") {
+    throw new GuardTenantIdError("tenant-id/hidden",
+      "guardTenantId.validate: tenantId cannot start with '.'");
+  }
+  if (tenantId.indexOf("..") >= 0) {
+    throw new GuardTenantIdError("tenant-id/path-traversal",
+      "guardTenantId.validate: tenantId contains '..'");
+  }
+  for (var i = 0; i < tenantId.length; i += 1) {
+    var c = tenantId.charCodeAt(i);
+    if (c > 0x7F) {                                                                                   // allow:raw-byte-literal — ASCII-only cap
+      throw new GuardTenantIdError("tenant-id/non-ascii",
+        "guardTenantId.validate: non-ASCII codepoint at offset " + i);
+    }
+    if (c < 0x20 || c === 0x7F || c === 0x2F || c === 0x5C) {                                         // allow:raw-byte-literal — C0/DEL/slash/backslash
+      throw new GuardTenantIdError("tenant-id/bad-char",
+        "guardTenantId.validate: forbidden char 0x" + c.toString(16) + " at offset " + i);
+    }
+  }
+  return tenantId;
+}
+
+/**
+ * @primitive b.guardTenantId.compliancePosture
+ * @signature b.guardTenantId.compliancePosture(posture)
+ * @since     0.9.26
+ * @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.guardTenantId.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 GuardTenantIdError("tenant-id/bad-profile",
+      "guardTenantId: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:               validate,
+  compliancePosture:      compliancePosture,
+  PROFILES:               PROFILES,
+  COMPLIANCE_POSTURES:    COMPLIANCE_POSTURES,
+  RESERVED:               RESERVED,
+  GuardTenantIdError:     GuardTenantIdError,
+  NAME:                   "tenantId",
+  KIND:                   "tenant-id",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.23",
+  "version": "0.9.28",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",