bmad-cybersec 2.0.0

package/lib/downloader.js

@@ -0,0 +1,297 @@
+import { createWriteStream } from 'fs';
+import { pipeline } from 'stream/promises';
+import { createHash } from 'crypto';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdir, rm, readFile } from 'fs/promises';
+import ora from 'ora';
+import { CONFIG } from './config.js';
+import { logger } from './logger.js';
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Allowed URL hosts for SSRF protection
+ * Only URLs from these domains are permitted for downloads
+ */
+const ALLOWED_HOSTS = [
+  'api.github.com',
+  'github.com',
+  'objects.githubusercontent.com',
+  'github-releases.githubusercontent.com',
+  'codeload.github.com'
+];
+
+/**
+ * Validates a URL against the allowed hosts to prevent SSRF attacks
+ * @param {string} urlString - The URL to validate
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateDownloadUrl(urlString) {
+  try {
+    const url = new URL(urlString);
+
+    // Must be HTTPS
+    if (url.protocol !== 'https:') {
+      return {
+        valid: false,
+        error: `Only HTTPS URLs are allowed. Received: ${url.protocol}`
+      };
+    }
+
+    // Must be from allowed host
+    const hostname = url.hostname.toLowerCase();
+    const isAllowed = ALLOWED_HOSTS.some(allowed =>
+      hostname === allowed || hostname.endsWith('.' + allowed)
+    );
+
+    if (!isAllowed) {
+      return {
+        valid: false,
+        error: `URL host "${hostname}" is not in the allowed list: ${ALLOWED_HOSTS.join(', ')}`
+      };
+    }
+
+    return { valid: true };
+  } catch {
+    return {
+      valid: false,
+      error: `Invalid URL format: ${urlString}`
+    };
+  }
+}
+
+/**
+ * Validates and fetches from a URL with SSRF protection
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Fetch options
+ * @returns {Promise<Response>}
+ * @throws {Error} If URL validation fails
+ */
+async function safeFetch(url, options = {}) {
+  const validation = validateDownloadUrl(url);
+  if (!validation.valid) {
+    throw new Error(`Security: ${validation.error}`);
+  }
+  return fetch(url, options);
+}
+
+/**
+ * Downloads a release tarball from GitHub
+ * @description Fetches release information from GitHub API, downloads the tarball asset,
+ * and optionally verifies the checksum. Falls back to source tarball if no release asset found.
+ * @param {Object} [options={}] - Download options
+ * @param {string} [options.version='latest'] - Release version tag (e.g., 'v2.0.0' or 'latest')
+ * @param {string|null} [options.branch=null] - Branch name for development builds (currently unused)
+ * @returns {Promise<string>} Path to the downloaded tarball in the temp directory
+ * @throws {Error} If release not found, download fails, or checksum verification fails
+ * @example
+ * // Download latest release
+ * const tarballPath = await downloadRelease();
+ *
+ * @example
+ * // Download specific version
+ * const tarballPath = await downloadRelease({ version: 'v2.0.0' });
+ */
+export async function downloadRelease(options = {}) {
+  const { version = 'latest', branch = null } = options;
+  const spinner = ora();
+
+  try {
+    // 1. Get release info from GitHub API
+    spinner.start('Fetching release information...');
+    const release = await fetchReleaseInfo(version);
+    spinner.succeed(`Found release: ${release.tag_name}`);
+
+    // 2. Find tarball and checksum assets
+    const tarballAsset = release.assets.find(a => a.name.endsWith('.tar.gz'));
+    const checksumAsset = release.assets.find(a => a.name.endsWith('.sha256'));
+
+    if (!tarballAsset) {
+      // Fallback to source tarball
+      logger.info('No release tarball found, using source archive');
+      return await downloadSourceTarball(release.tarball_url, release.tag_name);
+    }
+
+    // 3. Download with progress
+    spinner.start(`Downloading ${tarballAsset.name}...`);
+    const tarballPath = await downloadWithProgress(
+      tarballAsset.browser_download_url,
+      tarballAsset.name,
+      tarballAsset.size
+    );
+    spinner.succeed('Download complete');
+
+    // 4. Verify checksum - MANDATORY for release assets
+    if (checksumAsset) {
+      spinner.start('Verifying checksum...');
+      await verifyChecksum(tarballPath, checksumAsset.browser_download_url);
+      spinner.succeed('Checksum verified');
+    } else {
+      // Security: Checksum verification is MANDATORY for release tarballs
+      spinner.fail('Security: No checksum file found');
+      await rm(tarballPath, { force: true });
+      throw new Error(
+        'Security: Checksum verification is mandatory for release downloads. ' +
+        'The release is missing a .sha256 checksum file. ' +
+        'Use --from-git to clone directly if this is intentional.'
+      );
+    }
+
+    return tarballPath;
+
+  } catch (error) {
+    spinner.fail(`Download failed: ${error.message}`);
+    throw error;
+  }
+}
+
+async function fetchReleaseInfo(version) {
+  const endpoint = version === 'latest'
+    ? `${GITHUB_API}/repos/${CONFIG.GITHUB_OWNER}/${CONFIG.GITHUB_REPO}/releases/latest`
+    : `${GITHUB_API}/repos/${CONFIG.GITHUB_OWNER}/${CONFIG.GITHUB_REPO}/releases/tags/${version}`;
+
+  const headers = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'bmad-cyber-installer'
+  };
+
+  // Add auth token if available
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+
+  const response = await fetchWithRetry(endpoint, { headers });
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`Release ${version} not found`);
+    }
+    if (response.status === 403) {
+      throw new Error('GitHub API rate limit exceeded. Set GITHUB_TOKEN or try again later.');
+    }
+    throw new Error(`GitHub API error: ${response.status}`);
+  }
+
+  return response.json();
+}
+
+async function downloadSourceTarball(url, tagName) {
+  const tempDir = join(tmpdir(), CONFIG.TEMP_DIR_PREFIX);
+  await mkdir(tempDir, { recursive: true });
+
+  const filename = `${tagName}.tar.gz`;
+  const filePath = join(tempDir, filename);
+
+  const headers = {
+    'User-Agent': 'bmad-cyber-installer'
+  };
+
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+
+  const response = await fetchWithRetry(url, { headers });
+
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.status}`);
+  }
+
+  const fileStream = createWriteStream(filePath);
+  await pipeline(response.body, fileStream);
+
+  return filePath;
+}
+
+async function downloadWithProgress(url, filename, expectedSize) {
+  const tempDir = join(tmpdir(), CONFIG.TEMP_DIR_PREFIX);
+  await mkdir(tempDir, { recursive: true });
+
+  const filePath = join(tempDir, filename);
+
+  const headers = {
+    'User-Agent': 'bmad-cyber-installer'
+  };
+
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+
+  const response = await fetchWithRetry(url, { headers });
+
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.status}`);
+  }
+
+  const fileStream = createWriteStream(filePath);
+  await pipeline(response.body, fileStream);
+
+  return filePath;
+}
+
+async function verifyChecksum(filePath, checksumUrl) {
+  const headers = {
+    'User-Agent': 'bmad-cyber-installer'
+  };
+
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+
+  // Download checksum file (with SSRF protection)
+  const response = await safeFetch(checksumUrl, { headers });
+  if (!response.ok) {
+    throw new Error(`Failed to download checksum file: ${response.status}`);
+  }
+  const checksumContent = await response.text();
+  const expectedHash = checksumContent.split(' ')[0].trim();
+
+  // Validate hash format (should be 64 hex characters for SHA256)
+  if (!/^[a-fA-F0-9]{64}$/.test(expectedHash)) {
+    throw new Error('Invalid checksum format in checksum file');
+  }
+
+  // Calculate actual hash
+  const fileBuffer = await readFile(filePath);
+  const hash = createHash('sha256').update(fileBuffer).digest('hex');
+
+  if (hash.toLowerCase() !== expectedHash.toLowerCase()) {
+    await rm(filePath);
+    throw new Error('Checksum verification failed. File may be corrupted or tampered with.');
+  }
+}
+
+async function fetchWithRetry(url, options = {}, retries = 3) {
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      // Use safeFetch for SSRF protection
+      return await safeFetch(url, options);
+    } catch (error) {
+      // Don't retry security validation errors
+      if (error.message.startsWith('Security:')) {
+        throw error;
+      }
+      if (attempt === retries) throw error;
+      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+      logger.info(`Retry ${attempt}/${retries} after ${delay}ms...`);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+}
+
+/**
+ * Cleans up temporary download files
+ * @description Removes the temporary directory used for storing downloaded tarballs.
+ * Silently ignores any cleanup errors.
+ * @returns {Promise<void>}
+ * @example
+ * await cleanup();
+ */
+export async function cleanup() {
+  const tempDir = join(tmpdir(), CONFIG.TEMP_DIR_PREFIX);
+  try {
+    await rm(tempDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+}

package/lib/extractor.js

@@ -0,0 +1,353 @@
+import tar from 'tar';
+import { existsSync, promises as fs, realpathSync } from 'fs';
+import { join, dirname, basename, resolve, relative, normalize } from 'path';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import { logger } from './logger.js';
+
+/**
+ * Validates that a path does not escape the target directory (zip-slip protection)
+ * @param {string} targetDir - The target extraction directory (absolute path)
+ * @param {string} entryPath - The path from the archive entry
+ * @returns {{ safe: boolean, resolvedPath?: string, error?: string }}
+ */
+function validatePathSafety(targetDir, entryPath) {
+  // Normalize and resolve the full path
+  const normalizedEntry = normalize(entryPath).replace(/\\/g, '/');
+
+  // Reject paths with suspicious patterns BEFORE resolution
+  if (normalizedEntry.includes('..') ||
+      normalizedEntry.startsWith('/') ||
+      normalizedEntry.includes('//')) {
+    return {
+      safe: false,
+      error: `Path traversal detected: "${entryPath}"`
+    };
+  }
+
+  // Resolve to absolute path
+  const resolvedPath = resolve(targetDir, normalizedEntry);
+
+  // Ensure the resolved path is within the target directory
+  const relativePath = relative(targetDir, resolvedPath);
+  if (relativePath.startsWith('..') || resolve(targetDir, relativePath) !== resolvedPath) {
+    return {
+      safe: false,
+      error: `Path escapes target directory: "${entryPath}" resolves to "${resolvedPath}"`
+    };
+  }
+
+  return { safe: true, resolvedPath };
+}
+
+/**
+ * Validates that a symlink target stays within the extraction directory
+ * @param {string} targetDir - The target extraction directory
+ * @param {string} linkPath - The path where the symlink will be created
+ * @param {string} linkTarget - The target of the symlink
+ * @returns {{ safe: boolean, error?: string }}
+ */
+function validateSymlinkSafety(targetDir, linkPath, linkTarget) {
+  // Resolve the symlink target relative to the link's directory
+  const linkDir = dirname(linkPath);
+  const resolvedTarget = resolve(linkDir, linkTarget);
+
+  // Ensure the target stays within the extraction directory
+  const relativePath = relative(targetDir, resolvedTarget);
+  if (relativePath.startsWith('..')) {
+    return {
+      safe: false,
+      error: `Symlink "${linkPath}" points outside target directory to "${linkTarget}"`
+    };
+  }
+
+  return { safe: true };
+}
+
+const ALWAYS_SKIP = [
+  '.git/',
+  '.github/',
+  'node_modules/',
+  '*.test.js',
+  '*.test.ts',
+  '*.spec.js',
+  '*.spec.ts',
+  'coverage/',
+  '.nyc_output/',
+  '__tests__/'
+];
+
+const PRIORITY_FILES = [
+  '_bmad/',
+  '.claude/',
+  'src/utility/tools/',
+  'CLAUDE.md'
+];
+
+const OPTIONAL_FILES = {
+  withDocs: ['Docs/'],
+  withDev: ['dev-tools/']
+};
+
+/**
+ * Extracts framework files from a tarball to the target directory
+ * @description Extracts files from a downloaded tarball, filtering out unnecessary files
+ * (tests, node_modules, etc.) and optionally handling file conflicts with existing files.
+ * @param {string} tarballPath - Path to the tarball file to extract
+ * @param {string} targetDir - Target directory to extract files into
+ * @param {Object} [options={}] - Extraction options
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite existing files without prompting
+ * @param {boolean} [options.force=false] - Force extraction without conflict checking
+ * @param {boolean} [options.withDocs=false] - Include documentation files in extraction
+ * @param {boolean} [options.withDev=false] - Include development tools in extraction
+ * @param {boolean} [options.dryRun=false] - List files without extracting
+ * @returns {Promise<Object>} Extraction result object
+ * @returns {boolean} [returns.success] - True if extraction completed successfully
+ * @returns {boolean} [returns.cancelled] - True if user cancelled the operation
+ * @returns {boolean} [returns.dryRun] - True if this was a dry run
+ * @returns {number} returns.filesExtracted - Number of files extracted (0 for dry run or cancel)
+ * @returns {string[]} [returns.files] - List of files (only in dry run mode)
+ * @throws {Error} If tarball extraction fails
+ * @example
+ * // Basic extraction
+ * const result = await extractFramework('./release.tar.gz', './my-project');
+ *
+ * @example
+ * // Dry run to preview files
+ * const result = await extractFramework('./release.tar.gz', './my-project', { dryRun: true });
+ * console.log(result.files);
+ */
+export async function extractFramework(tarballPath, targetDir, options = {}) {
+  const {
+    overwrite = false,
+    force = false,
+    withDocs = false,
+    withDev = false,
+    dryRun = false
+  } = options;
+
+  const spinner = ora();
+
+  // 1. Build file filter
+  const filter = buildFilter({ withDocs, withDev });
+
+  // 2. If not force, check for conflicts
+  if (!force && !dryRun) {
+    spinner.start('Checking for existing files...');
+    const conflicts = await findConflicts(tarballPath, targetDir, filter);
+    spinner.stop();
+
+    if (conflicts.length > 0) {
+      const action = await promptOverwrite(conflicts);
+      if (action === 'cancel') {
+        return { cancelled: true, filesExtracted: 0 };
+      }
+      if (action === 'skip') {
+        // Add conflicts to skip list
+        filter.skipFiles = conflicts;
+      }
+    }
+  }
+
+  // 3. Dry run - just list files
+  if (dryRun) {
+    spinner.start('Analyzing tarball contents...');
+    const files = await listTarballContents(tarballPath, filter);
+    spinner.stop();
+
+    logger.info('\nFiles that would be extracted:');
+    files.forEach(f => logger.info(`  ${f}`));
+    logger.info(`\nTotal: ${files.length} files`);
+
+    return { dryRun: true, files, filesExtracted: 0 };
+  }
+
+  // 4. Extract with security validations
+  spinner.start('Extracting framework files...');
+  let fileCount = 0;
+  const securityViolations = [];
+  const absoluteTargetDir = resolve(targetDir);
+
+  await tar.extract({
+    file: tarballPath,
+    cwd: targetDir,
+    strip: 1, // Remove top-level directory
+    filter: (path, entry) => {
+      // First check normal filtering
+      if (!shouldExtract(path, filter)) {
+        return false;
+      }
+
+      // Security: Validate path does not escape target directory (zip-slip protection)
+      // After strip:1, we need to check the resulting path
+      const parts = path.split('/');
+      parts.shift(); // Remove top-level directory (strip: 1)
+      const strippedPath = parts.join('/');
+
+      if (strippedPath) {
+        const pathValidation = validatePathSafety(absoluteTargetDir, strippedPath);
+        if (!pathValidation.safe) {
+          securityViolations.push(pathValidation.error);
+          logger.warn(`Security: Skipping unsafe path - ${pathValidation.error}`);
+          return false;
+        }
+
+        // Security: Validate symlinks don't point outside target directory
+        if (entry.type === 'SymbolicLink' && entry.linkpath) {
+          const symlinkValidation = validateSymlinkSafety(
+            absoluteTargetDir,
+            pathValidation.resolvedPath,
+            entry.linkpath
+          );
+          if (!symlinkValidation.safe) {
+            securityViolations.push(symlinkValidation.error);
+            logger.warn(`Security: Skipping unsafe symlink - ${symlinkValidation.error}`);
+            return false;
+          }
+        }
+      }
+
+      fileCount++;
+      return true;
+    },
+    onentry: (entry) => {
+      // Preserve permissions
+      if (entry.mode) {
+        entry.mode = entry.mode;
+      }
+    }
+  });
+
+  if (securityViolations.length > 0) {
+    logger.warn(`\nSecurity: ${securityViolations.length} potentially malicious entries were blocked during extraction.`);
+  }
+
+  spinner.succeed(`Extracted ${fileCount} files`);
+
+  return { success: true, filesExtracted: fileCount };
+}
+
+function buildFilter({ withDocs, withDev }) {
+  const skip = [...ALWAYS_SKIP];
+  const include = [...PRIORITY_FILES];
+
+  if (withDocs) {
+    include.push(...OPTIONAL_FILES.withDocs);
+  } else {
+    skip.push('Docs/');
+  }
+
+  if (withDev) {
+    include.push(...OPTIONAL_FILES.withDev);
+  } else {
+    skip.push('dev-tools/');
+  }
+
+  return { skip, include, skipFiles: [] };
+}
+
+function shouldExtract(path, filter) {
+  // Normalize path
+  const normalizedPath = path.replace(/\\/g, '/');
+
+  // Check explicit skip files
+  if (filter.skipFiles.includes(normalizedPath)) {
+    return false;
+  }
+
+  // Check always-skip patterns
+  for (const pattern of filter.skip) {
+    if (pattern.endsWith('/')) {
+      if (normalizedPath.includes(pattern) || normalizedPath.startsWith(pattern)) {
+        return false;
+      }
+    } else if (pattern.startsWith('*')) {
+      const ext = pattern.slice(1);
+      if (normalizedPath.endsWith(ext)) {
+        return false;
+      }
+    } else if (normalizedPath === pattern || normalizedPath.includes(`/${pattern}`)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function findConflicts(tarballPath, targetDir, filter) {
+  const conflicts = [];
+
+  // List tarball contents
+  const entries = [];
+  await tar.list({
+    file: tarballPath,
+    onentry: (entry) => {
+      if (entry.type === 'File' && shouldExtract(entry.path, filter)) {
+        // Remove top-level directory from path
+        const parts = entry.path.split('/');
+        parts.shift();
+        const relativePath = parts.join('/');
+        if (relativePath) {
+          entries.push(relativePath);
+        }
+      }
+    }
+  });
+
+  // Check for existing files
+  for (const entry of entries) {
+    const fullPath = join(targetDir, entry);
+    if (existsSync(fullPath)) {
+      conflicts.push(entry);
+    }
+  }
+
+  return conflicts;
+}
+
+async function promptOverwrite(conflicts) {
+  console.log('\n');
+  logger.warn(`Found ${conflicts.length} existing files that would be overwritten:`);
+
+  // Show first 10 conflicts
+  const shown = conflicts.slice(0, 10);
+  shown.forEach(f => logger.info(`  - ${f}`));
+  if (conflicts.length > 10) {
+    logger.info(`  ... and ${conflicts.length - 10} more`);
+  }
+
+  const { action } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'How would you like to handle existing files?',
+      choices: [
+        { name: 'Overwrite all', value: 'overwrite' },
+        { name: 'Skip existing files', value: 'skip' },
+        { name: 'Cancel installation', value: 'cancel' }
+      ]
+    }
+  ]);
+
+  return action;
+}
+
+async function listTarballContents(tarballPath, filter) {
+  const files = [];
+
+  await tar.list({
+    file: tarballPath,
+    onentry: (entry) => {
+      if (entry.type === 'File' && shouldExtract(entry.path, filter)) {
+        const parts = entry.path.split('/');
+        parts.shift();
+        const relativePath = parts.join('/');
+        if (relativePath) {
+          files.push(relativePath);
+        }
+      }
+    }
+  });
+
+  return files.sort();
+}