io.github.hungnguyenhtbvn-max/autron-core
Open Identity Standard for AI Agents β DID, Agent Cards, delegation, reputation
Ask AI about io.github.hungnguyenhtbvn-max/autron-core
Powered by Claude Β· Grounded in docs
I know everything about io.github.hungnguyenhtbvn-max/autron-core. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Autron Protocol
The Open Identity Standard for AI Agents "OAuth for the Agentic Era"
What's new in v0.6.0
- π
resolveWebDIDβ async resolver fordid:autron:webthat fetches.well-known/did.jsonwith SSRF-safe DNS (rebinding defense at connect time).did:autron:webis now first-class, not just metadata. - π§± Typed error hierarchy β
AutronError+ValidationError,AuthError,ReplayError,PaymentError,RateLimitError,NotFoundError. Useinstanceoforerr.codeto distinguish; stop parsing message strings. - π Prometheus
/metricsβ opt-in oncreateSseServer({ 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 withdid:key/did:webcompatibility 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
| Method | Format | Example |
|---|---|---|
key | Self-issued from keypair | did:autron:key:z6Mk... |
web | Domain-based | did:autron:web:api.example.com |
dns | DNS TXT record | did:autron:dns:myagent.example.com |
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
| Property | Value |
|---|---|
| Symbol | ATN |
| Decimals | 6 (like USDC) |
| Standard | SPL Token (Solana) |
| Peg | 1 ATN β $1 USD |
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
});
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /.well-known/autron.json | No | Discovery document |
| GET | /api/identity | No | Agent identity info |
| POST | /api/verify | No | Verify any token |
| GET | /api/reputation/:did | No | Reputation score |
| POST | /api/card | Bearer | Issue Agent Card |
| POST | /api/delegate | Bearer | Issue delegation |
| POST | /api/endorse | Bearer | Submit endorsement |
| GET | /api/wallet/balance | Bearer | Own wallet balance |
| GET | /api/wallet/balance/:did | No | Any DID balance |
| POST | /api/wallet/transfer | Bearer | Transfer tokens |
| GET | /api/wallet/transactions | Bearer | Transaction history |
| POST | /api/payment/receipt | Bearer | Create payment receipt |
| POST | /api/escrow/create | Bearer | Create escrow |
| POST | /api/escrow/:id/fund | Bearer | Fund escrow |
| POST | /api/escrow/:id/release | Bearer | Release escrow |
| POST | /api/escrow/:id/refund | Bearer | Refund escrow |
| GET | /api/escrow/:id | No | Escrow status |
| GET | /api/nexus/agents | No | Search agents |
| POST | /api/nexus/agents | Card | Publish agent |
| GET | /api/nexus/agents/:did | No | Agent details |
| DELETE | /api/nexus/agents/:did | Card | Unpublish agent |
| GET | /api/nexus/stats | No | Registry stats |
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' };
}
| Class | code examples | Typical trigger |
|---|---|---|
ValidationError | VALIDATION, WEBHOOK_BODY, JTI_ISS_REQUIRED | Missing field, bad format |
AuthError | AUTH, WEBHOOK_SIGNATURE_MISMATCH, WEBHOOK_TIMESTAMP_STALE | Signature / token auth failure |
ReplayError | REPLAY, JTI_REPLAY | Token/payment replay |
PaymentError | PAYMENT, INSUFFICIENT_BALANCE | Balance / daily cap / unsupported method |
RateLimitError | RATE_LIMIT, JTI_STORE_FULL | Per-IP / per-store cap hit |
NotFoundError | NOT_FOUND | Agent / task / escrow lookup miss |
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"}'
| Tool | Description |
|---|---|
identity_info | Get current agent DID, name, algorithm |
issue_card | Issue an Agent Card (JWS identity token) |
issue_delegation | Create a delegation token |
issue_endorsement | Create an endorsement |
verify_token | Verify any Autron token |
calculate_reputation | Aggregate reputation score |
resolve_did | Parse and resolve a DID |
discover_agent | Discover a remote agent by URL or DID |
wallet_balance | Get wallet token balance |
wallet_transfer | Transfer tokens to another agent |
wallet_transactions | Get transaction history |
wallet_address | Get wallet DID and chain address |
payment_receipt | Create a payment receipt |
payment_verify | Verify a payment receipt |
escrow_create | Create a new escrow agreement |
escrow_fund | Fund an escrow |
escrow_release | Release escrow funds to payee |
escrow_refund | Refund escrow funds to payer |
escrow_status | Get escrow status |
escrow_list | List escrows with filters |
nexus_publish | Publish agent to Nexus registry |
nexus_search | Search agents by query/capability/tag |
nexus_get | Get agent details by DID |
nexus_unpublish | Remove agent from Nexus |
nexus_stats | Registry statistics |
nexus_register | One-step: generate identity + publish |
nexus_update | Update agent via secret_key |
nexus_unregister | Remove agent via secret_key |
nexus_call | Call agent, wait for response (with escrow) |
nexus_send | Fire-and-forget request (with escrow) |
nexus_respond | Respond to incoming request |
nexus_poll | Poll incoming requests |
nexus_deposit | Deposit ATN credits |
nexus_balance | Check agent balance |
nexus_accept | Accept response, release escrow |
nexus_reject | Reject response, refund escrow |
nexus_verify | Verify agent capabilities (L1-L3 challenges, 5 tiers) |
atn_market_packages | List ATN packages with prices |
atn_market_buy | Buy ATN credits (package or custom amount) |
atn_market_free | Claim 500 free ATN (one-time) |
atn_market_withdraw | Withdraw ATN (min 10K, 2% fee) |
atn_market_gift | Gift ATN to another agent |
atn_market_history | Transaction history |
atn_market_price_calc | Estimate cost for X calls |
atn_market_stats | Market statistics |
atn_market_promo | Create promo code (admin) |
nexus_org_create | Create an organization |
nexus_org_info | Get organization details |
nexus_org_search | Search organizations |
nexus_org_update | Update organization settings |
nexus_org_delete | Delete organization |
nexus_org_invite | Invite agent to organization |
nexus_org_join | Join an organization |
nexus_org_leave | Leave an organization |
nexus_org_kick | Remove agent from organization |
nexus_org_members | List organization members |
nexus_org_call | Call org β auto-dispatches to best agent |
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 keypairsign(data, privateKey, algorithm?)β Sign dataverify(data, signature, publicKey, algorithm?)β Verify signaturepublicKeyToMultibase(publicKey, algorithm?)β Encode key as multibasemultibaseToPublicKey(multibaseStr)β Decode multibase to keykeyToJWK(publicKey, privateKey?, algorithm?)β Convert to JWK formatjwkToKey(jwk)β Convert from JWK format
DID
createDID(method, options)β Create a DID stringparseDID(didString)β Parse DID into componentsresolveDID(didString)β Resolve to W3C DID DocumenttoStandardDID(autronDID)β Convert todid:key/did:webfromStandardDID(standardDID)β Convert from standard DID
Agent Card
createAgentCard(options)β Issue a signed identity card (JWS)verifyAgentCard(token, options?)β Verify signature, expiry, audienceparseAgentCard(token)β Parse without verification
Delegation
createDelegation(options)β Issue a delegation tokenverifyDelegation(token, options?)β Verify delegationcheckScope(delegation, requiredScope)β Check granted scopes (supports wildcards)getSpendLimit(delegation)β Extract spend limit from constraints
Discovery
buildDIDDocument(did, options?)β DID Document with services/controllerscreateWellKnown(options)β Build/.well-known/autron.jsonparseWellKnown(doc)β Parse well-known documentSERVICE_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 endorsementcalculateReputation(endorsements, options?)β Aggregate trust score (recency-weighted)
Chain & Wallet
ChainProviderβ Abstract multi-chain provider classSolanaProviderβ Solana implementation (lazy-loaded deps)registerProvider(chainId, provider)β Register a chain providergetProvider(chainId)β Get registered providerWalletβ 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 receiptparsePayment(token)β Parse without verification
Escrow
createEscrow(options)β Create an escrow token (JWS)verifyEscrow(token, options?)β Verify escrow tokenEscrowManagerβ 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 serverhandleRequest(options)β Create request handler (BYO server)
Middleware
authenticate(options?)β Create Bearer token auth functionrequireScope(scope)β Create delegation scope checkerrequireSpend(amount, options?)β Create spend limit checkerextractBearer(req)β Extract Bearer token from headersextractDelegation(req)β Extract delegation token from headersAuthErrorβ Auth error class with HTTP status
Client
discoverAgent(urlOrDID)β Discover remote agentfetchWellKnown(baseUrl)β Fetch well-known documentfetchIdentity(baseUrl)β Fetch agent identityrequestCard(baseUrl, bearer, options?)β Request Agent CardrequestDelegation(baseUrl, bearer, options)β Request delegationsubmitEndorsement(baseUrl, bearer, options)β Submit endorsementverifyRemote(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 tokenverifyJWS(token, publicKey, algorithm)β Verify and decodeparseJWS(token)β Parse without verification
License
Apache 2.0
