Autron Protocol

The Open Identity Standard for AI Agents "OAuth for the Agentic Era"

What's new in v0.6.0

• 🌐 `resolveWebDID` — async resolver for did:autron:web that fetches

.well-known/did.json with SSRF-safe DNS (rebinding defense at connect time). did:autron:web is now first-class, not just metadata.

• 🧱 Typed error hierarchy — AutronError + ValidationError,

AuthError, ReplayError, PaymentError, RateLimitError, NotFoundError. Use instanceof or err.code to distinguish; stop parsing message strings.

• 📊 Prometheus `/metrics` — opt-in on createSseServer({ metrics: true }).

Exposes SSE sessions, rate-limit map sizes, per-agent webhook breaker state, ATN totals, and registry counts.

14 security-audit rounds, 662 tests, production-deployed. See examples/ for runnable recipes and CHANGELOG.md for the full history.

Install

npm install @autron/core

Quick Start

const { generateKeypair, createDID, resolveDID, toStandardDID } = require('@autron/core');

const keys = generateKeypair();
const did = createDID('key', keys);
console.log('Agent DID:', did);
// → did:autron:key:z6Mk...

const doc = resolveDID(did);
console.log('DID Document:', JSON.stringify(doc, null, 2));

// Compatible with standard DIDs
console.log('Standard:', toStandardDID(did));
// → did:key:z6Mk...

Why Autron?

• Simple: Agent identity in 5 minutes, any language
• Self-contained: Core identity works without blockchain or central server
• Cryptographically secure: Ed25519 / secp256k1 signatures
• Compatible: W3C DID, JWT/JWS, works with MCP & A2A
• Payment-ready: Optional on-chain payments with Solana (ATN token)
• Brand-first: did:autron:* namespace with did:key/did:web compatibility mapping
• TypeScript ready: Full type declarations included

Architecture

Layer 0: Crypto        — Ed25519 / secp256k1 keypairs, JWK, multibase
Layer 1: DID           — did:autron:key / web / dns
Layer 2: Agent Card    — Short-lived identity tokens (agent-card+jwt)
Layer 3: Delegation    — Scoped permission tokens (delegation+jwt)
Layer 4: Reputation    — Endorsements & trust scores (endorsement+jwt)
Layer 5: Payment       — On-chain payments & escrow (payment+jwt, escrow+jwt)
Layer 6: Nexus         — Agent registry & marketplace (SQLite, MCP SSE)

Layers 0-4 work standalone. Layer 5 requires @solana/web3.js (lazy-loaded). Layer 6 adds a searchable agent registry with MCP remote access.

DID Methods

Resolving did:autron:web (v0.6.0+)

Fetch the hosted DID Document from /.well-known/did.json on the encoded domain:

const { resolveWebDID } = require('@autron/core');

const doc = await resolveWebDID('did:autron:web:api.example.com');
console.log(doc.verificationMethod[0].publicKeyMultibase);

// Path-based (hosted at /agents/bot/did.json):
await resolveWebDID('did:autron:web:api.example.com:agents:bot');

// Port-encoded (per spec: %3A = `:`):
await resolveWebDID('did:autron:web:api.example.com%3A8443');

// Local dev: opt into private-IP targets
await resolveWebDID('did:autron:web:127.0.0.1%3A3000', { allowPrivate: true });

The resolver is SSRF-safe: it re-validates the DNS-resolved address at connect time (defeating DNS rebinding), rejects oversized responses (128 KiB default), and requires document.id to match the requested DID (or the standard did:web: form).

Runnable: examples/01-did-web-identity.js

Agent Card

Issue and verify cryptographic identity cards (JWS compact serialization):

const { generateKeypair, createDID, createAgentCard, verifyAgentCard } = require('@autron/core');

const keys = generateKeypair();
const did = createDID('key', keys);

// Issue a card (short-lived JWS token)
const card = createAgentCard({
  issuer: did,
  privateKey: keys.privateKey,
  name: 'MyAgent',
  capabilities: ['chat', 'search'],
  ttl: 86400, // 24 hours
});

// Verify (extracts public key from DID automatically)
const { issuer, subject, payload } = verifyAgentCard(card);

Delegation

Grant scoped permissions to other agents:

const { createDelegation, verifyDelegation, checkScope } = require('@autron/core');

const token = createDelegation({
  delegator: parentDID,
  delegate: childDID,
  privateKey: parentKeys.privateKey,
  scope: ['read:*', 'write:messages'],
  constraints: { maxCalls: 100 },
  ttl: 3600, // 1 hour
});

const result = verifyDelegation(token);
checkScope(result, 'read:files');     // true (matches read:*)
checkScope(result, 'write:messages'); // true (exact match)
checkScope(result, 'admin');          // false

Reputation

Endorse other agents and calculate trust scores:

const { createEndorsement, verifyEndorsement, calculateReputation } = require('@autron/core');

// Endorse another agent
const endorsement = createEndorsement({
  endorser: myDID,
  subject: otherDID,
  privateKey: myKeys.privateKey,
  rating: 0.9,
  categories: ['coding', 'search'],
  comment: 'Reliable agent',
});

// Aggregate reputation from multiple endorsements
const rep = calculateReputation(verifiedEndorsements);
console.log(rep.score);      // 0.0-1.0 (recency-weighted average)
console.log(rep.categories); // { coding: { score: 0.9, count: 3 }, ... }

Payment & Escrow

On-chain payments between agents using Solana. Autron Ed25519 keys are natively compatible with Solana — zero key conversion needed.

Wallet

const { Wallet } = require('@autron/core');

// Create wallet from identity (reads autron.json)
const wallet = Wallet.create(identity, { chain: 'solana' });

console.log(wallet.address);  // Solana base58 address
console.log(wallet.chainId);  // 'solana:devnet'

// Check balance
const balance = await wallet.getBalance();

// Transfer ATN tokens
const tx = await wallet.transfer(recipientDID, 1000000); // 1 ATN
console.log(tx.txId);

Payment Receipts

Cryptographic proof of on-chain payments:

const { createPayment, verifyPayment } = require('@autron/core');

// Create receipt after a transfer
const receipt = createPayment({
  payer: myDID,
  payee: otherDID,
  privateKey: myKeys.privateKey,
  txId: 'solana-tx-id...',
  amount: 1000000,
  chain: 'solana:devnet',
  memo: 'Payment for coding service',
});

// Verify receipt
const { payer, payee, txId, amount, chain } = verifyPayment(receipt);

Escrow

Hold funds in escrow with conditions and deadlines:

const { createEscrow, EscrowManager } = require('@autron/core');

// Create escrow agreement
const escrowToken = createEscrow({
  payer: myDID,
  payee: freelancerDID,
  privateKey: myKeys.privateKey,
  amount: 5000000, // 5 ATN
  chain: 'solana:devnet',
  conditions: 'Deliver code by Friday',
  deadline: Math.floor(Date.now() / 1000) + 7 * 86400, // 7 days
});

// Manage escrow lifecycle
const manager = new EscrowManager({ dbPath: './escrow.db' });
const { escrowId } = manager.register(escrowToken);
await manager.fund(escrowId);     // payer → escrow
await manager.release(escrowId);  // escrow → payee
// or: await manager.refund(escrowId);  // escrow → payer

ATN Token

Discovery

Build discoverable DID Documents and well-known metadata:

const { buildDIDDocument, createWellKnown, SERVICE_TYPES } = require('@autron/core');

// DID Document with service endpoints
const doc = buildDIDDocument(did, {
  services: [
    { type: SERVICE_TYPES.AGENT_CARD, serviceEndpoint: 'https://example.com/card' },
    { type: SERVICE_TYPES.PAYMENT, serviceEndpoint: 'https://example.com/pay' },
    { type: SERVICE_TYPES.API, serviceEndpoint: 'https://example.com/api/v1' },
  ],
});

// /.well-known/autron.json
const wk = createWellKnown({
  did,
  name: 'MyAgent',
  capabilities: ['chat', 'search'],
  cardEndpoint: 'https://example.com/.well-known/agent-card',
});

HTTP Server

Run a full identity server with discovery, verification, wallet, and escrow endpoints:

const { generateKeypair, createDID, createServer } = require('@autron/core');

const keys = generateKeypair();
const did = createDID('key', keys);

const server = createServer({
  identity: { did, privateKey: keys.privateKey, name: 'MyAgent' },
  port: 3000,
  cors: true,
  // wallet,        // optional: enable wallet endpoints
  // escrowManager, // optional: enable escrow endpoints
});

Error handling (v0.6.0+)

Every error thrown by @autron/core is either a plain Error (for genuinely unexpected issues) or an AutronError subclass. Use instanceof or err.code to route:

const {
  ValidationError, AuthError, ReplayError,
  PaymentError, RateLimitError, NotFoundError,
} = require('@autron/core');

function toHttpResponse(err) {
  if (err instanceof ValidationError)   return { status: 400, code: err.code, message: err.message };
  if (err instanceof AuthError)         return { status: 401, code: err.code, message: err.message };
  if (err instanceof PaymentError)      return { status: 402, code: err.code, message: err.message };
  if (err instanceof NotFoundError)     return { status: 404, code: err.code, message: err.message };
  if (err instanceof ReplayError)       return { status: 409, code: err.code, message: err.message };
  if (err instanceof RateLimitError)    return { status: 429, code: err.code, message: err.message };
  return { status: 500, code: 'INTERNAL', message: 'Internal error' };
}

Runnable: examples/02-error-handling.js

Observability (v0.6.0+)

Opt in to the Prometheus /metrics endpoint on createSseServer:

const { NexusRegistry, createSseServer } = require('@autron/core');

createSseServer({
  nexus: new NexusRegistry({ dbPath: './nexus.db' }),
  port: 3100,
  metrics: true,   // ← exposes /metrics
});

The endpoint returns Prometheus 0.0.4 text format. Exposed metrics: autron_version_info, autron_sse_sessions_active, autron_listen_sessions_active, autron_rate_limit_keys{bucket}, autron_nexus_agents{status}, autron_atn_total_bought, autron_atn_total_withdrawn, autron_webhook_breaker{state}.

Runnable: examples/03-prometheus-metrics.js

Webhook receiver (v0.6.0+)

Nexus delivers agent-bound events as HMAC-signed HTTPS POSTs. Verify them using the canonical helper:

const { verifyWebhookSignature, AuthError } = require('@autron/core');

app.post('/nexus/webhook', async (req, res) => {
  try {
    verifyWebhookSignature({
      body: req.rawBody,                           // Buffer — NOT JSON-parsed
      signature: req.headers['x-nexus-signature'],
      timestamp: req.headers['x-nexus-timestamp'],
      secret: WEBHOOK_SECRET,                      // from nexus_set_webhook
      maxSkewSec: 300,                             // freshness window
    });
    // signature + timestamp OK → dispatch
  } catch (e) {
    if (e instanceof AuthError) return res.status(401).end();
    return res.status(400).end();
  }
});

Runnable: examples/04-webhook-receiver.js

Middleware

Protect your endpoints with Agent Card authentication and delegation scope checks:

const { authenticate, requireScope, requireSpend, AuthError } = require('@autron/core');

const auth = authenticate({ audience: myDID });
const scopeCheck = requireScope('write:messages');
const spendCheck = requireSpend(1000000); // enforce spend limit from delegation

function handleRequest(req, res) {
  try {
    const agent = auth(req);         // Verify Bearer Agent Card
    const deleg = scopeCheck(req);   // Verify X-Delegation-Token scope
    // agent.did, agent.name, agent.capabilities
    // deleg.delegator, deleg.scope, deleg.constraints
  } catch (err) {
    if (err instanceof AuthError) {
      res.writeHead(err.status);
      res.end(err.message);
    }
  }
}

MCP Server

Expose Autron identity and Nexus operations as MCP tools for AI agents:

npx autron mcp          # stdio transport (local)
npx autron-mcp          # direct binary (local)
npx autron-mcp-sse      # SSE transport (remote, port 3100)

Local (stdio) — Claude Code / Cursor (mcp.json):

{
  "mcpServers": {
    "autron": {
      "command": "npx",
      "args": ["autron-mcp"]
    }
  }
}

Remote (SSE) — OpenClaw / any MCP client:

openclaw mcp set autron '{"url":"http://your-server:3100/sse"}'

Resources: autron://identity, autron://well-known

Nexus Registry

Searchable agent marketplace with verification tiers (Baby -> Junior -> Pro -> Expert -> Elite). Agents prove identity with Agent Cards and can verify capabilities through challenge-based evaluation:

const { generateKeypair, createDID, createAgentCard, NexusRegistry } = require('@autron/core');

const keys = generateKeypair();
const did = createDID('key', keys);

// Publish
const nexus = new NexusRegistry({ dbPath: './nexus.db' });
const card = createAgentCard({ issuer: did, privateKey: keys.privateKey, name: 'MyBot', capabilities: ['chat'] });
nexus.publish({ card_token: card, description: 'A chat assistant', tags: ['chat', 'ai'] });

// Search
const results = nexus.search({ capability: 'chat', min_reputation: 0.5 });
console.log(results.agents);  // [{ did, name, capabilities, reputation, ... }]

// Stats
const stats = nexus.stats();
console.log(stats);  // { total, active, capabilities: { chat: 10, ... }, recent: [...] }

CLI

# Identity
npx autron init --name "MyAgent"    # Generate identity → autron.json
npx autron info                     # Show current identity
npx autron card --ttl 24h           # Issue an Agent Card
npx autron verify <token>           # Verify any token
npx autron endorse <did> --rating 0.9 --category coding
npx autron delegate <did> --scope "read:*,write:*"

# Wallet & Payments
npx autron wallet balance            # Show ATN balance
npx autron wallet transfer <did> --amount 1000000
npx autron wallet address            # Show Solana address
npx autron wallet airdrop            # Request devnet SOL

# Token Management
npx autron token create-mint --name "Autron Token" --symbol ATN
npx autron token mint --to <did> --amount 1000000000
npx autron token info

# Payment Receipts
npx autron payment receipt <payee> <txId> <amount>
npx autron payment verify <token>

# Escrow
npx autron escrow create <payee> --amount 5000000 --deadline 7d
npx autron escrow fund <id>
npx autron escrow release <id>
npx autron escrow status <id>
npx autron escrow list --status funded

# Server
npx autron serve --port 3000 --cors
npx autron mcp                       # Start MCP server

TypeScript

Full type declarations are included — no @types package needed:

import {
  generateKeypair,
  createDID,
  createAgentCard,
  verifyAgentCard,
  Wallet,
  createPayment,
  EscrowManager,
  type Keypair,
  type VerifiedAgentCard,
  type VerifiedPayment,
  type Algorithm,
} from '@autron/core';

const keys: Keypair = generateKeypair('ed25519');
const did: string = createDID('key', { publicKey: keys.publicKey });
const card: string = createAgentCard({ issuer: did, privateKey: keys.privateKey });
const result: VerifiedAgentCard = verifyAgentCard(card);

API

Crypto

• generateKeypair(algorithm?) — Generate Ed25519 or secp256k1 keypair
• sign(data, privateKey, algorithm?) — Sign data
• verify(data, signature, publicKey, algorithm?) — Verify signature
• publicKeyToMultibase(publicKey, algorithm?) — Encode key as multibase
• multibaseToPublicKey(multibaseStr) — Decode multibase to key
• keyToJWK(publicKey, privateKey?, algorithm?) — Convert to JWK format
• jwkToKey(jwk) — Convert from JWK format

DID

• createDID(method, options) — Create a DID string
• parseDID(didString) — Parse DID into components
• resolveDID(didString) — Resolve to W3C DID Document
• toStandardDID(autronDID) — Convert to did:key / did:web
• fromStandardDID(standardDID) — Convert from standard DID

Agent Card

• createAgentCard(options) — Issue a signed identity card (JWS)
• verifyAgentCard(token, options?) — Verify signature, expiry, audience
• parseAgentCard(token) — Parse without verification

Delegation

• createDelegation(options) — Issue a delegation token
• verifyDelegation(token, options?) — Verify delegation
• checkScope(delegation, requiredScope) — Check granted scopes (supports wildcards)
• getSpendLimit(delegation) — Extract spend limit from constraints

Discovery

• buildDIDDocument(did, options?) — DID Document with services/controllers
• createWellKnown(options) — Build /.well-known/autron.json
• parseWellKnown(doc) — Parse well-known document
• SERVICE_TYPES — Standard service type constants (AgentCard, Delegation, Messaging, API, Payment, Escrow, Wallet)

Reputation

• createEndorsement(options) — Issue a signed endorsement (0.0-1.0 rating)
• verifyEndorsement(token, options?) — Verify endorsement
• calculateReputation(endorsements, options?) — Aggregate trust score (recency-weighted)

Chain & Wallet

• ChainProvider — Abstract multi-chain provider class
• SolanaProvider — Solana implementation (lazy-loaded deps)
• registerProvider(chainId, provider) — Register a chain provider
• getProvider(chainId) — Get registered provider
• Wallet — High-level wallet (balance, transfer, transactions)
• Wallet.create(identity, options?) — Factory from autron.json identity

Payment

• createPayment(options) — Create a payment receipt (JWS)
• verifyPayment(token, options?) — Verify payment receipt
• parsePayment(token) — Parse without verification

Escrow

• createEscrow(options) — Create an escrow token (JWS)
• verifyEscrow(token, options?) — Verify escrow token
• EscrowManager — SQLite-backed escrow lifecycle (register, fund, release, refund, expire)
• ESCROW_STATUS — Status constants (created, funded, released, refunded, expired, disputed)

Server

• createServer(options) — Create and start HTTP identity server
• handleRequest(options) — Create request handler (BYO server)

Middleware

• authenticate(options?) — Create Bearer token auth function
• requireScope(scope) — Create delegation scope checker
• requireSpend(amount, options?) — Create spend limit checker
• extractBearer(req) — Extract Bearer token from headers
• extractDelegation(req) — Extract delegation token from headers
• AuthError — Auth error class with HTTP status

Client

• discoverAgent(urlOrDID) — Discover remote agent
• fetchWellKnown(baseUrl) — Fetch well-known document
• fetchIdentity(baseUrl) — Fetch agent identity
• requestCard(baseUrl, bearer, options?) — Request Agent Card
• requestDelegation(baseUrl, bearer, options) — Request delegation
• submitEndorsement(baseUrl, bearer, options) — Submit endorsement
• verifyRemote(baseUrl, token) — Verify token remotely

Nexus

• NexusRegistry — SQLite-backed agent registry (publish, search, get, unpublish, stats, expire)
• NEXUS_STATUS — Status constants (active, inactive, expired, suspended)

MCP

• createMCPServer(options?) — Create MCP server instance (57 tools, 2 resources)
• createSseServer(options?) — Create HTTP/SSE MCP transport server + Nexus HTTP API

JWS (Low-level)

• createJWS(header, payload, privateKey, algorithm) — Create JWS compact token
• verifyJWS(token, publicKey, algorithm) — Verify and decode
• parseJWS(token) — Parse without verification

License

Apache 2.0