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>

src/routes/admin.test.ts

@@ -168,6 +168,27 @@ describe("Admin Routes", () => {
         expect(feedConfig).toBeTruthy();
         expect((feedConfig as any).title).toBe("Test Feed");
         expect((feedConfig as any).description).toBe("Test Description");
+
+        // Two-id model: the feed id is an opaque read id; the inbound address is
+        // a separate noun.noun.NN mailbox, mapped via the inbound: index.
+        const mailboxId = (feedConfig as any).mailbox_id as string;
+        expect(mailboxId).toMatch(/^[a-z]+\.[a-z]+\.\d{2}$/);
+        expect(feedId).toMatch(/^[A-Za-z0-9_-]{22}$/);
+        expect(feedId).not.toBe(mailboxId);
+        expect((feedList?.feeds[0] as any).mailbox_id).toBe(mailboxId);
+        expect(
+          await mockEnv.EMAIL_STORAGE.get(`inbound:${mailboxId}`, "text"),
+        ).toBe(feedId);
+
+        // The dashboard shows the inbound address and the opaque feed URL,
+        // distinctly — and never exposes the address as a readable feed URL.
+        const dash = await request("/admin", {
+          headers: { Cookie: authCookie },
+        });
+        const html = await dash.text();
+        expect(html).toContain(`${mailboxId}@test.getmynews.app`);
+        expect(html).toContain(`/rss/${feedId}`);
+        expect(html).not.toContain(`/rss/${mailboxId}`);
       });
 
       it("should reject feed creation with missing title", async () => {
@@ -732,6 +753,15 @@ describe("Admin Routes", () => {
       it("lists attachments with download links on the email detail page", async () => {
         const authCookie = await loginAndGetCookie();
         const feedId = "detail-feed";
+        await mockEnv.EMAIL_STORAGE.put(
+          `feed:${feedId}:config`,
+          JSON.stringify({
+            title: "Detail Feed",
+            mailbox_id: "detail.feed.10",
+            language: "en",
+            created_at: 1,
+          }),
+        );
         const emailKey = `feed:${feedId}:1`;
         await mockEnv.EMAIL_STORAGE.put(
           emailKey,
@@ -769,6 +799,15 @@ describe("Admin Routes", () => {
       it("renders inline cid images in place and hides them from the attachments list", async () => {
         const authCookie = await loginAndGetCookie();
         const feedId = "detail-feed";
+        await mockEnv.EMAIL_STORAGE.put(
+          `feed:${feedId}:config`,
+          JSON.stringify({
+            title: "Detail Feed",
+            mailbox_id: "detail.feed.10",
+            language: "en",
+            created_at: 1,
+          }),
+        );
         const emailKey = `feed:${feedId}:3`;
         await mockEnv.EMAIL_STORAGE.put(
           emailKey,
@@ -814,6 +853,15 @@ describe("Admin Routes", () => {
       it("does not render an attachments section when the email has none", async () => {
         const authCookie = await loginAndGetCookie();
         const feedId = "detail-feed";
+        await mockEnv.EMAIL_STORAGE.put(
+          `feed:${feedId}:config`,
+          JSON.stringify({
+            title: "Detail Feed",
+            mailbox_id: "detail.feed.10",
+            language: "en",
+            created_at: 1,
+          }),
+        );
         const emailKey = `feed:${feedId}:2`;
         await mockEnv.EMAIL_STORAGE.put(
           emailKey,

src/routes/admin.tsx

@@ -666,7 +666,10 @@ app.get("/", async (c) => {
                   </thead>
                   <tbody id="feed-table-body">
                     {feedsWithConfig.map((feed) => {
-                      const emailAddress = feedEmailAddress(feed.id, env);
+                      const emailAddress = feedEmailAddress(
+                        feed.mailbox_id,
+                        env,
+                      );
                       const rssUrl = feedRssUrl(feed.id, env);
                       const atomUrl = feedAtomUrl(feed.id, env);
                       const titleDisplay = clampText(feed.title, 160);
@@ -823,7 +826,7 @@ app.get("/", async (c) => {
 
             <ul class="feed-list">
               {feedsWithConfig.map((feed) => {
-                const emailAddress = feedEmailAddress(feed.id, env);
+                const emailAddress = feedEmailAddress(feed.mailbox_id, env);
                 const rssUrl = feedRssUrl(feed.id, env);
                 const atomUrl = feedAtomUrl(feed.id, env);
                 const titleDisplay = clampText(feed.title, 140);

src/routes/admin/emails.tsx

@@ -169,7 +169,7 @@ emailsRouter.get("/feeds/:feedId/emails", async (c) => {
     return c.text("Feed not found", 404);
   }
 
-  const emailAddress = feedEmailAddress(feedId, env);
+  const emailAddress = feedEmailAddress(feedConfig.mailbox_id, env);
   const rssUrl = feedRssUrl(feedId, env);
   const atomUrl = feedAtomUrl(feedId, env);
 
@@ -466,6 +466,8 @@ emailsRouter.get("/emails/:emailKey", async (c) => {
   if (!emailData) return c.text("Email not found", 404);
 
   const feedId = repo.feedIdFromEmailKey(emailKey);
+  const feedConfig = await repo.getConfig(FeedId.unchecked(feedId));
+  if (!feedConfig) return c.text("Feed not found", 404);
   // Inline images render in place; only downloadable attachments go in the list.
   const attachments = (emailData.attachments ?? []).filter((a) => !a.inline);
 
@@ -584,7 +586,10 @@ emailsRouter.get("/emails/:emailKey", async (c) => {
                 value={new Date(emailData.receivedAt).toLocaleString()}
               />
               <SenderField from={emailData.from} feedId={feedId} />
-              <CopyField label="To:" value={feedEmailAddress(feedId, env)} />
+              <CopyField
+                label="To:"
+                value={feedEmailAddress(feedConfig.mailbox_id, env)}
+              />
             </div>
           </div>
 

src/routes/admin/feeds.tsx

@@ -121,7 +121,7 @@ feedsRouter.post("/create", async (c) => {
       ? parseInt(lifetimeHoursRaw, 10)
       : undefined;
 
-    const { feedId } = await createFeedRecord(env, {
+    const { feedId, mailboxId } = await createFeedRecord(env, {
       title: parsedData.title,
       description: parsedData.description,
       language: parsedData.language,
@@ -133,7 +133,7 @@ feedsRouter.post("/create", async (c) => {
     if (isJson) {
       return c.json({
         feedId,
-        email: feedEmailAddress(feedId, env),
+        email: feedEmailAddress(mailboxId, env),
         feedUrl: feedRssUrl(feedId, env),
       });
     }

src/routes/api/index.ts

@@ -63,7 +63,7 @@ function toFeed(
     updatedAt: config.updated_at,
     expiresAt: config.expires_at,
     emailCount,
-    emailAddress: feedEmailAddress(id, env),
+    emailAddress: feedEmailAddress(config.mailbox_id, env),
     rssUrl: feedRssUrl(id, env),
     atomUrl: feedAtomUrl(id, env),
   };
@@ -117,7 +117,7 @@ apiApp.openapi(
           title: f.title,
           description: f.description,
           expiresAt: f.expires_at,
-          emailAddress: feedEmailAddress(f.id, env),
+          emailAddress: feedEmailAddress(f.mailbox_id, env),
           rssUrl: feedRssUrl(f.id, env),
           atomUrl: feedAtomUrl(f.id, env),
         })),

src/routes/api/schemas.ts

@@ -14,7 +14,9 @@ export const FeedIdParam = z.object({
     .min(1)
     .openapi({
       param: { name: "feedId", in: "path" },
-      example: "happy-otter-1234",
+      description:
+        "The feed's opaque id (the read id in /rss/:feedId), not the inbound address.",
+      example: "kZ8xQ2pLm4nR7vT1wB9yJc",
     }),
 });
 

src/routes/inbound.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach } from "vitest";
 import { http, HttpResponse } from "msw";
 import worker from "../index";
-import { server, createMockEnv, MockR2 } from "../test/setup";
+import { server, createMockEnv, MockR2, seedInboundIndex } from "../test/setup";
 import type { Env } from "../types";
 import type { ForwardEmailPayload } from "../infrastructure/forwardemail";
 
@@ -64,6 +64,7 @@ describe("POST /api/inbound — IP middleware", () => {
       `feed:${VALID_FEED_ID}:config`,
       JSON.stringify({ allowed_senders: [] }),
     );
+    await seedInboundIndex(env, VALID_FEED_ID);
   });
 
   it("returns 401 when IP is not in the ForwardEmail allowlist", async () => {
@@ -99,9 +100,10 @@ describe("POST /api/inbound — IP middleware", () => {
 describe("POST /api/inbound — handler logic", () => {
   let env: Env;
 
-  beforeEach(() => {
+  beforeEach(async () => {
     stubForwardEmailIps();
     env = createMockEnv() as unknown as Env;
+    await seedInboundIndex(env, VALID_FEED_ID);
   });
 
   it("returns 500 on malformed JSON body", async () => {
@@ -232,9 +234,10 @@ describe("POST /api/inbound — handler logic", () => {
 describe("POST /api/inbound — attachment upload", () => {
   let env: Env;
 
-  beforeEach(() => {
+  beforeEach(async () => {
     stubForwardEmailIps();
     env = createMockEnv({ withR2: true }) as unknown as Env;
+    await seedInboundIndex(env, VALID_FEED_ID);
   });
 
   it("uploads attachments to R2 and records ids in metadata", async () => {

src/routes/rss.test.ts

@@ -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;