Attestations
Attestations are cryptographic proofs that conditions have been met. MACAW supports two fundamental types: internal attestations set by tools during workflow execution, and external attestations that require human or third-party approval.
Core Concept
Policies define what can happen. Attestations prove that something did happen. They enable workflows where one step must complete before another can proceed, and where certain operations require explicit approval from humans or external systems.
Cryptographic Proof
Attestations are signed by the attesting party, creating tamper-evident records that can be verified independently.
Time-Bound
Attestations can expire via time_to_live or be consumed on use. An approval from yesterday doesn't authorize today's action unless explicitly configured.
Auditable
Every attestation is logged with full context: who attested, when, for what operation, and under what conditions.
Internal vs External Attestations
The key distinction in MACAW is between attestations set automatically by tools (internal) and those requiring explicit approval from humans or external systems (external).
| Internal | External | |
|---|---|---|
| Set By | Tools during workflow execution | Humans or third-party systems |
| approval_criteria | Not used | Required |
| max_uses | Supported | Not used |
| one_time | Supported | Supported |
| time_to_live | Supported | Supported |
| Status Flow | Set → Active → Consumed/Expired | Pending → Approved/Denied → Consumed/Expired |
Internal Attestations
Set automatically by tools as part of workflow execution. Used to prove that a previous step completed successfully.
External Attestations
Require explicit approval from humans or external systems. Must specify who can approve via approval_criteria.
Attestation Lifecycle
INTERNAL ATTESTATION: EXTERNAL ATTESTATION:
Tool Execution Agent Request (missing attestation)
│ │
▼ ▼
context.attestations.set() Policy creates pending attestation
│ │
▼ ▼
[Active] [Pending]
│ │
├──► Consumed (one_time/max_uses) ├──► approve_attestation() ──► [Approved]
│ │ │
└──► Expired (time_to_live) ├──► deny_attestation() ──► [Denied]
│
└──► Expired (time_to_live/polling_timeout)Internal attestations become active immediately. External attestations enter a pending state and must be explicitly approved or denied before they can be used.
Policy Syntax
Attestations are referenced in MAPL policies to create dependencies between operations.
{
"attestations": [
"file_read_complete",
"manager_approval::{params.amount > 10000}"
],
"constraints": {
"attestations": {
"manager_approval": {
"approval_criteria": "role:manager",
"timeout": 300,
"time_to_live": 3600
}
}
}
}Conditional Syntax
The ::{condition} syntax makes attestation requirements conditional. The attestation is only required when the condition evaluates to true.
Example: manager_approval::{params.amount > 10000} only requires manager approval for amounts over 10,000.
Blocking Behavior
When timeout is specified, external attestation requests block and poll for approval using an exponential backoff sequence.
Request → Policy Check → Attestation Required?
│
┌────────────────────────┴────────────────────────┐
│ No Yes │
▼ ▼
Execute immediately Check attestation cache
│
┌───────────────┴───────────────┐
│ Found valid Not │
▼ found │
Execute ▼
Check external storage
│
┌─────────────────┴─────────────────┐
│ Found approved Not │
▼ found │
Execute ▼
timeout > 0? (blocking enabled)
│
┌────────────┴────────────┐
│ Yes No │
▼ ▼
Create pending attestation Reject
Poll with backoff sequence
│
┌──────────┴──────────┐
│ Approved Denied/Timeout │
▼ ▼
Execute RejectPolling Backoff Sequence
When blocking is enabled, the system polls for approval using this backoff sequence (in seconds):
After 10 seconds between polls, it continues at 10-second intervals until timeout is reached.
MACAWClient API
The MACAWClient provides methods to manage attestations programmatically:
from macaw_client import MACAWClient
client = MACAWClient(...)
# List attestations (optionally filter by status)
pending = client.list_attestations(status="pending")
all_attestations = client.list_attestations()
# Approve a pending external attestation
for att in pending:
if att["key"] == "manager_approval":
client.approve_attestation(att, reason="Approved per policy")
# Deny a pending external attestation
client.deny_attestation(att, reason="Amount exceeds budget")list_attestations()
Returns attestations visible to this agent. Filter by status: "pending", "approved", "denied".
approve_attestation()
Approve a pending external attestation. Requires meeting the approval_criteria.
deny_attestation()
Deny a pending external attestation. The attestation becomes unusable.