@nordsym/apiclaw 1.5.17 → 1.5.19

package/WHITELIST-ARCHITECTURE.md

@@ -1,379 +0,0 @@
-# APIClaw Multi-Product Whitelist Architecture
-
-**Version:** 2.0  
-**Date:** 2026-03-18  
-**Status:** Production Ready
-
----
-
-## Overview
-
-APIClaw supports multiple products (Hivr, NordSym, partners) accessing Direct Call APIs via HTTP endpoints with:
-- **Product-namespaced agentIds** (`product:agentName`)
-- **Per-provider access control** (some products get certain APIs only)
-- **Dynamic whitelist syncing** from product Convex deployments
-- **Per-product analytics** tracking
-
----
-
-## Architecture
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  Products                                                     │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
-│  │  Hivr    │  │ NordSym  │  │Partner X │                   │
-│  │ Convex   │  │  Convex  │  │  Convex  │                   │
-│  └─────┬────┘  └─────┬────┘  └─────┬────┘                   │
-└────────┼─────────────┼─────────────┼────────────────────────┘
-         │             │             │
-         │ agents:list │ team:list   │ agents:list
-         │             │             │
-         └─────────────┴─────────────┴────────────────────┐
-                                                           │
-┌──────────────────────────────────────────────────────────────┤
-│  APIClaw Product Whitelist                                   │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │  product-whitelist.ts                                  │  │
-│  │  - Fetch from multiple Convex sources                  │  │
-│  │  - Cache per product (5 min TTL)                       │  │
-│  │  - Namespace: product:agentId                          │  │
-│  │  - Fallback to static whitelist                        │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                               │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │  access-control.ts                                     │  │
-│  │  - Per-provider permissions                            │  │
-│  │  - Pattern matching (hivr:*, nordsym:*)                │  │
-│  │  - Deny by default                                     │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                               │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │  http-api.ts                                           │  │
-│  │  - /api/discover?agentId=hivr:bytebee                  │  │
-│  │  - POST /api/call_api { agentId, provider, ... }      │  │
-│  └────────────────────────────────────────────────────────┘  │
-└───────────────────────────────────────────────────────────────┘
-                          │
-                          │ Logs usage
-                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Analytics                                                    │
-│  - Product-level tracking                                    │
-│  - Per-agent usage                                           │
-│  - Provider access logs                                      │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Product Configuration
-
-**File:** `src/product-whitelist.ts`
-
-### Adding a New Product
-
-```typescript
-const PRODUCT_SOURCES: ProductSource[] = [
-  {
-    name: 'hivr',
-    convexUrl: 'https://sensible-quail-275.convex.cloud',
-    queryPath: 'agents:list',
-    agentIdField: 'agentId',
-  },
-  {
-    name: 'nordsym',
-    convexUrl: 'https://nordsym-deployment.convex.cloud',
-    queryPath: 'team:listAgents',
-    agentIdField: 'memberId',
-    authToken: process.env.NORDSYM_API_TOKEN, // Optional
-  },
-];
-```
-
-**Fields:**
-- `name` — Product identifier (used in namespace)
-- `convexUrl` — Convex deployment URL
-- `queryPath` — Convex query function path
-- `agentIdField` — Field name for agent identifier
-- `authToken` — Optional Bearer token for auth
-
----
-
-## Access Control Rules
-
-**File:** `src/access-control.ts`
-
-### Rule Format
-
-```typescript
-interface AccessRule {
-  agentPattern: string;      // e.g., "hivr:*", "nordsym:mollebot"
-  allowedProviders: string[]; // e.g., ["*"], ["brave_search", "groq"]
-  description?: string;
-}
-```
-
-### Default Rules
-
-```typescript
-const DEFAULT_RULES: AccessRule[] = [
-  {
-    agentPattern: 'hivr:*',
-    allowedProviders: ['*'], // All providers
-    description: 'Hivr bees get full access',
-  },
-  {
-    agentPattern: 'nordsym:*',
-    allowedProviders: ['brave_search', 'groq', 'replicate'],
-    description: 'NordSym team gets selected providers',
-  },
-];
-```
-
-### Pattern Matching
-
-- `hivr:*` — All Hivr agents
-- `hivr:bytebee` — Specific agent
-- `nordsym:molle*` — Prefix match
-
-### Provider Wildcards
-
-- `*` — All providers
-- `brave_*` — All Brave providers
-- `["brave_search", "groq"]` — Specific list
-
----
-
-## Usage Examples
-
-### HTTP API Request (Namespaced)
-
-```bash
-curl -X POST "https://apiclaw.com/api/call_api" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "agentId": "hivr:bytebee",
-    "provider": "brave_search",
-    "action": "search",
-    "params": {"query": "AI news"}
-  }'
-```
-
-### HTTP API Request (Legacy)
-
-```bash
-# Legacy format (no namespace) still works
-curl -X POST "https://apiclaw.com/api/call_api" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "agentId": "bytebee",
-    "provider": "brave_search",
-    "action": "search",
-    "params": {"query": "AI news"}
-  }'
-```
-
-### Discovery Endpoint
-
-```bash
-curl "https://apiclaw.com/api/discover?query=web+search&agentId=hivr:bytebee"
-```
-
----
-
-## Security Model
-
-### 1. Whitelist Check
-- Agent must exist in product's Convex deployment
-- Fetched dynamically (cached 5 min)
-- Fallback to static list if all sources fail
-
-### 2. Access Control
-- Per-provider permissions checked
-- Pattern-based rules (`hivr:*`, `nordsym:mollebot`)
-- Deny by default
-
-### 3. Response on Denial
-
-```json
-{
-  "error": "Access Denied",
-  "message": "Provider not in access list",
-  "hint": "Contact admin@nordsym.com for access"
-}
-```
-
----
-
-## Analytics Tracking
-
-**Product-level metrics tracked:**
-- Total calls per product
-- Per-agent usage within product
-- Provider access patterns
-- Success/error rates
-- Latency per product
-
-**Log format:**
-```jsonl
-{
-  "timestamp": "2026-03-18T16:00:00.000Z",
-  "provider": "brave_search",
-  "action": "search",
-  "type": "direct",
-  "userId": "hivr:bytebee",
-  "success": true,
-  "latencyMs": 150,
-  "metadata": {
-    "product": "hivr"
-  }
-}
-```
-
----
-
-## Cache Management
-
-### Per-Product Caching
-- Each product cached separately
-- TTL: 5 minutes
-- Parallel fetches from all sources
-
-### Manual Invalidation
-
-```typescript
-import { invalidateCache } from './product-whitelist.js';
-
-// Invalidate specific product
-invalidateCache('hivr');
-
-// Invalidate all
-invalidateCache();
-```
-
----
-
-## Error Handling
-
-### Product Source Down
-
-- Other products continue working
-- Falls back to static whitelist if ALL sources fail
-- Logs warning, no crash
-
-### Partial Failures
-
-```
-[Whitelist] hivr: Fetched 12 agents
-[Whitelist] nordsym: HTTP 500
-[Whitelist] Total agents: 12 (1 source failed)
-```
-
----
-
-## Migration Guide
-
-### From v1 (Hivr-only) to v2 (Multi-product)
-
-**Old code:**
-```typescript
-const authorized = await isAuthorized('bytebee');
-```
-
-**New code:**
-```typescript
-const authorized = await isAuthorized('hivr:bytebee');
-// OR legacy format still works
-const authorized = await isAuthorized('bytebee');
-```
-
-**Breaking changes:** None (backward compatible)
-
----
-
-## Testing
-
-### Local Test
-
-```bash
-# Start HTTP API
-npm run start:http
-
-# Test whitelisted agent
-curl "http://localhost:3000/api/discover?query=web&agentId=hivr:bytebee"
-# → 200 OK
-
-# Test unauthorized agent
-curl "http://localhost:3000/api/discover?query=web&agentId=hacker:evil"
-# → 403 Access Denied
-```
-
-### Test Access Control
-
-```bash
-# Hivr bee accessing allowed provider
-curl -X POST "http://localhost:3000/api/call_api" \
-  -d '{"agentId":"hivr:bytebee","provider":"brave_search","action":"search","params":{}}'
-# → 200 OK
-
-# NordSym accessing restricted provider (if not in allowlist)
-curl -X POST "http://localhost:3000/api/call_api" \
-  -d '{"agentId":"nordsym:bot","provider":"restricted_api","action":"call","params":{}}'
-# → 403 Provider not in access list
-```
-
----
-
-## Future Enhancements
-
-### Planned
-- [ ] Convex table for access rules (dynamic updates)
-- [ ] Webhook triggers when new agent added (instant sync)
-- [ ] Per-agent rate limits
-- [ ] Usage quotas per product
-- [ ] Admin UI for whitelist management
-
-### Possible
-- [ ] Geographic restrictions
-- [ ] Time-based access windows
-- [ ] Cost allocation per product
-- [ ] Audit logs
-
----
-
-## Troubleshooting
-
-### New agent not authorized immediately
-**Solution:** Wait 5 minutes (cache TTL) or restart APIClaw HTTP server
-
-### All agents unauthorized
-**Check:**
-1. Product source Convex URL correct?
-2. Query path returns array?
-3. agentIdField matches response structure?
-
-**Debug:**
-```bash
-# Check logs
-tail -f ~/.apiclaw/logs/api-calls.jsonl | grep whitelist
-```
-
-### Access denied despite whitelist
-**Check:**
-1. Is provider in access rules?
-2. Does pattern match agentId?
-3. Check logs for reason
-
----
-
-## Contact
-
-**Questions:** admin@nordsym.com  
-**Issues:** GitHub issues (APIClaw repo)  
-**Docs:** https://apiclaw.com/docs/whitelist
-
----
-
-**Last updated:** 2026-03-18  
-**Architecture version:** 2.0

package/api/discover.ts

@@ -1,71 +0,0 @@
-/**
- * APIClaw Discovery API - Vercel Serverless Function
- * GET /api/discover?query=...&agentId=...
- */
-
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import { isAuthorized, getProduct } from '../dist/product-whitelist.js';
-import { discoverAPIs } from '../dist/discovery.js';
-import { logAPICall } from '../dist/analytics.js';
-
-export default async function handler(
-  req: VercelRequest,
-  res: VercelResponse
-) {
-  // CORS
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Agent-Id');
-  
-  if (req.method === 'OPTIONS') {
-    return res.status(200).end();
-  }
-  
-  if (req.method !== 'GET') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-  
-  const { query, agentId, category, maxResults } = req.query;
-  
-  if (!query || typeof query !== 'string') {
-    return res.status(400).json({ error: 'Missing query parameter' });
-  }
-  
-  const agentIdStr = typeof agentId === 'string' ? agentId : undefined;
-  
-  if (!(await isAuthorized(agentIdStr))) {
-    return res.status(403).json({ 
-      error: 'Unauthorized', 
-      message: 'This endpoint is restricted. Contact admin@nordsym.com',
-    });
-  }
-  
-  const startTime = Date.now();
-  const results = discoverAPIs(query, { 
-    category: typeof category === 'string' ? category : undefined,
-    maxResults: typeof maxResults === 'string' ? parseInt(maxResults) : 5,
-  });
-  const responseTimeMs = Date.now() - startTime;
-  
-  // Log to analytics
-  const product = agentIdStr ? getProduct(agentIdStr) : null;
-  logAPICall({
-    timestamp: new Date().toISOString(),
-    provider: 'apiclaw_discovery',
-    action: 'discover',
-    type: 'open',
-    userId: agentIdStr || 'unknown',
-    success: true,
-    latencyMs: responseTimeMs,
-    metadata: product ? { product } : undefined,
-  });
-  
-  return res.status(200).json({
-    success: true,
-    query,
-    agentId: agentIdStr,
-    product,
-    results,
-    responseTimeMs,
-  });
-}

package/api/health.ts

@@ -1,20 +0,0 @@
-/**
- * APIClaw Health Check - Vercel Serverless Function
- * GET /api/health
- */
-
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-
-export default async function handler(
-  req: VercelRequest,
-  res: VercelResponse
-) {
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  
-  return res.status(200).json({
-    status: 'ok',
-    service: 'apiclaw-http-api',
-    version: '2.0.0',
-    timestamp: new Date().toISOString(),
-  });
-}

package/convex/adminActivate.d.ts

@@ -1,3 +0,0 @@
-export declare const activateWorkspace: any;
-export declare const createSessionForWorkspace: any;
-//# sourceMappingURL=adminActivate.d.ts.map

package/convex/adminActivate.js

@@ -1,47 +0,0 @@
-import { mutation } from "./_generated/server";
-import { v } from "convex/values";
-export const activateWorkspace = mutation({
-    args: { workspaceId: v.id("workspaces") },
-    handler: async (ctx, { workspaceId }) => {
-        const workspace = await ctx.db.get(workspaceId);
-        if (!workspace) {
-            return { success: false, error: "not_found" };
-        }
-        await ctx.db.patch(workspaceId, {
-            status: "active",
-            tier: "backer", // Give Hivr bees backer status
-            weeklyUsageLimit: 999999,
-            usageLimit: 999999,
-            backerUntil: new Date("2026-12-31T23:59:59Z").getTime(), // Founding Backer until end of 2026
-            updatedAt: Date.now(),
-        });
-        return { success: true };
-    },
-});
-function generateToken() {
-    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-    let result = '';
-    for (let i = 0; i < 32; i++) {
-        result += chars.charAt(Math.floor(Math.random() * chars.length));
-    }
-    return result;
-}
-export const createSessionForWorkspace = mutation({
-    args: { workspaceId: v.id("workspaces") },
-    handler: async (ctx, { workspaceId }) => {
-        const workspace = await ctx.db.get(workspaceId);
-        if (!workspace || workspace.status !== "active") {
-            return { success: false, error: "workspace_not_active" };
-        }
-        const sessionToken = "apiclaw_" + generateToken();
-        await ctx.db.insert("agentSessions", {
-            workspaceId,
-            sessionToken,
-            fingerprint: "hivr-bees",
-            lastUsedAt: Date.now(),
-            createdAt: Date.now(),
-        });
-        return { success: true, sessionToken };
-    },
-});
-//# sourceMappingURL=adminActivate.js.map

package/convex/adminStats.d.ts

@@ -1,3 +0,0 @@
-export declare const getTotalWorkspaces: any;
-export declare const listWorkspaces: any;
-//# sourceMappingURL=adminStats.d.ts.map

package/convex/adminStats.js

@@ -1,42 +0,0 @@
-import { query } from "./_generated/server";
-// Get total user/workspace count
-export const getTotalWorkspaces = query({
-    args: {},
-    handler: async (ctx) => {
-        const workspaces = await ctx.db.query("workspaces").collect();
-        const providers = await ctx.db.query("providers").collect();
-        return {
-            totalWorkspaces: workspaces.length,
-            totalProviders: providers.length,
-            activeWorkspaces: workspaces.filter(w => w.status === "active").length,
-            backers: workspaces.filter(w => w.tier === "backer").length,
-            workspaceBreakdown: {
-                free: workspaces.filter(w => w.tier === "free").length,
-                pro: workspaces.filter(w => w.tier === "pro").length,
-                enterprise: workspaces.filter(w => w.tier === "enterprise").length,
-                backer: workspaces.filter(w => w.tier === "backer").length,
-            },
-            providerBreakdown: {
-                pending: providers.filter(p => p.status === "pending").length,
-                approved: providers.filter(p => p.status === "approved").length,
-                rejected: providers.filter(p => p.status === "rejected").length,
-            }
-        };
-    },
-});
-// List all workspace emails (for inspection)
-export const listWorkspaces = query({
-    args: {},
-    handler: async (ctx) => {
-        const workspaces = await ctx.db.query("workspaces").collect();
-        return workspaces.map(w => ({
-            email: w.email,
-            status: w.status,
-            tier: w.tier,
-            usageCount: w.usageCount,
-            createdAt: w.createdAt,
-            lastActiveAt: w.lastActiveAt,
-        }));
-    },
-});
-//# sourceMappingURL=adminStats.js.map

package/convex/agents.d.ts

@@ -1,54 +0,0 @@
-/**
- * Get main agent info for a workspace
- */
-export declare const getMainAgent: any;
-/**
- * Rename the main agent
- */
-export declare const renameMainAgent: any;
-/**
- * Initialize main agent (auto-generate name and ID if not set)
- * Called on first API call
- */
-export declare const ensureMainAgent: any;
-/**
- * Get all subagents for a workspace
- */
-export declare const getSubagents: any;
-/**
- * Get stats for a specific subagent
- */
-export declare const getSubagentStats: any;
-/**
- * Rename a subagent
- */
-export declare const renameSubagent: any;
-/**
- * Track a subagent call (upsert subagent record)
- * Called when X-APIClaw-Subagent header is present
- */
-export declare const trackSubagentCall: any;
-/**
- * Pre-register a task agent (subagent)
- * Allows agents to be registered before they make their first call
- */
-export declare const registerTaskAgent: any;
-/**
- * Update AI backend for workspace or subagent
- * Called when X-APIClaw-AI-Backend header is present
- */
-export declare const updateAIBackend: any;
-/**
- * Get agent overview for workspace (main + subagents summary)
- */
-export declare const getAgentOverview: any;
-/**
- * Delete a subagent
- */
-export declare const deleteSubagent: any;
-/**
- * Update subagent stats (call count, last active)
- * Internal helper for tracking
- */
-export declare const updateSubagentStats: any;
-//# sourceMappingURL=agents.d.ts.map