@principles/pd-cli 1.134.0 → 1.135.1

package/src/commands/rulecode.ts

@@ -31,6 +31,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import type { Command } from 'commander';
+import { isPathInside } from '../utils/path-security.js';
 import {
   RULECODE_SPEC_TEXT,
   checkForbiddenPatterns,
@@ -113,11 +114,33 @@ function isGoldenTraceCaseInput(value: unknown): value is GoldenTraceCaseInput {
 /**
  * Load and validate golden trace cases from a JSON file.
  * Returns either the validated cases or a structured error.
+ * Exported for boundary regression tests (internal test surface).
  */
-function loadGoldenTraceCases(filePath: string): { cases?: GoldenTraceCaseInput[]; error?: { reason: string; nextAction: string } } {
+export function loadGoldenTraceCases(
+  filePath: string,
+  workspaceDir?: string,
+): { cases?: GoldenTraceCaseInput[]; error?: { reason: string; nextAction: string } } {
   let raw: string;
   try {
+    if (!filePath || filePath.trim().length === 0) {
+      throw new Error('golden trace path is empty');
+    }
     const resolved = path.resolve(filePath);
+    // CWE-22 boundary: canonical containment against the workspace root
+    // (rejects sibling-prefix and traversal escapes; relative workspaces
+    // canonicalize consistently). Filesystem-root targets are rejected by
+    // containment when a workspace root is supplied.
+    const normalized = path.normalize(resolved);
+    if (normalized.split(/[\\/]/).includes('..')) {
+      throw new Error('golden trace path contains parent traversal');
+    }
+    if (workspaceDir) {
+      if (!isPathInside(workspaceDir, resolved)) {
+        throw new Error('golden trace path must be inside the workspace directory');
+      }
+    } else if (normalized === path.parse(normalized).root) {
+      throw new Error('golden trace path resolves to filesystem root');
+    }
     raw = fs.readFileSync(resolved, 'utf8');
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -286,7 +309,7 @@ export async function handleRulecodeReplay(opts: ReplayOptions): Promise<void> {
     return;
   }
 
-  const traceResult = loadGoldenTraceCases(opts.goldenTrace);
+  const traceResult = loadGoldenTraceCases(opts.goldenTrace, opts.workspace);
   if (traceResult.error || traceResult.cases === undefined) {
     const { error } = traceResult;
     const output: RulecodeReplayOutput = {

package/src/resolve-workspace.ts

@@ -15,15 +15,24 @@
 
 import * as path from 'path';
 import { discoverWorkspaceDefault } from './services/pd-config-loader.js';
+import { assertSafeDirectoryRoot } from './utils/path-security.js';
 
 /** Environment variable name for workspace directory. */
 export const WORKSPACE_ENV = 'PD_WORKSPACE_DIR';
 
 // ── Internal helpers ────────────────────────────────────────────────────────
 
-/** Normalize path to forward slashes for cross-platform comparison. */
+/**
+ * Normalize a path to forward slashes for cross-platform string comparison.
+ *
+ * Comparison-only helper: it never resolves against the filesystem and never
+ * feeds a filesystem operation, so it intentionally uses `path.normalize`
+ * (pure string normalization) instead of `path.resolve`. Callers compare two
+ * paths for equality after normalization; the workspace root itself is
+ * validated by `assertWorkspaceDirInside` before any IO uses it.
+ */
 function normalizePath(p: string): string {
-  return path.resolve(p).replace(/\\/g, '/');
+  return path.normalize(p).replace(/\\/g, '/');
 }
 
 /** Emit workspace warnings to stderr. */
@@ -31,6 +40,31 @@ function emitWarning(msg: string): void {
   process.stderr.write(`[PD:workspace] WARNING: ${msg}\n`);
 }
 
+/**
+ * Validate an operator-supplied workspace root before it is used as an IO
+ * root. Delegates to the shared canonical-root validator (empty, parent
+ * traversal, filesystem root). Returns nothing; callers keep the original
+ * value so downstream resolution semantics are unchanged.
+ */
+function assertWorkspaceDirInside(p: string, source: string): void {
+  assertSafeDirectoryRoot(p, source);
+}
+
+/** Emit a warning when an explicit override differs from config default. */
+function emitWarningIfDiffers(
+  override: string,
+  configDefault: string | undefined,
+  discovered: { configPath?: string } | null,
+): void {
+  if (configDefault && normalizePath(override) !== normalizePath(configDefault)) {
+    emitWarning(
+      `"${override}" differs from config default "${configDefault}" ` +
+        `(source: ${discovered?.configPath}). Using explicit override. ` +
+        `Consider updating workspace.default in config.`,
+    );
+  }
+}
+
 // ── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -46,34 +80,24 @@ export function resolveWorkspaceDir(workspaceDir?: string): string {
 
   // Step 2: Check --workspace flag (highest priority)
   if (workspaceDir) {
-    if (configDefault && normalizePath(workspaceDir) !== normalizePath(configDefault)) {
-      emitWarning(
-        `--workspace "${workspaceDir}" differs from config default "${configDefault}" ` +
-        `(source: ${discovered.configPath}). Using explicit flag. ` +
-        `Consider updating workspace.default in config.`,
-      );
-    }
+    assertWorkspaceDirInside(workspaceDir, '--workspace');
+    emitWarningIfDiffers(workspaceDir, configDefault, discovered);
     return workspaceDir;
   }
 
   // Step 3: Check PD_WORKSPACE_DIR env var
   const envWorkspace = process.env.PD_WORKSPACE_DIR?.trim();
   if (envWorkspace) {
-    if (configDefault && normalizePath(envWorkspace) !== normalizePath(configDefault)) {
-      emitWarning(
-        `PD_WORKSPACE_DIR "${envWorkspace}" differs from config default "${configDefault}" ` +
-        `(source: ${discovered.configPath}). Using env var. ` +
-        `Consider aligning or updating workspace.default.`,
-      );
-    }
+    assertWorkspaceDirInside(envWorkspace, WORKSPACE_ENV);
+    emitWarningIfDiffers(envWorkspace, configDefault, discovered);
     return envWorkspace;
   }
 
   // Step 4: Use discovered config default
   if (configDefault) {
+    assertWorkspaceDirInside(configDefault, 'workspace.default');
     return configDefault;
   }
-
   // Step 5: No resolution possible — throw (preserves current behavior)
   throw new Error(
     'No workspace directory configured. Set --workspace <path>, ' +

package/src/services/console-launcher.ts

@@ -34,6 +34,12 @@ export interface ConsoleLaunchResult {
   reused: boolean;
   /** True when a browser should/has been opened (skipped in --json mode). */
   browserOpened: boolean;
+  /**
+   * PID of the freshly spawned console server process. Present only when
+   * status === 'started'; absent on 'reused' (the server was started by
+   * another process, so this launcher cannot know its PID).
+   */
+  serverPid?: number;
 }
 
 export interface ConsoleLaunchOptions {
@@ -212,20 +218,62 @@ export async function findAvailablePort(
 
 // ─── Browser opener (best-effort, no throw) ──────────────────────────────────
 
+/**
+ * Validate a browser URL before it is handed to a system opener.
+ * Only http/https targets are allowed — other schemes (file:, javascript:,
+ * custom protocols) could be abused. This is the primary defense for the
+ * win32 opener path, which no longer routes through a shell.
+ */
+function assertSafeBrowserUrl(rawUrl: string): string {
+  if (!rawUrl || rawUrl.trim().length === 0) {
+    throw new Error('browser URL is empty');
+  }
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`invalid browser URL: "${rawUrl}"`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`invalid browser URL: protocol must be http(s), got "${url.protocol}"`);
+  }
+  return url.toString();
+}
+
 /**
  * Open the system browser. Best-effort — failures are reported but do not
  * crash the launcher.
+ *
+ * Security: the URL is validated (http/https only) and every opener is
+ * invoked with a parameterized `spawn` (no shell). In particular the win32
+ * path uses `explorer.exe` with an argument array instead of the previous
+ * `cmd.exe /c start "" <url>` form, which ran the URL through the cmd shell
+ * and allowed shell metacharacters in the URL to be interpreted as commands
+ * (command injection).
  */
-export async function openBrowser(url: string): Promise<{ opened: boolean; reason?: string; nextAction?: string }> {
+export async function openBrowser(rawUrl: string): Promise<{ opened: boolean; reason?: string; nextAction?: string }> {
   const { spawn } = await import('child_process');
   const { platform } = process;
 
+  let url: string;
+  try {
+    url = assertSafeBrowserUrl(rawUrl);
+  } catch (err) {
+    return {
+      opened: false,
+      reason: err instanceof Error ? err.message : String(err),
+      nextAction: 'Use an http:// or https:// URL.',
+    };
+  }
+
   let cmd: string;
   let args: string[];
 
   if (platform === 'win32') {
-    cmd = process.env.ComSpec || 'cmd.exe';
-    args = ['/c', 'start', '""', url];
+    // Parameterized spawn (no shell): explorer.exe receives the validated
+    // URL as a plain argument and opens it in the default browser.
+    cmd = 'explorer.exe';
+    args = [url];
   } else if (platform === 'darwin') {
     cmd = 'open';
     args = [url];

package/src/services/pd-config-loader.ts

@@ -15,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'js-yaml';
+import { canonicalPath, isPathInside } from '../utils/path-security.js';
 import {
   validatePdConfig,
   computeEffectivePdConfig,
@@ -316,6 +317,32 @@ function loadOpenClawPluginConfig(): { workspace?: string } | null {
   return null;
 }
 
+/**
+ * Validate a candidate config directory before it is joined into a config
+ * path for filesystem reads. Candidate dirs are operator-supplied
+ * (PD_WORKSPACE_DIR / plugin config / home default), so we normalize with
+ * `path.normalize` (pure string, no filesystem access), then reject empty,
+ * parent-traversal, or root paths. This keeps the subsequent
+ * `path.join(dir, PD_CONFIG_DIR, ...)` inside the intended directory
+ * boundary (CWE-22 mitigation).
+ *
+ * Platform note: no `path.isAbsolute` check — absolute-ness is
+ * platform-dependent (a Windows-style path is not absolute on POSIX
+ * runners) and relative dirs resolve inside cwd without traversal risk.
+ */
+function assertConfigDirBoundary(dir: string, source: string): void {
+  if (!dir || dir.trim().length === 0) {
+    throw new Error(`Invalid config search dir (${source}): path is empty`);
+  }
+  const normalized = path.normalize(dir);
+  if (normalized.split(/[\\/]/).includes('..')) {
+    throw new Error(`Invalid config search dir (${source}): "${dir}" contains parent traversal`);
+  }
+  if (normalized === path.parse(normalized).root) {
+    throw new Error(`Invalid config search dir (${source}): "${dir}" resolves to filesystem root`);
+  }
+}
+
 /**
  * Search known locations for a .pd/config.yaml that contains a workspace.default field.
  * This runs BEFORE workspace resolution and does NOT require knowing the workspace dir.
@@ -346,7 +373,14 @@ export function discoverWorkspaceDefault(): WorkspaceDiscoveryResult | null {
 
   // Search each candidate for .pd/config.yaml with workspace.default
   for (const { dir, source } of candidates) {
-    const configPath = path.join(dir, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+    assertConfigDirBoundary(dir, source);
+    // CWE-22: resolve the candidate root once, then verify the joined config
+    // path stays inside that root before any filesystem access.
+    const candidateRoot = canonicalPath(dir);
+    const configPath = path.resolve(candidateRoot, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+    if (!isPathInside(candidateRoot, configPath)) {
+      throw new Error(`Invalid config search dir (${source}): "${dir}" escapes its boundary`);
+    }
     if (fs.existsSync(configPath)) {
       const workspaceDefault = extractWorkspaceDefault(configPath);
       if (workspaceDefault) {

package/src/services/quality-scorecard/strong-model-gate.ts

@@ -60,6 +60,40 @@ Flags: ${localEval.flags.length > 0 ? localEval.flags.join(', ') : 'none'}
 Do NOT output anything other than this JSON object.`;
 }
 
+/**
+ * CWE-918 (SSRF) mitigation for operator-supplied LLM API base URLs.
+ *
+ * Threat model: OPENAI_BASE_URL is explicitly configured by the Owner /
+ * operator in the environment or Runtime Profile — it is trusted operator
+ * configuration, NOT untrusted remote input. Local and private-network
+ * OpenAI-compatible endpoints (llama.cpp, LM Studio, local gateways,
+ * intranet model servers) are legitimate PD runtime targets and must keep
+ * working.
+ *
+ * What stays blocked:
+ * - non-http(s) schemes (file:, javascript:, data:, ...)
+ * - malformed / unparseable URLs
+ * - credentials embedded in the URL (secrets leak into logs/errors)
+ *
+ * Callers must not allow the host to be rewritten from untrusted input
+ * after this validation; the endpoint is derived from this URL only.
+ */
+export function assertSafeLlmBaseUrl(rawBaseUrl: string): URL {
+  let url: URL;
+  try {
+    url = new URL(rawBaseUrl);
+  } catch {
+    throw new Error(`Invalid OPENAI_BASE_URL: "${rawBaseUrl}" is not a valid URL`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(`Invalid OPENAI_BASE_URL: protocol must be http or https, got "${url.protocol}"`);
+  }
+  if (url.username || url.password) {
+    throw new Error(`Invalid OPENAI_BASE_URL: credentials must not be embedded in the URL`);
+  }
+  return url;
+}
+
 export async function adjudicate(
   episode: PainEpisode,
   localEval: LocalEvaluation,
@@ -67,7 +101,11 @@ export async function adjudicate(
 ): Promise<StrongModelAdjudication> {
   const { modelId: strongModelId, log } = config;
   const prompt = buildAdjudicationPrompt(episode, localEval);
-  const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+  // CWE-918 (SSRF): validate the operator-supplied base URL before any
+  // network request — http(s) only, no embedded credentials. Local and
+  // private OpenAI-compatible endpoints remain valid (trusted operator
+  // configuration; llama.cpp / LM Studio / local gateways are supported).
+  const baseUrl = assertSafeLlmBaseUrl(process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1');
   const apiKey = process.env.OPENAI_API_KEY;
 
   if (!apiKey) {
@@ -82,7 +120,11 @@ export async function adjudicate(
   }
 
   try {
-    const resp = await fetch(`${baseUrl}/chat/completions`, {
+    // Build the endpoint on the validated URL: append the chat completions
+    // path to the base URL's (possibly empty) path component.
+    const endpoint = new URL(baseUrl);
+    endpoint.pathname = endpoint.pathname.replace(/\/+$/, '') + '/chat/completions';
+    const resp = await fetch(endpoint.toString(), {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',

package/src/utils/path-security.ts

@@ -0,0 +1,96 @@
+/**
+ * Path containment primitives (CWE-22 boundary guards).
+ *
+ * Single source of truth for "is this filesystem target inside that root?"
+ * across pd-cli security boundaries. All containment decisions compare
+ * CANONICAL (fully resolved) paths via `path.relative`, never by string
+ * prefix — a string `startsWith` on a possibly-relative root is wrong on
+ * two counts: (1) a relative root never prefixes an absolute target, and
+ * (2) `/work/foo` is a prefix of `/work/foobar` without being a boundary.
+ *
+ * ── Symlink policy ────────────────────────────────────────────────────────
+ * The guarantee provided here is LEXICAL containment: `path.resolve` +
+ * `path.relative`, without resolving symlinks. We deliberately do NOT
+ * `realpath` the target before containment because:
+ *   1. PD's IO roots are operator-supplied workspace directories; symlinks
+ *      inside the workspace are created by the owner and treated as trusted
+ *      content.
+ *   2. On Windows, junction points (worktree junctions, `node_modules`
+ *      junctions) resolve to a *different physical location* via `realpath`;
+ *      realpath-based containment would reject legitimate local workflows
+ *      (e.g. a worktree whose `node_modules` is junctioned to the main
+ *      checkout).
+ * If a future caller must constrain the physical read target (e.g. reading a
+ * file whose path could be a symlink to an untrusted location), that caller
+ * must realpath the target FIRST and then run containment on the resolved
+ * path — do not weaken this module's contract.
+ */
+
+import * as path from 'node:path';
+
+/**
+ * Canonicalize a user/operator-supplied path once. Every derived filesystem
+ * target must be compared against this canonical root.
+ */
+export function canonicalPath(p: string): string {
+  return path.resolve(p);
+}
+
+/**
+ * True when `candidate` is strictly inside `parent` (canonical comparison).
+ *
+ * - Both arguments are resolved against cwd first, so relative inputs work.
+ * - `candidate === parent` returns false (strict containment). Callers that
+ *   want to allow the root itself should check equality separately.
+ * - Sibling-prefix attacks (`/work/foobar` vs parent `/work/foo`) cannot
+ *   pass because `path.relative` yields a non-`..`-prefixed path only for
+ *   real descendants.
+ */
+export function isPathInside(parent: string, candidate: string): boolean {
+  const root = path.resolve(parent);
+  const target = path.resolve(candidate);
+  const rel = path.relative(root, target);
+  return (
+    rel !== '' &&
+    rel !== '..' &&
+    !rel.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(rel)
+  );
+}
+
+/**
+ * Throw unless `candidate` is strictly inside `parent`. `label` names the
+ * candidate in the error message (e.g. "--workspace").
+ */
+export function assertPathInside(parent: string, candidate: string, label: string): void {
+  if (!isPathInside(parent, candidate)) {
+    throw new Error(`Invalid ${label}: "${candidate}" is outside "${parent}"`);
+  }
+}
+
+/**
+ * Validate an operator-supplied directory root before it is used as an IO
+ * root: rejects empty values, residual parent-traversal segments, and
+ * filesystem-root results. Returns the canonical root.
+ *
+ * No `path.isAbsolute` requirement: absolute-ness is platform-dependent (a
+ * Windows-style path like `Z:\work` is not absolute on POSIX runners) and
+ * relative paths resolve inside cwd, so they carry no traversal risk. The
+ * guards that matter are: empty, parent traversal, and filesystem root.
+ */
+export function assertSafeDirectoryRoot(input: string, label: string): string {
+  if (!input || input.trim().length === 0) {
+    throw new Error(`Invalid ${label}: path is empty`);
+  }
+  // Un-normalized `..` segments that survive normalize() mean the input
+  // escaped a parent boundary (e.g. "..\\..\\evil") — reject rather than
+  // trust them. Foldable segments ("a/../b") canonicalize safely.
+  if (path.normalize(input).split(/[\\/]/).includes('..')) {
+    throw new Error(`Invalid ${label}: "${input}" contains parent traversal`);
+  }
+  const root = canonicalPath(input);
+  if (root === path.parse(root).root) {
+    throw new Error(`Invalid ${label}: "${input}" resolves to filesystem root`);
+  }
+  return root;
+}