Assistant/architecture/adrs/ADR-0010-credential-ref-secret-resolution.md

ADR-0010 - CredentialRef Secret Resolution

Status: Accepted Date: 2026-08-17 Accepted under: DEV-000061 rev.2 Creator scope decision

Decision

Long-lived runtime credentials are represented in canonical configuration as typed CredentialRef metadata, never as plaintext secret values. A trusted runtime resolves a CredentialRef through a provider-neutral Secret Resolver into a secret value stored in a protected Secret Backend.

The V1 backend is the existing protected local secret storage exposed to trusted runtimes as files under an explicitly configured root such as /run/secrets. This is bootstrap delivery, not canonical live configuration. The resolver is technical platform infrastructure and owns no domain meaning, provider state, model state, authority, or Interaction semantics.

Docker environment variables may carry minimal bootstrap references, such as a credential reference id or an allowed secret file path, but Docker environment is not the long-term canonical configuration store for Domovoy. Operational concepts such as provider endpoints, model bindings, routing configuration, health, project settings, capability configuration, and runtime policy must remain movable toward canonical registries without redeploy.

Boundaries

• Plaintext secrets, API keys, tokens and passwords remain forbidden in source, task packets, logs, tests and ordinary environment configuration.
• Secret-file references are allowed only through typed resolver policy and fail closed outside the protected backend root.
• Canonical owners store CredentialRef metadata and policy only; the secret value stays in the Secret Backend.
• The resolver is not Interaction-specific and must be reusable by other trusted runtime consumers.
• Cognitive models receive no plaintext secret unless a future explicitly authorized operation requires it.

Consequences

DEV-000061 may connect interaction_role by creating a CredentialRef and resolving it from the protected V1 local backend. This adds a minimal platform/secrets mechanism and typed contracts/secrets contract without introducing Vault, Kubernetes secrets, HSM, distributed replication, secret management UI, automatic rotation, PKI, or cluster scheduling.