@blamejs/core 0.11.29 → 0.11.30

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.30 (2026-05-21) — **JMAP blob upload + download handlers on `b.mail.server.jmap` (RFC 8620 §6).** The JMAP listener now exposes turnkey HTTP handlers for blob upload (`POST /jmap/upload/{accountId}`) and blob download (`GET /jmap/download/{accountId}/{blobId}/{name}`). Upload streams the request body into `b.safeBuffer.boundedChunkCollector` (default cap 50 MiB; operator-tunable via `opts.maxBlobBytes`), then calls the operator backend's `mailStore.uploadBlob(actor, accountId, contentType, bytes) → { blobId, type?, size? }` and returns the JSON descriptor clients pass to subsequent `Email/set` / `Email/import` calls. Download walks the operator backend's `mailStore.downloadBlob(actor, accountId, blobId) → { bytes, type }` and pipes the bytes through with the right `Content-Type` + `Content-Disposition` headers. Both handlers refuse 503 when the corresponding backend hook is missing — never silent OK.
+
+EmailSubmission (RFC 8621 §7) was already in the JMAP method catalogue at `lib/mail-server-registry.js`; operators wire `EmailSubmission/get` / `EmailSubmission/set` through the existing `opts.methods` dispatch and compose `b.mail.send.deliver` (shipped v0.11.24) for the actual outbound send. No additional framework wiring is required. **Added:** *`uploadHandler(req, res)` — POST `/jmap/upload/{accountId}`* — Streams the request body through `b.safeBuffer.boundedChunkCollector` so a runaway upload refuses with `413 maxSizeUpload` instead of OOM'ing the process. Default cap 50 MiB; tune via `b.mail.server.jmap.create({ maxBlobBytes })`. The `accountId` path segment is identifier-shape-validated (`/^[A-Za-z0-9_-]{1,64}$/`) — path-traversal shapes are refused at the boundary. Calls `mailStore.uploadBlob(actor, accountId, contentType, bytes) → { blobId, type?, size? }`; the listener echoes `accountId` + `blobId` + `type` + `size` back as a `201 Created` JSON response per RFC 8620 §6.1. · *`downloadHandler(req, res)` — GET `/jmap/download/{accountId}/{blobId}/{name}`* — Parses the path's `accountId` / `blobId` / `name` segments + optional `?accept=<type>` query, calls `mailStore.downloadBlob(actor, accountId, blobId) → { bytes, type } | Buffer | null`, and pipes the bytes through with `Content-Type` (backend-supplied OR query-`accept` OR `application/octet-stream` fallback) + `Content-Length` + `Content-Disposition: attachment; filename="<safe-name>"` (only when the filename matches the safe `[A-Za-z0-9._-]{1,200}` shape — anti header-injection). Missing blob → `404 invalidArguments`. · *Both handlers exposed on the listener handle* — `b.mail.server.jmap.create(opts)` returns `{ apiHandler, sessionHandler, discoveryHandler, eventSourceHandler, uploadHandler, downloadHandler, MailServerJmapError }`. Operators mount each at the path their HTTP router exposes; the `session.uploadUrl` / `session.downloadUrl` already advertise the canonical paths. · *EmailSubmission methods continue through the existing dispatch path* — RFC 8621 §7 — `EmailSubmission/get` / `EmailSubmission/changes` / `EmailSubmission/query` / `EmailSubmission/queryChanges` / `EmailSubmission/set` are already in the JMAP method catalogue at `lib/mail-server-registry.js`. Operators wire them through `b.mail.server.jmap.create({ methods: { 'EmailSubmission/set': async function (actor, args) { ... b.mail.send.deliver(...) ... } } })`. No additional framework wiring is required for v0.11.30; the substrate composition (JMAP method → `b.mail.send.deliver` → SMTP MX → DSN) was already complete after v0.11.24. **Security:** *AccountId path-traversal refusal at the boundary* — Both handlers validate the `accountId` URL segment against `/^[A-Za-z0-9_-]{1,64}$/`. URL-encoded path-traversal payloads (`%2E%2E%2F`, `..%2F`, `/`) refuse with `400 invalidArguments` before any backend call. Operator-side validation in `mailStore.uploadBlob` / `mailStore.downloadBlob` is a defense-in-depth second layer. · *Upload size cap via `safeBuffer.boundedChunkCollector` (cap-bounded)* — Replaces the prior hand-rolled `Buffer.concat(chunks, received)` shape with the framework's bounded-collector primitive. The collector throws `mail-server-jmap/blob-too-large` on overflow; the handler converts it into a `413 maxSizeUpload` JSON error per RFC 8620 §6.1. A misbehaving client cannot stream a multi-gigabyte payload past the limit — the collector enforces the cap byte-by-byte. · *`Content-Disposition` filename is identifier-shape only* — Download responses only set the `Content-Disposition` header when the URL's `name` segment matches `/^[A-Za-z0-9._-]{1,200}$/`. Filenames with `;` / `"` / CRLF cannot be smuggled into the header — RFC 6266 §4.3 + CVE-2023-46604-class header-injection defense. **References:** [RFC 8620 (JMAP Core — §6 Blob upload/download)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 8621 (JMAP Mail — §7 EmailSubmission)](https://www.rfc-editor.org/rfc/rfc8621.html) · [RFC 6266 (Content-Disposition in HTTP)](https://www.rfc-editor.org/rfc/rfc6266.html) · [RFC 5987 (Encoding-aware filename* parameter)](https://www.rfc-editor.org/rfc/rfc5987.html)
+
 - 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)

package/lib/mail-server-jmap.js

@@ -121,6 +121,7 @@ var lazyRequire = require("./lazy-require");
 var C = require("./constants");
 var bCrypto = require("./crypto");
 var safeJson = require("./safe-json");
+var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var guardJmap = require("./guard-jmap");
 var mailServerRegistry = require("./mail-server-registry");
@@ -670,6 +671,306 @@ function create(opts) {
     req.on("error", _cleanup);
   }
 
+  // RFC 8620 §6.1 — blob upload. Operators POST raw bytes to
+  // `/jmap/upload/{accountId}` with `Content-Type` set to the
+  // blob MIME type. The handler streams the request body into a
+  // bounded buffer, calls `mailStore.uploadBlob(actor, accountId,
+  // contentType, bytes)`, and returns the JSON descriptor
+  // `{ accountId, blobId, type, size }` the client uses in
+  // subsequent Email/set / Email/import calls.
+  //
+  // Path parameters are extracted from the URL; the operator-side
+  // HTTP router MUST mount this handler at a prefix that exposes
+  // the accountId segment (e.g. `/jmap/upload/:accountId`). The
+  // handler defensively re-parses the URL in case the router didn't
+  // populate `req.params`.
+  var DEFAULT_MAX_BLOB_BYTES = opts.maxBlobBytes || (50 * 1024 * 1024);                                // allow:raw-byte-literal — 50 MiB default blob upload cap
+  // RFC 8620 §1.2 — JMAP `Id` is a non-empty string of < 256 octets in
+  // `[A-Za-z0-9_-]`. The earlier shape capped at 64 chars which refused
+  // legitimate-shape accounts; widen to the full spec maximum.
+  var MAX_JMAP_ID_LEN = 255;                                                                           // allow:raw-byte-literal — RFC 8620 §1.2 Id max length
+  var JMAP_ID_RE      = /^[A-Za-z0-9_-]{1,255}$/;
+  // Anti-polynomial: bound the URL length BEFORE any regex / split runs
+  // (CodeQL flags `\/+` on uncontrolled input). Headers + URL paths in
+  // practice stay well under 8 KiB; over-long URLs refuse outright.
+  var MAX_URL_LEN     = 8192;                                                                          // allow:raw-byte-literal — 8 KiB URL cap
+
+  // Strip a query string + walk the path producing non-empty segments,
+  // WITHOUT any unbounded regex. Returns an empty array when the URL
+  // is over the cap so the caller can refuse with 400.
+  function _splitPathSegments(rawUrl) {
+    if (typeof rawUrl !== "string" || rawUrl.length === 0 || rawUrl.length > MAX_URL_LEN) {
+      return [];
+    }
+    var qIdx = rawUrl.indexOf("?");
+    var pathOnly = qIdx === -1 ? rawUrl : rawUrl.slice(0, qIdx);
+    var out = [];
+    var cur = "";
+    for (var i = 0; i < pathOnly.length; i += 1) {
+      var ch = pathOnly.charCodeAt(i);
+      if (ch === 0x2f) {                                                                               // allow:raw-byte-literal — '/' (0x2f)
+        if (cur.length > 0) { out.push(cur); cur = ""; }
+      } else {
+        cur += pathOnly[i];
+      }
+    }
+    if (cur.length > 0) out.push(cur);
+    return out;
+  }
+
+  function uploadHandler(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.uploadBlob !== "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: "Upload backend not configured (mailStore.uploadBlob)",
+      }));
+      return;
+    }
+    // Extract accountId from URL path. The mount path is
+    // `/jmap/upload/{accountId}`; the operator's router may strip
+    // the `/jmap/upload/` prefix (so segments == [accountId]) OR
+    // pass through the full path. Either shape gives the trailing
+    // segment as accountId — but the WHOLE URL must split cleanly
+    // (`_splitPathSegments` refuses over-long input).
+    var segments = _splitPathSegments(req.url);
+    if (segments.length === 0) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Upload URL is empty or exceeds the " + MAX_URL_LEN + "-byte cap",
+      }));
+      return;
+    }
+    var accountId = (req.params && req.params.accountId) || segments[segments.length - 1] || "";
+    if (!accountId || accountId.length > MAX_JMAP_ID_LEN || !JMAP_ID_RE.test(accountId)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Upload URL missing or malformed accountId path segment (JMAP Id: [A-Za-z0-9_-]{1," + MAX_JMAP_ID_LEN + "})",
+      }));
+      return;
+    }
+    var contentType = req.headers && req.headers["content-type"]
+      ? String(req.headers["content-type"]).split(";")[0].trim()
+      : "application/octet-stream";
+    var collector = safeBuffer.boundedChunkCollector({
+      maxBytes:    DEFAULT_MAX_BLOB_BYTES,
+      errorClass:  MailServerJmapError,
+      sizeCode:    "mail-server-jmap/blob-too-large",
+      sizeMessage: "Blob exceeds maxSizeUpload (" + DEFAULT_MAX_BLOB_BYTES + " bytes)",
+    });
+    var refused = false;
+
+    req.on("data", function (chunk) {
+      if (refused) return;
+      try { collector.push(chunk); }
+      catch (_e) {
+        refused = true;
+        res.statusCode = 413;
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({
+          type:        "urn:ietf:params:jmap:error:limit",
+          limit:       "maxSizeUpload",
+          description: "Blob exceeds maxSizeUpload (" + DEFAULT_MAX_BLOB_BYTES + " bytes)",
+        }));
+        try { req.destroy(); } catch (_e2) { /* silent-catch: socket already torn down */ }
+      }
+    });
+    req.on("end", function () {
+      if (refused) return;
+      var bytes = collector.result();
+      Promise.resolve()
+        .then(function () { return opts.mailStore.uploadBlob(actor, accountId, contentType, bytes); })
+        .then(function (meta) {
+          if (!meta || typeof meta !== "object" || typeof meta.blobId !== "string") {
+            throw new MailServerJmapError("mail-server-jmap/bad-upload-result",
+              "uploadBlob backend MUST return { blobId, type?, size? }");
+          }
+          res.statusCode = 201;                                                                        // allow:raw-byte-literal — HTTP 201 Created
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            accountId: accountId,
+            blobId:    meta.blobId,
+            type:      meta.type || contentType,
+            size:      typeof meta.size === "number" ? meta.size : bytes.length,
+          }));
+        })
+        .catch(function (err) {
+          _emit("mail.server.jmap.upload_threw",
+            { accountId: accountId, error: (err && err.message) || String(err) }, "failure");
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            type:        "urn:ietf:params:jmap:error:serverFail",
+            description: "Upload failed",
+          }));
+        });
+    });
+    req.on("error", function () {
+      if (!refused) {
+        refused = true;
+        try { res.statusCode = 400; res.end(); }                                                       // allow:raw-byte-literal — HTTP 400
+        catch (_e) { /* silent-catch: socket already torn down */ }
+      }
+    });
+  }
+
+  // RFC 8620 §6.2 — blob download. GET `/jmap/download/{accountId}/
+  // {blobId}/{name}?accept={type}`. Backend hook returns a stream-
+  // shaped buffer (Buffer or async-iterable) + the canonical MIME
+  // type; the handler pipes it to the response.
+  function downloadHandler(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.downloadBlob !== "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: "Download backend not configured (mailStore.downloadBlob)",
+      }));
+      return;
+    }
+    var rawUrl = String(req.url || "");
+    if (rawUrl.length > MAX_URL_LEN) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL exceeds the " + MAX_URL_LEN + "-byte cap",
+      }));
+      return;
+    }
+    var qIdx2 = rawUrl.indexOf("?");
+    var query = qIdx2 === -1 ? "" : rawUrl.slice(qIdx2 + 1);
+    var acceptType = "";
+    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);
+      if (k === "accept") {
+        try { acceptType = decodeURIComponent(v); } catch (_e) { /* silent-catch: malformed % encoding */ }
+      }
+    });
+    // Path parsing — `/jmap/download/{accountId}/{blobId}/{name}`. The
+    // operator's router may strip the `/jmap/download/` prefix, so
+    // valid segment counts are EXACTLY 3 (router-stripped) OR 5+ AND
+    // starting with `jmap` + `download`. Anything else refuses BEFORE
+    // a tail-segment remap could land path tokens in the wrong
+    // accountId / blobId / name slots.
+    var pathSegs = _splitPathSegments(rawUrl);
+    var routerSupplied = req.params && req.params.accountId && req.params.blobId && req.params.name;
+    var accountId, blobId, fileName;
+    if (routerSupplied) {
+      accountId = req.params.accountId;
+      blobId    = req.params.blobId;
+      fileName  = req.params.name;
+    } else if (pathSegs.length === 3) {
+      accountId = pathSegs[0];
+      blobId    = pathSegs[1];
+      fileName  = pathSegs[2];
+    } else if (pathSegs.length >= 5 &&
+               pathSegs[pathSegs.length - 5].toLowerCase() === "jmap" &&
+               pathSegs[pathSegs.length - 4].toLowerCase() === "download") {
+      accountId = pathSegs[pathSegs.length - 3];
+      blobId    = pathSegs[pathSegs.length - 2];
+      fileName  = pathSegs[pathSegs.length - 1];
+    } else {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL must be /jmap/download/{accountId}/{blobId}/{name} (or router-stripped {accountId}/{blobId}/{name})",
+      }));
+      return;
+    }
+    if (!accountId || accountId.length > MAX_JMAP_ID_LEN || !JMAP_ID_RE.test(accountId)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL has malformed accountId segment (JMAP Id: [A-Za-z0-9_-]{1," + MAX_JMAP_ID_LEN + "})",
+      }));
+      return;
+    }
+    if (!blobId || blobId.length > MAX_JMAP_ID_LEN || !JMAP_ID_RE.test(blobId)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL has malformed blobId segment (JMAP Id: [A-Za-z0-9_-]{1," + MAX_JMAP_ID_LEN + "})",
+      }));
+      return;
+    }
+    Promise.resolve()
+      .then(function () { return opts.mailStore.downloadBlob(actor, accountId, blobId); })
+      .then(function (result) {
+        if (!result || (typeof result !== "object" && !Buffer.isBuffer(result))) {
+          res.statusCode = 404;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            type:        "urn:ietf:params:jmap:error:invalidArguments",
+            description: "Blob not found",
+          }));
+          return;
+        }
+        var bytes  = Buffer.isBuffer(result) ? result : result.bytes;
+        var bType  = result.type || acceptType || "application/octet-stream";
+        if (!Buffer.isBuffer(bytes)) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            type:        "urn:ietf:params:jmap:error:serverFail",
+            description: "downloadBlob backend returned a non-Buffer body",
+          }));
+          return;
+        }
+        res.statusCode = 200;
+        res.setHeader("Content-Type", bType);
+        res.setHeader("Content-Length", bytes.length);
+        // RFC 5987 — operator may want to surface fileName via
+        // Content-Disposition. Default to attachment when the
+        // download is a non-text type.
+        if (fileName && /^[A-Za-z0-9._-]{1,200}$/.test(fileName)) {
+          res.setHeader("Content-Disposition", "attachment; filename=\"" + fileName + "\"");
+        }
+        res.end(bytes);
+      })
+      .catch(function (err) {
+        _emit("mail.server.jmap.download_threw",
+          { accountId: accountId, blobId: blobId, error: (err && err.message) || String(err) }, "failure");
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({
+          type:        "urn:ietf:params:jmap:error:serverFail",
+          description: "Download failed",
+        }));
+      });
+  }
+
   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
@@ -687,6 +988,8 @@ function create(opts) {
     sessionHandler:       sessionHandler,
     discoveryHandler:     discoveryHandler,
     eventSourceHandler:   eventSourceHandler,
+    uploadHandler:        uploadHandler,
+    downloadHandler:      downloadHandler,
     MailServerJmapError:  MailServerJmapError,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.29",
+  "version": "0.11.30",
   "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:bb88c938-c54a-4094-afe0-0fa2adc94cbd",
+  "serialNumber": "urn:uuid:f3f28554-3b87-49b1-9378-0caf849de6ae",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T15:36:40.156Z",
+    "timestamp": "2026-05-21T16:27:12.212Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.29",
+      "bom-ref": "@blamejs/core@0.11.30",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.29",
+      "version": "0.11.30",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.29",
+      "purl": "pkg:npm/%40blamejs/core@0.11.30",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.29",
+      "ref": "@blamejs/core@0.11.30",
       "dependsOn": []
     }
   ]