feat(tunnel): zero-touch tunnel enrollment — control-plane PKI, host agent, iOS, nginx isolation

Customers install one command / log in once; hardware-generated keys never leave the device; CSRs return certs + subdomain; frpc + base-app run as durable services. No .p12, no manual cert import. Implements the MVP fast-path of docs/PLAN_TUNNEL_AUTOMATION.md. Control-plane / PKI (control-plane/): - ca/x509-assembler.ts: single KMS-signed real X.509 issuance primitive (Ed25519 + P-256) - ca/csr-ec.ts: P-256 PKCS#10 proof-of-possession (verifyCsrPoPEc) + CSR-key routing - ca/frpclient-issue.ts, ca/device-issue.ts: P-256 frp-client + device leaf signers - ca/rotate.ts + api/renew.ts: real-X.509 /renew + /device/:id/renew (mTLS current cert) - registry/devices.ts: device registry + per-account cap/rate-limit - auth/session.ts: device:enroll capability token mint/verify - api/device-enroll.ts: POST /device/enroll (ownership-gated, deny-by-default) - pairing/native-redeem.ts + shared gateAndConsumePairingCode; api/provision.ts native arm - boot/native-ca.ts + main.ts: wire two P-256 CAs + issuers + routers (dev / KMS fail-fast) Contracts: relay-contracts enroll right; relay-auth SPIFFE /device/ arm + spiffeIdFor(kind) Host agent (agent/): - transport/frpcToml.ts; provision/frpcBinary.ts + untar.ts (verify-download + traversal-safe extract) - keys P-256 keygen/CSR/loadIdentity; service two-unit install + BIND_HOST loopback S-GATE - net/loopbackLiteral.ts strict guard; health/probe.ts + transport/frpSupervise.ts; cli pair --install iOS (ios/Packages/ClientTLS): SecureEnclaveKey + CertificateSigningRequest + DeviceEnrollmentClient + Keychain enroll refactor (SecKey/Security.framework end-to-end, avoids the -25300 trap) Isolation (deploy/nginx): njs/getCertSub.js SAN parser + zone-anchored map -> 403 Verified: 758 tests green (control-plane 246, agent 267, relay-auth 133, relay-contracts 85, iOS ClientTLS 27), all tsc clean; real nginx+njs docker 403/200/400; Swift CSR accepted by the real control-plane verifier; frpc extract byte-identical to `tar -xO`. Cross-validation caught + fixed 5 real defects (1 critical, 4 high). Remaining = infra (KMS, nginx deploy, VPS frps, physical iPhone) per PROGRESS_LOG runbook. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 16:11:13 +02:00
parent 31054450fc
commit e7f3bd05f0
79 changed files with 9920 additions and 385 deletions
--- a/agent/src/service/install.ts
+++ b/agent/src/service/install.ts
@@ -1,10 +1,20 @@
 /**
- * Service install dispatcher — PLAN_RELAY_AGENT T17. Detects the platform, writes the unit, and
- * loads it. REFUSES to install as root (EXPLORE §4d least privilege). All IO is injected so the
- * logic is unit-testable without touching the real system.
+ * Service install dispatcher — PLAN_RELAY_AGENT T17, re-targeted for the native tunnel
+ * (PLAN_TUNNEL_AUTOMATION B5). Detects the platform and emits TWO durable units — the base-app and
+ * the agent — then loads/enables both. REFUSES to install as root (EXPLORE §4d least privilege).
+ * All IO is injected so the logic is unit-testable without touching the real system.
+ *
+ * Two safety controls are load-bearing here:
+ *   - FIX C-host-1 (S-GATE, CRITICAL): the base-app unit MUST bind loopback. A non-loopback
+ *     `BIND_HOST` (e.g. `0.0.0.0`) is REJECTED — the throw happens before any file is written, so a
+ *     rejected install emits nothing. An absent value is normalized to `127.0.0.1`.
+ *   - FIX M-host-2service: base-app env (BIND_HOST/ALLOWED_ORIGINS/PORT/…) is routed to the
+ *     base-app unit ONLY; the agent unit (which supervises frpc) never carries it.
 */
 import type { AgentConfig } from '../config/agentConfig.js'
 import {
+  agentLabel,
+  baseAppLabel,
  buildLaunchdPlist,
  launchdLoadCommand,
  launchdPlistPath,
@@ -12,6 +22,8 @@ import {
  type ServiceEnv,
 } from './launchd.js'
 import {
+  agentUnitName,
+  baseAppUnitName,
  buildSystemdUnit,
  systemdDisableCommand,
  systemdEnableCommand,
@@ -19,15 +31,17 @@ import {
  type SystemdUnitOptions,
 } from './systemd.js'
 import { DEFAULT_ORIGIN_ZONE, mergeOrigins, subdomainOrigin } from './originConfig.js'
+import { isLoopbackHostLiteral } from '../net/loopbackLiteral.js'

 export type ServicePlatform = 'launchd' | 'systemd'

 /**
 * Per-host packaging inputs threaded to the unit writers (PLAN_NATIVE_TUNNEL S2). All optional so
- * existing callers (and relay callers) are unaffected — an empty object writes the historical unit.
+ * existing callers (and relay callers) are unaffected. `env` is the BASE-APP env (routed to the
+ * base-app unit only); `baseAppExec` overrides the base-app `ExecStart` argv.
 */
 export interface InstallOptions {
-  /** S0 env injected into the supervised process (BIND_HOST, ALLOWED_ORIGINS, PORT, …). */
+  /** Base-app env injected into the base-app unit (BIND_HOST, ALLOWED_ORIGINS, PORT, …). */
  readonly env?: ServiceEnv
  /** systemd `EnvironmentFile=` path (preferred over inline for values best kept off the unit). */
  readonly envFile?: string
@@ -35,26 +49,84 @@ export interface InstallOptions {
  readonly zone?: string
  /** Parent domain (e.g. `yaojia.wang`); with `cfg.subdomain` derives the tunnel ALLOWED_ORIGINS. */
  readonly domain?: string
+  /** Base-app process argv (default `['node','dist/server.js']`). */
+  readonly baseAppExec?: readonly string[]
 }

-/** S0 base-app env vars the install CLI bakes into the per-host unit, passed through verbatim. */
-const BASE_APP_ENV_KEYS = ['ALLOWED_ORIGINS', 'PORT', 'SHELL_PATH', 'IDLE_TTL', 'USE_TMUX'] as const
+/** S0 base-app env vars the install CLI bakes into the base-app unit, passed through verbatim. */
+const BASE_APP_ENV_KEYS = [
+  'ALLOWED_ORIGINS',
+  'PORT',
+  'SHELL_PATH',
+  'IDLE_TTL',
+  'USE_TMUX',
+  'SCROLLBACK_BYTES',
+  'MAX_PAYLOAD_BYTES',
+] as const

 /**
 * Tunnel hosts MUST bind loopback. At the relay the device-cert mTLS is the ONLY auth gate, so a
 * default `0.0.0.0` bind (`src/config.ts`) would serve an unauth'd shell on the LAN, bypassing mTLS
- * entirely (PLAN_NATIVE_TUNNEL S0/R2). `buildInstallOptions` therefore defaults `BIND_HOST` here.
+ * entirely (PLAN_NATIVE_TUNNEL S0/R2, FIX C-host-1). This is the normalized loopback default.
 */
 export const TUNNEL_DEFAULT_BIND_HOST = '127.0.0.1'

 /** Native-tunnel origin zone → `https://<subdomain>.terminal.<domain>`; overridable via TUNNEL_ZONE. */
 export const TUNNEL_ORIGIN_ZONE = 'terminal'

+/** Native-tunnel origin zone label; native installs MUST use this (FIX L-host-zone). */
+export const NATIVE_ORIGIN_ZONE = 'terminal'
+
+/** Base-app process argv when the caller does not override it. */
+const DEFAULT_BASE_APP_EXEC: readonly string[] = ['node', 'dist/server.js']
+
+/** A base-app BIND_HOST that is not loopback — the S-GATE fail-closed error (FIX C-host-1). */
+export class BindHostError extends Error {
+  constructor(value: string) {
+    super(
+      `refusing to install: BIND_HOST="${value}" is not loopback. A tunnel host MUST bind ` +
+        '127.0.0.1/::1/localhost — the device-cert mTLS at the relay is the only auth gate, so a ' +
+        '0.0.0.0 (or LAN-IP) bind would serve an unauth\'d shell on the LAN. [FIX C-host-1 S-GATE]',
+    )
+    this.name = 'BindHostError'
+  }
+}
+
+/**
+ * True iff `value` is a loopback bind address (a well-formed 127.0.0.0/8 IPv4 literal, ::1, or
+ * localhost). Delegates to the shared strict check so a suffixed hostname such as
+ * `127.0.0.1.attacker.example.com` — which Node would DNS-resolve before bind() — is REJECTED,
+ * not treated as loopback (FIX C-host-1 S-GATE).
+ */
+function isLoopbackBindHost(value: string): boolean {
+  return isLoopbackHostLiteral(value)
+}
+
+/**
+ * S-GATE (FIX C-host-1): normalize an absent/empty BIND_HOST to loopback; REJECT any non-loopback
+ * value (throws `BindHostError`). The emitted base-app unit can therefore never bind `0.0.0.0`.
+ */
+export function normalizeBindHost(value: string | undefined): string {
+  if (value === undefined || value.length === 0) return TUNNEL_DEFAULT_BIND_HOST
+  if (!isLoopbackBindHost(value)) throw new BindHostError(value)
+  return value
+}
+
+/** Assert a native-tunnel install uses the `terminal` zone (FIX L-host-zone). Throws otherwise. */
+export function assertNativeZone(zone: string | undefined): void {
+  if (zone !== NATIVE_ORIGIN_ZONE) {
+    throw new Error(
+      `native tunnel install requires zone="${NATIVE_ORIGIN_ZONE}" (got "${zone ?? '(default term)'}")` +
+        ' — the base-app origin must be https://<sub>.terminal.<domain> [FIX L-host-zone]',
+    )
+  }
+}
+
 /**
 * Resolve the per-host `InstallOptions` from the process environment (PLAN_NATIVE_TUNNEL S0/S2).
- * Sources the S0 base-app env — defaulting `BIND_HOST` to loopback so a tunnel install can never
- * emit a LAN-exposed unit — plus the tunnel-origin `domain`/`zone` used to derive ALLOWED_ORIGINS.
- * Pure/immutable: `env` is a parameter, so this is unit-testable without touching real process state.
+ * Sources the S0 base-app env — normalizing/gating `BIND_HOST` to loopback (S-GATE: throws on a
+ * non-loopback value so no install can ever emit a LAN-exposed unit) — plus the tunnel-origin
+ * `domain`/`zone` used to derive ALLOWED_ORIGINS. Pure/immutable (env is a parameter).
 */
 export function buildInstallOptions(env: NodeJS.ProcessEnv): InstallOptions {
  const passthrough = Object.fromEntries(
@@ -62,13 +134,16 @@ export function buildInstallOptions(env: NodeJS.ProcessEnv): InstallOptions {
      (entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].length > 0,
    ),
  )
-  const serviceEnv: ServiceEnv = { BIND_HOST: env.BIND_HOST || TUNNEL_DEFAULT_BIND_HOST, ...passthrough }
+  // S-GATE at env-read time: a non-loopback BIND_HOST fails closed here (before any install).
+  const serviceEnv: ServiceEnv = { BIND_HOST: normalizeBindHost(env.BIND_HOST), ...passthrough }
  const domain = env.TUNNEL_DOMAIN
  const envFile = env.AGENT_ENV_FILE
+  const baseAppEntry = env.BASE_APP_ENTRY
  return {
    env: serviceEnv,
    ...(domain ? { domain, zone: env.TUNNEL_ZONE || TUNNEL_ORIGIN_ZONE } : {}),
    ...(envFile ? { envFile } : {}),
+    ...(baseAppEntry ? { baseAppExec: ['node', baseAppEntry] } : {}),
  }
 }

@@ -96,18 +171,26 @@ export function detectPlatform(os: NodeJS.Platform): ServicePlatform | null {
 }

 /**
- * Resolve the env map injected into the unit. When a `domain` (+ `cfg.subdomain`) is supplied, the
- * tunnel origin `https://<subdomain>.<zone>.<domain>` is merged into ALLOWED_ORIGINS so the base app
- * trusts its own tunnel host — never weakening any origin the caller already provided. Immutable.
+ * Resolve the BASE-APP env injected into the base-app unit. Runs the S-GATE on `BIND_HOST` (throws
+ * `BindHostError` on a non-loopback value, before any write) and, when a `domain` (+ `cfg.subdomain`)
+ * is supplied, merges the tunnel origin `https://<subdomain>.<zone>.<domain>` into ALLOWED_ORIGINS —
+ * never weakening an origin the caller already provided. Immutable.
 */
-function resolveEnv(cfg: AgentConfig, options: InstallOptions): ServiceEnv {
+function resolveBaseAppEnv(cfg: AgentConfig, options: InstallOptions): ServiceEnv {
  const base = options.env ?? {}
-  if (!options.domain || !cfg.subdomain) return base
+  const bindHost = normalizeBindHost(base.BIND_HOST) // S-GATE — throws on non-loopback
+  const withBind: ServiceEnv = { ...base, BIND_HOST: bindHost }
+  if (!options.domain || !cfg.subdomain) return withBind
  const origin = subdomainOrigin(cfg.subdomain, options.domain, options.zone ?? DEFAULT_ORIGIN_ZONE)
-  return { ...base, ALLOWED_ORIGINS: mergeOrigins(base.ALLOWED_ORIGINS, origin) }
+  return { ...withBind, ALLOWED_ORIGINS: mergeOrigins(withBind.ALLOWED_ORIGINS, origin) }
 }

-/** Write + load the service unit for `platform`. Throws RootRefusedError if running as root. */
+/**
+ * Write + load BOTH service units for `platform`: the base-app (`node dist/server.js` + base-app
+ * env) and the agent (`<bin> run`, supervises frpc — no base-app env). Throws RootRefusedError if
+ * running as root, or BindHostError (S-GATE) BEFORE any write if the base-app BIND_HOST is not
+ * loopback (so a rejected install emits nothing).
+ */
 export async function installService(
  cfg: AgentConfig,
  platform: ServicePlatform,
@@ -115,34 +198,57 @@ export async function installService(
  options: InstallOptions = {},
 ): Promise<void> {
  if (deps.getuid() === 0) throw new RootRefusedError()
+  // Resolve (and S-GATE) the base-app env BEFORE any IO — a non-loopback BIND_HOST throws here,
+  // so nothing is ever written for a rejected install.
+  const baseAppEnv = resolveBaseAppEnv(cfg, options)
  const bin = deps.binPath()
-  const env = resolveEnv(cfg, options)
+  const baseAppExec = options.baseAppExec ?? DEFAULT_BASE_APP_EXEC
+
  if (platform === 'launchd') {
-    const path = launchdPlistPath(deps.homedir())
-    deps.writeFile(path, buildLaunchdPlist(bin, env))
-    const { cmd, args } = launchdLoadCommand(path)
-    await deps.runCommand(cmd, args)
+    const baseAppPath = launchdPlistPath(deps.homedir(), baseAppLabel())
+    deps.writeFile(baseAppPath, buildLaunchdPlist(baseAppExec, baseAppEnv, baseAppLabel()))
+    const agentPath = launchdPlistPath(deps.homedir(), agentLabel())
+    deps.writeFile(agentPath, buildLaunchdPlist([bin, 'run'], {}, agentLabel()))
+    for (const path of [baseAppPath, agentPath]) {
+      const { cmd, args } = launchdLoadCommand(path)
+      await deps.runCommand(cmd, args)
+    }
    return
  }
-  const path = systemdUnitPath(deps.homedir())
-  const systemdOptions: SystemdUnitOptions = options.envFile
-    ? { env, envFile: options.envFile }
-    : { env }
-  deps.writeFile(path, buildSystemdUnit(bin, deps.username(), systemdOptions))
-  const { cmd, args } = systemdEnableCommand()
-  await deps.runCommand(cmd, args)
+
+  const baseAppOptions: SystemdUnitOptions = options.envFile
+    ? { env: baseAppEnv, envFile: options.envFile }
+    : { env: baseAppEnv }
+  const baseAppPath = systemdUnitPath(deps.homedir(), baseAppUnitName())
+  deps.writeFile(
+    baseAppPath,
+    buildSystemdUnit(baseAppExec.join(' '), deps.username(), baseAppOptions, 'web-terminal base app (loopback)'),
+  )
+  const agentPath = systemdUnitPath(deps.homedir(), agentUnitName())
+  deps.writeFile(
+    agentPath,
+    buildSystemdUnit(`${bin} run`, deps.username(), {}, 'web-terminal host agent (frpc supervisor)'),
+  )
+  for (const unit of [baseAppUnitName(), agentUnitName()]) {
+    const { cmd, args } = systemdEnableCommand(unit)
+    await deps.runCommand(cmd, args)
+  }
 }

-/** Unload the service unit for `platform`. */
+/** Unload/disable BOTH service units for `platform` (agent first, then base-app). */
 export async function uninstallService(
  platform: ServicePlatform,
  deps: Pick<InstallDeps, 'runCommand' | 'homedir'>,
 ): Promise<void> {
  if (platform === 'launchd') {
-    const { cmd, args } = launchdUnloadCommand(launchdPlistPath(deps.homedir()))
-    await deps.runCommand(cmd, args)
+    for (const label of [agentLabel(), baseAppLabel()]) {
+      const { cmd, args } = launchdUnloadCommand(launchdPlistPath(deps.homedir(), label))
+      await deps.runCommand(cmd, args)
+    }
    return
  }
-  const { cmd, args } = systemdDisableCommand()
-  await deps.runCommand(cmd, args)
+  for (const unit of [agentUnitName(), baseAppUnitName()]) {
+    const { cmd, args } = systemdDisableCommand(unit)
+    await deps.runCommand(cmd, args)
+  }
 }
--- a/agent/src/service/launchd.ts
+++ b/agent/src/service/launchd.ts
@@ -2,23 +2,38 @@
 * macOS launchd plist writer — PLAN_RELAY_AGENT T17. The service runs as the LOGGED-IN USER, not
 * root (EXPLORE §4d least privilege); no secrets in the plist (key/cert stay in the keystore).
 *
- * PLAN_NATIVE_TUNNEL S2: the plist can now inject a caller-supplied per-host env map
+ * PLAN_NATIVE_TUNNEL S2: the plist can inject a caller-supplied per-host env map
 * (BIND_HOST, ALLOWED_ORIGINS, PORT, SHELL_PATH, IDLE_TTL, USE_TMUX, …) as a launchd
 * `<key>EnvironmentVariables</key><dict>…</dict>` block. Values are XML-escaped and keys are
 * sorted for deterministic, immutable output.
+ *
+ * PLAN_TUNNEL_AUTOMATION B5 (FIX M-host-2service): the writer is PARAMETERIZED on `label` +
+ * `programArguments`, so a native-tunnel install emits TWO distinct plists — the base-app
+ * (`node dist/server.js`, carrying the base-app env) and the agent (`<bin> run`, which supervises
+ * frpc). Base-app env is routed to the base-app plist ONLY by the caller (`install.ts`).
 */

 /** Shared env-map shape for the durable-service writers (launchd + systemd). Immutable. */
 export type ServiceEnv = Readonly<Record<string, string>>

-const LABEL = 'com.web-terminal.agent'
+/** The native-tunnel agent unit (supervises frpc). */
+const AGENT_LABEL = 'com.web-terminal.agent'
+/** The base-app unit (`node dist/server.js`, loopback-bound). */
+const BASE_APP_LABEL = 'com.web-terminal.base-app'

+export function agentLabel(): string {
+  return AGENT_LABEL
+}
+export function baseAppLabel(): string {
+  return BASE_APP_LABEL
+}
+/** Back-compat alias for the agent label. */
 export function launchdLabel(): string {
-  return LABEL
+  return AGENT_LABEL
 }

-export function launchdPlistPath(homedir: string): string {
-  return `${homedir}/Library/LaunchAgents/${LABEL}.plist`
+export function launchdPlistPath(homedir: string, label: string = AGENT_LABEL): string {
+  return `${homedir}/Library/LaunchAgents/${label}.plist`
 }

 /** Escape the five XML-significant characters so env keys/values/paths are plist-safe. */
@@ -44,24 +59,34 @@ function environmentVariablesBlock(env: ServiceEnv): readonly string[] {
  return lines
 }

+/** Build the `<key>ProgramArguments</key><array>…</array>` lines. */
+function programArgumentsBlock(programArguments: readonly string[]): readonly string[] {
+  const lines = ['  <key>ProgramArguments</key>', '  <array>']
+  for (const arg of programArguments) {
+    lines.push(`    <string>${escapeXml(arg)}</string>`)
+  }
+  lines.push('  </array>')
+  return lines
+}
+
 /**
- * Build the plist. ExecStart = `<bin> run`; RunAtLoad + KeepAlive (restart on failure). When `env`
- * is non-empty, a launchd `EnvironmentVariables` dict is injected so the supervised process
- * receives the per-host tunnel config. Pure/immutable — returns a fresh string.
+ * Build a plist for `label` running `programArguments` (e.g. `[bin, 'run']` or `[node, serverJs]`);
+ * RunAtLoad + KeepAlive (restart on failure). When `env` is non-empty, a launchd
+ * `EnvironmentVariables` dict is injected. Pure/immutable — returns a fresh string.
 */
-export function buildLaunchdPlist(binPath: string, env: ServiceEnv = {}): string {
+export function buildLaunchdPlist(
+  programArguments: readonly string[],
+  env: ServiceEnv = {},
+  label: string = AGENT_LABEL,
+): string {
  return [
    '<?xml version="1.0" encoding="UTF-8"?>',
    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
    '<plist version="1.0">',
    '<dict>',
    '  <key>Label</key>',
-    `  <string>${escapeXml(LABEL)}</string>`,
-    '  <key>ProgramArguments</key>',
-    '  <array>',
-    `    <string>${escapeXml(binPath)}</string>`,
-    '    <string>run</string>',
-    '  </array>',
+    `  <string>${escapeXml(label)}</string>`,
+    ...programArgumentsBlock(programArguments),
    '  <key>RunAtLoad</key>',
    '  <true/>',
    '  <key>KeepAlive</key>',
--- a/agent/src/service/systemd.ts
+++ b/agent/src/service/systemd.ts
@@ -2,14 +2,22 @@
 * Linux systemd unit writer — PLAN_RELAY_AGENT T17. Runs as the LOGGED-IN USER (never root,
 * EXPLORE §4d), restart-on-failure; no secrets in the unit (key/cert stay in the keystore).
 *
- * PLAN_NATIVE_TUNNEL S2: the unit can now inject the per-host tunnel env via an
- * `EnvironmentFile=` line (preferred — keeps values out of the world-readable unit) and/or
- * inline `Environment=` lines from a caller-supplied env map. Inline `Environment=` is emitted
- * after `EnvironmentFile=` so an explicit value overrides the file on conflict.
+ * PLAN_NATIVE_TUNNEL S2: the unit can inject the per-host tunnel env via an `EnvironmentFile=`
+ * line (preferred — keeps values out of the world-readable unit) and/or inline `Environment=`
+ * lines from a caller-supplied env map. Inline `Environment=` is emitted after `EnvironmentFile=`
+ * so an explicit value overrides the file on conflict.
+ *
+ * PLAN_TUNNEL_AUTOMATION B5 (FIX M-host-2service): the writer is PARAMETERIZED on the full
+ * `ExecStart` command + `Description`, so a native-tunnel install emits TWO distinct units — the
+ * base-app (`node dist/server.js`, carrying the base-app env) and the agent (`<bin> run`, which
+ * supervises frpc). Base-app env is routed to the base-app unit ONLY by the caller (`install.ts`).
 */
 import type { ServiceEnv } from './launchd.js'

-const UNIT_NAME = 'web-terminal-agent.service'
+/** The native-tunnel agent unit (supervises frpc). */
+const AGENT_UNIT = 'web-terminal-agent.service'
+/** The base-app unit (`node dist/server.js`, loopback-bound). */
+const BASE_APP_UNIT = 'web-terminal-base-app.service'

 /** DEL (0x7F) and everything below the printable ASCII range are rejected in env values. */
 const FIRST_PRINTABLE_ASCII = 0x20
@@ -22,18 +30,25 @@ export interface SystemdUnitOptions {
  readonly envFile?: string
 }

+export function agentUnitName(): string {
+  return AGENT_UNIT
+}
+export function baseAppUnitName(): string {
+  return BASE_APP_UNIT
+}
+/** Back-compat alias for the agent unit name. */
 export function systemdUnitName(): string {
-  return UNIT_NAME
+  return AGENT_UNIT
 }

-export function systemdUnitPath(homedir: string): string {
-  return `${homedir}/.config/systemd/user/${UNIT_NAME}`
+export function systemdUnitPath(homedir: string, unitName: string = AGENT_UNIT): string {
+  return `${homedir}/.config/systemd/user/${unitName}`
 }

 /**
 * True if `value` contains any control character (C0 range below 0x20, or DEL 0x7F). A raw
- * newline/CR would terminate the single `Environment=` line and let the remainder inject arbitrary
- * directives into the `[Service]` section — so such values are rejected rather than escaped.
+ * newline/CR would terminate the current line and let the remainder inject arbitrary directives into
+ * the `[Service]` section — so such values are rejected rather than escaped.
 */
 function hasControlChar(value: string): boolean {
  for (const char of value) {
@@ -44,14 +59,25 @@ function hasControlChar(value: string): boolean {
  return false
 }

-/** Quote a systemd `Environment=` value: reject control chars, then double-quote escaping `\` and `"`. */
-function quoteEnvAssignment(key: string, value: string): string {
+/**
+ * Reject ANY field interpolated into the unit that carries a control character. EVERY value written
+ * into the unit (ExecStart, User, Description, EnvironmentFile path, and each Environment key+value)
+ * flows through this one guard, so no field can smuggle a newline that starts a new `[Service]`
+ * directive. Fail loud rather than escape — these fields are never legitimately multi-line.
+ */
+function assertNoControlChar(fieldName: string, value: string): void {
  if (hasControlChar(value)) {
    throw new Error(
-      `refusing to write systemd Environment for '${key}': value contains a control character ` +
+      `refusing to write systemd unit: ${fieldName} contains a control character ` +
        '(newline/CR/etc.) that could corrupt the [Service] section',
    )
  }
+}
+
+/** Quote a systemd `Environment=` value: reject control chars (key AND value), then escape `\` and `"`. */
+function quoteEnvAssignment(key: string, value: string): string {
+  assertNoControlChar(`Environment key '${key}'`, key)
+  assertNoControlChar(`Environment value for '${key}'`, value)
  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
  return `"${key}=${escaped}"`
 }
@@ -59,7 +85,10 @@ function quoteEnvAssignment(key: string, value: string): string {
 /** Build the `EnvironmentFile=` / `Environment=` lines (empty array when neither is supplied). */
 function environmentLines(options: SystemdUnitOptions): readonly string[] {
  const lines: string[] = []
-  if (options.envFile) lines.push(`EnvironmentFile=${options.envFile}`)
+  if (options.envFile) {
+    assertNoControlChar('EnvironmentFile path', options.envFile)
+    lines.push(`EnvironmentFile=${options.envFile}`)
+  }
  const entries = Object.entries(options.env ?? {}).sort(([a], [b]) => a.localeCompare(b))
  for (const [key, value] of entries) {
    lines.push(`Environment=${quoteEnvAssignment(key, value)}`)
@@ -68,23 +97,29 @@ function environmentLines(options: SystemdUnitOptions): readonly string[] {
 }

 /**
- * Build the unit. ExecStart = `<bin> run`; Restart=on-failure; User=<user> (never root). When
- * `options.env`/`options.envFile` are supplied, the per-host tunnel env is injected into the
- * `[Service]` section. Pure/immutable — returns a fresh string.
+ * Build a unit whose `ExecStart` is `execStart` (a full command line, e.g. `<bin> run` or
+ * `node dist/server.js`); Restart=on-failure; User=<user> (never root). When `options.env`/
+ * `options.envFile` are supplied, the per-host tunnel env is injected. Pure/immutable.
 */
 export function buildSystemdUnit(
-  binPath: string,
+  execStart: string,
  user: string,
  options: SystemdUnitOptions = {},
+  description: string = 'web-terminal host agent',
 ): string {
+  // Guard every non-env field the same way env values are guarded — a newline in ExecStart/User/
+  // Description would otherwise inject a `[Service]` directive on the next line.
+  assertNoControlChar('ExecStart', execStart)
+  assertNoControlChar('User', user)
+  assertNoControlChar('Description', description)
  return [
    '[Unit]',
-    'Description=web-terminal host agent (rendezvous relay)',
+    `Description=${description}`,
    'After=network-online.target',
    '',
    '[Service]',
    'Type=simple',
-    `ExecStart=${binPath} run`,
+    `ExecStart=${execStart}`,
    'Restart=on-failure',
    'RestartSec=1',
    `User=${user}`,
@@ -96,9 +131,13 @@ export function buildSystemdUnit(
  ].join('\n')
 }

-export function systemdEnableCommand(): { cmd: string; args: readonly string[] } {
-  return { cmd: 'systemctl', args: ['--user', 'enable', '--now', UNIT_NAME] }
+export function systemdEnableCommand(
+  unitName: string = AGENT_UNIT,
+): { cmd: string; args: readonly string[] } {
+  return { cmd: 'systemctl', args: ['--user', 'enable', '--now', unitName] }
 }
-export function systemdDisableCommand(): { cmd: string; args: readonly string[] } {
-  return { cmd: 'systemctl', args: ['--user', 'disable', '--now', UNIT_NAME] }
+export function systemdDisableCommand(
+  unitName: string = AGENT_UNIT,
+): { cmd: string; args: readonly string[] } {
+  return { cmd: 'systemctl', args: ['--user', 'disable', '--now', unitName] }
 }