@principles/pd-cli 1.152.12 → 1.152.14

package/src/utils/path-security.ts

@@ -1,96 +0,0 @@
-/**
- * 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;
-}

package/src/utils/production-workspace-guard.test.ts

@@ -1,157 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import * as path from 'path';
-import * as os from 'os';
-import {
-  isProductionWorkspace,
-  guardUatWorkspace,
-  getSafeUatWorkspacePath,
-  resolveWorkspacePath,
-  formatGuardRefusal,
-  type GuardRefusal,
-} from './production-workspace-guard.js';
-
-// Use os.homedir()-derived paths so the tests work cross-platform
-// (previously hardcoded Windows paths like D:\.openclaw\workspace which on
-// Linux resolve to <cwd>/D:\.openclaw\workspace — meaningless).
-const HOMEDIR_WORKSPACE = path.join(os.homedir(), '.openclaw', 'workspace');
-
-const PRODUCTION_PATHS = [
-  HOMEDIR_WORKSPACE,
-];
-
-const SAFE_PATHS = [
-  path.join(os.homedir(), '.openclaw', 'workspace-test'),
-  path.join(os.homedir(), '.openclaw', 'workspace-backup'),
-  path.join(os.tmpdir(), 'pd-uat-workspace'),
-  path.join(os.tmpdir(), 'pd-test-any'),
-  // A path that is clearly unrelated on every platform
-  path.join(os.tmpdir(), 'completely-unrelated-work'),
-];
-
-describe('isProductionWorkspace', () => {
-  it.each(PRODUCTION_PATHS)('detects production: %s', (prodPath) => {
-    expect(isProductionWorkspace(path.resolve(prodPath))).toBe(true);
-  });
-  it.each(SAFE_PATHS)('allows safe: %s', (safePath) => {
-    expect(isProductionWorkspace(path.resolve(safePath))).toBe(false);
-  });
-  it('detects descendant', () => {
-    const prodPath = path.resolve(HOMEDIR_WORKSPACE);
-    const descendantPath = path.join(prodPath, 'sub', 'child');
-    expect(isProductionWorkspace(descendantPath)).toBe(true);
-  });
-  it('rejects sibling workspace-test (ERR-030)', () => {
-    expect(isProductionWorkspace(path.resolve(path.join(os.homedir(), '.openclaw', 'workspace-test')))).toBe(false);
-  });
-  it('rejects sibling workspace-backup (ERR-030)', () => {
-    expect(isProductionWorkspace(path.resolve(path.join(os.homedir(), '.openclaw', 'workspace-backup')))).toBe(false);
-  });
-});
-
-describe('guardUatWorkspace', () => {
-  describe('refused', () => {
-    it.each(PRODUCTION_PATHS)('refuses production: %s', (prodPath) => {
-      const r = guardUatWorkspace(prodPath, 'test');
-      expect(r.refused).toBe(true);
-      if (r.refused) {
-        expect(r.reason).toContain('UAT/runtime test commands are not allowed');
-        expect(r.nextAction).toContain('temporary workspace');
-      }
-    });
-    it('refuses descendant', () => {
-      const prodPath = path.resolve(HOMEDIR_WORKSPACE);
-      const descendantPath = path.join(prodPath, 'subdir');
-      expect(guardUatWorkspace(descendantPath, 'test').refused).toBe(true);
-    });
-  });
-  describe('allowed', () => {
-    it.each(SAFE_PATHS)('allows safe: %s', (safePath) => {
-      const r = guardUatWorkspace(safePath, 'test');
-      expect(r.refused).toBe(false);
-    });
-    it.each([
-      path.join(os.homedir(), '.openclaw', 'workspace-test'),
-      path.join(os.homedir(), '.openclaw', 'workspace-backup'),
-    ])('allows sibling: %s (ERR-030)', (p) => {
-        expect(guardUatWorkspace(p, 'test').refused).toBe(false);
-      });
-  });
-});
-
-describe('JSON output (EP-04)', () => {
-  it('outputs single object with reason and nextAction', () => {
-    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
-    const json = formatGuardRefusal(r as GuardRefusal, 'test', true);
-    const parsed = JSON.parse(json);
-    expect(parsed).toMatchObject({
-      status: 'refused', reason: expect.any(String), nextAction: expect.any(String),
-      workspace: expect.any(String), isProduction: true,
-    });
-    expect(Array.isArray(parsed)).toBe(false);
-  });
-  it('no console prefixes in JSON', () => {
-    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
-    const json = formatGuardRefusal(r as GuardRefusal, 'test', true);
-    expect(json).not.toContain('[pd-cli]');
-    expect(json).not.toContain('ERROR:');
-    expect(json.trim().startsWith('{')).toBe(true);
-  });
-});
-
-describe('text output (EP-03)', () => {
-  it('includes reason and nextAction', () => {
-    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
-    const text = formatGuardRefusal(r as GuardRefusal, 'test', false);
-    expect(text).toContain('Reason:');
-    expect(text).toContain('Next Action:');
-  });
-});
-
-describe('getSafeUatWorkspacePath', () => {
-  it('returns deterministic temp path', () => {
-    const p1 = getSafeUatWorkspacePath();
-    const p2 = getSafeUatWorkspacePath();
-    expect(p1).toBe(p2);
-    expect(p1).toContain(os.tmpdir());
-    expect(p1).toContain('pd-uat-workspace');
-  });
-});
-
-describe('resolveWorkspacePath', () => {
-  it('resolves an absolute path as-is', () => {
-    const abs = path.resolve('/tmp/my-workspace');
-    expect(resolveWorkspacePath(abs)).toBe(abs);
-  });
-
-  it('resolves a relative path against cwd', () => {
-    const result = resolveWorkspacePath('relative/path');
-    const expected = path.resolve(process.cwd(), 'relative/path');
-    expect(result).toBe(expected);
-  });
-
-  it('defaults to cwd when no input is provided', () => {
-    const result = resolveWorkspacePath(undefined);
-    expect(result).toBe(path.resolve(process.cwd()));
-  });
-});
-
-describe('PD_PRODUCTION_WORKSPACE env var (module-load-time)', () => {
-  // NOTE: PRODUCTION_WORKSPACE_PATHS is built once at module load time from
-  // process.env.PD_PRODUCTION_WORKSPACE. Setting the env var after the module
-  // is loaded does NOT change behavior. These tests verify that the default
-  // production path (HOMEDIR_WORKSPACE) is correctly protected, which is the
-  // primary regression risk.
-
-  it('guardUatWorkspace refuses the default production workspace', () => {
-    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
-    expect(r.refused).toBe(true);
-    if (r.refused) {
-      expect(r.isProduction).toBe(true);
-      expect(r.workspace).toBe(path.resolve(HOMEDIR_WORKSPACE));
-    }
-  });
-
-  it('isProductionWorkspace returns true for the default production path', () => {
-    expect(isProductionWorkspace(path.resolve(HOMEDIR_WORKSPACE))).toBe(true);
-  });
-});

package/src/utils/production-workspace-guard.ts

@@ -1,210 +0,0 @@
-/**
- * Production Workspace Guard
- *
- * Prevents UAT/runtime test commands from writing to production workspaces.
- *
- * Production workspaces:
- * - Default: ~/.openclaw/workspace (cross-platform)
- * - Additional paths declared via PD_PRODUCTION_WORKSPACE env var
- *   (use path.delimiter — `;` on Windows, `:` on Unix — to separate multiple paths)
- *
- * This module follows ERR-030 (path prefix matching must use segment boundaries)
- * and EP-03/EP-04 (fail loud with structured reason and nextAction).
- */
-
-import * as path from 'path';
-import * as os from 'os';
-import { existsSync } from 'fs';
-
-// ── Production workspace paths ─────────────────────────────────────────────────
-
-/**
- * List of production workspace paths that should be protected from UAT/test writes.
- * Built from: the universal default (~/.openclaw/workspace) plus any paths
- * declared via PD_PRODUCTION_WORKSPACE.
- */
-function buildProductionWorkspacePaths(): string[] {
-  const paths = [path.resolve(path.join(os.homedir(), '.openclaw', 'workspace'))];
-  const extra = process.env.PD_PRODUCTION_WORKSPACE;
-  if (extra) {
-    for (const p of extra.split(path.delimiter)) {
-      const trimmed = p.trim();
-      if (trimmed) paths.push(path.resolve(trimmed));
-    }
-  }
-  return paths;
-}
-
-const PRODUCTION_WORKSPACE_PATHS = buildProductionWorkspacePaths();
-
-// ── Resolution helpers ───────────────────────────────────────────────────────
-
-/**
- * Resolve the workspace path from environment variable or current directory.
- */
-export function resolveWorkspacePath(inputPath?: string): string {
-  if (!inputPath) {
-    // Default to current directory
-    return path.resolve(process.cwd());
-  }
-  return path.resolve(inputPath);
-}
-
-/**
- * Check if a path is a production workspace.
- *
- * This follows ERR-030: path matching must use segment boundaries (path.sep)
- * to avoid false positives on sibling directories like "workspace-backup".
- *
- * @param resolvedPath - The absolute, normalized workspace path to check
- * @returns true if the path is a production workspace
- */
-export function isProductionWorkspace(resolvedPath: string): boolean {
-  const normalized = resolvedPath.toLowerCase();
-
-  for (const prodPath of PRODUCTION_WORKSPACE_PATHS) {
-    const normalizedProd = prodPath.toLowerCase();
-
-    // Exact match
-    if (normalized === normalizedProd) {
-      return true;
-    }
-
-    // Descendant match: must have path separator after prefix
-    // ERR-030: "startsWith" without separator matches sibling directories
-    if (normalized.startsWith(normalizedProd + path.sep)) {
-      return true;
-    }
-
-    // Handle Windows path variations
-    // D:\.openclaw\workspace should not match D:\.openclaw\workspace-backup
-    // Use case-insensitive comparison (already normalized)
-    if (path.sep === '\\') {
-      // Windows: check both forward and backslash
-      if (normalized.startsWith(normalizedProd + '/')) {
-        return true;
-      }
-      if (normalized.startsWith(normalizedProd.replace(/\\/g, '/') + '/')) {
-        return true;
-      }
-      if (normalized.startsWith(normalizedProd.replace(/\\/g, '/') + '\\')) {
-        return true;
-      }
-    }
-  }
-
-  return false;
-}
-
-// ── Guard logic ──────────────────────────────────────────────────────────────
-
-/**
- * Guard result for UAT/test commands attempting to write to production workspace.
- */
-export interface GuardRefusal {
-  refused: true;
-  reason: string;
-  nextAction: string;
-  workspace: string;
-  isProduction: true;
-}
-
-/**
- * Guard result allowing the operation.
- */
-export interface GuardAllowed {
-  refused: false;
-  workspace: string;
-  isProduction: false;
-}
-
-export type GuardResult = GuardRefusal | GuardAllowed;
-
-/**
- * Check if a workspace is protected from UAT/test writes.
- *
- * This is the main guard function for UAT/runtime test commands.
- * It returns a structured result following EP-03/EP-04 requirements.
- *
- * @param inputPath - The workspace path to check (optional, resolves to cwd if not provided)
- * @param commandContext - Context string for the error message (e.g., "pd runtime uat")
- * @returns GuardResult indicating if the operation is allowed or refused
- */
-export function guardUatWorkspace(
-  inputPath: string | undefined,
-  _commandContext: string
-): GuardResult {
-  const resolved = resolveWorkspacePath(inputPath);
-
-  // PRI-334: Guard check should happen BEFORE file existence check
-  // This prevents production workspace writes even if directory doesn't exist yet
-  if (isProductionWorkspace(resolved)) {
-    return {
-      refused: true,
-      workspace: resolved,
-      isProduction: true,
-      reason: `UAT/runtime test commands are not allowed to write to the production workspace (${resolved}). This prevents test/synthetic data from polluting your real PD state.`,
-      nextAction: `Use a temporary workspace for testing (recommended: ${os.tmpdir()}/pd-uat-workspace) or explicitly confirm you understand the risk by using --allow-production-workspace-for-uat (not recommended).`,
-    };
-  }
-
-  if (!existsSync(resolved)) {
-    // Non-existent workspace is safe to use (will be created)
-    return {
-      refused: false,
-      workspace: resolved,
-      isProduction: false,
-    };
-  }
-
-  return {
-    refused: false,
-    workspace: resolved,
-    isProduction: false,
-  };
-}
-
-/**
- * Get a safe UAT workspace path in the system temp directory.
- *
- * This follows the safe execution path requirement from PRI-334.
- */
-export function getSafeUatWorkspacePath(): string {
-  const tempDir = os.tmpdir();
-  // Create a unique but deterministic path for UAT workspaces
-  const uatWorkspace = path.join(tempDir, 'pd-uat-workspace');
-  return uatWorkspace;
-}
-
-/**
- * Format guard refusal for console output.
- *
- * Follows EP-03/EP-04: structured reason + nextAction.
- */
-export function formatGuardRefusal(refusal: GuardRefusal, commandContext: string, jsonMode = false): string {
-  if (jsonMode) {
-    // JSON mode: output exactly one JSON object with reason and nextAction
-    return JSON.stringify(
-      {
-        status: 'refused',
-        reason: refusal.reason,
-        nextAction: refusal.nextAction,
-        workspace: refusal.workspace,
-        isProduction: refusal.isProduction,
-      },
-      null,
-      2
-    );
-  }
-
-  // Text mode: human-readable structured output
-  return [
-    `[pd-cli] ERROR: ${commandContext} - workspace guard triggered`,
-    '',
-    `Reason: ${refusal.reason}`,
-    `Next Action: ${refusal.nextAction}`,
-    `Workspace: ${refusal.workspace}`,
-    '',
-    'This guard prevents UAT/runtime test data from polluting your production workspace.',
-  ].join('\n');
-}