a2a-acl

Per-tool capability ACL + AAE envelope verification for agent-to-agent communication.

When two AI agents talk to each other across organisational boundaries, the receiver's owner needs control over what the caller is permitted to do — not just whether they're a "trusted" peer. This library implements the policy layer: cryptographic identity verification, per-capability allowlists, optional trust-score gating, payload sanitisation, and rate limiting — as drop-in Express middleware.

It is the open-source extraction of the gateway that runs in front of ownify's production agents. See the design write-up: Per-tool ACL for the agent web — how ownify locks down agent-to-agent calls.

What it gives you

| Stage | What it enforces | Failure mode | |---|---|---| | verifyAaeMiddleware | Cryptographic envelope (Ed25519, with replay + revocation + audience check) | 401 | | aclCheckMiddleware | The (receiver_slug, caller_did, capability) tuple is in your ACL store | 403 acl_no_capability_grant | | trustScoreGateMiddleware | Caller's trust score clears the matched rule's threshold_override (or your default) | 403 trust_score_below_threshold | | sanitiseMiddleware | Strip prompt-injection markers from request body | (forwards, audit-only) | | depthGuardMiddleware | AAE chain hop count ≤ maxHopCount | 403 recursion_depth_exceeded | | circuitOpenCheckMiddleware | Upstream peer slug isn't in cooldown | 503 upstream_circuit_open | | rateLimitMiddleware | Per-(caller, peer) requests/minute + daily token budget | 429 | | auditMiddleware | Fire-and-forget sink for every decision | (logs only) |

The library ships the algorithm. You plug in the storage: key resolution, ACL match, trust scores, revocation list. Whatever backs them — Postgres, Redis, SQLite, in-memory tests — is your choice.

Capability schema

message
invoke_tool:<name>            (e.g. invoke_tool:sendgrid)
read_memory:<wing>            (wing-wide read access)
read_memory:<wing>/<room>     (single-room read access)

message lets the peer chat with your agent's LLM (soft layer). invoke_tool:* triggers a specific named skill (hard layer). read_memory:* lists/reads memory drawers in a wing or room (hard layer).

Default is deny. The receiver's owner grants exactly what the peer is allowed to do. No grant by trust score alone, no implicit allowlist for being a registered peer.

Install

npm install a2a-acl express

Requires Node 20+. Express is a peer dep — works with Express 4 and 5.

Usage

import express from 'express';
import {
  firewallChain,
  KeyResolver, TrustResolver, RevocationChecker,
  NonceCache, RateLimiter, DailyTokenBudget, CircuitBreaker,
} from 'a2a-acl';

// 1. Resolvers — you provide the storage backend.

const keyResolver = new KeyResolver({
  resolve: async (keyId) => {
    // Return { public_key_b64url: '...32-byte-base64url...', sig_alg: 'Ed25519' }
    // or null if unknown. Throw on transient failures (resolver retries).
    return await db.keys.findOne({ key_id: keyId });
  },
});

const trustResolver = new TrustResolver({
  resolve: async (did) => ({ score: await scoreLookup(did) }),
});

const revocationChecker = new RevocationChecker({
  check: async (jti) => await db.revocations.exists({ jti }),
});

const nonceCache = new NonceCache();
const rateLimiter = new RateLimiter({ requestsPerMinute: 5 });
const tokenBudget = new DailyTokenBudget({ tokensPerDay: 10_000 });
const circuitBreaker = new CircuitBreaker();

// 2. ACL match callback.

async function matchAcl({ slug, callerDid, capability }) {
  // Wing-prefix fallback for read_memory: a wing-wide grant covers
  // any room within that wing.
  const candidates = [capability];
  if (capability.startsWith('read_memory:') && capability.includes('/')) {
    const wing = capability.split(':')[1].split('/')[0];
    candidates.push(`read_memory:${wing}`);
  }
  return await db.acl.findOne({
    peer_slug: slug,
    caller_did: callerDid,
    capability: { $in: candidates },
  });
}

// 3. Wire the chain.

const app = express();
app.use(express.json());

app.use('/api/a2a/:slug', (req, _res, next) => {
  req.firewall = { slug: req.params.slug };
  next();
});

app.use('/api/a2a/:slug', ...firewallChain({
  keyResolver, revocationChecker, nonceCache, trustResolver,
  rateLimiter, tokenBudget, circuitBreaker, matchAcl,
  defaultThreshold: 0.7,
  maxHopCount: 3,
  expectedAud: 'a2a-ingress',
  basePath: '/api/a2a/:slug',
  logger: console, // optional; pino-style { info, warn, error }
  sink: (row) => db.audit.insert(row), // optional
}));

// Your handlers run only after the chain accepts.
app.post('/api/a2a/:slug/message', (req, res) => {
  // forward to your agent runtime, stream its reply back
});

app.listen(3000);

A complete working example lives in examples/express-server.js. Run it with npm run example.

What's req.firewall

Each middleware writes its decision/state to req.firewall.* so later stages can read it:

| Field | Set by | Type | |---|---|---| | req.firewall.public | verifyAae (when path is agent-card / well-known) | boolean | | req.firewall.aae | verifyAae | the verification result object | | req.firewall.callerDid | verifyAae | DID string from envelope iss | | req.firewall.aclRule | aclCheck | the matched rule (whatever your matchAcl returned) | | req.firewall.trustScore | trustScoreGate | number 0..1 | | req.firewall.sanitiseHits | sanitise | count of sanitise patterns that fired | | req.firewall.tokenEstimate | rateLimit | bytes-÷-4 estimate of this request |

What's NOT in the library

• Storage. Your DB schema, your tables, your queries.
• A specific trust-score algorithm. You decide what trust means.
• Outbound envelope signing. The signing side is on the caller's control plane; this library is for the receiving gateway.
• Framework adapters beyond Express. Add Fastify/Hono in v0.2 if there's demand — the core (resolvers, sanitiser, rate-limit, AAE parse/verify, capability schema) is framework-agnostic.

Why this exists

The agent web is racing to ship. Most platforms either have no agent-to-agent authorization, or a single global trust-score gate that's not really authorization. Neither matches how delegation between organisations actually works.

This library is the policy layer that runs at ownify.ai in production. We extracted it so others building agent infrastructure don't have to roll their own.

If you find a bug, open an issue. If you want it adapted to your stack, send a PR.

Security

Defaults are strict: audience required, expiry required, max envelope lifetime 5 minutes, only Ed25519 accepted, replay-cache fail-closed when full. See SECURITY.md for the full threat model, the things this library does NOT defend against (SQL injection in your callbacks, body-size attacks, prompt injection beyond known markers, multi-replica replay), and how to report a vulnerability.

License

MIT.