# 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 `context.approval` marked `approved` with at least two
distinct approver subject ids. Repeated entries from one subject count once.

flex-auth consumes that 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. This package checks that the claim *says* approved with
distinct approvers. It does **not** re-derive the claim's temporal validity,
signature, or supersession state — those belong to `approval-engine` to assert
and to the PEP to verify against the live claim. A PDP re-deriving them from a
caller-supplied blob would be inventing an authority it does not have.