Secret Management
This page describes the intended design recorded in ADR#0023 (accepted) and ADR#0030 and ADR#0033 (both draft). The standalone secrets-service topology is a target, not a claim of deployed behavior. ADR#0023 records that the write model was validated by a credential prototype embedded in the gateway, with its own secret-store adapter, and requires extracting its mechanics into the secrets service. Accepted ADR#0074 draws the boundary of that extraction, which remains unfinished. That prototype does not establish standalone-service readiness.
Provider Credential Custody explains the reference-only boundary for provider configuration. The proposed Supplied Credential Material contract keeps secret-bearing inputs separate from persisted metadata.
Third-Party Connections explains the connection HTTP proxy boundary proposed in draft ADR#0096: ordinary provider requests stay HTTP, the trusted proxy injects credentials, and custody handles OAuth exchange and refresh. Protobuf contracts describe lifecycle, authorization and bindings. The relay contract now defines that binding, proof and failure profile; runtime extraction and enforcement still require implementation.
Scope
This page covers only SecretStore, the port that stores and resolves retrievable credentials: provider OAuth tokens, webhook signing secrets, bot tokens, and API credentials (ADR#0023 Decision 2). Cryptographic operations, key custody tiers, and key states belong to the KeyManagement port, covered by Key Management, Key States, and Key Custody. The two ports are typed separately so that business code never sees a generic provider interface, and neither port's caller ever holds an OpenBao artifact (ADR#0023 Decision 2).
Concepts
SecretRef
A SecretRef is an opaque handle a caller holds in place of a credential. The secrets service resolves it internally to a tenant, a vault, and a key; it is never an OpenBao path, and a caller cannot parse or construct one (ADR#0023 Decision 2). The accepted baseline leaves encoding unspecified. The connector draft selects a custody-minted random handle; see draft resolutions.
Vault
A vault is a user-visible logical grouping of secrets within a company. It is enforced by policy, not by cryptographic separation: two vaults in the same company are a console-visible organizing boundary, not two OpenBao security boundaries (ADR#0023 Decision 5). The connector milestone uses a policy grouping, with no independent lifecycle aggregate. A future vault resource requires a separate contract; see draft resolutions.
Connection
A connection is the external system a credential authenticates against: a source host, an issue tracker, a chat workspace, an observability backend. It is the structural half of a pair whose other half is the material, and it is the half that holds still under rotation. Replacing the bytes behind a credential does not make it a different connection.
No general connection resource exists in this platform yet. ADR#0032 defines a ModelProviderConnection for one provider class, and draft ADR#0063 Decision 5 defers the form for every other class to its own record. So a ConnectionDeclaration names a provider and label predicates that admission is meant to resolve against a catalog the security plane owns, and that catalog is not described anywhere on this page because it is not decided. Recording the gap is the point: until the resource exists, a declaration is a reviewable statement of intent rather than a resolution path.
Fingerprints and reason enums
Events and snapshots in the write model below carry references, fingerprints, and reason enums, never values (ADR#0023 Decision 4). A fingerprint lets the aggregate and the recovery worker compare whether this is the same credential material as before, without holding or re-deriving the material itself. A reason field records why a state changed (for example, a rotation trigger versus an operator-initiated revocation) without carrying the credential value. ADR#0023 calls these reason enums; whether the implementation fixes a closed set of typed values or a bounded non-secret string is an open decision (see Open decisions).
The write model
The write model has three parts, which ADR#0023 Decision 4 records as validated end to end by the gateway-embedded prototype:
- The credential aggregate. An event-sourced aggregate on JetStream. Its events and snapshots carry refs, fingerprints, and reason enums, and never the secret value itself.
- The write saga. Storing a credential proceeds as a pending event, an OpenBao write, and an activation recorded with metadata only. The value is written to OpenBao inside that saga; the platform's own event log never receives it.
- The recovery worker. It reconciles an aggregate stuck between the pending event and activation by reading OpenBao metadata, never a value, to determine whether the write actually landed.
There is no distributed transaction between the platform's state and OpenBao. The saga and the recovery worker are the entire consistency mechanism; a stuck write is a recoverable state, not a two-phase-commit failure (ADR#0023 Decision 4).
ADR#0023 attributes this shape to a prototype that already built it end to end, and it calls extracting that prototype, not rebuilding it, the work adopting this ADR requires. The prototype's internal type and event names, its exact operation surface, and the recovery worker's precise reconciliation algorithm are not published in the ADR and are not restated here beyond what Decision 4 fixes.
Credential states
The write path fixes two states. Pending runs from the moment the saga's pending event is recorded until the OpenBao write and activation complete; active follows once activation is recorded with metadata only and the credential is resolvable. The recovery worker reconciles an aggregate stuck between those two. Richer lifecycle states (an explicit write-failure state, rotation in progress, revocation) are not enumerated by ADR#0023; the complete credential state machine is an open decision (see Open decisions).
A separate axis, which version of the credential material is current and whether an older version has been removed, is not tracked as platform state in parallel with OpenBao. It derives from OpenBao KV v2 mechanics instead (ADR#0023 Decision 4): the key-level current_version pointer identifies the version resolution serves, and the per-version destroyed and deletion_time fields report whether that version, or an earlier one, has been removed. The KV v2 version counter is the credential's version number; rotation advances current_version rather than the platform maintaining a second counter.
ADR#0023 does not enumerate a complete credential lifecycle state machine beyond what Decision 4 fixes here. The five explicit states in Decision 6 (active, decrypt-only, disabled, pending destruction, destroyed) belong to KeyManagement's KeyRef, not to SecretStore's credential aggregate, and should not be read across.
Resolution
A caller resolves a SecretRef over NATS core request/reply, authenticated by the tenant-scoped NATS user JWTs a2a-auth-callout already mints (ADR#0023 Decision 3). Tenant identity is always derived server-side from the authenticated connection, never from a field the caller supplies; the NATS account, which is the tenant unit, scopes who can even address a company's resolve subjects.
Values never traverse JetStream, a log, or a trace. JetStream carries only the metadata that surrounds a credential: rotation, revocation, cache-invalidation, and audit-correlation events, never the value itself (ADR#0023 Decision 3).
Who may resolve a ref
Resolution above answers how a caller that already holds a SecretRef exchanges it for a value, and how tenant scoping bounds which company's refs that caller can address. It does not answer how a caller comes to hold a ref in the first place. That question has three parts, and this page owns only one of them.
- The store. Everything above: what material exists, what state it is in, and how a holder resolves it. Fixed by ADR#0023 and, for the credential aggregate's events and exposure rule, by ADR#0047 and ADR#0048.
- The declaration. What an Agent revision says it needs. Draft ADR#0063 puts a
ConnectionDeclarationonAgentDependenciesthat names a provider and label predicates and carries no credential, no ref, and no version. It grants nothing; it is a reviewable statement that this behavior reaches that system. - The grant. What turns a declared requirement plus a live authorization decision into a usable connection for the duration of one execution. For model providers, draft ADR#0032 defines this as an attempt-scoped
ModelAccessGrant. For tool and channel connections it is undecided (see Open decisions).
The agent runtime is not the caller in any of these cases. Draft ADR#0032 Decision 4 fixes that for the model path: the native implementation "never receives the token, confirmation key, renewal authority, upstream credential, or permission to resolve a SecretRef", because a platform-controlled supervisor holds the grant and exposes only a session-scoped endpoint.
The provider agent contracts research corpus found the same boundary reached independently by four external implementations outside this repository, which is worth recording because it means the shape is not a local preference. In all four the agent holds an opaque placeholder and the real value is substituted into the outbound request at network egress, and in all four the substitution both sets the authenticated form and removes the placeholder rather than leaving both present. Whether this platform's tool and channel egress point works that way is part of the undecided grant above, not something ADR#0023 fixes.
The same words mean different things elsewhere
Five layers sit between stored material and a usable connection, and this page owns only the first. Naming them in order is what keeps the rest legible:
- Vault. A policy-enforced grouping of stored material within a company.
- Credential. The material itself plus its state, addressed by a
SecretRef. - Connection. The external system that material authenticates against.
- Declaration. What an Agent revision says it reaches. Grants nothing.
- Grant. What turns a declaration plus a live authorization decision into something usable for one execution.
The research corpus uses some of the same words for different layers, so a reader comparing the two needs the mapping rather than the vocabulary:
| Layer | Anthropic Managed Agents | OpenAI Agents API | OpenComputer | xAI |
|---|---|---|---|---|
| Vault | vault (vlt_...) | vault | SecretStore | none |
| Credential | vault_credential (vcrd_...) | vault.credential | a name passed to useSecret() | passed inline on every request |
| Connection | not separable, a credential is bound to one mcp_server_url | not separable, a credential matches a server URL | defineConnection, fused with the credential | none |
| Declaration | none | none | defineConnection in source, published as requiredConnections | none |
| Grant | none | none | none, egress substitution stands in for one | none |
| Attachment point | vault_ids[] fixed at session creation | vault_ids[] at session creation | secretStore at sandbox creation | none |
Two collisions in that table are worth stating outright, because both have already produced a wrong reading of the corpus.
The first is the word vault. Ours is a console-visible organizing boundary and nothing more: two vaults in the same company are a policy grouping, not two OpenBao security boundaries (ADR#0023 Decision 5). Anthropic's and OpenAI's vault is that plus an attachment point. vault_ids[] is fixed on the session at creation, which makes their vault the unit of session-scoped reach. Ours carries no such meaning, and nothing in this platform attaches a vault to a session today.
The second is the word connector, which is not another name for a vault id. In the OpenAI Responses API a connector_id points at a provider-held stored connection, one layer below a vault. The Agents API has no such field: its per-tool selector is credential_id, documented as "The vault credential selected for this MCP server", so it selects material and not a connection. xAI's OpenAPI schema carries connector_id and the documentation states that it and require_approval "are not currently supported", so the only other appearance of the word in the corpus is a rejection. A connector in the sense either vendor uses it is the resource our Connection concept says we do not have.
Caching
Caches are bounded, with event-driven invalidation from rotation and revocation events as the primary mechanism and a TTL backstop as the maximum stale window after a missed event; that TTL is bounded in minutes, not hours. Invalidation is fan-out, not queue-group work-sharing: resolve traffic load-balances across the queue group, but every replica that holds a resolved value, each secrets-service replica and each gateway replica holding a value as bounded ambient state, must observe rotation and revocation through its own JetStream consumer, because queue-group delivery would evict one replica's cache and leave the others serving a stale or revoked credential. A consumer may hold a resolved value as bounded ambient state under that TTL behind fan-out invalidation, which is how ADR#0074 Q2 amends ADR#0023 Decision 6.
Whether a resolved secret value is held in a single-owner, zeroizing wrapper analogous to KeyManagement's Dek wrapper, and exactly what that wrapper requires, is not fixed by ADR#0023 and is an open decision.
Failure handling
The service fails closed: a secret that cannot be resolved is an operation that does not happen, and there is no plaintext fallback (ADR#0023 Decision 6). This extends to the service's own bootstrap: an instance that cannot authenticate to OpenBao, at startup or when renewal lapses, does not report ready, does not join the resolve queue group, and retries with backoff rather than serving in a degraded mode (ADR#0023 Decision 3).
Whether resolve failures map to a stable, caller-visible taxonomy analogous to KeyManagement's eight wrap_dek and unwrap_dek categories is not fixed by ADR#0023, so this taxonomy is an open decision rather than a restatement of an existing model.
ADR#0023 commits to dual audit: a business-context record (caller, tenant, vault, ref, purpose, outcome) with a correlation ID threaded into the OpenBao request, so the provider's own audit log can join back to who asked and why once adoption proves the identifier reaches that log (ADR#0023 Decision 6). What the service does when an audit sink itself fails to accept a record is not fixed; ADR#0023 lists correct behavior when audit sinks fail among the proofs required before adoption, which means this behavior must be answered before adoption, not assumed.
What the service never does
- Let a secret value cross into JetStream, a log, or a trace.
- Accept a caller-supplied OpenBao path, or any other provider artifact, as a
SecretRefor anywhere else across the port boundary. - Hold a standing, broad OpenBao token; it mints short-lived, narrowly scoped credentials per request instead (ADR#0023 Decision 3).
- Serve a cached value past its bounded window as a plaintext fallback when an invalidation event is missed.
Accepted baseline and connector draft resolutions
The source ADRs retain their recorded statuses. Draft ADR0095 and the connector security profile supply concrete connector decisions without claiming their implementation or accepting the drafts by implication.
| Concern | Connector draft resolution |
|---|---|
| SecretRef identity | Custody mints 32 random bytes as 43-character unpadded base64url; opaque, nonauthorizing and unrelated to an OpenBao path |
| Reason typing | Closed protobuf reason/result enums at domain boundaries; raw provider text never controls classification |
| Credential lifecycle | Explicit live/staged, refresh, unusable, revoke and destroy states and recovery in ADR0095 and secrets/credentials |
| Vault | Tenant policy grouping for this milestone, with no separate cryptographic boundary or independent lifecycle aggregate |
| Resolved values | Direct caller-sealed replies; bounded memory lifetime, zeroizing wrappers, no Debug/serialization/logging or persistent RPC result |
| Resolve errors | Typed denial, unusable, stale/superseded, unavailable and key-veto outcomes; no credential or provider body in error detail |
| Audit outage | Durable acceptance before credential use; body-free durable completion outbox; outage/backlog limits refuse new work |
| Non-model grants/egress | Attempt-scoped grants and explicit authenticated HTTP relay under ADR0096; provider traffic remains HTTP |
| Anomalies | Typed replay, scope widening, unauthorized custody caller, key/restore mismatch, stale projection and cleanup-debt signals with fail-closed response and bounded metrics |
The detailed lookup material is resource parents, account identity, relay recovery, and HTTP transport. Deployment still has to demonstrate these boundaries, not merely generate types.
