@blamejs/core 0.9.49 → 0.10.1

package/lib/guard-pop3-command.js

@@ -0,0 +1,317 @@
+"use strict";
+/**
+ * @module     b.guardPop3Command
+ * @nav        Guards
+ * @title      Guard POP3 Command
+ * @order      453
+ *
+ * @intro
+ *   POP3 command-line validator (RFC 1939 Post Office Protocol — Version 3).
+ *   Gates every command verb the framework's POP3 listener accepts
+ *   from peers — `USER` / `PASS` / `APOP` / `AUTH` / `STLS` / `CAPA` /
+ *   `STAT` / `LIST` / `RETR` / `DELE` / `NOOP` / `RSET` / `TOP` / `UIDL`
+ *   / `QUIT`.
+ *
+ *   POP3 is a simple line-oriented text protocol. Each command is a
+ *   single CRLF-terminated line; responses are `+OK ...` or `-ERR ...`
+ *   single-line or multi-line (terminated by `.` on a line of its own).
+ *
+ *   ## Smuggling defense — bare-CR / bare-LF refusal
+ *
+ *   Same wire-protocol concern as SMTP / IMAP. POP3's `.<CRLF>`
+ *   end-of-multiline terminator is matched on canonical CRLF only;
+ *   bare-LF dot-terminators are refused. Command lines themselves
+ *   must be CRLF-terminated and contain no bare CR or LF.
+ *
+ *   ## STLS injection
+ *
+ *   RFC 2595 STLS upgrade (POP3's equivalent of STARTTLS) is subject
+ *   to the same pre-handshake command-buffer injection class as
+ *   SMTP / IMAP STARTTLS (CVE-2021-38371 Exim, CVE-2021-33515
+ *   Dovecot). This guard refuses trailing payload on the STLS line;
+ *   the listener's STLS handler is responsible for draining the
+ *   pre-handshake buffer.
+ *
+ *   ## Per-verb shape
+ *
+ *   RFC 1939 §6 and RFC 2449 §5 define the verbs:
+ *
+ *     - `USER` <name>          — single argument
+ *     - `PASS` <password>       — single argument; refuse in CAPA
+ *                                 (operator must rely on TLS confidentiality)
+ *     - `APOP` <name> <digest>  — RFC 1939 §7 challenge-response (legacy)
+ *     - `AUTH` [<sasl-mech>]    — RFC 5034 SASL framework (PLAIN /
+ *                                 CRAM-MD5 / SCRAM-SHA-256 / EXTERNAL)
+ *     - `STLS`                  — RFC 2595 §4 TLS upgrade
+ *     - `CAPA`                  — RFC 2449 §5 capability discovery
+ *     - `STAT`                  — no args
+ *     - `LIST` [msg]            — optional msg-number argument
+ *     - `RETR` <msg>            — single message-number argument
+ *     - `DELE` <msg>            — single message-number argument
+ *     - `NOOP`                  — no args
+ *     - `RSET`                  — no args
+ *     - `TOP`  <msg> <n>        — RFC 2449 §5 — message + header-line count
+ *     - `UIDL` [msg]            — RFC 1939 §7 — optional msg arg
+ *     - `QUIT`                  — no args
+ *
+ *   ## Caps
+ *
+ *     - Command line capped at 255 bytes per RFC 2449 §4 (response
+ *       lines are 512 octets including CRLF; the command-line cap is
+ *       even tighter).
+ *     - Username + password capped at 40 octets each per RFC 1939 §3
+ *       (longer values accepted under permissive but the wire is
+ *       interpretation-defined).
+ *     - Message-number capped at 10-decimal-digit positive integer.
+ *
+ *   Throws `GuardPop3CommandError` on every refusal.
+ *
+ * @card
+ *   POP3 command-line validator (RFC 1939 + RFC 2449 capabilities +
+ *   RFC 2595 STLS + RFC 5034 AUTH). Refuses bare-CR / bare-LF
+ *   (smuggling defense), caps command-line / username / password / msg
+ *   bytes, validates per-verb shape.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardPop3CommandError = defineClass("GuardPop3CommandError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict: {
+    maxLineBytes:       255,                                                                         // allow:raw-byte-literal — RFC 2449 §4 cap
+    maxUsernameBytes:   40,                                                                          // allow:raw-byte-literal — RFC 1939 §3 cap
+    maxPasswordBytes:   40,                                                                          // allow:raw-byte-literal — RFC 1939 §3 cap
+    allowBareLf:        false,
+    allowApop:          false,                                                                       // RFC 1939 §7 — legacy challenge-response with MD5; refuse under strict (M³AAWG)
+  },
+  balanced: {
+    maxLineBytes:       512,                                                                         // allow:raw-byte-literal — RFC 2449 §4 response cap
+    maxUsernameBytes:   128,                                                                         // allow:raw-byte-literal — balanced username cap
+    maxPasswordBytes:   128,                                                                         // allow:raw-byte-literal — balanced password cap
+    allowBareLf:        false,
+    allowApop:          true,
+  },
+  permissive: {
+    maxLineBytes:       1024,                                                                        // allow:raw-byte-literal — permissive cap for legacy peers
+    maxUsernameBytes:   256,                                                                         // allow:raw-byte-literal — permissive username cap
+    maxPasswordBytes:   256,                                                                         // allow:raw-byte-literal — permissive password cap
+    allowBareLf:        true,
+    allowApop:          true,
+  },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// POP3 verbs per RFC 1939 §6 + RFC 2449 §5 + RFC 2595 §4 + RFC 5034.
+var KNOWN_VERBS = Object.freeze({
+  USER: true, PASS: true, APOP: true, AUTH: true, STLS: true,
+  CAPA: true, STAT: true, LIST: true, RETR: true, DELE: true,
+  NOOP: true, RSET: true, TOP:  true, UIDL: true, QUIT: true,
+});
+
+var ZERO_ARG_VERBS = Object.freeze({
+  STLS: true, CAPA: true, STAT: true, NOOP: true, RSET: true, QUIT: true,
+});
+
+var MSG_NUM_RE = /^[1-9][0-9]{0,9}$/;                                                                 // allow:regex-no-length-cap — anchored + bounded repeat
+
+/**
+ * @primitive b.guardPop3Command.validate
+ * @signature b.guardPop3Command.validate(line, opts?)
+ * @since     0.9.52
+ * @status    stable
+ * @related   b.guardSmtpCommand.validate, b.guardImapCommand.validate
+ *
+ * Validate a single POP3 command line (without its CRLF terminator).
+ * Returns `{ verb, args }` on success; throws `GuardPop3CommandError`
+ * on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   tls:       boolean,    // when false + verb is USER/PASS under
+ *                            strict, refuse with `guard-pop3-command/
+ *                            cleartext-auth` (TLS required for credentials)
+ *
+ * @example
+ *   var parsed = b.guardPop3Command.validate("USER alice", { tls: true });
+ *   // → { verb: "USER", args: ["alice"] }
+ *
+ *   var pending = b.guardPop3Command.validate("RETR 12");
+ *   // → { verb: "RETR", args: ["12"] }
+ */
+function validate(line, opts) {
+  opts = opts || {};
+  var profileName = typeof opts.profile === "string" ? opts.profile : DEFAULT_PROFILE;
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    profileName = COMPLIANCE_POSTURES[opts.posture];
+  }
+  var caps = PROFILES[profileName];
+  if (!caps) {
+    throw new GuardPop3CommandError("guard-pop3-command/bad-profile",
+      "guardPop3Command.validate: unknown profile '" + profileName + "'");
+  }
+  if (typeof line !== "string") {
+    throw new GuardPop3CommandError("guard-pop3-command/bad-input",
+      "guardPop3Command.validate: line must be a string");
+  }
+  if (line.length === 0) {
+    throw new GuardPop3CommandError("guard-pop3-command/empty-line",
+      "guardPop3Command.validate: empty command line");
+  }
+  if (line.length > caps.maxLineBytes) {
+    throw new GuardPop3CommandError("guard-pop3-command/line-too-long",
+      "guardPop3Command.validate: line " + line.length + " bytes exceeds cap " + caps.maxLineBytes);
+  }
+  for (var i = 0; i < line.length; i += 1) {
+    var c = line.charCodeAt(i);
+    if (c === 0x00 || c === 0x7F || (c < 0x20 && c !== 0x09)) {                                       // allow:raw-byte-literal — control-byte refusal
+      if (c === 0x0A && caps.allowBareLf) continue;
+      throw new GuardPop3CommandError("guard-pop3-command/bad-byte",
+        "guardPop3Command.validate: control byte 0x" + c.toString(16) + " at offset " + i);          // allow:raw-byte-literal — hex format literal in error message
+    }
+  }
+
+  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 GuardPop3CommandError("guard-pop3-command/unknown-verb",
+      "guardPop3Command.validate: unknown verb '" + verb + "' (RFC 1939 §6)");
+  }
+  if (ZERO_ARG_VERBS[verb] && rest.length > 0) {
+    throw new GuardPop3CommandError("guard-pop3-command/unexpected-args",
+      "guardPop3Command.validate: verb '" + verb + "' takes no arguments");
+  }
+
+  // Per-verb shape — switch dispatch (statically resolved, not
+  // dynamic; CodeQL accepts switch as a fixed call graph).
+  var args = [];
+  switch (verb) {
+  case "USER":
+    if (!rest) throw new GuardPop3CommandError("guard-pop3-command/missing-username",
+      "guardPop3Command.validate: USER requires a name argument");
+    if (rest.length > caps.maxUsernameBytes) {
+      throw new GuardPop3CommandError("guard-pop3-command/username-too-long",
+        "guardPop3Command.validate: USER name " + rest.length + " bytes exceeds cap " + caps.maxUsernameBytes);
+    }
+    if (opts.tls === false && profileName === "strict") {
+      throw new GuardPop3CommandError("guard-pop3-command/cleartext-auth",
+        "guardPop3Command.validate: USER refused over cleartext (use STLS first; RFC 2595)");
+    }
+    args = [rest];
+    break;
+  case "PASS":
+    if (!rest) throw new GuardPop3CommandError("guard-pop3-command/missing-password",
+      "guardPop3Command.validate: PASS requires a password argument");
+    if (rest.length > caps.maxPasswordBytes) {
+      throw new GuardPop3CommandError("guard-pop3-command/password-too-long",
+        "guardPop3Command.validate: PASS argument " + rest.length + " bytes exceeds cap " + caps.maxPasswordBytes);
+    }
+    if (opts.tls === false && profileName === "strict") {
+      throw new GuardPop3CommandError("guard-pop3-command/cleartext-auth",
+        "guardPop3Command.validate: PASS refused over cleartext (use STLS first; RFC 2595)");
+    }
+    args = [rest];
+    break;
+  case "APOP":
+    if (!caps.allowApop) {
+      throw new GuardPop3CommandError("guard-pop3-command/apop-refused",
+        "guardPop3Command.validate: APOP refused under profile '" + profileName +
+        "' (RFC 1939 §7 uses MD5 challenge-response; deprecated by M³AAWG)");
+    }
+    var apopParts = rest.split(" ");
+    if (apopParts.length !== 2) {
+      throw new GuardPop3CommandError("guard-pop3-command/bad-apop",
+        "guardPop3Command.validate: APOP requires `name digest`");
+    }
+    args = apopParts;
+    break;
+  case "AUTH":
+    // RFC 5034 — `AUTH` alone lists supported mechanisms; `AUTH MECH`
+    // initiates a mechanism. Allow either shape.
+    args = rest ? rest.split(" ") : [];
+    // RFC 2595 §2.1 + RFC 5034 §4 — credentials over cleartext are
+    // refused under strict identically to USER/PASS. `AUTH` with no
+    // mech argument is a CAPA-style enumeration and stays allowed
+    // pre-TLS; a mech-bearing AUTH initiates the credential exchange
+    // and MUST be over TLS.
+    if (args.length > 0 && opts.tls === false && profileName === "strict") {
+      throw new GuardPop3CommandError("guard-pop3-command/cleartext-auth",
+        "guardPop3Command.validate: AUTH " + args[0] + " refused over cleartext (use STLS first; RFC 2595 §2.1 + RFC 5034 §4)");
+    }
+    break;
+  case "LIST":
+  case "UIDL":
+    // Optional msg-number argument.
+    if (rest) {
+      if (!MSG_NUM_RE.test(rest)) {                                                                  // allow:regex-no-length-cap — MSG_NUM_RE anchored + bounded
+        throw new GuardPop3CommandError("guard-pop3-command/bad-msg-number",
+          "guardPop3Command.validate: " + verb + " msg-number must be a positive decimal integer");
+      }
+      args = [rest];
+    }
+    break;
+  case "RETR":
+  case "DELE":
+    if (!rest || !MSG_NUM_RE.test(rest)) {                                                            // allow:regex-no-length-cap — MSG_NUM_RE anchored + bounded
+      throw new GuardPop3CommandError("guard-pop3-command/bad-msg-number",
+        "guardPop3Command.validate: " + verb + " requires a positive decimal message-number");
+    }
+    args = [rest];
+    break;
+  case "TOP":
+    // `TOP msg n` — message + non-negative line-count.
+    var topParts = rest.split(" ");
+    if (topParts.length !== 2 ||
+        !MSG_NUM_RE.test(topParts[0]) ||                                                              // allow:regex-no-length-cap — MSG_NUM_RE anchored + bounded
+        !/^[0-9]{1,10}$/.test(topParts[1])) {                                                         // allow:regex-no-length-cap — anchored + bounded line-count
+      throw new GuardPop3CommandError("guard-pop3-command/bad-top",
+        "guardPop3Command.validate: TOP requires `msg-num line-count` (both decimal)");
+    }
+    args = topParts;
+    break;
+  default:
+    // STLS / CAPA / STAT / NOOP / RSET / QUIT — ZERO_ARG_VERBS guard
+    // above already enforced no-args. Empty args.
+    args = [];
+    break;
+  }
+
+  return { verb: verb, args: args };
+}
+
+/**
+ * @primitive b.guardPop3Command.compliancePosture
+ * @signature b.guardPop3Command.compliancePosture(posture)
+ * @since     0.9.52
+ * @status    stable
+ *
+ * Return the effective profile for a compliance posture, or `null`
+ * for unknown names.
+ *
+ * @example
+ *   b.guardPop3Command.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+module.exports = {
+  validate:                 validate,
+  compliancePosture:        compliancePosture,
+  PROFILES:                 PROFILES,
+  COMPLIANCE_POSTURES:      COMPLIANCE_POSTURES,
+  KNOWN_VERBS:              KNOWN_VERBS,
+  ZERO_ARG_VERBS:           ZERO_ARG_VERBS,
+  GuardPop3CommandError:    GuardPop3CommandError,
+};

package/lib/guard-smtp-command.js

@@ -259,6 +259,17 @@ function _validateGreeting(verb, rest, caps) {
     throw new GuardSmtpCommandError("guard-smtp-command/bad-shape",
       verb + " requires a domain or address literal argument (RFC 5321 §4.1.1.1)");
   }
+  // RFC 5321 §4.1.1.1: HELO/EHLO accepts a domain. Real-world MTAs
+  // (Postfix, Exim, sendmail) tolerate a single trailing space after
+  // the domain — the framework refused it because the DOMAIN_RE
+  // doesn't match a domain with trailing whitespace. Strip a single
+  // trailing space before the leading-space / double-space check so a
+  // legitimate "HELO mail.example.com " passes while abusive multi-
+  // space shapes still refuse.
+  if (rest.charAt(rest.length - 1) === " " &&
+      rest.charAt(rest.length - 2) !== " ") {
+    rest = rest.slice(0, -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) {
@@ -506,9 +517,53 @@ function detectBodySmuggling(buf) {
     throw new GuardSmtpCommandError("guard-smtp-command/bad-input",
       "detectBodySmuggling: input must be a Buffer");
   }
-  for (var i = 1; i < buf.length - 2; i += 1) {
-    if (buf[i] === 0x0a /* LF */ && buf[i - 1] !== 0x0d /* CR */ &&
-        buf[i + 1] === 0x2e /* . */ && buf[i + 2] === 0x0a /* LF */) {
+  // The CVE-2023-51764 / 51765 / 51766 / 2024-32178 class is any
+  // dot-line whose line boundary is anything OTHER than canonical
+  // \r\n on BOTH sides of the dot. The canonical-and-only terminator
+  // is `\r\n.\r\n`. Every other shape that some receiver might honor
+  // is a smuggling vector:
+  //
+  //   shape           leading      .   trailing
+  //   --------------  -----------  -   -------------
+  //   bare-LF/bare-LF  \n          .   \n           ← original detector
+  //   bare-LF/CRLF     \n          .   \r\n
+  //   CRLF/bare-LF     \r\n        .   \n           ← bare-LF terminator
+  //   bare-CR/anything \r (no LF)  .   *            ← bare CR (RFC violations)
+  //
+  // Standalone `.\n` or `\n.\n` at the START of the buffer also
+  // count: a dot at byte 0 followed by `\n` would terminate any
+  // receiver that accepts bare-LF dot.
+  //   0x0a = LF, 0x0d = CR, 0x2e = `.`
+  if (buf.length >= 2 && buf[0] === 0x2e && buf[1] === 0x0a) return true;
+  // Walk every LF in the buffer. The previous byte must be CR for the
+  // line boundary to be canonical; otherwise the line started with
+  // bare-LF. If the next bytes are `.` followed by ANY of (LF, CRLF),
+  // the shape is a smuggling candidate.
+  for (var i = 0; i < buf.length - 1; i += 1) {
+    if (buf[i] !== 0x0a) continue;
+    var leadingBareLf = (i === 0) || (buf[i - 1] !== 0x0d);
+    if (buf[i + 1] !== 0x2e) continue;
+    // Trailing terminator shape after the dot:
+    //   buf[i+2] == LF        → bare-LF terminator (always smuggling)
+    //   buf[i+2] == CR && buf[i+3] == LF → CRLF after dot
+    //                                       (only smuggling when the
+    //                                        leading boundary was bare-LF)
+    if (i + 2 < buf.length && buf[i + 2] === 0x0a) {
+      // `.\n` after a bare-LF or CRLF line boundary — both
+      // smuggling vectors (CRLF.\n is the v0.9.x-audit case).
+      return true;
+    }
+    if (leadingBareLf && i + 3 < buf.length &&
+        buf[i + 2] === 0x0d && buf[i + 3] === 0x0a) {
+      // bare-LF.\r\n — smuggling shape (CVE-2023-51764 Postfix).
+      return true;
+    }
+  }
+  // Also check for bare-CR-only dot terminators: `\r.\r` (no LF).
+  // Some legacy parsers honor bare CR as line terminator.
+  for (var j = 0; j < buf.length - 2; j += 1) {
+    if (buf[j] === 0x0d && (j + 1 >= buf.length || buf[j + 1] !== 0x0a) &&
+        buf[j + 1] === 0x2e && j + 2 < buf.length && buf[j + 2] === 0x0d) {
       return true;
     }
   }

package/lib/mail-agent.js

@@ -485,17 +485,30 @@ async function _delete(ctx, args) {
 }
 
 async function _sievePut(ctx, args) {
-  // Pre-parse shape-only validation lands today; full b.safeSieve
-  // parse lands v0.9.26 and will be invoked from the throw-stub at
-  // that slice. The agent-level guard lets operators wire RBAC + name
-  // shape today.
+  // Two-stage validation: agent-level shape guard for RBAC + name +
+  // size, then the full RFC 5228 grammar parse via b.safeSieve. The
+  // grammar parse refuses unknown / not-yet-implemented capabilities
+  // at `require` time (RFC 5228 §3.2) so the operator's persistence
+  // step never gets a script the framework can't actually execute.
   _entry(ctx, "sieve.put", args);
   guardMailSieve.validate({
     kind: "put", actor: args.actor, name: args.name, script: args.script,
   }, { profile: _profileFor(ctx), posture: ctx.posture, ownedNames: args.ownedNames });
-  throw new MailAgentError("mail-agent/not-implemented",
-    "agent.sieve.put: full Sieve parser lands at v0.9.26 (b.safeSieve); " +
-    "shape-only validation passed — wire the persistence step in the operator handler");
+  var safeSieve = require("./safe-sieve");                                                            // allow:inline-require — lazy-load until first sieve.put call
+  var rv = safeSieve.validate(args.script, {
+    profile:           _profileFor(ctx),
+    compliancePosture: ctx.posture,
+  });
+  if (!rv.ok) {
+    throw new MailAgentError("mail-agent/sieve-parse-error",
+      "agent.sieve.put: Sieve script refused — " +
+      (rv.issues[0] && rv.issues[0].snippet ? rv.issues[0].snippet : "parse failed"));
+  }
+  ctx.auditEmit("mail.agent.sieve.put", args && args.actor, {
+    name:         args.name,
+    requiredCaps: rv.requiredCaps,
+  });
+  return { ok: true, requiredCaps: rv.requiredCaps };
 }
 
 function _notImplemented(ctx, method, args) {

package/lib/mail-arc-sign.js

@@ -52,6 +52,7 @@ var nodeCrypto = require("node:crypto");
 var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var safeBuffer = require("./safe-buffer");
+var dkim = require("./mail-dkim");
 var { defineClass } = require("./framework-error");
 
 var MailAuthError = defineClass("MailAuthError", { alwaysPermanent: true });
@@ -107,20 +108,23 @@ function _canonRelaxedHeader(name, value) {
   return name.toLowerCase() + ":" + trimmed + "\r\n";
 }
 
+// RFC 8617 §5.1.1 references RFC 6376 §3.4.4 for body canonicalization.
+// The DKIM verifier and signer share `_canonBodyRelaxed`; ARC MUST
+// produce a byte-identical canon so a downstream ARC-verifier (which
+// composes the DKIM verifier per §5.1.1) reaches the same body hash.
+// Earlier inline shape collapsed `[ \t]+` across newlines (the regex
+// is global and not bound per-line), which diverged from DKIM's
+// per-line `safeBuffer.stripTrailingHspace` on a line whose only WSP
+// run sat at the end. Compose the DKIM canon directly.
 function _canonRelaxedBody(body) {
-  // Relaxed body canon: collapse runs of WSP within lines, strip
-  // trailing WSP, remove all trailing empty lines, append single CRLF
-  // unless body is empty.
-  if (body.length === 0) return "";
-  var normalized = body.replace(/\r?\n/g, "\r\n");
-  var collapsed = normalized.replace(/[ \t]+/g, " ").replace(/[ \t]+\r\n/g, "\r\n");
-  collapsed = collapsed.replace(/(\r\n)+$/, "");
-  return collapsed + "\r\n";
+  return dkim._canonBodyRelaxedForTest(body || "");
 }
 
 function _bodyHashB64(body, algorithm) {
   var hashAlgo = algorithm.indexOf("sha256") !== -1 ? "sha256" : "sha512";
   var canonical = _canonRelaxedBody(body);
+  // RFC 6376 §3.4.4 — empty body canon is `\r\n` (one CRLF). Hash
+  // includes that CRLF.
   return nodeCrypto.createHash(hashAlgo).update(canonical).digest("base64");
 }