> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Workstreams A-F and review gates for the Prism-first Prism-Vault shared config/secrets broker. Companion to SPEC-122 v0.2.

# 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.

| Role                   | Identity | Scope                                                                                                                  |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| Operator / ratifier    | Frank    | Ratify SPEC-122 v0.2 and scoped Plan #28 before build-start                                                            |
| Backend implementation | Donna    | Own Phase 0B audit migration/model/service/router/tests, Phase 0C MCP coordination, and Phase 1 LAN provider after V-0 |
| Architecture           | Texi     | Maintain SPEC/Plan wording, phase boundaries, compatibility gates, and architecture review                             |
| Governance             | Candi    | Validate V-1 through V-6 gates, scope/auth/audit policy, and raw-secret handling                                       |
| Runtime / deploy       | Samantha | Verify server1 Vault readiness, deploy/smoke path, and LAN runtime evidence                                            |
| Install / bootstrap    | Lafonda  | Own Vault install policy, token bootstrap, and operator runbook review                                                 |
| Docs                   | Desiree  | Update API contract, build/deploy docs, changelog, and proofread ratification docs                                     |
| Cursor / operator UI   | Sable    | Optional Phase 3 UI/help lane if reachable                                                                             |
| Security review        | Andora   | Review real-provider secret handling before Phase 1 resolve if reachable                                               |

## 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:

| Role       | Identity | Scope                                   |
| ---------- | -------- | --------------------------------------- |
| PO         | Carla    | Scope ratification, viewer acceptance   |
| PM         | Donna    | Cradle-to-grave delivery, PR authorship |
| Arch / RTE | Texi     | Architecture gating, RTE merge gate     |
| Deploy RTE | Samantha | Deploy execution, smoke validation      |

## 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.