Summary

Implements the Agent Auth Protocol for Zentity: a system that gives agents enough identity to act on behalf of humans without turning the agent into a long-term container for human PII.

The design solves three problems at once: the caller authenticates as a machine, the human still approves sensitive actions, and the relying party learns who acted without getting a globally trackable agent identifier.

See Agent Architecture for the full design narrative.

Standards implemented

Architecture

The implementation is organized around five protocol concerns that form a chain:

Secure Transport → Structured Intent → Agent Control Plane → Consent Channel → Token Semantics

Principal boundaries

Three distinct caller classes, each with its own auth helper:

• Browser user — session cookie → requireBrowserSession()
• User-delegated machine — OAuth access token → requireUserAccessToken()
• Pure machine client — client_credentials → requireClientCredentials()

Agent registration and lifecycle are machine-facing OAuth surfaces. Human approval comes later through CIBA.

Host and session hierarchy

Agent identity splits into two layers because two lifetimes need two keys:

• Durable host (agent_host) — Ed25519 keypair persisted per installation, keyed by public_key_thumbprint. Survives restarts. One user+client can have multiple hosts (laptops, containers).
• Ephemeral session (agent_session) — fresh Ed25519 keypair per process. Registered with a host-signed host-attestation+jwt. Carries runtime metadata (display_name, model, version).

Trust tiers

Two operational tiers based on what Zentity can verify about the installation:

Attestation widens default host policy — it does not mint a separate token class.

Capability containment

Answers one question repeatedly: "Can this session do this action without interrupting the user?"

• Host policies (agent_host_policy) — durable grants with constraint operators (max, min, in, not_in, eq)
• Session grants (agent_session_grant) — ephemeral, seeded from host policy at registration
• Usage ledger (capability_usage_ledger) — append-only, enforces daily_limit_count, daily_limit_amount, cooldown_sec
• Grant evaluator (grant-evaluation.ts) — the sole CIBA auto-approve path

Auto-approval is refused for: identity scopes, missing capabilities, biometric-strength capabilities, no matching grant, or exceeded limits.

Approval routing

Three outcomes based on risk, not transport:

purchase always routes to biometric approval. read_profile can become silent for attested hosts.

Token anatomy (AAP profile)

CIBA access tokens carry the AAP draft claim vocabulary: agent, task, capabilities, oversight, audit. Exchanged tokens additionally carry delegation.

• sub — human pairwise identifier for target client
• act.sub — agent pairwise identifier for target client (derived from session ID + sector)
• authorization_details — round-tripped from CIBA request through approval to token
• purchase-authorization+jwt — RFC 8693 exchange artifact for downstream merchants

Binding chain

Each phase produces evidence the next can reuse:

OAuth user token → Durable host registration → Fresh session registration
  → Agent-Assertion on CIBA → Human approval → Access token (sub + act.sub)
    → Optional RFC 8693 exchange to purchase-authorization+jwt

Lifecycle

Two session clocks (idle TTL: 30min, max lifetime: 24h). No reactivation — expired sessions require fresh registration under the same host. Host key rotation invalidates all sessions.

Discovery and introspection

• /.well-known/agent-configuration — protocol discovery (endpoints, algorithms, features)
• GET /api/auth/agent/capabilities — capability catalog with schemas and approval strengths
• POST /api/auth/agent/introspect — RFC 7662-style, re-evaluates session lifecycle at query time
• GET /api/auth/agent/jwks — signing keys for agent-facing JWT verification
• /.well-known/agent-card.json — A2A agent card with agent-auth security scheme

What changed

New (apps/web)

• Schema: agent_host, agent_session, agent_host_policy, agent_session_grant, capability_usage_ledger
• CIBA: grant-evaluation.ts, agent-binding.ts, agent-jwt.ts, agent-lifecycle.ts, aap-profile.ts, pairwise-agent.ts, usage-ledger.ts, approval-path.ts
• Auth: principal boundary helpers, agent registration routes, introspection, capability discovery, host key rotation, revocation
• Dashboard: /dashboard/agents management UI
• Identity: hardened JWKS fetcher for vendor attestation

New (apps/mcp)

• Persistent Ed25519 host key with XDG-compliant storage
• Host + session registration on every startup
• Agent-Assertion attached to all CIBA requests
• Tools surface agent identity and authorization_details

New (apps/demo-rp)

• Agent runtime module with Ed25519 key management
• Aether AI scenario updated for AAP token flow

Removed

• Boundary system (agent-boundaries.ts, boundary-evaluation.ts, auto-approve.ts, /dashboard/agent-policies)
• agent-claims.ts (replaced by aap-profile.ts)
• agentic-authorization.md (replaced by agent-architecture.md)