AgentTrust ID Architecture

This document describes the current implementation in this repository. It intentionally avoids roadmap claims, fixed latency/cost claims, and legacy certificate/JWT language that is not part of the current SDK-facing path.

Service Map

Service	Port	Current responsibility	Code reference
Gateway	`8080`	Public HTTP entrypoint with GraphQL and REST routes; proxies service endpoints	`cmd/gateway/main.go`
Identity Service	`8081`	Org-scoped agent registry, public-key metadata, capabilities, reputation init, agent audit rows	`internal/identity/handler.go`, `internal/identity/service.go`
Auth Service / Fast Guard	`8082`	Action checks, sessions, approvals, legacy token routes, opaque agent-token routes	`cmd/auth-service/main.go`, `internal/auth/action_check.go`, `internal/tokens/opaque.go`
Revocation Service	`8083`	Agent/certificate/token revocation state and Redis revocation cache	`internal/revocation/service.go`
Audit Service	`8084`	Audit-event ingestion/query and compliance summaries	`internal/audit/`
Guardian Router	`8085`	Risk-tier routing to Spot and Deep Guard	`cmd/guardian-router/main.go`, `internal/guardian/router/handler.go`
Spot Guard	`8086` HTTP health, `50051` gRPC	Policy-engine evaluation with risk scoring	`internal/guardian/spot/server.go`, `internal/guardian/policy_cache.go`
Deep Guard	`8087` HTTP health, `50052` gRPC	Claude-backed high-risk review; deterministic evaluator in demo mode	`internal/guardian/deep/server.go`, `internal/guardian/deep/claude.go`
Notification Service	`8088`	Alerts and notification delivery	`internal/notifications/`
Dashboard	`3002`	Operator UI	`dashboard/`

mTLS between Go services is available behind MTLS_ENABLED=true, but deployment templates do not all enable it by default. Treat it as configurable support, not a universally enforced service mesh.

Gateway Surface

Gateway :8080 · GraphQL + REST is accurate: the gateway registers /graphql and REST proxy routes in cmd/gateway/main.go. This means the gateway process exposes both surfaces when deployed. It does not mean AgentTrust ID is operating a hosted public SaaS API for arbitrary external callers unless the operator deploys it that way.

Core Runtime Flow

Register an agent

POST /api/v1/agents creates an org-scoped agent record. The org comes from authenticated context; the handler does not trust an org_id body field. The service validates name/framework/capability inputs, stores a public key if supplied or generated, initializes reputation, and writes an agent_created audit event in the same transaction.

Current response shape is an agent object. The current identity creation path does not return a private key or certificate object.
Issue an opaque token

POST /api/v1/agent-tokens/issue issues random opaque tokens with the at_ prefix. Tokens are not JWTs, contain no embedded claims, and cannot be verified offline. The service stores token metadata under a token hash in Redis.
Introspect an opaque token

POST /api/v1/agent-tokens/introspect returns an RFC-7662-style response with active: true only when the token format is valid, the token hash exists, the token has not expired, and the requested scopes fit.
Authorize an action

POST /api/v1/actions/check routes mediated runtime checks through internal/agenttrust/check.go. The unified checker performs effect classification, session/scope checks, anomaly checks, approval-gate checks, Guardian routing, session metrics, and audit/event output.
Revoke quickly

Agent revocation updates the database, writes revocation state to Redis, invalidates auth-service cache keys, and publishes a revocation event. Certificate and legacy token revocation paths still exist for older credential records; the SDK-facing runtime token path is opaque agent-tokens.

Integration surfaces

AgentTrust ID enforces at three integration surfaces - MCP, A2A, and Direct API - all routed through the shared UnifiedChecker. Federation is an identity bridge that maps external identities into those sessions; it is not a separate enforcement surface.

Surface	What it does	Code reference
MCP Proxy	Proxies MCP JSON-RPC tool calls and sampling requests through AgentTrust ID checks	`internal/mcp/proxy.go`, `internal/mcp/sampling_guard.go`
A2A Server	Handles A2A JSON-RPC task dispatch and routes mediated actions through the shared checker	`internal/a2a/server.go`, `internal/a2a/adapter.go`
Direct API	Bridges verified JWT claims into local AgentTrust ID sessions; it is not the opaque-token issuer	`internal/agenttrust/api_adapter.go`
Federation (identity bridge)	Verifies federation tokens server-side, resolves providers, and creates local AgentTrust ID sessions	`internal/federation/federation_tokens.go`, `internal/federation/agenttrust_bridge.go`

Guardian Pipeline

The current Guardian path is deterministic and risk-tier based, not a fixed 90/8/2 traffic split.

Tier	Current implementation
Fast Guard	Auth-service rule checks for agent state, capability/scope fit, session constraints, revocation, and deny-list patterns
Guardian Router	Loads action risk tier from routing rules and sends medium-risk work to Spot or high/critical work to Deep
Spot Guard	Go gRPC policy engine that evaluates cached Guardian policies and risk context
Deep Guard	Go gRPC service that builds request context for Claude-backed review; demo mode uses deterministic local decisions

For destructive/admin effects, the unified checker fails closed if the Guardian router is unavailable.

Sessions And Approval

Sessions are Redis-backed runtime authorization contexts. The checker enforces session ownership, scope ceilings, mode, allowed actions, and elevation state. Human approval requests are represented by ApprovalRequest; approved elevation is time-boxed to a maximum of five minutes.

Audit And Integrity

Mutating service paths write audit rows for state changes. The integrity layer verifies live session/accountability data and audit-chain continuity; do not describe it as full replay of every historical decision unless that exact verification path is being used.