@agentcommunity/aid-engine/dist/index.d.ts

Core engine for Agent Identity & Discovery (AID) validation and discovery

import { AidRecord, ProtocolToken, AuthToken } from '@agentcommunity/aid';

interface CacheEntry {
    lastSeen: string;
    pka: string | null;
    kid: string | null;
    hash?: string | null;
}
interface ProbeAttempt {
    name: string;
    type: 'TXT' | 'RRSIG';
    result: 'NOERROR' | 'NXDOMAIN' | 'NODATA' | 'ERROR';
    ttl?: number | undefined;
    byteLength?: number;
    reason?: string;
}
interface QueriedBlock {
    strategy: 'base-first';
    hint: {
        proto?: string | undefined;
        source: 'cli' | null;
        present: boolean;
    };
    attempts: ProbeAttempt[];
    wellKnown: {
        attempted: boolean;
        used: boolean;
        url: string | null;
        httpStatus: number | null;
        contentType: string | null;
        byteLength: number | null;
        status: 'ok' | 'not_found' | 'http_error' | 'bad_content_type' | 'invalid_json' | 'oversize' | null;
        snippet: string | null;
    };
}
interface RecordBlock {
    raw: string | null;
    parsed: Partial<AidRecord> | null;
    valid: boolean;
    warnings: Array<{
        code: string;
        message: string;
    }>;
    errors: Array<{
        code: string;
        message: string;
    }>;
}
interface DnssecBlock {
    present: boolean;
    method: 'RRSIG';
    proof: unknown | null;
}
interface TlsBlock {
    checked: boolean;
    valid: boolean | null;
    host: string | null;
    sni: string | null;
    issuer: string | null;
    san: string[] | null;
    validFrom: string | null;
    validTo: string | null;
    daysRemaining: number | null;
    redirectBlocked: boolean | null;
}
interface PkaBlock {
    present: boolean;
    attempted: boolean;
    verified: boolean | null;
    kid: string | null;
    alg: string | null;
    createdSkewSec: number | null;
    covered: string[] | null;
}
interface DowngradeBlock {
    checked: boolean;
    previous: {
        pka: string | null;
        kid: string | null;
    } | null;
    status: 'no_change' | 'downgrade' | 'first_seen' | null;
}
interface DoctorReport {
    domain: string;
    queried: QueriedBlock;
    record: RecordBlock;
    dnssec: DnssecBlock;
    tls: TlsBlock;
    pka: PkaBlock;
    downgrade: DowngradeBlock;
    exitCode: number;
    cacheEntry: CacheEntry | null;
}
interface CheckOptions {
    protocol?: string;
    probeProtoSubdomain?: boolean;
    probeProtoEvenIfBase?: boolean;
    timeoutMs: number;
    allowFallback: boolean;
    wellKnownTimeoutMs: number;
    showDetails?: boolean;
    dumpWellKnownPath?: string | null;
    checkDowngrade?: boolean;
    previousCacheEntry?: CacheEntry;
}

declare function runCheck(domain: string, opts: CheckOptions): Promise<DoctorReport>;

/**
 * Standardized error messages for aid-doctor CLI
 * Ensures consistency across all modules
 */
declare const ERROR_MESSAGES: {
    readonly UNKNOWN_ERROR: "An unexpected error occurred. Please check your input and try again.";
    readonly DNS_LOOKUP_FAILED: "DNS lookup failed for the specified domain. Check network connectivity and domain spelling.";
    readonly NO_RECORD_FOUND: "No AID TXT record found for the domain. Ensure the record exists at _agent.<domain>.";
    readonly INVALID_TXT_FORMAT: "The AID TXT record has an invalid format. Ensure it follows v=aid1;key=value;... structure.";
    readonly UNSUPPORTED_PROTOCOL: "The specified protocol is not supported. See the official protocol registry for valid tokens.";
    readonly DEPRECATED_RECORD: "The AID record has been deprecated. Check the deprecation date and update accordingly.";
    readonly SECURITY_VIOLATION: "A security check failed. The record or endpoint may be compromised.";
    readonly TLS_VALIDATION_FAILED: "TLS certificate validation failed. Ensure the certificate is valid and not expired.";
    readonly PKA_HANDSHAKE_FAILED: "PKA endpoint proof handshake failed. Verify the public key and private key configuration.";
    readonly FALLBACK_FAILED: "The .well-known fallback failed. Ensure the HTTPS endpoint returns valid JSON.";
    readonly BYTE_LIMIT_EXCEEDED: "The record exceeds the 255-byte DNS limit. Use aliases and shorten fields.";
    readonly BYTE_LIMIT_WARNING: "Record size is close to the 255-byte limit. Consider using aliases.";
    readonly TLS_EXPIRING_SOON: "TLS certificate expires soon. Renew to avoid interruptions.";
    readonly DNSSEC_NOT_DETECTED: "DNSSEC not detected. Enable for better integrity.";
    readonly PKA_NOT_PRESENT: "Endpoint proof (PKA) not present. Consider adding for security.";
    readonly DOWNGRADE_DETECTED: "Security downgrade detected: a previously present PKA or KID has been removed.";
    readonly ENABLE_DNSSEC: "Enable DNSSEC at your domain registrar to improve DNS integrity.";
    readonly ADD_PKA: "Add PKA endpoint proof by running 'aid-doctor pka generate'.";
    readonly RENEW_TLS: "Renew your TLS certificate soon to avoid expiration.";
    readonly USE_ALIASES: "Use single-letter aliases (e.g., u for uri) to reduce record size.";
};

/**
 * @agentcommunity/aid-doctor - CLI tool for Agent Identity & Discovery
 *
 * This file contains the logic for the interactive record generator.
 */

type AidGeneratorData = {
    uri: string;
    proto: ProtocolToken | '';
    auth: AuthToken | '';
    desc: string;
    domain: string;
    docs?: string;
    dep?: string;
    pka?: string;
    kid?: string;
};
declare function buildTxtRecordVariant(formData: AidGeneratorData, useAliases: boolean): string;
declare function buildTxtRecord(formData: AidGeneratorData): string;
declare function validateTxtRecord(record: string): {
    isValid: boolean;
    error?: string;
};

/**
 * Pure function that generates Ed25519 key pair without any side effects.
 * Returns the key data that can be used by consumers to handle storage.
 */
declare function generateEd25519KeyPair(): Promise<{
    publicKey: string;
    privateKeyPem: string;
    privateKeyBytes: Uint8Array;
}>;
declare function verifyPka(pka: string): {
    valid: boolean;
    reason?: string;
};

export { type AidGeneratorData, type CacheEntry, type CheckOptions, type DnssecBlock, type DoctorReport, type DowngradeBlock, ERROR_MESSAGES, type PkaBlock, type ProbeAttempt, type QueriedBlock, type RecordBlock, type TlsBlock, buildTxtRecord, buildTxtRecordVariant, generateEd25519KeyPair, runCheck, validateTxtRecord, verifyPka };