@marktiderman/genesis-chat 0.1.0 → 0.2.0

package/src/__tests__/server-runner.test.ts

@@ -0,0 +1,277 @@
+/** @feat:chat */
+import { describe, expect, it, vi } from "vitest";
+import { createChatRunner, chatRunnerHandler, type ChatEffect, type ChatNotification, type Transcriber } from "../server";
+import { fakeSupabase } from "./server-fakes";
+
+const effect = (id: number, kind: string, payload: Record<string, unknown>, attempts = 1): ChatEffect => ({
+  id,
+  kind,
+  key: `${kind}:${id}`,
+  payload,
+  attempts,
+});
+
+const target = (userId: string, over: Record<string, unknown> = {}) => ({
+  user_id: userId,
+  conversation_id: "c1",
+  title: null,
+  sender_id: "ana",
+  preview: "see you at 6",
+  mentioned: false,
+  unread_total: 3,
+  ...over,
+});
+
+const names: Record<string, string> = { ana: "Ana" };
+
+describe("createChatRunner: push", () => {
+  it("delivers one notification per message with every recipient, titled by the sender in a direct conversation", async () => {
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => [effect(1, "push", { message_id: "m1", conversation_id: "c1" })],
+        push_targets: () => [target("bo"), target("cy", { mentioned: true, unread_total: 7 })],
+      },
+      tables: { conversations: [{ id: "c1", kind: "direct" }] },
+    });
+    const deliver = vi.fn(async (_n: ChatNotification) => {});
+    const runner = createChatRunner({ supabase: sb.client, deliver, resolveName: (id) => names[id] });
+    expect(await runner.run()).toMatchObject({ claimed: 1, done: 1, failed: 0 });
+    expect(deliver).toHaveBeenCalledTimes(1);
+    expect(deliver.mock.calls[0]![0]).toEqual({
+      category: "messages",
+      messageId: "m1",
+      conversationId: "c1",
+      recipients: [
+        { userId: "bo", badge: 3, mentioned: false },
+        { userId: "cy", badge: 7, mentioned: true },
+      ],
+      title: "Ana",
+      body: "see you at 6",
+      senderId: "ana",
+      threadKey: "c1",
+      idempotencyKey: "push:m1",
+      data: { url: "/messages/c1", conversationId: "c1", messageId: "m1", seq: null },
+      mutableContent: false,
+      categoryId: "messages",
+    });
+    // Only the kinds it handles are claimed; the effect is settled as done.
+    expect(sb.rpcCalls[0]).toEqual({ fn: "claim_effects", args: { p_kinds: ["push", "transcribe", "storage.remove", "video.remove"], p_limit: 50 } });
+    expect(sb.rpcCalls.at(-1)).toEqual({ fn: "complete_effect", args: { p_id: 1, p_error: null } });
+  });
+
+  it("titles a group by its title and prefixes the preview with the sender", async () => {
+    const sb = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "push", { message_id: "m1" })], push_targets: () => [target("bo", { title: "Cohort 4" })] },
+      tables: { conversations: [{ id: "c1", kind: "group" }] },
+    });
+    const deliver = vi.fn(async (_n: ChatNotification) => {});
+    await createChatRunner({ supabase: sb.client, deliver, resolveName: (id) => names[id] }).run();
+    expect(deliver.mock.calls[0]![0]).toMatchObject({ title: "Cohort 4", body: "Ana: see you at 6" });
+  });
+
+  it("sets a collapse key only when the app asks, and always carries the message id and seq", async () => {
+    const make = () =>
+      fakeSupabase({
+        rpc: { claim_effects: () => [effect(1, "push", { message_id: "m1" })], push_targets: () => [target("bo")] },
+        tables: { conversations: [{ id: "c1", kind: "group" }], messages: [{ id: "m1", seq: 42 }] },
+      });
+    const plain = vi.fn(async (_n: ChatNotification) => {});
+    await createChatRunner({ supabase: make().client, deliver: plain }).run();
+    const n = plain.mock.calls[0]![0];
+    expect("collapseKey" in n).toBe(false);
+    expect(n.threadKey).toBe("c1");
+    expect(n.data).toMatchObject({ messageId: "m1", seq: 42, conversationId: "c1" });
+
+    const collapsing = vi.fn(async (_n: ChatNotification) => {});
+    await createChatRunner({ supabase: make().client, deliver: collapsing, collapse: true }).run();
+    expect(collapsing.mock.calls[0]![0].collapseKey).toBe("chat:c1");
+  });
+
+  it("asks for a push badge without the kinds the app leaves out of its own", async () => {
+    const sb = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "push", { message_id: "m1" })], push_targets: () => [target("bo", { title: "Cohort 4" })] },
+      tables: { conversations: [{ id: "c1", kind: "group" }] },
+    });
+    await createChatRunner({ supabase: sb.client, deliver: vi.fn(async () => {}), badgeExcludeKinds: ["support"] }).run();
+    expect(sb.rpcCalls.find((c) => c.fn === "push_targets")?.args).toEqual({ p_message_id: "m1", p_badge_exclude_kinds: ["support"] });
+  });
+
+  it("builds an iOS rich push: the sender's name and photo, the group, and the message ids", async () => {
+    const conv = "0a1b2c3d-0000-4000-8000-000000000001";
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => [effect(1, "push", { message_id: "m1" })],
+        push_targets: () => [{ ...target("bo", { title: "Cohort 4" }), conversation_id: conv }],
+      },
+      tables: { conversations: [{ id: conv, kind: "group" }] },
+    });
+    const deliver = vi.fn(async (_n: ChatNotification) => {});
+    await createChatRunner({
+      supabase: sb.client,
+      deliver,
+      resolveName: (id) => names[id],
+      resolveAvatar: () => "https://cdn.example.test/ana.jpg",
+    }).run();
+    const n = deliver.mock.calls[0]![0];
+    expect(n.mutableContent).toBe(true);
+    expect(n.categoryId).toBe("messages");
+    expect(n.data).toMatchObject({ conversationId: conv, messageId: "m1", senderId: "ana", senderName: "Ana", senderAvatar: "https://cdn.example.test/ana.jpg", groupName: "Cohort 4" });
+  });
+
+  it("opens the app's own route when a notification is tapped", async () => {
+    const sb = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "push", { message_id: "m1" })], push_targets: () => [target("bo", { title: "Cohort 4" })] },
+      tables: { conversations: [{ id: "c1", kind: "group" }] },
+    });
+    const deliver = vi.fn(async (_n: ChatNotification) => {});
+    await createChatRunner({ supabase: sb.client, deliver, linkFor: (c, m) => `/inbox?c=${c}&m=${m}` }).run();
+    expect(deliver.mock.calls[0]![0].data.url).toBe("/inbox?c=c1&m=m1");
+  });
+
+  it("settles a message with no targets as done without delivering", async () => {
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "push", { message_id: "m1" })], push_targets: () => [] } });
+    const deliver = vi.fn(async () => {});
+    expect(await createChatRunner({ supabase: sb.client, deliver }).run()).toMatchObject({ claimed: 1, done: 1, failed: 0 });
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
+  it("settles a failed delivery with its error, and keeps working the others", async () => {
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => [effect(1, "push", { message_id: "m1" }), effect(2, "push", { message_id: "m2" }), effect(3, "storage.remove", { bucket: "genesis-chat", path: "c/u/a.jpg" })],
+        push_targets: (a) => [target("bo", { conversation_id: String(a.p_message_id) })],
+      },
+    });
+    const deliver = vi.fn(async (n: ChatNotification) => {
+      if (n.messageId === "m1") throw new Error("push service down");
+    });
+    expect(await createChatRunner({ supabase: sb.client, deliver }).run()).toMatchObject({ claimed: 3, done: 2, failed: 1 });
+    const settled = sb.rpcCalls.filter((c) => c.fn === "complete_effect").map((c) => c.args);
+    expect(settled).toContainEqual({ p_id: 1, p_error: "push service down" });
+    expect(settled).toContainEqual({ p_id: 2, p_error: null });
+    expect(settled).toContainEqual({ p_id: 3, p_error: null });
+  });
+
+  it("caps effects of one kind in flight", async () => {
+    let inFlight = 0;
+    let most = 0;
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => Array.from({ length: 10 }, (_, i) => effect(i, "push", { message_id: `m${i}` })),
+        push_targets: () => [target("bo")],
+      },
+    });
+    const deliver = async () => {
+      most = Math.max(most, ++inFlight);
+      await new Promise((r) => setTimeout(r, 5));
+      inFlight--;
+    };
+    const report = await createChatRunner({ supabase: sb.client, deliver, batch: { concurrency: 3, limit: 10 } }).run();
+    expect(report.done).toBe(10);
+    expect(most).toBe(3);
+  });
+
+  it("claims only the kinds it was given", async () => {
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [] } });
+    await createChatRunner({ supabase: sb.client, deliver: async () => {}, kinds: ["transcribe"] }).run();
+    expect(sb.rpcCalls[0]!.args.p_kinds).toEqual(["transcribe"]);
+  });
+});
+
+describe("createChatRunner: storage.remove and video.remove", () => {
+  it("removes the file, and counts not found as done", async () => {
+    const ok = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "storage.remove", { bucket: "genesis-chat", path: "c/u/a.jpg" })] } });
+    expect(await createChatRunner({ supabase: ok.client, deliver: async () => {} }).run()).toMatchObject({ done: 1 });
+    expect(ok.removed).toEqual([{ bucket: "genesis-chat", paths: ["c/u/a.jpg"] }]);
+
+    const gone = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "storage.remove", { path: "c/u/b.jpg" })] },
+      removeError: { message: "Object not found", statusCode: "404" },
+    });
+    expect(await createChatRunner({ supabase: gone.client, deliver: async () => {} }).run()).toMatchObject({ done: 1, failed: 0 });
+
+    const down = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "storage.remove", { path: "c/u/b.jpg" })] },
+      removeError: { message: "Internal", statusCode: "500" },
+    });
+    expect(await createChatRunner({ supabase: down.client, deliver: async () => {} }).run()).toMatchObject({ done: 0, failed: 1 });
+  });
+
+  it("removes a hosted video through the adapter, and is done without one", async () => {
+    const remove = vi.fn(async () => {});
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "video.remove", { provider: "mux", provider_id: "asset1" })] } });
+    await createChatRunner({ supabase: sb.client, deliver: async () => {}, video: { name: "mux", remove } }).run();
+    expect(remove).toHaveBeenCalledWith("asset1");
+    const none = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "video.remove", { provider: "mux", provider_id: "asset1" })] } });
+    expect(await createChatRunner({ supabase: none.client, deliver: async () => {} }).run()).toMatchObject({ done: 1 });
+  });
+});
+
+describe("createChatRunner: transcribe", () => {
+  const voice = { id: "a1", kind: "voice", provider: "storage", path: "c/u/v.m4a", mime: "audio/mp4", duration_ms: 4200, transcript_status: "pending" };
+
+  it("signs a 10 minute URL, transcribes it and stores the transcript", async () => {
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "transcribe", { attachment_id: "a1" })] }, tables: { attachments: [voice] } });
+    const transcribe = vi.fn(async () => ({ text: "Running late, sorry" }));
+    const transcriber: Transcriber = { name: "fake", transcribe };
+    expect(await createChatRunner({ supabase: sb.client, deliver: async () => {}, transcriber }).run()).toMatchObject({ done: 1 });
+    expect(sb.signed).toEqual(["c/u/v.m4a@600"]);
+    expect(transcribe).toHaveBeenCalledWith({ url: "https://files.test/c/u/v.m4a?token=x", mime: "audio/mp4", durationMs: 4200, language: undefined });
+    expect(sb.rpcCalls).toContainEqual({
+      fn: "update_attachment",
+      args: { p_attachment_id: "a1", p_patch: { transcript: "Running late, sorry", transcript_status: "ready" } },
+    });
+  });
+
+  it("turns transcripts off without a transcriber", async () => {
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "transcribe", { attachment_id: "a1" })] }, tables: { attachments: [voice] } });
+    expect(await createChatRunner({ supabase: sb.client, deliver: async () => {} }).run()).toMatchObject({ done: 1 });
+    expect(sb.rpcCalls).toContainEqual({ fn: "update_attachment", args: { p_attachment_id: "a1", p_patch: { transcript_status: "off" } } });
+  });
+
+  it("retries a provider failure, and marks it failed on the last attempt", async () => {
+    const transcriber: Transcriber = { name: "fake", transcribe: async () => Promise.reject(new Error("Deepgram answered HTTP 503")) };
+    const early = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "transcribe", { attachment_id: "a1" }, 3)] }, tables: { attachments: [voice] } });
+    expect(await createChatRunner({ supabase: early.client, deliver: async () => {}, transcriber }).run()).toMatchObject({ failed: 1 });
+    expect(early.rpcCalls.filter((c) => c.fn === "update_attachment")).toEqual([]);
+    expect(early.rpcCalls).toContainEqual({ fn: "complete_effect", args: { p_id: 1, p_error: "Deepgram answered HTTP 503" } });
+
+    const last = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "transcribe", { attachment_id: "a1" }, 8)] }, tables: { attachments: [voice] } });
+    expect(await createChatRunner({ supabase: last.client, deliver: async () => {}, transcriber }).run()).toMatchObject({ failed: 1 });
+    expect(last.rpcCalls).toContainEqual({ fn: "update_attachment", args: { p_attachment_id: "a1", p_patch: { transcript_status: "failed" } } });
+  });
+
+  it("leaves a hosted video's transcript to its provider, and a deleted attachment alone", async () => {
+    const sb = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "transcribe", { attachment_id: "v1" }), effect(2, "transcribe", { attachment_id: "gone" })] },
+      tables: { attachments: [{ ...voice, id: "v1", kind: "video", provider: "mux", path: null }] },
+    });
+    const transcribe = vi.fn();
+    expect(await createChatRunner({ supabase: sb.client, deliver: async () => {}, transcriber: { name: "fake", transcribe } }).run()).toMatchObject({ done: 2 });
+    expect(transcribe).not.toHaveBeenCalled();
+  });
+});
+
+describe("chatRunnerHandler", () => {
+  const secret = "s".repeat(40);
+  const runner = { run: vi.fn(async () => ({ claimed: 2, done: 2, failed: 0 })) };
+  const handler = chatRunnerHandler({ runner, secret });
+
+  it("rejects a missing or wrong secret without running", async () => {
+    expect((await handler(new Request("https://app.test/api/chat-runner", { method: "POST" }))).status).toBe(401);
+    const wrong = await handler(new Request("https://app.test/api/chat-runner", { method: "POST", headers: { authorization: `Bearer ${"t".repeat(40)}` } }));
+    expect(wrong.status).toBe(401);
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
+  it("runs with the right secret and answers the counts", async () => {
+    const res = await handler(new Request("https://app.test/api/chat-runner", { method: "POST", headers: { authorization: `Bearer ${secret}` } }));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ claimed: 2, done: 2, failed: 0 });
+  });
+
+  it("refuses everyone when the secret is too short", async () => {
+    const weak = chatRunnerHandler({ runner, secret: "short" });
+    expect((await weak(new Request("https://app.test/x", { method: "POST", headers: { authorization: "Bearer short" } }))).status).toBe(500);
+  });
+});

package/src/__tests__/server-safety.test.ts

@@ -0,0 +1,290 @@
+/** @feat:chat Moderation mapping and the SSRF-safe link unfurler. */
+import { describe, expect, it, vi } from "vitest";
+import { carriesCredential, createLinkUnfurler, guardedLookup, isPrivateAddress, moderationVerdict, openAiModerator, parseOpenGraph } from "../server";
+import { fakeFetch, jsonResponse } from "./server-fakes";
+
+describe("moderationVerdict", () => {
+  it("maps scores to clean, flagged and hidden with default thresholds", () => {
+    expect(moderationVerdict({ harassment: 0.1, violence: 0.2 })).toEqual({ result: "clean" });
+    expect(moderationVerdict({ harassment: 0.6 })).toEqual({ result: "flagged", reason: "Automatic moderation: harassment 0.60" });
+    expect(moderationVerdict({ harassment: 0.95, violence: 0.55 })).toEqual({
+      result: "hidden",
+      reason: "Automatic moderation: harassment 0.95, violence 0.55",
+    });
+  });
+
+  it("is stricter for sexual/minors and softer to flag self-harm by default", () => {
+    expect(moderationVerdict({ "sexual/minors": 0.55 }).result).toBe("hidden");
+    expect(moderationVerdict({ "self-harm/intent": 0.35 }).result).toBe("flagged");
+    expect(moderationVerdict({ "self-harm/intent": 0.92 }).result).toBe("flagged");
+  });
+
+  it("takes configured thresholds, and the provider's flag", () => {
+    expect(moderationVerdict({ harassment: 0.6 }, { thresholds: { flag: 0.7 } }).result).toBe("clean");
+    expect(moderationVerdict({ violence: 0.6 }, { categories: { violence: { hide: 0.5 } } }).result).toBe("hidden");
+    expect(moderationVerdict({ harassment: 0.1 }, { flagged: true }).result).toBe("flagged");
+  });
+});
+
+describe("openAiModerator", () => {
+  it("sends text with the first photo, further photos alone, and keeps the highest scores", async () => {
+    const f = fakeFetch((_url, init) => {
+      const body = JSON.parse(String(init!.body)) as { input: { type: string }[] };
+      const withText = body.input.some((i) => i.type === "text");
+      return jsonResponse({ results: [{ flagged: false, category_scores: withText ? { harassment: 0.2, violence: 0.1 } : { violence: 0.93 } }] });
+    });
+    const verdict = await openAiModerator({ apiKey: "sk-test", fetch: f.fetch }).moderate({ text: "hi", imageUrls: ["https://f.test/1", "https://f.test/2"] });
+    expect(verdict).toEqual({ result: "hidden", reason: "Automatic moderation: violence 0.93" });
+    expect(f.calls).toHaveLength(2);
+    expect(f.calls[0]!.url).toBe("https://api.openai.com/v1/moderations");
+    expect((f.calls[0]!.init!.headers as Record<string, string>).authorization).toBe("Bearer sk-test");
+    expect(JSON.parse(String(f.calls[0]!.init!.body))).toEqual({
+      model: "omni-moderation-latest",
+      input: [
+        { type: "text", text: "hi" },
+        { type: "image_url", image_url: { url: "https://f.test/1" } },
+      ],
+    });
+  });
+
+  it("throws on an HTTP error so the effect retries", async () => {
+    const m = openAiModerator({ apiKey: "k", fetch: fakeFetch(() => new Response("no", { status: 429 })).fetch });
+    await expect(m.moderate({ text: "x", imageUrls: [] })).rejects.toThrow("HTTP 429");
+  });
+});
+
+describe("isPrivateAddress", () => {
+  it.each([
+    "127.0.0.1",
+    "10.1.2.3",
+    "172.16.0.1",
+    "192.168.1.1",
+    "169.254.169.254",
+    "100.64.0.1",
+    "0.0.0.0",
+    "224.0.0.1",
+    "::1",
+    "::",
+    "[::1]",
+    "fe80::1",
+    "fd00:ec2::254",
+    "::ffff:127.0.0.1",
+    "::ffff:7f00:1",
+    "64:ff9b::a9fe:a9fe",
+    "::ffff:0:7f00:1", // IPv4-translated 127.0.0.1
+    "::ffff:0:a00:1", // IPv4-translated 10.0.0.1
+    "2002:7f00:1::", // 6to4 of 127.0.0.1
+    "2002:a9fe:a9fe::1", // 6to4 of 169.254.169.254
+    "2001::1", // Teredo
+    "64:ff9b:1::1", // local-use NAT64
+    "3fff::1", // documentation
+    "192.88.99.1", // 6to4 relay
+    "not-an-ip",
+  ])("blocks %s", (ip) => expect(isPrivateAddress(ip)).toBe(true));
+
+  it.each(["93.184.216.34", "1.1.1.1", "2606:4700:4700::1111", "::ffff:93.184.216.34", "2002:5db8:d822::1", "2001:4860:4860::8888"])("allows %s", (ip) => expect(isPrivateAddress(ip)).toBe(false));
+});
+
+const html = (head: string, extra = "") => `<!doctype html><html><head>${head}</head><body>${extra}</body></html>`;
+const page = (body: string, headers: Record<string, string> = {}) =>
+  new Response(body, { status: 200, headers: { "content-type": "text/html; charset=utf-8", ...headers } });
+const publicDns = async () => ["93.184.216.34"];
+
+describe("createLinkUnfurler", () => {
+  it("parses Open Graph data with entities, caps and an https image", async () => {
+    const f = fakeFetch(() =>
+      page(
+        html(
+          `<title>Fallback</title><meta property="og:title" content="Tom &amp; Jerry&#39;s &#x1F600; plan">` +
+            `<meta content='Week   3\n of 12' property='og:description'><meta property="og:image" content="/img/cover.png">` +
+            `<meta property="og:site_name" content="Coach&nbsp;Co">`,
+        ),
+      ),
+    );
+    const preview = await createLinkUnfurler({ fetch: f.fetch, resolve: publicDns }).unfurl("https://coach.example/plan");
+    expect(preview).toEqual({
+      url: "https://coach.example/plan",
+      status: "ok",
+      title: "Tom & Jerry's \u{1F600} plan",
+      description: "Week 3 of 12",
+      imageUrl: "https://coach.example/img/cover.png",
+      siteName: "Coach Co",
+    });
+    expect(f.calls[0]!.init!.redirect).toBe("manual");
+  });
+
+  it("falls back to <title> and meta description, caps lengths and drops a non-https image", () => {
+    const og = parseOpenGraph(
+      html(`<title>  A   page  </title><meta name="description" content="${"d".repeat(700)}"><meta property="og:image" content="http://x.example/i.png">`),
+      "https://x.example/",
+    );
+    expect(og.title).toBe("A page");
+    expect(og.description).toHaveLength(600);
+    expect(og.imageUrl).toBeNull();
+  });
+
+  it("ignores tags outside the head and inside scripts or comments", () => {
+    const og = parseOpenGraph(
+      `<head><!-- <meta property="og:title" content="comment"> --><script>var s='<meta property="og:title" content="script">'</script>` +
+        `<meta property="og:title" content="real"></head><body><meta property="og:description" content="body"></body>`,
+      "https://x.example/",
+    );
+    expect(og).toMatchObject({ title: "real", description: null });
+  });
+
+  // Each of these took seconds when every unclosed start rescanned to the end of the page.
+  it.each([
+    ["unclosed scripts", "<script "],
+    ["unclosed comments", "<!--"],
+    ["unclosed metas", "<meta "],
+    ["unclosed titles", "<title>"],
+    ["an attribute's open quotes", "<meta x='"],
+    ["a long attribute name", "a"],
+    ["unclosed tags in a title", "<title>" + "<".repeat(1000)],
+  ])("parses a 512 KiB page of %s in linear time", (_, unit) => {
+    const page = unit.repeat(Math.ceil((512 * 1024) / unit.length));
+    const started = performance.now();
+    parseOpenGraph(unit === "a" ? `<meta ${page}>` : page, "https://x.example/");
+    expect(performance.now() - started).toBeLessThan(500);
+  });
+
+  it("still reads a title and an unclosed script runs to the end", () => {
+    expect(parseOpenGraph(`<title>Hi</title><script>var x = 1;<meta property="og:title" content="no">`, "https://x.example/").title).toBe("Hi");
+  });
+
+  it.each([
+    ["http://coach.example/", "blocked"],
+    ["https://127.0.0.1/", "blocked"],
+    ["https://[::1]/", "blocked"],
+    ["https://169.254.169.254/latest/meta-data", "blocked"],
+    ["https://2130706433/", "blocked"],
+    ["https://localhost/", "blocked"],
+    ["https://metadata.google.internal/", "blocked"],
+    ["https://intranet/", "blocked"],
+    ["https://user:pw@coach.example/", "blocked"],
+    ["https://coach.example:8443/", "blocked"],
+  ])("refuses %s without fetching", async (url, status) => {
+    const f = fakeFetch(() => page(html("<title>x</title>")));
+    expect((await createLinkUnfurler({ fetch: f.fetch, resolve: publicDns }).unfurl(url)).status).toBe(status);
+    expect(f.calls).toHaveLength(0);
+  });
+
+  it("refuses a name that resolves to a private address", async () => {
+    const f = fakeFetch(() => page(html("<title>x</title>")));
+    const u = createLinkUnfurler({ fetch: f.fetch, resolve: async () => ["93.184.216.34", "10.0.0.5"] });
+    expect((await u.unfurl("https://sneaky.example/")).status).toBe("blocked");
+    expect(f.calls).toHaveLength(0);
+  });
+
+  it("checks every redirect hop, and refuses a redirect into a private address", async () => {
+    const f = fakeFetch((url) =>
+      url === "https://coach.example/a"
+        ? new Response(null, { status: 302, headers: { location: "https://internal.example/admin" } })
+        : page(html("<title>secret</title>")),
+    );
+    const resolve = async (host: string) => (host === "internal.example" ? ["192.168.0.10"] : ["93.184.216.34"]);
+    expect((await createLinkUnfurler({ fetch: f.fetch, resolve }).unfurl("https://coach.example/a")).status).toBe("blocked");
+    expect(f.calls.map((c) => c.url)).toEqual(["https://coach.example/a"]);
+
+    const literal = fakeFetch(() => new Response(null, { status: 301, headers: { location: "https://169.254.169.254/" } }));
+    expect((await createLinkUnfurler({ fetch: literal.fetch, resolve: publicDns }).unfurl("https://coach.example/")).status).toBe("blocked");
+    const downgrade = fakeFetch(() => new Response(null, { status: 301, headers: { location: "http://coach.example/" } }));
+    expect((await createLinkUnfurler({ fetch: downgrade.fetch, resolve: publicDns }).unfurl("https://coach.example/")).status).toBe("blocked");
+  });
+
+  it("follows at most 3 redirects", async () => {
+    let n = 0;
+    const f = fakeFetch(() => new Response(null, { status: 302, headers: { location: `/hop${++n}` } }));
+    expect((await createLinkUnfurler({ fetch: f.fetch, resolve: publicDns }).unfurl("https://coach.example/")).status).toBe("failed");
+    expect(f.calls).toHaveLength(4);
+
+    let m = 0;
+    const ok = fakeFetch(() => (++m <= 3 ? new Response(null, { status: 302, headers: { location: `/hop${m}` } }) : page(html("<title>Here</title>"))));
+    expect(await createLinkUnfurler({ fetch: ok.fetch, resolve: publicDns }).unfurl("https://coach.example/")).toMatchObject({ status: "ok", title: "Here" });
+  });
+
+  it("fails on non-HTML, a declared oversize body, an HTTP error or a network error", async () => {
+    const run = (respond: () => Response | Promise<Response>, maxBytes?: number) =>
+      createLinkUnfurler({ fetch: fakeFetch(respond).fetch, resolve: publicDns, ...(maxBytes ? { maxBytes } : {}) }).unfurl("https://coach.example/");
+    expect((await run(() => new Response("%PDF", { headers: { "content-type": "application/pdf" } }))).status).toBe("failed");
+    expect((await run(() => new Response("{}", { headers: { "content-type": "application/json" } }))).status).toBe("failed");
+    expect((await run(() => page(html("<title>x</title>"), { "content-length": "999999" }), 1000)).status).toBe("failed");
+    expect((await run(() => new Response("gone", { status: 404, headers: { "content-type": "text/html" } }))).status).toBe("failed");
+    expect((await run(() => Promise.reject(new TypeError("fetch failed")))).status).toBe("failed");
+  });
+
+  it("reads no more than maxBytes of an undeclared body", async () => {
+    let pulled = 0;
+    const stream = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulled++;
+        controller.enqueue(new TextEncoder().encode(pulled === 1 ? '<head><meta property="og:title" content="Top"></head>' : "x".repeat(1000)));
+        if (pulled > 1000) controller.close();
+      },
+    });
+    const f = fakeFetch(() => new Response(stream, { headers: { "content-type": "text/html" } }));
+    expect(await createLinkUnfurler({ fetch: f.fetch, resolve: publicDns, maxBytes: 4096 }).unfurl("https://coach.example/")).toMatchObject({ status: "ok", title: "Top" });
+    expect(pulled).toBeLessThan(10);
+  });
+
+  it("without a resolver, refuses every named host (logged once) unless allowUnresolved", async () => {
+    const f = fakeFetch(() => page(html("<title>x</title>")));
+    const log = vi.fn();
+    const u = createLinkUnfurler({ fetch: f.fetch, resolve: async () => null, log });
+    expect((await u.unfurl("https://10.0.0.1/")).status).toBe("blocked");
+    expect((await u.unfurl("https://localtest.me/")).status).toBe("blocked");
+    expect((await u.unfurl("https://coach.example/")).status).toBe("blocked");
+    expect(f.calls).toHaveLength(0);
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(log.mock.calls[0]![0]).toContain("allowUnresolved");
+
+    const opted = createLinkUnfurler({ fetch: f.fetch, resolve: async () => null, allowUnresolved: true, log });
+    expect((await opted.unfurl("https://coach.example/")).status).toBe("ok");
+    expect((await opted.unfurl("https://10.0.0.1/")).status).toBe("blocked");
+  });
+
+  it("times out a DNS lookup that hangs", async () => {
+    const f = fakeFetch(() => page(html("<title>x</title>")));
+    const u = createLinkUnfurler({ fetch: f.fetch, resolve: () => new Promise<string[]>(() => {}), timeoutMs: 50 });
+    expect((await u.unfurl("https://slow.example/")).status).toBe("failed");
+    expect(f.calls).toHaveLength(0);
+  });
+
+  it("never fetches a link whose query carries a credential", async () => {
+    const f = fakeFetch(() => page(html("<title>x</title>")));
+    const u = createLinkUnfurler({ fetch: f.fetch, resolve: publicDns });
+    for (const url of ["https://app.example/reset?token=abc", "https://s3.example/f?X-Amz-Signature=1&a=b", "https://app.example/login?a=1&code=xyz"]) {
+      expect((await u.unfurl(url)).status).toBe("blocked");
+    }
+    expect(f.calls).toHaveLength(0);
+    expect(carriesCredential("https://app.example/page?ref=newsletter")).toBe(false);
+  });
+
+  it("drops an og:image whose host is private or local", async () => {
+    const run = async (image: string, resolve: (host: string) => Promise<string[]> = publicDns) =>
+      (await createLinkUnfurler({ fetch: fakeFetch(() => page(html(`<title>T</title><meta property="og:image" content="${image}">`))).fetch, resolve }).unfurl(
+        "https://coach.example/",
+      )).imageUrl;
+    expect(await run("https://10.0.0.1/i.png")).toBeNull();
+    expect(await run("https://intranet.local/i.png")).toBeNull();
+    expect(await run("https://cdn.example/i.png", async (h) => (h === "cdn.example" ? ["192.168.1.9"] : ["93.184.216.34"]))).toBeNull();
+    expect(await run("https://cdn.example/i.png?sig=abc")).toBe("https://cdn.example/i.png?sig=abc");
+  });
+
+  it("passes a dispatcher to fetch, and guardedLookup refuses a private answer at connect time", async () => {
+    const f = fakeFetch(() => page(html("<title>x</title>")));
+    const dispatcher = { pinned: true };
+    await createLinkUnfurler({ fetch: f.fetch, resolve: publicDns, dispatcher }).unfurl("https://coach.example/");
+    expect((f.calls[0]!.init as RequestInit & { dispatcher?: unknown }).dispatcher).toBe(dispatcher);
+
+    const lookup = (host: string, all: boolean) =>
+      new Promise<{ error: Error | null; address?: unknown }>((resolve) =>
+        guardedLookup(host, { all }, (error, address) => resolve({ error, address })),
+      );
+    const local = await lookup("localhost", false);
+    expect(local.error?.message).toContain("private address");
+    const ip = await lookup("1.1.1.1", true);
+    expect(ip.error).toBeNull();
+    expect(ip.address).toEqual([{ address: "1.1.1.1", family: 4 }]);
+  });
+});

package/src/__tests__/web-markdown.test.tsx

@@ -0,0 +1,88 @@
+/**
+ * @vitest-environment happy-dom
+ * @feat:chat
+ */
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { ChatMarkdown, isSafeHref, parseMarkdown } from "../web/markdown";
+
+afterEach(cleanup);
+
+const UUID = "3f2b8c1e-0d4a-4c6b-9e1f-2a3b4c5d6e7f";
+
+describe("parseMarkdown", () => {
+  it("reads bold, italic, code, links, mentions and line breaks", () => {
+    expect(parseMarkdown(`**hi** *there* _you_ \`x<y\` [site](https://example.com) @[Sam Lee](user:${UUID})\nnext`)).toEqual([
+      { type: "bold", children: [{ type: "text", text: "hi" }] },
+      { type: "text", text: " " },
+      { type: "italic", children: [{ type: "text", text: "there" }] },
+      { type: "text", text: " " },
+      { type: "italic", children: [{ type: "text", text: "you" }] },
+      { type: "text", text: " " },
+      { type: "code", text: "x<y" },
+      { type: "text", text: " " },
+      { type: "link", href: "https://example.com", children: [{ type: "text", text: "site" }] },
+      { type: "text", text: " " },
+      { type: "mention", name: "Sam Lee", userId: UUID },
+      { type: "break" },
+      { type: "text", text: "next" },
+    ]);
+  });
+
+  it("leaves snake_case, lone stars and unclosed markers as written", () => {
+    expect(parseMarkdown("my_var_name and 2 * 3 and **open")).toEqual([{ type: "text", text: "my_var_name and 2 * 3 and **open" }]);
+  });
+
+  it("links bare https URLs without their trailing punctuation", () => {
+    expect(parseMarkdown("see https://example.com/a?b=1.")).toEqual([
+      { type: "text", text: "see " },
+      { type: "link", href: "https://example.com/a?b=1", children: [{ type: "text", text: "https://example.com/a?b=1" }] },
+      { type: "text", text: "." },
+    ]);
+  });
+
+  it("keeps a link's words but drops a javascript:, data: or relative target", () => {
+    for (const href of ["javascript:alert(1)", "JavaScript:alert(1)", "data:text/html,<b>x</b>", "/relative", "vbscript:x"]) {
+      const nodes = parseMarkdown(`[click](${href})`);
+      expect(nodes.some((n) => n.type === "link")).toBe(false);
+      expect(nodes).toEqual([{ type: "text", text: "click" }]);
+    }
+    expect(isSafeHref("https://ok.example")).toBe(true);
+    expect(isSafeHref("http://ok.example")).toBe(true);
+    expect(isSafeHref("javascript:alert(1)")).toBe(false);
+    expect(isSafeHref("mailto:a@b.c")).toBe(false);
+  });
+
+  it("honours backslash escapes", () => {
+    expect(parseMarkdown("\\*not italic\\*")).toEqual([{ type: "text", text: "*not italic*" }]);
+  });
+});
+
+describe("ChatMarkdown", () => {
+  it("renders HTML in a message as text, never as elements", () => {
+    const { container } = render(<ChatMarkdown text={'<img src=x onerror="alert(1)"><script>alert(2)</script> **<b>bold</b>**'} />);
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("script")).toBeNull();
+    expect(container.querySelector("b")).toBeNull();
+    expect(container.textContent).toContain('<img src=x onerror="alert(1)">');
+    expect(container.querySelector("strong")?.textContent).toBe("<b>bold</b>");
+  });
+
+  it("opens links in a new tab with noopener noreferrer, and never a javascript: one", () => {
+    const { container } = render(<ChatMarkdown text="[ok](https://example.com) [bad](javascript:alert(1)) https://x.example" />);
+    const links = [...container.querySelectorAll("a")];
+    expect(links.map((a) => a.getAttribute("href"))).toEqual(["https://example.com", "https://x.example"]);
+    for (const a of links) {
+      expect(a.getAttribute("target")).toBe("_blank");
+      expect(a.getAttribute("rel")).toBe("noopener noreferrer");
+    }
+    expect(container.textContent).toContain("bad");
+  });
+
+  it("draws mentions as a chip, and line breaks as <br>", () => {
+    const { container } = render(<ChatMarkdown text={`hey @[Sam](user:${UUID})\nthere`} me={UUID} />);
+    const chip = container.querySelector(`[data-mention="${UUID}"]`);
+    expect(chip?.textContent).toBe("@Sam");
+    expect(container.querySelectorAll("br")).toHaveLength(1);
+  });
+});