secrets-engine/workplans/SECRETS-WP-0006-catalog-lane-adoption.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated
SECRETS-WP-0006	workplan	Adopt concrete OpenBao credential lanes from ops-warden	infotech	secrets-engine	active	codex	custodian	2026-08-21	2026-08-21

SECRETS-WP-0006 - Adopt concrete OpenBao credential lanes from ops-warden

Goal

Move concrete, OpenBao-backed credential workflows from ops-warden's interim proxy into the secrets-engine catalog and operating surface without moving secret custody out of OpenBao or misassigning generic routing and identity capabilities to this repo.

The intake originates in ops-warden message cbd312f8-347e-44cc-933b-9712e2036646 after earlier requests on 2026-08-11 and 2026-08-15.

Scope decision

Accept these concrete OpenBao KV lanes for catalog admission and staged operation:

• issue-core-ingestion-api-key;
• reuse-surface-hub-write-token;
• openrouter-llm-connect;
• forgejo-admin-api-token;
• email-connect-transactional.

Do not create catalog entries for these generic or non-owned routes:

• openbao-api-key remains a generic credential-routing template. Concrete workload credentials beneath it may become catalog lanes, but the template is not itself a secret lane.
• key-cape-oidc-login remains owned by key-cape/Keycloak. secrets-engine may consume OIDC identity for OpenBao authentication, but it does not own login, MFA, or identity-token issuance.

The current implementation is generic at the catalog level for KV mount/path/fields, and secrets-engine exec supports exec-env plus the npm-specific npm-config adapter. The remaining delivery-mode names are not all exec adapters: read-check is verification, approle-login is auth-capability handoff, and exec-file/wrapped are not yet implemented by exec.

Design constraints

• OpenBao remains the custody, policy, lease, and audit backend.
• No raw value, token, password, wrapped token, AppRole material, or accessor is written to Git, State Hub, chat, prompts, workplans, or normal logs.
• Catalog adoption does not by itself authorize production mutation or value access. Each production lane needs a resolved approval and a reviewed live apply/verification plan.
• Existing workload delivery must not be displaced. ESO/Kubernetes delivery and provider-side rotation remain owned by their current runtime and provider owners until an explicit migration is approved.
• High-risk lanes must retain exact consumer, field, rotation-owner, denial, and revocation metadata.
• The production stage role currently manages owner-scoped paths on the secret mount, while these lanes use the existing platform mount. Admission must not silently broaden the stage role or attempt to create that mount.

Confirm capability and ownership with ops-warden

id: SECRETS-WP-0006-T01
status: done
priority: high

Completed 2026-08-21. Replied in the existing thread with State Hub message 7fb0c2ce-be41-4a1d-95b0-e2cdd97d5718, marked the inbound message read, and recorded decision ae676382-1826-4e04-aa4e-bb77990c7a0d. The reply accepted the five concrete KV lanes, declined the generic OpenBao route and key-cape login route, corrected the six-delivery-mode interpretation, and kept interim proxies in place pending per-lane verification.

Reply in the existing State Hub thread with the accepted five-lane scope, the two declined generic/non-owned routes, and the delivery-mode correction. Accept ops-warden's offer of a PR-shaped non-secret metadata contribution for the five concrete lanes.

Done when the reply is posted, the inbound message is marked read, and this decision is recorded as non-secret State Hub evidence.

Define admission contract for existing production lanes

id: SECRETS-WP-0006-T02
status: done
priority: high

Completed 2026-08-21. Added explicit mount_management, delivery_auth, and workload_delivery semantics, with the operating contract documented in docs/catalog-admission.md. Existing mounts and externally managed delivery auth now render non-mutating checks; apply cannot create or rewrite them. Existing workload delivery remains independent metadata, while an optional engine-managed AppRole is a separate approval-gated native delivery surface.

Define how a catalog entry represents a lane whose KV mount already exists and whose workload delivery is ESO/Kubernetes rather than a secrets-engine-created AppRole. Separate these concepts where needed:

• existing-mount versus engine-managed mount;
• workload delivery versus agent/operator exec delivery;
• catalog/verification metadata versus engine-managed consumer auth;
• provider-side rotation owner versus OpenBao value update workflow.

Acceptance:

• Dry-run cannot propose creating or broadening the shared platform mount.
• A lane can retain its existing workload auth/delivery while optionally exposing an approved exec-time adapter.
• The production stage role is not broadened by implication.

Review and import the five catalog entries

id: SECRETS-WP-0006-T03
status: progress
priority: high

Progress 2026-08-21: the offered contribution did not arrive, so drafted all five entries from ops-warden playbooks and the authoritative railiance-platform CCRs. Sent message ceace632-2332-46d8-a2b3-1714fbfa7e2c requesting line-by-line confirmation of coordinates, fields, consumers, lifecycle owners, and proposed native delivery. T03 remains progress until that review returns; interim proxy ownership is unchanged.

Review ops-warden's proposed entries line by line against the schema, canonical security boundary, live route metadata, and owning workload documentation. Correct field lists, mount/path, consumers, delivery modes, approval references, rotation owners, and negative checks before merging.

Acceptance:

• All five files contain non-secret metadata only.
• Generic openbao-api-key and key-cape-oidc-login entries are absent.
• Each entry names an exact lane rather than a provider-wide wildcard.
• Each high-risk lane has explicit rotation and deactivation expectations.

Implement guards and offline verification

id: SECRETS-WP-0006-T04
status: done
priority: high

Completed 2026-08-21: implemented non-mutating existing-mount/auth planning and apply behavior, workload-delivery validation, exact field guards for exec and verification, safe policy/role overrides, route guidance, and focused tests. All five admitted entries load and render kv-mount-check plus an exact-path policy and bounded AppRole plan. Generic/wildcard entries and undeclared fields are negatively covered. Privileged provision, verify, exec, handoff, and live revoke operations now fail closed without a resolved approval. Full verification passes 82 tests.

Implement only the schema/planning/delivery changes required by the admitted entries. Add tests for shared existing mounts, auth/delivery separation, multi-field selection, exact exec-env injection, and rejection of wildcard or generic provider-wide entries.

Acceptance:

• The complete catalog loads and validates.
• Each admitted lane renders a non-mutating guarded plan.
• Negative tests prove no wildcard path, broad policy, undeclared field, or unsupported delivery mode is accepted.
• uv run pytest and git diff --check pass.

Stage live apply and verification

id: SECRETS-WP-0006-T05
status: wait
priority: high

For each lane, obtain the required decision/operator approval before any live OpenBao policy, auth-role, provisioning, rotation, or delivery change. Start with metadata/capability-safe checks and preserve the current ops-warden proxy until native positive and negative verification succeeds.

Acceptance per lane:

• Approval is resolved and linked.
• Existing workload delivery remains healthy.
• Positive access and unrelated-consumer denial are proven without reading a value into evidence.
• Rollback/revocation steps are recorded.

Reconcile routing ownership and retire interim proxies

id: SECRETS-WP-0006-T06
status: wait
priority: medium

After a lane is natively ready, update the ops-warden delegation register and safe next action for that lane. Retire interim proxy operation lane by lane, not as a seven-lane batch.

Acceptance:

• Native readiness is evidenced before the proxy is retired.
• ops-warden remains the routing front door and does not vend non-SSH secrets.
• The generic OpenBao route and key-cape login route retain their correct owners.

Exit criteria

• The five concrete OpenBao lanes have reviewed catalog entries and guarded offline plans.
• Live ownership moves only for lanes that pass approved positive/negative verification.
• The two generic/non-owned routes are not mislabeled as secrets-engine lanes.
• No secret material is recorded in repository or coordination evidence.