feat(unsubscribe): RFC 8058 one-click unsubscribe on feed deletion

Capture each sender's List-Unsubscribe one-click URL during ingestion
(stored per sender in feed metadata, mirroring the iconDomain pattern) and
fire one-click POSTs via ctx.waitUntil when a feed is deleted, so newsletters
stop mailing the now-dead address. Tracked with a new unsubscribes_sent
counter surfaced on the status page and /api/stats.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

src/utils/stats.ts

@@ -8,6 +8,7 @@ const EMPTY_COUNTERS: Counters = {
   feeds_deleted: 0,
   emails_received: 0,
   emails_rejected: 0,
+  unsubscribes_sent: 0,
 };
 
 export async function getCounters(kv: KVNamespace): Promise<Counters> {
@@ -39,6 +40,7 @@ export async function bumpCounters(
     current.feeds_deleted += changes.feeds_deleted ?? 0;
     current.emails_received += changes.emails_received ?? 0;
     current.emails_rejected += changes.emails_rejected ?? 0;
+    current.unsubscribes_sent += changes.unsubscribes_sent ?? 0;
     if (changes.last_email_at) current.last_email_at = changes.last_email_at;
     if (changes.last_feed_created_at)
       current.last_feed_created_at = changes.last_feed_created_at;

src/utils/unsubscribe.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from "vitest";
+import { http, HttpResponse } from "msw";
+import { server, createMockEnv } from "../test/setup";
+import {
+  parseOneClickUnsubscribe,
+  sendOneClickUnsubscribe,
+  sendUnsubscribes,
+} from "./unsubscribe";
+import { getCounters } from "./stats";
+import type { Env } from "../types";
+
+const POST_HEADER = "List-Unsubscribe=One-Click";
+
+describe("parseOneClickUnsubscribe", () => {
+  it("returns the https URL when the one-click Post header is present", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "list-unsubscribe": "<https://news.example.com/u?t=abc>",
+        "list-unsubscribe-post": POST_HEADER,
+      }),
+    ).toBe("https://news.example.com/u?t=abc");
+  });
+
+  it("prefers the https URL when both https and mailto are present", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "list-unsubscribe":
+          "<mailto:[email protected]>, <https://example.com/u/1>",
+        "list-unsubscribe-post": POST_HEADER,
+      }),
+    ).toBe("https://example.com/u/1");
+  });
+
+  it("returns null for a mailto-only header", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "list-unsubscribe": "<mailto:[email protected]>",
+        "list-unsubscribe-post": POST_HEADER,
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null when the Post header is missing", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "list-unsubscribe": "<https://example.com/u/1>",
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null when the Post header has the wrong value", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "list-unsubscribe": "<https://example.com/u/1>",
+        "list-unsubscribe-post": "List-Unsubscribe=Something",
+      }),
+    ).toBeNull();
+  });
+
+  it("matches headers and Post value case-insensitively", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "List-Unsubscribe": "<https://example.com/u/1>",
+        "List-Unsubscribe-Post": "list-unsubscribe=ONE-CLICK",
+      }),
+    ).toBe("https://example.com/u/1");
+  });
+
+  it("ignores plaintext http URLs", () => {
+    expect(
+      parseOneClickUnsubscribe({
+        "list-unsubscribe": "<http://example.com/u/1>",
+        "list-unsubscribe-post": POST_HEADER,
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null when there are no headers", () => {
+    expect(parseOneClickUnsubscribe({})).toBeNull();
+  });
+});
+
+describe("sendOneClickUnsubscribe", () => {
+  it("POSTs the one-click body and returns true on success", async () => {
+    let captured: { method: string; contentType: string; body: string } | null =
+      null;
+    server.use(
+      http.post("https://example.com/u/1", async ({ request }) => {
+        captured = {
+          method: request.method,
+          contentType: request.headers.get("content-type") ?? "",
+          body: await request.text(),
+        };
+        return HttpResponse.text("ok");
+      }),
+    );
+
+    const ok = await sendOneClickUnsubscribe("https://example.com/u/1");
+
+    expect(ok).toBe(true);
+    expect(captured).toEqual({
+      method: "POST",
+      contentType: "application/x-www-form-urlencoded",
+      body: POST_HEADER,
+    });
+  });
+
+  it("returns false on a non-ok response", async () => {
+    server.use(
+      http.post("https://example.com/u/1", () =>
+        HttpResponse.text("nope", { status: 404 }),
+      ),
+    );
+    expect(await sendOneClickUnsubscribe("https://example.com/u/1")).toBe(
+      false,
+    );
+  });
+
+  it("returns false (no throw) on a network error", async () => {
+    server.use(
+      http.post("https://example.com/u/1", () => HttpResponse.error()),
+    );
+    expect(await sendOneClickUnsubscribe("https://example.com/u/1")).toBe(
+      false,
+    );
+  });
+});
+
+describe("sendUnsubscribes", () => {
+  it("de-dupes URLs and bumps unsubscribes_sent by the success count", async () => {
+    const env = createMockEnv() as unknown as Env;
+    let hitsOne = 0;
+    let hitsTwo = 0;
+    server.use(
+      http.post("https://example.com/a", () => {
+        hitsOne += 1;
+        return HttpResponse.text("ok");
+      }),
+      http.post("https://example.com/b", () => {
+        hitsTwo += 1;
+        return HttpResponse.text("ok");
+      }),
+    );
+
+    await sendUnsubscribes(
+      [
+        "https://example.com/a",
+        "https://example.com/a",
+        "https://example.com/b",
+      ],
+      env,
+    );
+
+    expect(hitsOne).toBe(1);
+    expect(hitsTwo).toBe(1);
+    const counters = await getCounters(env.EMAIL_STORAGE);
+    expect(counters.unsubscribes_sent).toBe(2);
+  });
+
+  it("only counts successful requests", async () => {
+    const env = createMockEnv() as unknown as Env;
+    server.use(
+      http.post("https://example.com/ok", () => HttpResponse.text("ok")),
+      http.post("https://example.com/bad", () =>
+        HttpResponse.text("no", { status: 500 }),
+      ),
+    );
+
+    await sendUnsubscribes(
+      ["https://example.com/ok", "https://example.com/bad"],
+      env,
+    );
+
+    const counters = await getCounters(env.EMAIL_STORAGE);
+    expect(counters.unsubscribes_sent).toBe(1);
+  });
+
+  it("does nothing for an empty list", async () => {
+    const env = createMockEnv() as unknown as Env;
+    await sendUnsubscribes([], env);
+    const counters = await getCounters(env.EMAIL_STORAGE);
+    expect(counters.unsubscribes_sent).toBe(0);
+  });
+});

src/utils/unsubscribe.ts

@@ -0,0 +1,83 @@
+import { Env } from "../types";
+import { UNSUBSCRIBE_TIMEOUT_MS } from "../config/constants";
+import { bumpCounters } from "./stats";
+import { logger } from "../lib/logger";
+
+/**
+ * Extract a one-click unsubscribe URL from a stored email's headers per
+ * RFC 8058. Returns the first `https:` URL in `List-Unsubscribe` only when
+ * `List-Unsubscribe-Post: List-Unsubscribe=One-Click` is also present — that
+ * Post header is what authorises an unattended one-click POST. `mailto:` and
+ * plaintext `http:` links are ignored (Workers cannot send SMTP and we never
+ * unsubscribe over plaintext). Header keys are matched case-insensitively;
+ * `EmailData.headers` already lowercases them, but we don't rely on it.
+ */
+export function parseOneClickUnsubscribe(
+  headers: Record<string, string>,
+): string | null {
+  let listUnsubscribe = "";
+  let post = "";
+  for (const [key, value] of Object.entries(headers)) {
+    const k = key.toLowerCase();
+    if (k === "list-unsubscribe") listUnsubscribe = value;
+    else if (k === "list-unsubscribe-post") post = value;
+  }
+
+  if (post.trim().toLowerCase() !== "list-unsubscribe=one-click") return null;
+
+  const matches = listUnsubscribe.match(/<([^>]+)>/g);
+  if (!matches) return null;
+  for (const token of matches) {
+    const url = token.slice(1, -1).trim();
+    if (/^https:\/\//i.test(url)) return url;
+  }
+  return null;
+}
+
+/**
+ * Fire a single RFC 8058 one-click unsubscribe POST. Returns whether the
+ * endpoint accepted it. Never throws: network/timeout errors are logged and
+ * reported as a failure so callers can keep going.
+ */
+export async function sendOneClickUnsubscribe(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      redirect: "follow",
+      signal: AbortSignal.timeout(UNSUBSCRIBE_TIMEOUT_MS),
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "User-Agent": "kill-the-news/1.0",
+      },
+      body: "List-Unsubscribe=One-Click",
+    });
+    return res.ok;
+  } catch (error) {
+    logger.warn("One-click unsubscribe failed", { url, error: String(error) });
+    return false;
+  }
+}
+
+/**
+ * Send one-click unsubscribe requests for a batch of URLs (de-duplicated) and
+ * record the number that succeeded in the `unsubscribes_sent` counter. Never
+ * throws — intended to run in the background via ctx.waitUntil on feed deletion.
+ */
+export async function sendUnsubscribes(
+  urls: string[],
+  env: Env,
+): Promise<void> {
+  const unique = Array.from(new Set(urls.filter(Boolean)));
+  if (unique.length === 0) return;
+
+  const results = await Promise.allSettled(
+    unique.map((url) => sendOneClickUnsubscribe(url)),
+  );
+  const succeeded = results.filter(
+    (r) => r.status === "fulfilled" && r.value,
+  ).length;
+
+  if (succeeded > 0) {
+    await bumpCounters(env.EMAIL_STORAGE, { unsubscribes_sent: succeeded });
+  }
+}