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

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
+  }
+}

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
+}