Changeset 0.9.1 (#51)

This commit is contained in:
2026-02-23 13:42:23 +00:00
parent 8264aa6016
commit febcbde3d7
21 changed files with 1881 additions and 423 deletions

View File

@@ -1,44 +1,521 @@
# Roadmap — Chat Switchboard
## v0.9.0 (Current)
**See also:**
- [ARCHITECTURE.md](ARCHITECTURE.md) — Core services design, store layer, scope model
- [EXTENSIONS.md](EXTENSIONS.md) — Extension system spec (Browser/Starlark/Sidecar tiers,
manifests, browser tool bridge, surfaces/modes, model roles)
- [x] Consolidated schema (21 migrations → 1)
- [x] Store layer abstraction (all DB access via typed interfaces)
- [x] Persona-as-trust-boundary model (replaces presets)
**Versioning (pre-1.0):** `0.<major>.<minor>` — hotfixes use quad: `0.x.y.z`
No compatibility guarantees before 1.0.
---
## Dependency Graph
Features have real dependencies. This ordering respects them.
```
v0.9.x Stability + Quick UX Wins
v0.9.3 API Key Encryption + Vault
v0.10.0 Model Roles (utility + embedding) + Usage Tracking
v0.10.1 Summarize & Continue (first utility role consumer)
┌───────┴──────────────┐
│ │
v0.11.0 Extension v0.12.0 File Handling
Foundation + Vision
(browser tier) │
│ │
├── Custom renderers ├── Doc gen outputs
├── Image gen tool ├── KB documents
├── STT/TTS │
│ │
├───────────────────────┤
│ │
v0.13.0 Web Search + Tools Expansion
v0.14.0 Knowledge Bases (embedding role + file storage + pgvector)
v0.15.0 Compaction (utility role + background job)
v0.16.0 @mention Routing + Multi-model
v0.17.0 Extension Surfaces + Modes
v0.18.0 Smart Routing (policy on model roles)
v0.19.0 Live Collaboration (presence, co-editing)
v0.20.0 Auth Strategy (mTLS/OIDC) + Full RBAC
v0.21.0 Tasks / Autonomous Agents
```
---
## ✅ v0.9.0 — Schema Consolidation + BYOK
The "rewrite" release: 21 migrations collapsed to 1, store layer abstraction,
and the model pipeline made real for end users.
**Schema & Architecture**
- [x] Consolidated schema (21 migrations → single 001_initial.sql)
- [x] Store layer abstraction (all DB via typed interfaces, no raw SQL in handlers)
- [x] Persona-as-trust-boundary model (replaces old presets concept)
- [x] Scope model (global/team/personal) for configs, personas, models
- [x] Capabilities resolver chain (catalog → known → heuristic)
- [x] Three-state model visibility (enabled/disabled/team-only)
- [x] User model preferences (hide, sort)
- [x] Audit log foundation
- [x] Backward-compatible API routes
- [x] Backward-compatible API routes (v0.8 → v0.9 field aliases)
## v0.9.1 (Next)
**Capabilities System**
- [x] Two-tier resolution: catalog (provider API, per-provider) → heuristic inference
- [x] Venice provider: full capability mapping incl. `optimizedForCode`
- [x] `ResolveIntrinsic` with gap-fill merging (catalog authoritative, heuristic fills gaps)
- [x] Preset capability inheritance via `GetByModelIDAny` fallback
- [ ] Chat search (full-text search across messages)
- [ ] Keyboard shortcuts + command palette (Ctrl+K)
- [ ] PWA enhancements (offline indicator, install prompt)
- [ ] API key at-rest encryption
- [ ] v0.8 → v0.9 migration script (002_v08_to_v09.sql)
**BYOK (Bring Your Own Key)**
- [x] Auto-fetch models on provider creation
- [x] User-facing refresh endpoint + "Refresh Models" button
- [x] Personal models in selector with `scope=personal` badge
- [x] Composite model IDs (`configId:modelId`) prevent cross-provider collisions
## v0.10
**Bug Fixes (0.9.0.x)**
- [x] API key storage (`json:"-"` tag silently dropped keys)
- [x] NULL model_default scan crash (sql.NullString)
- [x] Nil slice → JSON null (make([]T, 0))
- [x] Frontend error swallowing
- [ ] Grant management UI (admin assigns model access per team)
- [ ] Model visibility toggle in admin panel
- [ ] Team/group notes (shared note folders)
- [ ] Conversation export (markdown, JSON)
- [ ] Plugin system (tool registration API)
**Testing**
- [x] Journey-based integration tests (API-only, 4-actor × 3-provider matrix)
- [x] Live Venice API integration test
- [x] Frontend JS test suite (107 tests, 27 suites)
## v0.11
---
- [ ] OIDC/Keycloak authentication mode
- [ ] mTLS client certificate authentication
- [ ] SSO integration patterns
- [ ] Rate limiting per user/team (configurable quotas)
## ✅ v0.9.1 — Capability Architecture + Docs
## Future
- [x] Removed static known model table (same model ≠ same capabilities across providers)
- [x] Resolution chain: catalog → heuristic only, no hardcoded table
- [x] Frontend KNOWN_MODELS removed — backend is sole source of truth
- [x] Heuristic patterns expanded (qwen3, gpt-5, grok, kimi, minimax, glm-5, gemma-3)
- [x] All providers updated to use `InferCapabilities()` directly
- [x] EXTENSIONS.md recovered and updated with Appendix A (Custom Renderers)
and Appendix B (Model Roles)
- [x] ROADMAP.md, CHANGELOG.md, README.md comprehensive rewrite
- [ ] SQLite backend option (for single-user / dev deployments)
- [ ] Multi-model conversations (different models per message)
- [ ] Conversation templates (reusable multi-turn starters)
- [ ] Agent mode (multi-step tool use with human-in-the-loop)
- [ ] Model cost tracking and reporting
---
## v0.9.2 — Quick UX Wins + Hardening
Polish that doesn't need new infrastructure. Ship fast, stabilize.
**UX**
- [x] Collapsible code blocks (long outputs get `<details>` wrapper)
- [x] HTML preview for generated content (sandboxed iframe toggle)
- [x] Token count estimate in input area (before send)
- [x] "Conversation is getting long" warning (context % thresholds)
**Hardening**
- [x] Proxy interception detection (Content-Type checks, actionable error messages)
- [x] Environment injection to frontend (`window.__ENV__`)
- [x] Enhanced debug diagnostics (NET:PROXY log type, Content-Type capture, env info)
- [ ] Team admin audit scoping (see only their team's audit entries)
---
## v0.9.3 — API Key Encryption + Vault
Two-tier encryption with a trust boundary between organizational keys (admin-
accessible) and personal BYOK keys (user-only). Personal keys are protected
by a per-user encryption key (UEK) that the platform admin cannot recover
without the user's passphrase.
### Threat Model
| Threat | Global/Team keys | Personal BYOK keys |
|--------|-----------------|---------------------|
| DB backup theft | ✅ Protected (env-var AES) | ✅ Protected (UEK AES) |
| SQL injection exfil | ✅ Protected | ✅ Protected |
| Admin reads DB directly | ⚠️ Admin can decrypt (owns env var) | ✅ Admin cannot decrypt (lacks user passphrase) |
| Admin modifies server code | ⚠️ Out of scope (runtime access) | ⚠️ Out of scope (runtime access) |
### Crypto Design
**Two encryption paths, one mechanism (AES-256-GCM):**
1. **Global/Team keys** — encrypted with a key derived from `ENCRYPTION_KEY`
env var. Admin-owned, admin-recoverable. Simple.
2. **Personal keys** — encrypted with a per-user **User Encryption Key (UEK)**.
The UEK is a random 256-bit key generated at account creation, itself
encrypted with a key derived from the user's password via Argon2id.
```
Password → Argon2id(salt) → Password-Derived Key (PDK)
PDK → AES-256-GCM-Decrypt(encrypted_uek) → UEK (plaintext, session-only)
UEK → AES-256-GCM-Decrypt(api_key_enc) → API key (plaintext, per-request)
```
The UEK lives in server memory for the duration of the session (alongside the
JWT). It is never written to disk, logs, or the database in plaintext.
### Schema Changes (migration)
```sql
-- Users: vault support
ALTER TABLE users ADD COLUMN encrypted_uek BYTEA;
ALTER TABLE users ADD COLUMN uek_salt BYTEA; -- Argon2id salt
ALTER TABLE users ADD COLUMN uek_nonce BYTEA; -- GCM nonce for UEK wrap
ALTER TABLE users ADD COLUMN vault_set BOOLEAN NOT NULL DEFAULT false;
-- API configs: encrypted key storage
ALTER TABLE api_configs ADD COLUMN api_key_enc BYTEA;
ALTER TABLE api_configs ADD COLUMN key_nonce BYTEA;
ALTER TABLE api_configs ADD COLUMN key_scope TEXT NOT NULL DEFAULT 'global';
-- key_scope: 'global' | 'team' | 'personal'
-- global/team: decrypt with env-var-derived key
-- personal: decrypt with user's UEK
-- Team providers: same pattern
ALTER TABLE team_providers ADD COLUMN api_key_enc BYTEA;
ALTER TABLE team_providers ADD COLUMN key_nonce BYTEA;
```
Migration backfills: encrypt existing plaintext keys using the env var key
(all existing keys are global/team scope). Drop plaintext `api_key` column
after backfill. If `ENCRYPTION_KEY` is not set, migration refuses to run
(fail-safe).
### Auth Mode Integration
**Builtin auth** — password serves double duty: authentication + UEK
derivation. No additional UX. On login, derive PDK → unwrap UEK → cache
in session. User never knows the vault exists.
**mTLS / OIDC** (v0.20.0) — authentication is external (cert/token).
Vault passphrase is conditionally required:
```
External auth → auto-authenticated
├── Personal providers DISABLED → straight to app, no prompt
└── Personal providers ENABLED
├── First visit → "Set a vault passphrase to protect your API keys"
└── Returning → "Unlock your vault" (passphrase field, pre-filled username)
```
Terminology: **"vault passphrase"** for mTLS/OIDC users (distinct from their
non-existent account password). Builtin auth users never see this term.
### Backend Implementation
**`server/crypto/vault.go`** — pure encryption/decryption, no DB awareness:
- `DeriveKey(password, salt) → key` (Argon2id, 64MB memory, 3 iterations)
- `GenerateUEK() → (uek, error)` (crypto/rand, 32 bytes)
- `WrapUEK(uek, pdk) → (ciphertext, nonce, error)`
- `UnwrapUEK(ciphertext, nonce, pdk) → (uek, error)`
- `Encrypt(plaintext, key) → (ciphertext, nonce, error)`
- `Decrypt(ciphertext, nonce, key) → (plaintext, error)`
- `DeriveEnvKey(envVar) → key` (SHA-256 of env var, simple deterministic)
**Session UEK caching** — UEK stored in a sync.Map keyed by user ID, evicted
on logout / token expiry. Completion handler retrieves UEK from cache to
decrypt personal provider keys at request time.
**Provider resolution**`key_scope` determines decryption path:
```go
func (s *Store) DecryptAPIKey(config ApiConfig, uekCache *sync.Map) (string, error) {
switch config.KeyScope {
case "global", "team":
return crypto.Decrypt(config.APIKeyEnc, config.KeyNonce, envDerivedKey)
case "personal":
uek, ok := uekCache.Load(config.UserID)
if !ok { return "", ErrVaultLocked }
return crypto.Decrypt(config.APIKeyEnc, config.KeyNonce, uek.([]byte))
}
}
```
### Edge Cases
| Scenario | Behavior |
|----------|----------|
| **User changes password** (builtin) | Re-derive PDK, re-encrypt UEK with new PDK. Personal API keys unchanged (keyed to UEK, not password). |
| **Admin resets user password** | Old UEK unrecoverable. Personal keys destroyed. Admin UI warns before confirming. |
| **mTLS user forgets passphrase** | Self-service reset: destroys encrypted personal keys. UX: "This will erase your stored API keys." |
| **Admin disables personal providers** | Keys stay encrypted in DB (inert). Re-enable later → keys accessible if user remembers passphrase. |
| **`ENCRYPTION_KEY` not set** | Startup refuses to run if encrypted keys exist in DB. Fresh install: keys stored plaintext with deprecation warning in logs + admin panel. |
| **`ENCRYPTION_KEY` rotated** | Admin CLI tool: `switchboard vault rekey` — re-encrypts all global/team keys with new env key. Personal keys unaffected (keyed to UEK). |
### Frontend Changes
- Provider management (Settings → Providers): no change to UX for builtin auth
- mTLS/OIDC splash: conditional vault passphrase prompt (new component)
- Admin → Users → Reset Password: warning dialog about personal key destruction
- Admin → Settings: indicator for `ENCRYPTION_KEY` status (set / not set)
### Checklist
**Crypto core**
- [ ] `server/crypto/vault.go` — Argon2id derivation, AES-256-GCM wrap/unwrap
- [ ] `server/crypto/vault_test.go` — round-trip, wrong-password, corruption
- [ ] Env-var key derivation + validation on startup
**Schema + migration**
- [ ] Migration: add encrypted columns, backfill existing keys, drop plaintext
- [ ] `ENCRYPTION_KEY` enforcement (refuse to start if keys exist but no env var)
**Auth integration**
- [ ] UEK generation on user creation (builtin auth)
- [ ] UEK unwrap on login, cache in session
- [ ] UEK re-wrap on password change
- [ ] UEK destruction on admin password reset (with confirmation)
- [ ] Vault passphrase prompt for mTLS/OIDC (when personal providers enabled)
**Provider key lifecycle**
- [ ] Encrypt on provider create/update
- [ ] Decrypt on completion request (per key_scope)
- [ ] `ErrVaultLocked` handling (prompt user to unlock)
**Admin tooling**
- [ ] `switchboard vault rekey` CLI command
- [ ] Admin UI: encryption status indicator
- [ ] Admin UI: password reset warning
---
Two pieces of infrastructure that everything downstream depends on.
**Model Roles** (see [EXTENSIONS.md Appendix B](EXTENSIONS.md#appendix-b-model-roles))
- [ ] `model_roles` in global_settings: named slots (utility, embedding, generation)
- [ ] Each role: primary provider+model, optional fallback provider+model
- [ ] Team-level role overrides (team.settings JSONB)
- [ ] Backend API: `roles.Complete(ctx, "utility", messages)` with automatic fallback
- [ ] Backend API: `roles.Embed(ctx, "embedding", text)` with automatic fallback
- [ ] Admin UI: role configuration (select provider + model per role)
**Usage Tracking**
- [ ] Capture from provider responses: prompt_tokens, completion_tokens,
cache_creation_tokens, cache_read_tokens
- [ ] `usage_log` table: channel_id, user_id, model_id, provider_id,
role (nullable — "utility", "embedding", or NULL for user chat),
token counts, timestamp
- [ ] Model pricing from catalog sync (Venice/OpenAI report pricing)
- [ ] Admin override pricing (per M tokens, decimal)
- [ ] Cost calculated at query time (join usage × pricing)
- [ ] Per-user and per-team usage dashboard in admin panel
---
## v0.10.1 — Summarize & Continue
First consumer of the utility model role. User-triggered conversation
compaction — not automatic (that's v0.15.0).
- [ ] "Summarize and continue" button (appears alongside context length warning)
- [ ] Calls utility role to summarize conversation history
- [ ] Summary inserted as system message, earlier messages hidden from context
- [ ] Original messages preserved in DB (viewable via "show full history" toggle)
- [ ] Respects team-level role overrides for utility model selection
---
## v0.11.0 — Extension Foundation (Browser Tier)
The platform play. See [EXTENSIONS.md](EXTENSIONS.md) for full spec.
**Core Loader** (EXTENSIONS.md §4, §7)
- [ ] `extensions.js` — loader, registry, scoped context (~200 lines)
- [ ] `Extensions.register()` API with permission enforcement
- [ ] Manifest format parser and validator
- [ ] `extensions` + `extension_user_settings` tables
- [ ] Admin endpoints: install, uninstall, enable/disable
- [ ] Asset serving: `/api/v1/extensions/:id/assets/*path`
- [ ] Extension settings UI in Settings modal
**Browser Tool Bridge** (EXTENSIONS.md §5)
- [ ] `ctx.tools.handle()` API for browser tool registration
- [ ] Tool schema collection: merge built-in + extension tools
- [ ] `tool.call.*` / `tool.result.*` WebSocket routing
- [ ] 30-second timeout with LLM error recovery
- [ ] Tool execution via EventBus `WaitFor` pattern
**Custom Renderer API** (EXTENSIONS.md Appendix A)
- [ ] `ctx.renderers.register()` — pattern + render function
- [ ] Renderer pipeline in message display (after markdown, before DOM insert)
- [ ] First-party renderers: collapsible code, HTML preview, mermaid, LaTeX
(migrate core v0.9.2 implementations to extension format)
**First Extensions**
- [ ] Image generation tool (browser or sidecar, uses generation model role)
- [ ] STT/TTS (browser extension, Web Speech API — personal use case)
---
## v0.12.0 — File Handling + Vision
File input into chat — table stakes for serious use.
**Storage Backend**
- [ ] S3-compatible API (MinIO, Ceph RGW, AWS — anything with S3 API)
- [ ] Local PVC fallback (single-node / dev)
- [ ] Admin config: backend selection, endpoint, credentials, size limits
- [ ] Reused by KBs (v0.14.0) and compaction snapshots (v0.15.0)
**Chat Integration**
- [ ] `attachments` table (metadata in PG, blobs in object store)
- [ ] Image/file upload in chat messages
- [ ] Multimodal message assembly for vision-capable models
- [ ] Text extraction on upload (PDF, DOCX, TXT → tsvector)
- [ ] Paste-to-upload (clipboard image support)
- [ ] Document generation output storage (extension → attachment → download)
---
## v0.13.0 — Web Search + Tools Expansion
Built-in tools that use the tool framework shipped in v0.7.x.
- [ ] `web_search` tool: search provider abstraction (SearXNG, Brave, DuckDuckGo)
- [ ] `url_fetch` tool: retrieve and extract content from URLs
- [ ] Sidecar or direct HTTP from backend (configurable)
- [ ] Results injected into context
- [ ] "Research X and save to my notes" workflow
---
## v0.14.0 — Knowledge Bases
Depends on: embedding model role (v0.10.0), file storage (v0.12.0).
- [ ] Embedding pipeline: chunking (recursive, semantic), generation via embedding role
- [ ] `pgvector` storage and similarity search
- [ ] `knowledge_bases` table with team scoping
- [ ] KB document storage via v0.12.0 storage backend
- [ ] `kb_search` tool (uses existing tool framework)
- [ ] Context injection in completion flow
- [ ] Notes embedded too (once pipeline exists)
- [ ] Per-channel KB toggle
---
## v0.15.0 — Compaction
Depends on: utility model role (v0.10.0).
- [ ] Auto-compaction service: background job that calls utility model to summarize
- [ ] Channel-scoped: triggers when context exceeds threshold
- [ ] Summaries stored as system messages
- [ ] Configurable: per-channel opt-in/out, summary model override
- [ ] Admin controls for resource limits
---
## v0.16.0 — @mention Routing + Multi-model
The channel schema already supports multiple models. This adds routing.
- [ ] @mention parsing in messages (users and AI models)
- [ ] Resolve mentions against `channel_models`
- [ ] Multi-model channels: fire completions per mentioned model
- [ ] "Add a model" UI per channel
- [ ] Enables: second opinions, cross-model conversations
---
## v0.17.0 — Extension Surfaces + Modes
Depends on: extension foundation (v0.11.0).
See [EXTENSIONS.md §6](EXTENSIONS.md#6-surfaces-modes).
- [ ] Surface registration and activation API
- [ ] Mode selector in sidebar (below brand, above chat history)
- [ ] `ctx.ui.replace()` / `ctx.ui.restore()` for region management
- [ ] `surface.activated` / `surface.deactivated` events
- [ ] Editor mode (extension: file tree + code editor + AI chat split pane)
- [ ] Article mode (extension: outline + rich text + AI assistant panel)
---
## v0.18.0 — Smart Routing
Depends on: model roles (v0.10.0), usage tracking (v0.10.0).
Rules-based routing engine — policy, not ML.
- [ ] Admin routing policies: "cheapest model with required capabilities",
"prefer private providers, fallback to cloud", "for team X, use Y"
- [ ] Fallback chains: primary provider down → next with same model
- [ ] Cost-aware: factor pricing into routing decisions
- [ ] Latency-aware: track response times per provider, prefer faster
---
## v0.19.0 — Live Collaboration
Depends on: extension surfaces (v0.17.0), WebSocket infrastructure (already exists).
- [ ] Typing indicators and presence (who's online, who's in this channel)
- [ ] Co-editing for extension surfaces (editor mode, article mode)
- [ ] Enables: IDE extension with pair programming, collaborative doc editing
- [ ] Cursor sharing, selection highlighting
---
## v0.20.0 — Auth Strategy (mTLS/OIDC) + Full RBAC
Enterprise auth modes on top of the teams foundation.
Depends on: vault passphrase support from v0.9.3 (conditional unlock for
personal providers under external auth).
- [ ] `AUTH_MODE` env var: `builtin` | `mtls` | `oidc`
- [ ] All three resolve to the same internal user model
- [ ] `auth_source` + `external_id` columns on users table
- [ ] mTLS: header trust, auto-provision from cert DN
- [ ] OIDC: Keycloak/Okta token validation, claim extraction, role mapping
- [ ] Per-source auto-activate policy: auto_activate, default_team, default_role
- [ ] Vault passphrase prompt for mTLS/OIDC users (v0.9.3 conditional unlock)
- [ ] Fine-grained permissions: model access, KB write, task create, token budgets
---
## v0.21.0 — Tasks / Autonomous Agents
The capstone: everything combined into autonomous workflows.
- [ ] Scheduler + task runner
- [ ] `task_create` tool
- [ ] `type: 'service'` channels with no human members
- [ ] Depends on: completion handler, tool execution, notes, web search
- [ ] Admin controls for resource limits, execution budgets
---
## TBD (unscheduled — real features, no immediate need)
Items that are real but don't yet have a version assignment. Pull left
based on need.
**Extension System — Server Tiers**
- Starlark runtime integration (Tier 1 — server sandbox)
- Sidecar HTTP tool protocol (Tier 2 — container isolation)
- Server-side tool execution in completion handler
**Desktop + Mobile**
- Desktop app (Tauri)
- Full PWA with offline capability
- Mobile-optimized layouts (beyond current responsive)
**Data + Portability**
- Bulk export/import (account data, conversations, settings)
- ChatGPT/other tool import
- GDPR-style "download my data"
- Backup/restore CronJob manifests
**Platform**
- Rate limiting per user/team/tier (token budgets)
- Provider health monitoring + key rotation
- Multi-tenant SaaS mode
- Workflow builder (visual DAG for chaining models + tools)
- Plugin/extension marketplace
- Virtual scroll for long conversations
- SQLite backend option (single-user / dev)