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

package/src/privileged/bootstrap.ts

@@ -0,0 +1,289 @@
+import type { Socket } from 'node:net'
+import type { ClientHandshake } from './protocol'
+import type { HelperDeps, HelperRuntime } from './server'
+import { Buffer } from 'node:buffer'
+import { chmodSync, chownSync, existsSync, readFileSync, rmSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { checkPrivilegedPath, describeRejection } from './path-guard'
+import { attachSocket, createHelperRuntime, createNodeHelperDeps } from './server'
+
+export interface HelperBootstrapOptions {
+  socketPath: string
+  token: string
+  hostsPath?: string
+  /** Caddy binary; fixed here so the client never names an executable. */
+  caddyBin: string
+  /** Caddyfile to load; fixed for the same reason. */
+  caddyConfigPath: string
+  /** Admin API socket; used by `ca.trust` instead of the TCP default. */
+  caddyAdminSocket?: string
+  caddyCwd?: string
+  caddyEnv?: Record<string, string>
+  /**
+   * Owner of the socket file. The helper runs as root while its client runs as
+   * the developer, so the socket must be handed back or the client cannot
+   * connect to it.
+   */
+  ownerUid?: number
+  ownerGid?: number
+  /** Caddy storage directory, handed back to the owner when Caddy stops. */
+  caddyStoragePath?: string
+  /**
+   * How long the helper lingers with no clients before exiting.
+   *
+   * Kept short so a helper nobody is using does not stay on the machine as an
+   * idle root process. Within the same terminal a restart usually happens
+   * sooner than this and still reuses the running helper.
+   */
+  idleTimeoutMs?: number
+  /**
+   * Whether the idle timer may end this process.
+   *
+   * True for the real helper, which owns its process. False when `startHelper`
+   * is called in-process (tests): exiting there would take the caller down
+   * with it.
+   */
+  exitOnIdle?: boolean
+  deps?: HelperDeps
+  log?: (message: string) => void
+}
+
+export interface RunningHelper {
+  runtime: HelperRuntime
+  close: () => Promise<void>
+}
+
+const HANDSHAKE_TIMEOUT_MS = 120_000
+
+/** Default idle lifetime after the last client leaves. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 30_000
+
+/**
+ * Runs the privileged side of the plugin: listens on a local socket, accepts
+ * only a client presenting the shared token, then serves until that client
+ * disconnects. Losing the client is the cleanup trigger, so a crashed or
+ * `SIGKILL`ed plugin still leaves hosts and Caddy restored.
+ */
+export async function startHelper(options: HelperBootstrapOptions): Promise<RunningHelper> {
+  const { socketPath, token } = options
+  const log = options.log ?? ((message: string) => process.stdout.write(`[uhrp-helper] ${message}\n`))
+
+  // The binary and the config travel in as arguments from a process running as
+  // the developer. Refuse them when they can be rewritten by someone else:
+  // running as root, a swapped binary or Caddyfile is a local privilege gain.
+  for (const check of [
+    checkPrivilegedPath(options.caddyBin, { label: 'Caddy binary', ownerUid: options.ownerUid }),
+    checkPrivilegedPath(options.caddyConfigPath, { label: 'Caddyfile', ownerUid: options.ownerUid }),
+  ]) {
+    if (check) {
+      log(describeRejection(check))
+      throw new Error(describeRejection(check))
+    }
+  }
+  const deps = options.deps ?? createNodeHelperDeps({
+    hostsPath: options.hostsPath,
+    log,
+    caddyBin: options.caddyBin,
+    caddyConfigPath: options.caddyConfigPath,
+    caddyAdminSocket: options.caddyAdminSocket,
+    caddyCwd: options.caddyCwd,
+    caddyEnv: options.caddyEnv,
+    caddyStoragePath: options.caddyStoragePath,
+    storageOwner: typeof options.ownerUid === 'number'
+      ? { uid: options.ownerUid, gid: options.ownerGid ?? options.ownerUid }
+      : undefined,
+  })
+  const runtime = createHelperRuntime(deps)
+
+  // A previous session that was killed cannot have cleaned up its entries; do
+  // it now, before any client attaches.
+  await runtime.sweepStaleEntries().catch(() => {})
+
+  try {
+    rmSync(socketPath, { force: true })
+  }
+  catch {}
+
+  const connections = new Set<Socket>()
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
+  // The real helper is a process of its own and may end itself. When this runs
+  // inside a host process (tests), only the socket is released.
+  const exitOnIdle = options.exitOnIdle ?? true
+  let idleTimer: ReturnType<typeof setTimeout> | undefined
+
+  const stopIdleTimer = (): void => {
+    if (idleTimer) {
+      clearTimeout(idleTimer)
+      idleTimer = undefined
+    }
+  }
+
+  const server = createServer((socket) => {
+    let buffer = ''
+    let authenticated = false
+    stopIdleTimer()
+    connections.add(socket)
+    socket.on('close', () => {
+      connections.delete(socket)
+      if (connections.size === 0)
+        scheduleIdleExit()
+    })
+
+    const timer = setTimeout(() => {
+      if (!authenticated)
+        socket.destroy()
+    }, HANDSHAKE_TIMEOUT_MS)
+    timer.unref?.()
+
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString('utf8')
+      const index = buffer.indexOf('\n')
+      if (index < 0)
+        return
+
+      const line = buffer.slice(0, index)
+      const rest = buffer.slice(index + 1)
+
+      let parsed: Partial<ClientHandshake>
+      try {
+        parsed = JSON.parse(line)
+      }
+      catch {
+        socket.destroy()
+        return
+      }
+
+      if (parsed.type !== 'handshake' || typeof parsed.token !== 'string') {
+        socket.destroy()
+        return
+      }
+
+      clearTimeout(timer)
+      socket.removeListener('data', onData)
+
+      if (parsed.token !== token) {
+        socket.end(`${JSON.stringify({ type: 'handshake', ok: false, reason: 'invalid token' })}\n`)
+        return
+      }
+
+      authenticated = true
+      socket.write(`${JSON.stringify({ type: 'handshake', ok: true, pid: process.pid })}\n`)
+      attachSocket(socket, runtime, log)
+
+      // Requests pipelined behind the handshake belong to the attached client.
+      if (rest.trim() !== '')
+        socket.emit('data', Buffer.from(rest))
+    }
+
+    socket.on('data', onData)
+    socket.on('error', () => {})
+  })
+
+  /**
+   * Exits once nobody needs the helper.
+   *
+   * Without this, every dev server that ever ran leaves a root process behind.
+   * The socket and token are removed too, but only while they still carry this
+   * process's identity: a newer helper may already own them.
+   */
+  function scheduleIdleExit(): void {
+    if (idleTimer || connections.size > 0)
+      return
+
+    idleTimer = setTimeout(() => {
+      idleTimer = undefined
+      if (connections.size > 0)
+        return
+
+      log('no clients left; shutting down')
+      removeOwnSocket(socketPath, token)
+
+      if (!exitOnIdle) {
+        server.close()
+        return
+      }
+
+      server.close(() => process.exit(0))
+      // A listener with no clients closes synchronously, but keep a backstop so
+      // the process cannot linger if a close callback never arrives.
+      setTimeout(() => process.exit(0), 1000).unref?.()
+    }, idleTimeoutMs)
+    idleTimer.unref?.()
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(socketPath, () => resolve())
+  })
+
+  // A helper nobody ever connects to is as useless as one whose clients left:
+  // start the timer now so a failed handshake does not strand it.
+  scheduleIdleExit()
+
+  try {
+    // The client is not root: hand the socket back to the developer and keep it
+    // private to them. Without the chown, `connect()` fails with EACCES and the
+    // client only sees a silent retry loop.
+    if (typeof options.ownerUid === 'number') {
+      chownSync(socketPath, options.ownerUid, options.ownerGid ?? options.ownerUid)
+      chmodSync(socketPath, 0o600)
+    }
+    else {
+      chmodSync(socketPath, 0o600)
+    }
+  }
+  catch (error) {
+    log(`could not set socket ownership: ${(error as Error).message}`)
+  }
+
+  return {
+    runtime,
+    async close() {
+      // Closing the listener alone would wait for clients to hang up first;
+      // shutdown has to drop the open connections as well.
+      for (const socket of connections)
+        socket.destroy()
+      connections.clear()
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve())
+      })
+    },
+  }
+}
+
+/**
+ * Removes this helper's socket and token, but only if they are still its own.
+ *
+ * A newer helper may have taken both over; deleting them then would break a
+ * session this process never served.
+ */
+function removeOwnSocket(socketPath: string, token: string): void {
+  if (process.platform === 'win32')
+    return
+
+  try {
+    const tokensDir = dirname(socketPath)
+    const tokenFile = join(tokensDir, 'helper.token')
+    const current = existsSync(tokenFile) ? readFileSync(tokenFile, 'utf8').trim() : undefined
+    if (current === token)
+      rmSync(tokenFile, { force: true })
+  }
+  catch {}
+
+  try {
+    rmSync(socketPath, { force: true })
+  }
+  catch {}
+}
+
+/** Sockets left behind by a killed helper cannot be reused; remove them first. */
+export function removeStaleSocket(socketPath: string): void {
+  if (process.platform === 'win32')
+    return
+  try {
+    rmSync(socketPath, { force: true })
+  }
+  catch {}
+}

package/src/privileged/client.ts

@@ -0,0 +1,288 @@
+import type { Buffer } from 'node:buffer'
+import type { Socket } from 'node:net'
+import type {
+  ClientHandshake,
+  HelperEvent,
+  HelperMessage,
+  HelperRequest,
+  RpcId,
+  ServerHandshake,
+} from './protocol'
+import { connect } from 'node:net'
+import process from 'node:process'
+import { decodeMessage, serializeMessage, splitLines } from './protocol'
+
+/**
+ * Environment variables the privileged helper needs so Caddy behaves like the
+ * user's own process (PKI location, proxy settings) without `sudo -E`.
+ */
+export const FORWARDED_ENV_KEYS = [
+  'HOME',
+  'USER',
+  'LOGNAME',
+  'TMPDIR',
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'http_proxy',
+  'https_proxy',
+  'NO_PROXY',
+  'no_proxy',
+] as const
+
+export function collectForwardedEnv(source: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const key of FORWARDED_ENV_KEYS) {
+    const value = source[key]
+    if (typeof value === 'string' && value !== '')
+      result[key] = value
+  }
+  return result
+}
+
+export interface HelperResults {
+  'ping': { pid: number }
+  'hosts.add': void
+  'hosts.remove': void
+  'port.free': { killed: number[] }
+  /** `started: false` means Caddy was already running and was reused. */
+  'caddy.start': { pid?: number, started?: boolean }
+  'caddy.stop': void
+  'ca.trust': { trusted: boolean, output: string }
+}
+
+export class HelperConnectionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'HelperConnectionError'
+  }
+}
+
+export interface PrivilegedClient {
+  readonly connected: boolean
+  call: <M extends keyof HelperResults>(method: M, ...params: HelperParams<M>) => Promise<HelperResults[M]>
+  onEvent: (listener: (event: HelperEvent) => void) => () => void
+  close: () => Promise<void>
+}
+
+type HelperParams<M extends keyof HelperResults>
+  = M extends 'hosts.add' | 'hosts.remove' ? [params: { ip: string, host: string }]
+    : M extends 'port.free' ? [params: { port: number }]
+      : []
+
+interface PendingCall {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export interface ConnectOptions {
+  socketPath: string
+  token: string
+  /** Total time to wait for the helper to accept the connection. */
+  timeoutMs?: number
+  retryIntervalMs?: number
+  callTimeoutMs?: number
+}
+
+function openSocket(socketPath: string): Promise<Socket> {
+  return new Promise<Socket>((resolve, reject) => {
+    const socket = connect(socketPath)
+
+    function onConnect(): void {
+      socket.removeListener('error', onError)
+      resolve(socket)
+    }
+
+    function onError(error: Error): void {
+      socket.removeListener('connect', onConnect)
+      reject(error)
+    }
+
+    socket.once('error', onError)
+    socket.once('connect', onConnect)
+  })
+}
+
+/**
+ * Connects to an already-running helper and performs the token handshake.
+ * Retries because the helper may still be starting while sudo asks for a password.
+ */
+export async function connectClient(options: ConnectOptions): Promise<PrivilegedClient> {
+  const {
+    socketPath,
+    token,
+    timeoutMs = 120_000,
+    retryIntervalMs = 100,
+    callTimeoutMs = 30_000,
+  } = options
+
+  const deadline = Date.now() + timeoutMs
+  let lastError: Error | undefined
+
+  while (Date.now() < deadline) {
+    try {
+      return await handshake(socketPath, token, callTimeoutMs)
+    }
+    catch (error) {
+      lastError = error as Error
+
+      // A permission or protocol error will not resolve by waiting, and
+      // retrying hides the real cause behind a silent hang.
+      const code = (lastError as NodeJS.ErrnoException).code
+      if (code === 'EACCES' || lastError instanceof HelperConnectionError)
+        throw lastError
+
+      await new Promise(resolve => setTimeout(resolve, retryIntervalMs))
+    }
+  }
+
+  throw new HelperConnectionError(
+    `privileged helper is not reachable at ${socketPath}: ${lastError?.message ?? 'timed out'}`,
+  )
+}
+
+function handshake(socketPath: string, token: string, callTimeoutMs: number): Promise<PrivilegedClient> {
+  return new Promise<PrivilegedClient>((resolve, reject) => {
+    void openSocket(socketPath).then((socket) => {
+      let buffer = ''
+      let settled = false
+
+      const fail = (error: Error): void => {
+        if (settled)
+          return
+        settled = true
+        socket.destroy()
+        reject(error)
+      }
+
+      const onData = (chunk: Buffer): void => {
+        if (settled)
+          return
+
+        const split = splitLines(buffer, chunk.toString('utf8'))
+        buffer = split.rest
+        const line = split.lines[0]
+        if (line === undefined)
+          return
+
+        let hello: ServerHandshake
+        try {
+          hello = JSON.parse(line) as ServerHandshake
+        }
+        catch (error) {
+          return fail(new HelperConnectionError(`invalid handshake reply: ${(error as Error).message}`))
+        }
+
+        if (hello.type !== 'handshake')
+          return fail(new HelperConnectionError('helper did not answer the handshake'))
+
+        if (!hello.ok)
+          return fail(new HelperConnectionError(hello.reason ?? 'helper rejected the handshake'))
+
+        settled = true
+        socket.removeListener('data', onData)
+        socket.removeListener('error', onError)
+        const remaining = split.lines.slice(1)
+        resolve(createClient(socket, [split.rest, ...remaining].filter(Boolean).join('\n'), callTimeoutMs))
+      }
+
+      function onError(error: Error): void {
+        fail(error)
+      }
+
+      socket.on('data', onData)
+      socket.on('error', onError)
+
+      const greeting: ClientHandshake = { type: 'handshake', token }
+      socket.write(serializeMessage(greeting))
+    }, reject)
+  })
+}
+
+function createClient(socket: Socket, initialBuffer: string, callTimeoutMs: number): PrivilegedClient {
+  let buffer = initialBuffer
+  let connected = true
+  let nextId: RpcId = 1
+
+  const pending = new Map<RpcId, PendingCall>()
+  const listeners = new Set<(event: HelperEvent) => void>()
+
+  socket.on('data', (chunk: Buffer) => {
+    const split = splitLines(buffer, chunk.toString('utf8'))
+    buffer = split.rest
+
+    for (const line of split.lines) {
+      const decoded = decodeMessage(line)
+      if (!decoded.ok)
+        continue
+
+      const message: HelperMessage = decoded.message
+      if (!('id' in message)) {
+        for (const listener of listeners)
+          listener(message)
+        continue
+      }
+
+      const entry = pending.get(message.id)
+      if (!entry)
+        continue
+
+      pending.delete(message.id)
+      clearTimeout(entry.timer)
+
+      if (message.ok)
+        entry.resolve(message.result)
+      else
+        entry.reject(new Error(message.error.message))
+    }
+  })
+
+  const disconnect = (): void => {
+    if (!connected)
+      return
+    connected = false
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer)
+      pending.delete(id)
+      entry.reject(new HelperConnectionError('privileged helper connection closed'))
+    }
+  }
+
+  socket.on('close', disconnect)
+  socket.on('error', disconnect)
+
+  function call(method: keyof HelperResults, params?: unknown): Promise<unknown> {
+    if (!connected)
+      return Promise.reject(new HelperConnectionError('privileged helper is not connected'))
+
+    const id = nextId++
+    const request = { id, method, params } as unknown as HelperRequest
+
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id)
+        reject(new HelperConnectionError(`privileged helper did not answer "${method}" in time`))
+      }, callTimeoutMs)
+
+      pending.set(id, { resolve, reject, timer })
+      socket.write(serializeMessage(request))
+    })
+  }
+
+  return {
+    get connected() {
+      return connected
+    },
+    call: call as PrivilegedClient['call'],
+    onEvent(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    async close() {
+      disconnect()
+      socket.destroy()
+    },
+  }
+}

package/src/privileged/entry.ts

@@ -0,0 +1,73 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+export interface HelperEntry {
+  /**
+   * Executable started through sudo. This is the node runtime, so the caller
+   * only has to append `args` and the helper's own flags.
+   */
+  entry: string
+  /** Script (and loader) arguments that follow the runtime. */
+  args: string[]
+}
+
+export interface ResolveHelperEntryOptions {
+  /** Directory of the running bundle: `dist` in published builds, `src` from source. */
+  moduleDir: string
+  /** Node executable used to run a compiled helper. */
+  nodeBin?: string
+  exists?: (path: string) => boolean
+}
+
+/**
+ * Locates the helper entry next to the running module.
+ *
+ * Published builds ship a compiled `privileged-helper.js` and start it with
+ * node; running from the repository uses `tsx` so the TypeScript source works
+ * without a build step.
+ *
+ * The running module sits in a subdirectory (`src/caddy`, `src/privileged`),
+ * while the helper lives one level up in `src`, so both lookups walk up instead
+ * of assuming a fixed depth.
+ */
+export function resolveHelperEntry(options: ResolveHelperEntryOptions): HelperEntry {
+  const { moduleDir, nodeBin = process.execPath, exists = existsSync } = options
+
+  for (const name of ['privileged-helper.js', 'privileged-helper.cjs', 'privileged-helper.mjs']) {
+    const candidate = findUp(moduleDir, name, exists)
+    if (candidate)
+      return { entry: nodeBin, args: [candidate] }
+  }
+
+  const source = findUp(moduleDir, 'privileged-helper.ts', exists)
+  const tsxCli = findUp(moduleDir, 'node_modules/tsx/dist/cli.mjs', exists)
+  if (source && tsxCli)
+    return { entry: nodeBin, args: [tsxCli, source] }
+
+  throw new Error(`privileged helper entry not found in ${moduleDir}. Build the package first.`)
+}
+
+/**
+ * Walks up from `from` looking for a relative path.
+ *
+ * Stops at the filesystem root so a helper outside the project is never picked
+ * up by accident.
+ */
+function findUp(
+  from: string,
+  relative: string,
+  exists: (path: string) => boolean,
+): string | undefined {
+  let current = from
+  while (true) {
+    const candidate = join(current, relative)
+    if (exists(candidate))
+      return candidate
+
+    const parent = dirname(current)
+    if (parent === current)
+      return undefined
+    current = parent
+  }
+}