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: 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 var
const 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 key
const 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.ts
index 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 TTL
function 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);