@dupecom/botcha 0.13.1 → 0.15.0

package/dist/src/middleware/tap-enhanced-verify.js

@@ -0,0 +1,368 @@
+/**
+ * TAP-Enhanced BOTCHA Verification Middleware
+ * Extends existing BOTCHA middleware with Trusted Agent Protocol support
+ *
+ * Provides multiple verification modes:
+ * - TAP (full): Cryptographic signature + computational challenge
+ * - Signature-only: Cryptographic verification without challenge
+ * - Challenge-only: Existing BOTCHA computational challenge
+ * - Flexible: TAP preferred but allows fallback
+ */
+import { generateSpeedChallenge, verifySpeedChallenge } from '../challenges/speed.js';
+import { verifyHTTPMessageSignature, parseTAPIntent, extractTAPHeaders, getVerificationMode, buildTAPChallengeResponse } from '../../packages/cloudflare-workers/src/tap-verify.js';
+import { getTAPAgent, updateAgentVerification, createTAPSession } from '../../packages/cloudflare-workers/src/tap-agents.js';
+const defaultTAPOptions = {
+    // BOTCHA defaults
+    requireSignature: false,
+    allowChallenge: true,
+    challengeType: 'speed',
+    challengeDifficulty: 'medium',
+    // TAP defaults
+    requireTAP: false,
+    preferTAP: true,
+    tapEnabled: true,
+    auditLogging: false,
+    trustedIssuers: ['openclaw.ai', 'anthropic.com', 'openai.com'],
+    maxSessionDuration: 3600,
+    signatureAlgorithms: ['ecdsa-p256-sha256', 'rsa-pss-sha256'],
+    requireCapabilities: []
+};
+// ============ MAIN MIDDLEWARE ============
+/**
+ * Enhanced BOTCHA middleware with TAP support
+ */
+export function tapEnhancedVerify(options = {}) {
+    const opts = { ...defaultTAPOptions, ...options };
+    return async (req, res, next) => {
+        const startTime = Date.now();
+        try {
+            // Determine verification approach
+            const { mode, hasTAPHeaders, hasChallenge } = getVerificationMode(req.headers);
+            let result;
+            // Route to appropriate verification method
+            if (mode === 'tap' && opts.tapEnabled) {
+                result = await performFullTAPVerification(req, opts);
+            }
+            else if (mode === 'signature-only' && opts.tapEnabled) {
+                result = await performSignatureOnlyVerification(req, opts);
+            }
+            else if (mode === 'challenge-only') {
+                result = await performChallengeOnlyVerification(req, opts);
+            }
+            else {
+                // Fallback or error case
+                result = await handleVerificationFallback(req, opts, mode);
+            }
+            // Custom verification hook
+            if (opts.customVerify && result.verified) {
+                const customResult = await opts.customVerify(req);
+                if (!customResult) {
+                    result.verified = false;
+                    result.error = 'Custom verification failed';
+                }
+            }
+            // Audit logging
+            if (opts.auditLogging) {
+                logVerificationAttempt(req, result, Date.now() - startTime);
+            }
+            // Handle successful verification
+            if (result.verified) {
+                // Attach verification context to request
+                req.tapAgent = result.agent_id ? await getTAPAgentById(opts.agentsKV, result.agent_id) : null;
+                req.verificationMethod = result.verification_method;
+                req.tapSession = result.session_id;
+                req.challengesPassed = result.challenges_passed;
+                req.verificationDuration = Date.now() - startTime;
+                return next();
+            }
+            // Handle verification failure
+            return sendVerificationChallenge(res, result, opts);
+        }
+        catch (error) {
+            console.error('TAP verification error:', error);
+            if (opts.auditLogging) {
+                console.log('TAP_VERIFICATION_ERROR', {
+                    error: error instanceof Error ? error.message : String(error),
+                    path: req.path,
+                    method: req.method,
+                    timestamp: new Date().toISOString()
+                });
+            }
+            return res.status(500).json({
+                success: false,
+                error: 'VERIFICATION_ERROR',
+                message: 'Internal verification error'
+            });
+        }
+    };
+}
+// ============ VERIFICATION METHODS ============
+/**
+ * Full TAP verification (crypto + computational)
+ */
+async function performFullTAPVerification(req, opts) {
+    const { tapHeaders } = extractTAPHeaders(req.headers);
+    if (!tapHeaders['x-tap-agent-id'] || !opts.agentsKV) {
+        return {
+            verified: false,
+            verification_method: 'tap',
+            challenges_passed: { computational: false, cryptographic: false },
+            error: 'Missing TAP agent ID or storage not configured'
+        };
+    }
+    // Get agent from registry
+    const agentResult = await getTAPAgent(opts.agentsKV, tapHeaders['x-tap-agent-id']);
+    if (!agentResult.success || !agentResult.agent) {
+        return {
+            verified: false,
+            verification_method: 'tap',
+            challenges_passed: { computational: false, cryptographic: false },
+            error: `Agent ${tapHeaders['x-tap-agent-id']} not found`
+        };
+    }
+    const agent = agentResult.agent;
+    // Verify cryptographic signature
+    const cryptoResult = await verifyCryptographicSignature(req, agent);
+    // Verify computational challenge
+    const challengeResult = await verifyComputationalChallenge(req);
+    // Both must pass for full TAP
+    const verified = cryptoResult.valid && challengeResult.valid;
+    // Update agent verification timestamp
+    if (opts.agentsKV) {
+        await updateAgentVerification(opts.agentsKV, agent.agent_id, verified);
+    }
+    // Create session if successful
+    let sessionId;
+    if (verified && opts.sessionsKV && tapHeaders['x-tap-intent'] && tapHeaders['x-tap-user-context']) {
+        const intentResult = parseTAPIntent(tapHeaders['x-tap-intent']);
+        if (intentResult.valid && intentResult.intent) {
+            const sessionResult = await createTAPSession(opts.sessionsKV, agent.agent_id, agent.app_id, tapHeaders['x-tap-user-context'], agent.capabilities || [], intentResult.intent);
+            if (sessionResult.success) {
+                sessionId = sessionResult.session?.session_id;
+            }
+        }
+    }
+    return {
+        verified,
+        agent_id: agent.agent_id,
+        verification_method: 'tap',
+        challenges_passed: {
+            computational: challengeResult.valid,
+            cryptographic: cryptoResult.valid
+        },
+        session_id: sessionId,
+        error: verified ? undefined : `Crypto: ${cryptoResult.error || 'OK'}, Challenge: ${challengeResult.error || 'OK'}`,
+        metadata: {
+            solve_time_ms: challengeResult.solveTimeMs,
+            signature_valid: cryptoResult.valid,
+            capabilities: agent.capabilities?.map((c) => c.action)
+        }
+    };
+}
+/**
+ * Signature-only verification
+ */
+async function performSignatureOnlyVerification(req, opts) {
+    const { tapHeaders } = extractTAPHeaders(req.headers);
+    if (!tapHeaders['x-tap-agent-id'] || !opts.agentsKV) {
+        return {
+            verified: false,
+            verification_method: 'signature-only',
+            challenges_passed: { computational: false, cryptographic: false },
+            error: 'Missing TAP agent ID'
+        };
+    }
+    // Get agent from registry
+    const agentResult = await getTAPAgent(opts.agentsKV, tapHeaders['x-tap-agent-id']);
+    if (!agentResult.success || !agentResult.agent) {
+        return {
+            verified: false,
+            verification_method: 'signature-only',
+            challenges_passed: { computational: false, cryptographic: false },
+            error: 'Agent not found'
+        };
+    }
+    // Verify signature
+    const cryptoResult = await verifyCryptographicSignature(req, agentResult.agent);
+    return {
+        verified: cryptoResult.valid,
+        agent_id: agentResult.agent.agent_id,
+        verification_method: 'signature-only',
+        challenges_passed: {
+            computational: false,
+            cryptographic: cryptoResult.valid
+        },
+        error: cryptoResult.error,
+        metadata: {
+            signature_valid: cryptoResult.valid
+        }
+    };
+}
+/**
+ * Challenge-only verification (existing BOTCHA)
+ */
+async function performChallengeOnlyVerification(req, opts) {
+    const challengeResult = await verifyComputationalChallenge(req);
+    return {
+        verified: challengeResult.valid,
+        verification_method: 'challenge',
+        challenges_passed: {
+            computational: challengeResult.valid,
+            cryptographic: false
+        },
+        error: challengeResult.error,
+        metadata: {
+            solve_time_ms: challengeResult.solveTimeMs
+        }
+    };
+}
+/**
+ * Handle verification fallback cases
+ */
+async function handleVerificationFallback(req, opts, mode) {
+    if (opts.requireTAP) {
+        return {
+            verified: false,
+            verification_method: 'tap',
+            challenges_passed: { computational: false, cryptographic: false },
+            error: 'TAP authentication required'
+        };
+    }
+    // Fallback to challenge-only if allowed
+    if (opts.allowChallenge) {
+        return await performChallengeOnlyVerification(req, opts);
+    }
+    return {
+        verified: false,
+        verification_method: 'challenge',
+        challenges_passed: { computational: false, cryptographic: false },
+        error: 'No valid verification method available'
+    };
+}
+// ============ HELPER FUNCTIONS ============
+async function verifyCryptographicSignature(req, agent) {
+    if (!agent.public_key || !agent.signature_algorithm) {
+        return { valid: false, error: 'Agent has no cryptographic key configured' };
+    }
+    const verificationRequest = {
+        method: req.method,
+        path: req.path,
+        headers: req.headers,
+        body: typeof req.body === 'string' ? req.body : JSON.stringify(req.body)
+    };
+    return await verifyHTTPMessageSignature(verificationRequest, agent.public_key, agent.signature_algorithm);
+}
+async function verifyComputationalChallenge(req) {
+    const challengeId = req.headers['x-botcha-challenge-id'];
+    const answers = req.headers['x-botcha-answers'];
+    if (!challengeId || !answers) {
+        return { valid: false, error: 'Missing challenge ID or answers' };
+    }
+    try {
+        const answersArray = JSON.parse(answers);
+        if (!Array.isArray(answersArray)) {
+            return { valid: false, error: 'Answers must be an array' };
+        }
+        const result = verifySpeedChallenge(challengeId, answersArray);
+        return {
+            valid: result.valid,
+            error: result.reason,
+            solveTimeMs: result.solveTimeMs
+        };
+    }
+    catch (err) {
+        return { valid: false, error: `Challenge verification error: ${err instanceof Error ? err.message : 'Unknown error'}` };
+    }
+}
+async function getTAPAgentById(agentsKV, agentId) {
+    if (!agentsKV)
+        return null;
+    try {
+        const result = await getTAPAgent(agentsKV, agentId);
+        return result.success ? result.agent : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sendVerificationChallenge(res, result, opts) {
+    // Generate challenge if needed
+    let challenge = null;
+    if (!result.challenges_passed.computational && opts.allowChallenge) {
+        challenge = generateSpeedChallenge();
+    }
+    // Build TAP challenge response
+    const response = buildTAPChallengeResponse(result, challenge);
+    // Add challenge headers
+    if (challenge) {
+        res.header('X-Botcha-Challenge-Id', challenge.id);
+        res.header('X-Botcha-Challenge-Type', 'speed');
+        res.header('X-Botcha-Time-Limit', challenge.timeLimit.toString());
+    }
+    // 403 Forbidden for all verification failures (not 401 which implies re-authentication)
+    const statusCode = 403;
+    res.status(statusCode).json(response);
+}
+function logVerificationAttempt(req, result, durationMs) {
+    const logEntry = {
+        timestamp: new Date().toISOString(),
+        method: req.method,
+        path: req.path,
+        userAgent: req.headers['user-agent'],
+        clientIP: req.ip || req.socket?.remoteAddress,
+        verificationMethod: result.verification_method,
+        verified: result.verified,
+        challengesPassed: result.challenges_passed,
+        agentId: result.agent_id,
+        sessionId: result.session_id,
+        durationMs,
+        error: result.error
+    };
+    console.log('TAP_VERIFICATION_AUDIT', logEntry);
+}
+// ============ PRE-CONFIGURED MODES ============
+export const tapVerifyModes = {
+    /**
+     * Require full TAP authentication (crypto + challenge)
+     */
+    strict: (options = {}) => tapEnhancedVerify({
+        requireTAP: true,
+        allowChallenge: true,
+        auditLogging: true,
+        ...options
+    }),
+    /**
+     * Prefer TAP but allow computational fallback
+     */
+    flexible: (options = {}) => tapEnhancedVerify({
+        preferTAP: true,
+        allowChallenge: true,
+        requireTAP: false,
+        ...options
+    }),
+    /**
+     * Signature-only verification (no computational challenge)
+     */
+    signatureOnly: (options = {}) => tapEnhancedVerify({
+        requireTAP: false,
+        allowChallenge: false,
+        tapEnabled: true,
+        ...options
+    }),
+    /**
+     * Development mode with relaxed security
+     */
+    development: (options = {}) => tapEnhancedVerify({
+        requireTAP: false,
+        allowChallenge: true,
+        auditLogging: true,
+        trustedIssuers: ['test-issuer', 'localhost', 'development'],
+        ...options
+    })
+};
+/**
+ * Alias for tapEnhancedVerify for backward compatibility with docs.
+ * Docs reference: import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware'
+ */
+export const createTAPVerifyMiddleware = tapEnhancedVerify;
+export default tapEnhancedVerify;

package/dist/src/middleware/verify.d.ts

@@ -0,0 +1,12 @@
+import { Request, Response, NextFunction } from 'express';
+interface BotchaOptions {
+    requireSignature?: boolean;
+    allowChallenge?: boolean;
+    challengeType?: 'standard' | 'speed';
+    challengeDifficulty?: 'easy' | 'medium' | 'hard';
+    trustedProviders?: string[];
+    customVerify?: (req: Request) => Promise<boolean>;
+}
+export declare function botchaVerify(options?: BotchaOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+export default botchaVerify;
+//# sourceMappingURL=verify.d.ts.map

package/dist/src/middleware/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/middleware/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK1D,UAAU,aAAa;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACrC,mBAAmB,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACnD;AASD,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,IAGxC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,mBAqD9D;AA0FD,eAAe,YAAY,CAAC"}

package/dist/src/middleware/verify.js

@@ -0,0 +1,141 @@
+import { generateChallenge, verifyChallenge } from '../challenges/compute.js';
+import { generateSpeedChallenge, verifySpeedChallenge } from '../challenges/speed.js';
+import { verifyWebBotAuth, isTrustedProvider } from '../utils/signature.js';
+const defaultOptions = {
+    requireSignature: false,
+    allowChallenge: true,
+    challengeType: 'standard',
+    challengeDifficulty: 'medium',
+};
+export function botchaVerify(options = {}) {
+    const opts = { ...defaultOptions, ...options };
+    return async (req, res, next) => {
+        const result = await verifyAgent(req, opts);
+        if (result.verified) {
+            req.agent = result.agent;
+            req.verificationMethod = result.method;
+            req.provider = result.provider;
+            return next();
+        }
+        // Not verified - return challenge or denial
+        const challenge = opts.allowChallenge
+            ? (opts.challengeType === 'speed'
+                ? generateSpeedChallenge()
+                : generateChallenge(opts.challengeDifficulty))
+            : undefined;
+        // Add challenge-specific headers
+        if (challenge) {
+            res.header('X-Botcha-Challenge-Id', challenge.id);
+            res.header('X-Botcha-Challenge-Type', opts.challengeType === 'speed' ? 'speed' : 'standard');
+            res.header('X-Botcha-Time-Limit', challenge.timeLimit.toString());
+        }
+        res.status(403).json({
+            success: false,
+            error: 'BOTCHA_VERIFICATION_FAILED',
+            code: 'BOTCHA_CHALLENGE',
+            message: '🚫 Access denied. This endpoint is for AI agents only.',
+            hint: result.hint,
+            challenge: challenge ? (opts.challengeType === 'speed'
+                ? {
+                    id: challenge.id,
+                    type: 'speed',
+                    problems: challenge.challenges,
+                    timeLimit: `${challenge.timeLimit}ms`,
+                    instructions: challenge.instructions,
+                    submitHeader: 'X-Botcha-Challenge-Id',
+                    answerHeader: 'X-Botcha-Answers',
+                }
+                : {
+                    id: challenge.id,
+                    type: 'standard',
+                    puzzle: challenge.puzzle,
+                    timeLimit: `${challenge.timeLimit}ms`,
+                    hint: challenge.hint,
+                    submitHeader: 'X-Botcha-Challenge-Id',
+                    answerHeader: 'X-Botcha-Solution',
+                }) : undefined,
+        });
+    };
+}
+async function verifyAgent(req, opts) {
+    // Method 1: Web Bot Auth cryptographic signature (strongest)
+    const signatureAgent = req.headers['signature-agent'];
+    if (signatureAgent) {
+        // Check if from trusted provider
+        if (!isTrustedProvider(signatureAgent)) {
+            return {
+                verified: false,
+                hint: `Provider ${signatureAgent} not in trusted list`,
+            };
+        }
+        const sigResult = await verifyWebBotAuth(req.headers, req.method, req.path, typeof req.body === 'string' ? req.body : JSON.stringify(req.body));
+        if (sigResult.valid) {
+            return {
+                verified: true,
+                method: 'signature',
+                agent: sigResult.agent,
+                provider: sigResult.provider,
+            };
+        }
+    }
+    // Method 2: Challenge-Response (if challenge solution provided)
+    const challengeId = req.headers['x-botcha-challenge-id']
+        || req.headers['x-botcha-id'];
+    const solution = req.headers['x-botcha-solution'];
+    const answersHeader = req.headers['x-botcha-answers'];
+    if (challengeId && (solution || answersHeader)) {
+        const speedPayload = answersHeader || (solution && looksLikeJsonArray(solution) ? solution : undefined);
+        if (speedPayload) {
+            const answers = parseJsonArray(speedPayload);
+            if (!answers) {
+                return { verified: false, hint: 'Invalid speed challenge answers format' };
+            }
+            const speedResult = verifySpeedChallenge(challengeId, answers);
+            if (speedResult.valid) {
+                return {
+                    verified: true,
+                    method: 'challenge',
+                    agent: `speed-challenge-verified (${speedResult.solveTimeMs}ms)`,
+                };
+            }
+            return { verified: false, hint: speedResult.reason };
+        }
+        if (!solution) {
+            return { verified: false, hint: 'Missing challenge solution' };
+        }
+        const result = verifyChallenge(challengeId, solution);
+        if (result.valid) {
+            return {
+                verified: true,
+                method: 'challenge',
+                agent: `challenge-verified (${result.timeMs}ms)`,
+            };
+        }
+        return { verified: false, hint: result.reason };
+    }
+    // Method 3: X-Agent-Identity header (dev/testing ONLY — should NOT be enabled in production)
+    // NOTE: This is intentionally NOT enabled by default in the standalone verify middleware.
+    // Use the Express middleware (lib/index.ts) with allowTestHeader: true for dev mode.
+    // No verification succeeded — User-Agent patterns are NOT sufficient for verification.
+    // A User-Agent header can be trivially spoofed by any HTTP client.
+    return {
+        verified: false,
+        hint: 'Provide Signature-Agent header (Web Bot Auth) or solve a challenge (X-Botcha-Challenge-Id + X-Botcha-Solution)',
+    };
+}
+export default botchaVerify;
+function looksLikeJsonArray(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith('[') && trimmed.endsWith(']');
+}
+function parseJsonArray(value) {
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return null;
+        return parsed.map(item => String(item));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/utils/badge-image.d.ts

@@ -0,0 +1,15 @@
+import { BadgePayload } from './badge.js';
+interface BadgeImageOptions {
+    width?: number;
+    height?: number;
+}
+/**
+ * Generate an SVG badge image
+ */
+export declare function generateBadgeSvg(payload: BadgePayload, options?: BadgeImageOptions): string;
+/**
+ * Generate an HTML verification page
+ */
+export declare function generateBadgeHtml(payload: BadgePayload, badgeId: string): string;
+export {};
+//# sourceMappingURL=badge-image.d.ts.map

package/dist/src/utils/badge-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge-image.d.ts","sourceRoot":"","sources":["../../../src/utils/badge-image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AAEvD,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA6BD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAuER;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAyJhF"}