@stacksjs/rpx 0.11.8 → 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.8",
+  "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/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,37 +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)
-
-    // Login keychain — no sudo; Chrome/Arc often read this store on macOS.
-    const loginKeychain = join(homedir(), 'Library/Keychains/login.keychain-db')
-    try {
-      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 {
-      return false
-    }
+    debugLog('ssl', 'Trusting Root CA for browsers (login + system keychains)', verbose)
+    return trustRootCaForBrowsers(certPath, { serverName, verbose })
   }
   catch {
     return false
@@ -413,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 -p ssl -p basic -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')
 
@@ -423,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 -p ssl -p basic -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."
 `
@@ -436,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 -p ssl -p basic -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."
 `
@@ -731,49 +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 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
-        }
-
-        const keychains = [
-          '/Library/Keychains/System.keychain',
-          join(homedir(), 'Library/Keychains/login.keychain-db'),
-        ]
-
-        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 keychains', 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

@@ -16,11 +16,35 @@ export {
   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 })
+}