@blamejs/core 0.11.27 → 0.11.29

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.29 (2026-05-21) — **JMAP Push — EventSource SSE handler on `b.mail.server.jmap` (RFC 8620 §7.3).** The JMAP listener now exposes a real EventSource handler at `/jmap/eventsource`. The session-resource's `eventSourceUrl` becomes a live push channel: clients connect with `?types=*|<csv>&closeafter=no|state&ping=<seconds>`, the listener subscribes via the operator backend's `mailStore.subscribePush(actor, types, emitFn)` hook, and StateChange events arrive as `event: state` SSE frames with the `{ "@type": "StateChange", changed: {...} }` payload per RFC 8620 §7.4. Keepalive `event: ping` frames default to 30 s (operator-tunable 5-900 s), `closeafter=state` closes after one event for poll-like clients, and the SSE response carries the headers proxies expect (`Cache-Control: no-cache`, `Connection: keep-alive`, `X-Accel-Buffering: no`) so nginx-fronted deployments don't buffer the stream. Without the backend subscribe hook the handler refuses with `503 serverUnavailable`, never silent OK. **Added:** *`eventSourceHandler(req, res)` exposed on the JMAP listener handle* — `b.mail.server.jmap.create(opts).eventSourceHandler` mounts on the operator's HTTP router at whatever path the session-resource's `eventSourceUrl` points to (default `/jmap/eventsource`). Authentication is delegated to the surrounding HTTP middleware (the handler expects `req.user` / `req.actor` to be set); unauthenticated requests return `401 forbidden` per RFC 8620 §1.5. Query-string params parse `types=` (CSV or `*` wildcard), `closeafter=` (`no` | `state`), `ping=` (seconds, clamped 5..900) per §7.3. · *Operator backend hook — `mailStore.subscribePush(actor, types, emitFn)`* — Backends opt in by exposing a `subscribePush` method that accepts (1) the authenticated actor, (2) a parsed `types` list (or `null` for the wildcard `*`), and (3) an `emitFn(event)` callback the backend calls when a state change occurs. The expected event shape is `{ kind: 'StateChange', changed: { <accountId>: { <typeName>: <stateString>, ... }, ... }, pushed?: {...} }`; the listener formats it into the SSE `event: state\ndata: <JSON>\n\n` wire shape. The subscribe call may return either `void` or an `unsubscribe()` function the listener invokes on disconnect. · *SSE wire-correct headers + initial-state hint* — Response headers: `Content-Type: text/event-stream; charset=utf-8`, `Cache-Control: no-cache`, `Connection: keep-alive`, `X-Accel-Buffering: no` (nginx-specific — disables response buffering on the stream so per-event frames flush immediately). The initial bytes carry `retry: 5000\n\n` (HTML5 SSE reconnect hint — 5 s) + a `: connected\n\n` comment so clients can confirm the channel is alive before the first state event. **Security:** *Push backend missing returns `503 serverUnavailable` (no silent accept)* — If the operator wired the listener without `mailStore.subscribePush`, the handler returns `503 urn:ietf:params:jmap:error:serverUnavailable` with a `description` pointing at the missing hook. RFC 8620 §7.3 expects the server to honour subscriptions or refuse explicitly — silently accepting would let a client believe events will arrive when the server cannot deliver. · *`closeafter` accepts only `no` | `state` (RFC 8620 §7.3)* — Any other value returns `400 invalidArguments` before the subscribe hook fires. Prevents an operator-supplied query string from steering the handler into an undocumented mode. · *Ping interval clamped 5..900 seconds* — `ping=<seconds>` below 5 s or above 900 s clamps to the bounds rather than refusing — a misconfigured client cannot DoS the listener via 1 ms ping floods, and a 24 h ping won't outlast intermediate proxy idle timeouts (typical 60-120 s). The clamped default (30 s) matches the RFC 8620 §7.3 example. · *Ping timer is `.unref()`'d* — Background timers without `.unref()` pin the Node process — graceful shutdown waits indefinitely. The interval is unref'd immediately after creation; per-connection cleanup (`req.on('close')` / `req.on('error')`) clears the timer + invokes the backend's optional `unsubscribe()` + ends the response. **References:** [RFC 8620 (JMAP Core — §7 Push / §7.3 EventSource / §7.4 StateChange)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 8621 (JMAP Mail)](https://www.rfc-editor.org/rfc/rfc8621.html) · [RFC 8887 (JMAP WebSocket transport — opt-in, deferred to a later slice)](https://www.rfc-editor.org/rfc/rfc8887.html) · [HTML5 Server-Sent Events (EventSource)](https://html.spec.whatwg.org/multipage/server-sent-events.html)
+
+- 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-jmap.js

@@ -502,6 +502,174 @@ function create(opts) {
       });
   }
 
+  // RFC 8620 §7.3 — EventSource (Server-Sent Events) push channel.
+  // Clients connect to `/jmap/eventsource?types=...&closeafter=...&ping=N`.
+  // Server holds the connection open and writes `event: state` + JSON
+  // payloads when the operator backend reports a state change.
+  // Periodic `event: ping` keeps intermediate proxies / load-balancers
+  // from closing the idle connection.
+  //
+  // closeafter=state — close after first state event (poll-like).
+  // closeafter=no (default) — keep open until disconnect.
+  // ping=<seconds> — keepalive interval (default 30s, min 5s, max 900s).
+  function eventSourceHandler(req, res) {
+    var actor = req.user || (req.actor || null);
+    if (!actor) {
+      res.statusCode = 401;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:forbidden",
+        description: "Authentication required",
+      }));
+      return;
+    }
+    if (typeof opts.mailStore.subscribePush !== "function") {
+      res.statusCode = 503;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:serverUnavailable",
+        description: "Push subscribe backend not configured (mailStore.subscribePush)",
+      }));
+      return;
+    }
+    // Parse query params from the URL. The HTTP server hands `req.url`
+    // with the query intact; we don't depend on Node's URL constructor
+    // for the query-string parse — small inline scan is enough.
+    var url = String(req.url || "");
+    var qIdx = url.indexOf("?");
+    var query = qIdx === -1 ? "" : url.slice(qIdx + 1);
+    var params = Object.create(null);
+    query.split("&").forEach(function (pair) {
+      if (!pair) return;
+      var eq = pair.indexOf("=");
+      var k = eq === -1 ? pair : pair.slice(0, eq);
+      var v = eq === -1 ? "" : pair.slice(eq + 1);
+      try { params[decodeURIComponent(k)] = decodeURIComponent(v); }
+      catch (_e) { /* drop-silent — malformed % encoding */ }
+    });
+    var typesStr = params.types || "*";
+    var types = typesStr === "*"
+      ? null
+      : typesStr.split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    var closeAfter = (params.closeafter || "no").toLowerCase();
+    if (closeAfter !== "no" && closeAfter !== "state") {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "closeafter must be 'no' or 'state' (RFC 8620 §7.3)",
+      }));
+      return;
+    }
+    // RFC 8620 §7.3 — `ping=0` is the EXPLICIT opt-out for the
+    // keepalive event channel. Treat it as "no ping" rather than
+    // clamping to the default. Any other non-finite / out-of-band
+    // value falls back to the 30 s default; in-band values
+    // (5..900 s) pass through unchanged so clients see the same
+    // negotiated interval they requested.
+    var pingN;
+    var pingDisabled = false;
+    if (params.ping === "0") {
+      pingDisabled = true;
+      pingN = 0;
+    } else {
+      pingN = parseInt(params.ping, 10);
+      if (!isFinite(pingN) || pingN < 5) pingN = 30;                                                   // allow:raw-byte-literal — RFC 8620 §7.3 default ping seconds
+      if (pingN > 900) pingN = 900;                                                                    // allow:raw-byte-literal — operator-supplied ping seconds, not bytes // allow:raw-time-literal — explicit max-ping cap (15 minutes)
+    }
+
+    // SSE wire headers per the HTML5 spec § "Server-sent events"
+    // and RFC 8620 §7.3 — Content-Type MUST be `text/event-stream`,
+    // intermediates MUST NOT cache (`Cache-Control: no-cache`),
+    // `Connection: keep-alive` instructs proxies to leave it open.
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");                                                          // disables nginx response buffering on the EventSource stream
+    // Initial event tells the client the stream is alive + carries
+    // the current session state so a fresh subscriber can compare
+    // against its cached `state` to know whether a missed update
+    // happened during the (re)connect.
+    res.write("retry: 5000\n\n");                                                                      // allow:raw-byte-literal — SSE reconnect-after hint (5s)
+    res.write(": connected\n\n");
+
+    var closed = false;
+    var pingTimer = null;
+    var unsubscribe = null;
+
+    function _send(eventName, data) {
+      if (closed) return;
+      try {
+        res.write("event: " + eventName + "\n");
+        res.write("data: " + (typeof data === "string" ? data : JSON.stringify(data)) + "\n\n");
+      } catch (_e) {
+        // Socket already torn down — clean up.
+        _cleanup();
+      }
+    }
+
+    function _cleanup() {
+      if (closed) return;
+      closed = true;
+      if (pingTimer) { clearInterval(pingTimer); pingTimer = null; }
+      if (typeof unsubscribe === "function") {
+        try { unsubscribe(); } catch (_e) { /* silent-catch: drop-silent — unsubscribe is best-effort cleanup */ }
+      }
+      try { res.end(); } catch (_e) { /* silent-catch: drop-silent — socket already torn down */ }
+    }
+
+    function _pingTick() {
+      if (closed) return;
+      // RFC 8620 §7.3 — ping payload carries `{ "interval": <N> }` so
+      // clients can detect stale connections via interval drift and
+      // tell whether the server clamped their requested value.
+      var pingPayload = JSON.stringify({ interval: pingN });
+      try { res.write("event: ping\ndata: " + pingPayload + "\n\n"); }
+      catch (_e) { _cleanup(); }
+    }
+
+    // Operator-supplied emit-fn — the backend pushes
+    // { kind: "StateChange", changed: { <accountId>: { <type>: <state> } } }
+    // events into the SSE stream. The listener formats per RFC 8620
+    // §7.4 — `event: state` carries the StateChange object body.
+    var emitFn = function (event) {
+      if (!event || closed) return;
+      if (event.kind === "StateChange") {
+        _send("state", {
+          "@type":  "StateChange",
+          changed:  event.changed || {},
+          pushed:   event.pushed  || undefined,
+        });
+        if (closeAfter === "state") {
+          _cleanup();
+        }
+      }
+    };
+
+    Promise.resolve()
+      .then(function () { return opts.mailStore.subscribePush(actor, types, emitFn); })
+      .then(function (unsub) {
+        if (closed) {
+          if (typeof unsub === "function") { try { unsub(); } catch (_e) { /* silent-catch: drop-silent — unsubscribe is best-effort cleanup */ } }
+          return;
+        }
+        unsubscribe = typeof unsub === "function" ? unsub : null;
+        if (!pingDisabled) {
+          pingTimer = setInterval(_pingTick, pingN * 1000);                                            // allow:raw-time-literal — seconds → ms conversion // allow:raw-byte-literal — not bytes, time conversion
+          if (pingTimer && typeof pingTimer.unref === "function") pingTimer.unref();
+        }
+      })
+      .catch(function (err) {
+        _emit("mail.server.jmap.push_subscribe_threw",
+          { error: (err && err.message) || String(err) }, "failure");
+        _cleanup();
+      });
+
+    req.on("close", _cleanup);
+    req.on("error", _cleanup);
+  }
+
   function discoveryHandler(req, res) {
     // RFC 8620 §2.2 — well-known endpoint redirects (or directly returns)
     // the session URL. We redirect to /jmap/session per the most common
@@ -518,6 +686,7 @@ function create(opts) {
     apiHandler:           apiHandler,
     sessionHandler:       sessionHandler,
     discoveryHandler:     discoveryHandler,
+    eventSourceHandler:   eventSourceHandler,
     MailServerJmapError:  MailServerJmapError,
   };
 }

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.29",
   "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:bb88c938-c54a-4094-afe0-0fa2adc94cbd",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T13:46:21.069Z",
+    "timestamp": "2026-05-21T15:36:40.156Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.27",
+      "bom-ref": "@blamejs/core@0.11.29",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.27",
+      "version": "0.11.29",
       "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.29",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.27",
+      "ref": "@blamejs/core@0.11.29",
       "dependsOn": []
     }
   ]