Skip to content

Write HTML. Render video. Built for agents.

32.5 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  symlinkSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
  downloadAndRewriteFonts,
  downloadAssets,
  isPrivateUrl,
  safeFetch,
  toStandaloneSvg,
} from "./assetDownloader.js";
import { CaptureDirRefusedError } from "./captureErrors.js";
import type { DesignTokens } from "./types.js";
import type { IconCandidate } from "./faviconRanker.js";
import { CAPTURE_USER_AGENT } from "./userAgent.js";
import sharp from "sharp";
import { publicRequest } from "./publicNetwork.js";
import { loadSharp } from "../utils/optionalPackages.js";

vi.mock("./publicNetwork.js", () => ({ publicRequest: vi.fn() }));
vi.mock("../utils/optionalPackages.js", async (importOriginal) => {
  const actual = await importOriginal<typeof import("../utils/optionalPackages.js")>();
  return { ...actual, loadSharp: vi.fn(actual.loadSharp) };
});

// Exercise production URL/redirect checks while replacing only the socket transport.
function mockRequest(implementation: (url: string, init?: RequestInit) => Promise<Response>) {
  vi.mocked(publicRequest).mockImplementation((url, init) => implementation(String(url), init));
}

describe("isPrivateUrl — SSRF denylist (security: F-003)", () => {
  it("blocks loopback, private, and metadata IPv4", () => {
    for (const u of [
      "http://127.0.0.1/",
      "http://10.0.0.5/",
      "http://172.16.0.1/",
      "http://192.168.1.1/",
      "http://169.254.169.254/", // cloud metadata
      "http://100.64.0.1/",
      "http://192.0.0.1/",
      "http://198.18.0.1/",
      "http://224.0.0.1/",
      "http://240.0.0.1/",
    ]) {
      expect(isPrivateUrl(u), u).toBe(true);
    }
  });

  it("blocks 0.0.0.0 and the 0.0.0.0/8 range", () => {
    expect(isPrivateUrl("http://0.0.0.0/")).toBe(true);
    expect(isPrivateUrl("http://0.1.2.3/")).toBe(true);
  });

  it("blocks IPv6 loopback, IPv4-mapped, ULA, and link-local", () => {
    for (const u of [
      "http://[::1]/",
      "http://[::ffff:169.254.169.254]/", // IPv4-mapped metadata
      "http://[fd00::1]/", // unique-local fc00::/7
      "http://[fe80::1]/", // link-local fe80::/10
      "http://[fec0::1]/",
      "http://[ff02::1]/",
    ]) {
      expect(isPrivateUrl(u), u).toBe(true);
    }
  });

  it("still blocks alternate IPv4 encodings (WHATWG canonicalization)", () => {
    expect(isPrivateUrl("http://2130706433/")).toBe(true); // decimal 127.0.0.1
    expect(isPrivateUrl("http://0x7f000001/")).toBe(true); // hex
  });

  it("blocks non-http(s) schemes and internal suffixes", () => {
    expect(isPrivateUrl("file:///etc/passwd")).toBe(true);
    expect(isPrivateUrl("http://db.internal/")).toBe(true);
    expect(isPrivateUrl("http://svc.local/")).toBe(true);
  });

  it("allows ordinary public URLs", () => {
    expect(isPrivateUrl("https://example.com/logo.png")).toBe(false);
    expect(isPrivateUrl("http://example.com./logo.png")).toBe(false);
    expect(isPrivateUrl("http://notlocalhost.example/logo.png")).toBe(false);
    expect(isPrivateUrl("https://cdn.jsdelivr.net/a.svg")).toBe(false);
  });
});

describe("safeFetch — re-validates the denylist on every redirect hop (security: F-002)", () => {
  afterEach(() => vi.mocked(publicRequest).mockReset());

  it("blocks a public URL that redirects to a private/metadata host", async () => {
    const fetchMock = vi.fn(async (input: string, _init?: RequestInit) => {
      if (input === "https://public.example/logo.png") {
        return new Response(null, {
          status: 302,
          headers: { location: "http://169.254.169.254/latest/meta-data/" },
        });
      }
      // The metadata host must NEVER be fetched.
      throw new Error(`safeFetch followed a redirect to a private host: ${input}`);
    });
    mockRequest(fetchMock);

    const res = await safeFetch("https://public.example/logo.png");
    expect(res).toBeNull();
    // First (public) hop fetched; the redirect target was rejected before fetch.
    expect(fetchMock).toHaveBeenCalledTimes(1);
    expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({ redirect: "manual" });
  });

  it("follows a redirect to another public host and returns the final response", async () => {
    const fetchMock = vi.fn(async (input: string, _init?: RequestInit) => {
      if (input === "https://a.example/x")
        return new Response(null, { status: 301, headers: { location: "https://b.example/y" } });
      return new Response("ok", { status: 200 });
    });
    mockRequest(fetchMock);

    const res = await safeFetch("https://a.example/x");
    expect(res?.status).toBe(200);
    expect(await res?.text()).toBe("ok");
  });

  it("blocks localhost and internal DNS aliases initially and after redirects", async () => {
    for (const host of [
      "localhost.",
      "foo.localhost",
      "FOO.LOCALHOST.",
      "db.internal.",
      "svc.local.",
    ]) {
      const target = `http://${host}/private`;
      const fetchMock = vi.fn(
        async () =>
          new Response(null, {
            status: 302,
            headers: { location: target },
          }),
      );
      mockRequest(fetchMock);
      expect(isPrivateUrl(target), target).toBe(true);
      expect(await safeFetch(target), target).toBeNull();
      expect(fetchMock).not.toHaveBeenCalled();
      expect(await safeFetch("https://public.example/asset"), target).toBeNull();
      expect(fetchMock).toHaveBeenCalledTimes(1);
    }
  });

  it("cancels redirect bodies before validating the next hop", async () => {
    const canceled = vi.fn();
    mockRequest(
      vi.fn(
        async () =>
          new Response(new ReadableStream({ cancel: canceled }), {
            status: 302,
            headers: { location: "http://169.254.169.254/metadata" },
          }),
      ),
    );
    expect(await safeFetch("https://public.example/asset")).toBeNull();
    expect(canceled).toHaveBeenCalledOnce();
    expect(publicRequest).toHaveBeenCalledTimes(1);
  });

  it("returns null when the initial URL is private", async () => {
    const fetchMock = vi.fn(async () => new Response("ok"));
    mockRequest(fetchMock);
    const res = await safeFetch("http://169.254.169.254/");
    expect(res).toBeNull();
    expect(fetchMock).not.toHaveBeenCalled();
  });
});

describe("toStandaloneSvg — scraped inline SVGs must survive as .svg files", () => {
  it("adds the SVG namespace that outerHTML omits for inline SVG", () => {
    const inline = '<svg viewBox="0 0 24 24"><path d="M0 0h24v24H0z"/></svg>';
    const out = toStandaloneSvg(inline);
    expect(out).toContain('xmlns="http://www.w3.org/2000/svg"');
    // Nothing else may change — the path geometry is the brand mark.
    expect(out).toContain('<path d="M0 0h24v24H0z"/>');
    expect(out.endsWith("</svg>")).toBe(true);
  });

  it("leaves an SVG that already declares xmlns untouched", () => {
    const already = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><rect/></svg>';
    expect(toStandaloneSvg(already)).toBe(already);
  });

  it("declares xmlns:xlink only when an xlink: attribute is actually used", () => {
    const withXlink = '<svg viewBox="0 0 8 8"><use xlink:href="#a"/></svg>';
    expect(toStandaloneSvg(withXlink)).toContain('xmlns:xlink="http://www.w3.org/1999/xlink"');
    const without = '<svg viewBox="0 0 8 8"><use href="#a"/></svg>';
    expect(toStandaloneSvg(without)).not.toContain("xmlns:xlink");
  });

  it("is idempotent and preserves attributes on the root", () => {
    const inline = '<svg class="logo" width="120" height="24" fill="currentColor"><g/></svg>';
    const once = toStandaloneSvg(inline);
    expect(toStandaloneSvg(once)).toBe(once);
    for (const attr of ['class="logo"', 'width="120"', 'height="24"', 'fill="currentColor"']) {
      expect(once).toContain(attr);
    }
  });

  it("returns non-SVG input unchanged rather than corrupting it", () => {
    expect(toStandaloneSvg("<div>not an svg</div>")).toBe("<div>not an svg</div>");
  });
});

describe("downloadAndRewriteFonts — attempt caps", () => {
  afterEach(() => vi.mocked(publicRequest).mockReset());

  async function expectFailedFontAttempts(css: string, expectedAttempts: number): Promise<void> {
    const dir = mkdtempSync(join(tmpdir(), "hf-font-attempts-"));
    const fetchMock = vi.fn(async () => new Response("failed", { status: 503 }));
    mockRequest(fetchMock);

    try {
      await downloadAndRewriteFonts(css, dir);
      expect(fetchMock).toHaveBeenCalledTimes(expectedAttempts);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  }

  it("counts failed requests toward the global 30-font cap", async () => {
    const css = Array.from(
      { length: 35 },
      (_, i) =>
        `@font-face { font-family: Family${i}; src: url(https://fonts${i}.example/font-${i}.woff2); }`,
    ).join("\n");
    await expectFailedFontAttempts(css, 30);
  });

  it("counts failed requests toward the six-attempt per-family cap", async () => {
    const css = Array.from(
      { length: 10 },
      (_, i) =>
        `@font-face { font-family: Shared; src: url(https://fonts.example/font-${i}.woff2); }`,
    ).join("\n");
    await expectFailedFontAttempts(css, 6);
  });

  it("does not start a font request after the capture budget is exhausted", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-font-budget-"));
    const css = "@font-face { font-family: Budget; src: url(https://fonts.example/budget.woff2); }";
    const fetchMock = vi.fn();
    mockRequest(fetchMock);

    try {
      await downloadAndRewriteFonts(css, dir, { remainingMs: () => 0 });
      expect(fetchMock).not.toHaveBeenCalled();
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

function withTempDir<T>(run: (dir: string) => Promise<T>): Promise<T> {
  const dir = mkdtempSync(join(tmpdir(), "hf-drops-"));
  return run(dir).finally(() => rmSync(dir, { recursive: true, force: true }));
}

/** The two fields `downloadAssets` reads off the token bundle. */
function tokensWithNoSvgs(): DesignTokens {
  return { svgs: [], sections: [], ogImage: "" } as unknown as DesignTokens;
}

/**
 * openai.com's declared icons, in DOM order, with the attributes the page really carries.
 * `rankIconCandidates` puts `favicon.svg` first, so that is the file a capture must land.
 */
const OPENAI_ICONS: IconCandidate[] = [
  {
    rel: "icon",
    href: "https://openai.example/favicon.svg",
    sizes: null,
    type: "image/svg+xml",
  },
  {
    rel: "icon",
    href: "https://openai.example/favicon.ico",
    sizes: "48x48",
    type: "image/x-icon",
  },
  {
    rel: "apple-touch-icon",
    href: "https://openai.example/apple-icon.png",
    sizes: "180x180",
    type: "image/png",
  },
];

describe("drop counts — why a referenced asset is not in the capture", () => {
  afterEach(() => vi.mocked(publicRequest).mockReset());

  /** `n` @font-face rules, each naming a DIFFERENT family, so only the global cap can bite. */
  function fontCss(n: number): string {
    return Array.from(
      { length: n },
      (_, i) =>
        `@font-face { font-family: Family${i}; src: url(https://fonts${i}.example/font-${i}.woff2); }`,
    ).join("\n");
  }

  it("counts every face the budget never let it reach, not just the one it stopped on", async () => {
    // Four declared, zero budget: the honest number is four, and a warning string could only
    // ever have said "some".
    await withTempDir(async (dir) => {
      const fetchMock = vi.fn();
      mockRequest(fetchMock);
      const { drops } = await downloadAndRewriteFonts(fontCss(4), dir, { remainingMs: () => 0 });
      expect(fetchMock).not.toHaveBeenCalled();
      expect(drops["budget-exhausted"]).toBe(4);
      expect(drops["cap-reached"]).toBe(0);
      expect(drops.unavailable).toBe(0);
    });
  });

  it("separates the faces the global cap refused from the ones that failed", async () => {
    // 35 declared, cap 30: 30 are attempted and every attempt 503s, 5 are never reached.
    await withTempDir(async (dir) => {
      mockRequest(vi.fn(async () => new Response("no", { status: 503 })));
      const { drops } = await downloadAndRewriteFonts(fontCss(35), dir);
      expect(drops["cap-reached"]).toBe(5);
      expect(drops.unavailable).toBe(30);
      expect(drops["budget-exhausted"]).toBe(0);
    });
  });

  it("counts the faces the per-family cap refused", async () => {
    // 10 rules, all one family, per-family cap 6: 6 attempted, 4 refused.
    await withTempDir(async (dir) => {
      mockRequest(vi.fn(async () => new Response("no", { status: 503 })));
      const css = Array.from(
        { length: 10 },
        (_, i) =>
          `@font-face { font-family: Shared; src: url(https://fonts.example/f-${i}.woff2); }`,
      ).join("\n");
      const { drops } = await downloadAndRewriteFonts(css, dir);
      expect(drops["cap-reached"]).toBe(4);
      expect(drops.unavailable).toBe(6);
    });
  });

  it("reports all zeroes when nothing was refused, which is what makes thin readable", async () => {
    // The whole point of the tally: this page declared one face and we have it. A reader can now
    // tell this apart from a page that declared thirty and got truncated to one.
    await withTempDir(async (dir) => {
      mockRequest(
        vi.fn(
          async () =>
            new Response(
              new Uint8Array(
                readFileSync(
                  new URL(
                    "../../../../docs/public/catalog/assets/a634cb9e7783af7e.woff2",
                    import.meta.url,
                  ),
                ),
              ),
              { status: 200 },
            ),
        ),
      );
      const { css, drops } = await downloadAndRewriteFonts(fontCss(1), dir);
      expect(css).toContain("assets/fonts/font-0.woff2");
      expect(drops).toEqual({
        "size-floor": 0,
        "size-ceiling": 0,
        "budget-exhausted": 0,
        "cap-reached": 0,
        unavailable: 0,
      });
    });
  });

  it("counts an image dropped for being under the raster floor", async () => {
    // A valid small PNG is under the 10 KB floor; preserve the recorded drop reason.
    await withTempDir(async (dir) => {
      mockRequest(
        vi.fn(
          async () =>
            new Response(
              new Uint8Array(
                await sharp({ create: { width: 2, height: 2, channels: 4, background: "red" } })
                  .png()
                  .toBuffer(),
              ),
              { status: 200 },
            ),
        ),
      );
      const { assets, drops } = await downloadAssets(tokensWithNoSvgs(), dir, [
        { type: "Image", url: "https://cdn.example/hero.png", contexts: ["img[src]"] },
      ] as never);
      expect(assets).toEqual([]);
      expect(drops["size-floor"]).toBe(1);
      expect(drops.unavailable).toBe(0);
    });
  });

  it("counts every catalogued image the budget never let it reach", async () => {
    await withTempDir(async (dir) => {
      const fetchMock = vi.fn();
      mockRequest(fetchMock);
      const catalog = Array.from({ length: 7 }, (_, i) => ({
        type: "Image",
        url: `https://cdn.example/img-${i}.png`,
        contexts: ["img[src]"],
      }));
      const { assets, drops } = await downloadAssets(
        tokensWithNoSvgs(),
        dir,
        catalog as never,
        [],
        { remainingMs: () => 0 },
      );
      expect(fetchMock).not.toHaveBeenCalled();
      expect(assets).toEqual([]);
      expect(drops["budget-exhausted"]).toBe(7);
    });
  });

  it("counts the inline SVGs the 30-per-run cap refused", async () => {
    // 34 inline SVGs on the page, 30 kept: the four the cap dropped are now countable.
    await withTempDir(async (dir) => {
      const svgs = Array.from({ length: 34 }, (_, i) => ({
        outerHTML: `<svg viewBox="0 0 ${i} 10"><rect width="10" height="10" fill="#abc"/></svg>`,
        isLogo: false,
      }));
      const { assets, drops } = await downloadAssets(
        { svgs, sections: [], ogImage: "" } as unknown as DesignTokens,
        dir,
      );
      expect(assets).toHaveLength(30);
      expect(drops["cap-reached"]).toBe(4);
    });
  });

  it("writes an inline SVG logo over 10 KB whole, and skips one over the size cap uncut", async () => {
    await withTempDir(async (dir) => {
      const shapes = (n: number) =>
        Array.from({ length: n }, (_, i) => `<path d="M${i} 0h1v10h-1z"/>`).join("");
      const logo = `<svg viewBox="0 0 3000 10">${shapes(3000)}</svg>`;
      const huge = `<svg viewBox="0 0 1 10">${shapes(1)}<desc>${"x".repeat(3 * 1024 * 1024)}</desc></svg>`;
      expect(logo.length).toBeGreaterThan(10_000);
      const { assets, drops } = await downloadAssets(
        {
          svgs: [
            { outerHTML: logo, isLogo: true },
            { outerHTML: huge, isLogo: false },
          ],
          sections: [],
          ogImage: "",
        } as unknown as DesignTokens,
        dir,
      );
      expect(assets).toHaveLength(1);
      const written = readFileSync(join(dir, assets[0]!.localPath), "utf-8");
      expect(written).toBe(toStandaloneSvg(logo));
      expect(written.endsWith("</svg>")).toBe(true);
      expect(drops["size-ceiling"]).toBe(1);
    });
  });
});

describe("asset fetches present the same identity as the page navigation", () => {
  afterEach(() => vi.mocked(publicRequest).mockReset());

  /**
   * Measured against the real origin: `GET /favicon.svg` answers `403 text/html` to
   * `User-Agent: HyperFrames/1.0` and `200 image/svg+xml` to the browser UA the capture
   * already navigates with. The other two icons are served to either agent.
   */
  function serveLikeAnAntiBotEdge() {
    return vi.fn(async (url: string, init?: RequestInit) => {
      const agent = new Headers(init?.headers).get("user-agent") ?? "";
      if (url.endsWith("/favicon.svg") && !agent.startsWith("Mozilla/")) {
        return new Response("<html>denied</html>", {
          status: 403,
          headers: { "content-type": "text/html" },
        });
      }
      const body =
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24"/></svg>';
      return new Response(body, { status: 200, headers: { "content-type": "image/svg+xml" } });
    });
  }

  it("lands the icon the ranker chose from an origin that refuses non-browser agents", async () => {
    // With a bot UA the ranker's winner 403s and the capture silently falls through to the
    // next candidate, so the file on disk is chosen by the CDN rather than by the ranker.
    await withTempDir(async (dir) => {
      mockRequest(serveLikeAnAntiBotEdge());
      const { icons } = await downloadAssets(tokensWithNoSvgs(), dir, [], OPENAI_ICONS);
      expect(icons.headline?.file).toBe("assets/favicon.svg");
      expect(icons.icons[0]?.url).toBe("https://openai.example/favicon.svg");
    });
  });

  it("sends one User-Agent for every asset request", async () => {
    await withTempDir(async (dir) => {
      const fetchMock = serveLikeAnAntiBotEdge();
      mockRequest(fetchMock);
      await downloadAssets(tokensWithNoSvgs(), dir, [], OPENAI_ICONS);
      const agents = fetchMock.mock.calls.map((call) =>
        new Headers(call[1]?.headers).get("user-agent"),
      );
      expect(agents).not.toHaveLength(0);
      expect(new Set(agents)).toEqual(new Set([CAPTURE_USER_AGENT]));
    });
  });
});

async function testIco(): Promise<Buffer> {
  const png = await sharp({ create: { width: 16, height: 16, channels: 4, background: "red" } })
    .png()
    .toBuffer();
  const header = Buffer.alloc(22);
  header.writeUInt16LE(1, 2);
  header.writeUInt16LE(1, 4);
  header[6] = 16;
  header[7] = 16;
  header.writeUInt16LE(1, 10);
  header.writeUInt16LE(32, 12);
  header.writeUInt32LE(png.length, 14);
  header.writeUInt32LE(22, 18);
  return Buffer.concat([header, png]);
}

describe("declared icons — keep them all, headline the bare mark", () => {
  afterEach(() => vi.mocked(publicRequest).mockReset());

  /** A mark knocked out of a full-bleed rounded rect: the shape openai.com's favicon.svg has. */
  const BADGE_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180">
    <rect width="180" height="180" rx="90" fill="#000" /><path d="M60 60h60v60H60z" fill="#fff" />
  </svg>`;

  /** One shape with transparent margins. */
  const BARE_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180">
    <path d="M40 40h100v100H40z" fill="#000" />
  </svg>`;

  function solidPng(alpha: number): Promise<Buffer> {
    return sharp({
      create: { width: 64, height: 64, channels: 4, background: { r: 20, g: 20, b: 20, alpha } },
    })
      .png()
      .toBuffer();
  }

  const CONTENT_TYPE: Record<string, string> = {
    ".svg": "image/svg+xml",
    ".png": "image/png",
    ".ico": "image/vnd.microsoft.icon",
  };

  /** Serve each URL the bytes the test names for it; 404 anything unexpected. */
  function serve(bodies: Record<string, Buffer | string>) {
    return vi.fn(async (url: string) => {
      const body = Object.entries(bodies).find(([suffix]) => url.endsWith(suffix))?.[1];
      if (body === undefined) return new Response("nope", { status: 404 });
      const ext = url.slice(url.lastIndexOf("."));
      const bytes = typeof body === "string" ? Buffer.from(body) : body;
      return new Response(new Uint8Array(bytes), {
        status: 200,
        headers: { "content-type": CONTENT_TYPE[ext] ?? "application/octet-stream" },
      });
    });
  }

  it("writes one file per declared icon, named for its rel and sizes", async () => {
    await withTempDir(async (dir) => {
      mockRequest(
        serve({
          "favicon.svg": BADGE_SVG,
          "favicon.ico": await testIco(),
          "apple-icon.png": await solidPng(1),
        }),
      );
      const { icons } = await downloadAssets(tokensWithNoSvgs(), dir, [], OPENAI_ICONS);
      expect(icons.icons.map((i) => i.file)).toEqual([
        "assets/icon-icon-unsized.svg",
        "assets/icon-apple-touch-icon-180x180.png",
        "assets/icon-icon-48x48.ico",
      ]);
    });
  });

  it("records openai.com's icons as badges, and says the headline had no bare mark to pick", async () => {
    // Measured against the real files: the SVG is a mark knocked out of a full-bleed disc, and
    // the apple-touch PNG is an opaque white square, because Apple composites those onto an
    // opaque tile. openai.com declares no bare mark at all, so the headline falls back to the
    // ranker and the manifest has to say so rather than implying a preference was satisfied.
    await withTempDir(async (dir) => {
      mockRequest(
        serve({
          "favicon.svg": BADGE_SVG,
          "favicon.ico": await testIco(),
          "apple-icon.png": await solidPng(1),
        }),
      );
      const { icons } = await downloadAssets(tokensWithNoSvgs(), dir, [], OPENAI_ICONS);
      expect(icons.icons.map((i) => i.shape)).toEqual(["badge", "badge", "unknown"]);
      expect(icons.headline).toMatchObject({
        file: "assets/favicon.svg",
        source: "assets/icon-icon-unsized.svg",
        shape: "badge",
      });
      expect(icons.headline?.reason).toContain("no bare-mark candidate");
    });
  });

  it("headlines a lower-ranked bare mark over the better-ranked badge", async () => {
    // The ordering rule, on its own. By declared quality the SVG wins outright; by shape the
    // PNG does, and shape is what the brand band needs. Under the old rule this lands
    // assets/favicon.svg.
    await withTempDir(async (dir) => {
      mockRequest(serve({ "favicon.svg": BADGE_SVG, "apple-icon.png": await solidPng(0) }));
      const { icons } = await downloadAssets(tokensWithNoSvgs(), dir, [], [
        { rel: "icon", href: "https://x.test/favicon.svg", sizes: null, type: "image/svg+xml" },
        {
          rel: "apple-touch-icon",
          href: "https://x.test/apple-icon.png",
          sizes: "180x180",
          type: "image/png",
        },
      ] as IconCandidate[]);
      expect(icons.headline).toMatchObject({
        file: "assets/favicon.png",
        source: "assets/icon-apple-touch-icon-180x180.png",
        shape: "bare-mark",
        rank: 1,
      });
      expect(icons.headline?.reason).toContain("bare mark preferred over 1 badge");
    });
  });

  it("headlines the SVG when it is the bare mark", async () => {
    await withTempDir(async (dir) => {
      mockRequest(serve({ "favicon.svg": BARE_SVG }));
      const { icons } = await downloadAssets(tokensWithNoSvgs(), dir, [], [
        { rel: "icon", href: "https://x.test/favicon.svg", sizes: null, type: "image/svg+xml" },
      ] as IconCandidate[]);
      expect(icons.headline).toMatchObject({ file: "assets/favicon.svg", shape: "bare-mark" });
    });
  });

  it("keeps assets/favicon.<ext> so a stem match still finds the icon", async () => {
    await withTempDir(async (dir) => {
      mockRequest(serve({ "favicon.svg": BARE_SVG }));
      const { assets } = await downloadAssets(tokensWithNoSvgs(), dir, [], [
        { rel: "icon", href: "https://x.test/favicon.svg", sizes: null, type: "image/svg+xml" },
      ] as IconCandidate[]);
      expect(assets.map((a) => a.localPath)).toContain("assets/favicon.svg");
    });
  });
});

describe("capture download security boundaries", () => {
  it("preserves two different fonts whose URL extensions canonicalize to the same name", async () => {
    await withTempDir(async (dir) => {
      const first = readFileSync(
        new URL("../../../../docs/public/catalog/assets/a634cb9e7783af7e.woff2", import.meta.url),
      );
      const second = readFileSync(
        new URL("../../../../docs/public/catalog/assets/8963f64fa28dc4ae.woff2", import.meta.url),
      );
      expect(first.equals(second)).toBe(false);
      mockRequest(
        vi.fn(
          async (url: string) =>
            new Response(new Uint8Array(url.endsWith(".ttf") ? first : second)),
        ),
      );
      const css =
        "@font-face{font-family:A;src:url(https://fonts.example/site.ttf)} @font-face{font-family:B;src:url(https://fonts.example/site.woff2)}";
      const result = await downloadAndRewriteFonts(css, dir);
      expect(result.css).toContain("assets/fonts/site.woff2");
      expect(result.css).toContain("assets/fonts/site-2.woff2");
      expect(readFileSync(join(dir, "assets/fonts/site.woff2"))).toEqual(first);
      expect(readFileSync(join(dir, "assets/fonts/site-2.woff2"))).toEqual(second);
    });
  });

  it("shares the capture byte budget between fonts and icons", async () => {
    await withTempDir(async (dir) => {
      const bytes = readFileSync(
        new URL("../../../../docs/public/catalog/assets/a634cb9e7783af7e.woff2", import.meta.url),
      );
      const fetchMock = vi.fn(async () => new Response(new Uint8Array(bytes)));
      mockRequest(fetchMock);
      const byteBudget = { remainingBytes: bytes.length };
      await downloadAndRewriteFonts(
        "@font-face{font-family:A;src:url(https://fonts.example/site.woff2)}",
        dir,
        { byteBudget },
      );
      const result = await downloadAssets(tokensWithNoSvgs(), dir, [], OPENAI_ICONS, {
        byteBudget,
      });
      expect(result.icons.icons).toEqual([]);
      expect(fetchMock).toHaveBeenCalledTimes(1);
      expect(byteBudget.remainingBytes).toBe(0);
    });
  });

  afterEach(() => vi.mocked(publicRequest).mockReset());

  it("canonicalizes an icon ADS suffix and its promoted copy while preserving SVG bytes", async () => {
    await withTempDir(async (dir) => {
      const body =
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24"/></svg>';
      mockRequest(vi.fn(async () => new Response(body)));
      const { icons } = await downloadAssets(
        tokensWithNoSvgs(),
        dir,
        [],
        [
          {
            rel: "icon",
            href: "https://public.example/favicon.svg:payload",
            sizes: null,
            type: null,
          },
        ],
      );
      expect(icons.icons[0]?.file).toBe("assets/icon-icon-unsized.svg");
      expect(icons.headline?.file).toBe("assets/favicon.svg");
      expect(readFileSync(join(dir, "assets/favicon.svg"), "utf8")).toBe(body);
    });
  });

  it("does not publish arbitrary bytes as an OG image", async () => {
    await withTempDir(async (dir) => {
      mockRequest(vi.fn(async () => new Response(new Uint8Array(6000).fill(65))));
      const tokens = tokensWithNoSvgs();
      tokens.ogImage = "https://public.example/og.jpg::$DATA";
      const { assets, drops } = await downloadAssets(tokens, dir);
      expect(assets).toEqual([]);
      expect(drops.unavailable).toBe(1);
      expect(readdirSync(join(dir, "assets"))).not.toContain("og-image.jpg::$DATA");
    });
  });

  it.each(["font.woff2:ads", "CON.woff2"])(
    "writes valid font %s under a safe name and rewrites CSS",
    async (name) => {
      await withTempDir(async (dir) => {
        const bytes = readFileSync(
          new URL("../../../../docs/public/catalog/assets/a634cb9e7783af7e.woff2", import.meta.url),
        );
        mockRequest(vi.fn(async () => new Response(new Uint8Array(bytes))));
        const source = `@font-face{font-family:Demo;src:url(https://public.example/${name})}`;
        const result = await downloadAndRewriteFonts(source, dir);
        const names = readdirSync(join(dir, "assets/fonts"));
        expect(names).toHaveLength(1);
        expect(names[0]).not.toMatch(/:|^CON\./i);
        expect(result.css).toContain(`assets/fonts/${names[0]}`);
        expect(readFileSync(join(dir, "assets/fonts", names[0]!))).toEqual(bytes);
      });
    },
  );

  it("leaves invalid font URLs unchanged and records their rejection", async () => {
    await withTempDir(async (dir) => {
      mockRequest(vi.fn(async () => new Response(new Uint8Array(2048))));
      const source = "@font-face{font-family:Demo;src:url(https://public.example/font.woff2)}";
      const result = await downloadAndRewriteFonts(source, dir);
      expect(result.css).toBe(source);
      expect(result.drops.unavailable).toBe(1);
      expect(readdirSync(join(dir, "assets/fonts"))).toEqual([]);
    });
  });
});

describe("a planted directory link inside the capture directory (#4304)", () => {
  // Creating symlinks needs elevated rights on Windows.
  const posixOnly = it.skipIf(process.platform === "win32");

  function plantedLink(root: string, link: string): { outputDir: string; outside: string } {
    const outputDir = join(root, "capture");
    const outside = join(root, "outside");
    mkdirSync(join(outputDir, link, ".."), { recursive: true });
    mkdirSync(outside);
    symlinkSync(outside, join(outputDir, link));
    return { outputDir, outside };
  }

  posixOnly.each(["assets", "assets/svgs"])(
    "refuses to write page-derived assets through a planted %s/ symlink",
    async (link) => {
      await withTempDir(async (root) => {
        const { outputDir, outside } = plantedLink(root, link);
        const svgs = [
          {
            outerHTML: `<svg viewBox="0 0 10 10"><rect width="10" height="10" fill="#abc"/></svg>`,
            isLogo: false,
          },
        ];

        await expect(
          downloadAssets({ svgs, sections: [], ogImage: "" } as unknown as DesignTokens, outputDir),
        ).rejects.toThrow(/outside the capture directory/);
        expect(readdirSync(outside)).toEqual([]);
      });
    },
  );

  posixOnly("refuses a dangling assets/ symlink before its svgs folder", async () => {
    await withTempDir(async (root) => {
      const outputDir = join(root, "capture");
      const target = join(root, "missing");
      mkdirSync(outputDir);
      symlinkSync(target, join(outputDir, "assets"));

      await expect(
        downloadAssets(
          { svgs: [], sections: [], ogImage: "" } as unknown as DesignTokens,
          outputDir,
        ),
      ).rejects.toThrow(CaptureDirRefusedError);
      expect(existsSync(target)).toBe(false);
    });
  });

  posixOnly("refuses to create the fonts directory through a planted assets/ symlink", async () => {
    await withTempDir(async (root) => {
      const { outputDir, outside } = plantedLink(root, "assets");

      await expect(downloadAndRewriteFonts("", outputDir)).rejects.toThrow(
        /outside the capture directory/,
      );
      expect(readdirSync(outside)).toEqual([]);
    });
  });
});

describe("downloadAssets without sharp", () => {
  afterEach(() => vi.mocked(publicRequest).mockReset());

  it("fails the download instead of counting every image unavailable", async () => {
    vi.mocked(loadSharp).mockRejectedValueOnce(new Error("sharp is not installed"));
    await withTempDir(async (dir) => {
      const fetchMock = vi.fn();
      mockRequest(fetchMock);
      await expect(
        downloadAssets(tokensWithNoSvgs(), dir, [
          { type: "Image", url: "https://cdn.example/hero.png", contexts: ["img[src]"] },
        ] as never),
      ).rejects.toThrow("sharp is not installed");
      expect(fetchMock).not.toHaveBeenCalled();
    });
  });
});