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(proxy): never route loopback destinations through the proxy (#951) (#963)

tashdroidfe7744c027bf
diff --git a/.env.example b/.env.example
index 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.ts
index 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 answering
diff --git a/server/src/__tests__/lib/url-guard.test.ts b/server/src/__tests__/lib/url-guard.test.ts
index 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.ts
index 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.ts
index 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 {