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

feat(proxy): per-key proxy override — each API key can route through its own exit (#590) (#819)

suantea (asuan_suan)647683ad78af
diff --git a/server/src/__tests__/db/migrate/roundtrip.test.ts b/server/src/__tests__/db/migrate/roundtrip.test.ts
index b9b84c38..d18cd194 100644
--- a/server/src/__tests__/db/migrate/roundtrip.test.ts
+++ b/server/src/__tests__/db/migrate/roundtrip.test.ts
@@ -25,6 +25,7 @@ const CUSTOM_MODEL_ENDPOINT_IDENTITY_FILENAME = '20260729_000001_custom_model_en
const CUSTOM_ENDPOINT_HOST_LABELS_FILENAME = '20260802_000001_custom_endpoint_host_labels.ts';
const KEY_MODEL_SCOPE_FILENAME = '20260805_000001_key_model_scope.ts';
const CLIENT_PROFILES_FILENAME = '20260805_000002_client_profiles.ts';
+const API_KEY_PROXY_FILENAME = '20260810_000001_api_key_proxy.ts';
interface SchemaRow {
type: string;
@@ -96,6 +97,7 @@ describe('migration round trip', () => {
CUSTOM_ENDPOINT_HOST_LABELS_FILENAME,
KEY_MODEL_SCOPE_FILENAME,
CLIENT_PROFILES_FILENAME,
+ API_KEY_PROXY_FILENAME,
]);
} finally {
db.close();
diff --git a/server/src/__tests__/lib/proxy.test.ts b/server/src/__tests__/lib/proxy.test.ts
index 7d1e661f..a42d4dec 100644
--- a/server/src/__tests__/lib/proxy.test.ts
+++ b/server/src/__tests__/lib/proxy.test.ts
@@ -14,6 +14,7 @@ import {
PROXY_SCHEMES,
proxyFetch,
describeAbort,
+ withKeyProxy,
} from '../../lib/proxy.js';
// Every env var the proxy config reads, in both the upper- and lower-case
@@ -568,3 +569,131 @@ describe('proxyFetch abort error enrichment', () => {
).rejects.toBe(typeErr);
});
});
+
+// Per-key proxy override (#590). The fallback loop wraps each dispatch in
+// withKeyProxy(route.proxyUrl, ...), which parks the URL in AsyncLocalStorage;
+// dispatchFetch reads it there and prefers it over the global proxy. Providers
+// are process singletons, so ALS is what makes "this key exits from there"
+// possible without threading a proxy argument through every provider call.
+//
+// Assertions ride the SOCKS path: the agent handed to https.request carries the
+// proxy host/port, so which dispatcher was chosen is directly observable
+// (undici's ProxyAgent is opaque by comparison, and the port makes global vs
+// per-key unambiguous).
+describe('per-key proxy override (#590)', () => {
+ const agentPortOf = (spy: ReturnType<typeof stubHttpsRequest>, call = 0): unknown =>
+ ((spy.mock.calls[call]?.[0] as any)?.agent)?.proxy?.port;
+
+ it('routes the attempt through the key\'s own proxy instead of the global one', async () => {
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('socks5://127.0.0.1:1081', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(agentPortOf(reqSpy)).toBe(1081);
+ });
+
+ it('proxies through the key\'s proxy even when no global proxy is configured', async () => {
+ applyProxyUrl('');
+ const fetchSpy = vi.spyOn(global, 'fetch');
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('socks5h://127.0.0.1:1082', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(agentPortOf(reqSpy)).toBe(1082);
+ expect(fetchSpy).not.toHaveBeenCalled();
+ });
+
+ it('an empty override falls through to the global proxy', async () => {
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('', () => proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+ await withKeyProxy(undefined, () => proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(agentPortOf(reqSpy, 0)).toBe(1080);
+ expect(agentPortOf(reqSpy, 1)).toBe(1080);
+ });
+
+ it('the override does not outlive the call it was set for', async () => {
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('socks5://127.0.0.1:1083', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+ // Next request, no override in scope: back to the global proxy.
+ await proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq');
+
+ expect(agentPortOf(reqSpy, 0)).toBe(1083);
+ expect(agentPortOf(reqSpy, 1)).toBe(1080);
+ });
+
+ it('keeps concurrent attempts on their own key\'s proxy', async () => {
+ applyProxyUrl('');
+ const reqSpy = stubHttpsRequest();
+
+ await Promise.all([
+ withKeyProxy('socks5://127.0.0.1:1084', () => proxyFetch('https://a.example.com/v1', undefined, 'groq')),
+ withKeyProxy('socks5://127.0.0.1:1085', () => proxyFetch('https://b.example.com/v1', undefined, 'groq')),
+ ]);
+
+ const ports = reqSpy.mock.calls.map(call => ((call[0] as any).agent)?.proxy?.port).sort();
+ expect(ports).toEqual([1084, 1085]);
+ });
+
+ it('still honors NO_PROXY for the upstream host', async () => {
+ process.env.NO_PROXY = 'api.example.com';
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(okResponse());
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('socks5://127.0.0.1:1086', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(reqSpy).not.toHaveBeenCalled();
+ expect((fetchSpy.mock.calls[0]?.[1] as any)?.dispatcher).toBeUndefined();
+ });
+
+ it('still honors the per-platform bypass list', async () => {
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ applyProxyBypass('groq');
+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(okResponse());
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('socks5://127.0.0.1:1087', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(reqSpy).not.toHaveBeenCalled();
+ expect((fetchSpy.mock.calls[0]?.[1] as any)?.dispatcher).toBeUndefined();
+ });
+
+ it('still honors the global proxy off switch', async () => {
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ applyProxyEnabled(false);
+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(okResponse());
+ const reqSpy = stubHttpsRequest();
+
+ await withKeyProxy('socks5://127.0.0.1:1088', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(reqSpy).not.toHaveBeenCalled();
+ expect((fetchSpy.mock.calls[0]?.[1] as any)?.dispatcher).toBeUndefined();
+ });
+
+ it('falls back to the global proxy when the key\'s proxy cannot be built, without logging its credentials', async () => {
+ const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+ applyProxyUrl('socks5://127.0.0.1:1080');
+ const reqSpy = stubHttpsRequest();
+
+ // A port outside the valid range makes SocksProxyAgent throw on construction.
+ await withKeyProxy('socks5h://alice:[email protected]:not-a-port', () =>
+ proxyFetch('https://api.example.com/v1', { method: 'POST' }, 'groq'));
+
+ expect(agentPortOf(reqSpy)).toBe(1080);
+ const logged = errSpy.mock.calls.flat().join(' ');
+ expect(logged).toContain('per-key dispatcher');
+ expect(logged).not.toContain('hunter2');
+ });
+});
diff --git a/server/src/__tests__/routes/keys-proxy.test.ts b/server/src/__tests__/routes/keys-proxy.test.ts
new file mode 100644
index 00000000..88b05e56
--- /dev/null
+++ b/server/src/__tests__/routes/keys-proxy.test.ts
@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb } from '../../db/index.js';
+import { encrypt } from '../../lib/crypto.js';
+import { decryptProxyUrl } from '../../lib/key-proxy.js';
+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';
+
+let dashToken = '';
+
+async function request(app: Express, method: string, path: string, body?: any) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const url = `http://127.0.0.1:${addr.port}${path}`;
+
+ const res = await fetch(url, {
+ method,
+ headers: {
+ ...(body ? { 'Content-Type': 'application/json' } : {}),
+ ...(isGatedApiPath(path) ? { Authorization: `Bearer ${dashToken}` } : {}),
+ },
+ body: body ? JSON.stringify(body) : undefined,
+ });
+
+ const data = await res.json().catch(() => null);
+ server.close();
+ return { status: res.status, body: data };
+}
+
+const PROXY_WITH_CREDS = 'socks5h://alice:[email protected]:1080';
+
+// Per-key proxy override (#590). The URL is a credential in its own right —
+// `user:pass@` is the norm for commercial proxies — so it is stored with the
+// same AES-256-GCM treatment as the API key on the row, never echoed back in
+// the clear, and only accepted on schemes the proxy layer can dispatch through.
+describe('Keys API — per-key proxy override (#590)', () => {
+ let app: Express;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ app = createApp();
+ dashToken = mintDashboardToken();
+ });
+
+ beforeEach(() => {
+ getDb().prepare('DELETE FROM api_keys').run();
+ });
+
+ function insertKey(): number {
+ const { encrypted, iv, authTag } = encrypt('sk-test');
+ const result = getDb().prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
+ VALUES ('groq', 'test', ?, ?, ?, 'healthy', 1)
+ `).run(encrypted, iv, authTag);
+ return Number(result.lastInsertRowid);
+ }
+
+ const proxyRow = (id: number) => getDb().prepare(
+ 'SELECT proxy_encrypted, proxy_iv, proxy_auth_tag FROM api_keys WHERE id = ?',
+ ).get(id) as { proxy_encrypted: string | null; proxy_iv: string | null; proxy_auth_tag: string | null };
+
+ describe('POST /api/keys', () => {
+ it('stores the proxy URL encrypted, never as plaintext', async () => {
+ const post = await request(app, 'POST', '/api/keys', {
+ platform: 'groq', key: 'sk-groq-1', proxyUrl: PROXY_WITH_CREDS,
+ });
+ expect(post.status).toBe(201);
+
+ const row = proxyRow(Number(post.body.id));
+ expect(row.proxy_encrypted).toBeTruthy();
+ expect(row.proxy_iv).toBeTruthy();
+ expect(row.proxy_auth_tag).toBeTruthy();
+ // Nothing recognisable survives in the column: not the password, not the
+ // username, not the host, not even the scheme.
+ const stored = String(row.proxy_encrypted);
+ for (const secret of ['hunter2', 'alice', 'proxy.internal', 'socks5h', '1080']) {
+ expect(stored).not.toContain(secret);
+ }
+ // ...and it round-trips.
+ expect(decryptProxyUrl(row)).toBe(PROXY_WITH_CREDS);
+ });
+
+ it('answers with the password masked, not the URL it was given', async () => {
+ const post = await request(app, 'POST', '/api/keys', {
+ platform: 'groq', key: 'sk-groq-1', proxyUrl: PROXY_WITH_CREDS,
+ });
+ expect(post.body.maskedProxyUrl).toBe('socks5h://alice:***@proxy.internal:1080');
+ expect(JSON.stringify(post.body)).not.toContain('hunter2');
+ });
+
+ it('leaves the columns NULL when no override is given', async () => {
+ const post = await request(app, 'POST', '/api/keys', { platform: 'groq', key: 'sk-groq-1' });
+ expect(post.status).toBe(201);
+ expect(post.body.maskedProxyUrl).toBe('');
+ const row = proxyRow(Number(post.body.id));
+ expect(row.proxy_encrypted).toBeNull();
+ expect(row.proxy_iv).toBeNull();
+ expect(row.proxy_auth_tag).toBeNull();
+ });
+
+ it('accepts every scheme the proxy layer can dispatch through', async () => {
+ for (const proxyUrl of [
+ 'http://proxy:8080',
+ 'https://proxy:8443',
+ 'socks4://127.0.0.1:1080',
+ 'socks4a://127.0.0.1:1080',
+ 'socks5://127.0.0.1:1080',
+ 'socks5h://user:[email protected]:1080',
+ '', // explicit "no override"
+ ]) {
+ const post = await request(app, 'POST', '/api/keys', { platform: 'groq', key: 'sk-groq-1', proxyUrl });
+ expect(post.status, proxyUrl).toBe(201);
+ }
+ });
+
+ it('rejects a scheme the proxy layer cannot dispatch through', async () => {
+ for (const proxyUrl of ['ftp://proxy:21', 'file:///etc/passwd', 'ws://proxy:8080', 'javascript:alert(1)']) {
+ const post = await request(app, 'POST', '/api/keys', { platform: 'groq', key: 'sk-groq-1', proxyUrl });
+ expect(post.status, proxyUrl).toBe(400);
+ expect(post.body.error.message).toMatch(/socks5/);
+ }
+ expect(getDb().prepare('SELECT COUNT(*) AS n FROM api_keys').get()).toEqual({ n: 0 });
+ });
+
+ it('rejects anything that is not a URL at all', async () => {
+ for (const proxyUrl of ['proxy.internal:1080', 'not a url', 'http://', ' ']) {
+ const post = await request(app, 'POST', '/api/keys', { platform: 'groq', key: 'sk-groq-1', proxyUrl });
+ // A whitespace-only value is the "clear it" spelling, so it is legal.
+ expect(post.status, proxyUrl).toBe(proxyUrl.trim() === '' ? 201 : 400);
+ }
+ });
+ });
+
+ describe('PATCH /api/keys/:id', () => {
+ it('sets an override on an existing key', async () => {
+ const id = insertKey();
+ const patch = await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: PROXY_WITH_CREDS });
+ expect(patch.status).toBe(200);
+ expect(patch.body.maskedProxyUrl).toBe('socks5h://alice:***@proxy.internal:1080');
+ expect(JSON.stringify(patch.body)).not.toContain('hunter2');
+ expect(decryptProxyUrl(proxyRow(id))).toBe(PROXY_WITH_CREDS);
+ });
+
+ it("'' clears the override back to NULL", async () => {
+ const id = insertKey();
+ await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: PROXY_WITH_CREDS });
+ const patch = await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: '' });
+ expect(patch.status).toBe(200);
+ expect(patch.body.maskedProxyUrl).toBe('');
+ expect(proxyRow(id)).toEqual({ proxy_encrypted: null, proxy_iv: null, proxy_auth_tag: null });
+ expect(decryptProxyUrl(proxyRow(id))).toBe('');
+ });
+
+ it('leaves the override alone when only other fields are patched', async () => {
+ const id = insertKey();
+ await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: PROXY_WITH_CREDS });
+ const patch = await request(app, 'PATCH', `/api/keys/${id}`, { label: 'renamed' });
+ expect(patch.status).toBe(200);
+ expect(patch.body.maskedProxyUrl).toBeUndefined();
+ expect(decryptProxyUrl(proxyRow(id))).toBe(PROXY_WITH_CREDS);
+ });
+
+ it('rejects an invalid override and leaves the stored one untouched', async () => {
+ const id = insertKey();
+ await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: PROXY_WITH_CREDS });
+ const patch = await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: 'ftp://proxy:21' });
+ expect(patch.status).toBe(400);
+ expect(decryptProxyUrl(proxyRow(id))).toBe(PROXY_WITH_CREDS);
+ });
+
+ it('a body naming only proxyUrl satisfies the at-least-one-field rule', async () => {
+ const id = insertKey();
+ const patch = await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: 'http://proxy:8080' });
+ expect(patch.status).toBe(200);
+ });
+ });
+
+ describe('GET /api/keys', () => {
+ it('shows that an override exists without handing the credentials back', async () => {
+ const id = insertKey();
+ await request(app, 'PATCH', `/api/keys/${id}`, { proxyUrl: PROXY_WITH_CREDS });
+
+ const list = await request(app, 'GET', '/api/keys');
+ expect(list.status).toBe(200);
+ const key = list.body.find((k: any) => k.id === id);
+ expect(key.maskedProxyUrl).toBe('socks5h://alice:***@proxy.internal:1080');
+ expect(JSON.stringify(list.body)).not.toContain('hunter2');
+ });
+
+ it("reports '' for a key with no override", async () => {
+ const id = insertKey();
+ const list = await request(app, 'GET', '/api/keys');
+ expect(list.body.find((k: any) => k.id === id).maskedProxyUrl).toBe('');
+ });
+ });
+});
diff --git a/server/src/__tests__/services/health-key-proxy.test.ts b/server/src/__tests__/services/health-key-proxy.test.ts
new file mode 100644
index 00000000..ee5c52d8
--- /dev/null
+++ b/server/src/__tests__/services/health-key-proxy.test.ts
@@ -0,0 +1,114 @@
+import { beforeAll, beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { EventEmitter } from 'events';
+import https from 'https';
+import { encrypt } from '../../lib/crypto.js';
+import { encryptProxyUrl } from '../../lib/key-proxy.js';
+import { getDb, initDb } from '../../db/index.js';
+
+const validateKey = vi.hoisted(() => vi.fn());
+
+vi.mock('../../providers/index.js', () => ({
+ resolveProvider: () => ({ name: 'Mistral', validateKey }),
+}));
+
+const { checkKeyHealth, probeKeyValidity } = await import('../../services/health.js');
+const { applyProxyUrl, applyProxyEnabled, applyProxyBypass, proxyFetch } = await import('../../lib/proxy.js');
+
+// The agent handed to https.request carries the SOCKS proxy's port, so which
+// proxy a validation call went through is directly observable.
+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);
+}
+
+// #590: a key exists behind its own proxy precisely because the provider is
+// unreachable (or geo-blocked) without it. Validating such a key on the direct
+// path would fail three checks in a row and auto-disable a perfectly good
+// credential, so health checks and cooldown probes go through the key's proxy
+// exactly like its traffic does.
+describe('Key health — per-key proxy override (#590)', () => {
+ let nextId = 7000;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ beforeEach(() => {
+ validateKey.mockReset();
+ vi.restoreAllMocks();
+ delete process.env.NO_PROXY;
+ applyProxyEnabled(true);
+ applyProxyBypass('');
+ applyProxyUrl('');
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ function seedKey(proxyUrl: string): number {
+ const id = ++nextId;
+ const key = encrypt('mistral-health-test-key');
+ const proxy = encryptProxyUrl(proxyUrl);
+ getDb().prepare(`
+ INSERT INTO api_keys
+ (id, platform, label, encrypted_key, iv, auth_tag, enabled, status, proxy_encrypted, proxy_iv, proxy_auth_tag)
+ VALUES (?, 'mistral', 'health-test', ?, ?, ?, 1, 'unknown', ?, ?, ?)
+ `).run(id, key.encrypted, key.iv, key.authTag, proxy.encrypted, proxy.iv, proxy.authTag);
+ return id;
+ }
+
+ /** A provider whose validateKey actually reaches out, like the real ones. */
+ function validatingProvider(): void {
+ validateKey.mockImplementation(async () => {
+ await proxyFetch('https://api.mistral.ai/v1/models', undefined, 'mistral');
+ return true;
+ });
+ }
+
+ const agentPortOf = (spy: ReturnType<typeof stubHttpsRequest>): unknown =>
+ ((spy.mock.calls[0]?.[0] as any)?.agent)?.proxy?.port;
+
+ it('checkKeyHealth validates through the key\'s own proxy', async () => {
+ const id = seedKey('socks5h://127.0.0.1:1091');
+ validatingProvider();
+ const reqSpy = stubHttpsRequest();
+
+ expect(await checkKeyHealth(id)).toBe('healthy');
+ expect(agentPortOf(reqSpy)).toBe(1091);
+ });
+
+ it('checkKeyHealth uses the global proxy for a key with no override', async () => {
+ const id = seedKey('');
+ applyProxyUrl('socks5://127.0.0.1:1090');
+ validatingProvider();
+ const reqSpy = stubHttpsRequest();
+
+ expect(await checkKeyHealth(id)).toBe('healthy');
+ expect(agentPortOf(reqSpy)).toBe(1090);
+ });
+
+ it('probeKeyValidity probes through the key\'s own proxy too', async () => {
+ const id = seedKey('socks5://127.0.0.1:1092');
+ applyProxyUrl('socks5://127.0.0.1:1090');
+ validatingProvider();
+ const reqSpy = stubHttpsRequest();
+
+ expect(await probeKeyValidity(id)).toBe('valid');
+ expect(agentPortOf(reqSpy)).toBe(1092);
+ });
+});
diff --git a/server/src/__tests__/services/router-key-proxy.test.ts b/server/src/__tests__/services/router-key-proxy.test.ts
new file mode 100644
index 00000000..82c2256d
--- /dev/null
+++ b/server/src/__tests__/services/router-key-proxy.test.ts
@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeAll, beforeEach, vi, afterEach } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import { encrypt } from '../../lib/crypto.js';
+import { encryptProxyUrl } from '../../lib/key-proxy.js';
+import { routeRequest, setRoutingStrategy } from '../../services/router.js';
+
+// Per-key proxy override (#590): the URL rides on the RouteResult the router
+// already builds, so the dispatch loop needs neither a query nor a decrypt per
+// attempt. These pin that contract — the loop reads route.proxyUrl and nothing
+// else.
+describe('Router — per-key proxy override (#590)', () => {
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ beforeEach(() => {
+ const db = getDb();
+ setRoutingStrategy('priority');
+ db.prepare('DELETE FROM api_keys').run();
+ db.prepare("DELETE FROM settings WHERE key = 'active_profile_id'").run();
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ function insertKey(proxyColumns: { encrypted: string | null; iv: string | null; authTag: string | null }): number {
+ const db = getDb();
+ const { encrypted, iv, authTag } = encrypt('sk-google-1');
+ const result = db.prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, proxy_encrypted, proxy_iv, proxy_auth_tag)
+ VALUES ('google', 'test', ?, ?, ?, 'healthy', 1, ?, ?, ?)
+ `).run(encrypted, iv, authTag, proxyColumns.encrypted, proxyColumns.iv, proxyColumns.authTag);
+ return Number(result.lastInsertRowid);
+ }
+
+ it('carries the decrypted proxy URL on the route', () => {
+ insertKey(encryptProxyUrl('socks5h://alice:[email protected]:1080'));
+ const route = routeRequest();
+ expect(route.platform).toBe('google');
+ expect(route.proxyUrl).toBe('socks5h://alice:[email protected]:1080');
+ });
+
+ it("carries '' for a key with no override", () => {
+ insertKey({ encrypted: null, iv: null, authTag: null });
+ expect(routeRequest().proxyUrl).toBe('');
+ });
+
+ it('falls back to the global proxy when the override cannot be decrypted', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ // Ciphertext from a different ENCRYPTION_KEY: the key itself still works,
+ // so the request must proceed on the global proxy rather than fail.
+ insertKey({ encrypted: 'deadbeef', iv: '00'.repeat(16), authTag: '11'.repeat(16) });
+ const route = routeRequest();
+ expect(route.apiKey).toBe('sk-google-1');
+ expect(route.proxyUrl).toBe('');
+ expect(warn).toHaveBeenCalled();
+ });
+});
diff --git a/server/src/db/migrate/defaults.ts b/server/src/db/migrate/defaults.ts
index 26812471..cec4b27b 100644
--- a/server/src/db/migrate/defaults.ts
+++ b/server/src/db/migrate/defaults.ts
@@ -20,6 +20,7 @@ import * as customModelEndpointIdentity from '../migrations/20260729_000001_cust
import * as customEndpointHostLabels from '../migrations/20260802_000001_custom_endpoint_host_labels.js';
import * as keyModelScope from '../migrations/20260805_000001_key_model_scope.js';
import * as clientProfiles from '../migrations/20260805_000002_client_profiles.js';
+import * as apiKeyProxy from '../migrations/20260810_000001_api_key_proxy.js';
export interface MigrationModule {
up(db: Db): void;
@@ -52,6 +53,7 @@ export const CUSTOM_MODEL_ENDPOINT_IDENTITY_FILENAME = '20260729_000001_custom_m
export const CUSTOM_ENDPOINT_HOST_LABELS_FILENAME = '20260802_000001_custom_endpoint_host_labels.ts';
export const KEY_MODEL_SCOPE_FILENAME = '20260805_000001_key_model_scope.ts';
export const CLIENT_PROFILES_FILENAME = '20260805_000002_client_profiles.ts';
+export const API_KEY_PROXY_FILENAME = '20260810_000001_api_key_proxy.ts';
export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [
{ filename: LEGACY_BASELINE_FILENAME, module: legacyBaseline },
@@ -75,4 +77,5 @@ export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [
{ filename: CUSTOM_ENDPOINT_HOST_LABELS_FILENAME, module: customEndpointHostLabels },
{ filename: KEY_MODEL_SCOPE_FILENAME, module: keyModelScope },
{ filename: CLIENT_PROFILES_FILENAME, module: clientProfiles },
+ { filename: API_KEY_PROXY_FILENAME, module: apiKeyProxy },
];
diff --git a/server/src/db/migrations/20260810_000001_api_key_proxy.ts b/server/src/db/migrations/20260810_000001_api_key_proxy.ts
new file mode 100644
index 00000000..24171ead
--- /dev/null
+++ b/server/src/db/migrations/20260810_000001_api_key_proxy.ts
@@ -0,0 +1,37 @@
+import type { Db } from '../types.js';
+
+/**
+ * Per-key proxy override (#590): a key can carry its own proxy URL
+ * (http/https/socks4/socks4a/socks5/socks5h) so the same provider can be
+ * reached from different exit IPs while the global proxy stays the default.
+ *
+ * The URL is stored ENCRYPTED, not as plain text: a proxy URL routinely
+ * embeds `user:pass@` credentials, which are exactly as sensitive as the API
+ * key sitting in the same row — storing them in the clear next to an
+ * AES-encrypted key would hand anyone who copied the DB a working set of
+ * proxy credentials. So it mirrors the key's own storage: ciphertext + iv +
+ * auth tag from lib/crypto.ts (AES-256-GCM). All three columns NULL = no
+ * per-key override (the API surface spells that as '').
+ */
+const COLUMNS = ['proxy_encrypted', 'proxy_iv', 'proxy_auth_tag'] as const;
+
+function hasColumn(db: Db, table: string, column: string): boolean {
+ const columns = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[];
+ return columns.some((candidate) => candidate.name === column);
+}
+
+export function up(db: Db): void {
+ for (const column of COLUMNS) {
+ if (!hasColumn(db, 'api_keys', column)) {
+ db.prepare(`ALTER TABLE api_keys ADD COLUMN ${column} TEXT`).run();
+ }
+ }
+}
+
+export function down(db: Db): void {
+ for (const column of COLUMNS) {
+ if (hasColumn(db, 'api_keys', column)) {
+ db.prepare(`ALTER TABLE api_keys DROP COLUMN ${column}`).run();
+ }
+ }
+}
diff --git a/server/src/lib/fallback-loop.ts b/server/src/lib/fallback-loop.ts
index d407a663..6920e6f8 100644
--- a/server/src/lib/fallback-loop.ts
+++ b/server/src/lib/fallback-loop.ts
@@ -52,6 +52,7 @@ import { getSetting } from '../db/index.js';
import { newBreaker, recordBreakerFailure } from './guardrails.js';
import { getRequestTrace, newRequestTrace, runWithRequestTrace, type AttemptOutcome, type AttemptTraceRecord, type RequestTrace } from './attempt-trace.js';
import { logRequest, persistRequestAttempts } from './request-log.js';
+import { withKeyProxy } from './proxy.js';
// Every surface caps failover hops at the same number.
export const FALLBACK_MAX_RETRIES = 20;
@@ -1080,7 +1081,12 @@ async function runFallbackLoopAttempts(hooks: FallbackHooks, trace: RequestTrace
try {
let outcome: DispatchOutcome;
try {
- outcome = await hooks.dispatch(route, attempt);
+ // #590 (per-key proxy): if THIS key carries its own proxy URL, route the
+ // attempt through it (withKeyProxy → proxyFetch reads the ALS store);
+ // otherwise the global proxy / direct path applies as before. The URL
+ // arrives already decrypted on the route (services/router.ts), so an
+ // attempt costs nothing extra — no query, no decrypt.
+ outcome = await withKeyProxy(route.proxyUrl, () => hooks.dispatch(route, attempt));
} catch (err: any) {
// Client-caused abort: the composed fetch signal fired because OUR
// client hung up mid-attempt (see newClientAbortError). Not a
diff --git a/server/src/lib/key-proxy.ts b/server/src/lib/key-proxy.ts
new file mode 100644
index 00000000..3c5c4c20
--- /dev/null
+++ b/server/src/lib/key-proxy.ts
@@ -0,0 +1,104 @@
+import { encrypt, decrypt } from './crypto.js';
+import { PROXY_SCHEMES } from './proxy.js';
+
+/**
+ * Per-key proxy override (#590) — storage and presentation helpers.
+ *
+ * A proxy URL routinely carries `user:pass@` credentials, so it is stored the
+ * same way the API key on that row is: AES-256-GCM ciphertext + iv + auth tag
+ * (see the 20260810_000001_api_key_proxy migration). Everything outside the DB
+ * layer speaks in plain strings, with '' meaning "no override".
+ */
+
+/** The three columns that hold a key's encrypted proxy URL. */
+export interface EncryptedProxyColumns {
+ proxy_encrypted: string | null;
+ proxy_iv: string | null;
+ proxy_auth_tag: string | null;
+}
+
+/** The accepted schemes, spelled for humans (error messages, docs). */
+const SCHEME_LIST = 'http, https, socks4, socks4a, socks5 or socks5h';
+
+export const KEY_PROXY_URL_ERROR =
+ `proxyUrl must be a valid proxy URL using ${SCHEME_LIST} (e.g. socks5://user:pass@host:1080), or '' to clear it`;
+
+/** Longest proxy URL accepted — generous for credentials, bounded for the DB. */
+export const KEY_PROXY_URL_MAX = 2048;
+
+/**
+ * True when `url` is storable as a per-key override: either '' (no override)
+ * or a parseable URL on one of the schemes the proxy layer can dispatch
+ * through. Deliberately the SAME scheme list the global proxy validator uses
+ * (routes/settings.ts), so a URL that works globally works per-key.
+ */
+export function isValidKeyProxyUrl(url: string): boolean {
+ const trimmed = url.trim();
+ if (!trimmed) return true;
+ if (trimmed.length > KEY_PROXY_URL_MAX) return false;
+ let parsed: URL;
+ try {
+ parsed = new URL(trimmed);
+ } catch {
+ return false;
+ }
+ if (!PROXY_SCHEMES.includes(parsed.protocol)) return false;
+ // `http://` parses fine but names no host to connect to.
+ return parsed.hostname !== '';
+}
+
+/**
+ * Encrypt a per-key proxy URL for storage. '' (or whitespace) clears the
+ * override, which is all three columns NULL.
+ */
+export function encryptProxyUrl(url: string): { encrypted: string | null; iv: string | null; authTag: string | null } {
+ const trimmed = url.trim();
+ if (!trimmed) return { encrypted: null, iv: null, authTag: null };
+ const { encrypted, iv, authTag } = encrypt(trimmed);
+ return { encrypted, iv, authTag };
+}
+
+/**
+ * Read a per-key proxy URL back off a row. Returns '' for "no override" and
+ * also for a row that cannot be decrypted (a DB carried over to a different
+ * ENCRYPTION_KEY): a failed decrypt must degrade to the global proxy, never
+ * take the request down — the key itself fails loudly on the same row anyway.
+ */
+export function decryptProxyUrl(row: Partial<EncryptedProxyColumns> | undefined | null): string {
+ if (!row?.proxy_encrypted || !row.proxy_iv || !row.proxy_auth_tag) return '';
+ try {
+ return decrypt(row.proxy_encrypted, row.proxy_iv, row.proxy_auth_tag).trim();
+ } catch {
+ console.warn('[proxy] A key\'s proxy override could not be decrypted — falling back to the global proxy.');
+ return '';
+ }
+}
+
+/**
+ * Render a proxy URL for the dashboard with any embedded password removed —
+ * the counterpart of maskKey() for this field. The username stays visible
+ * (it identifies the account without being the secret):
+ * socks5://alice:[email protected]:1080 → socks5://alice:***@proxy.internal:1080
+ * '' stays ''.
+ */
+export function maskProxyUrl(url: string): string {
+ const trimmed = url.trim();
+ if (!trimmed) return '';
+ // Split on the LAST '@' before the first '/' of the path so a password
+ // containing '@' can't shorten the match.
+ const schemeEnd = trimmed.indexOf('://');
+ if (schemeEnd < 0) return trimmed.replace(/:[^:@]*@/, ':***@');
+ const scheme = trimmed.slice(0, schemeEnd + 3);
+ const rest = trimmed.slice(schemeEnd + 3);
+ const pathStart = rest.search(/[/?#]/);
+ const authority = pathStart < 0 ? rest : rest.slice(0, pathStart);
+ const tail = pathStart < 0 ? '' : rest.slice(pathStart);
+ const at = authority.lastIndexOf('@');
+ if (at < 0) return trimmed;
+ const userinfo = authority.slice(0, at);
+ const host = authority.slice(at + 1);
+ const colon = userinfo.indexOf(':');
+ // Userinfo with no password has nothing to hide.
+ if (colon < 0) return trimmed;
+ return `${scheme}${userinfo.slice(0, colon)}:***@${host}${tail}`;
+}
diff --git a/server/src/lib/proxy.ts b/server/src/lib/proxy.ts
index fed959be..d7d12132 100644
--- a/server/src/lib/proxy.ts
+++ b/server/src/lib/proxy.ts
@@ -1,7 +1,21 @@
import http from 'http';
import https from 'https';
+import { AsyncLocalStorage } from 'node:async_hooks';
import { assertProviderUrlAllowed } 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
+// singletons, so the per-key override cannot live on the provider instance —
+// it rides request-scoped AsyncLocalStorage instead, set by the dispatcher
+// around a provider call and read here in proxyFetch.
+const perKeyProxyStore = new AsyncLocalStorage<string>();
+
+/** Run `fn` with a per-key proxy override in effect; empty URL = global proxy. */
+export function withKeyProxy<T>(proxyUrl: string | undefined, fn: () => T): T {
+ return perKeyProxyStore.run(proxyUrl ?? '', fn);
+}
+
+
// 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,
// which throws on some Node 20.x builds ("webidl.util.markAsUncloneable is not
@@ -128,6 +142,37 @@ let cached: {
} | null = null;
const CACHE_TTL_MS = 30_000;
+// #590: per-key proxy dispatchers, keyed by the key's proxy URL. Independent
+// of the global cache so a per-key override never poisons the global one.
+//
+// A working dispatcher is cached for as long as it stays in the map: the cache
+// key IS the whole proxy URL, so unlike the global entry (whose URL can change
+// under it) it can never go stale — re-building it on a timer would only churn
+// connection pools. A FAILED build is cached briefly instead, so a proxy that
+// was down doesn't stay written off forever.
+//
+// The map is bounded: entries are per distinct proxy URL, so at human scale
+// this holds a handful, but nothing stops an operator from pointing a hundred
+// keys at a hundred rotating exits. Oldest-first eviction keeps a bad day from
+// turning into an unbounded pile of agents. An evicted (or expired) dispatcher
+// is dropped, not closed — closing it would tear down requests still streaming
+// through it; the GC collects it once they finish. Same as the global cache.
+const perKeyCached = new Map<string, { dispatcher: unknown | undefined; isSocks: boolean; ts: number }>();
+const PER_KEY_FAILURE_TTL_MS = 30_000;
+const PER_KEY_CACHE_MAX = 32;
+
+function rememberPerKeyDispatcher(proxyUrl: string, entry: { dispatcher: unknown | undefined; isSocks: boolean; ts: number }): void {
+ // Delete-then-set so re-use moves an entry to the young end of the map and
+ // eviction takes the genuinely least-recently-used URL.
+ perKeyCached.delete(proxyUrl);
+ perKeyCached.set(proxyUrl, entry);
+ while (perKeyCached.size > PER_KEY_CACHE_MAX) {
+ const oldest = perKeyCached.keys().next().value;
+ if (oldest === undefined) break;
+ perKeyCached.delete(oldest);
+ }
+}
+
/** Called once at startup (after initDb) and on PUT /api/settings/proxy. */
export function applyProxyUrl(dbValue: string): void {
const { url, source } = resolveProxySource(dbValue);
@@ -502,6 +547,28 @@ async function dispatchFetch(
requestType: ProxyRequestType,
timeoutMs: number | undefined,
): Promise<Response> {
+ // #590: a per-key proxy override (set via withKeyProxy around the provider
+ // call) takes precedence over the global proxy for THIS request. Empty
+ // string (the store default) means "fall back to global".
+ 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.
+ if (!shouldBypassProxy(url, platform)) {
+ const resolved = await resolvePerKeyDispatcher(perKeyUrl);
+ if (resolved) {
+ if (resolved.isSocks) {
+ return socksFetch(url, init, resolved.dispatcher as http.Agent, platform, requestType, timeoutMs);
+ }
+ return fetch(url, { ...init, dispatcher: resolved.dispatcher } as unknown as RequestInit);
+ }
+ }
+ // 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.
if (shouldBypassProxy(url, platform)) {
@@ -524,6 +591,37 @@ async function dispatchFetch(
return fetch(url, { ...init, dispatcher: resolved.dispatcher } as unknown as RequestInit);
}
+/** Build (and TTL-cache) a dispatcher for a per-key proxy URL. Returns
+ * undefined when the URL is empty or the agent fails to build. */
+async function resolvePerKeyDispatcher(proxyUrl: string): Promise<{ dispatcher: unknown; isSocks: boolean } | undefined> {
+ const now = Date.now();
+ const hit = perKeyCached.get(proxyUrl);
+ if (hit?.dispatcher) {
+ rememberPerKeyDispatcher(proxyUrl, hit);
+ return { dispatcher: hit.dispatcher, isSocks: hit.isSocks };
+ }
+ // Negative entry, still inside its cool-off: don't retry the build yet.
+ if (hit && now - hit.ts < PER_KEY_FAILURE_TTL_MS) return undefined;
+
+ try {
+ const isSocks = isSocksProxyUrl(proxyUrl);
+ if (isSocks) {
+ const SocksAgent = await loadSocksAgent();
+ const dispatcher = new SocksAgent(proxyUrl);
+ rememberPerKeyDispatcher(proxyUrl, { dispatcher, isSocks: true, ts: now });
+ return { dispatcher, isSocks: true };
+ }
+ const ProxyAgentCtor = await loadHttpProxyAgent();
+ const dispatcher = new ProxyAgentCtor({ uri: proxyUrl });
+ rememberPerKeyDispatcher(proxyUrl, { dispatcher, isSocks: false, ts: now });
+ return { dispatcher, isSocks: false };
+ } catch (err: any) {
+ console.error(`[proxy] Failed to create per-key dispatcher for "${redactProxyUrl(proxyUrl)}": ${err.message}`);
+ rememberPerKeyDispatcher(proxyUrl, { dispatcher: undefined, isSocks: false, ts: now });
+ return undefined;
+ }
+}
+
/**
* Returns true when the proxy is configured AND enabled. Used by the dashboard
* to show the "Active" badge. Intentionally does NOT construct a dispatcher (so
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index 44dbc9ec..9479481d 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -18,6 +18,7 @@ import { probeEmbeddingDimensions, registerCustomEmbeddingModel } from '../servi
import { endpointScopeForBaseUrl, normalizeBaseUrl } from '../lib/endpoint-scope.js';
import type { Db } from '../db/types.js';
import { parseModelScope } from '../lib/model-scope.js';
+import { KEY_PROXY_URL_ERROR, KEY_PROXY_URL_MAX, decryptProxyUrl, encryptProxyUrl, isValidKeyProxyUrl, maskProxyUrl } from '../lib/key-proxy.js';
export const keysRouter = Router();
@@ -49,10 +50,17 @@ const upload = multer({
// `key` is optional so keyless providers (Kilo's anonymous gateway) can be added
// without one; the handler enforces a non-empty key for everyone else.
+// #590 (per-key proxy): an optional per-key proxy override. Only schemes the
+// proxy layer can actually dispatch through are accepted — an unvalidated
+// string would be stored, encrypted, and only surface as a failed dispatcher
+// at request time, one attempt at a time. '' = no override (global proxy).
+const proxyUrlSchema = z.string().max(KEY_PROXY_URL_MAX).refine(isValidKeyProxyUrl, { message: KEY_PROXY_URL_ERROR });
+
const addKeySchema = z.object({
platform: z.enum(PLATFORMS),
key: z.string().optional(),
label: z.string().optional(),
+ proxyUrl: proxyUrlSchema.optional(),
});
// `modelScope` (#657): the model_id list this key may serve — relay stations
@@ -62,8 +70,10 @@ const updateKeySchema = z.object({
enabled: z.boolean().optional(),
label: z.string().optional(),
modelScope: z.array(z.string().trim().min(1).max(200)).max(100).nullable().optional(),
-}).refine(data => data.enabled !== undefined || data.label !== undefined || data.modelScope !== undefined, {
- message: 'At least one of enabled, label or modelScope must be provided',
+ // #590: '' clears the per-key proxy; absent leaves it unchanged.
+ proxyUrl: proxyUrlSchema.optional(),
+}).refine(data => data.enabled !== undefined || data.label !== undefined || data.modelScope !== undefined || data.proxyUrl !== undefined, {
+ message: 'At least one of enabled, label, modelScope or proxyUrl must be provided',
});
const importKeySchema = z.object({
@@ -312,6 +322,10 @@ keysRouter.get('/', (_req: Request, res: Response) => {
lastHealthError: row.last_health_error ?? null,
// The model_id list this key is limited to; null = serves everything (#657).
modelScope: scope ? [...scope] : null,
+ // The per-key proxy override with its password masked (#590). '' = no
+ // override. Enough for the dashboard to show that a key routes through
+ // its own exit, without handing the proxy credentials back out.
+ maskedProxyUrl: maskProxyUrl(decryptProxyUrl(row)),
models: row.platform === 'custom' ? (modelsByEndpoint.get(endpointOf(Number(row.id))) ?? []) : undefined,
cooldowns: cooldowns.map(c => ({
modelId: c.modelId,
@@ -567,15 +581,22 @@ keysRouter.post('/', (req: Request, res: Response) => {
}
const { encrypted, iv, authTag } = encrypt(keyToStore);
+ // #590: the proxy URL is encrypted like the key itself — it usually embeds
+ // `user:pass@` credentials. Absent/'' stores NULLs = no override.
+ const proxyUrl = parsed.data.proxyUrl?.trim() ?? '';
+ const proxy = encryptProxyUrl(proxyUrl);
const result = db.prepare(`
- INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
- VALUES (?, ?, ?, ?, ?, 'unknown', 1)
- `).run(platform, label ?? '', encrypted, iv, authTag);
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, proxy_encrypted, proxy_iv, proxy_auth_tag)
+ VALUES (?, ?, ?, ?, ?, 'unknown', 1, ?, ?, ?)
+ `).run(platform, label ?? '', encrypted, iv, authTag, proxy.encrypted, proxy.iv, proxy.authTag);
res.status(201).json({
id: result.lastInsertRowid,
platform,
label: label ?? '',
+ // Echoed back masked, never in the clear — the response body ends up in
+ // logs and dev tools.
+ maskedProxyUrl: maskProxyUrl(proxyUrl),
maskedKey: maskKey(keyToStore),
status: 'unknown',
enabled: true,
@@ -1470,7 +1491,7 @@ keysRouter.patch('/:id', (req: Request, res: Response) => {
return;
}
- const { enabled, label, modelScope } = parsed.data;
+ const { enabled, label, modelScope, proxyUrl } = parsed.data;
const updates: string[] = [];
const values: (string | number | null)[] = [];
@@ -1482,6 +1503,13 @@ keysRouter.patch('/:id', (req: Request, res: Response) => {
updates.push('label = ?');
values.push(label);
}
+ // #590: stored encrypted (credentials), so a change rewrites all three
+ // columns; '' clears them to NULL.
+ if (proxyUrl !== undefined) {
+ const proxy = encryptProxyUrl(proxyUrl);
+ updates.push('proxy_encrypted = ?', 'proxy_iv = ?', 'proxy_auth_tag = ?');
+ values.push(proxy.encrypted, proxy.iv, proxy.authTag);
+ }
// Deduped; an empty result stores NULL, which the router reads as "unscoped".
const scopeIds = modelScope == null ? [] : [...new Set(modelScope)];
if (modelScope !== undefined) {
@@ -1502,6 +1530,7 @@ keysRouter.patch('/:id', (req: Request, res: Response) => {
const response: Record<string, unknown> = { success: true };
if (enabled !== undefined) response.enabled = enabled;
if (label !== undefined) response.label = label;
+ if (proxyUrl !== undefined) response.maskedProxyUrl = maskProxyUrl(proxyUrl);
if (modelScope !== undefined) response.modelScope = scopeIds.length > 0 ? scopeIds : null;
res.json(response);
});
diff --git a/server/src/services/health.ts b/server/src/services/health.ts
index e749619e..dc9927f1 100644
--- a/server/src/services/health.ts
+++ b/server/src/services/health.ts
@@ -1,6 +1,8 @@
import { getDb } from '../db/index.js';
import { resolveProvider } from '../providers/index.js';
import { decrypt } from '../lib/crypto.js';
+import { decryptProxyUrl } from '../lib/key-proxy.js';
+import { withKeyProxy } from '../lib/proxy.js';
import type { Platform, KeyStatus } from '@freellmapi/shared/types.js';
import { inferQuotaPoolKey } from './provider-quota.js';
import type { Scheduler } from '../lib/scheduler.js';
@@ -77,13 +79,17 @@ export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {
try {
const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
- const validation = await provider.validateKey(apiKey, {
+ // #590: probe the key from the same exit its traffic uses. A key that is
+ // only reachable through its own proxy (the reason to set one) would
+ // otherwise be validated direct, fail, and be auto-disabled after three
+ // checks while real requests through the proxy were working fine.
+ const validation = await withKeyProxy(decryptProxyUrl(row), () => provider.validateKey(apiKey, {
platform: row.platform as Platform,
keyId,
quotaPoolKey: inferQuotaPoolKey(row.platform as Platform, null),
endpoint: 'models',
origin: 'health',
- });
+ }));
const isValid = typeof validation === 'boolean' ? validation : validation.valid;
const lastError = isValid
? null
@@ -157,13 +163,14 @@ export async function probeKeyValidity(keyId: number): Promise<KeyProbeOutcome>
if (!provider) return 'error';
const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
- const validation = await provider.validateKey(apiKey, {
+ // Same reasoning as checkKeyHealth: probe through the key's own proxy (#590).
+ const validation = await withKeyProxy(decryptProxyUrl(row), () => provider.validateKey(apiKey, {
platform: row.platform as Platform,
keyId,
quotaPoolKey: inferQuotaPoolKey(row.platform as Platform, null),
endpoint: 'models',
origin: 'probe',
- });
+ }));
const isValid = typeof validation === 'boolean' ? validation : validation.valid;
return isValid ? 'valid' : 'invalid';
} catch {
diff --git a/server/src/services/router.ts b/server/src/services/router.ts
index 87ce9741..67d7bcc4 100644
--- a/server/src/services/router.ts
+++ b/server/src/services/router.ts
@@ -1,6 +1,7 @@
import { getDb, getSetting, setSetting } from '../db/index.js';
import { getProvider, hasProvider, resolveProvider } from '../providers/index.js';
import { decrypt } from '../lib/crypto.js';
+import { decryptProxyUrl } from '../lib/key-proxy.js';
import {
canMakeRequest,
canUseTokens,
@@ -121,6 +122,10 @@ interface KeyRow {
// Optional JSON array of model_id strings this key may serve; NULL = every
// model of its platform (#657).
model_scope_json: string | null;
+ // Encrypted per-key proxy override (#590); all NULL = no override.
+ proxy_encrypted: string | null;
+ proxy_iv: string | null;
+ proxy_auth_tag: string | null;
}
// Chain row joined with the model fields the bandit needs to score it.
@@ -173,6 +178,17 @@ export interface RouteResult {
* to ONE relay instead of every relay serving the same model id.
*/
endpointScope: string;
+ /**
+ * This key's own proxy URL, already decrypted, '' when it has none (#590).
+ *
+ * It rides the route rather than being looked up at dispatch time on
+ * purpose: selectKeyForModel already reads the whole api_keys row and
+ * already decrypts on it, so the override costs one extra AES-GCM open per
+ * ROUTE — not a prepared SELECT plus a decrypt per ATTEMPT, on the hot path
+ * of every request. Optional so test doubles and any future construction
+ * path simply mean "no override".
+ */
+ proxyUrl?: string;
// Daily limits for this model, so a 429 handler can tell a genuine daily
// exhaustion (escalate the cooldown) from a transient per-minute spike.
rpdLimit: number | null;
@@ -1174,6 +1190,8 @@ function selectKeyForModel(entry: ChainRow, estimatedTokens: number, skipKeys?:
modelDbId: entry.model_db_id,
apiKey: decryptedKey,
keyId: key.id,
+ // Decrypted once here, at the point the row is already in hand (#590).
+ proxyUrl: decryptProxyUrl(key),
platform: entry.platform,
displayName: entry.display_name,
endpointScope: entry.endpoint_scope ?? '',