@nordsym/apiclaw 1.5.16 → 1.5.18

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/direct-test.mjs

@@ -1,51 +0,0 @@
-import { executeAPICall } from './dist/execute.js';
-
-const tests = [
-  'exchange_rates', 'market_data', 'aviation', 'pdf_generate',
-  'screenshot', 'verify_email', 'verify_number', 'vat_check',
-  'world_news', 'finance_news', 'scrape', 'image_crop',
-  'skills', 'form_submit'
-];
-
-const params = {
-  exchange_rates: { base: 'USD', symbols: 'EUR' },
-  market_data: { symbols: 'AAPL' },
-  aviation: { flight_iata: 'AA100' },
-  pdf_generate: { document_url: 'https://example.com' },
-  screenshot: { url: 'https://example.com' },
-  verify_email: { email: 'test@example.com' },
-  verify_number: { number: '+14158586273' },
-  vat_check: { vat_number: 'LU26375245' },
-  world_news: { url: 'https://example.com/news' },
-  finance_news: { tickers: 'AAPL' },
-  scrape: { url: 'https://example.com' },
-  image_crop: { url: 'https://example.com/img.jpg', width: '200' },
-  skills: { q: 'javascript' },
-  form_submit: { endpoint: 'test', data: {} }
-};
-
-let working = 0, blocked = 0;
-
-console.log('🔬 Testing all 14 APILayer services...\n');
-
-for (const action of tests) {
-  try {
-    const result = await executeAPICall('apilayer', action, params[action]);
-    
-    if (result.success) {
-      console.log(`✅ ${action}`);
-      working++;
-    } else {
-      const errMsg = result.error || result.message || 'Failed';
-      console.log(`❌ ${action}: ${errMsg.substring(0, 60)}`);
-      blocked++;
-    }
-  } catch (e) {
-    console.log(`❌ ${action}: ${e.message.substring(0, 60)}`);
-    blocked++;
-  }
-}
-
-console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-console.log(`📊 FAKTISKA SIFFROR: ${working}/14 working, ${blocked}/14 blocked`);
-console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);

package/dist/access-control.d.ts

@@ -1,45 +0,0 @@
-/**
- * Access Control System
- * Controls which products/agents can access which providers
- *
- * Rules format:
- * - Wildcard: "hivr:*" = all Hivr agents
- * - Specific: "hivr:bytebee" = only ByteBee
- * - Product-level: "nordsym:*" = all NordSym agents
- *
- * Provider wildcards:
- * - "*" = all providers
- * - "brave_*" = all Brave providers
- * - Specific: ["brave_search", "groq"]
- */
-interface AccessRule {
-    agentPattern: string;
-    allowedProviders: string[];
-    description?: string;
-}
-/**
- * Check if agentId is allowed to access provider
- */
-export declare function canAccessProvider(agentId: string, provider: string): boolean;
-/**
- * Get allowed providers for agentId
- */
-export declare function getAllowedProviders(agentId: string): string[];
-/**
- * Add new access rule (runtime)
- */
-export declare function addAccessRule(rule: AccessRule): void;
-/**
- * Get all access rules (for debugging/admin)
- */
-export declare function getAccessRules(): AccessRule[];
-/**
- * Check if agentId + provider combination is allowed
- * Combines whitelist check + access control
- */
-export declare function isAllowed(agentId: string | undefined, provider: string): Promise<{
-    allowed: boolean;
-    reason?: string;
-}>;
-export {};
-//# sourceMappingURL=access-control.d.ts.map

package/dist/access-control.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../src/access-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,UAAU,UAAU;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA4DD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAyB5E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAe7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAIpD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAE7C;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBhD"}