@dupecom/botcha-cloudflare 0.16.0 → 0.18.0

package/dist/tap-delegation-routes.js

@@ -0,0 +1,378 @@
+/**
+ * TAP Delegation Chain API Routes
+ *
+ * Endpoints for creating, querying, revoking, and verifying
+ * delegation chains between TAP agents.
+ *
+ * Routes:
+ *   POST   /v1/delegations              — Create delegation
+ *   GET    /v1/delegations/:id          — Get delegation details
+ *   GET    /v1/delegations              — List delegations (by agent)
+ *   POST   /v1/delegations/:id/revoke   — Revoke delegation (cascades)
+ *   POST   /v1/verify/delegation        — Verify delegation chain
+ */
+import { extractBearerToken, verifyToken } from './auth.js';
+import { TAP_VALID_ACTIONS } from './tap-agents.js';
+import { createDelegation, getDelegation, listDelegations, revokeDelegation, verifyDelegationChain, } from './tap-delegation.js';
+// ============ VALIDATION HELPERS ============
+async function validateAppAccess(c, requireAuth = true) {
+    const queryAppId = c.req.query('app_id');
+    let jwtAppId;
+    const authHeader = c.req.header('authorization');
+    const token = extractBearerToken(authHeader);
+    if (token) {
+        const result = await verifyToken(token, c.env.JWT_SECRET, c.env);
+        if (result.valid && result.payload) {
+            jwtAppId = result.payload.app_id;
+        }
+    }
+    const appId = queryAppId || jwtAppId;
+    if (requireAuth && !appId) {
+        return { valid: false, error: 'MISSING_APP_ID', status: 401 };
+    }
+    return { valid: true, appId };
+}
+// ============ ROUTE HANDLERS ============
+/**
+ * POST /v1/delegations
+ * Create a delegation from one agent to another
+ */
+export async function createDelegationRoute(c) {
+    try {
+        const appAccess = await validateAppAccess(c, true);
+        if (!appAccess.valid) {
+            return c.json({
+                success: false,
+                error: appAccess.error,
+                message: 'Authentication required'
+            }, (appAccess.status || 401));
+        }
+        const body = await c.req.json().catch(() => ({}));
+        // Validate required fields
+        if (!body.grantor_id || !body.grantee_id) {
+            return c.json({
+                success: false,
+                error: 'MISSING_REQUIRED_FIELDS',
+                message: 'grantor_id and grantee_id are required'
+            }, 400);
+        }
+        if (!body.capabilities || !Array.isArray(body.capabilities) || body.capabilities.length === 0) {
+            return c.json({
+                success: false,
+                error: 'MISSING_CAPABILITIES',
+                message: 'At least one capability is required'
+            }, 400);
+        }
+        // Validate capability actions
+        for (const cap of body.capabilities) {
+            if (!cap.action || !TAP_VALID_ACTIONS.includes(cap.action)) {
+                return c.json({
+                    success: false,
+                    error: 'INVALID_CAPABILITY',
+                    message: `Invalid capability action. Valid: ${TAP_VALID_ACTIONS.join(', ')}`
+                }, 400);
+            }
+        }
+        const options = {
+            grantor_id: body.grantor_id,
+            grantee_id: body.grantee_id,
+            capabilities: body.capabilities,
+            duration_seconds: body.duration_seconds,
+            max_depth: body.max_depth,
+            parent_delegation_id: body.parent_delegation_id,
+            metadata: body.metadata,
+        };
+        const result = await createDelegation(c.env.AGENTS, c.env.SESSIONS, appAccess.appId, options);
+        if (!result.success) {
+            // Determine appropriate status code
+            const status = result.error?.includes('not found') ? 404
+                : result.error?.includes('does not belong') ? 403
+                    : result.error?.includes('Cannot delegate') ? 403
+                        : result.error?.includes('depth limit') ? 403
+                            : result.error?.includes('cycle') ? 409
+                                : result.error?.includes('revoked') ? 410
+                                    : result.error?.includes('expired') ? 410
+                                        : 400;
+            return c.json({
+                success: false,
+                error: 'DELEGATION_CREATION_FAILED',
+                message: result.error
+            }, status);
+        }
+        const del = result.delegation;
+        return c.json({
+            success: true,
+            delegation_id: del.delegation_id,
+            grantor_id: del.grantor_id,
+            grantee_id: del.grantee_id,
+            app_id: del.app_id,
+            capabilities: del.capabilities,
+            chain: del.chain,
+            depth: del.depth,
+            max_depth: del.max_depth,
+            parent_delegation_id: del.parent_delegation_id || null,
+            created_at: new Date(del.created_at).toISOString(),
+            expires_at: new Date(del.expires_at).toISOString(),
+            metadata: del.metadata || null,
+        }, 201);
+    }
+    catch (error) {
+        console.error('Delegation creation error:', error);
+        return c.json({
+            success: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error'
+        }, 500);
+    }
+}
+/**
+ * GET /v1/delegations/:id
+ * Get delegation details
+ */
+export async function getDelegationRoute(c) {
+    try {
+        const delegationId = c.req.param('id');
+        if (!delegationId) {
+            return c.json({
+                success: false,
+                error: 'MISSING_DELEGATION_ID',
+                message: 'Delegation ID is required'
+            }, 400);
+        }
+        const result = await getDelegation(c.env.SESSIONS, delegationId);
+        if (!result.success || !result.delegation) {
+            return c.json({
+                success: false,
+                error: 'DELEGATION_NOT_FOUND',
+                message: result.error || 'Delegation not found or expired'
+            }, 404);
+        }
+        const del = result.delegation;
+        return c.json({
+            success: true,
+            delegation_id: del.delegation_id,
+            grantor_id: del.grantor_id,
+            grantee_id: del.grantee_id,
+            app_id: del.app_id,
+            capabilities: del.capabilities,
+            chain: del.chain,
+            depth: del.depth,
+            max_depth: del.max_depth,
+            parent_delegation_id: del.parent_delegation_id || null,
+            created_at: new Date(del.created_at).toISOString(),
+            expires_at: new Date(del.expires_at).toISOString(),
+            revoked: del.revoked,
+            revoked_at: del.revoked_at ? new Date(del.revoked_at).toISOString() : null,
+            revocation_reason: del.revocation_reason || null,
+            metadata: del.metadata || null,
+            time_remaining: Math.max(0, del.expires_at - Date.now()),
+        });
+    }
+    catch (error) {
+        console.error('Delegation retrieval error:', error);
+        return c.json({
+            success: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error'
+        }, 500);
+    }
+}
+/**
+ * GET /v1/delegations
+ * List delegations for an agent
+ *
+ * Query params:
+ *   agent_id    — required, the agent to list delegations for
+ *   direction   — 'in', 'out', or 'both' (default: 'both')
+ *   include_revoked — 'true' to include revoked delegations
+ *   include_expired — 'true' to include expired delegations
+ */
+export async function listDelegationsRoute(c) {
+    try {
+        const appAccess = await validateAppAccess(c, true);
+        if (!appAccess.valid) {
+            return c.json({
+                success: false,
+                error: appAccess.error,
+                message: 'Authentication required'
+            }, (appAccess.status || 401));
+        }
+        const agentId = c.req.query('agent_id');
+        if (!agentId) {
+            return c.json({
+                success: false,
+                error: 'MISSING_AGENT_ID',
+                message: 'agent_id query parameter is required'
+            }, 400);
+        }
+        const direction = (c.req.query('direction') || 'both');
+        const includeRevoked = c.req.query('include_revoked') === 'true';
+        const includeExpired = c.req.query('include_expired') === 'true';
+        const result = await listDelegations(c.env.SESSIONS, {
+            agent_id: agentId,
+            app_id: appAccess.appId,
+            direction,
+            include_revoked: includeRevoked,
+            include_expired: includeExpired,
+        });
+        if (!result.success) {
+            return c.json({
+                success: false,
+                error: 'LIST_FAILED',
+                message: result.error || 'Failed to list delegations'
+            }, 500);
+        }
+        const delegations = result.delegations.map(del => ({
+            delegation_id: del.delegation_id,
+            grantor_id: del.grantor_id,
+            grantee_id: del.grantee_id,
+            capabilities: del.capabilities,
+            chain: del.chain,
+            depth: del.depth,
+            created_at: new Date(del.created_at).toISOString(),
+            expires_at: new Date(del.expires_at).toISOString(),
+            revoked: del.revoked,
+            parent_delegation_id: del.parent_delegation_id || null,
+        }));
+        return c.json({
+            success: true,
+            delegations,
+            count: delegations.length,
+            agent_id: agentId,
+            direction,
+        });
+    }
+    catch (error) {
+        console.error('Delegation listing error:', error);
+        return c.json({
+            success: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error'
+        }, 500);
+    }
+}
+/**
+ * POST /v1/delegations/:id/revoke
+ * Revoke a delegation (cascades to sub-delegations)
+ */
+export async function revokeDelegationRoute(c) {
+    try {
+        const delegationId = c.req.param('id');
+        if (!delegationId) {
+            return c.json({
+                success: false,
+                error: 'MISSING_DELEGATION_ID',
+                message: 'Delegation ID is required'
+            }, 400);
+        }
+        const appAccess = await validateAppAccess(c, true);
+        if (!appAccess.valid) {
+            return c.json({
+                success: false,
+                error: appAccess.error,
+                message: 'Authentication required'
+            }, (appAccess.status || 401));
+        }
+        // Verify delegation exists and belongs to this app
+        const existing = await getDelegation(c.env.SESSIONS, delegationId);
+        if (!existing.success || !existing.delegation) {
+            return c.json({
+                success: false,
+                error: 'DELEGATION_NOT_FOUND',
+                message: 'Delegation not found or expired'
+            }, 404);
+        }
+        if (existing.delegation.app_id !== appAccess.appId) {
+            return c.json({
+                success: false,
+                error: 'UNAUTHORIZED',
+                message: 'Delegation does not belong to this app'
+            }, 403);
+        }
+        const body = await c.req.json().catch(() => ({}));
+        const reason = body.reason || undefined;
+        const result = await revokeDelegation(c.env.SESSIONS, delegationId, reason);
+        if (!result.success) {
+            return c.json({
+                success: false,
+                error: 'REVOCATION_FAILED',
+                message: result.error
+            }, 500);
+        }
+        const del = result.delegation;
+        return c.json({
+            success: true,
+            delegation_id: del.delegation_id,
+            revoked: true,
+            revoked_at: del.revoked_at ? new Date(del.revoked_at).toISOString() : null,
+            revocation_reason: del.revocation_reason || null,
+            message: 'Delegation revoked. Sub-delegations have been cascaded.',
+        });
+    }
+    catch (error) {
+        console.error('Delegation revocation error:', error);
+        return c.json({
+            success: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error'
+        }, 500);
+    }
+}
+/**
+ * POST /v1/verify/delegation
+ * Verify an entire delegation chain is valid
+ *
+ * Body: { delegation_id: string }
+ *
+ * Returns the full chain and effective capabilities if valid.
+ */
+export async function verifyDelegationRoute(c) {
+    try {
+        const body = await c.req.json().catch(() => ({}));
+        if (!body.delegation_id) {
+            return c.json({
+                success: false,
+                error: 'MISSING_DELEGATION_ID',
+                message: 'delegation_id is required'
+            }, 400);
+        }
+        const result = await verifyDelegationChain(c.env.AGENTS, c.env.SESSIONS, body.delegation_id);
+        if (!result.valid) {
+            return c.json({
+                success: false,
+                valid: false,
+                error: result.error,
+            }, 400);
+        }
+        return c.json({
+            success: true,
+            valid: true,
+            chain_length: result.chain.length,
+            chain: result.chain.map(del => ({
+                delegation_id: del.delegation_id,
+                grantor_id: del.grantor_id,
+                grantee_id: del.grantee_id,
+                capabilities: del.capabilities,
+                depth: del.depth,
+                created_at: new Date(del.created_at).toISOString(),
+                expires_at: new Date(del.expires_at).toISOString(),
+            })),
+            effective_capabilities: result.effective_capabilities,
+        });
+    }
+    catch (error) {
+        console.error('Delegation verification error:', error);
+        return c.json({
+            success: false,
+            error: 'INTERNAL_ERROR',
+            message: 'Internal server error'
+        }, 500);
+    }
+}
+export default {
+    createDelegationRoute,
+    getDelegationRoute,
+    listDelegationsRoute,
+    revokeDelegationRoute,
+    verifyDelegationRoute,
+};

package/dist/tap-delegation.d.ts

@@ -0,0 +1,127 @@
+/**
+ * TAP Delegation Chains
+ *
+ * "User X authorized Agent Y to do Z until time T."
+ *
+ * Signed, auditable chains of trust between TAP agents. A delegation grants
+ * a subset of one agent's capabilities to another agent, with time bounds
+ * and depth limits. Delegations can be chained (A→B→C) with each link
+ * only narrowing capabilities, never expanding them.
+ *
+ * Key invariants:
+ * - Capabilities can only be narrowed (subset enforcement)
+ * - Chain depth is capped (default max: 3)
+ * - Revoking a delegation cascades to all sub-delegations
+ * - Expired delegations are automatically invalid
+ * - Both grantor and grantee must belong to the same app
+ */
+import type { KVNamespace } from './agents.js';
+import { TAPCapability } from './tap-agents.js';
+export interface Delegation {
+    delegation_id: string;
+    grantor_id: string;
+    grantee_id: string;
+    app_id: string;
+    capabilities: TAPCapability[];
+    parent_delegation_id?: string;
+    chain: string[];
+    depth: number;
+    max_depth: number;
+    created_at: number;
+    expires_at: number;
+    revoked: boolean;
+    revoked_at?: number;
+    revocation_reason?: string;
+    metadata?: Record<string, string>;
+}
+export interface CreateDelegationOptions {
+    grantor_id: string;
+    grantee_id: string;
+    capabilities: TAPCapability[];
+    duration_seconds?: number;
+    max_depth?: number;
+    parent_delegation_id?: string;
+    metadata?: Record<string, string>;
+}
+export interface DelegationResult {
+    success: boolean;
+    delegation?: Delegation;
+    error?: string;
+}
+export interface DelegationListResult {
+    success: boolean;
+    delegations?: Delegation[];
+    error?: string;
+}
+export interface DelegationVerifyResult {
+    valid: boolean;
+    chain?: Delegation[];
+    effective_capabilities?: TAPCapability[];
+    error?: string;
+}
+/**
+ * Check if capabilitiesB is a subset of capabilitiesA.
+ *
+ * A capability in B is valid if there exists a capability in A with the same
+ * action, and B's scope is a subset of A's scope (or A has wildcard scope).
+ * B's restrictions must be equal or stricter.
+ */
+export declare function isCapabilitySubset(parent: TAPCapability[], child: TAPCapability[]): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Create a delegation from one agent to another.
+ *
+ * Validates:
+ * - Both agents exist and belong to the same app
+ * - Grantor has the capabilities being delegated
+ * - Capabilities are a valid subset (never expanded)
+ * - Chain depth is within limits
+ * - Parent delegation (if sub-delegation) is valid and not revoked/expired
+ */
+export declare function createDelegation(agents: KVNamespace, sessions: KVNamespace, appId: string, options: CreateDelegationOptions): Promise<DelegationResult>;
+/**
+ * Get a delegation by ID
+ */
+export declare function getDelegation(sessions: KVNamespace, delegationId: string): Promise<DelegationResult>;
+/**
+ * List delegations for an agent (inbound, outbound, or both)
+ */
+export declare function listDelegations(sessions: KVNamespace, options: {
+    agent_id?: string;
+    app_id?: string;
+    direction?: 'in' | 'out' | 'both';
+    include_revoked?: boolean;
+    include_expired?: boolean;
+}): Promise<DelegationListResult>;
+/**
+ * Revoke a delegation and cascade to all sub-delegations.
+ *
+ * When a delegation is revoked, all delegations that have it as a parent
+ * (directly or transitively) are also revoked. This is enforced by marking
+ * each delegation record as revoked.
+ */
+export declare function revokeDelegation(sessions: KVNamespace, delegationId: string, reason?: string): Promise<DelegationResult>;
+/**
+ * Verify an entire delegation chain is valid.
+ *
+ * Walks from the leaf delegation up through parent delegations to the root,
+ * verifying each link is:
+ * - Not revoked
+ * - Not expired
+ * - Capabilities are valid subsets
+ *
+ * Returns the full chain and effective (intersected) capabilities.
+ */
+export declare function verifyDelegationChain(agents: KVNamespace, sessions: KVNamespace, delegationId: string): Promise<DelegationVerifyResult>;
+declare const _default: {
+    createDelegation: typeof createDelegation;
+    getDelegation: typeof getDelegation;
+    listDelegations: typeof listDelegations;
+    revokeDelegation: typeof revokeDelegation;
+    verifyDelegationChain: typeof verifyDelegationChain;
+    isCapabilitySubset: typeof isCapabilitySubset;
+};
+export default _default;
+//# sourceMappingURL=tap-delegation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-delegation.d.ts","sourceRoot":"","sources":["../src/tap-delegation.ts"],"names":[],"mappings":"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"}