@stacksjs/rpx 0.11.5 → 0.11.8

package/src/registry.ts

@@ -0,0 +1,346 @@
+/**
+ * Registry of currently-active rpx proxies.
+ *
+ * Each running upstream (e.g. a `./buddy dev` invocation) writes a small JSON
+ * file into `~/.stacks/rpx/registry.d/<id>.json` describing where to forward
+ * traffic. The rpx daemon watches this directory and rebuilds its routing
+ * table whenever entries appear, change, or disappear.
+ *
+ * Design choices worth knowing about:
+ *   - One file per entry → no shared-file locking, no merge conflicts.
+ *   - Atomic write via temp file + rename → readers never see partial JSON.
+ *   - Each entry carries the writer's PID so the daemon can GC files left
+ *     behind by a writer that was killed -9.
+ *   - `id` is validated against a strict charset to keep it from escaping
+ *     the registry directory.
+ */
+import type { PathRewrite } from './types'
+import * as fs from 'node:fs'
+import * as fsp from 'node:fs/promises'
+import { homedir } from 'node:os'
+import * as path from 'node:path'
+import * as process from 'node:process'
+import { debugLog } from './utils'
+
+export interface RegistryEntry {
+  id: string
+  from: string
+  to: string
+  /**
+   * Optional. PID of the long-running process that owns this entry. When set,
+   * the daemon's PID-GC reaps the entry the moment that process dies. Omit
+   * (or set to `undefined`) for manually-managed entries created via
+   * `rpx register` — those persist until explicit `rpx unregister`.
+   */
+  pid?: number
+  cwd?: string
+  createdAt: string
+  pathRewrites?: PathRewrite[]
+  cleanUrls?: boolean
+  changeOrigin?: boolean
+}
+
+const ID_PATTERN = /^[a-zA-Z0-9._-]+$/
+
+/**
+ * Default location for the registry directory. The daemon's PID file and log
+ * sit alongside it under `~/.stacks/rpx/`.
+ */
+export function getRegistryDir(): string {
+  return path.join(homedir(), '.stacks', 'rpx', 'registry.d')
+}
+
+/**
+ * Validate an entry id. Rejects anything that could escape the registry dir
+ * (path traversal, slashes) or that would round-trip oddly through a filename.
+ */
+export function isValidId(id: string): boolean {
+  return typeof id === 'string' && id.length > 0 && id.length <= 128 && ID_PATTERN.test(id)
+}
+
+function entryPath(dir: string, id: string): string {
+  if (!isValidId(id))
+    throw new Error(`invalid registry id: ${JSON.stringify(id)}`)
+  return path.join(dir, `${id}.json`)
+}
+
+/**
+ * Check whether a PID is alive. `kill(pid, 0)` returns without sending a
+ * signal but throws ESRCH if the process is gone — exactly the probe we need.
+ * EPERM means the process exists but we don't own it; treat as alive.
+ */
+export function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false
+  try {
+    process.kill(pid, 0)
+    return true
+  }
+  catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+function isValidEntry(value: unknown): value is RegistryEntry {
+  if (!value || typeof value !== 'object')
+    return false
+  const e = value as Partial<RegistryEntry>
+  // pid is optional. When present it must be a positive integer; when absent
+  // (manual entries from `rpx register`) the daemon's PID-GC skips it.
+  const pidOk = e.pid === undefined
+    || (typeof e.pid === 'number' && Number.isInteger(e.pid) && e.pid > 0)
+  return (
+    typeof e.id === 'string' && isValidId(e.id)
+    && typeof e.from === 'string' && e.from.length > 0
+    && typeof e.to === 'string' && e.to.length > 0
+    && pidOk
+    && typeof e.createdAt === 'string'
+  )
+}
+
+async function ensureDir(dir: string): Promise<void> {
+  await fsp.mkdir(dir, { recursive: true })
+}
+
+/**
+ * Atomically write an entry to disk.
+ *
+ * Writes to a temp file in the same directory, then renames into place. POSIX
+ * rename within the same filesystem is atomic, so a concurrent reader either
+ * sees the old file or the new file — never a half-written one.
+ */
+export async function writeEntry(entry: RegistryEntry, dir: string = getRegistryDir(), verbose?: boolean): Promise<void> {
+  if (!isValidEntry(entry))
+    throw new Error(`invalid registry entry: ${JSON.stringify(entry)}`)
+
+  await ensureDir(dir)
+  const finalPath = entryPath(dir, entry.id)
+  const tmpPath = `${finalPath}.tmp.${process.pid}.${Date.now()}`
+  const json = JSON.stringify(entry, null, 2)
+
+  try {
+    await fsp.writeFile(tmpPath, json, { encoding: 'utf8', mode: 0o644 })
+    await fsp.rename(tmpPath, finalPath)
+    debugLog('registry', `wrote entry ${entry.id} → ${finalPath}`, verbose)
+  }
+  catch (err) {
+    // Best-effort cleanup of the temp file if the rename never landed.
+    await fsp.unlink(tmpPath).catch(() => {})
+    throw err
+  }
+}
+
+/**
+ * Remove an entry by id. No-op if the file is already gone.
+ */
+export async function removeEntry(id: string, dir: string = getRegistryDir(), verbose?: boolean): Promise<void> {
+  const target = entryPath(dir, id)
+  try {
+    await fsp.unlink(target)
+    debugLog('registry', `removed entry ${id}`, verbose)
+  }
+  catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT')
+      throw err
+  }
+}
+
+/**
+ * Read a single entry by id. Returns `null` if missing or malformed (malformed
+ * files are deleted so they don't keep poisoning subsequent reads).
+ */
+export async function readEntry(id: string, dir: string = getRegistryDir(), verbose?: boolean): Promise<RegistryEntry | null> {
+  const target = entryPath(dir, id)
+  try {
+    const raw = await fsp.readFile(target, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (!isValidEntry(parsed)) {
+      debugLog('registry', `entry ${id} failed validation, removing`, verbose)
+      await fsp.unlink(target).catch(() => {})
+      return null
+    }
+    return parsed
+  }
+  catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'ENOENT')
+      return null
+    if (err instanceof SyntaxError) {
+      debugLog('registry', `entry ${id} has invalid JSON, removing`, verbose)
+      await fsp.unlink(target).catch(() => {})
+      return null
+    }
+    throw err
+  }
+}
+
+/**
+ * Read all entries from the registry directory. Malformed files are pruned.
+ * This does NOT GC stale PIDs — call `gcStaleEntries` for that explicitly.
+ */
+export async function readAll(dir: string = getRegistryDir(), verbose?: boolean): Promise<RegistryEntry[]> {
+  let names: string[]
+  try {
+    names = await fsp.readdir(dir)
+  }
+  catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT')
+      return []
+    throw err
+  }
+
+  const out: RegistryEntry[] = []
+  for (const name of names) {
+    if (!name.endsWith('.json'))
+      continue
+    const id = name.slice(0, -'.json'.length)
+    if (!isValidId(id))
+      continue
+    const entry = await readEntry(id, dir, verbose)
+    if (entry)
+      out.push(entry)
+  }
+  return out
+}
+
+/**
+ * Remove entries whose writer PID is no longer alive. Returns the count of
+ * entries removed. Safe to call repeatedly; intended to run on daemon startup
+ * and on a slow timer (e.g. every 5s) while the daemon is up.
+ */
+export async function gcStaleEntries(dir: string = getRegistryDir(), verbose?: boolean): Promise<number> {
+  const entries = await readAll(dir, verbose)
+  let removed = 0
+  for (const entry of entries) {
+    // Manually-managed entries (no pid) opt out of PID-GC. The user is
+    // responsible for `rpx unregister` when they're done.
+    if (entry.pid === undefined)
+      continue
+    if (!isPidAlive(entry.pid)) {
+      debugLog('registry', `GC: pid ${entry.pid} for ${entry.id} is dead, removing`, verbose)
+      await removeEntry(entry.id, dir, verbose).catch(() => {})
+      removed++
+    }
+  }
+  return removed
+}
+
+export interface WatchHandle {
+  close: () => void
+}
+
+export interface WatchOptions {
+  debounceMs?: number
+  pollMs?: number
+  verbose?: boolean
+}
+
+/**
+ * Watch the registry directory and invoke `onChange` with the full current
+ * entry list whenever something changes. Events are debounced so a flurry of
+ * rapid writes (e.g. several `./buddy dev` invocations starting in parallel)
+ * triggers at most one rebuild.
+ *
+ * The watcher tolerates a missing directory at startup — it creates the dir
+ * before opening the watch, so the first `writeEntry` doesn't race the daemon.
+ */
+export function watchRegistry(
+  onChange: (entries: RegistryEntry[]) => void | Promise<void>,
+  opts: WatchOptions & { dir?: string } = {},
+): WatchHandle {
+  const dir = opts.dir ?? getRegistryDir()
+  const debounceMs = opts.debounceMs ?? 100
+  const pollMs = opts.pollMs ?? Math.max(debounceMs * 2, 250)
+  const verbose = opts.verbose
+
+  // Create the dir up front so fs.watch has something to attach to.
+  fs.mkdirSync(dir, { recursive: true })
+
+  let pending: ReturnType<typeof setTimeout> | null = null
+  let closed = false
+  let lastSignature: string | null = null
+  let pollInFlight = false
+
+  const signatureFor = (entries: RegistryEntry[]): string => {
+    return JSON.stringify(
+      entries
+        .map(entry => ({
+          id: entry.id,
+          from: entry.from,
+          to: entry.to,
+          pid: entry.pid,
+          pathRewrites: entry.pathRewrites,
+          cleanUrls: entry.cleanUrls,
+          changeOrigin: entry.changeOrigin,
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+    )
+  }
+
+  const fire = () => {
+    pending = null
+    if (closed)
+      return
+    readAll(dir, verbose)
+      .then((entries) => {
+        lastSignature = signatureFor(entries)
+        return onChange(entries)
+      })
+      .catch((err) => {
+        debugLog('registry', `watcher onChange failed: ${err}`, verbose)
+      })
+  }
+
+  const schedule = () => {
+    if (closed)
+      return
+    if (pending)
+      clearTimeout(pending)
+    pending = setTimeout(fire, debounceMs)
+  }
+
+  const poll = () => {
+    if (closed || pollInFlight)
+      return
+
+    pollInFlight = true
+    readAll(dir, verbose)
+      .then((entries) => {
+        const signature = signatureFor(entries)
+        if (signature !== lastSignature)
+          schedule()
+      })
+      .catch((err) => {
+        debugLog('registry', `watcher poll failed: ${err}`, verbose)
+      })
+      .finally(() => {
+        pollInFlight = false
+      })
+  }
+
+  const pollInterval = setInterval(poll, pollMs)
+
+  const watcher = fs.watch(dir, { persistent: true }, (_eventType, filename) => {
+    // Ignore temp files from our own atomic-write protocol.
+    if (filename && /\.tmp\.\d+\.\d+$/.test(filename))
+      return
+    schedule()
+  })
+
+  watcher.on('error', (err) => {
+    debugLog('registry', `watcher error: ${err}`, verbose)
+  })
+
+  // Fire once on startup so the daemon picks up entries that already exist.
+  schedule()
+
+  return {
+    close: () => {
+      closed = true
+      if (pending)
+        clearTimeout(pending)
+      clearInterval(pollInterval)
+      watcher.close()
+    },
+  }
+}

package/src/start.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-console */
 import type { IncomingHttpHeaders, SecureServerOptions } from 'node:http2'
 import type { ServerOptions } from 'node:https'
-import type { BaseProxyConfig, CleanupOptions, PathRewrite, ProxyConfig, ProxyOption, ProxyOptions, ProxySetupOptions, SingleProxyConfig, SSLConfig, StartOptions } from './types'
+import type { BaseProxyConfig, CleanupOptions, ProxyConfig, ProxyOption, ProxyOptions, ProxySetupOptions, SingleProxyConfig, SSLConfig, StartOptions } from './types'
 import { exec, execSync } from 'node:child_process'
 import * as fs from 'node:fs'
 import * as http from 'node:http'
@@ -14,15 +14,18 @@ import * as process from 'node:process'
 import * as tls from 'node:tls'
 import { log } from './logger'
 import { colors } from './colors'
-import { version } from '../package.json'
 import { config } from './config'
+import { runViaDaemon } from './daemon-runner'
 import { addHosts, checkHosts, removeHosts } from './hosts'
 import { checkExistingCertificates, cleanupCertificates, generateCertificate, httpsConfig, loadSSLConfig } from './https'
 import { DefaultPortManager, findAvailablePort, isPortInUse } from './port-manager'
 import { ProcessManager } from './process-manager'
-import { debugLog, getSudoPassword, resolvePathRewrite } from './utils'
+import { createProxyFetchHandler } from './proxy-handler'
+import type { ProxyRoute } from './proxy-handler'
+import { debugLog, getSudoPassword, safeStringify } from './utils'
 
 const processManager = new ProcessManager()
+const version = '0.12.0'
 // Create a global port manager for coordinating port usage
 const globalPortManager = new DefaultPortManager('0.0.0.0')
 
@@ -295,7 +298,7 @@ async function testConnection(hostname: string, port: number, verbose?: boolean,
 }
 
 export async function startServer(options: SingleProxyConfig): Promise<void> {
-  debugLog('server', `Starting server with options: ${JSON.stringify(options)}`, options.verbose)
+  debugLog('server', `Starting server with options: ${safeStringify(options)}`, options.verbose)
 
   // Parse URLs early to get the hostnames
   const fromUrl = new URL((options.from?.startsWith('http') ? options.from : `http://${options.from}`) || 'localhost:5173')
@@ -487,7 +490,7 @@ async function createProxyServer(
       headers: normalizedHeaders,
     }
 
-    debugLog('request', `Proxy request options: ${JSON.stringify(proxyOptions)}`, verbose)
+    debugLog('request', `Proxy request options: ${safeStringify(proxyOptions)}`, verbose)
 
     const proxyReq = http.request(proxyOptions, (proxyRes) => {
       debugLog('response', `Proxy response received with status ${proxyRes.statusCode}`, verbose)
@@ -697,7 +700,7 @@ async function createProxyServer(
 }
 
 export async function setupProxy(options: ProxySetupOptions): Promise<void> {
-  debugLog('setup', `Setting up reverse proxy: ${JSON.stringify(options)}`, options.verbose)
+  debugLog('setup', `Setting up reverse proxy: ${safeStringify(options)}`, options.verbose)
 
   const { from, to, fromPort, sourceUrl, ssl, verbose, cleanup: cleanupOptions, vitePluginUsage, changeOrigin, cleanUrls } = options
   const httpPort = 80
@@ -827,7 +830,32 @@ export function startProxy(options: ProxyOption): void {
     ...options,
   }
 
-  debugLog('proxy', `Starting proxy with options: ${JSON.stringify(mergedOptions)}`, mergedOptions?.verbose)
+  debugLog('proxy', `Starting proxy with options: ${safeStringify(mergedOptions)}`, mergedOptions?.verbose)
+
+  // viaDaemon: register with the long-running daemon instead of binding our
+  // own :443. The daemon owns TLS termination and host-header routing for
+  // every concurrent `rpx start` on this machine.
+  if (mergedOptions.viaDaemon) {
+    if (!mergedOptions.from || !mergedOptions.to) {
+      log.error('viaDaemon mode requires both `from` and `to`')
+      return
+    }
+    runViaDaemon({
+      proxies: [{
+        id: mergedOptions.id,
+        from: mergedOptions.from,
+        to: mergedOptions.to,
+        cleanUrls: mergedOptions.cleanUrls,
+        changeOrigin: mergedOptions.changeOrigin,
+        pathRewrites: mergedOptions.pathRewrites,
+      }],
+      verbose: mergedOptions.verbose,
+    }).catch((err) => {
+      log.error(`Failed to register with rpx daemon: ${err.message}`)
+      process.exit(1)
+    })
+    return
+  }
 
   // Start DNS server for custom domains on macOS (any domain that's not localhost/127.0.0.1)
   const targetDomain = mergedOptions.to || ''
@@ -884,7 +912,7 @@ export function startProxy(options: ProxyOption): void {
     regenerateUntrustedCerts: mergedOptions.regenerateUntrustedCerts,
   }
 
-  debugLog('proxy', `Server options: ${JSON.stringify(serverOptions)}`, mergedOptions.verbose)
+  debugLog('proxy', `Server options: ${safeStringify(serverOptions)}`, mergedOptions.verbose)
 
   startServer(serverOptions).catch((err) => {
     debugLog('proxy', `Failed to start proxy: ${err}`, mergedOptions.verbose)
@@ -918,7 +946,7 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
     verbose: false,
     cleanUrls: false,
     changeOrigin: false,
-    regenerateUntrustedCerts: false,
+    regenerateUntrustedCerts: true,
   } as any
 
   if (options) {
@@ -929,9 +957,35 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
   }
 
   const verbose = getVerbose(mergedOptions)
-  debugLog('config', `Starting with config: ${JSON.stringify(mergedOptions, null, 2)}`, verbose)
+  debugLog('config', `Starting with config: ${safeStringify(mergedOptions, 2)}`, verbose)
   debugLog('config', `Is multi-proxy? ${'proxies' in mergedOptions}`, verbose)
 
+  // viaDaemon mode short-circuits before any port binding / cert work — the
+  // daemon owns all of that. We only need to register entries and block.
+  if (mergedOptions.viaDaemon) {
+    const isMulti = 'proxies' in mergedOptions && Array.isArray(mergedOptions.proxies)
+    const proxies = isMulti
+      ? (mergedOptions.proxies as Array<BaseProxyConfig & { cleanUrls?: boolean, changeOrigin?: boolean }>)
+        .map(p => ({
+          id: p.id,
+          from: p.from,
+          to: p.to,
+          cleanUrls: p.cleanUrls ?? mergedOptions.cleanUrls,
+          changeOrigin: p.changeOrigin ?? mergedOptions.changeOrigin,
+          pathRewrites: p.pathRewrites,
+        }))
+      : [{
+          id: mergedOptions.id,
+          from: mergedOptions.from,
+          to: mergedOptions.to,
+          cleanUrls: mergedOptions.cleanUrls,
+          changeOrigin: mergedOptions.changeOrigin,
+          pathRewrites: mergedOptions.pathRewrites,
+        }]
+    await runViaDaemon({ proxies, verbose })
+    return
+  }
+
   // Start dev servers first if configured
   if ('proxies' in mergedOptions && Array.isArray(mergedOptions.proxies)) {
     debugLog('servers', `Found ${mergedOptions.proxies.length} proxies in config`, verbose)
@@ -1161,16 +1215,13 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
   if (sslConfig && proxyOptions.length > 1) {
     debugLog('proxies', `Creating shared HTTPS server for ${proxyOptions.length} domains`, verbose)
 
-    // Build routing table: domain → { fromPort, sourceHost, cleanUrls, changeOrigin, pathRewrites }
-    const routingTable = new Map<string, { fromPort: number, sourceHost: string, cleanUrls: boolean, changeOrigin: boolean, pathRewrites?: PathRewrite[] }>()
+    const routingTable = new Map<string, ProxyRoute>()
 
     for (const option of proxyOptions) {
       const domain = option.to || 'rpx.localhost'
       const fromUrl = new URL(option.from?.startsWith('http') ? option.from : `http://${option.from}`)
-      const fromPort = Number.parseInt(fromUrl.port) || 80
 
       routingTable.set(domain, {
-        fromPort,
         sourceHost: fromUrl.host,
         cleanUrls: option.cleanUrls || false,
         changeOrigin: option.changeOrigin || false,
@@ -1221,72 +1272,7 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
           requestCert: false,
           rejectUnauthorized: false,
         },
-        async fetch(req: Request) {
-          const url = new URL(req.url)
-          const hostHeader = req.headers.get('host') || ''
-          // Strip port from Host header (e.g., "stacks.localhost:443" → "stacks.localhost")
-          const hostname = hostHeader.split(':')[0]
-
-          const route = routingTable.get(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
-
-          // Check path rewrites — route specific path prefixes to different backends.
-          // By default the prefix is preserved (matches Vite/nginx/http-proxy-middleware
-          // semantics); set `stripPrefix: true` per-rewrite to strip.
-          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',
-            })
-
-            const responseHeaders = new Headers(response.headers)
-
-            // Handle clean URLs redirect
-            if (route.cleanUrls && url.pathname.endsWith('.html')) {
-              const cleanPath = url.pathname.replace(/\.html$/, '')
-              return new Response(null, {
-                status: 301,
-                headers: { Location: cleanPath },
-              })
-            }
-
-            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 })
-          }
-        },
+        fetch: createProxyFetchHandler(host => routingTable.get(host), verbose),
         error(err: Error) {
           debugLog('server', `Shared proxy server error: ${err}`, verbose)
           return new Response(`Server Error: ${err.message}`, { status: 500 })

package/src/types.ts

@@ -29,6 +29,11 @@ export interface BaseProxyConfig {
   to: string // stacks.localhost
   start?: StartOptions
   pathRewrites?: PathRewrite[]
+  /**
+   * Stable id used when registering this proxy with the rpx daemon. Derived
+   * from `to` if omitted. Must match `/^[a-zA-Z0-9._-]+$/` and be ≤128 chars.
+   */
+  id?: string
 }
 
 export type BaseProxyOptions = Partial<BaseProxyConfig>
@@ -53,6 +58,12 @@ export interface SharedProxyConfig {
   cleanUrls: boolean
   changeOrigin?: boolean // default: false - changes the origin of the host header to the target URL
   regenerateUntrustedCerts?: boolean // If true, will regenerate and re-trust certs that exist but are not trusted by the system.
+  /**
+   * Route this proxy through the long-running rpx daemon instead of binding
+   * its own :443. Lets multiple `rpx start` invocations coexist on shared
+   * `:443` (Valet-style). Default: `false` for backward compatibility.
+   */
+  viaDaemon?: boolean
 }
 
 export type SharedProxyOptions = Partial<SharedProxyConfig>

package/src/utils.ts

@@ -36,6 +36,54 @@ export function debugLog(category: string, message: string, verbose?: boolean):
     logger.debug(`[rpx:${category}] ${message}`)
 }
 
+const REDACTED = '[redacted]'
+const SENSITIVE_KEYS = new Set([
+  'certificate',
+  'privatekey',
+  'key',
+  'cert',
+  'ca',
+  'rootca',
+  'password',
+  'sudo_password',
+])
+const PEM_BLOCK_RE = /-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/
+
+function isSensitiveKey(key: string): boolean {
+  const normalized = key.toLowerCase()
+  return SENSITIVE_KEYS.has(normalized)
+    || normalized.endsWith('password')
+    || normalized.includes('secret')
+    || normalized.includes('token')
+}
+
+export function redactSensitive(value: unknown): unknown {
+  if (Array.isArray(value))
+    return value.map(item => redactSensitive(item))
+
+  if (typeof value === 'string')
+    return PEM_BLOCK_RE.test(value) ? REDACTED : value
+
+  if (!value || typeof value !== 'object')
+    return value
+
+  const output: Record<string, unknown> = {}
+  for (const [key, nested] of Object.entries(value)) {
+    if (isSensitiveKey(key)) {
+      output[key] = REDACTED
+      continue
+    }
+
+    output[key] = redactSensitive(nested)
+  }
+
+  return output
+}
+
+export function safeStringify(value: unknown, space?: number): string {
+  return JSON.stringify(redactSensitive(value), null, space)
+}
+
 /**
  * Extracts hostnames from proxy configuration
  */