safe-fetch-mcp-server: Skill for Claude Code

Testing & Validation

Testing here is security testing. A fetch server that "works" is not enough — it must provably refuse the dangerous cases. Ordinary AI-generated tests only assert that valid URLs succeed; they never assert that internal targets are refused. Those refusals are the whole point.

1. Test-first, one test per threat

Write the failing test before the guard exists, then implement until green. There must be a test for every row of the threat matrix in the security skill. Minimum set:

• Refuse http://169.254.169.254/latest/meta-data/ (cloud metadata).
• Refuse loopback http://127.0.0.1, http://127.1.
• Refuse private ranges http://10.0.0.5, http://192.168.1.1.
• Refuse IPv4-mapped IPv6 loopback http://[::ffff:127.0.0.1].
• Refuse IPv6 loopback/ULA http://[::1].
• Refuse encoded IPs (octal/hex/decimal/dotless variants).
• Refuse a redirect whose next hop is internal (302 → http://127.0.0.1).
• Refuse non-http(s) schemes (file:, gopher:, ftp:).
• Refuse URLs with userinfo (http://user:pass@host).
• Enforce max-bytes truncation and timeouts.
• Regression: a re-fetch / poller path also goes through the guard (the 2026 bypass).
• Allow a normal public URL and return clean markdown.

Example (Vitest)

import { describe, it, expect } from "vitest";
import { assertSafeUrl } from "../src/security/index.js";

describe("SSRF guard", () => {
  it("refuses the cloud metadata endpoint", async () => {
    await expect(
      assertSafeUrl("http://169.254.169.254/latest/meta-data/")
    ).rejects.toThrow();
  });

  it("refuses IPv4-mapped IPv6 loopback", async () => {
    await expect(assertSafeUrl("http://[::ffff:127.0.0.1]/")).rejects.toThrow();
  });

  it("re-validates each redirect hop", async () => {
    // Spin up a local server that 302s to http://127.0.0.1 and assert the fetch is refused.
  });

  it("allows a normal public URL", async () => {
    await expect(assertSafeUrl("https://example.com")).resolves.toBeTruthy();
  });
});