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

package/src/caddy/privileged.ts

@@ -0,0 +1,124 @@
+import type { PrivilegedClient } from '../privileged/client'
+import type { HelperEvent } from '../privileged/protocol'
+import { Buffer } from 'node:buffer'
+import { EventEmitter } from 'node:events'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { resolveHelperEntry } from '../privileged/entry'
+import { openHelperSession } from '../privileged/session'
+
+export interface PrivilegedEnv {
+  /** Executable started as root, resolved from the running bundle. */
+  helperEntry: string
+  helperArgs: string[]
+}
+
+/**
+ * Resolves what the helper needs to be started from the current bundle.
+ * `__dirname` exists in both the CJS and ESM outputs (tsup injects a shim).
+ */
+export function resolvePrivilegedEnv(): PrivilegedEnv {
+  const moduleDir = typeof __dirname === 'string'
+    ? __dirname
+    : dirname(fileURLToPath(import.meta.url))
+  const resolved = resolveHelperEntry({ moduleDir })
+  return { helperEntry: resolved.entry, helperArgs: resolved.args }
+}
+
+/** Re-emits helper events as the `stdout`/`stderr` events the log parsing expects. */
+export class HelperCaddyProcess extends EventEmitter {
+  readonly stdout = new EventEmitter()
+  readonly stderr = new EventEmitter()
+  private finished = false
+  private readonly unsubscribe: () => void
+
+  constructor(private readonly client: PrivilegedClient) {
+    super()
+    this.unsubscribe = client.onEvent(event => this.handleEvent(event))
+  }
+
+  private handleEvent(event: HelperEvent): void {
+    if (event.type !== 'event')
+      return
+
+    if (event.kind === 'caddy.stdout') {
+      this.stdout.emit('data', Buffer.from(event.data))
+      return
+    }
+
+    if (event.kind === 'caddy.stderr') {
+      this.stderr.emit('data', Buffer.from(event.data))
+      return
+    }
+
+    if (event.kind === 'caddy.exit') {
+      this.finished = true
+      this.emit('exit', event.code, event.signal)
+    }
+  }
+
+  /** Asks the helper to stop Caddy; the helper also stops it on disconnect. */
+  kill(): void {
+    this.unsubscribe()
+    if (this.finished)
+      return
+    this.finished = true
+    void this.client.call('caddy.stop').catch(() => {})
+  }
+}
+
+export interface OpenedPrivilegedSession {
+  client: PrivilegedClient
+  reused: boolean
+  close: () => Promise<void>
+}
+
+export interface PrivilegedSessionOptions {
+  log?: (message: string) => void
+  /** Runs the helper as the current user; tests use this to avoid sudo. */
+  direct?: boolean
+  /** Caddy binary the helper may run; fixed before the session opens. */
+  caddyBin: string
+  /** Caddyfile the helper may load. */
+  caddyConfigPath: string
+  /** Admin API socket; `ca.trust` talks to it instead of the TCP default. */
+  caddyAdminSocket?: string
+  /** Shown before the password prompt so the request is not a surprise. */
+  reason?: { target: string, https: boolean }
+}
+
+/** Where Caddy keeps its PKI, per platform. */
+export function caddyStoragePath(): string {
+  return process.platform === 'win32'
+    ? join(process.env.AppData ?? '', 'Caddy')
+    : join(process.env.HOME ?? '', 'Library/Application Support/Caddy')
+}
+
+/**
+ * Opens (or reuses) the privileged helper for this runtime directory.
+ * Only the helper runs as root: the plugin process, its caches and its
+ * `node_modules` keep the developer's identity.
+ */
+export function openPrivilegedSession(
+  runtimeDir: string,
+  options: PrivilegedSessionOptions,
+): Promise<OpenedPrivilegedSession> {
+  const env = resolvePrivilegedEnv()
+  return openHelperSession({
+    runtimeDir,
+    helperEntry: env.helperEntry,
+    helperArgs: env.helperArgs,
+    direct: options.direct,
+    // Caddy keeps its PKI under the user's home; the helper runs it as root, so
+    // it must know which tree to hand back afterwards.
+    caddyStoragePath: caddyStoragePath(),
+    // The binary and Caddyfile are fixed here: the privileged helper must never
+    // execute a path supplied over the socket.
+    caddyBin: options.caddyBin,
+    caddyConfigPath: options.caddyConfigPath,
+    caddyAdminSocket: options.caddyAdminSocket,
+    reason: options.reason,
+    log: options.log,
+  })
+}

package/src/caddy/utils.ts

@@ -1,51 +1,8 @@
-import { exec } from 'node:child_process'
-import { createServer } from 'node:net'
 import ora from 'ora'
 import { consola } from '../utils'
 
 let spinner: ora.Ora
 
-/**
- * @returns whether the port is in use
- */
-export function tryPort(port: number): Promise<boolean> {
-  return new Promise<boolean>((resolve, _reject) => {
-    try {
-      const server = createServer().listen(port)
-      server.on('listening', () => {
-        server.close()
-        resolve(false)
-      })
-      server.on('error', (err) => {
-        // @ts-expect-error err.code
-        if (err.code === 'EADDRINUSE')
-          resolve(true)
-        server.close()
-      })
-    }
-    catch {
-      resolve(true)
-    }
-  })
-}
-
-/**
- * npx free-port :port
- */
-export async function kill(port: number): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    exec(`npx @maxbo/free-port ${port} -s`, (err, stdout, _stderr) => {
-      if (err) {
-        reject(err)
-      }
-      else {
-        consola.log(stdout)
-        resolve()
-      }
-    })
-  })
-}
-
 function getNumber(number: number): string {
   if (number <= 0)
     return '0%'

package/src/index.ts

@@ -7,7 +7,9 @@ import c from 'picocolors'
 import { createUnplugin } from 'unplugin'
 import { CaddyInstant } from './caddy'
 import { hmrSseBridgeClientScript, setupHmrSseBridge } from './hmr-sse-bridge'
-import { consola, generateQrcode, getIpv4List, isAdmin, once } from './utils'
+import { isPrivilegeDenied, markPrivilegeDenied } from './privilege-state'
+import { PrivilegeDeniedError } from './privileged/launch'
+import { consola, generateQrcode, getIpv4List, once } from './utils'
 
 let config: ResolvedConfig
 
@@ -62,10 +64,15 @@ export const vitePrintUrls = once((
 ) => {
   _printUrls?.()
 
+  // Declined earlier in this process; a hot restart must not ask again.
+  if (isPrivilegeDenied())
+    return
+
   if (caddy)
     return
-  caddy = new CaddyInstant()
-  caddy.run(source, target, {
+  const instance = new CaddyInstant()
+  caddy = instance
+  instance.run(source, target, {
     base,
     ...options,
   }).then(async () => {
@@ -73,6 +80,16 @@ export const vitePrintUrls = once((
 
     consola.success(`  ${c.green('➜')}  ${c.bold('run caddy reverse proxy success')}: ${colorUrl(`${options.https ? 'https' : 'http'}://${target}${base}`)}`)
   }).catch((e) => {
+    // Declining the password is a choice, not a crash: drop the half-started
+    // instance so a later attempt can prompt again.
+    if (caddy === instance)
+      caddy = undefined as unknown as CaddyInstant
+    if (e instanceof PrivilegeDeniedError) {
+      markPrivilegeDenied()
+      consola.warn('reverse proxy skipped: administrator permission was not granted.')
+      consola.info('Restart the dev server to enable it again.')
+      return
+    }
     throw e
   })
 })
@@ -96,10 +113,6 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
       if (!enable)
         return
 
-      if (!isAdmin()) {
-        consola.warn('please run as administrator')
-        return
-      }
       if (!target) {
         consola.fail('please provide target')
         return
@@ -153,11 +166,6 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
     if (!enable)
       return
 
-    if (!isAdmin()) {
-      consola.warn('please run as administrator')
-      return
-    }
-
     if (!target) {
       consola.fail('please provide target')
       return
@@ -177,6 +185,9 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
     }
     const source = `${devServer.host}:${devServer.port}`
 
+    if (isPrivilegeDenied())
+      return
+
     if (caddy)
       return
 
@@ -204,9 +215,10 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
       options.https = false
     }
 
-    caddy = new CaddyInstant()
+    const instance = new CaddyInstant()
+    caddy = instance
 
-    caddy.run(source, target, {
+    instance.run(source, target, {
       base,
       ...options,
     }).then(() => {
@@ -216,6 +228,14 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
         consola.success(`  ${c.green('➜')}  ${c.bold('run caddy reverse proxy success')}: ${colorUrl(`${options.https ? 'https' : 'http'}://${target}${base}`)}`)
       })
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = undefined as unknown as CaddyInstant
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied()
+        consola.warn('reverse proxy skipped: administrator permission was not granted.')
+        consola.info('Restart the dev server to enable it again.')
+        return
+      }
       throw e
     })
   },
@@ -231,11 +251,6 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
     if (!enable)
       return
 
-    if (!isAdmin()) {
-      consola.warn('please run as administrator')
-      return
-    }
-
     if (!target) {
       consola.fail('please provide target')
       return
@@ -257,10 +272,11 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
 
     const source = `${devServer.host}:${devServer.port}`
 
-    if (caddy)
+    if (isPrivilegeDenied())
       return
 
-    caddy = new CaddyInstant()
+    if (caddy)
+      return
 
     let base = '/'
     const publicPath = compiler.options.output?.publicPath as unknown
@@ -272,7 +288,10 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
     if (base !== '/' && !base.endsWith('/'))
       base = `${base}/`
 
-    caddy.run(source, target, {
+    const instance = new CaddyInstant()
+    caddy = instance
+
+    instance.run(source, target, {
       base,
       ...options,
     }).then(async () => {
@@ -280,6 +299,14 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
 
       consola.success(`  ${c.green('➜')}  ${c.bold('run caddy reverse proxy success')}: ${colorUrl(`${options.https ? 'https' : 'http'}://${target}${base}`)}`)
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = undefined as unknown as CaddyInstant
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied()
+        consola.warn('reverse proxy skipped: administrator permission was not granted.')
+        consola.info('Restart the dev server to enable it again.')
+        return
+      }
       throw e
     })
   },

package/src/nuxt.ts

@@ -2,7 +2,7 @@ import type { Options } from './types'
 import process from 'node:process'
 import { defineNuxtModule } from '@nuxt/kit'
 import { vitePrintUrls } from '.'
-import { consola, isAdmin } from './utils'
+import { consola } from './utils'
 import '@nuxt/schema'
 
 export interface ModuleOptions extends Options {
@@ -26,11 +26,6 @@ export default defineNuxtModule<ModuleOptions>({
     if (!enable)
       return
 
-    if (!isAdmin()) {
-      consola.warn('please run as administrator')
-      return
-    }
-
     if (!target) {
       consola.fail('please provide target')
       return

package/src/privilege-state.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether the user dismissed the password prompt in this process.
+ *
+ * Kept in its own module so the flag outlives a hot restart. Vite rebuilds the
+ * dev server in place (`Object.assign(server, newServer)`) rather than starting
+ * a new process, so module scope is the only place that distinguishes "saved
+ * the config again" from "started the dev server again".
+ */
+let denied = false
+
+/** Records that the user declined; every entry point checks this first. */
+export function markPrivilegeDenied(): void {
+  denied = true
+}
+
+export function isPrivilegeDenied(): boolean {
+  return denied
+}
+
+/** Test hook: restores the initial state between cases. */
+export function resetPrivilegeDenied(): void {
+  denied = false
+}

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