@pipeup/mailbox 0.0.1 → 0.5.1

package/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:22-alpine
+WORKDIR /app
+COPY package.json ./
+COPY src ./src
+ENV PORT=8787 HOST=0.0.0.0 DATA_DIR=/data
+VOLUME /data
+EXPOSE 8787
+USER node
+CMD ["node", "src/cli.mjs"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pipeup contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @pipeup/mailbox
+
+The reference HTTP mailbox server for Pipeup shared comments, and a checker for any server that claims to
+speak the same contract (`pm1`, [add-ons design](../../docs/design/addons.md) section 7.7).
+
+A mailbox stores opaque, encrypted batches of comments. The server can't read them: it holds ciphertext and
+never sees the key, which stays in the shared file's address. Run it when your organisation doesn't want even
+ciphertext to go to a public service. The Pipeup project ships this software; it runs no mailbox for anyone.
+
+- About 200 lines of Node (`node:http`, `node:crypto`), no dependencies, Node 22 or newer.
+- Storage is one append-only JSON-lines file per mailbox in `DATA_DIR`, plus a small metadata file.
+- It speaks plain HTTP on localhost. Put a TLS proxy in front: browsers only accept `https:` for a shared
+  file (`http://localhost` and `http://127.0.0.1` work for development with the headless engine).
+
+## Run it
+
+```sh
+CREATE_TOKEN="$(openssl rand -base64 24)" DATA_DIR=/var/lib/pipeup-mailbox npx @pipeup/mailbox
+```
+
+or with Docker:
+
+```sh
+docker build -t pipeup-mailbox .
+docker run -d -p 127.0.0.1:8787:8787 -v pipeup-mailbox:/data -e CREATE_TOKEN=... -e TRUST_PROXY=on pipeup-mailbox
+```
+
+| Variable         | Default   | Meaning                                                                                          |
+| ---------------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `PORT`           | 8787      | Port to listen on.                                                                               |
+| `HOST`           | 127.0.0.1 | Address to bind (`0.0.0.0` inside a container).                                                  |
+| `DATA_DIR`       | `./data`  | Where mailboxes are stored.                                                                      |
+| `CREATE_TOKEN`   | none      | When set, creating a mailbox needs `Authorization: Bearer <it>`. Set it.                         |
+| `WRITE_TOKENS`   | off       | `on` gives each mailbox a write token, which the share file carries and POST bodies must repeat. |
+| `MAX_MAILBOX_MB` | 64        | Quota per mailbox. A full mailbox answers 507.                                                   |
+| `KEEP_DAYS`      | 365       | Mailboxes are deleted this many days after their last write. `0` keeps them for ever.            |
+| `RATE_POST`      | 60        | POSTs per minute per network address.                                                            |
+| `RATE_GET`       | 600       | GETs per minute per network address.                                                             |
+| `TRUST_PROXY`    | off       | `on` takes the network address from `X-Forwarded-For`. Turn it on only behind your own proxy.    |
+
+A mailbox is also capped at 100,000 batches and every request body at 512 KiB.
+
+Programmatic use (tests, embedding):
+
+```js
+import { createMailboxServer } from "@pipeup/mailbox";
+const mailbox = createMailboxServer({ memory: true, writeTokens: true, createToken: "secret" });
+const { port } = await mailbox.listen(0);
+```
+
+## Behind a TLS proxy
+
+The proxy must pass the CORS headers through (the server sets them itself) and must not add
+`Access-Control-Allow-Credentials`. Pages opened from `file://` send `Origin: null`; the answer
+`Access-Control-Allow-Origin: *` is what lets them read the response, and `Access-Control-Expose-Headers:
+Retry-After` is what lets them read a 429.
+
+Caddy (serving under `/pipeup`):
+
+```caddy
+share.example.com {
+	handle_path /pipeup/* {
+		reverse_proxy 127.0.0.1:8787
+	}
+}
+```
+
+The server serves under any prefix, so you can instead keep the prefix with `handle /pipeup/*`. Caddy
+passes `X-Forwarded-For` by default; set `TRUST_PROXY=on`.
+
+nginx:
+
+```nginx
+location /pipeup/ {
+    proxy_pass http://127.0.0.1:8787/;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    client_max_body_size 1m;
+    # The server already sends these on every response, errors included. If you terminate CORS in nginx
+    # instead, repeat them on errors too, with "always":
+    #   add_header Access-Control-Allow-Origin "*" always;
+    #   add_header Access-Control-Expose-Headers "Retry-After" always;
+    # and never add Access-Control-Allow-Credentials.
+    # On a private address, also: add_header Access-Control-Allow-Private-Network "true" always;
+}
+```
+
+Don't add the headers in both places: duplicated `Access-Control-Allow-Origin` values make browsers refuse
+the response. With `proxy_pass` the server's own headers go through untouched. Then run the checker.
+
+## Check a server
+
+```sh
+PIPEUP_MAILBOX_CREATE_TOKEN=... npx @pipeup/mailbox check https://share.example.com/pipeup
+```
+
+It prints PASS, FAIL or SKIP for each check and exits with 1 on any failure. It works against any
+implementation, and an operator who writes their own should run it before pointing pages at it. It
+creates two mailboxes and deletes both. It checks CORS headers on success and on errors, a simple-request
+POST with a `text/plain` body, an idempotent retry, an id mismatch being refused, cursor paging and `more`,
+the 512 KiB limit (413), the 429 body and exposed `Retry-After` (SKIP when the server can't be made to
+limit within 80 POSTs), and 404 after `DELETE`. The create token is read from the environment, never from the
+command line, so it stays out of shell history and process lists. `http:` is accepted only for `localhost`
+and `127.0.0.1`.
+
+## The contract in short
+
+| Endpoint                               | Purpose                                                                           |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| `GET <base>/m/<id>/ops?since=<cursor>` | New batches after the cursor, oldest first, with `next`, `more` and `expires`.    |
+| `POST <base>/m/<id>/ops`               | Append one batch `{id, ct, token?}`; 201 appended, 200 already there.             |
+| `POST <base>/m`                        | Create a mailbox; returns its id, stop key (shown once) and optional write token. |
+| `DELETE <base>/m/<id>`                 | Delete it with `Authorization: Bearer <stop key>`; 204.                           |
+
+Every error is JSON `{v: 1, error, message}`: 400 `bad-request`, 403 `token`, 404 `gone`, 409 `cursor`, 413
+`too-large`, 429 `rate` (with `Retry-After` and `retryAfter`), 507 `full`. Mailboxes are never listed.
+The cursor is the number of batches before it. The rule every implementation must keep: every batch
+committed before a response that returned `next` is in that response or an earlier one, and none committed
+later is skipped.
+
+## Serverless and edge notes
+
+The reference server is a long-running process. The contract also fits platforms with no server, as long as
+each meets the cursor rule above:
+
+- **Cloudflare Workers**: one Durable Object per mailbox. Appends are serialised for free, and the cursor is
+  a counter in the object's storage.
+- **Deno Deploy**: Deno KV with a per-mailbox counter, incremented in an atomic transaction together with the
+  write of the batch.
+- **AWS Lambda**: DynamoDB with the mailbox as partition key and a sequence number as sort key, written with a
+  conditional put (`attribute_not_exists`) and retried on conflict.
+
+Answer `OPTIONS` and send the CORS headers on every response, errors included, whatever the platform.
+
+## What the operator can see
+
+Ciphertext only: never comment text, names, anchors, the document id or the key. The operator does see
+metadata: mailbox ids, when each request is made, batch sizes and counts, the network addresses and user
+agents of everyone reading and writing, and so which addresses use the same document. The operator can
+withhold, delete or show different readers different batches. They can't forge or alter a comment
+(signatures), and a replayed batch is dropped by its id.
+
+The write token is not in logs because it travels only in POST bodies. The mailbox id is in your access
+logs, so keep those logs as private as you would any capability URL.
+
+## Tests
+
+```sh
+npm test
+```

package/package.json

@@ -1 +1,34 @@
-{"name":"@pipeup/mailbox","version":"0.0.1","description":"Placeholder; the real release follows.","license":"MIT"}
+{
+  "name": "@pipeup/mailbox",
+  "version": "0.5.1",
+  "description": "Reference HTTP mailbox server for Pipeup shared comments (contract pm1), and a checker for any server.",
+  "homepage": "https://pipeup-ai.github.io/pipeup/",
+  "author": "Pipeup contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeup-ai/pipeup.git",
+    "directory": "services/mailbox"
+  },
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "pipeup-mailbox": "./src/cli.mjs"
+  },
+  "main": "./src/server.mjs",
+  "exports": {
+    ".": "./src/server.mjs",
+    "./check": "./src/check.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "Dockerfile"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  }
+}

package/src/check.mjs

@@ -0,0 +1,288 @@
+// The contract's own checks (pm1), runnable against any server.
+import { createHash } from "node:crypto";
+
+/**
+ * @typedef {{name: string, status: "PASS" | "FAIL" | "SKIP", note?: string}} CheckResult
+ */
+
+const ctOf = (s) => `pu1.${Buffer.from(s).toString("base64url")}`;
+const idOf = (ct) => createHash("sha256").update(ct).digest("base64url").slice(0, 22);
+const batch = (s) => {
+  const ct = ctOf(s);
+  return { id: idOf(ct), ct };
+};
+
+class Fail extends Error {}
+const ok = (cond, msg) => {
+  if (!cond) throw new Fail(msg);
+};
+
+/**
+ * @param {string} base the server's base address (no trailing slash needed)
+ * @param {{createToken?: string}} [opts]
+ * @returns {Promise<CheckResult[]>}
+ */
+export async function runChecks(base, opts = {}) {
+  const u = new URL(base);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && local)) {
+    throw new Error("The base address must be https: (http: only for localhost or 127.0.0.1).");
+  }
+  const root = base.replace(/\/+$/, "");
+  const tag = Date.now().toString(36);
+
+  async function call(method, url, { body, headers, raw } = {}) {
+    const res = await fetch(url, {
+      method,
+      body,
+      headers,
+      credentials: "omit",
+      redirect: "manual",
+    });
+    const text = await res.text();
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = undefined;
+    }
+    return { status: res.status, headers: res.headers, data, text: raw ? text : undefined };
+  }
+  const simple = (url, obj) =>
+    call("POST", url, {
+      body: typeof obj === "string" ? obj : JSON.stringify(obj),
+      headers: { "Content-Type": "text/plain;charset=UTF-8" },
+    });
+  const corsOk = (r, what) => {
+    ok(
+      r.headers.get("access-control-allow-origin") === "*",
+      `${what}: Access-Control-Allow-Origin must be *`,
+    );
+    ok(
+      (r.headers.get("access-control-expose-headers") ?? "")
+        .toLowerCase()
+        .split(/\s*,\s*/)
+        .includes("retry-after"),
+      `${what}: Access-Control-Expose-Headers must include Retry-After`,
+    );
+    ok(
+      !r.headers.has("access-control-allow-credentials"),
+      `${what}: must not send Access-Control-Allow-Credentials`,
+    );
+  };
+  const errOk = (r, status, code, what) => {
+    ok(r.status === status, `${what}: expected ${status}, got ${r.status}`);
+    ok(
+      r.data?.v === 1 && r.data.error === code && typeof r.data.message === "string",
+      `${what}: expected JSON {v:1,error:"${code}",message}`,
+    );
+    corsOk(r, what);
+  };
+
+  async function create() {
+    const headers = { "Content-Type": "text/plain;charset=UTF-8" };
+    if (opts.createToken) headers.Authorization = `Bearer ${opts.createToken}`;
+    const r = await call("POST", `${root}/m`, { body: '{"v":1}', headers });
+    ok(r.status === 201, `create: expected 201, got ${r.status} (is the create token right?)`);
+    ok(r.data?.v === 1 && /^[A-Za-z0-9_-]{22,64}$/.test(r.data.mailbox ?? ""), "create: bad mailbox id");
+    ok(typeof r.data.stop === "string" && r.data.stop.length > 0, "create: missing stop key");
+    ok(r.data.limits && r.data.limits.body >= 524288, "create: limits.body must be at least 524288");
+    corsOk(r, "create");
+    return {
+      id: r.data.mailbox,
+      stop: r.data.stop,
+      token: r.data.token ?? undefined,
+      url: `${root}/m/${r.data.mailbox}`,
+    };
+  }
+
+  /** @type {CheckResult[]} */
+  const results = [];
+  const run = async (name, fn) => {
+    try {
+      const note = await fn();
+      results.push(
+        typeof note === "string" && note.startsWith("skip:")
+          ? { name, status: "SKIP", note: note.slice(5).trim() }
+          : { name, status: "PASS" },
+      );
+    } catch (e) {
+      results.push({
+        name,
+        status: "FAIL",
+        note: e instanceof Fail ? e.message : `${e?.cause?.code ?? ""} ${e?.message ?? e}`.trim(),
+      });
+    }
+  };
+
+  let a;
+  let rateBox;
+  await run("create a mailbox (POST <base>/m)", async () => {
+    a = await create();
+    rateBox = await create();
+  });
+  if (!a) return results;
+  const post = (b, extra = {}) =>
+    simple(`${a.url}/ops`, { ...b, ...(a.token ? { token: a.token } : {}), ...extra });
+  const b1 = batch(`one-${tag}`);
+  const b2 = batch(`two-${tag}`);
+  const b3 = batch(`three-${tag}`);
+  const get = (since) =>
+    call("GET", `${a.url}/ops${since === undefined ? "" : `?since=${encodeURIComponent(since)}`}`, {
+      headers: { Accept: "application/json" },
+    });
+
+  await run("OPTIONS answers 204 with methods, headers and max-age", async () => {
+    const r = await call("OPTIONS", `${a.url}/ops`);
+    ok(r.status === 204, `expected 204, got ${r.status}`);
+    ok(
+      /GET/.test(r.headers.get("access-control-allow-methods") ?? "") &&
+        /POST/.test(r.headers.get("access-control-allow-methods") ?? ""),
+      "Allow-Methods must list GET and POST",
+    );
+    ok(
+      /content-type/i.test(r.headers.get("access-control-allow-headers") ?? ""),
+      "Allow-Headers must list Content-Type",
+    );
+    ok(r.headers.has("access-control-max-age"), "Max-Age missing");
+    corsOk(r, "OPTIONS");
+  });
+  await run("empty mailbox: GET answers the contract shape with CORS headers", async () => {
+    const r = await get();
+    ok(r.status === 200 && r.data?.v === 1, `expected 200 {v:1}, got ${r.status}`);
+    ok(Array.isArray(r.data.batches) && r.data.batches.length === 0, "batches must be an empty array");
+    ok(
+      typeof r.data.next === "string" && r.data.next.length <= 64 && /^[\x20-\x7e]*$/.test(r.data.next),
+      "next must be printable ASCII, 64 characters at most",
+    );
+    ok(typeof r.data.more === "boolean", "more must be a boolean");
+    corsOk(r, "GET");
+  });
+  await run("simple-request POST (text/plain body) appends: 201", async () => {
+    const r = await post(b1);
+    ok(r.status === 201 && r.data?.v === 1, `expected 201 {v:1}, got ${r.status}`);
+    corsOk(r, "POST");
+  });
+  await run("the same POST again is idempotent: 200", async () => {
+    const r = await post(b1);
+    ok(r.status === 200 && r.data?.v === 1, `expected 200 {v:1}, got ${r.status}`);
+    const g = await get();
+    ok(g.data.batches.filter((x) => x.id === b1.id).length === 1, "the retried batch was stored twice");
+  });
+  await run("id that does not match ct is refused: 400 bad-request", async () => {
+    errOk(await post({ id: b2.id, ct: b3.ct }), 400, "bad-request", "id mismatch");
+  });
+  await run("invalid JSON and a bad ct are refused: 400 bad-request", async () => {
+    errOk(await simple(`${a.url}/ops`, "{nope"), 400, "bad-request", "bad JSON");
+    errOk(await post({ id: idOf("x"), ct: "x" }), 400, "bad-request", "bad ct");
+  });
+  await run("cursors page forward without skipping or repeating", async () => {
+    ok((await post(b2)).status === 201, "second POST failed");
+    ok((await post(b3)).status === 201, "third POST failed");
+    const first = await get();
+    ok(
+      first.data.batches.map((x) => x.id).join() === [b1.id, b2.id, b3.id].join(),
+      "batches must come oldest first, each once",
+    );
+    const again = await get(first.data.next);
+    ok(again.status === 200 && again.data.batches.length === 0, "since=next must return nothing new");
+    const mid = await get("1");
+    const viaCursor = [];
+    let since = "";
+    for (let i = 0; i < 20; i++) {
+      const r = await get(since);
+      ok(r.status === 200, `GET since=${since} gave ${r.status}`);
+      viaCursor.push(...r.data.batches.map((x) => x.id));
+      since = r.data.next;
+      if (!r.data.more) break;
+    }
+    ok(
+      viaCursor.join() === [b1.id, b2.id, b3.id].join(),
+      "following next while more is true must reach every batch once",
+    );
+    ok(mid.status === 200 || mid.status === 409, "an arbitrary cursor must answer 200 or 409");
+    const b4 = batch(`four-${tag}`);
+    ok((await post(b4)).status === 201, "fourth POST failed");
+    const later = await get(first.data.next);
+    ok(
+      later.data.batches.map((x) => x.id).join() === b4.id,
+      "a batch committed after a cursor must be returned by since=cursor",
+    );
+  });
+  await run("unknown cursor: 409 cursor", async () => {
+    errOk(await get("zzzz-not-a-cursor"), 409, "cursor", "unknown cursor");
+  });
+  await run("body over 512 KiB: 413 too-large", async () => {
+    const ct = `pu1.${"A".repeat(524288)}`;
+    errOk(
+      await simple(`${a.url}/ops`, { id: idOf(ct), ct, ...(a.token ? { token: a.token } : {}) }),
+      413,
+      "too-large",
+      "oversized body",
+    );
+  });
+  await run("a body just under the limit is accepted", async () => {
+    const ct = `pu1.${"B".repeat(524288 - 400)}`;
+    const r = await post({ id: idOf(ct), ct });
+    ok(r.status === 201, `expected 201, got ${r.status}`);
+  });
+  await run("unknown mailbox: 404 gone, with CORS headers", async () => {
+    errOk(
+      await call("GET", `${root}/m/${"x".repeat(22)}/ops`, { headers: { Accept: "application/json" } }),
+      404,
+      "gone",
+      "unknown mailbox",
+    );
+  });
+  await run("write token: a POST without it is refused (403 token)", async () => {
+    if (!a.token) return "skip: this server does not issue write tokens";
+    errOk(await simple(`${a.url}/ops`, batch(`tok-${tag}`)), 403, "token", "missing write token");
+    errOk(
+      await simple(`${a.url}/ops`, { ...batch(`tok-${tag}`), token: "wrong" }),
+      403,
+      "token",
+      "wrong write token",
+    );
+    return undefined;
+  });
+  await run("DELETE with a wrong stop key: 403 token", async () => {
+    errOk(
+      await call("DELETE", a.url, { headers: { Authorization: "Bearer wrong" } }),
+      403,
+      "token",
+      "wrong stop key",
+    );
+  });
+  await run("DELETE with the stop key: 204, then every request answers 404", async () => {
+    const d = await call("DELETE", a.url, { headers: { Authorization: `Bearer ${a.stop}` } });
+    ok(d.status === 204, `expected 204, got ${d.status}`);
+    corsOk(d, "DELETE");
+    errOk(await get(), 404, "gone", "GET after DELETE");
+    errOk(await post(batch(`after-${tag}`)), 404, "gone", "POST after DELETE");
+  });
+  await run("rate limit: 429 with Retry-After header, retryAfter in the body, readable", async () => {
+    if (!rateBox) return "skip: no second mailbox";
+    const b = batch(`rate-${tag}`);
+    const body = JSON.stringify({ ...b, ...(rateBox.token ? { token: rateBox.token } : {}) });
+    for (let i = 0; i < 80; i++) {
+      const r = await call("POST", `${rateBox.url}/ops`, {
+        body,
+        headers: { "Content-Type": "text/plain;charset=UTF-8" },
+      });
+      if (r.status === 429) {
+        errOk(r, 429, "rate", "429");
+        const h = Number(r.headers.get("retry-after"));
+        ok(Number.isFinite(h) && h >= 0, "Retry-After header must be a number of seconds");
+        ok(typeof r.data.retryAfter === "number", "retryAfter in the body must be a number");
+        return undefined;
+      }
+      ok(r.status === 200 || r.status === 201, `unexpected ${r.status} while probing the rate limit`);
+    }
+    return "skip: the server did not limit 80 POSTs in a row";
+  });
+  if (rateBox)
+    await call("DELETE", rateBox.url, { headers: { Authorization: `Bearer ${rateBox.stop}` } }).catch(
+      () => {},
+    );
+  return results;
+}

package/src/cli.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// pipeup-mailbox: run the reference server from the environment, or `check <base>` any server.
+import { createMailboxServer } from "./server.mjs";
+import { runChecks } from "./check.mjs";
+
+const env = process.env;
+const num = (v) => (v === undefined || v === "" ? undefined : Number(v));
+
+async function main(argv) {
+  if (argv[0] === "check") {
+    const base = argv[1];
+    if (!base || base.startsWith("-")) {
+      console.error("usage: pipeup-mailbox check <base>   (create token in PIPEUP_MAILBOX_CREATE_TOKEN)");
+      return 2;
+    }
+    if (argv.includes("--create-token")) {
+      console.error(
+        "Put the create token in the PIPEUP_MAILBOX_CREATE_TOKEN environment variable, not on the command line.",
+      );
+      return 2;
+    }
+    const results = await runChecks(base, { createToken: env.PIPEUP_MAILBOX_CREATE_TOKEN });
+    for (const r of results) console.log(`${r.status} ${r.name}${r.note ? ` (${r.note})` : ""}`);
+    const failed = results.filter((r) => r.status === "FAIL").length;
+    console.log(failed ? `${failed} check(s) failed.` : "All checks passed.");
+    return failed ? 1 : 0;
+  }
+  if (argv.length) {
+    console.error(
+      "usage: pipeup-mailbox            start the server (see README for the environment)\n       pipeup-mailbox check <base>",
+    );
+    return 2;
+  }
+  const mb = num(env.MAX_MAILBOX_MB);
+  const mailbox = createMailboxServer({
+    dataDir: env.DATA_DIR || "./data",
+    createToken: env.CREATE_TOKEN || undefined,
+    writeTokens: env.WRITE_TOKENS === "on",
+    maxMailboxBytes: mb === undefined ? undefined : mb * 1024 * 1024,
+    keepDays: num(env.KEEP_DAYS),
+    rate: { post: num(env.RATE_POST), get: num(env.RATE_GET) },
+    trustProxy: env.TRUST_PROXY === "on",
+  });
+  const { port } = await mailbox.listen(num(env.PORT) ?? 8787, env.HOST || "127.0.0.1");
+  console.log(`pipeup-mailbox listening on ${env.HOST || "127.0.0.1"}:${port} (put a TLS proxy in front)`);
+  if (!env.CREATE_TOKEN)
+    console.warn(
+      "warning: CREATE_TOKEN is not set, so anyone who can reach this server can create mailboxes.",
+    );
+  for (const s of ["SIGINT", "SIGTERM"]) process.on(s, () => mailbox.close().then(() => process.exit(0)));
+  return undefined;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    if (code !== undefined) process.exit(code);
+  },
+  (e) => {
+    console.error(e?.message ?? e);
+    process.exit(1);
+  },
+);

package/src/server.mjs

@@ -0,0 +1,279 @@
+// @pipeup/mailbox: the reference HTTP mailbox server (contract pm1, docs/design/addons.md section 7.7).
+// Stores opaque, content-addressed batches. No dependencies.
+import { createServer } from "node:http";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MAX_BODY = 524288;
+const PAGE_BYTES = 4 * 1024 * 1024;
+const PAGE_BATCHES = 1000;
+const CT = /^pu1\.[A-Za-z0-9_-]+$/;
+const sha = (s) => createHash("sha256").update(s).digest();
+const b64u = (b) => Buffer.from(b).toString("base64url");
+const same = (a, b) => timingSafeEqual(sha(a), sha(b));
+
+/**
+ * @typedef {object} MailboxOptions
+ * @property {string} [dataDir] where mailboxes are stored (one JSON-lines file each)
+ * @property {boolean} [memory] keep everything in memory (tests)
+ * @property {string} [createToken] when set, `POST <base>/m` needs `Authorization: Bearer <it>`
+ * @property {boolean} [writeTokens] issue a write token per mailbox, required in POST bodies
+ * @property {number} [maxMailboxBytes] default 64 MiB
+ * @property {number} [maxBatches] default 100,000
+ * @property {number} [keepDays] default 365, counted from the last write; 0 keeps for ever
+ * @property {{post?: number, get?: number}} [rate] per network address per minute (60 / 600)
+ * @property {boolean} [trustProxy] take the address from X-Forwarded-For (behind a TLS proxy)
+ * @property {() => number} [now] clock in ms (tests)
+ * @property {number} [pageBytes] page size limits (tests)
+ * @property {number} [pageBatches]
+ */
+
+/**
+ * @param {MailboxOptions} [options]
+ * @returns {{listen(port: number, host?: string): Promise<{port: number}>, close(): Promise<void>, server: import("node:http").Server}}
+ */
+export function createMailboxServer(options = {}) {
+  const o = options;
+  const now = o.now ?? Date.now;
+  const maxBytes = o.maxMailboxBytes ?? 64 * 1024 * 1024;
+  const maxBatches = o.maxBatches ?? 100000;
+  const keepDays = o.keepDays ?? 365;
+  const limits = { POST: o.rate?.post ?? 60, GET: o.rate?.get ?? 600 };
+  const pageBytes = o.pageBytes ?? PAGE_BYTES;
+  const pageBatches = o.pageBatches ?? PAGE_BATCHES;
+  const dir = o.memory ? null : (o.dataDir ?? "./data");
+  if (dir) mkdirSync(dir, { recursive: true });
+  /** @type {Map<string, any>} */
+  const boxes = new Map();
+  /** @type {Map<string, {start: number, n: number}>} */
+  const hits = new Map();
+
+  const expiry = (b) => (keepDays > 0 ? new Date(b.last + keepDays * 864e5).toISOString() : null);
+  const drop = (id) => {
+    boxes.delete(id);
+    if (dir) for (const e of ["json", "jsonl"]) rmSync(join(dir, `${id}.${e}`), { force: true });
+  };
+  /** The mailbox, loaded from disk on first use; undefined when gone or expired. */
+  function box(id) {
+    let b = boxes.get(id);
+    if (!b && dir && existsSync(join(dir, `${id}.json`))) {
+      b = JSON.parse(readFileSync(join(dir, `${id}.json`), "utf8"));
+      b.items = [];
+      b.ids = new Set();
+      b.bytes = 0;
+      if (existsSync(join(dir, `${id}.jsonl`))) {
+        for (const line of readFileSync(join(dir, `${id}.jsonl`), "utf8").split("\n")) {
+          if (line) add(b, JSON.parse(line));
+        }
+      }
+      boxes.set(id, b);
+    }
+    if (b && keepDays > 0 && now() > b.last + keepDays * 864e5) {
+      drop(id);
+      return undefined;
+    }
+    return b;
+  }
+  function add(b, item) {
+    b.items.push(item);
+    b.ids.add(item.id);
+    b.bytes += item.ct.length;
+  }
+
+  function send(res, status, body, extra = {}) {
+    res.writeHead(status, {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Expose-Headers": "Retry-After",
+      ...extra,
+    });
+    res.end(status === 204 ? undefined : JSON.stringify(body));
+  }
+  const fail = (res, status, error, message, extra, headers) =>
+    send(res, status, { v: 1, error, message, ...extra }, headers);
+
+  function limited(req, kind) {
+    let addr = req.socket.remoteAddress ?? "?";
+    if (o.trustProxy)
+      addr = String(req.headers["x-forwarded-for"] ?? addr)
+        .split(",")[0]
+        .trim();
+    const key = `${kind}|${addr}`;
+    const t = now();
+    let h = hits.get(key);
+    if (!h || t - h.start >= 60000) hits.set(key, (h = { start: t, n: 0 }));
+    if (++h.n <= limits[kind]) return 0;
+    return Math.max(1, Math.ceil((h.start + 60000 - t) / 1000));
+  }
+
+  /** Reads the body as text; null when it is over the limit (the rest is drained). */
+  function readBody(req) {
+    return new Promise((resolve) => {
+      const parts = [];
+      let size = 0;
+      let over = Number(req.headers["content-length"] ?? 0) > MAX_BODY;
+      req.on("data", (c) => {
+        size += c.length;
+        if (size > MAX_BODY) over = true;
+        if (!over) parts.push(c);
+      });
+      req.on("end", () => resolve(over ? null : Buffer.concat(parts).toString("utf8")));
+      req.on("error", () => resolve(null));
+    });
+  }
+  const json = (text) => {
+    try {
+      const v = JSON.parse(text);
+      return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+
+  async function handle(req, res) {
+    const url = new URL(req.url ?? "/", "http://x");
+    const path = url.pathname.replace(/\/+$/, "");
+    const method = req.method ?? "GET";
+    if (method === "OPTIONS") {
+      return send(res, 204, null, {
+        "Access-Control-Allow-Methods": "GET, POST, DELETE",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        "Access-Control-Max-Age": "86400",
+        "Access-Control-Allow-Private-Network": "true",
+      });
+    }
+    const mm = /^(.*)\/m\/([A-Za-z0-9_-]{22,64})(\/ops)?$/.exec(path);
+    const isCreate = /\/m$/.test(path) && !mm;
+    if (!mm && !isCreate) return fail(res, 404, "not-found", "No such endpoint.");
+    const ops = Boolean(mm?.[3]);
+    if (isCreate ? method !== "POST" : ops ? method !== "GET" && method !== "POST" : method !== "DELETE") {
+      return fail(res, 405, "method", "Method not allowed here.", {}, { Allow: "GET, POST, DELETE" });
+    }
+    if (method !== "DELETE") {
+      const wait = limited(req, method === "POST" ? "POST" : "GET");
+      if (wait) {
+        return fail(
+          res,
+          429,
+          "rate",
+          "Too many requests.",
+          { retryAfter: wait },
+          { "Retry-After": String(wait) },
+        );
+      }
+    }
+    const bearer = (/^Bearer (.+)$/.exec(req.headers.authorization ?? "") ?? [])[1] ?? "";
+
+    if (isCreate) {
+      const body = await readBody(req);
+      if (body === null) return fail(res, 413, "too-large", "Body too large.");
+      if (o.createToken && !same(bearer, o.createToken))
+        return fail(res, 403, "token", "Create token wrong or missing.");
+      const id = b64u(randomBytes(16));
+      const stop = b64u(randomBytes(32));
+      const token = o.writeTokens ? b64u(randomBytes(18)) : null;
+      const b = {
+        id,
+        created: now(),
+        last: now(),
+        stop: sha(stop).toString("hex"),
+        token: token ? sha(token).toString("hex") : null,
+        items: [],
+        ids: new Set(),
+        bytes: 0,
+      };
+      boxes.set(id, b);
+      if (dir) {
+        // What is written is the mailbox's own record, not the batches (they go to the .jsonl file).
+        const meta = Object.fromEntries(
+          Object.entries(b).filter(([k]) => !["items", "ids", "bytes"].includes(k)),
+        );
+        writeFileSync(join(dir, `${id}.json`), JSON.stringify(meta));
+      }
+      return send(res, 201, {
+        v: 1,
+        mailbox: id,
+        stop,
+        token,
+        expires: expiry(b),
+        keep: keepDays > 0 ? "last-write" : null,
+        limits: { body: MAX_BODY, mailbox: maxBytes },
+      });
+    }
+
+    const b = box(mm[2]);
+    if (method === "DELETE") {
+      if (!b) return fail(res, 404, "gone", "No such mailbox.");
+      if (!bearer || sha(bearer).toString("hex") !== b.stop)
+        return fail(res, 403, "token", "Stop key wrong or missing.");
+      drop(b.id);
+      return send(res, 204, null);
+    }
+    if (method === "GET") {
+      if (!b) return fail(res, 404, "gone", "No such mailbox.");
+      const since = url.searchParams.get("since") ?? "";
+      if (since !== "" && !/^\d{1,15}$/.test(since)) return fail(res, 409, "cursor", "Unknown cursor.");
+      const from = since === "" ? 0 : Number(since);
+      if (from > b.items.length) return fail(res, 409, "cursor", "Unknown cursor.");
+      let to = from;
+      let size = 0;
+      while (to < b.items.length && to - from < pageBatches) {
+        size += b.items[to].ct.length;
+        if (size > pageBytes && to > from) break;
+        to++;
+      }
+      return send(res, 200, {
+        v: 1,
+        batches: b.items.slice(from, to),
+        next: String(to),
+        more: to < b.items.length,
+        expires: expiry(b),
+      });
+    }
+    // POST <mailbox>/ops
+    if (!b) {
+      await readBody(req);
+      return fail(res, 404, "gone", "No such mailbox.");
+    }
+    const text = await readBody(req);
+    if (text === null) return fail(res, 413, "too-large", "Body over 512 KiB.", {}, { Connection: "close" });
+    const m = json(text);
+    if (!m) return fail(res, 400, "bad-request", "Body is not a JSON object.");
+    if (b.token && !(typeof m.token === "string" && sha(m.token).toString("hex") === b.token)) {
+      return fail(res, 403, "token", "Write token wrong or missing.");
+    }
+    if (typeof m.ct !== "string" || !CT.test(m.ct)) return fail(res, 400, "bad-request", "Bad ct.");
+    if (m.id !== b64u(sha(m.ct)).slice(0, 22)) return fail(res, 400, "bad-request", "id does not match ct.");
+    if (b.ids.has(m.id)) return send(res, 200, { v: 1 });
+    if (b.bytes + m.ct.length > maxBytes || b.items.length >= maxBatches) {
+      return fail(res, 507, "full", "Mailbox is full.");
+    }
+    const item = { id: m.id, ct: m.ct };
+    if (dir) appendFileSync(join(dir, `${b.id}.jsonl`), JSON.stringify(item) + "\n");
+    add(b, item);
+    b.last = now();
+    return send(res, 201, { v: 1 });
+  }
+
+  const server = createServer((req, res) => {
+    handle(req, res).catch(() => {
+      if (!res.headersSent) fail(res, 500, "internal", "Server error.");
+      else res.end();
+    });
+  });
+  return {
+    server,
+    listen: (port, host) =>
+      new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => resolve({ port: /** @type {any} */ (server.address()).port }));
+      }),
+    close: () =>
+      new Promise((resolve) => {
+        server.close(() => resolve());
+        server.closeAllConnections();
+      }),
+  };
+}