@blamejs/core 0.9.24 → 0.9.38

package/lib/guard-envelope.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * @module     b.guardEnvelope
+ * @nav        Guards
+ * @title      Guard Envelope
+ * @order      455
+ *
+ * @intro
+ *   RFC 7489 §3.1 DMARC Identifier Alignment validator. Gates the
+ *   envelope-vs-header domain relationship at the MX listener's
+ *   end-of-DATA boundary so a sender that passes SPF / DKIM under
+ *   one domain but spoofs the user-visible `From:` header under
+ *   another is refused before the message reaches the mail-store.
+ *
+ *   ## What aligns with what
+ *
+ *   DMARC's central identifier is **RFC 5322 `From:` domain** — the
+ *   user-visible header field. Alignment requires at least one of:
+ *
+ *     - **SPF alignment** — `RFC5321.MailFrom` domain (envelope-from)
+ *       passed SPF (RFC 7208) AND matches the From-header domain.
+ *     - **DKIM alignment** — at least one DKIM signature with `d=<X>`
+ *       verified (RFC 6376) AND `<X>` matches the From-header domain.
+ *
+ *   Match semantics (RFC 7489 §3.1.1 / §3.1.2):
+ *
+ *     - **Strict (`s`)** — exact FQDN match. `From: alice@example.com`
+ *       requires the authenticated identifier to be exactly
+ *       `example.com`.
+ *     - **Relaxed (`r`)** — organizational-domain match (via Public
+ *       Suffix List). `From: alice@mail.example.com` aligns with
+ *       SPF `bounces.example.com` because both share organizational
+ *       domain `example.com`. Relaxed is the spec default per
+ *       RFC 7489 §6.2.
+ *
+ *   ## Why this primitive vs. b.mail.auth.dmarc.evaluate
+ *
+ *   `b.mail.auth.dmarc.evaluate` (existing) is the FULL DMARC policy
+ *   evaluation: parse DMARC TXT record, evaluate pct sampling,
+ *   compute final disposition (none / quarantine / reject), produce
+ *   the aggregate-report tuple. It composes the alignment check
+ *   internally.
+ *
+ *   `b.guardEnvelope.check` exposes JUST the alignment primitive so:
+ *
+ *     - The v0.9.36 MX listener can short-circuit on alignment fail
+ *       before even running the upstream DMARC TXT lookup.
+ *     - Operator middleware composing a custom anti-spoofing policy
+ *       can reuse the alignment primitive without dragging in the
+ *       full DMARC machinery (TXT parse, aggregate reporting, …).
+ *     - Tests against alignment edge cases don't have to mock the
+ *       full DMARC pipeline.
+ *
+ *   Both primitives produce the same alignment verdict for the same
+ *   input — `b.guardEnvelope` is the focused gate; `b.mail.auth.dmarc`
+ *   is the orchestrator.
+ *
+ *   ## Verdict shape
+ *
+ *   ```js
+ *   {
+ *     spf:    { aligned: bool, mode: "strict"|"relaxed", domain: string, fromDomain: string },
+ *     dkim:   [{ aligned: bool, mode, signingDomain, fromDomain }, …],
+ *     aligned: bool,      // at least one of SPF/DKIM aligned
+ *     action: "accept" | "refuse"
+ *   }
+ *   ```
+ *
+ *   When operator's profile is `strict` and neither SPF nor DKIM
+ *   aligns, action = `"refuse"`. Under `permissive`, action is
+ *   always `"accept"` (the primitive computes alignment but doesn't
+ *   gate on it — operator decides downstream from the verdict).
+ *
+ *   ## CVE / threat model
+ *
+ *   - **Display-name spoofing class** — `From: "Bank Of Foo" <a@evil.com>`
+ *     where SPF passes for `evil.com` and DKIM signs `evil.com`: this
+ *     primitive ALIGNS (both `evil.com`), so the spoof passes DMARC.
+ *     Defense lives upstream in `b.guardEmail` (display-name vs
+ *     domain mismatch detection).
+ *   - **Envelope-vs-header spoofing** (the class this PRIMITIVE
+ *     defends): `MAIL FROM:<service@aws-bounces.com>` SPF passes for
+ *     aws-bounces.com, but `From: payments@your-bank.example` —
+ *     misalignment refused under strict.
+ *   - **Same-org-different-subdomain attack** under strict: legitimate
+ *     mail from `bounces.example.com` to alignment-strict `example.com`
+ *     is REFUSED — operator opts to relaxed for cross-subdomain mail.
+ *   - **Public-suffix confusion** — relaxed mode uses
+ *     `b.publicSuffix.organizationalDomain` which composes the
+ *     vendored PSL; an attacker can't claim `co.uk` as their org
+ *     domain because PSL classifies it as a public suffix.
+ *
+ * @card
+ *   RFC 7489 §3.1 DMARC Identifier Alignment validator. Strict / relaxed match between RFC 5322 From-header domain and SPF MailFrom + DKIM d= identifiers. Composes b.publicSuffix.organizationalDomain for relaxed mode. Refuses envelope-vs-header spoofs at the MX boundary before mail-store touch.
+ */
+
+var { defineClass }    = require("./framework-error");
+var lazyRequire        = require("./lazy-require");
+var publicSuffix       = require("./public-suffix");
+
+var audit              = lazyRequire(function () { return require("./audit"); });
+
+var GuardEnvelopeError = defineClass("GuardEnvelopeError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  // Strict: gate refuses on alignment fail. Default for HIPAA / PCI /
+  // GDPR / SOC2 / banking / regulated mail.
+  strict:     { gateOnFailure: true,  defaultMode: "relaxed" },
+  // Balanced: gate refuses on alignment fail but defaults to relaxed
+  // mode (RFC 7489 §6.2 default). For most operator deployments.
+  balanced:   { gateOnFailure: true,  defaultMode: "relaxed" },
+  // Permissive: compute alignment but always accept; operator
+  // pipelines downstream consume the verdict for score-tagging.
+  permissive: { gateOnFailure: false, defaultMode: "relaxed" },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardEnvelope.check
+ * @signature b.guardEnvelope.check(ctx, opts?)
+ * @since     0.9.36
+ * @status    stable
+ * @related   b.publicSuffix.organizationalDomain, b.guardEmail.validateMessage
+ *
+ * Evaluate DMARC Identifier Alignment between the user-visible
+ * `From:` header domain and the authenticated identifiers (SPF
+ * MailFrom + DKIM d=). Returns the alignment verdict.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   spfMode:   "strict" | "relaxed",                      // per-call override (RFC 7489 §6.2)
+ *   dkimMode:  "strict" | "relaxed",                      // per-call override
+ *   audit:     b.audit namespace,
+ *
+ * @example
+ *   var v = b.guardEnvelope.check({
+ *     fromHeaderDomain: "example.com",
+ *     spfResult:        { result: "pass", domain: "bounces.example.com" },
+ *     dkimResults:      [{ result: "pass", signingDomain: "example.com" }],
+ *   });
+ *   if (v.action === "refuse") return reply(550, "5.7.1 DMARC alignment fail");
+ */
+function check(ctx, opts) {
+  opts = opts || {};
+  var profile = opts.profile || (opts.posture && COMPLIANCE_POSTURES[opts.posture]) || DEFAULT_PROFILE;
+  if (!PROFILES[profile]) {
+    throw new GuardEnvelopeError("guard-envelope/bad-profile",
+      "check: unknown profile '" + profile + "'");
+  }
+  var caps = PROFILES[profile];
+  var spfMode  = opts.spfMode  || caps.defaultMode;
+  var dkimMode = opts.dkimMode || caps.defaultMode;
+  if (spfMode !== "strict" && spfMode !== "relaxed") {
+    throw new GuardEnvelopeError("guard-envelope/bad-mode",
+      "check: spfMode must be 'strict' or 'relaxed'");
+  }
+  if (dkimMode !== "strict" && dkimMode !== "relaxed") {
+    throw new GuardEnvelopeError("guard-envelope/bad-mode",
+      "check: dkimMode must be 'strict' or 'relaxed'");
+  }
+  var auditImpl = opts.audit || audit();
+
+  if (!ctx || typeof ctx !== "object") {
+    throw new GuardEnvelopeError("guard-envelope/bad-input",
+      "check: ctx must be a plain object");
+  }
+  if (typeof ctx.fromHeaderDomain !== "string" || ctx.fromHeaderDomain.length === 0) {
+    throw new GuardEnvelopeError("guard-envelope/bad-input",
+      "check: ctx.fromHeaderDomain must be a non-empty string");
+  }
+  var fromDomain = ctx.fromHeaderDomain.toLowerCase();
+
+  // SPF alignment.
+  var spfVerdict = _spfVerdict(ctx.spfResult, fromDomain, spfMode);
+
+  // DKIM alignment — one entry per signature.
+  var dkimResults = Array.isArray(ctx.dkimResults) ? ctx.dkimResults : [];
+  var dkimVerdicts = dkimResults.map(function (r) {
+    return _dkimVerdict(r, fromDomain, dkimMode);
+  });
+
+  var anyAligned = spfVerdict.aligned || dkimVerdicts.some(function (d) { return d.aligned; });
+  var action = anyAligned || !caps.gateOnFailure ? "accept" : "refuse";
+
+  _emitAudit(auditImpl, anyAligned ? "guard.envelope.aligned" : "guard.envelope.misaligned", {
+    fromDomain:  fromDomain,
+    spfAligned:  spfVerdict.aligned,
+    dkimAligned: dkimVerdicts.some(function (d) { return d.aligned; }),
+    profile:     profile,
+  });
+
+  return {
+    spf:     spfVerdict,
+    dkim:    dkimVerdicts,
+    aligned: anyAligned,
+    action:  action,
+  };
+}
+
+/**
+ * @primitive b.guardEnvelope.compliancePosture
+ * @signature b.guardEnvelope.compliancePosture(posture)
+ * @since     0.9.36
+ * @status    stable
+ *
+ * Return the effective profile name for a compliance posture, or
+ * `null` for unknown posture names.
+ *
+ * @example
+ *   b.guardEnvelope.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _spfVerdict(spfResult, fromDomain, mode) {
+  var verdict = {
+    aligned:    false,
+    mode:       mode,
+    domain:     null,
+    fromDomain: fromDomain,
+    spfPass:    false,
+  };
+  if (!spfResult || typeof spfResult !== "object") return verdict;
+  verdict.spfPass = spfResult.result === "pass";
+  if (typeof spfResult.domain !== "string" || spfResult.domain.length === 0) return verdict;
+  verdict.domain = spfResult.domain.toLowerCase();
+  if (!verdict.spfPass) return verdict;
+  verdict.aligned = _domainAligned(verdict.domain, fromDomain, mode);
+  return verdict;
+}
+
+function _dkimVerdict(dkimResult, fromDomain, mode) {
+  var verdict = {
+    aligned:       false,
+    mode:          mode,
+    signingDomain: null,
+    fromDomain:    fromDomain,
+    dkimPass:      false,
+  };
+  if (!dkimResult || typeof dkimResult !== "object") return verdict;
+  verdict.dkimPass = dkimResult.result === "pass";
+  if (typeof dkimResult.signingDomain !== "string" || dkimResult.signingDomain.length === 0) return verdict;
+  verdict.signingDomain = dkimResult.signingDomain.toLowerCase();
+  if (!verdict.dkimPass) return verdict;
+  verdict.aligned = _domainAligned(verdict.signingDomain, fromDomain, mode);
+  return verdict;
+}
+
+function _domainAligned(authDomain, fromDomain, mode) {
+  if (mode === "strict") {
+    return authDomain === fromDomain;
+  }
+  // Relaxed — organizational-domain match via PSL.
+  var orgAuth, orgFrom;
+  try {
+    orgAuth = publicSuffix.organizationalDomain(authDomain);
+    orgFrom = publicSuffix.organizationalDomain(fromDomain);
+  } catch (_e) { return false; }
+  if (!orgAuth || !orgFrom) return false;
+  return orgAuth === orgFrom;
+}
+
+function _emitAudit(auditImpl, action, metadata) {
+  try {
+    if (auditImpl && typeof auditImpl.safeEmit === "function") {
+      auditImpl.safeEmit({
+        action:   action,
+        outcome:  "success",
+        metadata: metadata,
+      });
+    }
+  } catch (_e) { /* drop-silent — audit failure must not block accept loop */ }
+}
+
+module.exports = {
+  check:                   check,
+  compliancePosture:       compliancePosture,
+  PROFILES:                PROFILES,
+  COMPLIANCE_POSTURES:     COMPLIANCE_POSTURES,
+  GuardEnvelopeError:      GuardEnvelopeError,
+  NAME:                    "envelope",
+  KIND:                    "envelope-alignment",
+  _domainAligned:          _domainAligned,
+};

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