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>

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