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
import { Router } from 'express';
import type { NextFunction, Request, Response } from 'express';
import { z } from 'zod';
import multer from 'multer';
import path from 'path';
import { getDb } from '../db/index.js';
import { resolveProvider, getAllProviders } from '../providers/index.js';
import { OpenAICompatProvider, isAnonymousCredential } from '../providers/openai-compat.js';
import { getSyncState } from '../services/catalog-sync.js';
import { encrypt, decrypt, maskKey } from '../lib/crypto.js';
import { parseKeysFromFile, stripJsoncComments, stripTrailingCommas } from '../lib/key-parser.js';
import { assessProviderUrl } from '../lib/url-guard.js';
import { verifyCredentials } from '../services/auth.js';
import { getActiveCooldownsForKeys, clearCooldownsForKey } from '../services/ratelimit.js';
import { getMonthlyBudgetCaps, getMonthlyUsage, nextMonthResetAt } from '../services/key-budget.js';
import { resolveCustomEndpointKey, customEndpointKeyIds, siblingEndpointKeyId, endpointHasCredential, normalizeGroupLabel, setCustomEndpointGroup } from '../services/custom-endpoint.js';
import { registerCustomModels, registerCustomChatModels } from '../services/custom-model-register.js';
import { registerCustomMediaModel } from '../services/custom-media-register.js';
import { isSearchPlatform } from '../lib/search-platforms.js';
import { discoverEndpointModels, probeEndpointModel, classifyModelId, ModelDiscoveryError, type DiscoveredModelKind } from '../services/model-discovery.js';
import { probeEmbeddingDimensions, registerCustomEmbeddingModel } from '../services/embeddings.js';
import { endpointScopeForBaseUrl, normalizeBaseUrl } from '../lib/endpoint-scope.js';
import { recordCustomModelTombstone } from '../services/custom-model-tombstone.js';
import {
builtinDiscoveryEligibility,
builtinDiscoveryMode,
discoverBuiltinModels,
ineligibleMessage,
isBuiltinDiscoveryEligible,
registerDiscoveredModels,
registeredModelIds,
triggerBuiltinModelDiscovery,
} from '../services/builtin-model-discovery.js';
import type { Db } from '../db/types.js';
import type { Platform } from '@freellmapi/shared/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();
// Providers that stopped offering free API access but keep their adapter so
// existing keys still work if the catalog re-enables them. The setup
// checklist stops suggesting them to anyone who has no key yet; the dashboard
// pickers hide them through `hidden` in client/src/components/keys/shared.tsx.
// Empty since Auray was removed outright (#1583).
const UNLISTED_PLATFORMS = new Set<string>();
// Active providers — must match providers/index.ts registrations + shared/types.ts Platform.
// Moonshot and MiniMax direct integrations were dropped in V4. HuggingFace
// was dropped in V4 and re-added in V13 via the router.huggingface.co route.
// SambaNova was dropped in V23 (free tier permanently retired). GitHub Models
// was dropped after its retirement on 30 July 2026 (#1557). Auray was removed
// at the provider's request after it started charging for API access (#1583).
const PLATFORMS = [
'aclide',
'speka',
'kenari',
'typhoon',
'plugsky',
'inferbase',
'simplellm',
'llmtr',
'gizmo',
'blockrun',
'moondream',
'beatapi',
'apinex',
'onomeo',
'iteracompute',
'serpsearch',
'brave',
'freeai',
'google', 'groq', 'cerebras', 'sail', 'electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare', 'bai', 'radeon', 'nvidia', 'mistral',
'openrouter', 'cohere', 'tavily', 'exa', 'firecrawl', 'linkup', 'parallel', 'keenable', 'cloudflare', 'zhipu', 'ollama',
'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'ovh', 'agnes', 'reka', 'siliconflow',
'routeway', 'bazaarlink', 'ainative', 'aion', 'anyapi', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'modelscope',
'qianfan', 'volcengine', 'longcat', 'xfyun', 'aihorde', 'custom',
] as const;
const ALLOWED_IMPORT_EXTENSIONS = new Set(['.env', '.json', '.jsonc', '.md', '.txt', '.csv']);
const upload = multer({
storage: multer.memoryStorage(),
limits: { fileSize: 5 * 1024 * 1024, files: 10 },
fileFilter: (_req, file, cb) => {
const ext = path.extname(file.originalname).toLowerCase();
if (!ALLOWED_IMPORT_EXTENSIONS.has(ext)) {
cb(new Error('Unsupported file type'));
return;
}
cb(null, true);
},
});
// `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 });
// A label is free text, and two formats read it back as STRUCTURE: the .env
// export writes it as a `# label` comment line (a label carrying a newline
// injects a real `GOOGLE_KEY=...` line that the importer then loads as a
// key), and the CSV export writes it as one cell (the formula guard quotes the
// cell but cannot stop a newline from splitting the record). So a label is one
// line of text, full stop: line breaks and other control characters collapse
// to a space, and it is trimmed and bounded like every other operator label
// (groupLabel is trim().max(80)).
const LABEL_MAX = 200;
function sanitizeLabel(label: string): string {
// eslint-disable-next-line no-control-regex -- collapsing control chars is the point.
return label.replace(/[\r\n\t\u0000-\u001f\u007f]+/g, ' ').trim().slice(0, LABEL_MAX);
}
// Defensive read for exports: rows stored by older builds can still hold a
// newline, and an export must never write one into a label position.
const labelForExport = (label: string | null | undefined): string =>
label == null ? '' : sanitizeLabel(label);
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
// scope each key to a model group. null (or an empty array) clears the scope,
// returning the key to serving every model of its platform.
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(),
// #590: '' clears the per-key proxy; absent leaves it unchanged.
proxyUrl: proxyUrlSchema.optional(),
// Monthly budget caps (#1158): 0 clears the cap (unlimited).
monthlyRequestCap: z.number().int().min(0).max(1_000_000_000).optional(),
monthlyTokenCap: z.number().int().min(0).max(1_000_000_000_000).optional(),
// Custom-endpoint group label (#1176): '' clears it back to the single
// "Custom" group; absent leaves it unchanged. Applies to the whole endpoint.
groupLabel: z.string().trim().max(80).optional(),
// An absent credential leaves the encrypted key untouched.
key: z.string().trim().min(1).optional(),
}).refine(data => data.enabled !== undefined || data.label !== undefined || data.modelScope !== undefined || data.proxyUrl !== undefined || data.key !== undefined || data.monthlyRequestCap !== undefined || data.monthlyTokenCap !== undefined || data.groupLabel !== undefined, {
message: 'At least one of enabled, label, modelScope, proxyUrl, key, monthlyRequestCap, monthlyTokenCap or groupLabel must be provided',
});
const importKeySchema = z.object({
keyName: z.string().optional(),
keyValue: z.string().min(1),
platform: z.enum(PLATFORMS),
// A custom row names an ENDPOINT, so it only means something with the URL
// the export file carried alongside it (#687).
baseUrl: z.string().optional(),
// Models declared beside a custom endpoint in the paste (#382). Ignored for
// catalog platforms — their model lists come from the catalog, not the file.
models: z.array(z.object({
id: z.string().min(1),
supportsTools: z.boolean().optional(),
supportsVision: z.boolean().optional(),
})).max(200).optional(),
});
function handleUploadError(err: any, res: Response, next: NextFunction): boolean {
if (!err) return false;
if (err.code === 'LIMIT_FILE_SIZE') {
res.status(413).json({ error: { message: 'File too large. Maximum size is 5MB' } });
return true;
}
if (err.code === 'LIMIT_FILE_COUNT') {
res.status(413).json({ error: { message: 'Too many files. Maximum is 10' } });
return true;
}
if (err.message?.includes('Unsupported file type')) {
res.status(400).json({ error: { message: 'Unsupported file type' } });
return true;
}
next(err);
return true;
}
function parseUpload(file: Express.Multer.File) {
const content = file.buffer.toString('utf8');
if (!content.trim()) {
throw Object.assign(new Error('File contains no data'), { status: 400 });
}
if (/\.jsonc?$/i.test(file.originalname)) {
try {
JSON.parse(stripTrailingCommas(stripJsoncComments(content)));
} catch {
throw Object.assign(new Error('Invalid JSON format'), { status: 400 });
}
}
return parseKeysFromFile(content, file.originalname);
}
/** Name/value halves of a parsed key. A format that carries a label (CSV,
* export JSON) names it outright: splitting `label=value` on the first '='
* would cut a label like `team=alpha` short and prepend its tail to the
* stored secret. */
function splitParsedKey(parsedKey: { rawKey: string; label?: string }) {
const { rawKey, label } = parsedKey;
if (label !== undefined && rawKey.startsWith(`${label}=`)) {
return { keyName: label, keyValue: rawKey.slice(label.length + 1) };
}
return splitRawKey(rawKey);
}
function splitRawKey(rawKey: string) {
const eqIndex = rawKey.indexOf('=');
return {
keyName: eqIndex === -1 ? rawKey : rawKey.slice(0, eqIndex),
keyValue: eqIndex === -1 ? '' : rawKey.slice(eqIndex + 1),
};
}
function insertImportedKey(platform: (typeof PLATFORMS)[number], keyName: string, keyValue: string) {
if (platform === 'custom') {
throw new Error('Custom providers must be added with a base URL');
}
if (!resolveProvider(platform)) {
throw new Error(`Unsupported platform: ${platform}`);
}
const db = getDb();
const { encrypted, iv, authTag } = encrypt(keyValue.trim());
db.prepare(`
INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
VALUES (?, ?, ?, ?, ?, 'unknown', 1)
`).run(platform, keyName, encrypted, iv, authTag);
}
// Count enabled catalog models for a platform. Used to warn when a key is
// added for a provider that has zero models in the operator's current catalog
// tier — the Agnes case (#438): the provider is registered and selectable, but
// its models ship in the premium/live catalog and only appear for free-tier
// installs once they age into the monthly catalog, so a fresh install adds the
// key and silently sees nothing.
/**
* Whether a stored row belongs in an export file. Kept in one place because the
* export dialog shows a count before downloading, and computing that count from
* a different rule than the export itself made it lie: it promised 40 keys and
* wrote 39 whenever a no-auth custom endpoint was in the list (#687).
*
* A custom endpoint is worth exporting even when it holds only the `no-key`
* placeholder — the endpoint IS the thing being backed up, and its base_url
* restores it. Anything else needs a real secret to be worth a line.
*/
export function isExportableKey(row: { platform: string; baseUrl: string | null; key: string }): boolean {
if (row.platform === 'custom') return Boolean(row.baseUrl);
const v = row.key.trim();
return v.length > 0 && v !== 'no-key';
}
// Every model a platform's key can serve: chat rows, plus embedding and
// generative-media rows. Media-only providers (Speechify is TTS-only) never
// have a chat row, so counting `models` alone reported "no models" — and fired
// the no-catalog notice — for them even on a fully synced Premium install
// (#1327).
function enabledModelCount(platform: string): number {
const db = getDb();
const row = db.prepare(`
SELECT (SELECT COUNT(*) FROM models WHERE platform = ? AND enabled = 1)
+ (SELECT COUNT(*) FROM embedding_models WHERE platform = ? AND enabled = 1)
+ (SELECT COUNT(*) FROM media_models WHERE platform = ? AND enabled = 1) AS c
`).get(platform, platform, platform) as { c: number };
return row.c;
}
// The public API root the custom-provider workaround needs, or null when the
// platform does not speak the OpenAI-compatible protocol that path speaks
// (e.g. Speechify's own TTS API), in which case that advice is a dead end.
function openAICompatBaseUrl(platform: string): string | null {
const provider = resolveProvider(platform as Platform);
if (!(provider instanceof OpenAICompatProvider)) return null;
return provider.modelsUrl.replace(/\/models\/?$/, '');
}
// Non-null when the just-added key has no usable models yet, so the client can
// explain the silence instead of leaving the user staring at an empty list.
//
// #1327: the old copy told a Premium user to "add a Premium license key", and
// told everyone to add the provider as a custom OpenAI-compatible endpoint
// "with its base URL" without naming it — even for providers with no such
// endpoint. The notice now matches the install's actual catalog tier, names
// the base URL, and only offers the custom-provider route where it works.
function noModelsNotice(platform: string): string | undefined {
if (enabledModelCount(platform) > 0) return undefined;
// Search keys have engines, not models (#1174): a key whose engine is off
// or not in this catalog gets told where engines live instead of the chat
// advice below.
if (isSearchPlatform(platform)) {
return `Key saved, but no ${platform} search engine is turned on. Turn it on from Models → Search.`;
}
// #1348: a built-in provider the catalog does not carry fills its model list
// from its own /models, so the Premium and custom-provider advice below
// would send the operator the wrong way.
if (isBuiltinDiscoveryEligible(getDb(), platform)) {
return builtinDiscoveryMode() === 'auto'
? `Key saved. The catalog does not list ${platform} models, so they are being fetched from ${platform}'s own model list. ` +
`Use Fetch models on the key to review them or add more.`
: `Key saved. The catalog does not list ${platform} models. Use Fetch models on the key to pick which ones to use.`;
}
const baseUrl = openAICompatBaseUrl(platform);
const customRoute = baseUrl
? `add ${platform} as a custom OpenAI-compatible provider with base URL ${baseUrl}`
: null;
const premium = getSyncState().appliedTier === 'live';
if (premium) {
return (
`Key saved, but your Premium catalog does not list any ${platform} models yet. ` +
`Try Check for updates on the Premium page to pull the latest catalog` +
(customRoute ? `, or ${customRoute}.` : '.')
);
}
return (
`Key saved, but no ${platform} models are in your current catalog yet. ` +
`Newer providers are published to the premium catalog first and appear ` +
`for free-tier installs once they age into the monthly catalog. ` +
`Add a Premium license key to use them now` +
(customRoute ? `, or ${customRoute}.` : '.')
);
}
// Provider checklist (#543): every registered provider with whether the user
// has added at least one key yet, so the dashboard can show what's still
// missing without enumerating the whole list by hand. `custom` is excluded —
// it's a per-key user-defined placeholder, not a fixed free-tier provider to
// "check off".
keysRouter.get('/providers', (_req: Request, res: Response) => {
const db = getDb();
const countRows = db.prepare(`
SELECT
platform,
COUNT(*) AS total_keys,
SUM(CASE WHEN enabled = 1 THEN 1 ELSE 0 END) AS enabled_keys
FROM api_keys
GROUP BY platform
`).all() as Array<{ platform: string; total_keys: number; enabled_keys: number }>;
const countsByPlatform = new Map(countRows.map(r => [r.platform, r]));
const providers = getAllProviders()
.filter(p => p.platform !== 'custom')
.map(p => {
const counts = countsByPlatform.get(p.platform);
const keyCount = counts?.total_keys ?? 0;
return {
platform: p.platform,
name: p.name,
// 'search' keys serve /v1/search and the agents' web_search tools,
// never chat (#1174); the dashboard groups them separately.
kind: isSearchPlatform(p.platform) ? 'search' as const : 'chat' as const,
keyless: p.keyless,
configured: keyCount > 0,
keyCount,
enabledKeyCount: counts?.enabled_keys ?? 0,
};
})
.filter(p => p.configured || !UNLISTED_PLATFORMS.has(p.platform))
.sort((a, b) => a.name.localeCompare(b.name));
const configured = providers.filter(p => p.configured).length;
res.json({
providers,
summary: {
total: providers.length,
configured,
unconfigured: providers.length - configured,
},
});
});
// List all keys (masked)
keysRouter.get('/', (_req: Request, res: Response) => {
const db = getDb();
const rows = db.prepare('SELECT * FROM api_keys ORDER BY created_at DESC').all() as any[];
const modelCounts = new Map<string, number>();
const modelCountFor = (platform: string): number => {
if (!modelCounts.has(platform)) modelCounts.set(platform, enabledModelCount(platform));
return modelCounts.get(platform)!;
};
const customModels = [
...db.prepare(`
SELECT key_id, id, 'chat' AS kind, model_id, display_name, NULL AS family
FROM models
WHERE platform = 'custom' AND key_id IS NOT NULL
`).all() as any[],
...db.prepare(`
SELECT key_id, id, 'embedding' AS kind, model_id, display_name, family
FROM embedding_models
WHERE platform = 'custom' AND key_id IS NOT NULL
`).all() as any[],
...db.prepare(`
SELECT key_id, id, modality AS kind, model_id, display_name, NULL AS family
FROM media_models
WHERE platform = 'custom' AND key_id IS NOT NULL
`).all() as any[],
];
// Models are grouped by ENDPOINT, not by key row: an endpoint can hold
// several credentials (#619) while each model binds to just one of them, and
// every one of those keys serves the endpoint's whole model list.
const endpointOfKey = new Map<number, string>();
for (const row of rows) {
if (row.platform === 'custom' && row.base_url) endpointOfKey.set(Number(row.id), row.base_url);
}
const endpointOf = (keyId: number) => endpointOfKey.get(keyId) ?? `key:${keyId}`;
const modelsByEndpoint = new Map<string, any[]>();
for (const m of customModels) {
const keyId = Number(m.key_id);
if (!Number.isInteger(keyId)) continue;
const list = modelsByEndpoint.get(endpointOf(keyId)) ?? [];
list.push({
id: m.id,
kind: m.kind,
modelId: m.model_id,
displayName: m.display_name,
family: m.family ?? null,
});
modelsByEndpoint.set(endpointOf(keyId), list);
}
for (const list of modelsByEndpoint.values()) {
list.sort((a, b) => {
const ka = ['chat', 'embedding', 'image', 'audio', 'transcription'].indexOf(a.kind);
const kb = ['chat', 'embedding', 'image', 'audio', 'transcription'].indexOf(b.kind);
return (ka - kb) || String(a.displayName).localeCompare(String(b.displayName));
});
}
// A cooling-down key reads as healthy and enabled while the router skips it,
// so surface the cooldowns that explain the idleness. (#P0-7)
const cooldownsByKeyId = getActiveCooldownsForKeys(rows.map(row => Number(row.id)));
// #1348: which built-in platforms may fill their model list from their own
// /models, so the dashboard offers Fetch models on those key rows only.
const discoverable = new Map<string, boolean>();
const canDiscover = (platform: string) => {
if (platform === 'custom') return false;
if (!discoverable.has(platform)) discoverable.set(platform, isBuiltinDiscoveryEligible(db, platform));
return discoverable.get(platform)!;
};
const keys = rows.map(row => {
let maskedKey = '****';
let realKey = '';
try {
realKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
maskedKey = maskKey(realKey);
} catch {
maskedKey = '[decrypt failed]';
}
const cooldowns = cooldownsByKeyId.get(Number(row.id)) ?? [];
const scope = parseModelScope(row.model_scope_json);
const budgetCaps = getMonthlyBudgetCaps(Number(row.id));
// Usage alongside the caps so the dashboard can show "342 of 1,000 this
// month" instead of only the cap (OpenRouter's GET /api/v1/key returns
// limit_remaining for the same reason).
const monthlyUsage = getMonthlyUsage(Number(row.id));
return {
id: row.id,
platform: row.platform,
label: row.label,
maskedKey,
baseUrl: row.base_url ?? null,
// Optional custom-endpoint group label (#1176); null = legacy single
// "Custom" group.
groupLabel: row.group_label ?? null,
monthlyRequestCap: budgetCaps.requestCap,
monthlyTokenCap: budgetCaps.tokenCap,
monthlyUsage: {
requests: monthlyUsage.requests,
tokens: monthlyUsage.tokens,
resetsAt: nextMonthResetAt(),
},
status: row.status,
enabled: row.enabled === 1,
// `keyOptional`: the platform works with or without a key (Kilo, OVH,
// AI Horde). `keyless`: THIS row is the anonymous sentinel, so there is
// no credential to copy, scope or reveal. A real key saved on a
// key-optional platform is an ordinary key row (#1331).
keyOptional: resolveProvider(row.platform)?.keyless === true,
keyless: resolveProvider(row.platform)?.keyless === true && isAnonymousCredential(realKey),
// #1459: false for a provider that forbids automated key checks (LLMTR).
// Its keys stay 'unknown' until they serve a request, and "Check now"
// sends nothing, so the dashboard explains that instead of showing an
// unexplained "unchecked". modelsAvailable says whether this install has
// any of the provider's models to serve that first request with.
autoHealthCheck: resolveProvider(row.platform)?.supportsKeyValidation !== false,
// Search keys serve engines, not models, so they never count as missing models.
...(resolveProvider(row.platform)?.supportsKeyValidation === false && !isSearchPlatform(row.platform)
? { modelsAvailable: modelCountFor(row.platform) }
: {}),
// Lets the export dialog count exactly what the export will write.
exportable: isExportableKey({ platform: row.platform, baseUrl: row.base_url ?? null, key: realKey }),
createdAt: row.created_at,
lastCheckedAt: row.last_checked_at,
// #1493: last time this key was proven to work (valid probe or served
// request) — distinct from lastCheckedAt, which a transport error also
// refreshes.
lastHealthyAt: row.last_healthy_at ?? null,
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,
modelDiscovery: canDiscover(row.platform),
cooldowns: cooldowns.map(c => ({
modelId: c.modelId,
expiresAtMs: c.expiresAtMs,
remainingMs: c.remainingMs,
})),
};
});
res.json(keys);
});
// Clear every active cooldown for one key. An escalated cooldown can bench a key
// for up to 24h from a single bad window; once the operator has fixed the cause
// there is otherwise no way back short of restarting and waiting it out.
keysRouter.delete('/:id/cooldowns', (req: Request, res: Response) => {
const id = Number(req.params.id);
if (!Number.isInteger(id)) {
res.status(400).json({ error: 'Invalid key id' });
return;
}
const db = getDb();
const exists = db.prepare('SELECT 1 FROM api_keys WHERE id = ?').get(id);
if (!exists) {
res.status(404).json({ error: 'Key not found' });
return;
}
const cleared = clearCooldownsForKey(id);
res.json({ cleared });
});
// Is the caller connecting from this machine? Read from the real socket peer
// address, NOT req.ip or X-Forwarded-For: those are caller-controlled, so
// trusting them here would let a remote caller claim to be local.
function isLoopbackRemote(req: Request): boolean {
let addr = req.socket?.remoteAddress ?? '';
// Node reports IPv4 loopback over a dual-stack socket as "::ffff:127.0.0.1".
if (addr.startsWith('::ffff:')) addr = addr.slice(7);
if (addr === '::1') return true;
return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(addr);
}
// #786: the desktop build has no user-set password (its machine user's password
// is random and never shown), so re-verification would lock desktop users out of
// reading their own keys. The embedder marks the process
// (desktop/src/server-host.ts) and the two plaintext-key endpoints below skip
// re-auth for it — but ONLY for a request from this machine. The desktop app can
// bind 0.0.0.0 through its LAN-access toggle, and a remote viewer on that LAN
// still has to prove the password before it can lift a key.
function skipsReauth(req: Request): boolean {
return process.env.FREEAPI_DESKTOP === '1' && isLoopbackRemote(req);
}
// Export keys — returns plaintext keys in the requested format.
// GET /api/keys/export?format=json|env|csv&healthy=true
// The response is the raw file download (Content-Type varies by format).
// Password re-verification via x-reauth-password header is required, except for
// a local request on the desktop build (see skipsReauth).
keysRouter.get('/export', (req: Request, res: Response) => {
const user = (req as any).user;
if (!skipsReauth(req)) {
const password = req.headers['x-reauth-password'] as string | undefined;
if (!password || !verifyCredentials(user.email, password)) {
res.status(403).json({ error: { message: 'Password verification required to export keys', type: 'authentication_error' } });
return;
}
}
const db = getDb();
const format = (req.query.format as string) ?? 'json';
const healthyOnly = req.query.healthy === 'true';
let whereClause = '';
if (healthyOnly) {
whereClause = "WHERE status = 'healthy'";
}
const rows = db.prepare(`SELECT * FROM api_keys ${whereClause} ORDER BY platform, created_at ASC`).all() as any[];
// Decrypt and filter — only export keys with a real value
const decryptedKeys = rows
.map(row => {
let key = '';
try {
key = decrypt(row.encrypted_key, row.iv, row.auth_tag);
} catch {
key = '';
}
return {
platform: row.platform,
key,
label: row.label || '',
baseUrl: row.base_url || undefined,
};
})
.filter(k => isExportableKey({ platform: k.platform, baseUrl: k.baseUrl ?? null, key: k.key }));
if (decryptedKeys.length === 0) {
res.status(404).json({ error: { message: 'No keys to export' } });
return;
}
if (format === 'env') {
// .env format: GOOGLE_KEY=xxx\nGROQ_KEY=yyy
//
// Names have to stay unique. A .env is read back into a map keyed by name,
// so two rows sharing one name collapse into a single imported key — every
// second Google key was silently lost on a round trip. Repeats therefore
// take a numeric suffix (GOOGLE_KEY_2), which still resolves to the same
// platform through PREFIX_MAP.
//
// Custom endpoints get an indexed PAIR, because a custom key without its
// base_url cannot be restored — there is no endpoint to attach it to (#687).
const seenPerPlatform = new Map<string, number>();
let customIndex = 0;
const lines = decryptedKeys.map(k => {
if (k.platform === 'custom' && k.baseUrl) {
customIndex++;
return [
`# ${labelForExport(k.label) || `custom endpoint ${customIndex}`}`,
`CUSTOM_${customIndex}_BASE_URL=${k.baseUrl}`,
`CUSTOM_${customIndex}_KEY=${k.key}`,
].join('\n');
}
const n = (seenPerPlatform.get(k.platform) ?? 0) + 1;
seenPerPlatform.set(k.platform, n);
const envKey = `${k.platform.toUpperCase()}_KEY${n > 1 ? `_${n}` : ''}=${k.key}`;
const comment = labelForExport(k.label);
return comment ? `# ${comment}\n${envKey}` : envKey;
});
const content = lines.join('\n\n') + '\n';
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
res.setHeader('Content-Disposition', 'attachment; filename="freellmapi-keys.env"');
res.send(content);
return;
}
if (format === 'csv') {
// CSV format: platform,key,label
const escCsv = (v: string) => `"${v.replace(/"/g, '""')}"`;
// CSV formula-injection guard: a spreadsheet treats a cell that starts with
// =, +, -, @, tab or CR as a live formula, so a label like `=HYPERLINK(...)`
// would execute on open. Prefix such cells with a single quote to force them
// to be read as text. Applied to the free-text fields the user controls
// (labels AND base_url — the custom endpoint column is free text too, and
// the importer strips the guard quote back off both); the key value must
// round-trip verbatim for re-import, and the platform is one of our own
// fixed enum values.
const neutralize = (v: string) => (/^[=+\-@\t\r]/.test(v) ? `'${v}` : v);
// base_url is the fourth column: a custom row is an ENDPOINT, and without
// its URL the key cannot be re-imported (#687). Blank for every other
// platform. The importer tolerates the three-column form too, so files
// written by older builds still load.
const header = 'platform,key,label,base_url';
const lines = decryptedKeys.map(k =>
[escCsv(k.platform), escCsv(k.key), escCsv(neutralize(labelForExport(k.label))), escCsv(neutralize(k.baseUrl ?? ''))].join(',')
);
const content = [header, ...lines].join('\n') + '\n';
res.setHeader('Content-Type', 'text/csv; charset=utf-8');
res.setHeader('Content-Disposition', 'attachment; filename="freellmapi-keys.csv"');
res.send(content);
return;
}
// Default: JSON format (round-trip safe — can be imported directly)
const jsonExport = {
version: 1,
exportedAt: new Date().toISOString(),
source: 'freellmapi',
keys: decryptedKeys,
};
res.setHeader('Content-Type', 'application/json; charset=utf-8');
res.setHeader('Content-Disposition', 'attachment; filename="freellmapi-keys.json"');
res.json(jsonExport);
});
// Reveal ONE key in plaintext, so the dashboard can offer a copy action for a
// credential it otherwise only ever shows masked (#705). Exporting every key to
// a file was the only way to read one back, which is a poor trade for "what is
// the key on this row again?". Gated exactly like the export it narrows: the
// session alone is not enough, the password has to be re-entered — except for a
// local request on the desktop build, which has no password to re-enter (see
// skipsReauth; a LAN client of that same desktop server still needs one).
keysRouter.post('/:id/reveal', (req: Request, res: Response) => {
const user = (req as any).user;
if (!skipsReauth(req)) {
const password = req.headers['x-reauth-password'] as string | undefined;
if (!password || !verifyCredentials(user.email, password)) {
res.status(403).json({ error: { message: 'Password verification required to reveal a key', type: 'authentication_error' } });
return;
}
}
const id = parseInt(req.params.id as string, 10);
if (isNaN(id)) {
res.status(400).json({ error: { message: 'Invalid key ID' } });
return;
}
const row = getDb().prepare('SELECT encrypted_key, iv, auth_tag FROM api_keys WHERE id = ?')
.get(id) as { encrypted_key: string; iv: string; auth_tag: string } | undefined;
if (!row) {
res.status(404).json({ error: { message: 'Key not found' } });
return;
}
try {
res.json({ key: decrypt(row.encrypted_key, row.iv, row.auth_tag) });
} catch {
res.status(500).json({ error: { message: 'This key could not be decrypted. It was stored with a different ENCRYPTION_KEY.' } });
}
});
// Add a key
keysRouter.post('/', (req: Request, res: Response) => {
const parsed = addKeySchema.safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
const { platform } = parsed.data;
const label = parsed.data.label === undefined ? undefined : sanitizeLabel(parsed.data.label);
const isKeyless = resolveProvider(platform)?.keyless === true;
const rawKey = parsed.data.key?.trim() ?? '';
if (!isKeyless && !rawKey) {
res.status(400).json({ error: { message: 'key is required' } });
return;
}
// Key-optional providers (Kilo, OVH, AI Horde) store a sentinel when no key
// is given so routing sees the platform as configured; the provider then
// calls upstream anonymously. A real key is stored encrypted like any other
// and sent as the bearer (#1331).
const keyToStore = isKeyless ? (rawKey || 'no-key') : rawKey;
const proxyUrl = parsed.data.proxyUrl?.trim() ?? '';
const db = getDb();
if (isKeyless) {
const rows = db.prepare('SELECT id, encrypted_key, iv, auth_tag FROM api_keys WHERE platform = ? ORDER BY id')
.all(platform) as { id: number; encrypted_key: string; iv: string; auth_tag: string }[];
const plaintext = (r: typeof rows[number]): string | null => {
try { return decrypt(r.encrypted_key, r.iv, r.auth_tag); } catch { return null; }
};
const sentinel = rows.find(r => isAnonymousCredential(plaintext(r)));
const respond = (id: number, maskedKey: string) => res.status(200).json({
id,
platform,
label: label ?? '',
maskedKey,
status: 'unknown',
enabled: true,
modelsAvailable: enabledModelCount(platform),
notice: noModelsNotice(platform),
});
if (!rawKey) {
// Only one sentinel row is needed: re-enable an existing row instead of
// piling up duplicates each time the user clicks "Enable".
const existing = sentinel ?? rows[0];
if (existing) {
db.prepare("UPDATE api_keys SET enabled = 1, status = 'unknown' WHERE id = ?").run(existing.id);
respond(existing.id, maskKey(plaintext(existing) ?? keyToStore));
return;
}
} else if (sentinel) {
// A real key upgrades the anonymous row in place rather than leaving a
// second, anonymous row competing with it in the pool.
const { encrypted, iv, authTag } = encrypt(rawKey);
const updates = ['encrypted_key = ?', 'iv = ?', 'auth_tag = ?', 'enabled = 1', "status = 'unknown'", 'last_checked_at = NULL', 'last_health_error = NULL'];
const values: (string | number | null)[] = [encrypted, iv, authTag];
if (label !== undefined) { updates.push('label = ?'); values.push(label); }
if (parsed.data.proxyUrl !== undefined) {
const proxy = encryptProxyUrl(proxyUrl);
updates.push('proxy_encrypted = ?', 'proxy_iv = ?', 'proxy_auth_tag = ?');
values.push(proxy.encrypted, proxy.iv, proxy.authTag);
}
db.prepare(`UPDATE api_keys SET ${updates.join(', ')} WHERE id = ?`).run(...values, sentinel.id);
clearCooldownsForKey(sentinel.id);
respond(sentinel.id, maskKey(rawKey));
return;
}
}
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 proxy = encryptProxyUrl(proxyUrl);
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 (?, ?, ?, ?, ?, 'unknown', 1, ?, ?, ?)
`).run(platform, label ?? '', encrypted, iv, authTag, proxy.encrypted, proxy.iv, proxy.authTag);
// #1348: fetch the provider's models in the background when the catalog
// carries none for it. No-op for every other platform.
triggerBuiltinModelDiscovery(db, platform, 'key_added');
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,
modelsAvailable: enabledModelCount(platform),
notice: noModelsNotice(platform),
});
});
// ── Custom OpenAI-compatible providers (#117, #212) ───────────────────────
// User-configured endpoints (llama.cpp / LM Studio / vLLM / Ollama / any
// OpenAI-compatible base_url). Each DISTINCT base_url gets its own 'custom'
// api_keys row, and every registered model binds to its endpoint's key via
// models.key_id — so several custom providers coexist without overwriting
// each other (#212). Re-submitting an existing base_url updates its key/label;
// re-registering an existing model id re-binds it to the submitted endpoint.
// A model can be given as a bare id ("qwen3:4b") or as {model, displayName}.
// `model`/`displayName` (singular) stay supported for older clients; `models`
// (plural) lets one submit bind several model ids to the same endpoint. (#281)
// A custom model can declare its capabilities at registration. `supportsTools`
// defaults to 1 (modern OpenAI-compatible servers — Ollama, vLLM, LM Studio —
// all emit tool calls), `supportsVision` defaults to 0 unless declared. Leaving
// a flag unset keeps the DB default on insert and preserves the stored value on
// re-registration, so a capability the user later toggled isn't clobbered. (#470)
const modelEntrySchema = z.union([
z.string().min(1),
z.object({
model: z.string().min(1),
displayName: z.string().optional(),
supportsTools: z.boolean().optional(),
supportsVision: z.boolean().optional(),
// #1506: a kind forwarded from discovery metadata (the endpoint's own
// `type`/metadata) so an id with no media keyword still routes to the
// table that can serve it. Absent, the handler falls back to the
// id-based classifier (#1051).
kind: z.enum(['embedding', 'image', 'audio', 'transcription', 'video']).optional(),
}),
]);
// `baseUrl` and `keyId` are both optional but at least one is required: the
// bulk registration that follows model discovery (#488) already holds the
// api_keys row it fetched the list with, and naming that row keeps the new
// models on the same credential of the endpoint's pool (#619/#640).
const customProviderSchema = z.object({
baseUrl: z.string().url('baseUrl must be a valid URL').optional(),
keyId: z.number().int().positive().optional(),
model: z.string().optional(),
models: z.array(modelEntrySchema).optional(),
displayName: z.string().optional(),
apiKey: z.string().optional(),
label: z.string().optional(),
// Top-level defaults applied to every model in this submit; a per-entry flag
// (object form) overrides them for that one model.
supportsTools: z.boolean().optional(),
supportsVision: z.boolean().optional(),
// Endpoint group (#1176). Absent keeps the endpoint's current group; '' moves
// it back to the single "Custom" group.
groupLabel: z.string().trim().max(80).optional(),
}).refine(
d => d.baseUrl !== undefined || d.keyId !== undefined,
{ message: 'baseUrl or keyId is required' },
);
// Naming no model at all is the credential-only add: a second key for an
// endpoint already registered (#702). It needs the endpoint to exist and a key
// to actually add, so those two checks live in the handler where the DB is in
// reach; a submit that is neither that nor a registration still gets the old
// 'model or models is required'.
interface CustomEndpointRef {
baseUrl: string;
/** The api_keys row this endpoint is already stored under, or null when the
* endpoint has never been registered. */
keyId: number | null;
/** Plaintext of that row's credential, when there is one. */
storedKey: string | null;
}
/**
* Turn a `{ keyId?, baseUrl? }` reference into the endpoint it names. A keyId
* is the stronger reference (it identifies one credential of the pool); a bare
* baseUrl falls back to the endpoint's first stored key, which is how the rest
* of the custom-endpoint machinery addresses an endpoint. Throws a
* `{ status, message }` for a reference that names nothing usable.
*/
function resolveEndpointRef(ref: { keyId?: number; baseUrl?: string }): CustomEndpointRef {
const db = getDb();
const requestedBaseUrl = ref.baseUrl === undefined ? undefined : normalizeBaseUrl(ref.baseUrl);
if (ref.keyId !== undefined) {
const row = db.prepare('SELECT id, platform, base_url, encrypted_key, iv, auth_tag FROM api_keys WHERE id = ?')
.get(ref.keyId) as { id: number; platform: string; base_url: string | null; encrypted_key: string; iv: string; auth_tag: string } | undefined;
if (!row || row.platform !== 'custom' || !row.base_url) {
throw Object.assign(new Error('keyId does not name a custom endpoint'), { status: 400 });
}
if (requestedBaseUrl !== undefined && requestedBaseUrl !== row.base_url) {
throw Object.assign(new Error('baseUrl does not match the endpoint keyId belongs to'), { status: 400 });
}
let storedKey: string | null = null;
try {
storedKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
} catch { /* an undecryptable row still names the endpoint */ }
return { baseUrl: row.base_url, keyId: row.id, storedKey };
}
if (!requestedBaseUrl) {
throw Object.assign(new Error('baseUrl or keyId is required'), { status: 400 });
}
// Any key of this base_url serves the whole endpoint (#619), so the first one
// is as good a representative as any.
const rows = db.prepare(`
SELECT id, encrypted_key, iv, auth_tag FROM api_keys
WHERE platform = 'custom' AND base_url = ? ORDER BY id
`).all(requestedBaseUrl) as Array<{ id: number; encrypted_key: string; iv: string; auth_tag: string }>;
for (const row of rows) {
try {
return { baseUrl: requestedBaseUrl, keyId: row.id, storedKey: decrypt(row.encrypted_key, row.iv, row.auth_tag) };
} catch { /* try the next credential */ }
}
return { baseUrl: requestedBaseUrl, keyId: rows[0]?.id ?? null, storedKey: null };
}
/**
* Models attached to an imported custom endpoint (#382). Ids that look like
* embedding models go through the embeddings path — it needs a dimension, so
* reuse the stored one when the model is already registered and probe the
* endpoint (as POST /api/embeddings/custom does) only for a new id. Everything
* else registers as a chat model. A failure registers as a per-model error and
* skips that model only: the key import itself has already succeeded.
*/
async function registerImportedModels(
db: Db,
baseUrl: string,
keyId: number,
apiKey: string,
keyName: string,
models: Array<{ id: string; supportsTools?: boolean; supportsVision?: boolean }>,
errors: Array<{ key: string; error: string }>,
): Promise<number> {
// #1051: classify by id, not just /embedding/. A whisper, diffusion or video
// id registered as a chat model 404s in every chain; they go to their own
// tables (or, for video, are skipped — nothing can serve a custom video
// model yet).
const kindOf = (id: string) => /embedding/i.test(id) ? 'embedding' : classifyModelId(id);
const chat = models.filter(m => kindOf(m.id) === undefined);
const embeds = models.filter(m => kindOf(m.id) === 'embedding');
const media = models.filter(m => {
const kind = kindOf(m.id);
return kind === 'image' || kind === 'audio' || kind === 'transcription';
});
const video = models.filter(m => kindOf(m.id) === 'video');
let registered = 0;
if (chat.length > 0) {
const entries = chat.map(m => ({
modelId: m.id,
displayName: null,
supportsTools: m.supportsTools,
supportsVision: m.supportsVision,
}));
registered += db.transaction(() => registerCustomChatModels(db, baseUrl, keyId, entries))().length;
}
for (const m of media) {
try {
registerCustomMediaModel(db, keyId, {
modelId: m.id,
displayName: null,
modality: kindOf(m.id) as 'image' | 'audio' | 'transcription',
});
registered++;
} catch (err: any) {
errors.push({ key: `${keyName}: ${m.id}`, error: err?.message ?? 'media registration failed' });
}
}
for (const m of video) {
errors.push({ key: `${keyName}: ${m.id}`, error: 'video generation models are not supported on custom endpoints yet; skipped' });
}
for (const m of embeds) {
try {
const existing = db.prepare(
"SELECT dimensions FROM embedding_models WHERE platform = 'custom' AND model_id = ?",
).get(m.id) as { dimensions: number } | undefined;
const dimensions = existing?.dimensions ?? await probeEmbeddingDimensions(baseUrl, apiKey, m.id);
registerCustomEmbeddingModel(db, {
keyId,
modelId: m.id,
displayName: null,
family: m.id,
dimensions,
maxInputTokens: null,
quotaLabel: 'custom endpoint',
});
registered++;
} catch (err: any) {
errors.push({ key: `${keyName}: ${m.id}`, error: err?.message ?? 'embedding registration failed' });
}
}
return registered;
}
// SSRF guard (#440): a base_url is the one user-controlled outbound target.
// Cloud metadata / link-local addresses are rejected outright; private ranges
// too when FREEAPI_BLOCK_PRIVATE_PROVIDER_URLS is set. Re-checked at request
// time in proxyFetch for URLs already in the DB.
async function rejectUnsafeBaseUrl(baseUrl: string, res: Response): Promise<boolean> {
const verdict = await assessProviderUrl(baseUrl);
if (verdict.allowed) return false;
res.status(400).json({ error: { message: `baseUrl rejected: ${verdict.reason}` } });
return true;
}
// Ask a configured custom endpoint what models it currently serves (#488).
// Relays add and drop models weekly, so re-typing the ids by hand goes stale
// immediately. This reads ONLY the operator's own base_url with the operator's
// own key — it never reads or refreshes the published provider catalog. Nothing
// is written: the picked ids come back through POST /custom to be registered.
const discoverModelsSchema = z.object({
baseUrl: z.string().url('baseUrl must be a valid URL').optional(),
keyId: z.number().int().positive().optional(),
// Lets the Keys page fetch a list for an endpoint the user is still typing in,
// before it has been saved. Falls back to the endpoint's stored credential.
apiKey: z.string().optional(),
}).refine(
d => d.baseUrl !== undefined || d.keyId !== undefined,
{ message: 'baseUrl or keyId is required' },
);
keysRouter.post('/custom/discover-models', async (req: Request, res: Response) => {
const parsed = discoverModelsSchema.safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
// #1348: a keyId naming a BUILT-IN key asks that provider's own /models,
// through its registered adapter, for platforms the catalog does not carry.
if (parsed.data.keyId !== undefined && parsed.data.baseUrl === undefined) {
const builtin = builtinKeyRow(parsed.data.keyId);
if (builtin) {
await discoverForBuiltinKey(builtin, parsed.data.apiKey, res);
return;
}
}
let endpoint: CustomEndpointRef;
try {
endpoint = resolveEndpointRef(parsed.data);
} catch (err: any) {
res.status(err.status ?? 400).json({ error: { message: err.message } });
return;
}
if (await rejectUnsafeBaseUrl(endpoint.baseUrl, res)) return;
// A submitted key wins (the user may be rotating it); otherwise use what the
// endpoint already has. Local servers with auth off keep the 'no-key'
// sentinel, which the bearer header carries harmlessly.
const apiKey = parsed.data.apiKey?.trim() || endpoint.storedKey || 'no-key';
try {
const discovered = await discoverEndpointModels(endpoint.baseUrl, apiKey);
// "Already registered" means bound to THIS endpoint — any key of the pool
// counts, since they all serve the same model list (#619).
const db = getDb();
const registeredIds = new Set<string>();
if (endpoint.keyId != null) {
const poolIds = [...customEndpointKeyIds(db, endpoint.keyId)];
const placeholders = poolIds.map(() => '?').join(', ');
const rows = db.prepare(
`SELECT model_id FROM models WHERE platform = 'custom' AND key_id IN (${placeholders})`,
).all(...poolIds) as { model_id: string }[];
for (const row of rows) registeredIds.add(row.model_id);
}
const models = discovered.map(m => ({ ...m, registered: registeredIds.has(m.id) }));
res.json({
baseUrl: endpoint.baseUrl,
keyId: endpoint.keyId,
models,
total: models.length,
registeredCount: models.filter(m => m.registered).length,
});
} catch (err: any) {
if (err instanceof ModelDiscoveryError) {
// `upstream_error`, never `authentication_error`: this status is relayed
// from the operator's own endpoint, and a client that reads a bare 401 as
// "session expired" would sign the operator out for testing a bad key.
res.status(err.status).json({ error: { message: err.message, type: 'upstream_error' } });
return;
}
res.status(502).json({ error: { message: `Model discovery failed: ${err?.message ?? 'unknown error'}` } });
}
});
// ── Built-in provider discovery (#1348) ─────────────────────────────────────
// The same Fetch models flow as a custom endpoint, for built-in platforms the
// catalog carries no models for (see services/builtin-model-discovery.ts for
// the eligibility rules). The catalog stays authoritative: an ineligible
// platform is refused, and registered rows are marked source='discovered' so
// a later catalog adopts or retires them.
interface BuiltinKeyRow {
id: number;
platform: string;
encrypted_key: string;
iv: string;
auth_tag: string;
proxy_encrypted?: string | null;
proxy_iv?: string | null;
proxy_auth_tag?: string | null;
}
function builtinKeyRow(keyId: number): BuiltinKeyRow | undefined {
const row = getDb().prepare(`
SELECT id, platform, encrypted_key, iv, auth_tag, proxy_encrypted, proxy_iv, proxy_auth_tag
FROM api_keys WHERE id = ?
`).get(keyId) as BuiltinKeyRow | undefined;
return row && row.platform !== 'custom' ? row : undefined;
}
async function discoverForBuiltinKey(key: BuiltinKeyRow, apiKey: string | undefined, res: Response): Promise<void> {
const db = getDb();
const eligibility = builtinDiscoveryEligibility(db, key.platform);
if (!eligibility.eligible || !eligibility.provider) {
res.status(400).json({ error: { message: ineligibleMessage(key.platform, eligibility.reason) } });
return;
}
try {
const discovered = await discoverBuiltinModels(eligibility.provider, key, apiKey);
const registeredIds = registeredModelIds(db, key.platform);
const models = discovered.map(m => ({ ...m, registered: registeredIds.has(m.id) }));
res.json({
platform: key.platform,
baseUrl: eligibility.provider.modelsUrl.replace(/\/models\/?$/, ''),
keyId: key.id,
models,
total: models.length,
registeredCount: models.filter(m => m.registered).length,
});
} catch (err: any) {
if (err instanceof ModelDiscoveryError) {
// upstream_error, never authentication_error: see the custom route.
res.status(err.status).json({ error: { message: err.message, type: 'upstream_error' } });
return;
}
res.status(502).json({ error: { message: `Model discovery failed: ${err?.message ?? 'unknown error'}` } });
}
}
const registerDiscoveredSchema = z.object({
keyId: z.number().int().positive(),
models: z.array(z.string().trim().min(1).max(256)).min(1).max(500),
});
// Register the models the operator ticked in Fetch models for a built-in key.
// Chat models only: the built-in adapters route media and embeddings through
// the catalog's own tables, so a non-chat id is reported back, not stored.
keysRouter.post('/discovered-models', (req: Request, res: Response) => {
const parsed = registerDiscoveredSchema.safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
const key = builtinKeyRow(parsed.data.keyId);
if (!key) {
res.status(400).json({ error: { message: 'keyId does not name a built-in provider key' } });
return;
}
const db = getDb();
const eligibility = builtinDiscoveryEligibility(db, key.platform);
if (!eligibility.eligible) {
res.status(400).json({ error: { message: ineligibleMessage(key.platform, eligibility.reason) } });
return;
}
const ids = [...new Set(parsed.data.models)];
const nonChat = ids.filter(id => classifyModelId(id) !== undefined);
const chat = ids.filter(id => classifyModelId(id) === undefined);
const result = registerDiscoveredModels(db, key.platform, chat.map(modelId => ({ modelId })), { explicit: true });
res.json({
platform: key.platform,
created: result.created.length,
registered: result.created,
existing: result.existing,
skippedNonChat: nonChat,
});
});
// POST /custom/probe — fire one minimal real chat request at the endpoint so an
// unmeasured model gains a reliability/speed sample without waiting for natural
// traffic (#685 follow-up). Interactive: the operator is watching, so a bounded
// timeout and a clean error beat a silent 120s hang. Only a SUCCESSFUL probe
// writes a `requests` row (which the stats cache folds into the bandit); a
// failure (401 / timeout / unreachable) surfaces the reason and records nothing.
keysRouter.post('/custom/probe', async (req: Request, res: Response) => {
const parsed = discoverModelsSchema.safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
let endpoint: CustomEndpointRef;
try {
endpoint = resolveEndpointRef(parsed.data);
} catch (err: any) {
res.status(err.status ?? 400).json({ error: { message: err.message } });
return;
}
if (await rejectUnsafeBaseUrl(endpoint.baseUrl, res)) return;
const apiKey = parsed.data.apiKey?.trim() || endpoint.storedKey || 'no-key';
// Probe a model actually REGISTERED on this endpoint when there is one — the
// sample must feed the stats of a model the router can pick, not whatever id
// happens to lead the upstream /models list. Any key of the pool counts
// (#619), and knowing the id up front also skips the discovery round-trip.
// Only an endpoint with nothing registered falls back to discovery.
let registeredModelId: string | null = null;
// The endpoint's key pool, hoisted so the capability write-back below can
// scope its UPDATE to the same keys (an unscoped model_id match would touch
// every unrelated custom endpoint that happens to serve the same id).
let poolIds: number[] = [];
if (endpoint.keyId != null) {
const db = getDb();
poolIds = [...customEndpointKeyIds(db, endpoint.keyId)];
const placeholders = poolIds.map(() => '?').join(', ');
const row = db.prepare(
`SELECT model_id FROM models WHERE platform = 'custom' AND key_id IN (${placeholders}) ORDER BY id LIMIT 1`,
).get(...poolIds) as { model_id: string } | undefined;
registeredModelId = row?.model_id ?? null;
}
try {
const probe = await probeEndpointModel(endpoint.baseUrl, apiKey, registeredModelId);
// Only a successful probe records a sample. The row mirrors what the proxy
// writes on a real request so the decay-weighted stats cache picks it up.
if (endpoint.keyId != null) {
getDb().prepare(`
INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, ttfb_ms, request_type)
VALUES ('custom', ?, ?, 'success', ?, ?, ?, ?, 'chat')
`).run(probe.modelId, endpoint.keyId, probe.inputTokens, probe.outputTokens, probe.latencyMs, probe.latencyMs);
// A real completion just succeeded, which is stronger evidence than any
// health ping — lift whatever cooldown was still holding the key back.
clearCooldownsForKey(endpoint.keyId);
}
// Phase 1 (#874): a successful tool-call probe is positive evidence the
// model speaks the OpenAI tool-call protocol — write it back to the models
// row so the tool-aware router can pick it. Only a POSITIVE result writes
// (the "only write success samples" philosophy); a negative/unknown result
// leaves the existing flag untouched.
//
// Scoped to THIS endpoint's key pool: `model_id` alone is not unique across
// custom endpoints (two relays both serving 'gpt-4o-mini' are two different
// upstreams), so an unscoped UPDATE would claim tool support for endpoints
// that were never probed.
if (probe.toolCalls && poolIds.length > 0) {
const placeholders = poolIds.map(() => '?').join(', ');
getDb().prepare(
`UPDATE models SET supports_tools = 1
WHERE platform = 'custom' AND model_id = ? AND key_id IN (${placeholders})`,
).run(probe.modelId, ...poolIds);
}
// Response stays { modelId, latencyMs } for backward compat; capability
// flags ride along as optional fields the client can opt to render.
res.json({
modelId: probe.modelId,
latencyMs: probe.latencyMs,
...(probe.reasoning !== undefined ? { reasoning: probe.reasoning } : {}),
...(probe.toolCalls !== undefined ? { toolCalls: probe.toolCalls } : {}),
});
} catch (err: any) {
if (err instanceof ModelDiscoveryError) {
// `upstream_error`, never `authentication_error`: this status is relayed
// from the operator's own endpoint, and a client that reads a bare 401 as
// "session expired" would sign the operator out for testing a bad key.
res.status(err.status).json({ error: { message: err.message, type: 'upstream_error' } });
return;
}
res.status(502).json({ error: { message: `Probe failed: ${err?.message ?? 'unknown error'}` } });
}
});
keysRouter.post('/custom', async (req: Request, res: Response) => {
const parsed = customProviderSchema.safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
let endpoint: CustomEndpointRef;
try {
endpoint = resolveEndpointRef(parsed.data);
} catch (err: any) {
res.status(err.status ?? 400).json({ error: { message: err.message } });
return;
}
const baseUrl = endpoint.baseUrl;
if (await rejectUnsafeBaseUrl(baseUrl, res)) return;
// Local servers often need no key; keep a sentinel so there's always a bearer.
const providedKey = parsed.data.apiKey?.trim() || undefined;
const label = parsed.data.label?.trim() || undefined;
// Flatten singular + plural inputs into one list, dedupe by model id, drop
// blanks. Capability flags resolve per-entry first, then fall back to the
// submit-level defaults, then to undefined (DB default). `displayName` is
// optional and stays NULL when the submit did not name the model: the field
// is genuinely optional, so an unnamed model takes its id on insert and keeps
// whatever name it already has on re-registration (see the upsert below).
const topTools = parsed.data.supportsTools;
const topVision = parsed.data.supportsVision;
const entries: { modelId: string; displayName: string | null; supportsTools?: boolean; supportsVision?: boolean; kind?: DiscoveredModelKind }[] = [];
const seen = new Set<string>();
const addEntry = (rawId: string, rawDisplay?: string, tools?: boolean, vision?: boolean, kind?: DiscoveredModelKind) => {
const modelId = rawId.trim();
if (!modelId || seen.has(modelId)) return;
seen.add(modelId);
entries.push({
modelId,
displayName: rawDisplay?.trim() || null,
supportsTools: tools ?? topTools,
supportsVision: vision ?? topVision,
kind,
});
};
if (parsed.data.model?.trim()) addEntry(parsed.data.model, parsed.data.displayName);
for (const m of parsed.data.models ?? []) {
if (typeof m === 'string') addEntry(m);
else addEntry(m.model, m.displayName, m.supportsTools, m.supportsVision, m.kind);
}
// A lone model submitted through the plural `models` also carries its name in
// the top-level `displayName` — that is exactly what the dashboard's custom
// form sends, and binding the field to the singular `model` alone silently
// dropped the name the user typed, leaving the row named after its model id
// (#704). Only a submit that resolves to ONE unnamed model may take it: a
// single name cannot fan out across several ids, which is why the form
// disables the input as soon as a second id is entered.
const soleName = parsed.data.displayName?.trim();
if (soleName && !parsed.data.model?.trim() && entries.length === 1 && entries[0]!.displayName === null) {
entries[0]!.displayName = soleName;
}
const db = getDb();
// Credential-only add (#702): a relay hands out one key per plan, and pooling
// them is the point of #619, but every route into this handler used to demand
// a model alongside the key. On an endpoint whose models are all registered
// there was nothing left to name, so operators invented a throwaway model id
// to get past the check, and deleting it afterwards took the new key with it.
if (entries.length === 0) {
if (!providedKey) {
res.status(400).json({ error: { message: 'model or models is required' } });
return;
}
if (endpoint.keyId === null) {
res.status(400).json({ error: { message: 'model or models is required to register a new endpoint' } });
return;
}
if (endpointHasCredential(db, baseUrl, providedKey)) {
res.status(409).json({ error: { message: 'this endpoint already has that key' } });
return;
}
const added = resolveCustomEndpointKey(db, baseUrl, providedKey, label, endpoint.keyId);
if (parsed.data.groupLabel !== undefined) setCustomEndpointGroup(db, added.keyId, normalizeGroupLabel(parsed.data.groupLabel));
res.status(added.created ? 201 : 200).json({
success: true,
keyId: added.keyId,
platform: 'custom',
baseUrl,
models: [],
created: 0,
alreadyRegistered: 0,
maskedKey: maskKey(added.storedKey),
});
return;
}
// #1051: a whisper, diffusion or video id submitted here used to register as
// a chat model and then 404 in every chain. Classify by id and route each
// entry to the table that can actually serve it. An explicit capability flag
// on the entry is an operator override: someone who says "this is a chat
// model with vision/tools" wins over the keyword guess.
const overridden = (e: typeof entries[number]) => e.supportsTools !== undefined || e.supportsVision !== undefined;
const kindOf = (e: typeof entries[number]) => {
// #1506: a forwarded discovery kind is authoritative for a generic-id
// model; an explicit capability flag forces chat over both the kind and
// the id guess (#1051).
if (overridden(e)) return undefined;
if (e.kind !== undefined) return e.kind;
return classifyModelId(e.modelId);
};
const chatEntries = entries.filter(e => kindOf(e) === undefined || kindOf(e) === 'embedding');
const embedEntries = chatEntries.filter(e => kindOf(e) === 'embedding');
const pureChatEntries = chatEntries.filter(e => kindOf(e) !== 'embedding');
const mediaEntries = entries.filter(e => {
const kind = kindOf(e);
return kind === 'image' || kind === 'audio' || kind === 'transcription';
});
const videoEntries = entries.filter(e => kindOf(e) === 'video');
const { keyId, storedKey, registered } = registerCustomModels(
db, baseUrl, providedKey, label, endpoint.keyId ?? undefined, pureChatEntries,
);
if (parsed.data.groupLabel !== undefined) setCustomEndpointGroup(db, keyId, normalizeGroupLabel(parsed.data.groupLabel));
const mediaRegistered: Array<{ modelDbId: number; model: string; modality: string; created: boolean }> = [];
const perModelErrors: Array<{ model: string; error: string }> = [];
for (const e of mediaEntries) {
try {
mediaRegistered.push(db.transaction(() => registerCustomMediaModel(db, keyId, {
modelId: e.modelId,
displayName: e.displayName,
modality: kindOf(e) as 'image' | 'audio' | 'transcription',
}))());
} catch (err: any) {
perModelErrors.push({ model: e.modelId, error: err?.message ?? 'media registration failed' });
}
}
const embeddingsRegistered: Array<{ model: string }> = [];
for (const e of embedEntries) {
try {
const existing = db.prepare(
"SELECT dimensions FROM embedding_models WHERE platform = 'custom' AND model_id = ?",
).get(e.modelId) as { dimensions: number } | undefined;
const dimensions = existing?.dimensions ?? await probeEmbeddingDimensions(baseUrl, providedKey ?? storedKey, e.modelId);
registerCustomEmbeddingModel(db, {
keyId,
modelId: e.modelId,
displayName: e.displayName,
family: e.modelId,
dimensions,
maxInputTokens: null,
quotaLabel: 'custom endpoint',
});
embeddingsRegistered.push({ model: e.modelId });
} catch (err: any) {
perModelErrors.push({ model: e.modelId, error: err?.message ?? 'embedding registration failed' });
}
}
// `model`/`displayName`/`modelDbId` echo the first model for older clients;
// `models` carries the full set registered in this call.
const first = registered[0];
res.status(201).json({
success: true,
keyId,
...(first ? {
modelDbId: first.modelDbId,
model: first.model,
displayName: first.displayName,
supportsTools: first.supportsTools,
supportsVision: first.supportsVision,
} : {}),
platform: 'custom',
baseUrl,
models: registered,
media: mediaRegistered,
embeddings: embeddingsRegistered,
// Video generation has no custom-endpoint serving path yet; saying so
// beats registering a chat model that can never answer.
videoSkipped: videoEntries.map(e => e.modelId),
modelErrors: perModelErrors,
// Bulk registration (#488) needs to tell the user what actually changed:
// picking a whole discovered list re-submits ids that are already there.
created: registered.filter(m => m.created).length
+ mediaRegistered.filter(m => m.created).length
+ embeddingsRegistered.length,
alreadyRegistered: registered.filter(m => !m.created).length
+ mediaRegistered.filter(m => !m.created).length,
maskedKey: maskKey(storedKey),
});
});
keysRouter.post('/import', (req: Request, res: Response, next: NextFunction) => {
upload.single('file')(req, res, async (err: any) => {
if (handleUploadError(err, res, next)) return;
try {
if (!req.file) {
res.status(400).json({ error: { message: 'No file uploaded' } });
return;
}
const result = parseUpload(req.file);
const imported: Array<{ keyName: string; platform: string }> = [];
const skipped = [...result.skipped];
const errors: Array<{ key: string; error: string }> = [];
let modelsRegistered = 0;
// One SSRF verdict per endpoint, not per key: a pooled endpoint (#619)
// brings several keys to the same URL and each check costs a DNS lookup.
const urlVerdicts = new Map<string, { allowed: boolean; reason?: string }>();
for (const parsedKey of result.keys) {
const { keyName, keyValue } = splitParsedKey(parsedKey);
if (!parsedKey.platform) {
skipped.push(keyName);
continue;
}
const platformParse = z.enum(PLATFORMS).safeParse(parsedKey.platform);
if (!platformParse.success) {
skipped.push(keyName);
continue;
}
// Custom rows name an ENDPOINT. They used to be dropped outright, which
// made every export/import round trip lose them (#687); they import now,
// but only with the base_url that says where the endpoint is.
if (platformParse.data === 'custom') {
if (!parsedKey.baseUrl) {
skipped.push(keyName);
continue;
}
const baseUrl = normalizeBaseUrl(parsedKey.baseUrl);
// Same SSRF guard the manual add path uses (#440) — an import file is
// just as capable of naming a cloud metadata address.
let verdict = urlVerdicts.get(baseUrl);
if (!verdict) {
verdict = await assessProviderUrl(baseUrl);
urlVerdicts.set(baseUrl, verdict);
}
if (!verdict.allowed) {
errors.push({ key: keyName, error: `baseUrl rejected: ${verdict.reason}` });
continue;
}
try {
// A placeholder value means "endpoint with auth off" — hand it to
// the resolver as "no key submitted" so it stores the sentinel once
// instead of treating 'no-key' as a real secret.
const secret = keyValue.trim() === 'no-key' ? undefined : keyValue.trim() || undefined;
const db = getDb();
const resolved = resolveCustomEndpointKey(db, baseUrl, secret, keyName);
imported.push({ keyName, platform: 'custom' });
if (parsedKey.models?.length) {
modelsRegistered += await registerImportedModels(
db, baseUrl, resolved.keyId, resolved.storedKey, keyName, parsedKey.models, errors,
);
}
} catch (insertErr) {
errors.push({ key: keyName, error: (insertErr as Error).message });
}
continue;
}
if (!keyValue.trim()) {
errors.push({ key: keyName, error: 'keyValue must be at least 1 character' });
continue;
}
try {
insertImportedKey(platformParse.data, keyName, keyValue);
imported.push({ keyName, platform: platformParse.data });
} catch (insertErr) {
errors.push({ key: keyName, error: (insertErr as Error).message });
}
}
res.json({
imported: imported.length,
skipped,
errors,
total: result.keys.length + result.skipped.length,
modelsRegistered,
});
} catch (handlerErr: any) {
res.status(handlerErr.status ?? 500).json({ error: { message: handlerErr.message } });
}
});
});
keysRouter.post('/preview', (req: Request, res: Response, next: NextFunction) => {
upload.array('files', 10)(req, res, (err: any) => {
if (handleUploadError(err, res, next)) return;
try {
const files = req.files as Express.Multer.File[] | undefined;
if (!files || files.length === 0) {
res.status(400).json({ error: { message: 'No files uploaded' } });
return;
}
const keys: Array<{
keyName: string; keyValue: string; detectedPlatform: string | null; prefix: string;
baseUrl?: string; models?: Array<{ id: string; supportsTools?: boolean; supportsVision?: boolean }>;
isDuplicate: boolean;
}> = [];
const skipped: string[] = [];
// Build a set of existing decrypted key values for duplicate detection
const db = getDb();
const existingRows = db.prepare('SELECT encrypted_key, iv, auth_tag FROM api_keys').all() as any[];
const existingKeys = new Set<string>();
for (const row of existingRows) {
try {
existingKeys.add(decrypt(row.encrypted_key, row.iv, row.auth_tag));
} catch { /* skip undecryptable rows */ }
}
let duplicateCount = 0;
for (const file of files) {
const result = parseUpload(file);
for (const parsedKey of result.keys) {
const { keyName, keyValue } = splitParsedKey(parsedKey);
const isDuplicate = existingKeys.has(keyValue.trim());
if (isDuplicate) duplicateCount++;
keys.push({
keyName,
keyValue,
detectedPlatform: parsedKey.platform,
prefix: parsedKey.prefix,
// Without this the dialog can show a custom row but never restore
// it — the endpoint it belongs to would be lost between the two
// calls the dashboard actually makes (#687). Models ride the same
// round trip (#382).
...(parsedKey.baseUrl ? { baseUrl: parsedKey.baseUrl } : {}),
...(parsedKey.models?.length ? { models: parsedKey.models } : {}),
isDuplicate,
});
}
skipped.push(...result.skipped);
}
res.json({ keys, total: keys.length, skipped, duplicates: duplicateCount });
} catch (handlerErr: any) {
res.status(handlerErr.status ?? 500).json({ error: { message: handlerErr.message } });
}
});
});
keysRouter.post('/import-selected', async (req: Request, res: Response) => {
const parsed = z.object({ keys: z.array(importKeySchema).max(100) }).safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
let imported = 0;
let modelsRegistered = 0;
const errors: Array<{ key: string; error: string }> = [];
// Build a set of existing decrypted key values for duplicate detection
const db = getDb();
const existingRows = db.prepare('SELECT encrypted_key, iv, auth_tag FROM api_keys').all() as any[];
const existingKeys = new Set<string>();
for (const row of existingRows) {
try {
existingKeys.add(decrypt(row.encrypted_key, row.iv, row.auth_tag));
} catch { /* skip undecryptable rows */ }
}
// One SSRF verdict per endpoint, not per key — same reasoning as /import: a
// pooled endpoint brings several keys to one URL and each check costs a DNS
// lookup.
const urlVerdicts = new Map<string, { allowed: boolean; reason?: string }>();
for (const key of parsed.data.keys) {
const keyName = key.keyName?.trim() || key.platform;
// This is the route the dashboard actually uses (preview → import-selected),
// so a custom endpoint could not be restored from its own export file until
// it handled one — /import alone was never reachable from the UI (#687).
if (key.platform === 'custom') {
if (!key.baseUrl) {
errors.push({ key: keyName, error: 'Custom providers must be added with a base URL' });
continue;
}
const baseUrl = normalizeBaseUrl(key.baseUrl);
// An import file can name a cloud metadata address just as easily as the
// manual add form can (#440), so it gets the same guard.
let verdict = urlVerdicts.get(baseUrl);
if (!verdict) {
verdict = await assessProviderUrl(baseUrl);
urlVerdicts.set(baseUrl, verdict);
}
if (!verdict.allowed) {
errors.push({ key: keyName, error: `baseUrl rejected: ${verdict.reason}` });
continue;
}
try {
// 'no-key' is the auth-less-local-server placeholder, not a secret —
// hand it over as "no key submitted" so the resolver stores the
// sentinel once instead of encrypting the literal string. Going
// through the resolver (not a raw INSERT) keeps endpoint pooling
// intact, so re-importing does not duplicate the row (#619).
const secret = key.keyValue.trim() === 'no-key' ? undefined : key.keyValue.trim() || undefined;
const resolved = resolveCustomEndpointKey(db, baseUrl, secret, keyName);
imported++;
if (key.models?.length) {
modelsRegistered += await registerImportedModels(
db, baseUrl, resolved.keyId, resolved.storedKey, keyName, key.models, errors,
);
}
} catch (err) {
errors.push({ key: keyName, error: (err as Error).message });
}
continue;
}
if (existingKeys.has(key.keyValue.trim())) {
errors.push({ key: keyName, error: 'Duplicate key — already exists' });
continue;
}
try {
insertImportedKey(key.platform, keyName, key.keyValue);
imported++;
existingKeys.add(key.keyValue.trim());
} catch (err) {
errors.push({ key: keyName, error: (err as Error).message });
}
}
res.json({
imported,
skipped: [],
errors,
total: parsed.data.keys.length,
modelsRegistered,
});
});
// Delete a key
keysRouter.delete('/:id', (req: Request, res: Response) => {
const id = parseInt(req.params.id as string, 10);
if (isNaN(id)) {
res.status(400).json({ error: { message: 'Invalid key ID' } });
return;
}
const db = getDb();
const row = db.prepare('SELECT platform, base_url FROM api_keys WHERE id = ?').get(id) as { platform: string; base_url: string | null } | undefined;
if (!row) {
res.status(404).json({ error: { message: 'Key not found' } });
return;
}
// Another credential for the SAME endpoint keeps it alive — the models move
// over to it instead of being cascaded away with this key (#619).
const sibling = row.platform === 'custom' ? siblingEndpointKeyId(db, id, row.base_url) : null;
const remove = db.transaction(() => {
if (sibling != null) {
for (const table of ['models', 'embedding_models', 'media_models']) {
db.prepare(`UPDATE ${table} SET key_id = ? WHERE platform = 'custom' AND key_id = ?`).run(sibling, id);
}
db.prepare('DELETE FROM api_keys WHERE id = ?').run(id);
return;
}
db.prepare('DELETE FROM api_keys WHERE id = ?').run(id);
// Custom models exist only because POST /custom registered them alongside
// their endpoint key (#117) — they can't route without it. Cascade away
// the models bound to THIS endpoint (#212); other custom providers keep
// theirs. Legacy rows (key_id NULL) are swept once no custom keys remain,
// so they never linger in the fallback chain forever (#189).
if (row.platform === 'custom') {
const defaultEmbedding = db.prepare("SELECT value FROM settings WHERE key = 'embeddings_default_family'").get() as { value: string } | undefined;
// #926: the scheduled custom-model sync only knows a model by "is it in
// the table yet". Without a tombstone, a key the operator deleted to get
// rid of its models would have them all re-registered by the next pass.
const scope = endpointScopeForBaseUrl(row.base_url);
const doomed = db.prepare("SELECT model_id FROM models WHERE platform = 'custom' AND key_id = ?").all(id) as { model_id: string }[];
for (const m of doomed) recordCustomModelTombstone(db, scope, m.model_id);
db.prepare("DELETE FROM fallback_config WHERE model_db_id IN (SELECT id FROM models WHERE platform = 'custom' AND key_id = ?)").run(id);
db.prepare("DELETE FROM models WHERE platform = 'custom' AND key_id = ?").run(id);
db.prepare("DELETE FROM embedding_models WHERE platform = 'custom' AND key_id = ?").run(id);
db.prepare("DELETE FROM media_models WHERE platform = 'custom' AND key_id = ?").run(id);
const remaining = db.prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'custom'").get() as { n: number };
if (remaining.n === 0) {
db.prepare("DELETE FROM fallback_config WHERE model_db_id IN (SELECT id FROM models WHERE platform = 'custom')").run();
db.prepare("DELETE FROM models WHERE platform = 'custom'").run();
db.prepare("DELETE FROM embedding_models WHERE platform = 'custom'").run();
db.prepare("DELETE FROM media_models WHERE platform = 'custom'").run();
}
if (defaultEmbedding) {
const stillExists = db.prepare('SELECT 1 FROM embedding_models WHERE family = ? LIMIT 1').get(defaultEmbedding.value);
if (!stillExists) {
const replacement = db.prepare('SELECT family FROM embedding_models ORDER BY family, priority LIMIT 1').get() as { family: string } | undefined;
if (replacement) {
db.prepare("UPDATE settings SET value = ? WHERE key = 'embeddings_default_family'").run(replacement.family);
}
}
}
}
// #1516: key-bound rows on ANY platform die with their key. The custom
// branch above already removed this endpoint's rows (plus tombstones and
// the legacy sweep); this covers key_id-pinned rows on standard
// platforms, which the catalog prune (key_id IS NULL only) never touches.
// Shared catalog rows (key_id NULL) are untouched.
db.prepare('DELETE FROM fallback_config WHERE model_db_id IN (SELECT id FROM models WHERE key_id = ?)').run(id);
db.prepare('DELETE FROM models WHERE key_id = ?').run(id);
db.prepare('DELETE FROM embedding_models WHERE key_id = ?').run(id);
db.prepare('DELETE FROM media_models WHERE key_id = ?').run(id);
});
remove();
res.json({ success: true });
});
// Toggle all keys for a platform
keysRouter.patch('/platform/:platform', (req: Request, res: Response) => {
const platform = req.params.platform as string;
if (!(PLATFORMS as readonly string[]).includes(platform)) {
res.status(400).json({ error: { message: `Invalid platform '${platform}'` } });
return;
}
const { enabled } = req.body;
if (typeof enabled !== 'boolean') {
res.status(400).json({ error: { message: 'enabled must be a boolean' } });
return;
}
// #1176: custom endpoints split into named groups, and a group's switch must
// reach only that group. `group` narrows the sweep: a label, or null for the
// ungrouped "Custom" endpoints. Absent keeps the whole-platform sweep.
const { group } = req.body;
if (group !== undefined && (platform !== 'custom' || (group !== null && typeof group !== 'string'))) {
res.status(400).json({ error: { message: 'group applies only to the custom platform and must be a string or null' } });
return;
}
const db = getDb();
const groupLabel = group === undefined ? undefined : normalizeGroupLabel(group);
const result = groupLabel === undefined
? db.prepare('UPDATE api_keys SET enabled = ? WHERE platform = ?').run(enabled ? 1 : 0, platform)
: groupLabel === null
? db.prepare("UPDATE api_keys SET enabled = ? WHERE platform = 'custom' AND group_label IS NULL").run(enabled ? 1 : 0)
: db.prepare("UPDATE api_keys SET enabled = ? WHERE platform = 'custom' AND group_label = ?").run(enabled ? 1 : 0, groupLabel);
res.json({ success: true, enabled, updatedKeys: result.changes });
});
// Update key (toggle enable/disable or edit label)
keysRouter.patch('/:id', (req: Request, res: Response) => {
const id = parseInt(req.params.id as string, 10);
if (isNaN(id)) {
res.status(400).json({ error: { message: 'Invalid key ID' } });
return;
}
const parsed = updateKeySchema.safeParse(req.body);
if (!parsed.success) {
res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });
return;
}
const { enabled, label, modelScope, proxyUrl, key, monthlyRequestCap, monthlyTokenCap, groupLabel } = parsed.data;
const updates: string[] = [];
const values: (string | number | null)[] = [];
let changedKey: string | undefined;
if (key !== undefined) {
const db = getDb();
const stored = db.prepare('SELECT platform, encrypted_key, iv, auth_tag FROM api_keys WHERE id = ?')
.get(id) as { platform: string; encrypted_key: string; iv: string; auth_tag: string } | undefined;
if (!stored) {
res.status(404).json({ error: { message: 'Key not found' } });
return;
}
// Key-optional platforms (Kilo, OVH, AI Horde) accept a real key here like
// any other provider: it replaces the anonymous sentinel (#1331).
if (stored.platform === 'cloudflare') {
const separator = key.indexOf(':');
if (separator < 1 || !key.slice(0, separator).trim() || !key.slice(separator + 1).trim()) {
res.status(400).json({ error: { message: 'Cloudflare key must be in format "account_id:api_token"' } });
return;
}
}
try {
if (decrypt(stored.encrypted_key, stored.iv, stored.auth_tag) !== key) changedKey = key;
} catch {
// An undecryptable old credential is still replaceable.
changedKey = key;
}
}
if (enabled !== undefined) {
updates.push('enabled = ?');
values.push(enabled ? 1 : 0);
}
if (changedKey !== undefined) {
const { encrypted, iv, authTag } = encrypt(changedKey);
updates.push('encrypted_key = ?', 'iv = ?', 'auth_tag = ?', "status = 'unknown'", 'last_checked_at = NULL', 'last_health_error = NULL');
values.push(encrypted, iv, authTag);
// #1459: pasting in a new key means "use this key". A row the health
// checker auto-disabled would otherwise stay off with a fresh credential
// and never serve a request. An explicit `enabled` in the same call wins.
if (enabled === undefined) updates.push('enabled = 1');
}
if (label !== undefined) {
updates.push('label = ?');
values.push(sanitizeLabel(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);
}
// Monthly budget caps (#1158): 0 = unlimited.
if (monthlyRequestCap !== undefined) {
updates.push('monthly_request_cap = ?');
values.push(monthlyRequestCap);
}
if (monthlyTokenCap !== undefined) {
updates.push('monthly_token_cap = ?');
values.push(monthlyTokenCap);
}
// Custom-endpoint group label (#1176) is written below, across the
// endpoint's whole key pool rather than this one row.
const db = getDb();
if (groupLabel !== undefined) {
const row = db.prepare('SELECT platform FROM api_keys WHERE id = ?').get(id) as { platform: string } | undefined;
if (!row) {
res.status(404).json({ error: { message: 'Key not found' } });
return;
}
if (row.platform !== 'custom') {
res.status(400).json({ error: { message: 'groupLabel applies only to custom endpoints' } });
return;
}
}
// Deduped; an empty result stores NULL, which the router reads as "unscoped".
const scopeIds = modelScope == null ? [] : [...new Set(modelScope)];
if (modelScope !== undefined) {
updates.push('model_scope_json = ?');
values.push(scopeIds.length > 0 ? JSON.stringify(scopeIds) : null);
}
values.push(id);
// Re-submitting the same key satisfies "something changed" but is a no-op;
// it must not turn into an invalid UPDATE with an empty SET list.
const result = db.transaction(() => {
const changes = updates.length === 0
? 1
: db.prepare(`UPDATE api_keys SET ${updates.join(', ')} WHERE id = ?`).run(...values).changes;
if (changes > 0 && groupLabel !== undefined) setCustomEndpointGroup(db, id, normalizeGroupLabel(groupLabel));
return { changes };
})();
if (result.changes === 0) {
res.status(404).json({ error: { message: 'Key not found' } });
return;
}
if (changedKey !== undefined) clearCooldownsForKey(id);
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 (key !== undefined) response.maskedKey = maskKey(key);
if (modelScope !== undefined) response.modelScope = scopeIds.length > 0 ? scopeIds : null;
if (groupLabel !== undefined) response.groupLabel = normalizeGroupLabel(groupLabel);
res.json(response);
});