attp

Agent Trust Transport Protocol -- secure agent-to-server communication with mandatory signing.

ATTP is a transport-layer security protocol for AI agents. It adds cryptographic identity, request signing, and trust levels to every API call. Think of it as HTTPS for agents: where HTTPS encrypts the channel, ATTP authenticates the agent and signs every payload.

Zero dependencies. Node.js 18+ only. Uses built-in crypto module exclusively.

Install

npm install attp

Quick Start

Client (3 lines)

const attp = require('attp');

const res = await attp.fetch('attp://api.example.com/v1/data', {
  method: 'POST',
  body: JSON.stringify({ amount: 500 }),
});

console.log(res.attp.verified);     // true -- server response was signed
console.log(res.attp.auditId);      // SHA-256 audit trail hash

Server (3 lines)

const attp = require('attp');
const express = require('express');
const app = express();

app.use(attp.verify({ minTrust: 'L2' }));

app.post('/v1/data', (req, res) => {
  console.log(req.agent.id);         // agent-a1b2c3d4e5f6...
  console.log(req.agent.trustLevel); // L2
  console.log(req.agent.verified);   // true
  res.json({ status: 'ok' });
});

app.listen(3000);

How It Works

Request Lifecycle

1. Key Generation -- On first use, ATTP auto-generates an ECDSA P-256 key pair at ~/.attp/keys/
2. Agent Passport -- A JWT-structured token is created: header.payload.signature signed with the agent's private key
3. Request Signing -- The request body is hashed (SHA-256) and signed with ECDSA
4. Header Injection -- Five ATTP headers are added: trust passport, body signature, nonce, timestamp, protocol version
5. URL Conversion -- attp:// is converted to https:// and sent via native fetch()
6. Server Verification -- The server middleware verifies the passport, signature, nonce uniqueness, and timestamp freshness
7. Response Signing -- The server signs its response body and adds server signature headers
8. Client Verification -- The client verifies the server's response signature

Fail-Closed Security

If any verification step fails, the request is rejected. Missing headers, expired timestamps, invalid signatures, replayed nonces -- all result in immediate rejection with structured JSON errors.

Trust Levels

| Level | Label | Score Range | Description | |-------|-------|-------------|-------------| | L0 | Unverified | 0-19 | No identity verification | | L1 | Basic | 20-39 | Self-asserted identity | | L2 | Verified | 40-59 | Cryptographically signed identity | | L3 | Trusted | 60-79 | Third-party attested identity | | L4 | High Assurance | 80-100 | Hardware-backed, audited identity |

ATTP Headers

Request Headers (Client -> Server)

| Header | Description | |--------|-------------| | X-Agent-Trust | Agent Passport JWT (ES256-signed) | | X-Agent-Signature | ECDSA signature of request body hash | | X-Agent-Nonce | UUID v4 (replay protection) | | X-Agent-Timestamp | ISO 8601 timestamp (freshness check, 300s window) | | X-ATTP-Version | Protocol version (1.0) | | X-Agent-Public-Key | Base64url-encoded agent public key PEM |

Response Headers (Server -> Client)

| Header | Description | |--------|-------------| | X-Server-Signature | ECDSA signature of response body hash | | X-Server-Nonce | UUID v4 | | X-Server-Timestamp | ISO 8601 timestamp | | X-Server-Public-Key | Base64url-encoded server public key PEM |

CLI

# Generate key pair
attp keygen

# Make an ATTP-signed request
attp fetch attp://api.example.com/v1/data
attp fetch attp://api.example.com/v1/transfer -X POST -d '{"amount":500}'

# Show agent identity
attp whoami

# Verify a server's JWKS endpoint
attp verify https://api.example.com

API Reference

Client

attp.fetch(url, options)

Drop-in replacement for fetch(). Converts attp:// to https://, adds ATTP headers, verifies server response.

Returns a standard Response with an additional .attp property:

• .attp.verified -- boolean, whether server response signature was valid
• .attp.trustLevel -- server's signing status
• .attp.serverSignature -- hex string or null
• .attp.auditId -- SHA-256 audit trail hash

Extra options (beyond standard fetch):

• keyDir -- custom key directory (default: ~/.attp/keys/)
• trustLevel -- agent's self-asserted trust level (default: 'L2')
• trustScore -- agent's trust score (default: 55)
• capabilities -- array of capability strings
• agentType -- agent type string (default: 'autonomous')

attp.generateKeys(path?)

Generate ECDSA P-256 key pair. Default: ~/.attp/keys/

attp.loadKeys(path?)

Load existing keys. Returns null if not found.

attp.createPassport(options?)

Create an Agent Passport JWT token.

Server

attp.verify(options?)

Express/Connect-compatible middleware.

Options:

• minTrust -- minimum trust level: 'L0' | 'L1' | 'L2' | 'L3' | 'L4' (default: 'L0')
• requireSigning -- require ATTP headers (default: true)
• signResponses -- sign response bodies (default: true)
• jwksPath -- JWKS endpoint path (default: '/.well-known/agent-trust-keys')
• serverKeyDir -- server key directory
• onVerified -- callback (req, agent) on successful verification
• onRejected -- callback (req, reason) on rejection

Sets req.agent:

• .id -- agent ID
• .trustLevel -- L0-L4
• .trustScore -- 0-100
• .verified -- boolean
• .passport -- full decoded passport payload

Auto-serves JWKS at /.well-known/agent-trust-keys.

attp.handler(fn, options?)

Serverless wrapper for Vercel, AWS Lambda, etc:

module.exports = attp.handler((req, res) => {
  res.json({ hello: 'world' });
}, { minTrust: 'L2' });

Utilities

• attp.signData(data, privateKey) -- Sign data, returns hex string
• attp.verifySignature(data, signatureHex, publicKey) -- Verify signature
• attp.canonicalJSON(obj) -- RFC 8785 JCS canonical JSON
• attp.publicKeyToJWK(publicKeyPem) -- Convert PEM to JWK
• attp.agentIdFromPublicKey(publicKeyPem) -- Derive agent ID

Comparison

| | HTTP | HTTPS | ATTP | |--|------|-------|------| | Encryption | No | Yes | Yes (uses HTTPS) | | Server identity | No | Yes (TLS cert) | Yes (TLS + ECDSA) | | Client identity | No | Optional (mTLS) | Mandatory (Agent Passport) | | Request signing | No | No | Yes (every request) | | Response signing | No | No | Yes (every response) | | Replay protection | No | No | Yes (nonce + timestamp) | | Trust levels | No | No | Yes (L0-L4) | | Audit trail | No | No | Yes (per-request hash) |

Links

• IETF Draft: MCPS -- Secure MCP specification
• IETF Draft: Agent Payment Trust -- Agent trust protocol
• OWASP MCP Security Cheat Sheet -- Section 7: Transport Security
• AgentSign -- Agent identity platform

License

MIT -- CyberSecAI Ltd 2026