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/cli.ts

@@ -1,12 +1,20 @@
 /**
- * CLI entrypoint — PLAN_RELAY_AGENT T5. `pair | run | status | install | uninstall`.
- * All side effects (network/FS/tunnel) are injected via `CliDeps` so tests avoid real IO.
+ * CLI entrypoint — PLAN_RELAY_AGENT T5, extended for the native tunnel (PLAN_TUNNEL_AUTOMATION B5).
+ * `pair | run | status | install | uninstall`. All side effects (network/FS/tunnel/provision) are
+ * injected via `CliDeps` so `runCli` stays pure and offline-testable.
+ *
+ * `pair <CODE> --install` is the NATIVE zero-touch onboard: P-256 keygen (FIX H-host-2) → CSR →
+ * POST /enroll → provision the pinned frpc binary → write frpc.toml → install BOTH units (base-app
+ * + agent, base-app env routed to the base-app unit; the agent unit supervises frpc — NOT the old
+ * relay `runTunnel` rendezvous) → print `https://<sub>.terminal.<domain>`.
+ *
  * `status` prints host_id/subdomain/online ONLY — never key/cert material (INV9).
  */
 import type { AgentConfig } from './config/agentConfig.js'
 import type { AgentIdentity } from './keys/identity.js'
 import type { Keystore } from './keys/keystore.js'
-import type { InstallOptions } from './service/install.js'
+import { assertNativeZone, type InstallOptions } from './service/install.js'
+import { subdomainOrigin } from './service/originConfig.js'
 import type { EnrollResult } from 'relay-contracts'
 
 export type CliCommand = 'pair' | 'run' | 'status' | 'install' | 'uninstall'
@@ -25,12 +33,38 @@ export class CliUsageError extends Error {
   }
 }
 
+/** The non-secret enrollment result the native onboard needs (host id + assigned subdomain). */
+export interface NativeEnrollResult {
+  readonly hostId: string
+  readonly subdomain: string
+}
+
 export interface CliDeps {
   loadConfig(): AgentConfig
   openKeystore(stateDir: string): Keystore
+  /** Ed25519 identity for the legacy relay path. */
   generateIdentity(): AgentIdentity
+  /** P-256 identity for the native frp-client key (FIX H-host-2); private key never leaves the host. */
+  generateP256Identity(): AgentIdentity
+  /** Legacy relay redemption (Ed25519, E2E rendezvous). */
   redeem(cfg: AgentConfig, code: string, id: AgentIdentity, ks: Keystore): Promise<EnrollResult>
+  /** Native enroll: build the P-256 CSR, POST /enroll, store the returned cert; return ids only. */
+  enrollNative(
+    cfg: AgentConfig,
+    code: string,
+    id: AgentIdentity,
+    ks: Keystore,
+  ): Promise<NativeEnrollResult>
+  /** Download + verify + place the pinned frpc binary (B3); returns its path. */
+  provisionFrpc(cfg: AgentConfig): Promise<string>
+  /** Write the native `frpc.toml` for `subdomain` (base-app env is routed via installService). */
+  writeFrpcConfig(cfg: AgentConfig, subdomain: string): void
+  /** True iff a written native `frpc.toml` exists in `cfg.stateDir` (native-onboard signal). */
+  nativeConfigExists(cfg: AgentConfig): boolean
+  /** Legacy relay run-loop (Ed25519 WS rendezvous, T10 backoff + T9 heartbeat). */
   runTunnel(cfg: AgentConfig, ks: Keystore): Promise<number>
+  /** Native run-loop: supervise the pinned frpc child (restart-on-exit backoff + health probe). */
+  superviseFrpc(cfg: AgentConfig, ks: Keystore): Promise<number>
   /** Resolve per-host install inputs (S0 env incl. loopback BIND_HOST, tunnel origin) from env/flags. */
   resolveInstallOptions(): InstallOptions
   installService(cfg: AgentConfig, options: InstallOptions): Promise<void>
@@ -63,23 +97,60 @@ export function parseArgs(argv: readonly string[]): CliArgs {
   return args
 }
 
+/**
+ * Native zero-touch onboard for `pair <CODE> --install` (B5). Order is load-bearing: keygen(P-256)
+ * → enroll (CSR + POST /enroll) → provision frpc (so the binary exists before the agent unit
+ * starts) → write frpc.toml → install BOTH units (which start them) → print the tunnel URL.
+ */
+async function pairInstallNative(
+  code: string,
+  cfg: AgentConfig,
+  ks: Keystore,
+  deps: CliDeps,
+): Promise<number> {
+  const options = deps.resolveInstallOptions()
+  if (!options.domain) {
+    throw new CliUsageError(
+      'native install requires TUNNEL_DOMAIN — the origin is https://<sub>.terminal.<domain>',
+    )
+  }
+  assertNativeZone(options.zone) // FIX L-host-zone: native ⇒ `terminal`
+
+  const id = deps.generateP256Identity() // keygen (P-256, FIX H-host-2)
+  ks.saveIdentity(id)
+  const enroll = await deps.enrollNative(cfg, code, id, ks) // CSR → POST /enroll → store cert
+  await deps.provisionFrpc(cfg) // pinned frpc binary on disk before the service starts (B3)
+  deps.writeFrpcConfig(cfg, enroll.subdomain) // frpc.toml
+  await deps.installService(cfg, options) // base-app + agent units; base-app env routed → started
+
+  deps.print(subdomainOrigin(enroll.subdomain, options.domain, options.zone))
+  return 0
+}
+
 /** Dispatch a parsed CliArgs; returns a process exit code (0 = success). */
 export async function runCli(args: CliArgs, deps: CliDeps): Promise<number> {
   const cfg = deps.loadConfig()
   const ks = deps.openKeystore(cfg.stateDir)
   switch (args.command) {
     case 'pair': {
+      if (args.flags['install']) return pairInstallNative(args.code!, cfg, ks, deps)
+      // Legacy relay pair (Ed25519 rendezvous, no install).
       const id = ks.loadIdentity() ?? deps.generateIdentity()
       ks.saveIdentity(id)
       const enroll = await deps.redeem(cfg, args.code!, id, ks)
       deps.print(`paired: host ${enroll.hostId} subdomain ${enroll.subdomain}`)
-      if (args.flags['install']) await deps.installService(cfg, deps.resolveInstallOptions())
       return 0
     }
     case 'run': {
-      if (ks.loadIdentity() === null || ks.loadCert() === null) {
+      const id = ks.loadIdentity()
+      if (id === null || ks.loadCert() === null) {
         throw new CliUsageError('not enrolled — run `web-terminal-agent pair <CODE>` first')
       }
+      // Native onboard = a P-256 frp-client identity + a written frpc.toml. Supervise frpc as a
+      // child (restart-on-exit backoff + health probe) instead of the legacy Ed25519 relay tunnel.
+      if (id.alg === 'p256' && deps.nativeConfigExists(cfg)) {
+        return deps.superviseFrpc(cfg, ks)
+      }
       return deps.runTunnel(cfg, ks)
     }
     case 'status': {