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: quality pack — crypto guard, session hash, idempotency test, integration tightening, comments (#26)
Tashfeen1e149e03bb53
diff --git a/server/src/__tests__/db/idempotency.test.ts b/server/src/__tests__/db/idempotency.test.tsnew file mode 100644index 00000000..697c880e--- /dev/null+++ b/server/src/__tests__/db/idempotency.test.ts@@ -0,0 +1,89 @@+import { describe, it, expect } from 'vitest';+import Database from 'better-sqlite3';+import { initDb } from '../../db/index.js';++/**+ * Migrations V1–V9 must be idempotent: running initDb twice on the same+ * physical database file should produce identical state. New migrations+ * (V10+) should be added to this test as they ship.+ */+describe('Migration idempotency', () => {+ it('initDb on a fresh in-memory DB then re-run produces identical row counts', () => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ // Use a single shared file so both inits hit the same DB.+ const tmpPath = `/tmp/freeapi-idempotency-${Date.now()}.db`;++ const db1 = initDb(tmpPath);+ const before = {+ models: (db1.prepare('SELECT COUNT(*) AS c FROM models').get() as { c: number }).c,+ fallback: (db1.prepare('SELECT COUNT(*) AS c FROM fallback_config').get() as { c: number }).c,+ enabledModels: (db1.prepare('SELECT COUNT(*) AS c FROM models WHERE enabled = 1').get() as { c: number }).c,+ disabledModels: (db1.prepare('SELECT COUNT(*) AS c FROM models WHERE enabled = 0').get() as { c: number }).c,+ orphanFallbacks: (db1.prepare(`+ SELECT COUNT(*) AS c FROM fallback_config f+ LEFT JOIN models m ON f.model_db_id = m.id+ WHERE m.id IS NULL+ `).get() as { c: number }).c,+ };+ db1.close();++ // Re-init the same DB file — V1..V9 should all no-op idempotently.+ const db2 = initDb(tmpPath);+ const after = {+ models: (db2.prepare('SELECT COUNT(*) AS c FROM models').get() as { c: number }).c,+ fallback: (db2.prepare('SELECT COUNT(*) AS c FROM fallback_config').get() as { c: number }).c,+ enabledModels: (db2.prepare('SELECT COUNT(*) AS c FROM models WHERE enabled = 1').get() as { c: number }).c,+ disabledModels: (db2.prepare('SELECT COUNT(*) AS c FROM models WHERE enabled = 0').get() as { c: number }).c,+ orphanFallbacks: (db2.prepare(`+ SELECT COUNT(*) AS c FROM fallback_config f+ LEFT JOIN models m ON f.model_db_id = m.id+ WHERE m.id IS NULL+ `).get() as { c: number }).c,+ };+ db2.close();++ expect(after).toEqual(before);+ expect(after.orphanFallbacks).toBe(0);+ });++ it('every catalog row has exactly one fallback_config entry', () => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ const db = initDb(':memory:');++ const rows = db.prepare(`+ SELECT m.id, COUNT(f.id) AS fb_count+ FROM models m+ LEFT JOIN fallback_config f ON m.id = f.model_db_id+ GROUP BY m.id+ HAVING COUNT(f.id) <> 1+ `).all() as { id: number; fb_count: number }[];++ expect(rows).toEqual([]);+ });++ it('UNIQUE(platform, model_id) constraint holds — no duplicate catalog rows', () => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ const db = initDb(':memory:');++ const dups = db.prepare(`+ SELECT platform, model_id, COUNT(*) AS c FROM models+ GROUP BY platform, model_id+ HAVING COUNT(*) > 1+ `).all();++ expect(dups).toEqual([]);+ });++ it('all enabled catalog platforms have a registered provider', async () => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ const db = initDb(':memory:');+ const { hasProvider } = await import('../../providers/index.js');++ const platforms = (db.prepare(+ `SELECT DISTINCT platform FROM models WHERE enabled = 1`+ ).all() as { platform: any }[]).map(r => r.platform);++ const missing = platforms.filter(p => !hasProvider(p));+ expect(missing).toEqual([]);+ });+});diff --git a/server/src/__tests__/integration/full-flow.test.ts b/server/src/__tests__/integration/full-flow.test.tsindex 670d294f..bbf5465f 100644--- a/server/src/__tests__/integration/full-flow.test.ts+++ b/server/src/__tests__/integration/full-flow.test.ts@@ -39,10 +39,12 @@ describe('Full Integration Flow', () => {it('Step 1: Verify models are seeded', async () => {const { status, body } = await req(app, 'GET', '/api/models');expect(status).toBe(200);- expect(body.length).toBeGreaterThanOrEqual(14);+ // Tightened from >= 14 — current catalog post-V9 is 60+ rows; if a future+ // migration accidentally drops a chunk we want to know.+ expect(body.length).toBeGreaterThanOrEqual(50);expect(body[0]).toHaveProperty('modelId');expect(body[0]).toHaveProperty('hasProvider');- // All should have providers+ // All should have providers (catches drift between catalog and providers/index.ts)for (const m of body) {expect(m.hasProvider).toBe(true);}@@ -51,7 +53,7 @@ describe('Full Integration Flow', () => {it('Step 2: Verify fallback chain is populated', async () => {const { status, body } = await req(app, 'GET', '/api/fallback');expect(status).toBe(200);- expect(body.length).toBeGreaterThanOrEqual(14);+ expect(body.length).toBeGreaterThanOrEqual(50);expect(body[0]).toHaveProperty('priority');expect(body[0]).toHaveProperty('enabled');});diff --git a/server/src/__tests__/lib/crypto-init.test.ts b/server/src/__tests__/lib/crypto-init.test.tsnew file mode 100644index 00000000..4e26dacf--- /dev/null+++ b/server/src/__tests__/lib/crypto-init.test.ts@@ -0,0 +1,64 @@+import { describe, it, expect, beforeEach } from 'vitest';+import Database from 'better-sqlite3';+import { initEncryptionKey, encrypt, decrypt } from '../../lib/crypto.js';++function freshDb(): Database.Database {+ const db = new Database(':memory:');+ db.exec(`CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);+ return db;+}++describe('initEncryptionKey — input validation', () => {+ beforeEach(() => {+ delete process.env.ENCRYPTION_KEY;+ });++ it('accepts a valid 64-char hex env key', () => {+ process.env.ENCRYPTION_KEY = 'a'.repeat(64);+ const db = freshDb();+ expect(() => initEncryptionKey(db)).not.toThrow();+ // Round-trip a value to confirm the key actually works.+ const enc = encrypt('hello');+ expect(decrypt(enc.encrypted, enc.iv, enc.authTag)).toBe('hello');+ });++ it('throws on too-short env key (typo guard)', () => {+ process.env.ENCRYPTION_KEY = 'abc';+ const db = freshDb();+ expect(() => initEncryptionKey(db)).toThrow(/Invalid ENCRYPTION_KEY \(env\).+expected 64 hex chars/);+ });++ it('throws on too-long env key', () => {+ process.env.ENCRYPTION_KEY = 'a'.repeat(80);+ const db = freshDb();+ expect(() => initEncryptionKey(db)).toThrow(/Invalid ENCRYPTION_KEY \(env\)/);+ });++ it('throws on non-hex env key of correct length', () => {+ process.env.ENCRYPTION_KEY = 'g'.repeat(64); // g is not hex+ const db = freshDb();+ expect(() => initEncryptionKey(db)).toThrow(/Invalid ENCRYPTION_KEY \(env\)/);+ });++ it('still treats the placeholder as "not set" and falls through to DB / generation', () => {+ process.env.ENCRYPTION_KEY = 'your-64-char-hex-key-here';+ const db = freshDb();+ expect(() => initEncryptionKey(db)).not.toThrow();+ // Fell through to generation — DB now has a key.+ const row = db.prepare("SELECT value FROM settings WHERE key = 'encryption_key'").get() as { value: string };+ expect(row.value).toMatch(/^[0-9a-f]{64}$/);+ });++ it('throws on a corrupted DB-stored key', () => {+ const db = freshDb();+ db.prepare("INSERT INTO settings (key, value) VALUES ('encryption_key', ?)").run('not-hex');+ expect(() => initEncryptionKey(db)).toThrow(/Invalid ENCRYPTION_KEY \(db\)/);+ });++ it('generates a fresh key on a virgin DB and persists it', () => {+ const db = freshDb();+ initEncryptionKey(db);+ const row = db.prepare("SELECT value FROM settings WHERE key = 'encryption_key'").get() as { value: string };+ expect(row.value).toMatch(/^[0-9a-f]{64}$/);+ });+});diff --git a/server/src/app.ts b/server/src/app.tsindex 63b95fc8..4b1a0d50 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -17,6 +17,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));export function createApp() {const app = express();+ // CSP intentionally disabled — the SPA bundles inline styles and the OG+ // image is loaded from the same origin; enabling helmet's default CSP+ // breaks the React build's hashed-asset loader. HSTS off because this is+ // a single-user local proxy, served over HTTP on localhost. Both should+ // stay disabled unless someone serves the proxy over HTTPS publicly+ // (which is also not a supported deployment — see README).app.use(helmet({ contentSecurityPolicy: false, hsts: false }));app.use(cors());app.use(express.json({ limit: '1mb' }));diff --git a/server/src/lib/crypto.ts b/server/src/lib/crypto.tsindex 99aa5a47..6a7fc4e3 100644--- a/server/src/lib/crypto.ts+++ b/server/src/lib/crypto.ts@@ -5,6 +5,26 @@ const ALGORITHM = 'aes-256-gcm';let cachedKey: Buffer | null = null;+/**+ * AES-256-GCM uses a 32-byte key, hex-encoded as 64 chars.+ * A typo'd ENCRYPTION_KEY (e.g. "abc") would historically fall through+ * the placeholder check, get truncated to 1.5 bytes, and only fail at+ * the first encrypt() call with a cryptic node:crypto error. Validate+ * the length up front and fail fast with an actionable message.+ */+const KEY_BYTES = 32;+const KEY_HEX_LEN = KEY_BYTES * 2;++function parseHexKey(value: string, source: 'env' | 'db'): Buffer {+ if (value.length !== KEY_HEX_LEN || !/^[0-9a-fA-F]+$/.test(value)) {+ throw new Error(+ `Invalid ENCRYPTION_KEY (${source}): expected ${KEY_HEX_LEN} hex chars (32 bytes), got ${value.length} chars. ` ++ `Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`,+ );+ }+ return Buffer.from(value, 'hex');+}+/*** Initialize encryption key from env, DB, or generate a new one.* Must be called after DB is initialized.@@ -13,19 +33,19 @@ export function initEncryptionKey(db: Database.Database): void {// 1. Check env varconst envKey = process.env.ENCRYPTION_KEY;if (envKey && envKey !== 'your-64-char-hex-key-here') {- cachedKey = Buffer.from(envKey, 'hex');+ cachedKey = parseHexKey(envKey, 'env');return;}// 2. Check DB for persisted keyconst row = db.prepare("SELECT value FROM settings WHERE key = 'encryption_key'").get() as { value: string } | undefined;if (row) {- cachedKey = Buffer.from(row.value, 'hex');+ cachedKey = parseHexKey(row.value, 'db');return;}// 3. Generate and persist- cachedKey = crypto.randomBytes(32);+ cachedKey = crypto.randomBytes(KEY_BYTES);db.prepare("INSERT INTO settings (key, value) VALUES ('encryption_key', ?)").run(cachedKey.toString('hex'));}diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 1845fb76..b63b1d77 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -1,3 +1,4 @@+import crypto from 'crypto';import { Router } from 'express';import type { Request, Response } from 'express';import { z } from 'zod';@@ -15,12 +16,14 @@ const stickySessionMap = new Map<string, { modelDbId: number; lastUsed: number }const STICKY_TTL_MS = 30 * 60 * 1000; // 30 min session TTLfunction getSessionKey(messages: ChatMessage[]): string {- // Use the first user message as session identifier- // Hermes sends the full conversation each time, so first user msg is stable+ // Use the first user message as session identifier — clients like Hermes+ // re-send the full conversation each turn, so the first user message is+ // stable across turns. Hash the FULL message (not a 100-char slice) so+ // distinct conversations with identical openings don't collide.const firstUser = messages.find(m => m.role === 'user');if (!firstUser || typeof firstUser.content !== 'string') return '';- // Hash: first 100 chars of first user message + message count- return `${firstUser.content.slice(0, 100)}:${messages.length > 2 ? 'multi' : 'single'}`;+ const hash = crypto.createHash('sha1').update(firstUser.content).digest('hex');+ return `${hash}:${messages.length > 2 ? 'multi' : 'single'}`;}function getStickyModel(messages: ChatMessage[]): number | undefined {@@ -219,6 +222,12 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {};});+ // Token estimation is intentionally a heuristic (~4 chars per token). Used+ // for routing decisions (skip a model whose budget is too small) and for+ // streaming bookkeeping where the provider doesn't echo a final usage count.+ // Non-streaming requests reconcile against the provider's real `usage` block+ // (see line ~340). Streaming will drift from real consumption — accepted+ // tradeoff because per-request usage isn't always returned mid-stream.const estimatedInputTokens = messages.reduce((sum, m) => {if (typeof m.content !== 'string') return sum;return sum + Math.ceil(m.content.length / 4);