@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/webhooks.js

@@ -0,0 +1,642 @@
+/**
+ * BOTCHA Webhook Event System
+ *
+ * Delivers real-time events to API owners when things happen:
+ *   token.created / token.revoked
+ *   agent.tap.registered / tap.session.created
+ *   delegation.created / delegation.revoked
+ *
+ * KV keys (all stored in AGENTS namespace):
+ *   webhook:{id}               — WebhookConfig (without secret)
+ *   webhook_secret:{id}        — HMAC signing secret
+ *   app_webhooks:{app_id}      — JSON string[] of webhook IDs for this app
+ *   webhook_deliveries:{id}    — JSON DeliveryLog[] (last 100, TTL 7d)
+ */
+import { extractBearerToken, verifyToken, getSigningPublicKeyJWK } from './auth.js';
+export const ALL_EVENT_TYPES = [
+    'agent.tap.registered',
+    'token.created',
+    'token.revoked',
+    'tap.session.created',
+    'delegation.created',
+    'delegation.revoked',
+];
+// ============ ID GENERATION ============
+function generateId(prefix) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+    return `${prefix}_${hex}`;
+}
+// ============ HMAC-SHA256 SIGNING ============
+export async function computeHmacSignature(secret, body) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(body));
+    const hex = Array.from(new Uint8Array(sig)).map(b => b.toString(16).padStart(2, '0')).join('');
+    return `sha256=${hex}`;
+}
+// ============ KV HELPERS ============
+async function getWebhook(kv, id) {
+    const raw = await kv.get(`webhook:${id}`);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function saveWebhook(kv, webhook) {
+    await kv.put(`webhook:${webhook.id}`, JSON.stringify(webhook));
+}
+async function getAppWebhookIds(kv, appId) {
+    const raw = await kv.get(`app_webhooks:${appId}`);
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function setAppWebhookIds(kv, appId, ids) {
+    await kv.put(`app_webhooks:${appId}`, JSON.stringify(ids));
+}
+async function getDeliveries(kv, webhookId) {
+    const raw = await kv.get(`webhook_deliveries:${webhookId}`);
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function appendDelivery(kv, webhookId, log) {
+    const existing = await getDeliveries(kv, webhookId);
+    // Keep last 100
+    const updated = [log, ...existing].slice(0, 100);
+    // TTL 7 days
+    await kv.put(`webhook_deliveries:${webhookId}`, JSON.stringify(updated), { expirationTtl: 604800 });
+}
+// ============ RETRY DELAYS ============
+// Keep retries short for Worker waitUntil execution windows.
+const DELIVERY_ATTEMPTS = 3;
+const RETRY_DELAYS_MS = [150, 600];
+const DELIVERY_TIMEOUT_MS = 2500;
+const WAIT_UNTIL_BUDGET_MS = 12000;
+const MAX_WEBHOOKS_PER_APP = 25;
+function isPrivateIPv4(hostname) {
+    const parts = hostname.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(n => !Number.isInteger(n) || n < 0 || n > 255))
+        return false;
+    const [a, b] = parts;
+    if (a === 10)
+        return true;
+    if (a === 127)
+        return true;
+    if (a === 0)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    return false;
+}
+function isPrivateIPv6(hostname) {
+    const h = hostname.toLowerCase();
+    if (h === '::1')
+        return true;
+    if (h.startsWith('fe80:'))
+        return true; // link-local
+    if (h.startsWith('fc') || h.startsWith('fd'))
+        return true; // unique local
+    return false;
+}
+function validateWebhookUrl(urlValue) {
+    let parsed;
+    try {
+        parsed = new URL(urlValue);
+    }
+    catch {
+        return { valid: false, error: 'INVALID_URL', message: 'url must be a valid HTTPS URL' };
+    }
+    if (parsed.protocol !== 'https:') {
+        return { valid: false, error: 'INVALID_URL', message: 'url must use https:// scheme' };
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host === 'localhost' || host.endsWith('.localhost') || host === '0.0.0.0') {
+        return { valid: false, error: 'UNSAFE_URL', message: 'localhost and loopback webhook URLs are not allowed' };
+    }
+    if (isPrivateIPv4(host) || isPrivateIPv6(host)) {
+        return { valid: false, error: 'UNSAFE_URL', message: 'private-network webhook URLs are not allowed' };
+    }
+    return { valid: true, normalizedUrl: parsed.toString() };
+}
+function normalizeWebhookEvents(events) {
+    if (!Array.isArray(events) || events.length === 0) {
+        return { valid: false, message: 'events must be a non-empty array of supported event types' };
+    }
+    const unsupported = events.filter((event) => typeof event !== 'string' || !ALL_EVENT_TYPES.includes(event));
+    if (unsupported.length > 0) {
+        return {
+            valid: false,
+            message: `Unsupported event type(s): ${unsupported.map(String).join(', ')}`,
+        };
+    }
+    const deduped = Array.from(new Set(events));
+    return { valid: true, events: deduped };
+}
+// ============ SINGLE DELIVERY ATTEMPT ============
+async function attemptDelivery(url, body, signature, eventType, timeoutMs = DELIVERY_TIMEOUT_MS) {
+    const start = Date.now();
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Botcha-Signature': signature,
+                'X-Botcha-Event': eventType,
+                'User-Agent': 'Botcha-Webhook/1.0',
+            },
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const durationMs = Date.now() - start;
+        const success = response.status >= 200 && response.status < 300;
+        return { statusCode: response.status, success, durationMs };
+    }
+    catch (err) {
+        const durationMs = Date.now() - start;
+        const error = err instanceof Error ? err.message : 'Unknown error';
+        return { statusCode: null, success: false, error, durationMs };
+    }
+}
+// ============ CORE DELIVERY FUNCTION ============
+/**
+ * Fire-and-forget webhook delivery with retry logic.
+ * Call via: ctx.waitUntil(triggerWebhook(...))
+ */
+export async function triggerWebhook(kv, appId, eventType, data) {
+    // Build event payload
+    const event = {
+        id: generateId('evt'),
+        type: eventType,
+        created_at: new Date().toISOString(),
+        app_id: appId,
+        data,
+    };
+    const body = JSON.stringify(event);
+    // Load all webhooks for this app
+    const ids = await getAppWebhookIds(kv, appId);
+    if (ids.length === 0)
+        return;
+    const deadlineMs = Date.now() + WAIT_UNTIL_BUDGET_MS;
+    await Promise.allSettled(ids.map(async (webhookId) => {
+        try {
+            const webhook = await getWebhook(kv, webhookId);
+            if (!webhook)
+                return;
+            if (!webhook.enabled || webhook.suspended)
+                return;
+            if (!webhook.events.includes(eventType))
+                return;
+            const secret = await kv.get(`webhook_secret:${webhookId}`);
+            if (!secret)
+                return;
+            const signature = await computeHmacSignature(secret, body);
+            let success = false;
+            let attemptsMade = 0;
+            for (let attempt = 0; attempt < DELIVERY_ATTEMPTS; attempt++) {
+                if (attempt > 0) {
+                    const delayMs = RETRY_DELAYS_MS[Math.min(attempt - 1, RETRY_DELAYS_MS.length - 1)] || 0;
+                    if (Date.now() + delayMs >= deadlineMs)
+                        break;
+                    await sleep(delayMs);
+                }
+                const remainingMs = deadlineMs - Date.now();
+                if (remainingMs <= 0)
+                    break;
+                const timeoutMs = Math.max(300, Math.min(DELIVERY_TIMEOUT_MS, remainingMs));
+                const result = await attemptDelivery(webhook.url, body, signature, eventType, timeoutMs);
+                attemptsMade += 1;
+                const log = {
+                    delivery_id: generateId('dlv'),
+                    webhook_id: webhookId,
+                    event_type: eventType,
+                    event_id: event.id,
+                    attempted_at: Date.now(),
+                    attempt_number: attempt + 1,
+                    status_code: result.statusCode,
+                    success: result.success,
+                    error: result.error,
+                    duration_ms: result.durationMs,
+                };
+                await appendDelivery(kv, webhookId, log);
+                if (result.success) {
+                    success = true;
+                    webhook.consecutive_failures = 0;
+                    webhook.suspended = false;
+                    await saveWebhook(kv, webhook);
+                    break;
+                }
+            }
+            if (!success) {
+                if (attemptsMade === 0) {
+                    await appendDelivery(kv, webhookId, {
+                        delivery_id: generateId('dlv'),
+                        webhook_id: webhookId,
+                        event_type: eventType,
+                        event_id: event.id,
+                        attempted_at: Date.now(),
+                        attempt_number: 1,
+                        status_code: null,
+                        success: false,
+                        error: 'Delivery skipped: waitUntil execution budget exceeded',
+                        duration_ms: 0,
+                    });
+                }
+                webhook.consecutive_failures = (webhook.consecutive_failures || 0) + 1;
+                // Suspend after 3 consecutive failures
+                if (webhook.consecutive_failures >= 3) {
+                    webhook.suspended = true;
+                }
+                await saveWebhook(kv, webhook);
+            }
+        }
+        catch (error) {
+            console.error(`Webhook delivery failed for ${webhookId}:`, error);
+        }
+    }));
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// ============ AUTH HELPER FOR ROUTES ============
+function getVerificationPublicKey(env) {
+    const rawSigningKey = env?.JWT_SIGNING_KEY;
+    if (!rawSigningKey)
+        return undefined;
+    try {
+        const signingKey = JSON.parse(rawSigningKey);
+        return getSigningPublicKeyJWK(signingKey);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function validateAppAccess(c) {
+    const authHeader = c.req.header('authorization');
+    const token = extractBearerToken(authHeader);
+    if (!token) {
+        return { valid: false, error: 'UNAUTHORIZED', status: 401 };
+    }
+    const publicKey = getVerificationPublicKey(c.env);
+    const result = await verifyToken(token, c.env.JWT_SECRET, c.env, undefined, publicKey);
+    if (!result.valid || !result.payload) {
+        return { valid: false, error: 'INVALID_TOKEN', status: 401 };
+    }
+    const jwtAppId = result.payload.app_id;
+    if (!jwtAppId) {
+        return { valid: false, error: 'MISSING_APP_ID', status: 403 };
+    }
+    return { valid: true, appId: jwtAppId };
+}
+// ============ ROUTE HANDLERS ============
+/**
+ * POST /v1/webhooks
+ * Register a new webhook endpoint.
+ */
+export async function createWebhookRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const appId = auth.appId;
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ success: false, error: 'INVALID_JSON', message: 'Request body must be JSON' }, 400);
+    }
+    const { url, events } = body;
+    if (!url || typeof url !== 'string') {
+        return c.json({ success: false, error: 'MISSING_URL', message: 'url is required' }, 400);
+    }
+    const urlValidation = validateWebhookUrl(url);
+    if (!urlValidation.valid) {
+        return c.json({ success: false, error: urlValidation.error, message: urlValidation.message }, 400);
+    }
+    // Validate events
+    let eventList = [...ALL_EVENT_TYPES];
+    if (events !== undefined) {
+        const normalized = normalizeWebhookEvents(events);
+        if (!normalized.valid) {
+            return c.json({ success: false, error: 'INVALID_EVENTS', message: normalized.message }, 400);
+        }
+        eventList = normalized.events;
+    }
+    const webhookId = generateId('wh');
+    const now = Date.now();
+    const kv = c.env.AGENTS;
+    const existingIds = await getAppWebhookIds(kv, appId);
+    if (existingIds.length >= MAX_WEBHOOKS_PER_APP) {
+        return c.json({
+            success: false,
+            error: 'WEBHOOK_LIMIT_REACHED',
+            message: `Maximum of ${MAX_WEBHOOKS_PER_APP} webhooks per app`,
+        }, 400);
+    }
+    const webhook = {
+        id: webhookId,
+        app_id: appId,
+        url: urlValidation.normalizedUrl,
+        events: eventList,
+        enabled: true,
+        created_at: now,
+        updated_at: now,
+        consecutive_failures: 0,
+        suspended: false,
+    };
+    // Generate HMAC secret (32 random bytes → hex)
+    const secretBytes = new Uint8Array(32);
+    crypto.getRandomValues(secretBytes);
+    const secret = Array.from(secretBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+    // Save webhook config and secret
+    await saveWebhook(kv, webhook);
+    await kv.put(`webhook_secret:${webhookId}`, secret);
+    // Add to app index
+    await setAppWebhookIds(kv, appId, [...existingIds, webhookId]);
+    return c.json({
+        success: true,
+        webhook: {
+            id: webhookId,
+            app_id: appId,
+            url: webhook.url,
+            events: eventList,
+            enabled: true,
+            created_at: new Date(now).toISOString(),
+        },
+        // Secret shown ONCE — store it securely!
+        secret,
+        warning: '⚠️ Save your webhook secret now — it will never be shown again. Use it to verify X-Botcha-Signature headers.',
+        signature_info: 'Each delivery includes X-Botcha-Signature: sha256=<hmac-sha256-hex> header. Computed as HMAC-SHA256(secret, request_body).',
+    }, 201);
+}
+/**
+ * GET /v1/webhooks
+ * List all webhooks for the authenticated app.
+ */
+export async function listWebhooksRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const appId = auth.appId;
+    const kv = c.env.AGENTS;
+    const ids = await getAppWebhookIds(kv, appId);
+    const webhooks = (await Promise.all(ids.map(id => getWebhook(kv, id))))
+        .filter((w) => w !== null)
+        .map(w => ({
+        id: w.id,
+        app_id: w.app_id,
+        url: w.url,
+        events: w.events,
+        enabled: w.enabled,
+        suspended: w.suspended,
+        consecutive_failures: w.consecutive_failures,
+        created_at: new Date(w.created_at).toISOString(),
+        updated_at: new Date(w.updated_at).toISOString(),
+    }));
+    return c.json({ success: true, webhooks });
+}
+/**
+ * GET /v1/webhooks/:id
+ * Get a specific webhook.
+ */
+export async function getWebhookRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const webhookId = c.req.param('id');
+    const kv = c.env.AGENTS;
+    const webhook = await getWebhook(kv, webhookId);
+    if (!webhook) {
+        return c.json({ success: false, error: 'NOT_FOUND', message: 'Webhook not found' }, 404);
+    }
+    if (webhook.app_id !== auth.appId) {
+        return c.json({ success: false, error: 'FORBIDDEN' }, 403);
+    }
+    return c.json({
+        success: true,
+        webhook: {
+            id: webhook.id,
+            app_id: webhook.app_id,
+            url: webhook.url,
+            events: webhook.events,
+            enabled: webhook.enabled,
+            suspended: webhook.suspended,
+            consecutive_failures: webhook.consecutive_failures,
+            created_at: new Date(webhook.created_at).toISOString(),
+            updated_at: new Date(webhook.updated_at).toISOString(),
+        },
+    });
+}
+/**
+ * PUT /v1/webhooks/:id
+ * Update webhook (url, events, enabled).
+ */
+export async function updateWebhookRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const webhookId = c.req.param('id');
+    const kv = c.env.AGENTS;
+    const webhook = await getWebhook(kv, webhookId);
+    if (!webhook) {
+        return c.json({ success: false, error: 'NOT_FOUND', message: 'Webhook not found' }, 404);
+    }
+    if (webhook.app_id !== auth.appId) {
+        return c.json({ success: false, error: 'FORBIDDEN' }, 403);
+    }
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ success: false, error: 'INVALID_JSON' }, 400);
+    }
+    if (body.url !== undefined) {
+        const urlValidation = validateWebhookUrl(body.url);
+        if (!urlValidation.valid) {
+            return c.json({ success: false, error: urlValidation.error, message: urlValidation.message }, 400);
+        }
+        webhook.url = urlValidation.normalizedUrl;
+    }
+    if (body.events !== undefined) {
+        const normalized = normalizeWebhookEvents(body.events);
+        if (!normalized.valid) {
+            return c.json({ success: false, error: 'INVALID_EVENTS', message: normalized.message }, 400);
+        }
+        webhook.events = normalized.events;
+    }
+    if (typeof body.enabled === 'boolean') {
+        webhook.enabled = body.enabled;
+        // Re-enabling a suspended webhook resets failure counter
+        if (body.enabled && webhook.suspended) {
+            webhook.suspended = false;
+            webhook.consecutive_failures = 0;
+        }
+    }
+    webhook.updated_at = Date.now();
+    await saveWebhook(kv, webhook);
+    return c.json({
+        success: true,
+        webhook: {
+            id: webhook.id,
+            app_id: webhook.app_id,
+            url: webhook.url,
+            events: webhook.events,
+            enabled: webhook.enabled,
+            suspended: webhook.suspended,
+            updated_at: new Date(webhook.updated_at).toISOString(),
+        },
+    });
+}
+/**
+ * DELETE /v1/webhooks/:id
+ * Delete a webhook.
+ */
+export async function deleteWebhookRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const webhookId = c.req.param('id');
+    const kv = c.env.AGENTS;
+    const webhook = await getWebhook(kv, webhookId);
+    if (!webhook) {
+        return c.json({ success: false, error: 'NOT_FOUND', message: 'Webhook not found' }, 404);
+    }
+    if (webhook.app_id !== auth.appId) {
+        return c.json({ success: false, error: 'FORBIDDEN' }, 403);
+    }
+    await kv.delete(`webhook:${webhookId}`);
+    await kv.delete(`webhook_secret:${webhookId}`);
+    await kv.delete(`webhook_deliveries:${webhookId}`);
+    // Remove from app index
+    const ids = await getAppWebhookIds(kv, auth.appId);
+    await setAppWebhookIds(kv, auth.appId, ids.filter(id => id !== webhookId));
+    return c.json({ success: true, deleted: true, id: webhookId });
+}
+/**
+ * POST /v1/webhooks/:id/test
+ * Send a test event to verify endpoint reachability.
+ */
+export async function testWebhookRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const webhookId = c.req.param('id');
+    const kv = c.env.AGENTS;
+    const webhook = await getWebhook(kv, webhookId);
+    if (!webhook) {
+        return c.json({ success: false, error: 'NOT_FOUND', message: 'Webhook not found' }, 404);
+    }
+    if (webhook.app_id !== auth.appId) {
+        return c.json({ success: false, error: 'FORBIDDEN' }, 403);
+    }
+    const secret = await kv.get(`webhook_secret:${webhookId}`);
+    if (!secret) {
+        return c.json({ success: false, error: 'SECRET_NOT_FOUND' }, 500);
+    }
+    const testEvent = {
+        id: generateId('evt'),
+        type: 'token.created',
+        created_at: new Date().toISOString(),
+        app_id: auth.appId,
+        data: {
+            test: true,
+            message: '🐢 BOTCHA webhook test event — if you can read this, delivery is working!',
+            webhook_id: webhookId,
+        },
+    };
+    const body = JSON.stringify(testEvent);
+    const signature = await computeHmacSignature(secret, body);
+    const result = await attemptDelivery(webhook.url, body, signature, 'token.created');
+    const log = {
+        delivery_id: generateId('dlv'),
+        webhook_id: webhookId,
+        event_type: 'token.created',
+        event_id: testEvent.id,
+        attempted_at: Date.now(),
+        attempt_number: 1,
+        status_code: result.statusCode,
+        success: result.success,
+        error: result.error,
+        duration_ms: result.durationMs,
+    };
+    await appendDelivery(kv, webhookId, log);
+    return c.json({
+        success: result.success,
+        delivery: {
+            status_code: result.statusCode,
+            success: result.success,
+            duration_ms: result.durationMs,
+            error: result.error,
+        },
+        event: testEvent,
+        message: result.success
+            ? `✅ Test delivery succeeded (${result.statusCode}) in ${result.durationMs}ms`
+            : `❌ Test delivery failed: ${result.error || `HTTP ${result.statusCode}`}`,
+    });
+}
+/**
+ * GET /v1/webhooks/:id/deliveries
+ * Get recent delivery log (last 100 attempts).
+ */
+export async function listDeliveriesRoute(c) {
+    const auth = await validateAppAccess(c);
+    if (!auth.valid || !auth.appId) {
+        return c.json({ success: false, error: auth.error }, (auth.status ?? 401));
+    }
+    const webhookId = c.req.param('id');
+    const kv = c.env.AGENTS;
+    const webhook = await getWebhook(kv, webhookId);
+    if (!webhook) {
+        return c.json({ success: false, error: 'NOT_FOUND', message: 'Webhook not found' }, 404);
+    }
+    if (webhook.app_id !== auth.appId) {
+        return c.json({ success: false, error: 'FORBIDDEN' }, 403);
+    }
+    const deliveries = await getDeliveries(kv, webhookId);
+    return c.json({
+        success: true,
+        webhook_id: webhookId,
+        deliveries: deliveries.map(d => ({
+            delivery_id: d.delivery_id,
+            event_type: d.event_type,
+            event_id: d.event_id,
+            attempted_at: new Date(d.attempted_at).toISOString(),
+            attempt_number: d.attempt_number,
+            status_code: d.status_code,
+            success: d.success,
+            error: d.error,
+            duration_ms: d.duration_ms,
+        })),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dupecom/botcha-cloudflare",
-  "version": "0.20.2",
+  "version": "0.23.0",
   "description": "BOTCHA for Cloudflare Workers - Prove you're a bot. Humans need not apply.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,6 +40,8 @@
   },
   "homepage": "https://botcha.ai",
   "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
     "hono": "^4.7.0",
     "jose": "^5.9.6"
   },