@blamejs/core 0.9.24 → 0.9.28

package/lib/agent-tenant.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * @module     b.agent.tenant
+ * @nav        Agent
+ * @title      Agent Tenant
+ * @order      70
+ *
+ * @intro
+ *   Multi-tenant isolation as a first-class primitive. Replaces the
+ *   per-operator wiring of `actor.tenantId === registeredTenant` that
+ *   tends to leak across handlers, with one centralized scope:
+ *
+ *     - **Registry** — `register(tenantId, config)` declares a tenant
+ *       boundary at boot. Sealed registry rows so tenant metadata
+ *       doesn't leak in DB dumps.
+ *     - **Cross-tenant gate** — `check(actor, agentTenantId)` refuses
+ *       calls where `actor.tenantId !== agentTenantId` unless the
+ *       actor holds the `framework.cross-tenant-admin` scope.
+ *     - **Per-tenant derived keys** — `derivedKey(tenantId, purpose)`
+ *       composes `b.crypto.namespaceHash` to derive a stable per-
+ *       tenant key from the framework's primary seal key + tenant
+ *       context. Cross-tenant decrypt refused at the vault boundary.
+ *     - **Per-tenant audit** — `auditFor(tenantId)` returns an audit
+ *       wrapper that auto-tags metadata with the tenant id so each
+ *       tenant's audit trail is independently filterable.
+ *     - **Archive-default destroy** — `unregister(tenantId)` archives
+ *       the tenant + its derived key (retention-safe default).
+ *       Destruction requires explicit `{ destroy: true, stepUpToken,
+ *       dualControlApprover, reason }` — irreversible crypto-erasure
+ *       for GDPR Art. 17 / right-to-be-forgotten cases.
+ *
+ *   ```js
+ *   var tenant = b.agent.tenant.create({});
+ *
+ *   await tenant.register("acme-clinic", {
+ *     posture:        ["hipaa"],
+ *     archivePolicy:  "hipaa-6yr",
+ *   });
+ *
+ *   tenant.check({ id: "u1", tenantId: "acme-clinic" }, "acme-clinic");  // OK
+ *   tenant.check({ id: "u2", tenantId: "globex"      }, "acme-clinic");  // throws
+ *
+ *   var sealKey = tenant.derivedKey("acme-clinic", "seal");
+ *   var auditA  = tenant.auditFor("acme-clinic");
+ *   ```
+ *
+ * @card
+ *   Multi-tenant isolation as a first-class primitive. Cross-tenant
+ *   gating, per-tenant derived keys, per-tenant audit namespaces, and
+ *   archive-default destroy with step-up + dual-control.
+ */
+
+var lazyRequire      = require("./lazy-require");
+var { defineClass }  = require("./framework-error");
+var guardTenantId    = require("./guard-tenant-id");
+var bCrypto          = require("./crypto");
+var agentAudit       = require("./agent-audit");
+
+var audit            = lazyRequire(function () { return require("./audit"); });
+
+var AgentTenantError = defineClass("AgentTenantError", { alwaysPermanent: true });
+
+var CROSS_TENANT_ADMIN_SCOPE = "framework-cross-tenant-admin";
+
+/**
+ * @primitive b.agent.tenant.create
+ * @signature b.agent.tenant.create(opts)
+ * @since     0.9.26
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * Create the tenant-scope facade. Returns an instance with `register`
+ * / `unregister` / `lookup` / `list` / `check` / `derivedKey` /
+ * `auditFor`.
+ *
+ * @opts
+ *   backend:      { get, set, delete, list },     // optional; in-memory default
+ *   audit:        b.audit namespace,              // optional
+ *   permissions:  b.permissions instance,         // optional
+ *
+ * @example
+ *   var tenant = b.agent.tenant.create({});
+ *   await tenant.register("acme-clinic", { posture: ["hipaa"] });
+ *   var key = tenant.derivedKey("acme-clinic", "seal");
+ */
+function create(opts) {
+  opts = opts || {};
+  var backend = opts.backend || _inMemoryBackend();
+  if (typeof backend.get !== "function" || typeof backend.set !== "function" ||
+      typeof backend.delete !== "function" || typeof backend.list !== "function") {
+    throw new AgentTenantError("agent-tenant/bad-backend",
+      "create: backend must expose { get, set, delete, list }");
+  }
+  var auditImpl   = opts.audit || audit();
+  var permissions = opts.permissions || null;
+  var ctx = {
+    backend: backend, audit: auditImpl, permissions: permissions,
+    // Archived tenants — keys retained but no live config; restore
+    // requires explicit operator opt-in.
+    archive: new Map(),
+  };
+  return {
+    register:    function (tenantId, regOpts)      { return _register(ctx, tenantId, regOpts || {}); },
+    unregister:  function (tenantId, args)         { return _unregister(ctx, tenantId, args || {}); },
+    lookup:      function (tenantId, args)         { return _lookup(ctx, tenantId, args || {}); },
+    list:        function (args)                   { return _list(ctx, args || {}); },
+    check:       function (actor, agentTenantId)   { return _check(ctx, actor, agentTenantId); },
+    derivedKey:  function (tenantId, purpose)      { return _derivedKey(tenantId, purpose); },
+    auditFor:    function (tenantId)               { return _auditFor(ctx, tenantId); },
+    listArchived: function ()                       { var out = []; ctx.archive.forEach(function (v) { out.push({ tenantId: v.tenantId, archivedAt: v.archivedAt, policy: v.policy }); }); return out; },
+    CROSS_TENANT_ADMIN_SCOPE: CROSS_TENANT_ADMIN_SCOPE,
+    AgentTenantError: AgentTenantError,
+    _ctx: ctx,
+  };
+}
+
+// ---- Registry -------------------------------------------------------------
+
+async function _register(ctx, tenantId, regOpts) {
+  guardTenantId.validate(tenantId);
+  if (await ctx.backend.get(tenantId)) {
+    throw new AgentTenantError("agent-tenant/duplicate",
+      "register: '" + tenantId + "' already registered");
+  }
+  var row = {
+    tenantId:       tenantId,
+    posture:        Array.isArray(regOpts.posture) ? regOpts.posture.slice() :
+                      (regOpts.posture ? [regOpts.posture] : []),
+    archivePolicy:  regOpts.archivePolicy || null,
+    metadata:       regOpts.metadata || {},
+    registeredAt:   Date.now(),
+  };
+  await ctx.backend.set(tenantId, row);
+  agentAudit.safeAudit(ctx.audit, "agent.tenant.registered", regOpts.actor, {
+    tenantId: tenantId, posture: row.posture,
+  });
+  return { tenantId: tenantId, registeredAt: row.registeredAt };
+}
+
+async function _unregister(ctx, tenantId, args) {
+  guardTenantId.validate(tenantId);
+  var row = await ctx.backend.get(tenantId);
+  if (!row) {
+    throw new AgentTenantError("agent-tenant/not-found",
+      "unregister: '" + tenantId + "' not registered");
+  }
+  if (args.destroy === true) {
+    _checkDestroyPreconditions(args, tenantId);
+    await ctx.backend.delete(tenantId);
+    agentAudit.safeAudit(ctx.audit, "agent.tenant.destroyed", args.actor, {
+      tenantId: tenantId, reason: args.reason,
+      dualControlApprover: args.dualControlApprover,
+    });
+    return { tenantId: tenantId, mode: "destroyed" };
+  }
+  // Archive default — retain the key + metadata for retention-mandated
+  // restoration. Operator's compliance regime drives archivePolicy.
+  ctx.archive.set(tenantId, {
+    tenantId: tenantId, archivedAt: Date.now(),
+    policy: row.archivePolicy || "default-archive",
+    row: row,
+  });
+  await ctx.backend.delete(tenantId);
+  agentAudit.safeAudit(ctx.audit, "agent.tenant.archived", args.actor, {
+    tenantId: tenantId, policy: row.archivePolicy,
+  });
+  return { tenantId: tenantId, mode: "archived" };
+}
+
+async function _lookup(ctx, tenantId, args) {
+  guardTenantId.validate(tenantId);
+  var row = await ctx.backend.get(tenantId);
+  if (!row) return null;
+  return {
+    tenantId:      row.tenantId,
+    posture:       row.posture,
+    archivePolicy: row.archivePolicy,
+    metadata:      row.metadata,
+    registeredAt:  row.registeredAt,
+  };
+}
+
+async function _list(ctx, args) {
+  var rows = await ctx.backend.list();
+  return rows.map(function (r) {
+    return {
+      tenantId:      r.tenantId,
+      posture:       r.posture,
+      archivePolicy: r.archivePolicy,
+      registeredAt:  r.registeredAt,
+    };
+  });
+}
+
+// ---- Cross-tenant gate ----------------------------------------------------
+
+function _check(ctx, actor, agentTenantId) {
+  if (!agentTenantId) return;     // global-scoped agent, no tenant gate
+  if (!actor || typeof actor !== "object") {
+    throw new AgentTenantError("agent-tenant/no-actor",
+      "check: actor required for tenant-scoped agent");
+  }
+  // Cross-tenant admin scope — every cross-tenant call audits.
+  if (ctx.permissions && actor.roles && Array.isArray(actor.roles)) {
+    var isAdmin = ctx.permissions.check(actor, CROSS_TENANT_ADMIN_SCOPE);
+    if (isAdmin) {
+      if (actor.tenantId !== agentTenantId) {
+        agentAudit.safeAudit(ctx.audit, "agent.tenant.cross_tenant_access", actor, {
+          actorTenant: actor.tenantId || null, agentTenant: agentTenantId,
+        });
+      }
+      return;
+    }
+  }
+  if (!actor.tenantId) {
+    throw new AgentTenantError("agent-tenant/no-tenant-actor",
+      "check: actor.tenantId required for tenant-scoped agent");
+  }
+  if (actor.tenantId !== agentTenantId) {
+    agentAudit.safeAudit(ctx.audit, "agent.tenant.cross_tenant_refused", actor, {
+      actorTenant: actor.tenantId, agentTenant: agentTenantId,
+    });
+    throw new AgentTenantError("agent-tenant/cross-tenant-access-refused",
+      "actor.tenantId='" + actor.tenantId + "' does not match agentTenant='" + agentTenantId + "'");
+  }
+}
+
+// ---- Per-tenant derived key -----------------------------------------------
+
+function _derivedKey(tenantId, purpose) {
+  guardTenantId.validate(tenantId);
+  if (typeof purpose !== "string" || purpose.length === 0) {
+    throw new AgentTenantError("agent-tenant/bad-purpose",
+      "derivedKey: purpose required (e.g. 'seal' / 'audit' / 'session')");
+  }
+  // Composes b.crypto.namespaceHash for deterministic per-tenant key
+  // derivation. Cross-tenant decrypt is refused at the vault boundary
+  // because each tenant's seal-key derivation differs — even with
+  // disk access an attacker can't cross-decrypt.
+  return bCrypto.namespaceHash("agent.tenant.derive." + purpose, tenantId);
+}
+
+// ---- Per-tenant audit -----------------------------------------------------
+
+function _auditFor(ctx, tenantId) {
+  guardTenantId.validate(tenantId);
+  // Returns a wrapper that auto-tags every audit emit with the tenant
+  // id in metadata. Operator's audit pipeline filters by tenant.
+  return {
+    safeEmit: function (event) {
+      try {
+        var ev = Object.assign({}, event);
+        ev.metadata = Object.assign({}, ev.metadata || {}, { tenantId: tenantId });
+        ctx.audit.safeEmit(ev);
+      } catch (_e) { /* drop-silent */ }
+    },
+    tenantId: tenantId,
+  };
+}
+
+// ---- Destroy preconditions ------------------------------------------------
+
+function _checkDestroyPreconditions(args, tenantId) {
+  // Four preconditions for destroy — all must be present together.
+  // The framework checks the SHAPE; the operator's step-up / dual-
+  // control middleware validates the actual grants upstream.
+  if (typeof args.stepUpToken !== "string" || args.stepUpToken.length === 0) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-step-up",
+      "unregister: destroy=true requires opts.stepUpToken (operator's fresh MFA step-up grant)");
+  }
+  if (typeof args.dualControlApprover !== "string" || args.dualControlApprover.length === 0) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-dual-control",
+      "unregister: destroy=true requires opts.dualControlApprover (second admin actor id)");
+  }
+  if (typeof args.reason !== "string" || args.reason.length === 0) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-reason",
+      "unregister: destroy=true requires opts.reason (regulatory justification, e.g. 'GDPR Art. 17 #...')");
+  }
+  if (!args.actor) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-actor",
+      "unregister: destroy=true requires opts.actor");
+  }
+}
+
+// ---- In-memory backend ----------------------------------------------------
+
+function _inMemoryBackend() {
+  var map = new Map();
+  return {
+    get:    function (k)    { return Promise.resolve(map.get(k) || null); },
+    set:    function (k, v) { map.set(k, v); return Promise.resolve(); },
+    delete: function (k)    { map.delete(k); return Promise.resolve(); },
+    list:   function ()     {
+      var out = [];
+      map.forEach(function (v) { out.push(v); });
+      return Promise.resolve(out);
+    },
+  };
+}
+
+module.exports = {
+  create:                    create,
+  CROSS_TENANT_ADMIN_SCOPE:  CROSS_TENANT_ADMIN_SCOPE,
+  AgentTenantError:          AgentTenantError,
+  guards: {
+    tenantId: guardTenantId,
+  },
+};

package/lib/guard-event-bus-payload.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * @module     b.guardEventBusPayload
+ * @nav        Guards
+ * @title      Guard Event Bus Payload
+ * @order      439
+ *
+ * @intro
+ *   Payload-shape validator for `b.agent.eventBus` events. Bus owners
+ *   declare a schema per topic (flat key→type map); operators
+ *   publishing events validate against the schema before pubsub
+ *   dispatch; subscribers re-validate at delivery in case the payload
+ *   was tampered in-flight.
+ *
+ *   Per-topic schema is a flat object:
+ *
+ *     ```js
+ *     bus.registerTopic("mail.scan.malware-detected", {
+ *       schema: {
+ *         source:       "string",
+ *         confidence:   "number",
+ *         detectedAt:   "isoDateTime",
+ *         sampleId:     "string",
+ *       },
+ *       ...
+ *     });
+ *     ```
+ *
+ *   Types: `string` / `number` / `boolean` / `integer` / `isoDateTime`
+ *   / `array` / `object`. Optional fields suffix-marked with `?`
+ *   (e.g. `"reason?": "string"`).
+ *
+ *   Payload byte cap (default 64 KiB) — events are metadata, NOT bulk
+ *   data; publishers move bulk data through `b.objectStore` /
+ *   `b.mailStore` and reference IDs in events.
+ *
+ * @card
+ *   Validates `b.agent.eventBus` event payloads against per-topic
+ *   schemas. Bounded byte cap, flat-shape type checks.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardEventBusPayloadError = defineClass("GuardEventBusPayloadError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: 65536 },                                                                    // allow:raw-byte-literal — 64 KiB metadata cap
+  balanced:   { maxBytes: 262144 },                                                                   // allow:raw-byte-literal — 256 KiB
+  permissive: { maxBytes: 1048576 },                                                                  // allow:raw-byte-literal — 1 MiB
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;        // allow:regex-no-length-cap — value length-bounded by maxBytes payload cap
+
+/**
+ * @primitive b.guardEventBusPayload.validate
+ * @signature b.guardEventBusPayload.validate(payload, schema, opts?)
+ * @since     0.9.25
+ * @status    stable
+ * @related   b.agent.eventBus.create
+ *
+ * Validate an event payload against its declared schema. Returns
+ * the payload on success; throws on type mismatch / missing required
+ * field / oversize.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardEventBusPayload.validate(
+ *     { source: "1.2.3.4", confidence: 0.95 },
+ *     { source: "string", confidence: "number" }
+ *   );
+ */
+function validate(payload, schema, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new GuardEventBusPayloadError("event-bus-payload/bad-input",
+      "guardEventBusPayload.validate: payload must be a plain object");
+  }
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new GuardEventBusPayloadError("event-bus-payload/bad-schema",
+      "guardEventBusPayload.validate: schema must be a plain object");
+  }
+  var serialized;
+  try { serialized = JSON.stringify(payload); }
+  catch (e) {
+    throw new GuardEventBusPayloadError("event-bus-payload/unserializable",
+      "guardEventBusPayload.validate: payload not JSON-serializable: " +
+      (e && e.message ? e.message : String(e)));
+  }
+  if (Buffer.byteLength(serialized, "utf8") > profile.maxBytes) {
+    throw new GuardEventBusPayloadError("event-bus-payload/oversize",
+      "guardEventBusPayload.validate: " + Buffer.byteLength(serialized, "utf8") +
+      " bytes exceeds maxBytes=" + profile.maxBytes +
+      " (events are metadata; reference bulk data via objectStore IDs)");
+  }
+  // Walk schema; check each field's type + presence.
+  var schemaKeys = Object.keys(schema);
+  for (var i = 0; i < schemaKeys.length; i += 1) {
+    var key = schemaKeys[i];
+    var optional = key.charAt(key.length - 1) === "?";
+    var fieldName = optional ? key.slice(0, -1) : key;
+    var expectedType = schema[key];
+    var actual = payload[fieldName];
+    if (typeof actual === "undefined" || actual === null) {
+      if (!optional) {
+        throw new GuardEventBusPayloadError("event-bus-payload/missing-field",
+          "guardEventBusPayload.validate: required field '" + fieldName + "' missing");
+      }
+      continue;
+    }
+    _checkType(actual, expectedType, fieldName);
+  }
+  // Reject unknown keys — schema must be exhaustive.
+  var payloadKeys = Object.keys(payload);
+  for (var p = 0; p < payloadKeys.length; p += 1) {
+    var pk = payloadKeys[p];
+    if (!Object.prototype.hasOwnProperty.call(schema, pk) &&
+        !Object.prototype.hasOwnProperty.call(schema, pk + "?")) {
+      throw new GuardEventBusPayloadError("event-bus-payload/unknown-field",
+        "guardEventBusPayload.validate: unknown field '" + pk + "' not in schema");
+    }
+  }
+  return payload;
+}
+
+/**
+ * @primitive b.guardEventBusPayload.compliancePosture
+ * @signature b.guardEventBusPayload.compliancePosture(posture)
+ * @since     0.9.25
+ * @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.guardEventBusPayload.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _checkType(value, type, fieldName) {
+  if (type === "string" && typeof value !== "string") {
+    throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+      "field '" + fieldName + "' expected string, got " + typeof value);
+  }
+  if (type === "number" && (typeof value !== "number" || !isFinite(value))) {
+    throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+      "field '" + fieldName + "' expected finite number, got " +
+      (typeof value === "number" ? "non-finite number" : typeof value));
+  }
+  if (type === "boolean" && typeof value !== "boolean") {
+    throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+      "field '" + fieldName + "' expected boolean, got " + typeof value);
+  }
+  if (type === "integer" && !Number.isInteger(value)) {
+    throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+      "field '" + fieldName + "' expected integer");
+  }
+  if (type === "isoDateTime") {
+    // Length-bound the value before regex test so a hostile input can't
+    // burn regex-engine CPU. RFC 3339 ISO-8601 dateTime is bounded by
+    // ~40 chars even with fractional seconds + numeric offset; cap at 64
+    // for safety. The payload-level maxBytes cap also bounds the field.
+    if (typeof value !== "string" || value.length > 64 || !ISO_DATETIME_RE.test(value)) {             // allow:raw-byte-literal — ISO-8601 dateTime max length
+      throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+        "field '" + fieldName + "' expected ISO-8601 dateTime string");
+    }
+  }
+  if (type === "array" && !Array.isArray(value)) {
+    throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+      "field '" + fieldName + "' expected array");
+  }
+  if (type === "object") {
+    // Plain object check: rule out null first (typeof null === "object"
+    // pre-ES6 quirk), then array, then any non-object type.
+    if (value === null || Array.isArray(value) || typeof value !== "object") {
+      throw new GuardEventBusPayloadError("event-bus-payload/type-mismatch",
+        "field '" + fieldName + "' expected plain object");
+    }
+  }
+}
+
+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 GuardEventBusPayloadError("event-bus-payload/bad-profile",
+      "guardEventBusPayload: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                    validate,
+  compliancePosture:           compliancePosture,
+  PROFILES:                    PROFILES,
+  COMPLIANCE_POSTURES:         COMPLIANCE_POSTURES,
+  GuardEventBusPayloadError:   GuardEventBusPayloadError,
+  NAME:                        "eventBusPayload",
+  KIND:                        "event-bus-payload",
+};

package/lib/guard-event-bus-topic.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * @module     b.guardEventBusTopic
+ * @nav        Guards
+ * @title      Guard Event Bus Topic
+ * @order      438
+ *
+ * @intro
+ *   Topic name validator for `b.agent.eventBus.registerTopic` /
+ *   `publish` / `subscribe`. Refuses:
+ *
+ *     - dot-count < 3 (operators must use `<domain>.<source>.<event>`
+ *       shape so topic names are greppable + namespace-prefixed —
+ *       `mail.scan.malware-detected` not `malware`)
+ *     - non-ASCII (NFC + ASCII-only — operator-greppable across
+ *       audit logs + JMAP wire + cross-process)
+ *     - oversized (default 128 bytes — events are metadata, not bulk
+ *       data; long names defeat the greppability rationale)
+ *     - reserved `framework.*` prefix from operator code
+ *     - path-traversal shapes (`..` / `/` / `\` / NUL / C0)
+ *
+ * @card
+ *   Validates `b.agent.eventBus` topic names. Dot-count, ASCII,
+ *   reserved-prefix, path-traversal refusal.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardEventBusTopicError = defineClass("GuardEventBusTopicError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: 128, minDots: 2 },                                                          // allow:raw-byte-literal
+  balanced:   { maxBytes: 256, minDots: 2 },                                                          // allow:raw-byte-literal
+  permissive: { maxBytes: 512, minDots: 1 },                                                          // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var RESERVED_PREFIXES = Object.freeze(["framework.", "FRAMEWORK."]);
+
+/**
+ * @primitive b.guardEventBusTopic.validate
+ * @signature b.guardEventBusTopic.validate(name, opts?)
+ * @since     0.9.25
+ * @status    stable
+ * @related   b.agent.eventBus.create
+ *
+ * Validate an event-bus topic name. Returns the name on success;
+ * throws `GuardEventBusTopicError` on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardEventBusTopic.validate("mail.scan.malware-detected");
+ */
+function validate(name, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (typeof name !== "string" || name.length === 0) {
+    throw new GuardEventBusTopicError("event-bus-topic/bad-input",
+      "guardEventBusTopic.validate: name must be a non-empty string");
+  }
+  if (Buffer.byteLength(name, "utf8") > profile.maxBytes) {
+    throw new GuardEventBusTopicError("event-bus-topic/oversize",
+      "guardEventBusTopic.validate: name exceeds maxBytes=" + profile.maxBytes);
+  }
+  // Dot-count check — `<domain>.<source>.<event>` shape.
+  var dots = 0;
+  for (var d = 0; d < name.length; d += 1) if (name.charCodeAt(d) === 0x2E) dots += 1;                // allow:raw-byte-literal — '.' codepoint
+  if (dots < profile.minDots) {
+    throw new GuardEventBusTopicError("event-bus-topic/insufficient-dots",
+      "guardEventBusTopic.validate: name '" + name + "' has " + dots +
+      " dots; minimum " + profile.minDots + " required (use <domain>.<source>.<event> shape)");
+  }
+  // Reserved prefix refusal.
+  for (var r = 0; r < RESERVED_PREFIXES.length; r += 1) {
+    if (name.indexOf(RESERVED_PREFIXES[r]) === 0) {
+      throw new GuardEventBusTopicError("event-bus-topic/reserved-prefix",
+        "guardEventBusTopic.validate: name '" + name + "' uses reserved prefix '" +
+        RESERVED_PREFIXES[r] + "'");
+    }
+  }
+  // Path-traversal refusal.
+  if (name.indexOf("..") >= 0) {
+    throw new GuardEventBusTopicError("event-bus-topic/path-traversal",
+      "guardEventBusTopic.validate: name contains '..'");
+  }
+  // C0 / DEL / slash / non-ASCII refusal.
+  for (var i = 0; i < name.length; i += 1) {
+    var c = name.charCodeAt(i);
+    if (c > 0x7F) {                                                                                   // allow:raw-byte-literal — ASCII-only cap
+      throw new GuardEventBusTopicError("event-bus-topic/non-ascii",
+        "guardEventBusTopic.validate: name contains 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 GuardEventBusTopicError("event-bus-topic/bad-char",
+        "guardEventBusTopic.validate: forbidden char 0x" + c.toString(16) + " at offset " + i);
+    }
+  }
+  return name;
+}
+
+/**
+ * @primitive b.guardEventBusTopic.compliancePosture
+ * @signature b.guardEventBusTopic.compliancePosture(posture)
+ * @since     0.9.25
+ * @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.guardEventBusTopic.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 GuardEventBusTopicError("event-bus-topic/bad-profile",
+      "guardEventBusTopic: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                  validate,
+  compliancePosture:         compliancePosture,
+  PROFILES:                  PROFILES,
+  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
+  RESERVED_PREFIXES:         RESERVED_PREFIXES,
+  GuardEventBusTopicError:   GuardEventBusTopicError,
+  NAME:                      "eventBusTopic",
+  KIND:                      "event-bus-topic",
+};