fix: adversarial audit follow-ups (security, proxy, lifecycle)

.github/workflows/release.yml

@@ -21,6 +21,9 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    concurrency:
+      group: release
+      cancel-in-progress: false
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: pnpm/action-setup@d9184bf108216479bc5a137cc391f4d7b14c870b # v6.1.0
@@ -31,6 +34,7 @@ jobs:
           node-version: 26
           registry-url: https://registry.npmjs.org/
           cache: pnpm
+      - run: pnpm install --frozen-lockfile
 
       - name: Bump and push version
         if: inputs.upgrade != 'existing'

.gitignore

@@ -6,6 +6,7 @@ node_modules
 build
 dist
 *.tsbuildinfo
+.cache
 
 # Test-generated certificate directories
 test/custom-folder/

README.md

@@ -26,11 +26,12 @@ Usage notes:
   - `--cert-path <path>`: custom certificate directory (`CERT_PATH`)
   - `--reinstall`: force certificate re-generation (`REINSTALL=true`)
   - `--proxy <url>`: proxy all requests to the given http(s) URL (`PROXY_TARGET`)
+  - `-h, --help`: display help
 - Specifying a port number prevents HTTP to HTTPS redirect.
 
 ## Use as module
 
-Install as a dependency:
+Install as a dev dependency:
 
 ```sh
 npm i -D https-localhost

package.json

@@ -38,7 +38,8 @@
       "types": "./src/certs.ts",
       "import": "./src/certs.ts",
       "default": "./src/certs.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "main": "dist/cjs/index.js",
@@ -56,11 +57,14 @@
         "import": "./dist/esm/certs.js",
         "require": "./dist/cjs/certs.js",
         "default": "./dist/esm/certs.js"
-      }
+      },
+      "./package.json": "./package.json"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc --project tsconfig.build.esm.json && tsc --project tsconfig.build.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "build": "pnpm run build:esm && pnpm run build:cjs",
+    "build:esm": "tsc --project tsconfig.build.esm.json && node -e \"fs.writeFileSync('dist/esm/package.json', JSON.stringify({ type: 'module' }))\"",
+    "build:cjs": "tsc --project tsconfig.build.cjs.json && node -e \"fs.writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))\"",
     "fix": "oxfmt && oxlint --fix && knip && tsc --noEmit",
     "lint": "oxfmt --check && oxlint && knip && tsc --noEmit",
     "test": "node --test-concurrency=1 --test test/*.test.ts",
@@ -93,5 +97,13 @@
   "engines": {
     "node": ">=24"
   },
-  "packageManager": "pnpm@12.3.4"
+  "packageManager": "pnpm@12.3.4",
+  "pkg": {
+    "scripts": "*.js",
+    "targets": [
+      "node16-macos-x64",
+      "node16-linux-x64",
+      "node16-win-x64"
+    ]
+  }
 }

src/certs.ts

@@ -17,46 +17,98 @@ export type CertificatePair = {
 function getExe(): string {
   switch (process.platform) {
     case "darwin":
+      if (process.arch === "arm64") return `mkcert-${MKCERT_VERSION}-darwin-arm64`
       return `mkcert-${MKCERT_VERSION}-darwin-amd64`
     case "linux":
-      if (process.arch === "arm" || process.arch === "arm64") {
-        return `mkcert-${MKCERT_VERSION}-linux-arm`
-      }
+      if (process.arch === "arm64") return `mkcert-${MKCERT_VERSION}-linux-arm64`
+      if (process.arch === "arm") return `mkcert-${MKCERT_VERSION}-linux-arm`
       return `mkcert-${MKCERT_VERSION}-linux-amd64`
     case "win32":
       return `mkcert-${MKCERT_VERSION}-windows-amd64.exe`
     default:
-      console.error(
-        "Cannot generate the localhost certificate on your " +
-          "platform. Please, consider contacting the developer if you can help.",
+      throw new Error(
+        "Cannot generate the localhost certificate on your platform " +
+          `(${process.platform}-${process.arch}). Please, consider contacting the developer if you can help.`,
       )
-      process.exit(0)
+  }
+}
+
+const MAX_REDIRECTS = 5
+
+// mkcert release binaries are a few MB; a truncated or empty cache (e.g. an
+// interrupted download or an error page written by older versions) must be
+// re-downloaded instead of failing exec with a cryptic error forever.
+const MIN_EXECUTABLE_SIZE = 1024 * 1024
+
+function isValidCachedExecutable(exePath: string): boolean {
+  try {
+    const stat = fs.statSync(exePath)
+    return (
+      stat.isFile() &&
+      stat.size >= MIN_EXECUTABLE_SIZE &&
+      fs.accessSync(exePath, fs.constants.X_OK) === undefined
+    )
+  } catch {
+    return false
   }
 }
 
 async function download(url: string, destination: string): Promise<void> {
   console.log("Downloading the mkcert executable...")
-  const file = fs.createWriteStream(destination)
+  // Download to a temporary file and rename it into place: spawning a
+  // binary whose file descriptor is still open anywhere fails with ETXTBSY
+  // on Linux, and a rename gives the executable a fresh inode no writer
+  // holds. The temp file lives in the same directory so the rename is
+  // atomic.
+  const tempDestination = `${destination}.download-${process.pid}`
   return new Promise((resolve, reject) => {
-    function get(currentUrl: string): void {
+    function get(currentUrl: string, redirectsLeft: number): void {
+      let file: fs.WriteStream | undefined
+      function fail(error: Error): void {
+        file?.destroy()
+        fs.rmSync(tempDestination, { force: true })
+        reject(error)
+      }
       https
         .get(currentUrl, response => {
-          if (response.statusCode === 302 && response.headers.location !== undefined) {
-            get(response.headers.location)
+          const { statusCode } = response
+          const location = response.headers.location
+          if (
+            statusCode !== undefined &&
+            statusCode >= 300 &&
+            statusCode < 400 &&
+            location !== undefined
+          ) {
+            response.resume()
+            if (redirectsLeft <= 0) {
+              fail(new Error(`Too many redirects while downloading ${url}`))
+              return
+            }
+            get(new URL(location, currentUrl).toString(), redirectsLeft - 1)
+            return
+          }
+          if (statusCode !== 200) {
+            // Never write an error page into the executable file.
+            response.resume()
+            fail(new Error(`Failed to download ${currentUrl} (HTTP ${statusCode ?? "unknown"})`))
             return
           }
-          response.pipe(file)
-          file.on("finish", () => {
-            file.close(err => {
-              if (err === undefined || err === null) resolve()
-              else reject(new Error("Failed to close the certificate file", { cause: err }))
+          const output = fs.createWriteStream(tempDestination)
+          file = output
+          response.pipe(output)
+          output.on("finish", () => {
+            output.close(err => {
+              if (err === undefined || err === null) {
+                fs.renameSync(tempDestination, destination)
+                resolve()
+              } else fail(new Error("Failed to close the certificate file", { cause: err }))
             })
           })
-          file.on("error", reject)
+          output.on("error", fail)
         })
-        .on("error", reject)
+        .on("error", fail)
     }
-    get(url)
+    get(url, MAX_REDIRECTS)
   })
 }
 
@@ -78,16 +130,40 @@ async function runMkcert({
 
   return new Promise((resolve, reject) => {
     console.log("Running mkcert to generate certificates...")
-    execFile(exePath, args, (error, stdout, stderr) => {
-      if (stdout.length > 0) console.log(stdout)
-      if (stderr.length > 0) console.error(stderr)
-      if (error !== null) {
-        console.error(error)
-        reject(new Error(`mkcert failed: ${error.message}`))
-        return
+    // On Linux the freshly written executable may still be held by the
+    // downloader's fd for a moment (ETXTBSY); retry a few times before
+    // giving up. The error can surface either synchronously from execFile
+    // or through the callback.
+    const retry = (retriesLeft: number): void => {
+      setTimeout(() => attempt(retriesLeft), 250)
+    }
+    const attempt = (retriesLeft: number): void => {
+      let child: ReturnType<typeof execFile>
+      try {
+        child = execFile(exePath, args, (error, stdout, stderr) => {
+          if (stdout.length > 0) console.log(stdout)
+          if (stderr.length > 0) console.error(stderr)
+          if (error !== null) {
+            if ((error as NodeJS.ErrnoException).code === "ETXTBSY" && retriesLeft > 0) {
+              retry(retriesLeft - 1)
+              return
+            }
+            console.error(error)
+            reject(new Error(`mkcert failed: ${error.message}`))
+            return
+          }
+          resolve()
+        })
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ETXTBSY" && retriesLeft > 0) {
+          retry(retriesLeft - 1)
+          return
+        }
+        throw error
       }
-      resolve()
-    })
+      child.on("error", () => {})
+    }
+    attempt(5)
   })
 }
 
@@ -104,7 +180,9 @@ export async function generate({
   const url = `https://github.com/FiloSottile/mkcert/releases/download/${MKCERT_VERSION}/`
   const exe = getExe()
   const exePath = path.join(appDataPath, exe)
-  if (!fs.existsSync(exePath)) {
+  const cached = isValidCachedExecutable(exePath)
+  if (!cached) {
+    if (fs.existsSync(exePath)) fs.rmSync(exePath, { force: true })
     await download(url + exe, exePath)
     fs.chmodSync(exePath, "0755")
   }

src/cli.ts

@@ -42,24 +42,7 @@ if (proxy !== undefined && parsedArgs.positionals.length > 0) {
   process.exit(1)
 }
 
-const env = getEnv({
-  PORT: port,
-  HOST: host,
-  CERT_PATH: certPath,
-  REINSTALL: reinstall,
-  PROXY_TARGET: proxy,
-})
-
-const app = createServer({
-  domain: env.HOST,
-  certPath: env.CERT_PATH,
-  reinstall: env.REINSTALL,
-})
-if (env.PROXY_TARGET !== undefined) app.proxy(env.PROXY_TARGET, env.PORT)
-else app.serve(staticFolder, env.PORT)
-if (env.PORT === 443) app.redirect()
-
-process.on("uncaughtException", err => {
+function friendlyError(err: unknown): void {
   const error = err as NodeJS.ErrnoException
   switch (error.code) {
     case "EACCES":
@@ -82,4 +65,40 @@ process.on("uncaughtException", err => {
       break
   }
   process.exit(1)
+}
+
+let env: ReturnType<typeof getEnv>
+try {
+  env = getEnv({
+    PORT: port,
+    HOST: host,
+    CERT_PATH: certPath,
+    REINSTALL: reinstall,
+    PROXY_TARGET: proxy,
+  })
+} catch (err) {
+  const issues =
+    err !== null && typeof err === "object" && "issues" in err && Array.isArray(err.issues)
+      ? (err.issues as { path: (string | number | symbol)[]; message: string }[])
+      : undefined
+  const summary =
+    issues === undefined
+      ? err instanceof Error
+        ? err.message
+        : String(err)
+      : issues.map(issue => `${issue.path.join(".")}: ${issue.message}`).join("\n")
+  console.error(`Invalid arguments or environment:\n${summary}`)
+  process.exit(1)
+}
+
+process.on("unhandledRejection", friendlyError)
+process.on("uncaughtException", friendlyError)
+
+const app = createServer({
+  domain: env.HOST,
+  certPath: env.CERT_PATH,
+  reinstall: env.REINSTALL,
 })
+if (env.PROXY_TARGET !== undefined) app.proxy(env.PROXY_TARGET, env.PORT)
+else app.serve(staticFolder, env.PORT)
+if (env.PORT === 443) app.redirect()