claude-code-swarm 0.0.1 → 0.3.3

package/references/openhive/src/sync/middleware.ts

@@ -0,0 +1,140 @@
+/**
+ * Sync Middleware
+ *
+ * Authentication and access control for sync protocol endpoints.
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { getDatabase } from '../db/index.js';
+
+/**
+ * Verify sync token from Authorization header against known peers.
+ * Used for peer-to-peer sync protocol endpoints.
+ */
+export async function syncAuthMiddleware(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const authHeader = request.headers.authorization;
+
+  if (!authHeader) {
+    return reply.status(401).send({
+      error: 'Unauthorized',
+      message: 'Missing Authorization header. Provide a sync token.',
+    });
+  }
+
+  const [scheme, token] = authHeader.split(' ');
+  if (scheme?.toLowerCase() !== 'bearer' || !token) {
+    return reply.status(401).send({
+      error: 'Unauthorized',
+      message: 'Invalid Authorization header format. Use: Bearer <sync_token>',
+    });
+  }
+
+  const db = getDatabase();
+
+  // Look up sync token in peer configs
+  const peerConfig = db.prepare(
+    "SELECT id, name, status FROM sync_peer_configs WHERE sync_token = ? AND status IN ('active', 'pending')"
+  ).get(token) as { id: string; name: string; status: string } | undefined;
+
+  if (peerConfig) {
+    (request as Record<string, unknown>).syncPeerId = peerConfig.id;
+    (request as Record<string, unknown>).syncPeerName = peerConfig.name;
+    return;
+  }
+
+  // Also check hive_sync_peers for tokens set during handshake
+  const syncPeer = db.prepare(
+    "SELECT id, peer_swarm_id, status FROM hive_sync_peers WHERE sync_token = ? AND status IN ('active', 'backfilling')"
+  ).get(token) as { id: string; peer_swarm_id: string; status: string } | undefined;
+
+  if (syncPeer) {
+    (request as Record<string, unknown>).syncPeerId = syncPeer.id;
+    (request as Record<string, unknown>).syncPeerName = syncPeer.peer_swarm_id;
+    return;
+  }
+
+  return reply.status(401).send({
+    error: 'Unauthorized',
+    message: 'Invalid or expired sync token',
+  });
+}
+
+/**
+ * Restrict sync endpoints to Tailscale IP range (100.64.0.0/10).
+ * Configurable: can be disabled for hubless/internet mode.
+ */
+export async function meshOnlyMiddleware(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const ip = request.ip;
+
+  // Check if IP is in Tailscale CGNAT range (100.64.0.0/10)
+  if (!isTailscaleIP(ip)) {
+    return reply.status(403).send({
+      error: 'Forbidden',
+      message: 'Sync endpoints are restricted to mesh network access only',
+    });
+  }
+}
+
+function isTailscaleIP(ip: string): boolean {
+  // Tailscale uses 100.64.0.0/10 CGNAT range
+  if (ip.startsWith('100.')) {
+    const second = parseInt(ip.split('.')[1], 10);
+    return second >= 64 && second <= 127;
+  }
+  // Also allow localhost for development
+  return ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+}
+
+/** Per-peer rate limit state (GAP-7: periodic cleanup to prevent memory leak) */
+const peerRequestCounts = new Map<string, { count: number; resetAt: number }>();
+const RATE_LIMIT_WINDOW_MS = 1000; // 1 second
+const RATE_LIMIT_MAX = 100; // 100 events/second per peer
+const RATE_LIMIT_CLEANUP_INTERVAL_MS = 60_000; // Clean up stale entries every 60s
+
+// GAP-7: Periodically remove expired entries to prevent unbounded Map growth
+let rateLimitCleanupTimer: NodeJS.Timeout | null = null;
+
+function ensureRateLimitCleanup(): void {
+  if (rateLimitCleanupTimer) return;
+  rateLimitCleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of peerRequestCounts) {
+      if (now > entry.resetAt) {
+        peerRequestCounts.delete(key);
+      }
+    }
+  }, RATE_LIMIT_CLEANUP_INTERVAL_MS);
+  // Allow the process to exit even if this timer is running
+  rateLimitCleanupTimer.unref();
+}
+
+export async function syncRateLimitMiddleware(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  ensureRateLimitCleanup();
+
+  // Use authenticated peer identity if available, fall back to IP
+  const peerId = (request as Record<string, unknown>).syncPeerId as string || request.ip;
+  const now = Date.now();
+
+  let entry = peerRequestCounts.get(peerId);
+  if (!entry || now > entry.resetAt) {
+    entry = { count: 0, resetAt: now + RATE_LIMIT_WINDOW_MS };
+    peerRequestCounts.set(peerId, entry);
+  }
+
+  entry.count++;
+  if (entry.count > RATE_LIMIT_MAX) {
+    return reply.status(429).send({
+      error: 'Too Many Requests',
+      message: 'Sync rate limit exceeded',
+    });
+  }
+}

package/references/openhive/src/sync/peer-resolver.ts

@@ -0,0 +1,157 @@
+/**
+ * Peer Resolver
+ *
+ * Abstracts peer discovery sources (manual, hub, gossip).
+ */
+
+import * as peerConfigsDAL from '../db/dal/sync-peer-configs.js';
+import type { PeerResolver, SyncPeer, SyncPeerConfig, PeerSource } from './types.js';
+
+type PeerStatusCallback = (peerId: string, status: string) => void;
+
+// ── Manual Peer Resolver ────────────────────────────────────────
+
+export class ManualPeerResolver implements PeerResolver {
+  private callbacks: PeerStatusCallback[] = [];
+
+  getPeersForHive(hiveName: string): SyncPeer[] {
+    const configs = peerConfigsDAL.listPeerConfigs();
+    return configs
+      .filter(c => c.shared_hives.includes(hiveName))
+      .map(configToSyncPeer);
+  }
+
+  getAllPeers(): SyncPeer[] {
+    return peerConfigsDAL.listPeerConfigs().map(configToSyncPeer);
+  }
+
+  isPeerOnline(peerId: string): boolean {
+    const config = peerConfigsDAL.findPeerConfigById(peerId);
+    return config?.status === 'active';
+  }
+
+  onPeerStatusChange(cb: PeerStatusCallback): void {
+    this.callbacks.push(cb);
+  }
+
+  notifyStatusChange(peerId: string, status: string): void {
+    for (const cb of this.callbacks) {
+      cb(peerId, status);
+    }
+  }
+}
+
+// ── Hub Peer Resolver ───────────────────────────────────────────
+
+export class HubPeerResolver implements PeerResolver {
+  private callbacks: PeerStatusCallback[] = [];
+
+  getPeersForHive(hiveName: string): SyncPeer[] {
+    // Hub resolver reads from cached hub peers in sync_peer_configs
+    const configs = peerConfigsDAL.listPeerConfigs({ source: 'hub' });
+    return configs
+      .filter(c => c.shared_hives.includes(hiveName))
+      .map(configToSyncPeer);
+  }
+
+  getAllPeers(): SyncPeer[] {
+    return peerConfigsDAL.listPeerConfigs({ source: 'hub' }).map(configToSyncPeer);
+  }
+
+  isPeerOnline(peerId: string): boolean {
+    const config = peerConfigsDAL.findPeerConfigById(peerId);
+    return config?.status === 'active';
+  }
+
+  onPeerStatusChange(cb: PeerStatusCallback): void {
+    this.callbacks.push(cb);
+  }
+
+  /** Cache hub-discovered peers into sync_peer_configs for hub-failure resilience */
+  cachePeers(peers: Array<{ name: string; sync_endpoint: string; shared_hives: string[]; signing_key?: string | null }>): void {
+    for (const peer of peers) {
+      peerConfigsDAL.upsertPeerConfig({
+        name: peer.name,
+        sync_endpoint: peer.sync_endpoint,
+        shared_hives: peer.shared_hives,
+        signing_key: peer.signing_key,
+        is_manual: false,
+        source: 'hub',
+      });
+    }
+  }
+}
+
+// ── Composite Peer Resolver ─────────────────────────────────────
+
+export class CompositePeerResolver implements PeerResolver {
+  private callbacks: PeerStatusCallback[] = [];
+  private manualResolver: ManualPeerResolver;
+  private hubResolver: HubPeerResolver | null;
+
+  constructor(manualResolver: ManualPeerResolver, hubResolver: HubPeerResolver | null = null) {
+    this.manualResolver = manualResolver;
+    this.hubResolver = hubResolver;
+  }
+
+  /** Get peers from all sources, deduped by endpoint. Precedence: manual > hub > gossip */
+  getPeersForHive(hiveName: string): SyncPeer[] {
+    const allConfigs = peerConfigsDAL.listPeerConfigs();
+    const forHive = allConfigs.filter(c => c.shared_hives.includes(hiveName));
+    return dedupByEndpoint(forHive).map(configToSyncPeer);
+  }
+
+  getAllPeers(): SyncPeer[] {
+    const allConfigs = peerConfigsDAL.listPeerConfigs();
+    return dedupByEndpoint(allConfigs).map(configToSyncPeer);
+  }
+
+  isPeerOnline(peerId: string): boolean {
+    const config = peerConfigsDAL.findPeerConfigById(peerId);
+    return config?.status === 'active';
+  }
+
+  onPeerStatusChange(cb: PeerStatusCallback): void {
+    this.callbacks.push(cb);
+    this.manualResolver.onPeerStatusChange(cb);
+    this.hubResolver?.onPeerStatusChange(cb);
+  }
+
+  getManualResolver(): ManualPeerResolver {
+    return this.manualResolver;
+  }
+
+  getHubResolver(): HubPeerResolver | null {
+    return this.hubResolver;
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function configToSyncPeer(config: SyncPeerConfig): SyncPeer {
+  return {
+    id: config.id,
+    name: config.name,
+    sync_endpoint: config.sync_endpoint,
+    shared_hives: config.shared_hives,
+    signing_key: config.signing_key,
+    sync_token: config.sync_token,
+    status: config.status,
+    source: config.source,
+  };
+}
+
+/** Dedup configs by endpoint. Manual wins over hub, hub wins over gossip. */
+function dedupByEndpoint(configs: SyncPeerConfig[]): SyncPeerConfig[] {
+  const precedence: Record<PeerSource, number> = { manual: 0, hub: 1, gossip: 2 };
+  const byEndpoint = new Map<string, SyncPeerConfig>();
+
+  for (const config of configs) {
+    const existing = byEndpoint.get(config.sync_endpoint);
+    if (!existing || precedence[config.source] < precedence[existing.source]) {
+      byEndpoint.set(config.sync_endpoint, config);
+    }
+  }
+
+  return Array.from(byEndpoint.values());
+}

package/references/openhive/src/sync/resource-hooks.ts

@@ -0,0 +1,161 @@
+/**
+ * Resource Sync Write-Path Hooks
+ *
+ * Record sync events when resources are published/updated/unpublished/synced.
+ * Called from route handlers after standard DAL operations.
+ * Fire-and-forget — does not affect the response to the client.
+ *
+ * Unlike hive hooks (which target a specific sync group), resource events
+ * are broadcast to ALL active sync groups so every peered instance learns
+ * about the change.
+ */
+
+import { listSyncGroups } from '../db/dal/sync-groups.js';
+import { insertLocalEvent } from '../db/dal/sync-events.js';
+import { signEvent } from './crypto.js';
+import { getSyncService } from './service.js';
+import type { Agent } from '../types.js';
+import type {
+  HiveEventType,
+  AgentSnapshot,
+  SyncGroup,
+  ResourcePublishedPayload,
+  ResourceUpdatedPayload,
+  ResourceUnpublishedPayload,
+  ResourceSyncedPayload,
+} from './types.js';
+
+function getInstanceId(syncGroup: SyncGroup): string {
+  const service = getSyncService();
+  if (service) return service.getInstanceId();
+  return syncGroup.created_by_instance_id || 'unknown';
+}
+
+function agentToSnapshot(agent: Agent, instanceId: string): AgentSnapshot {
+  return {
+    instance_id: instanceId,
+    agent_id: agent.id,
+    name: agent.name,
+    avatar_url: agent.avatar_url,
+  };
+}
+
+function recordEventOnAllGroups(eventType: HiveEventType, payload: unknown): void {
+  const service = getSyncService();
+  const groups = listSyncGroups();
+
+  for (const group of groups) {
+    if (service) {
+      service.recordEvent(group.id, eventType, payload);
+    } else {
+      const instanceId = getInstanceId(group);
+      const payloadStr = JSON.stringify(payload);
+      const signature = signEvent(payloadStr, group.instance_signing_key_private);
+      insertLocalEvent({
+        sync_group_id: group.id,
+        event_type: eventType,
+        origin_instance_id: instanceId,
+        origin_ts: Date.now(),
+        payload: payloadStr,
+        signature,
+        is_local: true,
+      });
+    }
+  }
+}
+
+// ── Resource Hooks ──────────────────────────────────────────────
+
+export function onResourcePublished(
+  resource: { id: string; resource_type: string; name: string; description: string | null; git_remote_url: string; visibility: string },
+  tags: string[],
+  metadata: Record<string, unknown> | null,
+  agent: Agent,
+): void {
+  try {
+    const groups = listSyncGroups();
+    if (groups.length === 0) return;
+
+    const instanceId = getInstanceId(groups[0]);
+    const payload: ResourcePublishedPayload = {
+      resource_id: resource.id,
+      resource_type: resource.resource_type as ResourcePublishedPayload['resource_type'],
+      name: resource.name,
+      description: resource.description,
+      git_remote_url: resource.git_remote_url,
+      visibility: resource.visibility as 'shared' | 'public',
+      owner: agentToSnapshot(agent, instanceId),
+      tags,
+      metadata,
+    };
+
+    recordEventOnAllGroups('resource_published', payload);
+  } catch (err) {
+    console.error('[Sync Hook] onResourcePublished failed:', (err as Error).message);
+  }
+}
+
+export function onResourceUpdated(
+  resourceId: string,
+  fields: Partial<{ name: string; description: string; visibility: string; tags: string[]; metadata: Record<string, unknown> }>,
+  agent: Agent,
+): void {
+  try {
+    const groups = listSyncGroups();
+    if (groups.length === 0) return;
+
+    const instanceId = getInstanceId(groups[0]);
+    const payload: ResourceUpdatedPayload = {
+      resource_id: resourceId,
+      fields: fields as ResourceUpdatedPayload['fields'],
+      updated_by: agentToSnapshot(agent, instanceId),
+    };
+
+    recordEventOnAllGroups('resource_updated', payload);
+  } catch (err) {
+    console.error('[Sync Hook] onResourceUpdated failed:', (err as Error).message);
+  }
+}
+
+export function onResourceUnpublished(resourceId: string, agent: Agent): void {
+  try {
+    const groups = listSyncGroups();
+    if (groups.length === 0) return;
+
+    const instanceId = getInstanceId(groups[0]);
+    const payload: ResourceUnpublishedPayload = {
+      resource_id: resourceId,
+      unpublished_by: agentToSnapshot(agent, instanceId),
+    };
+
+    recordEventOnAllGroups('resource_unpublished', payload);
+  } catch (err) {
+    console.error('[Sync Hook] onResourceUnpublished failed:', (err as Error).message);
+  }
+}
+
+export function onResourceSynced(
+  resourceId: string,
+  commitHash: string,
+  commitMessage: string | null,
+  pusherAgentId: string,
+  filesAdded: number,
+  filesModified: number,
+  filesRemoved: number,
+): void {
+  try {
+    const payload: ResourceSyncedPayload = {
+      resource_id: resourceId,
+      commit_hash: commitHash,
+      commit_message: commitMessage,
+      pusher_agent_id: pusherAgentId,
+      files_added: filesAdded,
+      files_modified: filesModified,
+      files_removed: filesRemoved,
+    };
+
+    recordEventOnAllGroups('resource_synced', payload);
+  } catch (err) {
+    console.error('[Sync Hook] onResourceSynced failed:', (err as Error).message);
+  }
+}

package/references/openhive/src/sync/schema.ts

@@ -0,0 +1,158 @@
+/**
+ * Hive Sync Database Schema
+ *
+ * Migration schemas for cross-instance hive synchronization.
+ */
+
+// Version 12: Remote agent cache + origin tracking columns
+export const SYNC_SCHEMA_V12 = `
+-- Remote agent display cache (lightweight, no auth, no local API key)
+CREATE TABLE IF NOT EXISTS remote_agents_cache (
+  id TEXT PRIMARY KEY,
+  origin_instance_id TEXT NOT NULL,
+  origin_agent_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  avatar_url TEXT,
+  last_seen_at TEXT DEFAULT (datetime('now')),
+  UNIQUE(origin_instance_id, origin_agent_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_remote_agents_origin
+  ON remote_agents_cache(origin_instance_id);
+
+-- Posts: origin tracking
+ALTER TABLE posts ADD COLUMN sync_event_id TEXT;
+ALTER TABLE posts ADD COLUMN origin_instance_id TEXT;
+ALTER TABLE posts ADD COLUMN origin_post_id TEXT;
+ALTER TABLE posts ADD COLUMN remote_author_id TEXT
+  REFERENCES remote_agents_cache(id);
+
+-- Comments: origin tracking
+ALTER TABLE comments ADD COLUMN sync_event_id TEXT;
+ALTER TABLE comments ADD COLUMN origin_instance_id TEXT;
+ALTER TABLE comments ADD COLUMN origin_comment_id TEXT;
+ALTER TABLE comments ADD COLUMN remote_author_id TEXT
+  REFERENCES remote_agents_cache(id);
+
+-- Votes: origin tracking
+ALTER TABLE votes ADD COLUMN sync_event_id TEXT;
+ALTER TABLE votes ADD COLUMN origin_instance_id TEXT;
+
+-- Dedup indexes for synced content
+CREATE UNIQUE INDEX IF NOT EXISTS idx_posts_origin
+  ON posts(origin_instance_id, origin_post_id) WHERE origin_instance_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_comments_origin
+  ON comments(origin_instance_id, origin_comment_id) WHERE origin_instance_id IS NOT NULL;
+`;
+
+// Version 13: Sync groups, peers, events, pending queue
+export const SYNC_SCHEMA_V13 = `
+-- Hive sync groups (sync identity for a hive across instances)
+CREATE TABLE IF NOT EXISTS hive_sync_groups (
+  id TEXT PRIMARY KEY,
+  hive_id TEXT NOT NULL REFERENCES hives(id) ON DELETE CASCADE,
+  sync_group_name TEXT NOT NULL,
+  created_by_instance_id TEXT,
+  instance_signing_key TEXT NOT NULL,
+  instance_signing_key_private TEXT NOT NULL,
+  seq INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now')),
+  UNIQUE(hive_id),
+  UNIQUE(sync_group_name)
+);
+
+-- Peer sync state
+CREATE TABLE IF NOT EXISTS hive_sync_peers (
+  id TEXT PRIMARY KEY,
+  sync_group_id TEXT NOT NULL REFERENCES hive_sync_groups(id) ON DELETE CASCADE,
+  peer_swarm_id TEXT NOT NULL,
+  peer_endpoint TEXT NOT NULL,
+  peer_signing_key TEXT,
+  sync_token TEXT,
+  last_seq_sent INTEGER DEFAULT 0,
+  last_seq_received INTEGER DEFAULT 0,
+  last_sync_at TEXT,
+  status TEXT DEFAULT 'active'
+    CHECK (status IN ('active', 'paused', 'error', 'backfilling')),
+  last_error TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  UNIQUE(sync_group_id, peer_swarm_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hive_sync_peers_group ON hive_sync_peers(sync_group_id);
+CREATE INDEX IF NOT EXISTS idx_hive_sync_peers_status ON hive_sync_peers(status);
+
+-- Append-only event log
+CREATE TABLE IF NOT EXISTS hive_events (
+  id TEXT PRIMARY KEY,
+  sync_group_id TEXT NOT NULL REFERENCES hive_sync_groups(id) ON DELETE CASCADE,
+  seq INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  origin_instance_id TEXT NOT NULL,
+  origin_ts INTEGER NOT NULL,
+  payload TEXT NOT NULL,
+  signature TEXT NOT NULL,
+  received_at TEXT DEFAULT (datetime('now')),
+  is_local INTEGER DEFAULT 0,
+  UNIQUE(sync_group_id, seq)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hive_events_group_seq ON hive_events(sync_group_id, seq);
+CREATE INDEX IF NOT EXISTS idx_hive_events_type ON hive_events(sync_group_id, event_type);
+CREATE INDEX IF NOT EXISTS idx_hive_events_origin ON hive_events(origin_instance_id);
+CREATE INDEX IF NOT EXISTS idx_hive_events_origin_ts ON hive_events(origin_ts);
+
+-- Causal ordering queue (events waiting on dependencies)
+CREATE TABLE IF NOT EXISTS hive_events_pending (
+  id TEXT PRIMARY KEY,
+  sync_group_id TEXT NOT NULL,
+  event_json TEXT NOT NULL,
+  depends_on TEXT NOT NULL,
+  received_at TEXT DEFAULT (datetime('now'))
+);
+`;
+
+// Version 14: Manual/cached peer configs
+export const SYNC_SCHEMA_V14 = `
+-- Manual/cached peer configs
+CREATE TABLE IF NOT EXISTS sync_peer_configs (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  sync_endpoint TEXT NOT NULL,
+  shared_hives TEXT NOT NULL,
+  signing_key TEXT,
+  sync_token TEXT,
+  is_manual INTEGER DEFAULT 1,
+  source TEXT DEFAULT 'manual'
+    CHECK (source IN ('manual', 'hub', 'gossip')),
+  status TEXT DEFAULT 'pending'
+    CHECK (status IN ('pending', 'active', 'error', 'unreachable')),
+  last_heartbeat_at TEXT,
+  last_error TEXT,
+  gossip_ttl INTEGER DEFAULT 0,
+  failure_count INTEGER DEFAULT 0,
+  discovered_via TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  UNIQUE(sync_endpoint)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_peer_configs_status ON sync_peer_configs(status);
+CREATE INDEX IF NOT EXISTS idx_sync_peer_configs_source ON sync_peer_configs(source);
+`;
+
+// Version 15: Key rotation support — versioned signing keys
+export const SYNC_SCHEMA_V15 = `
+-- Add key version tracking to sync groups
+ALTER TABLE hive_sync_groups ADD COLUMN key_version INTEGER DEFAULT 1;
+ALTER TABLE hive_sync_groups ADD COLUMN previous_signing_key TEXT;
+ALTER TABLE hive_sync_groups ADD COLUMN previous_signing_key_private TEXT;
+ALTER TABLE hive_sync_groups ADD COLUMN key_rotated_at TEXT;
+
+-- Add key version to events for multi-key verification during transition
+ALTER TABLE hive_events ADD COLUMN key_version INTEGER DEFAULT 1;
+
+-- Add key version to peer state for tracking which key version a peer knows about
+ALTER TABLE hive_sync_peers ADD COLUMN peer_key_version INTEGER DEFAULT 1;
+`;