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

package/src/privileged/hosts-file.ts

@@ -0,0 +1,142 @@
+import { isIP } from 'node:net'
+
+/**
+ * `/etc/hosts` edits are modelled as pure string transformations so the helper
+ * can be tested without touching the real file.
+ *
+ * `/etc/hosts` is user data: a line may map several names at once
+ * (`127.0.0.1 a.test b.test`). Editing one name must never drop the others, and
+ * entries this plugin did not write must survive every operation.
+ */
+
+export const HOSTS_MARKER = '# uhrp'
+export const HOSTS_MARKER_PATTERN = /#\s*uhrp\b/
+
+export interface HostsEdit {
+  content: string
+  changed: boolean
+}
+
+interface ParsedLine {
+  ip: string
+  hosts: string[]
+}
+
+function detectEol(content: string): string {
+  return content.includes('\r\n') ? '\r\n' : '\n'
+}
+
+function toBodyLines(content: string): string[] {
+  const lines = content.split(/\r?\n/)
+  if (lines.length > 0 && lines[lines.length - 1] === '')
+    lines.pop()
+  return lines
+}
+
+function parseLine(line: string): ParsedLine | undefined {
+  const withoutComment = line.replace(/#.*/, '').trim()
+  if (!withoutComment)
+    return undefined
+  const [ip, ...hosts] = withoutComment.split(/\s+/)
+  if (!ip || hosts.length === 0)
+    return undefined
+  return { ip, hosts }
+}
+
+function isOwned(line: string): boolean {
+  return HOSTS_MARKER_PATTERN.test(line)
+}
+
+function mentionsHost(entry: ParsedLine, host: string): boolean {
+  return entry.hosts.some(candidate => candidate.toLowerCase() === host.toLowerCase())
+}
+
+function sameIpFamily(left: string, right: string): boolean {
+  const leftVersion = isIP(left)
+  return leftVersion !== 0 && leftVersion === isIP(right)
+}
+
+function rebuild(lines: string[], original: string, eol: string): HostsEdit {
+  const content = lines.length > 0 ? lines.join(eol) + eol : ''
+  return { content, changed: content !== original }
+}
+
+/**
+ * Drops `host` from its mapping and appends a marked entry for it.
+ *
+ * A user-written line that also maps other names is rewritten without `host`
+ * instead of being deleted, so `127.0.0.1 a.test b.test` keeps `b.test`.
+ */
+export function addHost(content: string, ip: string, host: string): HostsEdit {
+  const eol = detectEol(content)
+  const lines: string[] = []
+
+  for (const line of toBodyLines(content)) {
+    const entry = parseLine(line)
+    if (!entry || !mentionsHost(entry, host) || !sameIpFamily(entry.ip, ip)) {
+      lines.push(line)
+      continue
+    }
+
+    const remaining = entry.hosts.filter(candidate => candidate.toLowerCase() !== host.toLowerCase())
+    if (remaining.length === 0)
+      continue
+
+    // Preserve the original comment when one exists so a user's annotation is
+    // not silently dropped by our edit.
+    const comment = line.match(/#.*/)?.[0] ?? ''
+    const rebuilt = `${entry.ip} ${remaining.join(' ')}${comment ? ` ${comment}` : ''}`
+    lines.push(rebuilt)
+  }
+
+  lines.push(`${ip} ${host} ${HOSTS_MARKER}`)
+  return rebuild(lines, content, eol)
+}
+
+/**
+ * Removes `host` from the mapping to `ip`. Only lines this plugin wrote are
+ * removed outright; a user's line keeps its other names.
+ */
+export function removeHost(content: string, ip: string, host: string): HostsEdit {
+  const eol = detectEol(content)
+  const lines: string[] = []
+
+  for (const line of toBodyLines(content)) {
+    const entry = parseLine(line)
+    if (!entry || entry.ip !== ip || !mentionsHost(entry, host)) {
+      lines.push(line)
+      continue
+    }
+
+    const remaining = entry.hosts.filter(candidate => candidate.toLowerCase() !== host.toLowerCase())
+    if (remaining.length === 0)
+      continue
+
+    const comment = line.match(/#.*/)?.[0] ?? ''
+    lines.push(`${entry.ip} ${remaining.join(' ')}${comment ? ` ${comment}` : ''}`)
+  }
+
+  return rebuild(lines, content, eol)
+}
+
+/** Drops every entry this plugin wrote, used to clean up after a crashed session. */
+export function removeMarkedHosts(content: string): HostsEdit {
+  const eol = detectEol(content)
+  const lines = toBodyLines(content).filter(line => !isOwned(line))
+  return rebuild(lines, content, eol)
+}
+
+/** Hosts entries this plugin owns, without the marker. */
+export function listMarkedHosts(content: string): Array<{ ip: string, host: string }> {
+  const result: Array<{ ip: string, host: string }> = []
+  for (const line of toBodyLines(content)) {
+    if (!isOwned(line))
+      continue
+    const entry = parseLine(line)
+    if (!entry)
+      continue
+    for (const host of entry.hosts)
+      result.push({ ip: entry.ip, host })
+  }
+  return result
+}

package/src/privileged/launch.ts

@@ -0,0 +1,193 @@
+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
+}
+
+/**
+ * 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`.
+ */
+export function authenticateSudo(sudoCommand = 'sudo'): { ok: boolean, message?: string } {
+  if (platform() === 'win32')
+    return { ok: true }
+
+  if (spawnSync(sudoCommand, ['-n', 'true'], { stdio: 'ignore' }).status === 0)
+    return { ok: true }
+
+  if (spawnSync(sudoCommand, ['-v'], { stdio: 'inherit' }).status === 0)
+    return { ok: true }
+
+  return {
+    ok: false,
+    message: 'administrator permission is required to edit the hosts file and bind ports 80/443',
+  }
+}
+
+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 = authenticateSudo(sudoCommand)
+    if (!auth.ok)
+      throw new Error(auth.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,
+  ]
+
+  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/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' }
+}