palaryn 0.1.0 → 0.3.2

package/src/audit/logger.ts

@@ -0,0 +1,490 @@
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { AuditEvent, EventType, IncidentEvent, IncidentSeverity } from '../types/events';
+import { AuditConfig } from '../types/config';
+import { AuditStore } from '../storage/interfaces';
+import { ToolCall } from '../types/tool-call';
+import { DLPRedaction } from '../types/tool-result';
+
+/** Default maximum in-memory events before oldest are evicted */
+const DEFAULT_MAX_BUFFER_SIZE = 50000;
+
+export class AuditLogger {
+  private config: AuditConfig;
+  private events: AuditEvent[];
+  private logStream: fs.WriteStream | null;
+  private externalStore?: AuditStore;
+  private maxBufferSize: number;
+
+  constructor(config: AuditConfig, maxBufferSize?: number) {
+    this.config = config;
+    this.events = [];
+    this.maxBufferSize = maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+    this.logStream = null;
+
+    if (config.enabled && config.log_dir) {
+      if (!fs.existsSync(config.log_dir)) {
+        fs.mkdirSync(config.log_dir, { recursive: true });
+      }
+
+      const today = new Date().toISOString().split('T')[0];
+      const logFile = path.join(config.log_dir, `audit-${today}.jsonl`);
+      this.logStream = fs.createWriteStream(logFile, { flags: 'a' });
+      this.logStream.on('error', () => {
+        // Silently handle write errors (e.g. directory deleted during cleanup)
+        this.logStream = null;
+      });
+    }
+  }
+
+  /** Attach an external audit store (e.g. Redis, Postgres) for durable event persistence */
+  setStore(store: AuditStore): void {
+    this.externalStore = store;
+  }
+
+  /**
+   * Populate the in-memory event buffer from the external store.
+   * Call this after `setStore()` and after the store has been hydrated
+   * so that `getAllEvents()` returns persisted events across restarts.
+   */
+  hydrateFromStore(): void {
+    if (!this.externalStore) return;
+    const stored = this.externalStore.getAll();
+    if (stored.length > 0) {
+      // Merge: keep any events already in memory (logged before hydration)
+      const existingIds = new Set(this.events.map(e => e.event_id));
+      const newEvents = stored.filter(e => !existingIds.has(e.event_id));
+      this.events = [...newEvents, ...this.events];
+      // Enforce buffer limit
+      if (this.events.length > this.maxBufferSize) {
+        this.events = this.events.slice(-this.maxBufferSize);
+      }
+    }
+  }
+
+  log(event: Omit<AuditEvent, 'event_id' | 'timestamp'>): AuditEvent {
+    const fullEvent: AuditEvent = {
+      ...event,
+      event_id: randomUUID(),
+      timestamp: new Date().toISOString(),
+    };
+
+    // Write-ahead pattern: persist to file stream BEFORE in-memory push.
+    // This ensures the event is durably written before the caller gets
+    // acknowledgment. If the stream write fails, we still add to memory
+    // for query purposes but log a warning about the persistence failure.
+    if (this.logStream) {
+      try {
+        this.logStream.write(JSON.stringify(fullEvent) + '\n');
+      } catch (err) {
+        console.warn('Audit log stream write failed, event added to memory only:', (err as Error).message);
+      }
+    }
+
+    this.events.push(fullEvent);
+
+    // Evict oldest events if in-memory buffer exceeds capacity
+    if (this.events.length > this.maxBufferSize) {
+      this.events = this.events.slice(-this.maxBufferSize);
+    }
+
+    // Persist to external store (fire-and-forget write-through)
+    if (this.externalStore) {
+      this.externalStore.append(fullEvent);
+    }
+
+    if (this.config.console_output) {
+      console.log(JSON.stringify({
+        level: 'info',
+        event_type: fullEvent.event_type,
+        event_id: fullEvent.event_id,
+        tool_call_id: fullEvent.tool_call_id,
+        task_id: fullEvent.task_id,
+        actor_id: fullEvent.actor_id,
+        tool_name: fullEvent.tool_name,
+        timestamp: fullEvent.timestamp,
+        metadata: fullEvent.metadata,
+      }));
+    }
+
+    return fullEvent;
+  }
+
+  /** Common fields shared by all tool-call audit events. */
+  private baseFields(toolCall: ToolCall) {
+    return {
+      tool_call_id: toolCall.tool_call_id,
+      session_id: toolCall.source?.session_id,
+      task_id: toolCall.task_id,
+      workspace_id: toolCall.workspace_id,
+      actor_id: toolCall.actor.id,
+      tool_name: toolCall.tool.name,
+    };
+  }
+
+  logToolCallReceived(toolCall: ToolCall): AuditEvent {
+    return this.log({
+      event_type: 'TOOL_CALL_RECEIVED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        capability: toolCall.tool.capability,
+        platform: toolCall.source.platform,
+        has_constraints: !!toolCall.constraints,
+        labels: toolCall.context?.labels || [],
+        args_snapshot: this.redactArgs(toolCall.args),
+      },
+    });
+  }
+
+  /**
+   * Retrieve the stored args snapshot for a specific tool_call_id.
+   * Returns undefined if no TOOL_CALL_RECEIVED event exists for the given id.
+   */
+  getToolCallArgs(toolCallId: string): Record<string, unknown> | undefined {
+    const event = this.events.find(
+      e => e.event_type === 'TOOL_CALL_RECEIVED' && e.tool_call_id === toolCallId
+    );
+    return event?.metadata?.args_snapshot as Record<string, unknown> | undefined;
+  }
+
+  /**
+   * Deep-clone args and strip sensitive fields (headers and top-level keys).
+   */
+  private redactArgs(args: Record<string, unknown>): Record<string, unknown> {
+    const SENSITIVE_HEADERS = ['authorization', 'cookie', 'x-api-key', 'x-secret'];
+    const SENSITIVE_KEYS = ['password', 'secret', 'token', 'api_key'];
+
+    const cloned = JSON.parse(JSON.stringify(args)) as Record<string, unknown>;
+
+    // Strip sensitive top-level keys
+    for (const key of Object.keys(cloned)) {
+      if (SENSITIVE_KEYS.includes(key.toLowerCase())) {
+        cloned[key] = '[REDACTED]';
+      }
+    }
+
+    // Strip sensitive headers
+    if (cloned.headers && typeof cloned.headers === 'object' && !Array.isArray(cloned.headers)) {
+      const headers = cloned.headers as Record<string, unknown>;
+      for (const key of Object.keys(headers)) {
+        if (SENSITIVE_HEADERS.includes(key.toLowerCase())) {
+          headers[key] = '[REDACTED]';
+        }
+      }
+    }
+
+    return cloned;
+  }
+
+  logPolicyDecided(toolCall: ToolCall, decision: string, ruleId: string, reasons: string[]): AuditEvent {
+    return this.log({
+      event_type: 'POLICY_DECIDED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        decision,
+        rule_id: ruleId,
+        reasons,
+      },
+    });
+  }
+
+  logDLPScanned(toolCall: ToolCall, detected: string[], severity: string, redactionCount: number, redactions?: DLPRedaction[]): AuditEvent {
+    return this.log({
+      event_type: 'DLP_SCANNED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        detected,
+        severity,
+        redaction_count: redactionCount,
+        findings_count: detected.length,
+        redactions: redactions?.map(r => ({
+          path: r.path,
+          type: r.original_type,
+          method: r.method,
+          masked_preview: r.masked_preview,
+        })),
+        target_url: toolCall.args?.url,
+        actor_display: toolCall.actor.display || toolCall.actor.id,
+      },
+    });
+  }
+
+  logBudgetChecked(toolCall: ToolCall, estimatedCost: number, spentToDate: number, remaining: number): AuditEvent {
+    return this.log({
+      event_type: 'BUDGET_CHECKED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        estimated_cost: estimatedCost,
+        spent_to_date: spentToDate,
+        remaining,
+        would_exceed: estimatedCost > remaining,
+      },
+    });
+  }
+
+  logToolExecuted(toolCall: ToolCall, status: string, durationMs: number, httpStatus?: number): AuditEvent {
+    return this.log({
+      event_type: 'TOOL_EXECUTED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        status,
+        duration_ms: durationMs,
+        ...(httpStatus !== undefined && { http_status: httpStatus }),
+      },
+    });
+  }
+
+  logToolResultReturned(toolCall: ToolCall, status: string, durationMs: number, extraMetadata?: Record<string, unknown>): AuditEvent {
+    return this.log({
+      event_type: 'TOOL_RESULT_RETURNED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        status,
+        duration_ms: durationMs,
+        ...extraMetadata,
+      },
+    });
+  }
+
+  logApprovalRequested(toolCall: ToolCall, scope: string, reason: string, ttlSeconds: number): AuditEvent {
+    return this.log({
+      event_type: 'APPROVAL_REQUESTED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        scope,
+        reason,
+        ttl_seconds: ttlSeconds,
+        expires_at: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
+      },
+    });
+  }
+
+  logApprovalApproved(toolCall: ToolCall, approverId: string): AuditEvent {
+    return this.log({
+      event_type: 'APPROVAL_APPROVED',
+      tool_call_id: toolCall.tool_call_id,
+      task_id: toolCall.task_id,
+      workspace_id: toolCall.workspace_id,
+      actor_id: toolCall.actor.id,
+      tool_name: toolCall.tool.name,
+      metadata: {
+        approver_id: approverId,
+      },
+    });
+  }
+
+  logApprovalDenied(toolCall: ToolCall, approverId: string, reason: string): AuditEvent {
+    return this.log({
+      event_type: 'APPROVAL_DENIED',
+      tool_call_id: toolCall.tool_call_id,
+      task_id: toolCall.task_id,
+      workspace_id: toolCall.workspace_id,
+      actor_id: toolCall.actor.id,
+      tool_name: toolCall.tool.name,
+      metadata: {
+        approver_id: approverId,
+        reason,
+      },
+    });
+  }
+
+  logApprovalExpired(toolCall: ToolCall): AuditEvent {
+    return this.log({
+      event_type: 'APPROVAL_EXPIRED',
+      tool_call_id: toolCall.tool_call_id,
+      task_id: toolCall.task_id,
+      workspace_id: toolCall.workspace_id,
+      actor_id: toolCall.actor.id,
+      tool_name: toolCall.tool.name,
+      metadata: {},
+    });
+  }
+
+  logIncident(toolCall: ToolCall, severity: IncidentSeverity, incidentType: string, description: string, recommendedAction: string): AuditEvent {
+    return this.log({
+      event_type: 'INCIDENT_RAISED',
+      ...this.baseFields(toolCall),
+      metadata: {
+        severity,
+        incident_type: incidentType,
+        description,
+        recommended_action: recommendedAction,
+      },
+    });
+  }
+
+  getTaskTrace(taskId: string): AuditEvent[] {
+    return this.events
+      .filter(e => e.task_id === taskId)
+      .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  }
+
+  getToolCallEvents(toolCallId: string): AuditEvent[] {
+    return this.events
+      .filter(e => e.tool_call_id === toolCallId)
+      .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  }
+
+  getEventsByType(eventType: EventType): AuditEvent[] {
+    return this.events.filter(e => e.event_type === eventType);
+  }
+
+  getAllEvents(): AuditEvent[] {
+    return [...this.events];
+  }
+
+  /**
+   * Batch-flush helper: corks the stream (buffers writes), executes the
+   * callback, then uncorks to flush all buffered writes in a single I/O
+   * operation. Useful when logging many events in a tight loop.
+   *
+   * When called with no arguments, drains the write stream and returns
+   * a Promise that resolves when all buffered data has been flushed to
+   * the underlying resource. Use this before close() to ensure no
+   * in-flight audit events are lost.
+   */
+  flush(fn?: () => void): void | Promise<void> {
+    if (fn) {
+      this.logStream?.cork();
+      try {
+        fn();
+      } finally {
+        this.logStream?.uncork();
+      }
+      return;
+    }
+
+    // No-arg: drain the write stream so pending writes complete
+    if (!this.logStream) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      // If the stream buffer is already empty, resolve immediately
+      if (this.logStream!.writableLength === 0) {
+        resolve();
+        return;
+      }
+      this.logStream!.once('drain', () => resolve());
+      // Cork and uncork to trigger a drain
+      this.logStream!.cork();
+      this.logStream!.uncork();
+    });
+  }
+
+  close(): void {
+    if (this.logStream) {
+      this.logStream.end();
+      this.logStream = null;
+    }
+  }
+
+  /** Get aggregated event statistics for a workspace within a time window */
+  getEventStats(workspaceId: string, hours: number = 24): {
+    total_requests: number;
+    blocked_count: number;
+    approval_count: number;
+    error_count: number;
+    avg_duration_ms: number;
+    requests_per_minute: number;
+    active_agents: number;
+    policy_breakdown: Record<string, number>;
+    pipeline_throughput: { stage: string; passed: number; failed: number }[];
+  } {
+    const cutoff = new Date(Date.now() - hours * 3600000).toISOString();
+    const windowEvents = this.events.filter(
+      e => e.workspace_id === workspaceId && e.timestamp >= cutoff
+    );
+
+    // Count event types
+    const total_requests = windowEvents.filter(e => e.event_type === 'TOOL_CALL_RECEIVED').length;
+    const policyEvents = windowEvents.filter(e => e.event_type === 'POLICY_DECIDED');
+    const blocked_count = policyEvents.filter(e => e.metadata?.decision === 'deny').length;
+    const approval_count = windowEvents.filter(e => e.event_type === 'APPROVAL_REQUESTED').length;
+    const executedEvents = windowEvents.filter(e => e.event_type === 'TOOL_EXECUTED');
+    const error_count = executedEvents.filter(e => e.metadata?.status === 'error').length;
+
+    // Average duration from TOOL_RESULT_RETURNED
+    const resultEvents = windowEvents.filter(e => e.event_type === 'TOOL_RESULT_RETURNED');
+    const durations = resultEvents
+      .map(e => e.metadata?.duration_ms)
+      .filter((d): d is number => typeof d === 'number');
+    const avg_duration_ms = durations.length > 0
+      ? durations.reduce((a, b) => a + b, 0) / durations.length
+      : 0;
+
+    // Requests per minute — use actual event timespan (first→last), min 1 minute
+    const receivedEvents = windowEvents.filter(e => e.event_type === 'TOOL_CALL_RECEIVED');
+    let requests_per_minute = 0;
+    if (receivedEvents.length >= 2) {
+      const timestamps = receivedEvents.map(e => new Date(e.timestamp).getTime()).sort((a, b) => a - b);
+      const spanMinutes = Math.max((timestamps[timestamps.length - 1] - timestamps[0]) / 60000, 1);
+      requests_per_minute = receivedEvents.length / spanMinutes;
+    } else if (receivedEvents.length === 1) {
+      // Single request in window — report as 1 req/min (it happened)
+      requests_per_minute = 1;
+    }
+
+    // Distinct actor IDs
+    const actorIds = new Set(windowEvents.map(e => e.actor_id));
+    const active_agents = actorIds.size;
+
+    // Policy breakdown: group POLICY_DECIDED by decision
+    const policy_breakdown: Record<string, number> = {};
+    for (const pe of policyEvents) {
+      const decision = String(pe.metadata?.decision || 'unknown');
+      policy_breakdown[decision] = (policy_breakdown[decision] || 0) + 1;
+    }
+
+    // Pipeline throughput
+    const policyAllow = policyEvents.filter(
+      e => e.metadata?.decision === 'allow' || e.metadata?.decision === 'transform'
+    ).length;
+    const policyFail = policyEvents.filter(
+      e => e.metadata?.decision === 'deny' || e.metadata?.decision === 'require_approval'
+    ).length;
+    const dlpEvents = windowEvents.filter(e => e.event_type === 'DLP_SCANNED');
+    const budgetEvents = windowEvents.filter(e => e.event_type === 'BUDGET_CHECKED');
+    const execOk = executedEvents.filter(e => e.metadata?.status === 'ok').length;
+    const execFail = executedEvents.filter(e => e.metadata?.status !== 'ok').length;
+
+    const pipeline_throughput = [
+      { stage: 'auth', passed: total_requests, failed: 0 },
+      { stage: 'policy', passed: policyAllow, failed: policyFail },
+      { stage: 'dlp', passed: dlpEvents.length, failed: 0 },
+      { stage: 'budget', passed: budgetEvents.length, failed: 0 },
+      { stage: 'execute', passed: execOk, failed: execFail },
+    ];
+
+    return {
+      total_requests,
+      blocked_count,
+      approval_count,
+      error_count,
+      avg_duration_ms,
+      requests_per_minute,
+      active_agents,
+      policy_breakdown,
+      pipeline_throughput,
+    };
+  }
+
+  deleteByTaskId(taskId: string): void {
+    this.events = this.events.filter(e => e.task_id !== taskId);
+    if (this.externalStore) {
+      this.externalStore.deleteByTaskId(taskId);
+    }
+  }
+
+  deleteBySessionId(sessionId: string): void {
+    this.events = this.events.filter(e => e.session_id !== sessionId);
+    if (this.externalStore) {
+      this.externalStore.deleteBySessionId(sessionId);
+    }
+  }
+
+  clear(): void {
+    this.events = [];
+    if (this.externalStore) {
+      this.externalStore.clear();
+    }
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,5 @@
+export * from './pkce';
+export * from './password';
+export * from './providers';
+export * from './session';
+export * from './routes';

package/src/auth/password.ts

@@ -0,0 +1,21 @@
+import { scrypt, randomBytes, timingSafeEqual } from 'crypto';
+import { promisify } from 'util';
+
+const scryptAsync = promisify(scrypt);
+const SALT_LENGTH = 16;
+const KEY_LENGTH = 64;
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_LENGTH).toString('hex');
+  const hash = (await scryptAsync(password, salt, KEY_LENGTH) as Buffer).toString('hex');
+  return `${salt}:${hash}`;
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [salt, hash] = stored.split(':');
+  if (!salt || !hash) return false;
+  const derived = await scryptAsync(password, salt, KEY_LENGTH) as Buffer;
+  const storedBuf = Buffer.from(hash, 'hex');
+  if (derived.length !== storedBuf.length) return false;
+  return timingSafeEqual(derived, storedBuf);
+}

package/src/auth/pkce.ts

@@ -0,0 +1,22 @@
+import * as crypto from 'crypto';
+
+/**
+ * Generate a PKCE code_verifier (43-128 character random string).
+ */
+export function generateCodeVerifier(): string {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * Generate a PKCE code_challenge from a code_verifier (S256 method).
+ */
+export function generateCodeChallenge(verifier: string): string {
+  return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Generate a cryptographically random nonce for OAuth state.
+ */
+export function generateNonce(): string {
+  return crypto.randomBytes(32).toString('hex');
+}