@blamejs/core 0.14.12 → 0.14.14

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.14.11 (2026-05-31) — **Defensive LLM model-I/O primitives, C2PA timestamp countersignatures with CAWG identity assertions, and signed EU AI Act GPAI adherence declarations.** Closes the output side of the LLM trust boundary and hardens content provenance and AI-Act attestation. b.ai.output.sanitize treats model output as untrusted and neutralizes XSS, gates every markdown-image / link and HTML src/href URL against SSRF (the EchoLeak zero-click exfiltration class, CVE-2025-32711), and flags SQL- and command-shaped fragments; b.ai.output.redact strips PII and secret disclosures. b.ai.input.classifyWithSources classifies a prompt together with its retrieval-augmented sources under a stricter, trust-tier-relative threshold, and the new b.ai.prompt namespace assembles prompts with escape-by-default boundaries — untrusted context / user segments are fenced in a per-render crypto-nonce delimiter the content cannot forge and stripped of bidi, control, zero-width, and Unicode-Tags smuggling characters. b.contentCredentials COSE signatures now carry an RFC 3161 timestamp countersignature (C2PA sigTst2, RFC 9921) verified entirely through b.tsa, so a signed manifest stays verifiable after its signing certificate expires, plus a CAWG identity assertion with trust-anchored verification. b.compliance.aiAct.gpai.declareAdherence emits a tamper-evident, ML-DSA-87-signed GPAI Code-of-Practice adherence declaration whose obligation set is derived from the regulation rather than operator-asserted. **Added:** *`b.ai.output.sanitize` and `b.ai.output.redact`* — A new `b.ai.output` namespace that treats LLM output as untrusted before it reaches a browser, a downstream fetcher, a SQL / command sink, or a log. `sanitize(text, opts)` neutralizes active markup via `b.guardHtml`, gates every markdown image / link and HTML `src` / `href` URL through `b.safeUrl.parse` (scheme + credential) and `b.ssrfGuard.classify` (internal / loopback / link-local / cloud-metadata IP-range) so auto-fetch URLs to attacker or internal hosts are neutralized, and flags SQL- and command-shaped fragments rather than silently repairing them. `redact(text, opts)` strips PII and secret disclosures via `b.redact` plus an entity-selectable pass (`pan` / `ssn` / `ein` / `iban` / `jwt` / `aws` / `phi` / `email` / `phone`). Defends OWASP LLM05:2025 Improper Output Handling and LLM02:2025 Sensitive Information Disclosure; the markdown-image URL gate closes the EchoLeak zero-click exfiltration class (CVE-2025-32711, CVSS 9.3). · *`b.ai.input.classifyWithSources`* — Classifies a prompt together with its retrieval-augmented (RAG) sources, applying a stricter, trust-tier-relative threshold to retrieved data. Each source is `{ id, text, trust? }` with `trust` of `trusted` / `internal` / `untrusted` (unset defaults to `untrusted`, fail-closed); untrusted and internal sources escalate to `suspicious` on a single severity-2 signal and to `malicious` on any severity-3, where the direct prompt keeps the baseline threshold. The aggregate verdict is the worst across the prompt and all sources, and every malicious source is reported in `taintedSources`. Defends indirect prompt injection from poisoned context (OWASP LLM01:2025; NIST AI 600-1). · *`b.ai.prompt.template`* — A new `b.ai.prompt` namespace for assembling LLM prompts with escape-by-default boundaries. The `system` segment is operator-trusted; `context` and `user` segments are treated as untrusted (no global opt-out — mark a segment `{ text, trusted: true }` individually). Untrusted segments are wrapped in a per-render, high-entropy delimiter nonce the content cannot forge, with any forged boundary stripped before wrapping (spotlighting / datamarking, Microsoft 2024; NIST AI 100-2e2025), and stripped of bidi overrides (CVE-2021-42574 Trojan Source), C0 controls, zero-width characters, null bytes, and Unicode Tags (U+E0000..U+E007F ASCII-smuggling). Run `b.ai.input.refuseIfMalicious` on the untrusted content as defense in depth. · *C2PA RFC 3161 timestamp countersignature and CAWG identity assertion* — `b.contentCredentials.signCose` attaches an RFC 3161 timestamp countersignature (C2PA `sigTst2`, RFC 9921) and `b.contentCredentials.verifyCose` verifies it. Pass `timestamp:{ token }` to embed a TimeStampToken, or `timestamp:{}` to get back the DER `application/timestamp-query` to POST to a timestamp authority. `b.contentCredentials.attachIdentityAssertion` / `verifyIdentityAssertion` add the CAWG Identity Assertion v1.2: a signed creator / organization identity hash-bound to a manifest's referenced assertions, where the `x509` binding reports `verified:true` only when an identity trust anchor is supplied and the leaf chain verifies, and the `identity-claims-aggregator` and self-asserted paths stay `verified:false`. · *`b.compliance.aiAct.gpai.declareAdherence` / `verifyAdherence`* — Signed, tamper-evident GPAI Code-of-Practice adherence declarations (Regulation (EU) 2024/1689 Art. 53(1)(a-d); Art. 55 for systemic-risk models under Art. 51(2)). The in-scope obligation set is derived from the classifier, never operator-asserted — a model at or above the 10^25-FLOP systemic-risk threshold that omits the Art. 55 chapter is refused. Each commitment's evidence reference must be a SHA3-512 digest; a malformed hash is rejected so a hollow attestation cannot bind. The declaration ships inside an ML-DSA-87-signed CycloneDX 1.6 ML-BOM via `b.ai.modelManifest`; verify re-canonicalizes before trusting any field and rejects a declaration past its validity window. Cites the GPAI Code of Practice (10 July 2025), Annex XI/XII, and Directive (EU) 2019/790 Art. 4(3). **Security:** *Model output is now an untrusted channel by default* — When feeding retrieved documents into an LLM, classify them with `b.ai.input.classifyWithSources` (untrusted sources escalate on a single signal) rather than trusting model input; assemble prompts with `b.ai.prompt.template` so untrusted context / user text is fenced in a per-render crypto-nonce boundary it cannot forge; and pass model output through `b.ai.output.sanitize` / `b.ai.output.redact` before it is rendered, fetched, or logged. Each primitive is on by default and fail-closed — no opt-in flag enables the protection. · *Timestamp verification routes only through `b.tsa.verifyToken`* — C2PA `sigTst2` verification performs the full RFC 3161 check (CMS signature over the signed attributes, messageDigest recompute, critical sole `id-kp-timeStamping` EKU) — never a chain-only shortcut — closing the timestamp-validation-bypass class (CVE-2025-52556, CWE-347). Supply `timestampTrustAnchorsPem` to `verifyCose` to check the timestamp certificate chain; `verifyCose` returns `{ valid, reason, claims, alg, timestamp }` and never throws. **Detectors:** *LLM output URLs must keep the SSRF gate* — A new check requires the output sanitizer to gate every extracted URL through both `b.safeUrl.parse` and `b.ssrfGuard.classify`, so the markdown-image SSRF gate (the EchoLeak class) cannot be silently dropped. · *RAG sources must compose `classifyWithSources`* — A new check flags any code that maps `b.ai.input.classify` over a sources array by hand, which would lose the trust-tier-relative threshold for retrieved data. · *Prompt boundaries must use a per-render nonce* — A new check flags prompt-assembly that wraps untrusted content in a fixed, guessable literal fence (`<user_input>`, `[DATA]`) instead of a per-render high-entropy delimiter the content cannot forge. · *C2PA timestamp verification must route through `b.tsa`* — A new check flags any bespoke certificate-chain-only walk on a timestamp token in place of `b.tsa.verifyToken`, preventing a re-introduction of the timestamp-validation-bypass class. · *GPAI adherence declarations must be signed* — A new check flags any code that emits the GPAI Code-of-Practice adherence property without routing it through the `b.ai.modelManifest` signed envelope, keeping the declaration tamper-evident.

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
@@ -230,7 +230,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`)
 - **CSV** — RFC 4180 with Excel formula-injection prevention (`b.csv`)
 - **IDs + slugs** — RFC 9562 UUID v4 + v7 (`b.uuid`); URL-safe slugs (`b.slug`)
-- **Time + archive** — TZ-aware datetime (`b.time`); ZIP creation + adversarial-safe read with bomb caps + path-traversal + LFH/CD-skew defense (`b.archive` + `b.archive.read.zip`); one-liner quarantine extraction (`b.safeArchive.extract`); in-memory extraction with no disk write for read-only / serverless filesystems (`b.archive.read.zip(...).extractEntries()` / `.tar`); fs / objectStore / http / buffer / trusted-stream adapter contract (`b.archive.adapters`); recipient-sealed envelopes — hybrid-PQC key-pair, peer certificate, or per-tenant key with no key-pair to manage (`b.archive.wrap({ recipient: "tenant", tenantId })`)
+- **Time + archive** — TZ-aware datetime (`b.time`); ZIP creation + adversarial-safe read with bomb caps + path-traversal + LFH/CD-skew defense (`b.archive` + `b.archive.read.zip`); one-liner quarantine extraction (`b.safeArchive.extract`); one-liner in-memory extraction with no disk write for read-only / serverless filesystems (`b.safeArchive.extractToMemory`, or the low-level `b.archive.read.zip(...).extractEntries()` / `.tar`); fs / objectStore / http / buffer / trusted-stream adapter contract (`b.archive.adapters`); recipient-sealed envelopes — hybrid-PQC key-pair, peer certificate, or per-tenant key with no key-pair to manage (`b.archive.wrap({ recipient: "tenant", tenantId })`)
 - **Pagination + forms** — HMAC-signed cursor pagination (`b.pagination`); HTML form rendering + validation + CSRF (`b.forms`)
 
 ### Production

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/auth/oid4vp.js

@@ -148,40 +148,52 @@ function _validateDcql(dcql) {
 }
 
 /**
- * Walk the path against the resolved-claim object the SD-JWT VC
- * verifier produced. Returns { found, value }.
- *   path = ["address", "country"]    → claims.address.country
- *   path = ["array", 0]              → claims.array[0]
- *   null = "any element" (DCQL §6.4.2 array path semantics) — for
- *     v1-defensible we don't dispatch on null; refuse with a clear
- *     error so the operator knows the gap.
+ * Walk a DCQL claims path pointer (OpenID4VP 1.0 §7.1.1) against the
+ * resolved-claim object the SD-JWT VC verifier produced, applying
+ * `leafPredicate` at the terminal node and returning a boolean:
+ *   string  → object property                  (["address", "country"])
+ *   integer → array index                       (["array", 0])
+ *   null    → all elements of the array at this depth (recurse; the
+ *             match is an existence check over the candidate leaves)
+ * 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 NON-MATCH, not an
+ * error: this walks holder credential data, not operator config, so a
+ * structural mismatch fails the match cleanly (rule §5 defensive
+ * request-shape reader tier) rather than throwing and crashing the
+ * verify request.
  */
-function _resolvePath(claims, path) {
-  var node = claims;
-  for (var i = 0; i < path.length; i++) {
-    var seg = path[i];
-    if (seg === null) {
-      // DCQL §6.4.2: null means "any element of the array at this
-      // depth". Not in v1 — refuse loudly so it doesn't silently
-      // match nothing.
-      throw new AuthError("auth-oid4vp/null-path-segment-not-supported",
-        "DCQL: null path segment (any-element) not supported in v1; supply a numeric index");
-    }
-    if (node === undefined || node === null) return { found: false, value: undefined };
-    node = node[seg];
+function _walkPath(node, path, idx, leafPredicate) {
+  if (idx === path.length) return leafPredicate(node);
+  if (node === undefined || node === null) return false;
+  var seg = path[idx];
+  if (seg === null) {
+    if (!Array.isArray(node)) return false;
+    return node.some(function (el) { return _walkPath(el, path, idx + 1, leafPredicate); });
+  }
+  if (typeof seg === "number") {
+    if (!Array.isArray(node)) return false;
+    return _walkPath(node[seg], path, idx + 1, leafPredicate);
   }
-  return { found: node !== undefined, value: node };
+  // string segment selects an object property; a string key into an
+  // array is a non-match (use a null wildcard or integer index instead).
+  if (Array.isArray(node)) return false;
+  return _walkPath(node[seg], path, idx + 1, leafPredicate);
 }
 
 function _matchClaim(claims, claimQuery) {
-  var resolved = _resolvePath(claims, claimQuery.path);
-  if (!resolved.found) return false;
-  if (claimQuery.values && claimQuery.values.length > 0) {
-    return claimQuery.values.some(function (v) {
-      return v === resolved.value || JSON.stringify(v) === JSON.stringify(resolved.value);
-    });
+  var values = claimQuery.values;
+  var leafPredicate;
+  if (values && values.length > 0) {
+    leafPredicate = function (leaf) {
+      if (leaf === undefined) return false;
+      return values.some(function (v) {
+        return v === leaf || JSON.stringify(v) === JSON.stringify(leaf);
+      });
+    };
+  } else {
+    leafPredicate = function (leaf) { return leaf !== undefined; };
   }
-  return true;
+  return _walkPath(claims, claimQuery.path, 0, leafPredicate);
 }
 
 function _matchCredentialQuery(presentation, query) {
@@ -219,6 +231,13 @@ function _matchCredentialQuery(presentation, query) {
  * implement their own verifier transport call this directly after
  * SD-JWT VC verification.
  *
+ * Claim path pointers follow OpenID4VP 1.0 §7.1.1: a string segment
+ * selects an object property, a non-negative integer indexes an array,
+ * and a `null` segment matches any element of the array at that depth
+ * (e.g. `["degrees", null, "type"]` matches the `type` claim of any
+ * element in the `degrees` array). A `null` segment applied to a
+ * non-array node is a non-match.
+ *
  * @example
  *   var match = b.auth.oid4vp.matchDcql([
  *     { id: "id-card", format: "vc+sd-jwt", claims: { vct: "...", given_name: "Alice" } }

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/mail-srs.js

@@ -28,15 +28,24 @@
  *     - `local` is the original sender's local-part
  *     - `forwarder.example` is the rewriting forwarder's domain
  *
- *   SRS1 (double-forward case): when an already-SRS0-encoded address
- *   gets forwarded a second time, SRS1 wraps the SRS0 envelope
- *   instead of re-encoding from scratch, preserving the original
- *   sender chain.
+ *   Wire format (SRS1 — the multi-hop chain case):
+ *
+ *     SRS1=HHH=priorForwarder==<SRS0-body>@thisForwarder
+ *
+ *   When an already-SRS0 (or SRS1) address is forwarded again,
+ *   `srs1Rewrite(srsAddress)` wraps it: it keeps the original SRS0
+ *   body verbatim, prepends the preceding forwarder's domain, and
+ *   binds the pair with this forwarder's own HMAC tag — no new
+ *   timestamp, no repeated original local-part. `reverse()` detects
+ *   SRS1, verifies this hop's tag, and unwraps exactly one hop back to
+ *   the prior forwarder's SRS0 address so the bounce re-routes to it.
  *
  *   `b.mail.srs.create({ secret, forwarderDomain })` returns
- *   `{ rewrite, reverse }`. `rewrite(originalSender)` produces the
- *   SRS-encoded address; `reverse(srsAddress)` decodes back to the
- *   original sender + verifies the HMAC.
+ *   `{ rewrite, srs1Rewrite, reverse }`. `rewrite(originalSender)`
+ *   produces the SRS0 address; `srs1Rewrite(srsAddress)` chains a
+ *   further hop as SRS1; `reverse(srsAddress)` decodes an SRS0 back to
+ *   the original sender (verifying HMAC + expiry) or unwraps an SRS1
+ *   one hop back to the prior forwarder.
  *
  * @card
  *   SRS Sender Rewriting Scheme — forwarder envelope-from rewriting with HMAC-bound day-rotated tags so the next-hop SPF check passes and bounces route correctly back to the original sender.
@@ -94,6 +103,34 @@ function _dayDiff(stamp, nowMs) {
   return diff;
 }
 
+// Parse an SRS1 local-part "SRS1=<tag>=<priorForwarder>==<srs0Body>"
+// into its three fields. The 4-char base32 tag and the prior-forwarder
+// domain both carry no "=", so the FIRST "=" ends the tag and the FIRST
+// "==" (which can only fall immediately after the "="-free prior-forwarder
+// domain) ends the prior forwarder — even when the inner SRS0 body carries
+// its own single "=" separators.
+function _parseSrs1(localPart) {
+  var rest = localPart.slice(5);                                                                   // strip "SRS1="
+  var firstEq = rest.indexOf("=");
+  if (firstEq <= 0) {
+    throw new SrsError("srs/malformed",
+      "srs.reverse: SRS1 must be SRS1=tag=priorForwarder==<srs0body>");
+  }
+  var tag = rest.slice(0, firstEq);
+  var afterTag = rest.slice(firstEq + 1);
+  var sep = afterTag.indexOf("==");
+  if (sep <= 0) {
+    throw new SrsError("srs/malformed",
+      "srs.reverse: SRS1 missing the '==' prior-forwarder separator");
+  }
+  var srs0Body = afterTag.slice(sep + 2);
+  if (!srs0Body) {
+    throw new SrsError("srs/malformed",
+      "srs.reverse: SRS1 carries an empty inner SRS0 body");
+  }
+  return { tag: tag, priorForwarder: afterTag.slice(0, sep), srs0Body: srs0Body };
+}
+
 /**
  * @primitive b.mail.srs.create
  * @signature b.mail.srs.create(opts)
@@ -101,7 +138,11 @@ function _dayDiff(stamp, nowMs) {
  * @status    stable
  *
  * Build an SRS rewriter bound to the operator's forwarder domain +
- * HMAC signing secret. Returns `{ rewrite, reverse }`.
+ * HMAC signing secret. Returns `{ rewrite, srs1Rewrite, reverse }` —
+ * `rewrite` produces an SRS0 origin address, `srs1Rewrite` chains an
+ * already-SRS0/SRS1 address as SRS1 for a further forwarding hop, and
+ * `reverse` decodes either form (SRS0 → original sender with HMAC +
+ * expiry checks; SRS1 → the prior forwarder's address, one hop back).
  *
  * @opts
  *   secret:           string,   // operator's HMAC-SHA-256 signing secret (>=32 bytes recommended)
@@ -121,6 +162,11 @@ function _dayDiff(stamp, nowMs) {
  *   // Bounce arrives back at SRS0=...; decode to deliver
  *   var original = srs.reverse(rewritten);
  *   // → "alice@bob.com"
+ *
+ *   // A further forwarding hop chains the already-SRS0 address as SRS1
+ *   var hop2 = srs.srs1Rewrite(rewritten);
+ *   // → "SRS1=HHHH=forwarder.example==HHHH=TT=bob.com=alice@forwarder.example"
+ *   srs.reverse(hop2);   // → the prior-hop SRS0 address, re-routed one hop back
  */
 function create(opts) {
   if (!opts || typeof opts !== "object") {
@@ -158,13 +204,12 @@ function create(opts) {
       throw new SrsError("srs/bad-address",
         "srs.rewrite: localPart / domain exceeds RFC 5321 length cap");
     }
-    // Refuse SRS double-encoding from this primitive — operator must
-    // use srs1Rewrite() for already-SRS0 inputs (deferred per the
-    // v1-defensible decision: SRS1 wrapping is rare in operator
-    // deployments and adds substantial spec surface).
+    // Refuse SRS double-encoding from this primitive — already-SRS0 (or
+    // SRS1) inputs chain through srs1Rewrite(), which keeps the original
+    // SRS0 body verbatim rather than re-stamping it as a fresh origin.
     if (/^SRS[01]=/i.test(localPart)) {
       throw new SrsError("srs/already-rewritten",
-        "srs.rewrite: address already SRS-encoded; chain forwarding through SRS1 is not yet supported (operator demand TBD)");
+        "srs.rewrite: address already SRS-encoded; use srs1Rewrite() to chain a further forwarding hop");
     }
     var now = typeof nowMs === "number" ? nowMs : Date.now();
     var ts  = _dayStamp(now);
@@ -173,6 +218,49 @@ function create(opts) {
     return "SRS0=" + tag + "=" + ts + "=" + domain + "=" + localPart + "@" + forwarderDomain;
   }
 
+  function srs1Rewrite(srsAddress) {
+    validateOpts.requireNonEmptyString(
+      srsAddress, "srs.srs1Rewrite.address", SrsError, "srs/bad-address");
+    var at = srsAddress.lastIndexOf("@");
+    if (at <= 0 || at === srsAddress.length - 1) {
+      throw new SrsError("srs/bad-address",
+        "srs.srs1Rewrite: address must be in localPart@domain form");
+    }
+    var localPart = srsAddress.slice(0, at);
+    // The SRS0 body is kept verbatim across the whole chain (the SRS1
+    // optimization: no new timestamp, no repeated original local-part).
+    // `priorForwarder` is the domain the bounce must ultimately reach to
+    // recover the original sender — i.e. the forwarder that MINTED the
+    // inner SRS0. From an SRS0 input that is its own @domain; from an
+    // SRS1 input (a third or later hop) it is the originator already
+    // recorded in the SRS1, NOT the immediately-preceding forwarder, so
+    // every hop's bounce routes straight back to the SRS0 originator.
+    var priorForwarder, srs0Body;
+    if (/^SRS0=/i.test(localPart)) {
+      priorForwarder = srsAddress.slice(at + 1);
+      srs0Body = localPart.slice(5);
+    } else if (/^SRS1=/i.test(localPart)) {
+      var inner = _parseSrs1(localPart);
+      priorForwarder = inner.priorForwarder;
+      srs0Body = inner.srs0Body;
+    } else {
+      throw new SrsError("srs/not-srs0",
+        "srs.srs1Rewrite: input must be an SRS0 or SRS1 address (use rewrite() for a plain address)");
+    }
+    if (!priorForwarder || priorForwarder.indexOf("=") !== -1) {
+      throw new SrsError("srs/bad-address",
+        "srs.srs1Rewrite: prior forwarder domain must be a non-empty domain without '=' (would corrupt SRS1 field parsing)");
+    }
+    var opaque = priorForwarder + "==" + srs0Body;
+    var tag = _hashTag(secret, opaque);
+    var result = "SRS1=" + tag + "=" + priorForwarder + "==" + srs0Body + "@" + forwarderDomain;
+    if (result.length > 256) {                                                                     // RFC 5321 §4.5.3.1.3 path-length cap
+      throw new SrsError("srs/too-long",
+        "srs.srs1Rewrite: rewritten address exceeds the RFC 5321 256-octet path limit (forwarding chain too deep)");
+    }
+    return result;
+  }
+
   function reverse(srsAddress, nowMs) {
     validateOpts.requireNonEmptyString(
       srsAddress, "srs.reverse.address", SrsError, "srs/bad-address");
@@ -183,13 +271,15 @@ function create(opts) {
     }
     var localPart  = srsAddress.slice(0, at);
     var rcptDomain = srsAddress.slice(at + 1);
-    // Allow case-insensitive SRS0 prefix per the spec. Check this
-    // FIRST so an obviously-non-SRS0 input (`plain@example.com`)
+    // Allow case-insensitive SRS0 / SRS1 prefixes per the spec. Check
+    // this FIRST so an obviously-non-SRS input (`plain@example.com`)
     // gets the specific not-srs0 verdict instead of the more general
     // wrong-forwarder verdict.
-    if (!/^SRS0=/i.test(localPart)) {
+    var isSrs0 = /^SRS0=/i.test(localPart);
+    var isSrs1 = /^SRS1=/i.test(localPart);
+    if (!isSrs0 && !isSrs1) {
       throw new SrsError("srs/not-srs0",
-        "srs.reverse: address local-part does not start with SRS0=");
+        "srs.reverse: address local-part does not start with SRS0= or SRS1=");
     }
     // Domain binding — the rewriter is scoped to a specific forwarder
     // domain, and reverse() must verify the bounce arrived at THAT
@@ -203,6 +293,18 @@ function create(opts) {
         "srs.reverse: bounce addressed to '" + rcptDomain + "' but rewriter " +
         "is bound to forwarderDomain '" + forwarderDomain + "'");
     }
+    if (isSrs1) {
+      var s1 = _parseSrs1(localPart);
+      if (!_timingSafeStringEqual(s1.tag, _hashTag(secret, s1.priorForwarder + "==" + s1.srs0Body))) {
+        throw new SrsError("srs/bad-tag",
+          "srs.reverse: SRS1 HMAC tag does not verify (wrong secret or tampered envelope-from)");
+      }
+      // Unwrap exactly one hop: re-address the bounce to the prior
+      // forwarder's SRS0. That forwarder owns the inner SRS0's tag +
+      // expiry, so we do NOT re-check them here — per the SRS spec each
+      // hop verifies only its OWN hash.
+      return "SRS0=" + s1.srs0Body + "@" + s1.priorForwarder;
+    }
     var rest = localPart.slice(5);
     var parts = rest.split("=");
     if (parts.length < 4) {
@@ -231,8 +333,9 @@ function create(opts) {
   }
 
   return Object.freeze({
-    rewrite:  rewrite,
-    reverse:  reverse,
+    rewrite:      rewrite,
+    srs1Rewrite:  srs1Rewrite,
+    reverse:      reverse,
     forwarderDomain: forwarderDomain,
   });
 }

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/lib/safe-archive.js

@@ -24,9 +24,9 @@
  *   Format auto-detection sniffs the first ~512 bytes for magic
  *   signatures: ZIP (LFH magic `0x04034b50` + EOCD magic `0x06054b50`),
  *   tar (`ustar` at offset 257), gzip / tar.gz (RFC 1952 magic), and
- *   `b.crypto.encryptPacked`-wrapped envelopes (auto-unwrapped before
- *   format detection). Unrecognized inputs are flagged
- *   `safe-archive/format-unsupported`.
+ *   `b.archive.wrap` recipient (`BAWRP`) / passphrase (`BAWPP`)
+ *   envelopes (auto-unwrapped before format detection). Unrecognized
+ *   inputs are flagged `safe-archive/format-unsupported`.
  *
  *   The orchestrator refuses the WHOLE archive on any single critical
  *   guard issue — no partial extraction. Cleanup is `fs.rm`-recursive
@@ -58,13 +58,10 @@ var MAGIC_ZIP_LFH  = 0x04034b50;
 var MAGIC_ZIP_EOCD = 0x06054b50;
 // GZIP magic per RFC 1952 §2.3.1.
 var MAGIC_GZIP_BE  = 0x1f8b;
-// b.crypto.encryptPacked envelope magic — the prefix the framework's
-// PQ envelope writes. (Sentinel value for v0.12.10+ Flavor 1 unwrap.)
-var MAGIC_ENCPACKED = "EPACK";
 
 async function _sniffMagic(adapter) {
   // For random-access adapters, the format sniffer reads the first
-  // 512 bytes — enough for ZIP + GZIP + b.crypto.encryptPacked magic
+  // 512 bytes — enough for ZIP + GZIP + wrap-envelope magic
   // detection. tar magic lives at offset 257 inside the first 512-
   // byte header block, so we need at least 263 bytes; 512 covers it.
   if (adapter.kind !== "random-access") {
@@ -91,13 +88,13 @@ async function _sniffMagic(adapter) {
     var be2 = head.readUInt16BE(0);
     if (be2 === MAGIC_GZIP_BE) return { format: "gzip" };
   }
-  // b.crypto.encryptPacked — 5-byte ASCII prefix.
+  // archive-wrap envelopes — 5-byte ASCII prefix. BAWRP (recipient) and
+  // BAWPP (passphrase) are the only wrap envelopes the framework produces
+  // (b.archive.wrap / b.archive.wrapWithPassphrase) and the only ones
+  // b.archive.sniffEnvelope recognizes.
   if (head.length >= 5) {
     var prefix = head.slice(0, 5).toString("utf8");
-    if (prefix === MAGIC_ENCPACKED) return { format: "encryptPacked" };
-    // v0.12.15 — archive-wrap recipient envelope (v0.12.10 / BAWRP).
     if (prefix === "BAWRP") return { format: "wrap-recipient" };
-    // v0.12.15 — archive-wrap passphrase envelope (v0.12.11 / BAWPP).
     if (prefix === "BAWPP") return { format: "wrap-passphrase" };
   }
   // tar — "ustar" at offset 257 within the first 512-byte header.
@@ -124,6 +121,82 @@ async function _collectSourceBytes(source) {
   return source.range(0, size);
 }
 
+// Shared source→adapter resolution + envelope auto-unwrap for the three
+// orchestrator entry points (extract / extractToMemory / inspect). Returns
+// { source, format } — `source` is a random-access adapter positioned at the
+// (possibly unwrapped) archive and `format` is the sniffed inner format. The
+// CALLER owns closing the returned source in its own `finally`; this helper
+// performs the pre-unwrap fd-close-before-replace + the signal-forward-to-
+// inner-adapter discipline internally, and closes a string-opened descriptor
+// if it throws mid-resolve so a sniff/unwrap failure can't leak it.
+async function _resolveAndUnwrap(opts, label, refuseTrustedStream) {
+  var openedFromString = typeof opts.source === "string";
+  var source = opts.source;
+  if (openedFromString) {
+    source = archiveAdapters().fs(source, { signal: opts.signal });
+  } else if (Buffer.isBuffer(source)) {
+    source = archiveAdapters().buffer(source, { signal: opts.signal });
+  } else if (refuseTrustedStream && archiveAdapters().isTrustedStreamAdapter(source)) {
+    // Trusted-stream adapters satisfy the adapter contract, but the
+    // orchestrator's adversarial-safe central-directory walk + LFH/CD skew
+    // defense needs random access. Refuse upfront with a typed error so the
+    // operator sees the constraint at the entry point rather than a
+    // downstream `archive-read/wrong-entry-point`.
+    throw new SafeArchiveError("safe-archive/trusted-stream-unsupported",
+      label + ": trusted-stream adapter sources are not supported by the orchestrator " +
+      "(the adversarial-safe central-directory walk requires random access). Collect the " +
+      "bytes into a buffer adapter — `b.archive.adapters.buffer(await collect(readable))` — " +
+      "and pass that, or read with `b.archive.read.zip.fromTrustedStream` directly.");
+  } else if (!archiveAdapters().isRandomAccessAdapter(source)) {
+    throw new SafeArchiveError("safe-archive/bad-source",
+      label + ": opts.source must be a string path, Buffer, or b.archive.adapters.* result");
+  }
+  try {
+    var format = opts.format || "auto";
+    if (format === "auto") {
+      format = (await _sniffMagic(source)).format;
+    }
+    // Auto-unwrap path: when the sniffer identifies a wrap envelope, unwrap
+    // inline + re-sniff the inner bytes so operators get a single call
+    // regardless of envelope shape. Operator supplies opts.recipient or
+    // opts.passphrase matching the envelope kind.
+    if (format === "wrap-recipient" || format === "wrap-passphrase") {
+      var sealedBytes = await _collectSourceBytes(source);
+      var inner;
+      if (format === "wrap-recipient") {
+        if (!opts.recipient) {
+          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
+            label + ": source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
+            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
+        }
+        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
+      } else {
+        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
+          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
+            label + ": source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
+            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
+        }
+        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
+      }
+      // Close the original string-opened descriptor BEFORE replacing the
+      // source reference (overwriting it would leak the fd across repeated
+      // calls → EMFILE under load), then forward opts.signal to the inner
+      // buffer adapter so abort propagation survives the unwrap boundary.
+      if (typeof source.close === "function" && openedFromString) {
+        try { source.close(); } catch (_e) { /* drop-silent */ }
+      }
+      source = archiveAdapters().buffer(inner, { signal: opts.signal });
+      format = (await _sniffMagic(source)).format;
+    }
+    return { source: source, format: format };
+  } catch (e) {
+    if (typeof source.close === "function" && openedFromString) {
+      try { source.close(); } catch (_e2) { /* drop-silent */ }
+    }
+    throw e;
+  }
+}
+
 // ---- Public extract orchestrator ----------------------------------------
 
 /**
@@ -168,84 +241,10 @@ async function extract(opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(opts.destination,
     "b.safeArchive.extract: opts.destination", SafeArchiveError, "safe-archive/no-destination");
-  // Resolve source → adapter. Strings become fs adapters; Buffers
-  // become buffer adapters; anything else is assumed to BE an adapter
-  // already.
-  var source = opts.source;
-  if (typeof source === "string") {
-    source = archiveAdapters().fs(source, { signal: opts.signal });
-  } else if (Buffer.isBuffer(source)) {
-    source = archiveAdapters().buffer(source, { signal: opts.signal });
-  } else if (archiveAdapters().isTrustedStreamAdapter(source)) {
-    // Trusted-stream adapters are accepted by the contract but the
-    // orchestrator's extract path needs random-access (CD-walk +
-    // LFH/CD skew defense). Refuse upfront with a typed safe-archive
-    // error so the operator sees the constraint at the entry point
-    // rather than an `archive-read/wrong-entry-point` thrown by the
-    // downstream reader. Trusted-stream extract via
-    // `b.archive.read.zip.fromTrustedStream` is deferred to v0.12.8
-    // alongside the tar reader's sequential mode.
-    throw new SafeArchiveError("safe-archive/trusted-stream-unsupported",
-      "extract: trusted-stream adapter sources are not supported by the orchestrator " +
-      "(the adversarial-safe CD-walk requires random-access). Collect the bytes via " +
-      "`b.archive.adapters.buffer(await collect(readable))` and pass that, or use " +
-      "`b.archive.read.zip.fromTrustedStream` directly when the v0.12.8 sequential " +
-      "extract path lands");
-  } else if (!archiveAdapters().isRandomAccessAdapter(source)) {
-    throw new SafeArchiveError("safe-archive/bad-source",
-      "extract: opts.source must be a string path, Buffer, or b.archive.adapters.* result");
-  }
-
+  var resolved = await _resolveAndUnwrap(opts, "extract", true);
+  var source = resolved.source;
+  var format = resolved.format;
   try {
-    var format = opts.format || "auto";
-    if (format === "auto") {
-      var sniff = await _sniffMagic(source);
-      format = sniff.format;
-    }
-    // v0.12.15 — auto-unwrap path. When the sniffer identifies a
-    // wrap envelope, unwrap inline + re-sniff the inner bytes so
-    // operators get a single extract() call regardless of envelope
-    // shape. Operator must supply opts.recipient or opts.passphrase
-    // matching the envelope kind.
-    if (format === "wrap-recipient" || format === "wrap-passphrase") {
-      var sealedBytes = await _collectSourceBytes(source);
-      var inner;
-      if (format === "wrap-recipient") {
-        if (!opts.recipient) {
-          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
-            "extract: source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
-            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
-        }
-        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
-      } else {
-        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
-          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
-            "extract: source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
-            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
-        }
-        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
-      }
-      // Close the original source
-      // adapter BEFORE replacing it. When opts.source was a string
-      // path, the fs adapter opened a file descriptor; overwriting
-      // `source` loses the close reference and the descriptor
-      // leaks across repeated extract() calls (eventually EMFILE
-      // under load). The outer finally still closes whatever
-      // `source` points at, but the original handle needs explicit
-      // release here.
-      if (typeof source.close === "function" && typeof opts.source === "string") {
-        try { source.close(); } catch (_e) { /* drop-silent */ }
-      }
-      // Forward opts.signal to the
-      // inner buffer adapter so abort propagation stays intact
-      // across the unwrap boundary. Without it, an abort raised
-      // after unwrapping would no longer cancel inner range()
-      // calls, breaking the documented signal contract for
-      // large wrapped archives.
-      source = archiveAdapters().buffer(inner, { signal: opts.signal });
-      var innerSniff = await _sniffMagic(source);
-      format = innerSniff.format;
-    }
     var reader;
     if (format === "zip") {
       reader = archiveRead().zip(source, {
@@ -277,7 +276,7 @@ async function extract(opts) {
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
         "extract: format=" + JSON.stringify(format) + " — supported formats are " +
-        "zip, tar, tar.gz; b.crypto.encryptPacked-wrapped archives are auto-unwrapped first");
+        "zip, tar, tar.gz; b.archive.wrap recipient/passphrase envelopes are auto-unwrapped first");
     }
     var result = await reader.extract({
       destination:    opts.destination,
@@ -291,6 +290,109 @@ async function extract(opts) {
   }
 }
 
+/**
+ * @primitive b.safeArchive.extractToMemory
+ * @signature b.safeArchive.extractToMemory(opts)
+ * @since     0.14.13
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.safeArchive.extract, b.archive.read.zip, b.archive.read.tar
+ *
+ * In-memory counterpart to `b.safeArchive.extract` for read-only /
+ * serverless filesystems. 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`
+ * — an async generator that yields each regular file entry's decompressed
+ * bytes without ever writing to disk. Takes no `destination`; the caller
+ * owns where, if anywhere, the bytes land.
+ *
+ * Every defense the disk `extract` 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. Directory entries carry no bytes and are skipped. 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 the containment guarantee here.
+ *
+ * Trusted-stream adapter sources are refused upfront: the adversarial-safe
+ * central-directory walk requires random access. Collect the bytes into a
+ * buffer adapter, or read with `b.archive.read.zip.fromTrustedStream`
+ * directly.
+ *
+ * @opts
+ *   source:           b.archive.adapters.* | Buffer | string,
+ *   format:           "auto" | "zip" | "tar" | "tar.gz",
+ *   bombPolicy:       b.guardArchive.zipBombPolicy(...) | { ... },
+ *   entryTypePolicy:  b.guardArchive.entryTypePolicy(...) | { ... },
+ *   guardProfile:     "strict" | "balanced" | "permissive" | "hipaa" | ...,
+ *   recipient:        { privateKey, ecPrivateKey },  // for BAWRP envelopes
+ *   passphrase:       string | Buffer,               // for BAWPP envelopes
+ *   audit:            b.audit,
+ *   signal:           AbortSignal,
+ *
+ * @example
+ *   for await (var entry of b.safeArchive.extractToMemory({
+ *     source:       b.archive.adapters.fs("/var/uploads/payload.zip"),
+ *     guardProfile: "strict",
+ *   })) {
+ *     // entry → { name, bytes, size } — never touches disk
+ *     await store.put(entry.name, entry.bytes);
+ *   }
+ */
+async function* extractToMemory(opts) {
+  opts = opts || {};
+  var resolved = await _resolveAndUnwrap(opts, "extractToMemory", true);
+  var source = resolved.source;
+  var format = resolved.format;
+  var extractOpts = { allowDangerous: opts.allowDangerous, allowEncrypted: opts.allowEncrypted };
+  try {
+    if (format === "zip") {
+      var zr = archiveRead().zip(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+      for await (var ze of zr.extractEntries(extractOpts)) { yield ze; }
+    } else if (format === "tar") {
+      var tr = archiveTarRead().tar(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+      for await (var te of tr.extractEntries(extractOpts)) { yield te; }
+    } else if (format === "tar.gz") {
+      // The gz reader's asTar() shim exposes inspect + extract but NOT
+      // extractEntries, so materialize the gz layer to a Buffer (the gz
+      // bomb caps still run during toBuffer()) and walk a fresh tar reader
+      // over it — the tar bomb / guard / entry-type caps run on the inner
+      // walk, so no defense is dropped.
+      var tarBytes = await archiveGz().read.gz(source, {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxExpansionRatio:    opts.maxExpansionRatio,
+        audit:                opts.audit,
+      }).toBuffer();
+      var gtr = archiveTarRead().tar(archiveAdapters().buffer(tarBytes, { signal: opts.signal }), {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+      for await (var ge of gtr.extractEntries(extractOpts)) { yield ge; }
+    } else {
+      throw new SafeArchiveError("safe-archive/format-unsupported",
+        "extractToMemory: format=" + JSON.stringify(format) + " — supported formats are " +
+        "zip, tar, tar.gz; b.archive.wrap recipient/passphrase envelopes are auto-unwrapped first");
+    }
+  } finally {
+    if (typeof source.close === "function" && typeof opts.source === "string") {
+      try { source.close(); } catch (_e) { /* drop-silent */ }
+    }
+  }
+}
+
 /**
  * @primitive b.safeArchive.inspect
  * @signature b.safeArchive.inspect(opts)
@@ -316,53 +418,10 @@ async function extract(opts) {
  */
 async function inspect(opts) {
   opts = opts || {};
-  var source = opts.source;
-  if (typeof source === "string") {
-    source = archiveAdapters().fs(source, { signal: opts.signal });
-  } else if (Buffer.isBuffer(source)) {
-    source = archiveAdapters().buffer(source, { signal: opts.signal });
-  } else if (!archiveAdapters().isRandomAccessAdapter(source)) {
-    throw new SafeArchiveError("safe-archive/bad-source",
-      "inspect: opts.source must be a string path, Buffer, or random-access adapter");
-  }
+  var resolved = await _resolveAndUnwrap(opts, "inspect", false);
+  var source = resolved.source;
+  var format = resolved.format;
   try {
-    var format = opts.format || "auto";
-    if (format === "auto") {
-      var sniff = await _sniffMagic(source);
-      format = sniff.format;
-    }
-    // v0.12.16 — auto-unwrap path for inspect, parallel to the
-    // v0.12.15 extract path. Wrap envelopes (BAWRP / BAWPP) are
-    // unwrapped inline + re-sniffed so operators can enumerate
-    // entries of a sealed archive in a single inspect() call.
-    if (format === "wrap-recipient" || format === "wrap-passphrase") {
-      var sealedBytes = await _collectSourceBytes(source);
-      var inner;
-      if (format === "wrap-recipient") {
-        if (!opts.recipient) {
-          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
-            "inspect: source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
-            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
-        }
-        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
-      } else {
-        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
-          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
-            "inspect: source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
-            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
-        }
-        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
-      }
-      // v0.12.15 P1 — close the original fs adapter (if string-
-      // backed) BEFORE replacing the source reference. v0.12.15 P2
-      // — forward opts.signal to the inner buffer adapter.
-      if (typeof source.close === "function" && typeof opts.source === "string") {
-        try { source.close(); } catch (_e) { /* drop-silent */ }
-      }
-      source = archiveAdapters().buffer(inner, { signal: opts.signal });
-      var innerSniff = await _sniffMagic(source);
-      format = innerSniff.format;
-    }
     var reader;
     if (format === "zip") {
       reader = archiveRead().zip(source, {
@@ -388,7 +447,7 @@ async function inspect(opts) {
       });
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "inspect: format=" + JSON.stringify(format) + " — v0.12.19 ships ZIP + tar + tar.gz; auto-unwraps wrap envelopes");
+        "inspect: format=" + JSON.stringify(format) + " — supported formats are zip, tar, tar.gz; wrap envelopes are auto-unwrapped first");
     }
     var entries = await reader.inspect();
     var totalCompressed = 0;
@@ -412,6 +471,7 @@ async function inspect(opts) {
 
 module.exports = {
   extract:           extract,
+  extractToMemory:   extractToMemory,
   inspect:           inspect,
   SafeArchiveError:  SafeArchiveError,
   // Exposed for tests + sibling modules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.14.12",
+  "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:f81dd931-ce62-498a-ac6f-d9ac5b0be399",
+  "serialNumber": "urn:uuid:d4bb0c68-2752-4234-ac11-14ff95eaf273",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T18:05:40.945Z",
+    "timestamp": "2026-05-31T20:49:54.998Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.12",
+      "bom-ref": "@blamejs/core@0.14.14",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.12",
+      "version": "0.14.14",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.14.12",
+      "purl": "pkg:npm/%40blamejs/core@0.14.14",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.12",
+      "ref": "@blamejs/core@0.14.14",
       "dependsOn": []
     }
   ]