pi-crew 0.9.19 → 0.9.20

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [v0.9.20] — security hardening: RPC HMAC auth + per-task API key scoping + safe-bash whitelist (2026-07-06)
+
+Three defense-in-depth security upgrades distilled from cross-source research (52+ repos) and the H-1/H-2/H-6 audit findings. All three are additive (no breaking changes); two are opt-in via env vars, one is default-on.
+
+### Highlights
+
+- **RPC HMAC authentication (opt-in).** All cross-extension RPC channels (`ping`/`run`/`status`/`live-control` at extension layer; `ping`/`spawn`/`stop` at runtime layer) now support HMAC-SHA256 origin signing. When `PI_CREW_RPC_SECRET` is set, every request must carry a valid signature with timestamp + nonce (anti-replay) and channel binding (cross-channel replay guard). Timing-safe comparison prevents timing attacks. Unset = backward-compatible passthrough. Closes the H-2 authorization-bypass finding where any co-installed extension could spoof `source='pi-crew'` to spawn/kill subagents. New module `src/extension/rpc-hmac.ts`; 24 tests in `test/unit/rpc-hmac-auth.test.ts`.
+- **Per-task API key scoping (default-on).** Child workers previously inherited ALL model provider API keys via a broad allowlist. `buildChildPiSpawnOptions()` now takes an optional `model` param and calls `buildScopedAllowList()` to inject only the provider keys needed for the assigned model. When no model is given, only `BASE_ALLOWLIST` system vars pass through (zero provider keys leak). Reduces blast radius: a compromised child only gets keys for its model. Helpers `providerEnvKeys()` + `buildScopedAllowList()` in `src/utils/env-filter.ts`; per-task wiring in `src/runtime/child-pi.ts`; tests in `test/unit/api-key-scoping.test.ts`.
+- **Safe-bash whitelist mode (opt-in).** A deny-by-default whitelist as an opt-in alternative to the legacy blacklist `isDangerous()`. Enabled via `PI_CREW_SAFE_BASH_MODE=whitelist`. Only 16 read-only commands allowed (`ls cat head tail wc grep find echo pwd date whoami uname df du file stat`). Shell metacharacter regex blocks chaining/substitution before the first-token check (`ls; rm file` cannot smuggle `rm`); unmatched quotes are rejected as malformed input. Legacy blacklist path unchanged when not enabled. `src/tools/safe-bash.ts`; 21 tests in `test/unit/safe-bash-whitelist.test.ts`.
+
+### Verification
+
+| Gate | Result |
+|---|---|
+| Affected unit tests (20 files) | ✅ 187/187 pass |
+| safe-bash (blacklist + whitelist + ANSI) | ✅ 51/51 |
+| env-filter + API key scoping | ✅ 26/26 |
+| cross-extension-rpc + HMAC | ✅ 48/48 |
+| child-pi (hardening/exit/redaction/compaction) | ✅ 35/35 |
+| security (hardening/artifact/cwd/import/output) | ✅ 27/27 |
+| Live E2E (research workflow) | ✅ 3/3 tasks, end-to-end |
+| Extension load | ✅ |
+
+### Files
+
+- NEW: `src/extension/rpc-hmac.ts`, `test/unit/rpc-hmac-auth.test.ts`, `test/unit/api-key-scoping.test.ts`, `test/unit/safe-bash-whitelist.test.ts`
+- MOD: `src/extension/cross-extension-rpc.ts`, `src/runtime/cross-extension-rpc.ts`, `src/utils/env-filter.ts`, `src/runtime/child-pi.ts`, `src/tools/safe-bash.ts`, `src/tools/safe-bash-extension.ts`, `test/unit/env-filter.test.ts`, `test/unit/security-hardening.test.ts`
+
 ## [v0.9.19] — plan-execute workflow + main-session→planner analysis handoff (2026-07-03)
 
 New builtin workflow for the common "I already analyzed this — just plan + execute + verify it" case, plus a generic `analysis`/`analysisPath` channel on `team action='run'` for handing caller-session context to planner child workers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/cross-extension-rpc.ts

@@ -3,6 +3,7 @@ import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
 import { resolveContainedPath } from "../utils/safe-paths.ts";
 // Lazy-loaded to avoid pulling team-tool.ts (and its entire runtime chain) into module load.
 import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
+import { withHmacVerification } from "./rpc-hmac.ts";
 
 let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
@@ -143,9 +144,8 @@ function on(events: EventBusLike, channel: string, handler: (raw: unknown) => vo
 
 // SECURITY TRUST BOUNDARY: RPC channels (pi-crew:rpc:run, pi-crew:rpc:status,
 // pi-crew:rpc:live-control) are accessible to any extension on the shared event
-// bus. Mitigations applied: rate limiting (RPC_RATE_LIMIT_MAX), explicit intent
-// requirement for runs, operation allowlist for live-control reads, and cwd
-// containment validation. A full fix requires event-bus-level origin signing.
+// bus. Mitigations: rate limiting, explicit intent, operation allowlist, cwd
+// containment validation, and HMAC origin signing (see rpc-hmac.ts).
 
 export function registerPiCrewRpc(
 	events: EventBusLike | undefined,
@@ -153,150 +153,168 @@ export function registerPiCrewRpc(
 ): PiCrewRpcHandle | undefined {
 	if (!events) return undefined;
 	const unsubs = [
-		on(events, "pi-crew:rpc:ping", (raw) =>
-			reply(events, "pi-crew:rpc:ping", requestId(raw), {
-				success: true,
-				data: { version: PI_CREW_RPC_VERSION },
-			}),
+		on(
+			events,
+			"pi-crew:rpc:ping",
+			withHmacVerification(
+				(raw) =>
+					reply(events, "pi-crew:rpc:ping", requestId(raw), {
+						success: true,
+						data: { version: PI_CREW_RPC_VERSION },
+					}),
+				"pi-crew:rpc:ping",
+			),
 		),
-		on(events, "pi-crew:rpc:run", async (raw) => {
-			const id = requestId(raw);
-			try {
-				// SECURITY (HIGH #4 fix): Rate limit RPC run requests
-				const rateLimit = checkRpcRateLimit();
-				if (!rateLimit.allowed) {
+		on(
+			events,
+			"pi-crew:rpc:run",
+			withHmacVerification(async (raw) => {
+				const id = requestId(raw);
+				try {
+					// SECURITY (HIGH #4 fix): Rate limit RPC run requests
+					const rateLimit = checkRpcRateLimit();
+					if (!rateLimit.allowed) {
+						reply(events, "pi-crew:rpc:run", id, {
+							success: false,
+							error: `RPC run rate limit exceeded. Max ${RPC_RATE_LIMIT_MAX} requests per ${RPC_RATE_LIMIT_WINDOW_MS / 1000}s. Retry after ${Math.ceil((rateLimit.retryAfterMs ?? 60000) / 1000)}s.`,
+						});
+						return;
+					}
+					recordRpcRun();
+					const ctx = getCtx();
+					if (!ctx) throw new Error("No active pi-crew session context.");
+					// Validate payload: only allow known fields from TeamToolParamsValue
+					const ALLOWED_RPC_RUN_KEYS = new Set(["goal", "team", "workflow", "async", "cwd", "config", "skill", "model"]);
+					let params: TeamToolParamsValue;
+					if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+						const filtered: Record<string, unknown> = {
+							...(raw as object),
+						};
+						// Strip any keys not in the allowlist to prevent injection of unexpected fields
+						for (const key of Object.keys(filtered)) {
+							if (!ALLOWED_RPC_RUN_KEYS.has(key)) delete filtered[key];
+						}
+						params = {
+							...filtered,
+							action: "run",
+						} as TeamToolParamsValue;
+					} else {
+						params = { action: "run" };
+					}
+					const permission = isAllowedRpcRunParams(params);
+					if (!permission.ok) {
+						reply(events, "pi-crew:rpc:run", id, {
+							success: false,
+							error: permission.error ?? "permission denied",
+						});
+						return;
+					}
+					const result = await handleTeamTool(params, ctx);
+					reply(
+						events,
+						"pi-crew:rpc:run",
+						id,
+						result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details },
+					);
+				} catch (error) {
 					reply(events, "pi-crew:rpc:run", id, {
 						success: false,
-						error: `RPC run rate limit exceeded. Max ${RPC_RATE_LIMIT_MAX} requests per ${RPC_RATE_LIMIT_WINDOW_MS / 1000}s. Retry after ${Math.ceil((rateLimit.retryAfterMs ?? 60000) / 1000)}s.`,
+						error: error instanceof Error ? error.message : String(error),
 					});
-					return;
 				}
-				recordRpcRun();
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				// Validate payload: only allow known fields from TeamToolParamsValue
-				const ALLOWED_RPC_RUN_KEYS = new Set(["goal", "team", "workflow", "async", "cwd", "config", "skill", "model"]);
-				let params: TeamToolParamsValue;
-				if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-					const filtered: Record<string, unknown> = {
-						...(raw as object),
-					};
-					// Strip any keys not in the allowlist to prevent injection of unexpected fields
-					for (const key of Object.keys(filtered)) {
-						if (!ALLOWED_RPC_RUN_KEYS.has(key)) delete filtered[key];
-					}
-					params = {
-						...filtered,
-						action: "run",
-					} as TeamToolParamsValue;
-				} else {
-					params = { action: "run" };
-				}
-				const permission = isAllowedRpcRunParams(params);
-				if (!permission.ok) {
-					reply(events, "pi-crew:rpc:run", id, {
+			}, "pi-crew:rpc:run"),
+		),
+		on(
+			events,
+			"pi-crew:rpc:status",
+			withHmacVerification(async (raw) => {
+				const id = requestId(raw);
+				try {
+					const ctx = getCtx();
+					if (!ctx) throw new Error("No active pi-crew session context.");
+					const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
+					const result = await handleTeamTool({ action: "status", runId }, ctx);
+					reply(
+						events,
+						"pi-crew:rpc:status",
+						id,
+						result.isError
+							? { success: false, error: textOf(result) }
+							: {
+									success: true,
+									data: {
+										text: textOf(result),
+										details: result.details,
+									},
+								},
+					);
+				} catch (error) {
+					reply(events, "pi-crew:rpc:status", id, {
 						success: false,
-						error: permission.error ?? "permission denied",
+						error: error instanceof Error ? error.message : String(error),
 					});
-					return;
 				}
-				const result = await handleTeamTool(params, ctx);
-				reply(
-					events,
-					"pi-crew:rpc:run",
-					id,
-					result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details },
-				);
-			} catch (error) {
-				reply(events, "pi-crew:rpc:run", id, {
-					success: false,
-					error: error instanceof Error ? error.message : String(error),
-				});
-			}
-		}),
-		on(events, "pi-crew:rpc:status", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
-				const result = await handleTeamTool({ action: "status", runId }, ctx);
-				reply(
-					events,
-					"pi-crew:rpc:status",
-					id,
-					result.isError
-						? { success: false, error: textOf(result) }
-						: {
-								success: true,
-								data: {
-									text: textOf(result),
-									details: result.details,
-								},
-							},
-				);
-			} catch (error) {
-				reply(events, "pi-crew:rpc:status", id, {
-					success: false,
-					error: error instanceof Error ? error.message : String(error),
-				});
-			}
-		}),
+			}, "pi-crew:rpc:status"),
+		),
 		on(events, "pi-crew:live-control", (raw) => {
 			const request = parseLiveControlRealtimeMessage(raw);
 			if (request) publishLiveControlRealtime(request);
 		}),
-		on(events, "pi-crew:rpc:live-control", async (raw) => {
-			const id = requestId(raw);
-			try {
-				const ctx = getCtx();
-				if (!ctx) throw new Error("No active pi-crew session context.");
-				const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
-				const rawOp = typeof obj.operation === "string" ? obj.operation : "steer-agent";
-				// SECURITY: Reject any operation not in the explicit allowlist.
-				// Mutating ops (approve-plan, cancel-plan, steer-agent, stop-agent, etc.)
-				// require user consent and are blocked here.
-				if (!isAllowedRpcOperation(rawOp)) {
+		on(
+			events,
+			"pi-crew:rpc:live-control",
+			withHmacVerification(async (raw) => {
+				const id = requestId(raw);
+				try {
+					const ctx = getCtx();
+					if (!ctx) throw new Error("No active pi-crew session context.");
+					const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+					const rawOp = typeof obj.operation === "string" ? obj.operation : "steer-agent";
+					// SECURITY: Reject any operation not in the explicit allowlist.
+					// Mutating ops (approve-plan, cancel-plan, steer-agent, stop-agent, etc.)
+					// require user consent and are blocked here.
+					if (!isAllowedRpcOperation(rawOp)) {
+						reply(events, "pi-crew:rpc:live-control", id, {
+							success: false,
+							error: `RPC operation '${rawOp}' is not allowed. Allowed: ${[...RPC_ALLOWED_OPERATIONS].join(", ")}`,
+						});
+						return;
+					}
+					const result = await handleTeamTool(
+						{
+							action: "api",
+							runId: typeof obj.runId === "string" ? obj.runId : undefined,
+							config: {
+								operation: rawOp,
+								agentId: obj.agentId,
+								message: obj.message,
+								prompt: obj.prompt,
+							},
+						},
+						ctx,
+					);
+					reply(
+						events,
+						"pi-crew:rpc:live-control",
+						id,
+						result.isError
+							? { success: false, error: textOf(result) }
+							: {
+									success: true,
+									data: {
+										text: textOf(result),
+										details: result.details,
+									},
+								},
+					);
+				} catch (error) {
 					reply(events, "pi-crew:rpc:live-control", id, {
 						success: false,
-						error: `RPC operation '${rawOp}' is not allowed. Allowed: ${[...RPC_ALLOWED_OPERATIONS].join(", ")}`,
+						error: error instanceof Error ? error.message : String(error),
 					});
-					return;
 				}
-				const result = await handleTeamTool(
-					{
-						action: "api",
-						runId: typeof obj.runId === "string" ? obj.runId : undefined,
-						config: {
-							operation: rawOp,
-							agentId: obj.agentId,
-							message: obj.message,
-							prompt: obj.prompt,
-						},
-					},
-					ctx,
-				);
-				reply(
-					events,
-					"pi-crew:rpc:live-control",
-					id,
-					result.isError
-						? { success: false, error: textOf(result) }
-						: {
-								success: true,
-								data: {
-									text: textOf(result),
-									details: result.details,
-								},
-							},
-				);
-			} catch (error) {
-				reply(events, "pi-crew:rpc:live-control", id, {
-					success: false,
-					error: error instanceof Error ? error.message : String(error),
-				});
-			}
-		}),
+			}, "pi-crew:rpc:live-control"),
+		),
 	];
 	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
 }

package/src/extension/rpc-hmac.ts

@@ -0,0 +1,236 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+/**
+ * HMAC-based origin signing for cross-extension RPC.
+ *
+ * Shared secret is distributed via environment variable PI_CREW_RPC_SECRET.
+ * When the secret is configured, all RPC requests must include a valid HMAC
+ * signature. When the secret is NOT configured, HMAC is disabled (backward
+ * compat for setups that don't need it).
+ *
+ * Usage:
+ *   Sender:   signRpcRequest(params, "my-extension", "pi-crew:rpc:ping")
+ *   Receiver: wrap handler with withHmacVerification(handler, channel)
+ */
+
+export const RPC_HMAC_VERSION = 1;
+
+const SECRET_ENV_VAR = "PI_CREW_RPC_SECRET";
+const CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1000; // 5 min
+const SIGNATURE_VALIDITY_MS = 10 * 60 * 1000; // 10 min
+
+// --- Secret management -------------------------------------------------------
+
+/** Get the shared secret. Returns undefined if not configured. */
+export function getRpcSecret(): string | undefined {
+	return process.env[SECRET_ENV_VAR];
+}
+
+/** Set the shared secret (for testing or programmatic setup). */
+export function setRpcSecret(secret: string): void {
+	process.env[SECRET_ENV_VAR] = secret;
+}
+
+/** Clear the shared secret. */
+export function clearRpcSecret(): void {
+	delete process.env[SECRET_ENV_VAR];
+}
+
+/** Whether HMAC authentication is currently enabled. */
+export function isHmacEnabled(): boolean {
+	return typeof process.env[SECRET_ENV_VAR] === "string" && process.env[SECRET_ENV_VAR].length > 0;
+}
+
+// --- Types -------------------------------------------------------------------
+
+export interface RpcSignaturePayload {
+	version: number;
+	origin: string;
+	timestamp: number;
+	channel: string;
+	nonce: string;
+}
+
+export type RpcSignedPayload = RpcSignaturePayload & { signature: string };
+
+// --- Signing -----------------------------------------------------------------
+
+/**
+ * Create an HMAC signature for an RPC request.
+ *
+ * @throws if no secret is configured
+ */
+export function createRpcSignature(origin: string, channel: string, body: unknown): RpcSignedPayload {
+	const secret = getRpcSecret();
+	if (!secret) {
+		throw new Error(`[pi-crew HMAC] Cannot create signature: ${SECRET_ENV_VAR} not set.`);
+	}
+
+	const payload: RpcSignaturePayload = {
+		version: RPC_HMAC_VERSION,
+		origin,
+		timestamp: Date.now(),
+		channel,
+		nonce: randomBytes(16).toString("hex"),
+	};
+
+	const signature = computeHmac(secret, payload, body);
+	return { ...payload, signature };
+}
+
+// --- Verification ------------------------------------------------------------
+
+/**
+ * Verify an HMAC signature.
+ *
+ * @returns `{ valid: true }` or `{ valid: false, reason: string }`
+ */
+export function verifyRpcSignature(payload: RpcSignedPayload, body: unknown): { valid: true } | { valid: false; reason: string } {
+	const secret = getRpcSecret();
+	if (!secret) {
+		return { valid: false, reason: `[pi-crew HMAC] ${SECRET_ENV_VAR} not configured.` };
+	}
+
+	if (payload.version !== RPC_HMAC_VERSION) {
+		return { valid: false, reason: `HMAC version mismatch: expected ${RPC_HMAC_VERSION}, got ${payload.version}` };
+	}
+
+	const now = Date.now();
+	const age = now - payload.timestamp;
+	if (age < -CLOCK_SKEW_TOLERANCE_MS) {
+		return { valid: false, reason: `HMAC timestamp in the future by ${Math.abs(age)}ms` };
+	}
+	if (age > SIGNATURE_VALIDITY_MS) {
+		return { valid: false, reason: `HMAC signature expired (${age}ms old)` };
+	}
+
+	const expected = computeHmac(secret, payload, body);
+	return timingSafeCompare(payload.signature, expected) ? { valid: true } : { valid: false, reason: "HMAC signature mismatch" };
+}
+
+// --- Middleware --------------------------------------------------------------
+
+/**
+ * Wrap an RPC handler with HMAC verification.
+ *
+ * When HMAC is NOT configured (getRpcSecret() returns undefined), requests
+ * without signatures are passed through (backward compat). When HMAC IS
+ * configured, unsigned or invalid signatures are rejected.
+ */
+export function withHmacVerification<P extends { requestId: string }>(
+	handler: (params: P) => unknown | Promise<unknown>,
+	_channel: string,
+): (params: P) => unknown | Promise<unknown> {
+	return (params: P) => {
+		if (!isHmacEnabled()) {
+			// No secret configured → backward compat: allow unsigned
+			return handler(params);
+		}
+
+		const sigPayload = extractSignaturePayload(params);
+		if (!sigPayload) {
+			throw new Error("[pi-crew HMAC] Missing HMAC signature in RPC request.");
+		}
+
+		// Strip HMAC fields from body before verification (HMAC was signed over original params)
+		const originalBody = stripHmacFields(params);
+		const verification = verifyRpcSignature(sigPayload, originalBody);
+		if (!verification.valid) {
+			throw new Error(`[pi-crew HMAC] ${verification.reason}`);
+		}
+
+		// Pass original params (with HMAC fields stripped) to handler
+		return handler(originalBody as P);
+	};
+}
+
+// --- Helpers -----------------------------------------------------------------
+
+/**
+ * Attach HMAC signature fields to RPC request params.
+ */
+export function signRpcRequest<P extends Record<string, unknown>>(
+	params: P,
+	origin: string,
+	channel: string,
+): P & {
+	hmacVersion: number;
+	hmacOrigin: string;
+	hmacTimestamp: number;
+	hmacChannel: string;
+	hmacNonce: string;
+	hmacSignature: string;
+} {
+	const signed = createRpcSignature(origin, channel, params);
+	return {
+		...params,
+		hmacVersion: signed.version,
+		hmacOrigin: signed.origin,
+		hmacTimestamp: signed.timestamp,
+		hmacChannel: signed.channel,
+		hmacNonce: signed.nonce,
+		hmacSignature: signed.signature,
+	};
+}
+
+// --- Internal ----------------------------------------------------------------
+
+/** Strip HMAC signature fields from params to get the original body. */
+function stripHmacFields<P extends Record<string, unknown>>(params: P): Partial<P> {
+	const result = { ...params };
+	delete result.hmacVersion;
+	delete result.hmacOrigin;
+	delete result.hmacTimestamp;
+	delete result.hmacChannel;
+	delete result.hmacNonce;
+	delete result.hmacSignature;
+	return result;
+}
+
+function computeHmac(secret: string, payload: RpcSignaturePayload, body: unknown): string {
+	const payloadForHmac = {
+		version: payload.version,
+		origin: payload.origin,
+		timestamp: payload.timestamp,
+		channel: payload.channel,
+		nonce: payload.nonce,
+	};
+	const message = `${JSON.stringify(payloadForHmac)}:${JSON.stringify(body)}`;
+	return createHmac("sha256", secret).update(message).digest("hex");
+}
+
+function timingSafeCompare(a: string, b: string): boolean {
+	const bufA = Buffer.from(a, "hex");
+	const bufB = Buffer.from(b, "hex");
+	const maxLen = Math.max(bufA.length, bufB.length);
+	const safeA = Buffer.alloc(maxLen);
+	const safeB = Buffer.alloc(maxLen);
+	bufA.copy(safeA);
+	bufB.copy(safeB);
+	const equal = timingSafeEqual(safeA, safeB);
+	return equal && bufA.length === bufB.length;
+}
+
+/** Extract HMAC signature payload from request params. */
+export function extractSignaturePayload(params: unknown): RpcSignedPayload | null {
+	if (!params || typeof params !== "object" || Array.isArray(params)) return null;
+	const obj = params as Record<string, unknown>;
+	if (
+		typeof obj.hmacVersion !== "number" ||
+		typeof obj.hmacOrigin !== "string" ||
+		typeof obj.hmacTimestamp !== "number" ||
+		typeof obj.hmacChannel !== "string" ||
+		typeof obj.hmacNonce !== "string" ||
+		typeof obj.hmacSignature !== "string"
+	) {
+		return null;
+	}
+	return {
+		version: obj.hmacVersion,
+		origin: obj.hmacOrigin,
+		timestamp: obj.hmacTimestamp,
+		channel: obj.hmacChannel,
+		nonce: obj.hmacNonce,
+		signature: obj.hmacSignature,
+	};
+}