@stacksjs/rpx 0.11.5 → 0.11.8

package/src/https.ts

@@ -13,6 +13,50 @@ import { debugLog, execSudoSync, getPrimaryDomain, isMultiProxyConfig, isMultiPr
 
 let cachedSSLConfig: { key: string, cert: string, ca?: string } | null = null
 
+// Canonical filenames for the shared Root CA. The CA is a singleton across all
+// rpx-managed domains so that browsers only need to trust it once. Host certs
+// for individual domains are issued from this CA on demand.
+const ROOT_CA_CERT_FILENAME = 'rpx-root-ca.crt'
+const ROOT_CA_KEY_FILENAME = 'rpx-root-ca.key'
+
+export interface RootCAPaths {
+  caCertPath: string
+  caKeyPath: string
+}
+
+/**
+ * Returns the canonical Root CA cert + key paths inside `basePath`.
+ */
+export function getRootCAPaths(basePath: string): RootCAPaths {
+  return {
+    caCertPath: join(basePath, ROOT_CA_CERT_FILENAME),
+    caKeyPath: join(basePath, ROOT_CA_KEY_FILENAME),
+  }
+}
+
+/**
+ * Load a previously-persisted Root CA (cert + private key). Returns `null` if
+ * either file is missing or unreadable, signalling that a fresh CA needs to be
+ * created.
+ */
+async function loadRootCA(paths: RootCAPaths, verbose?: boolean): Promise<{ certificate: string, privateKey: string } | null> {
+  try {
+    const [certificate, privateKey] = await Promise.all([
+      fs.readFile(paths.caCertPath, 'utf8'),
+      fs.readFile(paths.caKeyPath, 'utf8'),
+    ])
+    if (!certificate.includes('-----BEGIN CERTIFICATE-----') || !privateKey.includes('PRIVATE KEY-----')) {
+      debugLog('ssl', `Root CA files at ${paths.caCertPath} look malformed, will regenerate`, verbose)
+      return null
+    }
+    return { certificate, privateKey }
+  }
+  catch (err) {
+    debugLog('ssl', `No existing Root CA at ${paths.caCertPath} (${(err as NodeJS.ErrnoException).code || err}), will create one`, verbose)
+    return null
+  }
+}
+
 /**
  * Resolves SSL paths based on configuration
  */
@@ -240,20 +284,22 @@ async function forceTrustCertificateMacOS(certPath: string): Promise<boolean> {
 
     debugLog('ssl', 'Trusting certificate via macOS security command', false)
 
-    // Use execSudoSync which handles SUDO_PASSWORD from env
+    // Login keychain — no sudo; Chrome/Arc often read this store on macOS.
+    const loginKeychain = join(homedir(), 'Library/Keychains/login.keychain-db')
     try {
-      execSudoSync(`security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${certPath}"`)
-      return true
+      execSync(`security add-trusted-cert -d -r trustRoot -p ssl -p basic -k "${loginKeychain}" "${certPath}"`, { stdio: 'ignore' })
+      if (await isCertTrusted(certPath, { verbose: false, regenerateUntrustedCerts: true }))
+        return true
+    }
+    catch { /* fall through to system keychain */ }
+
+    // System keychain — requires sudo / SUDO_PASSWORD.
+    try {
+      execSudoSync(`security add-trusted-cert -d -r trustRoot -p ssl -p basic -k /Library/Keychains/System.keychain "${certPath}"`)
+      return await isCertTrusted(certPath, { verbose: false, regenerateUntrustedCerts: true })
     }
     catch {
-      // If system keychain fails, try with the user's login keychain (no sudo needed)
-      try {
-        execSync(`security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db "${certPath}"`)
-        return true
-      }
-      catch {
-        return false
-      }
+      return false
     }
   }
   catch {
@@ -262,10 +308,11 @@ async function forceTrustCertificateMacOS(certPath: string): Promise<boolean> {
 }
 
 export async function generateCertificate(options: ProxyOptions): Promise<void> {
-  if (cachedSSLConfig) {
+  if (cachedSSLConfig && !(options as { forceRegenerate?: boolean }).forceRegenerate) {
     debugLog('ssl', 'Using cached SSL configuration', options.verbose)
     return
   }
+  clearSslConfigCache()
 
   // Get all unique domains from the configuration
   const domains: string[] = isMultiProxyOptions(options)
@@ -274,15 +321,37 @@ export async function generateCertificate(options: ProxyOptions): Promise<void>
 
   debugLog('ssl', `Generating certificate for domains: ${domains.join(', ')}`, options.verbose)
 
-  // Generate Root CA first
-  const rootCAConfig = httpsConfig(options, options.verbose)
-
-  if (options.verbose)
-    log.info('Generating Root CA certificate...')
-  const caCert = await createRootCA(rootCAConfig)
-
-  // Generate the host certificate with all domains
   const hostConfig = httpsConfig(options, options.verbose)
+  const sslDir = hostConfig.basePath || join(homedir(), '.stacks', 'ssl')
+  await fs.mkdir(sslDir, { recursive: true })
+  const rootCAPaths = getRootCAPaths(sslDir)
+
+  // Reuse the persisted Root CA when present so the user only has to trust it
+  // once. A fresh CA gets created (and persisted) on first run.
+  let caCert = await loadRootCA(rootCAPaths, options.verbose)
+  let caIsNew = false
+  if (!caCert) {
+    if (options.verbose)
+      log.info('Generating Root CA certificate (one-time)...')
+    caCert = await createRootCA(hostConfig)
+    try {
+      await Promise.all([
+        fs.writeFile(rootCAPaths.caCertPath, caCert.certificate),
+        fs.writeFile(rootCAPaths.caKeyPath, caCert.privateKey, { mode: 0o600 }),
+      ])
+      caIsNew = true
+      debugLog('ssl', `Persisted Root CA at ${rootCAPaths.caCertPath}`, options.verbose)
+    }
+    catch (err) {
+      debugLog('ssl', `Error saving Root CA files: ${err}`, options.verbose)
+      throw new Error(`Failed to save Root CA files: ${err}`)
+    }
+  }
+  else {
+    debugLog('ssl', `Reusing existing Root CA from ${rootCAPaths.caCertPath}`, options.verbose)
+  }
+
+  // Issue the host cert with all SANs from the (possibly reused) CA.
   if (options.verbose)
     log.info(`Generating host certificate for: ${domains.join(', ')}`)
 
@@ -294,14 +363,9 @@ export async function generateCertificate(options: ProxyOptions): Promise<void>
     },
   })
 
-  // Save the certificate files first before trying to trust them
-  // This prevents multiple trust attempts when files don't exist
+  // Persist host cert + key. Also write a copy of the CA cert at the per-domain
+  // `caCertPath` for back-compat with anything that still reads from there.
   try {
-    // Ensure the SSL directory exists
-    const sslDir = hostConfig.basePath || join(homedir(), '.stacks', 'ssl')
-    await fs.mkdir(sslDir, { recursive: true })
-
-    // Write certificate files
     await Promise.all([
       fs.writeFile(hostConfig.certPath, hostCert.certificate),
       fs.writeFile(hostConfig.keyPath, hostCert.privateKey),
@@ -315,15 +379,19 @@ export async function generateCertificate(options: ProxyOptions): Promise<void>
     throw new Error(`Failed to save certificate files: ${err}`)
   }
 
-  // Check if certificate is already trusted before attempting to add it
-  // This avoids unnecessary sudo prompts
-  const alreadyTrusted = await isCertTrusted(hostConfig.certPath, { verbose: options.verbose, regenerateUntrustedCerts: true })
-  if (alreadyTrusted) {
-    debugLog('ssl', 'Certificate is already trusted, skipping trust store update', options.verbose)
+  // The CA is the trust anchor — only it needs to live in the trust store.
+  // Skip the install step when the CA is already trusted (a freshly minted CA
+  // is never trusted yet; a reused one might still need a one-time install if
+  // someone wiped their keychain).
+  const caTrusted = caIsNew
+    ? false
+    : await isCertTrusted(rootCAPaths.caCertPath, { verbose: options.verbose, regenerateUntrustedCerts: true })
+
+  if (caTrusted) {
+    debugLog('ssl', 'Root CA already trusted, skipping trust store update', options.verbose)
     if (options.verbose)
-      log.success('Certificate is already trusted in system trust store')
+      log.success('Root CA is already trusted in system trust store')
 
-    // Cache the SSL config for reuse
     cachedSSLConfig = {
       key: hostCert.privateKey,
       cert: hostCert.certificate,
@@ -342,50 +410,34 @@ export async function generateCertificate(options: ProxyOptions): Promise<void>
 
   let isTrusted = false
 
-  // We'll use a stronger approach to ensure the certificate is properly trusted
+  // We install only the Root CA — host certs derive their trust from it.
   if (process.platform === 'darwin') {
     try {
-      // For macOS, add both CA and host certificates to system trust store in a single sudo call
-      // Combine both certificate trust operations into a single sudo command to avoid multiple password prompts
-      const combinedCmd = `security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${hostConfig.caCertPath}" && security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${hostConfig.certPath}"`
-      execSudoSync(combinedCmd)
+      execSudoSync(`security add-trusted-cert -d -r trustRoot -p ssl -p basic -k /Library/Keychains/System.keychain "${rootCAPaths.caCertPath}"`)
       if (options.verbose)
-        log.success('Successfully added CA and host certificates to system trust store')
-
-      // Also add to login keychain (no sudo needed)
-      try {
-        execSync(`security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db "${hostConfig.certPath}"`, { stdio: 'pipe' })
-      }
-      catch {
-        // Ignore login keychain errors - system keychain is sufficient
-      }
+        log.success('Successfully added Root CA to system trust store')
 
       isTrusted = true
 
-      // Create a simple trust-helper script for easy manual trust if needed
-      const sslScriptDir = hostConfig.basePath || join(homedir(), '.stacks', 'ssl')
-      const scriptPath = join(sslScriptDir, 'trust-rpx-cert.sh')
+      // Helper script for manual re-trust if the user ever wipes their keychain.
+      const scriptPath = join(sslDir, 'trust-rpx-cert.sh')
       const scriptContent = `#!/bin/bash
-echo "Trusting RPX certificate for domains: ${domains.join(', ')}"
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${hostConfig.caCertPath}"
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${hostConfig.certPath}"
-echo "Certificates trusted! Please restart your browser."
+echo "Trusting RPX Root CA"
+sudo security add-trusted-cert -d -r trustRoot -p ssl -p basic -k /Library/Keychains/System.keychain "${rootCAPaths.caCertPath}"
+echo "Root CA trusted! Please restart your browser."
 echo "If you still see certificate warnings, type 'thisisunsafe' on the warning page in Chrome/Arc browsers."
 `
       await fs.writeFile(scriptPath, scriptContent, { mode: 0o755 }) // Make it executable
     }
     catch (err) {
       if (options.verbose)
-        log.warn(`Could not add certificate to trust store automatically: ${err}`)
+        log.warn(`Could not add Root CA to trust store automatically: ${err}`)
 
-      // Create a trust helper script for manual trust
-      const sslScriptDir = hostConfig.basePath || join(homedir(), '.stacks', 'ssl')
-      const scriptPath = join(sslScriptDir, 'trust-rpx-cert.sh')
+      const scriptPath = join(sslDir, 'trust-rpx-cert.sh')
       const scriptContent = `#!/bin/bash
-echo "Trusting RPX certificate for domains: ${domains.join(', ')}"
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${hostConfig.caCertPath}"
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${hostConfig.certPath}"
-echo "Certificates trusted! Please restart your browser."
+echo "Trusting RPX Root CA"
+sudo security add-trusted-cert -d -r trustRoot -p ssl -p basic -k /Library/Keychains/System.keychain "${rootCAPaths.caCertPath}"
+echo "Root CA trusted! Please restart your browser."
 echo "If you still see certificate warnings, type 'thisisunsafe' on the warning page in Chrome/Arc browsers."
 `
       await fs.writeFile(scriptPath, scriptContent, { mode: 0o755 })
@@ -404,10 +456,9 @@ echo "If you still see certificate warnings, type 'thisisunsafe' on the warning
       // Create a more reliable trust script
       const trustScript = `
 mkdir -p "${certDir}" 2>/dev/null || true
-cp "${hostConfig.caCertPath}" "${certDir}/"
-cp "${hostConfig.certPath}" "${certDir}/"
+cp "${rootCAPaths.caCertPath}" "${certDir}/"
 update-ca-certificates
-echo "RPX certificates installed. Please restart your browser."
+echo "RPX Root CA installed. Please restart your browser."
 `
       // Use a temp file for the script
       const tmpScript = join(os.tmpdir(), `rpx-trust-${Date.now()}.sh`)
@@ -444,12 +495,12 @@ echo "RPX certificates installed. Please restart your browser."
     try {
       // Windows is different - use a PowerShell approach
       const winScript = `
-$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("${hostConfig.caCertPath.replace(/\//g, '\\')}")
+$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("${rootCAPaths.caCertPath.replace(/\//g, '\\')}")
 $store = New-Object System.Security.Cryptography.X509Certificates.X509Store("ROOT", "LocalMachine")
 $store.Open("ReadWrite")
 $store.Add($cert)
 $store.Close()
-Write-Host "Certificate trusted successfully!"
+Write-Host "Root CA trusted successfully!"
 `
       const psPath = join(os.tmpdir(), 'rpx-trust.ps1')
       await fs.writeFile(psPath, winScript)
@@ -498,6 +549,11 @@ export function getSSLConfig(): { key: string, cert: string, ca?: string } | nul
   return cachedSSLConfig
 }
 
+/** Clear in-process TLS cache so the next generate/load picks up new files on disk. */
+export function clearSslConfigCache(): void {
+  cachedSSLConfig = null
+}
+
 // needs to accept the options
 export async function checkExistingCertificates(options?: ProxyOptions): Promise<SSLConfig | null> {
   if (!options)
@@ -528,10 +584,15 @@ export async function checkExistingCertificates(options?: ProxyOptions): Promise
     const flagValue = options.regenerateUntrustedCerts
     const shouldCheckTrust = hasFlag ? flagValue !== false : true
     debugLog('ssl', `Trust check: hasFlag=${hasFlag}, flagValue=${flagValue}, shouldCheckTrust=${shouldCheckTrust}`, options.verbose)
-    const certIsTrusted = shouldCheckTrust ? await isCertTrusted(sslConfig.certPath, options) : true
-
-    if (!certIsTrusted) {
-      debugLog('ssl', 'Certificate exists but is not trusted, will regenerate', options.verbose)
+    // Trust anchor is the shared Root CA — host certs are not installed individually.
+    const sslDir = sslConfig.basePath || join(homedir(), '.stacks', 'ssl')
+    const rootCAPaths = getRootCAPaths(sslDir)
+    const caIsTrusted = shouldCheckTrust
+      ? await isCertTrusted(rootCAPaths.caCertPath, options)
+      : true
+
+    if (!caIsTrusted) {
+      debugLog('ssl', 'Root CA exists but is not trusted, will regenerate', options.verbose)
       // Don't attempt to trust here - let generateCertificate handle it in one place
       // This avoids multiple sudo prompts
       return null
@@ -680,23 +741,33 @@ export async function isCertTrusted(certPath: string, options?: { verbose?: bool
       try {
         // Get certificate fingerprint
         const certFingerprint = execSync(`openssl x509 -noout -fingerprint -sha256 -in "${certPath}"`).toString().trim()
-        const fingerprintValue = certFingerprint.split('=')[1]?.trim() || ''
+        const normalize = (raw: string) => raw.split('=').pop()!.replace(/SHA-256\s+hash:\s*/gi, '').replace(/:/g, '').trim().toUpperCase()
+        const fingerprintValue = normalize(certFingerprint)
 
         if (!fingerprintValue) {
           debugLog('ssl', 'Could not extract certificate fingerprint', options?.verbose)
           return false
         }
 
-        // Check if the fingerprint exists in the system keychain and is trusted
-        const keychainOutput = execSync(`security find-certificate -a -Z -p | openssl x509 -noout -fingerprint -sha256`).toString()
+        const keychains = [
+          '/Library/Keychains/System.keychain',
+          join(homedir(), 'Library/Keychains/login.keychain-db'),
+        ]
 
-        // If the fingerprint is found in the trusted certs, consider it trusted
-        if (keychainOutput.includes(fingerprintValue)) {
-          debugLog('ssl', 'Certificate fingerprint found in system keychain', options?.verbose)
-          return true
+        for (const keychain of keychains) {
+          try {
+            const listing = execSync(`security find-certificate -a -Z "${keychain}" 2>/dev/null || true`).toString()
+            for (const line of listing.split('\n')) {
+              if (line.toUpperCase().includes('SHA-256') && normalize(line) === fingerprintValue) {
+                debugLog('ssl', `Certificate fingerprint found in ${keychain}`, options?.verbose)
+                return true
+              }
+            }
+          }
+          catch { /* try next keychain */ }
         }
 
-        debugLog('ssl', 'Certificate fingerprint not found in system keychain', options?.verbose)
+        debugLog('ssl', 'Certificate fingerprint not found in system keychains', options?.verbose)
         return false
       }
       catch (error) {

package/src/index.ts

@@ -13,6 +13,7 @@ export {
 export {
   checkExistingCertificates,
   cleanupCertificates,
+  clearSslConfigCache,
   forceTrustCertificate,
   generateCertificate,
   httpsConfig,
@@ -22,6 +23,48 @@ export {
 
 export { DefaultPortManager, findAvailablePort, isPortInUse, portManager } from './port-manager'
 
+export {
+  gcStaleEntries,
+  getRegistryDir,
+  isPidAlive,
+  isValidId,
+  readAll,
+  readEntry,
+  removeEntry,
+  watchRegistry,
+  writeEntry,
+} from './registry'
+
+export type { RegistryEntry, WatchHandle, WatchOptions } from './registry'
+
+export {
+  acquireDaemonLock,
+  defaultDaemonSpawnCommand,
+  ensureDaemonRunning,
+  getDaemonPidPath,
+  getDaemonRpxDir,
+  isDaemonRunning,
+  readDaemonPid,
+  releaseDaemonLock,
+  runDaemon,
+  stopDaemon,
+} from './daemon'
+
+export type {
+  DaemonHandle,
+  DaemonOptions,
+  EnsureDaemonOptions,
+  EnsureDaemonResult,
+  StopDaemonOptions,
+  StopDaemonResult,
+} from './daemon'
+
+export { createProxyFetchHandler } from './proxy-handler'
+export type { GetRoute, ProxyFetchHandler, ProxyRoute } from './proxy-handler'
+
+export { deriveIdFromTarget, runViaDaemon } from './daemon-runner'
+export type { DaemonRunnerOptions, DaemonRunnerProxy } from './daemon-runner'
+
 export { cleanup } from './start'
 
 export { startProxies, startProxy, startServer } from './start'

package/src/process-manager.ts

@@ -3,7 +3,7 @@ import type { StartOptions } from './types'
 import { spawn } from 'node:child_process'
 import * as process from 'node:process'
 import { log } from './logger'
-import { debugLog } from './utils'
+import { debugLog, safeStringify } from './utils'
 
 export interface ManagedProcess {
   command: string
@@ -28,7 +28,7 @@ export class ProcessManager {
     debugLog('start', `Starting process ${id}:`, verbose)
     debugLog('start', `  Command: ${cmd} ${args.join(' ')}`, verbose)
     debugLog('start', `  Working directory: ${cwd}`, verbose)
-    debugLog('start', `  Environment variables: ${JSON.stringify(options.env)}`, verbose)
+    debugLog('start', `  Environment variables: ${safeStringify(options.env)}`, verbose)
 
     const childProcess = spawn(cmd, args, {
       cwd,

package/src/proxy-handler.ts

@@ -0,0 +1,99 @@
+/**
+ * The fetch handler used by the shared :443 server. Both the in-process
+ * multi-proxy mode in `start.ts` and the long-running daemon delegate to this
+ * module so routing semantics stay in one place.
+ *
+ * Routes are looked up via a caller-supplied `getRoute(hostname)` callback.
+ * The callback indirection lets each caller use whatever data structure makes
+ * sense (a fixed Map at startup, or a hot-swappable registry view) without
+ * coupling this module to either.
+ */
+import type { PathRewrite } from './types'
+import { debugLog } from './utils'
+import { resolvePathRewrite } from './utils'
+
+export interface ProxyRoute {
+  /** Upstream `host:port` to forward requests to (e.g. `localhost:5173`). */
+  sourceHost: string
+  /** Strip `.html` suffix and 301 to clean URLs. */
+  cleanUrls?: boolean
+  /** Set the `origin` header to the target. */
+  changeOrigin?: boolean
+  /** Per-route path rewrites (vite/nginx-style prefix routing). */
+  pathRewrites?: PathRewrite[]
+}
+
+export type GetRoute = (hostname: string) => ProxyRoute | undefined
+
+export type ProxyFetchHandler = (req: Request) => Promise<Response>
+
+/**
+ * Build a Bun.serve-compatible `fetch` handler that routes requests based on
+ * the `Host` header. Returns 404 when no route matches and 502 on upstream
+ * failures.
+ */
+export function createProxyFetchHandler(getRoute: GetRoute, verbose?: boolean): ProxyFetchHandler {
+  return async (req: Request): Promise<Response> => {
+    const url = new URL(req.url)
+    const hostHeader = req.headers.get('host') || ''
+    // Strip port (`stacks.localhost:443` → `stacks.localhost`).
+    const hostname = hostHeader.split(':')[0]
+
+    const route = getRoute(hostname)
+    if (!route) {
+      debugLog('request', `No route found for host: ${hostname}`, verbose)
+      return new Response(`No proxy configured for ${hostname}`, { status: 404 })
+    }
+
+    let targetHost = route.sourceHost
+    let targetPath = url.pathname
+
+    // Per-route path rewrites: prefix preserved by default, matching Vite /
+    // nginx / http-proxy-middleware semantics. See `resolvePathRewrite`.
+    const rewriteMatch = resolvePathRewrite(url.pathname, route.pathRewrites)
+    if (rewriteMatch) {
+      targetHost = rewriteMatch.targetHost
+      targetPath = rewriteMatch.targetPath
+      debugLog('request', `Path rewrite: ${url.pathname} → ${targetHost}${targetPath}`, verbose)
+    }
+
+    const targetUrl = `http://${targetHost}${targetPath}${url.search}`
+
+    try {
+      const headers = new Headers(req.headers)
+      headers.set('host', targetHost)
+      if (route.changeOrigin)
+        headers.set('origin', `http://${route.sourceHost}`)
+      headers.set('x-forwarded-for', '127.0.0.1')
+      headers.set('x-forwarded-proto', 'https')
+      headers.set('x-forwarded-host', hostname)
+
+      const response = await fetch(targetUrl, {
+        method: req.method,
+        headers,
+        body: req.body,
+        redirect: 'manual',
+      })
+
+      // Strip `.html` and 301 to the clean URL when enabled.
+      if (route.cleanUrls && url.pathname.endsWith('.html')) {
+        const cleanPath = url.pathname.replace(/\.html$/, '')
+        return new Response(null, {
+          status: 301,
+          headers: { Location: cleanPath },
+        })
+      }
+
+      const responseHeaders = new Headers(response.headers)
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: responseHeaders,
+      })
+    }
+    catch (err) {
+      debugLog('request', `Proxy error for ${hostname}: ${err}`, verbose)
+      return new Response(`Proxy Error: ${err}`, { status: 502 })
+    }
+  }
+}