palaryn 0.1.0 → 0.3.2

package/src/ratelimit/limiter.ts

@@ -0,0 +1,196 @@
+import { RateLimitConfig } from '../types/config';
+import { RateLimitStore } from '../storage/interfaces';
+import { ToolCall } from '../types/tool-call';
+
+interface WindowEntry {
+  timestamps: number[];
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  current: number;
+  limit: number;
+  remaining: number;
+  reset_at: string;
+  blocked_by?: 'actor' | 'workspace';
+}
+
+/**
+ * Sliding-window rate limiter.
+ * Tracks request counts per actor and per workspace within a configurable window.
+ * Optionally delegates to an external RateLimitStore (e.g. Redis) for cross-process state.
+ */
+export class RateLimiter {
+  private config: RateLimitConfig;
+  private windows: Map<string, WindowEntry> = new Map();
+  private store?: RateLimitStore;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+
+  constructor(config: RateLimitConfig, store?: RateLimitStore) {
+    this.config = config;
+    this.store = store;
+
+    // Periodic cleanup of stale entries (every 60 seconds)
+    if (config.enabled) {
+      this.cleanupTimer = setInterval(() => {
+        this.cleanupStaleEntries();
+      }, 60_000);
+      if (this.cleanupTimer && typeof this.cleanupTimer === 'object' && 'unref' in this.cleanupTimer) {
+        this.cleanupTimer.unref();
+      }
+    }
+  }
+
+  /** Remove entries with no timestamps in the current window */
+  private cleanupStaleEntries(): void {
+    const cutoff = Date.now() - this.config.window_ms;
+    for (const [key, entry] of this.windows) {
+      const valid = entry.timestamps.filter(t => t > cutoff);
+      if (valid.length === 0) {
+        this.windows.delete(key);
+      } else {
+        entry.timestamps = valid;
+      }
+    }
+  }
+
+  /** Stop the periodic cleanup timer (for tests and shutdown) */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+  }
+
+  /**
+   * Check if a tool call is within rate limits.
+   * Records the hit and returns the result.
+   * Optional overrides allow per-workspace rate limit configuration.
+   */
+  check(toolCall: ToolCall, overrides?: { actor_max_per_window?: number; workspace_max_per_window?: number; window_ms?: number }): RateLimitResult {
+    if (!this.config.enabled) {
+      return { allowed: true, current: 0, limit: 0, remaining: 0, reset_at: '' };
+    }
+
+    const now = Date.now();
+    const windowMs = overrides?.window_ms ?? this.config.window_ms;
+    const actorMax = overrides?.actor_max_per_window ?? this.config.actor_max_per_window;
+    const wsMax = overrides?.workspace_max_per_window ?? this.config.workspace_max_per_window;
+
+    // Check actor rate limit
+    const actorKey = `actor:${toolCall.actor.id}`;
+    const actorResult = this.hit(actorKey, now, windowMs, actorMax);
+    if (!actorResult.allowed) {
+      return {
+        allowed: false,
+        current: actorResult.current,
+        limit: actorResult.limit,
+        remaining: 0,
+        reset_at: new Date(actorResult.resetAt).toISOString(),
+        blocked_by: 'actor',
+      };
+    }
+
+    // Check workspace rate limit
+    const wsKey = `workspace:${toolCall.workspace_id}`;
+    const wsResult = this.hit(wsKey, now, windowMs, wsMax);
+    if (!wsResult.allowed) {
+      // Roll back the actor hit since we're rejecting
+      this.rollback(actorKey, now);
+      return {
+        allowed: false,
+        current: wsResult.current,
+        limit: wsResult.limit,
+        remaining: 0,
+        reset_at: new Date(wsResult.resetAt).toISOString(),
+        blocked_by: 'workspace',
+      };
+    }
+
+    const remaining = Math.min(
+      actorMax - actorResult.current,
+      wsMax - wsResult.current
+    );
+
+    return {
+      allowed: true,
+      current: actorResult.current,
+      limit: actorMax,
+      remaining,
+      reset_at: new Date(actorResult.resetAt).toISOString(),
+    };
+  }
+
+  private hit(key: string, now: number, windowMs: number, maxRequests: number) {
+    // Delegate to external store if available
+    if (this.store) {
+      return this.store.hit(key, windowMs, maxRequests);
+    }
+
+    const cutoff = now - windowMs;
+    let entry = this.windows.get(key);
+    if (!entry) {
+      entry = { timestamps: [] };
+      this.windows.set(key, entry);
+    }
+
+    // Prune expired timestamps
+    entry.timestamps = entry.timestamps.filter(t => t > cutoff);
+
+    // If all timestamps expired, remove the entry entirely to free memory
+    if (entry.timestamps.length === 0) {
+      // But we still need to record this hit, so keep the entry
+    }
+
+    // Record this hit
+    entry.timestamps.push(now);
+
+    const current = entry.timestamps.length;
+    const allowed = current <= maxRequests;
+    const resetAt = entry.timestamps.length > 0 ? entry.timestamps[0] + windowMs : now + windowMs;
+
+    // Periodic cleanup of stale windows (every 1000 entries)
+    if (this.windows.size > 1000) {
+      for (const [k, w] of this.windows) {
+        const validTimestamps = w.timestamps.filter(t => t > cutoff);
+        if (validTimestamps.length === 0) {
+          this.windows.delete(k);
+        }
+      }
+    }
+
+    return { allowed, current, limit: maxRequests, resetAt };
+  }
+
+  private rollback(key: string, timestamp: number) {
+    if (this.store) {
+      // Delegate rollback to the store if available
+      if ('rollback' in this.store && typeof (this.store as any).rollback === 'function') {
+        (this.store as any).rollback(key, this.config.window_ms);
+      }
+      return;
+    }
+    const entry = this.windows.get(key);
+    if (entry) {
+      const idx = entry.timestamps.lastIndexOf(timestamp);
+      if (idx !== -1) entry.timestamps.splice(idx, 1);
+    }
+  }
+
+  /** Wait for all pending store writes to complete. */
+  async flush(): Promise<void> {
+    if (this.store && 'flush' in this.store && typeof (this.store as any).flush === 'function') {
+      await (this.store as any).flush();
+    }
+  }
+
+  reset(): void {
+    this.windows.clear();
+    this.store?.reset();
+  }
+
+  /** Get the number of tracked window entries (for diagnostics) */
+  getWindowCount(): number {
+    return this.windows.size;
+  }
+}

package/src/replay/engine.ts

@@ -0,0 +1,142 @@
+import { AuditLogger } from '../audit/logger';
+import { PolicyEngine } from '../policy/engine';
+import { ToolCall } from '../types/tool-call';
+import { AuditEvent } from '../types/events';
+
+export interface ReplayComparison {
+  tool_call_id: string;
+  tool_name: string;
+  original_decision: string;
+  original_rule_id: string;
+  replay_decision: string;
+  replay_rule_id: string;
+  changed: boolean;
+  replay_reasons: string[];
+}
+
+export interface ReplayResult {
+  task_id: string;
+  policy_pack_path: string;
+  total_calls: number;
+  changed_count: number;
+  comparisons: ReplayComparison[];
+}
+
+/** Maximum number of tool calls to replay per session */
+const MAX_REPLAY_CALLS = 100;
+
+export class SessionReplayEngine {
+  private auditLogger: AuditLogger;
+
+  constructor(auditLogger: AuditLogger) {
+    this.auditLogger = auditLogger;
+  }
+
+  /**
+   * Replay a task's tool calls against an alternative policy pack.
+   *
+   * 1. Gets all events for the task_id from the audit logger.
+   * 2. Finds TOOL_CALL_RECEIVED events (which contain args_snapshot in metadata).
+   * 3. Reconstructs ToolCall objects from event data + args_snapshot.
+   * 4. Finds the original POLICY_DECIDED events for each tool_call_id.
+   * 5. Creates a new PolicyEngine with the alternative policy pack path.
+   * 6. Re-evaluates each ToolCall against the new policy.
+   * 7. Returns a comparison report.
+   */
+  replay(taskId: string, altPolicyPackPath: string): ReplayResult {
+    const events = this.auditLogger.getTaskTrace(taskId);
+
+    if (events.length === 0) {
+      return {
+        task_id: taskId,
+        policy_pack_path: altPolicyPackPath,
+        total_calls: 0,
+        changed_count: 0,
+        comparisons: [],
+      };
+    }
+
+    // Collect TOOL_CALL_RECEIVED and POLICY_DECIDED events
+    const receivedEvents = events.filter(e => e.event_type === 'TOOL_CALL_RECEIVED');
+    const policyEvents = events.filter(e => e.event_type === 'POLICY_DECIDED');
+
+    // Build a map of tool_call_id -> POLICY_DECIDED event for quick lookup
+    const policyMap = new Map<string, AuditEvent>();
+    for (const pe of policyEvents) {
+      policyMap.set(pe.tool_call_id, pe);
+    }
+
+    // Cap at MAX_REPLAY_CALLS
+    const capped = receivedEvents.slice(0, MAX_REPLAY_CALLS);
+
+    // Create the alternative policy engine
+    const altEngine = new PolicyEngine(altPolicyPackPath);
+
+    const comparisons: ReplayComparison[] = [];
+
+    for (const event of capped) {
+      // Reconstruct ToolCall from event metadata + args_snapshot
+      const toolCall = this.reconstructToolCall(event);
+
+      // Get original policy decision
+      const originalPolicy = policyMap.get(event.tool_call_id);
+      const originalDecision = originalPolicy?.metadata?.decision as string || 'unknown';
+      const originalRuleId = originalPolicy?.metadata?.rule_id as string || 'unknown';
+
+      // Re-evaluate against alternative policy
+      const replayResult = altEngine.evaluate(toolCall);
+
+      const changed = originalDecision !== replayResult.decision ||
+                      originalRuleId !== replayResult.rule_id;
+
+      comparisons.push({
+        tool_call_id: event.tool_call_id,
+        tool_name: event.tool_name,
+        original_decision: originalDecision,
+        original_rule_id: originalRuleId,
+        replay_decision: replayResult.decision,
+        replay_rule_id: replayResult.rule_id,
+        changed,
+        replay_reasons: replayResult.reasons,
+      });
+    }
+
+    return {
+      task_id: taskId,
+      policy_pack_path: altPolicyPackPath,
+      total_calls: comparisons.length,
+      changed_count: comparisons.filter(c => c.changed).length,
+      comparisons,
+    };
+  }
+
+  /**
+   * Reconstruct a ToolCall from an audit event's stored data.
+   * Uses the args_snapshot from metadata for the args field.
+   */
+  private reconstructToolCall(event: AuditEvent): ToolCall {
+    const metadata = event.metadata;
+    const argsSnapshot = (metadata.args_snapshot as Record<string, unknown>) || {};
+
+    return {
+      tool_call_id: event.tool_call_id,
+      task_id: event.task_id,
+      workspace_id: event.workspace_id,
+      actor: {
+        type: 'agent',
+        id: event.actor_id,
+      },
+      source: {
+        platform: (metadata.platform as string) || 'unknown',
+      },
+      tool: {
+        name: event.tool_name,
+        capability: (metadata.capability as 'read' | 'write' | 'delete' | 'admin') || 'read',
+      },
+      args: argsSnapshot,
+      context: {
+        labels: (metadata.labels as string[]) || [],
+      },
+    };
+  }
+}

package/src/replay/index.ts

@@ -0,0 +1 @@
+export { SessionReplayEngine, ReplayComparison, ReplayResult } from './engine';

package/src/saas/index.ts

@@ -0,0 +1 @@
+export * from './routes';