@startsimpli/integrations 0.2.35 → 0.2.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -9,7 +9,9 @@
     "./types": "./src/types/index.ts",
     "./api": "./src/api/index.ts",
     "./corpus": "./src/corpus/index.ts",
-    "./corpus-llm": "./src/corpus/llm.ts"
+    "./corpus-llm": "./src/corpus/llm.ts",
+    "./safe-fetch": "./src/safe-fetch/index.ts",
+    "./ingest": "./src/ingest/index.ts"
   },
   "files": [
     "src",
@@ -18,7 +20,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.13",
+    "undici": "^8.11.2",
+    "unpdf": "^1.8.1"
+  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "@tanstack/react-query": ">=5.0.0",
@@ -48,7 +55,7 @@
     "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
     "vitest": "^3.0.0",
-    "@startsimpli/llm": "0.4.18"
+    "@startsimpli/llm": "0.4.25"
   },
   "scripts": {
     "type-check": "tsc --noEmit",

package/src/__tests__/ingest.test.ts

@@ -0,0 +1,127 @@
+// @vitest-environment node
+/**
+ * Server-side ingest helpers (crochet_patterns-llmj, design D1/PK2): readable
+ * text from a fetched page, and the text layer of a stored PDF.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { extractPdfText, looksScanned, readableText, SCANNED_CHARS_PER_PAGE } from '../ingest';
+
+describe('readableText', () => {
+  const article = (rounds: number) =>
+    '<html><head><title>Amigurumi Bunny | Hook Blog</title><style>.ad{color:red}</style></head><body>' +
+    '<header><nav><a href="/">Home</a> <a href="/shop">Shop</a></nav></header>' +
+    '<aside class="sidebar">Subscribe to our newsletter for weekly deals</aside>' +
+    '<article><h1>Amigurumi Bunny</h1><p>A small bunny worked in the round with worsted yarn and a 3.5 mm hook.</p><ul>' +
+    Array.from({ length: rounds }, (_, i) => `<li>Rnd ${i + 1}: sc in each st around, working in a spiral without joining (${6 * (i + 1)})</li>`).join('') +
+    '</ul><p>Fasten off and stuff firmly.</p></article>' +
+    '<footer>Copyright 2026 Hook Blog</footer><script>trackEverything()</script></body></html>';
+
+  it('keeps the article, one round per line, and drops scripts, styles, nav and footer', () => {
+    const { title, text } = readableText(article(12), 'https://blog.test/bunny');
+    expect(title).toContain('Amigurumi Bunny');
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    expect(lines).toContain('Rnd 1: sc in each st around, working in a spiral without joining (6)');
+    expect(lines).toContain('Rnd 12: sc in each st around, working in a spiral without joining (72)');
+    expect(text).toContain('Fasten off and stuff firmly.');
+    for (const junk of ['trackEverything', 'color:red', 'Copyright 2026', 'newsletter', 'Shop']) {
+      expect(text).not.toContain(junk);
+    }
+  });
+
+  it('falls back to the page body when the page is too short for an article, still one round per line', () => {
+    const { text } = readableText(
+      '<html><head><title>Tiny</title><script>x()</script></head><body><p>Rnd 1: 6 sc in MR<br>Rnd 2: inc x6 (12)</p><div>Rnd 3: sc around (12)</div></body></html>',
+    );
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    expect(lines).toEqual(['Rnd 1: 6 sc in MR', 'Rnd 2: inc x6 (12)', 'Rnd 3: sc around (12)']);
+  });
+
+  it('reads a bare fragment', () => {
+    expect(readableText('Rnd 1: 6 sc<br>Rnd 2: inc').text).toBe('Rnd 1: 6 sc\nRnd 2: inc');
+  });
+
+  it('collapses inline whitespace and decodes entities', () => {
+    const { text } = readableText('<body><p>Rnd&nbsp;1:   6   sc\n  in   <b>MR</b> &amp; join</p></body>');
+    expect(text).toBe('Rnd 1: 6 sc in MR & join');
+  });
+});
+
+/** A minimal, valid PDF with one Helvetica text line per entry of `pages[i]`. */
+function makePdf(pages: string[][]): Uint8Array {
+  const esc = (s: string) => s.replace(/[\\()]/g, (c) => `\\${c}`);
+  const objs: string[] = [];
+  const n = pages.length;
+  // 1 catalog, 2 pages, 3 font, then (page, content) pairs
+  objs.push('<< /Type /Catalog /Pages 2 0 R >>');
+  objs.push(`<< /Type /Pages /Count ${n} /Kids [${pages.map((_, i) => `${4 + 2 * i} 0 R`).join(' ')}] >>`);
+  objs.push('<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>');
+  pages.forEach((lines, i) => {
+    const stream = lines.length
+      ? `BT /F1 11 Tf 14 TL 72 720 Td ${lines.map((l) => `(${esc(l)}) Tj T*`).join(' ')} ET`
+      : '';
+    objs.push(
+      `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 3 0 R >> >> /Contents ${5 + 2 * i} 0 R >>`,
+    );
+    objs.push(`<< /Length ${stream.length} >>\nstream\n${stream}\nendstream`);
+  });
+  let out = '%PDF-1.4\n';
+  const offsets: number[] = [];
+  objs.forEach((body, i) => {
+    offsets.push(out.length);
+    out += `${i + 1} 0 obj\n${body}\nendobj\n`;
+  });
+  const xref = out.length;
+  out += `xref\n0 ${objs.length + 1}\n0000000000 65535 f \n`;
+  for (const o of offsets) out += `${String(o).padStart(10, '0')} 00000 n \n`;
+  out += `trailer\n<< /Size ${objs.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`;
+  return new TextEncoder().encode(out);
+}
+
+const ROUNDS = Array.from({ length: 12 }, (_, i) => `Rnd ${i + 1}: sc in each st around (${6 * (i + 1)})`);
+
+describe('extractPdfText', () => {
+  it('returns the text layer page by page', async () => {
+    const bytes = makePdf([ROUNDS.slice(0, 6), ROUNDS.slice(6)]);
+    const r = await extractPdfText(bytes);
+    expect(r.pages).toHaveLength(2);
+    expect(r.pages[0]).toContain('Rnd 1: sc in each st around (6)');
+    expect(r.pages[0]).toContain('Rnd 6: sc in each st around (36)');
+    expect(r.pages[0]).not.toContain('Rnd 7:');
+    expect(r.pages[1]).toContain('Rnd 12: sc in each st around (72)');
+    expect(r.totalChars).toBe(r.pages[0]!.length + r.pages[1]!.length);
+  });
+
+  it('a page with a full text layer does not look scanned', async () => {
+    const r = await extractPdfText(makePdf([ROUNDS]));
+    expect(r.totalChars).toBeGreaterThanOrEqual(SCANNED_CHARS_PER_PAGE);
+    expect(looksScanned(r)).toBe(false);
+  });
+
+  it('does not detach or alter the caller’s buffer (the stored original)', async () => {
+    const bytes = makePdf([ROUNDS]);
+    const copy = bytes.slice();
+    await extractPdfText(bytes);
+    expect(bytes.byteLength).toBe(copy.byteLength);
+    expect(Buffer.from(bytes).equals(Buffer.from(copy))).toBe(true);
+  });
+
+  it('a PDF with no text layer reads as empty and looks scanned', async () => {
+    const r = await extractPdfText(makePdf([[], []]));
+    expect(r.pages).toEqual(['', '']);
+    expect(r.totalChars).toBe(0);
+    expect(looksScanned(r)).toBe(true);
+  });
+
+  it('rejects bytes that are not a PDF', async () => {
+    await expect(extractPdfText(new TextEncoder().encode('<html>not a pdf</html>'))).rejects.toThrow();
+  });
+});
+
+describe('looksScanned', () => {
+  it(`is true below ${SCANNED_CHARS_PER_PAGE} chars per page on average, false at or above`, () => {
+    expect(looksScanned({ pages: [], totalChars: 0 })).toBe(true);
+    expect(looksScanned({ pages: ['a', 'b'], totalChars: 2 * SCANNED_CHARS_PER_PAGE - 1 })).toBe(true);
+    expect(looksScanned({ pages: ['a', 'b'], totalChars: 2 * SCANNED_CHARS_PER_PAGE })).toBe(false);
+  });
+});

package/src/__tests__/safe-fetch-pinning.test.ts

@@ -0,0 +1,198 @@
+// @vitest-environment node
+/**
+ * safeFetch DNS pinning (crochet_patterns-yfj8 #1, design D5) and the address
+ * blocklist. The connection must go to the address that was validated: a
+ * record that answers public at pre-flight and private at connect is refused at
+ * connect. Uses a loopback http server only — no external network.
+ */
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Agent, fetch as undiciFetch } from 'undici';
+
+import { isBlockedAddress, pinnedLookup, safeFetch, SafeFetchError, type ResolvedAddress } from '../safe-fetch';
+
+const PUBLIC = '93.184.216.34';
+const asAddrs = (...addrs: string[]): ResolvedAddress[] =>
+  addrs.map((address) => ({ address, family: address.includes(':') ? 6 : 4 }));
+
+describe('isBlockedAddress', () => {
+  it.each([
+    '127.0.0.1',
+    '127.255.0.9',
+    '0.0.0.0',
+    '0.1.2.3',
+    '10.9.8.7',
+    '100.64.0.1', // CGNAT
+    '100.127.255.255',
+    '169.254.169.254',
+    '172.16.0.1',
+    '172.31.255.255',
+    '192.0.0.8',
+    '192.168.0.1',
+    '198.18.0.1', // benchmarking
+    '198.19.255.255',
+    '224.0.0.1', // multicast
+    '239.255.255.250',
+    '240.0.0.1', // reserved
+    '255.255.255.255',
+    '::',
+    '::1',
+    '[::1]',
+    'fc00::1',
+    'fd12:3456::1',
+    'fe80::1',
+    'fe80::1%en0',
+    'fec0::1',
+    'ff02::1',
+    '::ffff:169.254.169.254',
+    '::ffff:a9fe:a9fe', // the form WHATWG URL rewrites the above to
+    '::ffff:127.0.0.1',
+    '::127.0.0.1', // v4-compatible
+    '64:ff9b::a9fe:a9fe', // NAT64 of the metadata address
+    '64:ff9b::10.0.0.1',
+    '64:ff9b:1::1', // local-use NAT64
+    '2002:7f00:0001::1', // 6to4 of 127.0.0.1
+    '2002:c0a8:0101::', // 6to4 of 192.168.1.1
+    'not-an-ip',
+    '',
+  ])('blocks %s', (addr) => {
+    expect(isBlockedAddress(addr)).toBe(true);
+  });
+
+  it.each([
+    PUBLIC,
+    '8.8.8.8',
+    '1.1.1.1',
+    '172.32.0.1',
+    '172.15.255.255',
+    '100.128.0.1',
+    '100.63.255.255',
+    '198.20.0.1',
+    '223.255.255.255',
+    '2606:4700:4700::1111',
+    '2001:4860:4860::8888',
+    '::ffff:8.8.8.8',
+    '64:ff9b::808:808', // NAT64 of 8.8.8.8
+    '2002:0808:0808::1', // 6to4 of 8.8.8.8
+  ])('allows %s', (addr) => {
+    expect(isBlockedAddress(addr)).toBe(false);
+  });
+});
+
+describe('safeFetch url hygiene', () => {
+  it.each(['https://user:pass@blog.test/', 'https://user@blog.test/'])('refuses credentials in %s', async (url) => {
+    const fetch = vi.fn();
+    const err = await safeFetch(url, { fetch, lookup: async () => asAddrs(PUBLIC) }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(SafeFetchError);
+    expect((err as SafeFetchError).code).toBe('BAD_URL');
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['decimal', 'http://2130706433/'],
+    ['hex', 'http://0x7f.0.0.1/'],
+    ['NAT64 metadata literal', 'http://[64:ff9b::169.254.169.254]/'],
+    ['6to4 loopback literal', 'http://[2002:7f00:1::1]/'],
+  ])('refuses the %s form of an internal IP literal without resolving it', async (_label, url) => {
+    const fetch = vi.fn();
+    const lookup = vi.fn(async () => asAddrs(PUBLIC));
+    const err = await safeFetch(url, { fetch, lookup }).catch((e: unknown) => e);
+    expect((err as SafeFetchError).code).toBe('BLOCKED_ADDRESS');
+    expect(lookup).not.toHaveBeenCalled();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+});
+
+function callLookup(fn: ReturnType<typeof pinnedLookup>, host: string, options: object) {
+  return new Promise<{ err: NodeJS.ErrnoException | null; address: unknown; family?: number }>((resolve) => {
+    fn(host, options as never, (err, address, family) => resolve({ err, address, family }));
+  });
+}
+
+describe('pinnedLookup', () => {
+  it('hands back exactly the validated answer in the {all:true} form, resolving once', async () => {
+    const resolve = vi.fn(async () => asAddrs(PUBLIC, '2606:4700:4700::1111'));
+    const r = await callLookup(pinnedLookup(resolve), 'blog.test', { all: true });
+    expect(r.err).toBeNull();
+    expect(r.address).toEqual([
+      { address: PUBLIC, family: 4 },
+      { address: '2606:4700:4700::1111', family: 6 },
+    ]);
+    expect(resolve).toHaveBeenCalledTimes(1);
+    expect(resolve).toHaveBeenCalledWith('blog.test');
+  });
+
+  it('uses the (address, family) form without all, and honours options.family', async () => {
+    const resolve = async () => asAddrs('2606:4700:4700::1111', PUBLIC);
+    const plain = await callLookup(pinnedLookup(resolve), 'blog.test', {});
+    expect(plain).toMatchObject({ err: null, address: '2606:4700:4700::1111', family: 6 });
+    const v4 = await callLookup(pinnedLookup(resolve), 'blog.test', { family: 4 });
+    expect(v4).toMatchObject({ err: null, address: PUBLIC, family: 4 });
+  });
+
+  it('refuses the whole answer when any address is blocked', async () => {
+    const r = await callLookup(pinnedLookup(async () => asAddrs(PUBLIC, '169.254.169.254')), 'mixed.test', {
+      all: true,
+    });
+    expect(r.err).toBeInstanceOf(SafeFetchError);
+    expect((r.err as unknown as SafeFetchError).code).toBe('BLOCKED_ADDRESS');
+  });
+});
+
+describe('safeFetch connects only to the address it validated (no injected fetch)', () => {
+  let server: Server;
+  let port: number;
+  let connections = 0;
+
+  beforeAll(async () => {
+    server = createServer((_req, res) => {
+      res.writeHead(200, { 'content-type': 'text/html' });
+      res.end('<html><body>internal</body></html>');
+    });
+    server.on('connection', () => {
+      connections++;
+    });
+    await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+    port = (server.address() as AddressInfo).port;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((r) => server.close(() => r()));
+  });
+
+  it('control: an undici Agent connect.lookup decides where the socket goes', async () => {
+    // Proves the loopback server is reachable through a custom lookup, so the
+    // zero-connection assertion below is caused by pinning, not by an unreachable host.
+    const before = connections;
+    const agent = new Agent({
+      connect: {
+        lookup: (_h, opts, cb) =>
+          (opts as { all?: boolean }).all
+            ? (cb as (e: null, a: Array<{ address: string; family: number }>) => void)(null, [
+                { address: '127.0.0.1', family: 4 },
+              ])
+            : cb(null, '127.0.0.1', 4),
+      },
+    });
+    try {
+      const res = await undiciFetch(`http://rebind.test:${port}/`, { dispatcher: agent });
+      expect(await res.text()).toContain('internal');
+    } finally {
+      await agent.close();
+    }
+    expect(connections).toBe(before + 1);
+  });
+
+  it('a record that answers public at pre-flight and private at connect is refused at connect', async () => {
+    const before = connections;
+    const answers = [asAddrs(PUBLIC), asAddrs('127.0.0.1')];
+    const lookup = vi.fn(async () => answers.shift() ?? asAddrs('127.0.0.1'));
+    const err = await safeFetch(`http://rebind.test:${port}/`, { lookup, timeoutMs: 5000 }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(SafeFetchError);
+    expect((err as SafeFetchError).code).toBe('BLOCKED_ADDRESS');
+    // Once for the pre-flight, once inside connect.lookup — the socket used the second, checked answer.
+    expect(lookup).toHaveBeenCalledTimes(2);
+    expect(connections).toBe(before);
+  });
+});

package/src/__tests__/safe-fetch.test.ts

@@ -0,0 +1,186 @@
+// @vitest-environment node
+/**
+ * safeFetch SSRF guards (crochet_patterns-llmj — "paste a link to a pattern").
+ * DNS and fetch are injected fakes: no real network.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+import { safeFetch, SafeFetchError, type ResolvedAddress } from '../safe-fetch';
+
+const PUBLIC = '93.184.216.34';
+
+function fakeDns(map: Record<string, string[]> = {}) {
+  return vi.fn(async (host: string): Promise<ResolvedAddress[]> => {
+    const addrs = map[host] ?? [PUBLIC];
+    return addrs.map((address) => ({ address, family: address.includes(':') ? 6 : 4 }));
+  });
+}
+
+const html = (body = '<html><body>Rnd 1: 6 sc in magic ring</body></html>', type = 'text/html; charset=utf-8') =>
+  new Response(body, { status: 200, headers: { 'content-type': type } });
+const redirect = (location: string) => new Response(null, { status: 302, headers: { location } });
+
+function fakeFetch(...responses: Array<Response | ((init?: RequestInit) => Promise<Response>)>) {
+  return vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
+    const next = responses.shift();
+    if (!next) throw new Error('fake fetch: no more responses');
+    return typeof next === 'function' ? next(init) : next;
+  });
+}
+
+async function refusal(p: Promise<unknown>): Promise<SafeFetchError> {
+  const err = await p.then(
+    () => undefined,
+    (e: unknown) => e,
+  );
+  expect(err).toBeInstanceOf(SafeFetchError);
+  return err as SafeFetchError;
+}
+
+describe('safeFetch refuses internal addresses', () => {
+  it.each([
+    ['loopback v4', 'http://127.0.0.1/pattern'],
+    ['loopback v6', 'http://[::1]/pattern'],
+    ['cloud metadata', 'http://169.254.169.254/latest/meta-data/'],
+    ['10/8', 'http://10.0.0.5/'],
+    ['172.16/12 low end', 'http://172.16.0.1/'],
+    ['172.16/12 high end', 'http://172.31.255.255/'],
+    ['192.168/16', 'http://192.168.1.1/'],
+    ['unspecified', 'http://0.0.0.0/'],
+    ['v4-mapped v6 metadata', 'http://[::ffff:169.254.169.254]/'],
+  ])('%s (%s) as an IP literal, without fetching', async (_label, url) => {
+    const fetch = fakeFetch(html());
+    const err = await refusal(safeFetch(url, { fetch, lookup: fakeDns() }));
+    expect(err.code).toBe('BLOCKED_ADDRESS');
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('a DNS name that resolves to a private IP', async () => {
+    const fetch = fakeFetch(html());
+    const lookup = fakeDns({ 'patterns.evil.test': ['10.1.2.3'] });
+    const err = await refusal(safeFetch('https://patterns.evil.test/bunny', { fetch, lookup }));
+    expect(err.code).toBe('BLOCKED_ADDRESS');
+    expect(lookup).toHaveBeenCalledWith('patterns.evil.test');
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('a DNS name where ANY of its addresses is private', async () => {
+    const fetch = fakeFetch(html());
+    const lookup = fakeDns({ 'mixed.test': [PUBLIC, '192.168.0.9'] });
+    const err = await refusal(safeFetch('https://mixed.test/', { fetch, lookup }));
+    expect(err.code).toBe('BLOCKED_ADDRESS');
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('a redirect hop to a host that resolves privately', async () => {
+    const fetch = fakeFetch(redirect('http://internal.test/admin'), html());
+    const lookup = fakeDns({ 'internal.test': ['192.168.0.10'] });
+    const err = await refusal(safeFetch('https://blog.test/bunny', { fetch, lookup }));
+    expect(err.code).toBe('BLOCKED_ADDRESS');
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('a redirect hop straight to the metadata IP', async () => {
+    const fetch = fakeFetch(redirect('http://169.254.169.254/latest/meta-data/'), html());
+    const err = await refusal(safeFetch('https://blog.test/bunny', { fetch, lookup: fakeDns() }));
+    expect(err.code).toBe('BLOCKED_ADDRESS');
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('a non-http scheme', async () => {
+    const fetch = fakeFetch(html());
+    const err = await refusal(safeFetch('file:///etc/passwd', { fetch, lookup: fakeDns() }));
+    expect(err.code).toBe('BAD_URL');
+    expect(fetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('safeFetch fetches public pages', () => {
+  it('returns the body of a public html page, fetched with redirect: manual', async () => {
+    const fetch = fakeFetch(html());
+    const res = await safeFetch('https://blog.test/bunny', { fetch, lookup: fakeDns() });
+    expect(res.status).toBe(200);
+    expect(res.contentType).toBe('text/html');
+    expect(new TextDecoder().decode(res.body)).toContain('6 sc in magic ring');
+    expect(fetch.mock.calls[0]![1]?.redirect).toBe('manual');
+  });
+
+  it('allows 172.32.0.1 (just outside 172.16/12)', async () => {
+    const fetch = fakeFetch(html());
+    await expect(safeFetch('http://172.32.0.1/', { fetch, lookup: fakeDns() })).resolves.toMatchObject({ status: 200 });
+  });
+
+  it('follows 3 redirects (relative Location resolved), re-checking every hop with redirect: manual', async () => {
+    const fetch = fakeFetch(redirect('https://a.test/1'), redirect('/2'), redirect('https://c.test/3'), html());
+    const lookup = fakeDns();
+    const res = await safeFetch('https://start.test/', { fetch, lookup });
+    expect(res.finalUrl).toBe('https://c.test/3');
+    expect(fetch).toHaveBeenCalledTimes(4);
+    expect(String(fetch.mock.calls[2]![0])).toBe('https://a.test/2');
+    for (const call of fetch.mock.calls) expect(call[1]?.redirect).toBe('manual');
+    expect(lookup.mock.calls.map((c) => c[0])).toEqual(expect.arrayContaining(['start.test', 'a.test', 'c.test']));
+  });
+
+  it('refuses a 4th redirect', async () => {
+    const fetch = fakeFetch(redirect('/1'), redirect('/2'), redirect('/3'), redirect('/4'), html());
+    const err = await refusal(safeFetch('https://start.test/', { fetch, lookup: fakeDns() }));
+    expect(err.code).toBe('TOO_MANY_REDIRECTS');
+    expect(fetch).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe('safeFetch content limits', () => {
+  it('accepts application/pdf', async () => {
+    const fetch = fakeFetch(new Response(new Uint8Array([0x25, 0x50, 0x44, 0x46]), { headers: { 'content-type': 'application/pdf' } }));
+    const res = await safeFetch('https://blog.test/bunny.pdf', { fetch, lookup: fakeDns() });
+    expect(res.contentType).toBe('application/pdf');
+    expect(res.body.byteLength).toBe(4);
+  });
+
+  it.each(['application/json', 'image/png', 'application/octet-stream'])('refuses %s', async (type) => {
+    const fetch = fakeFetch(html('{}', type));
+    const err = await refusal(safeFetch('https://blog.test/x', { fetch, lookup: fakeDns() }));
+    expect(err.code).toBe('UNSUPPORTED_TYPE');
+  });
+
+  it('refuses a response with no content type', async () => {
+    const fetch = fakeFetch(new Response(new Uint8Array([1, 2, 3]), { status: 200 }));
+    const err = await refusal(safeFetch('https://blog.test/x', { fetch, lookup: fakeDns() }));
+    expect(err.code).toBe('UNSUPPORTED_TYPE');
+  });
+
+  it('refuses a declared content-length over maxBytes', async () => {
+    const fetch = fakeFetch(
+      new Response('x'.repeat(10), { headers: { 'content-type': 'text/html', 'content-length': '5000000' } }),
+    );
+    const err = await refusal(safeFetch('https://blog.test/x', { fetch, lookup: fakeDns(), maxBytes: 1000 }));
+    expect(err.code).toBe('TOO_LARGE');
+  });
+
+  it('aborts a streamed body (no content-length) once it passes maxBytes', async () => {
+    let pulled = 0;
+    const stream = new ReadableStream<Uint8Array>({
+      pull(c) {
+        pulled++;
+        if (pulled > 1000) return c.close();
+        c.enqueue(new Uint8Array(512));
+      },
+    });
+    const fetch = fakeFetch(new Response(stream, { headers: { 'content-type': 'text/html' } }));
+    const err = await refusal(safeFetch('https://blog.test/x', { fetch, lookup: fakeDns(), maxBytes: 2048 }));
+    expect(err.code).toBe('TOO_LARGE');
+    expect(pulled).toBeLessThan(1000);
+  });
+
+  it('aborts on timeout', async () => {
+    const hang = (init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError')));
+      });
+    const fetch = fakeFetch(hang);
+    const started = Date.now();
+    const err = await refusal(safeFetch('https://slow.test/', { fetch, lookup: fakeDns(), timeoutMs: 50 }));
+    expect(err.code).toBe('TIMEOUT');
+    expect(Date.now() - started).toBeLessThan(2000);
+  });
+});

package/src/ingest/index.ts

@@ -0,0 +1,126 @@
+/**
+ * Document ingest helpers (crochet_patterns-llmj, design D1/PK2): turn a fetched
+ * web page or a stored PDF into plain text for a model.
+ *
+ * SERVER-ONLY. Exported from the `@startsimpli/integrations/ingest` subpath,
+ * never from the package root (linkedom and unpdf are node-side dependencies).
+ */
+import { Readability } from '@mozilla/readability';
+import { parseHTML } from 'linkedom';
+import { extractText, getDocumentProxy } from 'unpdf';
+
+// ---------------------------------------------------------------------------
+// HTML
+// ---------------------------------------------------------------------------
+
+const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'IFRAME', 'HEAD']);
+const BLOCK = new Set([
+  'ADDRESS', 'ARTICLE', 'ASIDE', 'BLOCKQUOTE', 'BODY', 'CAPTION', 'DD', 'DETAILS', 'DIV', 'DL', 'DT',
+  'FIELDSET', 'FIGCAPTION', 'FIGURE', 'FOOTER', 'FORM', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'HEADER',
+  'HR', 'LI', 'MAIN', 'NAV', 'OL', 'P', 'PRE', 'SECTION', 'SUMMARY', 'TABLE', 'TBODY', 'TD', 'TFOOT',
+  'TH', 'THEAD', 'TR', 'UL',
+]);
+
+interface DomNode {
+  nodeType: number;
+  nodeName: string;
+  textContent: string | null;
+  childNodes: ArrayLike<DomNode>;
+}
+
+/** Text of a DOM subtree with a line break around every block element and at `<br>`. */
+function blockText(root: DomNode): string {
+  let out = '';
+  const walk = (node: DomNode) => {
+    if (node.nodeType === 3) {
+      out += (node.textContent ?? '').replace(/\s+/g, ' ');
+      return;
+    }
+    if (node.nodeType !== 1 && node.nodeType !== 9 && node.nodeType !== 11) return;
+    const tag = node.nodeName.toUpperCase();
+    if (SKIP.has(tag)) return;
+    if (tag === 'BR') {
+      out += '\n';
+      return;
+    }
+    const block = BLOCK.has(tag);
+    if (block) out += '\n';
+    for (let i = 0; i < node.childNodes.length; i++) walk(node.childNodes[i]!);
+    if (block) out += '\n';
+  };
+  walk(root);
+  return out
+    .split('\n')
+    .map((line) => line.replace(/[ \t ]+/g, ' ').trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * The readable text of an HTML page: Readability's main article when it finds
+ * one, else the whole body (scripts and styles dropped). Each block element and
+ * `<br>` starts a new line, so "Rnd 1 … / Rnd 2 …" list items stay one per line.
+ * `baseUrl` lets Readability resolve relative links; it does not change the text.
+ */
+export function readableText(html: string, baseUrl?: string): { title?: string; text: string } {
+  // linkedom leaves a bare fragment out of <body>; give it a document to live in.
+  const whole = /<html[\s>]/i.test(html) ? html : `<!doctype html><html><head></head><body>${html}</body></html>`;
+  const { document } = parseHTML(whole);
+  if (baseUrl && !document.querySelector('base')) {
+    const base = document.createElement('base');
+    base.setAttribute('href', baseUrl);
+    document.head?.appendChild(base);
+  }
+  const docTitle = document.title?.trim() || undefined;
+
+  let text = '';
+  let title = docTitle;
+  try {
+    // Readability mutates the document it is given; parse a fresh copy.
+    const article = new Readability(parseHTML(document.toString()).document as unknown as Document).parse();
+    if (article?.content) {
+      text = blockText(parseHTML(`<html><body>${article.content}</body></html>`).document as unknown as DomNode);
+      title = article.title?.trim() || docTitle;
+    }
+  } catch {
+    // fall through to the whole body
+  }
+  if (!text) text = blockText((document.body ?? document) as unknown as DomNode);
+  return title ? { title, text } : { text };
+}
+
+// ---------------------------------------------------------------------------
+// PDF
+// ---------------------------------------------------------------------------
+
+export interface PdfText {
+  /** One entry per page, trimmed. */
+  pages: string[];
+  /** Characters across all pages (trimmed). */
+  totalChars: number;
+}
+
+/**
+ * Text layer of a PDF, one string per page (unpdf / pdf.js). Throws on bytes
+ * that are not a readable PDF. The input is copied first, so the caller's
+ * buffer (the stored original) is never detached.
+ */
+export async function extractPdfText(bytes: Uint8Array): Promise<PdfText> {
+  const pdf = await getDocumentProxy(new Uint8Array(bytes), { verbosity: 0 });
+  try {
+    const { text } = await extractText(pdf, { mergePages: false });
+    const pages = text.map((t) => t.trim());
+    return { pages, totalChars: pages.reduce((n, p) => n + p.length, 0) };
+  } finally {
+    await pdf.loadingTask.destroy().catch(() => undefined);
+  }
+}
+
+/** Average under this many characters per page = no usable text layer (design R6). */
+export const SCANNED_CHARS_PER_PAGE = 200;
+
+/** True when a PDF has no usable text layer and should go to the model as a document. */
+export function looksScanned(r: PdfText): boolean {
+  return r.pages.length === 0 || r.totalChars / r.pages.length < SCANNED_CHARS_PER_PAGE;
+}

package/src/safe-fetch/index.ts

@@ -0,0 +1,387 @@
+/**
+ * safeFetch — server-side fetch of a USER-SUPPLIED url with SSRF guards
+ * (crochet_patterns-llmj: "paste a link to a pattern").
+ *
+ * SERVER-ONLY. Exported from the `@startsimpli/integrations/safe-fetch`
+ * subpath, never from the package root (client components import the root, and
+ * the default resolver is `node:dns`).
+ *
+ * Contract:
+ * - only http/https urls, no `user:pass@`;
+ * - every hop's host is resolved and EVERY address is checked
+ *   (`isBlockedAddress`); redirects are followed by hand (`redirect: 'manual'`)
+ *   so each hop is re-checked; at most `maxRedirects` (default 3);
+ * - only `allowTypes` content types (default text/html, application/pdf);
+ * - aborts over `maxBytes` (header or streamed) and after `timeoutMs`.
+ *
+ * DNS pinning (crochet_patterns-yfj8 #1, design D5): when `fetch` is not
+ * injected, requests go through npm `undici` with an Agent whose
+ * `connect.lookup` is `pinnedLookup(lookup)`. The check runs inside the lookup
+ * the socket uses, so the address that is checked is the address that is
+ * connected to — a record that flips to a private IP between the pre-flight
+ * check and connect is refused at connect.
+ *
+ * `lookup` and `fetch` are injectable so tests never touch the network.
+ */
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { isIP, type LookupFunction } from 'node:net';
+import { Agent, fetch as undiciFetch } from 'undici';
+
+export type SafeFetchErrorCode =
+  | 'BAD_URL'
+  | 'BLOCKED_ADDRESS'
+  | 'TOO_MANY_REDIRECTS'
+  | 'UNSUPPORTED_TYPE'
+  | 'TOO_LARGE'
+  | 'TIMEOUT'
+  | 'HTTP_ERROR';
+
+export class SafeFetchError extends Error {
+  constructor(
+    message: string,
+    public readonly code: SafeFetchErrorCode,
+    /** The hop that was refused, when there is one. */
+    public readonly url?: string,
+  ) {
+    super(message);
+    this.name = 'SafeFetchError';
+  }
+}
+
+export interface ResolvedAddress {
+  address: string;
+  family: 4 | 6;
+}
+
+export interface SafeFetchOptions {
+  /** Allowed content types (parameters like `; charset=` are ignored). Default text/html + application/pdf. */
+  allowTypes?: string[];
+  /** Byte cap on the body. Default 5 MB. */
+  maxBytes?: number;
+  /** Redirect hops allowed. Default 3. */
+  maxRedirects?: number;
+  /** Whole-request time cap. Default 10 s. */
+  timeoutMs?: number;
+  /** Resolves a hostname to ALL its addresses. Default: node:dns lookup({all:true}). */
+  lookup?: (hostname: string) => Promise<ResolvedAddress[]>;
+  /** Default: npm undici fetch with a DNS-pinning Agent (see `pinnedLookup`). */
+  fetch?: typeof fetch;
+}
+
+export interface SafeFetchResult {
+  /** The url that finally answered (after redirects). */
+  finalUrl: string;
+  status: number;
+  /** Bare media type, e.g. `text/html`. */
+  contentType: string;
+  body: Uint8Array;
+}
+
+export const SAFE_FETCH_DEFAULTS = {
+  allowTypes: ['text/html', 'application/pdf'],
+  maxBytes: 5 * 1024 * 1024,
+  maxRedirects: 3,
+  timeoutMs: 10_000,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Address blocklist
+// ---------------------------------------------------------------------------
+
+function parseV4(addr: string): number[] | null {
+  const parts = addr.split('.');
+  if (parts.length !== 4) return null;
+  const bytes = parts.map((p) => (/^\d{1,3}$/.test(p) ? Number(p) : NaN));
+  return bytes.every((b) => b >= 0 && b <= 255) ? bytes : null;
+}
+
+function parseV6(addr: string): number[] | null {
+  let s = addr.toLowerCase();
+  const zone = s.indexOf('%');
+  if (zone !== -1) s = s.slice(0, zone);
+  // A trailing dotted quad (::ffff:1.2.3.4) becomes two hextets.
+  const lastColon = s.lastIndexOf(':');
+  const tail = s.slice(lastColon + 1);
+  if (tail.includes('.')) {
+    const v4 = parseV4(tail);
+    if (!v4) return null;
+    s = `${s.slice(0, lastColon + 1)}${((v4[0]! << 8) | v4[1]!).toString(16)}:${((v4[2]! << 8) | v4[3]!).toString(16)}`;
+  }
+  const halves = s.split('::');
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(':') : [];
+  const rest = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+  const missing = 8 - head.length - rest.length;
+  if (halves.length === 1 ? missing !== 0 : missing < 1) return null;
+  const hextets = [...head, ...Array<string>(halves.length === 2 ? missing : 0).fill('0'), ...rest];
+  const bytes: number[] = [];
+  for (const h of hextets) {
+    if (!/^[0-9a-f]{1,4}$/.test(h)) return null;
+    const n = parseInt(h, 16);
+    bytes.push(n >> 8, n & 0xff);
+  }
+  return bytes;
+}
+
+function isBlockedV4([a, b, c]: number[]): boolean {
+  return (
+    a === 0 || // 0/8 "this network", incl. 0.0.0.0
+    a === 10 || // 10/8
+    a === 127 || // loopback
+    (a === 100 && b! >= 64 && b! <= 127) || // 100.64/10 CGNAT
+    (a === 169 && b === 254) || // link-local, incl. cloud metadata 169.254.169.254
+    (a === 172 && b! >= 16 && b! <= 31) || // 172.16/12
+    (a === 192 && b === 0 && c === 0) || // 192.0.0/24 IETF protocol assignments
+    (a === 192 && b === 168) || // 192.168/16
+    (a === 198 && (b === 18 || b === 19)) || // 198.18/15 benchmarking
+    a! >= 224 // 224/4 multicast, 240/4 reserved, 255.255.255.255
+  );
+}
+
+function startsWith(bytes: number[], prefix: number[]): boolean {
+  return prefix.every((b, i) => bytes[i] === b);
+}
+
+function isBlockedV6(bytes: number[]): boolean {
+  const first = bytes[0]!;
+  if ((first & 0xfe) === 0xfc) return true; // fc00::/7 unique local
+  if (first === 0xfe && (bytes[1]! & 0xc0) === 0x80) return true; // fe80::/10 link-local
+  if (first === 0xfe && (bytes[1]! & 0xc0) === 0xc0) return true; // fec0::/10 site-local (deprecated)
+  if (first === 0xff) return true; // ff00::/8 multicast
+  const zero = (n: number) => Array<number>(n).fill(0);
+  // ::/96 — :: and ::1 and the deprecated v4-compatible form; checked as the embedded v4
+  // (::  -> 0.0.0.0, ::1 -> 0.0.0.1, both in 0/8).
+  if (startsWith(bytes, zero(12))) return isBlockedV4(bytes.slice(12));
+  // ::ffff:0:0/96 v4-mapped
+  if (startsWith(bytes, [...zero(10), 0xff, 0xff])) return isBlockedV4(bytes.slice(12));
+  // 64:ff9b::/96 NAT64 well-known prefix
+  if (startsWith(bytes, [0x00, 0x64, 0xff, 0x9b, ...zero(8)])) return isBlockedV4(bytes.slice(12));
+  // 64:ff9b:1::/48 local-use NAT64 — translates to whatever the local network chooses
+  if (startsWith(bytes, [0x00, 0x64, 0xff, 0x9b, 0x00, 0x01])) return true;
+  // 2002::/16 6to4 — the v4 is bytes 2..5
+  if (bytes[0] === 0x20 && bytes[1] === 0x02) return isBlockedV4(bytes.slice(2, 6));
+  return false;
+}
+
+/**
+ * True when a connection to `addr` must be refused: loopback, private,
+ * link-local (cloud metadata), CGNAT, benchmarking, multicast, reserved, the
+ * unspecified address, IPv6 loopback/ULA/link-local/multicast, and any IPv6
+ * form that embeds a blocked IPv4 (mapped, compatible, NAT64, 6to4).
+ * Anything that does not parse as an IP is refused (fail closed).
+ */
+export function isBlockedAddress(addr: string): boolean {
+  const s = addr.startsWith('[') && addr.endsWith(']') ? addr.slice(1, -1) : addr;
+  const family = isIP(s.split('%')[0]!);
+  if (family === 4) {
+    const v4 = parseV4(s);
+    return !v4 || isBlockedV4(v4);
+  }
+  if (family === 6) {
+    const v6 = parseV6(s);
+    return !v6 || isBlockedV6(v6);
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// DNS
+// ---------------------------------------------------------------------------
+
+async function dnsLookupAll(hostname: string): Promise<ResolvedAddress[]> {
+  const addrs = await dnsLookup(hostname, { all: true, verbatim: true });
+  return addrs.map((a) => ({ address: a.address, family: a.family === 6 ? 6 : 4 }));
+}
+
+/** Resolves `hostname` and throws BLOCKED_ADDRESS if ANY answer is blocked. */
+async function resolveChecked(
+  resolve: (hostname: string) => Promise<ResolvedAddress[]>,
+  hostname: string,
+  url?: string,
+): Promise<ResolvedAddress[]> {
+  let addrs: ResolvedAddress[];
+  try {
+    addrs = await resolve(hostname);
+  } catch (err) {
+    throw new SafeFetchError(`Could not resolve ${hostname}: ${(err as Error)?.message ?? err}`, 'BAD_URL', url);
+  }
+  if (!addrs.length) throw new SafeFetchError(`Could not resolve ${hostname}`, 'BAD_URL', url);
+  const blocked = addrs.find((a) => isBlockedAddress(a.address));
+  if (blocked) {
+    throw new SafeFetchError(`${hostname} resolves to a blocked address (${blocked.address})`, 'BLOCKED_ADDRESS', url);
+  }
+  return addrs;
+}
+
+/**
+ * A `dns.lookup`-shaped function for `net.connect` / undici `connect.lookup`.
+ * It resolves with `resolve`, refuses the whole answer if any address is
+ * blocked, and hands the socket only the addresses it validated — so the
+ * connection goes to an address that was checked, not to a second resolution.
+ * Handles both callback forms (`{all:true}` → array; otherwise address+family).
+ */
+export function pinnedLookup(resolve: SafeFetchOptions['lookup'] = dnsLookupAll): LookupFunction {
+  return (hostname, options, callback) => {
+    const wanted = options?.family === 4 || (options?.family as unknown) === 'IPv4' ? 4
+      : options?.family === 6 || (options?.family as unknown) === 'IPv6' ? 6 : 0;
+    resolveChecked(resolve, hostname).then(
+      (addrs) => {
+        const list = wanted ? addrs.filter((a) => a.family === wanted) : addrs;
+        if (!list.length) {
+          const err = Object.assign(new Error(`No IPv${wanted} address for ${hostname}`), { code: 'ENOTFOUND' });
+          callback(err, '', 0);
+          return;
+        }
+        if (options?.all) callback(null, list.map((a) => ({ address: a.address, family: a.family })));
+        else callback(null, list[0]!.address, list[0]!.family);
+      },
+      (err: Error) => callback(err as NodeJS.ErrnoException, '', 0),
+    );
+  };
+}
+
+// ---------------------------------------------------------------------------
+// safeFetch
+// ---------------------------------------------------------------------------
+
+function parseHopUrl(raw: string | URL, base?: URL): URL {
+  let url: URL;
+  try {
+    url = new URL(raw, base);
+  } catch {
+    throw new SafeFetchError(`Not a valid url: ${String(raw)}`, 'BAD_URL', String(raw));
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new SafeFetchError(`Only http and https urls are allowed (got ${url.protocol})`, 'BAD_URL', url.href);
+  }
+  if (url.username || url.password) {
+    throw new SafeFetchError('Urls with credentials are not allowed', 'BAD_URL', url.href);
+  }
+  return url;
+}
+
+function bareHost(url: URL): string {
+  const h = url.hostname;
+  return h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h;
+}
+
+/** Rejects as soon as `signal` aborts, so a hung resolver cannot outlive the time cap. */
+function untilAborted<T>(p: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(new SafeFetchError('Timed out', 'TIMEOUT'));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new SafeFetchError('Timed out', 'TIMEOUT'));
+    signal.addEventListener('abort', onAbort, { once: true });
+    p.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+  });
+}
+
+/** undici wraps connect failures as `TypeError('fetch failed', { cause })`. */
+function findSafeFetchError(err: unknown): SafeFetchError | undefined {
+  for (let e: unknown = err, depth = 0; e && depth < 5; e = (e as { cause?: unknown }).cause, depth++) {
+    if (e instanceof SafeFetchError) return e;
+  }
+  return undefined;
+}
+
+async function readCapped(res: Response, maxBytes: number, url: string): Promise<Uint8Array> {
+  if (!res.body) return new Uint8Array(0);
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => undefined);
+      throw new SafeFetchError(`Response is larger than ${maxBytes} bytes`, 'TOO_LARGE', url);
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    body.set(c, offset);
+    offset += c.byteLength;
+  }
+  return body;
+}
+
+export async function safeFetch(url: string, options: SafeFetchOptions = {}): Promise<SafeFetchResult> {
+  const allowTypes = (options.allowTypes ?? SAFE_FETCH_DEFAULTS.allowTypes).map((t) => t.toLowerCase());
+  const maxBytes = options.maxBytes ?? SAFE_FETCH_DEFAULTS.maxBytes;
+  const maxRedirects = options.maxRedirects ?? SAFE_FETCH_DEFAULTS.maxRedirects;
+  const timeoutMs = options.timeoutMs ?? SAFE_FETCH_DEFAULTS.timeoutMs;
+  const resolve = options.lookup ?? dnsLookupAll;
+
+  let current = parseHopUrl(url);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let agent: Agent | undefined;
+  let fetchImpl: (input: string, init: RequestInit) => Promise<Response>;
+  if (options.fetch) {
+    fetchImpl = options.fetch;
+  } else {
+    // npm undici's own fetch: a npm-undici dispatcher must not be handed to Node's global fetch.
+    const pinned = new Agent({ connect: { lookup: pinnedLookup(resolve) } });
+    agent = pinned;
+    fetchImpl = (input, init) =>
+      undiciFetch(input, { ...(init as Parameters<typeof undiciFetch>[1]), dispatcher: pinned }) as unknown as Promise<Response>;
+  }
+
+  try {
+    for (let hop = 0; ; hop++) {
+      const host = bareHost(current);
+      // Pre-flight: an IP literal is checked as-is (never resolved); a name is resolved and every answer checked.
+      if (isIP(host)) {
+        if (isBlockedAddress(host)) {
+          throw new SafeFetchError(`Blocked address ${host}`, 'BLOCKED_ADDRESS', current.href);
+        }
+      } else {
+        await untilAborted(resolveChecked(resolve, host, current.href), controller.signal);
+      }
+
+      const res = await fetchImpl(current.href, { redirect: 'manual', signal: controller.signal });
+
+      if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get('location');
+        await res.body?.cancel().catch(() => undefined);
+        if (!location) throw new SafeFetchError(`HTTP ${res.status} without a Location`, 'HTTP_ERROR', current.href);
+        if (hop >= maxRedirects) {
+          throw new SafeFetchError(`More than ${maxRedirects} redirects`, 'TOO_MANY_REDIRECTS', current.href);
+        }
+        current = parseHopUrl(location, current);
+        continue;
+      }
+
+      if (!res.ok) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new SafeFetchError(`HTTP ${res.status}`, 'HTTP_ERROR', current.href);
+      }
+
+      const contentType = (res.headers.get('content-type') ?? '').split(';')[0]!.trim().toLowerCase();
+      if (!contentType || !allowTypes.includes(contentType)) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new SafeFetchError(`Unsupported content type: ${contentType || '(none)'}`, 'UNSUPPORTED_TYPE', current.href);
+      }
+
+      const declared = Number(res.headers.get('content-length'));
+      if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new SafeFetchError(`Response is larger than ${maxBytes} bytes`, 'TOO_LARGE', current.href);
+      }
+
+      const body = await readCapped(res, maxBytes, current.href);
+      return { finalUrl: current.href, status: res.status, contentType, body };
+    }
+  } catch (err) {
+    const own = findSafeFetchError(err);
+    if (own) throw own;
+    if (controller.signal.aborted) throw new SafeFetchError(`Timed out after ${timeoutMs} ms`, 'TIMEOUT', current.href);
+    throw new SafeFetchError(`Fetch failed: ${(err as Error)?.message ?? err}`, 'HTTP_ERROR', current.href);
+  } finally {
+    clearTimeout(timer);
+    if (agent) void agent.destroy().catch(() => undefined);
+  }
+}