@dupecom/botcha-cloudflare 0.15.0 → 0.18.0

package/dist/tap-edge.d.ts

@@ -0,0 +1,106 @@
+/**
+ * TAP Edge Verification — CDN-layer TAP signature verification
+ *
+ * Drop-in Hono middleware for Cloudflare Workers that:
+ * 1. Intercepts requests with TAP signature headers
+ * 2. Fetches agent public keys from BOTCHA or Visa JWKS
+ * 3. Verifies RFC 9421 signatures
+ * 4. Adds verification result headers to the proxied request
+ * 5. Passes through non-TAP requests unmodified
+ *
+ * Usage:
+ * ```typescript
+ * import { createTAPEdgeMiddleware } from '@dupecom/botcha/edge';
+ *
+ * app.use('*', createTAPEdgeMiddleware({
+ *   jwksUrls: ['https://botcha.ai/.well-known/jwks?app_id=YOUR_APP'],
+ *   allowUnverified: false,  // Block unsigned requests
+ *   requireTag: true,        // Require agent-browser-auth or agent-payer-auth tag
+ * }));
+ * ```
+ */
+import type { MiddlewareHandler } from 'hono';
+export interface TAPEdgeOptions {
+    jwksUrls?: string[];
+    staticKeys?: Map<string, string>;
+    allowUnverified?: boolean;
+    requireTag?: boolean;
+    blockOnFailure?: boolean;
+    keyCacheTtl?: number;
+    onVerified?: (result: EdgeVerificationResult) => void;
+    onFailed?: (result: EdgeVerificationResult) => void;
+}
+export interface EdgeVerificationResult {
+    verified: boolean;
+    tag?: string;
+    agentKeyId?: string;
+    algorithm?: string;
+    nonce?: string;
+    timestamp?: number;
+    error?: string;
+    source?: 'botcha' | 'visa' | 'static' | 'unknown';
+}
+export interface ParsedEdgeSignatureInput {
+    label: string;
+    components: string[];
+    created: number;
+    expires?: number;
+    keyId: string;
+    algorithm: string;
+    nonce?: string;
+    tag?: string;
+}
+export declare const TAP_EDGE_HEADERS: {
+    readonly VERIFIED: "X-TAP-Verified";
+    readonly TAG: "X-TAP-Tag";
+    readonly KEY_ID: "X-TAP-Key-ID";
+    readonly AGENT_SOURCE: "X-TAP-Agent-Source";
+    readonly NONCE: "X-TAP-Nonce";
+    readonly TIMESTAMP: "X-TAP-Timestamp";
+};
+export declare function createTAPEdgeMiddleware(options?: TAPEdgeOptions): MiddlewareHandler;
+/**
+ * Parse signature-input header according to RFC 9421
+ * Supports BOTH sig1 (BOTCHA) and sig2 (Visa TAP) labels
+ */
+export declare function parseEdgeSignatureInput(input: string): ParsedEdgeSignatureInput | null;
+/**
+ * Convert JWK to PEM format using Web Crypto
+ */
+export declare function jwkToPublicKeyPem(jwk: any): Promise<string>;
+/**
+ * Verify edge signature against signature base
+ */
+export declare function verifyEdgeSignature(req: any, parsed: ParsedEdgeSignatureInput, signature: string, publicKey: string, algorithm: string): Promise<EdgeVerificationResult>;
+/**
+ * Build signature base string according to RFC 9421 TAP format
+ */
+export declare function buildEdgeSignatureBase(authority: string, path: string, parsed: ParsedEdgeSignatureInput): string;
+/**
+ * Strict mode: require TAP on all requests, block failures
+ */
+export declare const tapEdgeStrict: (jwksUrls: string[]) => MiddlewareHandler;
+/**
+ * Flexible mode: verify if present, pass through if not
+ */
+export declare const tapEdgeFlexible: (jwksUrls: string[]) => MiddlewareHandler;
+/**
+ * Development mode: log only, never block
+ */
+export declare const tapEdgeDev: () => MiddlewareHandler;
+declare const _default: {
+    createTAPEdgeMiddleware: typeof createTAPEdgeMiddleware;
+    tapEdgeStrict: (jwksUrls: string[]) => MiddlewareHandler;
+    tapEdgeFlexible: (jwksUrls: string[]) => MiddlewareHandler;
+    tapEdgeDev: () => MiddlewareHandler;
+    TAP_EDGE_HEADERS: {
+        readonly VERIFIED: "X-TAP-Verified";
+        readonly TAG: "X-TAP-Tag";
+        readonly KEY_ID: "X-TAP-Key-ID";
+        readonly AGENT_SOURCE: "X-TAP-Agent-Source";
+        readonly NONCE: "X-TAP-Nonce";
+        readonly TIMESTAMP: "X-TAP-Timestamp";
+    };
+};
+export default _default;
+//# sourceMappingURL=tap-edge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-edge.d.ts","sourceRoot":"","sources":["../src/tap-edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAIvD,MAAM,WAAW,cAAc;IAE7B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IAGzB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACtD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAcD,eAAO,MAAM,gBAAgB;;;;;;;CAOnB,CAAC;AAIX,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,cAAmB,GAAG,iBAAiB,CAoFvF;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAkCtF;AA6CD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAOjE;AA0BD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,wBAAwB,EAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,CAAC,CA8DjC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAgCR;AAsMD;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,sBAK9C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,sBAKhD,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU,yBAKrB,CAAC;;;8BAzBqC,MAAM,EAAE;gCAUN,MAAM,EAAE;;;;;;;;;;;AAmBlD,wBAME"}

package/dist/tap-edge.js

@@ -0,0 +1,487 @@
+/**
+ * TAP Edge Verification — CDN-layer TAP signature verification
+ *
+ * Drop-in Hono middleware for Cloudflare Workers that:
+ * 1. Intercepts requests with TAP signature headers
+ * 2. Fetches agent public keys from BOTCHA or Visa JWKS
+ * 3. Verifies RFC 9421 signatures
+ * 4. Adds verification result headers to the proxied request
+ * 5. Passes through non-TAP requests unmodified
+ *
+ * Usage:
+ * ```typescript
+ * import { createTAPEdgeMiddleware } from '@dupecom/botcha/edge';
+ *
+ * app.use('*', createTAPEdgeMiddleware({
+ *   jwksUrls: ['https://botcha.ai/.well-known/jwks?app_id=YOUR_APP'],
+ *   allowUnverified: false,  // Block unsigned requests
+ *   requireTag: true,        // Require agent-browser-auth or agent-payer-auth tag
+ * }));
+ * ```
+ */
+// Headers added to proxied request after verification
+export const TAP_EDGE_HEADERS = {
+    VERIFIED: 'X-TAP-Verified', // 'true' or 'false'
+    TAG: 'X-TAP-Tag', // 'agent-browser-auth' or 'agent-payer-auth'
+    KEY_ID: 'X-TAP-Key-ID', // Which key was used
+    AGENT_SOURCE: 'X-TAP-Agent-Source', // 'botcha' | 'visa' | 'static'
+    NONCE: 'X-TAP-Nonce', // For body object linking downstream
+    TIMESTAMP: 'X-TAP-Timestamp', // Signature creation time
+};
+// ============ MAIN MIDDLEWARE ============
+export function createTAPEdgeMiddleware(options = {}) {
+    const { jwksUrls = [], staticKeys = new Map(), allowUnverified = true, requireTag = false, blockOnFailure = true, keyCacheTtl = 3600, onVerified, onFailed, } = options;
+    // In-memory key cache (per-isolate in CF Workers)
+    const keyCache = new Map();
+    return async (c, next) => {
+        // 1. Check for TAP signature headers
+        const signatureInput = c.req.header('signature-input');
+        const signature = c.req.header('signature');
+        if (!signatureInput || !signature) {
+            if (!allowUnverified) {
+                return c.json({ error: 'TAP_REQUIRED', message: 'TAP signature headers required' }, 403);
+            }
+            c.header(TAP_EDGE_HEADERS.VERIFIED, 'false');
+            await next();
+            return;
+        }
+        // 2. Parse signature input
+        const parsed = parseEdgeSignatureInput(signatureInput);
+        if (!parsed) {
+            const result = { verified: false, error: 'Invalid signature-input format' };
+            onFailed?.(result);
+            if (blockOnFailure) {
+                return c.json({ error: 'TAP_INVALID', message: 'Invalid TAP signature format' }, 403);
+            }
+            c.header(TAP_EDGE_HEADERS.VERIFIED, 'false');
+            await next();
+            return;
+        }
+        // 3. Check tag requirement
+        if (requireTag && !parsed.tag) {
+            return c.json({ error: 'TAP_TAG_REQUIRED', message: 'TAP tag required (agent-browser-auth or agent-payer-auth)' }, 403);
+        }
+        // 4. Resolve public key
+        const keyResult = await resolveKey(parsed.keyId, jwksUrls, staticKeys, keyCache, keyCacheTtl);
+        if (!keyResult) {
+            const result = { verified: false, error: 'Public key not found', agentKeyId: parsed.keyId };
+            onFailed?.(result);
+            if (blockOnFailure) {
+                return c.json({ error: 'TAP_KEY_NOT_FOUND', message: `Public key not found for keyId: ${parsed.keyId}` }, 403);
+            }
+            c.header(TAP_EDGE_HEADERS.VERIFIED, 'false');
+            await next();
+            return;
+        }
+        // 5. Verify signature
+        const verificationResult = await verifyEdgeSignature(c.req, parsed, signature, keyResult.key, parsed.algorithm);
+        if (verificationResult.verified) {
+            verificationResult.source = keyResult.source;
+            onVerified?.(verificationResult);
+            // Add verification headers
+            c.header(TAP_EDGE_HEADERS.VERIFIED, 'true');
+            if (parsed.tag)
+                c.header(TAP_EDGE_HEADERS.TAG, parsed.tag);
+            c.header(TAP_EDGE_HEADERS.KEY_ID, parsed.keyId);
+            c.header(TAP_EDGE_HEADERS.AGENT_SOURCE, keyResult.source);
+            if (parsed.nonce)
+                c.header(TAP_EDGE_HEADERS.NONCE, parsed.nonce);
+            if (parsed.created)
+                c.header(TAP_EDGE_HEADERS.TIMESTAMP, String(parsed.created));
+        }
+        else {
+            onFailed?.(verificationResult);
+            if (blockOnFailure) {
+                return c.json({ error: 'TAP_VERIFICATION_FAILED', message: verificationResult.error }, 403);
+            }
+            c.header(TAP_EDGE_HEADERS.VERIFIED, 'false');
+        }
+        await next();
+    };
+}
+// ============ HELPER FUNCTIONS ============
+/**
+ * Parse signature-input header according to RFC 9421
+ * Supports BOTH sig1 (BOTCHA) and sig2 (Visa TAP) labels
+ */
+export function parseEdgeSignatureInput(input) {
+    try {
+        // Match sig1 OR sig2
+        const sigMatch = input.match(/(sig[12])=\(([^)]+)\)/);
+        if (!sigMatch)
+            return null;
+        const label = sigMatch[1];
+        const components = sigMatch[2]
+            .split(' ')
+            .map(h => h.replace(/"/g, ''));
+        // Extract all params (keyid/keyId, alg, created, expires, nonce, tag)
+        const keyIdMatch = input.match(/keyid="([^"]+)"/i);
+        const algMatch = input.match(/alg="([^"]+)"/);
+        const createdMatch = input.match(/created=(\d+)/);
+        const expiresMatch = input.match(/expires=(\d+)/);
+        const nonceMatch = input.match(/nonce="([^"]+)"/);
+        const tagMatch = input.match(/tag="([^"]+)"/);
+        if (!keyIdMatch || !algMatch || !createdMatch)
+            return null;
+        return {
+            label,
+            keyId: keyIdMatch[1],
+            algorithm: algMatch[1],
+            created: parseInt(createdMatch[1]),
+            expires: expiresMatch ? parseInt(expiresMatch[1]) : undefined,
+            nonce: nonceMatch ? nonceMatch[1] : undefined,
+            tag: tagMatch ? tagMatch[1] : undefined,
+            components
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve public key from static keys, cache, or JWKS endpoints
+ */
+async function resolveKey(keyId, jwksUrls, staticKeys, cache, cacheTtl) {
+    // 1. Check static keys
+    if (staticKeys.has(keyId)) {
+        return { key: staticKeys.get(keyId), source: 'static' };
+    }
+    // 2. Check cache
+    const cached = cache.get(keyId);
+    if (cached && (Date.now() - cached.fetchedAt) / 1000 < cacheTtl) {
+        return { key: cached.key, source: cached.source };
+    }
+    // 3. Fetch from JWKS endpoints
+    for (const url of jwksUrls) {
+        try {
+            const resp = await fetch(url);
+            if (!resp.ok)
+                continue;
+            const jwks = await resp.json();
+            const matchingKey = jwks.keys?.find((k) => k.kid === keyId);
+            if (matchingKey) {
+                const pem = await jwkToPublicKeyPem(matchingKey);
+                const source = url.includes('visa.com') ? 'visa' :
+                    url.includes('botcha') ? 'botcha' : 'unknown';
+                cache.set(keyId, { key: pem, fetchedAt: Date.now(), source });
+                return { key: pem, source };
+            }
+        }
+        catch (e) {
+            console.error(`Failed to fetch JWKS from ${url}:`, e);
+        }
+    }
+    return null;
+}
+/**
+ * Convert JWK to PEM format using Web Crypto
+ */
+export async function jwkToPublicKeyPem(jwk) {
+    const algorithm = jwkAlgToImportParams(jwk.alg || jwk.kty);
+    const key = await crypto.subtle.importKey('jwk', jwk, algorithm, true, ['verify']);
+    const spki = await crypto.subtle.exportKey('spki', key);
+    const base64 = btoa(String.fromCharCode(...new Uint8Array(spki)));
+    const lines = base64.match(/.{1,64}/g) || [base64];
+    return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----`;
+}
+/**
+ * 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' };
+        case 'EC':
+            // Default EC to P-256
+            return { name: 'ECDSA', namedCurve: 'P-256' };
+        case 'RSA':
+            return { name: 'RSA-PSS', hash: 'SHA-256' };
+        case 'OKP':
+            // Octet Key Pair - Ed25519
+            return { name: 'Ed25519' };
+        default:
+            throw new Error(`Unsupported JWK algorithm: ${alg}`);
+    }
+}
+/**
+ * Verify edge signature against signature base
+ */
+export async function verifyEdgeSignature(req, parsed, signature, publicKey, algorithm) {
+    try {
+        // 1. Validate timestamps
+        const timestampValidation = validateEdgeTimestamps(parsed.created, parsed.expires);
+        if (!timestampValidation.valid) {
+            return { verified: false, error: timestampValidation.error };
+        }
+        // 2. Get authority from host header
+        // Try multiple ways to get the host
+        let authority = req.header('host') || req.header(':authority') || '';
+        // Fallback: try to extract from URL if available
+        if (!authority && 'url' in req && typeof req.url === 'string') {
+            try {
+                authority = new URL(req.url).hostname;
+            }
+            catch {
+                // ignore URL parse errors
+            }
+        }
+        // Get path from req - Hono Request has .path property
+        let path;
+        if ('path' in req && typeof req.path === 'string') {
+            path = req.path;
+        }
+        else if ('url' in req) {
+            path = new URL(req.url).pathname;
+        }
+        else {
+            path = '/';
+        }
+        // 3. Build signature base
+        const signatureBase = buildEdgeSignatureBase(authority, path, parsed);
+        // 4. Verify cryptographic signature
+        const isValid = await verifyCryptoSignature(signatureBase, signature, publicKey, algorithm, parsed.label);
+        if (!isValid) {
+            return { verified: false, error: 'Signature verification failed' };
+        }
+        return {
+            verified: true,
+            tag: parsed.tag,
+            agentKeyId: parsed.keyId,
+            algorithm: parsed.algorithm,
+            nonce: parsed.nonce,
+            timestamp: parsed.created,
+        };
+    }
+    catch (error) {
+        return {
+            verified: false,
+            error: `Verification error: ${error instanceof Error ? error.message : 'Unknown error'}`
+        };
+    }
+}
+/**
+ * Build signature base string according to RFC 9421 TAP format
+ */
+export function buildEdgeSignatureBase(authority, path, parsed) {
+    const lines = [];
+    // Add component lines (values are bare, no quotes)
+    for (const component of parsed.components) {
+        if (component === '@authority') {
+            lines.push(`"@authority": ${authority}`);
+        }
+        else if (component === '@path') {
+            lines.push(`"@path": ${path}`);
+        }
+        else if (component === '@method') {
+            lines.push(`"@method": GET`); // Edge typically handles GET requests
+        }
+        // Note: Other headers would need to be passed in if components include them
+    }
+    // Build @signature-params line with ALL fields
+    const componentsList = parsed.components.map(c => `"${c}"`).join(' ');
+    let paramsLine = `"@signature-params": ${parsed.label}=(${componentsList});created=${parsed.created};keyid="${parsed.keyId}";alg="${parsed.algorithm}"`;
+    if (parsed.expires !== undefined) {
+        paramsLine += `;expires=${parsed.expires}`;
+    }
+    if (parsed.nonce) {
+        paramsLine += `;nonce="${parsed.nonce}"`;
+    }
+    if (parsed.tag) {
+        paramsLine += `;tag="${parsed.tag}"`;
+    }
+    lines.push(paramsLine);
+    return lines.join('\n');
+}
+/**
+ * Validate created/expires timestamps according to TAP spec
+ */
+function validateEdgeTimestamps(created, expires) {
+    const now = Math.floor(Date.now() / 1000);
+    const clockSkew = 30; // 30 seconds tolerance for clock drift
+    // created must be in the past (with clock skew)
+    if (created > now + clockSkew) {
+        return { valid: false, error: 'Signature timestamp is in the future' };
+    }
+    // If expires is present, validate it
+    if (expires !== undefined) {
+        // expires must be in the future
+        if (expires < now) {
+            return { valid: false, error: 'Signature has expired' };
+        }
+        // expires - created must be <= 480 seconds (8 minutes per TAP spec)
+        const window = expires - created;
+        if (window > 480) {
+            return { valid: false, error: 'Signature validity window exceeds 8 minutes' };
+        }
+    }
+    else {
+        // No expires - fall back to 5-minute tolerance on created (backward compat)
+        const age = now - created;
+        if (age > 300) {
+            return { valid: false, error: 'Signature timestamp too old' };
+        }
+        if (age < -clockSkew) {
+            return { valid: false, error: 'Signature timestamp too new' };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Verify cryptographic signature using Web Crypto API
+ */
+async function verifyCryptoSignature(signatureBase, signature, publicKeyPem, algorithm, label) {
+    try {
+        // Extract signature bytes using the correct label
+        const sigPattern = new RegExp(`${label}=:([^:]+):`);
+        const sigMatch = signature.match(sigPattern);
+        if (!sigMatch)
+            return false;
+        const signatureBytes = Uint8Array.from(atob(sigMatch[1]), c => c.charCodeAt(0));
+        // Import public key
+        const keyData = importPublicKey(publicKeyPem, algorithm);
+        const cryptoKey = await crypto.subtle.importKey('spki', keyData, getImportParams(algorithm), false, ['verify']);
+        // Verify signature
+        const encoder = new TextEncoder();
+        const data = encoder.encode(signatureBase);
+        return await crypto.subtle.verify(getVerifyParams(algorithm), cryptoKey, signatureBytes, data);
+    }
+    catch (error) {
+        console.error('Crypto signature verification error:', error);
+        return false;
+    }
+}
+/**
+ * Import public key - handles PEM SPKI and raw Ed25519 formats
+ */
+function importPublicKey(key, algorithm) {
+    // Check if it's a raw Ed25519 key (32 bytes base64)
+    if (algorithm.toLowerCase().includes('ed25519') || algorithm === 'Ed25519') {
+        if (isRawEd25519Key(key)) {
+            return rawEd25519ToSPKI(key);
+        }
+    }
+    // Otherwise parse as PEM
+    return pemToArrayBuffer(key);
+}
+/**
+ * Detect raw Ed25519 public key (32 bytes = 43-44 base64 chars)
+ */
+function isRawEd25519Key(key) {
+    const stripped = key.replace(/[\s\n\r-]/g, '').replace(/BEGIN.*?END[^-]*-*/g, '');
+    try {
+        const decoded = atob(stripped.replace(/-/g, '+').replace(/_/g, '/'));
+        return decoded.length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert raw 32-byte Ed25519 key to SPKI format
+ */
+function rawEd25519ToSPKI(rawKey) {
+    const rawBytes = Uint8Array.from(atob(rawKey), c => c.charCodeAt(0));
+    if (rawBytes.length !== 32) {
+        throw new Error('Invalid Ed25519 key length');
+    }
+    // SPKI header for Ed25519 (12 bytes)
+    const spkiHeader = new Uint8Array([
+        0x30, 0x2a, // SEQUENCE (42 bytes)
+        0x30, 0x05, // SEQUENCE (5 bytes) - algorithm
+        0x06, 0x03, 0x2b, 0x65, 0x70, // OID 1.3.101.112 (Ed25519)
+        0x03, 0x21, 0x00 // BIT STRING (33 bytes, 0 unused bits)
+    ]);
+    const spki = new Uint8Array(spkiHeader.length + rawBytes.length);
+    spki.set(spkiHeader, 0);
+    spki.set(rawBytes, spkiHeader.length);
+    return spki.buffer;
+}
+/**
+ * Convert PEM public key 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;
+}
+/**
+ * Get Web Crypto API algorithm parameters for key import
+ */
+function getImportParams(algorithm) {
+    const alg = algorithm.toLowerCase();
+    if (alg.includes('ed25519')) {
+        return { name: 'Ed25519' };
+    }
+    switch (algorithm) {
+        case 'ecdsa-p256-sha256':
+            return { name: 'ECDSA', namedCurve: 'P-256' };
+        case 'rsa-pss-sha256':
+            return { name: 'RSA-PSS', hash: 'SHA-256' };
+        default:
+            throw new Error(`Unsupported algorithm: ${algorithm}`);
+    }
+}
+/**
+ * Get Web Crypto API algorithm parameters for signature verification
+ */
+function getVerifyParams(algorithm) {
+    const alg = algorithm.toLowerCase();
+    if (alg.includes('ed25519')) {
+        return { name: 'Ed25519' };
+    }
+    switch (algorithm) {
+        case 'ecdsa-p256-sha256':
+            return { name: 'ECDSA', hash: 'SHA-256' };
+        case 'rsa-pss-sha256':
+            return { name: 'RSA-PSS', saltLength: 32 };
+        default:
+            throw new Error(`Unsupported algorithm: ${algorithm}`);
+    }
+}
+// ============ CONVENIENCE PRESETS ============
+/**
+ * Strict mode: require TAP on all requests, block failures
+ */
+export const tapEdgeStrict = (jwksUrls) => createTAPEdgeMiddleware({
+    jwksUrls,
+    allowUnverified: false,
+    requireTag: true,
+    blockOnFailure: true
+});
+/**
+ * Flexible mode: verify if present, pass through if not
+ */
+export const tapEdgeFlexible = (jwksUrls) => createTAPEdgeMiddleware({
+    jwksUrls,
+    allowUnverified: true,
+    requireTag: false,
+    blockOnFailure: false
+});
+/**
+ * Development mode: log only, never block
+ */
+export const tapEdgeDev = () => createTAPEdgeMiddleware({
+    allowUnverified: true,
+    blockOnFailure: false,
+    onVerified: (r) => console.log('[TAP] Verified:', r),
+    onFailed: (r) => console.log('[TAP] Failed:', r),
+});
+// ============ EXPORTS ============
+export default {
+    createTAPEdgeMiddleware,
+    tapEdgeStrict,
+    tapEdgeFlexible,
+    tapEdgeDev,
+    TAP_EDGE_HEADERS,
+};

package/dist/tap-federation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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
+ */
+export interface FederatedKeySource {
+    url: string;
+    name: string;
+    trustLevel: 'high' | 'medium' | 'low';
+    refreshInterval: number;
+    enabled: boolean;
+}
+export interface FederatedKey {
+    kid: string;
+    kty: string;
+    alg: string;
+    publicKeyPem: string;
+    source: string;
+    sourceUrl: string;
+    trustLevel: 'high' | 'medium' | 'low';
+    fetchedAt: number;
+    expiresAt: number;
+    x5c?: string[];
+}
+export interface FederationConfig {
+    sources: FederatedKeySource[];
+    kvNamespace?: KVNamespace;
+    defaultRefreshInterval?: number;
+    maxCacheAge?: number;
+}
+export interface KeyResolutionResult {
+    found: boolean;
+    key?: FederatedKey;
+    error?: string;
+}
+interface KVNamespace {
+    get(key: string, type?: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+export declare const WELL_KNOWN_SOURCES: FederatedKeySource[];
+/**
+ * Fetch JWKS from a URL
+ * @throws Error if fetch fails or response is invalid
+ */
+export declare function fetchJWKS(url: string): Promise<{
+    keys: any[];
+}>;
+/**
+ * Convert a JWK from an external source to FederatedKey format
+ */
+export declare function jwkToFederatedKey(jwk: any, source: FederatedKeySource): Promise<FederatedKey>;
+/**
+ * Resolve Web Crypto import parameters based on JWK type
+ */
+export declare function resolveImportParams(jwk: any): any;
+/**
+ * Infer algorithm from JWK if not specified
+ */
+export declare function inferAlgorithm(jwk: any): string;
+export interface FederationResolver {
+    resolveKey(kid: string): Promise<KeyResolutionResult>;
+    refreshAll(): Promise<{
+        refreshed: number;
+        errors: string[];
+    }>;
+    getCachedKeys(): FederatedKey[];
+    clearCache(): void;
+}
+/**
+ * Create a federation resolver that fetches and caches keys from external sources
+ */
+export declare function createFederationResolver(config: FederationConfig): FederationResolver;
+/**
+ * Create a Visa-specific federation resolver
+ */
+export declare function createVisaFederationResolver(kvNamespace?: KVNamespace): FederationResolver;
+declare const _default: {
+    fetchJWKS: typeof fetchJWKS;
+    jwkToFederatedKey: typeof jwkToFederatedKey;
+    createFederationResolver: typeof createFederationResolver;
+    createVisaFederationResolver: typeof createVisaFederationResolver;
+    resolveImportParams: typeof resolveImportParams;
+    inferAlgorithm: typeof inferAlgorithm;
+    WELL_KNOWN_SOURCES: FederatedKeySource[];
+};
+export default _default;
+//# sourceMappingURL=tap-federation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-federation.d.ts","sourceRoot":"","sources":["../src/tap-federation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,UAAU,WAAW;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF;AAID,eAAO,MAAM,kBAAkB,EAAE,kBAAkB,EASlD,CAAC;AAIF;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,CAiBrE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAcjD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAK/C;AAaD,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtD,UAAU,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC/D,aAAa,IAAI,YAAY,EAAE,CAAC;IAChC,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAiIrF;AAID;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,kBAAkB,CAO1F;;;;;;;;;;AAID,wBAQE"}