@agentcommunity/aid

Agent Identity & Discovery

DNS for Agents

AID as the public address book for the agentic web.

It's a simple, open standard that uses the internet's own directory—DNS—to answer one question: "Given a domain, where is its AI agent, and how do I know it's the real one?"

No more hunting through API docs. No more manual configuration. It's the zero-friction layer for a world of interconnected agents.

Built by the team at agentcommunity.org.

• Website: aid.agentcommunity.org
• Docs: docs.agentcommunity.org/aid
• GitHub: github.com/agent-community/agent-identity-discovery

Install

pnpm add @agentcommunity/aid
# or
npm install @agentcommunity/aid
# or
yarn add @agentcommunity/aid

Quick Start (Node.js)

import { discover, AidError } from '@agentcommunity/aid';

try {
  const { record, ttl, queryName } = await discover('example.com');
  console.log('Found', record.proto, 'at', record.uri, 'TTL:', ttl, 'query:', queryName);
} catch (e) {
  if (e instanceof AidError) {
    console.error(`AID Error (${e.code})`, e.errorCode, e.message);
  } else {
    console.error('Unexpected error', e);
  }
}

Quick Start (Browser)

import { discover } from '@agentcommunity/aid/browser';

const { record } = await discover('example.com');
console.log('Agent:', record.proto, record.uri);

API

• discover(domain: string, options?) → { record, ttl, queryName }
  • Node uses DNS; Browser uses DNS-over-HTTPS.
  • Canonical query is _agent.<exact-host>. Clients do not implicitly walk to parent hosts. Protocol-specific _agent._<proto>.<exact-host> probing is legacy, diagnostic, or base-failure-only behavior where explicitly supported and configured.
  • Enterprise controls: securityMode: 'balanced' | 'strict' plus low-level policy knobs for DNSSEC, PKA, downgrade handling, and .well-known.
• parse(txt: string) → validated AID record
• AidError – error class exposing code (numeric) and errorCode (symbol)
• Constants and types exported from @agentcommunity/aid

Example: enterprise policy preset

import { discover } from '@agentcommunity/aid';

const result = await discover('example.com', {
  securityMode: 'balanced',
  previousSecurity: {
    version: 'aid2',
    keyThumbprints: ['WWpn_pfHui9YKR4CZtQsDGMu7_Gch2zYChfSvnxgtPk'],
    trustSource: 'dns',
  },
});

console.log(result.security.mode);
console.log(result.security.warnings);

v2.0 Notes

• New records default to aid2.
• pka (k) is the unpadded base64url Ed25519 JWK x value.
• DNS kid (i) is invalid for aid2; clients derive the RFC 7638 JWK thumbprint and use it as the HTTP signature keyid.
• The client sends Accept-Signature with an RFC 9421 nonce. The server returns Signature-Input and Signature.
• created and expires are mandatory. The response must include Cache-Control: no-store.
• v2 PKA does not sign HTTP Date and does not use AID-Challenge.

v2 PKA handshake expectations (summary)

• Covered fields set: "@method";req, "@target-uri";req, "@authority";req, and "@status".
• alg="ed25519", compared case-insensitively while preserving the received signature parameters.
• keyid equals the RFC 7638 thumbprint derived from k.
• nonce exactly matches the value sent in Accept-Signature.
• expires is after created and the validity window is short.
• pka is unpadded base64url for a 32-byte Ed25519 public key.

Legacy aid1 Notes (PKA + .well-known)

• Legacy aid1 fields: pka (k) and kid (i). When an aid1 record includes pka, the client performs a Public Key for Agent (PKA) handshake using HTTP Message Signatures (Ed25519).
• Legacy aid1 pka is a multibase string using base58btc (z...) of the raw 32-byte Ed25519 public key.
• Legacy aid1 handshake coverage: required fields are "AID-Challenge" "@method" "@target-uri" "host" "date".
• Legacy aid1 time window: both created and HTTP Date must be within ±300 seconds of now.
• Fallback: when DNS has ERR_NO_RECORD or ERR_DNS_LOOKUP_FAILED, discovery may fetch https://<domain>/.well-known/agent (TLS‑anchored) and validate the same data model; if the JSON contains pka, the handshake runs.

Legacy v1 PKA handshake expectations (summary)

• Covered fields set (exact): "AID-Challenge" "@method" "@target-uri" "host" "date"
• alg="ed25519"
• keyid equals record kid (normalize quotes for compare, preserve raw in base)
• created ± 300 seconds of current time
• HTTP Date ± 300 seconds of current time
• pka is multibase base58btc (z...) of a 32‑byte Ed25519 public key

Dev‑only loopback relax (well‑known)

For local testing against a mock HTTP server, the CLI and Node variant support a narrow, opt‑in relaxation:

• Set AID_ALLOW_INSECURE_WELL_KNOWN=1
• Host must be loopback (localhost, 127.0.0.1, or ::1)
• Only affects .well-known fallback; TXT path remains strict
• Validation is performed with a temporary https:// substitute, and the discovered http:// URI is restored afterward

This is intended for local development only. Production remote agents MUST use https://.

Example: guarded .well-known fallback

import { discover } from '@agentcommunity/aid';

const { record, queryName } = await discover('example.com', {
  wellKnownFallback: true,
  wellKnownTimeoutMs: 2000,
});

console.log('Query:', queryName); // either DNS name or https://<domain>/.well-known/agent

PKA handshake runs automatically when record.pka is present.

Error Codes

• 1000 ERR_NO_RECORD – no _agent TXT found
• 1001 ERR_INVALID_TXT – malformed record
• 1002 ERR_UNSUPPORTED_PROTO – protocol not supported
• 1003 ERR_SECURITY – security policy violation
• 1004 ERR_DNS_LOOKUP_FAILED – DNS lookup failed
• 1005 ERR_FALLBACK_FAILED – .well‑known fallback failed or invalid

Security Notes

• Remote agent URIs MUST use https://.
• Handshake verifies endpoint control when pka is present (Ed25519 HTTP Message Signatures).
• .well-known is optional and TLS‑anchored; use DNS first.

Redirect Security

Clients do not automatically follow cross‑origin redirects from the discovered URI. If an initial request returns a 301/302/307/308 to a different origin (hostname or port), the client treats it as a potential security risk. Implementations either surface ERR_SECURITY or require explicit confirmation. See the spec for details.

More on PKA

See the Identity & PKA reference for the exact v2 header coverage, algorithm, timestamps, key format, and legacy v1 compatibility behavior.

License

MIT © Agent Community