@johpaz/hive-sdk 0.0.14 → 0.0.16

package/packages/core/src/scheduler/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Hive Scheduler - Type Definitions
+ * 
+ * Type interfaces for the Croner-based scheduling system.
+ * All names use "CronJob" terminology (formerly ScheduledTask).
+ */
+
+import type { Database } from "bun:sqlite";
+import type { Cron } from "croner";
+
+/**
+ * Task type: recurring uses cron expression, one_shot uses fire_at
+ */
+export type TaskType = "recurring" | "one_shot";
+
+/**
+ * Task status
+ */
+export type TaskStatus = "active" | "paused" | "completed" | "failed" | "cancelled";
+
+/**
+ * Task run status
+ */
+export type TaskRunStatus = "running" | "success" | "failed" | "timeout";
+
+/**
+ * CronJob as stored in SQLite (cron_jobs table)
+ */
+export interface CronJob {
+  id: string;
+  name: string;
+  task: string;
+  task_type: TaskType;
+  cron_expression: string | null;
+  fire_at: string | null;
+  timezone: string;
+  start_at: string | null;
+  stop_at: string | null;
+  dom_and_dow: number;
+  max_runs: number | null;
+  protect: number;
+  interval_sec: number | null;
+  agent_id: string | null;
+  channel: string;
+  payload: string;
+  tool_name: string | null;
+  status: TaskStatus;
+  run_count: number;
+  error_count: number;
+  last_error: string | null;
+  created_at: string;
+  updated_at: string;
+  last_run_at: string | null;
+  next_run_at: string | null;
+  completed_at: string | null;
+}
+
+/**
+ * Task run history record
+ */
+export interface TaskRun {
+  id: string;
+  task_id: string;
+  status: TaskRunStatus;
+  started_at: string;
+  finished_at: string | null;
+  duration_ms: number | null;
+  error_message: string | null;
+  payload_snapshot: string | null;
+  agent_response: string | null;
+}
+
+/**
+ * Input for creating a new cron job
+ */
+export interface CreateCronJobInput {
+  name: string;
+  task: string;
+  task_type: TaskType;
+  cron_expression?: string;
+  fire_at?: string;
+  timezone: string;
+  start_at?: string;
+  stop_at?: string;
+  dom_and_dow?: boolean;
+  agent_id?: string | null;
+  channel?: string;
+  payload?: Record<string, unknown>;
+  tool_name?: string | null;
+  max_runs?: number | null;
+  protect?: boolean;
+  interval_sec?: number | null;
+}
+
+/**
+ * Input for updating an existing cron job
+ */
+export interface UpdateCronJobInput {
+  name?: string;
+  task?: string;
+  task_type?: TaskType;
+  cron_expression?: string | null;
+  fire_at?: string | null;
+  timezone?: string;
+  start_at?: string | null;
+  stop_at?: string | null;
+  dom_and_dow?: boolean;
+  agent_id?: string | null;
+  channel?: string;
+  payload?: Record<string, unknown>;
+  tool_name?: string | null;
+  max_runs?: number | null;
+  protect?: boolean;
+  interval_sec?: number | null;
+  status?: TaskStatus;
+}
+
+/**
+ * Scheduler status for a cron job
+ */
+export interface CronJobStatus {
+  id: string;
+  name: string;
+  nextRun: Date | null;
+  isBusy: boolean;
+  status: TaskStatus;
+}
+
+/**
+ * Handler function type for executing cron jobs
+ */
+export type CronJobExecutionHandler = (job: CronJob) => Promise<CronJobExecutionResult>;
+
+/**
+ * Result of cron job execution
+ */
+export interface CronJobExecutionResult {
+  success: boolean;
+  response?: string;
+  error?: string;
+}
+
+/**
+ * Internal job wrapper holding Croner instance and metadata
+ */
+export interface CronJobEntry {
+  job: CronJob;
+  cron: Cron;
+}
+
+/**
+ * Options for Croner job creation
+ */
+export interface CronerOptions {
+  timezone: string;
+  protect: boolean;
+  catch: boolean | ((error: Error) => void);
+  name: string;
+  maxRuns?: number;
+  interval?: number;
+  startAt?: string;
+  stopAt?: string;
+  domAndDow?: boolean;
+}

package/packages/core/src/security/Pairing.ts

@@ -0,0 +1,250 @@
+import crypto from "crypto";
+import { eventBus } from "../swarm/EventBus.ts";
+import { logger } from "../utils/logger.ts";
+
+export interface PairingCode {
+  code: string;
+  channel: string;
+  userId: string;
+  createdAt: number;
+  expiresAt: number;
+  attempts: number;
+}
+
+export interface PairingConfig {
+  codeLength?: number;
+  expirationMs?: number;
+  maxAttempts?: number;
+}
+
+export interface PairingStats {
+  pendingCodes: number;
+  totalAllowlist: number;
+  byChannel: Record<string, { pending: number; allowed: number }>;
+}
+
+export class PairingService {
+  private codes: Map<string, PairingCode> = new Map();
+  private allowlist: Map<string, Set<string>> = new Map();
+  private config: Required<PairingConfig>;
+  private log = logger.child("pairing");
+
+  constructor(config: PairingConfig = {}) {
+    this.config = {
+      codeLength: config.codeLength ?? 8,
+      expirationMs: config.expirationMs ?? 10 * 60 * 1000,
+      maxAttempts: config.maxAttempts ?? 3,
+    };
+
+    this.startCleanup();
+  }
+
+  generateCode(channel: string, userId: string): string {
+    this.cleanup();
+
+    const code = this.generateSecureCode();
+    const now = Date.now();
+
+    const record: PairingCode = {
+      code,
+      channel,
+      userId,
+      createdAt: now,
+      expiresAt: now + this.config.expirationMs,
+      attempts: 0,
+    };
+
+    this.codes.set(code, record);
+
+    this.log.info(`Generated pairing code for ${channel}:${userId}`);
+
+    eventBus.emit("pairing:requested", {
+      channel,
+      userId,
+      code,
+      expiresAt: record.expiresAt,
+    });
+
+    return code;
+  }
+
+  validateCode(code: string): PairingCode | null {
+    const record = this.codes.get(code);
+    if (!record) return null;
+
+    if (Date.now() > record.expiresAt) {
+      this.codes.delete(code);
+      eventBus.emit("pairing:expired", {
+        code,
+        channel: record.channel,
+        userId: record.userId,
+      });
+      return null;
+    }
+
+    return record;
+  }
+
+  approve(code: string): { success: boolean; error?: string } {
+    const record = this.validateCode(code);
+    if (!record) {
+      return { success: false, error: "Invalid or expired code" };
+    }
+
+    if (!this.allowlist.has(record.channel)) {
+      this.allowlist.set(record.channel, new Set());
+    }
+    this.allowlist.get(record.channel)!.add(record.userId);
+
+    this.codes.delete(code);
+
+    this.log.info(`Approved pairing for ${record.channel}:${record.userId}`);
+
+    eventBus.emit("pairing:approved", {
+      channel: record.channel,
+      userId: record.userId,
+    });
+
+    return { success: true };
+  }
+
+  reject(code: string, reason: string): boolean {
+    const record = this.codes.get(code);
+    if (!record) return false;
+
+    this.codes.delete(code);
+
+    this.log.info(`Rejected pairing for ${record.channel}:${record.userId}: ${reason}`);
+
+    eventBus.emit("pairing:rejected", {
+      channel: record.channel,
+      userId: record.userId,
+      reason,
+    });
+
+    return true;
+  }
+
+  attempt(code: string): boolean {
+    const record = this.codes.get(code);
+    if (!record) return false;
+
+    record.attempts++;
+
+    if (record.attempts >= this.config.maxAttempts) {
+      this.codes.delete(code);
+      this.log.warn(`Code ${code} exhausted attempts`);
+      return false;
+    }
+
+    return true;
+  }
+
+  isAllowed(channel: string, userId: string): boolean {
+    const channelAllowlist = this.allowlist.get(channel);
+    return channelAllowlist?.has(userId) ?? false;
+  }
+
+  removeFromAllowlist(channel: string, userId: string): boolean {
+    const channelAllowlist = this.allowlist.get(channel);
+    if (!channelAllowlist) return false;
+
+    const removed = channelAllowlist.delete(userId);
+
+    if (channelAllowlist.size === 0) {
+      this.allowlist.delete(channel);
+    }
+
+    if (removed) {
+      this.log.info(`Removed ${userId} from allowlist for ${channel}`);
+    }
+
+    return removed;
+  }
+
+  listAllowed(channel?: string): { channel: string; userId: string }[] {
+    const result: { channel: string; userId: string }[] = [];
+
+    if (channel) {
+      const channelAllowlist = this.allowlist.get(channel);
+      if (channelAllowlist) {
+        for (const userId of channelAllowlist) {
+          result.push({ channel, userId });
+        }
+      }
+    } else {
+      for (const [ch, users] of this.allowlist) {
+        for (const userId of users) {
+          result.push({ channel: ch, userId });
+        }
+      }
+    }
+
+    return result;
+  }
+
+  listPending(): PairingCode[] {
+    this.cleanup();
+    return Array.from(this.codes.values());
+  }
+
+  getStats(): PairingStats {
+    const byChannel: Record<string, { pending: number; allowed: number }> = {};
+
+    for (const [channel, users] of this.allowlist) {
+      byChannel[channel] = {
+        pending: 0,
+        allowed: users.size,
+      };
+    }
+
+    for (const record of this.codes.values()) {
+      if (!byChannel[record.channel]) {
+        byChannel[record.channel] = { pending: 0, allowed: 0 };
+      }
+      byChannel[record.channel]!.pending++;
+    }
+
+    return {
+      pendingCodes: this.codes.size,
+      totalAllowlist: Array.from(this.allowlist.values()).reduce(
+        (sum, set) => sum + set.size,
+        0
+      ),
+      byChannel,
+    };
+  }
+
+  clear(): void {
+    this.codes.clear();
+    this.allowlist.clear();
+    this.log.info("All pairing data cleared");
+  }
+
+  private generateSecureCode(): string {
+    const bytes = crypto.randomBytes(Math.ceil(this.config.codeLength / 2));
+    return bytes.toString("hex").toUpperCase().slice(0, this.config.codeLength);
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [code, record] of this.codes) {
+      if (now > record.expiresAt) {
+        this.codes.delete(code);
+        eventBus.emit("pairing:expired", {
+          code,
+          channel: record.channel,
+          userId: record.userId,
+        });
+      }
+    }
+  }
+
+  private startCleanup(): void {
+    setInterval(() => {
+      this.cleanup();
+    }, 60 * 1000);
+  }
+}
+
+export const pairingService = new PairingService();

package/packages/core/src/security/RateLimit.ts

@@ -0,0 +1,270 @@
+import { logger } from "../utils/logger.ts";
+
+export interface TokenBucketConfig {
+  maxTokens: number;
+  refillRate: number;
+  refillIntervalMs?: number;
+}
+
+export interface TokenBucket {
+  tokens: number;
+  lastUpdate: number;
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  retryAfterMs: number;
+}
+
+export interface TokenBucketStats {
+  totalBuckets: number;
+  activeBuckets: number;
+  totalTokensAvailable: number;
+}
+
+export class TokenBucketRateLimiter {
+  private buckets: Map<string, TokenBucket> = new Map();
+  private config: Required<TokenBucketConfig>;
+  private log = logger.child("token-bucket-limiter");
+
+  constructor(config: TokenBucketConfig) {
+    this.config = {
+      maxTokens: config.maxTokens,
+      refillRate: config.refillRate,
+      refillIntervalMs: config.refillIntervalMs ?? 1000,
+    };
+
+    this.startCleanup();
+  }
+
+  canProceed(key: string): RateLimitResult {
+    const now = Date.now();
+    let bucket = this.buckets.get(key);
+
+    if (!bucket) {
+      bucket = {
+        tokens: this.config.maxTokens,
+        lastUpdate: now,
+      };
+      this.buckets.set(key, bucket);
+    }
+
+    const elapsed = now - bucket.lastUpdate;
+    const tokensToAdd = (elapsed / this.config.refillIntervalMs) * this.config.refillRate;
+    bucket.tokens = Math.min(this.config.maxTokens, bucket.tokens + tokensToAdd);
+    bucket.lastUpdate = now;
+
+    if (bucket.tokens >= 1) {
+      bucket.tokens--;
+      return {
+        allowed: true,
+        remaining: Math.floor(bucket.tokens),
+        retryAfterMs: 0,
+      };
+    }
+
+    const retryAfterMs = Math.ceil(
+      ((1 - bucket.tokens) / this.config.refillRate) * this.config.refillIntervalMs
+    );
+
+    this.log.debug(`Rate limit hit for ${key}, retry after ${retryAfterMs}ms`);
+
+    return {
+      allowed: false,
+      remaining: 0,
+      retryAfterMs,
+    };
+  }
+
+  consume(key: string, tokens: number = 1): RateLimitResult {
+    const now = Date.now();
+    let bucket = this.buckets.get(key);
+
+    if (!bucket) {
+      bucket = {
+        tokens: this.config.maxTokens,
+        lastUpdate: now,
+      };
+      this.buckets.set(key, bucket);
+    }
+
+    const elapsed = now - bucket.lastUpdate;
+    const tokensToAdd = (elapsed / this.config.refillIntervalMs) * this.config.refillRate;
+    bucket.tokens = Math.min(this.config.maxTokens, bucket.tokens + tokensToAdd);
+    bucket.lastUpdate = now;
+
+    if (bucket.tokens >= tokens) {
+      bucket.tokens -= tokens;
+      return {
+        allowed: true,
+        remaining: Math.floor(bucket.tokens),
+        retryAfterMs: 0,
+      };
+    }
+
+    const retryAfterMs = Math.ceil(
+      ((tokens - bucket.tokens) / this.config.refillRate) * this.config.refillIntervalMs
+    );
+
+    return {
+      allowed: false,
+      remaining: 0,
+      retryAfterMs,
+    };
+  }
+
+  peek(key: string): number {
+    const bucket = this.buckets.get(key);
+    if (!bucket) return this.config.maxTokens;
+
+    const now = Date.now();
+    const elapsed = now - bucket.lastUpdate;
+    const tokensToAdd = (elapsed / this.config.refillIntervalMs) * this.config.refillRate;
+
+    return Math.min(this.config.maxTokens, bucket.tokens + tokensToAdd);
+  }
+
+  refill(key: string, tokens?: number): void {
+    const bucket = this.buckets.get(key);
+    if (!bucket) return;
+
+    bucket.tokens = Math.min(
+      this.config.maxTokens,
+      bucket.tokens + (tokens ?? this.config.maxTokens)
+    );
+  }
+
+  reset(key: string): void {
+    this.buckets.delete(key);
+  }
+
+  resetAll(): void {
+    this.buckets.clear();
+    this.log.info("All rate limit buckets cleared");
+  }
+
+  getStats(): TokenBucketStats {
+    let totalTokens = 0;
+    let activeBuckets = 0;
+    const now = Date.now();
+
+    for (const bucket of this.buckets.values()) {
+      const elapsed = now - bucket.lastUpdate;
+      const tokens = Math.min(
+        this.config.maxTokens,
+        bucket.tokens + (elapsed / this.config.refillIntervalMs) * this.config.refillRate
+      );
+
+      if (tokens < this.config.maxTokens) {
+        activeBuckets++;
+      }
+      totalTokens += tokens;
+    }
+
+    return {
+      totalBuckets: this.buckets.size,
+      activeBuckets,
+      totalTokensAvailable: Math.floor(totalTokens),
+    };
+  }
+
+  private startCleanup(): void {
+    setInterval(() => {
+      const now = Date.now();
+      for (const [key, bucket] of this.buckets) {
+        const elapsed = now - bucket.lastUpdate;
+        const fullTokens =
+          bucket.tokens + (elapsed / this.config.refillIntervalMs) * this.config.refillRate;
+
+        if (fullTokens >= this.config.maxTokens) {
+          this.buckets.delete(key);
+        }
+      }
+    }, 5 * 60 * 1000);
+  }
+}
+
+export interface SlidingWindowConfig {
+  windowMs: number;
+  maxRequests: number;
+}
+
+export interface SlidingWindowEntry {
+  timestamps: number[];
+}
+
+export class SlidingWindowRateLimiter {
+  private windows: Map<string, SlidingWindowEntry> = new Map();
+  private config: SlidingWindowConfig;
+  private log = logger.child("sliding-window-limiter");
+
+  constructor(config: SlidingWindowConfig) {
+    this.config = config;
+    this.startCleanup();
+  }
+
+  check(key: string): RateLimitResult {
+    const now = Date.now();
+    const windowStart = now - this.config.windowMs;
+
+    let entry = this.windows.get(key);
+    if (!entry) {
+      entry = { timestamps: [] };
+      this.windows.set(key, entry);
+    }
+
+    entry.timestamps = entry.timestamps.filter((t) => t > windowStart);
+
+    if (entry.timestamps.length >= this.config.maxRequests) {
+      const oldestInWindow = entry.timestamps[0];
+      const retryAfterMs = oldestInWindow + this.config.windowMs - now;
+
+      this.log.debug(`Sliding window limit hit for ${key}`);
+
+      return {
+        allowed: false,
+        remaining: 0,
+        retryAfterMs: Math.max(0, retryAfterMs),
+      };
+    }
+
+    entry.timestamps.push(now);
+
+    return {
+      allowed: true,
+      remaining: this.config.maxRequests - entry.timestamps.length,
+      retryAfterMs: 0,
+    };
+  }
+
+  reset(key: string): void {
+    this.windows.delete(key);
+  }
+
+  resetAll(): void {
+    this.windows.clear();
+  }
+
+  private startCleanup(): void {
+    setInterval(() => {
+      const now = Date.now();
+      const windowStart = now - this.config.windowMs;
+
+      for (const [key, entry] of this.windows) {
+        entry.timestamps = entry.timestamps.filter((t) => t > windowStart);
+        if (entry.timestamps.length === 0) {
+          this.windows.delete(key);
+        }
+      }
+    }, 60 * 1000);
+  }
+}
+
+export function createTokenBucketLimiter(config: TokenBucketConfig): TokenBucketRateLimiter {
+  return new TokenBucketRateLimiter(config);
+}
+
+export function createSlidingWindowLimiter(config: SlidingWindowConfig): SlidingWindowRateLimiter {
+  return new SlidingWindowRateLimiter(config);
+}