Attestations
An attestation is a verified statement from a trusted party: a tool, the control plane, your identity provider, or an approver. A policy requires it by name, and its declaration says which party attests it.
Who Attests
| Type | Attested by | How MACAW checks it | Declared with |
|---|---|---|---|
| Internal | A tool, through its ToolAgent, after it runs | The ToolAgent's signature | "internal": true |
| Built-in | The control plane, at registration | The tenant attestor's signature | The platform: idp_verified, phishing_resistant |
| Claim-based | The identity provider, in the requester's token | The IdP's signature, audience and expiry | claim |
| External | A person who meets approval_criteria, when asked | The approver's signed decision | approval_criteria |
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
Internal attestations, set by tools, and external attestations, approved by a person, take these fields. Claim-based and built-in attestations take none of them.
| 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 |
| priority | 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)
│ │
▼ ▼
logger.attest() 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": {
"file_read_complete": { "internal": true },
"manager_approval": {
"approval_criteria": "role:manager",
"timeout": 300,
"time_to_live": 3600
}
}
}
}Every attestation a policy requires is declared under constraints.attestations with its type: "internal": true, approval_criteria or claim. An undeclared one denies the call, a conditional one included, even when its condition is false.
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.