secrets-engine/README.md

secrets-engine

Headless, multi-application, multi-tenant secrets workflow and automation layer for approved secret custody, delivery, and lifecycle work across build, test, and production stages.

Layer: Engine / Lifecycle under the accepted NetKingdom Security Layer Model (layer.yaml). OpenBao remains the custody and enforcement backend. secrets-engine is the deterministic API over it: catalog, decision consumption, plan/apply, guarded provisioning, verification, delivery, evidence, lifecycle metadata, and native-access deactivation. It does not render authorization decisions. Local evidence can be inspected through an allowlisted per-lane audit summary without exposing record detail.

Start Here

• INTENT.md - why this repository exists, including the Engine / Lifecycle declaration.
• layer.yaml - machine-readable layer declaration and proposed surfaces.
• ProductRequirementsDocument.md - product requirements and MVP scope.
• NetKingdom security infrastructure boundary pointer
  • points to the canonical document in net-kingdom/docs/, covering responsibilities and interactions with OpenBao, flex-auth, user-engine, ops-warden, ops-bridge, info-tech-canon, State Hub, and agents.
• Bootstrap MVP workplan - first implementation plan after State Hub bootstrap.

Core Direction

The MVP proves the whynot-design-npm-publish lane end to end:

1. describe the lane in a non-secret catalog (catalog/);
2. verify an approved decision (State Hub or local fixture);
3. apply OpenBao policy/auth metadata through a stage-aware role;
4. provision and verify the value without printing it;
5. run a workload command through safe exec-time delivery.

Target command shape:

secrets-engine exec --catalog whynot-design-npm-publish -- npm publish

Quickstart

uv venv && uv pip install -e ".[dev]"
source .venv/bin/activate
secrets-engine catalog list

# Run the whole pilot chain live against a throwaway OpenBao dev server:
SECRETS_ENGINE_HUB_URL="" bash scripts/demo-e2e.sh

• CLI reference: docs/cli.md
• Publication-scope policy (maturity → token scope): docs/publication-scope-policy.md
• Stage roles & bootstrap tokens: docs/openbao-stage-roles.md
• warden-sign auth-capability lane: docs/warden-sign-auth-capability.md
• whynot-design real publish closeout: docs/whynot-design-real-publish-closeout.md
• ops-warden routing contract: docs/ops-warden-routing-contract.md
• Hardening backlog (exit bootstrap mode): docs/hardening-backlog.md
• Existing-lane catalog admission: docs/catalog-admission.md
• KeyCape service-auth consumer boundary: docs/service-auth.md
• Approval consume-before-OpenBao (GH-DEC-2026-003): docs/approval-consumption.md
• OpenBao JWT login contract (engine consumer): docs/openbao-jwt-login.md
• Secret-use evidence surface: docs/secret-use-evidence-contract.md

The implementation is a Python package (src/secrets_engine/). OpenBao is reached only through the bao CLI adapter (openbao.py); the rest of the code speaks in lanes and guarded plans.

Security Rules

• Do not put raw secret values in Git, State Hub, chat, prompts, issue comments, workplans, or normal logs.
• OpenBao is the backend custody and audit authority.
• Build, test, and production have separate policy boundaries.
• Production live actions fail closed until the durable State Hub action-authorization endpoint is available; local approval mirrors are throwaway-demo material only.
• A privileged production OpenBao call also requires a successful approval-engine CAS consume first. Conflict or unavailability means do not write.
• Temporary bootstrap OpenBao credentials must live outside repos, use mode 0600, be revocable, and be removed after narrower auth is working.