@blamejs/core 0.11.22 → 0.11.23

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.23 (2026-05-20) — **`b.mail.agent.expunge` — hard EXPUNGE with legal-hold + retention-floor refusal gates.** Operators (and the future IMAP EXPUNGE + JMAP Email/set destroyed wire-protocol adapters) get a single canonical path for permanent message removal that refuses to delete anything currently under legal hold or still inside the regulator-mandated retention window. The gate runs per-message; refused ids carry an explicit reason (`legal-hold` / `retention-floor` / `not-in-folder`) plus the floor + age + posture metadata that drove the refusal — wire adapters mirror those reasons to operators verbatim. The destructive SQL runs only on the surviving id set, inside a backend transaction that also bumps folder modseq + decrements quota atomically. **Added:** *`b.mail.agent.expunge({ actor, folder, objectIds })` — hard EXPUNGE primitive* — Composes two refusal gates before the destructive SQL runs. (1) Legal-hold gate: any message whose `legal_hold` flag is set refuses with reason `legal-hold`. The mail-store layer surfaces the flag in per-row metadata; this layer maps it to the operator-facing refusal. (2) Retention-floor gate: under a configured compliance posture (`hipaa` / `pci-dss` / `gdpr` / `soc2`), the regulator-mandated minimum retention TTL is read from `b.retention.COMPLIANCE_RETENTION_FLOOR_MS[posture]` and any message whose age (`now - receivedAt`) is below the floor refuses with reason `retention-floor` plus `floorMs` + `ageMs` + `posture` metadata. Returns `{ deleted: <ids>, refused: [{ id, reason, ... }] }`. Audit event `mail.agent.expunge.success` carries the requested / deleted / refused counts and a reason histogram so dashboards can spot abnormal refusal patterns without parsing per-id detail. · *`b.mailStore.create(...).hardExpunge(folder, objectIds)` — destructive SQL primitive* — Removes messages permanently from a folder inside a single backend transaction: deletes the message row + its flag rows, bumps the folder modseq, decrements the per-folder quota by the freed bytes / count. Returns `{ rows, deleted, refused }` where `refused` carries `{ id, reason: 'legal-hold' | 'not-in-folder' }` for each id the SQL gate refused (legal-hold is mirrored from the column; not-in-folder catches stale ids). The agent layer (`b.mail.agent.expunge`) is responsible for the retention-floor gate; this primitive is the wire-protocol-shaped backend surface. · *`b.mailStore.create(...).fetchByObjectId` returns `legalHold: boolean`* — Pre-existing fetch path now consistently exposes the legal-hold flag in its return shape. Previously the field existed in the returned object via a separate path; this commit consolidates the duplicate exports into a single canonical `legalHold` boolean derived from the SQLite `legal_hold` INTEGER column. **References:** [RFC 9051 (IMAP4rev2 — EXPUNGE semantics, §6.4.3)](https://www.rfc-editor.org/rfc/rfc9051.html) · [RFC 8621 (JMAP Mail — Email/set destroyed)](https://www.rfc-editor.org/rfc/rfc8621.html) · [45 CFR §164.316 (HIPAA — retention of records)](https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-C/part-164/subpart-C/section-164.316) · [PCI-DSS v4.0.1 §3.5.1.1 (retention of cardholder data)](https://www.pcisecuritystandards.org/document_library) · [GDPR Art. 17 (right to erasure — operator-side accountability)](https://gdpr-info.eu/art-17-gdpr/)
+
 - v0.11.22 (2026-05-20) — **`b.cert.create` — turnkey TLS-certificate manager composing ACME + sealed persistence + renewal scheduler + SNI + key escrow.** Operators wiring TLS no longer have to glue ACME + key generation + cert persistence + renewal scheduling + SNI dispatch + escrow by hand. `b.cert.create({ storage, acme, certs, renew, ocsp, audit, compliance })` accepts a declarative manifest of certificates plus the operator's choice of ACME challenge solver, and the manager owns the rest of the lifecycle: ACME RFC 8555 order + RFC 9773 ARI-aware renewal, leaf key rotation on renew, OCSP refresh scheduling, sealed-disk persistence via `b.vault.seal`, optional break-glass key escrow encrypted to an operator-supplied recipient via `b.crypto.encryptEnvelope`, and SNI dispatch for `https.createServer({ SNICallback })`. Composes existing primitives — `b.acme.create` (extended this release with per-challenge methods), `b.vault.seal`, `b.safeAsync.repeating`, `b.network.tls`, `b.audit` — so the operator-facing surface is one factory call. **Added:** *`b.cert.create(opts)` — turnkey certificate manager* — New top-level primitive. Storage backend: `sealed-disk` (default; sealed via `b.vault.seal`). ACME: directory URL + contact + auto-generated account key (sealed on disk; operator can override with explicit key material). Certs manifest: per-cert name + domains + keyAlg (ecdsa-p256 / ecdsa-p384 / rsa-2048 / rsa-3072 / rsa-4096) + challenge `{ type, provision, cleanup }` callbacks (http-01 / dns-01 / tls-alpn-01). Renewal: ARI-respecting scheduler with configurable `intervalMs` + `minDaysBeforeExpiry` thresholds. OCSP: `stapling: true` schedules periodic OCSP refresh via `b.network.tls.ocsp`. Key escrow: optional `keyEscrow: { recipient }` encrypts each renewed private key to the recipient public key via `b.crypto.encryptEnvelope` and persists alongside the sealed key — break-glass-only recovery path, NOT routine access. Surface: `start()` / `stop()` / `getContext(name)` / `sniCallback` / `refresh(name)` / event-emitter `on('cert.issued' | 'cert.renewed' | 'cert.renew-failed', handler)`. · *`b.acme.create.fetchAuthorization(authUrl)` — RFC 8555 §7.5 authorization GET* — POST-as-GET an authorization URL; returns the parsed authorization object with the challenge array. The challenge entries carry `{ type, url, token, status }` for each offered challenge type. Required by the cert manager's per-challenge flow but useful to operators implementing custom ACME wrappers. · *`b.acme.create.notifyChallengeReady(challengeUrl)` — RFC 8555 §7.5.1 ready-notification* — POST an empty JSON object to a challenge URL to signal the operator has provisioned the response. Returns the updated challenge object; the CA's validation runs asynchronously and the operator polls via `waitForAuthorization` afterwards. · *`b.acme.create.waitForAuthorization(authUrl, opts?)` — authorization status polling* — Polls an authorization until `status === 'valid'` (success) or `status === 'invalid'` (CA refused). Honors the client's `pollIntervalMs` + `pollMaxMs` defaults; per-call `opts.intervalMs` + `opts.timeoutMs` override available. Throws typed `acme/auth-invalid` on CA refusal and `acme/auth-timeout` on poll-budget exhaustion. · *`b.acme.create.buildCsr({ privateKey, publicKey, domains })` — RFC 2986 PKCS#10 CSR builder* — Builds a CertificationRequest signed with the leaf private key. Subject `CN=<first domain>`, all domains as `dNSName` entries in the SubjectAltName extension. Supports ECDSA P-256 (signed sha256), ECDSA P-384 (signed sha384), RSA 2048 / 3072 / 4096 (signed sha256). Ed25519 is rejected at the CSR layer because CA support is uneven — operators wanting Ed25519 certs build the CSR externally. PEM-encoded output ready to feed to `finalize(order, csrPem)`. · *`b.asn1Der` write primitives — `writeBitString` / `writeSet` / `writeUtf8String` / `writePrintableString` / `writeIa5String` / `writeBoolean` / `writeContextImplicit`* — ASN.1 DER encoder extensions needed for PKCS#10 CSR construction. PrintableString refuses input outside the RFC 5280 character set; IA5String refuses non-ASCII; UTF8String refuses non-string input. SET-OF encoding sorts children by their encoded bytes per DER. Internal-only today (consumed by `b.acme.create.buildCsr`); operators with their own ASN.1 needs can compose them. **Changed:** *`b.audit.FRAMEWORK_NAMESPACES` adds `cert`* — The cert-manager lifecycle emits `cert.account.generated` / `cert.issued` / `cert.renewed` / `cert.renew-failed` / `cert.challenge-cleanup` audit events; the audit-namespace coverage check at smoke-time now recognizes the `cert` namespace. **References:** [RFC 8555 (ACME)](https://www.rfc-editor.org/rfc/rfc8555.html) · [RFC 9773 (ACME Renewal Information / ARI)](https://www.rfc-editor.org/rfc/rfc9773.html) · [RFC 2986 (PKCS#10 Certification Request Syntax)](https://www.rfc-editor.org/rfc/rfc2986.html) · [RFC 5280 (X.509 Internet PKI)](https://www.rfc-editor.org/rfc/rfc5280.html) · [RFC 8737 (TLS-ALPN-01 challenge)](https://www.rfc-editor.org/rfc/rfc8737.html) · [OpenSSL CSR roundtrip — local OpenSSL validation](https://www.openssl.org/docs/man3.5/man1/openssl-req.html)
 
 - v0.11.21 (2026-05-20) — **Supply-chain hardening — pinact + zizmor + actionlint gate, sha-to-tag tag-integrity verifier, GOVERNANCE.md.** Closes the input + tag-integrity halves of the supply-chain trust boundary. `pinact` refuses any `uses:` reference that isn't pinned to a 40-char SHA with a verified version-comment (defense against the CVE-2025-30066 retroactive-tag-rewrite class). `zizmor` audits every workflow for the documented security anti-pattern catalog (template-injection / excessive-permissions / cache-poisoning / impostor-commit / unredacted-secrets / etc.). The new `sha-to-tag-verify` workflow refuses to let the publish workflow proceed if a release tag's commit SHA isn't on `main`'s first-parent history OR wasn't the result of a merged PR — the source-side gate that TanStack's 2026-05-11 attack (84 malicious `@tanstack/*` versions published with valid SLSA L3 provenance) demonstrated as a structural defense alongside provenance verification. SECURITY.md gains operator-facing `slsa-verifier` and tag-SHA-integrity recipes. New top-level `GOVERNANCE.md` documents the solo-maintainer governance model, succession plan, key-loss recovery, and dependent-notification protocol. **Added:** *`.github/workflows/actions-lint.yml` — pinact + zizmor + actionlint gate* — Three tools, three layers per the arxiv.org "Unpacking Security Scanners for GitHub Actions Workflows" taxonomy. `pinact run --check` refuses any `uses:` reference that isn't SHA-pinned with a matching version-comment; `pinact run --verify` re-resolves each pinned SHA's registered tag at check time and refuses if the workflow's version-comment disagrees (catches retroactive tag rewrites). `zizmor` audits at `--min-severity low` across every documented rule class (template-injection, excessive-permissions, dangerous-triggers, unpinned-uses, cache-poisoning, github-env, hardcoded-container-credentials, impostor-commit, known-vulnerable-actions, obfuscation, ref-confusion, secrets-inherit, self-hosted-runner, unredacted-secrets, unsound-contains, use-trusted-publishing); SARIF emitted to GitHub Code Scanning. `actionlint` runs YAML + expression validation + shellcheck on every `run:` block. Single documented exception in `.pinact.yaml` — the SLSA reusable workflow MUST be tag-pinned because its internal builder-fetch step refuses non-tag refs. · *`.github/workflows/sha-to-tag-verify.yml` — tag-SHA integrity gate* — Runs on every `v*` tag push and refuses to let the publish workflow start if the tag's commit SHA isn't on `main`'s first-parent history OR wasn't the result of a merged PR. Defends against the tag-mutation class (CVE-2025-30066: 23,000+ affected repos in March 2025) and the source-side-malicious-publish class (TanStack 2026-05-11: 84 valid-SLSA-L3-provenance malicious versions). The same chain is documented for operator-side re-verification in SECURITY.md's new "Verifying release-commit integrity" subsection. · *`GOVERNANCE.md` — solo-maintainer governance, succession, key-loss recovery, dependent-notification* — New top-level document covering: (a) current governance model (solo maintainer pre-1.0, maintainer-final on technical direction); (b) succession plan with TBD-successor-with-documented-re-open-trigger, repository ownership, npm publish credentials, SSH signing key rotation procedure, Sigstore identity rotation; (c) key-loss recovery for every asset (npm publish, GitHub org, SSH signing key, Sigstore, domain); (d) dependent-notification protocol via `security@blamejs.com` with 30-day no-activity escalation. Bus-factor-1 is the largest non-technical risk pre-1.0; this document makes the recovery path defensible. · *SECURITY.md — `slsa-verifier` and tag-SHA-integrity operator-verification recipes* — "Verifying release authenticity" gains a `slsa-verifier verify-artifact` recipe (pinned to v2.7.1) for offline / API-independent provenance verification — `gh attestation verify` walks the chain via the GitHub API; `slsa-verifier` does it from disk. The recipe explicitly states the limit: SLSA provenance binds the tarball bytes to a workflow+commit+tag, but does NOT prove the source is clean (the TanStack incident shipped valid-provenance malicious versions because the source side was compromised). A new "Verifying release-commit integrity" subsection documents the sha-to-tag chain operators run alongside provenance verification — the source-side gate. · *`.pinact.yaml` — pinact configuration with documented SLSA exception* — Defines a single tag-pin exception for `slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml`. The SLSA reusable workflow's internal builder-fetch step refuses non-tag `BUILDER_REF` values, so the call MUST be tag-pinned; mitigated by slsa-framework's upstream tag-protection + immutable-release rules. The same exception also appears as a per-line `# allow:slsa-framework-action-not-sha-pinned` marker in `npm-publish.yml` for the framework's own codebase-patterns gate. **Changed:** *Workflow version-comment integrity — every pinned action's `# vX.Y.Z` comment now matches the registered tag for that SHA* — Pre-existing pins carried stale version-comments (`actions/checkout@de0fac2e... # v6.0.0` where that SHA is actually `v6.0.2`, `actions/setup-node@48b55a01... # v6.0.0` where the SHA is `v6.4.0`, `actions/download-artifact@3e5f45b2... # v7.0.1` where the SHA is `v8.0.1`, `github/codeql-action@9e0d7b8d... # v3.30.9` where the SHA is `v4.35.5`). The SHAs themselves stay (they're the actual-released versions); the comments now match. This is what pinact's `--verify` check enforces structurally going forward — a stale version-comment is the early-warning signal that a retroactive tag rewrite landed without operator notice. **References:** [CVE-2025-30066 (tj-actions/changed-files retroactive tag rewrite)](https://nvd.nist.gov/vuln/detail/CVE-2025-30066) · [TanStack npm publish incident 2025-05-11](https://blog.tanstack.com/the-tanstack-may-2025-supply-chain-attack/) · [pinact](https://github.com/suzuki-shunsuke/pinact) · [zizmor](https://github.com/woodruffw/zizmor) · [actionlint](https://github.com/rhysd/actionlint) · [slsa-verifier](https://github.com/slsa-framework/slsa-verifier)

package/lib/mail-agent.js

@@ -104,6 +104,7 @@ var SCOPE_FOR_METHOD = Object.freeze({
   move:             "mail:move",
   flag:             "mail:move",
   delete:           "mail:move",
+  expunge:          "mail:expunge",
   "sieve.list":     "mail:sieve",
   "sieve.put":      "mail:sieve",
   "sieve.activate": "mail:sieve",
@@ -209,6 +210,7 @@ function create(opts) {
     move:      function (args) { return _dispatchOrLocal(ctx, "move",   args, _move); },
     flag:      function (args) { return _dispatchOrLocal(ctx, "flag",   args, _flag); },
     delete:    function (args) { return _dispatchOrLocal(ctx, "delete", args, _delete); },
+    expunge:   function (args) { return _dispatchOrLocal(ctx, "expunge", args, _expunge); },
 
     // Sieve — needs v0.9.26 interpreter.
     sieve:     {
@@ -484,6 +486,125 @@ async function _delete(ctx, args) {
   return r;
 }
 
+async function _expunge(ctx, args) {
+  // Hard EXPUNGE — permanent removal of messages from the mail store.
+  // Composes two refusal gates BEFORE the destructive SQL runs:
+  //
+  //   1. b.legalHold — any message whose `legal_hold` flag is set
+  //      refuses with reason "legal-hold". The mail-store layer
+  //      surfaces the flag in the row metadata; this layer maps that
+  //      to the operator-facing refusal.
+  //
+  //   2. b.retention.complianceFloor — given the operator's posture
+  //      (e.g. "hipaa"), `complianceFloor(posture, candidateTtlMs)`
+  //      returns the regulator-mandated minimum retention TTL. Any
+  //      message younger than that floor refuses with reason
+  //      "retention-floor".
+  //
+  // Both gates run per-message; the response shape carries an
+  // explicit refusal reason for every refused id so the wire-protocol
+  // adapter (IMAP EXPUNGE → "*  N EXPUNGE" suppression, JMAP
+  // Email/set destroyed → notDestroyed[id] = SetError) can mirror the
+  // reason to operators verbatim.
+  _entry(ctx, "expunge", args);
+  if (typeof args.folder !== "string" || !Array.isArray(args.objectIds)) {
+    throw new MailAgentError("mail-agent/bad-args",
+      "agent.expunge: { folder, objectIds, [candidateTtlMs] } required");
+  }
+
+  // Look up the regulator-mandated retention floor for the operator's
+  // active posture. For expunge semantics, the floor IS the minimum
+  // TTL — messages younger than the floor MUST NOT be hard-deleted,
+  // even on operator request. Distinct from `b.retention.
+  // complianceFloor(posture, candidateTtl)` which composes the
+  // candidate TTL into a max — that primitive's "candidate must be
+  // positive" contract doesn't apply here because expunge means TTL=0.
+  // Read the floor table directly.
+  var retentionModule = require("./retention");                                                    // allow:inline-require — lazy-load until first expunge call
+  var posture = (ctx && ctx.posture) || (args && args.posture) || null;
+  var floorMs = 0;
+  if (typeof posture === "string" && posture.length > 0) {
+    floorMs = retentionModule.COMPLIANCE_RETENTION_FLOOR_MS[posture] || 0;
+  }
+
+  // Read message metadata BEFORE invoking hardExpunge so the per-id
+  // refusal map is built from the same row set the destructive call
+  // sees. Use the store's hardExpunge primitive in two passes:
+  //   pass 1: pass an empty objectIds[] for the candidate scan? No —
+  //   hardExpunge returns the metadata for the ids it was asked about,
+  //   so call it ONCE with the full id set; it returns `refused` for
+  //   legal-hold refusals + the metadata rows for the survivors.
+  //   We then add retention-floor refusals to the response and pass
+  //   the FINAL surviving id set to a second hardExpunge call? No —
+  //   the surviving set is computed inline; the simpler shape is:
+  //
+  //   - Filter via metadata read (using a `dryRun` flag on
+  //     hardExpunge would work but adds API surface)
+  //
+  // Pragmatic v1: call hardExpunge once with the full set. It refuses
+  // legal-hold internally + returns the metadata for the rest. Then
+  // we filter the deleted set retroactively for retention-floor
+  // violations — but hardExpunge already DELETED them. That's wrong.
+  //
+  // Correct v1: call hardExpunge with an empty `objectIds` for a
+  // metadata-only pass? hardExpunge returns immediately for empty
+  // input. So we need an explicit "read metadata for these ids"
+  // query OR a hardExpunge `dryRun` flag.
+  //
+  // Use a fresh SELECT to read the gate-input data, then pass the
+  // surviving set to hardExpunge. The store exposes `queryByModseq`
+  // but that's a wide scan; for v1 expunge takes the metadata via a
+  // dedicated per-id lookup. (The store's hardExpunge SELECT is the
+  // same shape; expose it as `_selectForExpunge` via a small adapter,
+  // OR just round-trip through the existing fetchByObjectId.)
+  var nowMs = Date.now();
+  var refused = [];
+  var candidates = [];
+  for (var i = 0; i < args.objectIds.length; i += 1) {
+    var oid = args.objectIds[i];
+    var meta = ctx.store.fetchByObjectId(args.folder, oid);
+    if (!meta) {
+      refused.push({ id: oid, reason: "not-in-folder" });
+      continue;
+    }
+    if (meta.legalHold) {
+      refused.push({ id: oid, reason: "legal-hold" });
+      continue;
+    }
+    if (floorMs > 0) {
+      var receivedAt = meta.receivedAt || meta.internalDate || 0;
+      var ageMs = nowMs - receivedAt;
+      if (ageMs < floorMs) {
+        refused.push({ id: oid, reason: "retention-floor",
+                       floorMs: floorMs, ageMs: ageMs, posture: posture });
+        continue;
+      }
+    }
+    candidates.push(oid);
+  }
+
+  // Run the destructive SQL only on the surviving set.
+  var result = candidates.length > 0
+    ? ctx.store.hardExpunge(args.folder, candidates)
+    : { rows: [], deleted: [], refused: [] };
+
+  ctx.auditEmit("mail.agent.expunge.success", args.actor, {
+    folder:        args.folder,
+    requested:     args.objectIds.length,
+    deleted:       result.deleted.length,
+    refused:       refused.length,
+    refusedReasons: refused.reduce(function (acc, r) {
+      acc[r.reason] = (acc[r.reason] || 0) + 1; return acc;
+    }, {}),
+    posture:       posture,
+    floorMs:       floorMs,
+  });
+  return {
+    deleted: result.deleted,
+    refused: refused,
+  };
+}
+
 async function _sievePut(ctx, args) {
   // Two-stage validation: agent-level shape guard for RBAC + name +
   // size, then the full RFC 5228 grammar parse via b.safeSieve. The

package/lib/mail-store.js

@@ -185,6 +185,16 @@ function create(opts) {
   var stmtBumpQuota        = db.prepare(
     "INSERT INTO " + qQuota + " (folder_id, used_bytes, used_count, cap_bytes, cap_count) VALUES (?, ?, ?, NULL, NULL) " +
     "ON CONFLICT(folder_id) DO UPDATE SET used_bytes = used_bytes + excluded.used_bytes, used_count = used_count + excluded.used_count");
+  // Hard-expunge prepared statements — used by `hardExpunge` to delete
+  // a message permanently after retention-floor + legal-hold gates
+  // pass. The SELECT is the gate-input source (legal_hold flag + age);
+  // the DELETE + flag-cleanup + quota-decrement run inside a backend
+  // transaction so partial state can't survive a crash.
+  var stmtSelectForExpunge = db.prepare(
+    "SELECT objectid, folder_id, size_bytes, received_at, legal_hold FROM " + qMsgs +
+    " WHERE folder_id = ? AND objectid IN (SELECT value FROM json_each(?))");
+  var stmtDeleteMsg        = db.prepare("DELETE FROM " + qMsgs + " WHERE objectid = ?");
+  var stmtDeleteFlags      = db.prepare("DELETE FROM " + qFlags + " WHERE objectid = ?");
 
   return {
     appendMessage:    function (folderName, rawBytes, appendOpts) {
@@ -285,6 +295,98 @@ function create(opts) {
       objectids.forEach(function (oid) { stmtLegalHold.run(hold, oid); });
       return { changed: objectids.length };
     },
+    /**
+     * hardExpunge — remove messages permanently from a folder.
+     *
+     * Returns `{ rows: [{ objectid, size_bytes, received_at, legal_hold }],
+     *          deleted: <ids>, refused: [{ id, reason }] }`. Per-row
+     * `legal_hold` is the column value at expunge time so the caller
+     * (typically `b.mail.agent.expunge`) can refuse messages currently
+     * under hold.
+     *
+     * The caller is responsible for:
+     *   (1) Composing `b.legalHold` to refuse hold-flagged messages
+     *       before passing the surviving set here, AND
+     *   (2) Composing `b.retention.complianceFloor` to refuse messages
+     *       whose `received_at` is inside the regulated retention window.
+     *
+     * This primitive does the destructive SQL work + transaction-
+     * scoped quota decrement + modseq bump. Refusals must happen at
+     * the agent layer; this layer is the wire-protocol-shaped backend
+     * surface.
+     */
+    hardExpunge:      function (folderName, objectids) {
+      var folder = stmtGetFolderByName.get(folderName);
+      if (!folder) {
+        throw new MailStoreError("mail-store/no-folder",
+          "hardExpunge: folder '" + folderName + "' not found");
+      }
+      if (!Array.isArray(objectids) || objectids.length === 0) {
+        return { rows: [], deleted: [], refused: [] };
+      }
+      // Deduplicate objectids before the per-id pass. Without this,
+      // `hardExpunge(folder, [id, id])` would append the same row to
+      // `toDelete` twice and drive `usedBytes` / `usedCount` negative
+      // via the double-subtract in the transaction; `deleted` would
+      // also carry the duplicate id back to the caller. Preserve
+      // first-seen ordering for stable refused/deleted output.
+      var seenIds = Object.create(null);
+      var uniqueIds = [];
+      for (var ui = 0; ui < objectids.length; ui += 1) {
+        if (!seenIds[objectids[ui]]) {
+          seenIds[objectids[ui]] = true;
+          uniqueIds.push(objectids[ui]);
+        }
+      }
+      objectids = uniqueIds;
+      var rows = stmtSelectForExpunge.all(folder.id, JSON.stringify(objectids));
+      var byId = Object.create(null);
+      rows.forEach(function (r) { byId[r.objectid] = r; });
+      var refused = [];
+      var toDelete = [];
+      for (var i = 0; i < objectids.length; i += 1) {
+        var oid = objectids[i];
+        var row = byId[oid];
+        if (!row) {
+          refused.push({ id: oid, reason: "not-in-folder" });
+          continue;
+        }
+        if (row.legal_hold === 1) {
+          refused.push({ id: oid, reason: "legal-hold" });
+          continue;
+        }
+        toDelete.push(row);
+      }
+      if (toDelete.length === 0) return { rows: rows, deleted: [], refused: refused };
+
+      // One transaction: delete messages + their flags, bump folder
+      // modseq, decrement quota. Better-sqlite3-style `transaction`
+      // helpers wrap this; if the backend doesn't expose `transaction`,
+      // run the statements directly (atomicity falls back to per-stmt).
+      var totalBytes = 0;
+      var modseqBump = Date.now();
+      function _runTxn() {
+        for (var di = 0; di < toDelete.length; di += 1) {
+          stmtDeleteFlags.run(toDelete[di].objectid);
+          stmtDeleteMsg.run(toDelete[di].objectid);
+          totalBytes += toDelete[di].size_bytes || 0;
+        }
+        stmtBumpFolderModseq.run(modseqBump, folderName);
+        if (totalBytes > 0 || toDelete.length > 0) {
+          stmtDecrementQuota.run(totalBytes, toDelete.length, folder.id);
+        }
+      }
+      if (typeof db.transaction === "function") {
+        db.transaction(_runTxn)();
+      } else {
+        _runTxn();
+      }
+      return {
+        rows:    rows,
+        deleted: toDelete.map(function (r) { return r.objectid; }),
+        refused: refused,
+      };
+    },
     _backend:         db,
     _tablePrefix:     prefix,
   };
@@ -445,7 +547,7 @@ function _fetchByObjectId(args) {
     bodyText:       unsealed.body_text,
     bodyHtml:       unsealed.body_html,
     flags:          flags,
-    legalHold:      row.legal_hold === 1,
+    legalHold:      row.legal_hold === 1,                                                            // allow:raw-byte-literal — sqlite INTEGER column 0|1
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.22",
+  "version": "0.11.23",
   "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:617bc99b-11e9-4c47-8ede-269a573133ef",
+  "serialNumber": "urn:uuid:e4f090dd-9a46-4d67-b64e-b7b9105c5254",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T01:07:24.386Z",
+    "timestamp": "2026-05-21T02:10:35.980Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.22",
+      "bom-ref": "@blamejs/core@0.11.23",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.22",
+      "version": "0.11.23",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.22",
+      "purl": "pkg:npm/%40blamejs/core@0.11.23",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.22",
+      "ref": "@blamejs/core@0.11.23",
       "dependsOn": []
     }
   ]