@stacksjs/rpx 0.11.7 → 0.11.10

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.10",
   "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

@@ -28,6 +28,11 @@ import { checkExistingCertificates, generateCertificate } from './https'
 import { createProxyFetchHandler } from './proxy-handler'
 import { gcStaleEntries, getRegistryDir, isPidAlive, readAll, watchRegistry } from './registry'
 import type { RegistryEntry } from './registry'
+import {
+  reconcileStaleDevelopmentDns,
+  syncDevelopmentDnsFromRegistry,
+  tearDownDevelopmentDns,
+} from './dns'
 import { debugLog } from './utils'
 
 export interface DaemonOptions {
@@ -156,16 +161,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)
@@ -214,9 +241,17 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
   await gcStaleEntries(registryDir, verbose).catch((err) => {
     debugLog('daemon', `initial gc failed: ${err}`, verbose)
   })
-  rebuild(await readAll(registryDir, verbose))
+  const initialEntries = await readAll(registryDir, verbose)
+  rebuild(initialEntries)
 
-  const sslConfig = await bootstrapTls(opts)
+  await reconcileStaleDevelopmentDns({ rpxDir, verbose }).catch((err) => {
+    debugLog('daemon', `DNS reconcile on start failed: ${err}`, verbose)
+  })
+  await syncDevelopmentDnsFromRegistry(initialEntries, { rpxDir, verbose, ownerPid: process.pid }).catch((err) => {
+    debugLog('daemon', `DNS setup on start failed: ${err}`, verbose)
+  })
+
+  const sslConfig = await bootstrapTls(opts, registryDir)
 
   const httpsServer = Bun.serve({
     port: httpsPort,
@@ -258,7 +293,12 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
   }
 
   const watcher = watchRegistry(
-    (entries) => { rebuild(entries) },
+    (entries) => {
+      rebuild(entries)
+      syncDevelopmentDnsFromRegistry(entries, { rpxDir, verbose, ownerPid: process.pid }).catch((err) => {
+        debugLog('daemon', `DNS sync on registry change failed: ${err}`, verbose)
+      })
+    },
     { dir: registryDir, verbose },
   )
 
@@ -289,6 +329,9 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
     // `stop(false)` lets in-flight requests drain before closing the listener.
     httpsServer.stop(false)
     httpServer?.stop(false)
+    await tearDownDevelopmentDns({ rpxDir, verbose }).catch((err) => {
+      debugLog('daemon', `DNS teardown failed: ${err}`, verbose)
+    })
     await releaseDaemonLock(rpxDir)
     if (verbose)
       log.info('rpx daemon stopped')
@@ -369,6 +412,10 @@ export async function ensureDaemonRunning(opts: EnsureDaemonOptions = {}): Promi
   const rpxDir = opts.rpxDir ?? getDaemonRpxDir()
   const verbose = opts.verbose ?? false
 
+  await reconcileStaleDevelopmentDns({ rpxDir, verbose }).catch((err) => {
+    debugLog('daemon', `DNS reconcile before ensureDaemonRunning: ${err}`, verbose)
+  })
+
   const existingPid = await readDaemonPid(rpxDir)
   if (existingPid !== null && isPidAlive(existingPid)) {
     debugLog('daemon', `ensureDaemonRunning: already running pid=${existingPid}`, verbose)
@@ -455,6 +502,7 @@ export async function stopDaemon(opts: StopDaemonOptions = {}): Promise<StopDaem
   if (pid === null || !isPidAlive(pid)) {
     if (pid !== null)
       await releaseDaemonLock(rpxDir)
+    await reconcileStaleDevelopmentDns({ rpxDir, verbose }).catch(() => {})
     return { stopped: false, pid, forced: false }
   }
 
@@ -492,5 +540,18 @@ export async function stopDaemon(opts: StopDaemonOptions = {}): Promise<StopDaem
   }
   // SIGKILL bypasses the cleanup handler, so remove the pid file ourselves.
   await releaseDaemonLock(rpxDir)
+  await tearDownDevelopmentDns({ rpxDir, verbose }).catch((err) => {
+    debugLog('daemon', `DNS teardown after SIGKILL: ${err}`, verbose)
+  })
   return { stopped: true, pid, forced: true }
 }
+
+/**
+ * When the daemon is not running, ensure no stale macOS resolver overrides remain.
+ */
+export async function reconcileDevelopmentDnsOnIdle(opts: { rpxDir?: string, verbose?: boolean } = {}): Promise<void> {
+  const rpxDir = opts.rpxDir ?? getDaemonRpxDir()
+  if (await isDaemonRunning(rpxDir))
+    return
+  await reconcileStaleDevelopmentDns({ rpxDir, verbose: opts.verbose })
+}

package/src/dns-state.ts

@@ -0,0 +1,116 @@
+import * as fsp from 'node:fs/promises'
+import { homedir } from 'node:os'
+import * as path from 'node:path'
+
+export const DNS_STATE_VERSION = 1 as const
+export const RPX_DNS_STATE_FILE = 'dns-state.json'
+
+/** Single-label /etc/resolver files created by older rpx versions (whole-TLD hijack). */
+export const LEGACY_TLD_RESOLVER_LABELS = [
+  'com',
+  'test',
+  'dev',
+  'app',
+  'page',
+  'local',
+  'localhost',
+  'example',
+  'invalid',
+] as const
+
+export interface DnsState {
+  version: typeof DNS_STATE_VERSION
+  /** Basenames under /etc/resolver/ (e.g. `postline.test`, not `test`). */
+  resolvers: string[]
+  domains: string[]
+  ownerPid: number | null
+  updatedAt: string
+}
+
+export function defaultRpxDir(): string {
+  return path.join(homedir(), '.stacks', 'rpx')
+}
+
+export function getDnsStatePath(rpxDir: string = defaultRpxDir()): string {
+  return path.join(rpxDir, RPX_DNS_STATE_FILE)
+}
+
+export async function loadDnsState(rpxDir: string = defaultRpxDir()): Promise<DnsState | null> {
+  try {
+    const raw = await fsp.readFile(getDnsStatePath(rpxDir), 'utf8')
+    const parsed = JSON.parse(raw) as Partial<DnsState>
+    if (parsed.version !== DNS_STATE_VERSION || !Array.isArray(parsed.resolvers))
+      return null
+    return {
+      version: DNS_STATE_VERSION,
+      resolvers: parsed.resolvers.filter((r): r is string => typeof r === 'string'),
+      domains: Array.isArray(parsed.domains)
+        ? parsed.domains.filter((d): d is string => typeof d === 'string')
+        : [],
+      ownerPid: typeof parsed.ownerPid === 'number' ? parsed.ownerPid : null,
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+    }
+  }
+  catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT')
+      return null
+    throw err
+  }
+}
+
+export async function saveDnsState(rpxDir: string, state: DnsState): Promise<void> {
+  await fsp.mkdir(rpxDir, { recursive: true })
+  await fsp.writeFile(getDnsStatePath(rpxDir), `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+}
+
+export async function clearDnsState(rpxDir: string): Promise<void> {
+  await fsp.rm(getDnsStatePath(rpxDir), { force: true })
+}
+
+/**
+ * Normalize a dev hostname. Returns null for localhost / IPs — those use /etc/hosts only.
+ */
+export function normalizeDevDomain(raw: string): string | null {
+  const domain = raw.trim().toLowerCase().replace(/\.$/, '')
+  if (!domain || domain.includes('127.0.0.1'))
+    return null
+  if (domain === 'localhost' || domain.endsWith('.localhost'))
+    return null
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(domain))
+    return null
+  return domain
+}
+
+/**
+ * macOS resolver basename for a dev domain. Uses the registrable base (last two labels)
+ * so `api.postline.test` and `postline.test` share one `/etc/resolver/postline.test` file.
+ */
+export function resolverBasenameForDomain(raw: string): string | null {
+  const domain = normalizeDevDomain(raw)
+  if (!domain)
+    return null
+  const parts = domain.split('.')
+  if (parts.length < 2)
+    return null
+  return parts.slice(-2).join('.')
+}
+
+export function resolverBasenamesForDomains(domains: string[]): string[] {
+  const basenames = new Set<string>()
+  for (const raw of domains) {
+    const basename = resolverBasenameForDomain(raw)
+    if (basename)
+      basenames.add(basename)
+  }
+  return Array.from(basenames).sort()
+}
+
+export function devDomainsFromHosts(hosts: string[]): string[] {
+  const out = new Set<string>()
+  for (const raw of hosts) {
+    const domain = normalizeDevDomain(raw)
+    if (domain)
+      out.add(domain)
+  }
+  return Array.from(out).sort()
+}