feat(api): provider accounts + encrypted credential vault (#18)

[leon0399]

What

Opens v0.4 (BYOK, SPEC §14.1-§14.3) with the provider-vault core, stacked on stack/split-policy-engine (identity + config-resolver + policy engine).

• provider_accounts: owner scope (user now, org_unit enum-ready), provider_type (openai_compatible first — the rest of the SPEC §14.1 adapter vocabulary is enum-reserved so a new adapter is never an enum migration), auth_mode, base_url, default_model, models_cache (null until catalog sync feat(api): OpenRouter account and model catalog sync #84), enabled.
• credentials: AES-256-GCM envelopes under a versioned master-key ring (CREDENTIAL_MASTER_KEYS="1:<b64>,2:<b64>"). New secrets seal under the highest version; decryption selects the key by the row's key_version — rotation is append-a-version-and-re-encrypt-lazily, never a flag day. The GCM AAD binds each ciphertext to (provider_account_id, secret_type), so a payload copied onto another row fails authentication even with raw DB write access.
• SecretString (lifted from opencode's Redacted<T>): a decrypted key redacts through String()/JSON.stringify/template literals/util.inspect; only an explicit .reveal() at the model-client factory exposes the value.
• Resolution order (SPEC §14.3), wired into ModelsService.resolveModelCredential: the user's own enabled BYOK account first, then the instance env key, else a 402. The instance boots fine with no provider and no vault key ring — BYOK writes then fail closed with a clear 400.
• HTTP surface: GET/POST/DELETE /api/v1/provider-accounts — the API key is accepted write-only (@ApiHideProperty, absent from every response and from openapi.json), global auth guard, cross-tenant access 404s.

Closes #18.

Out of scope (sibling PR, stacked after this one): native OpenRouter provider, the web settings page, GET /api/v1/models real model selection, model-catalog metadata fixes, and the model-visibility allowlist — all of those build on this vault core but are carved separately.

Security & tenancy

• RLS FORCE on both provider_accounts and credentials, verified by a 9-test integration suite (providers-rls.integration.spec.ts): RLS enabled+forced check, encrypted-at-rest proof (ciphertext never contains the plaintext key), successful resolution (byok source, last_used_at stamped), cross-tenant invisibility of both tables plus a denied cross-tenant credential attach (INSERT ... VALUES (<other user's account>, ...) rejected by RLS/FK), a disabled account failing closed, a tampered/corrupted credential failing closed (added in this review pass — see below), and a vault-off instance failing closed on both write and read.
• Egress: the API key is @ApiHideProperty()-hidden from openapi.json (regenerated, checked — zero apiKey string leaks into the spec beyond the unrelated "type": "apiKey" auth-scheme literal) and absent from every response DTO (ProviderAccountResponse is an explicit allowlist with no secret-derived field); the e2e suite asserts the literal API key string never appears in any response body or body-as-text.
• Crypto: AES-256-GCM (AEAD), 12-byte random IV per encryption, AAD-bound to (provider_account_id, secret_type) so ciphertexts can't be replayed across rows, versioned key ring so rotation never bricks existing rows, and a missing/malformed CREDENTIAL_MASTER_KEYS fails closed (parseMasterKeyRing returns null → the service refuses BYOK writes with a 400, never a plaintext fallback). 17 unit tests cover roundtrip, rotation, a removed key version, tampered-ciphertext detection, and cross-account AAD-replay rejection.
• Fixed in this review pass: resolveUserCredential's own comment claimed failures "fail closed... and are logged", but the decryptCredential call had no try/catch — a CredentialCryptoError (tampered payload, or a rotated-away key version) would propagate unhandled instead of failing closed for that one account. Wrapped it so a decrypt failure now logs a warning and returns null, falling through to the instance env key exactly like a disabled account does. New integration test proves this end-to-end (confirmed the fail-closed log line fires and the suite still passes).

Review findings & refactors

• Real bug found and fixed (see Security section): unhandled CredentialCryptoError on a tampered/corrupted credential. Fixed with a scoped try/catch + a new integration test.
• Dropped a dead process.env.RUN_EXECUTION_MODE = 'inline' toggle from the e2e spec — inline execution mode doesn't exist on this base (worker mode is the only path); this carve artifact predated the master-side removal. Verified via repo-wide sweep that no other stale references, pre-reorg import paths, or leftover conflict markers exist in the slice.
• AGENTS.md: added providers/ to the module list + boundary-rule sentence (models/ consumes it via ProvidersService.resolveUserCredential), added migration 0018 to both the "don't hand-edit" exception list and the hand-authored-FORCE gotcha description.
• Migration regenerated fresh via drizzle-kit generate against this branch's actual cumulative schema (next number is 0018 on this base, not the original branch's 0021/0022) — SQL/snapshot/policies are byte-identical in shape to the original commit's migration, just renumbered; FORCE ROW LEVEL SECURITY hand-appended for both new tables per the established pattern.
• openapi.json regenerated via pnpm --filter api build, not hand-merged (+201 lines, matches the original commit's diff size).

Reference comparison

Verified directly against the cached checkouts (not just citing the original branch's research):

• opencode (packages/llm/src/route/auth.ts, packages/opencode/src/provider/auth.ts): uses Redacted<T> (Effect's redaction wrapper) pervasively across its auth/provider code — confirms the SecretString idea is a faithful port of something real and good. But auth.ts has zero encrypt/cipher/AES references — Redacted<T> is a type-level guard against accidental logging, not encryption at rest. No key rotation concept exists because there's nothing to rotate.
• open-webui (backend/open_webui/utils/valves.py, models/oauth_sessions.py, models/users.py, config.py): Fernet encryption exists, but scoped to tool "valves" config and OAuth session tokens only, both under a single static key (_fernet(), no versioning — confirmed directly, no key-version column anywhere). The actual model-provider credentials (OPENAI_API_KEYS) are an instance-wide, plaintext, semicolon-joined env list (config.py:325-329) — no per-user scoping, no encryption at all. Even open-webui's own user-facing API auth keys are a plaintext column (models/users.py, ApiKey.key = api_key, no encrypt call). Neither comp does per-user BYOK with envelope encryption or rotation; this vault is ahead of both on that specific axis, as the original commit's research claimed and I've now independently confirmed.

Spec / roadmap drift (flagged, not fixed in-slice)

ROADMAP.md's v0.4 bullet ("Provider abstraction + encrypted, scoped credential vault; model router; cost/quota tracking") is not struck out — this PR ships only the vault-core half (user-scope accounts + credentials + resolution + CRUD HTTP). Org-scope provider accounts, the model router beyond instance-env fallback, cost/quota tracking, and OpenRouter/model-selection all remain outstanding and are tracked by the stacked sibling PR and later waves. Removing the roadmap line now would be premature; left as-is intentionally.

Verification

• pnpm install — clean.
• pnpm --filter api typecheck — clean (tsgo --noEmit).
• pnpm --filter api lint — clean (oxlint, type-aware, auto-fix touched nothing).
• pnpm exec jest --maxWorkers=1 src/providers src/models — 3 suites passed (25 tests), 1 DB-gated integration suite correctly skipped without TEST_DATABASE_URL.
• RLS_TEST_PORT=55461 bash apps/api/scripts/rls-test.sh (full harness, run once, nothing concurrent) — green end to end: 7 integration suites / 60 tests (including the new tampered-credential fail-closed test — confirmed the warning log fires), queue integration 8/8, e2e 44 passed / 3 skipped (including provider-accounts.e2e-spec.ts).
• pnpm --filter api build — clean; regenerated openapi.json (+201 lines), confirmed no apiKey leak.

---

Summary by cubic

Adds per-user BYOK provider accounts and an encrypted credential vault, plus HTTP CRUD, and integrates credential resolution to prefer user BYOK over instance env keys. Secrets are sealed with AES-256-GCM under a versioned key ring and never returned by the API.

• New Features

  • New provider_accounts and credentials tables with RLS FORCE; openai_compatible supported first.
  • AES-256-GCM envelopes with AAD; versioned CREDENTIAL_MASTER_KEYS enables lazy key rotation.
  • SecretString redacts secrets in logs/JSON; only explicit reveal at the model-client factory.
  • GET|POST|DELETE /api/v1/provider-accounts; API key is write-only and hidden from openapi.json and responses.
  • ModelsService resolution: user BYOK → instance env key → 402; instance boots without a vault (BYOK writes return 400).
  • Migration 0018 adds schema and policies; .env.example documents CREDENTIAL_MASTER_KEYS; openapi.json regenerated.

• Bug Fixes

  • Decrypt errors (CredentialCryptoError) now fail closed and log a warning, falling back to the instance env key; test added.
  • Hardened vault: SecretString.equals() uses constant-time compare on SHA-256 digests (no length leaks), and API keys are trimmed before sealing to prevent whitespace auth failures.
  • Reduced write churn: debounce last_used_at updates to once per 60s per credential.

^{Written for commit 6c1e11e. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b057acd6-ae98-4dfc-a746-baaf7386352c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/split-provider-vault

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request implements the Bring Your Own Key (BYOK) provider accounts feature and an encrypted credential vault (#18). It introduces the provider_accounts and credentials tables with forced Row Level Security (RLS) to ensure strict tenant isolation. Credentials are encrypted at rest using AES-256-GCM under a versioned master-key ring (CREDENTIAL_MASTER_KEYS) and protected by a SecretString wrapper to prevent accidental exposure. The reviewer's feedback focuses on enhancing the security and robustness of this implementation. Key recommendations include hashing secrets with SHA-256 before performing a timing-safe comparison to prevent length-based timing attacks, defensively trimming whitespace during configuration parsing and API key ingestion, and debouncing lastUsedAt database updates to avoid performance bottlenecks under high load.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.