dsh-agent-mailbox

LIMITATIONS

Known limitations

- **Redaction is best-effort.** It catches whole `sk-` keys, bearer tokens, JWTs and `api_key=` forms. A secret **split across lines is not caught** — there is a test asserting exactly that, so the gap cannot be mistaken for coverage. - **No rate limiting.** A participant that can reach the port can fill the log. On loopback the OS decides who that is; with `requireAuth`, whoever holds a token. Request bodies are capped at 8 MiB and concurrent SSE subscribers at 32, but nothing limits how *often* an authorized peer may send. - **Every operation re-reads and re-parses the whole log**, and writes take a cross-process lock. A write that cannot acquire it within 5s is refused rather than raced; a lock abandoned by a crashed process is reclaimed after 10s. Fine for a conversation between agents; not a queue for high-volume traffic. Set `maxRecords` to bound it. `/mailbox-peers` is worse than the rest — it is O(peers × log) — and the peer set is itself peer-controlled. - **A log past roughly 512 MB stops working entirely.** `readFileSync` returns a string, and V8 caps string length. There is no partial-read recovery path: set `maxRecords` before you get there. - **The presence directory grows one file per distinct announced name and is never pruned.** Names are bounded and validated, so this is disk, not execution — but a peer that announces under many names leaves them all. - **No end-to-end encryption.** Messages are readable by anyone who can read the file. Signing gives integrity, not secrecy — deliberately, because the log's value is that a human can read it. - **Signing is symmetric.** HMAC proves a record was not altered by someone without the secret. It is not non-repudiation between mutually distrusting parties, and does not claim to be. It is also **opt-in**: with no `signingSecret`, `integrity()` reports `signed: false`, which is not an all-clear. - **A NUL byte in message text silently suppresses the delivery hook** for that message. Node refuses NUL in an environment value, and the hook is deliberately best-effort, so the send still succeeds and the doorbell does not ring. Control characters are stripped from stored text, so this only affects a hook reading its own out-of-band copy. - **A JSON-RPC notification has no error channel to the caller.** A `tools/call` sent without an `id` is executed, but JSON-RPC forbids answering it — so a failure cannot go back to the sender, who already has a 202. It is no longer *silent*: the failure is logged naming the tool and the reason, and counted as `droppedNotifications` on `GET /health`. Send an `id` for anything whose failure you need returned to you. This was reported from the field, not caught here. A `mailbox_send` with a wrong field name (`body` instead of `text`) wrote nothing, errored nothing, and answered "202 Accepted" — a send that neither writes nor reports, which is the worst failure a mailbox can have. - **`mailbox_attachment` is capability-based.** Anyone who learns a content hash can fetch those bytes, whether or not the message was addressed to them. The id is unguessable; it is not an access check.