secrets-engine/history/2026-08-23-scope-intent-capability-gap-assessment.md

Scope and Intent Capability Gap Assessment

Date: 2026-08-23
Author: codex
Compared: SCOPE.md against INTENT.md and the current implementation

Executive assessment

The repository has a credible, tested CLI MVP, but it is not yet the complete secure interaction and automation layer described by INTENT.md.

The strongest implemented slice is:

catalog -> approval-status check -> guarded plan -> policy/AppRole apply
        -> bounded presence/capability verification -> CLI-local exec/handoff
        -> non-secret route/evidence pointer

The weakest slice is lifecycle safety beyond that pilot chain. Rotation is metadata only, KV provisioning is not merge-safe for multi-field paths, KV revoke is destructive and incomplete, approval integration is still a pilot resolver rather than a production authorization contract, and service mode does not exist.

The intent remains directionally sound. The gap is maturity, not a need to move the system boundary: OpenBao should remain the backend; flex-auth/State Hub should authorize; key-cape/user-engine should own identity; ops-warden should route; and secrets-engine should remain the guarded workflow layer.

Open-work assessment

The only active repository workplan is SECRETS-WP-0006:

• T05 waits on explicit per-lane approval and scoped production OpenBao apply authority for five reviewed existing production lanes.
• T06 waits on successful native verification before ops-warden proxy retirement.

No approval or production authority was available during this assessment. The latest ops-warden message also parks the standalone warden-sign AppRole for break-glass use and explicitly requests no credential action. There was no safe, actionable live task, so documentation reconciliation was the appropriate work.

Intent scorecard

Intent area	Assessment	Current evidence	Material gap
Decision first	Partial	Privileged CLI handlers require a resolved status and reject missing, unapproved, or superseded decisions.	Resolution accepts tracked local fixtures, checks only coarse status, has no freshness/purpose/actor semantics, and does not enforce actual dual control. The five new CCR strings do not resolve through the State Hub UUID endpoint.
OpenBao enforces; engine orchestrates	Substantially aligned	Backend operations are isolated in openbao.py; catalog, plan, guards, delivery, routing, and evidence are separate modules.	Only the local bao/vault subprocess adapter exists. Some safety depends on local validation rather than backend-bound per-request authorization.
Stage-aware privilege	Partial	Stage names, stage mismatch rejection, build/test prefixes, static stage policies, and consumer policy/AppRole naming exist.	Production has no local owner-prefix invariant (STAGE_PREFIX["prod"] is empty). Static bootstrap stage policies and supplied credentials remain wider and longer-lived than per-action identity.
No values in coordination surfaces	Partial, with a concrete implementation risk	Catalog validation rejects secret-looking inline values; evidence is scrubbed; CLI output avoids values; exec output is redacted.	kv_put passes the raw value in the local bao subprocess argument vector. Exec/verification parse the complete KV path response in process memory. These do not put values in Git/State Hub, but they fall short of the strongest custody boundary in the intent.
Least friction without broad power	Partial	Human-readable dry-runs, one-command exec, route pointers, and exact consumer policies reduce hand-written OpenBao work.	Routine production still needs manual decision and credential bridging. There is no OIDC/service login, service API, or durable request orchestration.
Bootstrap honestly, then harden	Partial	Bootstrap files are mode checked, rejected inside Git worktrees, documented, and tracked in the hardening backlog.	Bootstrap mode is still part of the live CLI; one historical cleanup/revocation record remains incomplete; tracked local approval mirrors remain usable for production commands.
Prefer exec-time delivery	Partial	exec-env and npm-config are implemented, including temporary npm config cleanup and child-output redaction.	exec-file and wrapped are schema-only. Scoped login tokens are not explicitly revoked after exec/verify, and child delivery is local CLI execution only.
Auditable and reversible	Weak/partial	Scrubbed JSONL evidence and best-effort State Hub progress events exist; OpenBao remains the audit source.	Many failure paths produce no evidence, State Hub posting silently drops failures, actors are not cryptographically bound, no audit-report command exists, and KV revoke is destructive rather than reversible.
Typed multi-application catalog	Substantially aligned as metadata	Multiple KV lanes, an auth-capability lane, explicit org/repo/stage/consumer/field data, existing-mount semantics, and high-risk ownership checks are implemented.	This is not runtime multi-tenancy. Consumer claims are descriptive and are not authenticated or authorized by this process.
CLI and service API	CLI achieved; API absent	The documented CLI surface exists and the pilot flow has integration coverage.	No daemon, API, queue, scheduler, UI, remote protocol, or concurrency model exists.
Lifecycle: establish/access/rotate/deactivate	Establish/access partial; lifecycle incomplete	Apply, provision, verify, exec, handoff, and two forms of revoke exist.	No rotate command, compromise/suspend state, provider rotation, lease/accessor lifecycle, rollback orchestration, or safe soft deactivation exists.

Highest-priority gaps

P0 — Provisioning is unsafe for shared multi-field paths

provision_from_file reads one declared field and calls OpenBaoClient.kv_put. That adapter invokes:

bao kv put <mount>/<path> <field>=<value>

Two consequences matter:

1. kv put replaces the data at a KV v2 path rather than merging sibling fields. Updating one field can remove the others.
2. The raw value is present in the local subprocess argument vector while the command runs.

This is acceptable only as a constrained pilot/bootstrap primitive on a single-field or disposable path. It must not be used on the newly admitted issue-core, reuse-surface, Forgejo, or email paths. A production design needs a merge-safe update mechanism that does not expose values through argv, plus tests proving sibling preservation and failure cleanup.

P0 — KV revoke is destructive, incomplete, and inconsistent with dry-run

For a KV lane, live revoke deletes all KV metadata/versions but leaves the consumer AppRole and ACL policy. The dry-run text says it would delete both KV metadata and the AppRole, which the live path does not do.

This does not meet the intent's reversible lifecycle principle. The command needs explicit operations with different approvals, for example:

• suspend delivery by deleting/disabling AppRole credentials;
• deactivate consumer policy/auth;
• revoke leases/tokens by accessor;
• delete current value versions;
• irreversibly destroy KV metadata only under an explicit destruction action.

Until then, KV revoke should be treated as destructive path deletion, not a general revocation or deactivation workflow.

P0 — Production approval is not yet a complete authorization contract

The resolver accepts resolved, approved, or accepted status and absence of superseded_by. It does not validate action type, lane/stage binding, actor, expiry, allowed fields, operation, approval count, or flex-auth result. dual-control is a catalog label but is not enforced as two approvals.

Tracked local decision mirrors are useful for demos and historical pilots but are too permissive as a steady-state production authority source. Production should require a canonical decision object bound to the exact action and should fail closed when State Hub/flex-auth cannot prove that binding.

Important hardening gaps

P1 — Steady-state authentication is absent

The CLI accepts a token from an environment variable or a mode-0600 bootstrap file. It does not perform OpenBao OIDC, workload/service auth, short-lived issuer exchange, or per-action identity binding. This keeps routine production work dependent on attended external credential bridging.

P1 — Verification is narrower than the intent

KV positive verification checks one field, defaulting to the first. Route readiness also checks only the first field, so a multi-field lane can appear ready while sibling fields are missing. KV negative verification uses a fixed garbage token, not a real unrelated workload identity. Provider behavior and application health are outside the check.

High-risk lane acceptance should verify every declared field, use a real unrelated identity or capabilities proof, capture OpenBao audit request ids, and, where appropriate, call a value-safe provider/application smoke.

P1 — Delivery token lifecycle is implicit

Exec and verification create AppRole Secret IDs and login tokens. Secret ID use counts and token TTL/use bounds limit them, but the code does not revoke the issued token explicitly on success, child failure, interruption, or verification failure. Evidence does not include a safe lease/accessor lifecycle.

P1 — Evidence is informative, not a durable audit workflow

Local JSONL is append-only by convention, not tamper-evident. State Hub posting is best-effort and silently ignored on error. Apply/provision/handoff failures are generally recorded only if a caller adds separate evidence; there is no transaction id joining State Hub evidence to OpenBao audit entries, and no audit command summarizes a lane.

P1 — Lifecycle metadata is not lifecycle automation

Catalog entries require rotation/deactivation descriptions and owners, which is valuable governance metadata. The engine does not execute those plans, manage provider credential overlap, coordinate consumers, maintain compromised or deactivated state, or verify rollback.

Longer-term product gaps

P2 — Service mode

The intent describes a CLI and service API. Only the CLI exists. A service should wait until approval binding, auth, delivery token lifecycle, evidence, and destructive-operation semantics are hardened; exposing today's CLI directly would amplify its pilot shortcuts.

P2 — Runtime tenancy and consumer identity

The catalog can describe many applications and logical owners, but the engine does not authenticate a tenant, resolve claims, isolate concurrent callers, or enforce per-tenant quotas/policies. The current product is multi-application metadata and path orchestration, not a multi-tenant service.

P2 — Backend abstraction

OpenBao-specific behavior is isolated reasonably well, but there is only one subprocess backend. “OpenBao as the initial enforcement backend” remains an architectural option, not a demonstrated portable backend contract.

Current evolution phase

Against the phases in INTENT.md:

1. Bootstrap: implemented and still active.
2. MVP: achieved for the whynot-design npm pilot.
3. Stage separation: implemented in catalog/plan/static policy form, but steady-state stage authentication and stronger production owner binding are incomplete.
4. Hardening: started; existing-mount admission, risk classification, exact-field guards, bounded AppRoles, and fail-closed decisions exist. The P0 and P1 gaps above remain.
5. Service mode: not started.

Recommended next sequence

1. Keep SECRETS-WP-0006-T05 limited to approved metadata apply and explicit per-field, positive/negative verification. Do not provision or revoke the existing shared paths through the current KV lifecycle commands.
2. Fix provisioning transport and merge semantics, with sibling-preservation and process-argument tests.
3. Split KV suspend/deactivate/destroy semantics and make dry-run match live behavior.
4. Replace coarse/local production decision resolution with an action-bound, expiring, dual-control-capable authorization contract.
5. Add steady-state OIDC/service auth and explicit child-token revocation.
6. Strengthen multi-field/readiness and unrelated-identity verification, then correlate evidence with OpenBao audit request ids.
7. Implement rotation state and wrapped/file delivery before designing service mode.

Conclusion

INTENT.md still describes the right destination, but the accurate present tense is a guarded OpenBao CLI MVP with one proven native workload pilot and several reviewed-but-not-live production lane plans. The repository should not yet advertise itself as a service API, complete lifecycle engine, runtime multi-tenant system, wrapped-delivery broker, or production-safe general KV updater.