@dupecom/botcha-cloudflare 0.15.0 → 0.18.0

package/dist/tap-federation.js

@@ -0,0 +1,237 @@
+/**
+ * TAP Federation — External JWKS Federation for Cross-Platform Trust
+ * Enables BOTCHA to verify agents signed by Visa or other TAP-compatible providers
+ * Per Visa TAP spec: https://developer.visa.com/capabilities/trusted-agent-protocol
+ */
+// ============ WELL-KNOWN SOURCES ============
+export const WELL_KNOWN_SOURCES = [
+    {
+        url: 'https://mcp.visa.com/.well-known/jwks',
+        name: 'visa',
+        trustLevel: 'high',
+        refreshInterval: 3600, // 1 hour
+        enabled: true,
+    },
+    // Future: other payment schemes, agent providers, etc.
+];
+// ============ CORE FUNCTIONS ============
+/**
+ * Fetch JWKS from a URL
+ * @throws Error if fetch fails or response is invalid
+ */
+export async function fetchJWKS(url) {
+    const response = await fetch(url, {
+        headers: { 'Accept': 'application/json' },
+        // CF Workers: no timeout needed, runtime handles it
+    });
+    if (!response.ok) {
+        throw new Error(`JWKS fetch failed: ${response.status} ${response.statusText}`);
+    }
+    const jwks = await response.json();
+    if (!jwks.keys || !Array.isArray(jwks.keys)) {
+        throw new Error('Invalid JWKS: missing keys array');
+    }
+    return jwks;
+}
+/**
+ * Convert a JWK from an external source to FederatedKey format
+ */
+export async function jwkToFederatedKey(jwk, source) {
+    // Determine the algorithm params for import
+    const importParams = resolveImportParams(jwk);
+    // Import the JWK into Web Crypto
+    const cryptoKey = await crypto.subtle.importKey('jwk', jwk, importParams, true, ['verify']);
+    // Export as SPKI to get PEM
+    const spkiBuffer = await crypto.subtle.exportKey('spki', cryptoKey);
+    const publicKeyPem = arrayBufferToPem(spkiBuffer);
+    return {
+        kid: jwk.kid,
+        kty: jwk.kty,
+        alg: jwk.alg || inferAlgorithm(jwk),
+        publicKeyPem,
+        source: source.name,
+        sourceUrl: source.url,
+        trustLevel: source.trustLevel,
+        fetchedAt: Date.now(),
+        expiresAt: Date.now() + source.refreshInterval * 1000,
+        x5c: jwk.x5c,
+    };
+}
+/**
+ * Resolve Web Crypto import parameters based on JWK type
+ */
+export function resolveImportParams(jwk) {
+    const kty = jwk.kty;
+    const alg = jwk.alg;
+    if (kty === 'RSA') {
+        return { name: 'RSA-PSS', hash: 'SHA-256' };
+    }
+    if (kty === 'EC') {
+        return { name: 'ECDSA', namedCurve: jwk.crv || 'P-256' };
+    }
+    if (kty === 'OKP' && (jwk.crv === 'Ed25519' || alg === 'EdDSA')) {
+        return { name: 'Ed25519' };
+    }
+    throw new Error(`Unsupported key type: ${kty}`);
+}
+/**
+ * Infer algorithm from JWK if not specified
+ */
+export function inferAlgorithm(jwk) {
+    if (jwk.kty === 'RSA')
+        return 'PS256';
+    if (jwk.kty === 'EC' && jwk.crv === 'P-256')
+        return 'ES256';
+    if (jwk.kty === 'OKP' && jwk.crv === 'Ed25519')
+        return 'EdDSA';
+    return 'unknown';
+}
+/**
+ * Convert ArrayBuffer to PEM string
+ */
+function arrayBufferToPem(buffer) {
+    const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
+    const lines = base64.match(/.{1,64}/g) || [base64];
+    return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----`;
+}
+/**
+ * Create a federation resolver that fetches and caches keys from external sources
+ */
+export function createFederationResolver(config) {
+    // In-memory cache (per-isolate)
+    const memoryCache = new Map();
+    return {
+        /**
+         * Resolve a public key by kid
+         * Search order: memory cache → KV cache → fetch from sources
+         */
+        async resolveKey(kid) {
+            // 1. Check memory cache
+            const cached = memoryCache.get(kid);
+            if (cached && Date.now() < cached.expiresAt) {
+                return { found: true, key: cached };
+            }
+            // 2. Check KV cache
+            if (config.kvNamespace) {
+                try {
+                    const kvData = await config.kvNamespace.get(`federated_key:${kid}`, 'text');
+                    if (kvData) {
+                        const key = JSON.parse(kvData);
+                        if (Date.now() < key.expiresAt) {
+                            memoryCache.set(kid, key);
+                            return { found: true, key };
+                        }
+                    }
+                }
+                catch (error) {
+                    console.error('Federation: KV cache read error:', error);
+                    // Continue to fetch from sources
+                }
+            }
+            // 3. Fetch from all enabled sources
+            for (const source of config.sources.filter(s => s.enabled)) {
+                try {
+                    const jwks = await fetchJWKS(source.url);
+                    // Opportunistically cache ALL keys from this fetch
+                    let foundKey;
+                    for (const jwk of jwks.keys) {
+                        try {
+                            const key = await jwkToFederatedKey(jwk, source);
+                            memoryCache.set(jwk.kid, key);
+                            // Cache in KV
+                            if (config.kvNamespace) {
+                                try {
+                                    const ttl = Math.min(source.refreshInterval, config.maxCacheAge || 86400);
+                                    await config.kvNamespace.put(`federated_key:${jwk.kid}`, JSON.stringify(key), { expirationTtl: ttl });
+                                }
+                                catch { /* skip write errors */ }
+                            }
+                            // Check if this is the key we're looking for
+                            if (jwk.kid === kid) {
+                                foundKey = key;
+                            }
+                        }
+                        catch { /* skip invalid keys */ }
+                    }
+                    // Return if we found the key in this source
+                    if (foundKey) {
+                        return { found: true, key: foundKey };
+                    }
+                }
+                catch (error) {
+                    console.error(`Federation: Failed to fetch from ${source.name}:`, error);
+                    // Continue to next source (fail-open per BOTCHA philosophy)
+                }
+            }
+            return { found: false, error: `Key ${kid} not found in any federated source` };
+        },
+        /**
+         * Refresh all keys from all sources (background job)
+         */
+        async refreshAll() {
+            let refreshed = 0;
+            const errors = [];
+            for (const source of config.sources.filter(s => s.enabled)) {
+                try {
+                    const jwks = await fetchJWKS(source.url);
+                    for (const jwk of jwks.keys) {
+                        try {
+                            const key = await jwkToFederatedKey(jwk, source);
+                            memoryCache.set(jwk.kid, key);
+                            if (config.kvNamespace) {
+                                try {
+                                    await config.kvNamespace.put(`federated_key:${jwk.kid}`, JSON.stringify(key), { expirationTtl: source.refreshInterval });
+                                }
+                                catch (error) {
+                                    // Non-fatal
+                                }
+                            }
+                            refreshed++;
+                        }
+                        catch (e) {
+                            errors.push(`Failed to process key ${jwk.kid} from ${source.name}`);
+                        }
+                    }
+                }
+                catch (e) {
+                    errors.push(`Failed to fetch ${source.name}: ${e}`);
+                }
+            }
+            return { refreshed, errors };
+        },
+        /**
+         * Get all cached keys (for debugging/admin)
+         */
+        getCachedKeys() {
+            return Array.from(memoryCache.values());
+        },
+        /**
+         * Clear all caches
+         */
+        clearCache() {
+            memoryCache.clear();
+        },
+    };
+}
+// ============ CONVENIENCE EXPORTS ============
+/**
+ * Create a Visa-specific federation resolver
+ */
+export function createVisaFederationResolver(kvNamespace) {
+    return createFederationResolver({
+        sources: WELL_KNOWN_SOURCES,
+        kvNamespace,
+        defaultRefreshInterval: 3600,
+        maxCacheAge: 86400,
+    });
+}
+// ============ DEFAULT EXPORT ============
+export default {
+    fetchJWKS,
+    jwkToFederatedKey,
+    createFederationResolver,
+    createVisaFederationResolver,
+    resolveImportParams,
+    inferAlgorithm,
+    WELL_KNOWN_SOURCES,
+};

package/dist/tap-jwks.d.ts

@@ -0,0 +1,64 @@
+/**
+ * TAP JWKS — JWK Set Endpoint + Key Format Conversion
+ * Implements .well-known/jwks for TAP agent public key discovery
+ * Per Visa TAP spec: https://developer.visa.com/capabilities/trusted-agent-protocol
+ */
+import type { Context } from 'hono';
+export interface JWK {
+    kty: string;
+    kid: string;
+    use: string;
+    alg: string;
+    n?: string;
+    e?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    agent_id?: string;
+    agent_name?: string;
+    expires_at?: string;
+}
+export interface JWKSet {
+    keys: JWK[];
+}
+/**
+ * Convert PEM public key to JWK format
+ */
+export declare function pemToJwk(pem: string, algorithm: string, kid: string, metadata?: {
+    agent_id?: string;
+    agent_name?: string;
+    expires_at?: string;
+}): Promise<JWK>;
+/**
+ * Convert JWK back to PEM format (for verification)
+ */
+export declare function jwkToPem(jwk: JWK): Promise<string>;
+/**
+ * Map BOTCHA algorithm names to JWK algorithm identifiers
+ */
+export declare function algToJWKAlg(algorithm: string): string;
+/**
+ * GET /.well-known/jwks
+ * Returns JWK Set for app's TAP-enabled agents
+ */
+export declare function jwksRoute(c: Context): Promise<Response>;
+/**
+ * GET /v1/keys/:keyId
+ * Get a specific key by ID (agent_id)
+ */
+export declare function getKeyRoute(c: Context): Promise<Response>;
+/**
+ * GET /v1/keys
+ * List keys with optional filters (Visa TAP compatible)
+ */
+export declare function listKeysRoute(c: Context): Promise<Response>;
+declare const _default: {
+    pemToJwk: typeof pemToJwk;
+    jwkToPem: typeof jwkToPem;
+    algToJWKAlg: typeof algToJWKAlg;
+    jwksRoute: typeof jwksRoute;
+    getKeyRoute: typeof getKeyRoute;
+    listKeysRoute: typeof listKeysRoute;
+};
+export default _default;
+//# sourceMappingURL=tap-jwks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-jwks.d.ts","sourceRoot":"","sources":["../src/tap-jwks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAMpC,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IAEZ,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,GAAG,EAAE,CAAC;CACb;AAID;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,OAAO,CAAC,GAAG,CAAC,CAed;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAKxD;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAWrD;AAiFD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6E7D;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2D/D;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuBjE;;;;;;;;;AAED,wBAOE"}

package/dist/tap-jwks.js

@@ -0,0 +1,279 @@
+/**
+ * TAP JWKS — JWK Set Endpoint + Key Format Conversion
+ * Implements .well-known/jwks for TAP agent public key discovery
+ * Per Visa TAP spec: https://developer.visa.com/capabilities/trusted-agent-protocol
+ */
+// ============ PEM <-> JWK CONVERSION ============
+/**
+ * Convert PEM public key to JWK format
+ */
+export async function pemToJwk(pem, algorithm, kid, metadata) {
+    const keyData = pemToArrayBuffer(pem);
+    const importParams = getImportParamsForAlg(algorithm);
+    const cryptoKey = await crypto.subtle.importKey('spki', keyData, importParams, true, ['verify']);
+    const jwk = (await crypto.subtle.exportKey('jwk', cryptoKey));
+    return {
+        ...jwk,
+        kid,
+        use: 'sig',
+        alg: algToJWKAlg(algorithm),
+        ...(metadata?.agent_id && { agent_id: metadata.agent_id }),
+        ...(metadata?.agent_name && { agent_name: metadata.agent_name }),
+        ...(metadata?.expires_at && { expires_at: metadata.expires_at }),
+    };
+}
+/**
+ * Convert JWK back to PEM format (for verification)
+ */
+export async function jwkToPem(jwk) {
+    const importParams = jwkAlgToImportParams(jwk.alg);
+    const cryptoKey = await crypto.subtle.importKey('jwk', jwk, importParams, true, ['verify']);
+    const spkiBuffer = await crypto.subtle.exportKey('spki', cryptoKey);
+    return arrayBufferToPem(spkiBuffer);
+}
+// ============ ALGORITHM MAPPING ============
+/**
+ * Map BOTCHA algorithm names to JWK algorithm identifiers
+ */
+export function algToJWKAlg(algorithm) {
+    switch (algorithm) {
+        case 'ecdsa-p256-sha256':
+            return 'ES256';
+        case 'rsa-pss-sha256':
+            return 'PS256';
+        case 'ed25519':
+            return 'EdDSA';
+        default:
+            throw new Error(`Unsupported algorithm: ${algorithm}`);
+    }
+}
+/**
+ * Get Web Crypto import parameters for BOTCHA algorithm
+ */
+function getImportParamsForAlg(algorithm) {
+    switch (algorithm) {
+        case 'ecdsa-p256-sha256':
+            return {
+                name: 'ECDSA',
+                namedCurve: 'P-256',
+            };
+        case 'rsa-pss-sha256':
+            return {
+                name: 'RSA-PSS',
+                hash: 'SHA-256',
+            };
+        case 'ed25519':
+            // Note: Ed25519 support varies by runtime
+            // Cloudflare Workers supports it via Web Crypto
+            return {
+                name: 'Ed25519',
+            };
+        default:
+            throw new Error(`Unsupported algorithm: ${algorithm}`);
+    }
+}
+/**
+ * Get Web Crypto import parameters for JWK algorithm
+ */
+function jwkAlgToImportParams(alg) {
+    switch (alg) {
+        case 'ES256':
+            return {
+                name: 'ECDSA',
+                namedCurve: 'P-256',
+            };
+        case 'PS256':
+            return {
+                name: 'RSA-PSS',
+                hash: 'SHA-256',
+            };
+        case 'EdDSA':
+            return {
+                name: 'Ed25519',
+            };
+        default:
+            throw new Error(`Unsupported JWK algorithm: ${alg}`);
+    }
+}
+// ============ PEM UTILITIES ============
+/**
+ * Convert PEM string to ArrayBuffer
+ */
+function pemToArrayBuffer(pem) {
+    const base64 = pem
+        .replace(/-----BEGIN PUBLIC KEY-----/, '')
+        .replace(/-----END PUBLIC KEY-----/, '')
+        .replace(/\s/g, '');
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}
+/**
+ * Convert ArrayBuffer to PEM string
+ */
+function arrayBufferToPem(buffer) {
+    const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
+    const lines = base64.match(/.{1,64}/g) || [base64];
+    return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----`;
+}
+// ============ JWKS ENDPOINT HANDLERS ============
+/**
+ * GET /.well-known/jwks
+ * Returns JWK Set for app's TAP-enabled agents
+ */
+export async function jwksRoute(c) {
+    try {
+        const appId = c.req.query('app_id');
+        // Security: Don't expose all keys globally
+        if (!appId) {
+            return c.json({ keys: [] }, 200, {
+                'Cache-Control': 'public, max-age=3600',
+            });
+        }
+        const agents = c.env.AGENTS;
+        if (!agents) {
+            console.error('AGENTS KV namespace not available');
+            return c.json({ keys: [] }, 200);
+        }
+        // Get agent list for this app
+        const agentIndexKey = `app_agents:${appId}`;
+        const agentIdsData = await agents.get(agentIndexKey, 'text');
+        if (!agentIdsData) {
+            return c.json({ keys: [] }, 200, {
+                'Cache-Control': 'public, max-age=3600',
+            });
+        }
+        const agentIds = JSON.parse(agentIdsData);
+        // Fetch all agents in parallel
+        const agentPromises = agentIds.map(async (agentId) => {
+            const agentData = await agents.get(`agent:${agentId}`, 'text');
+            return agentData ? JSON.parse(agentData) : null;
+        });
+        const agentResults = await Promise.all(agentPromises);
+        // Filter to TAP-enabled agents with public keys
+        const tapAgents = agentResults.filter((agent) => agent !== null &&
+            agent.tap_enabled === true &&
+            Boolean(agent.public_key) &&
+            Boolean(agent.signature_algorithm));
+        // Convert PEM keys to JWK format
+        const jwkPromises = tapAgents.map(async (agent) => {
+            try {
+                return await pemToJwk(agent.public_key, agent.signature_algorithm, agent.agent_id, {
+                    agent_id: agent.agent_id,
+                    agent_name: agent.name,
+                    expires_at: agent.key_created_at
+                        ? new Date(agent.key_created_at + 31536000000).toISOString() // +1 year
+                        : undefined,
+                });
+            }
+            catch (error) {
+                console.error(`Failed to convert key for agent ${agent.agent_id}:`, error);
+                return null;
+            }
+        });
+        const jwks = (await Promise.all(jwkPromises)).filter((jwk) => jwk !== null);
+        return c.json({ keys: jwks }, 200, {
+            'Cache-Control': 'public, max-age=3600',
+        });
+    }
+    catch (error) {
+        console.error('JWKS endpoint error:', error);
+        // Fail-open: Return empty key set
+        return c.json({ keys: [] }, 200);
+    }
+}
+/**
+ * GET /v1/keys/:keyId
+ * Get a specific key by ID (agent_id)
+ */
+export async function getKeyRoute(c) {
+    try {
+        const keyId = c.req.param('keyId') || c.req.query('keyID');
+        if (!keyId) {
+            return c.json({ error: 'keyId or keyID parameter required' }, 400);
+        }
+        const agents = c.env.AGENTS;
+        if (!agents) {
+            console.error('AGENTS KV namespace not available');
+            return c.json({ error: 'Service unavailable' }, 503);
+        }
+        // Get agent by ID
+        const agentData = await agents.get(`agent:${keyId}`, 'text');
+        if (!agentData) {
+            return c.json({ error: 'Key not found' }, 404);
+        }
+        const agent = JSON.parse(agentData);
+        // Verify agent has TAP enabled and public key
+        if (!agent.tap_enabled || !agent.public_key || !agent.signature_algorithm) {
+            return c.json({ error: 'Key not found' }, 404);
+        }
+        // Convert to JWK — if the stored PEM is invalid, return a raw key stub
+        let jwk;
+        try {
+            jwk = await pemToJwk(agent.public_key, agent.signature_algorithm, agent.agent_id, {
+                agent_id: agent.agent_id,
+                agent_name: agent.name,
+                expires_at: agent.key_created_at
+                    ? new Date(agent.key_created_at + 31536000000).toISOString()
+                    : undefined,
+            });
+        }
+        catch (conversionError) {
+            // PEM is stored but can't be converted to JWK (e.g., invalid key material)
+            // Return a raw stub so the endpoint doesn't 500
+            console.warn('Failed to convert agent key to JWK:', conversionError);
+            jwk = {
+                kty: agent.signature_algorithm === 'ed25519' ? 'OKP' : 'EC',
+                kid: agent.agent_id,
+                alg: algToJWKAlg(agent.signature_algorithm),
+                use: 'sig',
+                raw_pem: agent.public_key,
+                error: 'Key material could not be converted to JWK format',
+            };
+        }
+        return c.json(jwk, 200, {
+            'Cache-Control': 'public, max-age=3600',
+        });
+    }
+    catch (error) {
+        console.error('Get key error:', error);
+        return c.json({ error: 'Internal server error' }, 500);
+    }
+}
+/**
+ * GET /v1/keys
+ * List keys with optional filters (Visa TAP compatible)
+ */
+export async function listKeysRoute(c) {
+    try {
+        const keyID = c.req.query('keyID');
+        const appId = c.req.query('app_id');
+        // If keyID provided, return single key (Visa TAP compat)
+        if (keyID) {
+            return getKeyRoute(c);
+        }
+        // If app_id provided, return all keys for app (same as jwksRoute)
+        if (appId) {
+            return jwksRoute(c);
+        }
+        // No filters: return empty set (don't expose all keys)
+        return c.json({ keys: [] }, 200, {
+            'Cache-Control': 'public, max-age=3600',
+        });
+    }
+    catch (error) {
+        console.error('List keys error:', error);
+        return c.json({ keys: [] }, 200);
+    }
+}
+export default {
+    pemToJwk,
+    jwkToPem,
+    algToJWKAlg,
+    jwksRoute,
+    getKeyRoute,
+    listKeysRoute,
+};