The vault — one mechanism, bound to an owner
Read docs/secrets.md. The module docstrings in app/core/vault.py and
app/core/secret_kinds.py carry the reasoning.
The rule
Every provider key, channel bot token, MCP credential and third-party API key seals
through app/core/vault.py. There is no second mechanism, and adding one is the
mistake this design exists to prevent.
CHANNEL_ENCRYPTION_KEY and the deployment-wide Fernet keys are gone, removed
before the migration chain was squashed into 0001_baseline. If you see them
referenced anywhere — code, docs, a skill, an .env example
— that reference is stale. Three mechanisms used to hold secrets and only one bound a
ciphertext to its owner; a Slack token could be copied from one organization's row
into another's and it decrypted.
Envelope, and what it buys
Each secret is sealed with its own random data key. That data key is sealed with a key derived from the master key and the scope that owns the secret.
- A ciphertext cannot move between owners. A row copied from org A into org B
fails to unwrap. Tenant isolation here is cryptographic, not a
WHEREclause somebody might forget. - The master key is rotatable. It never encrypts payloads, only data keys, so
rotation re-wraps one small blob per secret.
key_versionrecords which master key sealed an envelope — that column is what makes a staged rotation possible.
Scope is an organization, or the member for a personal MCP connection (which has no organization, and whose owner may belong to several).
VAULT_MASTER_KEY, falling back to SECRET_KEY so a fresh checkout runs. An
environment validator refuses the default SECRET_KEY outside development.
Kinds
A secret is not always a string, and the kind decides which fields exist:
none, api_key, azure_openai, aws_credentials, gcp_service_account.
StorableSecret is what a person can save; SecretValue adds none, which the
runtime can hold but nobody can store. That difference keeps "a secret with no value"
out of the API schema. The vault refuses to seal an empty value.
Adding a kind means: a new model in secret_kinds.py, a branch in
model_resolver._build_provider if a provider needs it, a Builder form field, and a
migration only if a stored shape changes. Validate on the way in — the failure mode of
a malformed service account is an auth error hours later with nothing pointing back at
the paste that caused it.
Four things that must stay true
- No API response returns a plaintext. There is no endpoint for it.
Plaintext leaves the vault only through the few
OrganizationSecretServicereaders its module docstring lists -resolve_for_bindingsfor the runner, and narrow ones that hand one value straight to a provider (listing_key,transcription_key,oauth_app). None returns it to a caller who could keep it. Do not add another without that shape. - No log line or audit entry contains one. Every secret-bearing field is a
SecretStr, which is what makes the carrying dataclasses mask themselves in a repr — the usual way a key escapes. - No spec carries one. A binding stores
secret_id; specs are exported to clients' git repositories. - A capability never learns where its credential came from, and the model never sees it.
tests/api/test_no_secret_escapes.py pins these. If it fails, the leak is real.
Declaring a need, not an instance
A capability declares a SecretRequirement — a kind. Code says "I need an API key";
a binding's secret_id says which one. needs_secret(config) is consulted by publish
validation and by the build, so the two cannot disagree.
A secret deleted after publish makes the run refuse, not degrade: a capability whose whole job is calling an authenticated API does not do half of it, and a run that quietly dropped the call would answer as if the API had said no.
Access
secrets:view / secrets:edit (resource permissions, so they carry a scope),
mcp:manage, connections:manage. A secret can be shared to one member or agent with
a grant. See the permissions-rbac skill.
Test
Cross-tenant unwrap must fail. That is an integration test — a mock cannot tell you the binding holds.
