@blamejs/core 0.9.28 → 0.9.39

package/lib/guard-smtp-command.js

@@ -0,0 +1,484 @@
+"use strict";
+/**
+ * @module     b.guardSmtpCommand
+ * @nav        Guards
+ * @title      Guard SMTP Command
+ * @order      450
+ *
+ * @intro
+ *   SMTP command-line validator. Gates every command verb the framework's
+ *   inbound MX listener (v0.9.34) and outbound submission listener
+ *   (v0.9.35) accept from peers — `EHLO` / `HELO` / `MAIL FROM` /
+ *   `RCPT TO` / `DATA` / `BDAT` / `VRFY` / `EXPN` / `NOOP` / `RSET` /
+ *   `QUIT` / `AUTH` / `STARTTLS` / `HELP`.
+ *
+ *   ## Smuggling defense — bare-CR / bare-LF refusal
+ *
+ *   The SMTP smuggling class (`CVE-2023-51764` Postfix, `CVE-2023-51765`
+ *   Sendmail, `CVE-2023-51766` Exim, `CVE-2026-32178` .NET
+ *   `System.Net.Mail`) exploits implementations that accept the
+ *   non-standard end-of-data sequence `<LF>.<LF>` or `<LF>.<CR><LF>`
+ *   instead of the standard `<CR><LF>.<CR><LF>`. The introduced break-
+ *   out lets a malicious peer inject a second message past SPF / DMARC
+ *   checks performed only on the outer envelope.
+ *
+ *   At the command-line level the defense is the same: every command
+ *   line MUST be CRLF-terminated; bare `\r` or `\n` anywhere inside a
+ *   command line is refused. Operators with peers that legitimately
+ *   speak bare-LF (rare; legacy Sendmail-to-Sendmail) opt into
+ *   `permissive` profile with audit emit per accepted bare-LF line.
+ *
+ *   ## STARTTLS command-buffer injection
+ *
+ *   `CVE-2021-38371` (Exim STARTTLS response injection) and
+ *   `CVE-2021-33515` (Dovecot lib-smtp STARTTLS command injection)
+ *   exploit implementations that don't drain the pre-STARTTLS receive
+ *   buffer when negotiating TLS — commands queued by an MitM before
+ *   the handshake get applied to the post-handshake (TLS-protected)
+ *   stream. The fix is stateful (drain the buffer on STARTTLS), so
+ *   this guard alone can't fully defend; it surfaces the requirement
+ *   to the v0.9.34 listener via `validate({ verb: "STARTTLS" })`
+ *   refusing trailing payload on the STARTTLS line and the listener's
+ *   pipelining-after-STARTTLS check enforcing buffer drain.
+ *
+ *   ## Per-verb shape
+ *
+ *   Each verb has a fixed argument shape (RFC 5321 §3 / §4.1):
+ *
+ *     - `EHLO` / `HELO` — exactly one arg (domain or address literal).
+ *     - `MAIL` — `FROM:<reverse-path>` (RFC 5321 §3.3) + optional
+ *       `SIZE=` / `BODY=` / `RET=` / `ENVID=` / `AUTH=` extension
+ *       params.
+ *     - `RCPT` — `TO:<forward-path>` (RFC 5321 §3.3) + optional
+ *       `NOTIFY=` / `ORCPT=` extension params.
+ *     - `DATA` — no args.
+ *     - `BDAT` — single decimal chunk size + optional `LAST` keyword
+ *       (RFC 3030 CHUNKING).
+ *     - `VRFY` / `EXPN` — single mailbox arg.
+ *     - `NOOP` — optional opaque string.
+ *     - `RSET` / `QUIT` / `STARTTLS` — no args.
+ *     - `AUTH` — SASL mechanism name + optional initial-response
+ *       (RFC 4954).
+ *     - `HELP` — optional argument.
+ *
+ *   Anything not matching the shape under `strict` profile is refused
+ *   with `guard-smtp-command/bad-shape`.
+ *
+ *   ## Caps
+ *
+ *     - Command line (path + arguments + CRLF) capped at 512 bytes
+ *       per RFC 5321 §4.5.3.1.1. SMTPUTF8 / EAI peers (RFC 6531) may
+ *       send longer command lines for non-ASCII addresses; `balanced`
+ *       profile bumps the cap to 1024.
+ *     - Forward-path / reverse-path mailbox capped at 256 bytes per
+ *       RFC 5321 §4.5.3.1.3.
+ *     - Domain part of a path capped at 255 bytes per RFC 1035
+ *       §2.3.4.
+ *     - Local part capped at 64 bytes per RFC 5321 §4.5.3.1.1.
+ *
+ *   Throws `GuardSmtpCommandError` on every refusal. Pure-functional —
+ *   no I/O, no state. The MX / submission listener composes one
+ *   instance per accepted connection.
+ *
+ * @card
+ *   SMTP command-line validator. Refuses bare-CR / bare-LF (smuggling
+ *   defense, CVE-2023-51764/51765/51766/2026-32178), caps line + path
+ *   + domain + local-part byte lengths (RFC 5321 §4.5.3.1), per-verb
+ *   shape check (EHLO / HELO / MAIL FROM / RCPT TO / DATA / BDAT /
+ *   VRFY / EXPN / NOOP / RSET / QUIT / AUTH / STARTTLS / HELP).
+ */
+
+var { defineClass } = require("./framework-error");
+var gateContract    = require("./gate-contract");
+
+var GuardSmtpCommandError = defineClass("GuardSmtpCommandError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+// RFC 5321 §4.5.3.1.1 — 512-octet line cap (excluding the trailing
+// CRLF). SMTPUTF8 / EAI extends this in practice; balanced/permissive
+// raise the cap accordingly.
+var PROFILES = Object.freeze({
+  strict:     { maxLineBytes: 512, maxMailbox: 256, maxLocalPart: 64, maxDomain: 255, allowBareLf: false, allowSmtpUtf8: false },                                                                          // allow:raw-byte-literal — RFC 5321 §4.5.3.1.1 caps
+  balanced:   { maxLineBytes: 1024, maxMailbox: 320, maxLocalPart: 64, maxDomain: 255, allowBareLf: false, allowSmtpUtf8: true },                                                                          // allow:raw-byte-literal — SMTPUTF8 (RFC 6531) line cap
+  permissive: { maxLineBytes: 4096, maxMailbox: 512, maxLocalPart: 64, maxDomain: 255, allowBareLf: true,  allowSmtpUtf8: true },                                                                          // allow:raw-byte-literal — permissive cap for legacy peers
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// Verbs we know — anything else is refused under strict, accepted as
+// opaque under permissive (operator's responsibility to handle).
+var KNOWN_VERBS = Object.freeze({
+  EHLO: true, HELO: true, MAIL: true, RCPT: true, DATA: true,
+  BDAT: true, VRFY: true, EXPN: true, NOOP: true, RSET: true,
+  QUIT: true, AUTH: true, STARTTLS: true, HELP: true,
+});
+
+// Verbs that take exactly zero arguments (anything trailing the verb
+// itself is refused). DATA's trailing CRLF is the end-of-command, not
+// an argument.
+var ZERO_ARG_VERBS = Object.freeze({ DATA: true, RSET: true, QUIT: true, STARTTLS: true });
+
+// Address-literal shape per RFC 5321 §4.1.3 (very loose — full
+// validation lives in safeUrl / IP-address parsing; here we just
+// gate the SMTP-side bracket shape).
+var ADDR_LIT_RE   = /^\[(?:IPv6:)?[0-9A-Fa-f:.]+\]$/;                                                                                                                                                     // allow:regex-no-length-cap — caller's command line is already maxLineBytes-capped
+var DOMAIN_RE     = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/;                                                                                                                                        // allow:regex-no-length-cap — domain length is checked separately against maxDomain
+var DECIMAL_RE    = /^[1-9][0-9]{0,9}$|^0$/;                                                                                                                                                              // allow:regex-no-length-cap — bounded by anchor + repeat-cap
+
+/**
+ * @primitive b.guardSmtpCommand.validate
+ * @signature b.guardSmtpCommand.validate(line, opts?)
+ * @since     0.9.32
+ * @status    stable
+ * @related   b.guardEmail.validateMessage, b.safeMime.parse
+ *
+ * Validate a single SMTP command line (without its CRLF terminator —
+ * the listener strips that before calling this). Returns a structured
+ * `{ verb, args, params }` shape on success; throws
+ * `GuardSmtpCommandError` on any refusal.
+ *
+ * @opts
+ *   profile:  "strict" | "balanced" | "permissive",
+ *   posture:  "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   var parsed = b.guardSmtpCommand.validate("MAIL FROM:<alice@example.com> SIZE=12345");
+ *   // → { verb: "MAIL", args: ["FROM:<alice@example.com>"], params: { SIZE: "12345" } }
+ */
+function validate(line, opts) {
+  opts = opts || {};
+  var caps = _resolveProfile(opts);
+  if (typeof line !== "string") {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-input",
+      "guardSmtpCommand.validate: line must be a string; got " + (typeof line));
+  }
+  if (line.length === 0) {
+    throw new GuardSmtpCommandError("guard-smtp-command/empty",
+      "guardSmtpCommand.validate: empty command line");
+  }
+  if (Buffer.byteLength(line, caps.allowSmtpUtf8 ? "utf8" : "ascii") > caps.maxLineBytes) {
+    throw new GuardSmtpCommandError("guard-smtp-command/oversize-line",
+      "guardSmtpCommand.validate: line exceeds maxLineBytes=" + caps.maxLineBytes +
+      " (RFC 5321 §4.5.3.1.1)");
+  }
+  // Smuggling defense — refuse bare CR / bare LF anywhere in the line.
+  // Listener has already stripped the terminating CRLF before calling.
+  if (line.indexOf("\r") !== -1) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bare-cr",
+      "guardSmtpCommand.validate: bare CR in command line (RFC 5321 §2.3.8; " +
+      "smuggling defense CVE-2023-51764/51765/51766)");
+  }
+  if (line.indexOf("\n") !== -1 && !caps.allowBareLf) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bare-lf",
+      "guardSmtpCommand.validate: bare LF in command line (RFC 5321 §2.3.8; " +
+      "smuggling defense CVE-2023-51764/51765/51766/2026-32178)");
+  }
+  if (line.indexOf("\u0000") !== -1) {
+    throw new GuardSmtpCommandError("guard-smtp-command/nul",
+      "guardSmtpCommand.validate: NUL byte refused");
+  }
+  // C0 controls (except SP=0x20, HTAB=0x09 not legal in commands, and
+  // LF=0x0a when allowBareLf is true under permissive profile per
+  // legacy Sendmail compat) plus DEL.
+  for (var i = 0; i < line.length; i += 1) {
+    var c = line.charCodeAt(i);
+    // LF under permissive: allowed by profile, already passed the
+    // bare-LF refusal earlier in this fn. Skip the control-char throw
+    // so the documented allowBareLf path actually accepts LF (Codex
+    // caught this: permissive profile was effectively broken).
+    if (c === 0x0a && caps.allowBareLf) continue;                                                                                                                                                            // allow:raw-byte-literal — RFC 5321 §2.3.8 LF, permissive bypass
+    if (c < 0x20 || c === 0x7f) {                                                                                                                                                                          // allow:raw-byte-literal — RFC 5321 §2.3.8 forbids C0 / DEL
+      throw new GuardSmtpCommandError("guard-smtp-command/control-char",
+        "guardSmtpCommand.validate: control char 0x" + c.toString(16) + " refused");
+    }
+    if (!caps.allowSmtpUtf8 && c > 0x7e) {                                                                                                                                                                 // allow:raw-byte-literal — RFC 5321 §2.3.1 7-bit ASCII; SMTPUTF8 relaxes
+      throw new GuardSmtpCommandError("guard-smtp-command/non-ascii",
+        "guardSmtpCommand.validate: non-ASCII byte refused (no SMTPUTF8 negotiated)");
+    }
+  }
+  var firstSpace = line.indexOf(" ");
+  var verb = (firstSpace === -1 ? line : line.slice(0, firstSpace)).toUpperCase();
+  var rest = firstSpace === -1 ? "" : line.slice(firstSpace + 1);
+
+  if (!KNOWN_VERBS[verb]) {
+    throw new GuardSmtpCommandError("guard-smtp-command/unknown-verb",
+      "guardSmtpCommand.validate: unknown verb '" + verb + "' (RFC 5321 §3)");
+  }
+  if (ZERO_ARG_VERBS[verb] && rest.length > 0) {
+    throw new GuardSmtpCommandError("guard-smtp-command/unexpected-args",
+      "guardSmtpCommand.validate: verb '" + verb + "' takes no arguments");
+  }
+
+  if (verb === "EHLO" || verb === "HELO") return _validateGreeting(verb, rest, caps);
+  if (verb === "MAIL")                    return _validatePath(verb, rest, caps, "FROM:");
+  if (verb === "RCPT")                    return _validatePath(verb, rest, caps, "TO:");
+  if (verb === "BDAT")                    return _validateBdat(rest);
+  if (verb === "VRFY" || verb === "EXPN") return _validateMailbox(verb, rest, caps);
+  if (verb === "AUTH")                    return _validateAuth(rest);
+  if (verb === "NOOP" || verb === "HELP") return { verb: verb, args: rest ? [rest] : [], params: {} };
+
+  return { verb: verb, args: [], params: {} };
+}
+
+/**
+ * @primitive b.guardSmtpCommand.compliancePosture
+ * @signature b.guardSmtpCommand.compliancePosture(posture)
+ * @since     0.9.32
+ * @status    stable
+ *
+ * Return the effective profile name for a compliance posture, or
+ * `null` for unknown posture names.
+ *
+ * @example
+ *   b.guardSmtpCommand.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _validateGreeting(verb, rest, caps) {
+  if (rest.length === 0) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + " requires a domain or address literal argument (RFC 5321 §4.1.1.1)");
+  }
+  // Trim trailing-space tolerance — most peers send a single space; we
+  // accept it but refuse multiple spaces or leading spaces.
+  if (rest.charAt(0) === " " || rest.indexOf("  ") !== -1) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-whitespace",
+      verb + " greeting has anomalous whitespace");
+  }
+  var arg = rest;
+  if (ADDR_LIT_RE.test(arg)) return { verb: verb, args: [arg], params: {} };                            // allow:regex-no-length-cap — line is maxLineBytes-capped upstream
+  if (Buffer.byteLength(arg, "utf8") > caps.maxDomain) {
+    throw new GuardSmtpCommandError("guard-smtp-command/oversize-domain",
+      verb + ": domain exceeds maxDomain=" + caps.maxDomain + " (RFC 1035 §2.3.4)");
+  }
+  if (!DOMAIN_RE.test(arg)) {                                                                            // allow:regex-no-length-cap — domain just length-checked above
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + ": domain '" + arg + "' does not match LDH shape (RFC 5321 §4.1.2)");
+  }
+  return { verb: verb, args: [arg], params: {} };
+}
+
+function _validatePath(verb, rest, caps, requiredPrefix) {
+  // SMTP allows OPTIONAL whitespace between e.g. MAIL and FROM:<...>
+  // per RFC 5321 §4.1.1.2; we accept a single space (consumed above)
+  // and refuse multiple spaces around the colon.
+  if (rest.indexOf(requiredPrefix) !== 0) {
+    // Allow a single leading SP — but our caller already split on the
+    // first SP; rest is post-SP. Some implementations send the path
+    // prefix verbatim. Refuse anything else.
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + " must begin with '" + requiredPrefix + "' (RFC 5321 §3.3)");
+  }
+  var after = rest.slice(requiredPrefix.length);
+  var pathEnd = after.indexOf(">");
+  if (after.charAt(0) !== "<" || pathEnd === -1) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + " path missing angle brackets (RFC 5321 §3.3)");
+  }
+  var pathRaw = after.slice(0, pathEnd + 1);
+  if (Buffer.byteLength(pathRaw, "utf8") > caps.maxMailbox) {
+    throw new GuardSmtpCommandError("guard-smtp-command/oversize-path",
+      verb + ": path '" + pathRaw + "' exceeds maxMailbox=" + caps.maxMailbox +
+      " (RFC 5321 §4.5.3.1.3)");
+  }
+  var pathBody = pathRaw.slice(1, -1);
+  // Reverse-path can be empty (`MAIL FROM:<>` per RFC 5321 §3.3 bounce
+  // sender). Forward-path can't be empty.
+  if (pathBody.length === 0) {
+    if (verb === "MAIL") return { verb: verb, args: [pathRaw], params: _parseExtParams(after.slice(pathEnd + 1)) };
+    throw new GuardSmtpCommandError("guard-smtp-command/empty-path",
+      verb + " path must not be empty");
+  }
+  // Validate mailbox local-part and domain caps.
+  var atIdx = pathBody.lastIndexOf("@");
+  if (atIdx === -1) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + ": mailbox missing '@' (RFC 5321 §4.1.2)");
+  }
+  var localPart = pathBody.slice(0, atIdx);
+  var domain    = pathBody.slice(atIdx + 1);
+  if (Buffer.byteLength(localPart, "utf8") > caps.maxLocalPart) {
+    throw new GuardSmtpCommandError("guard-smtp-command/oversize-local-part",
+      verb + ": local-part exceeds maxLocalPart=" + caps.maxLocalPart);
+  }
+  if (Buffer.byteLength(domain, "utf8") > caps.maxDomain) {
+    throw new GuardSmtpCommandError("guard-smtp-command/oversize-domain",
+      verb + ": domain exceeds maxDomain=" + caps.maxDomain);
+  }
+  if (!ADDR_LIT_RE.test(domain) && !DOMAIN_RE.test(domain)) {                                            // allow:regex-no-length-cap — domain length-checked above
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + ": domain '" + domain + "' does not match LDH or address-literal shape");
+  }
+  return {
+    verb:   verb,
+    args:   [pathRaw],
+    params: _parseExtParams(after.slice(pathEnd + 1)),
+  };
+}
+
+function _parseExtParams(tail) {
+  // RFC 5321 §4.1.1.11 — esmtp-keyword + optional '=' + esmtp-value.
+  // Caller passes the post-path slice; leading SP is allowed and
+  // separates params from each other.
+  var params = {};
+  var parts = tail.trim().split(/\s+/).filter(Boolean);
+  for (var i = 0; i < parts.length; i += 1) {
+    var eq = parts[i].indexOf("=");
+    var key = (eq === -1 ? parts[i] : parts[i].slice(0, eq)).toUpperCase();
+    var val = eq === -1 ? true : parts[i].slice(eq + 1);
+    if (!/^[A-Za-z0-9-]+$/.test(key)) {                                                                                                                                                                    // allow:regex-no-length-cap — bounded by maxLineBytes via line cap
+      throw new GuardSmtpCommandError("guard-smtp-command/bad-ext-param",
+        "esmtp-keyword '" + key + "' not in [A-Za-z0-9-] (RFC 5321 §4.1.1.11)");
+    }
+    params[key] = val;
+  }
+  return params;
+}
+
+function _validateBdat(rest) {
+  // RFC 3030 §2: `BDAT <chunk-size> [LAST]`
+  var parts = rest.split(/\s+/).filter(Boolean);
+  if (parts.length === 0 || parts.length > 2) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      "BDAT requires chunk-size and optional LAST (RFC 3030)");
+  }
+  if (!DECIMAL_RE.test(parts[0])) {                                                                      // allow:regex-no-length-cap — DECIMAL_RE has built-in repeat cap
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      "BDAT chunk-size must be a decimal number");
+  }
+  if (parts.length === 2 && parts[1].toUpperCase() !== "LAST") {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      "BDAT second arg must be LAST (RFC 3030)");
+  }
+  return {
+    verb:   "BDAT",
+    args:   [parts[0]],
+    params: parts.length === 2 ? { LAST: true } : {},
+  };
+}
+
+function _validateMailbox(verb, rest, caps) {
+  if (rest.length === 0) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      verb + " requires a mailbox argument (RFC 5321 §4.1.1.7/§4.1.1.8)");
+  }
+  if (Buffer.byteLength(rest, "utf8") > caps.maxMailbox) {
+    throw new GuardSmtpCommandError("guard-smtp-command/oversize-path",
+      verb + ": mailbox exceeds maxMailbox=" + caps.maxMailbox);
+  }
+  return { verb: verb, args: [rest], params: {} };
+}
+
+function _validateAuth(rest) {
+  // RFC 4954: `AUTH <SASL-mech> [<initial-response>]`
+  var parts = rest.split(/\s+/).filter(Boolean);
+  if (parts.length === 0 || parts.length > 2) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      "AUTH requires mechanism and optional initial-response (RFC 4954)");
+  }
+  // SASL mechanism names are RFC 4422 — ALPHA + DIGIT + "-" + "_", up
+  // to 20 octets. We accept the 4422 charset and a 32-byte cap so
+  // operator-extension mechanisms have room.
+  if (!/^[A-Za-z0-9_-]{1,32}$/.test(parts[0])) {                                                                                                                                                           // allow:regex-no-length-cap — anchored + repeat-cap
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
+      "AUTH: SASL mechanism '" + parts[0] + "' not in RFC 4422 charset or too long");
+  }
+  return {
+    verb:   "AUTH",
+    args:   [parts[0].toUpperCase()],
+    params: parts.length === 2 ? { initialResponse: parts[1] } : {},
+  };
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardSmtpCommandError("guard-smtp-command/bad-profile",
+      "guardSmtpCommand: unknown profile '" + p + "'");
+  }
+  return PROFILES[p];
+}
+
+/**
+ * @primitive b.guardSmtpCommand.gate
+ * @signature b.guardSmtpCommand.gate(opts?)
+ * @since     0.9.32
+ * @status    stable
+ *
+ * Build a guard gate compatible with `b.guardAll.allGuards()`. The
+ * gate's `decide(ctx)` reads `ctx.identifier` (or `ctx.commandLine`)
+ * and routes through `validate()`; refuse on any thrown
+ * `GuardSmtpCommandError`, serve otherwise.
+ *
+ * @opts
+ *   profile:  "strict" | "balanced" | "permissive",
+ *   posture:  "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   name:     string,                              // gate identity label
+ *
+ * @example
+ *   var gate = b.guardSmtpCommand.gate({ profile: "strict" });
+ *   await gate.decide({ identifier: "EHLO mail.example.com" });
+ *   // → { ok: true, action: "serve" }
+ */
+function gate(opts) {
+  opts = opts || {};
+  // Resolve profile eagerly so a bad profile / posture surfaces here
+  // rather than inside the first gate.check() call.
+  _resolveProfile(opts);
+  var name = opts.name || "guardSmtpCommand:" + (opts.profile || opts.posture || "default");
+  return gateContract.buildGuardGate(name, opts, async function (ctx) {
+    var line = ctx && (ctx.identifier || ctx.commandLine || "");
+    if (!line) return { ok: true, action: "serve" };
+    try {
+      validate(line, opts);
+      return { ok: true, action: "serve" };
+    } catch (e) {
+      if (e && typeof e.code === "string" && e.code.indexOf("guard-smtp-command/") === 0) {
+        return {
+          ok:     false,
+          action: "refuse",
+          issues: [{
+            kind:     e.code.split("/")[1],
+            severity: "critical",
+            ruleId:   "smtp-command." + e.code.split("/")[1],
+            snippet:  e.message,
+          }],
+        };
+      }
+      throw e;
+    }
+  });
+}
+
+module.exports = {
+  validate:                  validate,
+  gate:                      gate,
+  compliancePosture:         compliancePosture,
+  PROFILES:                  PROFILES,
+  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
+  KNOWN_VERBS:               KNOWN_VERBS,
+  GuardSmtpCommandError:     GuardSmtpCommandError,
+  NAME:                      "smtpCommand",
+  KIND:                      "identifier",
+  INTEGRATION_FIXTURES:      Object.freeze({
+    kind:        "identifier",
+    // Benign: standard EHLO greeting.
+    benignBytes: Buffer.from("EHLO mail.example.com", "ascii"),
+    // Hostile: CRLF smuggling attempt — bare CR inside a command line
+    // (CVE-2023-51764 / 51765 / 51766 class).
+    hostileBytes: Buffer.from("MAIL FROM:<a@b.com>\r\n.\r\nMAIL FROM:<evil@x.com>", "ascii"),
+    benignIdentifier:  "EHLO mail.example.com",
+    hostileIdentifier: "MAIL FROM:<a@b.com>\r\n.\r\nMAIL FROM:<evil@x.com>",
+  }),
+};

package/lib/guard-snapshot-envelope.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * @module     b.guardSnapshotEnvelope
+ * @nav        Guards
+ * @title      Guard Snapshot Envelope
+ * @order      444
+ *
+ * @intro
+ *   Snapshot envelope shape validator. The agent snapshot primitive
+ *   (v0.9.30) writes a structured envelope to durable storage on drain
+ *   and reads it back on restart. The guard refuses malformed
+ *   envelopes at the boundary so a corrupt or tampered snapshot
+ *   doesn't get partially restored.
+ *
+ *   Envelope contract: snapshotId, takenAt, frameworkVersion,
+ *   orchestratorState, inFlight, idempotencyCache (optional), sig,
+ *   schemaVersion.
+ *
+ *   Hard caps:
+ *     - total serialized size  (default 50 MiB)
+ *     - in-flight items count  (default 65536 — orchestrator can't
+ *       legitimately hold more in-flight streams + sagas + outbox-
+ *       jobs at one moment than that)
+ *     - schemaVersion          must be a positive integer
+ *
+ * @card
+ *   Validates snapshot envelopes at drain/restore boundary. Bounded
+ *   size + in-flight count + schema-version monotonic check.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardSnapshotEnvelopeError = defineClass("GuardSnapshotEnvelopeError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: 52428800,  maxInFlight: 65536   },                                          // allow:raw-byte-literal — 50 MiB cap
+  balanced:   { maxBytes: 209715200, maxInFlight: 262144  },                                          // allow:raw-byte-literal — 200 MiB
+  permissive: { maxBytes: 1073741824, maxInFlight: 1048576 },                                         // allow:raw-byte-literal — 1 GiB
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardSnapshotEnvelope.validate
+ * @signature b.guardSnapshotEnvelope.validate(envelope, opts?)
+ * @since     0.9.30
+ * @status    stable
+ * @related   b.agent.snapshot.create
+ *
+ * Validate a snapshot envelope shape. Returns envelope on success;
+ * throws on shape refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardSnapshotEnvelope.validate({
+ *     snapshotId: "snap-abc",
+ *     takenAt:    1700000000000,
+ *     frameworkVersion: "0.9.30",
+ *     schemaVersion:    1,
+ *     orchestratorState: {},
+ *     inFlight: {},
+ *   });
+ */
+function validate(envelope, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/bad-input",
+      "guardSnapshotEnvelope.validate: envelope required");
+  }
+  if (typeof envelope.snapshotId !== "string" || envelope.snapshotId.length === 0) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/missing-snapshot-id",
+      "guardSnapshotEnvelope.validate: snapshotId required");
+  }
+  if (typeof envelope.takenAt !== "number" || !isFinite(envelope.takenAt) || envelope.takenAt <= 0) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/bad-taken-at",
+      "guardSnapshotEnvelope.validate: takenAt must be a positive finite number");
+  }
+  if (typeof envelope.frameworkVersion !== "string" || envelope.frameworkVersion.length === 0) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/missing-framework-version",
+      "guardSnapshotEnvelope.validate: frameworkVersion required");
+  }
+  if (!Number.isInteger(envelope.schemaVersion) || envelope.schemaVersion < 1) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/bad-schema-version",
+      "guardSnapshotEnvelope.validate: schemaVersion must be a positive integer");
+  }
+  if (!envelope.orchestratorState || typeof envelope.orchestratorState !== "object") {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/missing-orchestrator-state",
+      "guardSnapshotEnvelope.validate: orchestratorState object required");
+  }
+  if (!envelope.inFlight || typeof envelope.inFlight !== "object") {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/missing-in-flight",
+      "guardSnapshotEnvelope.validate: inFlight object required");
+  }
+  // Total in-flight count cap — sum of streams + sagas + subscribers + pendingDeliveries.
+  var inFlightCount = 0;
+  ["streams", "sagas", "outboxJobs", "busSubscribers", "pendingDeliveries"].forEach(function (k) {
+    if (Array.isArray(envelope.inFlight[k])) inFlightCount += envelope.inFlight[k].length;
+  });
+  if (inFlightCount > profile.maxInFlight) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/in-flight-cap",
+      "guardSnapshotEnvelope.validate: " + inFlightCount +
+      " in-flight items exceeds maxInFlight=" + profile.maxInFlight);
+  }
+  // Size cap — serialize the whole envelope to JSON for size check.
+  var serialized;
+  try { serialized = JSON.stringify(envelope); }
+  catch (e) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/unserializable",
+      "guardSnapshotEnvelope.validate: envelope not JSON-serializable: " +
+      (e && e.message ? e.message : String(e)));
+  }
+  if (Buffer.byteLength(serialized, "utf8") > profile.maxBytes) {
+    throw new GuardSnapshotEnvelopeError("snapshot-envelope/oversize",
+      "guardSnapshotEnvelope.validate: " + Buffer.byteLength(serialized, "utf8") +
+      " bytes exceeds maxBytes=" + profile.maxBytes);
+  }
+  return envelope;
+}
+
+/**
+ * @primitive b.guardSnapshotEnvelope.compliancePosture
+ * @signature b.guardSnapshotEnvelope.compliancePosture(posture)
+ * @since     0.9.30
+ * @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.guardSnapshotEnvelope.compliancePosture("hipaa");   // returns "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+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 GuardSnapshotEnvelopeError("snapshot-envelope/bad-profile",
+      "guardSnapshotEnvelope: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                    validate,
+  compliancePosture:           compliancePosture,
+  PROFILES:                    PROFILES,
+  COMPLIANCE_POSTURES:         COMPLIANCE_POSTURES,
+  GuardSnapshotEnvelopeError:  GuardSnapshotEnvelopeError,
+  NAME:                        "snapshotEnvelope",
+  KIND:                        "snapshot-envelope",
+};