@nordsym/apiclaw 1.5.9 → 1.5.10

package/HIVR-WHITELIST-STATUS.md

@@ -0,0 +1,205 @@
+# Hivr Whitelist - Status & Verification
+
+**Date:** 2026-03-19
+**Issue:** Whitelist checking wrong field, no account attribution
+
+---
+
+## ✅ What I Fixed
+
+### 1. Hivr Whitelist — Field Name Mismatch
+
+**Problem:** Both whitelist files were looking for `agentId` field, but Hivr agents have `handle`
+
+**Files Fixed:**
+- `src/hivr-whitelist.ts` — Line 60: `a.agentId` → `a.handle`
+- `src/product-whitelist.ts` — Line 15: `agentIdField: 'agentId'` → `agentIdField: 'handle'`
+
+**Result:** Whitelist will now correctly extract bee handles from Hivr Convex
+
+---
+
+## ⚠️ What's Missing: Account Attribution
+
+**Your expectation:** All Hivr bee requests counted under `gustav@nordsym.com`
+
+**Current reality:** Requests logged only by bee handle (`bytebee`, `elderbee`, etc.)
+
+**Where tracking happens:**
+```typescript
+// src/http-api.ts line ~94
+logAPICall({
+  userId: agentId || 'unknown',  // Just the bee handle, no account email
+  // ...
+});
+```
+
+**No account/email field exists in the current system.**
+
+---
+
+## 🔍 Verification Steps
+
+### 1. Check Whitelist Works
+
+**Start APIClaw HTTP server:**
+```bash
+cd ~/Projects/apiclaw
+npm run start:http
+```
+
+**Expected log:**
+```
+[Hivr Whitelist] Fetched 12 agents from Hivr
+```
+
+**Test authorization:**
+```bash
+# Should return 200 (authorized)
+curl "http://localhost:3000/api/discover?query=web&agentId=elderbee"
+
+# Should return 403 (unauthorized)
+curl "http://localhost:3000/api/discover?query=web&agentId=fakeagent"
+```
+
+### 2. Check Which Bees Are Whitelisted
+
+**In APIClaw console (when server running):**
+```typescript
+import { getWhitelist } from './hivr-whitelist.js';
+const bees = await getWhitelist();
+console.log(bees); // Should list all Hivr bee handles
+```
+
+---
+
+## 📊 Account Attribution (NOT Implemented)
+
+**If you want gustav@nordsym.com attribution:**
+
+### Option A: Product Namespace (Already in place)
+
+Current system namespaces as `hivr:bytebee`, `hivr:elderbee`
+
+You can group by product:
+```typescript
+// In analytics
+const hivrRequests = logs.filter(log => log.userId.startsWith('hivr:'));
+const nordsymRequests = logs.filter(log => log.userId.startsWith('nordsym:'));
+```
+
+**Pros:** Works now with the fix
+**Cons:** Still no email/account tracking
+
+### Option B: Add Account Field (Requires Implementation)
+
+**Change needed:**
+```typescript
+// src/http-api.ts
+logAPICall({
+  userId: agentId,
+  accountEmail: 'gustav@nordsym.com',  // ← Add this
+  product: getProduct(agentId),        // Already exists
+  // ...
+});
+```
+
+**Pros:** Clear separation NordSym vs Hivr
+**Cons:** Requires code changes + analytics schema update
+
+### Option C: Convex Metadata (Clean Approach)
+
+**Store account mapping in Convex:**
+```typescript
+// apiclawProviders table (already exists!)
+{
+  agentId: "elderbee",
+  slug: "hivr-elderbee",
+  accountEmail: "gustav@nordsym.com",  // ← Add this field
+}
+```
+
+**Then in APIClaw:**
+```typescript
+const provider = await getProviderByAgent(agentId);
+logAPICall({
+  userId: agentId,
+  accountEmail: provider?.accountEmail,
+  // ...
+});
+```
+
+**Pros:** Clean, uses existing infrastructure
+**Cons:** Requires schema update + backfill
+
+---
+
+## 🎯 Recommendation
+
+**Immediate (today):**
+1. ✅ Field fix deployed (handle instead of agentId)
+2. Restart APIClaw HTTP server to apply
+3. Verify whitelist works (see steps above)
+
+**Short-term (if account attribution needed):**
+- Option C (Convex metadata) is cleanest
+- Add `accountEmail` to `apiclawProviders` table
+- Update HTTP API to include it in logs
+- **This aligns with the provider registration work already started**
+
+---
+
+## 📝 Current Whitelist Status
+
+**Bees expected to be whitelisted after fix:**
+- hivrqueen
+- elderbee
+- hivemind
+- hivesage_hivr_bot
+- buzzwriter
+- analyzerbee
+- buildbee
+- bytebee
+- reconbee
+- sprintbee
+- quillbee
+- marketmaven
+
+**Total:** 12 bees (all active Hivr agents)
+
+---
+
+**Created:** 2026-03-19 12:20 CET  
+**Updated:** 2026-03-19 12:26 CET  
+**Status:** ✅ VERIFIED WORKING — All Hivr bees whitelisted  
+**Server:** Running on localhost:3001
+
+---
+
+## ✅ Verification Complete (2026-03-19 12:26)
+
+**Issues Fixed:**
+1. Field name: `agentId` → `handle` ✓
+2. Convex HTTP response parsing: Access `.value` field ✓
+
+**Whitelist Status:** 14 Hivr bees successfully fetched and authorized
+
+**Tested Bees (all authorized ✓):**
+- bytebee
+- elderbee  
+- hivrqueen
+- symbot
+- marketmaven
+- reconbee
+- HiveMind_Hivr_bot
+- AnalyzerBee_Hivr_bot
+- Buzzwriter_Hivr_bot
+- BuildBee_Hivr_bot
+- HiveSage_Hivr_bot
+- OutreachBee_Hivr_bot
+- quillbee
+- sprintbee
+
+**Authorization Test:** Fake agents correctly blocked ✓
+
+**Next:** Account attribution (gustav@nordsym.com) — see Option C above

package/HIVR-WHITELIST.md

@@ -0,0 +1,148 @@
+# Hivr Auto-Whitelist System
+
+**Problem:** Manually updating hardcoded whitelist every time new bee is added = fragile + easy to forget.
+
+**Solution:** APIClaw dynamically fetches active agents from Hivr's Convex deployment.
+
+---
+
+## How It Works
+
+1. **Hivr Convex Deployment:** `sensible-quail-275` (PROD)
+2. **APIClaw queries:** `agents:list` from Hivr
+3. **Cache:** 5 minutes (performance)
+4. **Fallback:** Static whitelist if Convex unreachable
+
+---
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `src/hivr-whitelist.ts` | Dynamic whitelist module |
+| `src/http-api.ts` | Uses `isAuthorized()` from hivr-whitelist |
+
+---
+
+## Usage
+
+### In Code
+```typescript
+import { isAuthorized, invalidateCache } from './hivr-whitelist.js';
+
+// Check if agent is whitelisted
+const authorized = await isAuthorized('bytebee'); // true
+
+// Force refresh (after adding new bee)
+invalidateCache();
+```
+
+### Adding New Bee (Automatic!)
+1. Add agent in Hivr (hivr.online admin)
+2. APIClaw will auto-discover within 5 minutes
+3. **No code changes needed!**
+
+---
+
+## Manual Override (Emergency)
+
+If Hivr Convex is down, edit static fallback:
+
+**File:** `src/hivr-whitelist.ts`  
+**Line:** 10-23
+
+```typescript
+const STATIC_WHITELIST = [
+  'bytebee',
+  'symbot',
+  // Add emergency agents here
+];
+```
+
+Then rebuild:
+```bash
+npm run build
+```
+
+---
+
+## Testing
+
+### Local Test
+```bash
+# Start APIClaw HTTP API
+npm run start:http
+
+# Test authorization
+curl "http://localhost:3000/api/discover?query=web&agentId=bytebee"
+# Should return 200 (authorized)
+
+curl "http://localhost:3000/api/discover?query=web&agentId=unauthorized"
+# Should return 403 (unauthorized)
+```
+
+### Check Whitelist Cache
+APIClaw logs when fetching whitelist:
+```
+[Hivr Whitelist] Fetched 12 agents from Hivr
+```
+
+---
+
+## Troubleshooting
+
+**Problem:** New bee not authorized immediately  
+**Solution:** Wait 5 minutes (cache) or restart APIClaw server
+
+**Problem:** "Failed to fetch from Hivr Convex"  
+**Solution:** Check Hivr Convex URL in `hivr-whitelist.ts`, fallback to static
+
+**Problem:** All bees unauthorized  
+**Solution:** Check Hivr agents table has `agentId` field
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Hivr.online (sensible-quail-275)           │
+│  ┌───────────────────────────────────────┐  │
+│  │  agents table                         │  │
+│  │  { agentId: "bytebee", ... }          │  │
+│  └───────────────────────────────────────┘  │
+└─────────────────────────────────────────────┘
+                    ▲
+                    │ Query agents:list
+                    │ (every 5 min)
+                    │
+┌─────────────────────────────────────────────┐
+│  APIClaw HTTP API                           │
+│  ┌───────────────────────────────────────┐  │
+│  │  hivr-whitelist.ts                    │  │
+│  │  - Cached whitelist                   │  │
+│  │  - Auto-refresh every 5 min           │  │
+│  │  - Fallback to static list            │  │
+│  └───────────────────────────────────────┘  │
+│                    │                         │
+│  ┌───────────────────────────────────────┐  │
+│  │  http-api.ts                          │  │
+│  │  - /api/discover                      │  │
+│  │  - /api/call_api                      │  │
+│  │  - Calls isAuthorized(agentId)        │  │
+│  └───────────────────────────────────────┘  │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Future Improvements
+
+- [ ] Webhook from Hivr when new agent added (instant refresh)
+- [ ] Admin endpoint to manually refresh: `GET /api/admin/refresh-whitelist`
+- [ ] Whitelist per-API (some bees only get certain providers)
+- [ ] Usage quotas per bee (track in Convex)
+
+---
+
+**TL;DR:** Add agent in Hivr → APIClaw auto-whitelists within 5 min. Zero manual code changes.