What is the Attested Action Envelope

Where it fits

Static agent facts describe who an agent is and what it is capable of — a claim about identity and capability that holds over time. Receipts describe what an agent did — signed after the fact, once an action is complete. The Attested Action Envelope sits between them: it records a decision taken about a specific action, at a moment in time, before the action runs.

Static agent facts say what an agent is. Receipts say what an agent did. The envelope says what an agent may do, and preserves the refusals. Together the three give a system three tenses of accountable evidence — capability, decision, and history — each independently verifiable, none requiring trust in the party that produced it. In the agent-evidence family the envelope sits alongside receipts (which record what an agent did, after the fact) as the record of what an agent may do, decided before the fact.

The eight fields

An envelope is a JSON object with exactly these eight members. A document with any additional member, any missing member, a malformed action, or an outcome outside the closed set is not an envelope and MUST fail verification.

Canonicalization

The signing input is the JSON serialization of the envelope with the sig member removed, using: keys sorted lexicographically at every level; the compact separators "," and ":" (no insignificant whitespace); UTF-8 encoding. params values must be JSON-serializable. A conformant implementation produces byte-identical canonical bytes for equal envelopes — that determinism is what lets a second, independent implementation of the eight-field format verify sm-aae's envelopes, and vice versa.

Signature

sig is the Ed25519 signature (RFC 8032) over the canonical bytes, hex-encoded. pubkey is the raw 32-byte Ed25519 public key, hex-encoded. A verifier recomputes the canonical bytes and checks sig under pubkey; any mismatch yields failure, and hostile input never raises. verify_envelope is the reference implementation's single verification entry point — structural plus signature check, returning a plain boolean.

The envelope hash and the chain

The envelope hash is the lowercase-hex SHA-256 (FIPS 180-4) of the JSON serialization of the full envelope — including sig — under the same key ordering and separators. A successor envelope's prev_hash must equal the envelope hash of the agent's immediately preceding envelope. Because the hash covers sig, the chain commits to the signed artifacts themselves: swapping a signature anywhere breaks every later link.

envelope {
  agent_id
  action:     { verb, resource, params }
  policy_id                               (the authority the verdict cites)
  outcome:    authorized | denied | conditional
  prev_hash                               (SHA-256 of this agent's prior envelope, or null)
  issued_at                               (RFC 3339, caller-supplied)
  sig                                     (Ed25519 over the canonical body, sig removed)
  pubkey                                  (the signer's raw Ed25519 public key)
}

Verifying a chain

A verifier of an agent's chain — an unordered set of that agent's envelopes — recovers the unique genesis-first ordering, or rejects the set. The reference implementation's order_chain function returns that ordering, or None if the set does not form exactly one intact chain. It rejects:

• a gap — a prev_hash naming an envelope not present in the set, i.e. a deleted or withheld interior decision;
• a fork — two envelopes claiming the same predecessor;
• a foreign-chain splice — a prev_hash reaching into another agent's chain (more than one agent_id present);
• duplicates, or zero/multiple genesis envelopes (more or less than exactly one envelope with prev_hash = null).

An agent cannot quietly drop the one decision it would rather not have on record — doing so breaks the chain's reconstruction, and the break itself is the signal.

What it does not do