@claude-flow/security 3.0.0-alpha.9 → 3.0.0

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

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

@@ -1,279 +0,0 @@
-/**
- * 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);
-}