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(proxy): never route loopback destinations through the proxy (#951) (#963)
tashdroidfe7744c027bf
diff --git a/.env.example b/.env.exampleindex 45903dde..ffb510fd 100644--- a/.env.example+++ b/.env.example@@ -83,6 +83,16 @@ PORT=3001# proxy entirely.# NO_PROXY=localhost,127.0.0.1,.internal.corp+# Local and LAN destinations (localhost, 127.0.0.0/8, ::1, 0.0.0.0, RFC1918 /+# ULA / CGNAT addresses) always bypass the proxy — a remote proxy has no route+# back to your own machine, and an IP literal makes Tor log "giving Tor only an+# IP address" and refuse the connection. That is the right default for a local+# Ollama / llama.cpp / LM Studio endpoint.+# Set this to true only if proxying them is the point — e.g. an `ssh -D`+# dynamic tunnel, where http://127.0.0.1:11434 through the SOCKS proxy is meant+# to reach the REMOTE host's Ollama.+# FREEAPI_PROXY_LOCAL_DESTINATIONS=true+# Per-provider daily request cap, named PROVIDER_DAILY_REQUEST_CAP_<PLATFORM># (platform name upper-cased). Overrides the built-in default for that provider;# set to 0 to disable the cap. Example — cap OpenRouter at 50 requests/day:diff --git a/server/src/__tests__/lib/proxy.test.ts b/server/src/__tests__/lib/proxy.test.tsindex b37ad6a2..95d59428 100644--- a/server/src/__tests__/lib/proxy.test.ts+++ b/server/src/__tests__/lib/proxy.test.ts@@ -1,5 +1,6 @@import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';import { EventEmitter } from 'events';+import http from 'http';import https from 'https';import {applyProxyUrl,@@ -23,7 +24,19 @@ import {// Every env var the proxy config reads, in both the upper- and lower-case// spellings the convention allows. Cleared around each test so a developer// machine that genuinely sits behind a corporate proxy doesn't fail the suite.-const PROXY_ENV_VARS = ['PROXY_URL', 'ALL_PROXY', 'HTTPS_PROXY', 'HTTP_PROXY', 'NO_PROXY'];+// FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS is not a proxy knob, but the local/LAN+// cases below call proxyFetch with platform 'custom', which re-runs the SSRF+// guard — an operator machine that exports it would fail them for the wrong+// reason.+const PROXY_ENV_VARS = [+ 'PROXY_URL',+ 'ALL_PROXY',+ 'HTTPS_PROXY',+ 'HTTP_PROXY',+ 'NO_PROXY',+ 'FREEAPI_PROXY_LOCAL_DESTINATIONS',+ 'FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS',+];function clearProxyEnv(): void {for (const name of PROXY_ENV_VARS) {@@ -117,22 +130,31 @@ describe('SOCKS scheme detection (#630)', () => {// with a SocksProxyAgent. Stubbing https.request lets us assert *which* agent// the dispatcher picked (and that socks5h parsed into a real SOCKS5 agent)// without opening a socket.+const fakeRequest = ((_opts: any, cb: any) => {+ const req = new EventEmitter() as any;+ req.write = () => {};+ req.destroy = () => {};+ req.end = () => {+ const res = new EventEmitter() as any;+ res.statusCode = 200;+ res.statusMessage = 'OK';+ res.headers = {};+ res.destroy = () => {};+ cb(res);+ setImmediate(() => res.emit('end'));+ };+ return req;+}) as any;+function stubHttpsRequest() {- return vi.spyOn(https, 'request').mockImplementation(((_opts: any, cb: any) => {- const req = new EventEmitter() as any;- req.write = () => {};- req.destroy = () => {};- req.end = () => {- const res = new EventEmitter() as any;- res.statusCode = 200;- res.statusMessage = 'OK';- res.headers = {};- res.destroy = () => {};- cb(res);- setImmediate(() => res.emit('end'));- };- return req;- }) as any);+ return vi.spyOn(https, 'request').mockImplementation(fakeRequest);+}++// A plain `http://` destination rides http.request, not https.request — the+// local-endpoint cases (#951) are all http, so both transports need stubbing+// before a test can claim nothing reached the wire.+function stubHttpRequest() {+ return vi.spyOn(http, 'request').mockImplementation(fakeRequest);}describe('proxyFetch dispatcher selection for SOCKS schemes (#630)', () => {@@ -467,6 +489,111 @@ describe('proxyFetch routing', () => {});});+// #951: a local destination — Ollama/llama.cpp/LM Studio on 127.0.0.1, or on+// the LAN at 192.168.1.20 — is unreachable through a remote proxy, and because+// an IP literal must go on the wire as ATYP 0x01 (an IP) regardless of the+// `socks5h` suffix, it is exactly what makes Tor log "giving Tor only an IP+// address" and may get the connection refused. Loopback and private/LAN+// addresses therefore always bypass the proxy, unless the operator opts out+// with FREEAPI_PROXY_LOCAL_DESTINATIONS.+describe('local and LAN destinations bypass the proxy (#951)', () => {+ /** Run one request through the SOCKS-configured proxy and report the route. */+ const routeOf = async (url: string): Promise<'direct' | 'proxied'> => {+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(okResponse());+ const httpsSpy = stubHttpsRequest();+ const httpSpy = stubHttpRequest();+ await proxyFetch(url, { method: 'POST' }, 'custom');+ // A SOCKS route never touches fetch(): it goes out through http/https.request+ // with a SocksProxyAgent attached.+ if (httpsSpy.mock.calls.length + httpSpy.mock.calls.length > 0) {+ expect(fetchSpy).not.toHaveBeenCalled();+ return 'proxied';+ }+ expect(fetchSpy).toHaveBeenCalledTimes(1);+ // Direct means no dispatcher was injected either.+ expect((fetchSpy.mock.calls[0]?.[1] as any)?.dispatcher).toBeUndefined();+ return 'direct';+ };++ beforeEach(() => {+ applyProxyUrl('socks5h://127.0.0.1:9050');+ });++ const directCases: Array<[string, string]> = [+ ['IPv4 loopback', 'http://127.0.0.1:11434/api/chat'],+ ['the 127/8 range beyond .0.1', 'http://127.0.0.2:11434/api/chat'],+ ['"this host" 0.0.0.0', 'http://0.0.0.0:11434/api/chat'],+ ['bracketed IPv6 loopback', 'http://[::1]:11434/api/chat'],+ ['the localhost name', 'http://localhost:11434/api/chat'],+ ['a *.localhost subdomain', 'http://ollama.localhost:11434/api/chat'],+ ['the trailing-dot FQDN form of localhost', 'http://localhost.:11434/api/chat'],+ ['an RFC1918 LAN address', 'http://192.168.1.20:11434/api/chat'],+ ['a 10/8 LAN address', 'http://10.0.0.5:11434/api/chat'],+ ['a 172.16/12 LAN address', 'http://172.16.4.2:11434/api/chat'],+ ['an IPv6 ULA address', 'http://[fd12:3456::1]:11434/api/chat'],+ ];++ for (const [label, url] of directCases) {+ it(`sends ${label} direct`, async () => {+ expect(await routeOf(url)).toBe('direct');+ });+ }++ it('still routes a public destination through the SOCKS proxy', async () => {+ const fetchSpy = vi.spyOn(global, 'fetch');+ const reqSpy = stubHttpsRequest();++ await proxyFetch('https://api.openai.com/v1/models', { method: 'GET' }, 'openai');++ // Public host still goes through the SOCKS agent (port 9050).+ expect(fetchSpy).not.toHaveBeenCalled();+ expect((reqSpy.mock.calls[0][0] as any).agent?.proxy?.port).toBe(9050);+ });++ it('applies to the per-key proxy path too', async () => {+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(okResponse());+ const httpsSpy = stubHttpsRequest();+ const httpSpy = stubHttpRequest();++ await withKeyProxy('socks5h://127.0.0.1:9051', () =>+ proxyFetch('http://192.168.1.20:11434/api/chat', { method: 'POST' }, 'custom'));++ expect(httpsSpy).not.toHaveBeenCalled();+ expect(httpSpy).not.toHaveBeenCalled();+ expect(fetchSpy).toHaveBeenCalledTimes(1);+ expect((fetchSpy.mock.calls[0]?.[1] as any)?.dispatcher).toBeUndefined();+ });++ // The `ssh -D` case: the tunnel's far end is where 127.0.0.1:11434 is meant+ // to resolve, so the operator can force local destinations back through it.+ describe('FREEAPI_PROXY_LOCAL_DESTINATIONS opt-out', () => {+ it('routes loopback through the proxy when set', async () => {+ process.env.FREEAPI_PROXY_LOCAL_DESTINATIONS = 'true';+ applyProxyUrl('socks5h://127.0.0.1:9050');+ expect(await routeOf('http://127.0.0.1:11434/api/chat')).toBe('proxied');+ });++ it('routes a LAN address through the proxy when set', async () => {+ process.env.FREEAPI_PROXY_LOCAL_DESTINATIONS = '1';+ applyProxyUrl('socks5h://127.0.0.1:9050');+ expect(await routeOf('http://192.168.1.20:11434/api/chat')).toBe('proxied');+ });++ it('is ignored when set to a non-truthy value', async () => {+ process.env.FREEAPI_PROXY_LOCAL_DESTINATIONS = 'false';+ applyProxyUrl('socks5h://127.0.0.1:9050');+ expect(await routeOf('http://127.0.0.1:11434/api/chat')).toBe('direct');+ });++ it('still honours the global off switch', async () => {+ process.env.FREEAPI_PROXY_LOCAL_DESTINATIONS = 'true';+ applyProxyUrl('socks5h://127.0.0.1:9050');+ applyProxyEnabled(false);+ expect(await routeOf('http://127.0.0.1:11434/api/chat')).toBe('direct');+ });+ });+});+// SSRF guard, request-time half (#440). The save-time check validates the// literal base_url, but fetch()'s default redirect: 'follow' would re-request// a 3xx Location target with no re-validation — a public base_url answeringdiff --git a/server/src/__tests__/lib/url-guard.test.ts b/server/src/__tests__/lib/url-guard.test.tsindex e8f0d9c8..1e07cba5 100644--- a/server/src/__tests__/lib/url-guard.test.ts+++ b/server/src/__tests__/lib/url-guard.test.ts@@ -1,5 +1,5 @@import { describe, it, expect, afterEach } from 'vitest';-import { classifyIp, assessProviderUrl, isLoopbackOrPrivateUrl } from '../../lib/url-guard.js';+import { classifyIp, assessProviderUrl, isLoopbackOrPrivateUrl, isLoopbackOrPrivateHostname } 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@@ -170,4 +170,34 @@ describe('isLoopbackOrPrivateUrl (#592 local-endpoint cooldown exemption)', () =expect(isLoopbackOrPrivateUrl('')).toBe(false);expect(isLoopbackOrPrivateUrl('not a url')).toBe(false);});++ // The FQDN spelling resolves exactly like the bare name, so it must not slip+ // through as "some public host" (#951 — it would then get proxied).+ it('true for the trailing-dot FQDN spelling of localhost', () => {+ expect(isLoopbackOrPrivateUrl('http://localhost./v1')).toBe(true);+ expect(isLoopbackOrPrivateUrl('http://ollama.localhost./v1')).toBe(true);+ });+});++describe('isLoopbackOrPrivateHostname (hostname half, used by the proxy router)', () => {+ it('matches the same classes as the URL form', () => {+ expect(isLoopbackOrPrivateHostname('127.0.0.2')).toBe(true);+ expect(isLoopbackOrPrivateHostname('0.0.0.0')).toBe(true);+ expect(isLoopbackOrPrivateHostname('[::1]')).toBe(true);+ expect(isLoopbackOrPrivateHostname('::1')).toBe(true);+ expect(isLoopbackOrPrivateHostname('LocalHost')).toBe(true);+ expect(isLoopbackOrPrivateHostname('localhost.')).toBe(true);+ expect(isLoopbackOrPrivateHostname('ollama.localhost')).toBe(true);+ expect(isLoopbackOrPrivateHostname('192.168.1.20')).toBe(true);+ expect(isLoopbackOrPrivateHostname('10.0.0.5')).toBe(true);+ expect(isLoopbackOrPrivateHostname('[fd12:3456::1]')).toBe(true);+ });++ it('false for public hosts and names it cannot decide without DNS', () => {+ expect(isLoopbackOrPrivateHostname('api.openai.com')).toBe(false);+ expect(isLoopbackOrPrivateHostname('203.0.113.10')).toBe(false);+ expect(isLoopbackOrPrivateHostname('notlocalhost')).toBe(false);+ expect(isLoopbackOrPrivateHostname('my-lan-box.local')).toBe(false);+ expect(isLoopbackOrPrivateHostname('')).toBe(false);+ });});diff --git a/server/src/lib/proxy.ts b/server/src/lib/proxy.tsindex 80e6297f..b8684b96 100644--- a/server/src/lib/proxy.ts+++ b/server/src/lib/proxy.ts@@ -2,7 +2,7 @@ import http from 'http';import https from 'https';import { AsyncLocalStorage } from 'node:async_hooks';import { getSetting } from '../db/index.js';-import { assertProviderUrlAllowed } from './url-guard.js';+import { assertProviderUrlAllowed, isLoopbackOrPrivateHostname } from './url-guard.js';// #590 (per-key proxy): the SAME provider may be reached through different// exit IPs per key (geo-ban / risk-control avoidance). Providers are process@@ -132,6 +132,8 @@ let _proxyUrl = '';let _proxyEnabled = true;let _bypassPlatforms = new Set<string>();let _noProxyRules: string[] = [];+// Escape hatch for the `ssh -D` tunnel case — see shouldBypassProxy.+let _proxyLocalDestinations = false;let _initialized = false;// Cache.@@ -179,12 +181,16 @@ export function applyProxyUrl(dbValue: string): void {const { url, source } = resolveProxySource(dbValue);_proxyUrl = url;_noProxyRules = parseNoProxy(readEnv('NO_PROXY'));+ _proxyLocalDestinations = /^(1|true|yes)$/i.test(readEnv('FREEAPI_PROXY_LOCAL_DESTINATIONS'));cached = null;if (_proxyUrl) {console.log(`[proxy] Configured → ${redactProxyUrl(_proxyUrl)} (source: ${source})`);if (_noProxyRules.length > 0) {console.log(`[proxy] NO_PROXY direct for: ${_noProxyRules.join(', ')}`);}+ if (_proxyLocalDestinations) {+ console.log('[proxy] FREEAPI_PROXY_LOCAL_DESTINATIONS is set — localhost/LAN destinations go through the proxy too.');+ }} else {console.log('[proxy] Not configured — outbound requests go direct.');}@@ -246,18 +252,37 @@ export function getNoProxyRules(): string[] {/*** Returns true when a request should NOT use the proxy.* True when: proxy is disabled globally, the platform is in the bypass list,- * or the upstream host is covered by NO_PROXY.+ * the upstream host is covered by NO_PROXY, or the upstream is a local/LAN+ * destination (#951 — see below).+ *+ * A loopback (127.0.0.0/8, ::1, 0.0.0.0, `localhost`) or private/LAN+ * (RFC1918, ULA, CGNAT) destination is unreachable through a remote proxy:+ * that proxy has no route to your own 127.0.0.1 and, on any network but+ * yours, none to 192.168.1.20 either. Routing it there is never useful and,+ * for SOCKS, actively harmful: an IP literal must go on the wire as ATYP 0x01+ * (an IP) no matter what the `socks5h` suffix promises, so Tor logs "giving+ * Tor only an IP address" and may refuse the connection. The+ * Ollama/llama.cpp/LM Studio case — the app's primary documented local use,+ * "on localhost or the LAN" — is exactly this.+ *+ * FREEAPI_PROXY_LOCAL_DESTINATIONS=true opts out, for the one setup where+ * proxying a local address IS the point: an `ssh -D` dynamic tunnel, where+ * http://127.0.0.1:11434 sent through the SOCKS proxy resolves at the far end+ * and reaches the REMOTE host's Ollama.*/function shouldBypassProxy(url: string, platform?: string): boolean {if (!_proxyEnabled) return true;if (platform && _bypassPlatforms.has(platform.toLowerCase())) return true;- if (_noProxyRules.length > 0) {- try {- if (noProxyMatches(new URL(url).hostname)) return true;- } catch {- // Unparseable URL — leave the routing decision to the caller/fetch.- }++ let hostname: string;+ try {+ hostname = new URL(url).hostname;+ } catch {+ // Unparseable URL — leave the routing decision to the caller/fetch.+ return false;}+ if (_noProxyRules.length > 0 && noProxyMatches(hostname)) return true;+ if (!_proxyLocalDestinations && isLoopbackOrPrivateHostname(hostname)) return true;return false;}@@ -600,10 +625,10 @@ async function dispatchFetch(const perKeyUrl = perKeyProxyStore.getStore() ?? '';if (perKeyUrl) {// Every bypass still applies, unchanged: the global on/off switch, the- // per-platform bypass list, and NO_PROXY. A per-key override says WHICH- // proxy to use, not that this request must be proxied — an operator who- // turned proxying off, or listed the upstream in NO_PROXY, still gets a- // direct connection.+ // per-platform bypass list, NO_PROXY, and local/LAN destinations. A+ // per-key override says WHICH proxy to use, not that this request must be+ // proxied — an operator who turned proxying off, listed the upstream in+ // NO_PROXY, or points at a local box still gets a direct connection.if (!shouldBypassProxy(url, platform)) {const resolved = await resolvePerKeyDispatcher(perKeyUrl);if (resolved) {@@ -616,8 +641,9 @@ async function dispatchFetch(// Per-key proxy failed to build → fall through to the global/direct path.}- // Bypass check: disabled globally, this platform is exempt, or the upstream- // host is listed in NO_PROXY.+ // Bypass check: disabled globally, this platform is exempt, the upstream+ // host is listed in NO_PROXY, or it is a local/LAN destination no proxy can+ // reach (#951).if (shouldBypassProxy(url, platform)) {return fetch(url, init);}diff --git a/server/src/lib/url-guard.ts b/server/src/lib/url-guard.tsindex df41f032..a376ddfa 100644--- a/server/src/lib/url-guard.ts+++ b/server/src/lib/url-guard.ts@@ -131,6 +131,26 @@ export function classifyIp(ip: string): AddressClass {return 'public';}+/**+ * Hostname half of {@link isLoopbackOrPrivateUrl}: true when a bare hostname+ * names THIS machine or the LAN. Callers that already parsed the URL (the+ * proxy router, which needs the hostname for NO_PROXY anyway) use this+ * directly so the URL is parsed once.+ *+ * Normalises the two spellings a URL hostname can arrive in: IPv6 literals are+ * bracketed (`[::1]`), and the FQDN form carries a trailing dot (`localhost.`+ * — a real, resolvable spelling that must not slip past as a public name).+ */+export function isLoopbackOrPrivateHostname(hostname: string): boolean {+ const host = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();+ if (host === 'localhost' || host.endsWith('.localhost')) return true;+ if (net.isIP(host)) {+ const cls = classifyIp(host);+ return cls === 'loopback' || cls === 'private';+ }+ return false;+}+/*** Synchronous locality check for a stored provider base_url: true when the URL* points at THIS machine or the LAN (loopback, RFC1918/ULA private, 'localhost').@@ -151,13 +171,7 @@ export function isLoopbackOrPrivateUrl(rawUrl: string | null | undefined): boole} catch {return false;}- const hostname = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();- if (hostname === 'localhost' || hostname.endsWith('.localhost')) return true;- if (net.isIP(hostname)) {- const cls = classifyIp(hostname);- return cls === 'loopback' || cls === 'private';- }- return false;+ return isLoopbackOrPrivateHostname(url.hostname);}export interface UrlAssessment {