# Secrets PKI Ops Read Model Gap Map v1

Status: gap map for `OPS-PROD-SECRETS-PKI-OPS-READMODEL-001`

Owner: Platform Secrets/PKI / Platform Operations / Security

Last updated: 2026-06-06

## Purpose

Define the operator questions that must be answerable through GPUaaS platform
evidence and read models before expanding direct Vault UI use.

Vault, step-ca, cert-manager, and `packages/shared/pki` remain the custody and
issuance tools. GPUaaS read models expose custody posture, rotation posture,
certificate lifecycle posture, and break-glass evidence. They must never expose
secret values, unseal keys, root tokens, private keys, or pull credentials.

## Operator Questions

| Operator question | Current first surface | Direct UI still used | Gap |
|---|---|---|---|
| Which credential purposes exist and who owns rotation? | `packages/platform/secrets` custody registry, secrets/PKI architecture docs. | Vault UI or code inspection during incidents. | Need purpose inventory read model with purpose ID, material kind, custody tool, delivery mode, rotation owner, cadence, evidence component, and status. |
| Is Vault initialized, unsealed, mounted, and readable without exposing secrets? | Vault bootstrap runbook and deploy preflight logs. | Vault CLI/UI during deploy failures. | Need Vault readiness evidence surface with initialized/sealed/mount/policy/read-check status only. |
| Which certificates are near expiry, failed renewal, or revoked? | cert-manager/step-ca evidence, node lifecycle signals, PKI docs. | cert-manager/kubectl/step-ca direct inspection. | Need certificate lifecycle read model with issuer, subject class, not-after, renewal status, owner domain, and evidence link. |
| Was a rotation executed, verified, and audited? | Rotation runbooks, Fairway evidence, custody specs. | Vault UI or provider logs after manual action. | Need rotation evidence read model covering purpose, actor, started/completed time, old/new version refs, validation checks, and audit action. |
| Was break-glass access used correctly? | Vault bootstrap/root token runbook and incident evidence. | Manual Vault/cluster inspection. | Need break-glass event/evidence read model with approval ref, actor, scope, time window, post-action remediation, and root-token replacement status. |

## Current Coverage

| Area | Existing coverage | Status |
|---|---|---|
| Purpose registry | `packages/platform/secrets/registry.go` defines well-known purpose IDs, custody tools, delivery modes, rotation owners, audit actions, and evidence components. | Partial |
| Vault baseline | `Platform_Vault_Secrets_Baseline_v1.md` defines classes, actor model, path layout, delivery model, and invariants. | Partial |
| Vault bootstrap/runbook | `Vault_Bootstrap_and_Root_Token_Runbook.md` defines init/unseal/root-token handling and safe deploy preflight behavior. | Partial |
| Runtime trust model | `Secrets_PKI_Runtime_Trust_Model_v1.md` defines coordination-layer posture over Vault, step-ca, cert-manager, and PKI helpers. | Partial |
| Live rotation drills | Live secret rotation and break-glass drills remain approval-gated. | Blocked by approval |
| Operator read models | No consolidated status surface for purpose inventory, rotation state, cert lifecycle, Vault readiness, or break-glass evidence. | Gap |

## Read Model Work Packages

| Task | First output | Notes |
|---|---|---|
| `OPS-PROD-SECRETS-PKI-PURPOSE-INVENTORY-001` | Contract for secret/certificate purpose inventory from custody registry and environment evidence. Output: `doc/operations/Secrets_PKI_Purpose_Inventory_Read_Model_Contract_v1.md`. | Must expose status, ownership, cadence, and evidence links only. |
| `OPS-PROD-SECRETS-PKI-VAULT-READINESS-001` | Contract for Vault initialized/sealed/mount/policy/read-check status and deploy-preflight evidence. Output: `doc/operations/Secrets_PKI_Vault_Readiness_Read_Model_Contract_v1.md`. | Must not expose root token, unseal key, operational token, or secret values. |
| `OPS-PROD-SECRETS-PKI-CERT-LIFECYCLE-001` | Contract for certificate expiry, renewal, revocation, issuer, subject class, owner, and evidence link. Output: `doc/operations/Secrets_PKI_Certificate_Lifecycle_Read_Model_Contract_v1.md`. | Starts with node-agent, worker, ingress wildcard, and cert-manager/step-ca managed purposes. |
| `OPS-PROD-SECRETS-PKI-ROTATION-EVIDENCE-001` | Contract for rotation execution evidence: purpose, actor, approval ref, version refs, validation, audit, result, and next due date. Output: `doc/operations/Secrets_PKI_Rotation_Evidence_Read_Model_Contract_v1.md`. | Live rotation remains approval-gated; this task can start with non-destructive evidence format. |
| `OPS-PROD-SECRETS-PKI-BREAKGLASS-EVIDENCE-001` | Contract for break-glass event evidence, time-boxing, post-action remediation, and root-token replacement status. Output: `doc/operations/Secrets_PKI_Breakglass_Evidence_Read_Model_Contract_v1.md`. | This is evidence modeling only unless explicit live approval exists. |

## Direct UI Policy

| Tool | Default operator path | Direct UI remains allowed when |
|---|---|---|
| Vault UI/CLI | Purpose inventory, Vault readiness evidence, rotation evidence, break-glass evidence. | Approved break-glass, bootstrap, or custody diagnosis requires provider-native inspection by a named operator. |
| step-ca/cert-manager | Certificate lifecycle read model and PKI runbook evidence. | Certificate issuance/renewal debugging requires provider-native detail after platform evidence identifies the affected cert purpose. |

## Excluded Data

Secrets/PKI read models must not expose:

- Vault root tokens, unseal keys, operational tokens, wrapped tokens, or AppRole
  material;
- registry pull credentials, publish credentials, OIDC client secrets, Stripe
  secrets, JWT/JWKS private material, terminal signing material, or node task
  signing private material;
- private keys, CSR private material, or raw certificate private key PEM;
- raw Vault paths when they reveal tenant, customer, or secret material beyond
  approved purpose IDs;
- command output containing secret values.

## Guardrails

- Nodes do not talk directly to Vault.
- Direct Vault UI remains internal-only and break-glass; no public ops route.
- Live rotation and break-glass drills require explicit approval.
- Kubernetes Secrets are a transitional cache only when the source of truth and
  migration path are documented.
- Purpose IDs may name the credential class; read models must not disclose the
  underlying value.
- Every privileged manual action needs an audit/evidence record and post-action
  remediation checklist.

## Exit Criteria

Vault direct UI stops being a normal diagnostic path when:

- purpose inventory shows custody, delivery, rotation owner, cadence, and
  evidence status;
- Vault readiness status is visible without exposing secrets;
- certificate lifecycle posture shows expiry/renewal/revocation status by
  purpose;
- rotation evidence can prove execution and validation without secret material;
- break-glass events have time-boxed evidence and post-action remediation status.