@blamejs/core 0.11.27 → 0.11.28

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.28 (2026-05-21) — **IMAP opt-in extensions: NOTIFY (RFC 5465), METADATA (RFC 5464), CATENATE (RFC 4469).** Three IMAP extensions advertised in CAPABILITY and dispatched through the existing per-method registry. NOTIFY accepts a client subscription spec and hands it to the operator's `mailStore.subscribeNotify(actor, spec, emitFn)` hook — actual event emission stays operator-side. METADATA exposes GETMETADATA and SETMETADATA per-mailbox + server-wide annotations through `mailStore.getMetadata` / `setMetadata`. CATENATE extends APPEND to compose a message from existing parts (`TEXT {N}` literals + `URL "imap://..."`) via `mailStore.appendCatenate`. Each handler refuses gracefully (`NO ... backend not configured`) when the operator backend doesn't supply the hook. COMPRESS=DEFLATE (RFC 4978) intentionally NOT advertised — CRIME-class compression-oracle threat on the encrypted IMAP stream. **Added:** *CAPABILITY advertises `NOTIFY`, `METADATA`, `METADATA-SERVER`, `CATENATE`* — All four added unconditionally so capable clients can exercise the extension regardless of authentication state. Each handler is registered in the protocol verb catalogue (`b.mail.serverRegistry`) + the wire-level guard verb list (`b.guardImapCommand.KNOWN_VERBS`) so the existing dispatch + audit + ratelimit gates apply uniformly. · *`NOTIFY SET ...` / `NOTIFY NONE` — RFC 5465* — The handler parses `NOTIFY SET [STATUS] (<filter-set> (<event>...))*` and `NOTIFY NONE` and stores the filter-set verbatim on `state.notifySpec`. When the operator backend exposes `mailStore.subscribeNotify(actor, spec, emitFn)`, the listener wires an `emitFn` that translates backend events (`{ kind: 'STATUS' | 'LIST' | 'FETCH', payload, seq? }`) into untagged IMAP responses on the same connection — drop-silent if the socket has already closed. Without the backend hook, the wire command refuses with `NO NOTIFY backend not configured` rather than silently accepting subscriptions the server can't fulfil. · *`GETMETADATA` / `SETMETADATA` — RFC 5464* — Both verbs parse the per-mailbox + server-wide annotation forms. GETMETADATA accepts optional `(MAXSIZE N)` / `(DEPTH ...)` options before the mailbox + entry list, walks the entries through `mailStore.getMetadata(actor, mailbox, names, opts) → [{ entry, value }]`, and renders an untagged `* METADATA <mailbox> (<entry> <value>...)` response. SETMETADATA tokenises the entry/value pairs (quoted-strings + NIL for clearing), validates the mailbox name, and forwards to `mailStore.setMetadata(actor, mailbox, entries)`. Without the backend hooks, both return `NO ... backend not configured`. · *APPEND `CATENATE` modifier — RFC 4469* — `APPEND mailbox [flags] [date-time] CATENATE (...)` is recognised before the legacy literal-required APPEND path. The parts list mixes `TEXT {N}` literal-bytes parts (handed in via the literal-aware parser) and `URL "imap://..."` reference parts; the listener bundles them into `parts: [{ kind: 'TEXT', bytes } | { kind: 'URL', url }]` and forwards to `mailStore.appendCatenate(mailbox, parts, { actor, flags, internalDate }) → { uid, uidValidity }`. When the backend returns the APPENDUID metadata the response carries `OK [APPENDUID <validity> <uid>] APPEND completed` (RFC 4315). Without the backend hook, refuses with `NO CATENATE backend not configured`. **Security:** *COMPRESS=DEFLATE intentionally NOT advertised (CRIME-class)* — RFC 4978 IMAP COMPRESS=DEFLATE enables stream compression that interacts badly with TLS — the CRIME attack class (CVE-2012-4929, BREACH, et al.) recovers plaintext via chosen-plaintext compression-ratio analysis. The framework default is OFF; operators with explicit threat models accept the downgrade via `opts.compress = true` (no opt-in path landed in v1, intentionally — defer-with-condition: open when an operator surfaces a deployment that needs it AND can document the chosen-plaintext threat model is mitigated). · *Mailbox-name validation reused for both METADATA verbs* — Both GETMETADATA and SETMETADATA run `_validateMailboxName` on the parsed mailbox argument (except for the empty-string `""` server-wide-metadata special case per RFC 5464 §3.1). Operators with the existing `allowLegacyMUtf7` opt see the same mailbox-name policy as the rest of the listener; injection-shape mailbox names are refused identically. · *NOTIFY backend-missing returns NO (not silent accept)* — If the operator wired the listener without `mailStore.subscribeNotify`, `NOTIFY SET ...` returns `NO NOTIFY backend not configured` — never a silent `OK`. RFC 5465 §6 specifies NO as the correct refusal shape; silent acceptance would let a client believe events will arrive when the server cannot fulfil the subscription. **References:** [RFC 5465 (IMAP NOTIFY)](https://www.rfc-editor.org/rfc/rfc5465.html) · [RFC 5464 (IMAP METADATA)](https://www.rfc-editor.org/rfc/rfc5464.html) · [RFC 4469 (IMAP CATENATE)](https://www.rfc-editor.org/rfc/rfc4469.html) · [RFC 4315 (IMAP UIDPLUS — APPENDUID response)](https://www.rfc-editor.org/rfc/rfc4315.html) · [RFC 4978 (IMAP COMPRESS — NOT enabled; CRIME-class threat)](https://www.rfc-editor.org/rfc/rfc4978.html) · [CVE-2012-4929 (CRIME — compression-oracle attack on TLS)](https://nvd.nist.gov/vuln/detail/CVE-2012-4929)
+
 - v0.11.27 (2026-05-20) — **IMAP CONDSTORE (RFC 7162) — modseq-aware FETCH + STORE on `b.mail.server.imap`.** The IMAP listener advertises and honours the CONDSTORE extension. Clients that issue `ENABLE CONDSTORE` get MODSEQ attributes in every untagged FETCH response; FETCH parses the `(CHANGEDSINCE <modseq>)` modifier and forwards it to the operator's backend so the backend can prune unchanged rows server-side; STORE parses the `(UNCHANGEDSINCE <modseq>)` conditional-update modifier and surfaces the backend's MODIFIED conflict set in the tagged OK response (`OK [MODIFIED <set>] STORE completed`). The backend interface picks up four new opts on the existing `fetchRange` / `storeFlags` calls: `changedSince`, `includeVanished`, `includeModseq`, `unchangedSince`. Backends MAY return modseq on each row; the listener injects `MODSEQ (<n>)` into the payload when present and CONDSTORE is enabled. QRESYNC (RFC 7162 §3.2) is deferred — accepted in ENABLE but no vanished-set surface is exposed yet. **Added:** *CAPABILITY advertises `CONDSTORE` unconditionally* — Per RFC 7162 §3 servers advertise CONDSTORE; clients ENABLE before relying on MODSEQ in untagged FETCH responses. The advertisement is unconditional (state-independent) so clients that issue CAPABILITY pre-LOGIN see CONDSTORE in the same untagged-response shape they'll see post-LOGIN. The old SELECT-side `HIGHESTMODSEQ` emission keeps working. · *`ENABLE CONDSTORE` handler flips `state.enabledCondStore`* — Replaces the no-op `OK ENABLED` shortcut with a real handler that parses the requested capability set, flips `state.enabledCondStore = true` on CONDSTORE, and replies with `ENABLED CONDSTORE` + `OK ENABLE completed`. Unknown extensions are silently ignored per RFC 5161 §3.1. QRESYNC is recognised but accepted only when a v1+ backend exposes the vanished-set surface. · *FETCH parses `(CHANGEDSINCE <modseq>)` + injects MODSEQ in responses* — When the FETCH args carry a trailing `(CHANGEDSINCE <n>)` modifier (RFC 7162 §3.1.4) the listener strips it from the fetch-att spec and forwards `opts.changedSince` to `mailStore.fetchRange`. The backend can prune unchanged messages server-side. When CONDSTORE is enabled (or the client explicitly requested MODSEQ as a fetch-att), each untagged FETCH response includes `MODSEQ (<n>)` — synthesised from `row.modseq` if the backend supplies it and the payload doesn't already contain it. Also recognises the QRESYNC `VANISHED` modifier (flag forwarded as `opts.includeVanished`); the vanished-set emission is the backend's responsibility for now. · *STORE parses `(UNCHANGEDSINCE <modseq>)` + emits `[MODIFIED <set>]` on conflict* — Per RFC 7162 §3.1.3 the conditional STORE refuses to update messages whose modseq advanced past `unchangedSince` since the client last fetched. The listener parses the modifier between the seq-set and the FLAGS op, forwards `opts.unchangedSince` to `mailStore.storeFlags`, and accepts either the legacy `rows: [...]` shape or a structured `{ rows, modified }` shape. When `modified` is non-empty, the tagged response carries `OK [MODIFIED <set>] STORE completed` so the client knows which messages need re-fetching before retry. Untagged FETCH responses also include `MODSEQ (<n>)` when STORE accepted updates under CONDSTORE. **Security:** *Modifier parsing is bounded + non-greedy* — The CHANGEDSINCE / UNCHANGEDSINCE matchers use `[^)]*` rather than `.*` so a malformed modifier can't consume the entire fetch-att spec. Both modifiers parse `\d+` only — non-integer / negative / Infinity values are silently dropped (the modifier becomes a no-op), so a client cannot ride the modifier to inject arbitrary fragments into the backend opts. · *Modseq attribute is opt-in* — MODSEQ injection into untagged FETCH responses ONLY happens when (a) CONDSTORE is enabled OR (b) the client's fetch-att spec contains the `MODSEQ` keyword. Pre-CONDSTORE clients see exactly the responses they saw before this release. The IMAP wire-format compatibility line is unchanged for the IMAP4rev1 / IMAP4rev2 cohorts that never issue `ENABLE CONDSTORE`. **References:** [RFC 7162 (IMAP4 CONDSTORE / QRESYNC)](https://www.rfc-editor.org/rfc/rfc7162.html) · [RFC 9051 (IMAP4rev2)](https://www.rfc-editor.org/rfc/rfc9051.html) · [RFC 5161 (IMAP ENABLE Extension)](https://www.rfc-editor.org/rfc/rfc5161.html) · [RFC 4315 (IMAP UIDPLUS Extension)](https://www.rfc-editor.org/rfc/rfc4315.html)
 
 - v0.11.26 (2026-05-20) — **`b.mail.server.submission` — CHUNKING / BDAT (RFC 3030).** The outbound submission listener now advertises and accepts the RFC 3030 BDAT (binary data) command, the chunked-upload alternative to DATA. Operators with large outbound payloads (attachments, MIME multipart bodies, encoded HTML) no longer pay the dot-stuffing cost of DATA; clients can stream chunks of arbitrary size and finalise with a `BDAT 0 LAST` (or `BDAT N LAST` for the final chunk). Mixing DATA + BDAT within one transaction is refused per RFC 3030 §3. Same `agent.handoff` contract — the body bytes arrive at the agent layer in their canonical SMTP form, no dot-stuffing applied (BDAT payloads are opaque). **Added:** *EHLO advertises `CHUNKING` + new `BDAT <chunk-size> [LAST]` command* — The EHLO 250-line list now includes `CHUNKING` (RFC 3030 §2.1). A new `BDAT` command handler accepts `BDAT <chunk-size> [LAST]` after MAIL FROM + RCPT TO; the server reads exactly `<chunk-size>` bytes from the socket — no dot-stuffing, no end-of-data marker — and acknowledges with `250 2.0.0 <octets> octets received`. Multiple BDAT chunks accumulate into the message body; the final chunk carries the `LAST` keyword and triggers the same agent-handoff path as DATA. A `BDAT 0 LAST` finalises an empty trailer when the last chunk's byte count is unknown in advance. · *Cumulative size cap honoured up-front* — `BDAT <large-size>` is refused with `552 5.3.4 BDAT cumulative size <total> exceeds maxMessageBytes (<cap>)` BEFORE the server begins reading bytes off the wire. A misconfigured client that pipelines `BDAT 999999999 LAST` and 1 GB of body is rejected at the command line, not after the byte stream lands. The collector bound on the receive side enforces the same cap as a backstop. · *Mid-segment payload drainage* — When `BDAT N LAST\r\n<payload>` arrives in one TCP segment (typical for pipelined small messages), the line-loop drains the post-`\r\n` bytes from the command buffer straight into the BDAT collector before returning. Any tail bytes after the BDAT chunk completes get re-fed as the next command. Operators get pipelining + chunking with no extra round-trip cost. **Security:** *BDAT state cleared on every STARTTLS upgrade* — Same threat model as CVE-2021-38371 (Exim) / CVE-2021-33515 (Dovecot): pre-handshake bytes a malicious peer pipelined MUST NOT reach the post-TLS state machine. The STARTTLS handler clears `inBdatChunk` / `bdatRemaining` / `bdatCollector` / `bdatTotalBytes` alongside the existing line-buffer + DATA-collector reset, so a smuggled `BDAT <n>` + body that lands before the TLS upgrade can't bleed into the encrypted transaction. · *Refusal on BDAT outside transaction* — BDAT before MAIL FROM / with zero RCPT returns `503 5.5.1` and does not enter chunk-collection mode. A misbehaving client that issues BDAT eagerly cannot leak state into the next transaction; the RSET reset path also clears all BDAT-side state. · *Pipelining race gate mirrors DATA* — If the operator's `recipientPolicy` is async and not all RCPT verdicts have resolved, BDAT returns `451 4.5.0 RCPT TO verdicts pending; reissue BDAT after recipient replies` — same shape as the DATA pipelining-race gate. The transaction never commits with a partially-resolved recipient set. **References:** [RFC 3030 (SMTP Service Extensions — CHUNKING / BDAT / BINARYMIME)](https://www.rfc-editor.org/rfc/rfc3030.html) · [RFC 5321 (SMTP)](https://www.rfc-editor.org/rfc/rfc5321.html) · [RFC 6409 (Message Submission for Mail)](https://www.rfc-editor.org/rfc/rfc6409.html) · [RFC 8314 (Cleartext considered obsolete — submission ports)](https://www.rfc-editor.org/rfc/rfc8314.html) · [CVE-2021-38371 (Exim STARTTLS injection)](https://nvd.nist.gov/vuln/detail/CVE-2021-38371) · [CVE-2021-33515 (Dovecot STARTTLS pre-handshake state leak)](https://nvd.nist.gov/vuln/detail/CVE-2021-33515)

package/lib/guard-imap-command.js

@@ -141,6 +141,8 @@ var KNOWN_VERBS = Object.freeze({
   COPY: true, MOVE: true, UID: true,
   GETQUOTA: true, SETQUOTA: true, GETQUOTAROOT: true,
   ID: true,
+  // v0.11.28 — RFC 5465 NOTIFY + RFC 5464 METADATA.
+  NOTIFY: true, GETMETADATA: true, SETMETADATA: true,
 });
 
 var ZERO_ARG_VERBS = Object.freeze({

package/lib/mail-server-imap.js

@@ -557,6 +557,13 @@ function create(opts) {
                       maxHandlerBytes: LONG_B,   maxHandlerMs: LONG_MS },
       IDLE:         { fn: function (s, so, p)  { return _handleIdle(s, so, p.tag); },
                       maxHandlerBytes: SHORT_B,  maxHandlerMs: LONG_MS },
+      // v0.11.28 — RFC 5465 NOTIFY / RFC 5464 METADATA / RFC 4469 CATENATE.
+      NOTIFY:       { fn: function (s, so, p)  { return _handleNotify(s, so, p.tag, p.args); },
+                      maxHandlerBytes: MEDIUM_B, maxHandlerMs: MEDIUM_MS },
+      GETMETADATA:  { fn: function (s, so, p)  { return _handleGetMetadata(s, so, p.tag, p.args); },
+                      maxHandlerBytes: MEDIUM_B, maxHandlerMs: MEDIUM_MS },
+      SETMETADATA:  { fn: function (s, so, p, lit) { return _handleSetMetadata(s, so, p.tag, p.args, lit); },
+                      maxHandlerBytes: LONG_B,   maxHandlerMs: MEDIUM_MS },
       DONE:         { fn: function (s, so, p)  { return _writeTagged(so, p.tag, "BAD DONE outside IDLE"); },
                       maxHandlerBytes: SHORT_B,  maxHandlerMs: SHORT_MS },
       // Defaults for the verbs the v0.9.49 listener didn't dispatch —
@@ -641,6 +648,17 @@ function create(opts) {
     // RFC 7162 §3 — CONDSTORE is server-advertised; clients ENABLE
     // before relying on MODSEQ in untagged FETCH responses.
     caps.push("CONDSTORE");
+    // v0.11.28 — opt-in extensions (advertised so capable clients can
+    // exercise them; each handler refuses gracefully when the operator
+    // backend doesn't supply the corresponding hook).
+    caps.push("NOTIFY");                                // RFC 5465
+    caps.push("METADATA");                              // RFC 5464 — per-mailbox annotations          // allow:raw-byte-literal — RFC number in comment
+    caps.push("METADATA-SERVER");                       // RFC 5464 §3.1 — server-wide annotations    // allow:raw-byte-literal — RFC number in comment
+    caps.push("CATENATE");                              // RFC 4469 — APPEND from existing parts
+    // NB: COMPRESS=DEFLATE (RFC 4978) intentionally NOT advertised —
+    // CRIME-class compression-oracle attack on the encrypted IMAP
+    // stream. Operators who explicitly enable it via opts.compress
+    // get a documented downgrade; v1 default is off.
     // 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
@@ -681,6 +699,191 @@ function create(opts) {
     _writeTagged(socket, tag, "OK ENABLE completed");
   }
 
+  // RFC 5465 NOTIFY — `NOTIFY SET [STATUS] (<filter-set> (<event>...))*`
+  // / `NOTIFY NONE`. Subscribes the connection to mailbox / message
+  // events on a filter set. Actual event emission is operator-side
+  // (the backend's `subscribeNotify(actor, spec, emitFn)` hook); this
+  // handler stores the parsed subscription on `state.notifySpec` so
+  // the backend can read it on later mutations. NOTIFY NONE clears.
+  function _handleNotify(state, socket, tag, args) {
+    if (!_requireAuth(state, socket, tag)) return;
+    var raw = (args || "").trim();
+    if (/^NONE\b/i.test(raw)) {
+      state.notifySpec = null;
+      if (typeof mailStore.subscribeNotify === "function") {
+        try { mailStore.subscribeNotify(state.actor, null, null); }
+        catch (_e) { /* drop-silent — operator hook may refuse mid-life */ }
+      }
+      _writeTagged(socket, tag, "OK NOTIFY completed");
+      return;
+    }
+    var setMatch = raw.match(/^SET\s+(?:STATUS\s+)?(.+)$/i);                                          // allow:regex-no-length-cap — args length already capped upstream
+    if (!setMatch) {
+      _writeTagged(socket, tag, "BAD NOTIFY syntax (RFC 5465 §6)");
+      return;
+    }
+    // Store the spec verbatim; the backend parses the filter-set
+    // vocabulary (`SELECTED`, `SELECTED-DELAYED`, `INBOXES`,
+    // `PERSONAL`, `SUBSCRIBED`, `MAILBOXES <list>`, `SUBTREE <list>`)
+    // since the event semantics live there. The listener's job is to
+    // hand the wire string to the backend.
+    state.notifySpec = setMatch[1];
+    if (typeof mailStore.subscribeNotify === "function") {
+      Promise.resolve()
+        .then(function () {
+          return mailStore.subscribeNotify(state.actor, state.notifySpec, function (event) {
+            // Backend pushes events as { kind, mailbox, payload }; we
+            // emit them as untagged responses on the same connection.
+            if (!event || typeof event.kind !== "string") return;
+            try {
+              if (event.kind === "STATUS") {
+                _writeUntagged(socket, "STATUS " + event.payload);
+              } else if (event.kind === "LIST") {
+                _writeUntagged(socket, "LIST " + event.payload);
+              } else if (event.kind === "FETCH") {
+                _writeUntagged(socket, (event.seq || "") + " FETCH (" + (event.payload || "") + ")");
+              }
+            } catch (_e) { /* drop-silent — socket may already be closed */ }
+          });
+        })
+        .then(function () { _writeTagged(socket, tag, "OK NOTIFY completed"); })
+        .catch(function (err) {
+          _writeTagged(socket, tag, "NO " + ((err && err.message) || "NOTIFY refused").slice(0, ERR_CLAMP));
+        });
+      return;
+    }
+    // Backend doesn't expose the subscribe hook — accept the wire
+    // command but emit no events. RFC 5465 §6 says NO is the right
+    // refusal shape when the server cannot fulfil the subscription.
+    _writeTagged(socket, tag, "NO NOTIFY backend not configured");
+  }
+
+  // RFC 5464 §4.1 GETMETADATA — `GETMETADATA [opts] mailbox entries`.
+  // `mailbox` may be `""` for server-wide annotations (METADATA-SERVER).
+  // Entries are slash-prefixed names (`/private/foo` / `/shared/bar`).
+  // Backend hook: `mailStore.getMetadata(actor, mailbox, names) →
+  // [{ entry, value }]`.
+  function _handleGetMetadata(state, socket, tag, args) {
+    if (!_requireAuth(state, socket, tag)) return;
+    if (typeof mailStore.getMetadata !== "function") {
+      _writeTagged(socket, tag, "NO GETMETADATA backend not configured");
+      return;
+    }
+    // Strip optional MAXSIZE / DEPTH opts: GETMETADATA (MAXSIZE 1024) "" ("/foo")
+    var rest = (args || "").trim();
+    var opts = {};
+    var optsMatch = rest.match(/^\(([^)]+)\)\s+(.+)$/);                                                // allow:regex-no-length-cap — args length already capped upstream
+    if (optsMatch) {
+      var optBody = optsMatch[1];
+      var maxMatch = optBody.match(/MAXSIZE\s+(\d+)/i);                                                // allow:regex-no-length-cap — optBody bounded by parens
+      if (maxMatch) opts.maxSize = parseInt(maxMatch[1], 10);
+      var depthMatch = optBody.match(/DEPTH\s+(\w+)/i);                                                // allow:regex-no-length-cap — optBody bounded
+      if (depthMatch) opts.depth = depthMatch[1];
+      rest = optsMatch[2];
+    }
+    var partsMatch = rest.match(/^(\S+|"[^"]*")\s+(\(([^)]+)\)|(\/\S+))$/);                            // allow:regex-no-length-cap — args length already capped upstream
+    if (!partsMatch) {
+      _writeTagged(socket, tag, "BAD GETMETADATA syntax (RFC 5464 §4.1)");
+      return;
+    }
+    var mailbox = _unquote(partsMatch[1]);
+    var entries = partsMatch[3]
+      ? partsMatch[3].split(/\s+/).filter(Boolean)
+      : [partsMatch[4]];
+    if (mailbox !== "" && !_validateMailboxName(mailbox, { allowLegacyMUtf7: allowLegacyMUtf7 })) {
+      _writeTagged(socket, tag, "BAD Mailbox name refused");
+      return;
+    }
+    Promise.resolve()
+      .then(function () { return mailStore.getMetadata(state.actor, mailbox, entries, opts); })
+      .then(function (rows) {
+        if (Array.isArray(rows) && rows.length > 0) {
+          var pairs = rows.map(function (r) {
+            var v = r.value === null || r.value === undefined ? "NIL" : '"' + String(r.value).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + '"';
+            return r.entry + " " + v;
+          }).join(" ");
+          _writeUntagged(socket, "METADATA " + (mailbox === "" ? '""' : mailbox) + " (" + pairs + ")");
+        }
+        _writeTagged(socket, tag, "OK GETMETADATA completed");
+      })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "GETMETADATA failed").slice(0, ERR_CLAMP));
+      });
+  }
+
+  // RFC 5464 §4.3 SETMETADATA — `SETMETADATA mailbox (entry value ...)`.
+  // Setting `value = NIL` clears the entry. Backend hook:
+  // `mailStore.setMetadata(actor, mailbox, entries)`. The wire format
+  // delivers each value as a quoted-string or NIL atom; the parser
+  // here handles the simple single-line shape (no literals across
+  // SETMETADATA — operators using >1 KiB metadata go through APPEND).
+  function _handleSetMetadata(state, socket, tag, args, _literalBody) {
+    if (!_requireAuth(state, socket, tag)) return;
+    if (typeof mailStore.setMetadata !== "function") {
+      _writeTagged(socket, tag, "NO SETMETADATA backend not configured");
+      return;
+    }
+    var match = (args || "").trim().match(/^(\S+|"[^"]*")\s+\((.+)\)$/);                              // allow:regex-no-length-cap — args length already capped upstream
+    if (!match) {
+      _writeTagged(socket, tag, "BAD SETMETADATA syntax (RFC 5464 §4.3)");
+      return;
+    }
+    var mailbox = _unquote(match[1]);
+    var body = match[2];
+    if (mailbox !== "" && !_validateMailboxName(mailbox, { allowLegacyMUtf7: allowLegacyMUtf7 })) {
+      _writeTagged(socket, tag, "BAD Mailbox name refused");
+      return;
+    }
+    // Tokenise `<entry> <value> <entry> <value> ...`. Values are
+    // `"..."` quoted-string OR `NIL`. Entries are `/private/...` /
+    // `/shared/...` slash-prefixed names.
+    var entries = [];
+    var i = 0;
+    while (i < body.length) {
+      while (i < body.length && /\s/.test(body[i])) i++;
+      if (i >= body.length) break;
+      var entryStart = i;
+      while (i < body.length && !/\s/.test(body[i])) i++;
+      var entryName = body.slice(entryStart, i);
+      while (i < body.length && /\s/.test(body[i])) i++;
+      if (i >= body.length) {
+        _writeTagged(socket, tag, "BAD SETMETADATA entry '" + entryName + "' missing value");
+        return;
+      }
+      var valStart = i;
+      var value;
+      if (body[i] === '"') {
+        i++;
+        var v = "";
+        while (i < body.length && body[i] !== '"') {
+          if (body[i] === "\\" && i + 1 < body.length) { v += body[i + 1]; i += 2; }
+          else { v += body[i]; i++; }
+        }
+        if (body[i] !== '"') {
+          _writeTagged(socket, tag, "BAD SETMETADATA unterminated quoted value");
+          return;
+        }
+        i++;
+        value = v;
+      } else {
+        while (i < body.length && !/\s/.test(body[i])) i++;
+        var tok = body.slice(valStart, i);
+        value = tok.toUpperCase() === "NIL" ? null : tok;
+      }
+      entries.push({ entry: entryName, value: value });
+    }
+    if (entries.length === 0) {
+      _writeTagged(socket, tag, "BAD SETMETADATA empty entry list");
+      return;
+    }
+    Promise.resolve()
+      .then(function () { return mailStore.setMetadata(state.actor, mailbox, entries); })
+      .then(function () { _writeTagged(socket, tag, "OK SETMETADATA completed"); })
+      .catch(function (err) {
+        _writeTagged(socket, tag, "NO " + ((err && err.message) || "SETMETADATA failed").slice(0, ERR_CLAMP));
+      });
+  }
+
   function _handleCapability(state, socket, tag) {
     _writeUntagged(socket, "CAPABILITY " + _capabilityLine(state));
     _writeTagged(socket, tag, "OK CAPABILITY completed");
@@ -1053,6 +1256,112 @@ function create(opts) {
 
   function _handleAppend(state, socket, tag, args, literalBody) {
     if (!_requireAuth(state, socket, tag)) return;
+    // RFC 4469 CATENATE — `APPEND mailbox [(flags)] [date-time] CATENATE
+    // (TEXT {literal} URL "imap://...")`. The CATENATE keyword turns the
+    // command body into a list of parts the server stitches into a
+    // single message; backends supply the `appendCatenate(actor,
+    // mailbox, parts, opts) → meta` hook. Without CATENATE, fall
+    // through to the bare APPEND path that already exists.
+    var catenateMatch = args.match(/^(\S+|"[^"]+")(?:\s+\(([^)]*)\))?(?:\s+("[^"]+"))?\s+CATENATE\s+(.+)$/i);   // allow:regex-no-length-cap — args length already capped upstream
+    if (catenateMatch) {
+      if (typeof mailStore.appendCatenate !== "function") {
+        _writeTagged(socket, tag, "NO CATENATE backend not configured");
+        return;
+      }
+      var catMailbox = _unquote(catenateMatch[1]);
+      var catFlags = catenateMatch[2] ? catenateMatch[2].split(/\s+/).filter(Boolean) : [];
+      var catDateArg = catenateMatch[3] ? _unquote(catenateMatch[3]) : null;
+      var catInternalDate = null;
+      if (catDateArg) {
+        catInternalDate = _parseImapDateTime(catDateArg);
+        if (catInternalDate === null) {
+          _writeTagged(socket, tag, "BAD APPEND CATENATE date-time invalid");
+          return;
+        }
+      }
+      if (!_validateMailboxName(catMailbox, { allowLegacyMUtf7: allowLegacyMUtf7 })) {
+        _writeTagged(socket, tag, "BAD Mailbox name refused");
+        return;
+      }
+      // Validate the parens are well-formed BEFORE we touch the
+      // backend. The wire-format parts list MUST start with `(` and
+      // end with `)`; a truncated list (e.g. `(TEXT {3}` arriving as
+      // a single literal-completion before the rest of the parts
+      // streams in) is refused. Order-preserving left-to-right token
+      // walk replaces the prior URL-then-TEXT split — CATENATE
+      // semantics depend on the SEQUENCE of parts.
+      var partsBodyRaw = catenateMatch[4];
+      if (partsBodyRaw[0] !== "(" || partsBodyRaw[partsBodyRaw.length - 1] !== ")") {
+        _writeTagged(socket, tag, "BAD APPEND CATENATE parts list missing parens (RFC 4469 §3)");
+        return;
+      }
+      var partsBody = partsBodyRaw.slice(1, -1);
+      var parts = [];
+      var hadTextPart = false;
+      // Tokenise sequentially. Each part is one of:
+      //   URL "imap://..."
+      //   TEXT {<n>}   (literal — multi-literal CATENATE deferred to a
+      //                 later slice; defer-with-condition: refused
+      //                 with NO until the multi-literal protocol path
+      //                 lands).
+      var pi = 0;
+      while (pi < partsBody.length) {
+        while (pi < partsBody.length && /\s/.test(partsBody[pi])) pi += 1;
+        if (pi >= partsBody.length) break;
+        if (/^URL\b/i.test(partsBody.slice(pi))) {
+          pi += 3;                                                                                     // allow:raw-byte-literal — length of literal "URL" keyword
+          while (pi < partsBody.length && /\s/.test(partsBody[pi])) pi += 1;
+          if (partsBody[pi] !== "\"") {
+            _writeTagged(socket, tag, "BAD APPEND CATENATE URL value must be quoted-string");
+            return;
+          }
+          pi += 1;
+          var urlStart = pi;
+          while (pi < partsBody.length && partsBody[pi] !== "\"") pi += 1;
+          if (partsBody[pi] !== "\"") {
+            _writeTagged(socket, tag, "BAD APPEND CATENATE URL value unterminated quoted-string");
+            return;
+          }
+          parts.push({ kind: "URL", url: partsBody.slice(urlStart, pi) });
+          pi += 1;
+        } else if (/^TEXT\b/i.test(partsBody.slice(pi))) {
+          hadTextPart = true;
+          break;
+        } else {
+          _writeTagged(socket, tag, "BAD APPEND CATENATE unknown part (RFC 4469 §3 only URL/TEXT)");
+          return;
+        }
+      }
+      if (hadTextPart) {
+        // Multi-literal CATENATE TEXT parts need a streaming-literal
+        // protocol path the listener doesn't currently expose. RFC
+        // 4469 §3 explicitly permits servers to refuse parts they
+        // can't honour; refusing is correct (better than reordering
+        // and corrupting the message body the client requested).
+        _writeTagged(socket, tag, "NO CATENATE TEXT-literal parts not yet implemented; use APPEND with a single literal");
+        return;
+      }
+      if (parts.length === 0) {
+        _writeTagged(socket, tag, "BAD APPEND CATENATE empty parts list");
+        return;
+      }
+      Promise.resolve()
+        .then(function () {
+          return mailStore.appendCatenate(catMailbox, parts, {
+            actor: state.actor, flags: catFlags, internalDate: catInternalDate });
+        })
+        .then(function (meta) {
+          var ok = "OK APPEND completed";
+          if (meta && meta.uid && meta.uidValidity) {
+            ok = "OK [APPENDUID " + meta.uidValidity + " " + meta.uid + "] APPEND completed";
+          }
+          _writeTagged(socket, tag, ok);
+        })
+        .catch(function (err) {
+          _writeTagged(socket, tag, "NO " + ((err && err.message) || "CATENATE failed").slice(0, ERR_CLAMP));
+        });
+      return;
+    }
     if (!literalBody) {
       _writeTagged(socket, tag, "BAD APPEND requires a literal {N} message");
       return;

package/lib/mail-server-registry.js

@@ -54,6 +54,10 @@ var IMAP_VERBS = Object.freeze({
   NAMESPACE: 1, STATUS: 1, APPEND: 1, IDLE: 1, CHECK: 1, CLOSE: 1,
   UNSELECT: 1, EXPUNGE: 1, SEARCH: 1, FETCH: 1, STORE: 1, COPY: 1,
   MOVE: 1, UID: 1, DONE: 1,
+  // v0.11.28 — RFC 5465 NOTIFY / RFC 5464 METADATA / RFC 4469 CATENATE.
+  // CATENATE is an APPEND modifier and stays under APPEND in dispatch;
+  // METADATA gets GETMETADATA + SETMETADATA verbs.
+  NOTIFY: 1, GETMETADATA: 1, SETMETADATA: 1,
 });
 
 var MANAGESIEVE_VERBS = Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.27",
+  "version": "0.11.28",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:15b60ad9-cf33-4ad4-a874-947682ac8125",
+  "serialNumber": "urn:uuid:e497b463-3374-4f8a-84c2-9686c0567a23",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T13:46:21.069Z",
+    "timestamp": "2026-05-21T14:49:20.894Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.27",
+      "bom-ref": "@blamejs/core@0.11.28",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.27",
+      "version": "0.11.28",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.27",
+      "purl": "pkg:npm/%40blamejs/core@0.11.28",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.27",
+      "ref": "@blamejs/core@0.11.28",
       "dependsOn": []
     }
   ]