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](INTENT.md) - why this repository exists, including the Engine /
  Lifecycle declaration.
- [layer.yaml](layer.yaml) - machine-readable layer declaration and proposed
  surfaces.
- [ProductRequirementsDocument.md](ProductRequirementsDocument.md) - product
  requirements and MVP scope.
- [NetKingdom security infrastructure boundary pointer](docs/netkingdom-security-infrastructure.md)
  - 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](workplans/SECRETS-WP-0002-bootstrap.md) - 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:

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

## Quickstart

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