​

Plan #28 - Prism-Vault Shared Config and Secrets Service

Status: in_progress Spec: docs/specs/spec-122-v0-1-prism-vault-shared-config-secrets-service.md Diagrams: docs/diagrams/prism-vault/*.mmd Owner: Texi (architecture)

​

v0.3 Ratification Scope Update - 2026-05-18

Status: ratification-ready draft; implementation is blocked by V-0. Frank must ratify SPEC-122 v0.2 plus this scoped Plan #28 update before any new Prism-Vault implementation code lands. Operations Console remains the active implementation lane. Vault queues behind it. The existing settings-backed implementation is renamed Phase 0A. It establishes the HTTP router/schema/service contract, masked metadata, runtime resolve response shape, config get, scope denial, header-bound audit caller, agent run_ref requirement, stub audit IDs, and no-raw-value error tests. Phase 0A does not claim durable prism_vault_* tables, persistent append-only audit, MCP verb parity, real Vault KV v2 provider behavior, Render provider behavior, production secret migration, full CRUD, operator UI, or rotation/revocation automation. Ratification unlocks these next slices, in order:

1. Phase 0B - Durable audit and policy floor: Alembic migration/model, append-only audit sink, attempt/reservation before provider read, success/denied/failure finalization before raw values return, fail-closed audit behavior, and provider-neutral audit tests.
2. Phase 0C - MCP verb parity: thin shims for prism_vault_secret_get_metadata, prism_vault_secret_resolve, and prism_vault_config_get, with an MCP smoke proving the shims call /vault.
3. Phase 1 - LAN-first Vault KV v2 provider: server1 Vault container, non-root app token, scoped policy, readiness/policy probe, provider-neutral caller contract, and the same contract tests against the LAN provider.
4. Phase 2 - Local provider parity: local Vault KV v2 provider with .env as seed input only.
5. Phase 3 - Prism operations: masked metadata/config views, audit lookup, policy creation, migration export/import, and operator-facing workflows.
6. Phase 4 - Rotation and revocation: monthly/manual-on-demand rotation hooks, emergency revoke, and audit evidence.

Render remains deferred unless Frank explicitly reorders the lane.

​

v0.3 Coverage Reassignment - 2026-05-18

Carla is offline. She remains the eventual viewer/review coordinator, but she is not an active blocker for ratification or implementation sequencing.

​

v0.2 PO Decision Provenance

Per Carla (PO) signal 30c95af1-36a4-45af-a009-7fd9a1d086b6 2026-05-17T15:07Z, operator-confirmed:

• Target: LAN-only deployment + testing for today
• Cloud/Render: deferred to next week
• Acceptance criteria trimmed accordingly (see ## Acceptance below)

​

v0.2 Lane Assignments (Phase 0 Execution - 2026-05-17)

Superseded for active 2026-05-18 execution by v0.3 Coverage Reassignment. This table remains as provenance for the merged Phase 0A skeleton. Per Frank operator directive ratified 2026-05-17:

​

Phase 0A Scope Gate (2026-05-17)

Settings-backed skeleton, stub audit, no durable prism_vault_ tables.* Phase 0A explicitly establishes:

• API/auth/audit seam (HTTP router + service + schemas)
• SettingsBackedVaultProvider — reads values from existing Settings object, no secret ownership migration
• VaultAuditSink stub — generates pva_{uuid} audit IDs, writes nowhere (no durable table); audit persistence is explicitly deferred to Phase 1
• No Alembic migration in this phase; no prism_vault_* DB tables introduced

Phase 0B gate (separate PR after V-0 ratification):

• Persistent vault_audit_events table + Alembic migration
• Durable audit sink and fail-closed finalization tests

Phase 1 gate:

• LAN Vault KV v2 provider adapter
• LAN provider-backed contract tests

​

v0.2 Close-Out Definition (2026-05-17)

“Closed out today” means:

• Phase 0A skeleton merged (PR #434 commit c193451 merged 2026-05-17T14:22:41Z)
• Phase 0A deployed to server1 (pending Samantha + Frank go/no-go)
• 1 contract smoke pass: prism_vault_secret_get_metadata returns masked=true, no raw value
• 1 end-to-end caller resolution: Prism backend resolves one Prism-scoped secret on LAN

NOT close-out today: all of Plan #28. Remaining workstreams (B-Local, B-Render, D, E, F) carry to subsequent phases per PO direction 2026-05-17.

​

Intent

Use the Datris HashiCorp Vault implementation as prior art, but build Prism-Vault as a Prism-first config/secrets broker. Prism is the first consumer. Janus and DPA-Crawl/WebCrawl are later collaboration targets after the Prism local/LAN/Render paths prove the contract. Prism-Vault starts as a Prism-accessible separable subproject inside the Prism umbrella, with its own versioning, build, deploy, and contract-test lifecycle so it can peel off into a standalone service later.

​

Workstreams

​

A - Service Boundary and Contract

• Define Prism-Vault separable subproject boundary inside the Prism umbrella.
• Define provider-neutral API semantics.
• Define scope object and authorization inputs.
• Define audit schema and fail-closed errors.
• Lock provider credential isolation, purpose validation, policy-mutation restrictions, and audit append-only semantics into the contract before Phase 0B code lands.
• Treat Phase 0A as the existing vault_service.py + /vault HTTP router/schema skeleton only.
• Add thin mcp-node prism_vault_* verb shims in Phase 0C after durable audit lands.
• Defer any standalone SDK until a non-MCP consumer exists.
• Add version/build/deploy metadata from the first implementation commit.
• Name Phase 0B/Phase 1 contract tests for: provider credential isolation by mode, denied agent/worker policy mutation, purpose allowlist validation, audit fail-closed reservation/finalization, and emergency revocation semantics.

​

B - Provider Adapters

• LAN Vault KV v2 adapter with app token and scoped policies.
• Local Vault KV v2 adapter after LAN proves the contract.
• Render adapter for env/secret bindings.
• External managed provider adapter if Render env binding cannot safely support per-project runtime secrets.

​

C - Prism Local/LAN Integration

• Register Prism backend/service identity as a Prism-Vault client.
• Add Prism-scoped secret metadata CRUD.
• Add prism_vault_secret_resolve immediately before Prism agent/backend runtime execution needs a secret.
• Inject resolved fields as a short-lived env payload.
• Mask resolved values in Prism logs before persistence.
• Keep cross-project access default-deny.

​

D - Prism Render Production

• Define Render env contract.
• Add deploy smoke for provider binding presence.
• Run the same Prism-Vault contract tests against Render 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 every exception.
• Prove Prism cloud can consume Prism-Vault without caller-visible Render special cases.

​

E - Prism Operations

• Add masked metadata and config version views for operators.
• Add audit lookup scoped to the requesting Prism project.
• Add policy creation and monthly/manual-on-demand rotation hooks for common Prism provider keys.
• Add export/import for project migration between local, LAN, and Render.

​

F - Later Janus / DPA-Crawl Collaboration

• Add Janus/DPA-Crawl after Prism rollout gates pass.
• Add worker caller kind and job-scoped policy gates.
• Add crawl config read before job start.
• Add job credential resolution with required job_id.
• Keep non-Prism integration behind explicit policy and audit.

​

Review Gates

• Texi: architecture review of boundary, contract, and compatibility shape.
• Candi: security/governance review of auth, scope, and audit.
• Donna: Prism backend feasibility and integration plan.
• Lafonda: local/LAN/Render deploy and install review.
• Carla: viewer review of spec and Mermaid diagrams.
• Frank: review subproject-first boundary and later peel-off assumptions.
• Janus/DPA-Crawl owner: later-consumer review after Prism gates pass.

​

Acceptance

• SPEC-122 accepted with Prism-first rollout order.
• Mermaid diagrams render in Carla’s viewer.
• (v0.3 V-0 per Donna/Texi 2026-05-18) Frank ratifies SPEC-122 v0.2 plus this scoped Plan #28 update before Phase 0B/0C/1 implementation lands.
• Contract tests exist for LAN provider binding; local + Render bindings are deferred to subsequent phases.
• Contract tests exist for provider credential isolation by mode, denied agent/worker policy mutation, purpose validation, and fail-closed audit / revocation semantics.
• Prism can store masked metadata and resolve an allowed Prism-scoped runtime secret.
• Prism LAN path uses the Prism-Vault API contract; local/Render parity is deferred to subsequent phases unless Frank reorders.
• Prism-Vault has separable subproject version/build/deploy metadata sufficient for later extraction.
• (deferred next week per PO direction 2026-05-17) Render mode treats Prism-Vault as default service of record; Render-native exception list to be defined when Render phase begins.
• (deferred to Workstream E) Rotation baseline is monthly or manual on demand/request, with audit.
• Janus/DPA-Crawl integration is explicitly deferred and is not a v0.2 ship gate.
• PRs touching prism_vault migrations, docker-compose/server deploy config, provider adapters, or /vault service/router code must ship lockstep matching changes in the same PR. No schema-only, config-only, docker-cp-only, or code-only drift for these surfaces.
• Provider adapters must run a startup smoke probe against committed config/live binding before a Phase 1/2/3 slice is marked complete, and must fail closed when committed config and live binding disagree.
• Alembic migrations for the prism_vault tables must ship with the corresponding router/service code, and production migration flow must include a pre-deploy backup/restore check for audit_events because it is append-only and retention-bound.