claude-flow 3.25.5 → 3.26.0

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

@@ -1,302 +0,0 @@
-/**
- * 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

@@ -1,206 +0,0 @@
-/**
- * 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