Skip to content

feat(rules): blocked senders, filters and an automatic reply (ADR-0008) - #46

Draft
Madraka wants to merge 3 commits into
mainfrom
wip/adr-0008-rules
Draft

Madraka wants to merge 3 commits into
mainfrom
wip/adr-0008-rules

Conversation

@Madraka

@Madraka Madraka commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What and why

A first build of ADR-0008: a mailbox's rules for its incoming mail. Blocked senders, filters, and an automatic reply that leaves through the one sending path of ADR-0016. Refs #29.

Corrected after the audit of the draft (see the comment that answers it). Three commits: mailbox and routes, app, documents. On the builder's machine pnpm check, pnpm test:workerd and pnpm e2e pass at the head; it leaves draft when CI agrees.

Before this leaves draft

  • All three suites green in CI.
  • Each numbered decision of the record is traced to its code, and each deviation is listed here.
  • Every guard of the automatic reply has a test that fails when the guard is removed (who never gets one, how often, the marking headers, never to a list or a bounce, never from Spam).
  • The Turkish messages are read on the screens they appear on.
  • The commit is split and the roadmap, status and feature scope say what is built.

Checklist

  • pnpm check and pnpm test:workerd are green.
  • Original work. Nothing here comes from another mail product: no code, schema, test, text, translation or asset. No dependency under AGPL or GPL.
  • If this touches a trust boundary, it ships a regression test, and I say which one below. (It does: sending mail because of mail from a stranger. The tests are in test/workerd/auto-reply.test.ts and test/workerd/rules.test.ts; not yet reviewed.)
  • If this relies on a Cloudflare fact, the current source and the date I read it are in the change.
  • Commits are conventional and signed off (git commit -s).

🤖 Generated with Claude Code

@Madraka Madraka added this to the Milestone 3: version 0.1 milestone Nov 18, 2026
@Madraka Madraka added enhancement New feature or request security Touches a trust boundary. A vulnerability is never reported in an issue: see SECURITY.md area: app The single-page app under app/ area: mailbox The mailbox object: storage, sending, search labels Nov 18, 2026
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

First run of the browser suite on this branch (it had never run): 88 passed, 2 failed.

  1. test/e2e/mailbox.spec.ts:611 › "settings are in tabs; a person's choices take effect at once and stay, a mailbox's are saved": the compose window opened without the signature the test had just saved (Expected substring: "Kind regards from the pod bay", received an empty text). This branch changes the settings screens, so treat it as a regression of this change until shown otherwise.
  2. test/e2e/remembered.spec.ts:39: "Route is already handled". Not this branch: it is the test's own race, explained and corrected in fix(app): a choice from a formatting menu no longer closes the next menu #48. Rebase on main once fix(app): a choice from a formatting menu no longer closes the next menu #48 is merged.

pnpm check and the Workers-runtime suite passed on both versions of Node.

@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Audit of this draft against ADR-0008 (two independent readings, 2026-11-18)

Nothing was run for this audit: every point is from reading the code of ae07e1d. The 13 decisions are all built; none of what the record leaves undecided was built. What stands between this draft and "ready":

Must be corrected, each with a test that fails without the correction

  1. A reply can go to a blocked address. "Blocked" is decided on the header From; the reply goes to the envelope sender, and nobody asks the block list about that. Envelope a@x.test (blocked) with From: b@y.test lands in the Inbox and a@x.test is answered (shared/rules.ts replyOwed, workers/durableObject/auto-reply.ts consider). Decision 9.
  2. The assistant drafts an answer to mail the rules filed away. workers/arrival.ts wakes the auto-draft for every filed message, whatever its place. With the assistant on, mail from a blocked sender is given to the model and a draft appears. Before this change nothing arrived outside the Inbox.
  3. A waiting reply leaves after the reply was turned off, or after its end date. Whether the reply is on is asked when it is queued and never again when it leaves; a "not now" from the service keeps it waiting for hours.
  4. A member who may only send can take over a waiting automatic reply. The reschedule route gives it a time up to a year ahead and makes that member the person whose right is asked; unsend turns it into an ordinary draft addressed to a stranger. A waiting automatic reply must be refused by both routes.
  5. While the reply is stopped, every sender is recorded as answered. The log row is written before the saver's right is asked at leaving, and stays when the reply fails: everyone who wrote meanwhile gets nothing for seven days after an owner saves again, and each uses one of the reply's own cap slots.
  6. The screen and the reply can disagree. The API accepts textBody and htmlBody together; the reply sends the HTML, the settings screen shows the text. Refuse the pair unless the text is the text of the HTML, or show what is sent.
  7. "Block the sender" can block a whole domain. A From whose address has no @ is stored as a domain block while the dialog says "this address". Offer the block only for a whole address, and let the request say which kind it is.

Decide, then correct or record in the status document

  1. Once in seven days is keyed on the exact address: name+1@, name+2@ each get a reply, up to the reply's caps (10 an hour, 50 a day).
  2. At leaving the saver is asked for mailbox.send, though saving the reply needs mailbox.manage: an owner lowered to sender can no longer change the reply, and it keeps sending on their standing.
  3. The 256 KiB limit of the rules routes is checked after the whole body was read; workers/routes/choices.ts already has a reader that stops.
  4. Answered addresses are pruned only when the next reply is made: turned off, up to 350 strangers' addresses stay.
  5. The default subject is the English "Automatic reply", whatever the mailbox's language.

Tests that are missing

  • The saver's account was recovered after they saved the reply (the code asks; nothing proves it).
  • Only a parsed message is answered.
  • Decision 6 asks for full branch coverage of the rule function. The repository measures no coverage: either measure it for shared/rules.ts, or say in the status document that it is not measured.

Documents

  • docs/roadmap.md row 5 and docs/feature-scope.md say "built 2026-11-18" for a commit titled "wip". They must be true on the day this merges, and docs/status.md must carry what is left open from the list above.
  • docs/cloudflare/ledger.json, entry runtime.durable_objects.id.name: workers/durableObject/rules.ts now reads the object's name inside a method; the entry names only the alarm handler and leaving.ts.
  • docs/engineering-rules.md D6 lists four security modules with a coverage threshold; the rule function is a fifth, and no threshold exists for any.

Housekeeping

Found sound and not repeated here: the reply's target is the envelope sender and one whole address; nothing of the incoming message is reflected; it leaves only through the one sending path and is counted; no pattern or SQL is built from a person's text; a broken rule cannot fail a delivery; the six routes carry the rights the record names; the assistant and MCP cannot read or change rules; rule text reaches the page as text only; logs and audit rows carry no mail content.

Madraka and others added 3 commits November 18, 2026 16:25
…ailbox

ADR-0008, in the mailbox and its routes. A mailbox's filters and blocked
senders run once, where an arrival is filed, by one pure function over a
closed vocabulary; the automatic reply answers a person once in seven days
by RFC 3834 and leaves by the one function that lets mail leave.

With the corrections of the audit of the draft: the envelope sender is
asked of the block list; only mail filed in the Inbox wakes the assistant;
a waiting reply is asked again whether it is on, and needs its saver to
still hold mailbox.manage; a reply that does not leave for a reason of the
mailbox answered nobody; a waiting reply is nobody's to take back or give
a time; text and HTML are taken together only when they agree; a block
can say it means one whole address; the rules routes stop reading at
256 KiB; turning the reply off keeps no stranger's address.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
Two settings tabs, "Filters and blocked senders" and "Automatic reply",
and on a message "Block the sender" and "Filter messages like this" for
an owner of the mailbox. A block is offered only for a whole address and
says so in its request; the automatic reply shows the text of what is
sent.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
The roadmap, the feature scope, the architecture, the status with what
ADR-0008 leaves open and what was decided while building, the ledger
entry for the mailbox's name, rule D6 and the security skill.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Answer to the audit of the draft. Rebased on main (070226b) and split into three commits: 57215e3 (mailbox and routes), 5d3ae71 (app), 065f6b7 (documents). On this machine, at 065f6b7: pnpm check passed, pnpm test:workerd passed (32 files, 781 tests), pnpm e2e passed (90 tests). Every new test was run once with its control taken out and failed.

The seven corrections

  1. A blocked envelope sender. replyOwed also asks the block list about the envelope sender, as an address and as a domain (blocked in ReplyQuestion). Filing still goes by From. Tests: test/unit/auto-reply.test.ts, and auto-reply.test.ts › "an envelope sender that is blocked, whatever From names".
  2. The assistant and mail that was filed away. rules.file answers filed_away for a message that was stored outside the Inbox, or whose sender is blocked. finish in workers/arrival.ts wakes the assistant only for filed. Test: rules.test.ts › "the assistant is told only of mail in the Inbox", with an assistant of the test that counts wakes.
  3. A reply turned off, or past its end, while it waited. leaveOne asks answersNow again for an automatic reply and fails it with the internal reason off. Its row is removed in the next step, so no person sees that reason. Test: › "does not leave when it was turned off, or its end date passed, while it waited".
  4. Taking over a waiting reply. takeBack and giveTime answer not_found (404) for the mailbox's own reply (mailboxOwn in submissions.ts). Test: › "is nobody's to take back or give a time while it waits", tried by a sender and by an owner.
  5. Senders recorded as answered while the reply was stopped. A reply that does not leave for a reason of the mailbox (off, past its end, the saver's right, late, the sender check, the limits) takes back its row in auto_reply_log. A reply the service refused keeps its row, as before. Tested in the "stops when the person who saved it…" test: the person who wrote meanwhile is answered when they write again.
  6. The screen and the reply. parseAutoReply takes textBody and htmlBody together only when the text is the text of the HTML, whitespace aside. When a reply has only HTML, the settings screen shows that HTML's text. Tests: unit, and › "is not saved with a text and an HTML body that say different things".
  7. A block that becomes a domain. The request may carry kind: "address" or kind: "domain". With address, only one whole address is taken. "Block the sender" sends address and is offered only for a whole address. Tests: unit, and rules.test.ts › "is one whole address when the request says so…".

The five points to decide

  1. Once in seven days per exact address. Kept, and recorded in the status document. Folding + would be guessing at the other side's domain; the reply's own caps still bound it.
  2. The right asked when a reply leaves. Changed to mailbox.manage (AUTO_REPLY_RIGHT in workers/auth/standing.ts), at leaving and for stopped on GET …/auto-reply. Test: auto-reply-standing.test.ts › "stops when the person who saved it is no longer an owner, though they may still send".
  3. The 256 KiB limit. The reader that stops at the limit moved to workers/lib/body.ts, and both the rules routes and the choices route use it. Test: test/unit/body.test.ts, where an endless body is cut off at the limit.
  4. Answered addresses kept after the reply is off. Every save prunes entries older than seven days, and turning the reply off empties the table. A reply turned on again is a new absence, so its senders are answered again. Test: › "keeps no stranger's address once it is turned off".
  5. The English default subject. Kept, and recorded in the status document.

The missing tests

  • The saver's account recovered after saving: auto-reply-standing.test.ts › "stops when the account of the person who saved it was recovered since".
  • Only a parsed message is answered: two things hold this, the parsed-only check and the fact that such a message names no recipient. The test fails when both are taken out and not when one is; the test and the status document now say so.
  • Branch coverage of the rule function: not measured, because adding a coverage tool is a dependency change. The status document says so, and D6 now names the rule function as a fifth module.

Documents

The status document records 8, 11 and 12, the guards taken out, and what was not tried in a browser: the block not offered for a sender without an @, and the text shown for a reply with only HTML. Also updated: the ledger entry runtime.durable_objects.id.name (it now names workers/durableObject/rules.ts), D6 in the engineering rules, and B4 and B6 in the security skill. Roadmap row 5 and the feature scope say "built 2026-11-18". That is true only if this merges today; otherwise the date needs changing.

Two things that are new here

The PR stays a draft until CI is green.

Comment thread test/e2e/rules.spec.ts
const { cookie } = JSON.parse(readFileSync(session, "utf8")) as { cookie: string };
const made = await fetch(`${BASE}/api/v1/mailboxes`, {
method: "POST",
headers: { cookie, origin: BASE, "content-type": "application/json" },
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Second audit, at 065f6b7: five corrections, then pass

Two readings again: mine of the seven corrections, and an independent one of the whole change that was not told what the first audit found. Nothing was run for either; CI on this head is green (both pnpm check jobs, pnpm e2e, code scanning).

What holds

All seven corrections are in the code as the answer describes them, and each has the test it names:

  1. replyOwed asks the block list about the envelope sender, with the same folded text the reply is sent to and the seven days are counted for.
  2. rules.file answers filed_away, and finish wakes the assistant only for filed.
  3. leaveOne asks answersNow again for the mailbox's own reply.
  4. takeBack and giveTime answer not_found for it. I followed every writer of a stored header list: a send route overwrites it with its own, a message taken back loses it, so only auto-reply.ts can make a waiting message "automatic".
  5. A reply that does not leave for a reason of the mailbox takes back its row; one the service refused keeps it.
  6. parseAutoReply refuses a text and an HTML body that say different things.
  7. parseSender holds kind, and "Block the sender" is offered only for a whole address.

Points 8 to 12 are decided and recorded as the answer says, AUTO_REPLY_RIGHT is mailbox.manage at leaving and for stopped, and the limited reader is one function used by both routes. The independent reading found the target of the reply, its content, the way out, loops, the six routes' rights, the closed tool methods and the app's rendering sound.

To correct, each with a test that fails without it

A. A person can save HTML they were never shown. AutoReplySettings.tsx sends data.htmlBody back whenever the text on screen is unchanged, and the agreement check of correction 6 compares text only. An owner saves, through the API, an HTML body with a link and a remote image. A second owner opens the settings, sees the words, changes a date and saves: the same HTML is stored again, now on the second owner's standing, and it keeps answering strangers after the first owner is gone. Either the screen never saves back a body it does not show in full, or the server takes only an HTML body with nothing in it beyond what the screen can show. Whichever it is, nobody becomes the saver of markup they did not see.

B. The mailbox can answer itself through a +tag. "Not the mailbox itself" in replyOwed is an exact comparison, while mailboxAddressFor (workers/lib/inbound.ts) delivers name+anything@domain to name@domain. An envelope sender name+a@domain with the mailbox in To is owed a reply, and that reply is routed back into the same Inbox, where it also wakes the assistant. It stops after one turn, because the reply is marked automatic, but each tag is a new sender. Compare the envelope sender after the same step routing applies.

C. A stopped reply does work for every message, without a bound. With correction 5, a reply that fails with right takes back its row, so the reply's own caps never fill while it is stopped. Each arriving message then writes a waiting message, sets the alarm, asks the index several times, fails and removes its rows. Nothing is sent, but the cost is per message from any stranger. Have the first right failure leave a mark that consider reads, so nothing more is queued until the reply is saved again.

D. A waiting reply leaves with the words of an earlier save. A reply can wait for hours behind a "not now" or a full cap. Only on/off and the dates are asked again when it leaves; if the reply was edited, or saved by someone else, the old text leaves on the old saver's standing. requested_at is the set_at it was made under: when the stored object's set_at is no longer that, it does not leave, and its sender is not recorded as answered.

E. endOfRawText lower-cases the whole input on every call. It is called once for each script, style, head and similar element, so the work grows with the square of the input. The rules now reach it on every arrival that has no text part. Lower-case once per call of htmlToText and pass it down. The existing test for "text made to slow a pattern down" covers evaluate only; add one for the scanner.

Tests that are missing

  • The 256 KiB limit at the rules routes: only the helper is tested, so taking bodyWithin out of workers/routes/rules.ts fails nothing.
  • At most one reply for an arrival that is resumed.

To write down in the status document (not defects)

  • Who is never answered is RFC 3834's list and nothing more: an address such as a no-reply or postmaster local part, and Precedence: auto_reply, are answered.
  • The authentication results of the message are not asked before a reply is made.
  • A parsed message with no From, or a group as its From, has no sender for the block list and lands in the Inbox.
  • Filters and blocks need no fresh proof (decision 7), and their audit rows hold counts only.

Not provable by reading

Whether the sending service carries Auto-Submitted on the wire and which envelope sender it puts on the reply. The ledger should say what the current documentation says about custom header fields, or the status document should list it as not yet seen on a real account.

The documents say "built 2026-11-18"; that date holds only if this merges on that day.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: app The single-page app under app/ area: mailbox The mailbox object: storage, sending, search enhancement New feature or request security Touches a trust boundary. A vulnerability is never reported in an issue: see SECURITY.md

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants