@blamejs/core 0.9.19 → 0.9.21

package/lib/guard-agent-registry.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * @module     b.guardAgentRegistry
+ * @nav        Guards
+ * @title      Guard Agent Registry
+ * @order      435
+ *
+ * @intro
+ *   Registry-op shape validator for `b.agent.orchestrator.register` /
+ *   `lookup` / `unregister`. Refuses agent names that wouldn't be
+ *   safe to surface in audit logs, registry queries, or routing
+ *   keys:
+ *
+ *     - non-ASCII (NFC-normalized + ASCII-only — operator-greppable)
+ *     - path-traversal shapes (`..` / `/` / `\` / NUL / C0 / DEL)
+ *     - oversized (default 64 bytes per name)
+ *     - reserved `FRAMEWORK.*` / `ROOT` / `*` prefix from operator code
+ *     - duplicate-on-register (caller must `unregister` first)
+ *
+ * @card
+ *   Validates `b.agent.orchestrator.register` op shapes. Path-traversal
+ *   refusal, reserved-prefix refusal, non-ASCII refusal, oversize cap.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardAgentRegistryError = defineClass("GuardAgentRegistryError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxNameBytes: 64,  maxKindBytes: 32  },                                               // allow:raw-byte-literal
+  balanced:   { maxNameBytes: 128, maxKindBytes: 64  },                                               // allow:raw-byte-literal
+  permissive: { maxNameBytes: 512, maxKindBytes: 128 },                                               // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var RESERVED_PREFIXES = Object.freeze(["FRAMEWORK.", "ROOT.", "framework.", "root."]);
+var RESERVED_EXACT    = Object.freeze({ "ROOT": true, "FRAMEWORK": true, "*": true });
+
+/**
+ * @primitive b.guardAgentRegistry.validate
+ * @signature b.guardAgentRegistry.validate(op, opts?)
+ * @since     0.9.21
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * Validate a `{ kind, name, agent, opts }` registry op shape. Returns
+ * the op on success; throws `GuardAgentRegistryError` on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardAgentRegistry.validate({
+ *     kind: "register",
+ *     name: "tenant-acme-mail",
+ *     agentKind: "mail",
+ *   });
+ */
+function validate(op, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!op || typeof op !== "object") {
+    throw new GuardAgentRegistryError("agent-registry/bad-input",
+      "guardAgentRegistry.validate: op required");
+  }
+  if (op.kind !== "register" && op.kind !== "lookup" && op.kind !== "unregister" && op.kind !== "list") {
+    throw new GuardAgentRegistryError("agent-registry/bad-kind",
+      "guardAgentRegistry.validate: op.kind must be 'register' | 'lookup' | 'unregister' | 'list'");
+  }
+  if (op.kind === "list") return op;            // list takes optional filters only
+
+  _checkName(op.name, profile);
+  if (op.kind === "register") {
+    if (typeof op.agentKind !== "string" || op.agentKind.length === 0) {
+      throw new GuardAgentRegistryError("agent-registry/no-kind",
+        "guardAgentRegistry.validate: register op requires agentKind");
+    }
+    _checkKind(op.agentKind, profile);
+  }
+  return op;
+}
+
+/**
+ * @primitive b.guardAgentRegistry.compliancePosture
+ * @signature b.guardAgentRegistry.compliancePosture(posture)
+ * @since     0.9.21
+ * @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.guardAgentRegistry.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _checkName(name, profile) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new GuardAgentRegistryError("agent-registry/bad-name",
+      "guardAgentRegistry.validate: op.name must be a non-empty string");
+  }
+  if (Buffer.byteLength(name, "utf8") > profile.maxNameBytes) {
+    throw new GuardAgentRegistryError("agent-registry/name-too-long",
+      "guardAgentRegistry.validate: name exceeds maxNameBytes=" + profile.maxNameBytes);
+  }
+  if (RESERVED_EXACT[name]) {
+    throw new GuardAgentRegistryError("agent-registry/reserved-name",
+      "guardAgentRegistry.validate: name '" + name + "' is framework-reserved");
+  }
+  for (var p = 0; p < RESERVED_PREFIXES.length; p += 1) {
+    if (name.indexOf(RESERVED_PREFIXES[p]) === 0) {
+      throw new GuardAgentRegistryError("agent-registry/reserved-prefix",
+        "guardAgentRegistry.validate: name '" + name + "' uses reserved prefix '" +
+        RESERVED_PREFIXES[p] + "'");
+    }
+  }
+  if (name.indexOf("..") >= 0) {
+    throw new GuardAgentRegistryError("agent-registry/path-traversal",
+      "guardAgentRegistry.validate: name contains '..'");
+  }
+  for (var i = 0; i < name.length; i += 1) {
+    var c = name.charCodeAt(i);
+    if (c > 0x7F) {                                                                                   // allow:raw-byte-literal — ASCII-only cap
+      throw new GuardAgentRegistryError("agent-registry/non-ascii",
+        "guardAgentRegistry.validate: name contains non-ASCII codepoint at offset " + i);
+    }
+    if (c < 0x20 || c === 0x7F || c === 0x2F || c === 0x5C) {                                         // allow:raw-byte-literal — C0 / DEL / slash / backslash
+      throw new GuardAgentRegistryError("agent-registry/bad-name-char",
+        "guardAgentRegistry.validate: name contains forbidden char 0x" + c.toString(16));
+    }
+  }
+}
+
+function _checkKind(kind, profile) {
+  if (Buffer.byteLength(kind, "utf8") > profile.maxKindBytes) {
+    throw new GuardAgentRegistryError("agent-registry/kind-too-long",
+      "guardAgentRegistry.validate: agentKind exceeds maxKindBytes=" + profile.maxKindBytes);
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(kind)) {                                                              // allow:regex-no-length-cap — kind length bounded above
+    throw new GuardAgentRegistryError("agent-registry/bad-kind-shape",
+      "guardAgentRegistry.validate: agentKind must match /^[a-z][a-z0-9-]*$/");
+  }
+}
+
+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 GuardAgentRegistryError("agent-registry/bad-profile",
+      "guardAgentRegistry: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                  validate,
+  compliancePosture:         compliancePosture,
+  PROFILES:                  PROFILES,
+  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
+  RESERVED_PREFIXES:         RESERVED_PREFIXES,
+  RESERVED_EXACT:            RESERVED_EXACT,
+  GuardAgentRegistryError:   GuardAgentRegistryError,
+  NAME:                      "agentRegistry",
+  KIND:                      "agent-registry",
+};

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",
+};