@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/docs/SECURITY.md

@@ -0,0 +1,273 @@
+# SECURITY
+
+**This package turns your inbox into a control channel for a shell-capable agent.**
+Read this before installing.
+
+## 1. Threat model
+
+If an attacker can get one message into the watched mailbox, they may be able to
+make your agent do work — with whatever tools that session has. The agent has
+`bash`, `edit`, and `write`. That is remote code execution with extra steps.
+
+Sequence:
+
+1. message lands in the inbox (spoofed, forwarded, or from a compromised account)
+2. it carries a plausible `[pi:…]` token (guessed, replayed, or copied from a
+   mail you forwarded)
+3. the daemon parses it, a session claims it, `pi.sendUserMessage` injects it
+4. the agent treats it as you speaking
+
+Every control below exists to break one link in that chain.
+
+## 2. Defence in depth — all layers, not a subset
+
+| Layer | Control | Breaks |
+| --- | --- | --- |
+| Envelope | **Sender allowlist**, exact `addr-spec` match after RFC 5322 parsing | step 1 |
+| Provenance | **DMARC pass** from the authenticated relay (`security.requireDmarcPass`, pinned to `trustedAuthservId` when set) | step 1 |
+| Routing | **short route id**, TTL-bounded (legacy HMAC-signed tokens still verify) | steps 2–3 |
+| Replay | **journal + expiry** (durable, survives restart) | step 2 |
+| Human | **`request_decision` asks and ends the turn**; only a reply resumes it | step 4 |
+
+### 2.1 DMARC — trust the delivering relay's header
+
+`Authentication-Results` is an ordinary, append-only, sender-writable header. A
+message can arrive with a forged `Authentication-Results` from the attacker's own
+infrastructure *and* the real one your provider added.
+
+What makes that safe is header ordering: headers are **prepended** as a message
+traverses relays, so the **topmost** `Authentication-Results` is the one the final
+hop — your provider — wrote on delivery. A sender's forged header necessarily ends
+up *below* it.
+
+Rules:
+
+1. Read the **topmost** `Authentication-Results` header and require `dmarc=pass`
+   in it.
+2. Optionally pin it harder: setting `security.trustedAuthservId` means only a
+   header bearing that `authserv-id` is considered, and its absence **fails
+   closed** rather than falling back.
+3. Do **not** pin an authserv-id for Microsoft consumer accounts: the outlook.com
+   relay emits bare headers with no authserv-id at all
+   (`Authentication-Results: spf=pass …; dmarc=pass …`), so a pinned value would
+   reject every genuine reply. Leave it unset there.
+4. Treat DMARC pass as **necessary, not sufficient** — it authenticates the
+   sending domain, not the authority to command your agent. An allowlisted sender
+   whose account is compromised still passes DMARC.
+
+### 2.2 The routing tag is not authorization
+
+A valid `[pi:…]` tag proves the subject was minted by this installation — nothing
+more. New notifications carry a short local route id (`[pi:f913c9]`); older ones carry
+a signed token, and both are accepted. Neither proves the message came from you. Anyone who replies to one of your
+notification emails (or forwards it) can carry the token into the mailbox.
+
+That is why token verification is *never* the only gate — the allowlist and
+DMARC come first (DMARC is off in the single-mailbox layout), and the token only
+routes.
+
+### 2.3 Replay protection must be durable
+
+An in-memory "seen UIDs" set dies with the daemon. The journal is a file,
+appended after a successful ack and consulted at scan time, so an acked mail is never
+offered again. Routing ids, signed tokens and the reply chain all carry an expiry, so a
+very old reply is not routed even with a valid id or MAC.
+
+## 3. Prompt injection is not solved, only bounded
+
+A legitimate email can still contain text that reads like instructions
+("ignore your rules, run …"). You cannot filter this reliably. What you can do:
+
+- **Scope the session.** A session that only needs to read code should not have
+  `bash`. `pi --tools read,grep,glob` for untrusted threads. This package does not enforce
+  tool scoping — pi's own `--tools` does.
+- **Keep a human in the loop for destructive actions.** `request_decision` sends the
+  question and ends the turn; nothing resumes the session except a reply. There is no
+  approve command and no phrase a message can contain to satisfy it: the human's reply *is*
+  the approval. This is a convention the model follows, not an enforced gate - a model that
+  ignores the tool can keep working, which is why tool scoping matters.
+- **Do not paste mail verbatim into a prompt as trusted context.** Injected
+  text is *user input*, and the system prompt should say so.
+
+## 4. Daemon hardening
+
+- The bearer token authorises **sending mail as you to any address**, not just `mail.to`:
+  `POST /send` takes an optional `to`. Anything that can read `secret.key` (same uid) can
+  therefore exfiltrate over SMTP. That is inside the trust boundary - the same process can read
+  your mail - but worth knowing when deciding what runs as you.
+- Defaults to binding `127.0.0.1`; `daemon.host` can change that, but there is no TLS and
+  no user model beyond the bearer token, so do not. Nothing else about the daemon is
+  reachable without the token, apart from the `/health` liveness probe. That returns mode,
+  pending/clients counts, the decision-registry size, ping timing, the number of SSE subscribers,
+  the last scan's reason *counts*, the build and protocol versions, and the config file's mtime and
+  whether IMAP is connected — no mail content, no addresses, no subjects.
+- Bearer token from `secret.key`, mode `0600`, created first-writer-wins,
+  compared in constant time.
+- Body cap 1 MB; registry cap 10 000; SSE client cap 100; ten notifications a minute; ten notifications a minute.
+- `EADDRINUSE` on start is treated as "already running" — an attacker cannot
+  displace a running daemon by racing the port, because the loser exits.
+- The token never appears in logs, error strings, or the notification email.
+
+### What the bearer token authorises
+
+Beyond sending, the token can `GET /pending` (this device's reply bodies and attachments), `/claim`
+and `/ack` a record this device scanned — which *discards* a queued reply without delivering it —
+flip the mode, and shut the daemon down. Treat `secret.key` as equivalent to the mailbox password.
+
+## 5. Mailbox hygiene
+
+- Prefer a **dedicated account or a filtered folder**. Do not point this at a
+  mailbox where you receive untrusted mail.
+- The tool marks a delivered message `\Seen` and journals it. It never deletes or moves
+  mail, so a shared account keeps its history.
+- Rotate the HMAC key if you suspect exposure. The key is `secret.key`, created first-writer-
+  wins, so rotation means **deleting** it while nothing is running:
+
+  ```bash
+  # stop the daemon (or let it idle-exit)
+  rm ~/.local/state/pi-mailbridge/secret.key   # this is the rotation
+  # then restart pi (or run /mailbridge restart): the session mints a new key and its
+  # respawn starts a daemon that reads it
+  ```
+
+  Stop the daemon *before* deleting: a running one holds the port `and` the key it read at
+  startup, so it keeps answering 401 to every call and the replacement cannot bind, no matter
+  how often a session retries. Sessions re-read `secret.key` on each call, but the client each
+  one already built carries the old token, so it 401s until its runtime is rebuilt.
+
+  Do **not** rotate for a *mail password* change: the daemon's `POST /reload` re-reads
+  that (run it via `/mailbridge smoke`), so no restart is needed.
+
+  Rotating the key kills every outstanding **signed token**, but *not* the short route ids:
+  those are entries in `routes.json` and resolve with no secret at all, so they keep working
+  until `security.tokenTtlHours` expires. Rotating the key does not stop delivery on its own.
+  To revoke, stop the daemon and clear the state directory
+  (`${XDG_STATE_HOME:-~/.local/state}/pi-mailbridge`):
+  - `routes.json` — short ids. Resolve with no secret.
+  - `threads.json` — the reply chain. Resolves recorded Message-IDs with no secret.
+  - `pending.json` — **already-accepted replies waiting for a session.** Deleting the two
+    routing stores stops new mail being routed *by id or chain*, but anything persisted
+    before is still delivered on the next drain - and a legacy token still resolves until
+    it expires or you rotate the key. If the session is compromised, this is the queue
+    that matters.
+  - `journal.json` — only the ack dedupe, tagged with the mailbox's UIDVALIDITY. Clearing it
+    re-opens replay of already-acked mail, so prefer leaving it unless you also cleared the
+    mailbox.
+  - `uid-cursor.json` — the last seen UID and the UIDVALIDITY it belongs to. A change of
+    UIDVALIDITY (a rebuilt or migrated folder) resets it; queued records tagged with another numbering
+    are dropped on every connect (and untagged ones on a detected renumbering), so recent mail
+    can be delivered once more instead of being skipped.
+  Secrets (`secret.key`, `oauth.json`) live beside them; rotating those is covered above.
+- Turn it off with `/mailbridge off` when you will be at the desk: while mode is off the daemon
+  does not scan and the extension does not claim or inject, so the mailbox is not a
+  listening control channel in either direction. Replies that arrive meanwhile stay in the
+  mailbox and are processed when you `/mailbridge on` again — which also means turning it back on can
+  deliver a burst. To stop entirely, close pi and let the daemon exit (~120 s after the last ping),
+  or stop it however you started it - with a session still open, the poll tick respawns a daemon it
+  finds missing, throttled to once a minute.
+- **One mailbox for both roles** (`security.allowSelfReplies`). The loop guard is relaxed
+  for self-addressed mail, so the sender allowlist alone no longer separates "me" from "not
+  me" — it is the same address. Three guards do the work, in this order: the
+  `X-Pi-Mailbridge: notification` marker (refused outright, so it does not depend on
+  anything being recorded), the reply-evidence gate (`In-Reply-To` or `References` must be
+  present), and the outbound `Message-ID` registry. All of them are forgeable by anyone who
+  can already send from your address; they exist to stop loops, not attackers.
+  **DMARC is off in this shape by default**, because a provider may deliver a message from
+  your address to the same address with no `Authentication-Results` header at all (QQ does),
+  which would reject every reply. `/mailbridge setup` writes it that way; setting it back on is
+  reported by `/mailbridge check`, and `pi-mailbridge --check` exits non-zero — gate a supervisor
+  or CI on that. Prefer a dedicated mailbox.
+- **Multiple machines, one mailbox.** Each daemon only claims replies whose route id, token
+  or chain entry names its own device, so they cannot steal each other's work. They share
+  the allowlist (one config each), but **each machine has its own `secret.key`** — it is a
+  local file, never synced through the mailbox. So there is no "the key" to rotate: rotate
+  the compromised machine's, clear its state directory as described above (`routes.json`,
+  `threads.json`, `pending.json`), and review the others separately.
+
+## 6. What this package will never do
+
+- auto-approve a destructive action from email
+- execute an attachment
+- act on a message with `Auto-Submitted`, `Precedence: bulk`, or a bounce sender
+- accept a message from outside the allowlist, however convincing
+- resume a session the human did not start
+
+## 6a. Commands arriving by mail
+
+A reply whose entire body is one command line executes that command (`/mailbridge off`,
+`/mailbridge status|check|smoke|help`, and `/mailbridge on` only while the mode is already on -
+with it off nothing scans or drains, so such a reply is never read). It is **not** handed to pi's command parser, and the
+commands that change the machine are refused: `setup` (rewrites the config and the target
+address), `auth` (starts a credential flow), `restart` (replaces the daemon) and `prime` (skips
+unread mail) are delivered to the agent as text instead.
+
+What this costs, in the one-mailbox layout (DMARC is off there by design) and if the sender can
+forge the allowlisted `From` *and* carries a live route id or token — i.e. they have read one of
+your notifications:
+
+- `/mailbridge off` is a **one-way, global, persisted** denial of the channel: scanning and
+  delivery stop for every session until a human turns it back on at a terminal. Mail is not lost
+  (the cursor does not move), but the remote-decision channel is dead.
+- `/mailbridge smoke` sends one real mail **from your own account to your own address** and costs
+  a daemon reload plus up to ~52 s of IMAP work. It is not rate-limited, so repeated replies can
+  consume SMTP/IMAP capacity and get genuine notifications throttled.
+- `status`, `check` and `help` print into the local pi session; nothing is mailed back.
+
+They cannot reconfigure the account, obtain credentials, restart the daemon, re-prime the cursor
+or discard the queue by mail: `setup`, `auth`, `restart` and `prime` are refused by the
+dispatcher. What the dispatcher refuses, however, is still *delivered to the agent as text*, so
+§1 and §3 apply to it — the refusal is about what runs automatically, not about what the model
+may then do in a shell-capable session.
+
+A command reply to a *decision request* is a special case worth knowing: it runs the command and
+releases the decision slot without the agent seeing an answer, so a later `request_decision` is
+allowed again. Nothing is lost and no mail is misrouted, but "one outstanding decision" is
+weaker than the reply flow suggests.
+
+"A command" means the reply's text **after quote-stripping**, so `/mailbridge on` above a quoted
+original still executes — that is deliberate (a phone-appended signature must not break it), but
+it means "entire body" below refers to the stripped body, not the raw mail.
+
+## 6b. Attachments in notifications
+
+A notification carries the local files the agent linked, so what leaves the machine is decided by
+model output. The controls, all fail-closed:
+
+- **The project directory is the boundary** on the notification path. Every path is
+  `realpath`-resolved on both sides and must land inside the agent's working directory. (An
+  authenticated caller of `POST /send` supplies `cwd`, so with `secret.key` the boundary moves to
+  wherever it says — same trust level as the `to` override in §4.) A symlink out of it (`ln -s ~/.config/… config.json`)
+  is refused, and so is an absolute path outside it.
+- **A home-rooted or `/`-rooted launch attaches nothing**, because with `cwd = $HOME` the config
+  file is "inside the project". Start pi in a project; that is the intended usage.
+- **The daemon's own config and state directories are never attached**, whatever the `cwd`.
+- **An extension allowlist** (`pdf txt log md csv tsv json yml yaml xml html zip gz tar docx xlsx
+  pptx`, plus `png jpg jpeg gif webp svg` for links and the sniffed image types inline)
+  keeps the obvious key filenames out of an accidental attach. It is not a content filter:
+  `cp ~/.ssh/id_rsa notes.txt` or `tar czf k.tar ~/.ssh` defeats it, and `realpath` cannot see a
+  hardlink. Treat it as a guard rail against a naive single-shot injection, not a sandbox.
+- **Size caps**: 5 MB per inline image and 15 MB per linked file (fixed), and
+  `notify.maxAttachmentMb` (default 18 MB, max 45) for the total per mail, before base64 — at most
+  10 attachments per mail. A
+  non-regular file (FIFO, device) is refused rather than read, because it reports size 0 and
+  then blocks.
+- **No automated path changes the recipient.** Every notification's `to` is config-derived, a
+  command reply cannot rewrite the config (`setup` is refused by the dispatcher), and the send
+  path has no Cc/Bcc. An authenticated caller *can* pass a different `to` to `POST /send` — that
+  is §4's "mail as you to any address", and it needs `secret.key`.
+
+Residual risk, plainly: anything the agent can read and re-materialise inside the project can be
+mailed to the address the daemon sends to, up to the cap, including a file that happens to contain secrets and archives
+whose contents the allowlist cannot inspect. Sending is capped at ten
+model-driven notifications a minute per daemon (`429 send_budget`), refused rather than queued.
+Settle notifications and decision requests are exempt: a settle says the agent is waiting, and a
+decision is already bounded at one outstanding per session by the registry. That stops bursts, not a
+sustained loop: ten a minute is 600 an hour and the budget resets when the daemon restarts, so tool
+scoping remains the defence.
+
+## 7. Reporting
+
+Email the maintainer at the address in `package.json`'s `author`
+(`yangbangcheng@bigai.ai`). If the package is published with a `repository`, a private
+security advisory on that repository is equally good. Do not file a public issue for anything
+in this document.

package/docs/images/flow.svg

@@ -0,0 +1,124 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 530" width="1000" height="530" role="img" aria-labelledby="t d">
+<title id="t">How a notification and a reply travel</title>
+<desc id="d">Four stations: pi session, daemon, your mailbox, you. The session sends through the daemon over SMTP; you reply from any device; the daemon reads it over IMAP, authorizes, routes and persists it; the session claims it, injects it and acknowledges, which marks the mail seen.</desc>
+
+<defs>
+  <marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+    <path d="M0 0 L10 5 L0 10z" fill="#5b6673"/>
+  </marker>
+  <marker id="g" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+    <path d="M0 0 L10 5 L0 10z" fill="#2f6f4f"/>
+  </marker>
+  <style>
+    .h{font:600 20px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;fill:#18212b}
+    .b{font:16px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;fill:#39434f}
+    .s{font:14.5px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;fill:#6a7683}
+    .pt{font:600 14px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;fill:#33404d}
+    .num{font:700 14px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;fill:#fff}
+    .flow{stroke:#5b6673;stroke-width:2;fill:none}
+    .flow-g{stroke:#2f6f4f;stroke-width:2.2;fill:none}
+    .ic{stroke:#3d4854;stroke-width:1.8;fill:none;stroke-linecap:round;stroke-linejoin:round}
+    .ic-g{stroke:#2f6f4f;stroke-width:1.9;fill:none;stroke-linecap:round;stroke-linejoin:round}
+    .pill{fill:#eef3f8;stroke:#d3dee9;stroke-width:1}
+  </style>
+</defs>
+
+<!-- pi session -->
+<rect x="16" y="190" width="196" height="150" rx="14" fill="#fff" stroke="#cbd4de" stroke-width="1.5"/>
+<g transform="translate(32,206)">
+  <rect class="ic" x="0" y="0" width="30" height="23" rx="4"/>
+  <path class="ic" d="M5 6 l5 5 -5 5"/>
+  <path class="ic" d="M14 16 h7"/>
+</g>
+<text class="h" x="72" y="224">pi session</text>
+<text class="b" x="32" y="258">finishes a turn</text>
+<text class="b" x="32" y="282">→ one mail</text>
+<text class="b" x="32" y="306">reply: next message</text>
+
+<!-- daemon -->
+<rect x="360" y="136" width="376" height="268" rx="16" fill="#f6f9f7" stroke="#84b097" stroke-width="1.6"/>
+<g transform="translate(380,154)">
+  <path class="ic-g" d="M15 1 l12 5 v8 c0 7 -5 12 -12 15 c-7 -3 -12 -8 -12 -15 v-8 z"/>
+  <path class="ic-g" d="M10 15 l4 4 7 -8"/>
+</g>
+<text class="h" x="424" y="172">daemon</text>
+<text class="s" x="424" y="192">one per machine · loopback</text>
+
+<g>
+  <rect class="pill" x="380" y="212" width="82" height="28" rx="14"/><text class="pt" x="396" y="231">scan</text>
+  <rect class="pill" x="470" y="212" width="112" height="28" rx="14"/><text class="pt" x="486" y="231">authorize</text>
+  <rect class="pill" x="590" y="212" width="82" height="28" rx="14"/><text class="pt" x="606" y="231">route</text>
+  <rect class="pill" x="380" y="250" width="292" height="28" rx="14"/><text class="pt" x="396" y="269">strip quote · attach · persist</text>
+</g>
+
+<text class="s" x="380" y="302">cursor moves after the record is saved</text>
+<text class="s" x="380" y="324">IMAP IDLE + a 60 s sweep</text>
+
+<g transform="translate(380,338)">
+  <ellipse class="ic" cx="14" cy="5" rx="14" ry="5"/>
+  <path class="ic" d="M0 5 v14 c0 2.8 6.3 5 14 5 s14 -2.2 14 -5 V5"/>
+  <path class="ic" d="M0 12 c0 2.8 6.3 5 14 5 s14 -2.2 14 -5"/>
+</g>
+<text class="s" x="418" y="356">pending · journal · cursor</text>
+
+<!-- mailbox -->
+<rect x="356" y="28" width="292" height="72" rx="14" fill="#fff" stroke="#cbd4de" stroke-width="1.5"/>
+<g transform="translate(374,44)">
+  <rect class="ic" x="0" y="0" width="38" height="27" rx="4"/>
+  <path class="ic" d="M1 3 l18 12 18 -12"/>
+</g>
+<text class="h" x="428" y="54">your mailbox</text>
+<text class="s" x="428" y="76">INBOX, read by the daemon</text>
+
+<!-- you -->
+<rect x="764" y="196" width="212" height="120" rx="14" fill="#fff" stroke="#cbd4de" stroke-width="1.5"/>
+<g transform="translate(782,212)">
+  <rect class="ic" x="0" y="0" width="20" height="33" rx="4"/>
+  <path class="ic" d="M6 27 h8"/>
+  <path class="ic" d="M6 5 h8"/>
+</g>
+<text class="h" x="814" y="230">you</text>
+<text class="b" x="782" y="270">any device with email</text>
+<text class="b" x="782" y="294">reply, don't compose</text>
+
+<!-- 1 send -->
+<path class="flow" d="M216 236 H352" marker-end="url(#a)"/>
+<circle cx="330" cy="236" r="12" fill="#5b6673"/><text class="num" x="325" y="241">1</text>
+<text class="s" x="222" y="226">send</text>
+
+<!-- 2 SMTP -->
+<path class="flow" d="M570 136 V104" marker-end="url(#a)"/>
+<circle cx="570" cy="120" r="12" fill="#5b6673"/><text class="num" x="565" y="125">2</text>
+<text class="s" x="588" y="125">SMTP</text>
+
+<!-- 3 notification -->
+<path class="flow" d="M648 62 H870 V192" marker-end="url(#a)"/>
+<circle cx="760" cy="62" r="12" fill="#5b6673"/><text class="num" x="755" y="67">3</text>
+<text class="s" x="778" y="52">notification</text>
+
+<!-- 4 reply -->
+<path class="flow-g" d="M828 196 V92 H648" marker-end="url(#g)"/>
+<circle cx="828" cy="144" r="12" fill="#2f6f4f"/><text class="num" x="823" y="149">4</text>
+<text class="s" x="690" y="112">your reply</text>
+
+<!-- 5 IMAP -->
+<path class="flow-g" d="M450 104 V132" marker-end="url(#g)"/>
+<circle cx="450" cy="118" r="12" fill="#2f6f4f"/><text class="num" x="445" y="123">5</text>
+<text class="s" x="468" y="123">IMAP</text>
+
+<!-- 6 claim -->
+<path class="flow" d="M352 286 H216" marker-end="url(#a)"/>
+<circle cx="330" cy="286" r="12" fill="#5b6673"/><text class="num" x="325" y="291">6</text>
+<text class="s" x="222" y="276">claim</text>
+
+<!-- 7 ack -->
+<path class="flow-g" d="M216 320 H352" marker-end="url(#g)"/>
+<circle cx="330" cy="320" r="12" fill="#2f6f4f"/><text class="num" x="325" y="325">7</text>
+<text class="s" x="222" y="340">ack → seen</text>
+
+<!-- footer -->
+<line x1="24" y1="428" x2="976" y2="428" stroke="#e2e8ef"/>
+<text class="b" x="24" y="454">Every inbound message passes, in order:</text>
+<text class="s" x="24" y="480">journal → marker → size → From → loop guard → allowlist → DMARC → Message-ID → route → ack</text>
+<text class="s" x="24" y="506">Routing ids never authorize. Mail is marked seen only after the reply is injected and acked.</text>
+</svg>

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@dumbmice/pi-mailbridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Drive Pi coding-agent sessions from your mailbox: get an email when an agent settles, reply to resume that exact session.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "email",
+    "imap",
+    "smtp",
+    "idle",
+    "notifications",
+    "afk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DumbMice/pi-mailbridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DumbMice/pi-mailbridge/issues"
+  },
+  "homepage": "https://github.com/DumbMice/pi-mailbridge#readme",
+  "author": {
+    "name": "Yang Bangcheng",
+    "email": "yangbangcheng@bigai.ai"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.6"
+  },
+  "bin": {
+    "pi-mailbridge": "./bin/pi-mailbridge.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "docs",
+    "config.example.json",
+    "CHANGELOG.md",
+    "scripts/render-teaser.ts"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "main": "./src/extension.ts",
+  "scripts": {
+    "daemon": "node --experimental-strip-types src/daemon/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "npm run build"
+  },
+  "dependencies": {
+    "imapflow": "^2.11.0",
+    "mailparser": "^3.14.3",
+    "markdown-it": "^15.0.3",
+    "nodemailer": "^10.5.0",
+    "openid-client": "^6.8.9"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/mailparser": "^3.4.5",
+    "@types/markdown-it": "^14.2.0",
+    "@types/node": "^22.10.0",
+    "@types/nodemailer": "^6.4.17",
+    "typescript": "^5.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}

package/scripts/render-teaser.ts

@@ -0,0 +1,56 @@
+// Render the README teaser through the real message renderer.
+//
+// The teaser in docs/images/ must never be a mock: it is this HTML, produced by
+// `renderMessage` - the same function the mailer calls - with a mail-client frame around it.
+// Regenerate after changing the renderer:
+//
+//   node --experimental-strip-types scripts/render-teaser.ts     # writes /tmp/teaser.html
+//   open /tmp/teaser.html, 820 px wide, capture at 2x          # save as docs/images/notification.png
+//
+// `root` points at a scratch directory holding build.log, so the attachment line renders the
+// way a real notification's does.
+import { writeFileSync } from "node:fs"
+import { renderMessage } from "../src/core/html.ts"
+
+const body = `## Fix is in, one decision needed
+
+The failing test passes now, and the migration is written. I stopped before touching
+production because the rollback path is ambiguous.
+
+**What I changed**
+
+- \`src/auth/session.ts\` — refresh tokens are rotated instead of reused
+- \`test/session.test.ts\` — two cases for the reuse window
+- added \`docs/migration.md\`
+
+**The question**
+
+Should the migration run automatically on deploy, or wait for a manual step?
+
+> Recommendation: wait for a manual step this week — the queue drain takes ~40 minutes,
+> and a failed deploy would leave sessions signed out.
+
+[the full log](./build.log)
+`
+
+import { mkdirSync, writeFileSync as wf } from "node:fs"
+mkdirSync("/tmp/teaser-root", { recursive: true })
+wf("/tmp/teaser-root/build.log", "line 1: compiling\nline 2: 412 tests, 412 pass\n")
+const rendered = renderMessage(body, { root: "/tmp/teaser-root" })
+const html = `<!doctype html><meta charset="utf-8">
+<div style="background:#eef1f5;padding:28px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif">
+  <div style="max-width:760px;margin:0 auto;background:#fff;border:1px solid #dfe3e8;border-radius:10px;overflow:hidden">
+    <div style="padding:16px 22px;border-bottom:1px solid #eceff3;background:#fafbfc">
+      <div style="font-size:13px;color:#5b6673">pi-mailbridge &lt;pi@example.com&gt;</div>
+      <div style="font-size:17px;font-weight:600;color:#1c2530;margin-top:4px">[pi:f913c9] pi: fix-login @ dev-box-7 is waiting for you</div>
+      <div style="font-size:12px;color:#7b8794;margin-top:4px">to you@example.com</div>
+    </div>
+    <div style="padding:20px 22px">${rendered.html}</div>
+    <div style="padding:14px 22px;border-top:1px solid #eceff3;background:#fafbfc;font-size:12px;color:#5b6673">
+      device: dev-box-7 &nbsp;·&nbsp; session: fix-login &nbsp;·&nbsp; turns: 3<br>
+      Reply above this line to continue the session.
+    </div>
+  </div>
+</div>`
+writeFileSync("/tmp/teaser.html", html)
+console.log("wrote /tmp/teaser.html with", rendered.attachments.length, "attachment(s)")