@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/tap-ans.js

@@ -0,0 +1,481 @@
+/**
+ * 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)
+ */
+import { SignJWT } from 'jose';
+// ============ ANS NAME PARSING ============
+/**
+ * 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 function parseANSName(input) {
+    let raw = input.trim();
+    // Strip scheme
+    const withoutScheme = raw.startsWith('ans://')
+        ? raw.slice('ans://'.length)
+        : raw;
+    // Split by dots
+    const parts = withoutScheme.split('.');
+    if (parts.length < 2) {
+        return { success: false, error: `Invalid ANS name: "${input}" — must have at least 2 parts` };
+    }
+    let version = 'v1.0';
+    let label;
+    let domainParts;
+    // Detect version prefix: v1.0, v1, v2.0, etc.
+    // Match at the string level (before dot-splitting) to correctly capture "v1.0" as a unit.
+    const versionMatch = withoutScheme.match(/^(v\d+(?:\.\d+)?)\./);
+    if (versionMatch) {
+        version = versionMatch[1]; // "v1.0" or "v1"
+        const rest = withoutScheme.slice(version.length + 1); // "myagent.example.com"
+        const restParts = rest.split('.');
+        if (restParts.length < 2) {
+            return { success: false, error: `ANS name with version requires: v<ver>.<label>.<domain>` };
+        }
+        label = restParts[0];
+        domainParts = restParts.slice(1);
+    }
+    else if (parts.length === 2) {
+        // Root domain (e.g. "botcha.ai"): the entire name is the domain identity.
+        // label = apex label ("botcha"), domain = full name ("botcha.ai")
+        // dnsLookupName = "_ans.botcha.ai" (not "_ans.ai" which is uncontrollable)
+        label = parts[0];
+        domainParts = parts; // domain = full 2-part name
+    }
+    else {
+        // 3+ parts without version: label is first part, domain is the rest
+        // e.g. "myagent.example.com" → label="myagent", domain="example.com"
+        label = parts[0];
+        domainParts = parts.slice(1);
+    }
+    const domain = domainParts.join('.');
+    // For 2-part root domains, fqdn == domain (no separate subdomain label)
+    const fqdn = parts.length === 2 ? domain : `${label}.${domain}`;
+    // DNS TXT lookup lives at _ans.<domain>
+    const dnsLookupName = `_ans.${domain}`;
+    const components = {
+        raw: input,
+        version,
+        label,
+        domain,
+        fqdn,
+        dnsLookupName,
+    };
+    return { success: true, components };
+}
+// ============ DNS RESOLUTION (Cloudflare DNS-over-HTTPS) ============
+/**
+ * Resolve DNS TXT records using Cloudflare's DNS-over-HTTPS API.
+ * Works inside Cloudflare Workers (no Node.js dns module needed).
+ */
+async function resolveTXTRecords(name) {
+    try {
+        const url = `https://cloudflare-dns.com/dns-query?name=${encodeURIComponent(name)}&type=TXT`;
+        const response = await fetch(url, {
+            headers: {
+                'Accept': 'application/dns-json',
+            },
+        });
+        if (!response.ok) {
+            return { records: [], error: `DNS query failed: HTTP ${response.status}` };
+        }
+        const data = await response.json();
+        // Status 0 = NOERROR, Status 3 = NXDOMAIN
+        if (data.Status !== 0) {
+            return { records: [], error: `DNS status ${data.Status} (NXDOMAIN or error)` };
+        }
+        if (!data.Answer || data.Answer.length === 0) {
+            return { records: [] };
+        }
+        // Filter TXT records (type 16), strip surrounding quotes
+        const txtRecords = data.Answer
+            .filter(a => a.type === 16)
+            .map(a => a.data.replace(/^"|"$/g, '').replace(/"\s*"/g, '')); // handle multi-string TXT
+        return { records: txtRecords };
+    }
+    catch (err) {
+        return { records: [], error: `DNS fetch error: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Parse a raw ANS TXT record string into structured fields.
+ * Format: v=ANS1 name=myagent pub=<base64> cap=browse,search url=https://...
+ */
+function parseANSTXTRecord(raw) {
+    if (!raw.includes('v=ANS1') && !raw.includes('v=ANS')) {
+        return null;
+    }
+    const record = { version: 'ANS1', raw };
+    // Extract key=value pairs (values may be quoted)
+    const kvPattern = /(\w+)=("(?:[^"\\]|\\.)*"|[^\s]+)/g;
+    let match;
+    while ((match = kvPattern.exec(raw)) !== null) {
+        const key = match[1];
+        const value = match[2].replace(/^"|"$/g, '');
+        switch (key) {
+            case 'v':
+                record.version = value.replace('v=', '').trim() || 'ANS1';
+                break;
+            case 'name':
+                record.name = value;
+                break;
+            case 'pub':
+                record.pub = value;
+                break;
+            case 'cap':
+                record.cap = value.split(',').map(s => s.trim()).filter(Boolean);
+                break;
+            case 'url':
+                record.url = value;
+                break;
+            case 'did':
+                record.did = value;
+                break;
+        }
+    }
+    return record;
+}
+// ============ ANS RESOLUTION ============
+/**
+ * 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 async function resolveANSName(ansName) {
+    const parsed = parseANSName(ansName);
+    if (!parsed.success || !parsed.components) {
+        return { success: false, error: parsed.error };
+    }
+    const { components } = parsed;
+    // DNS TXT lookup
+    const dnsResult = await resolveTXTRecords(components.dnsLookupName);
+    if (dnsResult.error && dnsResult.records.length === 0) {
+        return {
+            success: false,
+            name: components,
+            error: `DNS lookup failed for ${components.dnsLookupName}: ${dnsResult.error}`,
+        };
+    }
+    // Find ANS record among TXT records
+    let ansRecord = null;
+    for (const txt of dnsResult.records) {
+        const parsed = parseANSTXTRecord(txt);
+        if (parsed) {
+            ansRecord = parsed;
+            break;
+        }
+    }
+    if (!ansRecord) {
+        return {
+            success: false,
+            name: components,
+            error: `No ANS TXT record found at ${components.dnsLookupName}. Found ${dnsResult.records.length} TXT record(s) but none matched ANS format (v=ANS1).`,
+        };
+    }
+    // Optionally fetch Agent Card from URL
+    let agentCard;
+    if (ansRecord.url) {
+        try {
+            const cardResponse = await fetch(ansRecord.url, {
+                headers: { 'Accept': 'application/json' },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (cardResponse.ok) {
+                agentCard = await cardResponse.json();
+            }
+        }
+        catch {
+            // Non-fatal: agent card fetch failed, continue without it
+        }
+    }
+    return {
+        success: true,
+        name: components,
+        record: ansRecord,
+        agentCard,
+        resolvedAt: Date.now(),
+    };
+}
+/**
+ * Verify ANS name ownership via key signature.
+ * The ANS TXT record must contain `pub=<base64-pubkey>`.
+ */
+export async function verifyANSOwnership(proof, resolvedRecord) {
+    // Determine which public key to use
+    const pubKeyB64 = proof.public_key || resolvedRecord.pub;
+    if (!pubKeyB64) {
+        return {
+            verified: false,
+            method: 'key-ownership',
+            error: 'No public key available in ANS record or proof. Add pub=<base64-key> to your _ans TXT record.',
+        };
+    }
+    try {
+        // Decode base64url public key (SPKI format expected)
+        const pubKeyBytes = base64urlDecode(pubKeyB64);
+        // Determine algorithm (default: ECDSA P-256)
+        const algorithm = proof.algorithm?.toUpperCase() || 'ECDSA-P256';
+        const cryptoAlg = algorithm === 'ED25519'
+            ? { name: 'Ed25519' }
+            : { name: 'ECDSA', namedCurve: 'P-256' };
+        const verifyAlg = algorithm === 'ED25519'
+            ? { name: 'Ed25519' }
+            : { name: 'ECDSA', hash: { name: 'SHA-256' } };
+        // Import public key
+        const cryptoKey = await crypto.subtle.importKey('spki', pubKeyBytes, cryptoAlg, false, ['verify']);
+        // Decode and verify signature over nonce
+        const sigBytes = base64urlDecode(proof.signature);
+        const nonceBytes = new TextEncoder().encode(proof.nonce);
+        const isValid = await crypto.subtle.verify(verifyAlg, cryptoKey, sigBytes, nonceBytes);
+        return {
+            verified: isValid,
+            method: 'key-ownership',
+            error: isValid ? undefined : 'Signature verification failed — nonce not signed by ANS key',
+        };
+    }
+    catch (err) {
+        return {
+            verified: false,
+            method: 'key-ownership',
+            error: `Crypto error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+// ============ BOTCHA CREDENTIAL ISSUANCE ============
+/**
+ * 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 async function issueANSBadge(components, trustLevel, jwtSecret, options) {
+    const now = Date.now();
+    const expiresInMs = (options?.expiresInSeconds ?? 86400 * 90) * 1000; // default 90 days
+    const expiresAt = now + expiresInMs;
+    const badgeId = generateId('ans');
+    const payload = {
+        type: 'botcha-ans-badge',
+        jti: badgeId,
+        ans_name: components.raw,
+        domain: components.domain,
+        label: components.label,
+        trust_level: trustLevel,
+        botcha: 'verified',
+        issuer: 'botcha.ai',
+    };
+    if (options?.agentId) {
+        payload.agent_id = options.agentId;
+    }
+    if (options?.capabilities) {
+        payload.capabilities = options.capabilities;
+    }
+    const secretBytes = new TextEncoder().encode(jwtSecret);
+    const token = await new SignJWT(payload)
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject(components.fqdn)
+        .setIssuer('botcha.ai')
+        .setIssuedAt()
+        .setExpirationTime(Math.floor(expiresAt / 1000))
+        .sign(secretBytes);
+    return {
+        badge_id: badgeId,
+        ans_name: components.raw,
+        domain: components.domain,
+        agent_id: options?.agentId,
+        verified: true,
+        verification_type: trustLevel === 'domain-validated' ? 'dns-ownership'
+            : trustLevel === 'key-validated' ? 'key-ownership'
+                : 'challenge-verified',
+        trust_level: trustLevel,
+        credential_token: token,
+        issued_at: now,
+        expires_at: expiresAt,
+        issuer: 'botcha.ai',
+    };
+}
+// ============ ANS DISCOVERY REGISTRY ============
+/**
+ * Save a verified ANS agent to the BOTCHA discovery registry.
+ * Stored in KV under `ans_registry:<domain>:<label>`
+ */
+export async function saveANSRegistryEntry(kv, entry) {
+    const key = `ans_registry:${entry.domain}:${entry.label}`;
+    const ttlSeconds = Math.max(1, Math.floor((entry.expires_at - Date.now()) / 1000));
+    await kv.put(key, JSON.stringify(entry), { expirationTtl: ttlSeconds });
+    // Also maintain a global index for listing
+    const indexKey = 'ans_registry_index';
+    const existingRaw = await kv.get(indexKey);
+    const index = existingRaw ? JSON.parse(existingRaw) : [];
+    const entryKey = `${entry.domain}:${entry.label}`;
+    if (!index.includes(entryKey)) {
+        index.push(entryKey);
+        await kv.put(indexKey, JSON.stringify(index));
+    }
+}
+/**
+ * Get a single ANS registry entry.
+ */
+export async function getANSRegistryEntry(kv, domain, label) {
+    const key = `ans_registry:${domain}:${label}`;
+    const raw = await kv.get(key);
+    if (!raw)
+        return null;
+    return JSON.parse(raw);
+}
+/**
+ * List all BOTCHA-verified ANS agents in the discovery registry.
+ * Optionally filter by domain.
+ */
+export async function listANSRegistry(kv, options) {
+    const indexKey = 'ans_registry_index';
+    const indexRaw = await kv.get(indexKey);
+    if (!indexRaw)
+        return [];
+    const index = JSON.parse(indexRaw);
+    const limit = options?.limit ?? 100;
+    const domainFilter = options?.domain;
+    const filtered = domainFilter
+        ? index.filter(k => k.startsWith(`${domainFilter}:`))
+        : index;
+    const entries = [];
+    for (const entryKey of filtered.slice(0, limit)) {
+        const [domain, label] = entryKey.split(':', 2);
+        const entry = await getANSRegistryEntry(kv, domain, label);
+        if (entry) {
+            entries.push(entry);
+        }
+    }
+    return entries.sort((a, b) => b.verified_at - a.verified_at);
+}
+// ============ NONCE MANAGEMENT ============
+/**
+ * Generate and store a fresh nonce for ANS ownership verification.
+ * TTL: 10 minutes — caller must sign and return within this window.
+ */
+export async function generateANSNonce(kv, ansName) {
+    const nonce = generateId('nonce');
+    const key = buildANSNonceKey(ansName);
+    await kv.put(key, JSON.stringify({ nonce, created_at: Date.now() }), {
+        expirationTtl: 600, // 10 minutes
+    });
+    return nonce;
+}
+/**
+ * Consume (verify + delete) a stored ANS nonce.
+ * Returns true if nonce matches. Nonces are single-use.
+ */
+export async function consumeANSNonce(kv, ansName, providedNonce) {
+    const key = buildANSNonceKey(ansName);
+    const raw = await kv.get(key);
+    if (!raw)
+        return false;
+    const stored = JSON.parse(raw);
+    if (stored.nonce !== providedNonce)
+        return false;
+    // Delete nonce — single use
+    await kv.delete(key);
+    return true;
+}
+function buildANSNonceKey(ansName) {
+    const parsed = parseANSName(ansName);
+    if (parsed.success && parsed.components) {
+        const canonical = `ans://${parsed.components.version}.${parsed.components.fqdn}`.toLowerCase();
+        return `ans_nonce:${canonical}`;
+    }
+    return `ans_nonce:${ansName.trim().toLowerCase()}`;
+}
+// ============ BOTCHA'S OWN ANS RECORD ============
+/**
+ * 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 function getBotchaANSRecord() {
+    return {
+        ans_name: 'ans://v1.0.botcha.ai',
+        dns_name: '_ans.botcha.ai',
+        txt_record: 'v=ANS1 name=botcha cap=verify,issue,discover url=https://botcha.ai/.well-known/agent.json did=did:web:botcha.ai',
+        agent_card: {
+            '@context': 'https://schema.org',
+            '@type': 'SoftwareApplication',
+            name: 'BOTCHA',
+            description: 'Reverse CAPTCHA for AI agents. Verification layer for the Agent Name Service.',
+            url: 'https://botcha.ai',
+            identifier: 'ans://v1.0.botcha.ai',
+            did: 'did:web:botcha.ai',
+            capabilities: ['verify', 'issue', 'discover'],
+            verification: {
+                type: 'ANS-BOTCHA-Badge',
+                endpoint: 'https://botcha.ai/v1/ans/verify',
+                discovery: 'https://botcha.ai/v1/ans/discover',
+            },
+        },
+    };
+}
+// ============ UTILITY ============
+function generateId(prefix) {
+    const bytes = new Uint8Array(12);
+    crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+    return `${prefix}_${hex}`;
+}
+function base64urlDecode(input) {
+    // Convert base64url to base64
+    const base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '=='.slice(0, (4 - base64.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+export default {
+    parseANSName,
+    resolveANSName,
+    verifyANSOwnership,
+    issueANSBadge,
+    saveANSRegistryEntry,
+    getANSRegistryEntry,
+    listANSRegistry,
+    generateANSNonce,
+    consumeANSNonce,
+    getBotchaANSRecord,
+};

package/dist/tap-delegation-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tap-delegation-routes.d.ts","sourceRoot":"","sources":["../src/tap-delegation-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAgEpC;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsGrD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDlD;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAqEpD;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAsErD;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkDrD;;;;;;;;AAED,wBAME"}
+{"version":3,"file":"tap-delegation-routes.d.ts","sourceRoot":"","sources":["../src/tap-delegation-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAiEpC;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiHrD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDlD;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAqEpD;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAiFrD;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkDrD;;;;;;;;AAED,wBAME"}

package/dist/tap-delegation-routes.js

@@ -12,6 +12,7 @@
  *   POST   /v1/verify/delegation        — Verify delegation chain
  */
 import { extractBearerToken, verifyToken, getSigningPublicKeyJWK } from './auth.js';
+import { triggerWebhook } from './webhooks.js';
 import { TAP_VALID_ACTIONS } from './tap-agents.js';
 import { createDelegation, getDelegation, listDelegations, revokeDelegation, verifyDelegationChain, } from './tap-delegation.js';
 // ============ VALIDATION HELPERS ============
@@ -120,6 +121,11 @@ export async function createDelegationRoute(c) {
             }, status);
         }
         const del = result.delegation;
+        // Webhook: delegation.created
+        const delCreateCtx = c.executionCtx;
+        if (delCreateCtx?.waitUntil) {
+            delCreateCtx.waitUntil(triggerWebhook(c.env.AGENTS, del.app_id, 'delegation.created', { delegation_id: del.delegation_id, grantor_id: del.grantor_id, grantee_id: del.grantee_id }));
+        }
         return c.json({
             success: true,
             delegation_id: del.delegation_id,
@@ -320,6 +326,11 @@ export async function revokeDelegationRoute(c) {
             }, 500);
         }
         const del = result.delegation;
+        // Webhook: delegation.revoked
+        const delRevokeCtx = c.executionCtx;
+        if (delRevokeCtx?.waitUntil) {
+            delRevokeCtx.waitUntil(triggerWebhook(c.env.AGENTS, del.app_id, 'delegation.revoked', { delegation_id: del.delegation_id, reason: del.revocation_reason }));
+        }
         return c.json({
             success: true,
             delegation_id: del.delegation_id,

package/dist/tap-did.d.ts

@@ -0,0 +1,140 @@
+/**
+ * BOTCHA DID — W3C DID Core 1.0 + did:web Method
+ *
+ * Implements:
+ *   - BOTCHA DID Document generation (did:web:botcha.ai)
+ *   - Basic did:web resolver (fetch DID Documents from remote hosts)
+ *   - DID parsing and validation utilities
+ *   - Agent DID helpers (did:web:botcha.ai:agents:<agent_id>)
+ *
+ * Standards:
+ *   - W3C DID Core 1.0: https://www.w3.org/TR/did-core/
+ *   - did:web method: https://w3c-ccg.github.io/did-web/
+ */
+export interface VerificationMethod {
+    id: string;
+    type: string;
+    controller: string;
+    publicKeyJwk?: Record<string, string | undefined>;
+    publicKeyMultibase?: string;
+}
+export interface ServiceEndpoint {
+    id: string;
+    type: string;
+    serviceEndpoint: string | string[] | Record<string, string>;
+    description?: string;
+}
+export interface DIDDocument {
+    '@context': string | string[];
+    id: string;
+    controller?: string | string[];
+    verificationMethod?: VerificationMethod[];
+    authentication?: (string | VerificationMethod)[];
+    assertionMethod?: (string | VerificationMethod)[];
+    keyAgreement?: (string | VerificationMethod)[];
+    capabilityInvocation?: (string | VerificationMethod)[];
+    capabilityDelegation?: (string | VerificationMethod)[];
+    service?: ServiceEndpoint[];
+    [key: string]: unknown;
+}
+export interface DIDResolutionResult {
+    '@context': string;
+    didDocument: DIDDocument | null;
+    didResolutionMetadata: {
+        contentType?: string;
+        error?: string;
+        retrieved?: string;
+        duration?: number;
+    };
+    didDocumentMetadata: {
+        created?: string;
+        updated?: string;
+        deactivated?: boolean;
+    };
+}
+export interface DIDParseResult {
+    valid: boolean;
+    method?: string;
+    methodSpecificId?: string;
+    error?: string;
+}
+/**
+ * Generate the canonical BOTCHA DID Document for did:web:botcha.ai.
+ *
+ * The ES256 signing key from BOTCHA's JWKS is registered as the
+ * assertionMethod — meaning VCs signed by this key are cryptographically
+ * tied to the botcha.ai DID Document.
+ *
+ * If no signing key is available (e.g. HS256-only deployment), the
+ * verificationMethod array is empty and VCs cannot be verified offline.
+ */
+export declare function generateBotchaDIDDocument(baseUrl: string, signingPublicKeyJwk?: {
+    kty: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
+}): DIDDocument;
+/**
+ * Parse and validate a DID string.
+ *
+ * Valid DID format: did:method:method-specific-id
+ *   - must start with "did:"
+ *   - method: lowercase alphanumeric
+ *   - method-specific-id: non-empty
+ */
+export declare function parseDID(did: string): DIDParseResult;
+/**
+ * Convert a did:web DID to an HTTPS URL for DID Document fetching.
+ *
+ * Spec rules (https://w3c-ccg.github.io/did-web/):
+ *   did:web:example.com             → https://example.com/.well-known/did.json
+ *   did:web:example.com:user:alice  → https://example.com/user/alice/did.json
+ *   did:web:example.com%3A8080      → https://example.com:8080/.well-known/did.json
+ *
+ * Algorithm:
+ *   1. Split the method-specific-id on unencoded ':' characters.
+ *   2. The first segment is the host — percent-decode it (e.g. %3A → ':' for port).
+ *   3. Remaining segments are path components — join with '/'.
+ *
+ * Returns null if the DID cannot be converted to a valid URL.
+ */
+export declare function didWebToUrl(did: string): string | null;
+/**
+ * Resolve a did:web DID by fetching its DID Document from the network.
+ *
+ * Supports:
+ *   - did:web:example.com (fetches /.well-known/did.json)
+ *   - did:web:example.com:path:resource (fetches /path/resource/did.json)
+ *
+ * Note: Only did:web is supported. Other methods return methodNotSupported.
+ * Cloudflare Workers support outbound fetch, so this works in production.
+ */
+export declare function resolveDIDWeb(did: string): Promise<DIDResolutionResult>;
+/**
+ * Build a did:web DID for a BOTCHA-registered agent.
+ *   agent_abc123 → did:web:botcha.ai:agents:agent_abc123
+ */
+export declare function buildAgentDID(agentId: string): string;
+/**
+ * Extract agent_id from a BOTCHA agent DID, if applicable.
+ * Returns null if the DID is not a BOTCHA agent DID.
+ */
+export declare function parseAgentDID(did: string): string | null;
+/**
+ * Check if a DID is a valid did:web DID (basic format validation).
+ */
+export declare function isValidDIDWeb(did: string): boolean;
+declare const _default: {
+    generateBotchaDIDDocument: typeof generateBotchaDIDDocument;
+    parseDID: typeof parseDID;
+    didWebToUrl: typeof didWebToUrl;
+    resolveDIDWeb: typeof resolveDIDWeb;
+    buildAgentDID: typeof buildAgentDID;
+    parseAgentDID: typeof parseAgentDID;
+    isValidDIDWeb: typeof isValidDIDWeb;
+};
+export default _default;
+//# sourceMappingURL=tap-did.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-did.d.ts","sourceRoot":"","sources":["../src/tap-did.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAClD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,kBAAkB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC1C,cAAc,CAAC,EAAE,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC;IACjD,eAAe,CAAC,EAAE,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC;IAClD,YAAY,CAAC,EAAE,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC;IAC/C,oBAAoB,CAAC,EAAE,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC;IACvD,oBAAoB,CAAC,EAAE,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC;IACvD,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAE5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,qBAAqB,EAAE;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,mBAAmB,EAAE;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAYD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,mBAAmB,CAAC,EAAE;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GACA,WAAW,CAqDb;AAID;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CA8BpD;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBtD;AAID;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmE7E;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKxD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKlD;;;;;;;;;;AAoBD,wBAQE"}