Step attestation
Included from Basic tier
A manual step is a step a human performs inside a run — a console, a
portal, a vendor UI, a registrar, a change board, or a command — stated in
advance in the action file (manual:, opschain docs orchestration) and
rendered from the run's facts. The run holds at the step until a human
answers it: an attestation (what was done, with typed evidence) lets
the run continue; a refusal (with a reason) fails the step by name, and
its on_error: applies. An unattested step past its timeout fails. Every
production change is then exactly one of: an automated step, an attested
step, or a break-glass record (opschain docs resources/breakglass_record).
A step attestation is that answer, stored with the run: who answered it (a principal id), when, the activity and command exactly as the run rendered them, the evidence and its class, the note or the reason, and the outputs the attester filled for later steps.
Served by StepService on /api/v2 — AttestStep, RefuseStep,
ListStepAttestations (opschain docs api-v2) — and
opschain runs attest|refuse (opschain docs cli/runs-attest,
opschain docs cli/runs-refuse); opschain runs show lists a run's manual
steps with their answers. Answers live in the server's store — PostgreSQL
or SQLite — and, in the local lane, in the home's store.
The v2 OpenAPI document declares this resource's schemas
(StepAttestation, ManualStep, ManualEvidenceDemand); the
resource-field coverage gate holds this page to them.
Attributes (StepAttestation)
Timestamps are RFC3339 in UTC.
| Field | Type | Meaning |
|---|---|---|
id | string | The answer's id (UUIDv7). |
run_id | string | The run (change) the manual step belongs to. |
step_id | string | The manual step. |
step_path | string | The step's full path in the run's tree. |
outcome | string | attested or refused. |
principal_id | string | The answering principal's id — never a username. On a server with no users (the SQLite store) it reads anonymous; in the local lane, local. |
answered_at | timestamp | When the answer was recorded. |
title | string | The step's title as rendered for this run. |
activity | string | The activity as rendered for this run — what the human was asked to do. |
command | string | The command as rendered, when the activity is a command. |
where | string | Where the activity is performed (a portal, a console, an account), as rendered. |
evidence_class | string | The strongest evidence kind present: reference, command, file or statement. |
evidence | array | The evidence items (the break-glass record's BreakglassEvidence shape, opschain docs resources/breakglass_record), the statement always present. |
note | string | The attester's note, or the refusal's reason (required for a refusal, at most 4000 bytes). |
outputs | map | The outputs the attester filled — every output the step declares, single-line values of at most 4096 bytes — published as the step's outputs (${{ steps.<name>.outputs.<key> }}). |
correlation_id | string | The chain the answer's event is on: the run's (opschain chains show <id>). |
Manual step (ManualStep)
ListStepAttestations answers a run's manual steps:
| Field | Type | Meaning |
|---|---|---|
step_id | string | The manual step's id. |
step_path | string | Its full path. |
state | string | pending (not yet reached), awaiting_attestation, attested, refused, timed_out, or the step's own state when it never reached waiting (skipped, cancelled, aborted). |
title | string | The declared title, as rendered once the step is reached. |
activity | string | The declared activity, as rendered once the step is reached. |
command | string | The declared command, as rendered. |
where | string | Where the activity is performed, as rendered. |
evidence | array | The evidence the step demands (ManualEvidenceDemand, below). |
attester_principals | array | Principal ids that may attest; with attester_groups empty too, every holder of the attest grant may. |
attester_groups | array | Groups whose members may attest. |
capabilities | array | Capability grants the attester must hold, each an execute grant on <run node>/attest/<capability>. |
outputs | array | The outputs the attestation fills. |
waiting_since | timestamp | When the step entered waiting. |
deadline | timestamp | When an unattested step fails (waiting_since plus the step's timeout:, else the server's step timeout). Set while it waits. |
attestation | object | The answer (StepAttestation), once given. |
can_attest | bool | Whether the caller may answer this step — attest or refuse it: exactly the decision AttestStep and RefuseStep make (below, "Who may"), taken from the caller's grants without a store read. False for an agent, a service account or a step's credential. It says nothing about the step's state: a step not awaiting attestation is still refused by state. |
The response also carries the evidence policy the answer's files are held to, so a form can refuse a file before uploading it:
| Field | Type | Meaning |
|---|---|---|
evidence_max_bytes | int64 | The per-file budget in bytes: breakglass.evidence_max_mb (a value outside 1–512 is ignored), 10 MB (10485760) when unset. |
evidence_types | array | The accepted media types: breakglass.evidence_types, lower-cased, a value without a / dropped; the five defaults when unset. A step's accept: narrows them further. |
Evidence demand (ManualEvidenceDemand)
| Field | Type | Meaning |
|---|---|---|
kind | string | reference, command, file or statement. |
name | string | The item's name, unique within the step. |
required | bool | The attestation is refused without it. A refusal never needs declared evidence. |
command | string | A command item's read-only check, as rendered. The attester supplies only its output; the command and the expect are the action author's, sealed with the action's version. |
expect | string | What the output must contain — a substring, or /a regular expression/. An output that does not satisfy it is refused. |
accept | array | A file item's accepted media types, narrowing the server's evidence policy. |
Evidence
Evidence has four kinds, each honest about what it proves — the same
kinds, shape and policy as a break-glass record: a reference the external
system minted (the strongest: it can be matched exactly against the
system's own log), a command check whose output satisfied its expect, a
file — a screenshot or an export, stored as an artifact on the run's node
and digest-sealed on the answer (weak: a screenshot proves presence, not
correctness) — and the attester's statement, always present. An
attestation on a statement and a screenshot is recorded as exactly that.
An evidence file is uploaded first (ArtifactService.UploadArtifact on
the run's node; opschain runs attest --evidence does it for you) and is
bounded by the same two stored settings as break-glass evidence —
breakglass.evidence_max_mb (default 10) and breakglass.evidence_types
(default image/png, image/jpeg, application/pdf, application/json,
text/plain), opschain docs settings-reference — narrowed by the step's
accept:. The server reads the stored artifact's digest, type and size
(never the caller's word) and the first 512 bytes of its content, refusing
by name a file whose content disagrees with its type. Files ride the
artifact store, never the log pipe: a console screenshot can carry a secret
in plain sight — redact before you attach.
Who may
Every verb is deny-by-default, 404-on-deny on the run's node:
- read (
ListStepAttestations) — read on the run's node. - attest and refuse (
AttestStep,RefuseStep) — read on the run's node and execute on its<node>/attestrule path; then, answeredpermission_deniedby name, an execute grant on<node>/attest/<capability>for every capability the step declares, and — when the step namesattesters:— the caller is one of its principals or a member of one of its groups.
Attesting and refusing are human verbs: an agent, a service account or
a step's credential is refused by name (permission_denied, "attesting or
refusing a manual step is a human verb"). continue, approve and
--approve-all never answer a manual step.
Events
An attestation writes audit:runs:attested, a refusal
audit:runs:refused — on the run's chain at the step, in the same
transaction as the answer, the step's transition and its outputs, carrying
principal ids only (opschain docs events). A refusal also fails the step
with manual step refused by <principal id>: <reason>; a timeout fails it
with manual step <path> was not attested within its <timeout> timeout.
Attested steps join the governed-activity export and the coverage query as
kind attested_step (opschain docs resources/governed_activity).
Retention
An answer ages out on the evidence ledger's horizon
(retention.evidence_ledger_days, default 730 days), archived with its
evidence items before deletion; every artifact it names as evidence is kept
while the answer is (opschain docs retention).
Postures
- Local lane (
--local, or no server targeted): the attached run prints the rendered activity and the verbs that answer it, and holds;opschain runs attest --local(orrefuse) from another terminal records the answer in the home's store under the lane's one implicit principal (local), its files in the home's artifact store with the default budget and types, and the attached run picks it up. The CLI says a local answer reaches a server only through the governed-activity export. - Server on the SQLite store: manual steps hold and answer;
references, command evidence and statements work; evidence files need
the PostgreSQL store's artifacts and are refused by name. This posture
has no users, so
principal_idreadsanonymous. - Server on PostgreSQL: everything on this page.
Not yet
approval: on a manual step — an approval-policy hold on one step — is
refused by name in this release; an approval policy matching the action
holds the whole run before it starts (opschain docs change-governance).
What changes it
- A run reaching a manual step holds it (
awaiting_attestation). opschain runs attest/AttestSteprecords an attestation; the run continues.opschain runs refuse/RefuseSteprecords a refusal; the step fails.- The step's timeout passing fails an unattested step (no answer is stored).
- Retention ages out an answer past the evidence ledger's horizon.