7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
fix(security): guard custom-provider base URLs against SSRF (#440) (#443)
Tashfeen10b509212f3f
diff --git a/.env.example b/.env.exampleindex d240ad31..5659ed7f 100644--- a/.env.example+++ b/.env.example@@ -16,6 +16,14 @@ PORT=3001# to disable proxy rate limiting.# PROXY_RATE_LIMIT_RPM=120+# Custom-provider URL policy. Cloud metadata and link-local addresses+# (169.254.169.254, metadata.google.internal, fe80::/10, ...) are ALWAYS+# blocked as custom provider base URLs. By default localhost and private LAN+# addresses stay allowed so local Ollama / LM Studio / llama.cpp setups work.+# If you host FreeLLMAPI on a VPS or anywhere the dashboard is reachable by+# others, set this to also block loopback and RFC1918/ULA private ranges.+# FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS=true+# Request analytics retention. Set either value to 0 to disable that limit.REQUEST_ANALYTICS_RETENTION_DAYS=90REQUEST_ANALYTICS_MAX_ROWS=100000diff --git a/server/src/__tests__/lib/url-guard.test.ts b/server/src/__tests__/lib/url-guard.test.tsnew file mode 100644index 00000000..7ebb615f--- /dev/null+++ b/server/src/__tests__/lib/url-guard.test.ts@@ -0,0 +1,117 @@+import { describe, it, expect, afterEach } from 'vitest';+import { classifyIp, assessProviderUrl } from '../../lib/url-guard.js';++// SSRF guard for user-supplied custom-provider base URLs (#440). Metadata and+// link-local targets must never be reachable; loopback/private stay allowed by+// default (local Ollama / LM Studio is the app's primary documented use case)+// and flip to blocked under FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS.++afterEach(() => {+ delete process.env.FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS;+});++describe('classifyIp', () => {+ it('classifies cloud metadata addresses', () => {+ expect(classifyIp('169.254.169.254')).toBe('metadata');+ expect(classifyIp('100.100.100.200')).toBe('metadata'); // Alibaba IMDS+ expect(classifyIp('fd00:ec2::254')).toBe('metadata'); // AWS IMDS IPv6+ });++ it('classifies link-local ranges', () => {+ expect(classifyIp('169.254.0.1')).toBe('link-local');+ expect(classifyIp('fe80::1')).toBe('link-local');+ });++ it('classifies loopback', () => {+ expect(classifyIp('127.0.0.1')).toBe('loopback');+ expect(classifyIp('127.8.8.8')).toBe('loopback');+ expect(classifyIp('::1')).toBe('loopback');+ expect(classifyIp('0.0.0.0')).toBe('loopback');+ });++ it('classifies private ranges', () => {+ expect(classifyIp('10.13.13.1')).toBe('private');+ expect(classifyIp('172.16.0.1')).toBe('private');+ expect(classifyIp('172.31.255.255')).toBe('private');+ expect(classifyIp('192.168.1.20')).toBe('private');+ expect(classifyIp('100.64.0.1')).toBe('private'); // CGNAT+ expect(classifyIp('fc00::1')).toBe('private'); // ULA+ expect(classifyIp('fd12:3456::1')).toBe('private');+ });++ it('classifies public addresses and IPv4-mapped IPv6', () => {+ expect(classifyIp('8.8.8.8')).toBe('public');+ expect(classifyIp('172.32.0.1')).toBe('public'); // just past 172.16/12+ expect(classifyIp('2606:4700::1111')).toBe('public');+ expect(classifyIp('::ffff:169.254.169.254')).toBe('metadata'); // mapped+ expect(classifyIp('::ffff:8.8.8.8')).toBe('public');+ });+});++describe('assessProviderUrl', () => {+ it('always blocks cloud metadata targets', async () => {+ const aws = await assessProviderUrl('http://169.254.169.254/latest/meta-data/');+ expect(aws.allowed).toBe(false);+ expect(aws.reason).toMatch(/metadata/);++ const gcp = await assessProviderUrl('http://metadata.google.internal/computeMetadata/v1/');+ expect(gcp.allowed).toBe(false);+ expect(gcp.reason).toMatch(/metadata/);+ });++ it('blocks decimal-encoded metadata IPs (URL canonicalisation)', async () => {+ // 2852039166 === 169.254.169.254 — WHATWG URL normalises integer hosts.+ const verdict = await assessProviderUrl('http://2852039166/latest/meta-data/');+ expect(verdict.allowed).toBe(false);+ expect(verdict.reason).toMatch(/metadata/);+ });++ it('blocks hostnames that resolve to metadata or link-local addresses', async () => {+ const verdict = await assessProviderUrl('http://innocent.example.com/v1', {+ resolve: async () => ['169.254.169.254'],+ });+ expect(verdict.allowed).toBe(false);++ const linkLocal = await assessProviderUrl('http://innocent.example.com/v1', {+ resolve: async () => ['1.2.3.4', 'fe80::1'],+ });+ expect(linkLocal.allowed).toBe(false);+ });++ it('allows loopback and private LAN targets by default (local Ollama)', async () => {+ expect((await assessProviderUrl('http://localhost:11434/v1', { resolve: async () => ['127.0.0.1'] })).allowed).toBe(true);+ expect((await assessProviderUrl('http://127.0.0.1:8080/v1')).allowed).toBe(true);+ expect((await assessProviderUrl('http://192.168.1.20:11434/v1')).allowed).toBe(true);+ });++ it('blocks loopback and private targets under FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS', async () => {+ process.env.FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS = 'true';+ expect((await assessProviderUrl('http://127.0.0.1:8080/v1')).allowed).toBe(false);+ expect((await assessProviderUrl('http://192.168.1.20:11434/v1')).allowed).toBe(false);+ expect((await assessProviderUrl('http://10.0.0.5:3000/v1')).allowed).toBe(false);+ // Metadata stays blocked, public stays allowed.+ expect((await assessProviderUrl('http://169.254.169.254/')).allowed).toBe(false);+ const pub = await assessProviderUrl('https://api.example.com/v1', { resolve: async () => ['93.184.216.34'] });+ expect(pub.allowed).toBe(true);+ });++ it('allows public URLs', async () => {+ const verdict = await assessProviderUrl('https://api.example.com/v1', {+ resolve: async () => ['93.184.216.34'],+ });+ expect(verdict.allowed).toBe(true);+ });++ it('rejects non-http(s) protocols and malformed URLs', async () => {+ expect((await assessProviderUrl('ftp://example.com/v1')).allowed).toBe(false);+ expect((await assessProviderUrl('file:///etc/passwd')).allowed).toBe(false);+ expect((await assessProviderUrl('not a url')).allowed).toBe(false);+ });++ it('lets unresolvable hostnames through (checked again at request time)', async () => {+ const verdict = await assessProviderUrl('http://my-offline-box.lan:11434/v1', {+ resolve: async () => { throw new Error('ENOTFOUND'); },+ });+ expect(verdict.allowed).toBe(true);+ });+});diff --git a/server/src/__tests__/routes/keys-ssrf-guard.test.ts b/server/src/__tests__/routes/keys-ssrf-guard.test.tsnew file mode 100644index 00000000..4c99ec2c--- /dev/null+++ b/server/src/__tests__/routes/keys-ssrf-guard.test.ts@@ -0,0 +1,92 @@+import { describe, it, expect, beforeAll, vi } from 'vitest';+import type { Express } from 'express';+import { createApp } from '../../app.js';+import { initDb, getDb } from '../../db/index.js';+import { proxyFetch } from '../../lib/proxy.js';+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';++// SSRF guard (#440): the custom-provider base_url is the only user-supplied+// outbound target. Metadata/link-local addresses must be rejected at save+// time (POST /api/keys/custom) and again at request time (proxyFetch).++let dashToken = '';++async function post(app: Express, path: string, body: unknown) {+ const server = app.listen(0);+ const addr = server.address() as { port: number };+ const res = await fetch(`http://127.0.0.1:${addr.port}${path}`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ ...(isGatedApiPath(path) ? { Authorization: `Bearer ${dashToken}` } : {}),+ },+ body: JSON.stringify(body),+ });+ const data = await res.json().catch(() => null);+ server.close();+ return { status: res.status, body: data };+}++describe('POST /api/keys/custom SSRF guard (#440)', () => {+ let app: Express;++ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ getDb().prepare("DELETE FROM settings WHERE key = 'active_profile_id'").run();+ app = createApp();+ dashToken = mintDashboardToken();+ });++ it('rejects an AWS metadata base URL', async () => {+ const res = await post(app, '/api/keys/custom', {+ baseUrl: 'http://169.254.169.254/latest/meta-data',+ model: 'not-a-model',+ });+ expect(res.status).toBe(400);+ expect(res.body.error.message).toMatch(/metadata/);+ });++ it('rejects the GCP metadata hostname', async () => {+ const res = await post(app, '/api/keys/custom', {+ baseUrl: 'http://metadata.google.internal/computeMetadata/v1',+ model: 'not-a-model',+ });+ expect(res.status).toBe(400);+ expect(res.body.error.message).toMatch(/metadata/);+ });++ it('rejects a decimal-encoded metadata IP', async () => {+ const res = await post(app, '/api/keys/custom', {+ baseUrl: 'http://2852039166/v1', // canonicalises to 169.254.169.254+ model: 'not-a-model',+ });+ expect(res.status).toBe(400);+ });++ it('still accepts a loopback base URL by default (local Ollama)', async () => {+ const res = await post(app, '/api/keys/custom', {+ baseUrl: 'http://127.0.0.1:11434/v1',+ model: 'qwen3:4b',+ });+ expect(res.status).toBe(201);+ });+});++describe('proxyFetch request-time SSRF guard (#440)', () => {+ it('blocks custom-platform requests to metadata addresses even when already saved', async () => {+ const spy = vi.spyOn(global, 'fetch');+ await expect(+ proxyFetch('http://169.254.169.254/latest/meta-data', undefined, 'custom', 'chat', 15_000),+ ).rejects.toThrow(/blocked.*metadata/);+ expect(spy).not.toHaveBeenCalled();+ spy.mockRestore();+ });++ it('does not re-guard built-in platforms', async () => {+ const spy = vi.spyOn(global, 'fetch').mockResolvedValueOnce(new Response('{}'));+ await proxyFetch('https://api.groq.com/openai/v1/models', undefined, 'groq', 'chat', 15_000);+ expect(spy).toHaveBeenCalledOnce();+ spy.mockRestore();+ });+});diff --git a/server/src/lib/proxy.ts b/server/src/lib/proxy.tsindex 5a38feb8..175d2a30 100644--- a/server/src/lib/proxy.ts+++ b/server/src/lib/proxy.ts@@ -1,5 +1,6 @@import http from 'http';import https from 'https';+import { assertProviderUrlAllowed } from './url-guard.js';// undici (ProxyAgent) and socks-proxy-agent are lazy-loaded on first proxy use// ONLY. Importing undici at module top-level eagerly runs its web/cache init,@@ -322,6 +323,15 @@ export async function proxyFetch(timeoutMs?: number,): Promise<Response> {try {+ // SSRF guard (#440): 'custom' is the only platform whose target URL is+ // user-supplied (base_url on the api_keys row), so it is re-assessed on+ // every request — a URL saved before the guard existed, edited in the DB,+ // or whose DNS now points somewhere blocked still can't reach cloud+ // metadata / link-local addresses.+ if (platform === 'custom') {+ await assertProviderUrlAllowed(url);+ }+// Bypass check: disabled globally, or this platform is exempt.if (shouldBypassProxy(platform)) {return await fetch(url, init);diff --git a/server/src/lib/url-guard.ts b/server/src/lib/url-guard.tsnew file mode 100644index 00000000..79625b1f--- /dev/null+++ b/server/src/lib/url-guard.ts@@ -0,0 +1,172 @@+import dns from 'node:dns';+import net from 'node:net';++// Outbound guard for user-supplied custom-provider base URLs (#440).+//+// A custom provider's base_url is the one place an authenticated dashboard+// user controls where the server sends requests. Left unchecked that is an+// SSRF vector: point base_url at a cloud metadata service and the proxy will+// happily fetch IAM credentials and echo them back through the completions+// response path.+//+// Policy, calibrated for a local-first app whose primary documented use case+// is pointing at llama.cpp / Ollama / LM Studio on localhost or the LAN:+//+// - Cloud metadata addresses and link-local ranges: ALWAYS blocked.+// (169.254.0.0/16 incl. 169.254.169.254, fe80::/10, Alibaba's+// 100.100.100.200, AWS's fd00:ec2::254, metadata.google.internal.)+// No legitimate LLM endpoint lives there and this is the actual+// credential-theft vector.+// - Loopback and RFC1918/ULA private ranges: allowed by default so+// existing local setups keep working, but blocked when the operator+// sets FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS=true (recommended for+// instances hosted on a VPS where the dashboard is exposed).+// - Everything else (public addresses): allowed.+//+// Known limitation: hostnames are resolved and classified here, but the+// actual fetch re-resolves DNS, so a hostile authoritative DNS server could+// still rebind between check and use. Pinning the resolved address into the+// dispatcher is the follow-up hardening step; the always-blocked classes+// above are also re-checked at request time (proxyFetch) which narrows the+// window to deliberate rebinding rather than casual misuse.++export type AddressClass = 'metadata' | 'link-local' | 'loopback' | 'private' | 'public';++const METADATA_HOSTNAMES = new Set([+ 'metadata.google.internal',+ 'metadata.goog',+]);++// Exact metadata addresses that sit outside the link-local range.+const METADATA_ADDRESSES = new Set([+ '100.100.100.200', // Alibaba Cloud IMDS+ 'fd00:ec2::254', // AWS IMDSv2 IPv6+]);++function classifyIpv4(ip: string): AddressClass {+ const octets = ip.split('.').map(Number);+ const [a, b] = octets;+ if (METADATA_ADDRESSES.has(ip)) return 'metadata';+ if (a === 169 && b === 254) return ip === '169.254.169.254' ? 'metadata' : 'link-local';+ if (a === 127) return 'loopback';+ if (a === 10) return 'private';+ if (a === 172 && b >= 16 && b <= 31) return 'private';+ if (a === 192 && b === 168) return 'private';+ // CGNAT range; contains Alibaba's metadata address and is never a place a+ // user-facing LLM endpoint is published.+ if (a === 100 && b >= 64 && b <= 127) return 'private';+ if (a === 0) return 'loopback'; // 0.0.0.0 → "this host"+ return 'public';+}++function classifyIpv6(ip: string): AddressClass {+ const lower = ip.toLowerCase();+ // IPv4-mapped (::ffff:a.b.c.d) — classify the embedded IPv4.+ const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);+ if (mapped) return classifyIpv4(mapped[1]);+ if (METADATA_ADDRESSES.has(lower)) return 'metadata';+ if (lower === '::1' || lower === '::') return 'loopback';+ const firstHextet = lower.split(':')[0] || '0';+ const value = parseInt(firstHextet.padStart(4, '0'), 16);+ if ((value & 0xffc0) === 0xfe80) return 'link-local'; // fe80::/10+ if ((value & 0xfe00) === 0xfc00) return 'private'; // fc00::/7 (ULA)+ return 'public';+}++export function classifyIp(ip: string): AddressClass {+ const version = net.isIP(ip);+ if (version === 4) return classifyIpv4(ip);+ if (version === 6) return classifyIpv6(ip);+ return 'public';+}++export interface UrlAssessment {+ allowed: boolean;+ reason?: string;+}++export interface AssessOptions {+ // Injectable for tests; defaults to a real DNS lookup.+ resolve?: (hostname: string) => Promise<string[]>;+ // Overrides the env flag; when true, loopback/private addresses are blocked.+ blockPrivate?: boolean;+}++async function defaultResolve(hostname: string): Promise<string[]> {+ const records = await dns.promises.lookup(hostname, { all: true, verbatim: true });+ return records.map(r => r.address);+}++function blockPrivateEnabled(): boolean {+ return /^(1|true|yes)$/i.test(process.env.FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS ?? '');+}++/**+ * Assess whether an outbound custom-provider URL is safe to contact.+ * Never throws on malformed input — a bad URL comes back as {allowed: false}.+ */+export async function assessProviderUrl(rawUrl: string, opts: AssessOptions = {}): Promise<UrlAssessment> {+ let url: URL;+ try {+ url = new URL(rawUrl);+ } catch {+ return { allowed: false, reason: 'not a valid URL' };+ }+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {+ return { allowed: false, reason: `unsupported protocol ${url.protocol.replace(/:$/, '')}` };+ }++ // WHATWG URL canonicalises decimal/hex/octal IPv4 forms (http://2852039166/+ // parses to hostname 169.254.169.254), so classifying url.hostname covers+ // those encodings too. IPv6 literals arrive bracketed — strip for net.isIP.+ const hostname = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();++ if (METADATA_HOSTNAMES.has(hostname)) {+ return { allowed: false, reason: 'cloud metadata endpoints are not reachable through custom providers' };+ }++ let addresses: string[];+ if (net.isIP(hostname)) {+ addresses = [hostname];+ } else {+ try {+ addresses = await (opts.resolve ?? defaultResolve)(hostname);+ } catch {+ // Unresolvable now may resolve later (device not on the LAN yet, DNS+ // hiccup). Saving is harmless — the request-time check runs again.+ return { allowed: true };+ }+ if (addresses.length === 0) return { allowed: true };+ }++ const blockPrivate = opts.blockPrivate ?? blockPrivateEnabled();+ for (const address of addresses) {+ const cls = classifyIp(address);+ if (cls === 'metadata') {+ return { allowed: false, reason: `resolves to a cloud metadata address (${address})` };+ }+ if (cls === 'link-local') {+ return { allowed: false, reason: `resolves to a link-local address (${address})` };+ }+ if (blockPrivate && (cls === 'loopback' || cls === 'private')) {+ return {+ allowed: false,+ reason: `resolves to a private address (${address}) and FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS is set`,+ };+ }+ }+ return { allowed: true };+}++/**+ * Request-time enforcement: throws when the URL is blocked. Used by+ * proxyFetch for the custom platform so a base_url that slipped into the DB+ * (older install, direct DB edit, DNS change after save) still can't reach a+ * blocked address class.+ */+export async function assertProviderUrlAllowed(rawUrl: string): Promise<void> {+ const verdict = await assessProviderUrl(rawUrl);+ if (!verdict.allowed) {+ throw new Error(`Custom provider URL blocked: ${verdict.reason}`);+ }+}diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.tsindex 8fd76956..483206fb 100644--- a/server/src/routes/keys.ts+++ b/server/src/routes/keys.ts@@ -7,6 +7,7 @@ import { getDb } from '../db/index.js';import { resolveProvider } from '../providers/index.js';import { encrypt, decrypt, maskKey } from '../lib/crypto.js';import { parseKeysFromFile, stripJsoncComments, stripTrailingCommas } from '../lib/key-parser.js';+import { assessProviderUrl } from '../lib/url-guard.js';export const keysRouter = Router();@@ -268,7 +269,7 @@ const customProviderSchema = z.object({{ message: 'model or models is required' },);-keysRouter.post('/custom', (req: Request, res: Response) => {+keysRouter.post('/custom', async (req: Request, res: Response) => {const parsed = customProviderSchema.safeParse(req.body);if (!parsed.success) {res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });@@ -276,6 +277,16 @@ keysRouter.post('/custom', (req: Request, res: Response) => {}const baseUrl = parsed.data.baseUrl.trim().replace(/\/+$/, '');++ // SSRF guard (#440): a base_url is the one user-controlled outbound target.+ // Cloud metadata / link-local addresses are rejected outright; private+ // ranges too when FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS is set. Re-checked+ // at request time in proxyFetch for URLs already in the DB.+ const verdict = await assessProviderUrl(baseUrl);+ if (!verdict.allowed) {+ res.status(400).json({ error: { message: `baseUrl rejected: ${verdict.reason}` } });+ return;+ }// Local servers often need no key; keep a sentinel so there's always a bearer.const providedKey = parsed.data.apiKey?.trim() || undefined;const label = parsed.data.label?.trim() || undefined;