Keysat
988a3cca9a
Multi-user authorization hardening from a full security evaluation (EVALUATION.md):
- P0: /api/settings/{export,import}-db are now admin-only. Previously any signed-in user could download the whole instance DB (all bcrypt hashes + plaintext AI keys) or replace it wholesale. Per-user CSV export/import stays open.
- AI custom-URL providers (Ollama, OpenAI-compatible) are now admin-only, and every server fetch to a user-supplied URL passes through assertSafeProviderUrl (blocks link-local/cloud-metadata; private LAN allowed by design). Fixed-URL cloud providers stay per-user. Removed the dead legacy /api/ai/config route.
- Dev: fixed broken quick-start (added npm run create-admin; rewrote README; dropped dead CLAUDE_API_KEY) and the export-db 0-byte path resolution (resolveDatabasePath now matches Prisma).
ExVer bumped to 1.1.0:8 (no schema/data migration). Tests 197 pass, build green, tsc clean.
46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
---
|
|
paths:
|
|
- proof-of-work/lib/ai/**
|
|
- proof-of-work/app/api/ai/**
|
|
---
|
|
|
|
# AI subsystem
|
|
|
|
Scoped guidance for the AI generation subsystem (`proof-of-work/lib/ai/**` and the
|
|
generate/generations route handlers). Whole-repo rules live in `AGENTS.md`.
|
|
|
|
## Architecture
|
|
|
|
- `generate/route.ts` kicks off a **detached background runner** (`generationRunner.ts`)
|
|
and returns an id; the client attaches via SSE (`generations/[id]/stream`) and can also
|
|
poll the row. Navigating away does NOT cancel generation.
|
|
- System prompt = `systemPromptBase.ts` (output contract: JSON-only, library
|
|
`exerciseId`s only, suggested weights) + the template's coaching prompt +
|
|
`PROGRAM_OUTPUT_SHAPE` + library + optional history block (`historyContext.ts`).
|
|
- Multi-config: `AIConfigProfile` rows per user; `UserPreferences.activeAIConfigId`
|
|
points at the active one and is mirrored into the legacy `ai*` columns for back-compat.
|
|
|
|
## Provider abstraction
|
|
|
|
- Each provider yields an async iterable of `GenerateChunk` (`text` / `usage` / `done` /
|
|
`error`); add new ones under `lib/ai/providers/` and register in `index.ts`.
|
|
`openai.ts` exports both `openai` and `openai-compatible`, so the four provider files
|
|
register **5** providers (`claude`, `openai`, `openai-compatible`, `gemini`, `ollama`).
|
|
- Streaming AI uses SSE; partial JSON is recovered with `lib/ai/lenientJson.ts`.
|
|
- Pricing/model menus live in `lib/ai/pricing.ts` (`PRICES`, `MODEL_MENU`) — keep them
|
|
paired so every menu model has a price entry (there's a test enforcing this).
|
|
|
|
## SSRF / provider-URL safety
|
|
|
|
- Any `fetch` to a user-supplied provider base URL MUST go through
|
|
`assertSafeProviderUrl` (`lib/ai/safeUrl.ts`) first — it enforces http(s) and blocks
|
|
link-local/cloud-metadata (169.254/16, fe80::/10) + unspecified. **Private-LAN +
|
|
loopback are allowed on purpose** (reaching `ollama.startos`/LAN gateways is the
|
|
feature). Currently wired into `providers/ollama.ts`, the `openai-compatible` path in
|
|
`providers/openai.ts` (NOT the fixed `api.openai.com` path), and the `ai/ollama/models`
|
|
probe. Add the guard to any new user-URL fetch path.
|
|
- Custom-URL providers (those with `requiresBaseUrl`: ollama, openai-compatible) are
|
|
**admin-only** — `isCustomUrlProvider` gates `ai/configs` POST + `[id]` PATCH + `ai/test`,
|
|
and `ai/ollama/models` is fully admin-only. The Settings UI hides them from non-admins.
|
|
This is a second defense layer on top of the IP block; keep both when adding routes.
|