@eddacraft/anvil-kindling-integration 0.1.0

package/src/query-service.ts

@@ -0,0 +1,217 @@
+/**
+ * Kindling Query Service (KINDLING-009)
+ *
+ * High-level query interface that wraps KindlingService.query() with
+ * convenience methods for each query scope. Applies query limit enforcement
+ * before returning results.
+ *
+ * This is the primary read API for Anvil CLI commands and tooling.
+ */
+
+import type { KindlingService } from './kindling-service.js';
+import type {
+  QueryResponse,
+  SessionQuery,
+  PlanQuery,
+  GateQuery,
+  ActionQuery,
+  ResultShape,
+  OutputFormat,
+} from './query-contract.js';
+import { enforceQueryLimits, limitsFromConfig } from './query-limits.js';
+import { createDebugger } from './utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Query Options
+// =============================================================================
+
+/**
+ * Common options for all query methods
+ */
+export interface QueryOptions {
+  /** Result structure (default: 'list') */
+  shape?: ResultShape;
+  /** Output format (default: 'json') */
+  format?: OutputFormat;
+  /** Include observations after this time */
+  time_after?: string;
+  /** Include observations before this time */
+  time_before?: string;
+  /** Maximum observations to return (capped by config) */
+  max_results?: number;
+  /** Maximum total payload size in bytes (capped by config) */
+  max_payload_bytes?: number;
+}
+
+/**
+ * Options specific to session queries
+ */
+export interface SessionQueryOptions extends QueryOptions {
+  /** Filter to specific phases */
+  include_phases?: Array<'plan' | 'gate' | 'action' | 'outcome' | 'error'>;
+}
+
+/**
+ * Options specific to plan queries
+ */
+export interface PlanQueryOptions extends QueryOptions {
+  /** Include linked execution run IDs (default: true) */
+  include_executions?: boolean;
+  /** Include plan version history (default: true) */
+  include_versions?: boolean;
+}
+
+/**
+ * Options specific to action queries
+ */
+export interface ActionQueryOptions extends QueryOptions {
+  /** Include approval chain (default: true) */
+  include_approval_chain?: boolean;
+}
+
+// =============================================================================
+// Query Service
+// =============================================================================
+
+/**
+ * High-level query service for Kindling observations.
+ *
+ * Provides typed convenience methods for each query scope and enforces
+ * query limits from the service configuration.
+ */
+export class KindlingQueryService {
+  private readonly service: KindlingService;
+
+  constructor(service: KindlingService) {
+    this.service = service;
+  }
+
+  /**
+   * Query: "What happened in this run?"
+   *
+   * Returns ordered observations for a specific session, optionally
+   * filtered by phase.
+   *
+   * @param sessionId - Session/run ID
+   * @param options - Query options
+   * @returns Query response with session observations
+   */
+  async querySession(sessionId: string, options: SessionQueryOptions = {}): Promise<QueryResponse> {
+    debug('querySession', { sessionId, shape: options.shape });
+    const request: SessionQuery = {
+      scope: 'session',
+      session_id: sessionId,
+      shape: options.shape ?? 'timeline',
+      format: options.format ?? 'json',
+      time_after: options.time_after,
+      time_before: options.time_before,
+      max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+      max_payload_bytes:
+        options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+      include_phases: options.include_phases,
+    };
+
+    const response = await this.service.query(request);
+    return this.applyLimits(response);
+  }
+
+  /**
+   * Query: "What happened because of this plan?"
+   *
+   * Returns plan metadata, versions, and linked executions.
+   * This is the only cross-session read allowed.
+   *
+   * @param planId - Plan ID
+   * @param options - Query options
+   * @returns Query response with plan observations
+   */
+  async queryPlan(planId: string, options: PlanQueryOptions = {}): Promise<QueryResponse> {
+    debug('queryPlan', { planId, shape: options.shape });
+    const request: PlanQuery = {
+      scope: 'plan',
+      plan_id: planId,
+      shape: options.shape ?? 'entity',
+      format: options.format ?? 'json',
+      time_after: options.time_after,
+      time_before: options.time_before,
+      max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+      max_payload_bytes:
+        options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+      include_executions: options.include_executions ?? true,
+      include_versions: options.include_versions ?? true,
+    };
+
+    const response = await this.service.query(request);
+    return this.applyLimits(response);
+  }
+
+  /**
+   * Query: "Why did this gate pass/fail?"
+   *
+   * Returns gate evaluation details with rule IDs, inputs, and outcomes.
+   *
+   * @param gateEvalId - Gate evaluation ID
+   * @param options - Query options
+   * @returns Query response with gate observations
+   */
+  async queryGate(gateEvalId: string, options: QueryOptions = {}): Promise<QueryResponse> {
+    debug('queryGate', { gateEvalId });
+    const request: GateQuery = {
+      scope: 'gate',
+      gate_eval_id: gateEvalId,
+      shape: options.shape ?? 'entity',
+      format: options.format ?? 'json',
+      time_after: options.time_after,
+      time_before: options.time_before,
+      max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+      max_payload_bytes:
+        options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+    };
+
+    const response = await this.service.query(request);
+    return this.applyLimits(response);
+  }
+
+  /**
+   * Query: "What exactly did this action do?"
+   *
+   * Returns action execution details with redacted command, environment,
+   * and linked governance.
+   *
+   * @param actionId - Action ID
+   * @param options - Query options
+   * @returns Query response with action observations
+   */
+  async queryAction(actionId: string, options: ActionQueryOptions = {}): Promise<QueryResponse> {
+    debug('queryAction', { actionId });
+    const request: ActionQuery = {
+      scope: 'action',
+      action_id: actionId,
+      shape: options.shape ?? 'entity',
+      format: options.format ?? 'json',
+      time_after: options.time_after,
+      time_before: options.time_before,
+      max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+      max_payload_bytes:
+        options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+      include_approval_chain: options.include_approval_chain ?? true,
+    };
+
+    const response = await this.service.query(request);
+    return this.applyLimits(response);
+  }
+
+  // ===========================================================================
+  // Private
+  // ===========================================================================
+
+  /**
+   * Apply query limits from the service configuration as a defense-in-depth layer.
+   */
+  private applyLimits(response: QueryResponse): QueryResponse {
+    const limits = limitsFromConfig(this.service.configuration.query_limits);
+    return enforceQueryLimits(response, limits);
+  }
+}

package/src/retention.ts

@@ -0,0 +1,153 @@
+/**
+ * Retention Management (KINDLING-016)
+ *
+ * Handles pruning of old observations and storage statistics.
+ * Works against the abstract IKindlingStore interface.
+ *
+ * Since the abstract store does not expose a direct "delete older than" method,
+ * retention is implemented via a dedicated IRetentionCapableStore interface
+ * that concrete stores can optionally implement.
+ */
+
+import type { KindlingConfig } from './config.js';
+
+// =============================================================================
+// Retention Store Interface
+// =============================================================================
+
+/**
+ * Extended store interface for stores that support retention operations.
+ *
+ * Not all stores need to implement this. The NoOpKindlingStore does not.
+ * Concrete SQLite or database-backed stores should implement this interface.
+ */
+export interface IRetentionCapableStore {
+  /**
+   * Delete all observations with timestamps older than the given ISO8601 date.
+   *
+   * @param olderThan - ISO8601 datetime cutoff
+   * @returns Number of observations deleted
+   */
+  deleteObservationsOlderThan(olderThan: string): Promise<number>;
+
+  /**
+   * Get storage statistics.
+   *
+   * @returns Observation count and estimated storage size in bytes
+   */
+  getStats(): Promise<StorageStats>;
+}
+
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+  /** Total number of observations in the store */
+  observation_count: number;
+  /** Estimated storage size in bytes */
+  estimated_size_bytes: number;
+}
+
+// =============================================================================
+// Type Guard
+// =============================================================================
+
+/**
+ * Check if a store supports retention operations.
+ */
+export function isRetentionCapable(store: unknown): store is IRetentionCapableStore {
+  if (store === null || typeof store !== 'object') {
+    return false;
+  }
+  const candidate = store as Record<string, unknown>;
+  return (
+    typeof candidate['deleteObservationsOlderThan'] === 'function' &&
+    typeof candidate['getStats'] === 'function'
+  );
+}
+
+// =============================================================================
+// Pruning
+// =============================================================================
+
+/**
+ * Result of a pruning operation
+ */
+export interface PruneResult {
+  /** Whether pruning was actually performed */
+  pruned: boolean;
+  /** Number of observations deleted (0 if not pruned) */
+  deleted_count: number;
+  /** The cutoff date used */
+  cutoff_date: string;
+  /** Reason if pruning was skipped */
+  skip_reason?: string;
+}
+
+/**
+ * Prune observations older than the configured retention period.
+ *
+ * If the store does not implement IRetentionCapableStore, this is a no-op
+ * that returns a skip result.
+ *
+ * @param store - The store to prune (must implement IRetentionCapableStore)
+ * @param config - Kindling configuration with retention settings
+ * @returns Prune result
+ */
+export async function pruneOldObservations(
+  store: unknown,
+  config: KindlingConfig
+): Promise<PruneResult> {
+  if (!config.enabled) {
+    return {
+      pruned: false,
+      deleted_count: 0,
+      cutoff_date: '',
+      skip_reason: 'Kindling is disabled',
+    };
+  }
+
+  if (!isRetentionCapable(store)) {
+    return {
+      pruned: false,
+      deleted_count: 0,
+      cutoff_date: '',
+      skip_reason: 'Store does not support retention operations',
+    };
+  }
+
+  const cutoffDate = new Date();
+  cutoffDate.setDate(cutoffDate.getDate() - config.retention.days);
+  const cutoffIso = cutoffDate.toISOString();
+
+  const deletedCount = await store.deleteObservationsOlderThan(cutoffIso);
+
+  return {
+    pruned: true,
+    deleted_count: deletedCount,
+    cutoff_date: cutoffIso,
+  };
+}
+
+// =============================================================================
+// Statistics
+// =============================================================================
+
+/**
+ * Get storage statistics from the store.
+ *
+ * If the store does not implement IRetentionCapableStore, returns zero values.
+ *
+ * @param store - The store to query
+ * @returns Storage statistics
+ */
+export async function getStorageStats(store: unknown): Promise<StorageStats> {
+  if (!isRetentionCapable(store)) {
+    return {
+      observation_count: 0,
+      estimated_size_bytes: 0,
+    };
+  }
+
+  return store.getStats();
+}

package/src/sensitive-data-validator.ts

@@ -0,0 +1,167 @@
+/**
+ * Sensitive Data Validation (KINDLING-015)
+ *
+ * Validates and redacts sensitive data from observations before they
+ * are persisted to Kindling. This is a defense-in-depth layer on top of
+ * the `containsSensitiveData` check in observation-contract.ts.
+ *
+ * Patterns detected:
+ * - API keys (sk-*, ghp_*, AKIA*)
+ * - Long hex tokens (40+ characters)
+ * - Email addresses
+ * - Password-like values
+ *
+ * @see observation-contract.ts for the base containsSensitiveData utility
+ */
+
+import { containsSensitiveData, type Observation } from './observation-contract.js';
+import { createDebugger } from './utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Sensitive Patterns
+// =============================================================================
+
+/**
+ * Known sensitive value patterns and their replacement strings
+ */
+const SENSITIVE_PATTERNS: ReadonlyArray<{
+  name: string;
+  pattern: RegExp;
+  replacement: string;
+}> = [
+  {
+    name: 'openai-api-key',
+    pattern: /sk-[a-zA-Z0-9]{20,}/g,
+    replacement: '[REDACTED:api-key]',
+  },
+  {
+    name: 'github-pat',
+    pattern: /ghp_[a-zA-Z0-9]{36,}/g,
+    replacement: '[REDACTED:github-token]',
+  },
+  {
+    name: 'github-fine-grained-pat',
+    pattern: /github_pat_[a-zA-Z0-9_]{36,}/g,
+    replacement: '[REDACTED:github-token]',
+  },
+  {
+    name: 'aws-access-key',
+    pattern: /AKIA[0-9A-Z]{16}/g,
+    replacement: '[REDACTED:aws-key]',
+  },
+  {
+    name: 'aws-secret-key',
+    pattern: /(?<=aws_secret_access_key\s*[=:]\s*)[^\s"',]+/gi,
+    replacement: '[REDACTED:aws-secret]',
+  },
+  {
+    name: 'hex-token',
+    pattern: /\b[0-9a-fA-F]{40,}\b/g,
+    replacement: '[REDACTED:token]',
+  },
+  {
+    name: 'email',
+    pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+    replacement: '[REDACTED:email]',
+  },
+  {
+    name: 'password-value',
+    pattern: /(?<=(?:password|passwd|pwd)\s*[=:]\s*["']?)[^\s"',]+/gi,
+    replacement: '[REDACTED:password]',
+  },
+  {
+    name: 'bearer-token',
+    pattern: /(?<=Bearer\s+)[a-zA-Z0-9._~+/=-]{20,}/gi,
+    replacement: '[REDACTED:bearer-token]',
+  },
+  {
+    name: 'npm-token',
+    pattern: /npm_[a-zA-Z0-9]{36,}/g,
+    replacement: '[REDACTED:npm-token]',
+  },
+];
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+/**
+ * Result of sensitive data validation
+ */
+export interface SensitiveDataValidationResult {
+  /** Whether any sensitive data was detected */
+  hasSensitiveData: boolean;
+  /** Detailed issues found */
+  issues: string[];
+}
+
+/**
+ * Validate that an observation does not contain sensitive data.
+ *
+ * Uses the contract-level `containsSensitiveData` check plus additional
+ * pattern matching for known credential formats.
+ *
+ * @param observation - The observation to validate
+ * @returns Validation result with issues if sensitive data found
+ */
+export function validateNoSensitiveData(observation: Observation): SensitiveDataValidationResult {
+  const issues: string[] = [];
+
+  // Run the contract-level check first
+  const contractCheck = containsSensitiveData(observation);
+  if (contractCheck.hasSensitiveData) {
+    issues.push(...contractCheck.issues);
+  }
+
+  // Run additional pattern checks against the serialized payload
+  const serialized = JSON.stringify(observation);
+
+  for (const { name, pattern } of SENSITIVE_PATTERNS) {
+    // Reset lastIndex for global regex patterns
+    pattern.lastIndex = 0;
+    if (pattern.test(serialized)) {
+      issues.push(`Sensitive pattern detected: ${name}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    debug('sensitive data detected in observation', {
+      issueCount: issues.length,
+      patterns: issues,
+    });
+  }
+
+  return {
+    hasSensitiveData: issues.length > 0,
+    issues,
+  };
+}
+
+// =============================================================================
+// Redaction
+// =============================================================================
+
+/**
+ * Deep-clone an observation and redact all known sensitive patterns from
+ * string values. This operates on the JSON serialization to catch values
+ * regardless of nesting depth.
+ *
+ * The returned observation is safe to persist.
+ *
+ * @param observation - The observation to redact
+ * @returns A new observation with sensitive values replaced
+ */
+export function redactSensitiveFields(observation: Observation): Observation {
+  debug('redacting sensitive fields from observation', { kind: observation.kind });
+  let serialized = JSON.stringify(observation);
+
+  for (const { pattern, replacement } of SENSITIVE_PATTERNS) {
+    // Reset lastIndex for global regex patterns
+    pattern.lastIndex = 0;
+    serialized = serialized.replace(pattern, replacement);
+  }
+
+  return JSON.parse(serialized) as Observation;
+}