@graphorin/agent 0.6.0 → 0.7.0

package/src/lateral-leak/causality-monitor.ts

@@ -0,0 +1,221 @@
+/**
+ * `CausalityMonitor` - lateral-leak defense primitive that maintains
+ * a per-`RunContext` `causalityChain` of bounded depth and refuses
+ * to let an assistant message reference information about a denied
+ * earlier action.
+ *
+ * The monitor is opt-in: agents declare `causalityMonitor:
+ * { strictness, denialPatterns?, ... }` on `createAgent({...})`.
+ * When the field is absent, the runtime instantiates a no-op monitor
+ * that records nothing and never flags.
+ *
+ * @packageDocumentation
+ */
+
+import type { LateralLeakVector } from '@graphorin/core';
+
+/**
+ * Operator-tunable strictness level. Default `'detect-and-flag'`
+ * for cloud-tier providers; `'detect'` for loopback providers;
+ * `'off'` for v0.1-alpha backward compatibility.
+ *
+ * @stable
+ */
+export type CausalityMonitorStrictness = 'off' | 'detect' | 'detect-and-flag' | 'detect-and-block';
+
+/**
+ * Per-agent configuration accepted by `createAgent({ causalityMonitor })`.
+ *
+ * @stable
+ */
+export interface CausalityMonitorConfig {
+  readonly strictness: CausalityMonitorStrictness;
+  /** Maximum depth of the chain. Default `32`. */
+  readonly maxChainDepth?: number;
+  /** Operator-extensible denial patterns. */
+  readonly denialPatterns?: ReadonlyArray<RegExp>;
+  /**
+   * When `true`, emit the chain on every `checkMessage(...)` call
+   * (high-cardinality; opt-in for compliance audits). Default
+   * `false` - only emit on detected leaks.
+   */
+  readonly auditAllChains?: boolean;
+}
+
+/**
+ * Default denial-pattern catalogue. The agent runtime extends this
+ * list when the operator supplies their own patterns.
+ *
+ * @stable
+ */
+export const DEFAULT_DENIAL_PATTERNS: ReadonlyArray<RegExp> = [
+  /SecretAccessDenied/i,
+  /ToolApprovalDenied/i,
+  /HandoffPermissionDenied/i,
+  /SandboxViolation/i,
+];
+
+/** Default chain depth when not specified. */
+export const DEFAULT_MAX_CHAIN_DEPTH = 32;
+
+/**
+ * Result returned by {@link CausalityMonitor.checkMessage}.
+ *
+ * @stable
+ */
+export interface CausalityMonitorCheck {
+  readonly leakDetected: boolean;
+  readonly severity: 'info' | 'warn' | 'block';
+  readonly causalityChain: ReadonlyArray<string>;
+  readonly matchedPattern?: string;
+  readonly decision: 'detect' | 'flag' | 'strip' | 'block';
+  readonly vector: LateralLeakVector;
+}
+
+/**
+ * In-memory primitive instantiated per `RunContext`. Bounded-depth
+ * append discipline keeps the memory footprint trivial even on long
+ * runs.
+ *
+ * @stable
+ */
+export class CausalityMonitor {
+  readonly strictness: CausalityMonitorStrictness;
+  readonly maxChainDepth: number;
+  readonly denialPatterns: ReadonlyArray<RegExp>;
+  readonly auditAllChains: boolean;
+  #chain: string[] = [];
+
+  constructor(cfg: CausalityMonitorConfig) {
+    this.strictness = cfg.strictness;
+    this.maxChainDepth = cfg.maxChainDepth ?? DEFAULT_MAX_CHAIN_DEPTH;
+    this.denialPatterns = cfg.denialPatterns
+      ? [...DEFAULT_DENIAL_PATTERNS, ...cfg.denialPatterns]
+      : DEFAULT_DENIAL_PATTERNS;
+    this.auditAllChains = cfg.auditAllChains ?? false;
+  }
+
+  /** Snapshot the current causality chain. */
+  get chain(): ReadonlyArray<string> {
+    return this.#chain.slice();
+  }
+
+  /**
+   * Append an entry to the causality chain, dropping the oldest
+   * when the chain exceeds `maxChainDepth`. Bounded-length, no PII,
+   * no secret values - entries are short opaque strings like
+   * `tool:slack-notify`, `tool.error:SecretAccessDenied`,
+   * `subagent:research-east`, `compaction:auto-trigger`.
+   */
+  recordCall(entry: string): void {
+    if (this.strictness === 'off') return;
+    if (entry.length === 0) return;
+    this.#chain.push(entry);
+    if (this.#chain.length > this.maxChainDepth) {
+      this.#chain.shift();
+    }
+  }
+
+  /** Reset the chain - e.g. on `agent.run` boundary. */
+  reset(): void {
+    this.#chain = [];
+  }
+
+  /**
+   * Inspect a candidate assistant-visible string and return whether
+   * the lateral-leak defense should fire. Pure decision based on
+   * the current chain + the operator-extensible denial patterns.
+   */
+  checkMessage(content: string): CausalityMonitorCheck {
+    if (this.strictness === 'off') {
+      return {
+        leakDetected: false,
+        severity: 'info',
+        causalityChain: [],
+        decision: 'detect',
+        vector: 'causality-laundering',
+      };
+    }
+    const chainHasDenial = this.#chain.some((entry) =>
+      this.denialPatterns.some((pat) => pat.test(entry)),
+    );
+    if (!chainHasDenial) {
+      return {
+        leakDetected: false,
+        severity: 'info',
+        causalityChain: this.chain,
+        decision: 'detect',
+        vector: 'causality-laundering',
+      };
+    }
+    let matchedPattern: string | undefined;
+    for (const pat of this.denialPatterns) {
+      if (pat.test(content)) {
+        matchedPattern = pat.source;
+        break;
+      }
+    }
+    const leakDetected = matchedPattern !== undefined;
+    if (!leakDetected) {
+      return {
+        leakDetected: false,
+        severity: 'info',
+        causalityChain: this.chain,
+        decision: 'detect',
+        vector: 'causality-laundering',
+      };
+    }
+    switch (this.strictness) {
+      case 'detect':
+        return {
+          leakDetected: true,
+          severity: 'info',
+          causalityChain: this.chain,
+          ...(matchedPattern !== undefined ? { matchedPattern } : {}),
+          decision: 'detect',
+          vector: 'causality-laundering',
+        };
+      case 'detect-and-flag':
+        return {
+          leakDetected: true,
+          severity: 'warn',
+          causalityChain: this.chain,
+          ...(matchedPattern !== undefined ? { matchedPattern } : {}),
+          decision: 'flag',
+          vector: 'causality-laundering',
+        };
+      case 'detect-and-block':
+        return {
+          leakDetected: true,
+          severity: 'block',
+          causalityChain: this.chain,
+          ...(matchedPattern !== undefined ? { matchedPattern } : {}),
+          decision: 'block',
+          vector: 'causality-laundering',
+        };
+      default: {
+        const _exhaustive: never = this.strictness;
+        void _exhaustive;
+        return {
+          leakDetected: false,
+          severity: 'info',
+          causalityChain: this.chain,
+          decision: 'detect',
+          vector: 'causality-laundering',
+        };
+      }
+    }
+  }
+
+  /**
+   * Drain the chain to the audit log on `agent.run` completion or
+   * `agent.abort`. The runtime supplies the audit emitter - the
+   * primitive itself is storage-agnostic.
+   */
+  flush(reason: 'agent.run.complete' | 'agent.abort'): {
+    readonly chain: ReadonlyArray<string>;
+    readonly reason: 'agent.run.complete' | 'agent.abort';
+  } {
+    return { chain: this.chain, reason };
+  }
+}

package/src/lateral-leak/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Lateral-leak defense layer aggregate exports.
+ *
+ * The three primitives compose orthogonally with the four other
+ * security boundaries (sub-agent secrets isolation, handoff input
+ * filter, outbound redaction, inbound sanitization).
+ *
+ * @packageDocumentation
+ */
+
+export {
+  CausalityMonitor,
+  type CausalityMonitorCheck,
+  type CausalityMonitorConfig,
+  type CausalityMonitorStrictness,
+  DEFAULT_DENIAL_PATTERNS,
+  DEFAULT_MAX_CHAIN_DEPTH,
+} from './causality-monitor.js';
+export {
+  type ChildTrustInput,
+  type ContentOriginKind,
+  computeSourceTrust,
+  evaluateMerge,
+  type MergeBiasDecision,
+  type MergeGuardConfig,
+  type TrustClass,
+} from './merge-guard.js';
+export {
+  type GuardOutcome,
+  guardOutboundContent,
+  type ProtocolBoundary,
+  type ProtocolEscapePolicy,
+  type ProtocolGuardConfig,
+  resolvePolicy,
+} from './protocol-guard.js';

package/src/lateral-leak/merge-guard.ts

@@ -0,0 +1,151 @@
+/**
+ * `MergeAgentSidewaysInjectionGuard` - layered on top of the
+ * `Agent.fanOut(...)` `'judge-merge'` strategy. Computes a
+ * per-child `sourceTrust` score in `[0.0, 1.0]` and flags merges
+ * where a low-trust child's contribution-weight exceeds the
+ * configured `maxLowTrustWeight` threshold.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Trust-class baseline used by the guard's `sourceTrust`
+ * computation. Mirrors the DEC-149 trust-class taxonomy from
+ * `@graphorin/provider`.
+ *
+ * @stable
+ */
+export type TrustClass = 'loopback' | 'public-tls' | 'public-mtls' | 'untrusted-skill';
+
+const TRUST_CLASS_BASELINE: Record<TrustClass, number> = {
+  loopback: 0.9,
+  'public-tls': 0.7,
+  'public-mtls': 0.8,
+  'untrusted-skill': 0.3,
+};
+
+/**
+ * Tool-source provenance multiplier. Mirrors the `ContentOrigin`
+ * annotation from `@graphorin/memory.context-engine`.
+ *
+ * @stable
+ */
+export type ContentOriginKind =
+  | 'built-in'
+  | 'user-defined'
+  | 'trusted-skill'
+  | 'untrusted-skill'
+  | 'mcp'
+  | 'web-search';
+
+const ORIGIN_MULTIPLIER: Record<ContentOriginKind, number> = {
+  'built-in': 1.0,
+  'user-defined': 0.9,
+  'trusted-skill': 0.85,
+  'untrusted-skill': 0.4,
+  mcp: 0.7,
+  'web-search': 0.5,
+};
+
+/**
+ * Per-agent guard configuration accepted by
+ * `createAgent({ mergeGuard })`.
+ *
+ * @stable
+ */
+export interface MergeGuardConfig {
+  readonly strictness: 'off' | 'detect' | 'detect-and-flag' | 'detect-and-block';
+  /** Default `0.3`. */
+  readonly maxLowTrustWeight?: number;
+  /** Default `0.5`. */
+  readonly lowTrustThreshold?: number;
+  /** Operator overrides for known agent ids. */
+  readonly sourceTrustOverrides?: Readonly<Record<string, number>>;
+}
+
+/**
+ * Per-child input descriptor for {@link computeSourceTrust}.
+ *
+ * @stable
+ */
+export interface ChildTrustInput {
+  readonly agentId: string;
+  readonly trustClass: TrustClass;
+  readonly origin: ContentOriginKind;
+  /** Rolling trust score in `[0.0, 1.0]`. Defaults to `1.0`. */
+  readonly historyAdjustment?: number;
+}
+
+/**
+ * Compose `baseline * provenance * historyAdjustment` and clamp.
+ *
+ * @stable
+ */
+export function computeSourceTrust(
+  input: ChildTrustInput,
+  overrides: Readonly<Record<string, number>> = {},
+): number {
+  const override = overrides[input.agentId];
+  if (override !== undefined) return Math.max(0, Math.min(1, override));
+  const baseline = TRUST_CLASS_BASELINE[input.trustClass];
+  const provenance = ORIGIN_MULTIPLIER[input.origin];
+  const history = input.historyAdjustment ?? 1.0;
+  return Math.max(0, Math.min(1, baseline * provenance * history));
+}
+
+/**
+ * Pure decision returned by {@link evaluateMerge}.
+ *
+ * @stable
+ */
+export interface MergeBiasDecision {
+  readonly biased: boolean;
+  readonly offendingChild?: string;
+  readonly contributionWeight?: number;
+  readonly sourceTrust?: number;
+  readonly decision: 'pass-through' | 'flag' | 'block';
+}
+
+/**
+ * Evaluate whether the merge is biased - a child with
+ * `sourceTrust < lowTrustThreshold` contributing more than
+ * `maxLowTrustWeight` of the merged output.
+ *
+ * Inputs are pre-computed per-child trust scores together with the
+ * estimated contribution weights (token-count overlap between each
+ * child's output and the merged output, normalized to sum to ~1.0).
+ *
+ * @stable
+ */
+export function evaluateMerge(
+  perChild: ReadonlyArray<{
+    readonly agentId: string;
+    readonly sourceTrust: number;
+    readonly contributionWeight: number;
+  }>,
+  cfg: MergeGuardConfig,
+): MergeBiasDecision {
+  if (cfg.strictness === 'off') {
+    return { biased: false, decision: 'pass-through' };
+  }
+  const lowTrustThreshold = cfg.lowTrustThreshold ?? 0.5;
+  const maxLowTrustWeight = cfg.maxLowTrustWeight ?? 0.3;
+  for (const child of perChild) {
+    if (child.sourceTrust < lowTrustThreshold && child.contributionWeight > maxLowTrustWeight) {
+      const decision: MergeBiasDecision['decision'] =
+        cfg.strictness === 'detect-and-block'
+          ? 'block'
+          : cfg.strictness === 'detect-and-flag'
+            ? 'flag'
+            : 'pass-through';
+      return {
+        biased: true,
+        offendingChild: child.agentId,
+        contributionWeight: child.contributionWeight,
+        sourceTrust: child.sourceTrust,
+        decision,
+      };
+    }
+  }
+  return { biased: false, decision: 'pass-through' };
+}

package/src/lateral-leak/protocol-guard.ts

@@ -0,0 +1,222 @@
+/**
+ * Protocol/header injection guard - escapes control characters in
+ * tool result bodies before they cross internal-service delivery
+ * boundaries (SSE, WebSocket, REST body, HTTP header, audit row).
+ *
+ * The default policy mirrors the deployment-posture matrix from the
+ * lateral-leak design (DEC-171 / suggested ADR-059):
+ *
+ * - `'sse' | 'http-header'`  → `'strict'`  (escape control chars to
+ *   `\xNN` hex literals; the safest default for cleartext frame
+ *   protocols).
+ * - `'ws' | 'rest-body'`     → `'replace'` (replace with the Unicode
+ *   replacement character `\uFFFD`).
+ * - `'audit'`                → `'strict'`  (regulated deployments).
+ * - `'reject'` is operator opt-in - the guard throws
+ *   {@link ProtocolInjectionRejectError} when control characters are
+ *   detected.
+ *
+ * @packageDocumentation
+ */
+
+import { ProtocolInjectionRejectError } from '../errors/index.js';
+
+/**
+ * Per-boundary identifier used by the runtime when calling the
+ * guard.
+ *
+ * @stable
+ */
+export type ProtocolBoundary = 'sse' | 'http-header' | 'ws' | 'rest-body' | 'audit';
+
+/**
+ * Per-boundary escape policy.
+ *
+ * @stable
+ */
+export type ProtocolEscapePolicy = 'strict' | 'replace' | 'reject';
+
+/**
+ * Configurable per-boundary policy table. Operators may override
+ * specific boundaries via `Agent.protocolGuard?: { ... }`.
+ *
+ * @stable
+ */
+export interface ProtocolGuardConfig {
+  readonly sse?: ProtocolEscapePolicy;
+  readonly httpHeader?: ProtocolEscapePolicy;
+  readonly ws?: ProtocolEscapePolicy;
+  readonly restBody?: ProtocolEscapePolicy;
+  readonly audit?: ProtocolEscapePolicy;
+}
+
+/**
+ * Resolved policy lookup. Pure function - no side effects.
+ *
+ * @stable
+ */
+export function resolvePolicy(
+  boundary: ProtocolBoundary,
+  cfg: ProtocolGuardConfig = {},
+): ProtocolEscapePolicy {
+  switch (boundary) {
+    case 'sse':
+      return cfg.sse ?? 'strict';
+    case 'http-header':
+      return cfg.httpHeader ?? 'strict';
+    case 'ws':
+      return cfg.ws ?? 'replace';
+    case 'rest-body':
+      return cfg.restBody ?? 'replace';
+    case 'audit':
+      return cfg.audit ?? 'strict';
+    default: {
+      const _exhaustive: never = boundary;
+      void _exhaustive;
+      return 'strict';
+    }
+  }
+}
+
+// Control-character catalogue used to detect injection attempts at
+// the framework's outbound delivery boundaries. Building the regex
+// programmatically avoids embedding control bytes in the source -
+// the bytes are exactly the ones a malicious tool result might
+// inject to escape framing on cleartext protocols.
+function buildControlCharsRegex(): RegExp {
+  const codePoints: number[] = [];
+  for (let n = 0; n < 0x20; n++) {
+    if (n === 0x09 || n === 0x0a || n === 0x0d) continue;
+    codePoints.push(n);
+  }
+  codePoints.push(0x7f);
+  const cls = codePoints.map((c) => `\\x${c.toString(16).padStart(2, '0')}`).join('');
+  return new RegExp(`[${cls}]`, 'g');
+}
+const CONTROL_CHARS_RE = buildControlCharsRegex();
+const SSE_FRAME_RE = /\r?\n\r?\n/g;
+const HEADER_CRLF_RE = /\r\n/g;
+
+/**
+ * Outcome of {@link guardOutboundContent}.
+ *
+ * @stable
+ */
+export interface GuardOutcome {
+  readonly content: string;
+  readonly escapedCharCount: number;
+  readonly matchedPattern?: string;
+  readonly decision: 'pass-through' | 'escaped' | 'replaced' | 'rejected';
+  readonly boundary: ProtocolBoundary;
+  readonly policy: ProtocolEscapePolicy;
+}
+
+function escapeStrict(
+  input: string,
+  boundary: ProtocolBoundary,
+): { content: string; count: number } {
+  let count = 0;
+  let out = input.replace(CONTROL_CHARS_RE, (ch) => {
+    count += 1;
+    return `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`;
+  });
+  if (boundary === 'sse') {
+    out = out.replace(SSE_FRAME_RE, (m) => {
+      count += 1;
+      return m.replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+    });
+  }
+  if (boundary === 'http-header' || boundary === 'audit') {
+    out = out.replace(HEADER_CRLF_RE, () => {
+      count += 1;
+      return '\\r\\n';
+    });
+  }
+  return { content: out, count };
+}
+
+function replaceUFFFD(input: string): { content: string; count: number } {
+  let count = 0;
+  const out = input.replace(CONTROL_CHARS_RE, () => {
+    count += 1;
+    return '\uFFFD';
+  });
+  return { content: out, count };
+}
+
+function findMatchedPattern(input: string): string | undefined {
+  if (CONTROL_CHARS_RE.test(input)) {
+    CONTROL_CHARS_RE.lastIndex = 0;
+    return 'control-char';
+  }
+  if (SSE_FRAME_RE.test(input)) {
+    SSE_FRAME_RE.lastIndex = 0;
+    return 'sse-frame';
+  }
+  if (HEADER_CRLF_RE.test(input)) {
+    HEADER_CRLF_RE.lastIndex = 0;
+    return 'header-crlf';
+  }
+  return undefined;
+}
+
+/**
+ * Apply the configured escape policy to a single string body. Pure
+ * - never mutates inputs.
+ *
+ * @stable
+ */
+export function guardOutboundContent(
+  input: string,
+  boundary: ProtocolBoundary,
+  cfg: ProtocolGuardConfig = {},
+): GuardOutcome {
+  const policy = resolvePolicy(boundary, cfg);
+  const matchedPattern = findMatchedPattern(input);
+  if (matchedPattern === undefined) {
+    return {
+      content: input,
+      escapedCharCount: 0,
+      decision: 'pass-through',
+      boundary,
+      policy,
+    };
+  }
+  switch (policy) {
+    case 'strict': {
+      const r = escapeStrict(input, boundary);
+      return {
+        content: r.content,
+        escapedCharCount: r.count,
+        matchedPattern,
+        decision: 'escaped',
+        boundary,
+        policy,
+      };
+    }
+    case 'replace': {
+      const r = replaceUFFFD(input);
+      return {
+        content: r.content,
+        escapedCharCount: r.count,
+        matchedPattern,
+        decision: 'replaced',
+        boundary,
+        policy,
+      };
+    }
+    case 'reject':
+      throw new ProtocolInjectionRejectError(boundary, matchedPattern);
+    default: {
+      const _exhaustive: never = policy;
+      void _exhaustive;
+      return {
+        content: input,
+        escapedCharCount: 0,
+        decision: 'pass-through',
+        boundary,
+        policy,
+      };
+    }
+  }
+}