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

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,174 @@
+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, rmSync } from 'node:fs'
+import { createServer } from 'node:net'
+import process from 'node:process'
+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
+  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
+  deps?: HelperDeps
+  log?: (message: string) => void
+}
+
+export interface RunningHelper {
+  runtime: HelperRuntime
+  close: () => Promise<void>
+}
+
+const HANDSHAKE_TIMEOUT_MS = 120_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`))
+  const deps = options.deps ?? createNodeHelperDeps({
+    hostsPath: options.hostsPath,
+    log,
+    caddyBin: options.caddyBin,
+    caddyConfigPath: options.caddyConfigPath,
+    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 server = createServer((socket) => {
+    let buffer = ''
+    let authenticated = false
+    connections.add(socket)
+    socket.on('close', () => connections.delete(socket))
+
+    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', () => {})
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(socketPath, () => resolve())
+  })
+
+  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())
+      })
+    },
+  }
+}
+
+/** 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,287 @@
+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[] }
+  'caddy.start': { pid?: number }
+  '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()
+    },
+  }
+}