The provider's half of the execution boundary, stated once so that native verification is a place a verifier is deployed rather than a product a vendor ships: how a system of record, or the last hop its owner controls in front of it, establishes that a request came from the executor holding a key it issued, that Decionis claimed a single-use grant for this exact intent over these exact parameters, and that the grant has not been presented before, and refuses, effecting nothing, otherwise.
The normative text is the repository's, at docs/authority/verifying-provider.md; this page renders that version. Section 7, the effect receipt, is normative as of this version: the Decionis OpenAPI document carries it, the executor forwards it, and five implementations build one from the same vectors. The key words MUST, MUST NOT, SHOULD and MAY are to be read as in RFC 2119.
A system of record is the only party that can refuse an instruction rather than merely fail to receive it. The profile is that chokepoint written down as something a provider can implement and claim. Passing its vectors demonstrates the procedure; the tier's conditions are the operator's.
| Tier | Who runs the procedure | What it binds | What it covers |
|---|---|---|---|
| Vendor-native | The system of record's own transaction layer. | The bytes; at VP-3, the effect. | Every path into the system: its API, batch, console, people. |
| Owner-native | The last hop its owner controls in front of the system of record (an API layer, a gateway, a sidecar), holding the only credential the system accepts. | The bytes; the effect by reconciliation. | The paths routed through it. |
| Executor-only | Nobody downstream: the executor forwards on a bearer. | The bytes, at the executor. | Agents that hold no other credential, for as long as containment holds. |
A hop at the second tier is a verifying provider in the profile's sense only when the system of record admits no other principal: the hop holds the system's sole credential, and the system is reachable by nothing else, whether by mutual TLS to a certificate only the hop has, or by a private link whose route exists only in the hop's namespace. Otherwise the hop is a network control, and bypass resistance says what those are worth.
ALLOW, and attests to the claim of that grant. Its execution-grant keys are published at https://api.decionis.com/.well-known/decionis-execution-grant-jwks.json.@decionis/agentsafe, or an adopter's process built on it. It signs each dispatch with a key the provider knows by keyid.sha256: over the RFC 8785 canonical form of the agent-safe.intent/1 binding. What every later record names.ALLOW. Claim: the executor's atomic consumption of it immediately before dispatch. Lease: the interval after the claim within which the dispatch must happen; the attestation expires with it.claim_attestation, schema ClaimAttestationClaims in the OpenAPI document), which the executor forwards under x-agent-safe-claim-attestation and signs over. It is issued only once the authority has atomically consumed the grant: it is the authority's proof that the claim happened, and it is not the grant.An implementation claims a level by passing every vector at that level and stating the level and the profile version.
The provider verifies the executor's HTTP message signature (RFC 9421) with its content digest (RFC 9530) and requires the covered components section 5 names. A provider at VP-1 refuses anything the executor did not send. It does not know whether the authority claimed anything.
VP-1, and the provider verifies the authority's attestation against the authority's published keys, checks that the request in hand is the one the attestation describes (grant, decision, intent hash, canonical parameter digest, expiry), and refuses a second presentation of the grant within the lease. A provider at VP-2 refuses what the authority never claimed. This is the level a system of record needs.
VP-2, and the provider signs what it effected, or refused, keyed by the grant and the claim, and returns it with its answer, so the effect plane becomes provider-attested rather than executor-reconciled. Section 7.
Verification proves what the authority issued; the authority's claim is what consumes it; only the attestation of that claim, bound to this request, permits the provider to effect. A grant, a decision or a dossier that a provider verified by signature alone MUST NOT, by itself, authorize an effect. Offline verification, @decionis/verify included, is deliberately stateless and cannot know whether a valid grant was consumed; a provider that effects on verify(grant) alone is replayable by construction.
For a dispatch, the executor sends these headers. The eight components the profile knows, in the order the executor lists them: @method, @path, content-digest, idempotency-key, x-agent-safe-intent-hash, x-agent-safe-grant-id, x-agent-safe-decision-id, x-agent-safe-claim-attestation. The first five are the base. @path is the request path without its query. Any other header the executor sends, such as x-agent-safe-dossier-id, is not covered and MUST NOT influence whether the provider effects.
| Header | Value | Covered |
|---|---|---|
| content-digest | sha-256=:<base64 of SHA-256 over the raw body>: (RFC 9530), the empty body included | as content-digest |
| idempotency-key | the intent-bound idempotency key | always |
| x-agent-safe-intent-hash | the intent hash | always |
| x-agent-safe-grant-id | the grant's id; the attestation's sub | on a dispatch |
| x-agent-safe-decision-id | the decision's id | on a dispatch |
| x-agent-safe-claim-attestation | the attestation, a compact JWS | when the authority attested |
| signature-input | agentsafe=(<components>);created=<unix seconds>;keyid="<id>";alg="ed25519" or alg="hmac-sha256" | the parameters |
| signature | agentsafe=:<base64 signature>: | the signature |
Normative, in this order. The first failing step names the refusal, and a refusal effects nothing.
signature-input, take the text after agentsafe= as the parameters. From signature, take the base64 between the colons after agentsafe=. Either header absent, or not of that form, is SIGNATURE_INVALID_OR_INCOMPLETE.sha-256=:<base64(SHA-256(body))>: over exactly the bytes received, the empty body included, and compare it with content-digest byte for byte. A difference is SIGNATURE_INVALID_OR_INCOMPLETE.SIGNATURE_INVALID_OR_INCOMPLETE. A request may carry a grant header the signature does not cover; such a header proves nothing about the grant, which is why the requirement is on the covered list and not on the headers present.created MUST lie within a window of the provider's clock. The window is the provider's; it SHOULD be no more than 300 seconds each way. Outside it is SIGNATURE_INVALID_OR_INCOMPLETE.keyid MUST name a key the provider issued to, or registered for, the executor, and alg MUST be that key's algorithm: ed25519 for an Ed25519 public key, hmac-sha256 for a shared secret. An unknown key, or an algorithm the key is not for, is SIGNATURE_INVALID_OR_INCOMPLETE.SIGNATURE_INVALID_OR_INCOMPLETE. Verify the signature over the UTF-8 bytes of the base: Ed25519 against the key, or HMAC-SHA256 compared in constant time and only at its full length. A failure is SIGNATURE_INVALID_OR_INCOMPLETE. A read verified at VP-1 alone ends here."@method": <the method, upper case>
"@path": <the request path, without its query>
"content-digest": <the content-digest value>
"idempotency-key": <the header value>
"x-agent-safe-intent-hash": <the header value>
"x-agent-safe-grant-id": <the header value>
"x-agent-safe-decision-id": <the header value>
"x-agent-safe-claim-attestation": <the header value>
"@signature-params": <the parameters, verbatim>x-agent-safe-claim-attestation on . into exactly three base64url parts. Decode the first as a JSON object: alg MUST be EdDSA, typ MUST be decionis-claim-attestation+jwt, and kid MUST name a key in the authority's execution-grant JWKS. Verify the Ed25519 signature, the third part, over the ASCII bytes of the first part, a dot, and the second part, with that key. Decode the second part as a JSON object, the claims. It MUST carry strings iss, sub, decision_id, dossier_id, claim_token_digest and jti, a number exp, and an object binding with strings intent_hash, execution_payload_digest and execution_payload_canonicalization_profile: the claims step 7 compares and the ones a receipt is built from; an attestation without them is not one. iss MUST equal the issuer of the authority the provider trusts, https://decionis.com for Decionis. Any failure is ATTESTATION_INVALID.ATTESTATION_DOES_NOT_DESCRIBE_THIS_REQUEST: sub equals x-agent-safe-grant-id; decision_id equals x-agent-safe-decision-id; binding.intent_hash equals x-agent-safe-intent-hash; binding.execution_payload_canonicalization_profile equals RFC8785/JCS; binding.execution_payload_digest equals sha256: followed by the lower-case hex of SHA-256 over the RFC 8785 canonical form of the body parsed as JSON, where the body MUST be a JSON text that is I-JSON (RFC 7493), with no lone surrogates, no non-finite numbers and no duplicate names, and a request with no body describes no parameters; and exp, in seconds since the epoch, is later than now. The provider MUST canonicalise, never hash the raw bytes: step 1 bound the bytes the executor sent, this step binds the parameters the authority saw, and the two need not be the same bytes. A provider that effects for more than one organisation SHOULD also require org_id to be the organisation this endpoint effects for.sub until exp. If sub was recorded by an earlier acceptance, the refusal is GRANT_REPLAYED. Otherwise the provider records it before effecting. The record MUST be visible to every instance that could effect this grant within the lease: the executor never retries a side effect, so a second presentation is never the executor. This step is not a second single-use authority. The grant was consumed once, at the authority, when the attestation was issued; the step guards the one thing an attestation cannot, a second presentation of that one consumption inside its lease.Accept. Effect exactly once and answer 2xx; a provider at VP-3 answers with its receipt, on a 2xx and on a 4xx of its own alike. Refuse. Effect nothing and answer 4xx, 409 in the reference implementations, with the body {"status":"REJECTED","reason_code":"<code>"}. A refusal MUST NOT be a 5xx: the executor reads 4xx as DEFINITELY_NOT_EXECUTED and finalizes FAILED, and 5xx as UNKNOWN_AFTER_DISPATCH. The response MUST NOT echo the body or the attestation.
| Code | Meaning |
|---|---|
| SIGNATURE_INVALID_OR_INCOMPLETE | Not sent by the executor for this request, or not covering what an effecting provider requires. |
| ATTESTATION_INVALID | Not the authority's attestation. |
| ATTESTATION_DOES_NOT_DESCRIBE_THIS_REQUEST | The authority's attestation, but of another grant, decision, intent, body, or time. |
| GRANT_REPLAYED | The authority's attestation of this request, already accepted once. |
The request was sent by the holder of the named key, for this intent hash, with this body. A copied set of headers, an altered body, or an altered covered header proves nothing.
The authority claimed this grant, for this intent, over these canonical parameters, within a lease that has not ended, and this is the first presentation. A compromised executor can sign a request; it cannot attest to one, because the attestation key is not in the executor. A leaked attestation cannot be presented again inside the lease, and never carried the claim token, only its digest. No instruction effects at the provider that the authority did not claim for exactly these parameters.
The party that effected says what it effected, under its own signature, bound to the grant it effected it under and to the claim it answered, and the authority records that statement with the commit. A dossier at VP-3 carries the provider's signature over the effect, not only the executor's report of it; when the grant named the effect it expected, a receipt whose digest agrees confirms the effect by the provider's key. What VP-2 alone does not give: that the effect matched the parameters.
The attestation lets the provider refuse what the authority never claimed. The receipt closes the other direction: after effecting, or refusing, a request it accepted at step 8, the provider signs what it did, bound to the grant it acted under and the claim it answered, and the authority records it with the commit. Until this existed, the exactly-once and the effect were the executor's word, checked by reconciliation; with it, the party that effected says so.
The Decionis OpenAPI document: the schema EffectReceiptClaims, the effect_receipt field of ExecutionFinalizeRequest and ExecutionFinalizeResponse, and the operations under /v1/execution/provider-keys. This section states what a provider does.
Key. The provider signs receipts with an Ed25519 key of its own. The organisation registers the public half with Decionis (POST https://api.decionis.com/v1/execution/provider-keys: kid, issuer, algorithm EdDSA, the OKP JWK), and the private half never leaves the provider. Revocation is a timestamp at the authority, never a deletion, so a receipt recorded under a retired key stays explicable. Rotation is a new kid.
Receipt. A compact JWS whose protected header is exactly alg EdDSA, kid the registered key id, typ decionis-effect-receipt+jwt, and whose claims are:
| Claim | Meaning |
|---|---|
| iss | The provider, exactly as registered with the key: a receipt under a key with another issuer does not verify. |
| aud | The authority's issuer, https://decionis.com for Decionis. |
| sub | The grant id: the attestation's sub. |
| decision_id, dossier_id | Copied from the attestation. |
| claim_token_digest | Copied from the attestation: which claim of the grant this receipt answers, which the authority ties to the claim token being finalized. |
| attestation_jti | The attestation's jti. |
| intent_hash | The attestation's binding.intent_hash. |
| idempotency_key | The request's, when the provider records it; MAY be omitted. |
| effect.status | EFFECTED, REFUSED, or INDETERMINATE. |
| effect.reference | The provider's own record: a ledger entry, a transaction id; MAY be omitted. |
| effect.digest | sha256: over the effect in the terms the grant's expected_effect_digest names, when the grant carries one and the provider can compute it; MAY be omitted. |
| effect.effected_at | RFC 3339. |
| iat, jti | As in RFC 7519; jti unique per receipt. |
The claims the receipt binds are the attestation's, which is the point: the provider copies sub, decision_id, dossier_id, claim_token_digest and jti from the attestation it verified at step 6 and cannot have obtained them any other way, since the claim token itself never reaches it. The header and the claims MUST be serialised in RFC 8785 canonical form before base64url encoding, so that every implementation signs the same bytes for the same receipt and the vectors can hold them to it. The receipt travels in the response header x-agent-safe-effect-receipt on every response to a request the provider accepted at step 8: the 2xx of an effect and the 4xx of the provider's own refusal alike. A signed refusal is evidence too.
@decionis/agentsafe reads nothing in the receipt. It forwards the header's value verbatim as effect_receipt in finalize-token, whatever the attempt's outcome, when the value has the shape of a compact JWS and is at most 20000 characters; otherwise it drops it, since the authority refuses a malformed body and the commit outcome would be lost with it.
It verifies the signature under the key the organisation registered for kid, requires iss to be the issuer registered with that key and aud to be itself, and checks that the receipt describes the finalization in hand: sub is the grant's jti, decision_id and dossier_id are the grant's, claim_token_digest is the digest of the claim token being finalized, and intent_hash, when present, is the one the grant bound. It records the receipt in the commit evidence as presented, verified or not, with one of six verification codes, and reports the verdict in the finalize response. When the grant carried expected_effect_digest and the verified receipt carries effect.digest, the receipt is read as Protocol 1.1 SIGNED_RECEIPT effect evidence with the provider key as observer, CONFIRMED only when the digests agree, the status is EFFECTED and the outcome is COMMITTED.
What it changes is the evidence, not the commit. A receipt authorises nothing and consumes nothing: a receipt for a grant the authority never claimed is recorded as a binding mismatch, and a receipt cannot be presented in place of an attestation. The executor's effect plane keeps reconciling its own observation; the receipt is the provider's statement beside it, not a replacement for it.
One JSON file per case, each self-contained. A request vector carries the provider's settings, the executor keys it knows, the authority JWKS, and a sequence of requests with the outcome the procedure MUST reach; a receipt vector carries what a provider signs after effecting and the exact canonical bytes every implementation MUST produce before signing. Every vector is run by five implementations that must agree: the reference in the executor's package, Go for Envoy and Kong, Java for Spring and Apigee, Rust with a tower layer, and .NET with ASP.NET Core middleware.
Twenty-five request cases at VP-1 and VP-2 and four receipt cases at VP-3, public halves only, at a fixed instant. payload-changed-after-claim is the case the profile exists for: the amount raised after the claim, the executor's signature valid over the changed body, the authority's attestation valid over the original parameters, and the two digests disagreeing at the provider. A receipt vector pins the canonical header.payload; an implementation signs it with a key of its own.
verifyProviderRequest and signEffectReceipt in @decionis/agentsafe, held to the same 100% mutation gate as the executor's own signature verification: a mutant that accepts what it should refuse is a provider that effects what the authority never claimed, and a mutant that copies the wrong claim into a receipt binds the provider's signature to the wrong grant.
A Go verifier behind Envoy's ext_authz filter, the same package as a Kong Gateway plugin, a Java 17 library with a servlet filter for Spring that also serves an Apigee callout, a Rust crate with a tower layer for axum and hyper, and a .NET library with ASP.NET Core middleware. None shares code with the executor; each passes every vector, request and receipt, and each carries a receipt builder for the layer that effects, so the hop an enterprise already has becomes a verifying provider without the system of record learning anything new.
To claim conformance, an implementation states the profile identifier and version, the level, and that every vector at that level passes with the outcomes the vectors name. It SHOULD state the tier at which it is deployed, since the vectors cannot.
keyid of its choosing; the executor names it with DOWNSTREAM_SIGNING_KEY_ID. Rotation is a new keyid; the old one is withdrawn once no dispatch can still carry it.kid, refresh at most once per bounded interval before refusing. The authority rotates with overlap, so a verifier keeps the previous key for the overlap.exp is authoritative and short, the length of the lease the authority named in claim_lease_expires_at; the created window is defence in depth.exp, shared by every instance that can effect. Since a lease is tens of seconds, the store is small.ext_authz needs with_request_body with allow_partial_message: false.kid is recorded as EFFECT_RECEIPT_KEY_UNKNOWN and confirms nothing. An authorization hop that runs the procedure in front of the system of record (Envoy, Kong) cannot sign a receipt: it answers before the effect; the receipt is the effecting layer's.hmac-sha256 makes VP-1 a statement the provider could have made itself; it is acceptable within one trust domain, and the attestation at VP-2 remains the authority's either way. For a system of record, prefer ed25519.The profile identifier changes only on an incompatible change to the procedure or the vectors; the version changes with the text.
The normative text lives in the Agent-Safe Pipeline repository at docs/authority/verifying-provider.md, beside the executor that produces what the profile verifies. Released versions of that repository, the profile included, are archived under the Zenodo concept DOI 10.5281/zenodo.22312955; cite the version DOI of the release that carries the text you implemented. The pages on the same procedure from the executor's side are execution binding, claim and finalize, evidence, and bypass resistance.