claude-flow 3.27.4 → 3.29.0

package/v3/@claude-flow/guidance/dist/gates.js

@@ -0,0 +1,302 @@
+/**
+ * Hook-based Enforcement Gates
+ *
+ * Uses Claude Flow hooks to enforce non-negotiable rules.
+ * The model can forget. The hook does not.
+ *
+ * Gates:
+ * 1. Destructive ops gate - requires confirmation + rollback plan
+ * 2. Tool allowlist gate - blocks non-allowlisted tools
+ * 3. Diff size gate - requires plan + staged commits for large diffs
+ * 4. Secrets gate - redacts and warns on secret patterns
+ *
+ * @module @claude-flow/guidance/gates
+ */
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_GATE_CONFIG = {
+    destructiveOps: true,
+    toolAllowlist: false,
+    diffSize: true,
+    secrets: true,
+    diffSizeThreshold: 300,
+    allowedTools: [],
+    secretPatterns: [
+        /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{8,}['"]/gi,
+        /(?:secret|password|passwd|pwd)\s*[:=]\s*['"][^'"]{4,}['"]/gi,
+        /(?:token|bearer)\s*[:=]\s*['"][^'"]{10,}['"]/gi,
+        /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/g,
+        /sk-[a-zA-Z0-9]{20,}/g,
+        /ghp_[a-zA-Z0-9]{36}/g,
+        /npm_[a-zA-Z0-9]{36}/g,
+        /AKIA[0-9A-Z]{16}/g,
+    ],
+    destructivePatterns: [
+        /\brm\s+-rf?\b/i,
+        /\bdrop\s+(database|table|schema|index)\b/i,
+        /\btruncate\s+table\b/i,
+        /\bgit\s+push\s+.*--force\b/i,
+        /\bgit\s+reset\s+--hard\b/i,
+        /\bgit\s+clean\s+-fd?\b/i,
+        /\bformat\s+[a-z]:/i,
+        /\bdel\s+\/[sf]\b/i,
+        /\b(?:kubectl|helm)\s+delete\s+(?:--all|namespace)\b/i,
+        /\bDROP\s+(?:DATABASE|TABLE|SCHEMA)\b/i,
+        /\bDELETE\s+FROM\s+\w+\s*$/i,
+        /\bALTER\s+TABLE\s+\w+\s+DROP\b/i,
+    ],
+};
+/** Severity ranking for gate decisions (module-level constant to avoid per-call allocation). */
+const GATE_DECISION_SEVERITY = {
+    'block': 3,
+    'require-confirmation': 2,
+    'warn': 1,
+    'allow': 0,
+};
+// ============================================================================
+// Enforcement Gates
+// ============================================================================
+export class EnforcementGates {
+    config;
+    activeRules = [];
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_GATE_CONFIG, ...config };
+    }
+    /**
+     * Update active rules from retrieval
+     */
+    setActiveRules(rules) {
+        this.activeRules = rules;
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Evaluate all gates for a command
+     */
+    evaluateCommand(command) {
+        const results = [];
+        if (this.config.destructiveOps) {
+            const result = this.evaluateDestructiveOps(command);
+            if (result)
+                results.push(result);
+        }
+        if (this.config.secrets) {
+            const result = this.evaluateSecrets(command);
+            if (result)
+                results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Evaluate all gates for a tool use
+     */
+    evaluateToolUse(toolName, params) {
+        const results = [];
+        if (this.config.toolAllowlist && this.config.allowedTools.length > 0) {
+            const result = this.evaluateToolAllowlist(toolName);
+            if (result)
+                results.push(result);
+        }
+        // Check tool params for secrets
+        if (this.config.secrets) {
+            const serialized = JSON.stringify(params);
+            const result = this.evaluateSecrets(serialized);
+            if (result)
+                results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Evaluate all gates for a file edit
+     */
+    evaluateEdit(filePath, content, diffLines) {
+        const results = [];
+        if (this.config.diffSize) {
+            const result = this.evaluateDiffSize(filePath, diffLines);
+            if (result)
+                results.push(result);
+        }
+        if (this.config.secrets) {
+            const result = this.evaluateSecrets(content);
+            if (result)
+                results.push(result);
+        }
+        return results;
+    }
+    // ===== Individual Gate Implementations =====
+    /**
+     * Gate 1: Destructive Operations
+     *
+     * If command includes delete, drop, rm, force, migration,
+     * require explicit confirmation and a rollback plan.
+     */
+    evaluateDestructiveOps(command) {
+        for (const pattern of this.config.destructivePatterns) {
+            // Reset lastIndex for global regex
+            pattern.lastIndex = 0;
+            const match = pattern.exec(command);
+            if (match) {
+                const triggeredRules = this.findTriggeredRules('security', 'critical');
+                return {
+                    decision: 'require-confirmation',
+                    gateName: 'destructive-ops',
+                    reason: `Destructive operation detected: "${match[0]}". Requires explicit confirmation and a rollback plan before proceeding.`,
+                    triggeredRules: triggeredRules.map(r => r.id),
+                    remediation: [
+                        '1. Confirm this operation is intentional',
+                        '2. Document the rollback plan (e.g., git ref, backup, undo command)',
+                        '3. If this is a migration, ensure it has a down/rollback step',
+                    ].join('\n'),
+                    metadata: {
+                        matchedPattern: match[0],
+                        fullCommand: command,
+                    },
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Gate 2: Tool Allowlist
+     *
+     * If tool not in allowlist, block and ask for permission.
+     */
+    evaluateToolAllowlist(toolName) {
+        if (this.config.allowedTools.length === 0)
+            return null;
+        const allowed = this.config.allowedTools.some(t => t === toolName || t === '*' || (t.endsWith('*') && toolName.startsWith(t.slice(0, -1))));
+        if (!allowed) {
+            return {
+                decision: 'block',
+                gateName: 'tool-allowlist',
+                reason: `Tool "${toolName}" is not in the allowlist. Request permission before using this tool.`,
+                triggeredRules: this.findTriggeredRules('security').map(r => r.id),
+                remediation: `Add "${toolName}" to the tool allowlist in gate configuration, or get explicit user approval.`,
+                metadata: {
+                    blockedTool: toolName,
+                    allowedTools: this.config.allowedTools,
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * Gate 3: Diff Size
+     *
+     * If patch exceeds threshold, require a plan and staged commits.
+     */
+    evaluateDiffSize(filePath, diffLines) {
+        if (diffLines <= this.config.diffSizeThreshold)
+            return null;
+        return {
+            decision: 'warn',
+            gateName: 'diff-size',
+            reason: `Diff for "${filePath}" is ${diffLines} lines (threshold: ${this.config.diffSizeThreshold}). Large changes should be planned and staged.`,
+            triggeredRules: this.findTriggeredRules('architecture').map(r => r.id),
+            remediation: [
+                '1. Create a plan breaking this change into logical commits',
+                '2. Stage changes incrementally (one concern per commit)',
+                '3. Run tests after each staged commit',
+                '4. Consider if this change should be split into multiple PRs',
+            ].join('\n'),
+            metadata: {
+                filePath,
+                diffLines,
+                threshold: this.config.diffSizeThreshold,
+            },
+        };
+    }
+    /**
+     * Gate 4: Secrets Detection
+     *
+     * If output matches secret patterns, redact and warn.
+     */
+    evaluateSecrets(content) {
+        const detectedSecrets = [];
+        for (const pattern of this.config.secretPatterns) {
+            // Reset lastIndex for global regex
+            pattern.lastIndex = 0;
+            const matches = content.match(pattern);
+            if (matches) {
+                for (const match of matches) {
+                    // Redact the secret (show first 4 and last 4 chars)
+                    const redacted = match.length > 12
+                        ? `${match.slice(0, 4)}${'*'.repeat(match.length - 8)}${match.slice(-4)}`
+                        : '*'.repeat(match.length);
+                    detectedSecrets.push(redacted);
+                }
+            }
+        }
+        if (detectedSecrets.length === 0)
+            return null;
+        return {
+            decision: 'block',
+            gateName: 'secrets',
+            reason: `Detected ${detectedSecrets.length} potential secret(s) in content. Secrets must not be committed or exposed.`,
+            triggeredRules: this.findTriggeredRules('security', 'critical').map(r => r.id),
+            remediation: [
+                '1. Move secrets to environment variables',
+                '2. Use .env files (ensure they are in .gitignore)',
+                '3. Use a secret management service for production',
+                `Detected patterns: ${detectedSecrets.join(', ')}`,
+            ].join('\n'),
+            metadata: {
+                secretCount: detectedSecrets.length,
+                redactedSecrets: detectedSecrets,
+            },
+        };
+    }
+    // ===== Aggregate Evaluation =====
+    /**
+     * Get the most restrictive decision from multiple gate results
+     */
+    aggregateDecision(results) {
+        if (results.length === 0)
+            return 'allow';
+        let maxSeverity = 0;
+        let worstDecision = 'allow';
+        for (const result of results) {
+            const s = GATE_DECISION_SEVERITY[result.decision];
+            if (s > maxSeverity) {
+                maxSeverity = s;
+                worstDecision = result.decision;
+            }
+        }
+        return worstDecision;
+    }
+    /**
+     * Get gate statistics
+     */
+    getActiveGateCount() {
+        let count = 0;
+        if (this.config.destructiveOps)
+            count++;
+        if (this.config.toolAllowlist && this.config.allowedTools.length > 0)
+            count++;
+        if (this.config.diffSize)
+            count++;
+        if (this.config.secrets)
+            count++;
+        return count;
+    }
+    // ===== Helpers =====
+    findTriggeredRules(domain, riskClass) {
+        return this.activeRules.filter(r => {
+            const domainMatch = r.domains.includes(domain);
+            const riskMatch = !riskClass || r.riskClass === riskClass;
+            return domainMatch && riskMatch;
+        });
+    }
+}
+/**
+ * Create enforcement gates
+ */
+export function createGates(config) {
+    return new EnforcementGates(config);
+}
+//# sourceMappingURL=gates.js.map

package/v3/@claude-flow/guidance/dist/gateway.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Deterministic Tool Gateway
+ *
+ * Extends EnforcementGates with idempotency, schema validation,
+ * and budget metering. Every tool call passes through a deterministic
+ * pipeline: idempotency check -> schema validation -> budget check ->
+ * enforcement gates -> allow/deny.
+ *
+ * @module @claude-flow/guidance/gateway
+ */
+import { EnforcementGates } from './gates.js';
+import type { GateConfig } from './types.js';
+/**
+ * Schema definition for a tool's parameters
+ */
+export interface ToolSchema {
+    /** Tool name this schema applies to */
+    toolName: string;
+    /** Parameters that must be present */
+    requiredParams: string[];
+    /** Parameters that may be present */
+    optionalParams: string[];
+    /** Expected type for each parameter */
+    paramTypes: Record<string, 'string' | 'number' | 'boolean' | 'object' | 'array'>;
+    /** Maximum total serialized size of all parameters in bytes */
+    maxParamSize: number;
+    /** Optional whitelist of allowed values per parameter */
+    allowedValues?: Record<string, unknown[]>;
+}
+/**
+ * Multi-dimensional budget tracking
+ */
+export interface Budget {
+    tokenBudget: {
+        used: number;
+        limit: number;
+    };
+    toolCallBudget: {
+        used: number;
+        limit: number;
+    };
+    storageBudget: {
+        usedBytes: number;
+        limitBytes: number;
+    };
+    timeBudget: {
+        usedMs: number;
+        limitMs: number;
+    };
+    costBudget: {
+        usedUsd: number;
+        limitUsd: number;
+    };
+}
+/**
+ * Record of a previous tool call for idempotency
+ */
+export interface IdempotencyRecord {
+    /** SHA-256 of tool name + sorted params */
+    key: string;
+    /** Tool that was called */
+    toolName: string;
+    /** Hash of the parameters */
+    paramsHash: string;
+    /** Cached result from the call */
+    result: unknown;
+    /** When the call was recorded */
+    timestamp: number;
+    /** Time-to-live in milliseconds */
+    ttlMs: number;
+}
+/**
+ * Decision returned by the gateway for each tool call evaluation
+ */
+export interface GatewayDecision {
+    /** Whether the call is allowed */
+    allowed: boolean;
+    /** Human-readable reason for the decision */
+    reason: string;
+    /** Which gate produced the decision (or 'none' if allowed) */
+    gate: string;
+    /** Evidence of what was checked */
+    evidence: Record<string, unknown>;
+    /** Whether an idempotency cache hit occurred */
+    idempotencyHit: boolean;
+    /** Cached result if idempotency hit */
+    cachedResult?: unknown;
+    /** Remaining budget after this decision */
+    budgetRemaining?: Budget;
+}
+export interface ToolGatewayConfig {
+    /** Tool schemas for validation */
+    schemas?: ToolSchema[];
+    /** Budget limits (partial; defaults to Infinity for unset dimensions) */
+    budget?: Partial<Budget>;
+    /** Default TTL for idempotency records in milliseconds */
+    idempotencyTtlMs?: number;
+    /** Maximum idempotency cache entries (default 10000) */
+    maxCacheSize?: number;
+    /** If true, evidence must be non-empty for allow decisions */
+    requireEvidence?: boolean;
+    /** Gate configuration passed through to EnforcementGates */
+    gateConfig?: Partial<GateConfig>;
+}
+export declare class DeterministicToolGateway {
+    private readonly gates;
+    private readonly schemas;
+    private budget;
+    private readonly idempotencyTtlMs;
+    private readonly maxCacheSize;
+    private readonly requireEvidence;
+    private readonly idempotencyCache;
+    private lastCleanupTime;
+    private static readonly CLEANUP_INTERVAL_MS;
+    constructor(config?: ToolGatewayConfig);
+    /**
+     * Evaluate whether a tool call should be allowed.
+     *
+     * Pipeline:
+     * 1. Check idempotency cache
+     * 2. Validate params against schema
+     * 3. Check budget
+     * 4. Run EnforcementGates checks
+     * 5. Return decision with remaining budget
+     */
+    evaluate(toolName: string, params: Record<string, unknown>, context?: Record<string, unknown>): GatewayDecision;
+    /**
+     * Record a completed tool call.
+     * Updates budgets and stores the result in the idempotency cache.
+     */
+    recordCall(toolName: string, params: Record<string, unknown>, result: unknown, durationMs: number, tokenCount?: number): void;
+    /**
+     * Validate tool parameters against the registered schema.
+     * Returns valid:true if no schema is registered for the tool.
+     */
+    validateSchema(toolName: string, params: Record<string, unknown>): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Check whether all budget dimensions are within limits.
+     */
+    checkBudget(): {
+        withinBudget: boolean;
+        budgetStatus: Budget;
+    };
+    /**
+     * Compute a deterministic idempotency key from tool name and params.
+     * Uses SHA-256 of `toolName:sortedParamsJSON`.
+     */
+    getIdempotencyKey(toolName: string, params: Record<string, unknown>): string;
+    /**
+     * Reset all budget counters to zero.
+     */
+    resetBudget(): void;
+    /**
+     * Get a snapshot of the current budget.
+     */
+    getBudget(): Budget;
+    /**
+     * Get all idempotency records (including expired ones not yet cleaned).
+     */
+    getCallHistory(): IdempotencyRecord[];
+    /**
+     * Access the underlying EnforcementGates instance.
+     */
+    getGates(): EnforcementGates;
+    /**
+     * Remove expired idempotency records (batched on interval to avoid per-call overhead).
+     */
+    private maybeCleanExpiredIdempotency;
+    /**
+     * Compute a deterministic SHA-256 key from tool name and sorted params.
+     */
+    private computeIdempotencyKey;
+    /**
+     * Compute a SHA-256 hash of params only (for the IdempotencyRecord).
+     */
+    private computeParamsHash;
+    /**
+     * Recursively sort object keys for deterministic serialization.
+     */
+    private sortObject;
+    /**
+     * Determine the type string for a parameter value.
+     */
+    private getParamType;
+    /**
+     * Create a deep clone of the current budget.
+     */
+    private cloneBudget;
+    /**
+     * Merge a partial budget config with defaults.
+     */
+    private mergeBudget;
+    private cloneDefaultBudget;
+    /**
+     * Find which budget dimensions have been exceeded.
+     */
+    private findExceededBudgets;
+}
+/**
+ * Create a DeterministicToolGateway instance
+ */
+export declare function createToolGateway(config?: ToolGatewayConfig): DeterministicToolGateway;
+//# sourceMappingURL=gateway.d.ts.map