@agentic-name-service/sdk

Orchestrates a three-party authentication handshake between an Agent, Gateway, and Guardian using MCP (Model Context Protocol) tool calls. The SDK manages the state machine for credential exchange, signature verification, and mutual authentication across distributed parties without centralizing trust. Implements a request-response pattern where the Agent initiates calls through the Gateway, which delegates verification to the Guardian, then returns authenticated tokens back through the MCP channel.

Routes MCP tool calls from agents through the Gateway with automatic injection of authentication context derived from the trilateral handshake. The SDK wraps the native MCP tool invocation mechanism, intercepts calls, appends signed auth tokens to the request metadata, and validates response signatures before returning results to the agent. Implements a middleware pattern that is transparent to the agent's tool-calling logic.

Records detailed audit logs of all authentication events (credential submission, Guardian verification, token generation, session renewal, expiration) with timestamps, actor information, and outcomes. The SDK provides structured logging hooks that emit events at each stage of the trilateral handshake, allowing downstream systems to capture and analyze authentication activity. Implements a pluggable logger interface that supports multiple backends (console, file, remote syslog, cloud logging services).

Enables a single agent to authenticate using multiple credentials (e.g., primary API key + backup certificate) and automatically fall back to alternative credentials if the primary credential fails. The SDK maintains a credential chain, attempts authentication with each credential in order, and stops at the first successful authentication. Implements a credential fallback pattern that improves resilience for agents with multiple credential sources.

Enforces fine-grained authorization based on scopes embedded in the authenticated session token. The SDK extracts scopes from the Guardian's verification proof, compares requested tool scopes against authorized scopes, and rejects tool calls that exceed the agent's authorization level. Implements a scope-matching pattern that supports both exact scope matching and wildcard scope patterns (e.g., 'tools:read:*' matches 'tools:read:users' and 'tools:read:data').

Manages the first leg of the trilateral handshake where the Agent submits its credentials to the Gateway via an MCP tool call. The SDK encapsulates the agent's identity (API key, certificate, or token) in a standardized credential envelope, sends it through the Gateway's MCP endpoint, and receives a challenge or intermediate token. Implements credential normalization to support multiple credential types (symmetric keys, asymmetric certificates, OIDC tokens) without requiring the agent to know the Gateway's preferred format.

Handles the second leg of the trilateral handshake by forwarding the Gateway's challenge to the Guardian for cryptographic verification. The SDK constructs a verification request containing the agent's credentials, the Gateway's challenge, and metadata about the authentication context, sends it through the Guardian's MCP endpoint, and receives a signed verification proof. Implements a delegation pattern where the Guardian acts as a trusted third party that validates the agent's legitimacy without the Gateway needing to store or verify credentials directly.

Synthesizes a final authenticated session token after both the Gateway and Guardian have validated the agent. The SDK combines the Gateway's intermediate token and the Guardian's verification proof into a single session token that encodes the agent's identity, verified scopes, and expiration time. Implements a token composition pattern where the final token is cryptographically bound to both the Gateway and Guardian's signatures, preventing token forgery or scope escalation.

Extracts and normalizes agent identity information from raw credentials (API keys, certificates, or tokens) into a standardized agent profile. The SDK parses credential metadata, resolves the agent's name, organization, and capabilities from a credential registry, and validates that the credential format matches the expected schema. Implements a credential-to-identity mapping that supports multiple credential sources (self-signed, CA-signed, OIDC-issued) without requiring the agent to explicitly declare its identity.

Validates that MCP tool schemas for authentication endpoints (credential-exchange, signature-verification) conform to the ANS specification before attempting to use them. The SDK inspects the tool's input/output schemas, parameter types, and required fields, and rejects tools that don't match the expected authentication interface. Implements a schema-driven validation pattern that prevents runtime errors from misconfigured authentication tools and provides clear error messages about schema mismatches.

Automatically detects the type of credential provided (API key, certificate, OIDC token, etc.) and normalizes it into a standard format for transmission to the Gateway. The SDK uses heuristics and format analysis to identify credential types without requiring explicit type declaration, then applies type-specific normalization (e.g., PEM parsing for certificates, JWT decoding for tokens). Implements a format-agnostic credential handling pattern that reduces boilerplate for agents with different credential sources.

Manages the complete lifecycle of an authenticated session from creation through expiration and renewal. The SDK tracks session state (active, expired, revoked), enforces expiration policies, and provides hooks for session renewal before expiration. Implements a state machine pattern with explicit transitions (created → active → expiring → expired or revoked), allowing agents to proactively refresh sessions before they expire and preventing use of expired tokens.

Implements configurable retry logic and error recovery strategies for authentication failures at each stage of the trilateral handshake. The SDK distinguishes between transient errors (network timeouts, temporary Guardian unavailability) and permanent errors (invalid credentials, schema mismatches), and applies appropriate recovery strategies (exponential backoff for transient, fail-fast for permanent). Implements a circuit-breaker pattern to prevent cascading failures if Guardian or Gateway becomes unavailable.