[Security] Storage of API Key

[Luke-Yong]

Idea: Encrypt API keys at rest in $DSH_HOME/.credentials.yaml

Category: Ideas
Status: Open for discussion

Summary

dsh currently persists provider API keys as plain text YAML in $DSH_HOME/.credentials.yaml (default ~/.dsh/.credentials.yaml, or a project-local .dsh-home):

DEEPSEEK_API_KEY: sk-…
OPENAI_API_KEY: sk-…

The document is protected only by filesystem permissions (0600 file under a 0700 directory) and by keeping the resolved path out of the model's context. Any process running as the same OS user — including the harness's own tool processes (bash, filesystem tools) — can read the raw secret. The dsh-credentials-local README already acknowledges this: "That is discretion, not a boundary", and defers an OS-keychain provider as the stronger answer.

Proposal: add at-rest encryption for the managed credentials document, so a key on disk is ciphertext, not the literal sk-… secret.

Why it matters

• Plain text at rest is the weakest link. File permissions stop other OS users; they do not stop same-UID processes (tool subprocesses, a compromised child process, backups, or cloud sync of $DSH_HOME).
• API keys are bearer credentials: whoever holds the string can spend tokens. An sk-… string sitting unencrypted in a user-controlled directory is one bad cat away from leakage.
• Defense in depth is standard practice for credential stores; every consumer-facing product the harness competes with encrypts secrets at rest.

Reference example: H's ARCHITECTURE.md

See ARCHITECTURE.md → Configuration for a working example of the target model:

• API key is stored on disk at ~/.h/store/api-keys.enc, AES-256-GCM encrypted.
• The encryption key is auto-generated per machine at ~/.h/.key (mode-restricted).
• The key is never persisted in browser localStorage and is never re-sent in agent request bodies.
• It survives app restarts and updates; removal is explicit via the UI or deleting ~/.h/.
• Tamper detection: an AES-GCM auth-tag mismatch on decrypt fails the read and resets the store — a corrupted or foreign file is unreadable without the machine key.

Proposal

Keep the existing credential seam (settings carry references; dsh-credentials-local owns values; consumers re-resolve per operation) and encrypt only the provider's managed store.

Option A — at-rest encryption in dsh-credentials-local (stopgap, CLI-first):

1. Generate a per-machine AES-256-GCM key on first use, stored at $DSH_HOME/.key (0600).
2. set/unset → decrypt current document (or start empty) → patch → re-encrypt → atomic write (keep the existing writer-lock and hot-reload behavior).
3. resolve/describe → read → decrypt → serve; auth-tag failure fails loud at boot and warns-and-keeps-last-good on live reload (mirrors today's parse-failure policy).
4. One-time migration: a plain-text document that parses as the legacy format is encrypted in place on first write, or via a dsh migration step.

Option B — OS-keychain provider (strongest, already named deferred work):

A sibling dsh-credentials-* package backed by the OS keychain (libsecret / Keychain / Windows Credential Manager). A keychain store is a boundary the harness's own tool processes cannot read at all — the current README explicitly calls this out as the deferred answer.

Option B is the correct end state; Option A is a cheap, cross-platform win in the meantime (protects backups, sync, and disk theft even though a same-UID process could still read the .key).

Trade-offs / open questions

• Where does the encryption key live? Adjacent .key file: simple, cross-platform, but still same-UID readable — protects at-rest copies, not same-UID processes. OS keychain: real boundary, but platform-specific and absent on headless Linux.
• Hot-reload semantics: the watcher currently re-reads, validates, and patches the parsed YAML; encryption adds a decrypt step per read and an encrypt step per write. Does comment-preservation still make sense on an encrypted store?
• Format versioning: the document currently has no version field. An encrypted store needs a format marker (and a SESSION_FORMAT_VERSION-style bump policy, though that's the session log — different mechanism here).
• Failure semantics: auth-tag mismatch = corrupted or foreign key. Fail loud vs. reset-and-warn (H resets; the current provider keeps last-good on invalid reload). Which fits dsh's "misconfiguration fails loud" rule better?
• Env layers are unaffected: env / project-env / user-env resolution and the read-only shadowing rule stay exactly as-is.

Impact

• Packages: dsh-credentials-local (encryption, key file, migration) and/or a new keychain provider package.
• Docs: credentials subsystem page, docs/user/guide/providers.md, package READMEs (security boundary section must be rewritten).
• Tests: unit tests for the encrypt/decrypt + migration paths, plus a product-visible snapshot/e2e for the Models-page store flow.

---

This is a discussion starter, not a design doc. Feedback welcome on Option A vs. B, the key-storage trade-off, and migration/failure semantics.

[denial123789]

I checked the rc.8 credential provider and agree that the current boundary should be made very explicit.

Today the managed store is plaintext YAML, with useful surrounding controls: POSIX owner-only file/directory modes, strict parsing whose diagnostics never quote secret-bearing lines, atomic locked writes, value-free describe(), write-only browser storage, references in settings, and per-operation resolution. It is deliberately not copied into process.env.

The remaining question should be split by threat:

• AES-GCM with a key in an adjacent same-UID file protects a backup/disk copy only when ciphertext and key authority are separated. It does not stop an Agent tool that can read both.
• An OS keychain can provide a stronger storage/broker boundary, but only if arbitrary same-UID tool commands cannot invoke the same authorized retrieval path.
• A compromised Harness process can observe a key after resolution regardless of at-rest storage.
• A separate low-privilege OS account/container/VM with a short-lived, capped credential is the strongest current control against an untrusted Agent reading a normal user's secrets.

I would keep the seam and implement a sibling provider. The provider contract should include value-free descriptions, per-operation resolution, non-interactive/headless behavior, fail-closed authentication errors, migration without argv/plaintext temp files, explicit secret-memory lifetime, and reference-only audit events.

For an encrypted-file migration, an auth-tag mismatch should preserve ciphertext and fail closed rather than silently reset the store. A safe migration also has to preserve source precedence: an inherited environment value may still shadow the migrated record until restart.

I published a source-backed threat matrix, current operating patterns, migration contract, incident response, and fifteen acceptance gates here:
https://sandbaseai.github.io/deepseek-harness-handbook/api-key-storage.html

[ylwl1997]

Support encrypting $DSH_HOME/.credentials.yaml at rest.

Owner-only file modes help on a personal laptop, but they don’t cover shared machines, backups, sync folders, or accidental curl/cat in support threads. Even OS keychain / DPAPI / libsecret wrapped keys with a clear threat model in the docs would be a big step up from plaintext YAML.

Also worth documenting explicitly: what is encrypted vs what remains in process memory / logs after load.