AITP Control Plane

A backend service that hosts the registry, audit log, revocation list, and webhook fan-out for an AITP (Agent Identity Trust Protocol) deployment.

This service is API-only. It ships no UI. Operators consume the JSON endpoints directly or front them with a separate UI app.

What this is

A coordination surface for AITP agents. It observes and audits; it does not sit in the trust path.

• Agent registry — agents self-enroll with a short-lived token; the CP caches their manifest and offered capabilities so peers can discover them.
• Audit event store — every handshake, delegation, and revocation reported by agents is persisted and streamed live over SSE.
• Revocation list — operators record revoked TCT JTIs; the CP signs and serves a periodically-refreshed revocation snapshot at /.well-known/aitp-revocation-list per RFC-AITP-0008.
• Webhook outbox — subscribers receive HMAC-signed deliveries for selected event types, with retries.
• Telemetry sink — POST /api/events accepts batched run telemetry from the aitp-playground and any other AITP runner.

What this is NOT

• Not a TCT issuer. AITP is bilateral peer-to-peer trust. Agents issue TCTs to each other in a four-message handshake, audience-bound and cnf-bound to the holder's Ed25519 key. A central issuer would break the protocol's threat model.
• Not a gateway or proxy. Handshake traffic is agent-to-agent. The CP never sees handshake payloads.
• Not a UI. No dashboard, no admin pages. Build one separately against the JSON API if you need one.

This README and docs/ describe the control plane. The protocol itself (handshake, TCTs, identity, revocation) is normatively defined by the AITP RFCs and implemented by aitp-rs — these docs link to the RFCs rather than restate them.

Quickstart

# 1. Postgres
docker compose up -d postgres

# 2. Environment
cp .env.example .env
# Generate secrets:
node -e "console.log('CP_AID_SEED_HEX=' + require('crypto').randomBytes(32).toString('hex'))"
node -e "console.log('ENROLLMENT_SECRET=' + require('crypto').randomBytes(32).toString('hex'))"

# 3. Install + migrate + run
npm install
npm run db:migrate
npm run dev

The service listens on http://localhost:4000. Probe it:

curl http://localhost:4000/api/health
curl http://localhost:4000/.well-known/aitp-manifest

Configuration

All settings are environment variables. .env.example is the canonical list; docs/operations.md is the runbook explaining how the rate-limit, retention, and telemetry subsystems behave.

Core

Webhooks & SSE

Rate limiting (in-memory, per-process — see operations.md)

Data retention (periodic sweep, multi-instance safe — set any TTL to 0 to keep that table forever)

Telemetry (OpenTelemetry, off by default)

API surface

See docs/ for the full documentation set — docs/api.md (prose API reference), docs/events.md (event types & projections), docs/data-model.md (Postgres schema), and docs/operations.md (runbook) — plus openapi.yaml for the machine-readable schema. High-level groups:

• Public discovery: /api/health, /api/readyz, /api/metrics, /.well-known/aitp-manifest, /.well-known/aitp-revocation-list
• Registry: /api/registry/enroll, /api/registry/agents, /api/registry/agents/:aid, /api/registry/agents/:aid/manifest, /api/registry/agents/:aid/export
• Sessions: /api/sessions, /api/sessions/:sessionId, /api/sessions/:sessionId/export, /api/sessions/:sessionId/replay
• Events: POST /api/events, GET /api/events/history, GET /api/events/stream (SSE)
• Audit: /api/audit
• Webhooks: /api/webhooks, /api/webhooks/:id, /api/webhooks/:id/circuit-breaker, /api/webhooks/:id/circuit-breaker/reset
• Revocation: /api/revocation/entries
• Dashboard JSON: /api/dashboard/overview, /api/dashboard/agents
• TCT lifecycle: /api/tcts (observed; CP does not issue)
• Delegation chains: /api/delegations
• Trust store: /api/trust-anchors, /api/trust-anchors/:id, /api/pinned-keys

Architecture

┌─────────────────────────────────────────────────────┐
│  AITP Control Plane (this repo)                     │
│  Next.js 15 route handlers + Postgres               │
│                                                     │
│  ┌──────────┐  ┌────────────┐  ┌────────────────┐   │
│  │ Registry │  │ Audit / SSE│  │ Webhook outbox │   │
│  └──────────┘  └────────────┘  └────────────────┘   │
│  ┌──────────────┐  ┌──────────────────────────┐     │
│  │ Revocation   │  │ /.well-known + CP AITP   │     │
│  │  list        │  │  identity (Ed25519)      │     │
│  └──────────────┘  └──────────────────────────┘     │
└────────────────┬────────────────────────────────────┘
                 │ JSON over HTTP
   ┌─────────────┴──────────────┐
   ▼                            ▼
┌──────────────────┐    ┌─────────────────────────┐
│ aitp-playground  │    │ Agents (aitp-rs / py)   │
│  (scenario       │    │  - publish manifests    │
│   runner)        │    │  - 4-msg handshake p2p  │
└──────────────────┘    └─────────────────────────┘

The CP never participates in a handshake. Agents talk to each other directly. They optionally:

1. Discover peers via GET /api/registry/agents?capability=demo.echo
2. Report events (handshake completed, delegation issued, TCT revoked) via POST /api/events
3. Enroll as a known agent via POST /api/registry/enroll → POST /api/registry/agents

Integration with aitp-playground

See docs/integration-playground.md for the exact contract, and docs/events.md for the event types a runner can report (and which ones drive session/TCT projections and webhook fan-out).

Development

npm run typecheck     # tsc --noEmit
npm run lint          # eslint
npm test              # jest unit
npm run test:integration  # jest against real Postgres on :5433

Bring up the test database:

docker compose up -d postgres-test

The integration suite expects DATABASE_URL=postgres://postgres:postgres@localhost:5433/aitp_control_plane_test.

Project layout

src/
  app/api/        Next.js App Router route handlers (the only thing rendered)
  lib/
    audit/        Event store, in-memory SSE bus
    db/           Drizzle schema + connection
    identity/     CP's own AITP keypair + manifest
    registry/     Agent CRUD, enrollment tokens, expiry job
    revocation/   Signed revocation snapshot producer
    sessions/     Handshake-session monitor (from audit events)
    webhooks/     Outbox dispatcher, HMAC signing, retry reaper
drizzle/          SQL migrations
docs/             Published docs: API reference, events, data model, ops runbook, integration contract
internal_docs/    Internal-only docs (deployment/CI) — NOT published to the website
plans/            Forward-looking roadmap

Deployment

CI builds a multi-arch container image and publishes it to GHCR (ghcr.io/agentidentitytrustprotocol/aitp-control-plane) on every push to main. The aitp SDK is the published @agentidentitytrustprotocol/aitp npm package, so the image and CI are self-contained — no sibling aitp-rs checkout or Rust toolchain required.

The full CI/CD pipeline and a step-by-step Railway deployment guide live in internal_docs/ — operational detail kept out of the published docs site.

License

See LICENSE.