@blamejs/core 0.8.43 → 0.8.49

package/lib/audit.js

@@ -1,39 +1,52 @@
 "use strict";
 /**
- * Audit log — tamper-evident, append-only record of every privileged action.
- *
- * audit_log table is baked into db.js's schema runner — apps cannot opt out.
- * Every row is hash-chained (lib/audit-chain.js); the chain is verified at
- * boot in db.init(); a chain break refuses-to-boot per the compliance stance.
- *
- * Action namespaces:
- *   - Framework owns: 'auth.*', 'system.*', 'audit.*', 'consent.*', 'subject.*'
- *   - Apps register their own via audit.registerNamespace('orders'), then
- *     can record 'orders.created', 'orders.shipped', etc.
- *   - Unregistered namespaces are rejected — prevents typos becoming silent
- *     unobservable events.
- *
- * Hash chain:
- *   - rowHash is computed over the *sealed* form of the row + the nonce.
- *     The sealed form is what's stored on disk; verification recomputes
- *     directly from disk without unsealing anything (faster + lets auditors
- *     verify integrity even without the vault key).
- *
- * Public API:
- *   audit.registerNamespace(name)
- *   audit.record({ actor, action, resource, outcome, reason, metadata, requestId }) → row
- *   audit.query(criteria) → rows  [auto-self-logs an 'audit.read' event before returning]
- *   audit.verify(opts?) → { ok, rowsVerified, breakAt? }
- *   audit.beginTrace() → traceId (32 hex chars)
- *
- * Conventions for `metadata` (apps SHOULD follow these keys for cross-app
- * tooling and RoPA correlation; framework's own subject.* events do):
- *   traceId        — cross-request correlation; same value across linked events
- *   parentEventId  — immediate parent event in the causation chain
- *   before         — state before a change (object), for change events
- *   after          — state after the change
- *   evidenceRef    — pointer to evidence (signed PDF hash, ticket URL, etc.)
- *   App-defined keys are also welcome; don't shadow these reserved ones.
+ * @module b.audit
+ * @featured true
+ * @nav    Observability
+ * @title  Audit
+ *
+ * @intro
+ *   Tamper-evident, append-only record of every privileged action — the
+ *   forensic surface every compliance posture (HIPAA / PCI-DSS / SOC 2 /
+ *   GDPR / SOX / DORA) bottoms out on. The `audit_log` table is baked
+ *   into db.js's schema runner so apps cannot opt out; the chain is
+ *   verified at boot and a break refuses-to-boot.
+ *
+ *   Hash chain: every row carries `prevHash` + `rowHash` computed over
+ *   the SEALED form of the row plus a nonce. Verification recomputes
+ *   directly from disk without unsealing — auditors can confirm
+ *   integrity without holding the vault key. Periodic SLH-DSA-SHAKE-256f
+ *   checkpoints (post-quantum signatures over the chain tip) anchor the
+ *   chain to off-line evidence; tampering that recomputes hashes still
+ *   fails checkpoint verification.
+ *
+ *   Namespaces: framework owns `auth.*` / `system.*` / `audit.*` /
+ *   `consent.*` / `subject.*`; apps call `registerNamespace("orders")`
+ *   at boot before emitting `orders.created`. Unregistered namespaces
+ *   are rejected so typos don't become silent unobservable events.
+ *
+ *   Action shape — the 5W form: WHO (`actor.userId` / sessionId / ip /
+ *   userAgent), WHAT (`action` = "namespace.verb[.qualifier]"), WHEN
+ *   (`recordedAt` ms epoch + monotonic counter), WHERE (`resource.kind`
+ *   / id), HOW (`outcome` ∈ {success, failure, denied} + `reason` +
+ *   `metadata`).
+ *
+ *   Two emit paths:
+ *     - `record(event)` — async, throws on bad input, awaits the chain
+ *       append. Use when the caller needs durability before continuing.
+ *     - `emit(event)` / `safeEmit(event)` — synchronous fire-and-forget;
+ *       events buffer in an AsyncHandler and drain serially through
+ *       record(). `safeEmit` is drop-silent on malformed input by
+ *       design: it runs in request hot paths where throwing would crash
+ *       the request that triggered the audit attempt.
+ *
+ *   Reserved metadata keys: `traceId` (cross-request correlation,
+ *   `beginTrace()` mints), `parentEventId`, `before` / `after` (state
+ *   diff for change events), `evidenceRef` (pointer to signed PDF /
+ *   ticket).
+ *
+ * @card
+ *   Tamper-evident, append-only record of every privileged action — the forensic surface every compliance posture (HIPAA / PCI-DSS / SOC 2 / GDPR / SOX / DORA) bottoms out on.
  */
 var auditChain = require("./audit-chain");
 var auditSign = require("./audit-sign");
@@ -42,6 +55,7 @@ var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var { generateToken } = require("./crypto");
 var cryptoField = require("./crypto-field");
+var dbRoleContext = require("./db-role-context");
 var handlers = require("./handlers");
 var { boot } = require("./log");
 var redact = require("./redact");
@@ -49,7 +63,7 @@ var safeAsync = require("./safe-async");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var observability = require("./observability");
-var { ClusterError } = require("./framework-error");
+var { AuditSegregationError, ClusterError } = require("./framework-error");
 
 var log = boot("audit");
 
@@ -226,6 +240,7 @@ var FRAMEWORK_NAMESPACES = [
   "inbox",      // b.inbox (inbox.received / handled / handle_failed / swept)
   "flag",       // b.flag (flag.evaluated / flag.evaluation.error / flag.cache.bust)
   "permissions", // b.permissions
+  "pqcagent",   // b.pqcAgent (pqcagent.operator_group.accepted)
   "restore",    // b.restore
   "retention",  // b.retention (retention.rule.declared / sweep.started / row.processed / sweep.completed / sweep.failed)
   "scheduler",  // b.scheduler (lifecycle: scheduler.start / scheduler.stop;
@@ -252,6 +267,27 @@ var FRAMEWORK_NAMESPACES = [
   "csp",        // b.middleware.cspReport (csp.violation)
   "resourceaccesslock", // b.resourceAccessLock (resourceaccesslock.mode_changed / refused)
   "process",    // b.processSpawn (process.spawn / process.spawn.failed)
+  "keychain",   // b.keychain (keychain.stored / keychain.retrieved / keychain.removed)
+  "fda21cfr11", // b.fda21cfr11 (signature.created / verified / gxp.assert_failed / audit.refused / posture.installed)
+  "ddl",        // b.ddlChangeControl (ddl.change.proposed / approved / rejected / applied / apply_refused)
+  "migrations", // b.migrations + b.externalDb.migrate (migrations.history.appended / verified / tampered)
+  "dlp",        // b.redact.installOutboundDlp (dlp.outbound.refused / redacted / scanned / installed)
+  "session",    // b.sessionDeviceBinding (session.device.bound / drift / refused)
+  "sandbox",    // b.sandbox (sandbox.run / sandbox.run.refused — operator-supplied transform isolation)
+  "safeurl",    // b.safeUrl.parse (safeurl.idn_homograph.refused — UTS #39 mixed-script host-label refusal)
+  "http",       // b.middleware.bodyParser (http.chunked.malformed.refused — RFC 9112 §7.1 chunked-decode failure with Connection: close) // allow:raw-byte-literal — RFC number in prose
+  "cryptofield", // b.cryptoField.eraseRow (cryptofield.vacuum.skipped — F-RTBF-2 vacuum-after-erase signal when DB not initialized at erase time)
+  "acme",       // b.acme (acme.account.registered / order.* / cert.issued / cert.renewed / cert.renew.skipped — RFC 8555 + RFC 9773 ARI workflow)
+  "tls",        // b.router 0-RTT posture (tls.0rtt.refused / tls.0rtt.replayed) — RFC 8446 §8 anti-replay surface // allow:raw-byte-literal — RFC number in prose
+  "workerpool", // b.workerPool (workerpool.created / terminated / task.completed / task.failed / task.timeout / spawn.failed — generic worker_threads pool)
+  "jwt",        // b.auth.jwt-external (jwt.jwe.refused — RFC 7516 5-segment JWE refusal)
+  "dr",         // b.drRunbook (dr.runbook.emitted)
+  "guardfilename", // b.guardFilename (guardfilename.sanitize.stripped)
+  "legalhold",  // b.legalHold (legalhold.placed / released / place_rejected / release_rejected)
+  "networkheartbeat", // b.network.heartbeat.passive (networkheartbeat.passive.timeout)
+  "router",     // b.router (router.redirect.cross_origin.refused / allowed)
+  "http2",      // b.router h2 GOAWAY tracker (http2.window_update.refused — CVE-2026-21714)
+  "tenant",     // b.tenantQuota (tenant.quota.exceeded / tenant.budget.exceeded / tenant.crossover)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 
@@ -293,6 +329,25 @@ var _chainWriter = chainWriter.create({
 
 // ---- Public API ----
 
+/**
+ * @primitive b.audit.registerNamespace
+ * @signature b.audit.registerNamespace(name)
+ * @since     0.1.0
+ * @related   b.audit.record, b.audit.safeEmit
+ *
+ * Register an action namespace at app bootstrap so `record()` / `emit()`
+ * accept events under it. Names must match `[a-z][a-z0-9_]*`. Calling
+ * twice is a no-op. Framework namespaces (auth / system / audit /
+ * consent / subject + every per-primitive namespace) are pre-registered.
+ *
+ * @example
+ *   b.audit.registerNamespace("orders");
+ *   b.audit.safeEmit({
+ *     action:  "orders.shipped",
+ *     actor:   { userId: "u-42" },
+ *     outcome: "success",
+ *   });
+ */
 function registerNamespace(name) {
   if (typeof name !== "string" || !/^[a-z][a-z0-9_]*$/.test(name)) {
     throw new Error("audit namespace must match [a-z][a-z0-9_]* — got: " + name);
@@ -316,6 +371,42 @@ function _validateAction(action) {
   }
 }
 
+/**
+ * @primitive b.audit.record
+ * @signature b.audit.record(event)
+ * @since     0.1.0
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.audit.safeEmit, b.audit.emit, b.audit.flush
+ *
+ * Append one event to the audit chain and await durability. Throws on a
+ * bad action shape, an unregistered namespace, or an outcome outside
+ * {success, failure, denied}. The chain-writer serializes the actual
+ * INSERT under a mutex so concurrent record() calls produce a strictly
+ * monotonic counter and a valid prevHash → rowHash chain.
+ *
+ * Use record() when the caller must know the row landed before
+ * continuing (consent grants, break-glass unseals, change-control
+ * approvals). For request hot paths where best-effort is acceptable,
+ * prefer safeEmit().
+ *
+ * @opts
+ *   actor:     { userId, ip, userAgent, sessionId },
+ *   action:    "namespace.verb[.qualifier]",
+ *   resource:  { kind, id },
+ *   outcome:   "success" | "failure" | "denied",
+ *   reason:    string,
+ *   metadata:  object,             // serialized to JSON
+ *   requestId: string,
+ *
+ * @example
+ *   await b.audit.record({
+ *     actor:    { userId: "u-42", ip: "10.0.0.1" },
+ *     action:   "consent.granted",
+ *     resource: { kind: "purpose", id: "marketing" },
+ *     outcome:  "success",
+ *     metadata: { traceId: b.audit.beginTrace() },
+ *   });
+ */
 async function record(event) {
   if (!event || typeof event !== "object") {
     throw new Error("audit.record requires an event object");
@@ -364,6 +455,39 @@ async function record(event) {
 // (otherwise legitimate audit auditing produces a Russell-set spiral).
 var _selfLogging = false;
 
+/**
+ * @primitive b.audit.query
+ * @signature b.audit.query(criteria)
+ * @since     0.1.0
+ * @compliance pci-dss, soc2
+ * @related   b.audit.verify, b.audit.verifyCheckpoints
+ *
+ * Read audit rows matching the criteria, returning unsealed rows for
+ * the auditor's view. Every call self-logs an `audit.read` event before
+ * returning (PCI DSS 10.2.3) so exfiltration attempts are forensically
+ * visible; recursion is guarded so the self-log doesn't trigger its own
+ * self-log. Plain-field criteria translate into derived-hash equality
+ * where the column is sealed.
+ *
+ * @opts
+ *   from:         number | Date | string,   // recordedAt >=
+ *   to:           number | Date | string,   // recordedAt <=
+ *   actorUserId:  string,
+ *   resourceId:   string,
+ *   action:       string,
+ *   resourceKind: string,
+ *   outcome:      "success" | "failure" | "denied",
+ *   limit:        number,
+ *   offset:       number,
+ *
+ * @example
+ *   var rows = await b.audit.query({
+ *     action: "consent.granted",
+ *     from:   Date.now() - 86400000,
+ *     limit:  100,
+ *   });
+ *   rows.length;   // → 42
+ */
 async function query(criteria) {
   criteria = criteria || {};
   if (!_selfLogging && criteria.action !== "audit.read") {
@@ -462,6 +586,30 @@ function _redactCriteria(c) {
 // bytes hex-encoded → 32 chars). Routed through C.BYTES so the byte
 // count has a single source of truth.
 var TRACE_ID_BYTES = C.BYTES.bytes(16);
+/**
+ * @primitive b.audit.beginTrace
+ * @signature b.audit.beginTrace()
+ * @since     0.1.0
+ * @related   b.audit.record, b.audit.query
+ *
+ * Mint a fresh 32-hex-char trace id apps thread through linked events
+ * via `metadata.traceId`. Width matches the W3C traceparent trace-id
+ * format (16 random bytes hex-encoded), so the id is interoperable with
+ * OpenTelemetry / W3C Trace Context propagation.
+ *
+ * @example
+ *   var traceId = b.audit.beginTrace();
+ *   await b.audit.record({
+ *     action:   "subject.export.requested",
+ *     outcome:  "success",
+ *     metadata: { traceId: traceId },
+ *   });
+ *   await b.audit.record({
+ *     action:   "subject.export.delivered",
+ *     outcome:  "success",
+ *     metadata: { traceId: traceId, parentEventId: "..." },
+ *   });
+ */
 function beginTrace() {
   return generateToken(TRACE_ID_BYTES);
 }
@@ -491,6 +639,32 @@ function _checkpointPayload(atMonotonicCounter, atRowHash, createdAt) {
 // opts:
 //   skipIfUnchanged: bool — return null without inserting if the chain tip
 //                           hasn't advanced since the most recent checkpoint
+/**
+ * @primitive b.audit.checkpoint
+ * @signature b.audit.checkpoint(opts)
+ * @since     0.4.0
+ * @compliance soc2, pci-dss, sox-404
+ * @related   b.audit.verifyCheckpoints, b.audit.verify
+ *
+ * Anchor the current chain tip with a fresh ML-DSA-87 (post-quantum)
+ * signature. Inserts a row into `audit_checkpoints` and updates the
+ * boot-time rollback-detection sidecar (single-node) or the cluster
+ * audit-tip row (cluster mode, fencing-token guarded). Cluster mode
+ * requires the caller hold leader status — `cluster.requireLeader()`
+ * throws otherwise.
+ *
+ * Returns the inserted checkpoint row, or `null` when the chain is
+ * empty / `skipIfUnchanged` and the tip hasn't advanced.
+ *
+ * @opts
+ *   skipIfUnchanged: boolean,   // null-return when tip didn't move
+ *
+ * @example
+ *   var ckpt = await b.audit.checkpoint({ skipIfUnchanged: true });
+ *   if (ckpt) {
+ *     console.log("anchored at counter", ckpt.atMonotonicCounter);
+ *   }
+ */
 async function checkpoint(opts) {
   cluster.requireLeader();
   opts = opts || {};
@@ -571,6 +745,32 @@ async function checkpoint(opts) {
 // audit_log row at atMonotonicCounter still has the recorded rowHash.
 //
 // Returns { ok, checkpointsVerified, breakAt? }.
+/**
+ * @primitive b.audit.verifyCheckpoints
+ * @signature b.audit.verifyCheckpoints()
+ * @since     0.4.0
+ * @compliance soc2, pci-dss, sox-404
+ * @related   b.audit.checkpoint, b.audit.verify
+ *
+ * Walk every checkpoint and verify (a) the public-key fingerprint
+ * matches the current signing key, (b) the ML-DSA-87 signature over the
+ * payload still verifies, (c) the audit_log row at the anchored counter
+ * still has the recorded rowHash. Catches tampering that recomputed
+ * chain hashes after holding the vault key, because the off-chain
+ * signature anchor is unforgeable without the signing key.
+ *
+ * Returns `{ ok: true, checkpointsVerified }` on success, or
+ * `{ ok: false, checkpointsVerified, breakAt, checkpointId, reason }`
+ * at the first break.
+ *
+ * @example
+ *   var result = await b.audit.verifyCheckpoints();
+ *   if (!result.ok) {
+ *     throw new Error("audit checkpoint break at " + result.breakAt +
+ *       ": " + result.reason);
+ *   }
+ *   result.checkpointsVerified;   // → 17
+ */
 async function verifyCheckpoints() {
   var rows = await _readAllCheckpointsAsc();
 
@@ -648,6 +848,33 @@ function _toMs(value) {
 
 // ---- Verify ----
 
+/**
+ * @primitive b.audit.verify
+ * @signature b.audit.verify(opts)
+ * @since     0.1.0
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.audit.verifyCheckpoints, b.audit.query
+ *
+ * Walk every audit_log row in monotonic order and recompute each
+ * `rowHash` against the canonicalized columns + nonce, confirming each
+ * row's `prevHash` matches the previous row's `rowHash`. Catches any
+ * insert / delete / mutation between checkpoints. Runs at boot in
+ * `db.init()`; operators also call it from a periodic job.
+ *
+ * Returns `{ ok: true, rowsVerified }` on a clean chain, or
+ * `{ ok: false, rowsVerified, breakAt, reason }` at the first break.
+ *
+ * @opts
+ *   from:  number,   // start counter (incremental verify after a known-good checkpoint)
+ *   to:    number,   // end counter
+ *
+ * @example
+ *   var result = await b.audit.verify();
+ *   if (!result.ok) {
+ *     console.error("audit chain break at row", result.breakAt);
+ *     process.exit(1);
+ *   }
+ */
 async function verify(opts) {
   // verifyChain just needs an executeAll; route through the same
   // resilience-wrapped reader the rest of audit uses.
@@ -752,6 +979,28 @@ function _ensureHandler() {
   return _auditHandler;
 }
 
+/**
+ * @primitive b.audit.emit
+ * @signature b.audit.emit(event)
+ * @since     0.1.0
+ * @related   b.audit.safeEmit, b.audit.record, b.audit.flush
+ *
+ * Synchronous fire-and-forget emit — events buffer in an AsyncHandler
+ * and drain serially through `record()`. Returns immediately; never
+ * returns a Promise. Unlike `safeEmit()`, emit() does NOT normalize
+ * outcome / action and does NOT redact metadata — callers pass already-
+ * shaped events. Most call sites should prefer `safeEmit` instead;
+ * `emit` is the lower-level surface the framework's own bound-actor
+ * wrapper uses.
+ *
+ * @example
+ *   b.audit.emit({
+ *     actor:    { userId: "u-42" },
+ *     action:   "system.config.reloaded",
+ *     outcome:  "success",
+ *     metadata: { source: "SIGHUP" },
+ *   });
+ */
 function emit(event) {
   _ensureHandler().emit(event);
 }
@@ -818,6 +1067,43 @@ function _normalizeAction(action) {
 // record() and await it with their own error handling. The audit chain
 // itself is verified at boot, so a silently dropped row shows up in the
 // next chain integrity sweep.
+/**
+ * @primitive b.audit.safeEmit
+ * @signature b.audit.safeEmit(event)
+ * @since     0.1.0
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.audit.emit, b.audit.record, b.audit.flush
+ *
+ * Hot-path-safe fire-and-forget audit emit. Drop-silent on malformed
+ * input by design — safeEmit runs from request middleware, log-stream
+ * hooks, and finalizers where throwing on a missing `action` would
+ * crash the request that triggered the audit attempt. Operators who
+ * need durability guarantees call `record()` and await it.
+ *
+ * Built-in normalization: action segments with hyphens become
+ * underscores ("biometric-id" → "biometric_id"); outcome aliases
+ * collapse to {success, failure, denied} ("ok" → "success", "error" →
+ * "failure", "refused" → "denied"). Actor / reason / metadata pass
+ * through `b.redact.redact()` so connection strings, JWTs, PEM blocks,
+ * AWS keys, and SSNs are scrubbed before they reach the chain.
+ *
+ * @opts
+ *   actor:     { userId, ip, userAgent, sessionId },
+ *   action:    "namespace.verb[.qualifier]",
+ *   resource:  { kind, id },
+ *   outcome:   string,            // normalized
+ *   reason:    string,            // redacted
+ *   metadata:  object,            // redacted
+ *   requestId: string,
+ *
+ * @example
+ *   b.audit.safeEmit({
+ *     actor:    { userId: req.user && req.user.id },
+ *     action:   "auth.login",
+ *     outcome:  "success",
+ *     metadata: { traceId: req.traceId, ua: req.headers["user-agent"] },
+ *   });
+ */
 function safeEmit(event) {
   if (!event || typeof event !== "object") return;
   if (typeof event.action !== "string") return;  // can't emit without an action
@@ -851,16 +1137,351 @@ function safeEmit(event) {
   } catch (_e) { /* audit best-effort — never break the caller */ }
 }
 
+/**
+ * @primitive b.audit.flush
+ * @signature b.audit.flush()
+ * @since     0.1.0
+ * @related   b.audit.emit, b.audit.safeEmit
+ *
+ * Drain the AsyncHandler buffer — every queued `emit()` / `safeEmit()`
+ * lands in the audit chain before the returned Promise resolves. Tests,
+ * graceful shutdown, and any code that needs to read audit_log
+ * immediately after emitting awaits flush().
+ *
+ * @example
+ *   b.audit.safeEmit({ action: "system.shutdown.requested", outcome: "success" });
+ *   await b.audit.flush();
+ *   var rows = await b.audit.query({ action: "system.shutdown.requested" });
+ *   rows.length;   // → 1
+ */
 async function flush() {
   if (!_auditHandler) return;
   await _auditHandler.drain();
 }
 
+// ---- SOX §404 / SOC 2 CC1.3 — actor-binding + segregation of duties ----
+//
+// Anyone with write access to the audit_log table can INSERT a row
+// claiming any actor identity. The framework already records actor
+// from the request context, but a privileged caller (operator script,
+// migration runner, anyone with the externalDb credentials) can claim
+// a different actor.
+//
+// bindActor(actorId, opts) returns a wrapper around audit.safeEmit /
+// audit.record that refuses any event whose actor.userId mismatches
+// the bound identity OR the SQL-bound role (when db-role-context is
+// active).
+//
+// SQL-side enforcement lives in lib/cluster-storage.js's framework-
+// schema generator — see generateActorBindingTriggerSql() below for
+// the Postgres trigger DDL. Operators apply that DDL in a migration
+// when they boot under sox-404 / soc2 / pci-dss posture so a non-
+// framework writer can't INSERT rows under a different role.
+function _checkActorBinding(actorId, eventActorId, opts) {
+  if (!actorId) return true;     // unbound — no enforcement
+  if (!eventActorId) {
+    return { ok: false, reason: "event missing actor.userId — refused under bound emit" };
+  }
+  if (eventActorId !== actorId) {
+    return { ok: false,
+      reason: "actor mismatch: bound='" + actorId + "', event='" + eventActorId + "'" };
+  }
+  // db-role-context check — when the caller is inside a runWithRole
+  // scope, the SQL-bound role and the bound actor must agree (subject
+  // to the operator-supplied `roleEquivalent` mapping).
+  if (opts && typeof opts.roleEquivalent === "function") {
+    var role = dbRoleContext.getRole();
+    if (role && !opts.roleEquivalent(actorId, role)) {
+      return { ok: false,
+        reason: "db-role mismatch: bound actor '" + actorId +
+          "' is not equivalent to SQL role '" + role + "'" };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * @primitive b.audit.bindActor
+ * @signature b.audit.bindActor(actorId, opts)
+ * @since     0.7.0
+ * @compliance sox-404, soc2
+ * @related   b.audit.assertSegregation, b.audit.generateActorBindingTriggerSql
+ *
+ * Wrap `safeEmit` / `record` so any event whose `actor.userId` doesn't
+ * match the bound id is refused (and an `audit.actor_binding.violation`
+ * event is recorded under the bound actor). When `opts.roleEquivalent`
+ * is provided and the caller is inside a `db-role-context.runWithRole`
+ * scope, the SQL-bound role and bound actor must agree per the
+ * operator-supplied mapping.
+ *
+ * Pair with `generateActorBindingTriggerSql()` for SQL-side enforcement
+ * — application-layer binding catches typos; the trigger catches
+ * privileged callers bypassing the framework.
+ *
+ * @opts
+ *   roleEquivalent: function (actorId, sqlRole) -> boolean,
+ *
+ * @example
+ *   var bound = b.audit.bindActor("u-42");
+ *   bound.safeEmit({
+ *     actor:   { userId: "u-42" },
+ *     action:  "orders.shipped",
+ *     outcome: "success",
+ *   });
+ *   bound.safeEmit({
+ *     actor:   { userId: "u-other" },
+ *     action:  "orders.shipped",
+ *     outcome: "success",
+ *   });
+ *   // → drops + records "audit.actor_binding.violation" under u-42
+ */
+function bindActor(actorId, opts) {
+  if (typeof actorId !== "string" || actorId.length === 0) {
+    throw new AuditSegregationError("audit/bind-actor-missing",
+      "audit.bindActor: actorId must be a non-empty string");
+  }
+  opts = opts || {};
+  function _violationEmit(eventAction, reason) {
+    try {
+      // Surface via the un-bound _ensureHandler so the violation row
+      // lands in the chain regardless of bind state.
+      _ensureHandler().emit({
+        action:   "audit.actor_binding.violation",
+        outcome:  "denied",
+        actor:    { userId: actorId },
+        metadata: { attemptedAction: eventAction, reason: reason },
+      });
+    } catch (_e) { /* drop-silent — never break the caller */ }
+  }
+  function boundSafeEmit(event) {
+    var rv = _checkActorBinding(actorId,
+      event && event.actor && event.actor.userId, opts);
+    if (rv !== true && !rv.ok) {
+      _violationEmit(event && event.action, rv.reason);
+      return;
+    }
+    safeEmit(event);
+  }
+  async function boundRecord(event) {
+    var rv = _checkActorBinding(actorId,
+      event && event.actor && event.actor.userId, opts);
+    if (rv !== true && !rv.ok) {
+      _violationEmit(event && event.action, rv.reason);
+      throw new AuditSegregationError("audit/actor-binding-violation",
+        "audit.bindActor.record: " + rv.reason);
+    }
+    return await record(event);
+  }
+  return {
+    actorId:   actorId,
+    safeEmit:  boundSafeEmit,
+    record:    boundRecord,
+  };
+}
+
+// Trigger-SQL generator — operators apply the returned DDL via
+// b.externalDb.migrate so the database itself refuses INSERTs into
+// _blamejs_audit_log where the row's stored actor mismatches the
+// SQL session's current_user.
+//
+// opts.column — defaults to "actorUserId"; operators with a separate
+//   role mapping table pass an explicit column name.
+// opts.roleMappingFn — Postgres function name that maps the row's
+//   actorUserId to the expected SQL role; defaults to identity match
+//   (current_user must equal the actorUserId).
+// opts.tableName — defaults to "_blamejs_audit_log".
+// opts.allowRoles — array of roles allowed to insert ANY actor (e.g.
+//   the framework's own service account); skipped checks for those
+//   roles.
+//
+// Returns { up: ddl, down: ddl } so the migration runner can install +
+// uninstall.
+/**
+ * @primitive b.audit.generateActorBindingTriggerSql
+ * @signature b.audit.generateActorBindingTriggerSql(opts)
+ * @since     0.7.0
+ * @compliance sox-404, soc2
+ * @related   b.audit.bindActor, b.audit.assertSegregation
+ *
+ * Emit Postgres trigger DDL that refuses INSERTs into the audit_log
+ * table whose stored `actorUserId` column doesn't match the SQL
+ * session's `current_user`. Operators apply the returned `up` script
+ * via `b.externalDb.migrate` under sox-404 / soc2 posture so a
+ * privileged caller (operator script, migration runner) can't write
+ * audit rows under a different actor identity.
+ *
+ * Returns `{ up, down, functionName, triggerName }` for migration
+ * runner symmetry.
+ *
+ * @opts
+ *   column:         string,             // default "actorUserId"
+ *   tableName:      string,             // default "_blamejs_audit_log"
+ *   roleMappingFn:  string,             // SQL fn name mapping actor → role
+ *   allowRoles:     string[],           // roles that bypass the check
+ *
+ * @example
+ *   var ddl = b.audit.generateActorBindingTriggerSql({
+ *     allowRoles: ["blamejs_service"],
+ *   });
+ *   await db.query(ddl.up);
+ */
+function generateActorBindingTriggerSql(opts) {
+  opts = opts || {};
+  var column = opts.column || "actorUserId";
+  var tableName = opts.tableName || "_blamejs_audit_log";
+  var allowRoles = Array.isArray(opts.allowRoles) ? opts.allowRoles : [];
+  var fnName = "_blamejs_audit_actor_binding_check";
+  var trigName = "_blamejs_audit_actor_binding_trig";
+  var allowList = allowRoles.length === 0 ? "" :
+    "  IF current_user IN (" +
+    allowRoles.map(function (r) { return "'" + r.replace(/'/g, "''") + "'"; }).join(", ") +
+    ") THEN RETURN NEW; END IF;\n";
+  var roleMatch = opts.roleMappingFn
+    ? "  IF " + opts.roleMappingFn + "(NEW.\"" + column + "\") IS DISTINCT FROM current_user THEN\n"
+    : "  IF NEW.\"" + column + "\" IS DISTINCT FROM current_user THEN\n";
+  var up =
+    "CREATE OR REPLACE FUNCTION " + fnName + "() RETURNS trigger AS $$\n" +
+    "BEGIN\n" +
+    allowList +
+    roleMatch +
+    "    RAISE EXCEPTION 'segregation-of-duties violation: actor=% does not match current_user=%', NEW.\"" + column + "\", current_user\n" +
+    "      USING ERRCODE = 'P0001';\n" +
+    "  END IF;\n" +
+    "  RETURN NEW;\n" +
+    "END;\n" +
+    "$$ LANGUAGE plpgsql;\n" +
+    "DROP TRIGGER IF EXISTS " + trigName + " ON " + tableName + ";\n" +
+    "CREATE TRIGGER " + trigName + "\n" +
+    "  BEFORE INSERT ON " + tableName + "\n" +
+    "  FOR EACH ROW EXECUTE FUNCTION " + fnName + "();\n";
+  var down =
+    "DROP TRIGGER IF EXISTS " + trigName + " ON " + tableName + ";\n" +
+    "DROP FUNCTION IF EXISTS " + fnName + "();\n";
+  return { up: up, down: down, functionName: fnName, triggerName: trigName };
+}
+
+// Boot-time check operators wire under sox-404 / soc2 posture. Verifies
+// the trigger function + trigger row are present in the externalDb
+// information_schema. Returns { ok, missing? } so the caller decides
+// whether to refuse boot.
+/**
+ * @primitive b.audit.assertSegregation
+ * @signature b.audit.assertSegregation(opts)
+ * @since     0.7.0
+ * @compliance sox-404, soc2
+ * @related   b.audit.generateActorBindingTriggerSql, b.audit.bindActor
+ *
+ * Boot-time check that confirms the actor-binding trigger function and
+ * trigger row exist in the externalDb's `pg_proc` / `pg_trigger`
+ * catalogs. Throws `AuditSegregationError` with the missing artifacts
+ * named when either is absent — operators wire this into the
+ * sox-404 / soc2 boot sequence so a forgotten migration refuses-to-boot
+ * instead of silently shipping without enforcement.
+ *
+ * @opts
+ *   db:            { query(sql, params) -> { rows } },   // required
+ *   functionName:  string,
+ *   triggerName:   string,
+ *
+ * @example
+ *   await b.audit.assertSegregation({ db: externalDb });
+ *   // throws if the trigger DDL hasn't been applied
+ */
+async function assertSegregation(opts) {
+  opts = opts || {};
+  var db = opts.db || null;
+  if (!db || typeof db.query !== "function") {
+    throw new AuditSegregationError("audit/segregation-no-db",
+      "audit.assertSegregation: opts.db with a query() method is required");
+  }
+  var fnName = opts.functionName || "_blamejs_audit_actor_binding_check";
+  var trigName = opts.triggerName || "_blamejs_audit_actor_binding_trig";
+  var fnRes = await db.query(
+    "SELECT 1 FROM pg_proc WHERE proname = $1 LIMIT 1", [fnName]
+  );
+  var fnPresent = !!(fnRes && fnRes.rows && fnRes.rows.length > 0);
+  var trigRes = await db.query(
+    "SELECT 1 FROM pg_trigger WHERE tgname = $1 LIMIT 1", [trigName]
+  );
+  var trigPresent = !!(trigRes && trigRes.rows && trigRes.rows.length > 0);
+  var missing = [];
+  if (!fnPresent) missing.push("function:" + fnName);
+  if (!trigPresent) missing.push("trigger:" + trigName);
+  var ok = missing.length === 0;
+  if (!ok) {
+    safeEmit({
+      action: "audit.actor_binding.violation",
+      outcome: "denied",
+      metadata: {
+        reason: "boot-time segregation check failed",
+        missing: missing,
+      },
+    });
+    throw new AuditSegregationError("audit/segregation-not-installed",
+      "audit.assertSegregation: SQL-side actor-binding trigger missing — " +
+      "apply the DDL from audit.generateActorBindingTriggerSql() under sox-404 / soc2 posture. " +
+      "Missing: " + missing.join(", "));
+  }
+  return { ok: ok, missing: missing };
+}
+
+// applyPosture — F-POSTURE-1 cascade hook. b.compliance.set(posture)
+// calls this to record the active posture so audit emissions can
+// surface the regulatory regime in metadata where downstream tooling
+// (forensic export, SIEM correlation) needs it. The chain itself is
+// posture-agnostic (every posture audits with the same SLH-DSA-SHAKE-
+// 256f signing key); this hook captures the posture name so query()
+// callers that filter by-posture have a stable column to look at.
+var _activePosture = null;
+/**
+ * @primitive b.audit.applyPosture
+ * @signature b.audit.applyPosture(posture)
+ * @since     0.7.27
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.audit.activePosture, b.compliance
+ *
+ * Cascade hook called by `b.compliance.set(posture)` to record the
+ * active regulatory regime. The chain itself is posture-agnostic —
+ * every posture audits with the same SLH-DSA-SHAKE-256f signing key —
+ * but downstream tooling (forensic export, SIEM correlation) reads the
+ * stored posture to filter / route. Returns `{ posture }` on accept,
+ * `null` on a non-string / empty argument.
+ *
+ * @example
+ *   b.audit.applyPosture("hipaa");
+ *   b.audit.activePosture();   // → "hipaa"
+ */
+function applyPosture(posture) {
+  if (typeof posture !== "string" || posture.length === 0) return null;
+  _activePosture = posture;
+  return { posture: posture };
+}
+/**
+ * @primitive b.audit.activePosture
+ * @signature b.audit.activePosture()
+ * @since     0.7.27
+ * @related   b.audit.applyPosture
+ *
+ * Return the posture string most recently passed to `applyPosture()`,
+ * or `null` if none has been set. Read-only accessor for downstream
+ * tooling that wants to tag audit-derived artifacts with the regime.
+ *
+ * @example
+ *   b.audit.applyPosture("pci-dss");
+ *   b.audit.activePosture();   // → "pci-dss"
+ */
+function activePosture() { return _activePosture; }
+
 module.exports = {
   registerNamespace:    registerNamespace,
   record:               record,
   emit:                 emit,
   safeEmit:             safeEmit,
+  applyPosture:         applyPosture,
+  activePosture:        activePosture,
+  bindActor:            bindActor,
+  assertSegregation:    assertSegregation,
+  generateActorBindingTriggerSql: generateActorBindingTriggerSql,
   flush:                flush,
   query:                query,
   verify:               verify,