@stacksjs/rpx 0.11.7 → 0.11.9

package/dist/macos-trust.d.ts

@@ -0,0 +1,40 @@
+export declare function getMacosLoginKeychainPath(): string;
+export declare function getMacosTrustKeychains(): string[];
+export declare function listCertSha256HashesByCommonName(keychain: string, commonName?: string): string[];
+/**
+ * Remove older rpx Root CA copies from keychains, keeping only the fingerprint
+ * that matches the on-disk `caPath` file.
+ */
+export declare function pruneStaleRootCas(options: PruneStaleRootCasOptions): void;
+/**
+ * True when the Root CA is trusted for SSL to `serverName` (macOS verify-cert).
+ * On other platforms, falls back to fingerprint presence in trust stores.
+ */
+export declare function isRootCaTrustedForSsl(caPath: string, serverName: string, options?: { verbose?: boolean }): boolean;
+export declare function isRootCaFingerprintInKeychains(caPath: string, options?: { verbose?: boolean }): boolean;
+/**
+ * Install the Root CA into login + system keychains with SSL/basic policies,
+ * pruning stale copies first. Returns true when SSL verification succeeds or
+ * the cert fingerprint is present in a keychain.
+ */
+export declare function trustRootCaForBrowsers(caPath: string, options: TrustRootCaForBrowsersOptions): boolean;
+/** Chrome/Edge need SSL + basic trust policies — plain trustRoot often leaves "trust settings: 0". */
+export declare const MACOS_CA_TRUST_FLAGS: '-d -r trustRoot -p ssl -p basic';
+export declare const MACOS_SYSTEM_KEYCHAIN: '/Library/Keychains/System.keychain';
+/** Default CN label for the shared rpx Root CA in macOS keychain listings. */
+export declare const RPX_ROOT_CA_COMMON_NAME: 'rpx.localhost';
+export declare interface ListCertsByCommonNameOptions {
+  keychain: string
+  commonName?: string
+}
+export declare interface PruneStaleRootCasOptions {
+  caPath: string
+  commonName?: string
+  keychains?: string[]
+  verbose?: boolean
+}
+export declare interface TrustRootCaForBrowsersOptions {
+  serverName: string
+  commonName?: string
+  verbose?: boolean
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/rpx",
   "type": "module",
-  "version": "0.11.7",
+  "version": "0.11.9",
   "description": "A modern and smart reverse proxy.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",

package/src/cert-inspect.ts

@@ -0,0 +1,69 @@
+import { execSync } from 'node:child_process'
+
+/**
+ * Normalize openssl / security fingerprint output to uppercase hex without separators.
+ */
+export function normalizeSha256Fingerprint(raw: string): string {
+  const value = raw.includes('=') ? raw.split('=').pop()! : raw
+  return value.replace(/SHA-256\s+hash:\s*/gi, '').replace(/:/g, '').trim().toUpperCase()
+}
+
+export function readCertSha256Fingerprint(certPath: string): string | null {
+  try {
+    const out = execSync(`openssl x509 -noout -fingerprint -sha256 -in "${certPath}"`, { encoding: 'utf8' })
+    return normalizeSha256Fingerprint(out)
+  }
+  catch {
+    return null
+  }
+}
+
+export function readCertCommonName(certPath: string): string | null {
+  try {
+    const subject = execSync(`openssl x509 -in "${certPath}" -noout -subject -nameopt RFC2253`, { encoding: 'utf8' })
+    const match = subject.match(/CN=([^,/]+)/)
+    return match?.[1]?.trim() ?? null
+  }
+  catch {
+    return null
+  }
+}
+
+export function certIncludesSanHostnames(certPath: string, hostnames: string[]): boolean {
+  try {
+    const text = execSync(`openssl x509 -in "${certPath}" -noout -text`, { encoding: 'utf8' })
+    return hostnames.every(host => text.includes(`DNS:${host}`))
+  }
+  catch {
+    return false
+  }
+}
+
+/**
+ * True when :443 (or `port`) presents a chain trusted by `caPath` for `domain`.
+ */
+export function verifyHttpsChain(domain: string, caPath: string, port = 443): boolean {
+  try {
+    const out = execSync(
+      `echo | openssl s_client -connect ${domain}:${port} -servername ${domain} -CAfile "${caPath}" 2>/dev/null | grep "Verify return code"`,
+      { encoding: 'utf8', timeout: 4000 },
+    )
+    return out.includes(': 0 (ok)')
+  }
+  catch {
+    return false
+  }
+}
+
+/**
+ * Parse `security find-certificate -Z` listing lines into SHA-256 hashes.
+ */
+export function parseSha256HashesFromSecurityListing(listing: string): string[] {
+  const hashes: string[] = []
+  for (const line of listing.split('\n')) {
+    const match = line.match(/SHA-256 hash:\s*([A-F0-9]+)/i)
+    if (match)
+      hashes.push(match[1]!.toUpperCase())
+  }
+  return hashes
+}

package/src/daemon-runner.ts

@@ -42,6 +42,16 @@ export interface DaemonRunnerOptions {
   detached?: boolean
   /** Override the daemon spawn command (tests). */
   spawnCommand?: string[]
+  /** Passed through to `ensureDaemonRunning` (default 5000ms). */
+  startupTimeoutMs?: number
+  /** Extra env for the daemon child (e.g. `SUDO_PASSWORD`). */
+  spawnEnv?: Record<string, string>
+  /**
+   * When true, registry entries omit `pid` so they persist until
+   * `rpx unregister` — avoids PID-GC dropping routes when the registering
+   * process is short-lived (e.g. a CLI wrapper).
+   */
+  persistent?: boolean
 }
 
 /**
@@ -78,14 +88,15 @@ export async function runViaDaemon(opts: DaemonRunnerOptions): Promise<void> {
     return { ...p, id }
   })
 
+  const createdAt = new Date().toISOString()
   for (const p of resolved) {
     await writeEntry({
       id: p.id,
       from: p.from,
       to: p.to,
-      pid: process.pid,
+      pid: opts.persistent ? undefined : process.pid,
       cwd: process.cwd(),
-      createdAt: new Date().toISOString(),
+      createdAt,
       cleanUrls: p.cleanUrls,
       changeOrigin: p.changeOrigin,
       pathRewrites: p.pathRewrites,
@@ -96,6 +107,8 @@ export async function runViaDaemon(opts: DaemonRunnerOptions): Promise<void> {
     rpxDir: opts.rpxDir,
     verbose,
     spawnCommand: opts.spawnCommand,
+    startupTimeoutMs: opts.startupTimeoutMs,
+    spawnEnv: opts.spawnEnv,
   })
 
   for (const p of resolved)

package/src/daemon.ts

@@ -156,16 +156,38 @@ function entryToRoute(entry: RegistryEntry): ProxyRoute {
  * Bootstrap the daemon's TLS material. Reuses the persisted Root CA and any
  * existing trusted host cert; mints fresh ones if none exist.
  *
- * The host cert is issued with the standard `*.localhost` SAN list (set by
- * `httpsConfig` via `getAllDomains`), so every `<app>.localhost` route is
- * covered without needing to regenerate when apps register.
+ * The host cert SAN list includes every hostname in the registry (e.g.
+ * `postline.localhost`, `api.postline.localhost`). Chrome does not treat
+ * `*.localhost` as matching `<app>.localhost`, so those names must be explicit.
  */
-async function bootstrapTls(opts: DaemonOptions): Promise<SSLConfig> {
+function pickPrimaryRegistryHost(hosts: string[]): string {
+  const appHost = hosts.find(h => !/^api\./.test(h) && !/^docs\./.test(h) && !/^dashboard\./.test(h))
+  return appHost ?? hosts[0] ?? 'rpx.localhost'
+}
+
+async function bootstrapTls(opts: DaemonOptions, registryDir: string): Promise<SSLConfig> {
+  const entries = await readAll(registryDir, opts.verbose)
+  const registryHosts = [...new Set(entries.map(e => e.to))]
+  const primary = pickPrimaryRegistryHost(registryHosts)
+  const hostnames = [...new Set([primary, ...registryHosts, 'rpx.localhost'])]
+
+  const sslDir = path.join(homedir(), '.stacks', 'ssl')
+  const sharedCert = path.join(sslDir, 'rpx.localhost.crt')
+
   const proxyOpts: ProxyOptions = {
-    https: opts.https ?? true,
-    to: 'rpx.localhost',
+    https: typeof opts.https === 'object'
+      ? { ...opts.https, certPath: sharedCert, keyPath: path.join(sslDir, 'rpx.localhost.key'), commonName: primary }
+      : {
+          certPath: sharedCert,
+          keyPath: path.join(sslDir, 'rpx.localhost.key'),
+          caCertPath: path.join(sslDir, 'rpx.localhost.ca.crt'),
+          commonName: primary,
+        },
     verbose: opts.verbose,
     regenerateUntrustedCerts: true,
+    ...(hostnames.length > 1
+      ? { proxies: hostnames.map(to => ({ from: 'localhost:1', to })) }
+      : { to: primary, from: 'localhost:1' }),
   }
 
   let sslConfig = await checkExistingCertificates(proxyOpts)
@@ -216,7 +238,7 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
   })
   rebuild(await readAll(registryDir, verbose))
 
-  const sslConfig = await bootstrapTls(opts)
+  const sslConfig = await bootstrapTls(opts, registryDir)
 
   const httpsServer = Bun.serve({
     port: httpsPort,

package/src/https.ts

@@ -9,8 +9,39 @@ import * as process from 'node:process'
 import { addCertToSystemTrustStoreAndSaveCert, createRootCA, generateCertificate as generateCert } from '@stacksjs/tlsx'
 import { log } from './logger'
 import { config } from './config'
+import {
+  MACOS_CA_TRUST_FLAGS,
+  MACOS_SYSTEM_KEYCHAIN,
+  getMacosLoginKeychainPath,
+  isRootCaFingerprintInKeychains,
+  isRootCaTrustedForSsl,
+  pruneStaleRootCas,
+  trustRootCaForBrowsers,
+} from './macos-trust'
 import { debugLog, execSudoSync, getPrimaryDomain, isMultiProxyConfig, isMultiProxyOptions, isSingleProxyOptions, isValidRootCA, safeDeleteFile } from './utils'
 
+export {
+  MACOS_CA_TRUST_FLAGS,
+  MACOS_SYSTEM_KEYCHAIN,
+  RPX_ROOT_CA_COMMON_NAME,
+  getMacosLoginKeychainPath,
+  getMacosTrustKeychains,
+  isRootCaFingerprintInKeychains,
+  isRootCaTrustedForSsl,
+  listCertSha256HashesByCommonName,
+  pruneStaleRootCas,
+  trustRootCaForBrowsers,
+} from './macos-trust'
+
+export {
+  certIncludesSanHostnames,
+  normalizeSha256Fingerprint,
+  parseSha256HashesFromSecurityListing,
+  readCertCommonName,
+  readCertSha256Fingerprint,
+  verifyHttpsChain,
+} from './cert-inspect'
+
 let cachedSSLConfig: { key: string, cert: string, ca?: string } | null = null
 
 // Canonical filenames for the shared Root CA. The CA is a singleton across all
@@ -34,6 +65,21 @@ export function getRootCAPaths(basePath: string): RootCAPaths {
   }
 }
 
+/** Paths for the shared multi-host daemon cert under `~/.stacks/ssl`. */
+export function getSharedDaemonCertPaths(sslDir: string): {
+  certPath: string
+  keyPath: string
+  caCertPath: string
+  rootCA: RootCAPaths
+} {
+  return {
+    certPath: join(sslDir, 'rpx.localhost.crt'),
+    keyPath: join(sslDir, 'rpx.localhost.key'),
+    caCertPath: join(sslDir, 'rpx.localhost.ca.crt'),
+    rootCA: getRootCAPaths(sslDir),
+  }
+}
+
 /**
  * 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
@@ -230,9 +276,12 @@ export async function loadSSLConfig(options: ProxyOption): Promise<SSLConfig | n
 /**
  * Force trust a certificate - exposing for direct use
  */
-export async function forceTrustCertificate(certPath: string): Promise<boolean> {
+export async function forceTrustCertificate(
+  certPath: string,
+  options?: { serverName?: string, verbose?: boolean },
+): Promise<boolean> {
   if (process.platform === 'darwin')
-    return forceTrustCertificateMacOS(certPath)
+    return forceTrustCertificateMacOS(certPath, options)
 
   if (process.platform === 'linux') {
     try {
@@ -270,28 +319,24 @@ export async function forceTrustCertificate(certPath: string): Promise<boolean>
  * Force trust a certificate on macOS using direct security command
  * This function first checks if the certificate is already trusted to avoid unnecessary sudo prompts
  */
-async function forceTrustCertificateMacOS(certPath: string): Promise<boolean> {
+async function forceTrustCertificateMacOS(
+  certPath: string,
+  options?: { serverName?: string, verbose?: boolean },
+): Promise<boolean> {
   if (process.platform !== 'darwin')
     return false
 
+  const serverName = options?.serverName ?? 'rpx.localhost'
+  const verbose = options?.verbose ?? false
+
   try {
-    // First check if already trusted to avoid unnecessary sudo prompts
-    const alreadyTrusted = await isCertTrusted(certPath, { verbose: false, regenerateUntrustedCerts: true })
-    if (alreadyTrusted) {
-      debugLog('ssl', 'Certificate is already trusted, skipping trust operation', false)
+    if (isRootCaTrustedForSsl(certPath, serverName, { verbose })) {
+      debugLog('ssl', 'Root CA already trusted for SSL, skipping trust operation', verbose)
       return true
     }
 
-    debugLog('ssl', 'Trusting certificate via macOS security command', false)
-
-    // Use execSudoSync which handles SUDO_PASSWORD from env
-    try {
-      execSudoSync(`security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${certPath}"`)
-      return true
-    }
-    catch {
-      return false
-    }
+    debugLog('ssl', 'Trusting Root CA for browsers (login + system keychains)', verbose)
+    return trustRootCaForBrowsers(certPath, { serverName, verbose })
   }
   catch {
     return false
@@ -299,10 +344,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)
@@ -403,7 +449,13 @@ export async function generateCertificate(options: ProxyOptions): Promise<void>
   // We install only the Root CA — host certs derive their trust from it.
   if (process.platform === 'darwin') {
     try {
-      execSudoSync(`security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${rootCAPaths.caCertPath}"`)
+      pruneStaleRootCas({ caPath: rootCAPaths.caCertPath, verbose: options.verbose })
+      const loginKeychain = getMacosLoginKeychainPath()
+      try {
+        execSync(`security add-trusted-cert ${MACOS_CA_TRUST_FLAGS} -k "${loginKeychain}" "${rootCAPaths.caCertPath}"`, { stdio: 'ignore' })
+      }
+      catch { /* login keychain optional */ }
+      execSudoSync(`security add-trusted-cert ${MACOS_CA_TRUST_FLAGS} -k ${MACOS_SYSTEM_KEYCHAIN} "${rootCAPaths.caCertPath}"`)
       if (options.verbose)
         log.success('Successfully added Root CA to system trust store')
 
@@ -413,7 +465,7 @@ export async function generateCertificate(options: ProxyOptions): Promise<void>
       const scriptPath = join(sslDir, 'trust-rpx-cert.sh')
       const scriptContent = `#!/bin/bash
 echo "Trusting RPX Root CA"
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${rootCAPaths.caCertPath}"
+sudo security add-trusted-cert ${MACOS_CA_TRUST_FLAGS} -k ${MACOS_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."
 `
@@ -426,7 +478,7 @@ echo "If you still see certificate warnings, type 'thisisunsafe' on the warning
       const scriptPath = join(sslDir, 'trust-rpx-cert.sh')
       const scriptContent = `#!/bin/bash
 echo "Trusting RPX Root CA"
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${rootCAPaths.caCertPath}"
+sudo security add-trusted-cert ${MACOS_CA_TRUST_FLAGS} -k ${MACOS_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."
 `
@@ -539,6 +591,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)
@@ -569,10 +626,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
@@ -711,39 +773,18 @@ export async function cleanupCertificates(domain: string, verbose?: boolean): Pr
  * Checks if a certificate is trusted by the system (macOS only for now)
  * If options.regenerateUntrustedCerts is false, always returns true (skips trust check)
  */
-export async function isCertTrusted(certPath: string, options?: { verbose?: boolean, regenerateUntrustedCerts?: boolean }): Promise<boolean> {
+export async function isCertTrusted(
+  certPath: string,
+  options?: { verbose?: boolean, regenerateUntrustedCerts?: boolean, serverName?: string },
+): Promise<boolean> {
   try {
     debugLog('ssl', `Checking if certificate is trusted: ${certPath}`, options?.verbose)
 
     // Different check methods per platform
     if (process.platform === 'darwin') {
-      // On macOS, use the security command to check if the cert is trusted
-      try {
-        // Get certificate fingerprint
-        const certFingerprint = execSync(`openssl x509 -noout -fingerprint -sha256 -in "${certPath}"`).toString().trim()
-        const fingerprintValue = certFingerprint.split('=')[1]?.trim() || ''
-
-        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()
-
-        // 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
-        }
-
-        debugLog('ssl', 'Certificate fingerprint not found in system keychain', options?.verbose)
-        return false
-      }
-      catch (error) {
-        debugLog('ssl', `Error checking certificate trust: ${error}`, options?.verbose)
-        return false
-      }
+      if (options?.serverName)
+        return isRootCaTrustedForSsl(certPath, options.serverName, { verbose: options.verbose })
+      return isRootCaFingerprintInKeychains(certPath, { verbose: options.verbose })
     }
     else if (process.platform === 'win32') {
       // On Windows, use PowerShell to check the certificate store

package/src/index.ts

@@ -13,13 +13,38 @@ export {
 export {
   checkExistingCertificates,
   cleanupCertificates,
+  clearSslConfigCache,
   forceTrustCertificate,
   generateCertificate,
+  getRootCAPaths,
+  getSharedDaemonCertPaths,
   httpsConfig,
   isCertTrusted,
   loadSSLConfig,
 } from './https'
 
+export {
+  MACOS_CA_TRUST_FLAGS,
+  MACOS_SYSTEM_KEYCHAIN,
+  RPX_ROOT_CA_COMMON_NAME,
+  getMacosLoginKeychainPath,
+  getMacosTrustKeychains,
+  isRootCaFingerprintInKeychains,
+  isRootCaTrustedForSsl,
+  listCertSha256HashesByCommonName,
+  pruneStaleRootCas,
+  trustRootCaForBrowsers,
+} from './macos-trust'
+
+export {
+  certIncludesSanHostnames,
+  normalizeSha256Fingerprint,
+  parseSha256HashesFromSecurityListing,
+  readCertCommonName,
+  readCertSha256Fingerprint,
+  verifyHttpsChain,
+} from './cert-inspect'
+
 export { DefaultPortManager, findAvailablePort, isPortInUse, portManager } from './port-manager'
 
 export {

package/src/macos-trust.ts

@@ -0,0 +1,175 @@
+import { execSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { readCertSha256Fingerprint } from './cert-inspect'
+import { debugLog, execSudoSync } from './utils'
+
+/** Chrome/Edge need SSL + basic trust policies — plain trustRoot often leaves "trust settings: 0". */
+export const MACOS_CA_TRUST_FLAGS = '-d -r trustRoot -p ssl -p basic'
+
+export const MACOS_SYSTEM_KEYCHAIN = '/Library/Keychains/System.keychain'
+
+/** Default CN label for the shared rpx Root CA in macOS keychain listings. */
+export const RPX_ROOT_CA_COMMON_NAME = 'rpx.localhost'
+
+export function getMacosLoginKeychainPath(): string {
+  return join(homedir(), 'Library/Keychains/login.keychain-db')
+}
+
+export function getMacosTrustKeychains(): string[] {
+  return [MACOS_SYSTEM_KEYCHAIN, getMacosLoginKeychainPath()]
+}
+
+export interface ListCertsByCommonNameOptions {
+  keychain: string
+  commonName?: string
+}
+
+export function listCertSha256HashesByCommonName(
+  keychain: string,
+  commonName: string = RPX_ROOT_CA_COMMON_NAME,
+): string[] {
+  const listing = execSync(
+    `security find-certificate -a -c "${commonName}" -Z "${keychain}" 2>/dev/null || true`,
+    { encoding: 'utf8' },
+  )
+  const hashes: string[] = []
+  for (const line of listing.split('\n')) {
+    const match = line.match(/SHA-256 hash:\s*([A-F0-9]+)/i)
+    if (match)
+      hashes.push(match[1]!.toUpperCase())
+  }
+  return hashes
+}
+
+export interface PruneStaleRootCasOptions {
+  caPath: string
+  commonName?: string
+  keychains?: string[]
+  verbose?: boolean
+}
+
+/**
+ * Remove older rpx Root CA copies from keychains, keeping only the fingerprint
+ * that matches the on-disk `caPath` file.
+ */
+export function pruneStaleRootCas(options: PruneStaleRootCasOptions): void {
+  if (process.platform !== 'darwin')
+    return
+
+  const keep = readCertSha256Fingerprint(options.caPath)
+  if (!keep)
+    return
+
+  const commonName = options.commonName ?? RPX_ROOT_CA_COMMON_NAME
+  const keychains = options.keychains ?? getMacosTrustKeychains()
+
+  for (const keychain of keychains) {
+    for (const hash of listCertSha256HashesByCommonName(keychain, commonName)) {
+      if (hash === keep)
+        continue
+      try {
+        if (keychain.startsWith('/Library'))
+          execSudoSync(`security delete-certificate -Z ${hash} "${keychain}"`)
+        else
+          execSync(`security delete-certificate -Z ${hash} "${keychain}"`, { stdio: 'ignore' })
+        debugLog('ssl', `Removed stale Root CA ${hash} from ${keychain}`, options.verbose)
+      }
+      catch { /* already removed */ }
+    }
+  }
+}
+
+/**
+ * True when the Root CA is trusted for SSL to `serverName` (macOS verify-cert).
+ * On other platforms, falls back to fingerprint presence in trust stores.
+ */
+export function isRootCaTrustedForSsl(
+  caPath: string,
+  serverName: string,
+  options?: { verbose?: boolean },
+): boolean {
+  if (process.platform !== 'darwin')
+    return isRootCaFingerprintInKeychains(caPath, options)
+
+  try {
+    const out = execSync(
+      `security verify-cert -c "${caPath}" -s "${serverName}" -l -L -R ssl 2>&1`,
+      { encoding: 'utf8' },
+    )
+    const ok = out.includes('successful')
+    debugLog('ssl', `verify-cert ${serverName}: ${ok ? 'trusted' : 'not trusted'}`, options?.verbose)
+    return ok
+  }
+  catch {
+    return false
+  }
+}
+
+export function isRootCaFingerprintInKeychains(
+  caPath: string,
+  options?: { verbose?: boolean },
+): boolean {
+  const fp = readCertSha256Fingerprint(caPath)
+  if (!fp)
+    return false
+
+  for (const keychain of getMacosTrustKeychains()) {
+    try {
+      const listing = execSync(`security find-certificate -a -Z "${keychain}" 2>/dev/null || true`, { encoding: 'utf8' })
+      for (const line of listing.split('\n')) {
+        if (line.toUpperCase().includes('SHA-256')) {
+          const lineFp = line.split('=').pop()!.replace(/SHA-256\s+hash:\s*/gi, '').replace(/:/g, '').trim().toUpperCase()
+          if (lineFp === fp) {
+            debugLog('ssl', `Root CA fingerprint found in ${keychain}`, options?.verbose)
+            return true
+          }
+        }
+      }
+    }
+    catch { /* try next keychain */ }
+  }
+
+  return false
+}
+
+export interface TrustRootCaForBrowsersOptions {
+  serverName: string
+  commonName?: string
+  verbose?: boolean
+}
+
+/**
+ * Install the Root CA into login + system keychains with SSL/basic policies,
+ * pruning stale copies first. Returns true when SSL verification succeeds or
+ * the cert fingerprint is present in a keychain.
+ */
+export function trustRootCaForBrowsers(
+  caPath: string,
+  options: TrustRootCaForBrowsersOptions,
+): boolean {
+  if (process.platform !== 'darwin')
+    return false
+
+  const serverName = options.serverName
+  pruneStaleRootCas({ caPath, commonName: options.commonName, verbose: options.verbose })
+
+  const loginKeychain = getMacosLoginKeychainPath()
+  try {
+    execSync(
+      `security add-trusted-cert ${MACOS_CA_TRUST_FLAGS} -k "${loginKeychain}" "${caPath}"`,
+      { stdio: 'ignore' },
+    )
+  }
+  catch { /* may already exist — re-apply trust below */ }
+
+  try {
+    execSudoSync(`security add-trusted-cert ${MACOS_CA_TRUST_FLAGS} -k ${MACOS_SYSTEM_KEYCHAIN} "${caPath}"`)
+  }
+  catch {
+    return false
+  }
+
+  return isRootCaTrustedForSsl(caPath, serverName, { verbose: options.verbose })
+    || isRootCaFingerprintInKeychains(caPath, { verbose: options.verbose })
+}