@blamejs/blamejs-shop 0.4.31 → 0.4.33

package/lib/vendor/blamejs/SECURITY.md

@@ -283,7 +283,7 @@ This is the minimum-viable security posture for a production deployment. The fra
 - [ ] Confirm `vault: { mode: "wrapped" }` in the app's config (not `"plaintext"`)
 - [ ] Store the passphrase in a secret manager (1Password / Vault / AWS Secrets Manager / sops) — never in git, never in shell history
 - [ ] Rotate the vault passphrase quarterly: `blamejs vault rotate`
-- [ ] When rotating the vault *keypair* (not just the passphrase) with `b.vaultRotate.rotate`, first re-seal every 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) and re-wrap tenant archives with `b.archive.rewrapTenant`, then pass `externalAadResealed` naming each re-sealed store (or `true` if you use none of them). Rotation refuses rather than silently orphaning a store it cannot reach, and its round-trip verify decrypts AAD-sealed cells under the new keypair and flags any that still open under the old one. Declare the rotation to each cluster node with `acceptVaultKeyRotation: true` so the membership adopts the new fingerprint instead of reporting `VAULT_KEY_DRIFT`
+- [ ] When rotating the vault *keypair* (not just the passphrase) with `b.vaultRotate.rotate`, first re-seal every 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 / `b.dsr.reseal` for a database-backed DSR ticket store) and re-wrap tenant archives with `b.archive.rewrapTenant`, then pass `externalAadResealed` naming each re-sealed store (or `true` if you use none of them). Rotation refuses rather than silently orphaning a store it cannot reach, and its round-trip verify decrypts AAD-sealed cells under the new keypair and flags any that still open under the old one. Declare the rotation to each cluster node with `acceptVaultKeyRotation: true` so the membership adopts the new fingerprint instead of reporting `VAULT_KEY_DRIFT`
 - [ ] In FIPS / regulated deployments, run `b.crypto.selfTest()` at start-up as a power-on integrity gate — it KATs SHA3/SHAKE against NIST FIPS 202 vectors and pairwise-tests ML-KEM-1024 / ML-DSA-87 / SLH-DSA-SHAKE-256f, throwing `crypto/self-test-failed` (fail closed) if the crypto stack is broken
 
 **Audit chain**
@@ -335,16 +335,18 @@ This is the minimum-viable security posture for a production deployment. The fra
 - [ ] For destructive operations (data purge, key rotation, financial close), wire `b.dualControl.create({ minApprovers: 2, consumeLockMs: C.TIME.minutes(2), approverRoles: ["security-officer"], minReasonLength: 20 })` and gate the consumer on `consume(grantId).ready`
 - [ ] For Postgres backends serving narrowed views or row-level-security policies, mount `b.middleware.dbRoleFor` so the request-time DB role is bound from the actor's permissions role; pair `b.db.declareRowPolicy` migrations with `b.externalDb.transaction({ sessionGucs })` for per-tenant binding
 - [ ] For password-using auth: configure `b.auth.password.policy({ profile: "pci-4.0" })` (or `nist-aal2` / `hipaa-aal2`) and call `policy.check()` on every signup AND password change; pass `policy.shouldRotate(passwordSetAt)` through the login response so the UI can prompt rotation; pass the user's last-N stored hashes to `policy.reuseProhibited()` on change flows
-- [ ] For session security: pass `{ req }` to `b.session.create()` and `b.session.verify()` so the IP / UA fingerprint is captured and checked; for high-value sessions (admin, finance) set `requireFingerprintMatch: true` OR `maxAnomalyScore: 0.7` with an operator-supplied `scorer(input)` function (impossible-travel detection, geo-distance, etc.)
+- [ ] For session security: pass `{ req }` to `b.session.create()` and `b.session.verify()` so the IP / UA fingerprint is captured and checked; for high-value sessions (admin, finance) set `requireFingerprintMatch: true` OR `maxAnomalyScore: 0.7` with an operator-supplied `scorer(input)` function (impossible-travel detection, geo-distance, etc.). When rotating a session at a privilege boundary (login, MFA, role change), pass the same `{ req, fingerprintFields }` to `b.session.rotate()` so the device binding re-keys to the new session id — a fingerprint-bound session rotated without `req` is refused, because the binding cannot follow the new id and would otherwise silently break or false-drift the user out on the next request
+- [ ] For RFC 9449 DPoP proof-of-possession deployments: wire `b.middleware.dpop` with a `replayStore` (a `b.nonceStore`-shaped `{ checkAndInsert }`, e.g. `b.nonceStore.create({ backend })`) — it is required at mount time, so single-use jti-replay defense is always enforced. Mounting the middleware without the store (or with one lacking `checkAndInsert`) throws at config time rather than failing open at request time with no replay defense (RFC 9449 §11.1)
 - [ ] For inbound admin paths reachable on the public network: mount `b.middleware.networkAllowlist({ paths: ["/admin"], allowedCidrs: [...] })` as the in-process CIDR fence above the application-layer auth gate
 - [ ] For outbound integrations: pin destination hosts via `b.httpClient.request({ allowedHosts: ["api.partner.com", ".internal.example.com"] })` so a compromised process can't reach arbitrary upstreams
 - [ ] For test suites that mount a mock server on `127.0.0.1` to exercise `b.httpClient` / `b.wsClient` against deterministic fixtures: keep the SSRF gate ON in production code, then in tests inject an explicit `allowInternal: true` (per-call) alongside the mock-server URL. The opt-in is loud and audited, the production posture is unchanged, and operators reviewing the test grep see exactly which call sites talk to internal addresses. Cloud-metadata IPs (`169.254.169.254` etc.) stay hard-deny under any `allowInternal` value
+- [ ] Before comparing a URL against an allowlist/denylist, building a cache/dedup key from one, or deciding whether a host is internal: canonicalize it with `b.safeUrl.canonicalize(url)` (or `b.ssrfGuard.canonicalizeHost(host)` for the host alone) first. It collapses obfuscated host + IP spellings — decimal / octal / hex / dotted IPv4, zero-compressed IPv6, IDN → punycode (rejecting confusable hosts), default ports, trailing-dot hosts (every count), path percent-encoding — to one comparable string, so `0177.0.0.1`, `0x7f.1`, `2130706433`, and `127.0.0.1` can't slip past a check that only string-matched the literal. An IPv4-mapped IPv6 host (`::ffff:1.2.3.4`) folds to its embedded IPv4 so a dual-stack peer unifies with a dotted-IPv4 entry, and credentials are dropped from the canonical form (NAT64 / 6to4 stay IPv6 so canonicalize-then-classify agrees with the SSRF classifier). Pair it with the `b.ssrfGuard` DNS-resolving gate, which still runs at fetch time
 - [ ] For file-upload routes: gate on magic bytes via `b.fileType.assertOneOf(buffer, ["image", "application/pdf"])` — never trust the client-supplied `Content-Type` alone
 - [ ] For routes that emit or accept CSV (operator exports, user-supplied uploads, mail attachments, object-store deliverables): wire `b.guardCsv.gate({ profile: "strict" })` into `b.staticServe.create({ contentSafety: { ".csv": gate } })` and `b.fileUpload.create({ contentSafety: gate })` — strict profile applies the OWASP-recommended `prefix-tab` formula-injection mitigation, the dangerous-function denylist (HYPERLINK / WEBSERVICE / IMAGE / IMPORT* / RTD / DDE / CALL), bidi / homoglyph / control / null-byte / BOM detection, dialect-ambiguity refusal, and CSV-bomb size caps; pick `compliancePosture: "hipaa" | "pci-dss" | "gdpr" | "soc2"` instead of (or layered over) the profile when the workload is regulated
 - [ ] For routes that accept YAML (config uploads, CI/CD pipelines, infra-as-code, document-import flows — ANY operator-supplied YAML the server parses): `b.guardYaml.gate({ profile: "strict" })` is wired by default into `b.fileUpload` + `b.staticServe` as of v0.7.12. For inbound YAML bodies that don't go through those primitives, wire `b.guardYaml.parse(body, { profile: "strict" })` before passing the parsed structure to operator handlers — strict refuses deserialization-tag RCE (defends CVE-2026-24009 Docling/PyYAML, CVE-2022-1471 SnakeYAML, CVE-2017-18342 PyYAML class), billion-laughs alias recursion (CVE-2026-27807 MarkUs class), Norway-problem implicit booleans, multi-document streams, leading-zero octals, duplicate keys, merge-key anchor-chains, bidi/null/control chars. Unlike JSON, YAML's threat surface includes language-specific deserialization triggers — `!!python/object/new:...` / `!!java.util.HashMap` / `!!ruby/object` etc. — which the source-level scan catches before any downstream parser (PyYAML / SnakeYAML / js-yaml) sees them
 - [ ] For routes that accept JSON bodies (REST APIs / webhook receivers / config uploads — ANY operator-supplied JSON the server parses): `b.guardJson.gate({ profile: "strict" })` is wired by default into `b.fileUpload` + `b.staticServe` as of v0.7.12. For inbound JSON request bodies that don't go through those primitives, wire `b.guardJson.parse(body, { profile: "strict" })` before passing the parsed structure to operator handlers — strict refuses prototype pollution at source level (catches `__proto__` / `constructor` / `prototype` keys before any parser sees the input — defends CVE-2025-55182 React Server Functions RCE class), duplicate keys (RFC 8259 SHOULD-unique smuggling), NaN/Infinity, comments, JSON5 syntax, BOM, bidi/null/control chars, numeric precision-loss, depth + breadth + array-length + string-length caps. Pair with `topLevelKeyAllowlist: [...]` for routes with a known shape so unauthorized keys refuse before validation
 - [ ] For routes that accept email (inbound webhooks from mail providers, .eml uploads, mailbox imports, message-archival flows, customer-support-ticket-by-email — ANY operator-supplied RFC 822/5322 message the server processes): `b.guardEmail.gate({ profile: "strict" })` is wired by default into `b.fileUpload` + `b.staticServe` as of v0.7.17. For inbound message bytes that don't go through those primitives, wire `b.guardEmail.validateMessage(bytes, { profile: "strict" })` BEFORE the parser sees the message — strict refuses SMTP smuggling (bare CR / bare LF outside CRLF pairs combined with embedded SMTP verbs `MAIL FROM`/`RCPT TO`/`DATA`/`EHLO`/`HELO`/`RSET`/`QUIT` — defends CVE-2023-51764 Postfix / CVE-2023-51765 Sendmail / CVE-2023-51766 Exim / CVE-2026-32178 .NET System.Net.Mail class), CRLF header injection in single-line headers (defends From/Bcc/body smuggling), IDN homograph mixed-script domains in address-bearing headers (Cyrillic / Greek / Armenian / Cherokee codepoints overlapping Latin — operator opts in to legitimate non-Latin via `allowedScripts: ["latin", "cyrillic"]`), Punycode `xn--` labels, display-name spoofing (`"support@apple.com" <attacker@evil>` — display contains @-address that doesn't match envelope domain), IP-literal addresses (`user@[1.2.3.4]` — bypasses DNS/DMARC alignment), RFC 5322 comment syntax in addresses, multiple @ characters, RFC 5321 length caps (local-part 64 / domain 255 / address 320), RFC 5322 line cap (998), BOM injection, bidi/null/control chars in addresses + headers. For per-address validation outside a full message context (form-submitted email, signup, MX-host validation), wire `b.guardEmail.validateAddress(addr, { profile: "strict" })`. Pair with operator's DMARC / SPF / DKIM verifier for envelope-alignment checks — guardEmail is the source-level gate, not the authentication-result interpreter
-- [ ] For an inbound `b.mail.server.mx` listener, wire the connection-level gate cascade so the anti-abuse controls actually run: `helo: b.mail.helo` (FCrDNS / HELO-shape / self-name spoofing → 550), `rbl: b.mail.rbl.create({ providers: [...] })` (connecting-IP DNS blocklist → 554, evaluated once per connection), and `greylist: b.mail.greylist.create({ store })` (first-seen (ip, sender, recipient) → 450 tempfail). A gate you don't wire is skipped, not synthesized — so an unwired RBL is no protection, not a default-allow surprise. SPF/DKIM/DMARC alignment is performed on the delivered message via the agent handoff until the inbound-authentication pipeline lands
+- [ ] For an inbound `b.mail.server.mx` listener, wire the connection-level gate cascade so the anti-abuse controls actually run: `helo: b.mail.helo` (FCrDNS / HELO-shape / self-name spoofing → 550), `rbl: b.mail.rbl.create({ providers: [...] })` (connecting-IP DNS blocklist → 554, evaluated once per connection), and `greylist: b.mail.greylist.create({ store })` (first-seen (ip, sender, recipient) → 450 tempfail). A gate you don't wire is skipped, not synthesized — so an unwired RBL is no protection, not a default-allow surprise. Wire `guardEnvelope: true` (or a config object) to run the DATA-phase SPF/DKIM/DMARC gate (`b.mail.inbound.verify`): enforce mode refuses with 550 5.7.26 (RFC 7372) when the sender's published DMARC policy says reject and with 550 5.7.1 on the RFC 7489 §6.6.1 multi-From spoofing shape, defers with 451 4.7.0 on DNS temperror or pipeline timeout, strips any sender-forged Authentication-Results header carrying your authserv-id before prepending the computed one (RFC 8601 §5), and hands the verdict to the agent as `auth` — start with `mode: "monitor"` to observe verdicts on live traffic before enforcing
 - [ ] For routes that accept markdown (rich-text editors, comment systems, README rendering, documentation submission, GitHub-style wikis, mail-rendered markdown, document-import flows — ANY operator-supplied markdown the server renders): `b.guardMarkdown.gate({ profile: "strict" })` is wired by default into `b.fileUpload` + `b.staticServe` as of v0.7.16. For inbound markdown bodies that don't go through those primitives, wire `b.guardMarkdown.validate(body, { profile: "strict" })` BEFORE passing the source to any markdown renderer (marked / markdown-it / commonmark / remark / parsedown — all of them) — strict refuses dangerous URL schemes in inline links + images + autolinks + reference-link definitions (defends CVE-2025-9540 Markup Markdown class, CVE-2025-24981 MDC class, NuGetGallery GHSA-gwjh-c548-f787, Joplin GHSA-hff8-hjwv-j9q7), whitespace-tolerant dangerous-tag matching (`<script\n>` / `<script\t>` — defends CVE-2026-30838 CommonMark DisallowedRawHtml bypass class), HTML-entity scheme bypass (`&#x6A;avascript:` / `&#106;avascript:` decoded BEFORE scheme matching), reference-link smuggling (`[label]: javascript:...`), front-matter YAML/TOML blocks, HTML comments, code-fence language injection (language tag containing `<>"' `` blocks attribute breakout), catastrophic emphasis runs (CVE-2025-6493 CodeMirror Markdown class, CVE-2025-7969 markdown-it class), inline DOCTYPE, bidi/null/control chars, total-bytes + line + link + image + autolink + ref-def + list-depth + blockquote-depth caps. **Layer with `b.guardHtml`**: source-level guardMarkdown then render then output-level guardHtml together close the residual bypass surface that either alone misses (markdown engines surprise; sanitizers also surprise — defense in depth)
 - [ ] For routes that accept XML (SOAP endpoints, sitemap submissions, RSS / Atom feeds, OAI-PMH harvesters, SAML / WS-Federation receivers, document-import flows — ANY operator-supplied XML the server parses): `b.guardXml.gate({ profile: "strict" })` is wired by default into `b.fileUpload` + `b.staticServe` as of v0.7.15. For inbound XML bodies that don't go through those primitives, wire `b.guardXml.validate(body, { profile: "strict" })` before passing the document to any XML parser — strict refuses DOCTYPE declarations unconditionally (XXE + billion-laughs vector — defends CVE-2026-24400 AssertJ class, CVE-2024-8176 libexpat recursive-entity stack-overflow class), `<!ENTITY>` declarations including parameter entities (out-of-band exfiltration vector), external entity references (SYSTEM / PUBLIC with file:// / http:// / ftp:// schemes — local file read + SSRF), `<xi:include>` remote inclusion (CVE-2024-25062 libxml2 use-after-free class), `xsi:schemaLocation` operator-controlled schema fetch, processing instructions (`<?xml-stylesheet ?>` CSS-injection vector), CDATA sections (often used to hide payloads from naive scanners), XML signature wrapping (xmldsig surface), bidi/null/control chars in element text + attribute values, and applies depth + element + per-attribute-value caps. DOCTYPE remains refused at every profile level (strict / balanced / permissive) because billion-laughs is universal. Operators integrating with legacy SOAP that requires DTDs must instead route through a separately-firewalled XML processor with explicit allowlist — the gate has no knob to relax DOCTYPE
 - [ ] **For ZIP-shaped uploads specifically**, reach for `b.safeArchive.extract({ source, destination, guardProfile: "strict" })` — the one-liner composes `b.archive.read.zip`'s random-access reader (LFH/CD skew defense + CD-walk validation), `b.guardArchive.zipBombPolicy` defaults (per-entry + per-archive + ratio caps), `b.guardArchive.entryTypePolicy` defaults (symlink / hardlink / device / fifo / socket entries refused), and `b.guardFilename.verifyExtractionPath`'s dual-check (string-normalize + `fs.realpath`-agreement; refuses pre-resolve names exceeding PATH_MAX=4096 to defend the CVE-2025-4517 TOCTOU class; and refuses per-segment Windows write-target hazards — reserved device names like `CON`/`NUL`, NTFS alternate-data-stream `name:stream` syntax, and trailing-dot/whitespace that Windows strips into a sibling overwrite — platform-unconditionally, since the extracting host may differ from the verifying host). The fs-coupled realpath check is the depth above `b.guardArchive.checkExtractionPath`'s portable string-only gate; operators with their own extract loop call both. Default refuses ZIP encrypted entries (v0.12.10/11 add the encryption read paths). For tar / gzip / 7z / rar / zstd, the read-side primitives land in v0.12.8 / v0.12.9; until then use the legacy guard-only path below
@@ -366,6 +368,7 @@ This is the minimum-viable security posture for a production deployment. The fra
 - [ ] For data with a TTL (GDPR Art. 17, PCI 3.1, retention windows): declare retention rules via `b.retention.create({ db, audit }).declare({ name, table, ageField, ttlMs, action: "erase" })` and run on a `b.scheduler` cadence; honour legal-hold via `legalHoldField`
 - [ ] For write-once-read-many object archives (SEC 17a-4, FINRA, HIPAA-shaped retention): create the bucket with `b.objectStore.bucketOps.create(name, { objectLockEnabled: true })` (Object Lock can ONLY be flipped at create time), apply a default retention via `setObjectLockConfiguration(name, { mode: "COMPLIANCE", years })`, and pin individual objects with `setObjectRetention(name, key, { mode, retainUntil })` or `setObjectLegalHold(name, key, "ON")` — `COMPLIANCE` cannot be shortened or bypassed by anyone (including root); pick deliberately
 - [ ] At boot, before any outbound socket opens: call `b.network.bootFromEnv({ env: process.env, audit: b.audit })` so operator-supplied NTP / DNS / proxy / DPI-trust / TCP socket settings (`BLAMEJS_NTP_*`, `BLAMEJS_DNS_*`, `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`, `BLAMEJS_EXTRA_CA_CERTS`, `BLAMEJS_SOCKET_*`) apply uniformly
+- [ ] If you ship spans/metrics to an OTLP collector through a custom exporter (rather than the framework's `b.otelExport` / `b.logStream`, which already do this): run every span / metric / resource attribute **value** through `b.observability.redactAttrs(attrs)` before serialization. Telemetry is a first-class egress sink — an attribute value holding a bearer token, password, or PII is otherwise shipped to the collector verbatim (CWE-532). `redactAttrs` composes `b.redact.redact`, drops any attribute whose redactor throws (fail toward dropping), and honours an operator override installed via `b.observability.setRedactor`
 - [ ] If the deployment sits behind a deep-packet-inspection proxy with its own re-signing CA: install the CA via `b.network.tls.addCa("/path/to/corp-ca.pem", { label: "corp-mitm" })` and pass `allowDpiTrust: true` to `b.security.assertProduction` — every CA addition audits with subject + fingerprint so a forensic review can reconstruct the trust path
 - [ ] For authenticated time (HIPAA / PCI / FIPS shops): use `b.network.ntp.nts.query({ host: ntsKeServer })` (RFC 8915) instead of plain SNTP; set `BLAMEJS_NTS_REQUIRE=1` to fail closed on negotiation failure
 - [ ] When a DNS answer drives a trust decision (DANE / TLSA pinning, SSHFP, CAA enforcement, OPENPGPKEY lookup) and the upstream resolver isn't itself trusted: verify the answer's DNSSEC signature with `b.network.dns.dnssec.verifyRrset(...)` rather than trusting the resolver's AD bit — an on-path or compromised resolver can set AD on a forged answer, but cannot forge the RRSIG. Validate the whole delegation chain root→TLD→zone with `b.network.dns.dnssec.verifyChain(...)` (default-pinned to the IANA root KSKs, or `trustAnchors` for a private root) so trust is anchored, not borrowed from the resolver. `verifyChain` bounds KeyTrap (CVE-2023-50387) amplification with non-configurable caps (≤4 same-tag candidate keys per RRSIG, ≤64 DNSKEYs/zone, ≤16 DS/delegation, ≤128 chain links, and a signature-validation budget that scales with chain depth so deep delegations validate while bounded collisions stay bounded) and caps NSEC3 iterations at 150 (CVE-2023-50868) — a hostile zone is refused, not allowed to exhaust CPU. For a negative answer that drives a fail-closed decision (an allowlist lookup, a revocation check), verify the NSEC / NSEC3 proof with `b.network.dns.dnssec.verifyDenial(...)` so a forged NXDOMAIN cannot suppress a record; keep the default Opt-Out refusal unless the zone's opt-out spans are acceptable for that decision. For DANE / TLSA, once the TLSA RRset is DNSSEC-verified, pin the peer certificate with `b.network.dns.dane.matchCertificate(...)` — a DANE-EE(3) match authenticates the key with no public CA, while PKIX usages are flagged as still needing PKIX
@@ -425,6 +428,7 @@ The framework's audit + consent chains are append-only at the application layer
 
 **Residency & replication**
 
+- [ ] For tables holding mixed-region personal data under a cross-border regulated posture (GDPR / UK-GDPR / DPDP / PIPL / LGPD / APPI / PDPA): declare per-row residency (`b.cryptoField.declarePerRowResidency(table, { residencyColumn, allowedTags })`) so local writes refuse rows whose tag falls outside the deployment's `dataResidency` region set, and pass `rowResidencyTag` on `b.externalDb.query` / `transaction` DML so a tagged backend refuses mismatched rows at the wire (refusals + cross-border replica reads land in the audit chain). Tag columns with `b.cryptoField.declareColumnResidency` for the column-scoped version of the same gate
 - [ ] WAL archive / streaming replicas MUST stay within the declared `b.db.getDataResidency().region`. Cross-region WAL ship (Aurora Global, RDS cross-region read replica, pg_basebackup over public internet) silently moves audit + consent rows out of the residency boundary even when the framework's `b.externalDb.residencyTag` enforcement is correct. Confirm replication topology + log-shipping path before flipping `personal` classification onto an externalDb backend
 - [ ] For point-in-time recovery: bound the PITR window with the framework's retention floor (`b.retention.complianceFloor`) — restoring a snapshot older than the consent-erasure timestamp re-materializes deleted personal data and creates a new GDPR Art. 17 violation. Pair PITR replay with a `b.retention` re-run before re-opening the restored DB to traffic
 - [ ] Backup encryption key MUST differ from the framework `BLAMEJS_VAULT_PASSPHRASE` — a single-key compromise that exfiltrates the running vault should not also unlock every backup bundle
@@ -435,6 +439,18 @@ The framework's audit + consent chains are append-only at the application layer
 - [ ] Enable `log_min_duration_statement` at the cluster level (typically `1000ms`) so slow queries land in the operator-managed log stream alongside the framework's `db.query.slow` observability events. The framework emits the `1s` / `5s` / `30s` buckets; the cluster log captures the SQL text the framework intentionally redacts from audit metadata
 - [ ] For roles that issue DDL (migration runner, framework boot): set `log_statement = ddl` so a forensic review can correlate the framework's `db.ddl.executed` audit row with the cluster log's verbatim DDL text — closes the trust gap between "framework says it ran X" and "cluster log shows X actually ran"
 
+## Per-row-key crypto-shred advisory (fixed in v0.14.25)
+
+Tables opted into per-row keying (`b.cryptoField.declarePerRowKey`) advertise crypto-erasure: `b.subject.eraseHard` / `b.retention` destroy a row's wrapped key so WAL / replica / backup residual ciphertext for that row becomes mathematically undecryptable. Before v0.14.25 that guarantee did not hold:
+
+- **The row key was re-derivable from disk.** `K_row` was derived deterministically from `vault.getDerivedHashSalt()` — a value stored in **plaintext** on disk — plus the table name and row id. An attacker with read access to the data directory could recompute `K_row` for any row, so deleting the wrapped-key entry shredded nothing.
+- **The wrapped key was sealed without AAD.** Despite the documented copy-row protection, the wrap carried no Additional Authenticated Data, so a database-write attacker could move a wrapped key (and the ciphertext it opens) between rows.
+- **The key was never materialized on write.** The materialize-on-INSERT path was never wired, so the feature was inert — no row ever actually carried a per-row key.
+
+v0.14.25 makes the guarantee real: each keyed row's secret is a fresh 32-byte CSPRNG value (never a function of any on-disk salt), stored AEAD-sealed and bound to `(table, rowId, column, schemaVersion)`; sealed columns on keyed rows are encrypted under the row key (`vault.row:` cells) and bound to the same tuple; and the key is materialized at the write boundary on every INSERT/UPDATE and destroyed by `eraseHard` / `retention`. A vault keypair rotation re-seals the wrapped secret old-root → new-root.
+
+**Operator action.** The per-row-key registry was empty in prior deployments (the path never ran), so there is no legacy ciphertext to migrate — keyed tables become correct from their first write under v0.14.25. If you scripted a parallel re-derivation of `K_row` from `getDerivedHashSalt()` outside the framework, remove it; the derivation input is now the sealed random secret. The same plaintext-salt class was corrected for the idempotency-middleware fingerprint HMAC (`b.middleware.idempotencyKey` with `fingerprintSeal`), which now seeds off the sealed `vault.getDerivedHashMacKey()`; cached fingerprints from before the upgrade are treated as a mismatch (replayed requests re-execute once), which is the safe behavior.
+
 ## Watch list
 
 CVE classes the framework tracks but does not currently ship a primitive for — operator awareness items: