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 top issues: x-api-key auth (#103), /v1 rate limiting (#35), LAN docs (#147) (#151)
Tashfeenca7cb9ee02c8
diff --git a/.env.example b/.env.exampleindex fe9dd0ef..677a0666 100644--- a/.env.example+++ b/.env.example@@ -4,6 +4,18 @@ ENCRYPTION_KEY=your-64-char-hex-key-here# Server port (default: 3001)PORT=3001+# Docker only: which host interface the container's port is published on.+# Defaults to 127.0.0.1, so the dashboard/API is reachable only from the+# machine running Docker. To open it to other devices on your LAN (e.g. a+# Raspberry Pi reached at http://192.168.1.x:3001), set HOST_BIND=0.0.0.0.+# Only do this on a trusted network — the proxy is single-user and guarded+# only by the unified API key.+# HOST_BIND=0.0.0.0++# Max /v1 proxy requests per minute per client IP (default: 120). Set to 0+# to disable proxy rate limiting.+# PROXY_RATE_LIMIT_RPM=120+# Comma-separated extra origins allowed to call the API from a browser.# localhost:5173, 127.0.0.1:5173, [::1]:5173 are allowed by default for the# Vite dev dashboard. Only set this if you serve the dashboard from adiff --git a/README.md b/README.mdindex bb8b9c3b..cac8df02 100644--- a/README.md+++ b/README.md@@ -121,6 +121,14 @@ docker compose up -dOpen http://localhost:3001, add your provider keys on the **Keys** page, reorder the **Fallback Chain** to taste, and grab your unified API key from the **Keys** page header. That unified key is what you point your OpenAI SDK at.+> **Reaching it from another machine?** By default the container is published only on `127.0.0.1`, so `http://<server-ip>:3001` won't load from another device (the page just hangs). To expose it on your LAN — e.g. a Raspberry Pi at `http://192.168.1.x:3001` — start it with `HOST_BIND=0.0.0.0`:+>+> ```bash+> HOST_BIND=0.0.0.0 docker compose up -d+> ```+>+> Only do this on a trusted network: the proxy is single-user and guarded only by the unified API key.+### Local development**Prerequisites:** Node.js 20+, npm.@@ -165,6 +173,8 @@ docker compose up -ddocker compose logs -f freellmapi```+By default the container's port is bound to `127.0.0.1` (localhost only). To reach the dashboard/API from another machine on your network, publish it on all interfaces with `HOST_BIND=0.0.0.0 docker compose up -d` — only on a trusted LAN, since the proxy is single-user.+SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`. Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because provider keys are encrypted at rest.More Docker operations and examples live in [docker/README.md](./docker/README.md).diff --git a/server/src/__tests__/routes/proxy-auth-cors.test.ts b/server/src/__tests__/routes/proxy-auth-cors.test.tsindex 3f43b3ce..d0431151 100644--- a/server/src/__tests__/routes/proxy-auth-cors.test.ts+++ b/server/src/__tests__/routes/proxy-auth-cors.test.ts@@ -1,7 +1,7 @@import { describe, it, expect, beforeAll } from 'vitest';import type { Express } from 'express';import { createApp } from '../../app.js';-import { initDb } from '../../db/index.js';+import { initDb, getUnifiedApiKey } from '../../db/index.js';async function request(app: Express, method: string, path: string, body?: any, headers: Record<string, string> = {}) {const server = app.listen(0);@@ -41,6 +41,29 @@ describe('Proxy authentication and CORS', () => {expect(body.error.type).toBe('authentication_error');});+ // #103: Claude Code via CC Switch (and other Anthropic-format clients) send+ // the key in the `x-api-key` header, not as an Authorization bearer token.+ it('rejects a wrong key supplied via the x-api-key header', async () => {+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ messages: [{ role: 'user', content: 'hello' }],+ }, { 'x-api-key': 'freellmapi-wrong-key' });++ expect(status).toBe(401);+ expect(body.error.type).toBe('authentication_error');+ });++ it('accepts the unified key supplied via the x-api-key header', async () => {+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {+ messages: [{ role: 'user', content: 'hello' }],+ }, { 'x-api-key': getUnifiedApiKey() });++ // Auth passes — it gets past the 401 gate. (Routing then fails because no+ // provider keys are configured in this test DB, which is fine: we only+ // care that the x-api-key header authenticated.)+ expect(status).not.toBe(401);+ expect(body?.error?.type).not.toBe('authentication_error');+ });+it('does not grant CORS access to arbitrary browser origins', async () => {const { status, headers } = await request(app, 'GET', '/api/ping', undefined, {Origin: 'https://attacker.example',diff --git a/server/src/__tests__/routes/proxy-rate-limit.test.ts b/server/src/__tests__/routes/proxy-rate-limit.test.tsnew file mode 100644index 00000000..094f5886--- /dev/null+++ b/server/src/__tests__/routes/proxy-rate-limit.test.ts@@ -0,0 +1,68 @@+import { describe, it, expect, beforeAll, afterAll } from 'vitest';+import type { Express } from 'express';+import { createApp } from '../../app.js';+import { initDb } from '../../db/index.js';++async function request(app: Express, headers: Record<string, string> = {}) {+ const server = app.listen(0);+ const addr = server.address() as any;+ const url = `http://127.0.0.1:${addr.port}/v1/chat/completions`;++ const res = await fetch(url, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json', ...headers },+ body: JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] }),+ });++ const text = await res.text();+ server.close();++ let json: any = null;+ try { json = JSON.parse(text); } catch {}++ return { status: res.status, body: json, headers: res.headers };+}++describe('Proxy per-IP rate limiting (#35 item #6)', () => {+ const originalRpm = process.env.PROXY_RATE_LIMIT_RPM;++ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ });++ afterAll(() => {+ if (originalRpm === undefined) delete process.env.PROXY_RATE_LIMIT_RPM;+ else process.env.PROXY_RATE_LIMIT_RPM = originalRpm;+ });++ it('returns 429 once the per-minute cap is exceeded', async () => {+ // Limiter reads the env at createApp() time, so set it before building.+ process.env.PROXY_RATE_LIMIT_RPM = '3';+ const app = createApp();++ // First 3 requests pass the limiter (they 401 on auth, but the limiter is+ // upstream of auth, so each one still counts against the window).+ for (let i = 0; i < 3; i++) {+ const res = await request(app);+ expect(res.status).not.toBe(429);+ }++ // The 4th trips the limit.+ const limited = await request(app);+ expect(limited.status).toBe(429);+ expect(limited.body.error.type).toBe('rate_limit_error');+ expect(limited.headers.get('retry-after')).toBeTruthy();+ expect(limited.headers.get('x-ratelimit-limit')).toBe('3');+ });++ it('does not rate-limit when PROXY_RATE_LIMIT_RPM=0', async () => {+ process.env.PROXY_RATE_LIMIT_RPM = '0';+ const app = createApp();++ for (let i = 0; i < 5; i++) {+ const res = await request(app);+ expect(res.status).not.toBe(429);+ }+ });+});diff --git a/server/src/app.ts b/server/src/app.tsindex a2ab60e3..da29f4b3 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -13,6 +13,7 @@ import { healthRouter } from './routes/health.js';import { settingsRouter } from './routes/settings.js';import { authRouter } from './routes/auth.js';import { requireAuth } from './middleware/requireAuth.js';+import { createProxyRateLimiter } from './middleware/rateLimit.js';import { errorHandler } from './middleware/errorHandler.js';const __dirname = path.dirname(fileURLToPath(import.meta.url));@@ -63,7 +64,10 @@ export function createApp() {app.use('/api/health', requireAuth, healthRouter);app.use('/api/settings', requireAuth, settingsRouter);- // OpenAI-compatible proxy+ // OpenAI-compatible proxy. Per-IP rate limiting (#35 item #6) runs first so+ // it throttles unauthenticated brute-force / flood attempts before any+ // routing work. Tune via PROXY_RATE_LIMIT_RPM; 0 disables it.+ app.use('/v1', createProxyRateLimiter());app.use('/v1', proxyRouter);// OpenAI Responses API shim (Codex CLI requires wire_api="responses"; see #96)app.use('/v1', responsesRouter);diff --git a/server/src/middleware/rateLimit.ts b/server/src/middleware/rateLimit.tsnew file mode 100644index 00000000..7090bf3a--- /dev/null+++ b/server/src/middleware/rateLimit.ts@@ -0,0 +1,78 @@+import type { Request, Response, NextFunction } from 'express';++// Per-IP fixed-window rate limiter for the public /v1 proxy (#35, item #6).+//+// The /v1 surface authenticates with the unified API key but has no password+// login like the dashboard does, so without this an attacker who can reach the+// server could brute-force the key or flood upstream providers. This caps how+// many requests a single client IP can make per minute and returns a standard+// OpenAI-shaped 429 once the cap is exceeded.+//+// FreeLLMAPI is a single-user tool, so the default ceiling is generous. Tune it+// with PROXY_RATE_LIMIT_RPM (requests per minute per IP); set it to 0 to turn+// rate limiting off entirely.++const WINDOW_MS = 60_000;+const DEFAULT_RPM = 120;+// Bound the IP map so a flood of distinct (e.g. spoofed) source addresses can't+// grow it without limit; expired entries are pruned opportunistically.+const MAX_TRACKED_IPS = 10_000;++interface WindowState {+ count: number;+ resetAt: number;+}++function parseLimit(): number {+ const raw = process.env.PROXY_RATE_LIMIT_RPM;+ if (raw === undefined || raw.trim() === '') return DEFAULT_RPM;+ const n = Number(raw);+ if (!Number.isFinite(n) || n < 0) return DEFAULT_RPM;+ return Math.floor(n);+}++export function createProxyRateLimiter() {+ const limit = parseLimit();+ const windows = new Map<string, WindowState>();++ return function proxyRateLimit(req: Request, res: Response, next: NextFunction): void {+ if (limit === 0) {+ next();+ return;+ }++ const now = Date.now();+ const ip = req.ip ?? req.socket.remoteAddress ?? 'unknown';++ let state = windows.get(ip);+ if (!state || now >= state.resetAt) {+ state = { count: 0, resetAt: now + WINDOW_MS };+ windows.set(ip, state);+ }+ state.count += 1;++ if (windows.size > MAX_TRACKED_IPS) {+ for (const [key, value] of windows) {+ if (now >= value.resetAt) windows.delete(key);+ }+ }++ res.setHeader('X-RateLimit-Limit', String(limit));+ res.setHeader('X-RateLimit-Remaining', String(Math.max(0, limit - state.count)));+ res.setHeader('X-RateLimit-Reset', String(Math.ceil(state.resetAt / 1000)));++ if (state.count > limit) {+ const retryAfter = Math.max(1, Math.ceil((state.resetAt - now) / 1000));+ res.setHeader('Retry-After', String(retryAfter));+ res.status(429).json({+ error: {+ message: `Rate limit exceeded: more than ${limit} requests per minute. Retry in ${retryAfter}s.`,+ type: 'rate_limit_error',+ },+ });+ return;+ }++ next();+ };+}diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 370a9ef7..f8e93488 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -33,6 +33,22 @@ export function timingSafeStringEqual(provided: string, expected: string): boolereturn crypto.timingSafeEqual(compareA, b) && a.length === b.length;}+// Extract the unified API key from an incoming request. Accepts both the+// OpenAI-style `Authorization: Bearer <key>` header and the Anthropic-style+// `x-api-key` header. Clients that speak the Anthropic wire format — notably+// Claude Code routed through CC Switch (#103) — send the key in `x-api-key`+// rather than a bearer token, and were getting a spurious "Invalid API key"+// 401 before this fallback existed.+export function extractApiToken(req: Request): string | undefined {+ const bearer = req.headers.authorization?.replace(/^Bearer\s+/i, '').trim();+ if (bearer) return bearer;++ const apiKeyHeader = req.headers['x-api-key'];+ const xApiKey = Array.isArray(apiKeyHeader) ? apiKeyHeader[0] : apiKeyHeader;+ const trimmed = xApiKey?.trim();+ return trimmed || undefined;+}+// Sticky sessions: track which model served each "session"// Key: hash of first user message → model_db_id// This prevents model switching mid-conversation which causes hallucination@@ -233,7 +249,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {// Authenticate with the unified API key for every proxy request, including// loopback callers. Browser pages can reach localhost, so socket locality is// not a reliable authorization boundary.- const token = req.headers.authorization?.replace(/^Bearer\s+/i, '');+ const token = extractApiToken(req);const unifiedKey = getUnifiedApiKey();if (!token || !timingSafeStringEqual(token, unifiedKey)) {res.status(401).json({diff --git a/server/src/routes/responses.ts b/server/src/routes/responses.tsindex bbbed628..8c81ca56 100644--- a/server/src/routes/responses.ts+++ b/server/src/routes/responses.ts@@ -15,6 +15,7 @@ import { contentToString } from '../lib/content.js';import {isRetryableError,timingSafeStringEqual,+ extractApiToken,getStickyModel,setStickyModel,logRequest,@@ -229,8 +230,8 @@ export function buildResponseObject(opts: {responsesRouter.post('/responses', async (req: Request, res: Response) => {const start = Date.now();- // Same unified-key bearer auth as the proxy.- const token = req.headers.authorization?.replace(/^Bearer\s+/i, '');+ // Same unified-key auth as the proxy (accepts Bearer or x-api-key).+ const token = extractApiToken(req);const unifiedKey = getUnifiedApiKey();if (!token || !timingSafeStringEqual(token, unifiedKey)) {res.status(401).json({ error: { message: 'Invalid API key', type: 'authentication_error' } });