@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/tap-ans.d.ts

@@ -0,0 +1,241 @@
+/**
+ * BOTCHA ANS Integration — tap-ans.ts
+ *
+ * Agent Name Service (ANS) is the emerging "DNS for AI agents" led by GoDaddy.
+ * ANS names like `ans://v1.0.myagent.example.com` resolve via DNS TXT records
+ * to structured agent metadata. This module makes BOTCHA the verification badge
+ * on top of ANS's domain-level trust.
+ *
+ * ANS gives you DV-level trust (domain exists). BOTCHA adds:
+ *   "this agent actually behaves like an AI."
+ *
+ * Together: ANS names the agent, BOTCHA verifies it.
+ *
+ * Key ANS spec: https://agentnameregistry.org
+ * ANS format:   ans://v1.0.<label>.<domain>
+ *               e.g. ans://v1.0.myagent.example.com
+ * DNS lookup:   TXT record at _ans.<domain>
+ *               e.g. _ans.example.com TXT "v=ANS1 ..."
+ *
+ * References:
+ *   - https://agentnameregistry.org
+ *   - GoDaddy ANS Marketplace (Dec 2025)
+ *   - IETF ANS draft (Nov 2025)
+ */
+export interface KVNamespace {
+    get(key: string, encoding?: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+            expiration?: number;
+        }>;
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/**
+ * Parsed ANS name components
+ * ans://v1.0.myagent.example.com
+ *   version: "v1.0"
+ *   label:   "myagent"
+ *   domain:  "example.com"
+ */
+export interface ANSNameComponents {
+    raw: string;
+    version: string;
+    label: string;
+    domain: string;
+    fqdn: string;
+    dnsLookupName: string;
+}
+/**
+ * Raw ANS TXT record content (after parsing)
+ * ANS spec v1: v=ANS1 name=<label> pub=<base64-pubkey> cap=<csv> url=<agentcard-url>
+ */
+export interface ANSTXTRecord {
+    version: string;
+    name?: string;
+    pub?: string;
+    cap?: string[];
+    url?: string;
+    did?: string;
+    raw: string;
+}
+/**
+ * Result of resolving an ANS name
+ */
+export interface ANSResolutionResult {
+    success: boolean;
+    name?: ANSNameComponents;
+    record?: ANSTXTRecord;
+    agentCard?: Record<string, unknown>;
+    error?: string;
+    resolvedAt?: number;
+}
+/**
+ * BOTCHA verification badge linked to an ANS name
+ */
+export interface ANSVerificationBadge {
+    badge_id: string;
+    ans_name: string;
+    domain: string;
+    agent_id?: string;
+    verified: boolean;
+    verification_type: 'dns-ownership' | 'key-ownership' | 'challenge-verified';
+    trust_level: 'domain-validated' | 'key-validated' | 'behavior-validated';
+    credential_token: string;
+    issued_at: number;
+    expires_at: number;
+    issuer: 'botcha.ai';
+}
+/**
+ * ANS-verified agent in the BOTCHA discovery registry
+ */
+export interface ANSRegistryEntry {
+    ans_name: string;
+    domain: string;
+    label: string;
+    agent_id?: string;
+    app_id?: string;
+    badge_id: string;
+    trust_level: 'domain-validated' | 'key-validated' | 'behavior-validated';
+    capabilities?: string[];
+    agent_card_url?: string;
+    verified_at: number;
+    expires_at: number;
+}
+/**
+ * Parse an ANS name into its components.
+ *
+ * Accepts:
+ *   - ans://v1.0.myagent.example.com
+ *   - v1.0.myagent.example.com   (without scheme)
+ *   - myagent.example.com        (bare domain, defaults to v1.0)
+ *   - example.com                (root domain, label = domain apex)
+ */
+export declare function parseANSName(input: string): {
+    success: boolean;
+    components?: ANSNameComponents;
+    error?: string;
+};
+/**
+ * Resolve an ANS name to agent metadata.
+ *
+ * Steps:
+ *  1. Parse the ANS name
+ *  2. Look up DNS TXT at _ans.<domain>
+ *  3. Parse ANS TXT record
+ *  4. Optionally fetch Agent Card from record.url
+ */
+export declare function resolveANSName(ansName: string): Promise<ANSResolutionResult>;
+/**
+ * Verify that the caller owns the ANS name.
+ *
+ * Ownership proof options (in order of strength):
+ *
+ * 1. Key ownership: caller provides a signature over a BOTCHA nonce using the
+ *    public key embedded in the ANS TXT record. This proves the holder of the
+ *    private key is the registrant.
+ *
+ * 2. DNS challenge: BOTCHA issues a nonce, caller must place it in a DNS TXT
+ *    record at _botcha-verify.<domain>. This proves DNS control.
+ *
+ * For Phase 1 we implement key-ownership verification using SubtleCrypto.
+ */
+export interface ANSOwnershipProof {
+    ans_name: string;
+    nonce: string;
+    signature: string;
+    algorithm?: string;
+    public_key?: string;
+}
+export interface ANSOwnershipResult {
+    verified: boolean;
+    method: 'key-ownership' | 'dns-challenge';
+    error?: string;
+}
+/**
+ * Verify ANS name ownership via key signature.
+ * The ANS TXT record must contain `pub=<base64-pubkey>`.
+ */
+export declare function verifyANSOwnership(proof: ANSOwnershipProof, resolvedRecord: ANSTXTRecord): Promise<ANSOwnershipResult>;
+/**
+ * Issue a BOTCHA-ANS linked verification badge.
+ *
+ * The badge is a signed JWT (HS256) containing:
+ *   - ans_name: canonical ANS identifier
+ *   - domain: verified domain
+ *   - trust_level: what was verified
+ *   - botcha: "verified" — the stamp
+ *
+ * This badge can be embedded in ANS Marketplace listings and verified
+ * by anyone who knows the BOTCHA JWT secret (or JWKS public key).
+ */
+export declare function issueANSBadge(components: ANSNameComponents, trustLevel: ANSVerificationBadge['trust_level'], jwtSecret: string, options?: {
+    agentId?: string;
+    capabilities?: string[];
+    agentCardUrl?: string;
+    expiresInSeconds?: number;
+}): Promise<ANSVerificationBadge>;
+/**
+ * Save a verified ANS agent to the BOTCHA discovery registry.
+ * Stored in KV under `ans_registry:<domain>:<label>`
+ */
+export declare function saveANSRegistryEntry(kv: KVNamespace, entry: ANSRegistryEntry): Promise<void>;
+/**
+ * Get a single ANS registry entry.
+ */
+export declare function getANSRegistryEntry(kv: KVNamespace, domain: string, label: string): Promise<ANSRegistryEntry | null>;
+/**
+ * List all BOTCHA-verified ANS agents in the discovery registry.
+ * Optionally filter by domain.
+ */
+export declare function listANSRegistry(kv: KVNamespace, options?: {
+    domain?: string;
+    limit?: number;
+}): Promise<ANSRegistryEntry[]>;
+/**
+ * Generate and store a fresh nonce for ANS ownership verification.
+ * TTL: 10 minutes — caller must sign and return within this window.
+ */
+export declare function generateANSNonce(kv: KVNamespace, ansName: string): Promise<string>;
+/**
+ * Consume (verify + delete) a stored ANS nonce.
+ * Returns true if nonce matches. Nonces are single-use.
+ */
+export declare function consumeANSNonce(kv: KVNamespace, ansName: string, providedNonce: string): Promise<boolean>;
+/**
+ * Returns the metadata for BOTCHA's own ANS registration.
+ * ans://v1.0.botcha.ai
+ *
+ * This would be placed as a TXT record at _ans.botcha.ai:
+ *   v=ANS1 name=botcha cap=verify,issue,discover url=https://botcha.ai/.well-known/agent.json
+ */
+export declare function getBotchaANSRecord(): {
+    ans_name: string;
+    dns_name: string;
+    txt_record: string;
+    agent_card: Record<string, unknown>;
+};
+declare const _default: {
+    parseANSName: typeof parseANSName;
+    resolveANSName: typeof resolveANSName;
+    verifyANSOwnership: typeof verifyANSOwnership;
+    issueANSBadge: typeof issueANSBadge;
+    saveANSRegistryEntry: typeof saveANSRegistryEntry;
+    getANSRegistryEntry: typeof getANSRegistryEntry;
+    listANSRegistry: typeof listANSRegistry;
+    generateANSNonce: typeof generateANSNonce;
+    consumeANSNonce: typeof consumeANSNonce;
+    getBotchaANSRecord: typeof getBotchaANSRecord;
+};
+export default _default;
+//# sourceMappingURL=tap-ans.d.ts.map

package/dist/tap-ans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tap-ans.d.ts","sourceRoot":"","sources":["../src/tap-ans.ts"],"names":[],"mappings":"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"}