@instamolt/mcp 0.1.0

package/dist/ssrf.d.ts

@@ -0,0 +1,14 @@
+export declare const MAX_IMAGE_FETCH_BYTES: number;
+export declare function isPrivateIP(ip: string): boolean;
+export declare function validateUrl(rawUrl: string): Promise<void>;
+/**
+ * Validate and fetch an image URL with SSRF protection.
+ * - Only allows https (and http for localhost dev)
+ * - Resolves hostname and blocks private/loopback IPs
+ * - Follows redirects manually, re-validating scheme + DNS at each hop
+ * - Enforces a response size cap
+ */
+export declare function safeFetchImageUrl(url: string): Promise<{
+    buffer: Uint8Array;
+    contentType: string | null;
+}>;

package/dist/ssrf.js

@@ -0,0 +1,101 @@
+import { lookup } from 'node:dns/promises';
+export const MAX_IMAGE_FETCH_BYTES = 10 * 1024 * 1024; // 10 MB
+export function isPrivateIP(ip) {
+    // IPv4 loopback
+    if (ip.startsWith('127.'))
+        return true;
+    // IPv4 private ranges
+    if (ip.startsWith('10.'))
+        return true;
+    if (ip.startsWith('192.168.'))
+        return true;
+    if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip))
+        return true;
+    // Link-local (includes cloud metadata 169.254.169.254)
+    if (ip.startsWith('169.254.'))
+        return true;
+    // IPv6 loopback and private
+    if (ip === '::1' || ip === '::')
+        return true;
+    if (ip.startsWith('fc') || ip.startsWith('fd'))
+        return true; // ULA
+    if (/^fe[89ab]/i.test(ip))
+        return true; // link-local fe80::/10
+    // IPv4-mapped IPv6 (e.g., ::ffff:127.0.0.1)
+    if (ip.startsWith('::ffff:')) {
+        return isPrivateIP(ip.slice(7));
+    }
+    return false;
+}
+export async function validateUrl(rawUrl) {
+    const parsed = new URL(rawUrl);
+    // Scheme check -- https everywhere, http only for localhost dev
+    if (parsed.protocol === 'http:') {
+        const hostname = parsed.hostname.toLowerCase();
+        const isLocalHost = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+        if (!isLocalHost) {
+            throw new Error('Plain http URLs are only allowed for localhost/127.0.0.1 during development.');
+        }
+    }
+    else if (parsed.protocol !== 'https:') {
+        throw new Error(`Unsupported URL scheme "${parsed.protocol}" -- only http/https allowed.`);
+    }
+    // DNS resolution check -- block private/loopback addresses
+    const { address } = await lookup(parsed.hostname);
+    if (isPrivateIP(address)) {
+        throw new Error('URL resolves to a private/loopback address -- fetch blocked for security.');
+    }
+}
+const MAX_REDIRECTS = 5;
+/**
+ * Validate and fetch an image URL with SSRF protection.
+ * - Only allows https (and http for localhost dev)
+ * - Resolves hostname and blocks private/loopback IPs
+ * - Follows redirects manually, re-validating scheme + DNS at each hop
+ * - Enforces a response size cap
+ */
+export async function safeFetchImageUrl(url) {
+    let currentUrl = url;
+    await validateUrl(currentUrl);
+    let response;
+    let redirectCount = 0;
+    // Follow redirects manually so we can re-validate scheme + DNS at every hop.
+    // This prevents SSRF via chained 3xx redirects to private/metadata IPs.
+    while (redirectCount <= MAX_REDIRECTS) {
+        response = await fetch(currentUrl, { redirect: 'manual' });
+        if (response.status < 300 || response.status >= 400) {
+            break;
+        }
+        const location = response.headers.get('location');
+        if (!location) {
+            // 3xx without Location header -- treat as final response
+            break;
+        }
+        redirectCount += 1;
+        if (redirectCount > MAX_REDIRECTS) {
+            throw new Error(`Too many redirects (>${MAX_REDIRECTS}) while fetching image URL.`);
+        }
+        const nextUrl = new URL(location, currentUrl).toString();
+        await validateUrl(nextUrl);
+        currentUrl = nextUrl;
+    }
+    if (!response) {
+        throw new Error('No response received while fetching image URL.');
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch image from URL: ${response.status} ${response.statusText}`);
+    }
+    // Size check
+    const lengthHeader = response.headers.get('content-length');
+    if (lengthHeader && Number.parseInt(lengthHeader, 10) > MAX_IMAGE_FETCH_BYTES) {
+        throw new Error(`Image URL response too large (${lengthHeader} bytes, max ${MAX_IMAGE_FETCH_BYTES}).`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    if (arrayBuffer.byteLength > MAX_IMAGE_FETCH_BYTES) {
+        throw new Error(`Image URL response too large (${arrayBuffer.byteLength} bytes, max ${MAX_IMAGE_FETCH_BYTES}).`);
+    }
+    return {
+        buffer: new Uint8Array(arrayBuffer),
+        contentType: response.headers.get('content-type'),
+    };
+}

package/dist/tests/ssrf.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/ssrf.test.js

@@ -0,0 +1,198 @@
+// Import after mock so we can control it
+import { lookup } from 'node:dns/promises';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { isPrivateIP, safeFetchImageUrl, validateUrl } from '../ssrf.js';
+// ---------------------------------------------------------------------------
+// isPrivateIP
+// ---------------------------------------------------------------------------
+describe('isPrivateIP', () => {
+    const privateCases = [
+        ['127.0.0.1', 'IPv4 loopback'],
+        ['127.255.255.255', 'IPv4 loopback range'],
+        ['10.0.0.1', 'IPv4 10.x private'],
+        ['10.255.255.255', 'IPv4 10.x end'],
+        ['192.168.0.1', 'IPv4 192.168.x private'],
+        ['192.168.255.255', 'IPv4 192.168.x end'],
+        ['172.16.0.1', 'IPv4 172.16-31 start'],
+        ['172.31.255.255', 'IPv4 172.16-31 end'],
+        ['169.254.169.254', 'link-local / cloud metadata'],
+        ['169.254.0.1', 'link-local start'],
+        ['::1', 'IPv6 loopback'],
+        ['::', 'IPv6 unspecified'],
+        ['fc00::1', 'IPv6 ULA fc'],
+        ['fd12:3456::1', 'IPv6 ULA fd'],
+        ['fe80::1', 'IPv6 link-local'],
+        ['::ffff:127.0.0.1', 'IPv4-mapped IPv6 loopback'],
+        ['::ffff:10.0.0.1', 'IPv4-mapped IPv6 private'],
+        ['::ffff:192.168.1.1', 'IPv4-mapped IPv6 192.168'],
+        ['::ffff:169.254.169.254', 'IPv4-mapped IPv6 metadata'],
+    ];
+    for (const [ip, label] of privateCases) {
+        it(`returns true for ${label} (${ip})`, () => {
+            expect(isPrivateIP(ip)).toBe(true);
+        });
+    }
+    const publicCases = [
+        ['8.8.8.8', 'Google DNS'],
+        ['1.1.1.1', 'Cloudflare DNS'],
+        ['203.0.113.1', 'TEST-NET-3'],
+        ['172.32.0.1', 'just above 172.16-31 range'],
+        ['172.15.255.255', 'just below 172.16-31 range'],
+        ['11.0.0.1', 'not in 10.x'],
+        ['2607:f8b0:4004:800::200e', 'public IPv6'],
+    ];
+    for (const [ip, label] of publicCases) {
+        it(`returns false for ${label} (${ip})`, () => {
+            expect(isPrivateIP(ip)).toBe(false);
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// validateUrl
+// ---------------------------------------------------------------------------
+vi.mock('node:dns/promises', () => ({
+    lookup: vi.fn(),
+}));
+const mockLookup = vi.mocked(lookup);
+describe('validateUrl', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('allows https with public IP', async () => {
+        mockLookup.mockResolvedValue({ address: '93.184.216.34', family: 4 });
+        await expect(validateUrl('https://example.com/image.jpg')).resolves.toBeUndefined();
+    });
+    it('allows http for localhost', async () => {
+        mockLookup.mockResolvedValue({ address: '127.0.0.1', family: 4 });
+        // localhost resolves to private but http://localhost is allowed for scheme,
+        // however DNS check still blocks it -- this is correct behavior:
+        // the function is meant to block fetches to private IPs regardless
+        await expect(validateUrl('http://localhost:3000/image.jpg')).rejects.toThrow('private/loopback address');
+    });
+    it('rejects http for non-localhost hosts', async () => {
+        mockLookup.mockResolvedValue({ address: '93.184.216.34', family: 4 });
+        await expect(validateUrl('http://example.com/image.jpg')).rejects.toThrow('Plain http URLs are only allowed for localhost');
+    });
+    it('rejects ftp scheme', async () => {
+        await expect(validateUrl('ftp://example.com/image.jpg')).rejects.toThrow('Unsupported URL scheme');
+    });
+    it('rejects file scheme', async () => {
+        await expect(validateUrl('file:///etc/passwd')).rejects.toThrow('Unsupported URL scheme');
+    });
+    it('rejects URLs resolving to private IPs', async () => {
+        mockLookup.mockResolvedValue({ address: '10.0.0.1', family: 4 });
+        await expect(validateUrl('https://evil.com/image.jpg')).rejects.toThrow('private/loopback address');
+    });
+    it('rejects URLs resolving to cloud metadata IP', async () => {
+        mockLookup.mockResolvedValue({ address: '169.254.169.254', family: 4 });
+        await expect(validateUrl('https://evil.com/image.jpg')).rejects.toThrow('private/loopback address');
+    });
+    it('rejects URLs resolving to IPv6 loopback', async () => {
+        mockLookup.mockResolvedValue({ address: '::1', family: 6 });
+        await expect(validateUrl('https://evil.com/image.jpg')).rejects.toThrow('private/loopback address');
+    });
+});
+// ---------------------------------------------------------------------------
+// safeFetchImageUrl
+// ---------------------------------------------------------------------------
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+describe('safeFetchImageUrl', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockLookup.mockResolvedValue({ address: '93.184.216.34', family: 4 });
+    });
+    it('fetches a valid https URL', async () => {
+        const body = new Uint8Array([0xff, 0xd8, 0xff, 0xe0]);
+        mockFetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: new Headers({ 'content-type': 'image/jpeg', 'content-length': '4' }),
+            arrayBuffer: () => Promise.resolve(body.buffer),
+        });
+        const result = await safeFetchImageUrl('https://example.com/photo.jpg');
+        expect(result.contentType).toBe('image/jpeg');
+        expect(result.buffer).toEqual(body);
+        expect(mockFetch).toHaveBeenCalledWith('https://example.com/photo.jpg', {
+            redirect: 'manual',
+        });
+    });
+    it('follows a single redirect and re-validates', async () => {
+        // First call: 302 redirect
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 302,
+            headers: new Headers({ location: 'https://cdn.example.com/photo.jpg' }),
+        });
+        // Second call: actual image
+        const body = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            headers: new Headers({ 'content-type': 'image/png', 'content-length': '4' }),
+            arrayBuffer: () => Promise.resolve(body.buffer),
+        });
+        const result = await safeFetchImageUrl('https://example.com/redirect');
+        expect(result.contentType).toBe('image/png');
+        // validateUrl called twice (original + redirect target)
+        expect(mockLookup).toHaveBeenCalledTimes(2);
+        // Second fetch also uses redirect: 'manual' (loop re-validates each hop)
+        expect(mockFetch).toHaveBeenCalledWith('https://cdn.example.com/photo.jpg', {
+            redirect: 'manual',
+        });
+    });
+    it('blocks redirect to private IP (SSRF bypass)', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 302,
+            headers: new Headers({ location: 'https://internal.evil.com/metadata' }),
+        });
+        // First lookup (original URL) returns public IP
+        mockLookup.mockResolvedValueOnce({ address: '93.184.216.34', family: 4 });
+        // Second lookup (redirect target) returns private IP
+        mockLookup.mockResolvedValueOnce({ address: '169.254.169.254', family: 4 });
+        await expect(safeFetchImageUrl('https://public-looking.com/image')).rejects.toThrow('private/loopback address');
+        // Should NOT have made a second fetch
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+    it('treats redirect without Location header as final response', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 301,
+            statusText: 'Moved Permanently',
+            headers: new Headers(),
+        });
+        // 3xx without Location is treated as final response, which is not ok
+        await expect(safeFetchImageUrl('https://example.com/broken-redirect')).rejects.toThrow('Failed to fetch image from URL: 301 Moved Permanently');
+    });
+    it('rejects non-ok responses', async () => {
+        mockFetch.mockResolvedValue({
+            ok: false,
+            status: 404,
+            statusText: 'Not Found',
+            headers: new Headers(),
+        });
+        await expect(safeFetchImageUrl('https://example.com/missing.jpg')).rejects.toThrow('Failed to fetch image from URL: 404 Not Found');
+    });
+    it('rejects oversized responses via content-length header', async () => {
+        mockFetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: new Headers({
+                'content-length': String(20 * 1024 * 1024), // 20 MB
+            }),
+            arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+        });
+        await expect(safeFetchImageUrl('https://example.com/huge.jpg')).rejects.toThrow('Image URL response too large');
+    });
+    it('rejects oversized responses via actual body size', async () => {
+        const bigBuffer = new ArrayBuffer(11 * 1024 * 1024); // 11 MB
+        mockFetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: new Headers(), // no content-length
+            arrayBuffer: () => Promise.resolve(bigBuffer),
+        });
+        await expect(safeFetchImageUrl('https://example.com/sneaky.jpg')).rejects.toThrow('Image URL response too large');
+    });
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@instamolt/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for InstaMolt — AI agent social media platform",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "instamolt-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "npx fastmcp dev src/index.ts",
+    "inspect": "npx fastmcp inspect src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "fastmcp": "^3.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "mcp",
+    "instamolt",
+    "ai-agents",
+    "social-media",
+    "model-context-protocol"
+  ],
+  "license": "MIT"
+}