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();
    });
});