Add AST-based security middleware and enforcement wiring

README.md

@@ -10,6 +10,7 @@ TypeScript runtime for deterministic multi-agent execution with:
 - Typed domain events for edge-triggered routing
 - Resource provisioning (git worktrees + deterministic port ranges)
 - MCP configuration layer with handler policy hooks
+- Security middleware for shell/tool policy enforcement
 
 ## Architecture Summary
 
@@ -37,6 +38,7 @@ TypeScript runtime for deterministic multi-agent execution with:
   - `runtime.ts`: env-driven defaults/singletons
   - `provisioning.ts`: resource provisioning and child suballocation helpers
 - `src/mcp`: MCP config types/conversion/handlers
+- `src/security`: shell AST parsing, rules engine, secure executor, and audit sinks
 - `src/examples`: provider entrypoints (`codex.ts`, `claude.ts`)
 - `src/config.ts`: centralized env parsing/validation/defaulting
 - `tests`: manager, manifest, pipeline/orchestration, state, provisioning, MCP
@@ -69,6 +71,7 @@ npm run dev -- claude "List potential improvements."
 
 - supported topologies (`sequential`, `parallel`, `hierarchical`, `retry-unrolled`)
 - persona definitions and tool-clearance metadata
+- persona definitions and tool-clearance policy (validated by shared Zod schema)
 - relationship DAG and unknown persona references
 - strict pipeline DAG
 - topology constraints (`maxDepth`, `maxRetries`)
@@ -98,6 +101,26 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 - session closure aborts child recursive work
 - run summaries expose aggregate `status`: success requires successful terminal executed DAG nodes and no critical-path failure
 
+## Security Middleware
+
+- Shell command parsing uses `bash-parser` AST traversal and extracts `Command`/`Word` nodes.
+- Rules are validated with strict Zod schemas (`src/security/schemas.ts`) before execution.
+- `SecurityRulesEngine` enforces:
+  - binary allowlists
+  - cwd/worktree boundary checks
+  - path traversal blocking (`../`)
+  - protected path blocking (state root + project context path)
+  - unified tool allowlist/banlist checks for shell binaries and MCP tool lists
+- `SecureCommandExecutor` runs commands via `child_process.spawn` with:
+  - explicit env scrub/inject policy (no implicit full env inheritance)
+  - timeout enforcement
+  - optional uid/gid drop
+  - stdout/stderr streaming hooks for audit
+- Every actor execution input now includes `security` helpers (`rulesEngine`, `createCommandExecutor(...)`) so executors can enforce shell/tool policy at the execution boundary.
+- Pipeline behavior on `SecurityViolationError` is configurable:
+  - `hard_abort` (default)
+  - `validation_fail` (retry-unrolled remediation)
+
 ## Environment Variables
 
 ### Provider/Auth
@@ -136,6 +159,17 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 - `AGENT_PORT_LOCK_DIR`
 - `AGENT_DISCOVERY_FILE_RELATIVE_PATH`
 
+### Security Middleware
+
+- `AGENT_SECURITY_VIOLATION_MODE`
+- `AGENT_SECURITY_ALLOWED_BINARIES`
+- `AGENT_SECURITY_COMMAND_TIMEOUT_MS`
+- `AGENT_SECURITY_AUDIT_LOG_PATH`
+- `AGENT_SECURITY_ENV_INHERIT`
+- `AGENT_SECURITY_ENV_SCRUB`
+- `AGENT_SECURITY_DROP_UID`
+- `AGENT_SECURITY_DROP_GID`
+
 Defaults are documented in `.env.example`.
 
 ## Quality Gate
@@ -155,5 +189,4 @@ npm run build
 
 ## Notes
 
-- Tool clearance allowlist/banlist is currently metadata only; hard enforcement must happen at the tool execution boundary.
 - `AgentManager.runRecursiveAgent(...)` remains available for low-level testing, but pipeline execution should use `SchemaDrivenExecutionEngine.runSession(...)`.