verify_receipt
Verify a CodeRifts signed chain-receipt you ALREADY HOLD: cryptographic authenticity (signature + key id), body binding, and — when lifecycle indices are available — whether it is currently valid authorization (not expired, superseded, or revoked) for a stated operation/target.
Use this when:
You already obtained a chain_receipt / receipt token from a prior preflight (or CI artifact) and are about to act (merge/deploy) under that receipt.
A contract-gate or policy requires offline/online proof that the receipt is authentic for this change before proceeding.
You must distinguish "signature ok" from "currently authorized" (stale or superseded receipts must not be treated as live approval).
Do not use when:
You do not have a receipt yet — call coderifts.preflight_change_set first.
You need a NEW decision for a changed base→head set — preflight again; verify_receipt does not re-diff specs.
The receipt you hold binds a different operation or target than the one you are about to perform — call coderifts.preflight_change_set with context.operation set to that operation (a merge receipt does not authorize a deploy); verify_receipt cannot re-scope or re-issue a decision.
You only need human-readable history of an old decision_id without a receipt token — use coderifts.get_decision_details.
The change set itself is unknown or incomplete — fix the change set and preflight; do not "verify" a placeholder.
Inputs: receipt token (required); target_id = decision_result.artifact_digest — required for an authorization verdict; omitted → target_not_stated. Optional intended context (operation, environment, fingerprint, audience, repository/branch/pull_request, base/head) and the body_hash-bound decision_result envelope. 30s clock-skew leeway on expiry. A 0s grace for declared destructive production operations is defined in the policy but is unreachable today: the intended-context schema has no destructive field, so nothing can declare one and the 30s leeway always applies. Returns { valid, status, currently_authorized (bool|null), reason, payload, authz_* }. Branch on currently_authorized; null = not evaluated.
When a decision envelope is also in hand (e.g. from a prior preflight), its control_envelope.next_agent_step (if present) is structured remediation guidance the agent MAY follow after a non-CONTINUE decision — still branch on execution_action; next_agent_step is suggestion, not permission.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Intended base commit/ref SHA the receipt must match (signed-wins vs envelope.base) | |
| head | No | Intended head commit/ref SHA the receipt must match (signed-wins vs envelope.head) | |
| token | Yes | The chain receipt token (base64url(body).base64url(signature)) | |
| branch | No | Intended branch the receipt must bind (place binding; optional) | |
| audience | No | Intended audience — must match the receipt | |
| operation | No | Intended operation the receipt must authorize (conventional: merge|deploy|tool_call|publish). Triggers authorization evaluation when non-empty; supply decision_result for full scope binding. | |
| target_id | No | REQUIRED to authorize under a held receipt. Set it to decision_result.artifact_digest — the digest of the artifact the receipt was issued for, which you already hold in the decision_result you are passing. The server does NOT derive it for you: it carries YOUR intended apply-site, and taking it from the envelope would compare that document against itself. Omit it and the answer is currently_authorized false with authz_reason target_not_stated and authz_status VERIFIED_TARGET_NOT_STATED — a missing input, distinct from target_mismatch, which means the receipt covers a different target. | |
| repository | No | Intended repository the receipt must bind (place binding; optional) | |
| environment | No | Intended environment (e.g. production) — must match the receipt | |
| fingerprint | No | Intended change fingerprint — must equal the receipt fp | |
| pull_request | No | Intended pull-request id the receipt must bind (place binding; optional) | |
| decision_result | No | The body_hash-bound decision envelope (carries operation/target/decision). Required for a meaningful AUTHORIZATION evaluation of scope; without it, intended context alone fails closed on authorization (currently_authorized false) while signature status remains independent. Full schema: https://coderifts.com/schemas/decision-result.v1.consumer.json. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| valid | Yes | true iff status is VERIFIED_CURRENT or RETIRED_KEY_VALID_AT_ISSUE | |
| reason | No | ||
| status | Yes | ||
| payload | No | ||
| authz_note | No | Present when no intended context supplied: status reflects signature+expiry only | |
| authz_state | No | Lifecycle state from isCurrentlyAuthorized when authorization is evaluated (optional; omitted when currently_authorized is null) | |
| authz_reason | No | When currently_authorized=false: the deny reason (operation_mismatch, decision_not_allow, superseded, expired, target_mismatch, environment_mismatch, …) | |
| authz_status | No | Authorization-level status (VERIFIED_WRONG_ENVIRONMENT / VERIFIED_SUPERSEDED / VERIFIED_SCOPE_MISMATCH / …) | |
| caller_value | No | Caller claim that differed from the signed envelope | |
| signed_value | No | Signed envelope slot when signed-wins fail-closed (source_binding_mismatch) | |
| authz_reasons | No | Every violation found; the first is authz_reason. [] when authorized. Fix all of them before re-verifying. | |
| binding_level | No | place_and_content | content_only — forensic, not a second verdict | |
| correlation_id | No | Route-owned trace id, set by the route itself rather than by correlation middleware; always a non-empty string on 200 | |
| currently_authorized | Yes | Whether the receipt currently authorizes the intended operation/target/fp (§106). null means authorization could not be evaluated (e.g. no intended context) — not unauthorized and not authorized. |