unplugin-https-reverse-proxy 4.0.4 → 4.1.0-beta.2

package/src/privileged/server.ts

@@ -0,0 +1,465 @@
+import type { Buffer } from 'node:buffer'
+import type { Socket } from 'node:net'
+import type { HelperEvent, HelperRequest, HelperResponse } from './protocol'
+import { execFile, spawn } from 'node:child_process'
+import { lchownSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+import { promisify } from 'node:util'
+import { addHost, removeHost, removeMarkedHosts } from './hosts-file'
+import { parseListeningPids, parseWindowsListeningPids } from './ports'
+import { serializeMessage } from './protocol'
+import { isAllowedFreePort, isSafeHost, isSafeIp } from './validation'
+
+const execFileAsync = promisify(execFile)
+
+/** Runs a command whose non-zero exit is expected, keeping stdout. */
+function execFileQuiet(file: string, args: string[]): Promise<{ stdout: string }> {
+  return new Promise((resolve) => {
+    execFile(file, args, (error, stdout) => resolve({ stdout: error && !stdout ? '' : stdout }))
+  })
+}
+
+export const HOSTS_PATH = platform() === 'win32'
+  ? 'C:\\Windows\\System32\\drivers\\etc\\hosts'
+  : '/etc/hosts'
+
+/**
+ * Command that drops the resolver cache so a fresh hosts entry is visible
+ * immediately. Each platform caches differently, so the command is per-OS.
+ */
+const FLUSH_COMMANDS: Record<string, Array<{ file: string, args: string[] }>> = {
+  win32: [{ file: 'ipconfig', args: ['/flushdns'] }],
+  darwin: [{ file: 'killall', args: ['-HUP', 'mDNSResponder'] }],
+  // systemd-resolved is the common case; the legacy name covers older distros
+  // and hosts without resolved simply have no cache to drop.
+  linux: [
+    { file: 'resolvectl', args: ['flush-caches'] },
+    { file: 'systemd-resolve', args: ['--flush-caches'] },
+  ],
+}
+
+const FLUSH_FALLBACK = [{ file: 'killall', args: ['-HUP', 'mDNSResponder'] }] as const
+
+/** Handle on the Caddy process owned by the helper. */
+export interface CaddyChild {
+  pid?: number
+  kill: (signal?: NodeJS.Signals) => boolean
+}
+
+/**
+ * Everything privileged the helper can do.
+ *
+ * Paths and arguments are fixed at helper start-up; the client only chooses
+ * when* something happens, never *what* runs. That keeps the privileged
+ * surface to a handful of primitives even if the socket is reached by an
+ * unexpected local process.
+ */
+export interface HelperDeps {
+  readHosts: () => string
+  writeHosts: (content: string) => void
+  flushDns: () => Promise<void>
+  freePort: (port: number) => Promise<number[]>
+  /** Caddy binary and the Caddyfile it must load, both fixed at start-up. */
+  caddyBin: string
+  caddyConfigPath: string
+  caddyCwd: string
+  caddyEnv: Record<string, string>
+  /** Installs the local root CA using a helper-owned command, not a client path. */
+  trustLocalCa: () => Promise<{ trusted: boolean, output: string }>
+  /** Caddy writes its PKI as root; this tree goes back to the user afterwards. */
+  caddyStoragePath?: string
+  storageOwner?: { uid: number, gid: number }
+  /** Starts Caddy with the configuration fixed at helper start-up. */
+  startCaddy: (emit: (event: HelperEvent) => void) => CaddyChild
+  stopCaddy: () => Promise<void>
+  log: (message: string) => void
+}
+
+/**
+ * Resolver caching only affects how fast a new entry is picked up, so a failed
+ * flush is logged instead of rolling back a hosts edit that already succeeded.
+ */
+async function flushDnsBestEffort(deps: HelperDeps): Promise<void> {
+  try {
+    await deps.flushDns()
+  }
+  catch (error) {
+    deps.log(`dns flush failed: ${(error as Error).message}`)
+  }
+}
+
+export interface HelperRuntime {
+  handle: (request: HelperRequest) => Promise<HelperResponse>
+  /** Registers a connected client so Caddy output reaches it. */
+  attach: (client: object) => void
+  /** Last client gone: stop Caddy and drop the hosts entries this plugin wrote. */
+  detach: (client: object) => Promise<void>
+  /** Runs the teardown once, regardless of how many clients were attached. */
+  dispose: () => Promise<void>
+  /** Removes hosts entries a previous crashed session left behind. */
+  sweepStaleEntries: () => Promise<boolean>
+}
+
+/**
+ * Request router shared by the helper process and its tests. Kept free of
+ * sockets so tests can drive it against a temp hosts file and a fake Caddy.
+ */
+export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
+  const clients = new Set<object>()
+  let teardown: Promise<void> | undefined
+  // Bumped whenever a client attaches. A teardown that started before the bump
+  // belongs to a previous generation and must not touch the new session.
+  let generation = 0
+  let caddy: CaddyChild | undefined
+
+  const broadcast = (event: HelperEvent): void => {
+    const line = serializeMessage(event)
+    for (const client of clients) {
+      const socket = client as Socket
+      if (typeof socket.write === 'function' && !socket.destroyed)
+        socket.write(line)
+    }
+  }
+
+  async function stopCaddy(): Promise<void> {
+    const current = caddy
+    caddy = undefined
+    if (current) {
+      try {
+        current.kill('SIGTERM')
+      }
+      catch {}
+    }
+    await deps.stopCaddy().catch(() => {})
+
+    // Give Caddy's files back to the developer: the next start runs as root
+    // again, but the developer must be able to read the PKI in between.
+    if (deps.caddyStoragePath && deps.storageOwner)
+      await reclaimTree(deps.caddyStoragePath, deps.storageOwner.uid, deps.storageOwner.gid).catch(() => {})
+  }
+
+  function dispose(): Promise<void> {
+    if (!teardown) {
+      const startedAt = generation
+      teardown = (async () => {
+        try {
+          // A client may have attached while this teardown was queued; its
+          // entries belong to the new session and must survive.
+          if (generation === startedAt) {
+            const edited = removeMarkedHosts(deps.readHosts())
+            if (edited.changed) {
+              deps.writeHosts(edited.content)
+              await deps.flushDns().catch(() => {})
+            }
+          }
+        }
+        catch (error) {
+          deps.log(`hosts cleanup failed: ${(error as Error).message}`)
+        }
+
+        // The new session owns Caddy now; stopping it here would kill a server
+        // this generation never started.
+        if (generation === startedAt)
+          await stopCaddy()
+      })()
+    }
+    return teardown
+  }
+
+  async function sweepStaleEntries(): Promise<boolean> {
+    try {
+      const edited = removeMarkedHosts(deps.readHosts())
+      if (!edited.changed)
+        return false
+      deps.writeHosts(edited.content)
+      await flushDnsBestEffort(deps)
+      return true
+    }
+    catch (error) {
+      deps.log(`stale hosts cleanup failed: ${(error as Error).message}`)
+      return false
+    }
+  }
+
+  async function handle(request: HelperRequest): Promise<HelperResponse> {
+    try {
+      switch (request.method) {
+        case 'ping':
+          return { id: request.id, ok: true, result: { pid: process.pid } }
+
+        case 'hosts.add': {
+          const { ip, host } = request.params
+          if (!isSafeIp(ip) || !isSafeHost(host))
+            return { id: request.id, ok: false, error: { message: 'invalid hosts entry' } }
+
+          const edited = addHost(deps.readHosts(), ip, host)
+          if (edited.changed)
+            deps.writeHosts(edited.content)
+          await flushDnsBestEffort(deps)
+          return { id: request.id, ok: true }
+        }
+
+        case 'hosts.remove': {
+          const { ip, host } = request.params
+          if (!isSafeIp(ip) || !isSafeHost(host))
+            return { id: request.id, ok: false, error: { message: 'invalid hosts entry' } }
+
+          const edited = removeHost(deps.readHosts(), ip, host)
+          if (edited.changed)
+            deps.writeHosts(edited.content)
+          await flushDnsBestEffort(deps)
+          return { id: request.id, ok: true }
+        }
+
+        case 'port.free': {
+          const { port } = request.params
+          if (!isAllowedFreePort(port))
+            return { id: request.id, ok: false, error: { message: `port ${port} is not releasable` } }
+
+          const killed = await deps.freePort(port)
+          return { id: request.id, ok: true, result: { killed } }
+        }
+
+        case 'caddy.start': {
+          if (caddy)
+            await stopCaddy()
+
+          caddy = deps.startCaddy(broadcast)
+          return { id: request.id, ok: true, result: { pid: caddy.pid } }
+        }
+
+        case 'caddy.stop': {
+          await stopCaddy()
+          return { id: request.id, ok: true }
+        }
+
+        case 'ca.trust': {
+          const result = await deps.trustLocalCa()
+          return { id: request.id, ok: true, result }
+        }
+
+        default:
+          return { id: (request as HelperRequest).id, ok: false, error: { message: 'unknown method' } }
+      }
+    }
+    catch (error) {
+      return { id: request.id, ok: false, error: { message: (error as Error).message } }
+    }
+  }
+
+  return {
+    handle,
+    attach(client) {
+      clients.add(client)
+      // Only the newest generation may clean up; an in-flight teardown started
+      // before this call is abandoned rather than cancelled mid-write.
+      generation++
+      teardown = undefined
+    },
+    async detach(client) {
+      clients.delete(client)
+      if (clients.size === 0)
+        await dispose()
+    },
+    dispose,
+    sweepStaleEntries,
+  }
+}
+
+export interface NodeHelperDepsOptions {
+  hostsPath?: string
+  caddyBin: string
+  caddyConfigPath: string
+  caddyCwd?: string
+  caddyEnv?: Record<string, string>
+  /** Caddy storage directory; handed back to the user when Caddy stops. */
+  caddyStoragePath?: string
+  /** Owner that receives the storage directory after Caddy stops. */
+  storageOwner?: { uid: number, gid: number }
+  log?: (message: string) => void
+}
+
+/** Best-effort recursive chown, skipping anything it cannot read. */
+async function reclaimTree(target: string, uid: number, gid: number): Promise<string[]> {
+  const reclaimed: string[] = []
+
+  const walk = (path: string): void => {
+    let stats
+    try {
+      // `lstat`: a symlink must never redirect a root chown to its target.
+      stats = lstatSync(path)
+    }
+    catch {
+      return
+    }
+
+    try {
+      lchownSync(path, uid, gid)
+      reclaimed.push(path)
+    }
+    catch {}
+
+    if (!stats.isDirectory())
+      return
+
+    let entries: string[]
+    try {
+      entries = readdirSync(path)
+    }
+    catch {
+      return
+    }
+
+    for (const entry of entries)
+      walk(join(path, entry))
+  }
+
+  walk(target)
+  return reclaimed
+}
+
+/** Installs the Caddy root CA using helper-owned commands. */
+async function trustLocalCaWithSystemTools(caddyBin: string): Promise<{ trusted: boolean, output: string }> {
+  // `caddy trust` reads the CA through the admin API, which only exists while
+  // Caddy is serving; the plugin calls this after Caddy is up.
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      caddyBin,
+      ['trust', '--ca', 'local', '--address', '127.0.0.1:2019'],
+      { timeout: 120_000 },
+    )
+    return { trusted: true, output: `${stdout}${stderr}`.trim() }
+  }
+  catch (error) {
+    const output = String((error as { stdout?: string }).stdout ?? '') + String((error as { stderr?: string }).stderr ?? '')
+    if (/already|not modified|no changes/i.test(output))
+      return { trusted: true, output: output.trim() }
+    throw new Error(output.trim() || (error as Error).message)
+  }
+}
+
+/** Production wiring for the helper process. */
+export function createNodeHelperDeps(options: NodeHelperDepsOptions): HelperDeps {
+  const hostsPath = options.hostsPath ?? HOSTS_PATH
+  const log = options.log ?? ((message: string) => process.stdout.write(`${message}\n`))
+  let caddy: CaddyChild | undefined
+
+  return {
+    readHosts: () => readFileSync(hostsPath, 'utf8'),
+    writeHosts: (content) => {
+      writeFileSync(hostsPath, content)
+    },
+    flushDns: async () => {
+      const candidates = FLUSH_COMMANDS[platform()] ?? [...FLUSH_FALLBACK]
+      let lastError: Error | undefined
+
+      for (const candidate of candidates) {
+        try {
+          await execFileAsync(candidate.file, candidate.args)
+          return
+        }
+        catch (error) {
+          lastError = error as Error
+        }
+      }
+
+      throw lastError ?? new Error('no DNS cache flush command for this platform')
+    },
+    freePort: async (port) => {
+      // `lsof` exits with 1 when nothing matches, which is the normal case for
+      // a free port; only its stdout carries the answer.
+      const pids = platform() === 'win32'
+        ? parseWindowsListeningPids((await execFileAsync('netstat', ['-ano'])).stdout, port)
+        : parseListeningPids((await execFileQuiet('lsof', [`-ti:${port}`, '-sTCP:LISTEN'])).stdout)
+
+      const killed: number[] = []
+      for (const pid of pids) {
+        if (pid === process.pid)
+          continue
+        try {
+          process.kill(pid, 'SIGTERM')
+          killed.push(pid)
+        }
+        catch {}
+      }
+      return killed
+    },
+    caddyBin: options.caddyBin,
+    caddyConfigPath: options.caddyConfigPath,
+    caddyCwd: options.caddyCwd ?? process.cwd(),
+    caddyEnv: options.caddyEnv ?? {},
+    trustLocalCa: () => trustLocalCaWithSystemTools(options.caddyBin),
+    caddyStoragePath: options.caddyStoragePath,
+    storageOwner: options.storageOwner,
+    startCaddy: (emit) => {
+      const child = spawn(options.caddyBin, ['run', '--adapter', 'caddyfile', '--config', options.caddyConfigPath], {
+        cwd: options.caddyCwd ?? process.cwd(),
+        env: { ...process.env, ...options.caddyEnv },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      child.stdout?.on('data', (data: Buffer) => emit({ type: 'event', kind: 'caddy.stdout', data: data.toString() }))
+      child.stderr?.on('data', (data: Buffer) => emit({ type: 'event', kind: 'caddy.stderr', data: data.toString() }))
+      child.on('exit', (code, signal) => emit({ type: 'event', kind: 'caddy.exit', code, signal }))
+      caddy = child as unknown as CaddyChild
+      return caddy
+    },
+    stopCaddy: async () => {
+      const current = caddy
+      caddy = undefined
+      if (!current)
+        return
+      try {
+        current.kill('SIGTERM')
+      }
+      catch {}
+    },
+    log,
+  }
+}
+
+/**
+ * Serves requests on an authenticated connection. When the client disappears —
+ * including a `SIGKILL` of the plugin process — the socket closes and `dispose`
+ * restores the machine state.
+ */
+export function attachSocket(socket: Socket, runtime: HelperRuntime, log: (message: string) => void): void {
+  let buffer = ''
+  runtime.attach(socket)
+
+  socket.on('data', (chunk: Buffer) => {
+    buffer += chunk.toString('utf8')
+    let index = buffer.indexOf('\n')
+    while (index >= 0) {
+      const line = buffer.slice(0, index)
+      buffer = buffer.slice(index + 1)
+      index = buffer.indexOf('\n')
+
+      if (!line.trim())
+        continue
+
+      let request: HelperRequest
+      try {
+        request = JSON.parse(line) as HelperRequest
+      }
+      catch (error) {
+        log(`invalid request: ${(error as Error).message}`)
+        continue
+      }
+
+      void runtime.handle(request).then((response) => {
+        if (!socket.destroyed)
+          socket.write(serializeMessage(response))
+      })
+    }
+  })
+
+  socket.on('error', (error) => {
+    log(`connection error: ${error.message}`)
+  })
+
+  socket.on('close', () => {
+    void runtime.detach(socket)
+  })
+}

package/src/privileged/session.ts

@@ -0,0 +1,114 @@
+import type { PrivilegedClient } from './client'
+import { Buffer } from 'node:buffer'
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { platform } from 'node:os'
+import { join } from 'node:path'
+import { connectExistingHelper, createHelperToken, startPrivilegedHelper } from './launch'
+
+export interface SessionScope {
+  /** Runtime directory shared by the plugin, e.g. `TEMP_DIR`. */
+  runtimeDir: string
+  /** Directory of the running bundle; used to locate the helper entry. */
+  helperEntry: string
+  helperArgs?: string[]
+  env?: NodeJS.ProcessEnv
+  sudoCommand?: string
+  /** Skips the interactive credential check; used by tests. */
+  skipAuth?: boolean
+  /** Runs the helper as the current user; used by tests without privileges. */
+  direct?: boolean
+  /** Caddy storage directory; the helper hands it back to the user on stop. */
+  caddyStoragePath?: string
+  /** Caddy binary the helper may run; the client cannot change it later. */
+  caddyBin: string
+  /** Caddyfile the helper may load. */
+  caddyConfigPath: string
+  log?: (message: string) => void
+}
+
+export interface OpenedSession {
+  client: PrivilegedClient
+  /** True when an already-running helper was reused. */
+  reused: boolean
+  close: () => Promise<void>
+}
+
+function tokenPath(runtimeDir: string): string {
+  return join(runtimeDir, 'helper.token')
+}
+
+export function sessionSocketPath(runtimeDir: string): string {
+  if (platform() === 'win32')
+    return `\\\\.\\pipe\\uhrp-${Buffer.from(runtimeDir).toString('hex').slice(0, 40)}`
+  return join(runtimeDir, 'helper.sock')
+}
+
+/**
+ * Connects to the helper already serving this runtime directory, or starts a
+ * new one. Reuse matters for multi-instance dev servers: the second instance
+ * attaches to the running Caddy instead of asking for a password again.
+ */
+export async function openHelperSession(scope: SessionScope): Promise<OpenedSession> {
+  const socketPath = sessionSocketPath(scope.runtimeDir)
+
+  if (existsSync(socketPath) || platform() === 'win32') {
+    const token = await readToken(scope.runtimeDir)
+    if (token) {
+      const reused = await connectExistingHelper(socketPath, token)
+      if (reused) {
+        return {
+          client: reused,
+          reused: true,
+          close: async () => {
+            await reused.close()
+          },
+        }
+      }
+    }
+  }
+
+  const token = createHelperToken()
+  const started = await startPrivilegedHelper({
+    socketPath,
+    token,
+    helperEntry: scope.helperEntry,
+    helperArgs: scope.helperArgs,
+    sudoCommand: scope.sudoCommand,
+    skipAuth: scope.skipAuth,
+    direct: scope.direct,
+    env: scope.env,
+    caddyStoragePath: scope.caddyStoragePath,
+    caddyBin: scope.caddyBin,
+    caddyConfigPath: scope.caddyConfigPath,
+    log: scope.log,
+  })
+
+  await writeToken(scope.runtimeDir, token)
+
+  return {
+    client: started.client,
+    reused: false,
+    close: async () => {
+      await started.close()
+    },
+  }
+}
+
+async function readToken(runtimeDir: string): Promise<string | undefined> {
+  try {
+    const content = await readFile(tokenPath(runtimeDir), 'utf8')
+    const token = content.trim()
+    return token === '' ? undefined : token
+  }
+  catch {
+    return undefined
+  }
+}
+
+async function writeToken(runtimeDir: string, token: string): Promise<void> {
+  try {
+    await writeFile(tokenPath(runtimeDir), token, { mode: 0o600 })
+  }
+  catch {}
+}

package/src/privileged/validation.ts

@@ -0,0 +1,38 @@
+import { isIP } from 'node:net'
+
+/**
+ * Validates values that cross the socket. Everything reaching the privileged
+ * helper is untrusted, and a hosts line in particular is a plain-text file: an
+ * unvalidated hostname containing a newline could inject entries this plugin
+ * does not own and therefore never cleans up.
+ */
+
+/** Ports the plugin may free. Wide enough for the two the proxy binds. */
+export const ALLOWED_FREE_PORTS = new Set([80, 443])
+
+const HOSTNAME_PATTERN = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i
+const IPV6_IN_HOSTS = /^[0-9a-f:.]+$/i
+
+export function isSafeHost(host: unknown): host is string {
+  if (typeof host !== 'string' || host.length === 0 || host.length > 253)
+    return false
+  // A hosts entry is whitespace separated, so any whitespace or control
+  // character would split the line or start a new one.
+  if (/[\s#\0]/.test(host))
+    return false
+  return HOSTNAME_PATTERN.test(host)
+}
+
+export function isSafeIp(ip: unknown): ip is string {
+  if (typeof ip !== 'string')
+    return false
+  if (isIP(ip) !== 0)
+    return true
+  // `::1` and friends are caught by isIP; this keeps the check explicit for
+  // hosts files that spell IPv6 without brackets.
+  return IPV6_IN_HOSTS.test(ip)
+}
+
+export function isAllowedFreePort(port: unknown): port is number {
+  return typeof port === 'number' && Number.isInteger(port) && ALLOWED_FREE_PORTS.has(port)
+}

package/src/privileged/windows-elevation.ts

@@ -0,0 +1,80 @@
+import type { ChildProcess } from 'node:child_process'
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+
+/**
+ * Windows has no `sudo`: elevation goes through UAC, and the elevated process
+ * is a new process that cannot inherit the parent's stdio. The helper talks
+ * over a named pipe, so it only needs to be started detached.
+ *
+ * `Start-Process -Verb RunAs` is the documented way to trigger the UAC prompt
+ * without a helper binary or a dependency on `sudo-prompt`.
+ */
+export interface WindowsElevationOptions {
+  /** Executable to run elevated; normally the node runtime. */
+  file: string
+  /** Arguments for that executable. */
+  args: string[]
+  /** Directory to start in; defaults to the parent's. */
+  cwd?: string
+}
+
+/** Quotes an argument for PowerShell's single-quoted string syntax. */
+export function quotePowerShell(value: string): string {
+  return `'${value.replace(/'/g, '\'\'')}'`
+}
+
+/**
+ * Builds the PowerShell command that starts `file` elevated. Exported so the
+ * escaping can be unit-tested without touching a real UAC prompt.
+ */
+export function buildElevationCommand(options: WindowsElevationOptions): string {
+  const argumentList = options.args.map(quotePowerShell).join(',')
+  const parts = [
+    'Start-Process',
+    '-FilePath',
+    quotePowerShell(options.file),
+  ]
+
+  if (argumentList)
+    parts.push('-ArgumentList', argumentList)
+
+  if (options.cwd)
+    parts.push('-WorkingDirectory', quotePowerShell(options.cwd))
+
+  parts.push('-Verb', 'RunAs')
+  parts.push('-WindowStyle', 'Hidden')
+
+  return parts.join(' ')
+}
+
+/**
+ * Starts the helper elevated on Windows. Resolves once PowerShell has accepted
+ * the request; the helper's own readiness is observed through the named pipe.
+ */
+export function spawnElevatedOnWindows(options: WindowsElevationOptions): Promise<ChildProcess> {
+  return new Promise((resolve, reject) => {
+    const script = buildElevationCommand(options)
+    const child = spawn(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-Command', script],
+      { stdio: 'ignore', windowsHide: true },
+    )
+
+    // PowerShell exits once UAC is answered; a non-zero code means the user
+    // dismissed the prompt or elevation was denied.
+    child.once('error', reject)
+    child.once('exit', (code) => {
+      if (code === 0)
+        return resolve(child)
+      reject(new Error(
+        `administrator permission was not granted (PowerShell exited with ${code}). `
+        + 'Accept the UAC prompt to let the plugin edit the hosts file and bind ports 80/443.',
+      ))
+    })
+  })
+}
+
+export function isWindowsElevationAvailable(): boolean {
+  return process.platform === 'win32'
+}