fix: hardening pass from a fresh review (scanner, CI, app, site, docs) (#491)

Untrusted-binary safety in the scanner, supply-chain hardening in the release/scan workflows, app state-management fixes, SSR security headers, CLI robustness, and README/CLAUDE.md accuracy. All checks green; 187 tests pass under TSan/ASan.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: p-linnane

.github/workflows/release.yml

@@ -73,16 +73,20 @@ jobs:
       - name: Create temporary certificate file
         env:
           DEVELOPER_ID_CERTIFICATE: ${{ secrets.DEVELOPER_ID_CERTIFICATE }}
-        run: echo -n "${DEVELOPER_ID_CERTIFICATE}" |
-          base64 --decode --output="${RUNNER_TEMP}/${TEMPORARY_CERTIFICATE_FILE}"
+        run: |
+          set +x  # don't xtrace the base64-encoded certificate
+          echo -n "${DEVELOPER_ID_CERTIFICATE}" |
+            base64 --decode --output="${RUNNER_TEMP}/${TEMPORARY_CERTIFICATE_FILE}"
 
       - name: Import certificate into keychain
         env:
           DEVELOPER_ID_CERTIFICATE_PASSWORD: ${{ secrets.DEVELOPER_ID_CERTIFICATE_PASSWORD }}
-        run: security import "${RUNNER_TEMP}/${TEMPORARY_CERTIFICATE_FILE}"
-          -k "${RUNNER_TEMP}/${TEMPORARY_KEYCHAIN_FILE}"
-          -P "${DEVELOPER_ID_CERTIFICATE_PASSWORD}"
-          -t cert -f pkcs12 -A
+        run: |
+          set +x  # don't xtrace the certificate password
+          security import "${RUNNER_TEMP}/${TEMPORARY_CERTIFICATE_FILE}" \
+            -k "${RUNNER_TEMP}/${TEMPORARY_KEYCHAIN_FILE}" \
+            -P "${DEVELOPER_ID_CERTIFICATE_PASSWORD}" \
+            -t cert -f pkcs12 -A
 
       - name: Clean up temporary certificate file
         if: always()
@@ -173,6 +177,7 @@ jobs:
           NOTARIZATION_PASSWORD: ${{ secrets.NOTARIZATION_PASSWORD }}
           ARTIFACT_NAME: ${{ needs.build.outputs.artifact_name }}
         run: |
+          set +x  # keep the notarization password out of the xtrace log
           xcrun notarytool submit "${ARTIFACT_NAME}" \
             --team-id "${DEVELOPMENT_TEAM}" \
             --apple-id "${APPLE_ID}" \
@@ -185,9 +190,15 @@ jobs:
             "${ARTIFACT_NAME}"
 
       - name: Download Sparkle
+        env:
+          # Keep in lockstep with the Sparkle framework version in Package.resolved
+          # so the sign_update tool matches the runtime that verifies updates.
+          SPARKLE_VERSION: "2.9.2"
+          SPARKLE_SHA256: "1cb340cbbef04c6c0d162078610c25e2221031d794a3449d89f2f56f4df77c95"
         run: |
-          curl -L -o "${RUNNER_TEMP}/sparkle.tar.xz" \
-            "https://github.com/sparkle-project/Sparkle/releases/download/2.8.1/Sparkle-2.8.1.tar.xz"
+          curl -fL -o "${RUNNER_TEMP}/sparkle.tar.xz" \
+            "https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz"
+          echo "${SPARKLE_SHA256}  ${RUNNER_TEMP}/sparkle.tar.xz" | shasum -a 256 -c -
           mkdir -p "${RUNNER_TEMP}/sparkle"
           tar xf "${RUNNER_TEMP}/sparkle.tar.xz" -C "${RUNNER_TEMP}/sparkle"
 
@@ -196,6 +207,7 @@ jobs:
           SPARKLE_KEY: ${{ secrets.SPARKLE_PRIVATE_KEY }}
           ARTIFACT_NAME: ${{ needs.build.outputs.artifact_name }}
         run: |
+          set +x  # never xtrace the EdDSA private key
           SPARKLE_KEY_FILE="${RUNNER_TEMP}/sparkle_private_key"
           echo "${SPARKLE_KEY}" > "${SPARKLE_KEY_FILE}"
           SIG_OUTPUT=$("${RUNNER_TEMP}/sparkle/bin/sign_update" "${ARTIFACT_NAME}" --ed-key-file "${SPARKLE_KEY_FILE}" 2>&1)

.github/workflows/scan-xip.yml

@@ -101,6 +101,13 @@ jobs:
           BUILD: ${{ inputs.build_number }}
         run: |
           XIP_PATH=$(echo "${XIP_URL}" | sed -E 's/.*[?&]path=([^&]*).*/\1/')
+          # The ADCDownloadAuth secret cookie is sent to adcdownload.apple.com${XIP_PATH}.
+          # Reject anything that isn't a clean absolute .xip path so a value like
+          # "@evil.example.com/x.xip" can't redirect curl (and the cookie) to another host.
+          if [[ ! "${XIP_PATH}" =~ ^/[A-Za-z0-9._~%/+-]+\.xip$ ]]; then
+            echo "::error::Refusing to use download path '${XIP_PATH}': not a clean absolute .xip path."
+            exit 1
+          fi
           ORIG_NAME=$(basename "${XIP_PATH}")
           VERSION=$(echo "${ORIG_NAME}" | sed -E 's/Xcode_([0-9]+(\.[0-9]+)*).*/\1/')
           MAJOR=${VERSION%%.*}

CLAUDE.md

@@ -12,13 +12,13 @@ macOSdb scans Apple's IPSW firmware files and Xcode `.xip` archives, extracts ve
 
 ## Tracked components
 
-**Filesystem binaries:** curl, httpd, LibreSSL, OpenSSH, Ruby, SQLite, vim, zsh
+**Filesystem binaries:** curl, httpd, LibreSSL, OpenSSH, Ruby, sudo, SQLite, vim, zsh
 
 **Dyld shared cache:** libbz2, libcurl, libexpat, libncurses, libpcap, libsqlite3, libssl, libxml2
 
-**Xcode toolchain:** Apple Clang, cctools, Git, ld, lldb, Swift
+**Xcode toolchain:** Apple Clang, cctools, Git, ld, lldb, Python, Swift
 
-**SDK libraries:** bzip2, expat, libcurl, libedit, libexslt, libffi, libxml2, libxslt, ncurses, sqlite3, zlib
+**SDK libraries:** bzip2, expat, libcurl, libexslt, libffi, libxml2, libxslt, ncurses, sqlite3, zlib
 
 ## Installation
 
@@ -73,9 +73,13 @@ macosdb scan ~/Downloads/UniversalMac_15.2_24C101_Restore.ipsw \
 macosdb scan ~/Downloads/Xcode_26.4_Apple_silicon.xip \
   --output data/xcode/releases --release-date 2026-03-24 --update-index --verbose
 
-# Validate archives and create SHA-256 sidecar hashes
+# Validate archives: create SHA-256 sidecars, or verify against existing ones
 macosdb validate ~/Downloads/UniversalMac_15.2_24C101_Restore.ipsw
 macosdb validate --dir /path/to/archive
+
+# Clean up leftover mounted DMGs and temp directories from aborted scans
+macosdb cleanup            # dry run — list what would be removed
+macosdb cleanup --force    # actually unmount and delete
 ```
 
 ### Shell completions
@@ -135,10 +139,12 @@ just test           # Run Swift tests
 just lint           # Run SwiftLint (--strict)
 just lint-json      # Validate JSON data files
 just typos          # Check for typos
-just audit          # Audit GitHub Actions workflows
+just audit          # Audit GitHub Actions workflows (zizmor)
+just periphery      # Scan for unused code
 just build-app      # Build the app with xcodebuild
 just test-xcode     # Run tests with xcodebuild (matches CI)
-just check          # Run all checks (lint, lint-json, test, audit, site format, site build)
+just lychee         # Check the built site for broken links
+just check          # Run all checks (lint, lint-json, typos, audit, periphery, test, site format, site build)
 ```
 
 ### Site

README.md

@@ -44,10 +44,19 @@ public actor DataProvider {
     }
 
     public func fetchRelease(_ entry: ReleaseIndexEntry) async throws -> Release {
-        if let cached = cachedReleases[entry.buildNumber] {
+        // Build numbers aren't guaranteed unique across products, so namespace the
+        // cache key by product directory.
+        let cacheKey = "\(entry.resolvedProductType.dataDirectory)/\(entry.buildNumber)"
+        if let cached = cachedReleases[cacheKey] {
             return cached
         }
 
+        // dataFile comes from the index; reject path traversal so a crafted index
+        // can't read outside the data directory when baseURL is a local file:// path.
+        guard !entry.dataFile.contains("..") else {
+            throw DataProviderError.invalidDataFile(entry.dataFile)
+        }
+
         let relativePath = "\(entry.resolvedProductType.dataDirectory)/\(entry.dataFile)"
         let url = baseURL.appendingPathComponent(relativePath)
         Self.logger.debug("Fetching release data from \(url)")
@@ -57,7 +66,7 @@ public actor DataProvider {
 
         let decoder = JSONDecoder()
         let release = try decoder.decode(Release.self, from: data)
-        cachedReleases[entry.buildNumber] = release
+        cachedReleases[cacheKey] = release
 
         Self.logger.info("Loaded release: \(release.displayName) (\(release.buildNumber))")
         return release
@@ -125,13 +134,16 @@ public actor DataProvider {
 enum DataProviderError: LocalizedError {
     case httpError(statusCode: Int, url: URL)
     case allReleasesFailed(count: Int)
+    case invalidDataFile(String)
 
     var errorDescription: String? {
         switch self {
         case .httpError(let statusCode, let url):
             "HTTP \(statusCode) fetching \(url)"
         case .allReleasesFailed(let count):
             "Loaded the release index but failed to fetch any of its \(count) releases"
+        case .invalidDataFile(let path):
+            "Refusing to fetch release data with an unsafe path: \(path)"
         }
     }
 }

Sources/macOSdbKit/DataProvider.swift

@@ -131,6 +131,9 @@ actor AEADecryptor {
 
     private func validateHeader(_ header: Data) throws -> Int {
         let bytes = [UInt8](header)
+        guard bytes.count >= 12 else {
+            throw ScannerError.aeaDecryptionFailed(reason: "AEA header too short")
+        }
 
         guard bytes[0] == 0x41, bytes[1] == 0x45,
               bytes[2] == 0x41, bytes[3] == 0x31 else {

Sources/macOSdbKit/Scanner/AEADecryptor.swift

@@ -24,16 +24,18 @@ actor DMGMounter {
         process.standardError = stderr
 
         try process.run()
+        // Drain both pipes before waiting: a large -plist output on stdout could
+        // otherwise fill the pipe buffer and deadlock against waitUntilExit().
+        let outputData = stdout.fileHandleForReading.readDataToEndOfFile()
+        let errorData = stderr.fileHandleForReading.readDataToEndOfFile()
         process.waitUntilExit()
 
         guard process.terminationStatus == 0 else {
-            let errorData = stderr.fileHandleForReading.readDataToEndOfFile()
             let errorMessage = String(data: errorData, encoding: .utf8) ?? "unknown error"
             Self.logger.error("hdiutil attach failed: \(errorMessage)")
             throw ScannerError.dmgMountFailed(path: dmgPath.path, reason: errorMessage)
         }
 
-        let outputData = stdout.fileHandleForReading.readDataToEndOfFile()
         return try parseMountOutput(outputData, dmgPath: dmgPath.path)
     }
 
@@ -50,10 +52,10 @@ actor DMGMounter {
 
         do {
             try process.run()
+            let errorData = stderr.fileHandleForReading.readDataToEndOfFile()
             process.waitUntilExit()
 
             if process.terminationStatus != 0 {
-                let errorData = stderr.fileHandleForReading.readDataToEndOfFile()
                 let errorMessage = String(data: errorData, encoding: .utf8) ?? "unknown error"
                 Self.logger.warning("hdiutil detach warning: \(errorMessage)")
             }