Bring Your Own Key (BYOK): per-user LLM API keys

[edspencer]

Part of the free/non-profit pivot (follows PRs #400–#404). BragDoc is now free; AI features should run on each user's own LLM API key instead of the platform's OPENAI_API_KEY.

Summary

• New shared packages/ai (@bragdoc/ai) provider factory, lifted from the CLI's createLLMFromConfig (OpenAI, Anthropic, Google, DeepSeek, Ollama, OpenAI-compatible), with the Google env-var mutation hack replaced by an explicit-key constructor
• New user_llm_config table storing AES-256-GCM-encrypted keys (WebCrypto, HKDF-derived from a new BYOK_ENCRYPTION_KEY secret — Cloudflare Workers-safe), one row per provider, key hint (last 4) for display, never returned to the client
• Settings UI on the Account page: provider + key + model, verified with a live probe on save
• Central resolveModelForUser(user, task) replaces the frozen model singletons in apps/web/lib/ai/index.ts; singletons are deleted so the compiler surfaces every call site. Typed no_api_key error → UI CTAs linking to settings
• Demo users fall through to the platform key; embeddings stay on the platform key in v1 (OpenAI-only API, fixed 1536-d vectors, trivial cost) so Workstreams keeps working regardless of the user's chat provider
• Marketing site: add "add your API key in Settings" to how-it-works/get-started flows, FAQ, CLI docs page

Full SPEC.md and PLAN.md in tasks/ directory.

[edspencer]

📋 Specification

# Task: Bring Your Own Key (BYOK) — per-user LLM API keys

GitHub issue: #405. Follows the free/non-profit pivot (PRs #400–#404, which should merge first).

BragDoc is now completely free. All server-side AI features currently run on the platform's
`OPENAI_API_KEY`; this task makes them run on each user's own LLM API key, stored encrypted,
configurable in Settings, with a multi-provider backend (OpenAI, Anthropic, Google, DeepSeek,
Ollama, OpenAI-compatible endpoints).

## Background Reading

- `.claude/docs/tech/ai-integration.md`, `authentication.md`, `database.md`
- `packages/cli/src/ai/providers.ts` + `packages/cli/src/config/types.ts` — the existing
  multi-provider factory this feature generalizes
- `apps/web/lib/ai/index.ts` — the frozen model singletons being replaced

## Current state (research findings, 2026-07-04)

**Web AI layer.** `apps/web/lib/ai/index.ts` binds everything to `openai(...)` via module-level
singletons (`routerModel`, `documentWritingModel`, `extractAchievementsModel`, `chatModel`);
`getLLM(taskType)` takes no user. ~15 files import these constants. Two additional seams bypass
it: `lib/llm-utils.ts` (raw `fetch` to the OpenAI REST API with `Bearer ${OPENAI_API_KEY}`,
hardcoded gpt-4, exposes RSC actions of unclear liveness) and `lib/ai/embeddings.ts`
(`openai.embedding('text-embedding-3-small')`, 1536-d, powers Workstreams).

**User is already in scope at every live AI call site** (chat routes, document generate,
performance review, standups, workstreams, achievements POST) — several lib functions even
accept a `_user` param and ignore it. Exceptions:
- `app/(app)/chat/actions.ts` `generateTitleFromUserMessage` receives only `{message}` — signature change needed.
- `/api/cli/commits` — legacy server-side extraction; the shipping CLI extracts locally and never calls it.
- Inbound email webhook — AI is currently disabled there; user resolvable by sender email if re-enabled.
- No cron/queue consumers exist.

**CLI.** Already fully BYOK client-side: `createLLMFromConfig()` supports all six providers
with config-or-env keys. Extraction happens locally; the CLI POSTs finished achievements.
Caveats found: the Google path mutates `process.env` (unsafe under server concurrency — must
be rewritten with `createGoogleGenerativeAI({ apiKey })`), and `lib/extraction.ts:37` still
hard-requires `OPENAI_API_KEY` (CLI bug, fix opportunistically).

**Versions.** `ai` and `@ai-sdk/{openai,google}` versions match between CLI and web. Web lacks
`@ai-sdk/anthropic` and `ollama-ai-provider-v2`. CLI uses zod v4, web zod v3 — the shared
package must keep zod out of its public API.

**Storage & crypto.** No encrypted-at-rest storage exists anywhere yet. Deploy target is
Cloudflare Workers (OpenNext, `nodejs_compat`); `node:crypto` cipher support is partial there,
WebCrypto (`crypto.subtle`) is fully supported and also present in Node 20+ for dev parity.
`user.preferences` jsonb is returned wholesale by `GET /api/user` — secrets must NOT live there.
Account deletion (`lib/account-deletion.ts`) preserves the user row, so the key table needs an
explicit delete there (cascade alone is insufficient).

**Demo mode.** Seeding uses pre-baked data (no LLM), but demo users hitting chat/generation go
through the same routes and today use the platform key.

## Specific Requirements

### 1. Shared provider package — `packages/ai` (`@bragdoc/ai`)

- Move from the CLI: `LLMProvider` union, per-provider config interfaces, `LLMConfig`,
  `DEFAULT_MODELS`, `PROVIDER_OPTIONS` (names + signup URLs), `createLLMFromConfig()`,
  `getLLMDisplayName()`, `isLLMConfigured()`.
- Fix the Google provider to use `createGoogleGenerativeAI({ apiKey })` — no env mutation.
- Add `verifyLLMConfig(config)` — instantiate the model and run a tiny `generateText` probe;
  returns `{ ok } | { ok: false, error }`. Used by the settings "verify & save" flow.
- Zod-free public surface. Deps: `ai`, `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`,
  `ollama-ai-provider-v2`. Built to `dist/` with declarations (tsc, mirroring `@bragdoc/cli`'s
  build) so the published CLI can consume compiled output; web consumes it as a workspace dep.
- Refactor `packages/cli` to import from `@bragdoc/ai` (delete its local copies).

### 2. Key storage — new `user_llm_config` table

One row per (user, provider):

- `id` uuid PK defaultRandom
- `userId` uuid notNull FK → User.id, onDelete cascade, indexed
- `provider` pgEnum('llm_provider'): openai | anthropic | google | deepseek | ollama | openai_compatible
- `encryptedApiKey` text (nullable — Ollama has no key), `iv` text — AES-256-GCM ciphertext + IV, base64
- `keyHint` varchar(8) — last 4 chars for display; never return the key itself
- `model` varchar — user's chosen model (defaults from `DEFAULT_MODELS`)
- `baseURL` varchar (nullable) — Ollama / OpenAI-compatible endpoints
- `isDefault` boolean — exactly one default per user (partial unique index)
- `lastVerifiedAt` timestamp (nullable), `createdAt`/`updatedAt`
- unique index on (userId, provider)

Migration via `db:generate` → `db:migrate`. Extend `deleteAccountData()` to hard-delete rows
(user row is anonymized, not deleted, so the FK cascade never fires).

### 3. Encryption — `apps/web/lib/crypto/llm-keys.ts`

- WebCrypto `crypto.subtle`, AES-256-GCM, random 12-byte IV per encryption.
- Key derived via HKDF-SHA256 from a new dedicated `BYOK_ENCRYPTION_KEY` secret
  (do NOT reuse `BETTER_AUTH_SECRET`; independent rotation). Add to `.env.example`,
  Cloudflare Worker secrets (staging + production), and deployment docs.
- Decryption strictly server-side inside route handlers / model resolution. The plaintext key
  must never appear in any API response, log line, or client component.

### 4. Model resolution — replace the singletons

- Delete `routerModel`, `documentWritingModel`, `extractAchievementsModel`, `chatModel`,
  `gpt4oModel` etc. from `lib/ai/index.ts` entirely (compile errors surface all ~15 importers —
  intentional; no silent env-key fallback path may remain).
- New `resolveModelForUser(user, task)` (task: 'chat' | 'extraction' | 'generation'):
  1. If `user.isDemo` (or impersonated demo session) → platform `OPENAI_API_KEY` with current
     task-model mapping (demo keeps working with zero setup).
  2. Else load the user's default `user_llm_config` row, decrypt, `createLLMFromConfig`.
  3. Else throw `NoLLMConfigError` (typed).
- Routes catch `NoLLMConfigError` → HTTP 409 JSON `{ error: 'no_llm_configured' }`.
- Thread the user through the sites that lack it: `chat/actions.ts` title generation;
  make `standup-summary.ts`/`workstreams.ts` use their already-passed user.
- `lib/llm-utils.ts`: determine liveness; delete if dead (expected), otherwise route through
  the resolver.
- `/api/cli/commits`: legacy, no CLI callers — remove the route (CLI extraction is local BYOK).
  If any old CLI version hits it, it 404s; acceptable.

### 5. Embeddings — platform key in v1 (explicit decision)

Embeddings are OpenAI-only (`text-embedding-3-small`, 1536-d, pgvector column) and power all of
Workstreams. Anthropic has no embeddings API; per-user embedding providers would mix vector
dimensions and invalidate stored vectors. Decision for v1: **embeddings stay on the platform
`OPENAI_API_KEY`** — cost is negligible (~$0.02/1M tokens; the documented workstreams cost model
is ~$2/user-year total, embeddings a small fraction of that) and Workstreams keeps working for
Anthropic/Ollama users. Revisit later (e.g. use the user's key when their provider is OpenAI).

### 6. API routes

- `GET /api/user/llm-config` — list configs, masked (provider, model, keyHint, isDefault, lastVerifiedAt).
- `PUT /api/user/llm-config` — upsert one provider config: zod-validate, run `verifyLLMConfig`
  with the raw key (reject on failure with the provider error), encrypt, store, set default.
- `DELETE /api/user/llm-config/[provider]`.
- All via `getAuthUser`, standard route conventions. Never echo the key back.

### 7. Settings UI (Account page)

- New "AI Provider" section on `app/(app)/account/page.tsx` (existing bordered-section layout):
  provider select (from `PROVIDER_OPTIONS`, with signup links), API key input (password field),
  model select/input (defaults from `DEFAULT_MODELS`), baseURL field for Ollama/OpenAI-compatible,
  "Verify & Save" button, configured-provider list showing keyHint + verified state + delete.
- shadcn Form + react-hook-form + zod (`components/projects/project-form.tsx` as template);
  new `hooks/use-llm-config.ts` SWR hook; toasts via `use-toast`.

### 8. "No key configured" UX

- Getting-started banner (`components/dashboard/getting-started-banner.tsx` + `use-getting-started`):
  add "Connect your AI provider" checklist item linking to `/account`.
- AI feature surfaces catch `no_llm_configured` (chat, generate-document dialog, standup,
  performance review, workstreams generate) → inline alert/CTA "Add your AI API key in Settings"
  instead of a generic failure toast.
- Demo mode is exempt (platform key) — demo remains the zero-setup way to try the product.

### 9. Marketing site

- `components/how-it-works/workflow-steps.tsx` — "Configure Your LLM" step covers both paths:
  web Settings key entry AND CLI `bragdoc llm set`.
- `components/get-started/path-a-steps.tsx` / `app/get-started/page.tsx` — add the settings-key
  step to the core flow.
- `lib/faq-data.ts` — add "Where do I put my API key?" answer (Settings → AI Provider; CLI
  configures its own key separately; Ollama needs no key).
- `components/cli-documentation.tsx` — note web features use the key from Settings.
- Privacy components (`privacy/llm-provider-privacy.tsx`, how-it-works privacy diagrams) —
  mention keys are encrypted at rest and only used to call your chosen provider.

### 10. Documentation

- `.claude/docs/tech/ai-integration.md` — new BYOK architecture section (resolution flow, table,
  crypto, embeddings exception).
- `database.md` (new table), `authentication.md` (no change to JWT), `deployment.md` +
  `docs/SELF_HOSTING.md` + `.env.example` (`BYOK_ENCRYPTION_KEY`; self-hosters may instead set
  env keys — document that env-var fallback applies only to demo/embeddings, or decide to allow
  a global env fallback for self-hosters via existing config).
- README: setup instructions.

## Expected Outcome

- A user with no key sees clear CTAs; adding a verified key in Settings unlocks all AI features
  using their provider/model; keys are AES-GCM encrypted at rest and never leave the server.
- Demo mode and Workstreams embeddings work unchanged on the platform key.
- CLI behavior unchanged (still local BYOK), now sharing the provider factory from `@bragdoc/ai`.
- `pnpm test` and `pnpm build` pass; no code path can reach the platform chat key for a
  non-demo user.

## Out of scope (future)

- House trial key with a small budget cap for new users (P3 — the `AppUsage` telemetry on the
  stream table is the accounting hook when we get there).
- Per-user embedding providers / vector migration.
- Multiple keys per provider, org/team keys, key rotation UI.

[edspencer]

📋 Implementation Plan

# Implementation Plan: BYOK (issue #405)

Four stacked PRs, mirroring the pivot series. Base everything on `main` **after** PRs #400–#404
merge (overlap is small but PR D touches files PR #403 edited).

## PR A — `byok/1-shared-ai-package`: `packages/ai`

1. Scaffold `packages/ai` (`@bragdoc/ai`): package.json (deps: `ai`, `@ai-sdk/openai`,
   `@ai-sdk/anthropic`, `@ai-sdk/google`, `ollama-ai-provider-v2`), tsc build to `dist/` with
   declarations (copy `@bragdoc/cli`'s build setup), `@repo/typescript-config/base.json`.
2. Move from `packages/cli/src/config/types.ts` + `src/ai/providers.ts` +
   `src/config/llm-setup.ts`: `LLMProvider`, per-provider config interfaces, `LLMConfig`,
   `DEFAULT_MODELS`, `PROVIDER_OPTIONS`, `createLLMFromConfig`, `getLLMDisplayName`,
   `isLLMConfigured`.
3. Rewrite Google path: `createGoogleGenerativeAI({ apiKey })` — remove the `process.env`
   mutation. Add `verifyLLMConfig()` (tiny `generateText` probe, short timeout, returns
   structured result).
4. Refactor `packages/cli` to import from `@bragdoc/ai`; delete duplicated code; ensure turbo
   builds `@bragdoc/ai` before `@bragdoc/cli` (workspace dep handles ordering). Fix
   `packages/cli/src/lib/extraction.ts` hard `OPENAI_API_KEY` requirement while there.
5. Verify: `pnpm build`, `pnpm test:cli`, CLI smoke (`bragdoc llm show` against a built CLI).

## PR B — `byok/2-key-storage-settings`: table, crypto, API, settings UI

1. Schema: `llmProviderEnum` + `userLLMConfig` table per SPEC §2; `db:generate` migration.
   Query helpers in `packages/database/src/llm-config/queries.ts` (get default for user, list,
   upsert, delete) — follow `standups/queries.ts` convention.
2. `apps/web/lib/crypto/llm-keys.ts`: HKDF-SHA256 from `BYOK_ENCRYPTION_KEY` → AES-256-GCM
   encrypt/decrypt via `crypto.subtle`; unit tests (round-trip, unique IVs, tamper detection).
3. Routes: `GET/PUT /api/user/llm-config`, `DELETE /api/user/llm-config/[provider]` per SPEC §6,
   with `verifyLLMConfig` on PUT. Route tests (mock `getAuthUser` per existing test pattern).
4. Settings UI: `components/account/llm-provider-settings.tsx` (+ subcomponents),
   `hooks/use-llm-config.ts` (SWR), section added to `app/(app)/account/page.tsx`.
5. `lib/account-deletion.ts`: delete `userLLMConfig` rows; update doc comment.
6. Env: `.env.example` + docs note; generate & set Worker secrets for staging/production
   (`wrangler secret put BYOK_ENCRYPTION_KEY --env …`) — coordinate with Ed at deploy time.

## PR C — `byok/3-per-user-models`: thread keys through every call site

1. `apps/web/lib/ai/resolve-model.ts`: `resolveModelForUser(user, task)` per SPEC §4
   (demo → platform key; else decrypt stored config → `createLLMFromConfig`; else throw
   `NoLLMConfigError`). Task→model mapping preserved for the platform/demo path.
2. Delete the singletons from `lib/ai/index.ts`; chase every compile error:
   - chat routes (`documents/[id]/chat`, `performance-review/chat`), generate routes
     (`documents/generate`, `performance-review/generate`)
   - `generate-document.ts`, `extract-achievements.ts`, `extract-commit-achievements.ts`,
     `standup-summary.ts` (use its `_user`), `workstreams.ts` naming, artifact handlers
     (`artifacts/text/server.ts`, `lib/artifacts/server.ts` interface), tools
     (`create-document`, `update-document`, `update-performance-review-document`)
   - `chat/actions.ts` title generation — add user param, update both callers
   - `llm-router.ts` (legacy, no live callers) — update or delete alongside evals check
3. `lib/llm-utils.ts`: confirm dead → delete (or route through resolver).
4. Remove `/api/cli/commits` route + its tests (legacy server-side extraction).
5. Embeddings: leave on platform key (SPEC §5) — add a code comment stating the decision.
6. Error UX: routes return 409 `{ error: 'no_llm_configured' }`; add `NoLLMConfiguredAlert`
   component; wire into chat, generate-document dialog, standup section, performance-review,
   workstreams zero-state. Getting-started banner checklist item.
7. Tests: resolver unit tests (demo fallback, missing-key throw), route tests updated,
   full `pnpm test` + `pnpm build`. Manual TEST_PLAN pass (below).

## PR D — `byok/4-marketing-docs`: messaging

1. Marketing per SPEC §9 (workflow-steps, get-started path, FAQ entry, CLI docs note, privacy
   components).
2. Tech docs per SPEC §10 (ai-integration.md BYOK section, database.md, deployment/self-hosting,
   README).
3. Marketing build + copy sweep for stale "server does the AI" phrasing.

## Dependencies / ordering

A → B → C → D strictly. A and B are independently mergeable and low-risk; C is the breaking
change (deploy needs `BYOK_ENCRYPTION_KEY` set BEFORE C reaches production); D is copy only.

## Test plan sketch (full TEST_PLAN.md to be written with PR C)

- No key: chat/generate/standup/perf-review/workstreams each show the settings CTA, not a crash.
- Add invalid key → verify fails with provider error; add valid OpenAI + Anthropic + Ollama
  (local) keys → each provider works for chat + document generation.
- Demo mode: full AI flows with no key configured.
- Achievement POST still generates embeddings (platform key) for a BYOK-Anthropic user;
  workstreams generate works for that user.
- Delete account → `user_llm_config` rows gone.
- Key never appears in any network response (inspect GET /api/user/llm-config), logs, or client
  bundle.

[edspencer]

📋 Test Plan

# Test Plan: BYOK — per-user LLM API keys (issue #405)

Manual test procedures for the BYOK feature, covering PR B (key storage +
settings UI) and PR C (per-user model resolution + no-key UX). Run against
a dev environment with `BYOK_ENCRYPTION_KEY` set and a user account that
has NO `user_llm_config` rows (fresh account or delete rows first).

## Prerequisites

- Dev server running (`pnpm dev:web`), logs at `apps/web/.next-dev.log`
- `BYOK_ENCRYPTION_KEY` set in `.env.local` (`openssl rand -base64 32`)
- Platform `OPENAI_API_KEY` set (demo mode + embeddings)
- A valid OpenAI API key, a valid Anthropic API key, and (optional) a
  local Ollama install (`ollama serve` + `ollama pull llama3.2`)
- Test account with ≥20 achievements (for workstreams) or use demo data

## 1. No key configured → CTA on every AI surface (no crashes)

With a non-demo account that has no LLM config:

1. **Dashboard getting-started banner**: shows a "Connect your AI
   provider" checklist item (unchecked). Clicking it navigates to
   `/account`. The banner does NOT auto-hide even if company/project/
   achievement are complete.
2. **Document generation** (Achievements → select → Generate Document):
   submitting shows the inline "Connect your AI provider" alert inside
   the dialog with an "Add your API key" button → `/account`. No generic
   red toast, no crash.
3. **Document chat** (open a report → chat panel): sending a message
   surfaces the "Connect your AI provider" toast with an "Add API key"
   action. Network tab shows `POST /api/documents/{id}/chat` → 409
   `{"error":"no_llm_configured"}` (clean JSON, not a broken stream).
4. **Performance review — generate**: the zero state "Generate Document"
   button shows the inline alert (not the generic error text).
5. **Performance review — chat**: sending a chat message shows the CTA
   toast; network tab shows 409 on `/api/performance-review/chat`.
6. **Standups**: "Regenerate" on the standup editor shows the CTA toast
   (409 from `/api/standups/{id}/achievements-summary`). Manual summary
   save (typing + save) still works WITHOUT a key — only regenerate
   requires one.
7. **Workstreams**: "Generate Workstreams" shows the CTA toast; network
   tab shows 409 on `/api/workstreams/generate` (returned before any SSE).
8. **Chat title fallback**: no 500s anywhere in `.next-dev.log`; failures
   are 409s only.

## 2. Key verification at save time (Settings → AI Provider)

On `/account`:

1. Enter an INVALID OpenAI key → "Verify & Save" fails with the provider
   error surfaced; no row is created (list unchanged).
2. Enter a VALID OpenAI key → saves; list shows OpenAI with key hint
   (last 4 chars), verified timestamp, default badge.
3. Repeat with Anthropic (valid key) → both providers listed; switching
   default works; exactly one default at a time.
4. Ollama (if available): provider Ollama, baseURL
   `http://localhost:11434/api`, model `llama3.2`, no API key required →
   verifies and saves.
5. Delete a provider config → row disappears; if it was default, another
   config is promoted to default.

## 3. AI features work with each configured provider

For each of OpenAI / Anthropic / Ollama set as default:

1. **Document chat**: open a report, ask the assistant to update the
   document → response streams, document updates via the tool.
2. **Document generation**: generate a document from achievements →
   completes and redirects to the new report.
3. **Performance review**: generate document + chat-driven update.
4. **Standup regenerate**: produces a summary.
5. **Workstreams generate**: full clustering runs; workstream names are
   generated (not the "Workstream N" fallback).
6. Getting-started "Connect your AI provider" item is now checked, and
   the banner auto-hides once all items are complete.

## 4. Demo mode works keyless

1. From an account with NO LLM config, toggle Demo Mode.
2. Run chat, document generation, performance review, standup and
   workstreams flows → all work (platform key), no CTA anywhere.
3. Getting-started item shows complete for demo (no nagging).
4. Exit demo mode → CTAs return for the real account.

## 5. Embeddings stay on the platform key

With Anthropic set as the user's default provider (no OpenAI config):

1. Create a new achievement (POST /api/achievements via UI quick-add).
2. Verify in DB that the achievement gets an `embedding` (1536-d) and
   `embeddingGeneratedAt` — i.e. embedding generation still succeeds
   despite the user having no OpenAI key.
3. Workstreams generate works end-to-end for this user (embeddings via
   platform key, naming via their Anthropic key).

## 6. Account deletion wipes keys

1. Configure ≥1 provider for a throwaway account.
2. Settings → Delete account.
3. Verify `SELECT * FROM user_llm_config WHERE user_id = '...'` returns
   zero rows (the user row itself is anonymized, not deleted, so this
   must be an explicit delete, not FK cascade).

## 7. Key material never leaves the server

1. `GET /api/user/llm-config` response contains provider, model, baseURL,
   `keyHint`, `isDefault`, `lastVerifiedAt` — NEVER `encryptedApiKey`,
   `iv`, or the raw key.
2. Search all network responses (devtools) for the raw key value → no
   hits except the original PUT request body you sent.
3. Search `.next-dev.log` for the raw key → no hits.
4. Search the client JS bundle (`view-source` / build output) for the raw
   key and for `BYOK_ENCRYPTION_KEY` → no hits.
5. DB check: `encrypted_api_key` and `iv` columns are base64 ciphertext,
   not the plaintext key.

## 8. Legacy surface removal

1. `POST /api/cli/commits` returns 404 (route removed; shipping CLI
   extracts locally and never calls it).
2. CLI flows unaffected: `bragdoc login`, `bragdoc extract` (local BYOK
   key from CLI config) still work and POST achievements successfully.

## Regression checks

- `pnpm test` and `pnpm build` pass from the repo root.
- `/prompt` playground pages still render all three prompts.
- No `OPENAI_API_KEY`-dependent code path is reachable for a non-demo
  user outside embeddings (`lib/ai/embeddings.ts`) and demo resolution
  (`lib/ai/resolve-model.ts`).

[edspencer]

AI Work Log

• 2026-07-06 23:48:42: Full BYOK stack implemented and opened as 4 stacked PRs: feat: shared @bragdoc/ai provider package (BYOK 1/4) #406 (shared @bragdoc/ai provider package), feat: encrypted per-user LLM key storage + settings UI (BYOK 2/4) #407 (encrypted key storage + settings UI, migration 0013), feat: per-user LLM model resolution — BYOK goes live (BYOK 3/4) #408 (per-user model resolution — breaking; requires BYOK_ENCRYPTION_KEY secret before deploy), docs: BYOK messaging across marketing site and docs (BYOK 4/4) #409 (marketing + docs). Merge in order 406→409, retargeting each child to main before deleting the parent branch. All CI green at time of writing.

[edspencer]

Security review (post-implementation): an adversarial review of the full stack verified key exposure, crypto soundness, authorization, and the no-platform-key-fallback guarantee all clean. Two findings were fixed in f290fcd0 on byok/2-key-storage-settings and merged up the stack:

1. SSRF guard on user-supplied baseURL — private/link-local/metadata addresses are now rejected by default (400 invalid_base_url), with BYOK_ALLOW_PRIVATE_BASEURLS=true as the self-hosting escape hatch (home-lab Ollama URLs). The 422 verification error echo is truncated to 300 chars.
2. Demo reset cleanup — user_llm_config rows for shadow demo users are now deleted in demo-data-cleanup.ts.

Deferred (low/info): unmetered verify probe (key-testing oracle), non-transactional isDefault handling (neon-http lacks transactions; self-healing), 500s after BYOK_ENCRYPTION_KEY rotation, no AAD/user binding on ciphertexts.

All CI green across #406–#409.