From c5e6666291b5f8946b3451c1229671efcd623bd7 Mon Sep 17 00:00:00 2001 From: Max Malkin Date: Tue, 3 Mar 2026 18:49:39 -0700 Subject: [PATCH 1/2] make agentauth-mcp the main focus of the homepage and root readme --- README.md | 240 +++++++++++++++---------------- services/approval-ui/src/App.tsx | 198 +++++++++++++++---------- 2 files changed, 233 insertions(+), 205 deletions(-) diff --git a/README.md b/README.md index 18c75b8..5283199 100644 --- a/README.md +++ b/README.md @@ -3,177 +3,163 @@ [![CI](https://github.com/maxmalkin/AgentAuth/actions/workflows/ci.yml/badge.svg)](https://github.com/maxmalkin/AgentAuth/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![MSRV](https://img.shields.io/badge/MSRV-1.85-orange.svg)](https://www.rust-lang.org) -[![Rust](https://img.shields.io/badge/Rust-stable-brightgreen.svg)](https://www.rust-lang.org) -A capability-based authentication system for AI agents. +Human-in-the-loop authorization for AI agents. Every tool call is cryptographically signed, scoped to what a human approved, and written to an immutable audit log. -AgentAuth enables AI agents to securely authenticate with third-party services while giving humans fine-grained control over what actions agents can perform. It implements a delegated authorization model where humans approve specific capabilities for their agents, and service providers can verify these grants in real-time. +## Try it with Claude Desktop in 5 minutes -## Features +The fastest way to see AgentAuth in action is with the included MCP server. It connects Claude Desktop to the AgentAuth stack so every tool call Claude makes is authenticated and human-approved. -- **Capability-based access control** - Define granular permissions (read, write, transact, custom) with resource-level scoping -- **Human-in-the-loop approvals** - Humans review and approve capability grants via WebAuthn/Passkey signing -- **Behavioral envelopes** - Rate limits, time windows, and transaction thresholds enforced at the protocol level -- **DPoP token binding** - Tokens are cryptographically bound to the agent's keypair, preventing theft and replay -- **Sub-5ms verification** - High-performance token verification via Redis caching -- **Audit trail** - Immutable, hash-chained audit log of all agent actions -- **HSM key storage** - Registry signing keys stored in AWS KMS, GCP Cloud KMS, or HashiCorp Vault +**Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Docker](https://docs.docker.com/get-docker/) -## Architecture - -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ -│ Agent │────▶│ Registry │◀────│ Approval UI │ -│ (SDK) │ │ Service │ │ (Human) │ -└─────────────┘ └─────────────┘ └─────────────────┘ - │ │ - │ ▼ - │ ┌─────────────┐ - │ │ Verifier │ - │ │ Service │ - │ └─────────────┘ - │ ▲ - ▼ │ -┌─────────────────────────────────────┐ -│ Service Provider │ -└─────────────────────────────────────┘ +```bash +# 1. Clone and start the full stack +git clone https://github.com/maxmalkin/AgentAuth.git +cd AgentAuth +./dev.sh ``` -- **Registry Service** - Issues and manages agent access tokens (AATs), handles capability grants -- **Verifier Service** - Lightweight, horizontally-scalable token verification (read-only) -- **Approval UI** - React frontend for humans to review and approve capability requests -- **Agent SDK** - Rust library (with Python bindings) for agents to authenticate - -## Quick Start - -### Prerequisites - -- Rust 1.85+ -- Bun 1.0+ -- Python 3.11+ -- Docker & Docker Compose -- cargo-nextest (`cargo install cargo-nextest`) - -### Setup +This starts: +- Registry on `http://localhost:8080` +- Verifier on `http://localhost:8081` +- Approval UI on `http://localhost:3001` +- Mock service on `http://localhost:9090` ```bash -# Clone the repository -git clone https://github.com/maxmalkin/AgentAuth.git -cd agentauth - -# Start dependencies (PostgreSQL, Redis, etc.) -docker-compose up -d +# 2. Run the MCP server +cd services/agentauth-mcp +bun run index.ts +``` -# Run database migrations -cargo install sqlx-cli -sqlx migrate run +On first run it prints an approval URL: +``` +[agentauth-mcp] Registered with registry +[agentauth-mcp] Approve this agent at: +[agentauth-mcp] http://localhost:3001/approve/01966b3c-… +[agentauth-mcp] Waiting for approval… +``` -# Build all crates -cargo build --workspace +Open the URL, review what capabilities the agent is requesting, click **Approve**. The MCP continues: +``` +[agentauth-mcp] Grant approved! +[agentauth-mcp] Ready — grant 01966b3c-… is approved +``` -# Run tests -cargo nextest run --workspace +```jsonc +// 3. Add to claude_desktop_config.json and restart Claude Desktop +// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json +// Windows: %APPDATA%\Claude\claude_desktop_config.json +{ + "mcpServers": { + "agentauth": { + "command": "bun", + "args": ["run", "/absolute/path/to/AgentAuth/services/agentauth-mcp/index.ts"], + "env": { + "REGISTRY_URL": "http://localhost:8080", + "SERVICE_URL": "http://localhost:9090" + } + } + } +} ``` -### Running Services +Now ask Claude to use the tools: +- **"Read my calendar"** → calls `read_calendar` (approved) +- **"Write a file called test.txt"** → calls `write_file` (approved) +- **"Send a payment of $100"** → 403 denied — `transact/payments` not in the grant -The easiest way to run all services locally is with the dev runner script: +State is saved at `~/.config/agentauth-mcp/state.json`. Subsequent runs start immediately without re-approval. -```bash -./dev.sh -``` +For full MCP documentation see [`services/agentauth-mcp/README.md`](services/agentauth-mcp/README.md). -This starts the registry, verifier, and approval UI in a single terminal with colored log output. +--- -To run individually: +## What AgentAuth enforces -```bash -# Start the registry service -cargo run -p registry-bin +| Guarantee | Mechanism | +|---|---| +| Agents only call what humans approved | Capability grants scoped per resource and action type | +| Stolen tokens can't be replayed | DPoP sender-constraint — token is bound to the agent's private key | +| Tokens expire | 15-minute lifetime; refresh requires the original grant to still be valid | +| Replay attacks blocked | Per-proof nonce checked in Redis before any verification | +| Rate limits enforced | Behavioral envelope (rpm, burst, time windows) checked at the verifier | +| Full audit trail | Append-only log with SHA-256 hash chain integrity | -# Start the verifier service (separate terminal) -cargo run -p verifier-bin +--- -# Start the approval UI (separate terminal) -cd services/approval-ui -bun install -bun run dev +## Architecture + +``` +Claude Desktop ──▶ agentauth-mcp ──▶ AgentAuth Registry :8080 + │ + Authorization: AgentBearer + AgentDPoP: + │ + Your Service ──▶ Verifier :8081 ──▶ allow / deny ``` -## Repository Structure +- **Registry** — issues and manages agent access tokens (AATs), handles capability grants and human approvals +- **Verifier** — lightweight, read-only, horizontally-scalable token verification (sub-5ms p99 with Redis warm) +- **Approval UI** — React frontend for humans to review and approve capability requests +- **agentauth-mcp** — Claude Desktop MCP server that demonstrates the full AgentAuth flow + +--- + +## Repository structure ``` -agentauth/ +AgentAuth/ +├── services/ +│ ├── agentauth-mcp/ # Claude Desktop MCP server (Bun + TypeScript) +│ ├── approval-ui/ # React approval frontend +│ ├── registry/ # Registry binary (Rust) +│ └── verifier/ # Verifier binary (Rust) ├── crates/ │ ├── core/ # Protocol types, crypto (no I/O) │ ├── registry/ # Registry service logic -│ ├── sdk/ # Rust agent SDK -│ ├── py/ # Python bindings (PyO3) -│ └── schema/ # JSON Schema validation -├── services/ -│ ├── registry/ # Registry binary -│ ├── verifier/ # Verifier binary -│ ├── audit-archiver/ # Audit log archival -│ └── approval-ui/ # React approval frontend +│ └── sdk/ # Rust agent SDK ├── migrations/ # SQLx database migrations -├── load-tests/ # k6 load test scripts -├── chaos/ # Chaos engineering experiments -├── deploy/ - ├── helm/ # Kubernetes Helm charts - └── grafana/ # Grafana dashboards +├── tests/integration/ # End-to-end tests +└── dev.sh # Start all services locally ``` -## SDK Usage - -### Rust +--- -```rust -use agentauth::{AgentAuthClient, AgentAuthConfig, Capability}; +## Building from source -let config = AgentAuthConfig::new("https://registry.example.com")?; -let client = AgentAuthClient::new(config)?; +```bash +# Prerequisites +cargo install cargo-nextest sqlx-cli -// Request capabilities -let grant = client.request_grant( - "service-provider-id", - vec![Capability::Read { - resource: "calendar".to_string(), - filter: None - }], -).await?; +# Start dependencies +docker-compose up -d +sqlx migrate run -// After human approval, get a token -let token = client.get_token("service-provider-id").await?; +# Build all Rust crates +cargo build --workspace -// Authenticate requests -client.authenticate_request("service-provider-id", &mut request).await?; +# Run tests +cargo nextest run --workspace ``` -### Python +--- -```python -from agentauth import AgentAuthClient, Capability +## Integrating AgentAuth into your own agent -client = AgentAuthClient("https://registry.example.com") +AgentAuth is designed to be embedded in any AI agent, not just Claude Desktop. The MCP server in `services/agentauth-mcp/` is a complete, working reference implementation you can adapt. -# Request capabilities -grant = await client.request_grant( - service_provider_id="service-provider-id", - capabilities=[Capability.read("calendar")] -) +The core pattern: -# After human approval, authenticate requests -headers = await client.authenticate_headers("service-provider-id", "POST", "/api/events") -``` +1. Generate an Ed25519 keypair on first run +2. POST your signed manifest to `/v1/agents/register` +3. POST to `/v1/grants/request` and block until a human approves +4. On each tool call, POST to `/v1/tokens/issue` to get a short-lived token +5. Send `Authorization: AgentBearer ` and `AgentDPoP: ` on every request to your service +6. Your service calls `/v1/tokens/verify` to check the token and capability -## Security +See [`services/agentauth-mcp/README.md`](services/agentauth-mcp/README.md) for the full implementation details including the Ed25519 canonical bytes format, DPoP proof structure, and token caching strategy. -- All signing keys stored in HSMs (AWS KMS, GCP Cloud KMS, Vault Transit) -- DPoP sender-constraint prevents token theft -- Nonce-based replay prevention -- Constant-time cryptographic comparisons -- Immutable audit log with hash chain integrity -- WebAuthn/Passkey for human approval signing +--- ## License diff --git a/services/approval-ui/src/App.tsx b/services/approval-ui/src/App.tsx index f9eaf2e..b8a87da 100644 --- a/services/approval-ui/src/App.tsx +++ b/services/approval-ui/src/App.tsx @@ -83,17 +83,40 @@ function HomePage() {

- Human-in-the-loop authorization for AI agents. + Let Claude call your tools. With human approval.

-

- Every tool call your agent makes is cryptographically signed, human-approved, and verified in real time — with a full audit trail. +

+ Drop the agentauth-mcp server into Claude Desktop and every tool call becomes cryptographically signed, scoped to what you approved, and written to an immutable audit log.

+ {/* MCP feature strip */} +
+
+ agentauth-mcp + · + Claude Desktop MCP server +
+
+ ✓ Ed25519 signed manifests + ✓ DPoP token binding + ✓ Human-approved capability grants +
+
+ {/* Primary actions */}
+ + + + + RUN THE DEMO + @@ -117,6 +140,99 @@ function HomePage() {
+ {/* ── Quick start ──────────────────────────────────────── */} +
+
+ QUICK START +

+ Start the AgentAuth stack, run the MCP server, approve the grant, connect Claude Desktop. Five minutes end to end. +

+
+ +
+
1 — Start the stack
+ + git clone https://github.com/maxmalkin/AgentAuth + cd AgentAuth && ./dev.sh +
+ # registry http://localhost:8080
+ # verifier http://localhost:8081
+ # approval UI http://localhost:3001
+ # mock service http://localhost:9090 +
+ +
+ +
+
2 — Run the MCP server
+ + cd services/agentauth-mcp + bun run index.ts +
+ [agentauth-mcp] Registered with registry
+ [agentauth-mcp] Approve this agent at:
+ [agentauth-mcp] http://localhost:3001/approve/…
+ [agentauth-mcp] Waiting for approval… +
+ +
+ +
+
3 — Approve the grant
+

+ Open the approval URL printed above. Review the capabilities the agent is requesting, then click APPROVE GRANT. The agent will start immediately. +

+ + + + + + + + GO TO AGENTS + +
+ +
+
4 — Connect Claude Desktop
+

+ Add to claude_desktop_config.json and restart Claude: +

+ + {"{"}
+   "mcpServers": {"{"}
+     "agentauth": {"{"}
+       "command": "bun",
+       "args": ["/path/to/agentauth-mcp/index.ts"],
+       "env": {"{"} "REGISTRY_URL": "http://localhost:8080" {"}"}
+     {"}"}
+   {"}"}
+ {"}"} + +
+ +
+
5 — Ask Claude to use your tools
+
+ {[ + { prompt: '"Read my calendar"', note: "→ calls read_calendar · read/calendar token" }, + { prompt: '"Write a file called test.txt"', note: "→ calls write_file · write/files token" }, + { prompt: '"Send a payment of $100"', note: "→ 403 denied — transact not in grant" }, + ].map(({ prompt, note }) => ( +
+
{prompt}
+
{note}
+
+ ))} +
+
+
+
+
+ {/* ── How it works ─────────────────────────────────────── */}
@@ -191,80 +307,6 @@ function HomePage() {
- {/* ── Quick start ──────────────────────────────────────── */} -
-
- QUICK START -
- -
-
1 — Start the stack
- - git clone https://github.com/maxmalkin/AgentAuth - cd AgentAuth && ./dev.sh -
- # registry http://localhost:8080
- # verifier http://localhost:8081
- # approval UI http://localhost:3001
- # mock service http://localhost:9090 -
- -
- -
-
2 — Run the MCP agent
- - cd services/agentauth-mcp - bun run index.ts -
- [agentauth-mcp] Registered with registry
- [agentauth-mcp] Approve this agent at:
- [agentauth-mcp] http://localhost:3001/approve/…
- [agentauth-mcp] Waiting for approval… -
- -
- -
-
3 — Approve the grant
-

- Open the approval URL printed above. Review the capabilities the agent is requesting, then click APPROVE GRANT. The agent will start immediately. -

- - - - - - - - GO TO AGENTS - -
- -
-
4 — Connect Claude Desktop
-

- Add to claude_desktop_config.json and restart Claude: -

- - {"{"}
-   "mcpServers": {"{"}
-     "agentauth": {"{"}
-       "command": "bun",
-       "args": ["/path/to/agentauth-mcp/index.ts"],
-       "env": {"{"} "REGISTRY_URL": "http://localhost:8080" {"}"}
-     {"}"}
-   {"}"}
- {"}"} - -
-
-
-
- {/* ── What's enforced ──────────────────────────────────── */}
From 5e128cfcd9ea2810037039e8b58b917c760e24e9 Mon Sep 17 00:00:00 2001 From: Max Malkin <60683392+maxmalkin@users.noreply.github.com> Date: Tue, 3 Mar 2026 18:55:01 -0700 Subject: [PATCH 2/2] Update README.md --- README.md | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 5283199..6678486 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ Human-in-the-loop authorization for AI agents. Every tool call is cryptographically signed, scoped to what a human approved, and written to an immutable audit log. -## Try it with Claude Desktop in 5 minutes +## Claude Desktop -The fastest way to see AgentAuth in action is with the included MCP server. It connects Claude Desktop to the AgentAuth stack so every tool call Claude makes is authenticated and human-approved. +The fastest way to see AgentAuth in action is with the included example MCP server. **Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Docker](https://docs.docker.com/get-docker/) @@ -70,8 +70,6 @@ Now ask Claude to use the tools: State is saved at `~/.config/agentauth-mcp/state.json`. Subsequent runs start immediately without re-approval. -For full MCP documentation see [`services/agentauth-mcp/README.md`](services/agentauth-mcp/README.md). - --- ## What AgentAuth enforces @@ -118,32 +116,13 @@ AgentAuth/ │ ├── core/ # Protocol types, crypto (no I/O) │ ├── registry/ # Registry service logic │ └── sdk/ # Rust agent SDK -├── migrations/ # SQLx database migrations +├── migrations/ # Database migrations ├── tests/integration/ # End-to-end tests └── dev.sh # Start all services locally ``` --- -## Building from source - -```bash -# Prerequisites -cargo install cargo-nextest sqlx-cli - -# Start dependencies -docker-compose up -d -sqlx migrate run - -# Build all Rust crates -cargo build --workspace - -# Run tests -cargo nextest run --workspace -``` - ---- - ## Integrating AgentAuth into your own agent AgentAuth is designed to be embedded in any AI agent, not just Claude Desktop. The MCP server in `services/agentauth-mcp/` is a complete, working reference implementation you can adapt. @@ -157,7 +136,7 @@ The core pattern: 5. Send `Authorization: AgentBearer ` and `AgentDPoP: ` on every request to your service 6. Your service calls `/v1/tokens/verify` to check the token and capability -See [`services/agentauth-mcp/README.md`](services/agentauth-mcp/README.md) for the full implementation details including the Ed25519 canonical bytes format, DPoP proof structure, and token caching strategy. +See [`services/agentauth-mcp/README.md`](services/agentauth-mcp/README.md) for the full implementation details. ---