@blamejs/core 0.12.10 → 0.12.12

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.12 (2026-05-23) — **`b.ai.disclosure.chatbot` + `b.ai.disclosure.deepfake` + `b.ai.disclosure.emotion` — EU AI Act Art. 50 transparency obligations (calendar-locked 2026-08-02) with US-CA AB-853 + China CAC GenAI cross-walk.** EU AI Act Art. 50 transparency primitives land ahead of the 2026-08-02 enforcement deadline. `b.ai.disclosure.chatbot(session, opts)` emits the Art. 50(1) first-contact "you are interacting with an AI system" disclosure with placement control (`first-message` / `always` / `on-request`). `b.ai.disclosure.deepfake(content, { contentType, placement, jurisdiction })` emits the Art. 50(4) synthetic-content label + machine-readable metadata payload for image / audio / video / text. `b.ai.disclosure.emotion({ systemType })` emits the Art. 50(3) emotion-recognition / biometric-categorisation notice. Each primitive emits a tamper-evident `ai-act/*-disclosure-applied` audit event so the compliance trail backs the user-facing notice. Cross-jurisdiction cross-walk lives in `opts.jurisdiction`: `"eu"` (default), `"us-ca"` adds AB-853 §22949.91 to the cross-walk array, `"cn"` adds CAC GenAI Measures Art. 12. The deepfake primitive returns a `schema: "c2pa-v1.4-ready"` metadata field that the v0.12.21 `b.contentCredentials` C2PA adapter will consume when it lands — this patch ships the label markup + schema; the C2PA manifest emission is the next composition. **Added:** *`b.ai.disclosure.chatbot(session, opts)` — Art. 50(1) first-contact disclosure* — Operators interacting with natural persons via an AI system get a primitive that emits the "you are interacting with an AI system" notice + audits the emission. `placement` opts: `"first-message"` (default — emit on first contact only, tracked via `session.aiDisclosureEmitted`), `"always"` (every response), `"on-request"` (operator wires their own trigger). Returns `{ text, language, jurisdiction, placement, shouldEmit, article, regulation }` — `shouldEmit` is the operator-consumable boolean for response-wire-up logic. · *`b.ai.disclosure.deepfake(content, opts)` — Art. 50(4) synthetic-content label* — Operators emitting model-generated or model-manipulated content get a primitive that returns both the visible label markup AND the machine-readable metadata payload. `contentType: "image" | "audio" | "video" | "text"` is required; `placement: "label" | "metadata" | "both"` (default `"both"`) controls what the primitive populates. The metadata payload includes `schema: "c2pa-v1.4-ready"` — the v0.12.21 `b.contentCredentials` C2PA adapter will consume this schema field when it lands. `crossWalk` array carries `["eu-ai-act/Art. 50(4)"]` plus the per-jurisdiction reference (AB-853 §22949.91 / CAC GenAI Art. 12). · *`b.ai.disclosure.emotion(opts)` — Art. 50(3) emotion-recognition / biometric-categorisation notice* — Operators deploying emotion-recognition or biometric-categorisation systems get the consent-flow notice primitive. `systemType: "emotion" | "biometric-categorisation"` (default `"emotion"`) selects which Art. 50(3) sub-obligation applies. Returns the notice payload + emits an `ai-act/emotion-disclosure-applied` audit event. · *Cross-jurisdiction cross-walk: EU + US-CA + China in a single primitive* — The `opts.jurisdiction` opt accepts `"eu"` (default — Regulation (EU) 2024/1689), `"us-ca"` (California AB-853 effective 2026), or `"cn"` (China CAC GenAI Measures). The chatbot + deepfake primitives both honour the cross-walk: the deepfake response's `crossWalk` array carries every jurisdiction-specific legal reference the same emission satisfies, so operators serving multi-region traffic emit one notice + audit one event + reference all applicable regimes. **Security:** *Drop-silent audit emission preserves the disclosure path under audit-bus failure* — If `opts.audit` is supplied but its `safeEmit` throws (network bus down, audit-sign chain malformed), the disclosure primitive still returns the user-facing notice payload. The Art. 50 obligation is the user-facing notice itself; the audit emission is a parallel best-effort chain-of-custody record. Refusing the disclosure to defend the audit chain would fail the wrong direction — the regulatory contract is satisfied by emitting the notice. Matches the framework's `audit.safeEmit` drop-silent contract for hot-path observability sinks. **Migration:** *C2PA manifest emission lands in v0.12.21* — The deepfake primitive's metadata payload includes a `schema: "c2pa-v1.4-ready"` field that the v0.12.21 `b.contentCredentials` adapter will consume. Operators emitting image / audio / video for v0.12.12-0.12.20 get the label markup + structured metadata; the actual C2PA manifest (signed JUMBF assertion chain) is the next composition layer.
+
+- v0.12.11 (2026-05-23) — **`b.archive.wrapWithPassphrase` + `b.archive.unwrapWithPassphrase` — Argon2id + XChaCha20-Poly1305 archive envelope + `b.backup` `cryptoStrategy: "passphrase"` with HIPAA / PCI-DSS 128-bit entropy floor.** Passphrase wrap lands as the second `b.archive` envelope strategy alongside v0.12.10's recipient wrap. `b.archive.wrapWithPassphrase(bytes, { passphrase, minEntropyBits })` produces a `BAWPP`-prefixed envelope under Argon2id (RFC 9106; framework-default 64 MiB / 3 iterations / 4 parallelism) key derivation with XChaCha20-Poly1305 AEAD; each envelope carries its own fresh salt in the wire format (5-byte magic + 1-byte version + 1-byte saltLen + salt + 24-byte nonce + ciphertext+tag) so KDF parameters can rotate in future minors without per-envelope version bumps. `b.archive.unwrapWithPassphrase(sealed, { passphrase })` verifies the `BAWPP` header before any Argon2id compute so non-envelope inputs fail with `archive-wrap/bad-magic` rather than burning the KDF on bad bytes. `b.backup.bundleAdapterStorage({ cryptoStrategy: "passphrase", passphrase })` composes the wrap layer transparently — bundle bytes hitting the adapter's `writeFile` are an opaque passphrase-derived envelope. Default `passphraseMinEntropyBits: 80` matches OWASP strong-password guidance; HIPAA + PCI-DSS postures raise the floor to 128 bits automatically (matching the framework's existing crypto-grade-password discipline for sealed-storage). The recipient strategy from v0.12.10 + passphrase strategy from v0.12.11 + plaintext strategy from v0.12.7 cover the operator's posture matrix: HIPAA / PCI-DSS pick recipient or passphrase; non-regulated deployments may stay on `"none"` when the storage layer is itself the protective boundary. **Added:** *`b.archive.wrapWithPassphrase(bytes, { passphrase, minEntropyBits })` — Argon2id-derived archive envelope* — Composes `b.backupCrypto.encryptWithFreshSalt(bytes, passphrase)` (Argon2id KDF + XChaCha20-Poly1305 AEAD, fresh per-envelope salt) and prepends a 7-byte `BAWPP` envelope header (5-byte magic + 1-byte version + 1-byte saltLen) so format sniffers can identify passphrase wrap output without trial KDF work. Entropy estimate uses observed-alphabet bit-count (the standard NIST/OWASP character-class approximation). `minEntropyBits` defaults to 80; the gate refuses upfront with `archive-wrap/weak-passphrase` when the estimate falls short. · *`b.archive.unwrapWithPassphrase(sealed, { passphrase })` — inverse with magic-check upfront* — Verifies the 7-byte `BAWPP` header (magic + version + saltLen) before any cryptographic work so non-envelope inputs (raw archives, recipient-wrap envelopes, truncated buffers) fail with `archive-wrap/bad-magic` / `archive-wrap/bad-version` / `archive-wrap/truncated-envelope` rather than wasting Argon2id compute. Routes through `b.backupCrypto.decryptWithPassphrase(encrypted, passphrase, saltHex)` so the framework's locked Argon2id parameters apply. · *`b.backup.bundleAdapterStorage({ cryptoStrategy: "passphrase", passphrase })` — Argon2id-keyed bundle storage* — Composes `b.archive.wrapWithPassphrase` transparently — every `writeBundle` payload is wrapped before `adapter.writeFile`; every `readBundle` payload is unwrapped after `adapter.readFile`. The `passphraseMinEntropyBits` opt defaults to 80 (OWASP strong-password floor); HIPAA + PCI-DSS postures raise the floor to 128 bits automatically. Passphrase + directory format combination refused upfront (same contract as recipient + directory). Wire-format envelope on disk is opaque ciphertext — no information leakage about archive contents through the storage adapter. · *HIPAA + PCI-DSS postures raise entropy floor to 128 bits under passphrase strategy* — `bundleAdapterStorage({ posture: "hipaa", cryptoStrategy: "passphrase", passphrase })` enforces `passphraseMinEntropyBits >= 128` regardless of the operator-supplied opt. The 128-bit floor matches the framework's existing crypto-grade-password discipline for sealed-storage cells. Operators sourcing passphrases from a CSPRNG (`b.crypto.generateBytes(16).toString("base64url")` → ~128 bits) pass without issue; operators typing dictionary phrases trip the gate. **Security:** *Magic-check before KDF work — non-envelope inputs can't burn Argon2id compute* — Adversarial inputs that look like passphrase envelopes but aren't (random bytes, recipient envelopes, raw archives) fail at byte 0-4 (magic check) rather than after a 64 MiB Argon2id round. Operators handing user-supplied bundles to readBundle on a server with concurrent load get bounded refusal latency rather than worst-case KDF compute under a chosen-bytes attack.
+
 - v0.12.10 (2026-05-23) — **`b.archive.wrap` + `b.archive.unwrap` — recipient-encrypted archive envelopes (Flavor 1) + `b.backup` `cryptoStrategy: "recipient"` + HIPAA/PCI-DSS posture refusal.** Flavor 1 lands as the whole-archive recipient-wrap substrate. `b.archive.wrap(bytes, { recipient })` produces a sealed envelope under the framework's hybrid PQC seal (ML-KEM-1024 + P-384 ECDH + SHAKE256 + XChaCha20-Poly1305) prefixed with a 6-byte `BAWRP` archive-wrap header so format sniffers can identify wrap envelopes without trial decryption. `b.archive.unwrap(sealed, { recipient })` is the inverse with magic-check upfront so non-envelope inputs throw `archive-wrap/bad-magic` rather than a crypto-level error. Recipient strategies: static keypair (`{ publicKey, ecPublicKey }`) and peer-cert (`{ peerCertDer, peerKemPubkey }`); the tenant strategy lands in v0.12.11 alongside the backup-crypto refactor + per-tenant key resolution. `b.backup.bundleAdapterStorage({ cryptoStrategy: "recipient", recipient })` composes the wrap/unwrap layer transparently: the bytes hitting the adapter's `writeFile` are a `BAWRP`-prefixed envelope, never the raw tar / tar.gz / directory bundle. HIPAA + PCI-DSS postures refuse `cryptoStrategy: "none"` upfront with `backup/posture-requires-encryption` — the storage adapter cannot itself satisfy the encryption-at-rest requirement; the recipient envelope is the framework-side gate. Flavor 2 (per-entry ZIP wrap with the 0xBADC extra-field marker) and the backup-crypto refactor into `lib/_crypto-base.js` ship in v0.12.11. **Added:** *`b.archive.wrap(bytes, { recipient })` — recipient-encrypted archive envelope* — Composes `b.crypto.encrypt` (or `b.crypto.encryptEnvelopeAsCertPeer` for the peer-cert strategy) under the framework's hybrid PQC seal. The output is a Buffer carrying a 6-byte `BAWRP` archive-wrap header (5-byte magic + 1-byte version) followed by the base64-encoded envelope bytes. Recipient strategies: `{ publicKey, ecPublicKey }` for the static-keypair path (ML-KEM-1024 PEM + P-384 ECDH PEM); `{ peerCertDer, peerKemPubkey }` for the peer-cert path (extracts the P-384 half from the cert per `b.crypto.encryptEnvelopeAsCertPeer`). `"tenant"` returns `archive-wrap/tenant-strategy-deferred` upfront — that strategy lands in v0.12.11 with the per-tenant key resolution. · *`b.archive.unwrap(sealed, { recipient })` — inverse with upfront magic check* — Verifies the 6-byte `BAWRP` header before any cryptographic work so non-envelope inputs (raw archives, other-magic envelopes, truncated buffers) fail with `archive-wrap/bad-magic` / `archive-wrap/bad-version` rather than a downstream `crypto/*` error. Routes through `b.crypto.decrypt(envelope, recipient, { raw: true })` so binary archive payloads (gzip, ZIP, tar) round-trip losslessly — `raw: true` is the contract that preserves bytes vs the default utf-8 decoding. · *`b.backup.bundleAdapterStorage({ cryptoStrategy: "recipient", recipient })` — opt-in envelope storage* — `cryptoStrategy: "none"` (default, v0.12.7-9 behaviour) writes plaintext bundle bytes to the adapter — safe for storage layers that are themselves the protective boundary (S3 SSE, disk-encrypted hosts). `cryptoStrategy: "recipient"` requires `opts.recipient` and wraps every `writeBundle` payload through `b.archive.wrap` before `adapter.writeFile`; `readBundle` unwraps after `adapter.readFile`. The wrap layer sits OUTSIDE the gz / tar layers so the bundle on disk is opaque ciphertext under the operator-controlled recipient key. Passphrase strategy is deferred to v0.12.11 alongside the `_crypto-base.js` refactor. · *HIPAA + PCI-DSS posture refuses plaintext bundles* — `bundleAdapterStorage({ posture: "hipaa" })` (or `"pci-dss"`) refuses `cryptoStrategy: "none"` upfront with `backup/posture-requires-encryption` — adapter-storage's plaintext default cannot itself satisfy encryption-at-rest requirements. Operators under these postures pass `cryptoStrategy: "recipient"` + a recipient key. The refusal message includes the posture name + the strategy that fails so audit-trail operators see exactly which gate blocked the call. **Security:** *Wrap envelope is the framework's hybrid PQC seal — ML-KEM-1024 + P-384 ECDH + SHAKE256 + XChaCha20-Poly1305* — Defence-in-depth posture: a CRQC against ML-KEM-1024 alone still has to defeat the classical P-384 ECDH leg; a future ECDH break alone still has to defeat ML-KEM-1024. The 4-byte envelope header (magic + KEM ID + cipher ID + KDF ID) is bound as AEAD AAD so a header-substitution attack fails Poly1305 verification. `b.archive.wrap` prepends a separate 6-byte archive-wrap header BEFORE the base64 envelope so format sniffing can identify wrap output without trial decryption — non-envelope inputs are refused at byte 0-4 (magic check) instead of after fruitless decapsulation work. **Detectors:** *`backup-adapter-storage-without-posture-check` — postures that mandate encryption must propagate to `cryptoStrategy`* — When a primitive that wires `b.backup.bundleAdapterStorage` carries a `posture:` opt drawn from the HIPAA / PCI-DSS / etc. set, the same code path must propagate `cryptoStrategy: "recipient"` (or refuse before reaching writeBundle). The detector matches `bundleAdapterStorage({ ... posture: ... })` invocations in `lib/` and requires a matching `cryptoStrategy` opt; missing it surfaces during the codebase-patterns gate so a future caller can't silently drop the contract. **Migration:** *Flavor 2 — per-entry ZIP recipient wrap with 0xBADC extra-field* — Per-entry encryption inside the carrier ZIP (method=STORE with the encrypted bytes as the stored payload + a 0xBADC user-defined-range extra-field marker carrying the recipient hint). Inspect-without-decrypt is the operator value: entry list + name-safety gating happens BEFORE any key resolution. Lands in v0.12.11 alongside the backup-crypto refactor. · *`lib/_crypto-base.js` refactor — backup-crypto, Flavor 1, Flavor 2 share substrate* — The legacy per-file Argon2id + XChaCha20-Poly1305 path in `lib/backup/crypto.js` gets factored into a private `_crypto-base.js` helper so all three encryption flavors compose the same primitive set. No operator-visible API change; closes the each-feature-rolls-its-own-crypto smell. · *`cryptoStrategy: "passphrase"` + tenant strategy* — Passphrase strategy on `bundleAdapterStorage` (Argon2id-derived key + XChaCha20-Poly1305) and the `"tenant"` recipient string (composes `b.vault.derivedKey({ tenant, purpose: "archive-wrap" })`) both ship in v0.12.11. The v0.12.10 surface is the recipient substrate; v0.12.11 lights up the per-tenant + passphrase strategies that consume it.
 
 - v0.12.9 (2026-05-23) — **`b.archive.gz` + `b.archive.read.gz` — gzip composition with `b.safeDecompress` bomb caps + `b.backup` `tar.gz` bundle format + `sha-to-tag verify` fetches `origin/main`.** gzip lands as the composition layer over the archive family. `b.archive.gz(bytes)` produces an RFC 1952 gzip stream with the same `toBuffer()` / `toAdapter(adapter)` / `digest()` shape every archive builder ships, and `b.archive.read.gz(adapter, opts)` reads it back through `b.safeDecompress` so a malicious `tar.gz` fails the gzip-layer bomb cap (1 GiB output / 100× ratio defaults) before the tar walker ever sees a decompressed byte. The reader exposes `toBuffer()` / `asTar(opts)` / `asZip(opts)` so operators can hand the decompressed bytes directly to a downstream archive reader without a round-trip through disk. `b.archive.tar().toGzip(adapter, opts)` is the write-side convenience for the most common combination. `b.backup.bundleAdapterStorage({ format: "tar.gz" })` adds gzip compression on the wire — bundle sizes drop ~3-5× on text-heavy backups (databases, JSON exports, mail spools); the readback path detects the format from the storage key suffix and composes `b.safeDecompress` automatically. The `sha-to-tag verify` workflow now explicitly fetches `origin/main` before walking the first-parent history, fixing a stale-ref bug that silently failed v0.12.6 through v0.12.8 tag verifications (the publish workflow itself was unaffected; the gate is independent). **Added:** *`b.archive.gz(bytes)` — standalone gzip write builder* — RFC 1952 gzip envelope with the standard archive-builder shape. `toBuffer()` returns the compressed bytes; `toAdapter(adapter)` writes through any writable adapter (fs / object-store / http) that exposes `.write(bytes)` + optional `.close()`; `digest()` returns a SHA3-512 hex hash of the compressed payload for operator integrity logs. `opts.level` accepts 0-9 (zlib default 6). Composes cleanly under `b.archive.tar().toGzip(adapter)` / `b.archive.zip()` for tar.gz / zip.gz convenience. · *`b.archive.read.gz(adapter, opts)` — gunzip reader with `b.safeDecompress` bomb caps* — Every decompression routes through `b.safeDecompress({ algorithm: "gzip", maxOutputBytes, maxRatio })` so a hostile gzip stream fails the bomb gate before any downstream parsing happens. Defaults: `maxDecompressedBytes` = 1 GiB, `maxExpansionRatio` = 100×. The reader exposes three downstream entry points: `toBuffer()` returns the raw decompressed bytes; `asTar(opts)` returns a `b.archive.read.tar` reader over the decompressed payload; `asZip(opts)` returns a `b.archive.read.zip` reader. `fromGzip` is the documented alias the spec uses (operators may reach for either). Refuses non-gzip input upfront via the `0x1f 0x8b` magic check (`archive-gz/bad-magic`). · *`b.archive.tar().toGzip(adapter, opts)` — tar.gz write convenience* — Pipes the tar builder's `toBuffer()` through `b.archive.gz()` and writes the resulting gzip envelope to a writable adapter. Equivalent to `b.archive.gz(t.toBuffer()).toAdapter(adapter)` but lets the operator stay in the tar-builder fluent chain when composing under fs / object-store / http adapters. · *`b.backup.bundleAdapterStorage({ format: "tar.gz" })` — compressed-on-the-wire bundles* — Adds gzip compression to the v0.12.8 tar bundle format. Bundle sizes drop ~3-5× on text-heavy backups (databases, JSON exports, mail spools); binary-heavy backups (compressed databases, encrypted archives) see ~1.0-1.1×. Read paths auto-detect via the `<bundleId>/bundle.tar.gz` storage key suffix and route through `b.safeDecompress` on readback. The v0.12.8 `maxBundleBytes` cap continues to gate against pathological projected-uncompressed sizes; `tar.gz` does not bypass it. · *`b.safeArchive.extract({ format: "tar.gz" })` — explicit tar.gz dispatch* — Operators handed a `.tar.gz` upload pass `format: "tar.gz"` explicitly; the orchestrator composes `b.archive.read.gz` → `.asTar()` and feeds the standard tar bomb-policy + entry-type-policy + guardProfile through. Defer-with-condition: auto-sniff for tar.gz (peek inside the gzip envelope for ustar magic at offset 257 of the decompressed prefix) lands when operator demand surfaces; today operators with `auto` mode on a `.tar.gz` payload get `format-unsupported gzip` with the explicit-format hint in the error message. **Fixed:** *`sha-to-tag verify` workflow fetches `origin/main` before first-parent walk* — The release-tag integrity gate runs on every `v*` tag push and verifies the tag's commit SHA appears on `main`'s first-parent history. `actions/checkout` was being asked for full history of the tag ref alone — `origin/main` wasn't fetched as a side effect, so `git rev-list --first-parent origin/main | grep -qx "$SHA"` walked a stale (or absent) ref and falsely refused. The check now explicitly fetches `origin/main` after checkout so the walk sees the current squash-merge HEAD. Affected releases (v0.12.6 / v0.12.7 / v0.12.8) had publish workflows that completed normally — `sha-to-tag verify` is an independent gate that was silently failing alongside successful publishes; nothing about the published artifacts was wrong. **Security:** *Bomb caps ride at the gz layer, not the tar/zip layer* — The decompression gate is enforced BEFORE the downstream archive reader sees any bytes — a hostile `tar.gz` that would decompress to 10 GiB of zero-filled tar entries fails the 1 GiB `maxDecompressedBytes` default cap during gunzip, never reaching the tar walker. Operators with legitimately large compressed archives pass `maxDecompressedBytes` higher; the framework refuses without an explicit opt-in. RFC 1952 §2.3.1 magic enforcement prevents content-type confusion (gzip-pretending-to-be-something-else inputs). **Detectors:** *`archive-gz-without-safedecompress` — direct `node:zlib` gunzip in `lib/` must compose `b.safeDecompress`* — Mirrors the v0.11.5 must-compose pattern: any `lib/` call to `zlib.gunzipSync` / `zlib.createGunzip` / `gunzip` outside `lib/archive-gz.js` (which IS the canonical gunzip site, with `b.safeDecompress` wired in) must carry an `allow:archive-gz-without-safedecompress` marker explaining why the bomb gate is bypassed. The detector locks the contract so v0.13+ work that touches a gzip-handling primitive can't quietly drop the cap.

package/index.js

@@ -442,6 +442,7 @@ module.exports = {
     input:           aiInput,
     aiContentDetect: require("./lib/ai-content-detect"),
     modelManifest:   require("./lib/ai-model-manifest"),
+    disclosure:      require("./lib/ai-disclosure"),
   },
   promisePool:      require("./lib/promise-pool"),
   sdNotify:         require("./lib/sd-notify"),

package/lib/ai-disclosure.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * @module b.ai.disclosure
+ * @nav    Compliance
+ * @title  AI Act Art. 50 disclosures
+ *
+ * @intro
+ *   EU AI Act Regulation (EU) 2024/1689 Article 50 transparency
+ *   obligations enter force 2026-08-02. This module ships the active
+ *   runtime primitives that emit disclosure markup at request time:
+ *
+ *   - `b.ai.disclosure.chatbot(session, opts)` — Art. 50(1).
+ *     Operators interacting with natural persons must disclose the
+ *     AI nature of the interaction. Returns the disclosure payload
+ *     (visible text / structured metadata) to wire into the response.
+ *
+ *   - `b.ai.disclosure.deepfake(content, opts)` — Art. 50(4).
+ *     Operators emitting AI-generated / AI-manipulated content
+ *     (image / audio / video / text) must label the output as
+ *     synthetic. Returns the disclosure payload + suggested
+ *     embedding points (visible label / C2PA metadata / both).
+ *
+ *   - `b.ai.disclosure.emotion(opts)` — Art. 50(3). Emotion-
+ *     recognition / biometric-categorisation systems must inform
+ *     the natural person of operation. Returns the notice payload.
+ *
+ *   Cross-jurisdiction:
+ *     - California AB-853 (effective 2026) — watermarking on
+ *       AI-generated content. The deepfake primitive emits both
+ *       AI Act Art. 50(4) AND AB-853 markup when `jurisdiction:
+ *       "us-ca"` is requested.
+ *     - China CAC GenAI Measures — content review marker. Same
+ *       primitive handles the cross-walk via the `jurisdiction:
+ *       "cn"` opt.
+ *
+ *   Composition:
+ *     - `b.audit-sign` chains every disclosure emission so the
+ *       Art. 50 compliance trail is tamper-evident.
+ *     - `b.agent.idempotency` (v0.9.22) ensures the chatbot
+ *       first-contact disclosure isn't double-emitted across
+ *       retry / reconnect.
+ *     - `b.contentCredentials` (v0.12.21 — deferred) will wire
+ *       C2PA manifest emission alongside the visible label.
+ *
+ *   Out of scope (this patch):
+ *     - C2PA manifest emission — defers to v0.12.21 b.contentCredentials.
+ *     - Watermark frame embedding into image/audio/video bytes —
+ *       operator's encoder pipeline (this primitive supplies the
+ *       label markup; the operator chooses the embed point).
+ *     - Real-time prohibited-content moderation — orthogonal,
+ *       composes with b.ai.input.refuseIfMalicious.
+ *
+ * @card
+ *   EU AI Act Art. 50 transparency obligation primitives — chatbot
+ *   disclosure, deepfake / synthetic-content labels, emotion-
+ *   recognition notices. Calendar-locked 2026-08-02.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var AiDisclosureError = defineClass("AiDisclosureError", { alwaysPermanent: true });
+
+// Audit emissions route through opts.audit (operator-supplied
+// instance) — see _emitAudit below. No framework-side audit
+// require needed; the primitive is a pure value-returning function
+// with the optional safeEmit-via-opts side-effect.
+
+var DEFAULT_CHATBOT_TEXT = "You are interacting with an AI system.";
+var DEFAULT_DEEPFAKE_TEXT = "This content has been generated or manipulated using artificial intelligence.";
+var DEFAULT_EMOTION_TEXT = "This system uses AI to recognise emotions or biometrically categorise individuals.";
+
+// Recognised jurisdiction codes. EU is implicit (the AI Act applies
+// throughout the Union); US-CA layers in AB-853; CN layers in the
+// CAC GenAI Measures.
+var SUPPORTED_JURISDICTIONS = ["eu", "us-ca", "cn"];
+
+// Content types eligible for a deepfake notice per Art. 50(4):
+// image / audio / video / text. Each carries different recommended
+// placement defaults (image+video → both label & metadata; audio →
+// audible preamble or metadata; text → visible disclaimer).
+var DEEPFAKE_CONTENT_TYPES = ["image", "audio", "video", "text"];
+
+/**
+ * @primitive b.ai.disclosure.chatbot
+ * @signature b.ai.disclosure.chatbot(session, opts)
+ * @since     0.12.12
+ * @status    stable
+ * @compliance eu-ai-act, ca-ab-853, cac-genai-label
+ * @related   b.ai.disclosure.deepfake, b.ai.disclosure.emotion, b.audit
+ *
+ * EU AI Act Art. 50(1) first-contact disclosure. Operators
+ * interacting with natural persons via an AI system must inform
+ * the person they are interacting with AI unless it is obvious from
+ * the circumstances (Art. 50(1) carve-out). This primitive returns
+ * the disclosure payload + emits an audit event per emission so
+ * the compliance trail is tamper-evident under `b.audit-sign`.
+ *
+ * @opts
+ *   placement:      "first-message" | "always" | "on-request",  // default "first-message"
+ *   language:       string,    // BCP 47 tag; defaults to en
+ *   text:           string,    // override the default disclosure text
+ *   jurisdiction:   string,    // "eu" (default) | "us-ca" | "cn"
+ *   audit:          object,    // b.audit instance for tamper-evident logging
+ *   correlationId:  string,    // audit chain correlation
+ *
+ * @example
+ *   var disclosure = b.ai.disclosure.chatbot({ id: "session-42" }, {
+ *     placement: "first-message",
+ *     language:  "en",
+ *   });
+ *   // disclosure.text   → "You are interacting with an AI system."
+ *   // disclosure.shouldEmit → true (first contact)
+ *   // operator wires disclosure.text into the response payload
+ */
+function chatbot(session, opts) {
+  opts = opts || {};
+  if (!session || typeof session !== "object") {
+    throw new AiDisclosureError("ai-disclosure/bad-session",
+      "chatbot: session must be an object carrying at minimum an id");
+  }
+  if (typeof session.id !== "string" || session.id.length === 0) {
+    throw new AiDisclosureError("ai-disclosure/bad-session",
+      "chatbot: session.id must be a non-empty string");
+  }
+  var placement = opts.placement || "first-message";
+  if (placement !== "first-message" && placement !== "always" && placement !== "on-request") {
+    throw new AiDisclosureError("ai-disclosure/bad-arg",
+      "chatbot: opts.placement must be \"first-message\" (default) | \"always\" | \"on-request\"; got " +
+      JSON.stringify(placement));
+  }
+  var jurisdiction = opts.jurisdiction || "eu";
+  _validateJurisdiction(jurisdiction, "chatbot");
+  var text = typeof opts.text === "string" && opts.text.length > 0
+    ? opts.text
+    : DEFAULT_CHATBOT_TEXT;
+  // Codex P1A on v0.12.12 PR #163 — "on-request" placement gates on
+  // the operator's explicit `opts.requested: true` signal. Without
+  // it, "on-request" collapsed into "always" semantics and emitted
+  // every call. The operator wires this from an explicit user
+  // gesture ("show me what AI features are in use") or an admin
+  // toggle. Default false so the gate stays closed when the opt
+  // isn't passed.
+  var requested = opts.requested === true;
+  var firstSeen = !session.aiDisclosureEmitted;
+  var shouldEmit = placement === "always" ||
+    (placement === "first-message" && firstSeen) ||
+    (placement === "on-request" && requested);
+  var emission = {
+    text:           text,
+    language:       opts.language || "en",
+    jurisdiction:   jurisdiction,
+    placement:      placement,
+    shouldEmit:     shouldEmit,
+    article:        "Art. 50(1)",
+    regulation:     "Regulation (EU) 2024/1689",
+  };
+  if (shouldEmit) {
+    // Codex P1B on v0.12.12 PR #163 — mark the session so subsequent
+    // calls with the same session under "first-message" placement
+    // see `aiDisclosureEmitted: true` and return shouldEmit=false.
+    // Without this mutation operators had to remember to flip the
+    // flag themselves; the default would re-emit on every call.
+    if (placement === "first-message") {
+      session.aiDisclosureEmitted = true;
+    }
+    _emitAudit(opts, "ai-act/chatbot-disclosure-applied", "success", {
+      sessionId:      session.id,
+      placement:      placement,
+      jurisdiction:   jurisdiction,
+      correlationId:  opts.correlationId || null,
+    });
+  }
+  return emission;
+}
+
+/**
+ * @primitive b.ai.disclosure.deepfake
+ * @signature b.ai.disclosure.deepfake(content, opts)
+ * @since     0.12.12
+ * @status    stable
+ * @compliance eu-ai-act, ca-ab-853, cac-genai-label
+ * @related   b.ai.disclosure.chatbot, b.contentCredentials
+ *
+ * EU AI Act Art. 50(4) synthetic-content disclosure. Operators
+ * emitting AI-generated or AI-manipulated content (image / audio /
+ * video / text) must label the output as synthetic in a clear and
+ * machine-readable manner. This primitive returns the disclosure
+ * payload (visible label + structured metadata) the operator wires
+ * into the encoder / response pipeline. C2PA manifest emission is
+ * deferred to v0.12.21 `b.contentCredentials` — this primitive
+ * supplies the label markup and the metadata schema that the C2PA
+ * adapter consumes when it lands.
+ *
+ * @opts
+ *   contentType:   "image" | "audio" | "video" | "text",        // required
+ *   placement:     "label" | "metadata" | "both",                // default "both"
+ *   jurisdiction:  string,    // "eu" (default) | "us-ca" | "cn"
+ *   language:      string,    // BCP 47 tag; defaults to en
+ *   text:          string,    // override the default disclosure text
+ *   audit:         object,
+ *   correlationId: string,
+ *
+ * @example
+ *   var disclosure = b.ai.disclosure.deepfake(imageBytes, {
+ *     contentType:  "image",
+ *     placement:    "both",
+ *     jurisdiction: "us-ca",
+ *   });
+ *   // disclosure.label    → "This content has been generated ..."
+ *   // disclosure.metadata → { ai_generated: true, schema: "c2pa-v1.4-ready" }
+ *   // disclosure.crossWalk → ["eu-ai-act/Art. 50(4)", "us-ca/AB-853 §22949.91"]
+ */
+function deepfake(content, opts) {
+  opts = opts || {};
+  if (content === undefined || content === null) {
+    throw new AiDisclosureError("ai-disclosure/bad-content",
+      "deepfake: content is required (Buffer | string | { type, bytes })");
+  }
+  if (typeof opts.contentType !== "string" ||
+      DEEPFAKE_CONTENT_TYPES.indexOf(opts.contentType) === -1) {
+    throw new AiDisclosureError("ai-disclosure/bad-arg",
+      "deepfake: opts.contentType must be one of " +
+      DEEPFAKE_CONTENT_TYPES.join(" | ") + "; got " + JSON.stringify(opts.contentType));
+  }
+  var placement = opts.placement || "both";
+  if (placement !== "label" && placement !== "metadata" && placement !== "both") {
+    throw new AiDisclosureError("ai-disclosure/bad-arg",
+      "deepfake: opts.placement must be \"label\" | \"metadata\" | \"both\" (default); got " +
+      JSON.stringify(placement));
+  }
+  var jurisdiction = opts.jurisdiction || "eu";
+  _validateJurisdiction(jurisdiction, "deepfake");
+  var text = typeof opts.text === "string" && opts.text.length > 0
+    ? opts.text
+    : DEFAULT_DEEPFAKE_TEXT;
+  var crossWalk = ["eu-ai-act/Art. 50(4)"];
+  if (jurisdiction === "us-ca") crossWalk.push("us-ca/AB-853 §22949.91");
+  if (jurisdiction === "cn") crossWalk.push("cn/CAC-GenAI Measures Art. 12");
+  var emission = {
+    label:          placement === "metadata" ? null : text,
+    metadata:       placement === "label" ? null : {
+      ai_generated:  true,
+      content_type:  opts.contentType,
+      schema:        "c2pa-v1.4-ready",                                              // v0.12.21 b.contentCredentials lights this up
+      jurisdiction:  jurisdiction,
+      regulation:    "Regulation (EU) 2024/1689",
+      article:       "Art. 50(4)",
+    },
+    language:       opts.language || "en",
+    contentType:    opts.contentType,
+    placement:      placement,
+    crossWalk:      crossWalk,
+  };
+  _emitAudit(opts, "ai-act/deepfake-disclosure-applied", "success", {
+    contentType:    opts.contentType,
+    placement:      placement,
+    jurisdiction:   jurisdiction,
+    correlationId:  opts.correlationId || null,
+  });
+  return emission;
+}
+
+/**
+ * @primitive b.ai.disclosure.emotion
+ * @signature b.ai.disclosure.emotion(opts)
+ * @since     0.12.12
+ * @status    stable
+ * @compliance eu-ai-act
+ * @related   b.ai.disclosure.chatbot, b.ai.disclosure.deepfake
+ *
+ * EU AI Act Art. 50(3) emotion-recognition / biometric-
+ * categorisation disclosure. Operators deploying these systems
+ * must inform the natural person of operation. Returns the notice
+ * payload the operator wires into the consent / pre-interaction
+ * flow.
+ *
+ * @opts
+ *   language:      string,
+ *   text:          string,
+ *   systemType:    "emotion" | "biometric-categorisation",   // default "emotion"
+ *   audit:         object,
+ *   correlationId: string,
+ *
+ * @example
+ *   var notice = b.ai.disclosure.emotion({ systemType: "emotion" });
+ *   // notice.text → "This system uses AI to recognise emotions ..."
+ *   // notice.article → "Art. 50(3)"
+ */
+function emotion(opts) {
+  opts = opts || {};
+  var systemType = opts.systemType || "emotion";
+  if (systemType !== "emotion" && systemType !== "biometric-categorisation") {
+    throw new AiDisclosureError("ai-disclosure/bad-arg",
+      "emotion: opts.systemType must be \"emotion\" (default) | \"biometric-categorisation\"; got " +
+      JSON.stringify(systemType));
+  }
+  var text = typeof opts.text === "string" && opts.text.length > 0
+    ? opts.text
+    : DEFAULT_EMOTION_TEXT;
+  var emission = {
+    text:           text,
+    language:       opts.language || "en",
+    systemType:     systemType,
+    article:        "Art. 50(3)",
+    regulation:     "Regulation (EU) 2024/1689",
+  };
+  _emitAudit(opts, "ai-act/emotion-disclosure-applied", "success", {
+    systemType:     systemType,
+    correlationId:  opts.correlationId || null,
+  });
+  return emission;
+}
+
+function _validateJurisdiction(jurisdiction, primitive) {
+  if (SUPPORTED_JURISDICTIONS.indexOf(jurisdiction) === -1) {
+    throw new AiDisclosureError("ai-disclosure/bad-jurisdiction",
+      primitive + ": opts.jurisdiction must be one of " +
+      SUPPORTED_JURISDICTIONS.join(" | ") + " (eu = default; us-ca = California AB-853; " +
+      "cn = China CAC GenAI Measures); got " + JSON.stringify(jurisdiction));
+  }
+}
+
+function _emitAudit(opts, action, outcome, metadata) {
+  if (!opts.audit || typeof opts.audit.safeEmit !== "function") return;
+  try {
+    opts.audit.safeEmit({
+      action:    action,
+      outcome:   outcome,
+      metadata:  metadata || {},
+    });
+  } catch (_e) {
+    // drop-silent — audit emit failure cannot crash the disclosure
+    // path. The Art. 50 obligation is the user-facing notice the
+    // primitive returns; the audit emission is a parallel best-
+    // effort chain-of-custody record. Throwing here would refuse
+    // the disclosure to defend the audit chain, which fails the
+    // wrong direction (the regulatory contract is satisfied by
+    // emitting the notice; the audit trail backs it up).
+  }
+}
+
+module.exports = {
+  chatbot:                  chatbot,
+  deepfake:                 deepfake,
+  emotion:                  emotion,
+  AiDisclosureError:        AiDisclosureError,
+  SUPPORTED_JURISDICTIONS:  Object.freeze(SUPPORTED_JURISDICTIONS.slice()),
+  DEEPFAKE_CONTENT_TYPES:   Object.freeze(DEEPFAKE_CONTENT_TYPES.slice()),
+};

package/lib/archive-wrap.js

@@ -28,15 +28,23 @@ var { defineClass } = require("./framework-error");
 var ArchiveWrapError = defineClass("ArchiveWrapError", { alwaysPermanent: true });
 
 var bCrypto = lazyRequire(function () { return require("./crypto"); });
+var backupCrypto = lazyRequire(function () { return require("./backup/crypto"); });
 
 // Envelope magic — 5-byte ASCII prefix the safe-archive sniffer
 // recognises. Distinct from b.crypto.encrypt's base64 envelope so
 // archive-wrap output can carry an unambiguous "this is an archive
-// recipient-wrap envelope" magic before the operator-controlled
-// payload.
-var ARCH_WRAP_MAGIC = "BAWRP";                                                       // allow:raw-byte-literal — 5-byte ASCII archive-wrap envelope magic
-var ARCH_WRAP_VERSION = 0x01;                                                        // allow:raw-byte-literal — version byte
+// wrap envelope" magic before the operator-controlled payload.
+var ARCH_WRAP_MAGIC = "BAWRP";                                                       // allow:raw-byte-literal — 5-byte ASCII archive-wrap recipient envelope magic
+var ARCH_WRAP_VERSION = 0x01;                                                        // allow:raw-byte-literal — recipient version byte
 var ARCH_WRAP_HEADER_BYTES = C.BYTES.bytes(6);                                        // magic(5) + version(1)
+// Passphrase variant — wire format: magic(5) + version(1) + saltLen(1)
+// + salt(saltLen bytes) + encrypted bytes (24-byte nonce + ciphertext+tag
+// from backup-crypto encryptWithPassphrase). The salt-prefix shape
+// lets the framework rotate KDF parameters in future minors without
+// per-envelope version bumps (each envelope carries its own salt).
+var ARCH_PASSPHRASE_MAGIC = "BAWPP";                                                 // allow:raw-byte-literal — 5-byte passphrase-wrap envelope magic
+var ARCH_PASSPHRASE_VERSION = 0x01;                                                  // allow:raw-byte-literal — passphrase version byte
+var ARCH_PASSPHRASE_HEADER_BYTES = C.BYTES.bytes(7);                                  // magic(5) + version(1) + saltLen(1)
 
 /**
  * @primitive b.archive.wrap
@@ -227,11 +235,213 @@ function _isWrapMagic(buf) {
     buf.slice(0, 5).toString("ascii") === ARCH_WRAP_MAGIC;
 }
 
+function _isPassphraseMagic(buf) {
+  return buf.length >= ARCH_PASSPHRASE_HEADER_BYTES &&
+    buf.slice(0, 5).toString("ascii") === ARCH_PASSPHRASE_MAGIC;
+}
+
+/**
+ * @primitive b.archive.wrapWithPassphrase
+ * @signature b.archive.wrapWithPassphrase(bytes, opts)
+ * @since     0.12.11
+ * @status    stable
+ * @related   b.archive.unwrapWithPassphrase, b.archive.wrap, b.backupCrypto
+ *
+ * Wrap archive bytes in a passphrase-derived envelope. The envelope
+ * wire format is the framework's standard Argon2id (RFC 9106) +
+ * XChaCha20-Poly1305 AEAD with a fresh per-envelope salt prefixed in
+ * a 7-byte `BAWPP` header (5-byte magic + 1-byte version + 1-byte
+ * salt length). Operators choosing the passphrase strategy (vs the
+ * recipient strategy from `b.archive.wrap`) reach for this primitive
+ * when they don't want to manage KEM keypairs but do want
+ * encryption-at-rest under operator-controlled material.
+ *
+ * @opts
+ *   passphrase:           Buffer | string,   // required; >= minEntropyBits
+ *   minEntropyBits:       number,            // default 80; HIPAA recipe sets 128
+ *
+ * @example
+ *   var sealed = await b.archive.wrapWithPassphrase(tarBytes, {
+ *     passphrase:     "operator-supplied-long-passphrase",
+ *     minEntropyBits: 128,
+ *   });
+ */
+async function wrapWithPassphrase(bytes, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+    throw new ArchiveWrapError("archive-wrap/bad-input",
+      "wrapWithPassphrase: bytes must be a Buffer or Uint8Array");
+  }
+  if (bytes.length === 0) {
+    throw new ArchiveWrapError("archive-wrap/empty-input",
+      "wrapWithPassphrase: bytes is empty");
+  }
+  if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
+    throw new ArchiveWrapError("archive-wrap/no-passphrase",
+      "wrapWithPassphrase: opts.passphrase is required (string or Buffer)");
+  }
+  var passLen = typeof opts.passphrase === "string"
+    ? Buffer.byteLength(opts.passphrase, "utf-8")
+    : opts.passphrase.length;
+  // Entropy estimate — character-set-aware bit count via Shannon's
+  // bound assuming uniform random selection over the observed
+  // alphabet. Operators sourcing passphrases from a random-bytes
+  // generator (high entropy density) pass without issue; operators
+  // typing dictionary phrases trip the gate.
+  // Codex P1 on v0.12.11 PR #162 — typeof NaN === "number" passes
+  // typeof gate but bypasses downstream comparisons. Use isFinite
+  // so NaN / Infinity can't slip past the entropy gate.
+  var minEntropy;
+  if (opts.minEntropyBits === undefined || opts.minEntropyBits === null) {
+    minEntropy = 80;                                                                  // allow:raw-byte-literal — entropy-bits default, not byte count
+  } else if (Number.isFinite(opts.minEntropyBits) && opts.minEntropyBits >= 0) {
+    minEntropy = Math.floor(opts.minEntropyBits);
+  } else {
+    throw new ArchiveWrapError("archive-wrap/bad-arg",
+      "wrapWithPassphrase: opts.minEntropyBits must be a finite non-negative number; got " +
+      JSON.stringify(opts.minEntropyBits) + " (NaN / Infinity refused so the entropy gate can't be bypassed)");
+  }
+  var estimated = _estimatePassphraseEntropyBits(opts.passphrase);
+  if (estimated < minEntropy) {
+    throw new ArchiveWrapError("archive-wrap/weak-passphrase",
+      "wrapWithPassphrase: passphrase estimated entropy " + estimated +
+      " bits is below opts.minEntropyBits=" + minEntropy +
+      " (length=" + passLen + " bytes). Strengthen the passphrase or lower the gate; " +
+      "HIPAA recipe is 128+ bits.");
+  }
+  var fresh = await backupCrypto().encryptWithFreshSalt(bytes, opts.passphrase);
+  var saltBytes = Buffer.from(fresh.salt, "hex");
+  if (saltBytes.length > 0xff) {
+    throw new ArchiveWrapError("archive-wrap/salt-too-long",
+      "wrapWithPassphrase: salt length " + saltBytes.length +
+      " exceeds 255-byte wire limit");
+  }
+  var header = Buffer.alloc(ARCH_PASSPHRASE_HEADER_BYTES);
+  header.write(ARCH_PASSPHRASE_MAGIC, 0, 5, "ascii");
+  header[5] = ARCH_PASSPHRASE_VERSION;
+  header[6] = saltBytes.length;
+  return Buffer.concat([header, saltBytes, fresh.encrypted]);
+}
+
+/**
+ * @primitive b.archive.unwrapWithPassphrase
+ * @signature b.archive.unwrapWithPassphrase(sealed, opts)
+ * @since     0.12.11
+ * @status    stable
+ * @related   b.archive.wrapWithPassphrase
+ *
+ * Recover archive bytes from a passphrase-derived envelope produced
+ * by `b.archive.wrapWithPassphrase`. Verifies the 7-byte `BAWPP`
+ * header before attempting key derivation so non-envelope inputs
+ * fail with `archive-wrap/bad-magic` rather than burning Argon2id
+ * compute on bad bytes.
+ *
+ * @opts
+ *   passphrase:  Buffer | string,   // required; same passphrase used at wrap-time
+ *
+ * @example
+ *   var recovered = await b.archive.unwrapWithPassphrase(sealed, {
+ *     passphrase: "operator-supplied-long-passphrase",
+ *   });
+ */
+async function unwrapWithPassphrase(sealed, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(sealed) && !(sealed instanceof Uint8Array)) {
+    throw new ArchiveWrapError("archive-wrap/bad-input",
+      "unwrapWithPassphrase: sealed must be a Buffer or Uint8Array");
+  }
+  if (sealed.length < ARCH_PASSPHRASE_HEADER_BYTES) {
+    throw new ArchiveWrapError("archive-wrap/bad-magic",
+      "unwrapWithPassphrase: input shorter than 7-byte BAWPP header");
+  }
+  var buf = Buffer.isBuffer(sealed) ? sealed : Buffer.from(sealed);
+  var magic = buf.slice(0, 5).toString("ascii");
+  if (magic !== ARCH_PASSPHRASE_MAGIC) {
+    throw new ArchiveWrapError("archive-wrap/bad-magic",
+      "unwrapWithPassphrase: input does not start with passphrase-wrap magic " +
+      JSON.stringify(ARCH_PASSPHRASE_MAGIC) + "; got " + JSON.stringify(magic));
+  }
+  var version = buf[5];
+  if (version !== ARCH_PASSPHRASE_VERSION) {
+    throw new ArchiveWrapError("archive-wrap/bad-version",
+      "unwrapWithPassphrase: passphrase-wrap version " + version + " not supported");
+  }
+  if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
+    throw new ArchiveWrapError("archive-wrap/no-passphrase",
+      "unwrapWithPassphrase: opts.passphrase is required");
+  }
+  var saltLen = buf[6];
+  if (sealed.length < ARCH_PASSPHRASE_HEADER_BYTES + saltLen) {
+    throw new ArchiveWrapError("archive-wrap/truncated-envelope",
+      "unwrapWithPassphrase: header claims " + saltLen + "-byte salt but only " +
+      (sealed.length - ARCH_PASSPHRASE_HEADER_BYTES) + " bytes remain");
+  }
+  var saltHex = buf.slice(ARCH_PASSPHRASE_HEADER_BYTES,
+    ARCH_PASSPHRASE_HEADER_BYTES + saltLen).toString("hex");
+  var encrypted = buf.slice(ARCH_PASSPHRASE_HEADER_BYTES + saltLen);
+  try {
+    return await backupCrypto().decryptWithPassphrase(encrypted, opts.passphrase, saltHex);
+  } catch (e) {
+    var err = new ArchiveWrapError("archive-wrap/decrypt-failed",
+      "unwrapWithPassphrase: decryption refused (wrong passphrase or tampered envelope): " +
+      ((e && e.message) || String(e)));
+    err.cause = e;
+    throw err;
+  }
+}
+
+function _estimatePassphraseEntropyBits(passphrase) {
+  // Codex P2 on v0.12.11 PR #162 — Buffer passphrases (CSPRNG-
+  // generated random bytes) shouldn't be UTF-8 decoded for entropy
+  // estimation; the decoding artifacts (invalid sequences, BOM,
+  // surrogate pairs) make the alphabet-class measure unstable and
+  // falsely reject strong random buffers. Treat Buffer input as
+  // raw bytes: observed-alphabet bit count over the byte values
+  // gives a stable approximation that credits CSPRNG output
+  // correctly (a 16-byte buffer with full byte variation scores
+  // 16 * log2(16+) ≈ 64-128 bits) and refuses all-zero buffers
+  // (alphabet=1, score 0).
+  if (Buffer.isBuffer(passphrase)) {
+    if (passphrase.length === 0) return 0;
+    var seen = new Set();
+    for (var bi = 0; bi < passphrase.length; bi += 1) {
+      seen.add(passphrase[bi]);
+    }
+    var byteAlphabet = seen.size;
+    if (byteAlphabet === 0) return 0;
+    return Math.floor(passphrase.length * Math.log2(byteAlphabet));
+  }
+  var s = typeof passphrase === "string" ? passphrase : String(passphrase);
+  if (s.length === 0) return 0;
+  // String passphrases — operator-typed phrases. Observed character-
+  // class alphabet count. log2(alphabetSize) bits per character is
+  // the standard NIST/OWASP "estimate by character classes" measure.
+  var hasLower = false, hasUpper = false, hasDigit = false, hasSpecial = false;
+  for (var i = 0; i < s.length; i += 1) {
+    var c = s.charCodeAt(i);
+    if (c >= 0x61 && c <= 0x7a) hasLower = true;
+    else if (c >= 0x41 && c <= 0x5a) hasUpper = true;
+    else if (c >= 0x30 && c <= 0x39) hasDigit = true;
+    else hasSpecial = true;
+  }
+  var alphabet = 0;
+  if (hasLower) alphabet += 26;                                                       // allow:raw-byte-literal — alphabet-size term, not byte count
+  if (hasUpper) alphabet += 26;                                                       // allow:raw-byte-literal — alphabet-size term, not byte count
+  if (hasDigit) alphabet += 10;                                                       // allow:raw-byte-literal — alphabet-size term, not byte count
+  if (hasSpecial) alphabet += 32;                                                     // allow:raw-byte-literal — alphabet-size term, not byte count
+  if (alphabet === 0) return 0;
+  return Math.floor(s.length * Math.log2(alphabet));
+}
+
 module.exports = {
-  wrap:             wrap,
-  unwrap:           unwrap,
-  ArchiveWrapError: ArchiveWrapError,
+  wrap:                  wrap,
+  unwrap:                unwrap,
+  wrapWithPassphrase:    wrapWithPassphrase,
+  unwrapWithPassphrase:  unwrapWithPassphrase,
+  ArchiveWrapError:      ArchiveWrapError,
   // Exposed for sibling modules + sniffer
-  _isWrapMagic:     _isWrapMagic,
-  ARCH_WRAP_MAGIC:  ARCH_WRAP_MAGIC,
+  _isWrapMagic:          _isWrapMagic,
+  _isPassphraseMagic:    _isPassphraseMagic,
+  ARCH_WRAP_MAGIC:       ARCH_WRAP_MAGIC,
+  ARCH_PASSPHRASE_MAGIC: ARCH_PASSPHRASE_MAGIC,
 };

package/lib/archive.js

@@ -549,11 +549,13 @@ var archiveGz = require("./archive-gz");
 var archiveWrap = require("./archive-wrap");
 
 module.exports = {
-  zip:               zip,
-  tar:               archiveTar.tar,
-  gz:                archiveGz.gz,
-  wrap:              archiveWrap.wrap,
-  unwrap:            archiveWrap.unwrap,
+  zip:                  zip,
+  tar:                  archiveTar.tar,
+  gz:                   archiveGz.gz,
+  wrap:                 archiveWrap.wrap,
+  unwrap:               archiveWrap.unwrap,
+  wrapWithPassphrase:   archiveWrap.wrapWithPassphrase,
+  unwrapWithPassphrase: archiveWrap.unwrapWithPassphrase,
   ArchiveError:      ArchiveError,
   TarError:          archiveTar.TarError,
   ArchiveGzError:    archiveGz.ArchiveGzError,

package/lib/backup/index.js

@@ -1083,11 +1083,11 @@ function bundleAdapterStorage(opts) {
   //                 BACKUP_ENCRYPTION_REQUIRED_POSTURES) REFUSE
   //                 "none" + require "recipient".
   var cryptoStrategy = opts.cryptoStrategy || "none";
-  if (cryptoStrategy !== "none" && cryptoStrategy !== "recipient") {
+  if (cryptoStrategy !== "none" && cryptoStrategy !== "recipient" &&
+      cryptoStrategy !== "passphrase") {
     throw new BackupError("backup/bad-crypto-strategy",
-      "bundleAdapterStorage: cryptoStrategy must be \"none\" (default — adapter-encrypted storage) " +
-      "or \"recipient\" (v0.12.10 — wraps bundle bytes in a hybrid PQC envelope before writeFile). " +
-      "Passphrase strategy is deferred to v0.12.11.");
+      "bundleAdapterStorage: cryptoStrategy must be \"none\" (default — adapter-encrypted storage), " +
+      "\"recipient\" (v0.12.10 — hybrid PQC envelope wrap), or \"passphrase\" (v0.12.11 — Argon2id + XChaCha20-Poly1305 wrap)");
   }
   var recipient = opts.recipient;
   if (cryptoStrategy === "recipient" && (!recipient || typeof recipient !== "object")) {
@@ -1096,29 +1096,67 @@ function bundleAdapterStorage(opts) {
       "({ publicKey, ecPublicKey } for the hybrid PQC envelope OR { peerCertDer, peerKemPubkey } " +
       "for the peer-cert envelope)");
   }
-  // Codex P1 on v0.12.10 PR #161 — the wrap layer composes only
-  // with the tar / tar.gz writeBundle branches. Pairing recipient
-  // strategy with format: "directory" would silently write plaintext
-  // per-file payloads because the directory branch doesn't apply
-  // the envelope. Refuse the combination upfront so operators see
-  // the contract gap rather than discover it via disk inspection.
-  // Per-file recipient encryption for directory format is a v0.12.11
-  // follow-up alongside the _crypto-base.js refactor.
-  if (cryptoStrategy === "recipient" && format === "directory") {
-    throw new BackupError("backup/recipient-strategy-needs-bundled-format",
-      "bundleAdapterStorage: cryptoStrategy: \"recipient\" requires format: \"tar\" or \"tar.gz\". " +
-      "Directory format writes per-file plaintext to the adapter — the wrap layer composes only " +
-      "with tar / tar.gz bundles in v0.12.10. Per-file recipient encryption is a v0.12.11 follow-up.");
+  var passphrase = opts.passphrase;
+  // HIPAA + PCI-DSS recipe raises the floor to 128 bits (per
+  // BACKUP_ENCRYPTION_REQUIRED_POSTURES below); default 80 matches
+  // OWASP "strong password" guidance for generic deployments.
+  // Codex P1 on v0.12.11 PR #162 — typeof NaN === "number" and
+  // typeof Infinity === "number" both pass the typeof gate but
+  // bypass downstream comparisons (NaN < 128 is false; estimated
+  // < NaN is false). Use Number.isFinite + a finite integer check
+  // so the entropy floor can't be NaN'd out under HIPAA.
+  var passphraseMinEntropyBits;
+  if (opts.passphraseMinEntropyBits === undefined ||
+      opts.passphraseMinEntropyBits === null) {
+    passphraseMinEntropyBits = 80;                                                    // allow:raw-byte-literal — entropy-bits default floor, not byte count
+  } else if (Number.isFinite(opts.passphraseMinEntropyBits) &&
+             opts.passphraseMinEntropyBits >= 0) {
+    passphraseMinEntropyBits = Math.floor(opts.passphraseMinEntropyBits);
+  } else {
+    throw new BackupError("backup/bad-arg",
+      "bundleAdapterStorage: passphraseMinEntropyBits must be a finite non-negative number; " +
+      "got " + JSON.stringify(opts.passphraseMinEntropyBits) +
+      " (NaN / Infinity are refused upfront so the HIPAA / PCI-DSS 128-bit floor can't be bypassed)");
+  }
+  if (cryptoStrategy === "passphrase") {
+    if (typeof passphrase !== "string" && !Buffer.isBuffer(passphrase)) {
+      throw new BackupError("backup/no-passphrase",
+        "bundleAdapterStorage: cryptoStrategy: \"passphrase\" requires opts.passphrase " +
+        "(string or Buffer; Argon2id key derivation + XChaCha20-Poly1305 AEAD). " +
+        "passphraseMinEntropyBits defaults to 80; HIPAA / PCI-DSS postures raise the floor to 128.");
+    }
+  }
+  // Codex P1 on v0.12.10 PR #161 — the wrap layers (recipient AND
+  // passphrase) compose only with the tar / tar.gz writeBundle
+  // branches. Pairing encryption strategy with format: "directory"
+  // would silently write plaintext per-file payloads. Refuse upfront
+  // so operators see the contract gap rather than discover it via
+  // disk inspection. Per-file encryption for directory format is a
+  // future patch alongside the _crypto-base.js refactor.
+  if ((cryptoStrategy === "recipient" || cryptoStrategy === "passphrase") &&
+      format === "directory") {
+    throw new BackupError("backup/" + cryptoStrategy + "-strategy-needs-bundled-format",
+      "bundleAdapterStorage: cryptoStrategy: " + JSON.stringify(cryptoStrategy) +
+      " requires format: \"tar\" or \"tar.gz\". Directory format writes per-file plaintext to " +
+      "the adapter — the wrap layer composes only with tar / tar.gz bundles. Per-file " +
+      "encryption for directory format is a future patch alongside the _crypto-base.js refactor.");
   }
   var posture = opts.posture;
-  if (posture && BACKUP_ENCRYPTION_REQUIRED_POSTURES.indexOf(posture) !== -1 &&
-      cryptoStrategy === "none") {
-    throw new BackupError("backup/posture-requires-encryption",
-      "bundleAdapterStorage: posture=" + JSON.stringify(posture) +
-      " requires cryptoStrategy: \"recipient\" (the adapter-storage layer cannot itself " +
-      "satisfy HIPAA / PCI-DSS encryption-at-rest with cryptoStrategy: \"none\"). " +
-      "The recipient+directory combination is refused separately so operators don't slip " +
-      "plaintext per-file payloads past the posture gate.");
+  if (posture && BACKUP_ENCRYPTION_REQUIRED_POSTURES.indexOf(posture) !== -1) {
+    if (cryptoStrategy === "none") {
+      throw new BackupError("backup/posture-requires-encryption",
+        "bundleAdapterStorage: posture=" + JSON.stringify(posture) +
+        " requires cryptoStrategy: \"recipient\" or \"passphrase\" (the adapter-storage layer " +
+        "cannot itself satisfy HIPAA / PCI-DSS encryption-at-rest with cryptoStrategy: \"none\"). " +
+        "The recipient+directory and passphrase+directory combinations are refused separately so " +
+        "operators don't slip plaintext per-file payloads past the posture gate.");
+    }
+    // v0.12.11 — passphrase strategy under HIPAA / PCI-DSS raises
+    // the entropy floor to 128 bits (matches the framework's
+    // existing crypto-grade-password discipline for sealed-storage).
+    if (cryptoStrategy === "passphrase" && passphraseMinEntropyBits < 128) {          // allow:raw-byte-literal — entropy-bits floor, not byte count
+      passphraseMinEntropyBits = 128;                                                  // allow:raw-byte-literal — entropy-bits floor, not byte count
+    }
   }
   // Codex P2 on v0.12.8 PR #159 — tar mode builds the whole archive
   // in memory before adapter.writeFile because the v0.12.8 adapter
@@ -1229,6 +1267,11 @@ function bundleAdapterStorage(opts) {
           : t.toBuffer();
         if (cryptoStrategy === "recipient") {
           payloadBytes = archiveLazy().wrap(payloadBytes, { recipient: recipient });
+        } else if (cryptoStrategy === "passphrase") {
+          payloadBytes = await archiveLazy().wrapWithPassphrase(payloadBytes, {
+            passphrase:     passphrase,
+            minEntropyBits: passphraseMinEntropyBits,
+          });
         }
         await adapter.writeFile(bundleId + keySuffix, payloadBytes);
         return;
@@ -1272,6 +1315,8 @@ function bundleAdapterStorage(opts) {
         var gzBytes = await adapter.readFile(bundleId + TAR_GZ_KEY_SUFFIX);
         if (cryptoStrategy === "recipient") {
           gzBytes = archiveLazy().unwrap(gzBytes, { recipient: recipient });
+        } else if (cryptoStrategy === "passphrase") {
+          gzBytes = await archiveLazy().unwrapWithPassphrase(gzBytes, { passphrase: passphrase });
         }
         var gzReader = archiveLazy().read.gz(archiveAdaptersLazy().buffer(gzBytes), {
           maxDecompressedBytes: maxBundleBytes,
@@ -1285,6 +1330,8 @@ function bundleAdapterStorage(opts) {
         var tarBytes = await adapter.readFile(bundleId + TAR_KEY_SUFFIX);
         if (cryptoStrategy === "recipient") {
           tarBytes = archiveLazy().unwrap(tarBytes, { recipient: recipient });
+        } else if (cryptoStrategy === "passphrase") {
+          tarBytes = await archiveLazy().unwrapWithPassphrase(tarBytes, { passphrase: passphrase });
         }
         var reader = archiveLazy().read.tar(archiveAdaptersLazy().buffer(tarBytes));
         await reader.extract({ destination: destDir });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.10",
+  "version": "0.12.12",
   "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:15ca08ce-3216-4a0c-bd31-d9c198e71e36",
+  "serialNumber": "urn:uuid:c9470d27-8ecf-46a8-8a75-2a26724c7831",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T19:05:59.300Z",
+    "timestamp": "2026-05-23T22:09:15.262Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.10",
+      "bom-ref": "@blamejs/core@0.12.12",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.10",
+      "version": "0.12.12",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.10",
+      "purl": "pkg:npm/%40blamejs/core@0.12.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.10",
+      "ref": "@blamejs/core@0.12.12",
       "dependsOn": []
     }
   ]