@blamejs/core 0.9.18 → 0.9.20

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.20 (2026-05-14) — **`b.mail.agent` — the standardization contract for every mail protocol blamejs ships.** Every above-the-wire mail surface (JMAP at v0.9.27, IMAP at v0.9.28, POP3 at v0.9.29, ManageSieve at v0.9.30, the MX listener at v0.9.24, submission at v0.9.25) translates protocol calls into `agent.X(args)`; RBAC, posture enforcement, audit emission, dispatch, and worker isolation are owned at the agent. (1) **`b.mail.agent.create({ store, audit, permissions, posture, identity, dispatch })`** — facade with 23 methods. Read surface (`search` / `fetch` / `thread` / `folders` / `quota`) is backed by v0.9.19 `b.mailStore` and runs immediately. Move surface (`move` / `flag` / `delete`) is backed by the new `mailStore.moveMessages` substrate; soft-delete moves to Trash + tags `\Deleted` (hard expunge wires at v0.9.28 with retention-floor enforcement). Write surface (`compose` / `send` / `reply` / `forward`), Sieve (`sieve.list/put/activate`), identity (`identity.set` / `vacation.set`), MDN (`mdn.send/parse/allowList`), regulated export, and migration `import` throw `mail-agent/not-implemented` with a `wiredAt` tag naming the slice that lights them up (defer-with-condition per the v1-defensible-scope rule). (2) **Dispatch contract** — `dispatch.mode` is `"local"` / `"queue"` / `"auto"`. `local` runs every method in-process. `queue` publishes envelopes to `mail.agent.tasks` via `b.queue.enqueue`; an `agent.consumer({ agent, queue })` running in a dedicated process or replicas across hosts pulls and executes. Posture metadata travels with each envelope; the consumer re-validates against its own posture before unseal so no posture downgrade survives the queue boundary. `auto` routes fast-path ops (`fetch` / `folders` / `flag` / `quota`) locally and heavy ops (`search` / `export`) to queue/workerPool when configured. (3) **Worker isolation** — `dispatch.workerPool` (composes `b.workerPool`) is validated at create-time; the agent reserves `vaultKeyDelivery: "in-worker"` (default) vs `"main-only"` (posture-conditional — HIPAA/PCI/GDPR default to main-only when the worker-script path wires at v0.9.26 Sieve). (4) **`b.mail.agent.consumer`** — the queue-side facade for multi-host load-spreading; carries its own `store` and re-validates posture at the boundary. (5) **Five new guards** through `b.gateContract` — **`b.guardMailQuery`** (search/fetch filter shape: bounded depth/keys/array-length, function/regex/Buffer/cycle refusal, `__proto__` key refusal, projection-column allowlist via `FILTERABLE_COLUMNS`, posture-required actor fields HIPAA→`purposeOfUse` / PCI→`pciScope` / GDPR→`lawfulBasis`); **`b.guardMailCompose`** (draft envelope: identity-vs-From alignment, recipient deduplication, attachment-byte cap default 25 MiB, body shape — exactly one of text/html unless `allowMultipartAlternative`, C0 control-char refusal in headers); **`b.guardMailReply`** (References-chain cap default 100 defends infinite-loop forwards, In-Reply-To continuity per RFC 5322 §3.6.4 — last References must match In-Reply-To, quoted-original byte cap, forwarded-attachment cardinality cap); **`b.guardMailMove`** (system-folder allowlist for INBOX/Sent/Drafts/Trash/Junk/Archive, admin-scope or `allowedFolders` gate for arbitrary destinations, path-traversal refusal, slash refusal — IMAP `.` hierarchy separator only); **`b.guardMailSieve`** (pre-parser shape-only: script-byte cap default 64 KiB, line-count cap defends one-byte-line bombs, name shape — path-traversal / slash / backslash refusal, actor-ownership check — non-admin actors restricted to their `ownedNames`; full Sieve parse at v0.9.26 via `b.safeSieve`). Each guard ships `strict` / `balanced` / `permissive` profiles and `hipaa` / `pci-dss` / `gdpr` / `soc2` postures (all pin `strict`). (6) **`b.mailStore.moveMessages(fromFolder, toFolder, objectIds)`** — per IMAP4rev2 §6.6.2, both folders bump modseq on move; agent.move composes this. (7) Fuzz harnesses ship for every new guard and the v0.9.19 substrates (`safe-mime` / `guard-message-id`) are now wired into the ClusterFuzzLite matrix.
+- v0.9.19 (2026-05-14) — **First slice of the blamepost mail-stack sequence — `b.mailStore` + `b.safeMime` + `b.guardMessageId` substrates.** Byte-level mail-store foundation that every above-the-wire mail primitive composes (agent at v0.9.20, MX listener at v0.9.23, submission listener at v0.9.24, JMAP/IMAP/POP3 at v0.9.26-29, ManageSieve at v0.9.30, DAV at v0.9.32). (1) **`b.safeMime`** — RFC 5322 + 2045/2046/2047/EAI MIME parser. Bounded: total parts cap (default 64), nesting-depth cap (default 16), boundary length cap (default 70 per RFC 2046 §5.1.1), header-bytes cap (default 64 KiB), header-line cap (default 998 per RFC 5322 §2.1.1), body-bytes cap (default 25 MiB), message cap (default 50 MiB), charset allowlist (UTF-8 / US-ASCII / common legacy 8-bit), transfer-encoding allowlist (7bit/8bit/binary/qp/base64). Surface: `parse(bytes, opts) → tree`, `walk(tree, visitor)`, `findFirst(tree, predicate)`, `extractText(tree, opts)` (RFC 2046 §5.1.4 last-wins for `multipart/alternative`), `extractAttachments(tree, opts)`. Includes RFC 2047 Q + B encoded-word decoding for `Subject:` / `From:` etc. + RFC 2231 charset'lang'value filename decoding. Throws `safe-mime/<code>` on every cap exceeded / malformed boundary / unknown charset / unknown CTE / control chars in headers / NUL bytes. **Defends CVE-2024-39929** (Exim MIME multipart parser) and **CVE-2025-30258** (gnumail truncated-MIME-tree class). Fuzz harness ships in `fuzz/safe-mime.fuzz.js`. (2) **`b.guardMessageId`** — RFC 5322 §3.6.4 Message-Id validator. Gates Message-Id / In-Reply-To / References at the mail-store append boundary, the MX inbound boundary (v0.9.23), and the submission outbound path (v0.9.24). Refuses oversized (>998 bytes), bare CR/LF/NUL/C0-control/DEL (header-injection defense — defends `From:` / `Bcc:` smuggling via folded Message-Id continuation), unbracketed under strict profile, empty value, missing `@`, nested angle brackets, bidi codepoints (CVE-2021-42574 RTLO class in mail-header context). Profile family: strict (default) / balanced / permissive. Posture family: hipaa / pci-dss / gdpr / soc2 → all pin profile to strict. Surface: `validate(value, opts)`, `validateList(value, opts)` (References-chain cap = 100), `compliancePosture(posture)`. Fuzz harness ships in `fuzz/guard-message-id.fuzz.js`. (3) **`b.mailStore`** — byte-level mail-store substrate with pluggable backend (sqlite default; operator's `b.externalDb` Postgres or any `{ prepare(sql) → { run, get, all } }`-shaped object). Surface: `create(opts)` returning `{ appendMessage, fetchByObjectId, queryByModseq, setFlags, createFolder, listFolders, threadFor, quota, setLegalHold }`. **Sealed by default** via `b.cryptoField.sealRow` — `subject` / `from_addr` / `to_addrs` / `body_text` / `body_html` route through vault-managed AEAD envelope on insert + unseal on fetch. Plaintext (forensic-queryable without unsealing): `objectid` / `modseq` / `internal_date` / `received_at` / `size_bytes` / `flags` / `legal_hold` / `from_hash` / `message_id_hash`. Per-folder monotonic `modseq` counter (RFC 7162 CONDSTORE substrate). Per-message `objectid` (RFC 8474 JMAP cross-protocol identity). Threading at append time via In-Reply-To + References chain walk (cryptoField.lookupHash for hash-aware threading on sealed columns). Quota substrate (per-folder `used_bytes` + `used_count` maintained atomically). Legal-hold flag composes existing `b.legalHold`. Schema bootstraps at construction with six IMAP4rev2 default folders (INBOX / Sent / Drafts / Trash / Junk / Archive) and JMAP role mapping. Append composes `b.safeMime.parse` (bounded inbound) + `b.guardMessageId.validate` (header-injection gate). **Per the operator-confirmed blamepost roadmap** (`memory/specs/blamepost-roadmap.md`); next slice v0.9.20 wires `b.mail.agent` on top of this substrate.
 - v0.9.18 (2026-05-14) — **18 CodeQL alerts closed across 4 rule classes + SECURITY.md hardening checklist additions for v0.9.13+ primitives + MIGRATING.md out-of-band breaking-changes section.** Post-v0.9.17 audit identified 18 pre-existing CodeQL security findings on `main` — accumulated over many releases, surfaced explicitly when v0.9.15's rename sweep changed line content. v0.9.18 closes them all. (1) **`js/file-system-race` (6 sites)** — TOCTOU between `fs.existsSync()` / `fs.statSync()` and a subsequent file op. Fixed via the framework's canonical TOCTOU-safe-read scaffold (open fd first → `fstatSync` → `readSync` loop → `closeSync` in `finally`) at `lib/atomic-file.js` (`_readSyncCore`), `lib/restore-rollback.js` (marker write switched to exclusive-create `wx` + EEXIST-tolerant), `lib/network-tls.js` (`_readPathFile` extraction with per-file ENOENT tolerance), `lib/backup/bundle.js` (open-fd-first plus required-vs-skip branch routing), `lib/static.js` (request-serve hot path narrowed to single fd). `lib/vault/seal-pem-file.js` retained as-is with a CodeQL suppression — the site has an in-line `lstat.ino === fstat.ino` inode-equality defense (line 290) that refuses with `seal-pem-file/toctou-detected` if an attacker swaps the file between `lstat` and `open`. (2) **`js/insecure-temporary-file` (6 sites)** — predictable temp paths. `lib/vault/rotate.js` now uses `mkdtempSync` for a per-rotation random scratch dir + plain filenames inside (replaces the predictable `_blamejs_rotate.tmp.db` / `_blamejs_verify.tmp.db` paths in `stagingDir`). `lib/mtls-ca.js` switched to exclusive-create `openSync(..., "wx", 0o600)` + `writeSync` + `fsyncSync` so an attacker pre-creating the path is refused at `EEXIST`. `lib/atomic-file.js` (`fsyncDir`), `lib/vault/rotate.js` (`_fsyncFileByPath`), `lib/http-client.js` (atomic tmp path) retained as-is with suppressions — `dirPath` / `p` are operator-supplied framework data paths (not `os.tmpdir`-reachable), and `tmpPath` carries 16 hex chars of crypto-random suffix (line 1802 `dest + ".tmp-" + bCrypto.generateToken(8)`). (3) **`js/path-injection` (2 sites in `lib/static.js`)** — `nodeFs.createReadStream(absPath)` in `_readMeta` (line 161) and the request-serve hot path (line 1115). Suppression comments added referencing the upstream `_resolveSafe` lexical-resolve + `startsWith(rootResolved + nodePath.sep)` + realpath escape check at lines 181-207 — `absPath` is sandbox-validated against `root` before reaching these lines. (4) **`js/remote-property-injection` (4 sites)** — `lib/websocket.js` (`ext.params: {}` → `Object.create(null)`), `lib/middleware/csrf-protect.js` (`var out = {}` → `Object.create(null)` for cookie-parse output). `lib/middleware/body-parser.js` (multipart `fields[currentField] = ...`) retained as-is with suppression — `currentField` is gated upstream at line 867 by `POISONED_KEYS = new Set(["__proto__", "constructor", "prototype"])` refusing the field BEFORE assignment with a 400 BodyParserError. **Plus: SECURITY.md hardening checklist** gains 5 lines covering `b.middleware.idempotencyKey.dbStore` (hash + seal defaults), `b.metrics.snapshot` (out-of-process metrics export), `b.selfUpdate.standaloneVerifier` (zero-dep install-pipeline verifier), `b.pqcAgent.reload` (TLS-posture refresh without restart), `b.crypto.hashFilesParallel` (parallel SBOM/integrity-sweep hashing). **Plus: MIGRATING.md** now carries an "Out-of-band breaking changes" section (the v0.9.15 dbStore schema break is the first entry); `scripts/gen-migrating.js` extended with an `OUT_OF_BAND_BREAKS` table so future schema/on-disk format breaks land in MIGRATING.md without operators needing to grep CHANGELOG.
 - v0.9.17 (2026-05-14) — **Two new `codebase-patterns` detectors + 192-site cleanup sweep — `node:` prefix consistency + internal-binding leak prevention.** Post-v0.9.16 audit surfaced two enforceable invariants the existing detectors didn't cover. (1) **`node-builtin-prefix` detector** — every `require("<X>")` of a Node built-in (`fs`, `path`, `crypto`, `stream`, `tls`, `url`, `os`, `net`, `http`, `http2`, `https`, `zlib`, `dgram`, `events`, `child_process`, `readline`, …) must use the modern `require("node:<X>")` form. Three reasons: (a) userland packages on npm CAN be named after built-ins, so without the `node:` prefix a typo or `npm install` accident could shadow the built-in; (b) the prefix is a clearer at-a-glance signal that the dependency is on Node, not on a userland module; (c) bundler / SEA static-trace passes treat `node:` prefix as an unambiguous Node-builtin marker. Sweep: 153 `require()` rewrites across 79 framework files (2 parallel agents). The detector skips JSDoc `@example` block continuation lines (`*`-prefixed), so operator-facing examples that show `var fs = require("fs")` aren't rewritten — operators write their own bindings however they prefer. (2) **`internal-binding-in-prose` detector** — internal binding names (`nodeFs` / `nodePath` / `nodeCrypto` / `nodeStream` / `nodeTls` / `nodeUrl` / `bCrypto` / `retryHelper`) must NOT appear in operator-facing surface: JSDoc/comment continuation lines or string literals (error messages, audit metadata). Operators see the public API name (`path` / `fs` / `crypto` / `retry` / …), never the framework's internal alias. Sweep: 39 prose-leak fixes across 16 files — comments rewritten to use the operator-facing word (`nodePath` → `path`, `nodeFs.watch failed` → `fs.watch failed`, debug-log `"op": "nodeFs.unlinkSync"` → `"op": "fs.unlinkSync"`). (3) **2 follow-on require-binding canonicalizations** surfaced by the node-prefix sweep — `lib/ws-client.js` now destructures `var { EventEmitter } = require("node:events")` (was binding the entire `events` module to a class-shaped name) and `lib/process-spawn.js` renames inline `nodeChild` → `childProcess` (matches the module-level `childProcess` lazyRequire in `lib/dev.js`).
 - v0.9.16 (2026-05-14) — **Operator-facing prose cleanup + `require-binding-name` detector now covers `lazyRequire` wrappers + dbStore seal round-trip test added.** Post-v0.9.15 audit surfaced three classes of follow-up. (1) **Operator-facing prose leaks (7 sites)** — the v0.9.15 mechanical rename pattern `<OLD>.` → `<NEW>.` also caught occurrences inside JSDoc `@opts` comments and error-message string literals, so operators reading `b.keychain.create(opts)` saw `// absolute nodePath; required if file fallback may engage` instead of `// absolute path`. Fixed: `lib/db.js` (stream-limit error), `lib/keychain.js` (fallback-file error + 3 JSDoc lines), `lib/restore-bundle.js` (staging-dir error), `lib/watcher.js` (fs.watch failure error). Operators see plain English; internal binding names stay internal. (2) **`require-binding-name` detector extended to cover `lazyRequire`** — the v0.9.15 detector only matched plain `var X = require("M")` and missed the framework's `var X = lazyRequire(function () { return require("M"); })` pattern (used to break load cycles). 34 additional inconsistencies surfaced (`auditFwk` / `auditMod` / `auditModule` / `lazyAudit` → `audit`, `crypto` / `fwCrypto` → `bCrypto`, `dbMod` / `dbModule` → `db`, etc.) — every minority site renamed per the same canonical-name map. (3) **dbStore seal round-trip test** — the v0.9.15 test suite covered seal-falls-back-when-vault-not-ready and cross-process-sealed-row-preserved, but did NOT exercise the actual default-ON seal/unseal path because the test environment didn't `b.vault.init(...)`. New `testDbStoreSealRoundTripWithVault` bootstraps a plaintext vault, builds a dbStore with `seal: true`, writes a record + reads it back, and asserts (a) `headers` + `body` columns carry the `vault:` envelope on disk, (b) the round-trip restores the original values, and (c) `status_code` stays plaintext so forensic SELECTs still work without unsealing.

package/index.js

@@ -86,6 +86,8 @@ var session = require("./lib/session");
 var storage = require("./lib/storage");
 var safeJson = require("./lib/safe-json");
 var safeJsonPath = require("./lib/safe-jsonpath");
+var safeMime = require("./lib/safe-mime");
+var mailStore = require("./lib/mail-store");
 var ntpCheck = require("./lib/ntp-check");
 var auditSign = require("./lib/audit-sign");
 var objectStore = require("./lib/object-store");
@@ -157,6 +159,12 @@ var guardCsv = require("./lib/guard-csv");
 var guardHtml = require("./lib/guard-html");
 var guardSvg = require("./lib/guard-svg");
 var guardFilename = require("./lib/guard-filename");
+var guardMessageId = require("./lib/guard-message-id");
+var guardMailQuery = require("./lib/guard-mail-query");
+var guardMailCompose = require("./lib/guard-mail-compose");
+var guardMailReply = require("./lib/guard-mail-reply");
+var guardMailMove = require("./lib/guard-mail-move");
+var guardMailSieve = require("./lib/guard-mail-sieve");
 var guardArchive = require("./lib/guard-archive");
 var guardJson = require("./lib/guard-json");
 var guardYaml = require("./lib/guard-yaml");
@@ -394,6 +402,12 @@ module.exports = {
   guardHtml:        guardHtml,
   guardSvg:         guardSvg,
   guardFilename:    guardFilename,
+  guardMessageId:   guardMessageId,
+  guardMailQuery:   guardMailQuery,
+  guardMailCompose: guardMailCompose,
+  guardMailReply:   guardMailReply,
+  guardMailMove:    guardMailMove,
+  guardMailSieve:   guardMailSieve,
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,
@@ -473,6 +487,8 @@ module.exports = {
   flag:             flag,
   safeJson:         safeJson,
   safeJsonPath:     safeJsonPath,
+  safeMime:         safeMime,
+  mailStore:        mailStore,
   safeSchema:       safeSchema,
   pagination:       pagination,
   metrics:          metrics,

package/lib/guard-mail-compose.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * @module     b.guardMailCompose
+ * @nav        Guards
+ * @title      Guard Mail Compose
+ * @order      431
+ *
+ * @intro
+ *   Outbound draft validator for `b.mail.agent.compose` /
+ *   `b.mail.agent.reply` / `b.mail.agent.forward`. Composes the
+ *   existing `b.guardEmail.validateMessage` for address + header shape
+ *   and adds compose-specific rules:
+ *
+ *     - identity vs From alignment — operator-supplied `identity.email`
+ *       must equal the From header local-part + domain (defends spoof-
+ *       at-submission)
+ *     - recipient deduplication — Sender / To / Cc / Bcc combined
+ *       cardinality cap (default 100; envelope-from never duplicated)
+ *     - attachment byte cap — sum of `body.attachments[*].size_bytes`
+ *       must not exceed `maxAttachmentBytes` (default 25 MiB to match
+ *       the RFC 5321 §4.5.3.1.10 receiver cap)
+ *     - body shape — exactly one of `text` / `html` required (multipart
+ *       at submission-time per RFC 2046 §5.1.3); both allowed when
+ *       operator explicitly opts in via `allowMultipartAlternative`
+ *     - Subject control-char refusal — same C0 / DEL rule the existing
+ *       `b.guardEmail` applies to header values
+ *
+ *   Profile vocabulary mirrors the rest of the guard family
+ *   (`strict` / `balanced` / `permissive`); posture vocabulary
+ *   (`hipaa` / `pci-dss` / `gdpr` / `soc2`) pins `strict`.
+ *
+ * @card
+ *   Validates outbound mail drafts at `b.mail.agent.compose`.
+ *   Identity-vs-From alignment, recipient dedup, attachment byte cap,
+ *   body shape, header control-char refusal.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardMailComposeError = defineClass("GuardMailComposeError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxRecipients: 100,  maxAttachmentBytes: 26214400, maxSubjectBytes: 998 },            // allow:raw-byte-literal — 25 MiB, RFC 5322 §2.1.1 line cap
+  balanced:   { maxRecipients: 500,  maxAttachmentBytes: 52428800, maxSubjectBytes: 998 },            // allow:raw-byte-literal — 50 MiB
+  permissive: { maxRecipients: 2000, maxAttachmentBytes: 104857600, maxSubjectBytes: 998 },           // allow:raw-byte-literal — 100 MiB
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardMailCompose.validate
+ * @signature b.guardMailCompose.validate(draft, opts?)
+ * @since     0.9.20
+ * @status    stable
+ * @related   b.guardMailReply, b.guardEmail
+ *
+ * Validate an outbound draft envelope. Returns the input on success;
+ * throws `GuardMailComposeError` on refusal.
+ *
+ * @opts
+ *   profile:    "strict" | "balanced" | "permissive",
+ *   posture:    "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   identity:   { email: string, name?: string },        // required if checkIdentity
+ *   checkIdentity: boolean,                               // default true
+ *   allowMultipartAlternative: boolean,                   // default false
+ *
+ * @example
+ *   b.guardMailCompose.validate({
+ *     from:    "alice@example.com",
+ *     to:      ["bob@example.com"],
+ *     subject: "hello",
+ *     body:    { text: "hi" },
+ *   }, { identity: { email: "alice@example.com" } });
+ */
+function validate(draft, opts) {
+  opts = opts || {};
+  var profileName = _resolveProfile(opts);
+  var profile = PROFILES[profileName];
+  if (!draft || typeof draft !== "object") {
+    throw new GuardMailComposeError("mail-compose/bad-input",
+      "guardMailCompose.validate: draft required");
+  }
+  if (typeof draft.from !== "string" || draft.from.length === 0) {
+    throw new GuardMailComposeError("mail-compose/no-from",
+      "guardMailCompose.validate: draft.from required");
+  }
+  _checkHeaderValue(draft.from, "from");
+  _checkAddrList(draft.to,  "to",  profile);
+  _checkAddrList(draft.cc,  "cc",  profile);
+  _checkAddrList(draft.bcc, "bcc", profile);
+  if (!_anyRecipient(draft)) {
+    throw new GuardMailComposeError("mail-compose/no-recipient",
+      "guardMailCompose.validate: at least one to/cc/bcc required");
+  }
+  _checkRecipientCardinality(draft, profile);
+
+  if (typeof draft.subject !== "undefined") {
+    if (typeof draft.subject !== "string") {
+      throw new GuardMailComposeError("mail-compose/bad-subject",
+        "guardMailCompose.validate: subject must be a string");
+    }
+    if (Buffer.byteLength(draft.subject, "utf8") > profile.maxSubjectBytes) {
+      throw new GuardMailComposeError("mail-compose/subject-too-long",
+        "guardMailCompose.validate: subject exceeds maxSubjectBytes=" + profile.maxSubjectBytes);
+    }
+    _checkHeaderValue(draft.subject, "subject");
+  }
+
+  _checkBody(draft.body, profile, !!opts.allowMultipartAlternative);
+
+  // Identity vs From alignment — defends spoof-at-submission. When the
+  // operator wires an identity for the actor, the draft's From: header
+  // must match that identity's email. Disable explicitly via
+  // checkIdentity: false (e.g. shared-mailbox submission roles).
+  var checkIdentity = opts.checkIdentity !== false;
+  if (checkIdentity && opts.identity && opts.identity.email) {
+    var fromAddr = _extractAddr(draft.from);
+    if (fromAddr.toLowerCase() !== String(opts.identity.email).toLowerCase()) {
+      throw new GuardMailComposeError("mail-compose/identity-mismatch",
+        "guardMailCompose.validate: From '" + fromAddr +
+        "' does not match identity '" + opts.identity.email + "'");
+    }
+  }
+  return draft;
+}
+
+/**
+ * @primitive b.guardMailCompose.compliancePosture
+ * @signature b.guardMailCompose.compliancePosture(posture)
+ * @since     0.9.20
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardMailCompose.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _checkAddrList(list, label, profile) {
+  if (typeof list === "undefined" || list === null) return;
+  if (!Array.isArray(list)) {
+    throw new GuardMailComposeError("mail-compose/bad-addr-list",
+      "guardMailCompose.validate: " + label + " must be an array of strings");
+  }
+  if (list.length > profile.maxRecipients) {
+    throw new GuardMailComposeError("mail-compose/too-many-recipients",
+      "guardMailCompose.validate: " + label + " count " + list.length +
+      " exceeds maxRecipients=" + profile.maxRecipients);
+  }
+  for (var i = 0; i < list.length; i += 1) {
+    if (typeof list[i] !== "string" || list[i].length === 0) {
+      throw new GuardMailComposeError("mail-compose/bad-addr",
+        "guardMailCompose.validate: " + label + "[" + i + "] must be a non-empty string");
+    }
+    _checkHeaderValue(list[i], label + "[" + i + "]");
+    var addr = _extractAddr(list[i]);
+    if (addr.indexOf("@") < 0) {
+      throw new GuardMailComposeError("mail-compose/bad-addr",
+        "guardMailCompose.validate: " + label + "[" + i + "] missing '@'");
+    }
+  }
+}
+
+function _checkRecipientCardinality(draft, profile) {
+  var all = [];
+  ["to", "cc", "bcc"].forEach(function (k) {
+    if (Array.isArray(draft[k])) {
+      for (var i = 0; i < draft[k].length; i += 1) {
+        all.push(_extractAddr(draft[k][i]).toLowerCase());
+      }
+    }
+  });
+  if (all.length > profile.maxRecipients) {
+    throw new GuardMailComposeError("mail-compose/too-many-recipients",
+      "guardMailCompose.validate: combined recipient count " + all.length +
+      " exceeds maxRecipients=" + profile.maxRecipients);
+  }
+  var seen = Object.create(null);
+  for (var j = 0; j < all.length; j += 1) {
+    if (seen[all[j]]) {
+      throw new GuardMailComposeError("mail-compose/duplicate-recipient",
+        "guardMailCompose.validate: '" + all[j] + "' appears in multiple recipient fields");
+    }
+    seen[all[j]] = true;
+  }
+}
+
+function _checkBody(body, profile, allowAlt) {
+  if (!body || typeof body !== "object") {
+    throw new GuardMailComposeError("mail-compose/no-body",
+      "guardMailCompose.validate: draft.body required");
+  }
+  var hasText = typeof body.text === "string" && body.text.length > 0;
+  var hasHtml = typeof body.html === "string" && body.html.length > 0;
+  if (!hasText && !hasHtml) {
+    throw new GuardMailComposeError("mail-compose/empty-body",
+      "guardMailCompose.validate: body.text or body.html required");
+  }
+  if (hasText && hasHtml && !allowAlt) {
+    throw new GuardMailComposeError("mail-compose/multipart-alternative-disallowed",
+      "guardMailCompose.validate: both text + html supplied — set allowMultipartAlternative: true");
+  }
+  if (Array.isArray(body.attachments)) {
+    var total = 0;
+    for (var i = 0; i < body.attachments.length; i += 1) {
+      var a = body.attachments[i];
+      if (!a || typeof a !== "object") {
+        throw new GuardMailComposeError("mail-compose/bad-attachment",
+          "guardMailCompose.validate: attachment[" + i + "] must be an object");
+      }
+      var size = typeof a.sizeBytes === "number" ? a.sizeBytes :
+                 (typeof a.size_bytes === "number" ? a.size_bytes : 0);
+      if (size < 0 || !isFinite(size)) {
+        throw new GuardMailComposeError("mail-compose/bad-attachment-size",
+          "guardMailCompose.validate: attachment[" + i + "].sizeBytes invalid");
+      }
+      total += size;
+      if (total > profile.maxAttachmentBytes) {
+        throw new GuardMailComposeError("mail-compose/attachment-too-big",
+          "guardMailCompose.validate: attachment total " + total +
+          " exceeds maxAttachmentBytes=" + profile.maxAttachmentBytes);
+      }
+    }
+  }
+}
+
+function _checkHeaderValue(v, label) {
+  for (var i = 0; i < v.length; i += 1) {
+    var c = v.charCodeAt(i);
+    if ((c < 0x20 && c !== 0x09) || c === 0x7F) {                                                     // allow:raw-byte-literal — C0 + DEL refusal in header
+      throw new GuardMailComposeError("mail-compose/control-char-in-header",
+        "guardMailCompose.validate: control char 0x" + c.toString(16) + " in " + label);
+    }
+  }
+}
+
+function _extractAddr(s) {
+  var lt = s.indexOf("<");
+  var gt = s.lastIndexOf(">");
+  if (lt >= 0 && gt > lt) return s.slice(lt + 1, gt).trim();
+  return s.trim();
+}
+
+function _anyRecipient(draft) {
+  return ["to", "cc", "bcc"].some(function (k) {
+    return Array.isArray(draft[k]) && draft[k].length > 0;
+  });
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardMailComposeError("mail-compose/bad-profile",
+      "guardMailCompose: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:            validate,
+  compliancePosture:   compliancePosture,
+  PROFILES:            PROFILES,
+  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
+  GuardMailComposeError: GuardMailComposeError,
+  NAME:                "mailCompose",
+  KIND:                "mail-compose",
+};

package/lib/guard-mail-move.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * @module     b.guardMailMove
+ * @nav        Guards
+ * @title      Guard Mail Move
+ * @order      433
+ *
+ * @intro
+ *   Destination-folder allowlist validator for `b.mail.agent.move`.
+ *   Refuses moves to system folders the actor doesn't have admin
+ *   scope for, refuses cross-account moves (`fromFolder` and
+ *   `toFolder` must belong to the same agent context), and refuses
+ *   path-traversal-shaped folder names (`..` / leading `.` / NUL /
+ *   bidi).
+ *
+ *   System folders the framework treats specially:
+ *
+ *     - **INBOX / Sent / Drafts**: always writable by the owner; no
+ *       admin scope required.
+ *     - **Junk / Trash**: always writable (Junk is the default Sieve
+ *       junk destination; Trash is the soft-delete target).
+ *     - **Archive**: always writable.
+ *     - any operator-created folder: writable when in the actor's
+ *       allowed-folders list (per the operator's RBAC) OR when the
+ *       actor has `mailScope: "admin"`.
+ *
+ *   The guard does NOT touch the underlying mail-store; that
+ *   composition lives in `b.mail.agent.move`. The guard validates
+ *   the SHAPE of the move call.
+ *
+ * @card
+ *   Validates `b.mail.agent.move` destination. System-folder allowlist,
+ *   path-traversal refusal, admin-scope gate for arbitrary destinations.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardMailMoveError = defineClass("GuardMailMoveError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxObjectIds: 1000,  maxFolderNameBytes: 255  },                                      // allow:raw-byte-literal
+  balanced:   { maxObjectIds: 5000,  maxFolderNameBytes: 255  },                                      // allow:raw-byte-literal
+  permissive: { maxObjectIds: 50000, maxFolderNameBytes: 1024 },                                      // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// System folders every actor may write to without admin scope.
+var SYSTEM_FOLDERS = Object.freeze({
+  INBOX: true, Sent: true, Drafts: true, Trash: true, Junk: true, Archive: true,
+});
+
+/**
+ * @primitive b.guardMailMove.validate
+ * @signature b.guardMailMove.validate(move, opts?)
+ * @since     0.9.20
+ * @status    stable
+ * @related   b.mail.agent.create
+ *
+ * Validate a `{ actor, fromFolder, toFolder, objectIds }` shape.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardMailMove.validate({
+ *     actor:      { id: "u1", mailScope: "user" },
+ *     fromFolder: "INBOX",
+ *     toFolder:   "Archive",
+ *     objectIds:  ["abc123"],
+ *   });
+ */
+function validate(move, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!move || typeof move !== "object") {
+    throw new GuardMailMoveError("mail-move/bad-input",
+      "guardMailMove.validate: move required");
+  }
+  if (!move.actor || typeof move.actor !== "object" || typeof move.actor.id !== "string") {
+    throw new GuardMailMoveError("mail-move/no-actor",
+      "guardMailMove.validate: move.actor with .id required");
+  }
+  _checkFolderName(move.fromFolder, "fromFolder", profile);
+  _checkFolderName(move.toFolder,   "toFolder",   profile);
+  if (move.fromFolder === move.toFolder) {
+    throw new GuardMailMoveError("mail-move/same-folder",
+      "guardMailMove.validate: fromFolder and toFolder are the same");
+  }
+  if (!Array.isArray(move.objectIds)) {
+    throw new GuardMailMoveError("mail-move/bad-objectids",
+      "guardMailMove.validate: objectIds must be an array");
+  }
+  if (move.objectIds.length === 0) {
+    throw new GuardMailMoveError("mail-move/empty-objectids",
+      "guardMailMove.validate: objectIds must be non-empty");
+  }
+  if (move.objectIds.length > profile.maxObjectIds) {
+    throw new GuardMailMoveError("mail-move/too-many-objectids",
+      "guardMailMove.validate: objectIds count " + move.objectIds.length +
+      " exceeds maxObjectIds=" + profile.maxObjectIds);
+  }
+  for (var i = 0; i < move.objectIds.length; i += 1) {
+    var oid = move.objectIds[i];
+    if (typeof oid !== "string" || oid.length === 0) {
+      throw new GuardMailMoveError("mail-move/bad-objectid",
+        "guardMailMove.validate: objectIds[" + i + "] must be a non-empty string");
+    }
+  }
+
+  // System-folder allowlist OR admin scope OR allowed-folders.
+  var dest = move.toFolder;
+  if (SYSTEM_FOLDERS[dest]) return move;
+  var isAdmin = move.actor.mailScope === "admin";
+  if (isAdmin) return move;
+  var allowed = Array.isArray(move.actor.allowedFolders) ? move.actor.allowedFolders : null;
+  if (allowed && allowed.indexOf(dest) >= 0) return move;
+  throw new GuardMailMoveError("mail-move/destination-not-allowed",
+    "guardMailMove.validate: destination '" + dest +
+    "' requires mailScope:'admin' or membership in actor.allowedFolders");
+}
+
+/**
+ * @primitive b.guardMailMove.compliancePosture
+ * @signature b.guardMailMove.compliancePosture(posture)
+ * @since     0.9.20
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardMailMove.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _checkFolderName(name, label, profile) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new GuardMailMoveError("mail-move/bad-folder-name",
+      "guardMailMove.validate: " + label + " must be a non-empty string");
+  }
+  if (Buffer.byteLength(name, "utf8") > profile.maxFolderNameBytes) {
+    throw new GuardMailMoveError("mail-move/folder-name-too-long",
+      "guardMailMove.validate: " + label + " exceeds maxFolderNameBytes=" + profile.maxFolderNameBytes);
+  }
+  // Path-traversal / control-char refusal. C0 controls, slash, NUL,
+  // leading `.`, and `..` segments are all refused regardless of
+  // profile.
+  if (name.indexOf("..") >= 0) {
+    throw new GuardMailMoveError("mail-move/path-traversal",
+      "guardMailMove.validate: " + label + " contains '..'");
+  }
+  if (name.charAt(0) === ".") {
+    throw new GuardMailMoveError("mail-move/hidden-name",
+      "guardMailMove.validate: " + label + " starts with '.' (hidden-folder shape refused)");
+  }
+  for (var i = 0; i < name.length; i += 1) {
+    var c = name.charCodeAt(i);
+    if (c < 0x20 || c === 0x7F) {                                                                     // allow:raw-byte-literal — C0 + DEL refusal
+      throw new GuardMailMoveError("mail-move/control-char-in-name",
+        "guardMailMove.validate: " + label + " contains control char 0x" + c.toString(16));
+    }
+    if (c === 0x2F) {                                                                                 // allow:raw-byte-literal — '/' refusal
+      throw new GuardMailMoveError("mail-move/slash-in-name",
+        "guardMailMove.validate: " + label + " contains '/' (use IMAP '.' hierarchy separator)");
+    }
+  }
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardMailMoveError("mail-move/bad-profile",
+      "guardMailMove: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:            validate,
+  compliancePosture:   compliancePosture,
+  PROFILES:            PROFILES,
+  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
+  SYSTEM_FOLDERS:      SYSTEM_FOLDERS,
+  GuardMailMoveError:  GuardMailMoveError,
+  NAME:                "mailMove",
+  KIND:                "mail-move",
+};