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

package/src/index.ts

@@ -7,7 +7,7 @@ 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 { consola, generateQrcode, getIpv4List, once } from './utils'
 
 let config: ResolvedConfig
 
@@ -96,10 +96,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
@@ -123,17 +119,17 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
 
       server.printUrls = () => vitePrintUrls(options, source, target, base, _printUrls)
 
-      // Setup SSE bridge for iOS Safari WSS workaround
+      // Setup SSE bridge for macOS/iOS Safari WSS workaround
       if (options.https) {
         setupHmrSseBridge(server)
         hmrSseBridgeActive = true
-        consola.info('HMR SSE bridge enabled for iOS Safari WSS workaround')
+        consola.info('HMR SSE bridge enabled for macOS/iOS Safari WSS workaround')
       }
     },
     transformIndexHtml() {
       if (!hmrSseBridgeActive)
         return []
-      // Inject client-side script to patch WebSocket on iOS Safari
+      // Inject client-side script to patch WebSocket on macOS/iOS Safari
       return [{
         tag: 'script',
         children: hmrSseBridgeClientScript,
@@ -153,11 +149,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
@@ -231,11 +222,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

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/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()
+    },
+  }
+}

package/src/privileged/entry.ts

@@ -0,0 +1,45 @@
+import { existsSync } from 'node:fs'
+import { 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.
+ */
+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 = join(moduleDir, name)
+    if (exists(candidate))
+      return { entry: nodeBin, args: [candidate] }
+  }
+
+  const source = join(moduleDir, 'privileged-helper.ts')
+  const tsxCli = join(moduleDir, '../node_modules/tsx/dist/cli.mjs')
+  if (exists(source) && exists(tsxCli))
+    return { entry: nodeBin, args: [tsxCli, source] }
+
+  throw new Error(`privileged helper entry not found in ${moduleDir}. Build the package first.`)
+}