@blamejs/core 0.8.42 → 0.8.49

package/lib/break-glass.js

@@ -1,41 +1,41 @@
 "use strict";
 /**
- * break-glass — column-policy / row-enforcement step-up auth.
+ * @module b.breakGlass
+ * @nav    Identity
+ * @title  Break Glass
  *
- * Operator declares which columns of which tables are GLASS-LOCKED.
- * Reading the encrypted value on any row of a glass-locked column
- * requires the calling operator to:
+ * @intro
+ *   Column-policy / row-enforcement step-up auth — PHI / PCI columns
+ *   require a fresh second-factor grant + operator-supplied reason;
+ *   every unseal is audited row-by-row.
  *
- *   1. Prove identity with a second factor (TOTP / passkey).
- *   2. Provide an operator-supplied REASON the audit chain captures.
- *   3. Hold a short-lived, scope-bounded GRANT.
+ *   The operator declares which columns of which tables are
+ *   GLASS-LOCKED. Reading a glass-locked column on any row requires
+ *   the caller to (1) prove identity with a fresh second factor (TOTP
+ *   or passkey), (2) supply a reason the audit chain captures, and
+ *   (3) hold a short-lived scope-bounded grant. Each row read emits a
+ *   per-row audit event; the default `maxRowsPerGrant: 1` enforces
+ *   row-by-row auth so every PHI / PCI access is its own discrete
+ *   authenticated event.
  *
- * Each row read under a grant emits a per-row audit event. Default
- * `maxRowsPerGrant: 1` enforces row-by-row auth — each row access is
- * its own discrete authenticated event, compliance-defensible by
- * construction. Operators with batch workflows raise the cap per-table.
+ *   Two crypto models ship side-by-side. Model A — the default — is a
+ *   policy gate: glass-locked columns sit in the regular cryptoField
+ *   sealed-row pipeline, and break-glass enforces the grant + audit
+ *   contract on every read path. Model B (`cryptographic: true` on the
+ *   policy) layers per-cell encryption on top: every (table, rowId,
+ *   column) triple gets its own key derived `K_cell = SHAKE256(DEK ||
+ *   table || rowId || column)`, AEAD-bound to AAD = `SHA3-512(table ||
+ *   rowId || column)` so swapping ciphertexts between rows fails
+ *   closed. Operators opt into Model B per-policy, then run
+ *   `b.breakGlass.migrate(table)` to convert existing rows.
  *
- * Spec: memory/specs/blamejs-break-glass-spec.md
+ *   Service-account bypass (`policy.serviceAccountBypass`) is opt-in
+ *   per-table — both an apiKey-id allowlist and a required role must
+ *   match. Admin tools (`listActiveAll`, `revokeAll`) cover security-
+ *   team dashboards and incident-response offboarding.
  *
- * Ships Model A (policy gate) + TOTP factor + config-time input
- * validation + 14 error codes + audit chain integration. Model B
- * (cryptographic gate via per-row K_row), passkey factor, service-
- * account bypass, and admin tools land in subsequent patches.
- *
- * Public API:
- *
- *   b.breakGlass.init({ now? })             — boot once
- *   b.breakGlass.policy.set(table, opts)
- *   b.breakGlass.policy.get(table)          — null if unset
- *   b.breakGlass.policy.list()
- *   b.breakGlass.policy.delete(table)
- *
- *   b.breakGlass.grant({ req, table, reason, factor, columns? })
- *   b.breakGlass.unsealRow(grant, table, rowId)
- *   b.breakGlass.revoke(grantId, { reason })
- *   b.breakGlass.listActive({ req })
- *
- *   b.breakGlass.BreakGlassError
+ * @card
+ *   Column-policy / row-enforcement step-up auth — PHI / PCI columns require a fresh second-factor grant + operator-supplied reason; every unseal is audited row-by-row.
  */
 var audit = require("./audit");
 var C = require("./constants");
@@ -177,9 +177,41 @@ async function _ensureDek(table) {
   return dek;
 }
 
-// Encrypt a single cell value with encryption context binding. Operators
-// in cryptographic mode use this at write time INSTEAD of letting
-// cryptoField.sealRow seal the column.
+/**
+ * @primitive b.breakGlass.encryptCell
+ * @signature b.breakGlass.encryptCell(plaintext, ctx)
+ * @since     0.5.1
+ * @status    stable
+ * @related   b.breakGlass.decryptCell, b.breakGlass.migrate, b.breakGlass.policy.set
+ *
+ * Encrypt a single glass-locked cell value with encryption-context
+ * binding. Operators running a policy in `cryptographic: true` mode
+ * call this at write time INSTEAD of letting `cryptoField.sealRow`
+ * seal the column. The framework derives a per-cell key from the
+ * policy's vault-sealed DEK plus `(table, rowId, column)`, encrypts
+ * with XChaCha20-Poly1305, and sets AAD to `SHA3-512(table || rowId
+ * || column)` so a ciphertext literally cannot be decrypted under a
+ * different row identifier even with the same DEK.
+ *
+ * Returns a string of the form `bgcell:1:<base64>` ready to write
+ * back to the column. Throws `breakglass/policy-not-set` when the
+ * table has no policy or the policy isn't in cryptographic mode, and
+ * `breakglass/grant-column-mismatch` when the column isn't glass-
+ * locked on the policy.
+ *
+ * @example
+ *   await b.breakGlass.policy.set("patients", {
+ *     columns:       ["ssn"],
+ *     factors:       ["totp"],
+ *     cryptographic: true,
+ *   });
+ *   var sealed = await b.breakGlass.encryptCell("123-45-6789", {
+ *     table:  "patients",
+ *     rowId:  "patient-001",
+ *     column: "ssn",
+ *   });
+ *   // → "bgcell:1:AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
+ */
 async function encryptCell(plaintext, ctx) {
   _requireInit();
   if (!ctx || typeof ctx !== "object" ||
@@ -207,11 +239,32 @@ async function encryptCell(plaintext, ctx) {
   return "bgcell:1:" + packed.toString("base64");
 }
 
-// Decrypt a cell value. Caller must hold a valid grant covering the
-// (table, column) — caller passes through unsealRow which gates this.
-// The encryption context (table, rowId, column) is passed both to the
-// key derivation AND the AAD; if the caller passes the wrong rowId
-// trying to "swap" ciphertexts between rows, decryption fails closed.
+/**
+ * @primitive b.breakGlass.decryptCell
+ * @signature b.breakGlass.decryptCell(ciphertext, ctx)
+ * @since     0.5.1
+ * @status    stable
+ * @related   b.breakGlass.encryptCell, b.breakGlass.unsealRow
+ *
+ * Decrypt a Model-B `bgcell:1:<base64>` cell value. Internal — the
+ * caller must already hold a valid grant covering the (table,
+ * column); operator-facing reads route through `b.breakGlass.unsealRow`
+ * which gates this call. The encryption context (`table, rowId,
+ * column`) is fed into BOTH the per-cell key derivation AND the AEAD
+ * AAD, so a caller passing the wrong `rowId` trying to swap
+ * ciphertexts between rows fails closed at the AEAD verify step.
+ *
+ * @example
+ *   // unsealRow routes here automatically for cryptographic-mode
+ *   // policies; calling decryptCell directly is rare and only for
+ *   // operator tooling that's already enforced its own grant gate.
+ *   var plaintext = await b.breakGlass.decryptCell(sealed, {
+ *     table:  "patients",
+ *     rowId:  "patient-001",
+ *     column: "ssn",
+ *   });
+ *   // → "123-45-6789"
+ */
 async function decryptCell(ciphertext, ctx) {
   _requireInit();
   if (typeof ciphertext !== "string" || ciphertext.indexOf("bgcell:1:") !== 0) {
@@ -238,6 +291,38 @@ async function decryptCell(ciphertext, ctx) {
 // back. The migration is idempotent — a row already in Model B form
 // (column starts with "bgcell:") is skipped.
 
+/**
+ * @primitive b.breakGlass.migrate
+ * @signature b.breakGlass.migrate(table, opts)
+ * @since     0.5.1
+ * @status    stable
+ * @related   b.breakGlass.encryptCell, b.breakGlass.policy.set
+ *
+ * One-shot migration that converts every existing row of a glass-
+ * locked table from Model A (cryptoField.sealRow only) into Model B
+ * per-cell ciphertext. Iterates via `_id`-keyset paging so memory
+ * stays bounded; rows already in Model B (column starts with
+ * `bgcell:`) are skipped, making the migration idempotent and safe
+ * to re-run after a partial failure.
+ *
+ * Emits a `breakglass.migrate` audit event on completion with totals
+ * and skipped counts. Refuses to run when the policy isn't in
+ * cryptographic mode — operator must `policy.set({ cryptographic:
+ * true })` first.
+ *
+ * @opts
+ *   batchSize:   number,   // _id-keyset page size (default 100)
+ *   callerOpts:  object,   // forwarded to audit actor resolution
+ *
+ * @example
+ *   await b.breakGlass.policy.set("patients", {
+ *     columns:       ["ssn", "dob"],
+ *     factors:       ["totp"],
+ *     cryptographic: true,
+ *   });
+ *   var summary = await b.breakGlass.migrate("patients", { batchSize: 250 });
+ *   // → { table: "patients", totalRows: 1200, migratedRows: 1198, skippedRows: 2 }
+ */
 async function migrate(table, opts) {
   _requireInit();
   opts = opts || {};
@@ -324,6 +409,29 @@ async function migrate(table, opts) {
 
 // ---- init ----
 
+/**
+ * @primitive b.breakGlass.init
+ * @signature b.breakGlass.init(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.policy.set, b.breakGlass.grant
+ *
+ * One-shot boot wiring. Clears the in-memory policy cache, resets the
+ * factor-lockout counter, and records the framework-wide trustProxy
+ * boundary so subsequent `grant()` calls populate the grant row's `ip`
+ * field from `X-Forwarded-For` only when proxies are trusted. Operators
+ * call this once at boot, before any policy / grant / unseal call —
+ * every other primitive throws `breakglass/not-initialized` until init
+ * has run.
+ *
+ * @opts
+ *   now:        number,    // testing-only override of Date.now (fixtures)
+ *   trustProxy: boolean,   // honor X-Forwarded-For when populating grant.ip (default false)
+ *
+ * @example
+ *   b.breakGlass.init({ trustProxy: true });
+ *   // → undefined  (init returns nothing; throws on bad opts)
+ */
 function init(opts) {
   opts = opts || {};
   validateOpts(opts, ["now", "trustProxy"], "breakGlass.init");
@@ -489,6 +597,47 @@ function _validatePolicySet(table, opts) {
   };
 }
 
+/**
+ * @primitive b.breakGlass.policy.set
+ * @signature b.breakGlass.policy.set(table, opts, callerOpts)
+ * @since     0.5.0
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.breakGlass.policy.get, b.breakGlass.policy.delete, b.breakGlass.grant
+ *
+ * Declare the column-policy that gates step-up auth on the named
+ * table. The listed columns become GLASS-LOCKED — every read of one of
+ * those columns on any row requires the caller to hold a fresh
+ * second-factor grant whose scope covers the column. Stored
+ * cluster-wide in `_blamejs_break_glass_policies` (sealed via
+ * cryptoField) so every node honors the same gate. Re-runs UPSERT;
+ * the policy cache flushes for the table.
+ *
+ * @opts
+ *   columns:              Array<string>,        // glass-locked column names (required, ≥1)
+ *   factors:              Array<string>,        // allowed second factors: "totp" / "passkey"
+ *   cryptographic:        boolean,              // opt into Model B per-cell encryption (default false)
+ *   grantTtl:             number,               // grant lifetime in ms (default 15 minutes)
+ *   maxRowsPerGrant:      number,               // rows a grant may unseal (default 1 — row-by-row)
+ *   reasonRequired:       boolean,              // require operator reason on grant (default true)
+ *   reasonMinLength:      number,               // minimum reason length in chars (default 12)
+ *   pinIp:                boolean,              // bind grant to issuing IP (default true)
+ *   sessionPin:           boolean,              // bind grant to issuing session (default true)
+ *   onLockedAccess:       string,               // "throw" | "redact" on unauthorized read (default "throw")
+ *   requireScope:         string,               // actor scope required before grant mints (e.g. "phi:admin")
+ *   serviceAccountBypass: object,               // { enabled, apiKeyIds, requireRole } — opt-in machine bypass
+ *   auditReasonStorage:   string,               // "cleartext" | "hmac" | "both" (default "cleartext")
+ *
+ * @example
+ *   await b.breakGlass.policy.set("patients", {
+ *     columns:         ["ssn", "dob"],
+ *     factors:         ["totp"],
+ *     grantTtl:        600000,
+ *     maxRowsPerGrant: 1,
+ *     requireScope:    "phi:admin",
+ *   });
+ *   // → { applied: true, table: "patients" }
+ */
 async function policySet(table, opts, callerOpts) {
   _requireInit();
   var validated = _validatePolicySet(table, opts);
@@ -540,6 +689,26 @@ async function policySet(table, opts, callerOpts) {
   return { applied: true, table: table };
 }
 
+/**
+ * @primitive b.breakGlass.policy.get
+ * @signature b.breakGlass.policy.get(table)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.policy.set, b.breakGlass.policy.list
+ *
+ * Read the current break-glass policy for `table` from the cluster-
+ * shared policies table, with an in-process cache that short-circuits
+ * the DB roundtrip on the unsealRow hot path. Returns `null` when the
+ * table has no policy declared (a non-glass-locked table). The cache
+ * invalidates on `policy.set` / `policy.delete`.
+ *
+ * @example
+ *   var policy = await b.breakGlass.policy.get("patients");
+ *   // → { table: "patients", columns: ["ssn", "dob"], factors: ["totp"], ... }
+ *
+ *   var none = await b.breakGlass.policy.get("posts");
+ *   // → null
+ */
 async function policyGet(table) {
   _requireInit();
   if (typeof table !== "string" || table.length === 0) return null;
@@ -576,6 +745,24 @@ async function policyGet(table) {
   return policy;
 }
 
+/**
+ * @primitive b.breakGlass.policy.list
+ * @signature b.breakGlass.policy.list()
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.policy.get, b.breakGlass.policy.set
+ *
+ * Enumerate every glass-locked table the cluster knows about. Used by
+ * compliance dashboards (which tables hold PHI / PCI?) and migration
+ * tooling that needs to walk the full set. Returns hydrated policy
+ * objects in `tableName` order — no abbreviated row form.
+ *
+ * @example
+ *   var policies = await b.breakGlass.policy.list();
+ *   // → [{ table: "patients", columns: ["ssn", "dob"], ... }, { table: "cards", ... }]
+ *   policies.length;
+ *   // → 2
+ */
 async function policyList() {
   _requireInit();
   var rows = await clusterStorage.executeAll(
@@ -589,6 +776,23 @@ async function policyList() {
   return out;
 }
 
+/**
+ * @primitive b.breakGlass.policy.delete
+ * @signature b.breakGlass.policy.delete(table, callerOpts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.policy.set
+ *
+ * Remove the break-glass policy for `table`. Subsequent reads of the
+ * previously glass-locked columns no longer require a grant — operators
+ * call this only when a column genuinely stops being PHI / PCI (rare;
+ * almost always the operator wants `policy.set` with a revised column
+ * list instead). Emits a `breakglass.policy.delete` audit event.
+ *
+ * @example
+ *   await b.breakGlass.policy.delete("legacy_patients");
+ *   // → { deleted: true, table: "legacy_patients" }
+ */
 async function policyDelete(table, callerOpts) {
   _requireInit();
   if (typeof table !== "string" || table.length === 0) {
@@ -647,6 +851,39 @@ async function _verifyPasskeyFactor(factor) {
   }
 }
 
+/**
+ * @primitive b.breakGlass.grant
+ * @signature b.breakGlass.grant(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @compliance hipaa, pci-dss, soc2
+ * @related   b.breakGlass.unsealRow, b.breakGlass.revoke, b.breakGlass.policy.set
+ *
+ * Mint a short-lived, scope-bounded break-glass grant. The framework
+ * verifies the operator's second factor (TOTP code or passkey
+ * assertion), records the operator-supplied reason into the audit
+ * chain, and issues a grant whose scope covers the named columns of
+ * the named table for `policy.grantTtl` ms or `policy.maxRowsPerGrant`
+ * row reads — whichever ends first. Failures emit a denied-grant audit
+ * row; repeated factor failures trigger the lockout primitive.
+ *
+ * @opts
+ *   req:      object,        // the active request (carries actor identity, ip, session)
+ *   table:    string,        // glass-locked table the grant scopes to
+ *   columns:  Array<string>, // optional subset of policy.columns (default = full policy)
+ *   reason:   string,        // operator-supplied reason (length-gated by policy.reasonMinLength)
+ *   factor:   object,        // { type: "totp", secret, code } or { type: "passkey", response, ... }
+ *
+ * @example
+ *   var handle = await b.breakGlass.grant({
+ *     req:     req,
+ *     table:   "patients",
+ *     columns: ["ssn"],
+ *     reason:  "ER admit verifying identity for patient-001",
+ *     factor:  { type: "totp", secret: req.user.totpSecret, code: "123456" },
+ *   });
+ *   // → { id: "bg-...", expiresAt: 1735000000000, rowsRemaining: 1, scopeTable: "patients", scopeColumns: ["ssn"] }
+ */
 async function grant(opts) {
   _requireInit();
   if (!opts || typeof opts !== "object") {
@@ -853,6 +1090,30 @@ function _reasonForAudit(reason, mode) {
 
 // ---- Use a grant ----
 
+/**
+ * @primitive b.breakGlass.unsealRow
+ * @signature b.breakGlass.unsealRow(grantHandle, table, rowId, opts)
+ * @since     0.5.0
+ * @status    stable
+ * @compliance hipaa, pci-dss, soc2
+ * @related   b.breakGlass.grant, b.breakGlass.decryptCell, b.breakGlass.revoke
+ *
+ * Read one row's glass-locked columns under an active grant. The
+ * framework validates the grant (not revoked, not expired, not
+ * exhausted, scope matches the table), atomically increments
+ * `rowsConsumed`, fetches and unseals the row, and emits a per-row
+ * `breakglass.unsealrow` audit event carrying the reason + actor +
+ * remaining rows. For Model B (cryptographic) policies, glass-locked
+ * columns route through `decryptCell` with encryption-context binding
+ * — a swapped ciphertext from another row fails closed at AEAD verify.
+ *
+ * @opts
+ *   req: object,   // optional originating request — populates ip / userAgent / sessionId / requestId on the audit row
+ *
+ * @example
+ *   var row = await b.breakGlass.unsealRow(handle, "patients", "patient-001", { req: req });
+ *   // → { _id: "patient-001", name: "Alice", ssn: "123-45-6789", dob: "1980-04-12", ... }
+ */
 async function unsealRow(grantHandle, table, rowId, opts) {
   _requireInit();
   if (!grantHandle || typeof grantHandle !== "object" || typeof grantHandle.id !== "string") {
@@ -1038,6 +1299,26 @@ async function unsealRow(grantHandle, table, rowId, opts) {
 
 // ---- Revoke ----
 
+/**
+ * @primitive b.breakGlass.revoke
+ * @signature b.breakGlass.revoke(grantId, opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.grant, b.breakGlass.revokeAll
+ *
+ * Mark a single grant revoked. Subsequent `unsealRow` calls against the
+ * grant id throw `breakglass/grant-revoked`. Idempotent — already-
+ * revoked grants stay at their original `revokedAt` timestamp because
+ * the UPDATE clause is gated on `revokedAt IS NULL`.
+ *
+ * @opts
+ *   reason:     string,   // operator note recorded into the audit row
+ *   callerOpts: object,   // forwarded to audit actor resolution
+ *
+ * @example
+ *   await b.breakGlass.revoke("bg-abc123", { reason: "operator finished read; releasing" });
+ *   // → { revoked: true, grantId: "bg-abc123" }
+ */
 async function revoke(grantId, opts) {
   _requireInit();
   if (typeof grantId !== "string" || grantId.length === 0) {
@@ -1063,6 +1344,27 @@ async function revoke(grantId, opts) {
 
 // ---- listActive ----
 
+/**
+ * @primitive b.breakGlass.listActive
+ * @signature b.breakGlass.listActive(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.listActiveAll, b.breakGlass.revoke
+ *
+ * Enumerate the active (not revoked, not expired, rows remaining)
+ * grants the caller currently holds. Lookup is keyed via cryptoField's
+ * `computeDerived` so the actor's id never appears in cleartext on the
+ * grants table — the framework hashes via the table's namespaced
+ * derivation. Unauthenticated callers (no actorId on `req`) get an
+ * empty array.
+ *
+ * @opts
+ *   req: object,   // request carrying the actor identity (req.user.id or req.apiKey.id)
+ *
+ * @example
+ *   var grants = await b.breakGlass.listActive({ req: req });
+ *   // → [{ id: "bg-...", scopeTable: "patients", scopeColumns: ["ssn"], expiresAt: ..., rowsRemaining: 1, factorType: "totp" }]
+ */
 async function listActive(opts) {
   _requireInit();
   opts = opts || {};
@@ -1110,6 +1412,32 @@ async function listActive(opts) {
 // audit row so post-incident review can distinguish operator-initiated
 // from service-initiated reads.
 
+/**
+ * @primitive b.breakGlass.unsealRowAsService
+ * @signature b.breakGlass.unsealRowAsService(req, table, rowId, opts)
+ * @since     0.5.0
+ * @status    stable
+ * @compliance hipaa, pci-dss, soc2
+ * @related   b.breakGlass.policy.set, b.breakGlass.unsealRow
+ *
+ * Machine-account read of a glass-locked row. Bypass is gated by the
+ * policy's `serviceAccountBypass` block — both the verified `req.apiKey.id`
+ * must be on the operator-declared allowlist AND the apiKey must
+ * carry the operator-declared role. Both checks must pass; either
+ * failure emits a denied bypass audit row and throws
+ * `breakglass/bypass-unauthorized`. Each successful bypass emits a
+ * distinct `breakglass.grant.bypass` audit row so post-incident review
+ * separates operator-initiated reads from scheduled-job reads.
+ *
+ * @opts
+ *   reason: string,   // operator-supplied reason recorded into the audit row
+ *
+ * @example
+ *   var row = await b.breakGlass.unsealRowAsService(req, "patients", "patient-001", {
+ *     reason: "nightly de-identification job",
+ *   });
+ *   // → { _id: "patient-001", name: "Alice", ssn: "123-45-6789", ... }
+ */
 async function unsealRowAsService(req, table, rowId, opts) {
   _requireInit();
   opts = opts || {};
@@ -1219,6 +1547,29 @@ async function unsealRowAsService(req, table, rowId, opts) {
 // teams when an account is suspected compromised. Both require
 // admin scope (operator wires via opts.requireScope or their own gate).
 
+/**
+ * @primitive b.breakGlass.listActiveAll
+ * @signature b.breakGlass.listActiveAll(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.listActive, b.breakGlass.revokeAll
+ *
+ * Admin variant of `listActive` — returns every active grant across
+ * every actor. Used by security-team dashboards and offboarding
+ * workflows; operators wire their own gate (`requireScope` or a
+ * middleware) on the calling route so non-admins can't enumerate the
+ * full grant pool. Each call emits a `breakglass.admin.listactiveall`
+ * audit row.
+ *
+ * @opts
+ *   table:      string,   // optional filter — only grants scoped to this table
+ *   since:      number,   // optional issuedAt floor (ms epoch)
+ *   callerOpts: object,   // forwarded to audit actor resolution
+ *
+ * @example
+ *   var all = await b.breakGlass.listActiveAll({ table: "patients" });
+ *   // → [{ id: "bg-...", issuedToActorId: "user-42", scopeTable: "patients", ... }]
+ */
 async function listActiveAll(opts) {
   _requireInit();
   opts = opts || {};
@@ -1261,6 +1612,31 @@ async function listActiveAll(opts) {
   return out;
 }
 
+/**
+ * @primitive b.breakGlass.revokeAll
+ * @signature b.breakGlass.revokeAll(criteria, opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.breakGlass.revoke, b.breakGlass.listActiveAll
+ *
+ * Mass-revoke grants matching a scope predicate. Refuses to run with
+ * empty criteria — IR teams must name at least one of `actorId` or
+ * `table` so the framework never silently revokes every grant in the
+ * cluster. The to-be-revoked grant ids are snapshotted into the audit
+ * row before the UPDATE, so post-incident timelines have the exact
+ * list. Common shape: revoke every active grant held by a suspected-
+ * compromised account.
+ *
+ * @opts
+ *   callerOpts: object,   // forwarded to audit actor resolution
+ *
+ * @example
+ *   var result = await b.breakGlass.revokeAll(
+ *     { actorId: "user-42", reason: "account compromise — IR-2026-0042" },
+ *     { callerOpts: { actor: { userId: "soc-on-call" } } }
+ *   );
+ *   // → { revokedCount: 3 }
+ */
 async function revokeAll(criteria, opts) {
   _requireInit();
   if (!criteria || typeof criteria !== "object") {