# Product Requirements Document: secrets-engine ## Summary secrets-engine provides the operational interface for approved secret lifecycle work across build, test, and production. It wraps OpenBao with a catalog, decision checks, stage-aware privilege boundaries, safe delivery modes, and non-secret audit evidence. The first implementation should focus on getting one real pilot lane working end to end: the whynot-design npm publish token. The design must also be general enough to support API keys, provider tokens, database passwords, CI credentials, and other workload secrets later. ## Related Documents - [NetKingdom security infrastructure boundary pointer](docs/netkingdom-security-infrastructure.md) points to the canonical document in `net-kingdom/docs/` and defines the responsibilities and interactions with OpenBao, flex-auth, user-engine, ops-warden, ops-bridge, info-tech-canon, State Hub, and agents. ## Background The current platform can define OpenBao paths, policies, and credential-change requests, but the live path still requires too much manual OpenBao UI/CLI work. This creates a trap: the secure process exists on paper, but daily work still falls back to handovers, broad platform-root access, and interface-specific mistakes. secrets-engine is the missing workflow layer. It should let an approved decision become an applied and verified secret lane without asking each operator or agent to understand every OpenBao endpoint, CLI quoting rule, auth role shape, or workload-specific delivery convention. ## Goals - Provide one interaction surface for approved secret establishment, access, rotation, deactivation, and verification. - Separate build, test, and production privileges from the beginning. - Let agents and operators apply approved OpenBao metadata without broad admin access. - Deliver secrets to commands and workloads without printing values. - Produce non-secret evidence suitable for State Hub progress, audits, and troubleshooting. - Give ops-warden a credential routing target that is not responsible for secret custody itself. ## Non-goals - Replacing OpenBao as the canonical vault and audit backend. - Replacing key-cape, user-engine, flex-auth, or State Hub. - Building a full UI before the CLI/API model is clear. - Automating high-risk production secret value provisioning before the approval, wrapped-delivery, and verification model is proven. - Storing raw secret values in Git, workplans, State Hub, chat, prompts, normal logs, or long-lived local files. ## Primary Users | User | Need | | --- | --- | | Platform operator | Apply approved secret changes without hand-typing OpenBao internals. | | Agent such as Codex or ops-warden | Request or use approved credentials through a safe front door. | | Workload maintainer | Get a clear request, review, approval, and consumption path. | | Security reviewer | See decisions, policy boundaries, verification evidence, and revocation state. | | Future service maintainer | Add new secret types and delivery modes without weakening production custody. | ## Operating Model ### Stage roles secrets-engine should bootstrap at least three OpenBao-facing roles: | Role | Intended use | Initial privilege shape | | --- | --- | --- | | secrets-engine-build | Build/dev lanes, generated test values, low-risk experimentation | Can manage approved build-stage metadata and values under build prefixes. | | secrets-engine-test | Test/staging lanes and integration verification | Can manage approved test-stage metadata and values; can perform positive/negative checks. | | secrets-engine-prod | Production metadata apply and tightly controlled delivery | Can apply approved prod metadata and auth roles; raw prod value read/provisioning remains gated and logged. | The exact OpenBao policy names can change, but the stage distinction is a product requirement, not an implementation detail. ### Bootstrap credential files Until proper OIDC/service authentication exists, a platform-root operator may create temporary OpenBao credentials for the three roles and place them outside repositories, for example under a local mode-0700 directory. The files must be: - mode 0600; - outside Git worktrees; - named by role and environment only, never by secret value; - revocable; - recorded in non-secret bootstrap notes by path and accessor only when safe; - treated as temporary infrastructure setup material. Agents may be told the file path, not the token value. The engine should read such files only when explicitly invoked in bootstrap mode. ## Functional Requirements ### FR1 - Secret catalog The engine must maintain a non-secret catalog of secret lanes and grants. Each catalog entry should include: - catalog id; - owning domain/repo/workload; - stage: build, test, production, or another explicit stage; - OpenBao mount and path; - fields exposed; - allowed consumers and auth claims; - delivery modes; - approval requirement; - TTL and rotation expectations; - verification requirements; - revocation/deactivation behavior; - audit evidence expectations. ### FR2 - Decision integration Privileged actions must require an approved decision or approved credential change request unless explicitly running in a local bootstrap or dry-run mode. The engine must be able to: - inspect a request; - render a human-reviewable plan; - link to the decision record when available; - refuse denied, superseded, stale, or unapproved requests; - record non-secret apply and verification evidence. ### FR3 - OpenBao metadata apply The engine must generate and apply OpenBao metadata safely: - ACL policies; - auth roles; - token roles where needed; - KV metadata where safe; - path and name restrictions based on catalog and stage; - dry-run output before live mutation. Production apply must fail closed if the request is not approved or if the plan contains an out-of-bound policy, role, mount, path, wildcard, or broad admin capability. ### FR4 - Secret provisioning The engine must support secret value provisioning without exposing raw values in coordination channels. Initial supported modes: - operator-attended OpenBao provisioning; - bootstrap local file import with strict permissions; - response-wrapped handoff where OpenBao supports it; - generated test secrets for non-production only. Production raw value automation should remain deliberately constrained until the wrapped or dual-control flow is proven. ### FR5 - Secret delivery The engine must provide delivery modes that avoid printing secret values: - exec-time environment injection; - exec-time temp file injection with cleanup; - workload-specific config file generation such as temporary npm config; - response wrapping for handoff flows; - read checks that return boolean/evidence, not the value. A representative target command shape: ```bash secrets-engine exec --catalog whynot-design-npm-publish -- npm publish ``` For npm, the engine should prefer creating a temporary npm config and setting the child process environment to use it, then deleting it after the child exits. ### FR6 - Verification The engine must support positive and negative verification without printing secrets. Positive checks prove an approved consumer can access or use the secret. Negative checks prove an unrelated consumer cannot. Evidence should include non-secret metadata such as catalog id, actor, decision id, path, timestamp, and result. ### FR7 - CLI/API interface The MVP must provide a CLI. The command names may evolve, but the first surface should cover: ```text secrets-engine catalog list secrets-engine catalog show secrets-engine decision inspect secrets-engine plan secrets-engine apply --stage secrets-engine provision --stage --from-file secrets-engine verify --positive secrets-engine verify --negative --negative-token-file secrets-engine exec --catalog -- secrets-engine revoke ``` The API should be designed after the CLI semantics are clear. ### FR8 - Audit and evidence The engine must never log raw secret values. It must write non-secret evidence for: - decision inspected; - plan rendered; - apply attempted/succeeded/failed; - secret provisioned without value disclosure; - exec delivery attempted/succeeded/failed; - verification positive/negative result; - revoke/deactivate/rotate actions. State Hub integration should use non-secret progress entries and decision links. OpenBao audit logs remain the backend source of truth for vault operations. ### FR9 - ops-warden routing ops-warden should route non-SSH credential requests to secrets-engine. It should not own or vend provider tokens, API keys, database passwords, or OpenBao values. A route result should tell the caller: - the catalog id; - the decision/request status; - whether the secret is ready/resolvable; - the safe command to request or execute with the credential; - what human decision or provisioning step is still missing. ## Security Requirements - Raw secret values must never appear in prompts, chat, Git, workplans, State Hub messages, issue comments, or normal logs. - Production operations must require an approved decision except break-glass flows, which must be explicit and heavily audited. - Stage roles must be unable to mutate paths outside their stage and allowed prefixes. - Production metadata appliers must not gain broad sys, auth, identity, root, or platform-admin semantics. - Bootstrap token files must be temporary, revocable, mode 0600, and outside repositories. - The engine must redact token-like values from child process output where it controls the execution path. - Every role and delivery mode must have a documented revocation path. ## MVP Scope The MVP is complete when it can support the whynot-design npm publish token pilot with this chain: 1. Catalog entry exists for whynot-design npm publish. 2. Approved decision/CCR is inspected. 3. OpenBao ACL policy and auth role are applied through a stage-appropriate secrets-engine role or bootstrap credential. 4. The token value is provisioned without being printed or logged. 5. Positive and negative verification pass. 6. A safe command can execute npm publish with the token injected only into the child process. 7. ops-warden can report the catalog entry as ready/resolvable. ## Success Metrics - Approved secret lanes can be applied without platform-root hand typing. - A typical approved non-production credential can be established in minutes. - Production metadata apply succeeds without granting raw secret read authority. - No secret values are found in repo history, State Hub payloads, logs, or chat. - Operators can understand a generated plan without knowing OpenBao endpoint quirks. - At least one real workload consumes a credential through secrets-engine exec. ## Risks | Risk | Mitigation | | --- | --- | | Wrapper accidentally becomes broad platform-admin by another name | Stage roles, path allowlists, decision checks, negative tests. | | Temporary bootstrap files become permanent | Track bootstrap mode, add revocation tasks, replace with OIDC/service auth. | | Agents exfiltrate secrets through logs or prompts | Prefer exec-time delivery, redaction, no raw read default. | | Product scope grows into identity/authorization | Keep key-cape/user-engine and flex-auth boundaries explicit. | | OpenBao-specific assumptions leak everywhere | Keep a catalog and interface model; isolate backend adapter code. | ## Open Questions - Should the first repo expose only a CLI, or also a tiny local service API? - What is the canonical State Hub decision object for secret establishment, rotation, and deactivation? - Which stage names are final: build, test, prod, or build, staging, production? - Should production value provisioning require two-person review immediately or only after the pilot? - Which identity claim should bind the whynot-design consumer long term: group, workload service account, repository identity, or a combination?