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>

control-plane/src/main.ts

@@ -23,6 +23,7 @@ import { createSessionRegistry } from './registry/sessions.js'
 import { createSubdomainAssigner } from './subdomain/assign.js'
 import { createPairingIssuer } from './pairing/issue.js'
 import { createPairingRedeemer } from './pairing/redeem.js'
+import { createNativeHostEnroller } from './pairing/native-redeem.js'
 import { createLeafSigner, type LeafSigner } from './ca/sign.js'
 import { loadRealLeafSigner } from './ca/issue.js'
 import { createRoutingTable } from './routing/table.js'
@@ -33,6 +34,17 @@ import { createAuthorizer, type CapabilityVerifier } from './api/authz.js'
 import { buildRouter } from './api/provision.js'
 import { buildCaSigner, inProcessCaSigner, type KmsResolver, type CaSigner } from './boot/ca-wiring.js'
 import { configureCapabilityVerifyKey } from './boot/verifier.js'
+import {
+  createDeviceRegistry,
+  createMemoryDeviceStore,
+  type DeviceRegistry,
+} from './registry/devices.js'
+import { createFrpClientLeafSigner } from './ca/frpclient-issue.js'
+import { createDeviceLeafSigner, type DeviceLeafSigner } from './ca/device-issue.js'
+import { createLeafRenewer } from './ca/rotate.js'
+import { buildDeviceEnrollRouter, type SubdomainOwnershipResolver } from './api/device-enroll.js'
+import { buildRenewRouter } from './api/renew.js'
+import { buildNativeCas, DEFAULT_NATIVE_DNS_ZONE, type NativeCas, type NativeCaMaterial } from './boot/native-ca.js'
 import type { RevocationBus } from 'relay-contracts'
 
 export interface ControlPlaneOverrides {
@@ -41,6 +53,29 @@ export interface ControlPlaneOverrides {
   readonly bus?: RevocationBus & Partial<TestableRevocationBus>
   readonly kmsResolver?: KmsResolver
   readonly caChainDer?: readonly Uint8Array[]
+  /** Production mode → native-CA + renew-anchor material is fail-closed (INV9). Defaults to NODE_ENV. */
+  readonly production?: boolean
+  /** Production-loaded native-tunnel CA material (per-CA KMS ref + public cert DER). */
+  readonly nativeCaMaterial?: NativeCaMaterial
+  /** DNS zone the native-tunnel leaves are stamped under (defaults to `terminal.yaojia.wang`). */
+  readonly nativeDnsZone?: string
+}
+
+/** Native-tunnel PKI handles exposed for wiring + tests (the enroll/renew issuers behind the routes). */
+export interface NativeTunnelHandles {
+  readonly nativeCas: NativeCas
+  /** Host frp-client P-256 leaf signer (used at onboarding to mint the first leaf). */
+  readonly hostSigner: LeafSigner
+  /** Device P-256 leaf signer (shares the device store with the registry + renew path). */
+  readonly deviceSigner: DeviceLeafSigner
+  /** Device registry (ownership + cap/rate + expiry-renewal source of truth). */
+  readonly deviceRegistry: DeviceRegistry
+}
+
+export interface BuiltControlPlane {
+  readonly app: FastifyInstance
+  readonly stores: Stores
+  readonly nativeTunnel: NativeTunnelHandles
 }
 
 /**
@@ -97,7 +132,7 @@ function devKmsResolver(): KmsResolver {
 export async function buildControlPlane(
   env: ControlPlaneEnv,
   overrides: ControlPlaneOverrides = {},
-): Promise<{ app: FastifyInstance; stores: Stores }> {
+): Promise<BuiltControlPlane> {
   const stores = overrides.stores ?? createMemoryStores()
   const bus: RevocationBus = overrides.bus ?? createInMemoryRevocationBus()
   const caChainDer = overrides.caChainDer ?? []
@@ -142,7 +177,81 @@ export async function buildControlPlane(
     expectedAud: env.baseDomain,
   })
 
+  // ── Native-tunnel PKI: frp-client-CA (host) + device-CA (device), both P-256 (§1.3) ───────────────
+  // Production is fail-closed: `buildNativeCas` refuses to boot without real KMS-backed material, and
+  // the renew route MUST validate presented certs against non-empty anchors (renew.ts). DEV generates
+  // self-signed in-process P-256 CAs so leaves chain to a real, re-parseable CA.
+  const production = overrides.production ?? process.env.NODE_ENV === 'production'
+  const nativeCas = await buildNativeCas(env, {
+    production,
+    ...(overrides.kmsResolver !== undefined ? { kmsResolver: overrides.kmsResolver } : {}),
+    ...(overrides.nativeCaMaterial !== undefined ? { material: overrides.nativeCaMaterial } : {}),
+  })
+  const nativeDnsZone = overrides.nativeDnsZone ?? DEFAULT_NATIVE_DNS_ZONE
+
+  // ONE DeviceStore shared across the device registry, the device signer, and the renew path so the
+  // signer's gate + renew-expiry bump all see the device the enroll route just registered.
+  const deviceStore = createMemoryDeviceStore()
+  const deviceRegistry = createDeviceRegistry({ devices: deviceStore })
+
+  const hostSigner = createFrpClientLeafSigner({
+    hosts: stores.hosts,
+    signer: nativeCas.frpClientCa.signer,
+    issuerName: nativeCas.frpClientCa.issuerName,
+    caChainDer: nativeCas.frpClientCa.anchorsDer,
+    trustDomain: env.relayTrustDomain,
+    dnsZone: nativeDnsZone,
+  })
+  // Native (EC-P256) `/enroll` arm: pairing-gated host onboarding that mints the FIRST frp-client leaf
+  // (mirrors the Ed25519 relay redeemer, but issues a P-256 leaf under a SERVER-assigned subdomain and
+  // returns no E2E-relay content secret — L-host-hcs). Shares the frp-client `hostSigner` above so the
+  // enroll-issued leaf and the later /renew leaf are stamped by the SAME CA + subdomain.
+  const nativeEnroller = createNativeHostEnroller({
+    pairing: stores.pairing,
+    hosts,
+    subdomains,
+    hostSigner,
+    pairingMaxRedeemAttempts: env.pairingMaxRedeemAttempts,
+    audit,
+  })
+  const deviceSigner = createDeviceLeafSigner({
+    signer: nativeCas.deviceCa.signer,
+    issuer: nativeCas.deviceCa.issuerName,
+    caChainDer: nativeCas.deviceCa.anchorsDer,
+    sanBaseDomain: nativeDnsZone,
+    trustDomain: env.relayTrustDomain,
+    devices: deviceStore,
+  })
+  const renewer = createLeafRenewer({ hostSigner, deviceSigner, deviceExpiry: deviceRegistry })
+
+  // The device leaf's dNSName SAN is nginx :8470's single tenant boundary, so the enroll route must
+  // NOT trust the client-supplied subdomain: resolve who OWNS it against the host-onboarding registry
+  // (deny-by-default: unknown → null). Same source of truth as `HostStore.getBySubdomain(...)`.
+  const ownership: SubdomainOwnershipResolver = {
+    async ownerOfSubdomain(subdomain) {
+      return (await hosts.getHostBySubdomain(subdomain))?.accountId ?? null
+    },
+  }
+
+  // Fail-closed: the renew route validates presented certs against these anchors; in production they
+  // MUST be non-empty (renew.ts: "production wiring MUST supply them"). Refuse to boot otherwise.
+  if (production && (nativeCas.frpClientCa.anchorsDer.length === 0 || nativeCas.deviceCa.anchorsDer.length === 0)) {
+    throw new Error('native-tunnel renew anchors must be non-empty in production (fail-closed) — refusing to boot')
+  }
+
   const app = Fastify({ logger: false })
-  await app.register(buildRouter({ authorizer, accounts, hosts, pairingIssuer, redeemer, deprovisioner }))
-  return { app, stores }
+  await app.register(buildRouter({ authorizer, accounts, hosts, pairingIssuer, redeemer, deprovisioner, nativeEnroller }))
+  // Device enrollment is bearer-gated by the SAME capability verifier seam the admin API uses.
+  await app.register(buildDeviceEnrollRouter({ verifier, devices: deviceRegistry, signer: deviceSigner, ownership }))
+  // Leaf renewal is mTLS-authenticated (current client cert) — anchors chain-validate the presented cert.
+  await app.register(
+    buildRenewRouter({
+      hosts,
+      devices: deviceRegistry,
+      renewer,
+      hostCaAnchorsDer: nativeCas.frpClientCa.anchorsDer,
+      deviceCaAnchorsDer: nativeCas.deviceCa.anchorsDer,
+    }),
+  )
+  return { app, stores, nativeTunnel: { nativeCas, hostSigner, deviceSigner, deviceRegistry } }
 }