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

package/src/privileged/launch.ts

@@ -0,0 +1,332 @@
+import type { Buffer } from 'node:buffer'
+import type { PrivilegedClient } from './client'
+import { spawn, spawnSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { platform } from 'node:os'
+import process from 'node:process'
+import { collectForwardedEnv, connectClient } from './client'
+import { spawnElevatedOnWindows } from './windows-elevation'
+
+export function createHelperToken(): string {
+  return randomBytes(24).toString('hex')
+}
+
+export interface LaunchOptions {
+  socketPath: string
+  token: string
+  /** Executable started as root (node, or tsx when running from source). */
+  helperEntry: string
+  /** Arguments placed before the helper's own `--socket/--token` flags. */
+  helperArgs?: string[]
+  sudoCommand?: string
+  /** Skips the interactive credential check; used by tests and Windows. */
+  skipAuth?: boolean
+  /**
+   * Starts the helper as the current user instead of going through sudo.
+   * Used by tests that need the helper protocol but not real privileges.
+   */
+  direct?: boolean
+  env?: NodeJS.ProcessEnv
+  log?: (message: string) => void
+  /** How long to wait for the helper socket to accept the connection. */
+  connectTimeoutMs?: number
+  /**
+   * Caddy's storage directory. Caddy runs as root in the helper, so the helper
+   * hands this tree back to the developer when it stops Caddy.
+   */
+  caddyStoragePath?: string
+  /** Caddy binary the helper is allowed to run, fixed for the whole session. */
+  caddyBin: string
+  /** Caddyfile the helper is allowed to load. */
+  caddyConfigPath: string
+  /** Admin API socket the helper talks to when installing the CA. */
+  caddyAdminSocket?: string
+  /** Shown before the password prompt so the request is not a surprise. */
+  reason?: { target: string, https: boolean }
+}
+
+/**
+ * Explains why a password is about to be requested. Without this the prompt
+ * appears out of nowhere in the middle of `npm run dev` and looks like something
+ * went wrong.
+ */
+export function describePasswordReason(target: string, https: boolean): string[] {
+  const port = https ? '443' : '80'
+  return [
+    `reverse proxy needs administrator permission for ${target}`,
+    `  · bind port ${port}${https ? ` for https://${target}` : ''}`,
+    `  · add ${target} to the hosts file`,
+    '',
+    'This is the only prompt; the rest of the dev server keeps running as you.',
+    'Press Ctrl+C at the prompt to skip the proxy and keep the dev server.',
+  ]
+}
+
+/**
+ * Asks for the administrator password once, up front, on the dev terminal.
+ *
+ * The credential cache is keyed by terminal, so a later `sudo -n` only finds
+ * this entry when the child stays in the same session. That is why the helper
+ * is spawned without `detached`.
+ *
+ * Returns `denied` when the user dismissed the prompt, so the caller can keep
+ * the dev server running instead of treating it as a crash.
+ */
+export async function authenticateSudo(
+  sudoCommand = 'sudo',
+  options: { target?: string, https?: boolean, quiet?: boolean } = {},
+): Promise<{ ok: boolean, denied?: boolean, message?: string }> {
+  if (platform() === 'win32')
+    return { ok: true }
+
+  if (spawnSync(sudoCommand, ['-n', 'true'], { stdio: 'ignore' }).status === 0)
+    return { ok: true }
+
+  // Tests drive this without a terminal; writing the notice there would print
+  // password instructions into the middle of the test output.
+  if (options.target && !options.quiet) {
+    for (const line of describePasswordReason(options.target, options.https ?? false))
+      process.stderr.write(`${line}\n`)
+    process.stderr.write('\n')
+  }
+
+  // `sudo -v` inherits the terminal, so Ctrl+C reaches this process too. Without
+  // a handler the default action kills the dev server, which reads as "the
+  // proxy crashed my dev server" when the user only meant to skip it.
+  let interrupted = false
+  const onSigint = (): void => {
+    interrupted = true
+  }
+  process.on('SIGINT', onSigint)
+
+  try {
+    const { status, signal } = await runPrompt(sudoCommand)
+    if (status === 0)
+      return { ok: true }
+
+    // `sudo` exits 1 on a wrong password and dies by the signal on Ctrl+C.
+    // Both are checked: a real Ctrl+C reaches this process and the child
+    // together, while a signal aimed at the child alone only shows up here.
+    const cancelled = interrupted || signal === 'SIGINT'
+    return {
+      ok: false,
+      denied: true,
+      message: cancelled
+        ? 'administrator permission was cancelled'
+        : 'administrator permission is required to edit the hosts file and bind ports 80/443',
+    }
+  }
+  finally {
+    process.off('SIGINT', onSigint)
+  }
+}
+
+/**
+ * Runs `sudo -v` with the terminal attached.
+ *
+ * Spawned asynchronously rather than with `spawnSync`: the synchronous form
+ * blocks the event loop, so the SIGINT handler above never runs and the exit
+ * looks like a plain failure instead of a cancellation.
+ *
+ * The terminal is put back into cooked mode first. Vite turns on raw mode for
+ * its `h + enter` shortcuts, and in that mode Enter no longer terminates the
+ * line sudo is reading, so the password appears to need a second Enter.
+ */
+function runPrompt(sudoCommand: string): Promise<{ status: number | null, signal: NodeJS.Signals | null }> {
+  return new Promise((resolve) => {
+    const restore = takeBackTerminal()
+    const child = spawn(sudoCommand, ['-v'], { stdio: 'inherit' })
+
+    const finish = (result: { status: number | null, signal: NodeJS.Signals | null }): void => {
+      restore()
+      resolve(result)
+    }
+
+    child.on('error', () => finish({ status: 1, signal: null }))
+    child.on('exit', (status, signal) => finish({ status, signal }))
+  })
+}
+
+/**
+ * Gives the terminal to `sudo` for the duration of the prompt.
+ *
+ * Vite keeps stdin in raw mode with a `data` listener attached, so that every
+ * keystroke reaches its shortcut handler. Two things break the password read:
+ *
+ * 1. Raw mode does no line editing, so Enter never terminates the line sudo is
+ *    waiting for.
+ * 2. The `data` listener is resumed, so it consumes the characters before sudo
+ *    can see them. sudo then reads nothing and reports a wrong password.
+ *
+ * Both are undone here and restored afterwards, so Vite's shortcuts keep
+ * working once the prompt is over.
+ */
+function takeBackTerminal(): () => void {
+  const stdin = process.stdin
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function')
+    return () => {}
+
+  const wasRaw = stdin.isRaw === true
+
+  // `pause` detaches the stream from the tty without removing Vite's listener,
+  // so the same handler still works when the stream is resumed later.
+  stdin.pause()
+
+  try {
+    stdin.setRawMode(false)
+  }
+  catch {
+    stdin.resume()
+    return () => {}
+  }
+
+  return () => {
+    if (wasRaw) {
+      try {
+        stdin.setRawMode(true)
+      }
+      catch {}
+    }
+    // Resume last: Vite's listener is still attached and expects a live stream.
+    stdin.resume()
+  }
+}
+
+/** The user dismissed the password prompt; this is a choice, not a failure. */
+export class PrivilegeDeniedError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PrivilegeDeniedError'
+  }
+}
+
+export interface PrivilegedHelperHandle {
+  client: PrivilegedClient
+  close: () => Promise<void>
+}
+
+/**
+ * Starts the privileged helper and connects to it.
+ *
+ * Only this child runs as root: the Node process that owns the dev server,
+ * its caches and `node_modules` keeps the developer's identity. The user's
+ * proxy/HOME settings reach Caddy through the helper's environment instead of
+ * `sudo -E`.
+ */
+export async function startPrivilegedHelper(options: LaunchOptions): Promise<PrivilegedHelperHandle> {
+  const {
+    socketPath,
+    token,
+    helperEntry,
+    helperArgs = [],
+    sudoCommand = 'sudo',
+    skipAuth = false,
+    direct = false,
+    env = process.env,
+    log,
+    connectTimeoutMs = 120_000,
+  } = options
+
+  if (!skipAuth && !direct) {
+    const auth = await authenticateSudo(sudoCommand, options.reason)
+    if (!auth.ok) {
+      const message = auth.message ?? 'administrator permission is required'
+      throw auth.denied ? new PrivilegeDeniedError(message) : new Error(message)
+    }
+  }
+
+  const forwarded = collectForwardedEnv(env)
+  const forwardedArgs = Object.entries(forwarded).map(([key, value]) => `${key}=${value}`)
+  // `helperEntry` is the runtime and `helperArgs` the script it must run, so
+  // the helper's own flags always come last. The owner ids travel with them
+  // because the helper only learns who its client is at handshake time.
+  const childArgv = [
+    ...helperArgs,
+    '--socket',
+    socketPath,
+    '--token',
+    token,
+    ...(typeof process.getuid === 'function' ? ['--owner-uid', String(process.getuid())] : []),
+    ...(typeof process.getgid === 'function' ? ['--owner-gid', String(process.getgid())] : []),
+    ...(options.caddyStoragePath ? ['--caddy-storage', options.caddyStoragePath] : []),
+    '--caddy',
+    options.caddyBin,
+    '--caddy-config',
+    options.caddyConfigPath,
+    ...(options.caddyAdminSocket ? ['--caddy-admin', options.caddyAdminSocket] : []),
+  ]
+
+  let child: ReturnType<typeof spawn> | undefined
+
+  if (!direct && platform() === 'win32') {
+    // UAC: the elevated helper is a separate process and cannot inherit stdio,
+    // so it reports through the named pipe instead. The user's environment is
+    // recovered by the helper from its own process env, which Windows keeps.
+    await spawnElevatedOnWindows({ file: helperEntry, args: childArgv, cwd: process.cwd() })
+  }
+  else {
+    const command = direct ? helperEntry : sudoCommand
+    const spawnArgs = direct
+      ? childArgv
+      : ['-n', 'env', ...forwardedArgs, helperEntry, ...childArgv]
+
+    // No `detached`: sudo stores its credential per session, and `setsid()`
+    // would make the helper look like a different login, so `sudo -n` could not
+    // reuse the password entered a moment earlier. The stdio pipes keep the
+    // helper reachable from this process.
+    child = spawn(command, spawnArgs, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    child.stdout?.on('data', (data: Buffer) => log?.(data.toString().trimEnd()))
+    child.stderr?.on('data', (data: Buffer) => log?.(data.toString().trimEnd()))
+
+    const exited = new Promise<number | null>(resolve => child!.once('exit', code => resolve(code)))
+
+    // Refused credentials make the helper exit immediately; report that instead
+    // of waiting for the full connection timeout.
+    const earlyExit = await Promise.race([
+      exited,
+      new Promise<undefined>(resolve => setTimeout(() => resolve(undefined), 500)),
+    ])
+
+    if (earlyExit !== undefined && earlyExit !== 0) {
+      throw new Error(
+        `privileged helper exited with code ${earlyExit}. `
+        + 'Administrator permission was refused, or sudo is not available.',
+      )
+    }
+  }
+
+  try {
+    const client = await connectClient({ socketPath, token, timeoutMs: connectTimeoutMs })
+    return {
+      client,
+      async close() {
+        await client.close().catch(() => {})
+        child?.unref()
+      },
+    }
+  }
+  catch (error) {
+    try {
+      child?.kill()
+    }
+    catch {}
+    throw error
+  }
+}
+
+/** Reuses a helper that is already running for this runtime directory. */
+export async function connectExistingHelper(
+  socketPath: string,
+  token: string,
+  timeoutMs = 1500,
+): Promise<PrivilegedClient | undefined> {
+  try {
+    return await connectClient({ socketPath, token, timeoutMs })
+  }
+  catch {
+    return undefined
+  }
+}

package/src/privileged/path-guard.ts

@@ -0,0 +1,74 @@
+import type { Stats } from 'node:fs'
+import { lstatSync } from 'node:fs'
+
+/**
+ * Why a path is refused before the helper runs it.
+ *
+ * The helper runs as root while the paths come from a process running as the
+ * developer. Anything that process, or any other local user, can rewrite after
+ * the check would become root-executed code or root-loaded config, so the
+ * checks below run once at startup and the result is trusted for the session.
+ */
+export interface PathRejection {
+  path: string
+  reason: string
+}
+
+export interface PathCheckOptions {
+  /**
+   * uid allowed to own the path besides root.
+   *
+   * The helper entry itself lives in the developer's `node_modules`, so the
+   * invoking user has to be accepted for the paths that came from there.
+   */
+  ownerUid?: number
+  /** Human-readable role, used in the rejection message. */
+  label: string
+}
+
+function describe(stats: Stats): string {
+  return `uid=${stats.uid} mode=${(stats.mode & 0o777).toString(8)}`
+}
+
+/**
+ * Rejects a path the helper must not execute or load.
+ *
+ * Symbolic links are refused outright: the check has to describe the file that
+ * will actually be used, and a link can be repointed after the check. Group- or
+ * world-writable files are refused because any local user could replace them
+ * between the check and the exec.
+ */
+export function checkPrivilegedPath(
+  path: string,
+  options: PathCheckOptions,
+): PathRejection | undefined {
+  let stats: Stats
+  try {
+    stats = lstatSync(path)
+  }
+  catch (error) {
+    return { path, reason: `${options.label} is not readable: ${(error as Error).message}` }
+  }
+
+  if (stats.isSymbolicLink())
+    return { path, reason: `${options.label} is a symbolic link (${describe(stats)})` }
+
+  if (!stats.isFile() && !stats.isDirectory())
+    return { path, reason: `${options.label} is neither a file nor a directory` }
+
+  const allowedOwner = stats.uid === 0 || (options.ownerUid !== undefined && stats.uid === options.ownerUid)
+  if (!allowedOwner)
+    return { path, reason: `${options.label} is owned by another user (${describe(stats)})` }
+
+  // Root's own files are fine at 644/755; the point is that no one else can
+  // write them.
+  if (stats.mode & 0o022)
+    return { path, reason: `${options.label} is group- or world-writable (${describe(stats)})` }
+
+  return undefined
+}
+
+/** Formats a rejection for the helper log; one place keeps the wording stable. */
+export function describeRejection(rejection: PathRejection): string {
+  return `refusing to start: ${rejection.reason} (${rejection.path})`
+}

package/src/privileged/ports.ts

@@ -0,0 +1,45 @@
+/**
+ * Helpers for freeing a listening TCP port without shelling out to `npx`.
+ * `parseListeningPids` keeps the decision testable: it only turns command
+ * output into pids, never spawns anything.
+ */
+
+/** Parses `lsof -ti:<port> -sTCP:LISTEN` output (one pid per line). */
+export function parseListeningPids(output: string): number[] {
+  const pids = new Set<number>()
+  for (const line of output.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed)
+      continue
+    if (!/^\d+$/.test(trimmed))
+      continue
+    const pid = Number(trimmed)
+    if (Number.isSafeInteger(pid) && pid > 0)
+      pids.add(pid)
+  }
+  return [...pids]
+}
+
+/** Parses `netstat -ano` output for the owning pids of a listening port on Windows. */
+export function parseWindowsListeningPids(output: string, port: number): number[] {
+  const pids = new Set<number>()
+  const suffix = `:${port}`
+
+  for (const line of output.split(/\r?\n/)) {
+    const columns = line.trim().split(/\s+/)
+    if (columns.length < 5)
+      continue
+    const protocol = columns[0].toUpperCase()
+    if (protocol !== 'TCP')
+      continue
+    if (!columns[1].endsWith(suffix))
+      continue
+    if (columns[3].toUpperCase() !== 'LISTENING')
+      continue
+    const pid = Number(columns[4])
+    if (Number.isSafeInteger(pid) && pid > 0)
+      pids.add(pid)
+  }
+
+  return [...pids]
+}

package/src/privileged/protocol.ts

@@ -0,0 +1,111 @@
+/**
+ * Wire protocol between the unprivileged plugin process and the privileged
+ * helper. Newline-delimited JSON keeps the helper dependency-free.
+ *
+ * The helper never executes a binary or uses a path supplied by the client:
+ * both are fixed when the helper starts (`--caddy` and `--caddy-config`), so a
+ * client that reaches the socket cannot turn the helper into a root shell.
+ */
+
+export type RpcId = number
+
+export interface RpcErrorPayload {
+  message: string
+  code?: string
+}
+
+export type HelperRequest =
+  | { id: RpcId, method: 'ping' }
+  | { id: RpcId, method: 'hosts.add', params: { ip: string, host: string } }
+  | { id: RpcId, method: 'hosts.remove', params: { ip: string, host: string } }
+  | { id: RpcId, method: 'port.free', params: { port: number } }
+  | { id: RpcId, method: 'caddy.start' }
+  | { id: RpcId, method: 'caddy.stop' }
+  | { id: RpcId, method: 'ca.trust' }
+
+/** Request method names, used by the client's typed `call` overloads. */
+export type HelperMethod = HelperRequest['method']
+
+export type HelperResponse =
+  | { id: RpcId, ok: true, result?: unknown }
+  | { id: RpcId, ok: false, error: RpcErrorPayload }
+
+export type HelperEvent =
+  | { type: 'event', kind: 'caddy.stdout', data: string }
+  | { type: 'event', kind: 'caddy.stderr', data: string }
+  | { type: 'event', kind: 'caddy.exit', code: number | null, signal: string | null }
+
+export type HelperMessage = HelperResponse | HelperEvent
+
+export interface ClientHandshake {
+  type: 'handshake'
+  token: string
+}
+
+export interface ServerHandshake {
+  type: 'handshake'
+  ok: boolean
+  pid?: number
+  reason?: string
+}
+
+export type DecodedMessage =
+  | { ok: true, message: HelperMessage }
+  | { ok: false, error: string }
+
+export function serializeMessage(message: unknown): string {
+  return `${JSON.stringify(message)}\n`
+}
+
+/** Splits a stream into complete lines, keeping the trailing partial line. */
+export function splitLines(buffer: string, chunk: string): { lines: string[], rest: string } {
+  const parts = (buffer + chunk).split('\n')
+  const rest = parts.pop() ?? ''
+  return { lines: parts.filter(line => line.trim() !== ''), rest }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+export function decodeMessage(line: string): DecodedMessage {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(line)
+  }
+  catch (error) {
+    return { ok: false, error: `invalid JSON: ${(error as Error).message}` }
+  }
+
+  if (!isRecord(parsed))
+    return { ok: false, error: 'message must be an object' }
+
+  if (parsed.type === 'event') {
+    if (typeof parsed.kind !== 'string')
+      return { ok: false, error: 'event.kind must be a string' }
+    return { ok: true, message: parsed as unknown as HelperEvent }
+  }
+
+  if (typeof parsed.id !== 'number')
+    return { ok: false, error: 'response.id must be a number' }
+
+  if (parsed.ok === true)
+    return { ok: true, message: { id: parsed.id, ok: true, result: parsed.result } }
+
+  if (parsed.ok === false) {
+    const error = isRecord(parsed.error) ? parsed.error : {}
+    return {
+      ok: true,
+      message: {
+        id: parsed.id,
+        ok: false,
+        error: {
+          message: typeof error.message === 'string' ? error.message : 'helper request failed',
+          code: typeof error.code === 'string' ? error.code : undefined,
+        },
+      },
+    }
+  }
+
+  return { ok: false, error: 'response.ok must be a boolean' }
+}