feat: decouple read FeedId from inbound MailboxId

Separate the two feed identities so the public read URL never reveals the
inbound address and vice-versa:

- FeedId becomes an opaque high-entropy token (read id + KV key); MailboxId
  (noun.noun.NN) owns the inbound address and the untrusted-input boundary
  via MailboxId.parse. They map only through the inbound:<mailbox> secondary
  index, resolved solely at reception.
- inbound index lifecycle is owned by FeedRepository: written by save/saveConfig,
  dropped by removeFromList(Bulk) — symmetric, never mirrored by hand (removes the
  manual delete in feed-service + the cron loop, and a silent empty-catch).
- Feed.mailboxId exposes a MailboxId VO (symmetry with Feed.id); the
  mailbox@domain shape lives on MailboxId.emailAddress(domain).
- Distinguish mailbox_unknown (no feed claims the address) from feed_not_found
  (dangling index) for observability; both forwardable, both 404.
- Drop the redundant EmailParser.extractMailbox pass-through so MailboxId.parse
  is the single parse boundary.

Docs (README/INSTALL/CLAUDE.md/landing) and tests updated; 439 tests green,
tsc clean, build dry-run OK.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Julien Herr
2026-05-24 22:46:37 +02:00
parent f7f10779bc
commit 1a4a479190
43 changed files with 649 additions and 149 deletions
+54
View File
@@ -54,6 +54,60 @@ describe("RSS Feed Route", () => {
});
});
describe("read/write id decoupling", () => {
const OPAQUE_ID = "kZ8xQ2pLm4nR7vT1wB9yJc";
const MAILBOX = "river.castle.42";
const RECEIVED_AT = 1700000002000;
beforeEach(async () => {
const emailKey = `feed:${OPAQUE_ID}:${RECEIVED_AT}`;
await mockEnv.EMAIL_STORAGE.put(
emailKey,
JSON.stringify({
subject: "Private",
from: "Sender <sender@example.com>",
content: "<p>secret body</p>",
receivedAt: RECEIVED_AT,
headers: {},
}),
);
await mockEnv.EMAIL_STORAGE.put(
`feed:${OPAQUE_ID}:metadata`,
JSON.stringify({
emails: [
{ key: emailKey, subject: "Private", receivedAt: RECEIVED_AT },
],
}),
);
await mockEnv.EMAIL_STORAGE.put(
`feed:${OPAQUE_ID}:config`,
JSON.stringify({
title: "Decoupled Feed",
language: "en",
mailbox_id: MAILBOX,
created_at: 1700000000000,
}),
);
// The inbound index points the address at the feed (reception only).
await mockEnv.EMAIL_STORAGE.put(`inbound:${MAILBOX}`, OPAQUE_ID);
});
it("serves the feed by its opaque read id", async () => {
const res = await testApp.request(`/${OPAQUE_ID}`, {}, mockEnv);
expect(res.status).toBe(200);
});
it("returns 404 when read by the inbound mailbox (no coupling)", async () => {
const res = await testApp.request(`/${MAILBOX}`, {}, mockEnv);
expect(res.status).toBe(404);
});
it("never leaks the inbound mailbox in the feed body", async () => {
const res = await testApp.request(`/${OPAQUE_ID}`, {}, mockEnv);
expect(await res.text()).not.toContain(MAILBOX);
});
});
describe("conditional GET (ETag + Last-Modified)", () => {
const FEED_ID = "test-feed-rss-cget";
const EMAIL_RECEIVED_AT = 1700000001000;