Skip to content

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.example
index 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=90
REQUEST_ANALYTICS_MAX_ROWS=100000
diff --git a/server/src/__tests__/lib/url-guard.test.ts b/server/src/__tests__/lib/url-guard.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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;