@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/tap-vc-routes.js

@@ -0,0 +1,367 @@
+/**
+ * DID/VC API Routes
+ *
+ * Endpoints:
+ *   GET  /.well-known/did.json        — BOTCHA DID Document (did:web:botcha.ai)
+ *   POST /v1/credentials/issue        — Issue VC from a valid BOTCHA access_token
+ *   POST /v1/credentials/verify       — Verify a VC JWT
+ *   GET  /v1/dids/:did/resolve        — Resolve a did:web DID Document
+ *
+ * All credential issuance requires a valid BOTCHA access_token in the
+ * Authorization header (Bearer <token>). The token is the result of a
+ * successful BOTCHA challenge solve (/v1/token/verify).
+ */
+import { extractBearerToken, verifyToken, getSigningPublicKeyJWK, } from './auth.js';
+import { generateBotchaDIDDocument, resolveDIDWeb, buildAgentDID, parseDID, } from './tap-did.js';
+import { issueVC, verifyVC } from './tap-vc.js';
+import { getTAPAgent } from './tap-agents.js';
+// ============ HELPERS ============
+function getSigningKey(env) {
+    const raw = env?.JWT_SIGNING_KEY;
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function getPublicKeyJwk(env) {
+    const sk = getSigningKey(env);
+    return sk ? getSigningPublicKeyJWK(sk) : undefined;
+}
+// ============ ROUTES ============
+/**
+ * GET /.well-known/did.json
+ *
+ * Returns the BOTCHA DID Document for did:web:botcha.ai.
+ * This is a public endpoint — no auth required.
+ * Resolvers use this to discover BOTCHA's public keys for VC verification.
+ */
+export async function didDocumentRoute(c) {
+    try {
+        const baseUrl = new URL(c.req.url).origin;
+        const publicKey = getPublicKeyJwk(c.env);
+        const doc = generateBotchaDIDDocument(baseUrl, publicKey);
+        return new Response(JSON.stringify(doc, null, 2), {
+            status: 200,
+            headers: {
+                'Content-Type': 'application/did+ld+json',
+                'Cache-Control': 'public, max-age=3600',
+                'Access-Control-Allow-Origin': '*',
+            },
+        });
+    }
+    catch (error) {
+        console.error('DID document error:', error);
+        return c.json({ error: 'INTERNAL_ERROR', message: 'Failed to generate DID document' }, 500);
+    }
+}
+/**
+ * POST /v1/credentials/issue
+ *
+ * Exchange a valid BOTCHA access_token for a W3C Verifiable Credential.
+ *
+ * Request (body, all optional):
+ *   {
+ *     "agent_id": "agent_xxx",          // Override agent identity in VC
+ *     "duration_seconds": 86400,        // VC validity period (default: 24h, max: 30d)
+ *   }
+ *
+ * Headers:
+ *   Authorization: Bearer <access_token>   (required — from /v1/token/verify)
+ *
+ * Response:
+ *   {
+ *     "success": true,
+ *     "credential_id": "urn:botcha:vc:...",
+ *     "vc": { ...W3C JSON-LD credential... },
+ *     "vc_jwt": "eyJ...",
+ *     "issued_at": "2026-...",
+ *     "expires_at": "2026-...",
+ *   }
+ */
+export async function issueVCRoute(c) {
+    try {
+        // 1. Authenticate — require a valid BOTCHA access_token
+        const authHeader = c.req.header('authorization');
+        const token = extractBearerToken(authHeader);
+        if (!token) {
+            return c.json({
+                success: false,
+                error: 'UNAUTHORIZED',
+                message: 'Missing Bearer token. Solve a BOTCHA challenge first: POST /v1/token/verify',
+            }, 401);
+        }
+        const publicKey = getPublicKeyJwk(c.env);
+        const tokenResult = await verifyToken(token, c.env.JWT_SECRET, c.env, undefined, publicKey);
+        if (!tokenResult.valid || !tokenResult.payload) {
+            return c.json({
+                success: false,
+                error: 'INVALID_TOKEN',
+                message: tokenResult.error || 'Token is invalid or expired',
+            }, 401);
+        }
+        const tokenPayload = tokenResult.payload;
+        // 2. Parse optional request body
+        let body = {};
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            // No body or non-JSON — that's fine, all fields are optional
+        }
+        const appId = tokenPayload.app_id;
+        if (!appId) {
+            return c.json({
+                success: false,
+                error: 'MISSING_APP_ID',
+                message: 'Token is missing app_id claim. Request a token scoped to your app.',
+            }, 403);
+        }
+        // 3. Look up agent DID if agent_id is provided (or from token)
+        const resolvedAgentId = body.agent_id || undefined;
+        let agentDid;
+        let capabilities;
+        let trustLevel = 'basic';
+        if (resolvedAgentId) {
+            const agentResult = await getTAPAgent(c.env.AGENTS, resolvedAgentId);
+            if (!agentResult.success || !agentResult.agent) {
+                return c.json({
+                    success: false,
+                    error: 'AGENT_NOT_FOUND',
+                    message: `Agent ${resolvedAgentId} not found in BOTCHA registry`,
+                }, 404);
+            }
+            const agent = agentResult.agent;
+            if (agent.app_id !== appId) {
+                return c.json({
+                    success: false,
+                    error: 'APP_ID_MISMATCH',
+                    message: 'Agent belongs to a different app. You can only issue credentials for agents in your own app.',
+                }, 403);
+            }
+            // Only include agent DID if it has a registered `did` field (custom) or
+            // derive it from their agent_id in BOTCHA's namespace
+            if (agent.did) {
+                agentDid = agent.did;
+            }
+            else if (agent.tap_enabled) {
+                // TAP-registered agents get a BOTCHA-namespace DID
+                agentDid = buildAgentDID(agent.agent_id);
+            }
+            // Collect capability strings
+            if (agent.capabilities && agent.capabilities.length > 0) {
+                capabilities = agent.capabilities.map((cap) => cap.scope && cap.scope.length > 0
+                    ? `${cap.action}:${cap.scope.join(',')}`
+                    : cap.action);
+            }
+            trustLevel = agent.trust_level || 'basic';
+        }
+        // 4. Issue the VC
+        const signingKey = getSigningKey(c.env);
+        const vcResult = await issueVC({
+            agent_id: resolvedAgentId,
+            app_id: appId,
+            solve_time_ms: tokenPayload.solveTime || 0,
+            challenge_type: 'speed', // access_tokens are always from speed challenges
+            trust_level: trustLevel,
+            capabilities,
+            agent_did: agentDid,
+            duration_seconds: body.duration_seconds,
+        }, signingKey, c.env.JWT_SECRET);
+        if (!vcResult.success) {
+            return c.json({
+                success: false,
+                error: 'VC_ISSUANCE_FAILED',
+                message: vcResult.error || 'Failed to issue credential',
+            }, 500);
+        }
+        return c.json({
+            success: true,
+            credential_id: vcResult.credential_id,
+            vc: vcResult.vc,
+            vc_jwt: vcResult.vc_jwt,
+            issued_at: vcResult.issued_at,
+            expires_at: vcResult.expires_at,
+            issuer: 'did:web:botcha.ai',
+            usage: {
+                note: 'Present vc_jwt to any service that accepts BOTCHA Verifiable Credentials.',
+                verify_endpoint: `${new URL(c.req.url).origin}/v1/credentials/verify`,
+                offline_verify: 'Fetch /.well-known/jwks and verify the JWT signature yourself.',
+                did_document: `${new URL(c.req.url).origin}/.well-known/did.json`,
+            },
+        }, 201);
+    }
+    catch (error) {
+        console.error('VC issuance route error:', error);
+        return c.json({
+            success: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error',
+        }, 500);
+    }
+}
+/**
+ * POST /v1/credentials/verify
+ *
+ * Verify a BOTCHA VC JWT. No auth required — the VC is the credential.
+ *
+ * Request body:
+ *   { "vc_jwt": "eyJ..." }
+ *
+ * Response (valid):
+ *   {
+ *     "valid": true,
+ *     "issuer": "did:web:botcha.ai",
+ *     "credential_id": "urn:botcha:vc:...",
+ *     "credential_subject": { ... },
+ *     "issued_at": "...",
+ *     "expires_at": "...",
+ *   }
+ *
+ * Response (invalid):
+ *   { "valid": false, "error": "..." }
+ */
+export async function verifyVCRoute(c) {
+    try {
+        let body = {};
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({
+                valid: false,
+                error: 'INVALID_REQUEST',
+                message: 'Request body must be JSON with a "vc_jwt" field',
+            }, 400);
+        }
+        if (!body.vc_jwt || typeof body.vc_jwt !== 'string') {
+            return c.json({
+                valid: false,
+                error: 'MISSING_VC_JWT',
+                message: 'Provide { "vc_jwt": "<JWT string>" } in the request body',
+            }, 400);
+        }
+        const signingKey = getSigningKey(c.env);
+        if (!signingKey && !c.env.JWT_SECRET) {
+            return c.json({
+                valid: false,
+                error: 'SERVICE_UNAVAILABLE',
+                message: 'VC verification is not configured on this server. Contact support.',
+            }, 503);
+        }
+        const result = await verifyVC(body.vc_jwt, signingKey, c.env.JWT_SECRET);
+        if (!result.valid) {
+            return c.json({
+                valid: false,
+                error: result.error || 'Verification failed',
+            }, 200); // 200 with valid:false — the request itself succeeded
+        }
+        return c.json({
+            valid: true,
+            issuer: result.issuer,
+            credential_id: result.credential_id,
+            credential_subject: result.credential_subject,
+            vc: result.vc,
+            issued_at: result.issued_at,
+            expires_at: result.expires_at,
+        });
+    }
+    catch (error) {
+        console.error('VC verification route error:', error);
+        return c.json({
+            valid: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error',
+        }, 500);
+    }
+}
+/**
+ * GET /v1/dids/:did/resolve
+ *
+ * Resolve a did:web DID Document.
+ * This is a public endpoint — no auth required.
+ *
+ * Supports: did:web:* only (other methods return methodNotSupported)
+ *
+ * Special case: did:web:botcha.ai is resolved locally (no outbound fetch).
+ *
+ * Query params:
+ *   (none currently)
+ *
+ * Response:
+ *   W3C DID Resolution Result object
+ */
+export async function resolveDIDRoute(c) {
+    try {
+        // The DID is URL-encoded in the path param — decode it
+        const rawParam = c.req.param('did');
+        if (!rawParam) {
+            return c.json({
+                '@context': 'https://w3id.org/did-resolution/v1',
+                didDocument: null,
+                didResolutionMetadata: { error: 'invalidDid: DID parameter is missing' },
+                didDocumentMetadata: {},
+            }, 400);
+        }
+        // Path parameters may be URL-encoded (e.g. "did%3Aweb%3Aexample.com")
+        const did = decodeURIComponent(rawParam);
+        // Validate DID format before attempting resolution
+        const parsed = parseDID(did);
+        if (!parsed.valid) {
+            return c.json({
+                '@context': 'https://w3id.org/did-resolution/v1',
+                didDocument: null,
+                didResolutionMetadata: { error: `invalidDid: ${parsed.error}` },
+                didDocumentMetadata: {},
+            }, 400);
+        }
+        if (parsed.method !== 'web') {
+            return c.json({
+                '@context': 'https://w3id.org/did-resolution/v1',
+                didDocument: null,
+                didResolutionMetadata: {
+                    error: `methodNotSupported: Method "${parsed.method}" is not supported. Only did:web is implemented.`,
+                },
+                didDocumentMetadata: {},
+            }, 400);
+        }
+        // Special case: resolve botcha.ai locally
+        if (did === 'did:web:botcha.ai') {
+            const baseUrl = new URL(c.req.url).origin;
+            const publicKey = getPublicKeyJwk(c.env);
+            const doc = generateBotchaDIDDocument(baseUrl, publicKey);
+            return c.json({
+                '@context': 'https://w3id.org/did-resolution/v1',
+                didDocument: doc,
+                didResolutionMetadata: {
+                    contentType: 'application/did+ld+json',
+                    retrieved: new Date().toISOString(),
+                    duration: 0,
+                },
+                didDocumentMetadata: {},
+            });
+        }
+        // Resolve external did:web
+        const result = await resolveDIDWeb(did);
+        const statusCode = result.didDocument ? 200 : 404;
+        return c.json(result, statusCode);
+    }
+    catch (error) {
+        console.error('DID resolution route error:', error);
+        return c.json({
+            '@context': 'https://w3id.org/did-resolution/v1',
+            didDocument: null,
+            didResolutionMetadata: { error: 'internalError: Internal server error' },
+            didDocumentMetadata: {},
+        }, 500);
+    }
+}
+export default {
+    didDocumentRoute,
+    issueVCRoute,
+    verifyVCRoute,
+    resolveDIDRoute,
+};

package/dist/tap-vc.d.ts

@@ -0,0 +1,125 @@
+/**
+ * BOTCHA Verifiable Credentials — W3C VC Data Model 2.0
+ *
+ * Implements:
+ *   - VC issuance: sign a BotchaVerification credential as a JWT
+ *   - VC verification: validate signature, expiry, and issuer
+ *   - Credential schema aligned with the VC Data Model 2.0 spec
+ *
+ * Encoding:
+ *   VCs are encoded as JWT-VCs per the VC Data Model 2.0 spec.
+ *   The JWT payload contains a "vc" claim with the JSON-LD credential,
+ *   plus standard JWT claims (iss, sub, jti, iat, nbf, exp).
+ *
+ * Signing:
+ *   - Preferred: ES256 with the BOTCHA JWT_SIGNING_KEY (verifiable offline)
+ *   - Fallback:  HS256 with JWT_SECRET (verifiable only by botcha.ai)
+ *
+ * Standards:
+ *   - W3C VC Data Model 2.0: https://www.w3.org/TR/vc-data-model-2.0/
+ *   - VC-JWT: https://www.w3.org/TR/vc-data-model-2.0/#json-web-token
+ *   - DID Core 1.0: https://www.w3.org/TR/did-core/
+ */
+import type { ES256SigningKeyJWK } from './auth.js';
+export interface BotchaCredentialSubject {
+    id?: string;
+    agent_id: string;
+    app_id: string;
+    challenge_type: string;
+    solve_time_ms: number;
+    trust_level: 'basic' | 'verified' | 'enterprise';
+    capabilities?: string[];
+}
+export interface VerifiableCredential {
+    '@context': string[];
+    type: string[];
+    id: string;
+    issuer: string;
+    credentialSubject: BotchaCredentialSubject;
+    validFrom: string;
+    validUntil: string;
+}
+export interface IssueVCOptions {
+    /** BOTCHA agent_id — from agent registration (optional; anonymous if not registered) */
+    agent_id?: string;
+    /** App that created the challenge */
+    app_id: string;
+    /** Challenge solve time in milliseconds */
+    solve_time_ms: number;
+    /** Challenge type (speed, hybrid, reasoning) */
+    challenge_type?: string;
+    /** Agent trust level */
+    trust_level?: 'basic' | 'verified' | 'enterprise';
+    /** Agent capabilities (strings like "browse:products") */
+    capabilities?: string[];
+    /** Agent DID — embedded as credentialSubject.id when present */
+    agent_did?: string;
+    /** Validity period in seconds (default: 86400 = 24 h; max: 2592000 = 30 days) */
+    duration_seconds?: number;
+}
+export interface VCIssuanceResult {
+    success: boolean;
+    /** The W3C VC JSON-LD object */
+    vc?: VerifiableCredential;
+    /** The signed JWT-VC (what you send to relying parties) */
+    vc_jwt?: string;
+    credential_id?: string;
+    issued_at?: string;
+    expires_at?: string;
+    error?: string;
+}
+export interface VCVerificationResult {
+    valid: boolean;
+    vc?: VerifiableCredential;
+    credential_subject?: BotchaCredentialSubject;
+    issuer?: string;
+    credential_id?: string;
+    issued_at?: string;
+    expires_at?: string;
+    error?: string;
+}
+/**
+ * Issue a W3C Verifiable Credential for a successful BOTCHA verification.
+ *
+ * The VC is encoded as a JWT-VC signed with BOTCHA's ES256 key.
+ * If no ES256 key is available, falls back to HS256.
+ *
+ * The JWT payload includes:
+ *   iss = did:web:botcha.ai
+ *   sub = agent DID or agent_id
+ *   jti = credential ID (urn:botcha:vc:<uuid>)
+ *   vc  = the full JSON-LD credential object
+ *   type = "botcha-vc" (BOTCHA-specific claim for quick type-checking)
+ */
+export declare function issueVC(options: IssueVCOptions, signingKey?: ES256SigningKeyJWK, secret?: string): Promise<VCIssuanceResult>;
+/**
+ * Verify a BOTCHA VC JWT.
+ *
+ * Checks (in order):
+ *   1. JWT signature (ES256 or HS256)
+ *   2. JWT expiration (exp claim)
+ *   3. Token type claim = "botcha-vc"
+ *   4. Issuer claim = "did:web:botcha.ai"
+ *   5. Presence of `vc` claim with credentialSubject
+ *
+ * Returns the decoded VC and credential subject if valid.
+ */
+export declare function verifyVC(vcJwt: string, signingKey?: ES256SigningKeyJWK, secret?: string): Promise<VCVerificationResult>;
+/**
+ * Extract the BOTCHA access_token payload from the Authorization header.
+ * Returns null if the token is missing or cannot be decoded (does NOT verify).
+ */
+export declare function extractVCPayloadClaims(vcJwt: string): {
+    agent_id?: string;
+    app_id?: string;
+    solve_time_ms?: number;
+    challenge_type?: string;
+    trust_level?: string;
+} | null;
+declare const _default: {
+    issueVC: typeof issueVC;
+    verifyVC: typeof verifyVC;
+    extractVCPayloadClaims: typeof extractVCPayloadClaims;
+};
+export default _default;
+//# sourceMappingURL=tap-vc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-vc.d.ts","sourceRoot":"","sources":["../src/tap-vc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAKpD,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,UAAU,GAAG,YAAY,CAAC;IACjD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,uBAAuB,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wBAAwB;IACxB,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,YAAY,CAAC;IAClD,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,EAAE,CAAC,EAAE,oBAAoB,CAAC;IAC1B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,oBAAoB,CAAC;IAC1B,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,kBAAkB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAoG3B;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,kBAAkB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,oBAAoB,CAAC,CAwE/B;AAID;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAmBP;;;;;;AAED,wBAIE"}