@stigmer/runner 3.4.1 → 3.5.0

package/src/tools/__tests__/url-guard.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from "vitest";
+import {
+  blockedReason,
+  resolveGuardPosture,
+  validateFetchUrl,
+  UrlGuardError,
+} from "../url-guard.js";
+
+describe("resolveGuardPosture", () => {
+  it("defaults to strict on cloud runners", () => {
+    expect(resolveGuardPosture("cloud", {})).toBe("strict");
+  });
+
+  it("defaults to relaxed on local runners", () => {
+    expect(resolveGuardPosture("local", {})).toBe("relaxed");
+  });
+
+  it("override=true relaxes a cloud runner", () => {
+    expect(resolveGuardPosture("cloud", { STIGMER_WEB_FETCH_ALLOW_PRIVATE: "true" })).toBe("relaxed");
+  });
+
+  it("override=false hardens a local runner", () => {
+    expect(resolveGuardPosture("local", { STIGMER_WEB_FETCH_ALLOW_PRIVATE: "false" })).toBe("strict");
+  });
+
+  it("ignores malformed override values", () => {
+    expect(resolveGuardPosture("cloud", { STIGMER_WEB_FETCH_ALLOW_PRIVATE: "yes" })).toBe("strict");
+  });
+});
+
+describe("blockedReason — strict posture", () => {
+  it.each([
+    ["127.0.0.1", "loopback"],
+    ["127.255.255.255", "loopback"],
+    ["0.0.0.0", "unspecified"],
+    ["10.0.0.1", "private (RFC 1918)"],
+    ["172.16.0.1", "private (RFC 1918)"],
+    ["172.31.255.255", "private (RFC 1918)"],
+    ["192.168.1.1", "private (RFC 1918)"],
+    ["169.254.169.254", "link-local (cloud metadata)"],
+    ["169.254.0.1", "link-local (cloud metadata)"],
+  ])("blocks %s as %s", (address, reason) => {
+    expect(blockedReason(address, "strict")).toBe(reason);
+  });
+
+  it.each(["8.8.8.8", "104.16.0.1", "172.15.0.1", "172.32.0.1", "192.169.0.1"])(
+    "allows public IPv4 %s",
+    (address) => {
+      expect(blockedReason(address, "strict")).toBeNull();
+    },
+  );
+
+  it.each([
+    ["::1", "loopback"],
+    ["::", "unspecified"],
+    ["fc00::1", "private (unique local)"],
+    ["fd12:3456::1", "private (unique local)"],
+    ["fe80::1", "link-local (cloud metadata)"],
+    ["febf::1", "link-local (cloud metadata)"],
+  ])("blocks IPv6 %s as %s", (address, reason) => {
+    expect(blockedReason(address, "strict")).toBe(reason);
+  });
+
+  it("allows public IPv6", () => {
+    expect(blockedReason("2606:4700::6810:1", "strict")).toBeNull();
+  });
+
+  it("blocks IPv4-mapped IPv6 carrying a blocked v4 (dotted form)", () => {
+    expect(blockedReason("::ffff:127.0.0.1", "strict")).toBe("loopback");
+    expect(blockedReason("::ffff:10.0.0.1", "strict")).toBe("private (RFC 1918)");
+  });
+
+  it("blocks IPv4-mapped IPv6 carrying a blocked v4 (hex form)", () => {
+    // ::ffff:7f00:1 is 127.0.0.1 — the hex spelling must not bypass the guard.
+    expect(blockedReason("::ffff:7f00:1", "strict")).toBe("loopback");
+    expect(blockedReason("::ffff:a9fe:a9fe", "strict")).toBe("link-local (cloud metadata)");
+  });
+
+  it("allows IPv4-mapped IPv6 carrying a public v4", () => {
+    expect(blockedReason("::ffff:8.8.8.8", "strict")).toBeNull();
+  });
+
+  it("fails closed on garbage", () => {
+    expect(blockedReason("not-an-ip", "strict")).toBe("unrecognized");
+  });
+});
+
+describe("blockedReason — relaxed posture", () => {
+  it.each(["127.0.0.1", "10.0.0.1", "192.168.1.1", "::1", "fd00::1"])(
+    "allows private/loopback %s (the machine belongs to the user)",
+    (address) => {
+      expect(blockedReason(address, "relaxed")).toBeNull();
+    },
+  );
+
+  it("still blocks the cloud metadata range", () => {
+    expect(blockedReason("169.254.169.254", "relaxed")).toBe("link-local (cloud metadata)");
+    expect(blockedReason("fe80::1", "relaxed")).toBe("link-local (cloud metadata)");
+    expect(blockedReason("::ffff:169.254.169.254", "relaxed")).toBe("link-local (cloud metadata)");
+  });
+});
+
+describe("validateFetchUrl", () => {
+  it("rejects malformed URLs", async () => {
+    await expect(validateFetchUrl("not a url", "strict")).rejects.toThrow(UrlGuardError);
+  });
+
+  it.each(["file:///etc/passwd", "ftp://example.com/x", "gopher://example.com"])(
+    "rejects non-http(s) scheme %s",
+    async (url) => {
+      await expect(validateFetchUrl(url, "strict")).rejects.toThrow(/only http and https/);
+    },
+  );
+
+  it("rejects literal blocked IPs without a DNS lookup", async () => {
+    await expect(validateFetchUrl("http://127.0.0.1:8080/x", "strict")).rejects.toThrow(/loopback/);
+    await expect(validateFetchUrl("http://169.254.169.254/latest/meta-data", "strict"))
+      .rejects.toThrow(/cloud metadata/);
+    await expect(validateFetchUrl("http://[::1]/", "strict")).rejects.toThrow(/loopback/);
+  });
+
+  it("allows literal loopback under the relaxed posture", async () => {
+    const url = await validateFetchUrl("http://127.0.0.1:3000/api", "relaxed");
+    expect(url.hostname).toBe("127.0.0.1");
+  });
+
+  it("rejects hostnames that resolve to blocked addresses", async () => {
+    // localhost resolves to 127.0.0.1 / ::1 everywhere.
+    await expect(validateFetchUrl("http://localhost:9999/", "strict")).rejects.toThrow(UrlGuardError);
+  });
+
+  it("rejects unresolvable hostnames", async () => {
+    await expect(
+      validateFetchUrl("http://definitely-not-a-real-host.stigmer.invalid/", "strict"),
+    ).rejects.toThrow(/Could not resolve/);
+  });
+});

package/src/tools/__tests__/web-fetch-tool.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createWebFetchTool } from "../web-fetch-tool.js";
+
+// Hostnames are literal public IPs throughout so the URL guard classifies
+// them without a DNS lookup — tests stay hermetic even though fetch itself
+// is mocked.
+const PUBLIC_URL = "http://8.8.8.8/page";
+
+const fetchMock = vi.fn();
+
+function textResponse(
+  body: string,
+  init: { status?: number; contentType?: string; headers?: Record<string, string> } = {},
+): Response {
+  return new Response(body, {
+    status: init.status ?? 200,
+    headers: { "content-type": init.contentType ?? "text/plain; charset=utf-8", ...init.headers },
+  });
+}
+
+function redirectResponse(location: string, status = 302): Response {
+  return new Response(null, { status, headers: { location } });
+}
+
+beforeEach(() => {
+  vi.stubGlobal("fetch", fetchMock);
+  fetchMock.mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+const invoke = (
+  input: { url: string; max_length?: number; start_index?: number },
+  posture: "strict" | "relaxed" = "strict",
+) => createWebFetchTool({ posture }).invoke(input) as Promise<string>;
+
+describe("web_fetch — identity", () => {
+  it("is named web_fetch with a url-first schema", () => {
+    const t = createWebFetchTool({ posture: "strict" });
+    expect(t.name).toBe("web_fetch");
+    expect(t.description).toContain("Fetch the contents of a URL");
+  });
+});
+
+describe("web_fetch — content handling", () => {
+  it("converts HTML to Markdown and strips chrome", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse(
+      `<html><head><title>T</title><script>evil()</script><style>.x{}</style></head>
+       <body><nav><a href="/home">Home</a></nav>
+       <h1>Docs</h1><p>Hello <a href="https://stigmer.ai">Stigmer</a>.</p>
+       <footer>© 2026</footer></body></html>`,
+      { contentType: "text/html" },
+    ));
+
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("# Docs");
+    expect(result).toContain("[Stigmer](https://stigmer.ai)");
+    expect(result).not.toContain("evil()");
+    expect(result).not.toContain(".x{}");
+    expect(result).not.toContain("Home");
+    expect(result).not.toContain("© 2026");
+  });
+
+  it("returns non-HTML text verbatim", async () => {
+    const markdown = "# Already markdown\n\nplain content";
+    fetchMock.mockResolvedValueOnce(textResponse(markdown, { contentType: "text/markdown" }));
+    await expect(invoke({ url: PUBLIC_URL })).resolves.toBe(markdown);
+  });
+
+  it("treats a missing content-type as text", async () => {
+    const response = new Response("raw", { status: 200 });
+    response.headers.delete("content-type");
+    fetchMock.mockResolvedValueOnce(response);
+    await expect(invoke({ url: PUBLIC_URL })).resolves.toBe("raw");
+  });
+
+  it("refuses binary content", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse("\x89PNG", { contentType: "image/png" }));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toMatch(/^Error: .*non-text content \(image\/png\)/);
+  });
+
+  it("reports HTTP error statuses", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse("gone", { status: 404 }));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("Error:");
+    expect(result).toContain("404");
+  });
+
+  it("describes an empty body instead of returning nothing", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse(""));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("empty body");
+  });
+});
+
+describe("web_fetch — pagination", () => {
+  const body = "abcdefghij".repeat(10); // 100 chars
+
+  it("windows content by max_length with a continuation notice", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse(body));
+    const result = await invoke({ url: PUBLIC_URL, max_length: 40 });
+    expect(result.startsWith(body.slice(0, 40))).toBe(true);
+    expect(result).toContain("truncated at 40 of 100");
+    expect(result).toContain("start_index=40");
+  });
+
+  it("continues from start_index without a notice at the end", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse(body));
+    const result = await invoke({ url: PUBLIC_URL, max_length: 60, start_index: 40 });
+    expect(result).toBe(body.slice(40));
+  });
+
+  it("rejects a start_index past the end", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse(body));
+    const result = await invoke({ url: PUBLIC_URL, start_index: 500 });
+    expect(result).toContain("Error: start_index 500 is beyond the end");
+  });
+
+  it("caps unbounded responses at the byte limit and says so", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse("a".repeat(2 * 1024 * 1024 + 100)));
+    const result = await invoke({ url: PUBLIC_URL, max_length: 50 });
+    expect(result).toContain("exceeded the 2 MB fetch limit");
+  });
+});
+
+describe("web_fetch — redirects", () => {
+  it("follows redirects and resolves relative Location headers", async () => {
+    fetchMock
+      .mockResolvedValueOnce(redirectResponse("/moved"))
+      .mockResolvedValueOnce(textResponse("landed"));
+
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toBe("landed");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[1][0])).toBe("http://8.8.8.8/moved");
+  });
+
+  it("re-guards every hop — a redirect into a private address is refused", async () => {
+    fetchMock.mockResolvedValueOnce(redirectResponse("http://10.0.0.1/internal"));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toMatch(/^Error: .*private/);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("gives up after too many redirects", async () => {
+    fetchMock.mockResolvedValue(redirectResponse("/again"));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("too many redirects");
+  });
+
+  it("fails on a redirect without a Location header", async () => {
+    fetchMock.mockResolvedValueOnce(new Response(null, { status: 302 }));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("without a Location header");
+  });
+});
+
+describe("web_fetch — guard and failure surface", () => {
+  it("refuses blocked addresses under the strict posture", async () => {
+    const result = await invoke({ url: "http://127.0.0.1:8080/x" });
+    expect(result).toMatch(/^Error: .*loopback/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("allows loopback under the relaxed posture", async () => {
+    fetchMock.mockResolvedValueOnce(textResponse("local dev server"));
+    const result = await invoke({ url: "http://127.0.0.1:3000/" }, "relaxed");
+    expect(result).toBe("local dev server");
+  });
+
+  it("refuses non-http schemes", async () => {
+    const result = await invoke({ url: "file:///etc/passwd" });
+    expect(result).toMatch(/^Error: .*only http and https/);
+  });
+
+  it("reports timeouts as a readable error", async () => {
+    fetchMock.mockRejectedValueOnce(
+      Object.assign(new Error("operation timed out"), { name: "TimeoutError" }),
+    );
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("timed out after 15s");
+  });
+
+  it("reports network failures without throwing", async () => {
+    fetchMock.mockRejectedValueOnce(new Error("socket hang up"));
+    const result = await invoke({ url: PUBLIC_URL });
+    expect(result).toContain("Error: Failed to fetch");
+    expect(result).toContain("socket hang up");
+  });
+});

package/src/tools/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Native built-in tools for the deep-agent harness.
+ *
+ * These are Stigmer-authored capabilities appended to the agent's tool list
+ * in execute-deep-agent/setup.ts (and mirrored for sub-agents in
+ * subagent-transformer.ts) — distinct from deepagents' backend tools
+ * (ls/read_file/execute/…) and from MCP tools, which arrive via the
+ * connection layer.
+ *
+ * Contract for adding a native tool (what keeps the two harnesses at parity):
+ *
+ * 1. Name it in snake_case (`web_fetch`, not `WebFetch` — PascalCase names
+ *    belong to the Cursor harness).
+ * 2. Register the name in shared/tool-kind.ts `TOOL_NAME_TO_KIND` and its
+ *    lockstep mirrors (test/fixtures/tool-view/classification.json, the SDK
+ *    fallback resolver), and extend the ToolKind enum comment in
+ *    agentexecution/v1/enum.proto with a `Native:` clause.
+ * 3. Name the primary argument to match the SDK's presentation `primaryField`
+ *    for the tool's kind (sdk/react tool-categories.ts) so both harnesses
+ *    render identically.
+ * 4. Decide the approval posture explicitly: unless the tool's kind maps to
+ *    an approval category in `toolApprovalCategory`, it is auto-approved.
+ */
+
+export { createThinkTool } from "./think-tool.js";
+export { createWebFetchTool } from "./web-fetch-tool.js";
+export { validateFetchUrl, resolveGuardPosture, UrlGuardError } from "./url-guard.js";
+export type { GuardPosture } from "./url-guard.js";

package/src/tools/url-guard.ts

@@ -0,0 +1,232 @@
+/**
+ * URL guard for the native `web_fetch` tool — the SSRF boundary.
+ *
+ * Why this is load-bearing: `web_fetch` is deliberately auto-approved (see
+ * shared/tool-kind.ts `toolApprovalCategory`), so in unattended runs it is
+ * the only ungated network path an agent has. On managed cloud runners the
+ * fetch executes inside the runner process, which sits on infrastructure
+ * with network reach to internal services and the cloud metadata endpoint —
+ * without this guard, "fetch a URL" becomes "read my pod's credentials".
+ *
+ * Posture is mode-aware because locality differs, not trust:
+ *
+ * - "strict" (managed cloud runners): loopback, RFC 1918 private,
+ *   link-local, and their IPv6 equivalents are all rejected.
+ * - "relaxed" (self-hosted / local runners): the machine belongs to the
+ *   user, and fetching their own dev server (http://localhost:3000) is a
+ *   legitimate ask — only the link-local range (which contains the cloud
+ *   metadata endpoint 169.254.169.254) stays blocked, as costless
+ *   defense-in-depth.
+ *
+ * The default posture derives from Config.mode ("cloud" → strict), NOT from
+ * cloudModeEnabled — that is the Cursor cloud-agent feature flag and says
+ * nothing about where this process runs. Config.mode tracks credential
+ * transport rather than physical locality (a desktop runner proxies traffic
+ * while executing on the user's machine), so STIGMER_WEB_FETCH_ALLOW_PRIVATE
+ * exists as an explicit override for embedders that know better. Managed
+ * cloud deployments never set it.
+ *
+ * Validation runs on the addresses DNS resolves to immediately before the
+ * request is dispatched, and the caller re-validates every redirect hop.
+ * Accepted limitation: a DNS-rebinding window remains between our lookup
+ * and the socket connect — Node's fetch (undici) offers no lookup pinning
+ * without replacing the dispatcher, and the strict posture's range blocks
+ * make the rebinding payoff (an internal address) unreachable anyway.
+ */
+
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+export type GuardPosture = "strict" | "relaxed";
+
+/** Thrown for every guard rejection; message is safe to surface to the model. */
+export class UrlGuardError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UrlGuardError";
+  }
+}
+
+/**
+ * Derive the guard posture from runner mode plus the explicit override.
+ *
+ * @param mode Config.mode — "cloud" means a managed runner on shared infrastructure.
+ * @param env  Environment to read STIGMER_WEB_FETCH_ALLOW_PRIVATE from.
+ */
+export function resolveGuardPosture(
+  mode: "local" | "cloud",
+  env: NodeJS.ProcessEnv = process.env,
+): GuardPosture {
+  const override = env.STIGMER_WEB_FETCH_ALLOW_PRIVATE;
+  if (override === "true") return "relaxed";
+  if (override === "false") return "strict";
+  return mode === "cloud" ? "strict" : "relaxed";
+}
+
+/**
+ * Validate a URL for fetching under the given posture.
+ *
+ * Checks the scheme, then resolves the hostname and checks EVERY address it
+ * resolves to (a hostname with one public and one private A record must be
+ * rejected, or the private record becomes the bypass).
+ *
+ * @returns the parsed URL on success.
+ * @throws UrlGuardError with a model-readable reason on rejection.
+ */
+export async function validateFetchUrl(
+  rawUrl: string,
+  posture: GuardPosture,
+): Promise<URL> {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new UrlGuardError(`Invalid URL: ${rawUrl}`);
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new UrlGuardError(
+      `Unsupported URL scheme "${url.protocol.replace(/:$/, "")}" — only http and https are allowed.`,
+    );
+  }
+
+  const addresses = await resolveAddresses(url.hostname);
+  for (const address of addresses) {
+    const reason = blockedReason(address, posture);
+    if (reason) {
+      throw new UrlGuardError(
+        `Refusing to fetch ${url.hostname}: it resolves to ${address}, a ${reason} address that this runner does not fetch from.`,
+      );
+    }
+  }
+
+  return url;
+}
+
+/**
+ * Resolve a hostname to all of its addresses. Literal IPs pass through
+ * (bracketed IPv6 hosts arrive from URL.hostname still bracketed).
+ */
+async function resolveAddresses(hostname: string): Promise<string[]> {
+  const literal = hostname.replace(/^\[|\]$/g, "");
+  if (isIP(literal) !== 0) {
+    return [literal];
+  }
+
+  try {
+    const records = await lookup(hostname, { all: true, verbatim: true });
+    return records.map((r) => r.address);
+  } catch {
+    throw new UrlGuardError(`Could not resolve hostname: ${hostname}`);
+  }
+}
+
+/**
+ * Classify an IP address against the posture's blocked ranges.
+ *
+ * @returns a human-readable range name when blocked, or null when allowed.
+ */
+export function blockedReason(address: string, posture: GuardPosture): string | null {
+  const family = isIP(address);
+
+  if (family === 4) {
+    return blockedReasonV4(address, posture);
+  }
+
+  if (family === 6) {
+    const groups = expandV6(address);
+    if (!groups) return "unrecognized";
+
+    // IPv4-mapped IPv6 (::ffff:a.b.c.d, in dotted OR hex form) — classify
+    // the embedded IPv4 so the mapping cannot smuggle a blocked v4 address
+    // past the guard.
+    const embedded = extractMappedV4(groups);
+    if (embedded) {
+      return blockedReasonV4(embedded, posture);
+    }
+    return blockedReasonV6(groups, posture);
+  }
+
+  // Unparseable — fail closed; only real addresses get sockets.
+  return "unrecognized";
+}
+
+function blockedReasonV4(address: string, posture: GuardPosture): string | null {
+  const octets = address.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
+    return "unrecognized";
+  }
+  const [a, b] = octets;
+
+  // Link-local (169.254.0.0/16) hosts the cloud metadata service at
+  // 169.254.169.254 — blocked under BOTH postures.
+  if (a === 169 && b === 254) return "link-local (cloud metadata)";
+
+  if (posture === "relaxed") return null;
+
+  if (a === 127) return "loopback";
+  if (a === 0) return "unspecified";
+  if (a === 10) return "private (RFC 1918)";
+  if (a === 172 && b >= 16 && b <= 31) return "private (RFC 1918)";
+  if (a === 192 && b === 168) return "private (RFC 1918)";
+
+  return null;
+}
+
+function blockedReasonV6(groups: readonly number[], posture: GuardPosture): string | null {
+  // fe80::/10 — IPv6 link-local, the v6 sibling of the metadata range;
+  // blocked under BOTH postures for symmetry with v4.
+  if ((groups[0] & 0xffc0) === 0xfe80) return "link-local (cloud metadata)";
+
+  if (posture === "relaxed") return null;
+
+  const allZero = groups.every((g) => g === 0);
+  if (allZero) return "unspecified";
+  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return "loopback";
+  // fc00::/7 — unique local (private) addresses.
+  if ((groups[0] & 0xfe00) === 0xfc00) return "private (unique local)";
+
+  return null;
+}
+
+/**
+ * Expand an IPv6 address (already validated by isIP) into its 8 groups.
+ * Handles `::` compression, a trailing dotted-IPv4 tail, and zone suffixes.
+ */
+function expandV6(address: string): number[] | null {
+  let text = address.toLowerCase().split("%")[0];
+
+  // Convert a dotted-IPv4 tail (e.g. ::ffff:127.0.0.1) into two hex groups.
+  const v4Tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  if (v4Tail) {
+    const octets = v4Tail[1].split(".").map(Number);
+    if (octets.length !== 4 || octets.some((o) => o > 255)) return null;
+    const hex = `${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+    text = text.slice(0, -v4Tail[1].length) + hex;
+  }
+
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+
+  const parseHalf = (half: string): number[] =>
+    half === "" ? [] : half.split(":").map((g) => parseInt(g, 16));
+
+  const head = parseHalf(halves[0]);
+  const tail = halves.length === 2 ? parseHalf(halves[1]) : [];
+  const fill = 8 - head.length - tail.length;
+  if (halves.length === 2 ? fill < 0 : head.length !== 8) return null;
+
+  const groups = [...head, ...(halves.length === 2 ? Array(fill).fill(0) : []), ...tail];
+  if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff)) {
+    return null;
+  }
+  return groups;
+}
+
+/** Extract the IPv4 payload from IPv4-mapped groups (::ffff:0:0/96), if any. */
+function extractMappedV4(groups: readonly number[]): string | null {
+  const isMapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
+  if (!isMapped) return null;
+  const [hi, lo] = [groups[6], groups[7]];
+  return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}