# ProofPack & Agent Delegation

ProofPack is a library and format that enables services to verify that agents are authorized by real humans, and to accept selective identity claims without seeing full personal data.

If you're building a service that accepts requests from agents, or if you're building an agent that needs to prove authorization, this guide is for you.

## The Problem: Distinguishing Bots from Authorized Agents

Every day, services face a dilemma:

* **Requests from agents**: Could be legitimate (human-authorized) or malicious (bot)
* **Traditional authentication**: Requires the human to log in repeatedly (bad UX for agents)
* **API tokens**: Easy to steal, don't prove human authorization
* **OAuth to social providers**: Requires centralized identity providers, slow, privacy-invasive

**ProofPack solves this:** Agents carry cryptographic proof that a verified human authorized them. Services verify locally, with zero latency and full privacy.

## What is ProofPack?

ProofPack is a **JSON format + library** for:

1. **Selective Disclosure**: Share only specific identity claims (age, nationality, AML status) without full ID
2. **Cryptographic Verification**: Merkle trees prove data hasn't been tampered with
3. **Delegation Proof**: IsDelegate attestations prove human → agent authorization
4. **On-Chain Trust**: All attestations anchor to blockchain (EAS on Base) for immutable verification

## The Two Verification Paths

### Path 1: Quick Check (Wallet Only)

**Question:** "Is this wallet acting for a verified human?"

Use the agent's wallet address and `verifyByWallet()`. No JWS required.

{% content-ref url="proofpack-agent-delegation/path1-wallet-only-javascript" %}
[path1-wallet-only-javascript](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/path1-wallet-only-javascript)
{% endcontent-ref %}

**Use cases:** MCP servers, connection handshakes, rate limiting, quick bot detection.

**Alternative: Simple REST API** — If you prefer not to use the library, see [IsDelegate REST API](https://docs.zipwire.io/fundamentals/security/attestations/is-delegate-rest-api). It requires trusting Zipwire's validation; for independent verification use ProofPack.

### Path 2: Full Proof (With Claims)

**Question:** "Is this agent authorized by a human, and does that human meet these criteria (age, nationality, AML)?"

The agent sends a proof in the request header. **ProofPack supports both JWS and JWT**; use the standard `Authorization: Bearer <token>` pattern—any client or gateway that handles Bearer tokens works. The token contains specific identity claims, Merkle proofs, and the delegation chain. Your service verifies it and reads the revealed claims.

{% content-ref url="proofpack-agent-delegation/path2-jws-claims-javascript" %}
[path2-jws-claims-javascript](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/path2-jws-claims-javascript)
{% endcontent-ref %}

**Use cases:** Payments, regulated services (KYC, compliance), premium features, any service that needs specific identity attributes.

## Installation

See [ProofPack Examples → Installation](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/installation) for npm, dotnet, and Rust.

## Setting Up Verification

Configure trusted roots and create the verifier/reader: [Quick setup: verification context](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/quick-setup-verification-context).

## Integration Examples

* **Express.js** — Middleware for `x-agent-wallet` or `Authorization: Bearer <token>` (JWS or JWT): [Express.js middleware](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/express-middleware)
* **ASP.NET Core** — Controller with wallet and JWS/JWT verification: [ASP.NET Core agent verification](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/aspnet-core-agent-verification)

## Common Use Cases

Time tracking, payment verification, compliance (KYC/AML), and MCP server integration: [Common use cases](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/common-use-cases).

## Troubleshooting

### "Agent not authorized by human"

**Causes:**

* Agent's wallet has no IsDelegate attestations
* IsDelegate was revoked
* IsDelegate points to an untrusted root
* IsDelegate is expired or invalid

**Fix:**

* Verify the human created the IsDelegate on [EAS](https://base.easscan.org)
* Check the refUID points to a valid IsAHuman attestation
* Check the Zipwire attester address matches your trusted roots

### "Invalid JWS signature"

**Causes:**

* JWS is tampered with
* Agent didn't sign it with their key
* JWS format is wrong

**Fix:**

* Verify the JWS comes directly from the agent
* Check the agent signed with their private key
* Verify JWS format: header.payload.signature

### "Merkle root mismatch"

**Causes:**

* Claims in the proof don't match on-chain attestation
* Proof was redacted incorrectly
* Attestation and proof were created separately

**Fix:**

* Verify the agent created the proof using the correct Mint API
* Check the Merkle root in the proof matches the on-chain attestation
* Ensure the agent is using the latest ProofPack library

## Security Best Practices

1. **Validate early**: Check agent authorization at the API entry point
2. **Trust roots carefully**: Only trust attesters you control or deeply trust
3. **Check revocation**: Revoked delegations should fail validation
4. **Use HTTPS**: Always transport proof tokens (JWS or JWT) over secure connections
5. **Log verifications**: Keep audit logs of what agents did
6. **Rate limit by verification**: Humans (verified) can request more than unverified agents

## Performance & Latency

* **Wallet-only check**: <100ms (no RPC calls needed with EAS GraphQL caching)
* **Full proof verification**: <200ms (local Merkle proof validation)
* **No IdP calls**: Zero latency waiting for external identity providers

ProofPack verification is **fast enough for request-path authentication**.

## The Future: Chained Agents

As agents become more sophisticated, sub-delegation becomes important:

```
Human (IsAHuman)
  ↓ IsDelegate
Primary Agent
  ↓ IsDelegate
Task-Specific Sub-Agent
  ↓ IsDelegate
Analysis Sub-Agent
```

ProofPack validates the entire chain, so services can trust requests from deep sub-agents.

***

## Related Documentation

* [ProofPack Examples](https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation/proofpack-examples) — copy-paste code for Path 1, Path 2, Express, ASP.NET Core, setup, use cases
* [IsDelegate Attestations](https://docs.zipwire.io/fundamentals/security/attestations/isdelegate-agent-delegation)
* [For AI Agents](https://docs.zipwire.io/use-cases/for-agents)
* [ProofPack GitHub](https://github.com/zipwireapp/ProofPack)
* [Zipwire Attest](https://zipwire.io/attest)

***

**Get Started:**

1. Install ProofPack library
2. Configure trusted roots
3. Add verification middleware to your API
4. Start accepting authorized agents!

**Questions?** Check the [ProofPack docs](https://github.com/zipwireapp/ProofPack) or contact Zipwire support.