@xemahq/biomes-platform-imap 0.6.0 → 0.7.0

package/SECURITY-BOUNDS.md

@@ -0,0 +1,85 @@
+# IMAP connector: memory bounds against a hostile server
+
+The connector runs on a shared adapter host and dials servers that users
+configure. This file covers imapflow 1.7.8, the version in the lockfile. For
+every place where imapflow builds more memory than the server sent, or keeps
+adding to a structure across responses, it says what bounds it. Update this
+file when imapflow is bumped.
+
+## Where the checks run
+
+imapflow parses each server response and then calls its logger once, before
+any handler of that response runs (`lib/imap-flow.js`, `handleResponse`). The
+connector's logger (`imap-client.factory.ts`, `checkResponse`) does not write
+anything. It runs the checks below, and on a refusal it closes the connection.
+`close()` clears the command in flight and the selected mailbox, so the
+refused response reaches no handler. Every refusal is a typed error, logged
+as `mail.response.refused`.
+
+| Check | Bound | Code |
+| --- | --- | --- |
+| Untagged `ESEARCH` or `VANISHED` | Refused every time | `MAIL_UNEXPECTED_RESPONSE` |
+| A keyword hidden in the log (a quoted string over 100 characters) | Refused every time | `MAIL_UNEXPECTED_RESPONSE` |
+| Control budget: the logged length of every response except an untagged FETCH, SEARCH, EXISTS, EXPUNGE or RECENT | 1 MiB per connection, measured on the logged form: imapflow logs a string over 100 characters as a ~40-byte placeholder, so long strings are under-charged. The true bound is `maxReceivedBytes` | `MAIL_UNEXPECTED_RESPONSE` |
+| Per-SEARCH budget: bytes received while a SEARCH runs | `maxSearchBytes` (4 MiB) | `MAIL_SEARCH_TOO_LARGE` |
+| Inbound ceiling: `stats().received`, counted after COMPRESS inflation | `maxReceivedBytes` (128 MiB) | `MAIL_INBOUND_TOO_LARGE` |
+
+The byte checks can be passed by at most the one response that crosses them.
+The keyword is read from the logged form the same way imapflow's
+`normalizeUntaggedCommand` reads it. A test checks the two agree.
+
+## Bounds imapflow enforces itself (configured by the connector)
+
+- One line: `maxLineLength` = `maxSearchBytes`. A longer line fails the stream
+  (`MAIL_SEARCH_TOO_LARGE`).
+- One literal: `maxLiteralSize` = `maxMessageBytes`.
+- One response: `maxResponseSize` = `maxMessageBytes` + 64 KiB. This bounds the bytes of one response, not its parse time or memory.
+- Nesting: the token parser refuses more than its `MAX_NODE_DEPTH`. The
+  connector refuses BODYSTRUCTURE nested deeper than 32
+  (`MAIL_BODYSTRUCTURE_TOO_DEEP`).
+
+## The commands the connector makes imapflow send
+
+During connect: CAPABILITY, ID (if offered), STARTTLS, LOGIN or AUTHENTICATE,
+NAMESPACE, COMPRESS (if offered) and ENABLE (CONDSTORE, UTF8=ACCEPT,
+IMAP4rev2; never QRESYNC).
+
+For `getMailboxLock`: LIST "" <path> when the folder is not cached, then
+SELECT. If SELECT answers NO, imapflow sends LIST again.
+
+The actions use UID SEARCH, UID FETCH (listing, BODYSTRUCTURE, download), UID
+STORE (`mark`) and LOGOUT. imapflow may also start IDLE on its own. The
+connector passes FETCH and STORE ranges as strings, so imapflow never resolves
+a range through its own SEARCH.
+
+## Every expansion and accumulation path these commands reach
+
+| Path (imapflow 1.7.8) | What it builds | Bound |
+| --- | --- | --- |
+| `commands/search.js` ESEARCH handler, on a plain SEARCH (lines 242-307) | Walks `ALL` ranges into the result Set, up to min(EXISTS, 2^24), in one synchronous loop. About 45 wire bytes after `* 4294967295 EXISTS` | Refused at the logger. The connector never sends `SEARCH RETURN` |
+| `commands/search.js` SEARCH handler | Adds UIDs to a Set across any number of lines, up to 2^24 | Per-SEARCH budget plus the line cap |
+| `imap-flow.js` `untaggedVanished` (global, and the SELECT handler) | `expandRange` up to 2^24 UIDs, one awaited expunge event each | Refused at the logger. QRESYNC is never enabled |
+| `commands/list.js` LIST / XLIST / LSUB and STATUS handlers (LIST during `getMailboxLock`) | One entry object per line, with a Set, arrays and strings, and a STATUS map | Control budget (logged form: long strings are under-charged; the true bound is `maxReceivedBytes`) |
+| `commands/select.js` FLAGS, `OK [PERMANENTFLAGS ...]` and other `OK [...]` codes | One Set per response, replaced by the next. Other codes are scalars | Control budget (logged form: long strings are under-charged; the true bound is `maxReceivedBytes`) |
+| `commands/select.js` and global EXISTS, global EXPUNGE | One bounded number (`parseUintValue`, 10 digits) | Nothing kept. Inbound ceiling |
+| `commands/select.js` FETCH and global `untaggedFetch` (STORE, IDLE, unsolicited) | One formatted message per response, emitted as a `flags` event that nothing listens to, then dropped | Per response. Inbound ceiling |
+| `commands/fetch.js` FETCH (the connector's own fetches) | One response at a time (back-pressure through `next`) | The listing budget `maxListBytes`. Each response is charged its envelope, BODYSTRUCTURE and flags at 2 bytes a character, plus 256 bytes per response and 64 bytes per flag. Unrequested UIDs, counts or attributes: `MAIL_UNREQUESTED_RESPONSE`. Downloads: `maxMessageBytes` and `maxFetchBytes` |
+| `commands/enable.js` ENABLED | Adds to a Set across lines | Control budget (logged form: long strings are under-charged; the true bound is `maxReceivedBytes`) |
+| `commands/id.js` ID | Adds keys to a map across lines | Control budget (logged form: long strings are under-charged; the true bound is `maxReceivedBytes`) |
+| `commands/namespace.js` NAMESPACE, global CAPABILITY, and the `[CAPABILITY]` section on any response, tagged included | One object or map per response, replaced by the next. The `authCapabilities` map keeps AUTH= names | Control budget, which also charges tagged responses |
+| `commands/copyuid-parser.js` `expandRange` (COPYUID) | UID lists | Not reachable: the connector never sends COPY or MOVE |
+| `resolveRange` with a search object | A SEARCH before the command | Not reachable: ranges are strings |
+| QUOTA, STATUS, a full LIST, APPEND | n/a | Not reachable: the connector never sends them |
+
+## What these bounds do not cover
+
+- Parsing a single response. imapflow parses the whole response before the
+  logger sees it. Each token costs an object, so one response costs about 27
+  times its wire size while it is handled. For a 4 MiB line of one-character
+  atoms that is 107 MiB, measured. The memory is released after the response.
+  `maxLineLength` bounds each line and `maxResponseSize` bounds the bytes of
+  one response, but neither bounds parse time or memory: imapflow's parser can
+  be super-linear on literal-dense input, which was not measured. Isolation is
+  planned for imap 0.8.0.
+- Time. The operation deadline (`MAIL_OPERATION_TIMEOUT`) bounds it, not the
+  checks above.