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

package/src/privileged/session.ts

@@ -0,0 +1,169 @@
+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 * as lockfile from 'proper-lockfile'
+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
+  /** Admin API socket; used by `ca.trust` instead of the TCP default. */
+  caddyAdminSocket?: string
+  /** Shown before the password prompt so the request is not a surprise. */
+  reason?: { target: string, https: boolean }
+  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.
+ *
+ * The check-then-start sequence runs under a lock. Two projects starting at the
+ * same moment would otherwise both fail to find a socket, both spawn a helper,
+ * and the second would delete the first one's socket while it was still
+ * serving.
+ */
+export async function openHelperSession(scope: SessionScope): Promise<OpenedSession> {
+  const socketPath = sessionSocketPath(scope.runtimeDir)
+  const release = await acquireStartLock(scope.runtimeDir)
+
+  try {
+    const reused = await tryReuse(socketPath, scope)
+    if (reused)
+      return reused
+
+    return await startNew(socketPath, scope)
+  }
+  finally {
+    release()
+  }
+}
+
+async function tryReuse(socketPath: string, scope: SessionScope): Promise<OpenedSession | undefined> {
+  if (!existsSync(socketPath) && platform() !== 'win32')
+    return undefined
+
+  const token = await readToken(scope.runtimeDir)
+  if (!token)
+    return undefined
+
+  const reused = await connectExistingHelper(socketPath, token)
+  if (!reused)
+    return undefined
+
+  return {
+    client: reused,
+    reused: true,
+    close: async () => {
+      await reused.close()
+    },
+  }
+}
+
+async function startNew(socketPath: string, scope: SessionScope): Promise<OpenedSession> {
+  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,
+    caddyAdminSocket: scope.caddyAdminSocket,
+    reason: scope.reason,
+    log: scope.log,
+  })
+
+  await writeToken(scope.runtimeDir, token)
+
+  return {
+    client: started.client,
+    reused: false,
+    close: async () => {
+      await started.close()
+    },
+  }
+}
+
+/**
+ * Serialises "is a helper running? if not, start one" across processes.
+ *
+ * The lock file is separate from the socket: the socket only exists once a
+ * helper is listening, while this lock guards the window before that.
+ */
+async function acquireStartLock(runtimeDir: string): Promise<() => void> {
+  const lockPath = join(runtimeDir, 'helper.start.lock')
+  try {
+    await writeFile(lockPath, '', { flag: 'a' })
+  }
+  catch {}
+
+  const release = await lockfile.lock(lockPath, {
+    realpath: false,
+    stale: 30_000,
+    retries: { retries: 100, minTimeout: 50, maxTimeout: 200 },
+  })
+
+  return () => {
+    void release().catch(() => {})
+  }
+}
+
+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'
+}

package/src/privileged-helper.ts

@@ -0,0 +1,123 @@
+import process from 'node:process'
+import { startHelper } from './privileged/bootstrap'
+
+interface ParsedArgs {
+  socket: string
+  token: string
+  hosts?: string
+  caddyBin: string
+  caddyConfig: string
+  ownerUid?: number
+  ownerGid?: number
+  caddyStorage?: string
+  caddyAdmin?: string
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  let socket = ''
+  let token = ''
+  let hosts: string | undefined
+  let caddyBin = ''
+  let caddyConfig = ''
+  let ownerUid: number | undefined
+  let ownerGid: number | undefined
+  let caddyStorage: string | undefined
+  let caddyAdmin: string | undefined
+
+  for (let index = 0; index < argv.length; index++) {
+    const current = argv[index]
+    if (current === '--socket')
+      socket = argv[++index] ?? ''
+    else if (current === '--token')
+      token = argv[++index] ?? ''
+    else if (current === '--hosts')
+      hosts = argv[++index] ?? undefined
+    else if (current === '--caddy')
+      caddyBin = argv[++index] ?? ''
+    else if (current === '--caddy-config')
+      caddyConfig = argv[++index] ?? ''
+    else if (current === '--owner-uid')
+      ownerUid = Number(argv[++index])
+    else if (current === '--owner-gid')
+      ownerGid = Number(argv[++index])
+    else if (current === '--caddy-storage')
+      caddyStorage = argv[++index] ?? undefined
+    else if (current === '--caddy-admin')
+      caddyAdmin = argv[++index] ?? undefined
+  }
+
+  if (!socket || !token)
+    throw new Error('usage: privileged-helper --socket <path> --token <token> --caddy <bin> --caddy-config <path>')
+  if (!caddyBin || !caddyConfig)
+    throw new Error('privileged-helper requires --caddy and --caddy-config')
+
+  return {
+    socket,
+    token,
+    hosts,
+    caddyBin,
+    caddyConfig,
+    ownerUid: Number.isInteger(ownerUid) ? ownerUid : undefined,
+    ownerGid: Number.isInteger(ownerGid) ? ownerGid : undefined,
+    caddyStorage,
+    caddyAdmin,
+  }
+}
+
+/**
+ * Entry point of the process that runs with elevated privileges.
+ *
+ * It owns no product logic. The Caddy binary and Caddyfile are fixed on the
+ * command line, so requests on the socket can only say *when* to act, never
+ * what* to execute.
+ */
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2))
+
+  const helper = await startHelper({
+    socketPath: args.socket,
+    token: args.token,
+    hostsPath: args.hosts,
+    caddyBin: args.caddyBin,
+    caddyConfigPath: args.caddyConfig,
+    ownerUid: args.ownerUid,
+    ownerGid: args.ownerGid,
+    caddyStoragePath: args.caddyStorage,
+    caddyAdminSocket: args.caddyAdmin,
+    caddyEnv: {
+      HOME: process.env.HOME ?? '',
+      // Keep Caddy's storage next to the invoking user's home even though the
+      // process runs as root.
+      XDG_DATA_HOME: process.env.XDG_DATA_HOME ?? '',
+    },
+  })
+
+  // Terminal signals reach the whole foreground process group, so they also hit
+  // this helper when one of several dev servers stops. Acting on them would tear
+  // down the shared Caddy and hosts entries the remaining projects still use.
+  // The socket closing is the only signal this helper acts on.
+  //
+  // Ctrl+C, Ctrl+\, Ctrl+Z and a terminal closing all arrive this way: SIGINT,
+  // SIGQUIT, SIGTSTP and SIGHUP. Ignoring SIGTSTP also keeps the helper from
+  // being suspended, which would stall every attached project's RPC.
+  for (const signal of ['SIGINT', 'SIGQUIT', 'SIGTSTP', 'SIGHUP'] as const)
+    process.on(signal, () => {})
+
+  // SIGTERM is different: IDE and process-tree runners send it to shut the tool
+  // down for real. It still must not drop a live session, so it only tears down
+  // when no dev server is attached.
+  process.on('SIGTERM', () => {
+    if (helper.runtime.clientCount() > 0)
+      return
+    void helper.runtime.dispose().finally(() => process.exit(0))
+  })
+
+  // A closed stdout (the parent died) must not interrupt the cleanup path.
+  process.stdout.on('error', () => {})
+  process.stderr.on('error', () => {})
+}
+
+main().catch((error: Error) => {
+  process.stderr.write(`[uhrp-helper] fatal: ${error.message}\n`)
+  process.exit(1)
+})

package/src/utils.ts

@@ -1,8 +1,4 @@
-import { execSync } from 'node:child_process'
-import { chmod, readdir, stat } from 'node:fs/promises'
 import { networkInterfaces } from 'node:os'
-import path from 'node:path'
-import process from 'node:process'
 import { createConsola } from 'consola'
 import c from 'picocolors'
 import qrcode from 'qrcode-terminal'
@@ -11,15 +7,6 @@ export const consola = createConsola({
   level: 3,
 }).withTag('reverse-proxy')
 
-export async function chmodRecursive(_path: string, mode: number): Promise<void> {
-  await chmod(_path, mode)
-  if ((await stat(_path)).isDirectory()) {
-    const children = await readdir(_path)
-    for (const child of children)
-      await chmodRecursive(path.join(_path, child), mode)
-  }
-}
-
 export function once<T extends (...args: any[]) => any>(fn: T): (...args: Parameters<T>) => ReturnType<T> {
   let called = false
   return (...args: any[]) => {
@@ -30,21 +17,6 @@ export function once<T extends (...args: any[]) => any>(fn: T): (...args: Parame
   }
 }
 
-export function isAdmin(): boolean {
-  if (process.platform === 'win32') {
-    try {
-      execSync('net session', { stdio: 'ignore' })
-      return true
-    }
-    catch {
-      return false
-    }
-  }
-  else {
-    return !!(process.getuid && process.getuid() === 0)
-  }
-}
-
 export function getIpv4List(): string[] {
   const interfaces = networkInterfaces()
 

package/src/host/index.ts

@@ -1,52 +0,0 @@
-import { exec } from 'node:child_process'
-import { chmodSync } from 'node:fs'
-import process from 'node:process'
-import { promisify } from 'node:util'
-
-import hostile from 'hostile'
-import { consola } from '../utils'
-
-const _setHost = promisify(hostile.set)
-const _removeHost = promisify(hostile.remove)
-
-function getPathOfSystemHostsPath(): string {
-  return process.platform === 'win32'
-    ? `${process.env.windir || 'C:\\WINDOWS'}\\system32\\drivers\\etc\\hosts`
-    : '/etc/hosts'
-}
-
-async function syncHost(): Promise<boolean> {
-  return new Promise<boolean>((resolve, _reject) => {
-    exec(
-      process.platform === 'win32'
-        ? 'ipconfig /flushdns'
-        : 'sudo -E killall -HUP mDNSResponder',
-      (error, _stdout, _stderr) => {
-        if (error) {
-          consola.error(`exec error: ${error}`)
-          return resolve(false)
-        }
-        return resolve(true)
-      },
-    )
-  })
-}
-
-export async function addHost(ip: string, host: string): Promise<boolean> {
-  if (process.platform !== 'win32')
-    chmodSync(getPathOfSystemHostsPath(), 0o777)
-  await _setHost('127.0.0.1', 'localhost')
-  await _setHost(ip, host)
-  if (ip === 'localhost')
-    await _setHost('127.0.0.1', host)
-  return await syncHost()
-}
-
-export async function removeHost(ip: string, host: string): Promise<boolean> {
-  if (process.platform !== 'win32')
-    chmodSync(getPathOfSystemHostsPath(), 0o777)
-  await _removeHost(ip, host)
-  if (ip === 'localhost')
-    await _removeHost('127.0.0.1', host)
-  return await syncHost()
-}