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

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);
+}

package/src/index.ts

@@ -109,6 +109,49 @@ export {
   type VerificationCode,
 } from './token-generator.js';
 
+// Tool-Output Guardrail (ADR-131 — closes OWASP ASI01 gap; ruvnet/ruflo#2149)
+export {
+  ToolOutputGuardrail,
+  createToolOutputGuardrail,
+  isToolOutputSafe,
+  type GuardrailConfig,
+  type GuardrailResult,
+  type GuardrailAction,
+  type InjectionFinding,
+  type InjectionSeverity,
+  type InjectionCategory,
+} from './tool-output-guardrail.js';
+
+// Agent Authorization Propagation (ADR-144 P1 — ruvnet/ruflo#2248)
+// Action-layer: SendMessage envelope + per-action scope check + MCP server
+// identity probe. Wraps the comms layer in P2; wraps the dispatcher in P3.
+export {
+  AgentAuthorizationPropagator,
+  AuthorizationPropagationError,
+  makeLegacyPermissiveScope,
+  type AuthScope,
+  type SendMessageEnvelope,
+  type ToolCallDecision,
+} from './authorization/propagator.js';
+
+// Plugin Integrity Verifier (ADR-145 P1 — ruvnet/ruflo#2254)
+// Install-layer: Ed25519 signature verification + trust-anchor allowlist.
+// Stage-2 semantic-intent scan (SCH defence) lands in P2.
+export {
+  PluginIntegrityVerifier,
+  canonicalize,
+  hashManifest,
+  fingerprint,
+  findAnchor,
+  type PluginManifest,
+  type SignedPluginManifest,
+  type TrustAnchor,
+  type TrustAnchors,
+  type VerificationStatus,
+  type VerificationResult,
+  type VerifierConfig,
+} from './plugins/integrity-verifier.js';
+
 // ============================================================================
 // Convenience Factory Functions
 // ============================================================================

package/src/plugins/integrity-verifier.ts

@@ -0,0 +1,265 @@
+/**
+ * PluginIntegrityVerifier — install-layer security for plugin supply chain.
+ *
+ * Implements P1 of ADR-145 (ruvnet/ruflo#2254): Stage-1 Ed25519 signature
+ * verification at `plugins install`. Stage-2 (semantic-intent scan against
+ * SCH attacks) lands in P2; per-namespace write ACLs land in P3-P4.
+ *
+ * Threat model
+ * ------------
+ * Ruflo's plugin install path fetches manifests from IPFS via Pinata with
+ * NO signature verification and NO intent analysis. Two attacks land today:
+ *
+ *   - DDIPE (arXiv:2604.03081): malicious logic embedded in plugin docs and
+ *     config templates. 11.6-33.5% bypass rate across 4 frameworks/5 models;
+ *     2.5% evade both detection and alignment. Stage-1 signing blocks the
+ *     static-payload variants.
+ *
+ *   - SCH (arXiv:2605.14460): malicious intent wrapped as natural-language
+ *     "compliance rules" in plugin descriptions. The agent generates the
+ *     harmful code at runtime — no static payload exists. 77.67% breach
+ *     success, 0.00% scanner detection. Stage-2 (P2) catches this; Stage-1
+ *     does not.
+ *
+ * Scope (P1)
+ * ----------
+ * - Ed25519 signature verification of a detached signature over the manifest.
+ * - Trust-anchor allowlist: the publisher's signing key fingerprint must be
+ *   in `trust-anchors.json`, gated on CODEOWNERS review.
+ * - Backwards compatible: default mode is warn-only. `CLAUDE_FLOW_STRICT_PLUGINS=true`
+ *   makes verification a hard gate.
+ *
+ * Non-goals (P1)
+ * --------------
+ * - Semantic intent scan (SCH defence). Lands in P2 with a pattern-rule
+ *   fallback for environments without LLM credentials.
+ * - Sandboxing the plugin runtime. Orthogonal blast-radius concern.
+ *
+ * Reference: ADR-145, arXiv:2605.14460 (SCH), arXiv:2604.03081 (DDIPE),
+ * arXiv:2604.16548 (Mnemonic Sovereignty survey).
+ */
+
+import { createHash } from 'node:crypto';
+import * as nodeCrypto from 'node:crypto';
+
+export interface PluginManifest {
+  readonly id: string;
+  readonly version: string;
+  /** Anything else; only `id` + `version` matter for the integrity hash. */
+  readonly [extra: string]: unknown;
+}
+
+export interface SignedPluginManifest {
+  readonly manifest: PluginManifest;
+  /** Hex-encoded SHA-256 of the canonical JSON serialisation of manifest. */
+  readonly manifestHash: string;
+  /** Hex-encoded detached Ed25519 signature over `manifestHash` bytes. */
+  readonly signature: string;
+  /** Hex-encoded Ed25519 public key of the signer. */
+  readonly publicKey: string;
+}
+
+export interface TrustAnchor {
+  /** Hex-encoded Ed25519 public key the publisher signs with. */
+  readonly publicKey: string;
+  /** Human-readable owner — for audit, not for trust decisions. */
+  readonly owner: string;
+  /** Optional ISO 8601 date after which this anchor is no longer trusted. */
+  readonly expiresAt?: string;
+  /** Optional plugin id glob this anchor is authoritative for (e.g. `@claude-flow/*`). */
+  readonly scope?: string;
+}
+
+export interface TrustAnchors {
+  readonly version: 1;
+  readonly anchors: ReadonlyArray<TrustAnchor>;
+}
+
+export type VerificationStatus =
+  | 'pass'
+  | 'signature-missing'
+  | 'signature-invalid'
+  | 'manifest-hash-mismatch'
+  | 'unknown-signer'
+  | 'signer-expired'
+  | 'signer-out-of-scope';
+
+export interface VerificationResult {
+  readonly status: VerificationStatus;
+  readonly pluginId: string;
+  readonly signerFingerprint?: string;
+  /** Verification timestamp — useful for telemetry correlation. */
+  readonly ts: number;
+  /** Operator-facing detail; do not parse — log only. */
+  readonly detail?: string;
+}
+
+export interface VerifierConfig {
+  readonly trustAnchors: TrustAnchors;
+  /**
+   * When true, `verify` returns the actual failure status. When false (legacy
+   * mode), `verify` returns the failure status BUT callers may choose to
+   * proceed with a warning — the strictness gate lives at the caller, not
+   * here, so the verifier itself is always pure.
+   */
+  readonly strict?: boolean;
+  /** Optional now-provider for tests. */
+  readonly now?: () => number;
+}
+
+/**
+ * Canonical JSON serialisation for hashing. Deterministic key ordering at
+ * every nesting level. Pure; identical input → identical output bytes.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']';
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalize(obj[k])).join(',') + '}';
+}
+
+/** Hex-encoded SHA-256 of the canonical-JSON manifest. */
+export function hashManifest(manifest: PluginManifest): string {
+  return createHash('sha256').update(canonicalize(manifest)).digest('hex');
+}
+
+/** Short fingerprint for telemetry — first 16 hex chars of the key. */
+export function fingerprint(publicKey: string): string {
+  return publicKey.slice(0, 16);
+}
+
+/**
+ * Find the trust anchor that vouches for a manifest. Returns the matched
+ * anchor (with anchor.publicKey === signer.publicKey) or null.
+ *
+ * Scope-matching uses a minimal glob: `*` at the end of the scope string
+ * matches any suffix. Empty/missing scope matches every plugin id.
+ */
+export function findAnchor(
+  anchors: ReadonlyArray<TrustAnchor>,
+  pluginId: string,
+  signerPublicKey: string,
+  now: number,
+): TrustAnchor | null {
+  for (const a of anchors) {
+    if (a.publicKey !== signerPublicKey) continue;
+    if (a.expiresAt && new Date(a.expiresAt).getTime() <= now) continue;
+    if (!a.scope || a.scope === '*' || a.scope === pluginId) return a;
+    if (a.scope.endsWith('*') && pluginId.startsWith(a.scope.slice(0, -1))) return a;
+  }
+  return null;
+}
+
+/**
+ * `PluginIntegrityVerifier` — Stage-1 verifier (signature + trust anchor).
+ *
+ * Pure-ish: holds the trust-anchor list and clock, no other state. Safe to
+ * construct per-invocation or share.
+ */
+export class PluginIntegrityVerifier {
+  constructor(private readonly config: VerifierConfig) {}
+
+  /**
+   * Verify a signed manifest. Returns the verification status; the caller
+   * decides what to do with `signature-missing` / `manifest-hash-mismatch`
+   * etc. based on its strict-mode policy.
+   */
+  async verify(signed: SignedPluginManifest): Promise<VerificationResult> {
+    const now = (this.config.now ?? Date.now)();
+    const pluginId = signed.manifest?.id ?? '<unknown>';
+
+    if (!signed.signature || !signed.publicKey) {
+      return { status: 'signature-missing', pluginId, ts: now };
+    }
+
+    // Re-hash the manifest and compare to the signed hash.
+    const recomputed = hashManifest(signed.manifest);
+    if (recomputed !== signed.manifestHash) {
+      return {
+        status: 'manifest-hash-mismatch',
+        pluginId,
+        signerFingerprint: fingerprint(signed.publicKey),
+        ts: now,
+        detail: `expected ${signed.manifestHash}, got ${recomputed}`,
+      };
+    }
+
+    // Find a trust anchor that vouches for this signer + plugin.
+    const anchor = findAnchor(this.config.trustAnchors.anchors, pluginId, signed.publicKey, now);
+    if (!anchor) {
+      return {
+        status: 'unknown-signer',
+        pluginId,
+        signerFingerprint: fingerprint(signed.publicKey),
+        ts: now,
+      };
+    }
+
+    // Ed25519 verify. Probe @noble/ed25519 (already a workspace dep); fall
+    // back to the failure status if it isn't resolvable in this environment
+    // (mirrors verify.mjs's #1880 precondition pattern).
+    const ed = await loadEd25519();
+    if (!ed) {
+      return {
+        status: 'signature-invalid',
+        pluginId,
+        signerFingerprint: fingerprint(signed.publicKey),
+        ts: now,
+        detail: '@noble/ed25519 not available — cannot verify',
+      };
+    }
+
+    // Required by @noble/ed25519 v2 for sync sha512.
+    if (!ed.etc.sha512Sync) {
+      ed.etc.sha512Sync = (...m: Uint8Array[]): Uint8Array => {
+        const h = nodeCrypto.createHash('sha512');
+        for (const x of m) h.update(x);
+        return h.digest();
+      };
+    }
+
+    let ok = false;
+    try {
+      const sigBytes = hexToBytes(signed.signature);
+      const msgBytes = hexToBytes(signed.manifestHash);
+      const pubBytes = hexToBytes(signed.publicKey);
+      ok = await ed.verify(sigBytes, msgBytes, pubBytes);
+    } catch {
+      ok = false;
+    }
+
+    if (!ok) {
+      return {
+        status: 'signature-invalid',
+        pluginId,
+        signerFingerprint: fingerprint(signed.publicKey),
+        ts: now,
+      };
+    }
+
+    return { status: 'pass', pluginId, signerFingerprint: fingerprint(signed.publicKey), ts: now };
+  }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length >>> 1);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.substr(i * 2, 2), 16);
+  return out;
+}
+
+interface NobleEd25519 {
+  verify(sig: Uint8Array, msg: Uint8Array, pub: Uint8Array): Promise<boolean>;
+  etc: { sha512Sync?: (...m: Uint8Array[]) => Uint8Array };
+}
+
+async function loadEd25519(): Promise<NobleEd25519 | null> {
+  try {
+    const mod = await import('@noble/ed25519');
+    return mod as unknown as NobleEd25519;
+  } catch {
+    return null;
+  }
+}