User Credentials

User Credentials

Edge adaptation of the upstream reference-based credential management system.

Upstream reference: User Credentials

What Upstream Provides

The credentials system separates secrets from configuration. Settings and cordis.yml store references (environment variable names), while actual values reside with CredentialProvider implementations. Key design choices: empty stored values are treated as nonexistent, credentials are resolved per-operation (no caching) for immediate hot-reload, and shadowing writes are rejected to prevent silent misconfiguration.

What Edge Changed

Direct Reuse Credential service

The upstream credential service (ctx.credentials) is used as-is. Reference resolution, shadow detection, change events (credentials/reference-updated), and credential RPC (describe/set/unset) are all upstream code.

Replacement Credential provider → DO KV + Worker env

EdgeCredentialProvider extends the upstream CredentialProvider abstract class with a two-tier resolution strategy:

• Tier 1: DO KV storage — runtime-writable credentials at dsh-edge:credential:{ref}. Supports set() and unset() from the settings UI.
• Tier 2: Worker environment variables — read-only fallback. DEEPSEEK_API_KEY is pre-registered as a known reference. Writes to env-backed refs are rejected (shadow prevention).

Resolution is per-call with no caching, matching upstream's hot-reload contract.

What Edge Did NOT Change

• Reference-based architecture (references in settings, values in provider)
• Per-operation resolution (no caching across calls)
• Shadow write prevention
• Empty-value-as-nonexistent rule
• Credential RPC (describe/set/unset) — handled by apiproxy
• Security invariant: credential values never appear in session events, logs, or API responses

Performance Characteristics

Credential resolution

Each LLM request resolves credentials via resolve(ref). Tier 1 (DO KV) is a single storage.get(); tier 2 (env var) is a synchronous property access. Both are sub-millisecond. Per-call resolution means rotated credentials take effect on the next request without restart.

Credential storage

Each set() is a single storage.put() with a small string value. Credentials are stored as plain text in DO KV — the Durable Object itself is the security boundary (access-key authenticated, single-tenant). This matches the upstream model where local credential files are protected by OS file permissions.

Architecture Summary

Component	Category	Edge Code
Credential service	Reuse	Upstream — reference resolution, shadow detection, events
EdgeCredentialProvider	Replace	~50 lines — DO KV + Worker env two-tier resolution

Key observation: The credential provider is a minimal replacement with a two-tier design unique to Edge. Tier 1 (DO KV) enables runtime credential management from the browser UI. Tier 2 (Worker env) provides the deployment-time API key without requiring UI setup. Per-call resolution ensures both tiers participate in every request.