​

SPEC-122 v0.2 - Prism-Vault Shared Config and Secrets Service

​

Summary

​

v0.2 Ratification Amendment - 2026-05-18

• backend/app/schemas/vault.py
• backend/app/services/vault_service.py
• backend/app/routers/vault.py
• backend/tests/test_vault_router.py
• Prism-Vault docs, diagrams, and Plan #28 surfaces

• durable prism_vault_* SQL tables,
• persistent append-only audit,
• real Vault KV v2 provider behavior,
• Render provider behavior,
• production secret ownership migration,
• full secret/config CRUD,
• MCP-side prism_vault_* verb parity,
• operator UI,
• rotation/revocation automation.

• Alembic migration and model for append-only Vault audit events.
• Service audit sink that writes an attempt/reservation before any provider read.
• Success, denied, and failure finalization before any raw value returns.
• Fail-closed prism_vault_audit_unavailable behavior when audit cannot be written.
• Provider-neutral tests for success, denied, missing, and audit-unavailable paths.

• prism_vault_secret_get_metadata
• prism_vault_secret_resolve
• prism_vault_config_get

• non-root app token,
• scoped Vault policy,
• readiness/policy probe,
• provider selection that keeps caller APIs provider-neutral,
• same contract tests against the LAN provider.

​

Diagrams

• Architecture: docs/diagrams/prism-vault/shared-service-architecture.mmd
• Runtime resolution: docs/diagrams/prism-vault/secret-resolution-sequence.mmd
• Deployment modes: docs/diagrams/prism-vault/deployment-modes.mmd
• Scope data model: docs/diagrams/prism-vault/scope-data-model.mmd

​

Problem

1. Local mode often uses .env and dev-service defaults.
2. LAN mode needs durable, non-root secret handling with private-network access.
3. Render production uses platform env/secret bindings and may need an external provider for per-project runtime secrets.
4. Agents need scoped runtime values without broad secret-store credentials.
5. Operators need masked metadata, audit evidence, and repairable config state.

​

Goals

• Deliver Prism-scoped secret/config management first.
• Support Prism agents and backend services as first-class runtime consumers.
• Support local, LAN, and Render deployments behind one Prism-Vault contract.
• Keep the provider-adapter design so Vault, Render, or a future managed provider can back the same API.
• Enforce tenant/project/environment/service scope in the backend.
• Return masked metadata on admin/read paths and reserve raw secret values for runtime resolution only.
• Capture audit rows sufficient to answer who resolved what, for which Prism project, purpose, and run/job/session.
• Establish subproject-first Prism-Vault version/build/deploy boundaries from day one, even while it lives under the Prism umbrella.
• Defer Janus/DPA-Crawl/WebCrawl integration until the Prism path is stable.

​

Non-Goals

• Making DPA-Crawl/WebCrawl the first consumer.
• Replacing Prism’s existing human auth system. Prism-Vault consumes authoritative caller identity; it does not become the IdP.
• Cross-tenant secret sharing in v0.1.
• Direct per-agent or per-worker Vault tokens in v0.1. Runtime consumers receive resolved env payloads, not provider credentials.
• Building a full human-facing admin console in this spec. Console screens can consume the API but are separate implementation work.
• Provider-specific rotation automation for every possible secret kind. v0.1 defines monthly and manual-on-demand rotation policy plus hooks/audit; individual automated rotators land incrementally.

​

Architecture Decision

1. Secret Store Surface - CRUD and metadata for secret records.
2. Config Store Surface - versioned non-secret Prism runtime config.
3. Credential Resolver Surface - runtime-only resolution for Prism agents, backend services, and later worker integrations.

​

Subproject Boundary

• Own separable subproject path, with repo-separation-ready boundaries.
• Own version string and changelog.
• Own build artifact or image.
• Own deploy config for local, LAN, and Render.
• Own contract tests.
• No hard dependency on Prism monolith internals for provider adapters.
• Prism integration goes through the Prism-Vault API, not direct table/provider access.

​

Phase 0 Boundary Concretization

• Code root / package boundary: Prism-Vault runtime code lands under the existing Prism repo at backend/app/{routers,schemas,services}/vault.py. Phase 0C adds mcp-node/src/verbs/vault.ts as the Prism-hosted agent surface. The extraction-ready subproject anchor remains prism-vault/, which holds the independent version line and README contract for later peel-off.
• Version source: prism-vault/VERSION is the source of truth for the subproject version. Prism repo/package versions must not silently substitute for the Prism-Vault line.
• Image / artifact name: the intended extraction-ready artifact name is prism-vault. Until extraction, any Prism-hosted build artifact or container image for this surface should carry that name in tags/labels rather than a Janus or generic backend label.
• Deploy config location: Prism-hosted deploy wiring lives in the normal Prism deploy surfaces (docker-compose*.yml, render.yaml, and related deploy/runbooks) with Prism-Vault-specific entries called out explicitly as the future service boundary.
• Contract-test target: Phase 0A contract tests target the Prism-hosted /vault HTTP routes at backend/tests/test_vault_router.py. Phase 0C adds matching MCP-side smoke coverage for the prism_vault_* verb surface.

​

Scope Model

tenant_id / project_id / environment / service / record_name

f4b93fa7 / PID-PGR01 / local  / prism        / openai-api-key
f4b93fa7 / PID-PGR01 / lan    / prism-agent  / github-token
f4b93fa7 / PID-PGR01 / render / prism-cloud  / workos-secret

f4b93fa7 / PID-DPA01 / lan / webcrawl / browserbase-key

• local
• lan
• render

​

Provider Binding

​

Local

​

LAN

• non-root app token,
• project-scoped policies,
• durable storage,
• normal seal/unseal operation,
• private LAN address,
• no public Vault port exposure.

​

Render

​

Provider credential isolation

​

API Contract

backend service -> /vault HTTP router -> thin mcp-node prism_vault_* verb shims

​

Secret metadata

prism_vault_secret_put(scope, name, fields, labels?, policy?)
prism_vault_secret_get_metadata(scope, name)
prism_vault_secret_list(scope, filters?)
prism_vault_secret_delete(scope, name)
prism_vault_secret_rotate(scope, name, rotator_ref?)

​

Runtime resolution

prism_vault_secret_resolve(scope, name, purpose, caller, run_ref?, field_allowlist?)

{
  "ttl_s": 900,
  "env": {
    "OPENAI_API_KEY": "...",
    "GITHUB_TOKEN": "..."
  },
  "audit_id": "..."
}

​

Config

prism_vault_config_put(scope, name, document, schema_ref?, labels?)
prism_vault_config_get(scope, name, version?)
prism_vault_config_list(scope, filters?)
prism_vault_config_promote(scope, name, from_version, to_environment)

​

Authorization Contract

• caller_identity
• caller_kind (human, agent, service)
• tenant_id
• requested project_id
• requested environment
• purpose

• Prism agents may resolve only Prism-scoped records that match their project, identity, and purpose.
• Prism backend services may manage service-scoped records through service identity.
• Operator/admin identities may write and rotate records within their tenant.
• Janus/DPA-Crawl and non-Prism projects have no default access in v0.1.

​

Prism Integration Contract

1. Prism backend service secrets for local/LAN/Render.
2. Prism agent runtime secret resolution for explicitly allowed purposes.
3. Prism config records for non-secret runtime config.
4. Masked metadata lookup for operator/admin inspection.
5. Audit lookup scoped to the requesting Prism project.

{
  "scope": {
    "tenant_id": "...",
    "project_id": "PID-PGR01",
    "environment": "lan",
    "service": "prism-agent"
  },
  "name": "agent-provider-credentials",
  "purpose": "prism.agent.execute",
  "run_ref": "session_or_scheduled_run_id",
  "field_allowlist": ["OPENAI_API_KEY"]
}

​

Later Janus / DPA-Crawl Contract

1. Read versioned crawl/extraction config before starting a job.
2. Resolve only the credentials that job needs immediately before execution.
3. Require job_id for worker resolves.
4. Mask resolved values in worker logs before persistence.

​

Data Model

​

prism_vault_secret_records

• id
• tenant_id
• project_id
• environment
• service
• name
• provider
• provider_ref
• labels
• active
• created_at
• updated_at

​

prism_vault_secret_versions

• id
• secret_record_id
• version
• field_names
• value_hash
• provider_version_ref
• created_by
• created_at

​

prism_vault_config_records

• id
• tenant_id
• project_id
• environment
• service
• name
• schema_ref
• active_version
• created_at
• updated_at

​

prism_vault_config_versions

• id
• config_record_id
• version
• document_json
• document_hash
• created_by
• created_at

​

prism_vault_access_policies

• id
• tenant_id
• project_id
• environment
• service
• record_ref
• caller_kind
• caller_identity_ref
• purpose
• permission
• effect

​

prism_vault_audit_events

• id
• tenant_id
• project_id
• environment
• service
• record_name
• record_kind
• operation
• caller_identity
• caller_kind
• purpose
• run_ref
• provider
• result
• value_hash
• created_at

​

Datris Lessons Adopted

• Self-describing secret payloads for complex provider slots.
• Masked metadata on read paths.
• Preserve existing sensitive field values when a UI sends the masked placeholder.
• Hot reload for config/AI/provider changes where the consuming service supports it.
• Runtime env injection, with log masking before persistence.

• No fail-open tenant fallback. Unmapped or missing caller credentials fail closed.
• No root-token provider access in LAN or Render.
• No stack traces returned to clients.
• No direct broad provider reads from application code.
• No caller-visible dependency on .env persistence in production.

​

Security Requirements

• All state-changing writes require authenticated caller identity.
• Raw secret values are returned only by prism_vault_secret_resolve.
• prism_vault_secret_resolve requires purpose.
• Prism project isolation is default-deny.
• Cross-project policies require explicit operator/admin creation and audit.
• Provider adapter credentials are service-owned and never sent to agents.
• Provider adapter credentials are adapter-local and mode-scoped; local callers cannot observe LAN or Render adapter credentials, and vice versa.
• Every value resolution writes an audit event before returning the value.
• resolve() MUST create an audit attempt/reservation before provider read and MUST finalize success, denied, or failure before returning any value.
• Audit writes are atomic with Prism-Vault authorization. If audit finalization cannot be written, no value is returned and the operation fails closed.
• Audit evidence is append-only and retained for at least 12 months.
• Runtime resolve responses remain provider-neutral: callers receive ttl_s, env, and audit_id, not provider refs or provider version refs.
• Policy write/modify is denied to agent and worker callers.
• purpose values are validated against a registered allowlist; wildcard/prefix policies require explicit per-record opt-in.
• Logs must mask exact resolved values and common transformed forms where practical.
• Render production defaults to Prism-Vault as service of record. Render-native encrypted env/secret handling is allowed only where the Render service boundary requires it; local .env is not production state.

​

Rotation Policy

• Monthly scheduled rotation for Prism-Vault-managed production secrets where the provider supports rotation.
• Manual on-demand rotation whenever an operator requests it, a credential is suspected exposed, a user/service leaves scope, or a provider key must be replaced.
• Every rotation attempt writes audit: requested_by, reason, record scope, provider, old value hash, new value hash, result, and timestamp.
• Rotation automation may be partial in v0.1, but the policy, audit shape, and manual operation path must exist.

​

Failure Modes

​

Implementation Plan

​

Phase 0A - Settings-backed service boundary skeleton

• Land this spec and Mermaid diagrams.
• Create the Prism-Vault separable subproject boundary and independent version/build plan inside the Prism umbrella.
• Define vault_service.py, /vault HTTP router, schemas, settings-backed provider, and router tests.
• Prove masked metadata, runtime resolve shape, config get, service-scope denial, header-bound audit caller, agent run_ref requirement, audit fail-closed seam, and no raw value in error paths.
• Do not introduce durable prism_vault_* tables or real provider behavior.

​

Phase 0B - Durable audit and policy floor

• Add append-only Vault audit migration/model/sink.
• Require audit attempt/reservation before provider read.
• Finalize success, denial, and failure audit before returning.
• Fail closed if audit is unavailable.
• Keep raw secret values out of Prism SQL.
• Add provider-neutral tests for audit success, denied, missing, and audit-unavailable paths.

​

Phase 0C - MCP verb parity

• Add thin mcp-node shims for prism_vault_secret_get_metadata, prism_vault_secret_resolve, and prism_vault_config_get.
• Add MCP smoke proving the shims call the /vault HTTP source contract.
• Do not add a standalone SDK in v0.1.

​

Phase 1 - Prism LAN provider

• Implement Vault KV v2 adapter for LAN mode.
• Add non-root app token and scoped policy.
• Add health/readiness probe for Vault availability and policy identity.
• Prove Prism agents and Prism backend services resolve only Prism-scoped records without cross-project leakage.

​

Phase 2 - Prism local provider

• Implement Vault KV v2 adapter for local mode.
• Implement Prism local bootstrap for Prism-scoped config and secrets.
• Treat .env as seed input only; state and audit still go through Prism-Vault.
• Prove Prism can put metadata, get masked metadata, resolve for a Prism runtime purpose, and observe audit.

​

Phase 3 - Prism Render provider

• Add Render adapter for service-level env/secret bindings.
• Define Render deploy env contract and smoke probes.
• Prove Render deployment serves the same Prism-Vault API contract as local/LAN.
• Make Prism-Vault the default service of record in Render.
• Use Render-native env/secret bindings only where the Render service boundary truly requires native injection; document each exception.

​

Phase 4 - Prism operations

• Add operator UI/API for masked metadata, config version history, promotion, policy creation, and audit lookup.
• Add monthly and manual-on-demand rotation hooks for common Prism provider keys.
• Add export/import for Prism project migration between local, LAN, and Render.

​

Phase 5 - Janus and DPA-Crawl collaboration

• Add Janus/DPA-Crawl as later consumers after Prism paths are stable.
• Add worker caller kind and job-scoped policy gates.
• Prove WebCrawl job credential resolution with job_id.
• Keep non-Prism integration behind explicit policy and audit.

​

Acceptance Criteria

• Prism can store masked metadata for Prism-scoped records.
• Prism agents can resolve an allowed Prism runtime secret and cannot resolve it outside the allowed purpose/scope.
• Prism backend services can consume Prism-Vault config in local, LAN, and Render modes.
• Local and LAN pass the same Prism-Vault contract tests against different providers.
• Render passes the same API contract, with provider-specific differences hidden behind the adapter.
• Masked metadata read never returns raw values.
• Every resolve emits an audit event with caller, scope, purpose, run_ref when present, provider, result, and value hash.
• Missing or unmapped tenant/project identity fails closed.
• Prism-Vault has separable subproject version/build/deploy metadata sufficient for later extraction from the Prism umbrella.
• Render mode treats Prism-Vault as the default service of record, with Render-native secret bindings documented as explicit exceptions.
• Monthly and manual-on-demand rotation policy is documented and audited.
• Provider adapter credentials remain isolated by deployment mode and are not exposed through runtime config or cross-mode resolution.
• Agent/worker callers cannot create or modify access policies.
• Purpose validation rejects unregistered purpose strings unless an explicit per-record wildcard rule exists.
• Audit evidence is append-only, retained for at least 12 months, and created before any resolved value is returned.
• Rotation/revocation docs explicitly state TTL as the max exposure window and document an emergency revocation path independent of normal TTL expiry.
• Janus/DPA-Crawl acceptance is deferred to Phase 5 and is not a v0.2 ship gate.

​

Ownership

• Architecture: Texi
• First consumer: Prism
• Prism backend integration: Donna / Prism backend owner
• Install/deploy: Lafonda
• Governance/security review: Candi
• Viewer/review coordination: Carla
• Later collaboration: Janus / DPA-Crawl after Prism rollout gates pass