Repository Public
1# Managed secrets (SP Vault Connect / Agents) — separate threat model23**This subsystem is not zero-knowledge.** To call an API or sign a payload on behalf of a workload while the4owner is away, the server must be able to use the secret. Everything here is therefore weaker than the personal5vault and is kept apart from it: different process, different table, different key, different UI section, and a6banner that says so.78## What it is for910API tokens, webhook signing keys and deployment credentials used by CI jobs, services and AI agents — secrets11that would otherwise sit in `.env` files and agent prompts. Not for personal passwords.1213## Design1415* `services/managed-secrets` runs as its own process bound to `127.0.0.1`. It alone holds the master key file16 (0600, never in the database, never in backups of the database, never in the manifest). Values are stored as17 AES-256-GCM ciphertext under `HKDF(master, account_id)` with the secret id, account and version as AAD.18* The API process authenticates to it with a token file and never stores values. It holds identities, grants,19 approvals, leases and the audit log.20* **Brokered operation first**: `operate` grants let a workload ask for an HTTPS call or an HMAC signature. The21 credential is injected inside the managed process; the workload receives the upstream response, with any echo22 of the credential removed. Upstream hosts are an explicit allow-list per secret; plain HTTP, redirects, private23 and loopback addresses are refused.24* **Raw delivery is the exception**: `read` grants return the value, always after a human approval for that25 single delivery. The product states that the recipient can then disclose it and that revocation cannot undo it.26* **Workload identity**: each identity has a P-256 key; every request is signed over method, path, timestamp,27 nonce and body hash (replay-protected). No bearer token exists to leak in logs.28* **Agents** can never be granted unattended access: `approval` is `lease` (a human opens a short window) or29 `each`. Approvals are bound to the exact operation displayed (method, URL, body hash) and are single-use.30* **Kill switch**: one action suspends every identity of the account and ends all leases; releasing it does not31 restore leases.32* **Prompt injection**: the approval screen is built from structured request fields. Text supplied by the agent33 is truncated, stripped of control and bidirectional characters, and displayed in a box labelled untrusted.34 Upstream responses are returned to the agent as data and are never interpreted by SP Vault.3536## Who can read a managed secret3738| Actor | Can read? |39|---|---|40| Operator / root on the node, or anyone who steals the master key file **and** the database | **Yes** |41| Database or database-backup thief without the key file | No |42| API process compromise | Can ask the managed process to use or reveal secrets (it is the policy enforcement point) |43| Workload with an `operate` grant | No (can use it within policy) |44| Workload with a `read` grant after approval | Yes — by design |45| Another account | No (tenant id is part of the key derivation and of every query) |4647## Residual risks4849A malicious allow-listed upstream can observe the credential (it is its own credential). DNS rebinding between50the address check and the connection is not fully closed. A compromised agent can misuse an open lease within51the grant's constraints until it expires or the kill switch is used: keep leases short and constraints narrow.52