Prism-Vault
Prism-Vault is a Prism-first shared config, secret, and credential-resolution
service. It gives Prism agents and Prism backend surfaces one stable contract
for runtime configuration and secret access across local, lan, and render
deployments.
Prism-Vault is in design. SPEC-122 v0.1 is draft; no implementation code has
landed yet. This page describes the agreed v0.1 shape. As each implementation
phase lands, the operator, build/deploy, and API pages described in the
Documentation Contract are
created alongside the code — not before it. Why it exists
Prism’s three deployment modes each pass credentials and config differently:
local leans on .env and dev-service defaults, lan needs durable non-root
secret handling on a private network, and render uses platform env/secret
bindings. Agents need scoped runtime values without broad secret-store
credentials, and operators need masked metadata, audit evidence, and repairable
config state. Prism-Vault makes that boundary explicit and uniform.
The Datris HashiCorp Vault implementation (datris-platform-oss, reviewed
2026-05-14) is prior art — its compact KV v2 wrapper, self-describing secret
records, masked metadata, and
runtime env injection are ergonomic lessons Prism-Vault keeps. Prism-Vault
hardens that model for production: no fail-open tenant fallback, no root-token
provider access, no broad provider reads from application code.
Subproject boundary
Prism-Vault starts as a separable subproject inside the Prism umbrella — not
a separate repository in v0.1 — but it behaves like an independent service from
the first commit:
- Own separable subproject path with repo-separation-ready boundaries.
- Own version string and changelog.
- Own build artifact / image and deploy config for local, LAN, and Render.
- Own contract tests.
- No hard dependency on Prism monolith internals; Prism integrates through the
Prism-Vault API, not direct table or provider access.
This keeps future extraction boring: move the subproject into its own repo or
deploy unit later, preserve the API.
Architecture
Prism-Vault is a broker with three internal surfaces — Secret Store, Config
Store, and Credential Resolver — all passing through one identity, scope,
policy, and audit gate. Callers never talk directly to Vault, Render env
bindings, or any future provider; the provider adapter sits behind the gate.
Source diagrams live in docs/diagrams/prism-vault/:
shared-service-architecture.mmd — the broker / adapter topology above.secret-resolution-sequence.mmd — runtime resolution call flow.deployment-modes.mmd — local / LAN / Render provider binding.scope-data-model.mmd — the scope tuple and durable record model.
Scope model
Authorization uses stable IDs; human-readable slugs are accepted as lookup input
only. The canonical scope tuple is:
tenant_id / project_id / environment / service / record_name
environment names are deployment/runtime scopes, not Git branches. The
required initial values are local, lan, and render; anything else
(staging, preview, customer-prod) needs explicit registration and policy.
API contract
v0.1 follows the normal Prism capability shape — no standalone SDK:
backend service -> /vault HTTP router -> thin mcp-node prism_vault_* verb shims
mcp-node verbs are the thin
client agents use. The logical verb surface:
| Surface | Verbs |
|---|
| Secret metadata | prism_vault_secret_put, prism_vault_secret_get_metadata, prism_vault_secret_list, prism_vault_secret_delete, prism_vault_secret_rotate |
| Runtime resolution | prism_vault_secret_resolve |
| Config | prism_vault_config_put, prism_vault_config_get, prism_vault_config_list, prism_vault_config_promote |
get_metadata and list never return raw secret values. Resolution is the
only v0.1 path that returns secret values — it requires a purpose, is
allowed only for runtime identities (registered Prism agent or backend service),
and returns a short-lived env payload with a TTL and an audit_id.
Authorization and audit
Authorization is enforced in the backend, not advisory. Every request resolves
caller_identity, caller_kind (human / agent / service), tenant_id,
project_id, environment, and purpose. The default rule is default-deny:
a caller can only operate inside its own tenant and project unless an explicit
policy grants the caller and purpose. If Prism-Vault is uncertain, it fails
closed and writes a denied audit event.
Every value resolution writes an audit event before returning the value.
Audit writes are atomic with authorization — if audit cannot be written, the
operation fails closed. Audit never stores raw secret values, only a value hash.
Rollout order
Prism-Vault is Prism-first. Janus and DPA-Crawl/WebCrawl inform the design
but are explicitly deferred — they integrate only after Prism local, lan,
and render paths pass the same contract tests.
| Phase | Scope |
|---|
| Phase 0 | Service boundary, provider adapter interface, contract tests |
| Phase 1 | Prism local provider (Vault KV v2 dev mode) |
| Phase 2 | Prism LAN provider (real Vault, app token, scoped policy) |
| Phase 3 | Prism Render provider (env/secret bindings, deploy smoke) |
| Phase 4 | Prism operations (operator UI/API, rotation hooks, export/import) |
| Phase 5 | Janus / DPA-Crawl collaboration (worker caller kind, job-scoped policy) |
Ownership
| Role | Owner |
|---|
| Architecture | Texi |
| First consumer | Prism |
| Prism backend integration | Donna |
| Install / deploy | Lafonda |
| Governance / security review | Candi |
| Viewer / review coordination | Carla |
| Documentation | Desiree |
See also
Last modified on May 16, 2026
