@blamejs/core 0.11.21 → 0.11.23

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.21",
+  "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:a3658057-6230-4935-a5ba-f8e7aaa9a3c7",
+  "serialNumber": "urn:uuid:e4f090dd-9a46-4d67-b64e-b7b9105c5254",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-20T23:16:52.590Z",
+    "timestamp": "2026-05-21T02:10:35.980Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.21",
+      "bom-ref": "@blamejs/core@0.11.23",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.21",
+      "version": "0.11.23",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.21",
+      "purl": "pkg:npm/%40blamejs/core@0.11.23",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.21",
+      "ref": "@blamejs/core@0.11.23",
       "dependsOn": []
     }
   ]