flex-auth/docs/secrets-engine-action-vocabulary.md

secrets-engine action vocabulary

Status: published Date: 2026-09-06 Workplan: FLEX-WP-0021-T01 Source: secrets-engine docs/gated-actions.md, read out of their cli.py Package: secrets-engine.catalog-lane.lifecycle v1 (examples/secrets-engine/policy_package.md)

FLEX-WP-0021-T01 required secrets-engine to name this list rather than letting flex-auth derive it, and made an inferred action a blocker rather than a default. That was not ceremony: four of the twelve would have been inferred wrongly, and one action that looks obvious does not exist at all.

The example vocabulary secrets-engine.lifecycle/v1 this replaces is not this list and was never published (FLEX-DEC-2026-005).

Request shape

Field	Value
resource.type	secret-catalog-lane
resource.system	secrets-engine
resource.id	the catalog id
resource.attributes.stage	deployment stage
resource.attributes.fields	sorted; populated for provision, rotate, verify, exec; empty list otherwise
resource.attributes.policy_targets / auth_targets	sorted
context.approval	approval claim; required for destroy only

Empty lists are sent rather than omitted or guessed.

The twelve actions

Action	Reaches OpenBao	Notes
apply	yes	apply --dry-run does not reach the gate
provision	yes	carries fields
rotate	yes	carries fields
verify	yes	carries fields
handoff	yes
wrap	yes
exec	yes	carries fields
deactivate	yes	also the gate for the CLI verb revoke
suspend	yes
destroy	yes	dual control; not reachable live yet
compromise	no	local delivery overlay only
reactivate	no	local delivery overlay only

Four things an inferred list gets wrong

1. revoke is not an action. The CLI verb revoke gates as deactivate, which is also reached from lifecycle deactivate. There is no revoke value and one must not be added. The package asserts this (test_revoke_is_not_an_action → unknown_action).

2. destroy is defined but not reachable live. Its handler raises before the gate, so only --dry-run renders. It stays in the vocabulary as the dual-control case; no live destroy Check arrives until SECRETS-WP-0007-T04 lands. Keeping it in the package now means the rule is reviewed and fixtured before the path opens rather than in the same change that opens it.

3. compromise and reactivate touch no OpenBao object. They mutate local delivery-overlay state only. They are gated because they change delivery posture, not because they write to the backend — a distinction worth recording, because a reviewer looking for backend writes would otherwise read their presence as a mistake.

4. Seven CLI surfaces never reach the gate and must not appear in the package: plan, apply --dry-run, route, audit, catalog, decision inspect, and evidence.

apply --dry-run is the one flex-auth cannot enforce. apply is an action and apply --dry-run is not, but both would arrive as apply — the distinction is invisible to the PDP. What keeps them apart is that the PEP does not call the gate for a dry run. flex-auth records the limit rather than implying a control it does not have.

Dual control on destroy

destroy requires an approval-claim on context.approval, issued by approval-engine, whose valid_now is true. That is the whole check.

The shape is approval-engine/schemas/approval_claim.schema.json. valid_now is a summary predicate — true only when the object is approved, inside its validity window, and not consumed, superseded, revoked, or expired — and the distinct-approver threshold is folded into it. A claim that failed the threshold returns reason_code: insufficient_approvers.

flex-auth consumes the claim as an input claim and never mutates it (security-layer-model_v0.7 §9.4). Per FLEX-DEC-2026-006 the approval fact is approval-engine's step-1 artifact and the decision is step 2; the PEP validates across both.

The package does not count approvers, re-derive validity/freshness/ signature/supersession, or compare binding.pdp_digest. Counting approvers is the duplication the split removes (GH-DEC-2026-005); the compensating property is reconstructability at the issuer under §9.6, which is approval-engine's. The digest comparison is real and preferred but the request digest is computed after policy evaluation, so a Rego rule cannot see it — it belongs in the PEP.

Correction, 2026-09-06

The first published rule required context.approval.status == "approved" and counted context.approval.approvals[].subject_id. Neither field exists: the claim's field is state (and valid, not approved, is the operative value), and it carries no approver list. The rule was unsatisfiable — every live destroy would have denied dual_control_required regardless of the approval. It failed closed, so it was never a hole, but it was a policy written against an invented shape. Corrected the same day.

Closed: pdp_digest is the mapping, and there will be no table

approval-engine declined to publish an action/target mapping (their commit 6d0dfc8) and was right to. A PIP asserting that secrets.kv.destroy means destroy would author policy semantics over two vocabularies it does not own — the same layer boundary flex-auth invoked against its own composed object — and the failure is asymmetric: a wrong mapping silently accepts a claim approved for a different action, which is worse than no mapping.

claim.binding.pdp_digest == decision.binding.request_digest

is the mapping, and it is stronger than a name table because it does not translate: it compares the PDP's own digest to the PDP's own digest, in one vocabulary, with nobody asserting equivalence.

binding.pdp_digest is now always present and may be null, so its absence is a stated fact rather than a missing key. Null means the approval was not issued against a PDP decision — it proves an approval exists, not that it was issued against the request being decided.

The destroy gate is therefore: pdp_digest non-null and equal, enforced by the PEP, before SECRETS-WP-0007-T04 makes destroy reachable.