Watch di lesson video: Securing AI Agents with Cryptographic Receipts
(Lesson video and thumbnail go add by di Microsoft content team after merge, e go follow di lesson 14 / 15 pattern.)
Dis lesson go cover:
After you finish dis lesson, you go sabi how to:
Imagine say you deploy AI agent for Contoso Travel. Di agent dey read customer request, call flights API check options, and book seats for customer side. For last quarter, di agent process 50,000 bookings.
Today auditor don show. Dem ask simple question: “Show me wetin your agent do.”
You give dem your log files. Auditor check dem and ask harder question: “How I go sabi say these logs no get edit?”
Dis na di audit-trail wahala. Most agent deployment today dey use:
None of these fit answer auditor question without forcing auditor to trust person (you, your cloud provider, your database vendor). For internal work, that trust dey okay. For regulated workload (finance, healthcare, anytin under EU AI Act), no fit work.
Cryptographic receipts reduce dis wahala by making signed statement independently verifiable. Auditor still need reason outside this matter to trust the signing key and di component wey make di statement. Embedded key show self-consistency, no issuer identity or enforcement location.
Receipt na JSON object wey record wetin agent do, sign with digital signature.
flowchart LR
A[Agent invokes a tool] --> B[Build receipt payload]
B --> C[Canonicalize JSON RFC 8785]
C --> E[Ed25519 sign canonical bytes]
E --> F[Receipt with signature]
F --> G[Auditor verifies offline]
G --> H{Signature valid?}
H -- yes --> I[Signed statement is intact]
H -- no --> J[Receipt rejected]
Minimal receipt look like dis:
{
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": "sha256:a3f9c1...",
"result_hash": "sha256:7b2e1d...",
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 47,
"previous_receipt_hash": "sha256:9d4e6a...",
"signature": {
"alg": "EdDSA",
"sig": "c5af83...",
"public_key": "8f3b2c..."
}
}
Three properties dey do di work:
Signature. Receipt signed by agent gateway using Ed25519 private key. Anybody with di right public key fit verify di signature offline. Relying party must pin dat key or resolve am from trusted registry outside di receipt. If anybody tamper with any signed field, signature go spoil.
Canonical encoding. Before signing, receipt serialized using JSON Canonicalization Scheme (JCS, RFC 8785). E make sure two implementations wey produce same logical receipt go produce byte-identical output. Without canonicalization, different JSON serializers go produce different signature for same content.
Hash chaining. The previous_receipt_hash field connect each receipt to di one before am. If person remove or reorder receipt, e go break di sequence. To detect truncation or signer-controlled rewrite, you need pinned current chain head, independently witnessed checkpoint, or authenticated closed-population commitment.
Together these properties give three guarantees:
You no need special library to produce receipt. Cryptographic primitives dey widely available and di logic na small Python lines.
Hands-on exercises for code_samples/18-signed-receipts.ipynb go show di full flow. Source-controlled code_samples/18-signed-receipts.execution-receipt.json record exact notebook hash, Python environment, cell count, and checks from latest clean run without changing lesson outputs. Summary version:
import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize # RFC 8785 canonical JSON
def b64url_nopad(data: bytes) -> str:
return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
def sha256_canonical(obj) -> str:
"""SHA-256 of a Python object's JCS-canonical JSON form."""
return f"sha256:{hashlib.sha256(canonicalize(obj)).hexdigest()}"
# Generate or load a signing key (in production, store in a key vault)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
TRUSTED_PUBLIC_KEYS = {b64url_nopad(bytes(verify_key))} # pinned out of band by the verifier
# Build the receipt payload (no signature yet)
tool_args = {"origin": "SYD", "destination": "LAX"}
tool_result = [{"flight": "QF11", "price": 1850, "stops": 0}]
payload = {
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": sha256_canonical(tool_args),
"result_hash": sha256_canonical(tool_result),
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 0,
"previous_receipt_hash": None,
}
# Canonicalize and sign the JCS bytes directly. PureEdDSA hashes internally.
canonical_bytes = canonicalize(payload)
signature_bytes = signing_key.sign(canonical_bytes).signature
# Attach a structured signature object.
receipt = {
**payload,
"signature": {
"alg": "EdDSA",
"sig": b64url_nopad(signature_bytes),
"public_key": b64url_nopad(bytes(verify_key)),
},
}
Dis na di whole signing pipeline. Exercises for notebook go show each step.
Verification na di opposite operation:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import CryptoError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
# Strict: Python's decoder skips characters outside the alphabet and also
# accepts padding, the standard +/ alphabet and non-zero spare bits.
# Re-encoding and comparing accepts only the one unpadded base64url form.
padding = "=" * ((4 - len(s) % 4) % 4)
data = base64.urlsafe_b64decode(s + padding)
if base64.urlsafe_b64encode(data).decode("ascii").rstrip("=") != s:
raise ValueError("not canonical unpadded base64url")
return data
def verify_receipt(receipt: dict, trusted_public_key: str) -> bool:
# trusted_public_key is the issuer's key, obtained from somewhere other
# than this receipt. Never use receipt["signature"]["public_key"] here:
# see "What Receipts Prove (and What They Do Not)" below.
# Fails closed: anything malformed returns False instead of raising.
if not isinstance(receipt, dict) or not isinstance(trusted_public_key, str):
return False
sig_obj = receipt.get("signature")
if not isinstance(sig_obj, dict) or sig_obj.get("alg") != "EdDSA":
return False
sig_b64 = sig_obj.get("sig")
if not isinstance(sig_b64, str):
return False
try:
# Reconstruct the payload that was actually signed (everything except signature).
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
verify_key = signing.VerifyKey(b64url_decode(trusted_public_key))
verify_key.verify(canonical_bytes, b64url_decode(sig_b64))
return True
except (CryptoError, TypeError, ValueError, KeyError, OverflowError):
return False
except Exception:
# An undecodable key or signature, or a payload that cannot be
# canonicalized: fail closed rather than raise.
return False
Dis function dey take receipt and issuer public key, return True if signature valid and False if no valid, including if input malformed. No network call and no verification service: once you get issuer key, verification dey local and offline. Wetin e still need na dat key, wey you gats get from somewhere outside di receipt.
To see tampering detection for action, notebook go show:
tool_args_hash field.Step 4 na wetin worth consider well. That receipt internally consistent: im signature real for im content and for di key e carry, so e verify against dis key inside am. E go fail only when you check am against issuer real key. Step 2 and 3 catch attacker wey no sign am again; step 4 catch di one wey sign again.
Dis na practical demonstration say receipts dey tamper-evident: any change to signed field go break di signature, if you verify with key wey attacker no supply. The signature object dey outside signed bytes, na why di key you verify with gats come from place outside receipt.
One signed receipt protect one action. Chain of receipts protect sequence.
flowchart LR
R0[Receipt 0<br/>genesis] --> R1[Receipt 1]
R1 --> R2[Receipt 2]
R2 --> R3[Receipt 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
Each receipt record hash of receipt before am. To remove receipt 2 quietly, attacker must either:
previous_receipt_hash field (go break receipt 3 signature), ORIf private key dey hardware key vault and verifiers check every receipt with issuer public key, obtained independently (published JWK Set or pinned config value), neither attack dey possible without detection. Publishing key inside receipt no enough: attacker fit re-sign with their own key and embed dat one instead, na dat be fixture 04_resigned_receipt.json.
Notebook go show:
previous_receipt_hash match actual hash of prior receipt.Dis na how you go produce audit trail wey external auditor fit verify with their own pinned issuer keys and chain checkpoints, no need to trust your mutable log store.
Dis na di most important part for dis lesson. Receipts powerful but dem get limit.
Receipts prove three things:
Receipts no prove:
policy_id actually evaluate, or say e go allow dis action if dem check. Receipt record wetin dem claim, no wetin dem enforce.Key inside receipt no be di key you verify with. Dis one come from point 3, and na di only place wey dis difference suppose change your code, no be your understanding. The public_key inside di sample na to make example self-contained. Verifier must no trust am. Anybody fit take receipt, change am, sign with key wey dem generate, embed dat key; e go verify perfectly against itself. Na fixture 04_resigned_receipt.json for sample_receipts/ be dis, and na why verify_receipt above take key as argument instead of read am from receipt. Make sure you get issuer key independently, from JWK Set for Production Checklist below or other anchor you pin before, then verify against dat. Signature checked with key wey come with di same envelope prove only say envelope self-consistent.
Dis boundary important for two reasons:
Common mistake na to assume say “we get receipts” mean “we dey governed.” E no mean so. Receipts na foundation. Governance na system wey you build on top.
Number 3 for above deserve im own section: action receipt talk “dis key sign dis content,” no be “human authorize dis.” For high-risk actions (refunds, deletions, wire transfers), separate approver signature fit lock exact action. To connect dat key to human and confirm human presence still separate work.
Follow-up notebook code_samples/human-authorization-receipts.ipynb add second receipt type, human.approval.v1, inside same envelope shape as lesson receipts (typed payload sign by Ed25519 over canonical JCS bytes, with signature object outside signed bytes). Approver key sign full canonical action and im digest; agent key sign claim wey carry same action digest plus parent_approval_ref, di receipt_hash of approval, same convention as previous_receipt_hash for chain you build above. One verify_chain check both artifacts under separate pinned key registries (approver keys vs agent keys), so code path shared but authorities never.
Property wey dis get, say am clear clear: pinned approver key sign dis exact action, and agent key sign statement wey carry same action digest later. E good evidence, but e no prove say action happen for sure. To control execution, exact approval must reserve and use once for actual executor boundary; unknown provider result must remain unknown, no blind retry. Notebook refusal fixtures test receipt-chain layer:
Each failure dey reject wit one correct reason, so auditor wey dey read refusal fit sabi whether authority don kpom, or the action wey dem claim don change. Verification na only to read and fit do am again: e no dey use the approval or call provider. One different executor need to get strong, atomic replay protection plus clear success, failure, and we no fit talk wetin happen outcomes. The human-approval receipt na one kind educational composition wey dis lesson define, no be receipt type wey draft-farley-acta-signed-receipts define.
Di Python code wey dey dis lesson minimal on purpose so you fit read every line and understand exactly wetin dey happen. For production, you get two options:
Build direktly on top di cryptographic primitives. Di 50 lines wey you see for top dey enough for plenty use cases. PyNaCl (Ed25519) and di jcs package (canonical JSON) na well-maintained and audited libraries.
Use production receipt library. Some open-source projects dey implement di same pattern with added features dem (key rotation, batch verification, JWK Set distribution, integration with policy engines):
draft-farley-acta-signed-receipts, revision 02). Dis lesson flat educational receipt no be like di draft {payload, signature} envelope and dem no present am as conformant implementation. Di draft publish shared conformance suite (agent-governance-testvectors) for implementations wey dey target im wire format.protect-mcp (npm) and @veritasacta/verify (npm) packages dey provide Node-based implementation of receipt signing and offline verification, to wrap any MCP server with tamper-evident audit trail, including held-for-co-sign flow wey pause action dey emit approval receipt wey bind to action digest (WebAuthn-backed for desktop flow), di same approval-receipt pattern as di human-authorization notebook wey dey top.pip install nobulex) provide di same Ed25519 + JCS signing pattern for Python with LangChain and CrewAI integrations, including published cross-validation test vectors and compliance mapping wey dem contribute via OWASP PR #2210.Di decision between rolling your own and using library na like di choice between writing your own JWT library and using tested one: both dey reasonable; di library save time and reduce audit surface; di from-scratch approach go force you understand every primitive. Dis lesson dey teach di from-scratch path so you get foundation for either choice.
Test your understanding before you move to di practice exercise.
1. Receipt dey sign with agent private Ed25519 key. Auditor only get public key. Auditor fit verify receipt offline?
2. Attacker change policy_id field of receipt to claim say dem govern am with more permissive policy. Signature dey over original payload. Wetin happen during verification?
3. Why receipt get tool_args_hash and result_hash instead of raw arguments and result?
4. previous_receipt_hash field dey link each receipt to e predecessor. If attacker silently delete one receipt for middle of chain, wetin go invalid?
5. Receipt verify cleanly. E mean say agent action correct, sound, or policy compliant?
Open code_samples/18-signed-receipts.ipynb and complete all four sections:
Stretch challenge 1: add one extra field wey you choose for receipt schema (like request ID for tracing), update canonical signing logic to include am, and confirm say receipt still fit round-trip through verification. Then change di field after signing and confirm verification fail. Dis one go force you understand how every byte of canonical encoding dey contribute to signature.
Stretch challenge 2: SHA-256-hash two receipts together (concatenate their canonical bytes for deterministic order) and put di resulting digest as new field on third receipt before signing am. Verify say all three receipts still fit round-trip. You don build one step inclusion proof: anybody wey hold di third receipt fit prove say first two exist at signing time without revealing their content. This na di pattern wey selective-disclosure receipts dey use for scale (Merkle commitments, RFC 6962).
Cryptographic receipts dey give AI agents audit trail wey:
Dem no be substitute for input validation, policy enforcement, executor admission, outcome evidence, completeness controls, or identity infrastructure. Dem be foundation for those layers. For regulated or multi-organization workflows, receipts dey make specific issuer statements independently checkable under auditor own trust configuration.
Di most important takeaway: Receipts show say particular key sign particular content. Timestamp wey carry na signer assertion unless separately time-attested. Receipt no prove say content dey true, or say action happen, or say all record set complete. Hold dis ones tight.
When you ready to move from dis lesson to deploying receipt-signed agents for real environment:
Join di Microsoft Foundry Discord make you fit meet oda learners dem, attend office hours, an get your AI Agents question dem answer.
Dis lekshan cover single-receipt signing an hash-chained sequences. Di same primitives fit join to form plenty advanced patterns wey you fit see as your governance posture dey grow:
authorization_*) an post-execution (result_*) parts wey get independent signatures, e dey useful wen di permission decision and di result wey dem see dem come from different pesin or different time dem. Dis one still join together with di receipt format wey dis lekshan teach.result_hash. Real world payload dem dey more than just one tool call result: pre-decision reasoning (model prediction, options dem consider, evidence an if e full, risk posture, accountability chain, gate outcome) fit dey inside di payload, sealed by one receipt. Dis one keep di receipt format simple but still let payload form change by domain.alg label no mean say you don migrate: profile gots define ML-DSA key encoding, canonical signed bytes, verification, relying-party policy, resistance to downgrade, an transition ways. Plan an test dual-signature transition with shared vectors before you talk say e fit work well.Disclaimer: Dis document don translate wit AI translation service Co-op Translator. Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation.