@blamejs/core 0.14.13 → 0.14.14

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.14.x
 
+- v0.14.14 (2026-05-31) — **Recognized consent purposes with lawful-basis gating, and a new b.privacy namespace for annual EdTech vendor-review attestations.** Closes the student-data gap where an educational-only consent purpose and an annual third-party vendor-review report were described but never implemented. b.consent gains a recognized-purpose vocabulary: a purpose value matching a recognized key carries lawful-basis constraints that grant() enforces, and the named educational-only purpose (FERPA's school-official exception and California's SOPIPA) refuses a legitimate_interests lawful basis. The new b.privacy namespace ships vendorReview(), a builder for the dated, clause-by-clause annual EdTech third-party / processor review FERPA and SOPIPA expect a school or district to keep — it computes whether every required clause (no targeted advertising, no commercial profiling, no sale of student data, deletion on request, school-official designation, and so on) is attested, names the gaps, and stamps a 365-day re-review clock. Free-form consent purposes keep working unchanged, so the vocabulary is opt-in and additive. **Added:** *`b.consent` recognized-purpose vocabulary + lawful-basis gating* — `b.consent.recognizedPurpose(name)` looks up a recognized purpose and `b.consent.listPurposes()` enumerates them. When a `grant({ purpose })` value matches a recognized key, `grant()` enforces that purpose's lawful-basis constraints; the `educational-only` purpose forbids a `legitimate_interests` basis (FERPA 34 CFR 99.31(a)(1) school-official exception; California SOPIPA Cal. B&P 22584; FTC school-authorized COPPA consent 16 CFR 312.5(c)(10)) and marks the data commercial-use-prohibited. The commercial-use prohibition is an operator trust-boundary obligation — `isGranted()` does not re-derive it. Any purpose value NOT in the vocabulary stays free-form and unconstrained, so existing callers are unaffected; the hash-chain column set is unchanged, so `b.consent.verify()` over existing rows is unaffected. · *`b.privacy.vendorReview` — annual EdTech vendor-review attestation* — A new `b.privacy` namespace whose `vendorReview(opts)` builds the dated third-party / processor review a FERPA school-official arrangement and California SOPIPA expect for every vendor that touches student data. The operator supplies a boolean attestation per clause (educational-purpose-only, no-targeted-advertising, no-commercial-profiling, no-sale-of-student-data, security-safeguards, deletion-on-request, sub-processor-currency, breach-notification, school-official-designation, directory-information-handling); `vendorReview` validates the shape, computes whether every required clause is attested (`attested`) and which are not (`gaps`), and stamps `reviewedAt` plus a 365-day `nextReviewDueAt` re-review clock. `b.privacy.listVendorReviewClauses()` returns the clause set with citations. Operator-feeds-metadata: the frozen report is not framework-persisted — compose it into your retention / audit / export sink. A best-effort `privacy.vendor_review.recorded` audit event fires when an audit sink is wired. **Detectors:** *A gated consent purpose must go through `b.consent`* — A new check flags any lib code that mints a consent row with a hardcoded `educational-only` purpose literal without composing the recognized-purpose vocabulary — which would record the value while never enforcing its FERPA / SOPIPA lawful-basis constraint.
+
 - v0.14.13 (2026-05-31) — **Close advertised-but-missing surface: SRS1 chained forwarding, DCQL array-wildcard claim paths, and in-memory safe-archive extraction.** Three primitives advertised a capability in their documentation or card but refused or omitted it at runtime; this release implements each. b.mail.srs gains srs1Rewrite for the SRS1 double-forward (and multi-hop) case — previously the @intro described SRS1 and create() threw, pointing at a function that was never exported. b.safeArchive gains extractToMemory, the in-memory counterpart to extract for read-only / serverless filesystems — previously the card advertised in-memory extraction but the orchestrator required a destination directory. b.auth.oid4vp.matchDcql now honours a null claims-path segment as the array wildcard the OpenID4VP DCQL spec defines, rather than refusing it as unsupported while the card advertised DCQL. A stale version-pinned wording in a safe-archive error message is corrected. Every change is additive or message-only — no existing caller changes behaviour. **Added:** *`b.mail.srs` SRS1 chained forwarding — `srs1Rewrite`* — `b.mail.srs.create(...)` now returns `srs1Rewrite` alongside `rewrite` / `reverse`. `srs1Rewrite(srsAddress)` chains an already-SRS0 (or SRS1) envelope-from for a further forwarding hop: it keeps the original SRS0 body verbatim, prepends the SRS0 originator's domain, and binds the pair with this forwarder's own HMAC-SHA-256 tag — no new timestamp, no repeated original local-part — emitting `SRS1=tag=originator==<SRS0-body>@thisForwarder`. `reverse()` now detects an SRS1 address, verifies this hop's tag and forwarder-domain binding, and unwraps exactly one hop back to the originator's SRS0 so a multi-hop bounce routes straight to the forwarder that can recover the original sender. Typed failure modes: `srs/not-srs0` (input not SRS-encoded), `srs/malformed` (missing the `==` separator), `srs/bad-tag` (tampered), `srs/too-long` (chain exceeds the RFC 5321 256-octet path limit). Implements the Sender Rewriting Scheme SRS1 wire format; the second-hop SPF rationale is RFC 7208 §2.4. · *`b.safeArchive.extractToMemory` — in-memory safe extraction* — An async generator counterpart to `b.safeArchive.extract` for read-only / serverless filesystems: it resolves the source, sniffs the format, auto-unwraps recipient (`BAWRP`) / passphrase (`BAWPP`) envelopes, and dispatches to the zip / tar / tar.gz reader's in-memory `extractEntries()`, yielding `{ name, bytes, size }` per regular-file entry without ever writing to disk. It takes no `destination`. Every defense the disk path runs applies unchanged: the zip-bomb caps (entry-count / per-entry / total / expansion-ratio), the `b.guardArchive` metadata cascade (Zip-Slip / path-traversal / symlink-escape / encrypted-entry refusal, CVE-2025-3445 class), and the entry-type policy. The disk-only realpath-agreement check (CVE-2025-4517 PATH_MAX TOCTOU defense) is intentionally absent — there is no extraction root — so the archive-level name refusals carry containment. Trusted-stream sources are refused upfront (the adversarial-safe central-directory walk needs random access). gzip magic per RFC 1952 §2.3.1. **Fixed:** *OID4VP DCQL `null` claim-path segment now resolves the array wildcard* — `b.auth.oid4vp.matchDcql` previously threw `auth-oid4vp/null-path-segment-not-supported` for a `null` claims-path segment while the namespace card advertised DCQL — under-disclosing a legitimate presentation (CWE-863). Per OpenID4VP 1.0 §7.1.1 a `null` segment selects all elements of the array at that depth; the matcher now recurses over array elements with existence semantics (with DCQL value-matching applied to any selected leaf), composed to arbitrary depth. A `null` segment on a non-array node — like an integer index into a non-array, or a string key into an array — is a clean non-match, not a thrown error, because the matcher walks holder credential data rather than operator config. String and integer claim paths are byte-identical to before; only queries that previously threw now succeed or fail cleanly. · *safe-archive trusted-stream refusal message no longer cites a stale version* — The thrown `safe-archive/trusted-stream-unsupported` message and its comment claimed trusted-stream extraction was "deferred to v0.12.8 / when the v0.12.8 sequential extract path lands." That path shipped long ago — `b.archive.read.zip.fromTrustedStream` and the tar sequential mode exist — so the message now points at them as present capabilities and drops the version-pinned wording. The error code is unchanged. **Detectors:** *A primitive may not advertise a capability and then throw an unimplemented stub* — A new check flags a bare `not yet supported` / `operator demand TBD` / `not supported in v1` refusal in a lib throw string (comments excluded). A defer is only complete with a written re-open condition; the SRS1 and DCQL stubs that this release implements both carried this bare-defer shape, and the detector keeps it from re-entering. · *DCQL `null` path segments must recurse, never refuse* — A new check flags the `null path segment not supported` refusal shape in `lib/auth/oid4vp.js`, so the spec-mandated array wildcard cannot be re-stubbed. · *`extractToMemory` must stay disk-free* — A new check flags any `writeFileSync` / `renameSync` / `mkdirSync` / `createWriteStream` inside the `extractToMemory` generator body, so the read-only / serverless contract cannot regress into a disk write.
 
 - v0.14.12 (2026-05-31) — **Vault key rotation re-seals AAD-bound storage under the new root instead of silently orphaning it.** Every AAD-sealed cell derives its key from the live vault root, so rotating the vault keypair changes those keys. `b.vaultRotate.rotate` previously re-sealed only legacy `vault:`-prefixed cells in `db.enc` and skipped `vault.aad:` cells, AAD-bound at-rest files, and operator-supplied AAD stores — leaving them encrypted under the retired keypair while still returning a success result and a passing round-trip verify, so the loss was invisible until the old keypair was discarded and the cells became permanently undecryptable. Rotation now re-seals `db.enc` (preserving its dataDir-bound AAD), `db.key.enc` (location-bound), every `{ aad: true }` table column, and the overflow store under the new root; refuses up front with a fail-closed error when operator-supplied AAD stores (agent idempotency / orchestrator / tenant / snapshot) are reachable unless each has been re-sealed via its module hook and explicitly acknowledged; and the round-trip verify now decrypts AAD-sealed cells under the new root and treats any cell that still opens under the old root as a regression. New explicit-root `b.vault.aad` seal / unseal / reseal primitives carry a cell from the old root to the new one while preserving its AAD tuple; `b.archive.rewrapTenant` re-wraps tenant-scoped archive envelopes; and `b.cluster` can adopt a rotated vault-key fingerprint instead of partitioning the membership during a rolling rotation. **Added:** *`b.vault.aad.sealRoot` / `unsealRoot` / `resealRoot`* — Explicit-root variants of the AAD seal / unseal that take a root-keypair JSON (`b.vault.getKeysJson()` output) instead of reading the live vault singleton. `resealRoot(value, aadParts, oldRootJson, newRootJson)` opens a cell under the old root and re-seals it under the new one while preserving the same AAD tuple (`table` / `rowId` / `column` / `schemaVersion`), which is what lets a rotation worker move AAD-bound state across a keypair change without altering the bound context. The default-root `b.vault.aad.seal` / `unseal` behaviour is unchanged. · *Per-store AAD re-seal hooks on the agent primitives* — `b.agent.idempotency.reseal`, `b.agent.orchestrator.reseal`, `b.agent.snapshot.reseal`, and the `b.agent.tenant` registry / tenant-cell reseal paths re-seal that module's AAD-bound rows from an old root to a new root over the operator's own store. Each module also exposes an `AAD_ROTATION` descriptor naming the store the rotation pipeline cannot reach on its own, so an operator can enumerate exactly what to re-seal before a rotation. · *`b.archive.rewrapTenant`* — Re-wraps a `recipient: "tenant"` archive envelope from an old vault root to a new one for a given `tenantId`, so a keypair rotation does not strand tenant-scoped archives. Opens the blob under the old root + tenantId, refuses a blob that is not a tenant-recipient envelope or that does not open under the supplied old root, and emits a fresh envelope bound to the new root. This is offered alongside the documented re-export path (decrypt with the old keypair, re-archive with the new one) for operators who hold the envelope but not the source. · *Cluster vault-key rotation acceptance* — A vault-key rotation changes the public-key fingerprint recorded in the canonical cluster-state row, which a peer would otherwise report as `VAULT_KEY_DRIFT`. `b.cluster` configuration gains `acceptVaultKeyRotation: true` to declare the change legitimate — the node adopts the rotated fingerprint and bumps a rotation epoch instead of refusing — and an optional `expectedVaultKeyFp` that narrows acceptance to a single blessed post-rotation fingerprint. The drift guard stays in force whenever a rotation is not declared; supplying `expectedVaultKeyFp` without `acceptVaultKeyRotation` is rejected at configuration time as a misconfiguration. **Changed:** *`b.vaultRotate.rotate` refuses when reachable AAD stores are not acknowledged* — Because the rotation pipeline walks only `db.enc` and cannot introspect an operator's own AAD-backed stores, it now detects which AAD-store modules are loadable and throws `vault-rotate/external-aad-unresealed` unless `opts.externalAadResealed` is either `true` (you do not use those features) or an array naming every detected store (you have re-sealed each via its hook). This converts a path that previously discarded data and reported success into a fail-closed gate. The error names each store and the hook to call. **Fixed:** *Rotation re-seals `vault.aad:` cells and AAD-bound at-rest files* — `db.enc` is re-written bound to its dataDir-scoped AAD (it was previously re-written un-bound, silently stripping the at-rest AAD binding on every rotation), `db.key.enc` retains its location-bound AAD, and every `{ aad: true }` table column plus the overflow store is re-sealed under the new root. Previously only `vault:`-prefixed cells were carried across, so AAD-sealed data was left encrypted under the retired keypair and lost once it was discarded. · *Round-trip verify no longer reports a false success* — `b.vaultRotate.verify` now samples and decrypts AAD-sealed cells under the new root and treats any cell that still decrypts under the old root as a regression, so an incomplete rotation fails verification instead of passing it. The prior verify checked only `vault:` cells and therefore reported `ok` even when AAD-sealed cells had been orphaned. **Security:** *A vault key rotation can no longer silently destroy encrypted data* — The orphaning path lost agent idempotency / orchestrator / tenant / snapshot state, `{ aad: true }` columns, and tenant archives with no error and a passing verify; the data became unrecoverable the moment the old keypair was retired. Rotation is now fail-closed end to end: it re-seals what it can reach, refuses to proceed past what it cannot until you acknowledge it, and verifies the result under the new root. If you performed a rotation on v0.14.11 or earlier and still hold the retired keypair, re-seal the affected cells under the current root with the explicit-root primitives before discarding it. **Detectors:** *AAD-backed store modules must expose a rotation reseal path* — A new check flags a module that registers an external `{ aad: true }` store but does not expose an `AAD_ROTATION` descriptor and reseal hook, which would leave its state unreachable by the rotation pipeline. · *A root-keyed seal family must ship its reseal* — A new check flags adding a `sealRoot` / `unsealRoot` pair without the matching `resealRoot`, since without it a rotated cell cannot be carried from the old root to the new one. · *Live-root AAD seals need a reseal path* — A new check flags a primitive that AAD-seals under the live vault root without a way to re-seal that state under a new root during rotation. · *Tenant archive re-wrapping must compose `b.archive.rewrapTenant`* — A new check flags tenant-scoped archive re-wrapping that opens and re-seals a tenant envelope by hand instead of routing through `b.archive.rewrapTenant`. · *Cluster vault-key drift needs the rotation-epoch accept gate* — A new check flags a cluster vault-key fingerprint comparison that hard-rejects a mismatch without honouring the `acceptVaultKeyRotation` epoch window. **Migration:** *Re-seal operator AAD stores before rotating* — Before calling `b.vaultRotate.rotate`, re-seal each AAD-backed store you use via its hook (`b.agent.idempotency.reseal`, `b.agent.orchestrator.reseal`, `b.agent.snapshot.reseal`, the `b.agent.tenant` `AAD_ROTATION` reseal paths) with the old and new root JSON, re-wrap tenant archives with `b.archive.rewrapTenant`, then pass `opts.externalAadResealed` as an array naming each re-sealed store. If you use none of these features, pass `opts.externalAadResealed: true`. Declare the rotation to each cluster node with `acceptVaultKeyRotation: true` so the membership adopts the new fingerprint rather than reporting drift.

package/README.md

@@ -212,7 +212,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Change control + WORM** — m-of-n approver DDL change-control with maintenance-window + ML-DSA-87 signed proposals (`b.ddlChangeControl`); row-level WORM triggers boot-asserted under `sec-17a-4` / `finra-4511` / `fda-21cfr11` (`b.db.declareWorm`); dual-control physical delete + crypto-erase + REINDEX in one transaction (`b.db.declareRequireDualControl`, `b.db.eraseHard`)
 - **Consumer-protection** — FTC click-to-cancel UX-parity attestation (`ftc-2024` / `ca-sb942` / `strict`) (`b.darkPatterns`)
 - **Differential privacy** — float-safe DP for aggregate releases: snapping-mechanism Laplace (Mironov 2012) + discrete Gaussian (Canonne–Kamath–Steinke 2020), CSPRNG noise, per-scope ε/δ budgets with basic + Rényi-DP accounting; defends the floating-point distinguishing attack that breaks naive Laplace samplers (NIST SP 800-226) (`b.ai.dp`)
-- **Privacy / DSR** — GDPR Articles 15–22 / CCPA / CPRA / LGPD / PIPEDA data-subject-rights workflow (`b.dsr`); IAB TCF v2 consent-string parse + encode + `disclosedVendors` validator (`b.iabTcf`); IAB MSPA / GPP universal-opt-out (USNAT / USCA / USVA / USCO / USCT / USUT) + GPC mirror (`b.iabMspa`); generic consent capture + withdrawal (`b.consent`)
+- **Privacy / DSR** — GDPR Articles 15–22 / CCPA / CPRA / LGPD / PIPEDA data-subject-rights workflow (`b.dsr`); IAB TCF v2 consent-string parse + encode + `disclosedVendors` validator (`b.iabTcf`); IAB MSPA / GPP universal-opt-out (USNAT / USCA / USVA / USCO / USCT / USUT) + GPC mirror (`b.iabMspa`); generic consent capture + withdrawal (`b.consent`); educational-only consent purpose with FERPA / SOPIPA lawful-basis gating + annual EdTech third-party vendor-review attestation (`b.consent.recognizedPurpose`, `b.privacy.vendorReview`)
 - **Incident reporters** — EU DORA Article 17 ICT-incident workflow per Commission Delegated Regulation 2024/1772 (`b.dora`); EU NIS2 (`b.nis2`); EU Cyber Resilience Act SBOM + secure-software-attestation (`b.cra`); SEC Form 8-K Item 1.05 cybersecurity-incident materiality-disclosure (`b.secCyber`); incident lifecycle coordinator (`b.incident`)
 - **Outbound DLP** — interceptor-installed on httpClient + mail + webhook with built-in detectors for PAN (Luhn), SSN, EIN, IBAN (mod-97), api-key shapes, PEM, SSH private keys, JWTs, AWS access keys, PHI composite; refuse / redact / audit-only verdicts under pci-dss / hipaa / fapi2 / soc2 / gdpr presets (`b.redact.installOutboundDlp`)
 ### Observability

package/index.js

@@ -26,7 +26,7 @@ _tls.DEFAULT_MIN_VERSION = "TLSv1.3";
  *                 frameworkSchema, clusterStorage, session, atomicFile,
  *                 cookies
  *   Audit:        audit, auditChain, auditSign, auditTools, consent,
- *                 subject, events, redact
+ *                 subject, events, redact, privacy
  *   HTTP:         router, middleware (csrf, cors, rate-limit, request-id,
  *                 security-headers, bot-guard, attach-user, require-auth,
  *                 error-handler, body-parser, csp-nonce, compression,
@@ -88,6 +88,7 @@ audit.export = function (opts) {
 };
 var auditChain = require("./lib/audit-chain");
 var consent = require("./lib/consent");
+var privacy = require("./lib/privacy");
 var subject = require("./lib/subject");
 var session = require("./lib/session");
 var storage = require("./lib/storage");
@@ -459,6 +460,7 @@ module.exports = {
   auditTools:       auditTools,
   events:           events,
   consent:          consent,
+  privacy:          privacy,
   subject:          subject,
   session:          session,
   storage:          storage,

package/lib/audit.js

@@ -270,6 +270,7 @@ var FRAMEWORK_NAMESPACES = [
   "flag",       // b.flag (flag.evaluated / flag.evaluation.error / flag.cache.bust)
   "permissions", // b.permissions
   "pqcagent",   // b.pqcAgent (pqcagent.operator_group.accepted)
+  "privacy",    // b.privacy (privacy.vendor_review.recorded)
   "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;

package/lib/consent.js

@@ -26,6 +26,12 @@
  *   enforcement at the trust boundary is the app's call (typical shape:
  *   `if (!b.consent.isGranted({ subjectId, purpose })) return 403`).
  *
+ *   `purpose` is free-form, but values matching the recognized-purpose
+ *   vocabulary (`b.consent.recognizedPurpose` / `listPurposes`) carry
+ *   lawful-basis constraints `grant()` enforces — e.g. `educational-only`
+ *   (FERPA school-official exception / California SOPIPA) refuses a
+ *   `legitimate_interests` basis.
+ *
  *   Cluster mode keeps `_blamejs_consent_tip` current with a fenced
  *   `INSERT … ON CONFLICT DO UPDATE … WHERE fencingToken <= EXCLUDED`
  *   so a partitioned old leader cannot rewrite the tip even if its
@@ -52,6 +58,31 @@ var FRAMEWORK_SQL_TIMEOUT_MS = C.TIME.seconds(30);
 var LAWFUL_BASES = ["consent", "contract", "legal_obligation", "vital_interests", "public_task", "legitimate_interests"];
 var ACTIONS = ["granted", "withdrawn", "expired", "superseded"];
 
+// Recognized consent purposes. A purpose value matching a key here carries
+// lawful-basis constraints that grant() enforces; any other (free-form)
+// purpose string stays valid and unconstrained, so the vocabulary is opt-in
+// and never breaks operators passing their own purpose names. FERPA's
+// school-official exception + California SOPIPA make "educational-only" the
+// canonical constrained purpose.
+//
+// Null-prototype map: the purpose value is operator-controlled, so a plain
+// object would let a free-form purpose colliding with an Object.prototype
+// member ("toString" / "constructor" / "__proto__") resolve to the prototype
+// value instead of undefined — recognizedPurpose() would return a function
+// and grant() would enter the recognized branch for a value listPurposes()
+// never exposes. A null prototype makes every unrecognized key resolve to
+// undefined (CWE-1321 defense).
+var PURPOSES = Object.freeze(Object.assign(Object.create(null), {
+  "educational-only": Object.freeze({
+    purpose:                 "educational-only",
+    forbidsLawfulBasis:      Object.freeze(["legitimate_interests"]),
+    commercialUseProhibited: true,
+    dataMinimization:        true,
+    citation:                "FERPA 34 CFR 99.31(a)(1) school-official exception; Cal. SB 1177 SOPIPA 22584(b)(1)-(4); 16 CFR 312.5(c)(10) FTC school-authorized COPPA consent",
+    notes:                   "K-12 / school-official use only; no targeted advertising, no commercial profiling, no sale. Lawful basis must be school authorization (consent / public_task / legal_obligation), not legitimate_interests. The commercial-use prohibition is an operator trust-boundary obligation — isGranted() does not re-derive it.",
+  }),
+}));
+
 var HASHABLE_COLS = [
   "_id", "recordedAt", "monotonicCounter",
   "subjectId", "subjectIdHash",
@@ -122,6 +153,22 @@ function grant(opts) {
   if (LAWFUL_BASES.indexOf(opts.lawfulBasis) === -1) {
     throw new Error("invalid lawfulBasis: '" + opts.lawfulBasis + "' (must be one of " + LAWFUL_BASES.join(", ") + ")");
   }
+  // Recognized-purpose vocabulary (opt-in): when the purpose matches a
+  // PURPOSES key, enforce its lawful-basis constraints. Free-form purposes
+  // remain unconstrained, so operators passing their own purpose names are
+  // unaffected.
+  var recognized = PURPOSES[opts.purpose];
+  if (recognized) {
+    if (recognized.forbidsLawfulBasis && recognized.forbidsLawfulBasis.indexOf(opts.lawfulBasis) !== -1) {
+      throw new Error("consent.grant: purpose '" + opts.purpose + "' forbids lawfulBasis '" +
+        opts.lawfulBasis + "' (" + recognized.citation + ")");
+    }
+    if (recognized.requiresLawfulBasis && recognized.requiresLawfulBasis.length > 0 &&
+        recognized.requiresLawfulBasis.indexOf(opts.lawfulBasis) === -1) {
+      throw new Error("consent.grant: purpose '" + opts.purpose + "' requires lawfulBasis in [" +
+        recognized.requiresLawfulBasis.join(", ") + "] (" + recognized.citation + ")");
+    }
+  }
   return _appendConsentRow({
     subjectId:    opts.subjectId,
     purpose:      opts.purpose,
@@ -133,6 +180,52 @@ function grant(opts) {
   });
 }
 
+/**
+ * @primitive  b.consent.recognizedPurpose
+ * @signature  b.consent.recognizedPurpose(name)
+ * @since      0.14.14
+ * @status     stable
+ * @compliance ferpa, ca-sopipa, coppa, gdpr
+ * @related    b.consent.grant, b.consent.listPurposes, b.consent.isGranted
+ *
+ * Look up a recognized consent purpose by value. Recognized purposes carry
+ * lawful-basis constraints that `grant()` enforces; the `educational-only`
+ * purpose (FERPA school-official exception / SOPIPA) forbids a
+ * `legitimate_interests` basis and marks the data commercial-use-prohibited.
+ * That commercial-use prohibition is an operator trust-boundary obligation —
+ * `isGranted()` does not re-derive it. Returns the frozen entry, or `null`
+ * for a free-form purpose (which remains valid for `grant()`).
+ *
+ * @opts
+ *   name: string,   // a purpose value, e.g. "educational-only"
+ *
+ * @example
+ *   b.consent.recognizedPurpose("educational-only");
+ *   // → { purpose: "educational-only", forbidsLawfulBasis: ["legitimate_interests"], ... }
+ *   b.consent.recognizedPurpose("marketing");   // → null (free-form)
+ */
+function recognizedPurpose(name) {
+  return PURPOSES[name] || null;
+}
+
+/**
+ * @primitive  b.consent.listPurposes
+ * @signature  b.consent.listPurposes()
+ * @since      0.14.14
+ * @status     stable
+ * @related    b.consent.recognizedPurpose, b.consent.grant
+ *
+ * Return the recognized-purpose values as a frozen array. Free-form
+ * purposes are not listed — they remain valid for `grant()` but carry no
+ * lawful-basis constraint.
+ *
+ * @example
+ *   b.consent.listPurposes();   // → ["educational-only"]
+ */
+function listPurposes() {
+  return Object.freeze(Object.keys(PURPOSES));
+}
+
 /**
  * @primitive  b.consent.withdraw
  * @signature  b.consent.withdraw(opts)
@@ -358,12 +451,15 @@ function _resetForTest() {
 }
 
 module.exports = {
-  grant:         grant,
-  withdraw:      withdraw,
-  isGranted:     isGranted,
-  history:       history,
-  verify:        verify,
-  LAWFUL_BASES:  LAWFUL_BASES,
-  ACTIONS:       ACTIONS,
-  _resetForTest: _resetForTest,
+  grant:             grant,
+  withdraw:          withdraw,
+  isGranted:         isGranted,
+  history:           history,
+  verify:            verify,
+  recognizedPurpose: recognizedPurpose,
+  listPurposes:      listPurposes,
+  LAWFUL_BASES:      LAWFUL_BASES,
+  PURPOSES:          PURPOSES,
+  ACTIONS:           ACTIONS,
+  _resetForTest:     _resetForTest,
 };

package/lib/framework-error.js

@@ -370,6 +370,10 @@ var DoraError             = defineClass("DoraError",             { alwaysPermane
 // posture name, runtime-switch refusal, assertion failures.
 // Permanent — these are configuration errors, not transient.
 var ComplianceError       = defineClass("ComplianceError",       { alwaysPermanent: true });
+// PrivacyError covers b.privacy config-time misuse: a malformed
+// vendorReview opts object, a non-boolean clause attestation, or an
+// unknown clause key. Permanent — operator configuration, not transient.
+var PrivacyError          = defineClass("PrivacyError",          { alwaysPermanent: true });
 // SmtpPolicyError covers MTA-STS / DANE / TLS-RPT misuse: bad-policy
 // shape, fetch failures, TLSA-record format errors, missing records.
 // Permanent — these are policy / DNS configuration errors, not
@@ -698,6 +702,7 @@ module.exports = {
   GuardAuthError:         GuardAuthError,
   DoraError:              DoraError,
   ComplianceError:        ComplianceError,
+  PrivacyError:           PrivacyError,
   SmtpPolicyError:        SmtpPolicyError,
   MailAuthError:          MailAuthError,
   MailArfError:           MailArfError,

package/lib/privacy.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * @module b.privacy
+ * @nav    Compliance
+ * @title  Privacy
+ *
+ * @intro
+ *   Privacy-program operational helpers. The first primitive,
+ *   `vendorReview`, builds the annual third-party / EdTech vendor-review
+ *   attestation that FERPA's school-official exception and California's
+ *   SOPIPA expect a school or district to keep on file for every
+ *   processor that touches student data: a dated, clause-by-clause
+ *   record that the vendor uses the data only for the authorized
+ *   educational purpose, runs no targeted advertising or commercial
+ *   profiling, sells nothing, keeps reasonable security safeguards,
+ *   deletes on request, and so on.
+ *
+ *   The builder follows the operator-feeds-metadata pattern: the
+ *   operator supplies the vendor's attested answers and `vendorReview`
+ *   returns a frozen report — `{ attested, gaps, reviewedAt,
+ *   nextReviewDueAt, ... }` — that composes into the operator's own
+ *   retention / audit / export sink. It is not framework-persisted.
+ *
+ * @card
+ *   Privacy-program helpers — annual FERPA / SOPIPA EdTech vendor-review attestation reports (`vendorReview`).
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var C = require("./constants");
+var { PrivacyError } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// The clause set a FERPA school-official / SOPIPA vendor review attests.
+// Each entry: { id, required, citation, description }. Every `required`
+// clause must be attested true for the review to pass (attested:true).
+var VENDOR_REVIEW_CLAUSES = Object.freeze([
+  Object.freeze({ id: "educationalPurposeOnly",       required: true,  citation: "FERPA 34 CFR 99.31(a)(1)(i)(B)", description: "Vendor uses student data only for the authorized educational purpose under direct school control; no redisclosure." }),
+  Object.freeze({ id: "noTargetedAdvertising",        required: true,  citation: "SOPIPA Cal. B&P 22584(b)(1)",    description: "No targeted advertising to students based on covered information." }),
+  Object.freeze({ id: "noCommercialProfiling",        required: true,  citation: "SOPIPA Cal. B&P 22584(b)(2)",    description: "No amassing of a student profile except in furtherance of K-12 purposes." }),
+  Object.freeze({ id: "noSaleOfStudentData",          required: true,  citation: "SOPIPA Cal. B&P 22584(b)(3)",    description: "No sale or rental of student information." }),
+  Object.freeze({ id: "securitySafeguards",           required: true,  citation: "SOPIPA Cal. B&P 22584(d)(1)",    description: "Reasonable security procedures and practices appropriate to the data's sensitivity." }),
+  Object.freeze({ id: "deletionOnRequest",            required: true,  citation: "SOPIPA Cal. B&P 22584(d)(2)",    description: "Deletes student PII within a reasonable time at the school's or district's request." }),
+  Object.freeze({ id: "subProcessorsCurrent",         required: true,  citation: "FERPA 34 CFR 99.33 (redisclosure)", description: "Sub-processor list is current and each is bound to the same restrictions." }),
+  Object.freeze({ id: "breachNotification",           required: true,  citation: "FERPA 34 CFR 99.31(a)(1) control + state breach law", description: "Notifies the school / district of any security breach without undue delay." }),
+  Object.freeze({ id: "schoolOfficialDesignation",    required: true,  citation: "FERPA 34 CFR 99.31(a)(1)(i)(B)", description: "Vendor is designated a school official with a legitimate educational interest." }),
+  Object.freeze({ id: "directoryInformationHandling", required: false, citation: "FERPA 34 CFR 99.37",             description: "Handles directory information per the school's opt-out notice (only when applicable)." }),
+]);
+
+var CLAUSE_IDS = VENDOR_REVIEW_CLAUSES.map(function (c) { return c.id; });
+
+/**
+ * @primitive  b.privacy.vendorReview
+ * @signature  b.privacy.vendorReview(opts)
+ * @since      0.14.14
+ * @status     stable
+ * @compliance ferpa, ca-sopipa, coppa
+ * @related    b.consent.recognizedPurpose, b.compliance.describe, b.retention
+ *
+ * Build a dated annual third-party / EdTech vendor-review attestation —
+ * the record a FERPA school-official arrangement and California SOPIPA
+ * expect a school or district to keep for every processor of student
+ * data. The operator supplies the vendor's attested answer (a boolean)
+ * per clause; `vendorReview` validates the shape, computes whether every
+ * REQUIRED clause is attested (`attested`) and which are not (`gaps`),
+ * and stamps the review date plus a 365-day `nextReviewDueAt` re-review
+ * clock. Operator-feeds-metadata: the returned report is frozen and is
+ * NOT framework-persisted — compose it into your retention / audit /
+ * export sink. A best-effort `privacy.vendor_review.recorded` audit event
+ * fires when an audit sink is wired.
+ *
+ * @opts
+ *   vendorName:   string,                    // required — the processor under review
+ *   reviewedAt:   number,                    // required — epoch ms of this review
+ *   clauses:      { <clauseId>: boolean },   // attested answer per clause (see listVendorReviewClauses)
+ *   reviewer:     string,                    // optional — who performed the review
+ *   notes:        string,                    // optional — free-text reviewer notes
+ *
+ * @example
+ *   var report = b.privacy.vendorReview({
+ *     vendorName: "Acme LMS",
+ *     reviewedAt: Date.now(),
+ *     clauses: {
+ *       educationalPurposeOnly: true, noTargetedAdvertising: true,
+ *       noCommercialProfiling: true, noSaleOfStudentData: true,
+ *       securitySafeguards: true, deletionOnRequest: true,
+ *       subProcessorsCurrent: true, breachNotification: true,
+ *       schoolOfficialDesignation: true,
+ *     },
+ *   });
+ *   // → { vendorName, reviewedAt, nextReviewDueAt, attested: true, gaps: [], clauses: {...} }
+ */
+function vendorReview(opts) {
+  validateOpts.requireObject(opts, "b.privacy.vendorReview: opts", PrivacyError, "privacy/bad-opts");
+  validateOpts.requireNonEmptyString(opts.vendorName, "b.privacy.vendorReview: opts.vendorName", PrivacyError, "privacy/bad-vendor");
+  if (typeof opts.reviewedAt !== "number" || !isFinite(opts.reviewedAt) || opts.reviewedAt <= 0) {
+    throw new PrivacyError("privacy/bad-reviewed-at",
+      "b.privacy.vendorReview: opts.reviewedAt must be a positive epoch-ms number");
+  }
+  var clauses = opts.clauses || {};
+  validateOpts.requireObject(clauses, "b.privacy.vendorReview: opts.clauses", PrivacyError, "privacy/bad-clauses");
+  // Reject unknown clause keys — a misspelled clause would otherwise
+  // silently never gate.
+  Object.keys(clauses).forEach(function (k) {
+    if (CLAUSE_IDS.indexOf(k) === -1) {
+      throw new PrivacyError("privacy/unknown-clause",
+        "b.privacy.vendorReview: unknown clause '" + k + "' (see b.privacy.listVendorReviewClauses())");
+    }
+  });
+  var resolved = {};
+  var gaps = [];
+  VENDOR_REVIEW_CLAUSES.forEach(function (clause) {
+    var v = clauses[clause.id];
+    // A supplied clause answer must be a boolean (config-time THROW); an
+    // omitted one defaults to not-attested.
+    validateOpts.optionalBoolean(v, "b.privacy.vendorReview: clauses." + clause.id, PrivacyError, "privacy/bad-clause-value");
+    var attestedTrue = v === true;
+    resolved[clause.id] = attestedTrue;
+    if (clause.required && !attestedTrue) gaps.push(clause.id);
+  });
+  var attested = gaps.length === 0;
+  var report = Object.freeze({
+    vendorName:      opts.vendorName,
+    reviewedAt:      opts.reviewedAt,
+    nextReviewDueAt: opts.reviewedAt + C.TIME.days(365),
+    coversPeriod:    Object.freeze({ from: opts.reviewedAt - C.TIME.days(365), to: opts.reviewedAt }),
+    reviewer:        opts.reviewer || null,
+    notes:           opts.notes || null,
+    attested:        attested,
+    gaps:            Object.freeze(gaps),
+    clauses:         Object.freeze(resolved),
+  });
+  try {
+    audit().safeEmit({
+      action:   "privacy.vendor_review.recorded",
+      outcome:  attested ? "success" : "denied",
+      metadata: { vendorName: opts.vendorName, attested: attested, gaps: gaps, reviewedAt: opts.reviewedAt },
+    });
+  } catch (_e) { /* drop-silent — audit is best-effort, never block the builder */ }
+  return report;
+}
+
+/**
+ * @primitive  b.privacy.listVendorReviewClauses
+ * @signature  b.privacy.listVendorReviewClauses()
+ * @since      0.14.14
+ * @status     stable
+ * @related    b.privacy.vendorReview
+ *
+ * Return the frozen FERPA / SOPIPA vendor-review clause set — each entry
+ * is `{ id, required, citation, description }`. Use it to render a review
+ * form or to enumerate the clauses `vendorReview` evaluates.
+ *
+ * @example
+ *   b.privacy.listVendorReviewClauses().map(function (c) { return c.id; });
+ *   // → ["educationalPurposeOnly", "noTargetedAdvertising", ...]
+ */
+function listVendorReviewClauses() {
+  return VENDOR_REVIEW_CLAUSES;
+}
+
+module.exports = {
+  vendorReview:            vendorReview,
+  listVendorReviewClauses: listVendorReviewClauses,
+  VENDOR_REVIEW_CLAUSES:   VENDOR_REVIEW_CLAUSES,
+  PrivacyError:            PrivacyError,
+};

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:0632934d-fe4a-4185-bb87-eef8617ef0a0",
+  "serialNumber": "urn:uuid:d4bb0c68-2752-4234-ac11-14ff95eaf273",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T19:38:16.822Z",
+    "timestamp": "2026-05-31T20:49:54.998Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.13",
+      "bom-ref": "@blamejs/core@0.14.14",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.13",
+      "version": "0.14.14",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.14.13",
+      "purl": "pkg:npm/%40blamejs/core@0.14.14",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.13",
+      "ref": "@blamejs/core@0.14.14",
       "dependsOn": []
     }
   ]