Auth4Agent Server

Auth4Agent Server is the trust and authentication infrastructure behind the Auth4Agent protocol.

It is responsible for:

• operator trust management
• DID registration
• challenge issuance
• proof verification
• scoped JWT issuance
• authorization enforcement
• JWKS publication
• revocation infrastructure

The server acts as the trust anchor for autonomous agents operating inside a verified domain boundary.

---

Why Auth4Agent Exists

Most authentication systems were designed around human interaction:

• browser sessions
• passwords
• OAuth redirects
• user accounts

Autonomous systems behave differently.

AI agents and machine workloads:

• communicate continuously
• authenticate without human interaction
• move across infrastructure boundaries
• require portable identity
• need verifiable trust relationships

Existing approaches usually rely on:

• long-lived API keys
• centralized service accounts
• infrastructure-scoped credentials

These approaches create several problems:

• credential leakage
• weak identity ownership
• poor auditability
• difficult rotation
• over-privileged access
• no machine-native trust model

Auth4Agent was designed to provide:

• decentralized machine identity
• cryptographic authentication
• scoped credentials
• operator-controlled authorization
• portable trust boundaries

---

Core Concepts

---

Operator

An operator represents a trust domain.

Examples:

• organization
• AI platform
• company
• infrastructure owner
• autonomous system provider

Operators:

• verify domain ownership
• establish root trust
• define authorization policy
• manage agent permissions

Example:

example.com

Operators are the authorization authority.

---

Agent

An agent is an autonomous machine identity.

Examples:

• AI assistants
• backend services
• orchestrators
• robotics systems
• drone controllers
• MCP servers
• infrastructure workers

Each agent:

• owns its own private key
• has its own DID
• authenticates independently
• requests credentials dynamically

Agents are never centrally issued static secrets.

---

DID (Decentralized Identifier)

Each agent receives a DID.

Example:

did:agent:example.com:5e5009ae48d7e3ea65545257ba3a6a7d

The DID becomes the permanent identity of the agent.

---

Challenge-Response Authentication

Instead of passwords or API keys:

1. Agent requests challenge
2. Server generates nonce-bound challenge
3. Agent signs challenge locally
4. Server verifies signature
5. JWT is issued

Private keys never leave the agent machine.

---

Authorization

Authentication alone is insufficient.

Operators define:

allowed_scopes

Example:

read:payments
read:orders
write:reports

Agents may request only scopes explicitly approved by operator policy.

Authorization is deny-by-default.

---

Architecture

┌──────────────────────┐
│      Operator        │
│  Trust + Policy      │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   Auth4Agent Server  │
│  Trust Infrastructure│
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│        Agent         │
│ DID + Private Key    │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Signed Challenge    │
│      Verification    │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│     Scoped JWT       │
└──────────────────────┘

---

Features

• DID-based machine identity
• Ed25519 proof authentication
• Challenge-response verification
• JWT issuance
• Scoped authorization
• JWKS support
• Offline verification support
• Replay protection
• Operator trust domains
• Revocation infrastructure
• Open protocol architecture

---

Security Model

---

Agents Own Keys

Private keys are:

• generated locally
• stored locally
• never uploaded

Identity belongs to the agent.

---

Replay Protection

Challenges are:

• single-use
• nonce-bound
• expiration-bound

Replay attempts are rejected.

---

Scoped Credentials

JWTs are:

• audience scoped
• permission scoped
• time bounded

---

Operator-Enforced Authorization

Agents cannot grant themselves permissions.

Authorization policy is controlled by operators.

---

JWKS-Based Verification

The server exposes:

/.well-known/jwks.json

allowing:

• offline token verification
• key discovery
• interoperable trust

---

Protocol Flow

1. operator registers trust domain
2. operator verifies DNS ownership
3. agent generates DID
4. agent registers DID
5. operator assigns scopes
6. agent requests challenge
7. agent signs challenge
8. server verifies proof
9. server validates authorization
10. server issues JWT
11. services verify JWT using JWKS

---

Installation

See:

• SETUP.md

---

Endpoints

---

Discovery

GET /.well-known/auth4agent

Provides:

• issuer metadata
• protocol metadata
• endpoint discovery

---

JWKS

GET /.well-known/jwks.json

Provides:

• public signing keys
• key IDs
• algorithm metadata

---

Challenge

POST /v1/challenge

Creates authentication challenge.

---

Token

POST /v1/token

Verifies proof and issues JWT.

---

Verify

POST /v1/verify

Performs:

• signature verification
• revocation checks
• token validation

---

DID Resolution

GET /v1/agent/:did

Resolves agent metadata.

---

Example JWT Claims

{
  "iss": "https://auth.example.com",
  "sub": "did:agent:example.com:...",
  "aud": ["api.example.com"],
  "scope": "read:payments",
  "operator_id": "uuid",
  "exp": 1778068315
}

---

Database Tables

The server initializes:

• operators
• agents
• challenges
• token_revocations
• audit_logs
• jwks_keys

---

Current Status

Implemented:

• operator registration
• DNS verification
• DID registration
• challenge-response authentication
• scoped JWT issuance
• replay protection
• authorization enforcement
• JWKS publishing
• offline verification support

Planned:

• federation trust
• distributed revocation
• delegated capabilities
• attestation support
• multi-issuer trust
• key rotation persistence
• trust graph infrastructure

---

Production Notes

This server implements security-sensitive infrastructure.

Before production deployment:

• enable HTTPS
• rotate signing keys
• isolate PostgreSQL
• monitor audit logs
• secure operator access
• review threat model
• harden deployment environment

Do not expose development keys publicly.

---

Project Structure

cmd/server/
internal/
├── auth/
├── db/
├── handlers/
├── http/
├── jobs/
├── service/

---

Design Goals

Auth4Agent is designed around several principles.

---

Machine-Native Authentication

No browser assumptions. No human login dependency.

---

Cryptographic Identity Ownership

Identity belongs to the agent, not the server.

---

Portable Trust

Agents should preserve identity across:

• infrastructure
• deployments
• providers

---

Decentralized Trust Boundaries

Operators establish trust domains without central identity ownership.

---

Open Protocol Architecture

The protocol is designed to be:

• inspectable
• interoperable
• extensible

---

Security Warning

This project is still early-stage infrastructure software.

Do not assume:

• formal audit
• production hardening
• protocol stability

Review and validate before production usage.

---

License

MIT