fix(security): make missing SHA-256 checksums a hard error

jdalton · jdalton · commit ea9d5e1b79a5 · 2026-03-24T14:04:34.000-04:00
- Add requirePythonChecksum() and requireSocketPatchChecksum() functions
  that throw hard errors when checksums are missing in production builds
- Update spawn.mts and resolve-binary.mts to use the new require functions
- Update SEA build downloads.mjs to require checksums for all external tools
- Add scripts/validate-checksums.mjs for build-time checksum validation

In development mode (checksums not inlined), downloads proceed without
verification. In production builds (checksums inlined), missing checksums
cause immediate failures to prevent supply chain attacks.

This is a security hardening change to ensure all external tool downloads
are verified against known-good SHA-256 checksums.
diff --git a/packages/cli/scripts/sea-build-utils/downloads.mjs b/packages/cli/scripts/sea-build-utils/downloads.mjs
@@ -327,16 +327,25 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
     const tag = config.version
     const url = `https://github.com/${config.owner}/${config.repo}/releases/download/${tag}/${assetName}`
 
-    // Get SHA256 checksum if available in external-tools.json.
+    // Get SHA256 checksum from external-tools.json.
+    // SECURITY: Checksum verification is REQUIRED for all external tool downloads.
+    // If checksum is missing, the build MUST fail.
     const toolConfig = externalTools[toolName]
     const sha256 = toolConfig?.checksums?.[assetName]
 
+    if (!sha256) {
+      throw new Error(
+        `Missing SHA-256 checksum for ${toolName} asset: ${assetName}. ` +
+          'This is a security requirement. Please update external-tools.json with the correct checksum.',
+      )
+    }
+
     await httpDownload(url, archivePath, {
       logger,
       progressInterval: 10,
       retries: 2,
       retryDelay: 5000,
-      ...(sha256 && { sha256 }),
+      sha256,
     })
 
     // Extract binary (or handle standalone binaries).
diff --git a/packages/cli/src/env/python-checksums.mts b/packages/cli/src/env/python-checksums.mts
@@ -13,15 +13,51 @@ import type { PythonChecksums } from '../types.mjs'
 /**
  * Get Python checksums from inlined environment variable.
  * Returns a map of asset filename to SHA-256 hex checksum.
+ *
+ * @throws Error if checksums are missing in production builds.
  */
 export function getPythonChecksums(): PythonChecksums {
   const checksums = process.env['INLINED_SOCKET_CLI_PYTHON_CHECKSUMS']
   if (!checksums) {
+    // In development mode (not inlined), return empty object.
+    // Build validation will catch missing checksums at build time.
     return {}
   }
   try {
     return JSON.parse(checksums) as PythonChecksums
   } catch {
-    return {}
+    throw new Error(
+      'Failed to parse Python checksums. This indicates a build configuration error.',
+    )
+  }
+}
+
+/**
+ * Lookup a Python checksum by asset name.
+ * In production builds (checksums inlined), throws a hard error if asset is missing.
+ * In dev mode (checksums not inlined), returns undefined to allow development.
+ *
+ * @param assetName - The asset filename to look up.
+ * @returns The SHA-256 hex checksum, or undefined in dev mode.
+ * @throws Error if checksum is not found in production builds.
+ */
+export function requirePythonChecksum(assetName: string): string | undefined {
+  const checksums = getPythonChecksums()
+
+  // In dev mode, checksums are not inlined so the object is empty.
+  // Allow downloads without verification during development.
+  if (Object.keys(checksums).length === 0) {
+    return undefined
+  }
+
+  // In production mode, checksums are inlined.
+  // Require checksum for every asset - missing checksum is a HARD ERROR.
+  const sha256 = checksums[assetName]
+  if (!sha256) {
+    throw new Error(
+      `Missing SHA-256 checksum for Python asset: ${assetName}. ` +
+        'This is a security requirement. Please update external-tools.json with the correct checksum.',
+    )
   }
+  return sha256
 }
diff --git a/packages/cli/src/env/socket-patch-checksums.mts b/packages/cli/src/env/socket-patch-checksums.mts
@@ -13,15 +13,51 @@ import type { SocketPatchChecksums } from '../types.mjs'
 /**
  * Get Socket Patch checksums from inlined environment variable.
  * Returns a map of asset filename to SHA-256 hex checksum.
+ *
+ * @throws Error if checksums are missing in production builds.
  */
 export function getSocketPatchChecksums(): SocketPatchChecksums {
   const checksums = process.env['INLINED_SOCKET_CLI_SOCKET_PATCH_CHECKSUMS']
   if (!checksums) {
+    // In development mode (not inlined), return empty object.
+    // Build validation will catch missing checksums at build time.
     return {}
   }
   try {
     return JSON.parse(checksums) as SocketPatchChecksums
   } catch {
-    return {}
+    throw new Error(
+      'Failed to parse Socket Patch checksums. This indicates a build configuration error.',
+    )
+  }
+}
+
+/**
+ * Lookup a Socket Patch checksum by asset name.
+ * In production builds (checksums inlined), throws a hard error if asset is missing.
+ * In dev mode (checksums not inlined), returns undefined to allow development.
+ *
+ * @param assetName - The asset filename to look up.
+ * @returns The SHA-256 hex checksum, or undefined in dev mode.
+ * @throws Error if checksum is not found in production builds.
+ */
+export function requireSocketPatchChecksum(assetName: string): string | undefined {
+  const checksums = getSocketPatchChecksums()
+
+  // In dev mode, checksums are not inlined so the object is empty.
+  // Allow downloads without verification during development.
+  if (Object.keys(checksums).length === 0) {
+    return undefined
+  }
+
+  // In production mode, checksums are inlined.
+  // Require checksum for every asset - missing checksum is a HARD ERROR.
+  const sha256 = checksums[assetName]
+  if (!sha256) {
+    throw new Error(
+      `Missing SHA-256 checksum for Socket Patch asset: ${assetName}. ` +
+        'This is a security requirement. Please update external-tools.json with the correct checksum.',
+    )
   }
+  return sha256
 }
diff --git a/packages/cli/src/utils/dlx/resolve-binary.mts b/packages/cli/src/utils/dlx/resolve-binary.mts
@@ -13,7 +13,7 @@ import { SOCKET_CLI_PYCLI_LOCAL_PATH } from '../../env/socket-cli-pycli-local-pa
 import { SOCKET_CLI_SFW_LOCAL_PATH } from '../../env/socket-cli-sfw-local-path.mts'
 import { SOCKET_CLI_SOCKET_PATCH_LOCAL_PATH } from '../../env/socket-cli-socket-patch-local-path.mts'
 import { getSfwNpmVersion } from '../../env/sfw-version.mts'
-import { getSocketPatchChecksums } from '../../env/socket-patch-checksums.mts'
+import { requireSocketPatchChecksum } from '../../env/socket-patch-checksums.mts'
 import { getSocketPatchVersion } from '../../env/socket-patch-version.mts'
 import { getSynpVersion } from '../../env/synp-version.mts'
 
@@ -167,8 +167,9 @@ export function resolveSocketPatch(): BinaryResolution {
   }
 
   // Get SHA-256 checksum for integrity verification.
-  const checksums = getSocketPatchChecksums()
-  const sha256 = checksums[assetName]
+  // In dev mode (checksums not inlined), returns undefined to allow development.
+  // In production builds, missing checksums throw a HARD ERROR.
+  const sha256 = requireSocketPatchChecksum(assetName)
 
   return {
     type: 'github-release',
diff --git a/packages/cli/src/utils/dlx/spawn.mts b/packages/cli/src/utils/dlx/spawn.mts
@@ -52,7 +52,7 @@ import { getDefaultOrgSlug } from '../../commands/ci/fetch-default-org-slug.mjs'
 import { getCliVersion } from '../../env/cli-version.mts'
 import { getPyCliVersion } from '../../env/pycli-version.mts'
 import { getPythonBuildTag } from '../../env/python-build-tag.mts'
-import { getPythonChecksums } from '../../env/python-checksums.mts'
+import { requirePythonChecksum } from '../../env/python-checksums.mts'
 import { getPythonVersion } from '../../env/python-version.mts'
 import { SOCKET_CLI_PYTHON_PATH } from '../../env/socket-cli-python-path.mts'
 import { getSynpVersion } from '../../env/synp-version.mts'
@@ -947,8 +947,9 @@ async function downloadPython(pythonDir: string): Promise<void> {
   const tarballName = 'python-standalone.tar.gz'
 
   // Get SHA-256 checksum for integrity verification.
-  const checksums = getPythonChecksums()
-  const sha256 = checksums[assetName]
+  // In dev mode (checksums not inlined), returns undefined to allow development.
+  // In production builds, missing checksums throw a HARD ERROR.
+  const sha256 = requirePythonChecksum(assetName)
 
   await safeMkdir(pythonDir, { recursive: true })
 
diff --git a/scripts/validate-checksums.mjs b/scripts/validate-checksums.mjs
@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Build-time validation for SHA-256 checksums.
+ * Ensures all required platform-specific tool assets have checksums defined
+ * in external-tools.json before building SEA binaries.
+ *
+ * This script is a security requirement - builds MUST NOT proceed if any
+ * checksums are missing for downloadable binaries.
+ *
+ * Exit codes:
+ * - 0: All required checksums are present.
+ * - 1: One or more checksums are missing.
+ */
+
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import { PLATFORM_MAP_TOOLS } from '../packages/cli/scripts/constants/external-tools-platforms.mjs'
+
+const logger = getDefaultLogger()
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootPath = path.join(__dirname, '..')
+
+// Load external tools configuration.
+const externalToolsPath = path.join(
+  rootPath,
+  'packages/cli/external-tools.json',
+)
+const externalTools = JSON.parse(readFileSync(externalToolsPath, 'utf8'))
+
+/**
+ * Validate that all required checksums exist for external tools.
+ * @returns {boolean} True if all checksums are valid, false otherwise.
+ */
+function validateChecksums() {
+  const errors = []
+  const warnings = []
+
+  logger.info('Validating SHA-256 checksums for external tools...\n')
+
+  // Track all unique assets that need checksums.
+  const requiredAssets = new Map() // Map<toolName, Set<assetName>>
+
+  // Collect all assets needed across all platforms.
+  for (const [platform, tools] of Object.entries(PLATFORM_MAP_TOOLS)) {
+    if (!tools) continue
+
+    for (const [toolName, assetName] of Object.entries(tools)) {
+      if (!assetName) continue
+
+      if (!requiredAssets.has(toolName)) {
+        requiredAssets.set(toolName, new Set())
+      }
+      requiredAssets.get(toolName).add(assetName)
+    }
+  }
+
+  // Validate each tool's checksums.
+  for (const [toolName, assets] of requiredAssets) {
+    const toolConfig = externalTools[toolName]
+
+    if (!toolConfig) {
+      errors.push(`Tool "${toolName}" not found in external-tools.json`)
+      continue
+    }
+
+    // Only GitHub release tools need checksums.
+    if (toolConfig.type !== 'github-release') {
+      continue
+    }
+
+    const checksums = toolConfig.checksums || {}
+    const missingAssets = []
+
+    for (const assetName of assets) {
+      if (!checksums[assetName]) {
+        missingAssets.push(assetName)
+      }
+    }
+
+    if (missingAssets.length > 0) {
+      errors.push(
+        `Missing checksums for ${toolName}:\n` +
+          missingAssets.map(a => `    - ${a}`).join('\n'),
+      )
+    } else {
+      logger.success(`${toolName}: ${assets.size} asset checksum(s) verified`)
+    }
+  }
+
+  // Check for extra checksums that aren't used (informational).
+  for (const [toolName, toolConfig] of Object.entries(externalTools)) {
+    if (toolConfig.type !== 'github-release' || !toolConfig.checksums) {
+      continue
+    }
+
+    const usedAssets = requiredAssets.get(toolName) || new Set()
+    const extraAssets = Object.keys(toolConfig.checksums).filter(
+      asset => !usedAssets.has(asset),
+    )
+
+    if (extraAssets.length > 0) {
+      warnings.push(
+        `${toolName} has ${extraAssets.length} unused checksum(s) (may be for unsupported platforms)`,
+      )
+    }
+  }
+
+  // Print summary.
+  console.log('')
+  if (warnings.length > 0) {
+    logger.warn('Warnings:')
+    for (const warning of warnings) {
+      logger.warn(`  ${warning}`)
+    }
+    console.log('')
+  }
+
+  if (errors.length > 0) {
+    logger.error('CHECKSUM VALIDATION FAILED')
+    console.log('')
+    for (const error of errors) {
+      logger.error(error)
+    }
+    console.log('')
+    logger.error(
+      'All external tool assets MUST have SHA-256 checksums defined in external-tools.json.',
+    )
+    logger.error('This is a security requirement to prevent supply chain attacks.')
+    return false
+  }
+
+  logger.success('\nAll required checksums are present.')
+  return true
+}
+
+// Run validation.
+const valid = validateChecksums()
+process.exit(valid ? 0 : 1)
