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
+17 -26
View File
@@ -1,36 +1,27 @@
import { describe, it, expect } from "vitest";
import { FeedId } from "./feed-id";
describe("FeedId.parse", () => {
it("extracts the feed id from an inbound address", () => {
expect(FeedId.parse("river.castle.42@example.com")?.value).toBe(
"river.castle.42",
);
});
it("preserves the original casing of the local part", () => {
expect(FeedId.parse("River.Castle.42@example.com")?.value).toBe(
"River.Castle.42",
);
});
it("rejects malformed feed ids", () => {
expect(FeedId.parse("user@example.com")).toBeNull();
expect(FeedId.parse("notanemail")).toBeNull();
expect(FeedId.parse("river.castle.4@example.com")).toBeNull();
expect(FeedId.parse("river.castle.123@example.com")).toBeNull();
});
});
describe("FeedId.generate", () => {
it("produces the noun.noun.NN format", () => {
it("produces an opaque base64url token", () => {
for (let i = 0; i < 50; i++) {
expect(FeedId.generate().value).toMatch(/^[a-z]+\.[a-z]+\.\d{2}$/);
expect(FeedId.generate().value).toMatch(/^[A-Za-z0-9_-]{22}$/);
}
});
it("round-trips through parse from an address", () => {
const id = FeedId.generate();
expect(FeedId.parse(`${id.value}@example.com`)?.value).toBe(id.value);
it("is unguessable: 50 ids are all distinct", () => {
const ids = new Set(
Array.from({ length: 50 }, () => FeedId.generate().value),
);
expect(ids.size).toBe(50);
});
it("does not produce the legacy noun.noun.NN format", () => {
expect(FeedId.generate().value).not.toMatch(/^[a-z]+\.[a-z]+\.\d{2}$/);
});
});
describe("FeedId.unchecked", () => {
it("wraps a value without validation", () => {
expect(FeedId.unchecked("anything").value).toBe("anything");
});
});