Discovery API (v1.1)

Cross-language parity for AID discover() wrappers with consistent security and fallback behavior.

Common behaviors

IDNA: Normalize domains to A-label (Punycode) before DNS.
DNS-first: Query _agent.<domain>. When protocol is specified, try _agent._<proto>.<domain> then _agent.<proto>.<domain> before base.
TXT parsing: Enforce v1.1 record rules (aliases, schemes, metadata constraints).
PKA: When pka/kid present, perform Ed25519 HTTP Message Signatures handshake with exact covered fields set.
Well-known fallback: Only on ERR_NO_RECORD or ERR_DNS_LOOKUP_FAILED. HTTPS JSON, ≤64KB, ~2s timeout, no redirects. Successful fallback uses TTL=300.
Redirect policy: Do not auto-follow redirects for handshake or well-known.

TypeScript/Node: { protocol?: string; timeout?: number; wellKnownFallback?: boolean; wellKnownTimeoutMs?: number }
Python: discover(domain, *, protocol=None, timeout=5.0, well_known_fallback=True, well_known_timeout=2.0)
- Accepts camelCase aliases wellKnownFallback and wellKnownTimeoutMs (deprecated with warnings)
Go: DiscoverWithOptions(domain string, timeout time.Duration, opts DiscoveryOptions)
- DiscoveryOptions{ Protocol string; WellKnownFallback bool; WellKnownTimeout time.Duration }
Rust: discover_with_options(domain: &str, options: DiscoveryOptions)
- DiscoveryOptions { protocol: Option<String>, timeout: Duration, well_known_fallback: bool, well_known_timeout: Duration }
.NET: Discovery.DiscoverAsync(string domain, DiscoveryOptions? options = null)
- DiscoveryOptions { string? Protocol; TimeSpan Timeout; bool WellKnownFallback; TimeSpan WellKnownTimeout }
Java: Discovery.discover(String domain, DiscoveryOptions options)
- DiscoveryOptions { String protocol; Duration timeout; boolean wellKnownFallback; Duration wellKnownTimeout }

Loopback relax: allowed only for .well-known fallback and only on loopback hosts; env/flag gated per language (never for TXT).
Rust PKA is behind the handshake feature; enable it to run handshake verification.
Test your implementation using the aid-doctor CLI tool for real-world validation.