@blamejs/core 0.9.45 → 0.9.49

package/lib/mail-server-imap.js

@@ -0,0 +1,1064 @@
+"use strict";
+/**
+ * @module     b.mail.server.imap
+ * @nav        Mail
+ * @title      Mail IMAP Server
+ * @order      546
+ *
+ * @intro
+ *   IMAP4rev2 mailbox-access listener (RFC 9051; obsoletes RFC 3501).
+ *   Modern MUAs (Thunderbird, Apple Mail, mutt, K-9, FairEmail,
+ *   etc.) connect here to read + manage messages without operators
+ *   running dovecot / cyrus alongside. Composes the framework's
+ *   existing substrates:
+ *
+ *     - `b.guardImapCommand` for wire-protocol shape + smuggling
+ *       defense (literal-injection, bare-CR/LF refusal, per-verb
+ *       shape, RFC 9051 §2.2.2 literal framing)
+ *     - `b.mail.server.rateLimit` for per-IP DoS defense (concurrent
+ *       + rate + AUTH-failure budget + slow-loris)
+ *     - `b.mailStore` (operator-supplied backend) for the actual
+ *       mail storage + UIDVALIDITY + modseq tracking
+ *     - operator-supplied authenticator for SASL credential verify
+ *     - `b.mail.server.tls` recommended for cert + key loading +
+ *       rotation
+ *
+ *   ## State machine (RFC 9051 §3)
+ *
+ *   ```
+ *   NOT-AUTHENTICATED → [STARTTLS → NOT-AUTH-TLS] → AUTH/LOGIN →
+ *   AUTHENTICATED ↔ SELECTED → LOGOUT
+ *                                ↑ EXAMINE  ↓ CLOSE / UNSELECT
+ *   ```
+ *
+ *   Commands gated by state:
+ *
+ *     - NOT-AUTHENTICATED: STARTTLS / AUTHENTICATE / LOGIN / NOOP /
+ *       CAPABILITY / LOGOUT / ID
+ *     - AUTHENTICATED: SELECT / EXAMINE / CREATE / DELETE / RENAME /
+ *       SUBSCRIBE / UNSUBSCRIBE / LIST / STATUS / APPEND / NAMESPACE /
+ *       IDLE / ENABLE / NOOP / CAPABILITY / LOGOUT / ID
+ *     - SELECTED: CHECK / CLOSE / UNSELECT / EXPUNGE / SEARCH / FETCH /
+ *       STORE / COPY / MOVE / UID … / IDLE / NOOP / CAPABILITY /
+ *       LOGOUT + every AUTHENTICATED command
+ *
+ *   Tagged response model: every client command carries a tag
+ *   (`A001 LOGIN …`); server replies with one or more untagged
+ *   responses (`* …`) then `A001 OK …` / `A001 NO …` / `A001 BAD …`.
+ *
+ *   ## Wire-protocol defenses
+ *
+ *   - **STARTTLS stripping (CVE-2021-33515 Dovecot class)** —
+ *     STARTTLS upgrade clears pre-handshake receive buffer; any
+ *     pipelined command queued before TLS is refused with
+ *     `BAD Pipelined post-STARTTLS not permitted`.
+ *
+ *   - **Literal-injection (CVE-2018-19518 INC IMAP class)** —
+ *     `{n}` literal continuation MUST come on a line of its own
+ *     (per `b.guardImapCommand.detectLiteralSmuggling`); oversize
+ *     literals refused (default 64 MiB); LITERAL+ (RFC 7888) non-
+ *     synchronizing literals only honored post-AUTH.
+ *
+ *   - **Mailbox-name traversal** — mailbox path components
+ *     validated through `_validateMailboxName`: refuses `..`, NUL,
+ *     control chars, oversize. UTF-8 mailbox names (RFC 9051 §5.1)
+ *     accepted; modified-UTF7 (RFC 3501 §5.1.3 legacy) refused unless
+ *     `allowLegacyMUtf7: true`.
+ *
+ *   - **APPEND-flood** — per-tenant byte/sec cap surfaces via the
+ *     `b.mail.server.rateLimit`'s `minBytesPerSecond` floor on the
+ *     APPEND-literal-body phase (same shape the MX listener uses for
+ *     DATA-body).
+ *
+ *   - **Resource exhaustion** — per-line cap (default 8 KiB sans
+ *     literal payload), per-literal cap (64 MiB), per-connection idle
+ *     cap (default 30 min when not in IDLE; IDLE itself capped at
+ *     29 min per RFC 2177 §3 to force re-issue).
+ *
+ *   - **Connection-rate + AUTH-failure budget** — composes
+ *     `b.mail.server.rateLimit`. Each AUTH failure increments the
+ *     budget; trip the cap and new AUTH attempts get
+ *     `* BAD Too many AUTH failures` + connection close.
+ *
+ *   ## Audit lifecycle
+ *
+ *   - `mail.server.imap.connect`      — IP, TLS state
+ *   - `mail.server.imap.auth_attempt` — mechanism, actor-hash
+ *   - `mail.server.imap.auth_success` — mechanism, tenantId, scopes
+ *   - `mail.server.imap.auth_failed`  — mechanism, reason
+ *   - `mail.server.imap.select`       — mailbox, modseq, exists count
+ *   - `mail.server.imap.append`       — mailbox, size, flags
+ *   - `mail.server.imap.fetch_bulk`   — sequence-set size, BODY parts
+ *   - `mail.server.imap.expunge`      — count, modseq
+ *   - `mail.server.imap.literal_overflow_refused` — attempt size, cap
+ *   - `mail.server.imap.rate_limit_refused`        — IP, reason
+ *   - `mail.server.imap.smtp_smuggling_detected`   — literal-injection
+ *
+ *   ## What v1 does NOT ship
+ *
+ *   - **SEARCH** — operator wires `opts.search(actor, mailbox, query)`
+ *     when ready; the listener emits `BAD search-not-configured`
+ *     until then. SEARCH expressions are operator-domain logic
+ *     against the mailStore index.
+ *   - **NOTIFY (RFC 5465)**, **METADATA (RFC 5464)**, **CATENATE
+ *     (RFC 4469)**, **URLAUTH (RFC 4467)**, **IMAPSIEVE (RFC 6785)**,
+ *     **COMPRESS=DEFLATE (RFC 4978)** — opt-in / refused.
+ *   - **CONDSTORE / QRESYNC (RFC 7162)** — modseq is exposed via
+ *     STATUS but per-FETCH CHANGEDSINCE delta is operator-side
+ *     follow-up.
+ *
+ * @card
+ *   IMAP4rev2 mailbox-access listener (RFC 9051; obsoletes RFC 3501).
+ *   State machine NOT-AUTH → STARTTLS → AUTH → SELECTED → LOGOUT.
+ *   Composes b.guardImapCommand (wire-protocol gate), b.mail.server.
+ *   rateLimit (DoS defense), operator-supplied mailStore + SASL
+ *   authenticator. Default-on per-IP rate-limit + literal-injection
+ *   refusal + mailbox-traversal refusal.
+ */
+
+var net  = require("node:net");
+var nodeTls = require("node:tls");
+var lazyRequire = require("./lazy-require");
+var C = require("./constants");
+var bCrypto = require("./crypto");
+var numericBounds = require("./numeric-bounds");
+var validateOpts = require("./validate-opts");
+var guardImapCommand = require("./guard-imap-command");
+var mailServerRateLimit = require("./mail-server-rate-limit");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var MailServerImapError = defineClass("MailServerImapError", { alwaysPermanent: true });
+
+var DEFAULT_MAX_LINE_BYTES   = C.BYTES.kib(8);
+var DEFAULT_MAX_LITERAL      = C.BYTES.mib(64);
+var DEFAULT_IDLE_TIMEOUT_MS  = C.TIME.minutes(30);
+var IDLE_BANDWIDTH_TIMEOUT_MS = C.TIME.minutes(29);  // RFC 2177 §3 — re-issue before 30
+var DEFAULT_GREETING_VENDOR  = "blamejs IMAP4rev2";
+var pkgVersion = require("../package.json").version;
+
+// Error-message clamp bytes — protocol-string clamp, not a byte count.
+// Centralized so the allow:raw-byte-literal marker lives in one place
+// and the per-call sites read cleanly.
+var ERR_CLAMP = 200;                                                                                  // allow:raw-byte-literal — protocol-reply error-message clamp
+var LINE_PREVIEW = 80;                                                                                // allow:raw-byte-literal — audit-line preview clamp
+
+// Mailbox name validator. RFC 9051 §5.1 — UTF-8 hierarchy. Refuse
+// path-traversal (`..`), NUL, C0 controls, leading/trailing slash,
+// oversize.
+function _validateMailboxName(name, opts) {
+  if (typeof name !== "string" || name.length === 0) return false;
+  if (name.length > 1024) return false;                                                              // allow:raw-byte-literal — mailbox name cap
+  for (var i = 0; i < name.length; i += 1) {
+    var c = name.charCodeAt(i);
+    if (c < 0x20 || c === 0x7F) return false;                                                        // allow:raw-byte-literal — control-byte refusal
+  }
+  if (name.indexOf("..") !== -1) return false;
+  if (name === "/" || name[0] === "/" || name[name.length - 1] === "/") return false;
+  // Modified-UTF7 detection — RFC 3501 §5.1.3. Sequences are
+  // `&...-`. Refuse under strict (RFC 9051 uses raw UTF-8).
+  if (opts && opts.allowLegacyMUtf7 !== true) {
+    if (/&[A-Za-z0-9+/]*-/.test(name)) return false;                                                  // allow:regex-no-length-cap — mailbox name already length-capped above
+  }
+  return true;
+}
+
+/**
+ * @primitive b.mail.server.imap.create
+ * @signature b.mail.server.imap.create(opts)
+ * @since     0.9.49
+ * @status    stable
+ * @related   b.mail.server.mx.create, b.mail.server.submission.create, b.mailStore.create
+ *
+ * Build an IMAP4rev2 listener (RFC 9051). The handle exposes
+ * `listen({ port, address })` → ephemeral-bind promise resolving to
+ * `{ port, address }`, plus `close()` for graceful shutdown.
+ *
+ * @opts
+ *   tlsContext:        SecureContext,   // required (no plaintext mode)
+ *   greeting:          string,           // default "blamejs IMAP4rev2"
+ *   maxLineBytes:      number,           // default 8192
+ *   maxLiteralBytes:   number,           // default 64 MiB
+ *   idleTimeoutMs:     number,           // default 30 min
+ *   profile:           "strict" | "balanced" | "permissive",
+ *   auth: {
+ *     mechanisms:      ["PLAIN", "LOGIN", "SCRAM-SHA-256", "EXTERNAL", "XOAUTH2"],
+ *     verify:          async function (mechanism, credentials) → { ok, actor },
+ *   },
+ *   mailStore:         b.mailStore handle,    // required
+ *   rateLimit:         b.mail.server.rateLimit handle | opts | false,
+ *   audit:             b.audit                // optional
+ *
+ * @example
+ *   var imap = b.mail.server.imap.create({
+ *     tlsContext: b.mail.server.tls.context({ certFile, keyFile }).secureContext,
+ *     auth: {
+ *       mechanisms: ["PLAIN", "SCRAM-SHA-256"],
+ *       verify:     async function (mech, creds) {
+ *         return { ok: true, actor: { tenantId: "t1", username: creds.authzid } };
+ *       },
+ *     },
+ *     mailStore: b.mailStore.create({ backend: b.db.handle() }),
+ *   });
+ *   await imap.listen({ port: 143 });
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "mail.server.imap.create",
+    MailServerImapError, "mail-server-imap/bad-opts");
+  if (!opts.tlsContext) {
+    throw new MailServerImapError("mail-server-imap/no-tls-context",
+      "mail.server.imap.create: tlsContext is required (no implicit plaintext mode). " +
+      "Use b.mail.server.tls.context({ certFile, keyFile, watch: true }) to load + " +
+      "auto-reload a cert/key pair from disk.");
+  }
+  if (!opts.mailStore || typeof opts.mailStore.appendMessage !== "function") {
+    throw new MailServerImapError("mail-server-imap/no-mail-store",
+      "mail.server.imap.create: mailStore is required (compose b.mailStore.create({ backend: ... }))");
+  }
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxLineBytes", "maxLiteralBytes", "idleTimeoutMs"],
+    "mail.server.imap.", MailServerImapError, "mail-server-imap/bad-bound");
+
+  var greeting          = opts.greeting        || DEFAULT_GREETING_VENDOR;
+  var maxLineBytes      = opts.maxLineBytes    || DEFAULT_MAX_LINE_BYTES;
+  var maxLiteralBytes   = opts.maxLiteralBytes || DEFAULT_MAX_LITERAL;
+  var idleTimeoutMs     = opts.idleTimeoutMs   || DEFAULT_IDLE_TIMEOUT_MS;
+  var profile           = opts.profile         || "strict";
+  var authConfig        = opts.auth            || null;
+  var mailStore         = opts.mailStore;
+  var allowLegacyMUtf7  = profile === "permissive";
+
+  var rateLimit;
+  if (opts.rateLimit === false) {
+    rateLimit = mailServerRateLimit.create({ disabled: true });
+  } else if (opts.rateLimit && typeof opts.rateLimit.admitConnection === "function") {
+    rateLimit = opts.rateLimit;
+  } else {
+    rateLimit = mailServerRateLimit.create(opts.rateLimit || {});
+  }
+
+  var tcpServer    = null;
+  var listening    = false;
+  var connections  = new Set();
+
+  function _emit(action, metadata, outcome) {
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  outcome || "success",
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit best-effort */ }
+  }
+
+  function _handleConnection(rawSocket) {
+    var remoteAddress = rawSocket.remoteAddress || "0.0.0.0";
+    var admit = rateLimit.admitConnection(remoteAddress);
+    if (!admit.ok) {
+      _emit("mail.server.imap.rate_limit_refused",
+        { remoteAddress: remoteAddress, reason: admit.reason }, "denied");
+      try { rawSocket.write("* BAD Too many connections from your IP\r\n"); }
+      catch (_e) { /* socket may be down */ }
+      try { rawSocket.destroy(); } catch (_e2) { /* idempotent */ }
+      return;
+    }
+    rawSocket.once("close", function () { rateLimit.releaseConnection(remoteAddress); });
+
+    var connectionId = "imapconn-" + bCrypto.generateToken(8);                                       // allow:raw-byte-literal — connection-id length
+    var socket = rawSocket;
+    connections.add(socket);
+
+    var state = {
+      id:            connectionId,
+      remoteAddress: remoteAddress,
+      tls:           false,
+      stage:         "not-authenticated",
+      actor:         null,
+      selectedMailbox: null,
+      selectedReadOnly: false,
+      authPending:   null,
+      pendingLiteral: null,         // { tag, verb, line, size, body }
+      idle:          null,          // { tag, timer }
+      // Per-connection receive buffer (must NOT be a closure variable —
+      // multiple concurrent connections would clobber each other).
+      lineBuffer:    Buffer.alloc(0),
+    };
+
+    _emit("mail.server.imap.connect",
+      { connectionId: connectionId, remoteAddress: remoteAddress });
+
+    socket.setTimeout(idleTimeoutMs);
+    socket.on("timeout", function () {
+      _writeUntagged(socket, "BYE Idle timeout");
+      _close(socket);
+    });
+    socket.on("error", function (err) {
+      _emit("mail.server.imap.socket_error",
+        { connectionId: connectionId, error: (err && err.message) || String(err) }, "failure");
+    });
+
+    // Greeting per RFC 9051 §7.1.5 — `* OK <greeting>`.
+    _writeUntagged(socket, "OK [CAPABILITY " + _capabilityLine(state) + "] " + greeting);
+
+    socket.on("data", function (chunk) {
+      state.lineBuffer = Buffer.concat([state.lineBuffer, chunk]);
+      _drainBuffer(state, socket);
+    });
+  }
+
+  // Receive-buffer drain: extract complete lines (CRLF-terminated)
+  // and dispatch. When the previous command opened a literal (e.g.
+  // APPEND ... {N}), the next N bytes are the literal payload — we
+  // accumulate them before resuming line-mode dispatch.
+  function _drainBuffer(state, socket) {
+    while (true) {
+      if (state.pendingLiteral) {
+        var need = state.pendingLiteral.size - state.pendingLiteral.body.length;
+        if (state.lineBuffer.length < need) {
+          state.pendingLiteral.body = Buffer.concat([state.pendingLiteral.body, state.lineBuffer]);
+          state.lineBuffer = Buffer.alloc(0);
+          return;
+        }
+        state.pendingLiteral.body = Buffer.concat([state.pendingLiteral.body, state.lineBuffer.subarray(0, need)]);
+        state.lineBuffer = state.lineBuffer.subarray(need);
+        _completeLiteralCommand(state, socket);
+        continue;
+      }
+      var crlf = state.lineBuffer.indexOf("\r\n");
+      if (crlf === -1) {
+        if (state.lineBuffer.length > maxLineBytes) {
+          _writeUntagged(socket, "BAD Line too long (cap " + maxLineBytes + ")");
+          _close(socket);
+        }
+        return;
+      }
+      var rawLine = state.lineBuffer.subarray(0, crlf).toString("utf8");
+      state.lineBuffer = state.lineBuffer.subarray(crlf + 2);
+      _handleLine(state, socket, rawLine);
+      if (state.stage === "closed") return;
+    }
+  }
+
+  function _handleLine(state, socket, line) {
+    // Continuation: AUTHENTICATE multi-step expects a client response
+    if (state.authPending) {
+      _runAuthStep(state, socket, line.trim());
+      return;
+    }
+    // IDLE termination — RFC 2177 §3 expects `DONE` line.
+    if (state.idle) {
+      if (line.toUpperCase() === "DONE") {
+        var idleTag = state.idle.tag;
+        if (state.idle.timer) clearTimeout(state.idle.timer);
+        state.idle = null;
+        _writeTagged(socket, idleTag, "OK IDLE terminated");
+      } else {
+        _writeUntagged(socket, "BAD Expected DONE during IDLE");
+      }
+      return;
+    }
+    var parsed;
+    try {
+      parsed = guardImapCommand.validate(line, {
+        profile: profile,
+        authenticated: state.actor !== null,
+      });
+    } catch (e) {
+      if (e && e.code === "guard-imap-command/literal-smuggling") {
+        _emit("mail.server.imap.smtp_smuggling_detected",
+          { connectionId: state.id, line: line.slice(0, LINE_PREVIEW) }, "denied");
+      }
+      _writeUntagged(socket, "BAD " + (e && e.message ? e.message.slice(0, ERR_CLAMP) : "syntax"));
+      return;
+    }
+    // Literal-opener: stash + emit continuation. Zero-length literals
+    // (`{0}`) are legal per RFC 9051 §6.3.12 (e.g. APPEND of an empty
+    // message body — rare but spec-compliant; refusing them would
+    // diverge from the wire-protocol).
+    if (parsed.literalSize !== null) {
+      if (parsed.literalSize > maxLiteralBytes) {
+        _emit("mail.server.imap.literal_overflow_refused",
+          { connectionId: state.id, attempted: parsed.literalSize, cap: maxLiteralBytes },
+          "denied");
+        _writeTagged(socket, parsed.tag,
+          "NO Literal " + parsed.literalSize + " bytes exceeds cap " + maxLiteralBytes);
+        return;
+      }
+      // Zero-byte literal: no continuation, no read — synthesize the
+      // pending-literal with an empty body and complete immediately on
+      // the next loop tick.
+      if (parsed.literalSize === 0) {
+        state.pendingLiteral = {
+          tag:  parsed.tag,
+          verb: parsed.verb,
+          line: line,
+          size: 0,
+          body: Buffer.alloc(0),
+          synchronizing: !parsed.literalNonSync,
+        };
+        _completeLiteralCommand(state, socket);
+        return;
+      }
+      state.pendingLiteral = {
+        tag:  parsed.tag,
+        verb: parsed.verb,
+        line: line,
+        size: parsed.literalSize,
+        body: Buffer.alloc(0),
+        synchronizing: !parsed.literalNonSync,
+      };
+      if (!parsed.literalNonSync) {
+        _writeUntagged(socket, "+ Ready for literal data");
+      }
+      return;
+    }
+    _dispatch(state, socket, parsed, line);
+  }
+
+  function _completeLiteralCommand(state, socket) {
+    var pending = state.pendingLiteral;
+    state.pendingLiteral = null;
+    // Strip the trailing literal opener `{N}` (or `{N+}`) from the line
+    var lineNoLit = pending.line.replace(/\{[0-9]+\+?\}$/, "").trim();                                // allow:regex-no-length-cap — line length already capped upstream
+    var parsed;
+    try { parsed = guardImapCommand.validate(lineNoLit, { profile: profile, authenticated: state.actor !== null }); }
+    catch (e) {
+      _writeTagged(socket, pending.tag, "BAD " + (e && e.message ? e.message.slice(0, ERR_CLAMP) : "syntax"));
+      return;
+    }
+    _dispatch(state, socket, parsed, lineNoLit, pending.body);
+  }
+
+  function _dispatch(state, socket, parsed, _rawLine, literalBody) {
+    var tag  = parsed.tag;
+    var verb = parsed.verb;
+    var args = parsed.args;
+
+    switch (verb) {
+    case "CAPABILITY": return _handleCapability(state, socket, tag);
+    case "NOOP":       return _writeTagged(socket, tag, "OK NOOP completed");
+    case "LOGOUT":     return _handleLogout(state, socket, tag);
+    case "ID":         return _handleId(state, socket, tag, args);
+    case "STARTTLS":   return _handleStartTls(state, socket, tag);
+    case "AUTHENTICATE": return _handleAuthenticate(state, socket, tag, args);
+    case "LOGIN":      return _handleLogin(state, socket, tag, args);
+    case "ENABLE":     return _writeTagged(socket, tag, "OK ENABLED");
+    case "SELECT":
+    case "EXAMINE":    return _handleSelect(state, socket, tag, args, verb === "EXAMINE");
+    case "LIST":       return _handleList(state, socket, tag, args);
+    case "STATUS":     return _handleStatus(state, socket, tag, args);
+    case "NAMESPACE":  return _writeUntagged(socket, "NAMESPACE ((\"\" \"/\")) NIL NIL"), _writeTagged(socket, tag, "OK NAMESPACE completed");
+    case "APPEND":     return _handleAppend(state, socket, tag, args, literalBody);
+    case "CHECK":      return _writeTagged(socket, tag, "OK CHECK completed");
+    case "CLOSE":
+    case "UNSELECT":   return _handleClose(state, socket, tag);
+    case "EXPUNGE":    return _handleExpunge(state, socket, tag);
+    case "FETCH":      return _handleFetch(state, socket, tag, args);
+    case "STORE":      return _handleStore(state, socket, tag, args);
+    case "UID":        return _handleUid(state, socket, tag, args);
+    case "IDLE":       return _handleIdle(state, socket, tag);
+    case "DONE":       return _writeTagged(socket, tag, "BAD DONE outside IDLE");
+    default:           return _writeTagged(socket, tag, "BAD Verb '" + verb + "' not implemented in v1");
+    }
+  }
+
+  function _capabilityLine(state) {
+    var caps = ["IMAP4rev2"];
+    if (!state.tls) caps.push("STARTTLS");
+    // Advertise AUTH=<mech> ONLY for mechanisms the operator wired
+    // in opts.auth.mechanisms. RFC 9051 §7.2 — clients pick from the
+    // advertised list; advertising AUTH=PLAIN when authConfig is null
+    // or doesn't include PLAIN sets clients up for AUTHENTICATE
+    // requests that the listener refuses with "no AUTHENTICATE
+    // configured" / "mechanism not advertised".
+    if (authConfig && Array.isArray(authConfig.mechanisms)) {
+      for (var i = 0; i < authConfig.mechanisms.length; i += 1) {
+        var m = String(authConfig.mechanisms[i]).toUpperCase();
+        if (caps.indexOf("AUTH=" + m) === -1) caps.push("AUTH=" + m);
+      }
+    }
+    return caps.join(" ");
+  }
+
+  function _handleCapability(state, socket, tag) {
+    _writeUntagged(socket, "CAPABILITY " + _capabilityLine(state));
+    _writeTagged(socket, tag, "OK CAPABILITY completed");
+  }
+
+  function _handleId(state, socket, tag, args) {
+    // RFC 2971 — clients send a key/value list, server replies with
+    // its own. We accept anything (validator caps line size) and reply
+    // with a minimal identifier.
+    void args;
+    _writeUntagged(socket, "ID (\"name\" \"blamejs\" \"version\" \"" + pkgVersion + "\")");
+    _writeTagged(socket, tag, "OK ID completed");
+  }
+
+  function _handleLogout(state, socket, tag) {
+    _writeUntagged(socket, "BYE Logging out");
+    _writeTagged(socket, tag, "OK LOGOUT completed");
+    _close(socket);
+  }
+
+  function _handleStartTls(state, socket, tag) {
+    if (state.tls) {
+      _writeTagged(socket, tag, "BAD TLS already negotiated");
+      return;
+    }
+    _writeTagged(socket, tag, "OK Begin TLS negotiation now");
+    // Drain pre-handshake buffer (RFC 9051 §11.1 / CVE-2021-33515
+    // class STARTTLS-injection defense). Any commands a client
+    // pipelined before the handshake are discarded — the post-TLS
+    // socket reads fresh.
+    state.lineBuffer = Buffer.alloc(0);
+    var tlsSocket = new nodeTls.TLSSocket(socket, {
+      isServer:      true,
+      secureContext: opts.tlsContext,
+    });
+    tlsSocket.on("secure", function () {
+      state.tls = true;
+      tlsSocket.setTimeout(idleTimeoutMs);
+      tlsSocket.on("data", function (chunk) {
+        state.lineBuffer = Buffer.concat([state.lineBuffer, chunk]);
+        _drainBuffer(state, tlsSocket);
+      });
+    });
+    tlsSocket.on("error", function (err) {
+      _emit("mail.server.imap.tls_handshake_failed",
+        { connectionId: state.id, error: (err && err.message) || String(err) }, "failure");
+      _close(socket);
+    });
+  }
+
+  function _handleAuthenticate(state, socket, tag, args) {
+    if (state.actor) {
+      _writeTagged(socket, tag, "BAD Already authenticated");
+      return;
+    }
+    if (!state.tls && profile !== "permissive") {
+      _writeTagged(socket, tag, "BAD AUTHENTICATE requires TLS (use STARTTLS first)");
+      return;
+    }
+    if (!authConfig || typeof authConfig.verify !== "function") {
+      _writeTagged(socket, tag, "NO AUTHENTICATE not configured on this listener");
+      return;
+    }
+    var authAdmit = rateLimit.checkAuthAdmit(state.remoteAddress);
+    if (!authAdmit.ok) {
+      _emit("mail.server.imap.auth_rate_limit_refused",
+        { connectionId: state.id, remoteAddress: state.remoteAddress, reason: authAdmit.reason },
+        "denied");
+      _writeTagged(socket, tag, "NO [ALERT] Too many AUTH failures from your IP");
+      _close(socket);
+      return;
+    }
+    var mechName = args.split(" ")[0].toUpperCase();
+    var initialResp = args.indexOf(" ") === -1 ? null : args.slice(args.indexOf(" ") + 1).trim();
+    var mechanisms = (authConfig.mechanisms || ["PLAIN", "LOGIN"]).map(function (m) {
+      return String(m).toUpperCase();
+    });
+    if (mechanisms.indexOf(mechName) === -1) {
+      _writeTagged(socket, tag, "NO Mechanism '" + mechName + "' not advertised");
+      return;
+    }
+    _emit("mail.server.imap.auth_attempt",
+      { connectionId: state.id, mechanism: mechName, remoteAddress: state.remoteAddress });
+    state.authPending = { mechanism: mechName, tag: tag, step: 0 };
+    _runAuthStep(state, socket, initialResp);
+  }
+
+  function _runAuthStep(state, socket, clientResp) {
+    var pending = state.authPending;
+    Promise.resolve()
+      .then(function () {
+        return authConfig.verify(pending.mechanism, {
+          step:           pending.step,
+          clientResponse: clientResp,
+          tls:            state.tls,
+          remoteAddress:  state.remoteAddress,
+        });
+      })
+      .then(function (result) {
+        pending.step += 1;
+        if (result && result.pending && typeof result.challenge === "string") {
+          // Server-side challenge — `+ <base64>` per RFC 9051 §6.2.2.
+          _writeContinuation(socket, result.challenge);
+          return;
+        }
+        if (result && result.ok === true && result.actor) {
+          state.actor = result.actor;
+          state.stage = "authenticated";
+          var savedTag = pending.tag;
+          state.authPending = null;
+          _emit("mail.server.imap.auth_success",
+            { connectionId: state.id, mechanism: pending.mechanism,
+              tenantId: result.actor.tenantId || null });
+          _writeTagged(socket, savedTag, "OK [CAPABILITY " + _capabilityLine(state) + "] AUTHENTICATE completed");
+          return;
+        }
+        var failTag = pending.tag;
+        state.authPending = null;
+        rateLimit.noteAuthFailure(state.remoteAddress);
+        _emit("mail.server.imap.auth_failed",
+          { connectionId: state.id, mechanism: pending.mechanism,
+            reason: (result && result.reason) || "verify-returned-fail" }, "denied");
+        _writeTagged(socket, failTag, "NO Authentication credentials invalid");
+      })
+      .catch(function (err) {
+        var failTag = pending.tag;
+        state.authPending = null;
+        rateLimit.noteAuthFailure(state.remoteAddress);
+        _emit("mail.server.imap.auth_failed",
+          { connectionId: state.id, mechanism: pending.mechanism,
+            reason: (err && err.message) || String(err) }, "failure");
+        _writeTagged(socket, failTag, "NO Authentication failed");
+      });
+  }
+
+  function _handleLogin(state, socket, tag, args) {
+    // RFC 9051 §6.3.4 — LOGIN is deprecated; new MUAs use AUTHENTICATE.
+    if (state.actor) {
+      _writeTagged(socket, tag, "BAD Already authenticated");
+      return;
+    }
+    if (profile === "strict") {
+      _writeTagged(socket, tag, "BAD LOGIN deprecated under strict profile; use AUTHENTICATE");
+      return;
+    }
+    if (!state.tls && profile !== "permissive") {
+      _writeTagged(socket, tag, "BAD LOGIN requires TLS (use STARTTLS first)");
+      return;
+    }
+    if (!authConfig || typeof authConfig.verify !== "function") {
+      _writeTagged(socket, tag, "NO AUTH not configured");
+      return;
+    }
+    var authAdmit = rateLimit.checkAuthAdmit(state.remoteAddress);
+    if (!authAdmit.ok) {
+      _writeTagged(socket, tag, "NO [ALERT] Too many AUTH failures from your IP");
+      _close(socket);
+      return;
+    }
+    // LOGIN args: `user pass` (quoted or atom).
+    var parts = _parseLoginArgs(args);
+    if (!parts) {
+      _writeTagged(socket, tag, "BAD LOGIN expects user + pass");
+      return;
+    }
+    Promise.resolve()
+      .then(function () {
+        return authConfig.verify("LOGIN", {
+          step: 0,
+          username:       parts[0],
+          password:       parts[1],
+          tls:            state.tls,
+          remoteAddress:  state.remoteAddress,
+        });
+      })
+      .then(function (result) {
+        if (result && result.ok && result.actor) {
+          state.actor = result.actor;
+          state.stage = "authenticated";
+          _emit("mail.server.imap.auth_success",
+            { connectionId: state.id, mechanism: "LOGIN", tenantId: result.actor.tenantId || null });
+          _writeTagged(socket, tag, "OK [CAPABILITY " + _capabilityLine(state) + "] LOGIN completed");
+          return;
+        }
+        rateLimit.noteAuthFailure(state.remoteAddress);
+        _emit("mail.server.imap.auth_failed",
+          { connectionId: state.id, mechanism: "LOGIN", reason: "verify-returned-fail" }, "denied");
+        _writeTagged(socket, tag, "NO LOGIN credentials invalid");
+      })
+      .catch(function () {
+        rateLimit.noteAuthFailure(state.remoteAddress);
+        _writeTagged(socket, tag, "NO LOGIN failed");
+      });
+  }
+
+  function _parseLoginArgs(args) {
+    if (typeof args !== "string") return null;
+    // Quoted or atom — simple parser sufficient for happy path.
+    var rest = args.trim();
+    function _take() {
+      if (rest[0] === "\"") {
+        var end = rest.indexOf("\"", 1);
+        if (end === -1) return null;
+        var v = rest.slice(1, end);
+        rest = rest.slice(end + 1).trim();
+        return v;
+      }
+      var sp = rest.indexOf(" ");
+      var v2 = sp === -1 ? rest : rest.slice(0, sp);
+      rest = sp === -1 ? "" : rest.slice(sp + 1).trim();
+      return v2;
+    }
+    var user = _take(); if (user === null) return null;
+    var pass = _take(); if (pass === null) return null;
+    return [user, pass];
+  }
+
+  function _requireAuth(state, socket, tag) {
+    if (!state.actor) {
+      _writeTagged(socket, tag, "NO Login first");
+      return false;
+    }
+    return true;
+  }
+
+  function _handleSelect(state, socket, tag, args, examine) {
+    if (!_requireAuth(state, socket, tag)) return;
+    var name = _unquote(args.trim());
+    if (!_validateMailboxName(name, { allowLegacyMUtf7: allowLegacyMUtf7 })) {
+      _writeTagged(socket, tag, "BAD Mailbox name refused");
+      return;
+    }
+    Promise.resolve()
+      .then(function () {
+        if (typeof mailStore.selectFolder === "function") {
+          return mailStore.selectFolder(state.actor, name, { readOnly: examine });
+        }
+        // Fallback shape — operators without selectFolder get a minimal
+        // OK with sentinel UIDVALIDITY 1.
+        return { exists: 0, recent: 0, uidvalidity: 1, uidnext: 1, modseq: 0, flags: [] };
+      })
+      .then(function (info) {
+        state.selectedMailbox = name;
+        state.selectedReadOnly = !!examine;
+        state.stage = "selected";
+        var flagsStr = (info.flags && info.flags.length) ? info.flags.join(" ") : "\\Seen \\Answered \\Flagged \\Deleted \\Draft";
+        _writeUntagged(socket, info.exists + " EXISTS");
+        _writeUntagged(socket, info.recent + " RECENT");
+        _writeUntagged(socket, "FLAGS (" + flagsStr + ")");
+        _writeUntagged(socket, "OK [UIDVALIDITY " + info.uidvalidity + "] UIDs valid");
+        _writeUntagged(socket, "OK [UIDNEXT " + info.uidnext + "] Predicted next UID");
+        if (info.modseq !== undefined) {
+          _writeUntagged(socket, "OK [HIGHESTMODSEQ " + info.modseq + "]");
+        }
+        _emit("mail.server.imap.select", {
+          connectionId: state.id, mailbox: name,
+          modseq: info.modseq || 0, exists: info.exists,
+        });
+        _writeTagged(socket, tag, "OK [" + (examine ? "READ-ONLY" : "READ-WRITE") + "] " +
+          (examine ? "EXAMINE" : "SELECT") + " completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "Select failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleList(state, socket, tag, args) {
+    if (!_requireAuth(state, socket, tag)) return;
+    // RFC 9051 §6.3.9 — LIST reference mailbox-pattern. Minimal
+    // implementation delegates to mailStore.listFolders if present.
+    void args;
+    Promise.resolve()
+      .then(function () {
+        if (typeof mailStore.listFolders === "function") {
+          return mailStore.listFolders(state.actor);
+        }
+        return [{ name: "INBOX", attributes: [] }];
+      })
+      .then(function (folders) {
+        for (var i = 0; i < folders.length; i += 1) {
+          var f = folders[i];
+          var attrs = (f.attributes || []).map(function (a) { return "\\" + a; }).join(" ");
+          _writeUntagged(socket, "LIST (" + attrs + ") \"/\" " + _quote(f.name));
+        }
+        _writeTagged(socket, tag, "OK LIST completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "List failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleStatus(state, socket, tag, args) {
+    if (!_requireAuth(state, socket, tag)) return;
+    var match = args.match(/^(\S+|"[^"]+")\s+\(([^)]+)\)$/);                                          // allow:regex-no-length-cap — args length already capped upstream
+    if (!match) {
+      _writeTagged(socket, tag, "BAD STATUS expects mailbox + paren-list of items");
+      return;
+    }
+    var name = _unquote(match[1]);
+    var items = match[2].split(/\s+/);
+    if (!_validateMailboxName(name, { allowLegacyMUtf7: allowLegacyMUtf7 })) {
+      _writeTagged(socket, tag, "BAD Mailbox name refused");
+      return;
+    }
+    Promise.resolve()
+      .then(function () {
+        if (typeof mailStore.statusFolder === "function") {
+          return mailStore.statusFolder(state.actor, name, items);
+        }
+        return { MESSAGES: 0, UIDNEXT: 1, UIDVALIDITY: 1, UNSEEN: 0 };
+      })
+      .then(function (info) {
+        var parts = [];
+        for (var k = 0; k < items.length; k += 1) {
+          var key = items[k].toUpperCase();
+          if (info[key] !== undefined) parts.push(key + " " + info[key]);
+        }
+        _writeUntagged(socket, "STATUS " + _quote(name) + " (" + parts.join(" ") + ")");
+        _writeTagged(socket, tag, "OK STATUS completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "Status failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleAppend(state, socket, tag, args, literalBody) {
+    if (!_requireAuth(state, socket, tag)) return;
+    if (!literalBody) {
+      _writeTagged(socket, tag, "BAD APPEND requires a literal {N} message");
+      return;
+    }
+    // RFC 9051 §6.3.12 — APPEND mailbox [(flags)] [date-time] literal
+    var match = args.match(/^(\S+|"[^"]+")(?:\s+\(([^)]*)\))?(?:\s+("[^"]+"))?$/);                    // allow:regex-no-length-cap — args length already capped upstream
+    if (!match) {
+      _writeTagged(socket, tag, "BAD APPEND syntax");
+      return;
+    }
+    var name = _unquote(match[1]);
+    var flags = match[2] ? match[2].split(/\s+/).filter(Boolean) : [];
+    if (!_validateMailboxName(name, { allowLegacyMUtf7: allowLegacyMUtf7 })) {
+      _writeTagged(socket, tag, "BAD Mailbox name refused");
+      return;
+    }
+    Promise.resolve()
+      .then(function () {
+        return mailStore.appendMessage(name, literalBody, { actor: state.actor, flags: flags });
+      })
+      .then(function (info) {
+        _emit("mail.server.imap.append",
+          { connectionId: state.id, mailbox: name, size: literalBody.length, flags: flags });
+        var token = info && info.uid ? "[APPENDUID " + (info.uidvalidity || 0) + " " + info.uid + "] " : "";
+        _writeTagged(socket, tag, "OK " + token + "APPEND completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "Append failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleClose(state, socket, tag) {
+    state.selectedMailbox = null;
+    state.selectedReadOnly = false;
+    state.stage = "authenticated";
+    _writeTagged(socket, tag, "OK CLOSE completed");
+  }
+
+  function _handleExpunge(state, socket, tag) {
+    if (!state.selectedMailbox) {
+      _writeTagged(socket, tag, "NO No mailbox selected");
+      return;
+    }
+    Promise.resolve()
+      .then(function () {
+        if (typeof mailStore.expungeFolder === "function") {
+          return mailStore.expungeFolder(state.actor, state.selectedMailbox);
+        }
+        return { expunged: [], modseq: 0 };
+      })
+      .then(function (info) {
+        var ex = info.expunged || [];
+        for (var i = 0; i < ex.length; i += 1) {
+          _writeUntagged(socket, ex[i] + " EXPUNGE");
+        }
+        _emit("mail.server.imap.expunge",
+          { connectionId: state.id, mailbox: state.selectedMailbox,
+            count: ex.length, modseq: info.modseq || 0 });
+        _writeTagged(socket, tag, "OK EXPUNGE completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "Expunge failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleFetch(state, socket, tag, args, useUid) {
+    if (!state.selectedMailbox) {
+      _writeTagged(socket, tag, "NO No mailbox selected");
+      return;
+    }
+    if (typeof mailStore.fetchRange !== "function") {
+      _writeTagged(socket, tag, "BAD FETCH backend not configured");
+      return;
+    }
+    var match = args.match(/^(\S+)\s+(.+)$/);                                                          // allow:regex-no-length-cap — args length already capped upstream
+    if (!match) {
+      _writeTagged(socket, tag, "BAD FETCH expects sequence-set + parts");
+      return;
+    }
+    var seqSet = match[1];
+    var partsSpec = match[2];
+    Promise.resolve()
+      .then(function () {
+        // useUid: true tells the backend to interpret seqSet as UIDs
+        // per RFC 9051 §6.4.9 — distinct from message-sequence-numbers
+        // under the SELECT context. UID FETCH responses MUST include
+        // the UID in the parts list per §6.4.9 ("the server SHOULD also
+        // include UID information in its response").
+        return mailStore.fetchRange(state.actor, state.selectedMailbox, seqSet, partsSpec,
+          { useUid: useUid === true });
+      })
+      .then(function (rows) {
+        var rs = rows || [];
+        _emit("mail.server.imap.fetch_bulk",
+          { connectionId: state.id, mailbox: state.selectedMailbox, count: rs.length });
+        for (var i = 0; i < rs.length; i += 1) {
+          var r = rs[i];
+          _writeUntagged(socket, r.seq + " FETCH (" + (r.payload || "") + ")");
+        }
+        _writeTagged(socket, tag, "OK FETCH completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "Fetch failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleStore(state, socket, tag, args, useUid) {
+    if (!state.selectedMailbox) {
+      _writeTagged(socket, tag, "NO No mailbox selected");
+      return;
+    }
+    if (state.selectedReadOnly) {
+      _writeTagged(socket, tag, "NO Mailbox is read-only");
+      return;
+    }
+    if (typeof mailStore.storeFlags !== "function") {
+      _writeTagged(socket, tag, "BAD STORE backend not configured");
+      return;
+    }
+    var match = args.match(/^(\S+)\s+([+-]?FLAGS(?:\.SILENT)?)\s+\(([^)]*)\)$/i);                     // allow:regex-no-length-cap — args length already capped upstream
+    if (!match) {
+      _writeTagged(socket, tag, "BAD STORE expects seq-set FLAGS (...)");
+      return;
+    }
+    var seqSet = match[1];
+    var op = match[2].toUpperCase();
+    var flagsArr = match[3].split(/\s+/).filter(Boolean);
+    var silent = /\.SILENT$/i.test(op);
+    var mode = op[0] === "+" ? "add" : op[0] === "-" ? "remove" : "replace";
+    Promise.resolve()
+      .then(function () {
+        return mailStore.storeFlags(state.actor, state.selectedMailbox, seqSet, mode, flagsArr,
+          { useUid: useUid === true });
+      })
+      .then(function (rows) {
+        if (!silent) {
+          var rs = rows || [];
+          for (var i = 0; i < rs.length; i += 1) {
+            var r = rs[i];
+            _writeUntagged(socket, r.seq + " FETCH (FLAGS (" + (r.flags || []).join(" ") + "))");
+          }
+        }
+        _writeTagged(socket, tag, "OK STORE completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "Store failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  function _handleUid(state, socket, tag, args) {
+    // UID FETCH / UID STORE / UID SEARCH / UID COPY / UID MOVE per
+    // RFC 9051 §6.4.9. The sub-command's sequence-set is interpreted
+    // as UIDs (not message-sequence-numbers); we pass `useUid: true`
+    // to the sub-handler which threads it through to the backend's
+    // mailStore.fetchRange / storeFlags via opts. Without this, the
+    // backend treats the seq-set as msg-numbers and a client's
+    // `UID FETCH 12345 (BODY[])` returns the WRONG message.
+    var sub = args.match(/^(\S+)\s+(.+)$/);                                                            // allow:regex-no-length-cap — args length already capped upstream
+    if (!sub) {
+      _writeTagged(socket, tag, "BAD UID expects a sub-command");
+      return;
+    }
+    var subVerb = sub[1].toUpperCase();
+    var subArgs = sub[2];
+    if (subVerb === "FETCH") return _handleFetch(state, socket, tag, subArgs, true);
+    if (subVerb === "STORE") return _handleStore(state, socket, tag, subArgs, true);
+    _writeTagged(socket, tag, "BAD UID " + subVerb + " not implemented in v1");
+  }
+
+  function _handleIdle(state, socket, tag) {
+    if (!_requireAuth(state, socket, tag)) return;
+    _writeContinuation(socket, "idling");
+    // RFC 2177 §3 — IDLE must be terminated with DONE before
+    // bandwidth-timeout. We schedule a soft cutoff 1 min before the
+    // hard 30-min cutoff to force client re-issue.
+    var timer = setTimeout(function () {
+      if (state.idle) {
+        _writeUntagged(socket, "BYE IDLE timed out — re-issue");
+        state.idle = null;
+        _close(socket);
+      }
+    }, IDLE_BANDWIDTH_TIMEOUT_MS);
+    state.idle = { tag: tag, timer: timer };
+  }
+
+  function _writeTagged(socket, tag, msg) {
+    try { socket.write(tag + " " + msg + "\r\n"); }
+    catch (_e) { /* socket may be down */ }
+  }
+  function _writeUntagged(socket, msg) {
+    try { socket.write("* " + msg + "\r\n"); }
+    catch (_e) { /* socket may be down */ }
+  }
+  function _writeContinuation(socket, msg) {
+    try { socket.write("+ " + msg + "\r\n"); }
+    catch (_e) { /* socket may be down */ }
+  }
+  function _close(socket) {
+    try { socket.end(); } catch (_e) { /* idempotent */ }
+    try { socket.destroy(); } catch (_e2) { /* idempotent */ }
+    connections.delete(socket);
+  }
+  function _quote(s) { return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + '"'; }
+  function _unquote(s) {
+    if (typeof s !== "string") return "";
+    if (s[0] === "\"" && s[s.length - 1] === "\"") return s.slice(1, -1);
+    return s;
+  }
+
+  // ---- Lifecycle ----------------------------------------------------------
+  async function listen(listenOpts) {
+    listenOpts = listenOpts || {};
+    if (listening) {
+      throw new MailServerImapError("mail-server-imap/already-listening",
+        "listen: already listening");
+    }
+    var port    = listenOpts.port    === undefined ? 143 : listenOpts.port;                           // allow:raw-byte-literal — RFC 9051 IMAP port (IANA)
+    var address = listenOpts.address || "0.0.0.0";
+    tcpServer = net.createServer(function (socket) { _handleConnection(socket); });
+    return new Promise(function (resolve, reject) {
+      tcpServer.once("error", reject);
+      tcpServer.listen(port, address, function () {
+        listening = true;
+        tcpServer.removeListener("error", reject);
+        _emit("mail.server.imap.listening",
+          { port: port, address: address });
+        resolve({ port: tcpServer.address().port, address: address });
+      });
+    });
+  }
+
+  async function close() {
+    if (!listening) return;
+    listening = false;
+    for (var s of connections) { try { s.destroy(); } catch (_e) { /* idempotent */ } }
+    connections.clear();
+    return new Promise(function (resolve) {
+      tcpServer.close(function () {
+        _emit("mail.server.imap.closed", {});
+        resolve();
+      });
+    });
+  }
+
+  return {
+    listen:               listen,
+    close:                close,
+  };
+}
+
+module.exports = {
+  create:               create,
+  MailServerImapError:  MailServerImapError,
+};