@claude-flow/security 3.0.0-alpha.1 → 3.0.0-alpha.11

package/src/application/index.ts

@@ -1,10 +1,10 @@
-/**
- * Security Application Layer - Public Exports
- *
- * @module v3/security/application
- */
-
-export {
-  SecurityApplicationService,
-  type SecurityAuditResult,
-} from './services/security-application-service.js';
+/**
+ * Security Application Layer - Public Exports
+ *
+ * @module v3/security/application
+ */
+
+export {
+  SecurityApplicationService,
+  type SecurityAuditResult,
+} from './services/security-application-service.js';

package/src/application/services/security-application-service.ts

@@ -1,193 +1,193 @@
-/**
- * Security Application Service - Application Layer
- *
- * Orchestrates security operations and provides simplified interface.
- *
- * @module v3/security/application/services
- */
-
-import { SecurityContext, PermissionLevel } from '../../domain/entities/security-context.js';
-import { SecurityDomainService, ValidationResult, ThreatDetectionResult } from '../../domain/services/security-domain-service.js';
-
-/**
- * Security audit result
- */
-export interface SecurityAuditResult {
-  passed: boolean;
-  score: number;
-  checks: Array<{
-    name: string;
-    passed: boolean;
-    severity: 'low' | 'medium' | 'high' | 'critical';
-    message: string;
-  }>;
-  recommendations: string[];
-}
-
-/**
- * Security Application Service
- */
-export class SecurityApplicationService {
-  private readonly domainService: SecurityDomainService;
-  private readonly contexts: Map<string, SecurityContext> = new Map();
-
-  constructor() {
-    this.domainService = new SecurityDomainService();
-  }
-
-  // ============================================================================
-  // Context Management
-  // ============================================================================
-
-  /**
-   * Create and register security context for agent
-   */
-  createAgentContext(agentId: string, role: string): SecurityContext {
-    const context = this.domainService.createAgentContext(agentId, role);
-    this.contexts.set(agentId, context);
-    return context;
-  }
-
-  /**
-   * Get security context
-   */
-  getContext(principalId: string): SecurityContext | undefined {
-    return this.contexts.get(principalId);
-  }
-
-  /**
-   * Remove security context
-   */
-  removeContext(principalId: string): boolean {
-    return this.contexts.delete(principalId);
-  }
-
-  // ============================================================================
-  // Validation
-  // ============================================================================
-
-  /**
-   * Validate path access
-   */
-  validatePath(path: string, principalId: string): ValidationResult {
-    const context = this.contexts.get(principalId);
-    if (!context) {
-      return {
-        valid: false,
-        errors: ['Security context not found'],
-        warnings: [],
-      };
-    }
-
-    return this.domainService.validatePath(path, context);
-  }
-
-  /**
-   * Validate command execution
-   */
-  validateCommand(command: string, principalId: string): ValidationResult {
-    const context = this.contexts.get(principalId);
-    if (!context) {
-      return {
-        valid: false,
-        errors: ['Security context not found'],
-        warnings: [],
-      };
-    }
-
-    return this.domainService.validateCommand(command, context);
-  }
-
-  /**
-   * Validate user input
-   */
-  validateInput(input: string): ValidationResult {
-    return this.domainService.validateInput(input);
-  }
-
-  /**
-   * Detect threats in content
-   */
-  detectThreats(content: string): ThreatDetectionResult {
-    return this.domainService.detectThreats(content);
-  }
-
-  // ============================================================================
-  // Audit
-  // ============================================================================
-
-  /**
-   * Run security audit on codebase
-   */
-  async auditCodebase(files: Array<{ path: string; content: string }>): Promise<SecurityAuditResult> {
-    const checks: SecurityAuditResult['checks'] = [];
-    const recommendations: string[] = [];
-    let criticalCount = 0;
-    let highCount = 0;
-
-    for (const file of files) {
-      const threats = this.domainService.detectThreats(file.content);
-
-      for (const threat of threats.threats) {
-        checks.push({
-          name: `${threat.type} in ${file.path}`,
-          passed: false,
-          severity: threat.severity,
-          message: threat.description,
-        });
-
-        if (threat.severity === 'critical') criticalCount++;
-        if (threat.severity === 'high') highCount++;
-      }
-
-      if (threats.safe) {
-        checks.push({
-          name: `Security check: ${file.path}`,
-          passed: true,
-          severity: 'low',
-          message: 'No threats detected',
-        });
-      }
-    }
-
-    // Generate recommendations
-    if (criticalCount > 0) {
-      recommendations.push('Address critical security issues immediately');
-    }
-    if (highCount > 0) {
-      recommendations.push('Review and fix high-severity findings');
-    }
-    recommendations.push('Run regular security scans');
-    recommendations.push('Keep dependencies updated');
-
-    // Calculate score
-    const totalChecks = checks.length;
-    const passedChecks = checks.filter((c) => c.passed).length;
-    const score = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 100;
-
-    return {
-      passed: criticalCount === 0 && highCount === 0,
-      score,
-      checks,
-      recommendations,
-    };
-  }
-
-  /**
-   * Check if operation is allowed
-   */
-  isOperationAllowed(
-    principalId: string,
-    operation: 'path' | 'command',
-    target: string
-  ): boolean {
-    const context = this.contexts.get(principalId);
-    if (!context || context.isExpired()) return false;
-
-    if (operation === 'path') {
-      return context.canAccessPath(target);
-    } else {
-      return context.canExecuteCommand(target);
-    }
-  }
-}
+/**
+ * Security Application Service - Application Layer
+ *
+ * Orchestrates security operations and provides simplified interface.
+ *
+ * @module v3/security/application/services
+ */
+
+import { SecurityContext, PermissionLevel } from '../../domain/entities/security-context.js';
+import { SecurityDomainService, ValidationResult, ThreatDetectionResult } from '../../domain/services/security-domain-service.js';
+
+/**
+ * Security audit result
+ */
+export interface SecurityAuditResult {
+  passed: boolean;
+  score: number;
+  checks: Array<{
+    name: string;
+    passed: boolean;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    message: string;
+  }>;
+  recommendations: string[];
+}
+
+/**
+ * Security Application Service
+ */
+export class SecurityApplicationService {
+  private readonly domainService: SecurityDomainService;
+  private readonly contexts: Map<string, SecurityContext> = new Map();
+
+  constructor() {
+    this.domainService = new SecurityDomainService();
+  }
+
+  // ============================================================================
+  // Context Management
+  // ============================================================================
+
+  /**
+   * Create and register security context for agent
+   */
+  createAgentContext(agentId: string, role: string): SecurityContext {
+    const context = this.domainService.createAgentContext(agentId, role);
+    this.contexts.set(agentId, context);
+    return context;
+  }
+
+  /**
+   * Get security context
+   */
+  getContext(principalId: string): SecurityContext | undefined {
+    return this.contexts.get(principalId);
+  }
+
+  /**
+   * Remove security context
+   */
+  removeContext(principalId: string): boolean {
+    return this.contexts.delete(principalId);
+  }
+
+  // ============================================================================
+  // Validation
+  // ============================================================================
+
+  /**
+   * Validate path access
+   */
+  validatePath(path: string, principalId: string): ValidationResult {
+    const context = this.contexts.get(principalId);
+    if (!context) {
+      return {
+        valid: false,
+        errors: ['Security context not found'],
+        warnings: [],
+      };
+    }
+
+    return this.domainService.validatePath(path, context);
+  }
+
+  /**
+   * Validate command execution
+   */
+  validateCommand(command: string, principalId: string): ValidationResult {
+    const context = this.contexts.get(principalId);
+    if (!context) {
+      return {
+        valid: false,
+        errors: ['Security context not found'],
+        warnings: [],
+      };
+    }
+
+    return this.domainService.validateCommand(command, context);
+  }
+
+  /**
+   * Validate user input
+   */
+  validateInput(input: string): ValidationResult {
+    return this.domainService.validateInput(input);
+  }
+
+  /**
+   * Detect threats in content
+   */
+  detectThreats(content: string): ThreatDetectionResult {
+    return this.domainService.detectThreats(content);
+  }
+
+  // ============================================================================
+  // Audit
+  // ============================================================================
+
+  /**
+   * Run security audit on codebase
+   */
+  async auditCodebase(files: Array<{ path: string; content: string }>): Promise<SecurityAuditResult> {
+    const checks: SecurityAuditResult['checks'] = [];
+    const recommendations: string[] = [];
+    let criticalCount = 0;
+    let highCount = 0;
+
+    for (const file of files) {
+      const threats = this.domainService.detectThreats(file.content);
+
+      for (const threat of threats.threats) {
+        checks.push({
+          name: `${threat.type} in ${file.path}`,
+          passed: false,
+          severity: threat.severity,
+          message: threat.description,
+        });
+
+        if (threat.severity === 'critical') criticalCount++;
+        if (threat.severity === 'high') highCount++;
+      }
+
+      if (threats.safe) {
+        checks.push({
+          name: `Security check: ${file.path}`,
+          passed: true,
+          severity: 'low',
+          message: 'No threats detected',
+        });
+      }
+    }
+
+    // Generate recommendations
+    if (criticalCount > 0) {
+      recommendations.push('Address critical security issues immediately');
+    }
+    if (highCount > 0) {
+      recommendations.push('Review and fix high-severity findings');
+    }
+    recommendations.push('Run regular security scans');
+    recommendations.push('Keep dependencies updated');
+
+    // Calculate score
+    const totalChecks = checks.length;
+    const passedChecks = checks.filter((c) => c.passed).length;
+    const score = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 100;
+
+    return {
+      passed: criticalCount === 0 && highCount === 0,
+      score,
+      checks,
+      recommendations,
+    };
+  }
+
+  /**
+   * Check if operation is allowed
+   */
+  isOperationAllowed(
+    principalId: string,
+    operation: 'path' | 'command',
+    target: string
+  ): boolean {
+    const context = this.contexts.get(principalId);
+    if (!context || context.isExpired()) return false;
+
+    if (operation === 'path') {
+      return context.canAccessPath(target);
+    } else {
+      return context.canExecuteCommand(target);
+    }
+  }
+}

package/src/authorization/propagator.ts

@@ -0,0 +1,279 @@
+/**
+ * AgentAuthorizationPropagator — action-layer security for agent delegation.
+ *
+ * Implements P1 of ADR-144 (ruvnet/ruflo#2248): scope-envelope on SendMessage
+ * + per-action authorization checks. P2-P5 wire this into the comms layer,
+ * MCP dispatcher, MCP auth validator, and provenance log respectively.
+ *
+ * Threat model
+ * ------------
+ * When agent A delegates a task to agent B via SendMessage, B can today
+ * escalate the granted scope by calling tools A was never authorized to
+ * invoke. RBAC/ABAC on agent roles do not solve this — roles don't compose
+ * under dynamic LLM delegation (arXiv:2605.05440, Grade A formal analysis).
+ *
+ * The fix is scope-based propagation: every SendMessage carries an
+ * `AuthScope` that is *monotonically reducing* — each hop can drop tools or
+ * servers from the granted set but never add them. This is the same shape
+ * as OAuth scope reduction; adding back a tool requires talking to the
+ * original principal out-of-band.
+ *
+ * Scope
+ * -----
+ * - P1 (this file): the component, the envelope, the type-level invariants.
+ *   No call sites yet — adding the wrapping/enforcement in P2-P4.
+ * - All operations synchronous, pure, allocation-light. Targets < 1 ms p99
+ *   for `wrapOutbound` + `checkToolCall` so it can sit on every SendMessage.
+ *
+ * Backwards compatibility
+ * -----------------------
+ * `scope` on the envelope is optional in v1. Agents without scope set
+ * operate in legacy permissive mode (all tools allowed, depth unlimited,
+ * server auth unchecked). `CLAUDE_FLOW_STRICT_AUTH=true` enables enforcement.
+ *
+ * Reference: ADR-144, arXiv:2605.05440 (Authorization Propagation),
+ * arXiv:2605.28914 (AIRGuard), arXiv:2605.22333 (MCP auth survey).
+ */
+
+/** Scope granted to an agent at a delegation hop. Monotonically reducing. */
+export interface AuthScope {
+  /** Stable identifier of the originating principal (agent or user). */
+  readonly principalId: string;
+  /** MCP tool IDs this scope is allowed to call. */
+  readonly grantedTools: ReadonlyArray<string>;
+  /** MCP server IDs whose tool responses this scope will accept. */
+  readonly grantedServers: ReadonlyArray<string>;
+  /** Max remaining delegation hops. Decrements on every `wrapOutbound`. */
+  readonly delegationDepth: number;
+  /** Unix ms after which this scope is no longer valid. */
+  readonly expiresAt: number;
+  /**
+   * Optional opaque ID for cross-referencing with ADR-144 P5 provenance log
+   * and ADR-146 telemetry events. Callers should treat as a correlation
+   * handle, not a security claim.
+   */
+  readonly scopeId?: string;
+}
+
+/** Envelope shape attached to every SendMessage when strict-auth is on. */
+export interface SendMessageEnvelope<T = unknown> {
+  /** Authorization scope governing what the receiver may do. */
+  readonly scope: AuthScope;
+  /** The original SendMessage payload, untouched. */
+  readonly payload: T;
+}
+
+/** Decision returned by `checkToolCall`. Never throws. */
+export interface ToolCallDecision {
+  readonly allowed: boolean;
+  /** Human-readable reason; stable enough to match in tests/telemetry. */
+  readonly reason?:
+    | 'tool-not-in-scope'
+    | 'server-not-in-scope'
+    | 'scope-expired'
+    | 'delegation-depth-exhausted'
+    | 'principal-mismatch';
+}
+
+/**
+ * Wrap-failure reasons surfaced to callers as a typed error. We use a
+ * discriminated union rather than throwing so the comms layer (P2) can
+ * decide whether to drop the SendMessage or surface to the user.
+ */
+export class AuthorizationPropagationError extends Error {
+  constructor(
+    public readonly code:
+      | 'scope-cannot-grow'
+      | 'depth-underflow'
+      | 'scope-expired'
+      | 'principal-mismatch',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'AuthorizationPropagationError';
+  }
+}
+
+/**
+ * Construct a default permissive scope. Used in legacy mode when no scope
+ * was attached upstream. Callers SHOULD migrate to explicit scopes; this is
+ * here so the propagator never has to special-case "no scope".
+ */
+export function makeLegacyPermissiveScope(principalId = 'legacy'): AuthScope {
+  return {
+    principalId,
+    grantedTools: ['*'],     // sentinel — see `checkToolCall`
+    grantedServers: ['*'],
+    delegationDepth: Number.MAX_SAFE_INTEGER,
+    expiresAt: Number.MAX_SAFE_INTEGER,
+  };
+}
+
+/**
+ * `AgentAuthorizationPropagator` — the load-bearing component for ADR-144.
+ *
+ * Construction is intentionally cheap (no I/O, no async). Callers can build
+ * a fresh instance per task without overhead, or share one — it holds no
+ * mutable state beyond the optional provenance buffer.
+ */
+export class AgentAuthorizationPropagator {
+  /**
+   * In-memory provenance buffer. P5 will flush this to the structured
+   * telemetry sink (ADR-146 GuardrailEvent shape). For P1 we just retain
+   * the last N events for inspection/tests.
+   */
+  private readonly provenance: Array<{
+    agentId: string;
+    toolId: string;
+    scope: AuthScope;
+    outcome: 'allowed' | 'denied';
+    reason?: string;
+    ts: number;
+  }> = [];
+
+  constructor(private readonly opts: { provenanceBufferMax?: number } = {}) {}
+
+  /**
+   * Attach a reduced scope to an outbound SendMessage.
+   *
+   * Invariants enforced (throws `AuthorizationPropagationError` on violation):
+   *   - newly granted tools MUST be a subset of `currentScope.grantedTools`
+   *   - newly granted servers MUST be a subset of `currentScope.grantedServers`
+   *   - delegationDepth MUST decrement by ≥ 1 (must remain ≥ 0)
+   *   - principalId is propagated unchanged
+   *   - expiresAt cannot be extended; copied from the holder
+   */
+  wrapOutbound<T>(
+    payload: T,
+    currentScope: AuthScope,
+    requested: { tools?: ReadonlyArray<string>; servers?: ReadonlyArray<string> } = {},
+  ): SendMessageEnvelope<T> {
+    if (currentScope.delegationDepth <= 0) {
+      throw new AuthorizationPropagationError(
+        'depth-underflow',
+        `cannot delegate further — delegationDepth=${currentScope.delegationDepth}`,
+      );
+    }
+    const now = Date.now();
+    if (currentScope.expiresAt <= now) {
+      throw new AuthorizationPropagationError(
+        'scope-expired',
+        `scope expired at ${new Date(currentScope.expiresAt).toISOString()}`,
+      );
+    }
+
+    const reducedTools = subsetOrThrow(
+      currentScope.grantedTools,
+      requested.tools ?? currentScope.grantedTools,
+      'tools',
+    );
+    const reducedServers = subsetOrThrow(
+      currentScope.grantedServers,
+      requested.servers ?? currentScope.grantedServers,
+      'servers',
+    );
+
+    const reducedScope: AuthScope = {
+      principalId: currentScope.principalId,
+      grantedTools: reducedTools,
+      grantedServers: reducedServers,
+      delegationDepth: currentScope.delegationDepth - 1,
+      expiresAt: currentScope.expiresAt,
+      scopeId: currentScope.scopeId,
+    };
+
+    return { scope: reducedScope, payload };
+  }
+
+  /**
+   * Validate a single tool call against a scope. Pure; never throws. Use the
+   * result's `allowed` to make the dispatch decision.
+   */
+  checkToolCall(
+    toolId: string,
+    scope: AuthScope,
+    opts: { serverId?: string; now?: number } = {},
+  ): ToolCallDecision {
+    const now = opts.now ?? Date.now();
+    if (scope.expiresAt <= now) return { allowed: false, reason: 'scope-expired' };
+
+    if (!matchesScopeList(scope.grantedTools, toolId)) {
+      return { allowed: false, reason: 'tool-not-in-scope' };
+    }
+    if (opts.serverId && !matchesScopeList(scope.grantedServers, opts.serverId)) {
+      return { allowed: false, reason: 'server-not-in-scope' };
+    }
+    return { allowed: true };
+  }
+
+  /**
+   * Verify an MCP server presented a valid credential before its response is
+   * consumed. P1 ships a permissive default (any non-empty credential is
+   * accepted) so the API is stable; P4 wires this to a real validator.
+   *
+   * Returns `false` on missing/empty credential; callers MUST treat `false`
+   * as a hard reject (same rule as ADR-131 reject findings).
+   */
+  verifyServerAuth(serverId: string, credential: unknown): boolean {
+    if (!serverId || typeof serverId !== 'string') return false;
+    if (credential == null) return false;
+    if (typeof credential === 'string' && credential.trim().length === 0) return false;
+    return true;
+  }
+
+  /**
+   * Record an action in the provenance buffer. P5 will route to telemetry;
+   * P1 keeps the last N events for test inspection and post-incident audit.
+   */
+  recordAction(
+    agentId: string,
+    toolId: string,
+    scope: AuthScope,
+    outcome: 'allowed' | 'denied',
+    reason?: string,
+  ): void {
+    const max = this.opts.provenanceBufferMax ?? 1024;
+    this.provenance.push({ agentId, toolId, scope, outcome, reason, ts: Date.now() });
+    if (this.provenance.length > max) this.provenance.splice(0, this.provenance.length - max);
+  }
+
+  /** Read-only view of recorded provenance for tests + audit CLI (P5). */
+  getProvenance(): ReadonlyArray<{
+    agentId: string;
+    toolId: string;
+    scope: AuthScope;
+    outcome: 'allowed' | 'denied';
+    reason?: string;
+    ts: number;
+  }> {
+    return this.provenance.slice();
+  }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function subsetOrThrow(
+  parent: ReadonlyArray<string>,
+  requested: ReadonlyArray<string>,
+  kind: 'tools' | 'servers',
+): ReadonlyArray<string> {
+  if (parent.includes('*')) return Array.from(new Set(requested));
+  for (const item of requested) {
+    if (!parent.includes(item) && item !== '*') {
+      throw new AuthorizationPropagationError(
+        'scope-cannot-grow',
+        `cannot grant ${kind} '${item}' — not in parent scope`,
+      );
+    }
+  }
+  // De-duplicate; preserve requested order
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const r of requested) if (!seen.has(r)) (seen.add(r), out.push(r));
+  return out;
+}
+
+function matchesScopeList(list: ReadonlyArray<string>, item: string): boolean {
+  if (list.includes('*')) return true;
+  return list.includes(item);
+}