diff --git a/work-items/open/20260527-000022-manifest-profiles/item.md b/work-items/open/20260527-000022-manifest-profiles/item.md index a775a0cf..cc28a0e2 100644 --- a/work-items/open/20260527-000022-manifest-profiles/item.md +++ b/work-items/open/20260527-000022-manifest-profiles/item.md @@ -23,6 +23,10 @@ legacy_ticket: null This work item was migrated from an unfinished TODO.md entry that did not have a dedicated legacy ticket file. +## Related work + +- `work-items/open/20260529-145355-manifest-profile-encrypted-secrets/item.md`: profiles should integrate with explicit encrypted secret references so API keys/tokens are not limited to process environment variables. + ## Acceptance criteria - Define the concrete requirements before implementation. diff --git a/work-items/open/20260529-145355-manifest-profile-encrypted-secrets/item.md b/work-items/open/20260529-145355-manifest-profile-encrypted-secrets/item.md new file mode 100644 index 00000000..5d07fc59 --- /dev/null +++ b/work-items/open/20260529-145355-manifest-profile-encrypted-secrets/item.md @@ -0,0 +1,64 @@ +--- +id: 20260529-145355-manifest-profile-encrypted-secrets +slug: manifest-profile-encrypted-secrets +title: Encrypted secret store for manifest profiles +status: open +kind: feature +priority: P2 +labels: [manifest, profiles, secrets, security] +created_at: 2026-05-29T14:53:55Z +updated_at: 2026-05-29T14:53:55Z +assignee: null +legacy_ticket: null +--- + +## Background + +WebSearch/WebFetch made API keys more visible as a UX problem: `WebSearch` currently expects `web.search.api_key_env`, so users must export `BRAVE_SEARCH_API_KEY` before starting the Pod/TUI process. That is inconvenient for long-lived Pods, profile switching, and per-project/provider configuration. + +This should not be solved by adding `.env` loading as an implicit side effect. `.env` files are easy to leak into projects, do not solve profile-specific credential selection cleanly, and still expose secrets through process environments. Instead, when manifest profiles are designed/implemented, add a first-class encrypted secret store that manifests/profiles can reference. + +Related work item: `work-items/open/20260527-000022-manifest-profiles/item.md`. + +## Requirements + +- Design a typed secret reference format for manifest/profile fields that need credentials. + - Existing env references such as `api_key_env = "BRAVE_SEARCH_API_KEY"` should keep working. + - Add a new encrypted-store reference form, e.g. `api_key_secret = "brave.search.default"` or a more general `SecretRef` enum. + - Secret references must be explicit in resolved config; do not silently read arbitrary `.env` files. +- Add an encrypted local secret store suitable for API keys/tokens. + - Store secrets outside tracked project files by default, under the user data/config directory. + - Use authenticated encryption and atomic writes. + - Do not log plaintext secrets, include them in session logs, expose them to model context, or return them through normal tool output. + - Keep encrypted blobs out of git-managed work-items/memory/session records. +- Integrate with manifest profiles. + - Profiles should be able to select different secret names for different roles/providers, e.g. Orchestrator/Coder/Researcher or web search provider variants. + - Profile resolution should validate that referenced secrets exist or produce a clear startup/tool diagnostic. + - A profile switch must not require restarting the shell just to change API keys. +- Provide a small CLI/TUI management surface. + - Add/update/list/delete secrets without printing plaintext by default. + - Support non-interactive set from stdin for scripts. + - Show references and metadata, not secret values. + - Consider migration helpers from existing env-var based configuration, but keep migration optional. +- Update credential consumers. + - WebSearch should support encrypted secret refs in addition to env vars. + - Provider API keys/tokens and future hosted/search credentials should be able to use the same mechanism. + - Existing env-var behavior remains as a fallback/compatibility path. +- Security and UX constraints. + - Fail closed when a referenced secret is missing or cannot be decrypted. + - Diagnostics should name the missing reference, not the secret value. + - Do not add hidden context injection or history mutation for secret resolution. + - Document the threat model and limitations, including OS account access and backup implications. + +## Acceptance criteria + +- Manifest/profile schema has a typed credential reference that can point either to an env var or encrypted secret-store entry. +- Encrypted secret-store files are created outside the repository by default and use authenticated encryption with atomic update behavior. +- A user can add/list/delete a Brave Search API key in the secret store and configure `WebSearch` to use it without exporting an environment variable. +- Resolved configuration and diagnostics never display plaintext secrets. +- Missing/decryption-failed secrets produce clear fail-closed errors. +- Existing env-var based configuration continues to work. +- Documentation explains how profiles reference secrets and how to manage them. +- Focused tests cover config parsing/resolution, missing secret diagnostics, no-plaintext serialization/logging paths, and WebSearch secret resolution. +- `cargo fmt --check` +- Relevant manifest/provider/tools/pod tests pass.