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>

relay-auth/src/agent/spiffe.ts

@@ -1,10 +1,14 @@
 /**
- * T9 · SPIFFE-ID scheme for per-host agent identity (INV4/INV14).
- * Form: `spiffe://relay.<domain>/account/<accountId>/host/<hostId>`.
+ * T9 · SPIFFE-ID scheme for per-host / per-device agent identity (INV4/INV14).
+ * Forms: `spiffe://relay.<domain>/account/<accountId>/host/<hostId>` (frp control channel) and
+ * `.../account/<accountId>/device/<deviceId>` (device data path, FIX H-cp-2 / H-native-6).
  */
 import type { SpiffeId } from '../types.js'
 import { SpiffeIdSchema } from '../types.js'
 
+/** Which identity arm a SPIFFE-ID names: a host agent or an end-user device. */
+export type SpiffeKind = 'host' | 'device'
+
 export class SpiffeError extends Error {
   constructor(message: string) {
     super(message)
@@ -18,21 +22,30 @@ export function trustDomain(env: NodeJS.ProcessEnv = process.env): string {
   return d !== undefined && d.length > 0 ? d : 'example.com'
 }
 
-export function spiffeIdFor(accountId: string, hostId: string, domain = trustDomain()): SpiffeId {
-  if (accountId.length === 0 || hostId.length === 0) {
-    throw new SpiffeError('accountId and hostId are required')
+/**
+ * Build a SPIFFE-ID. The optional 4th `kind` param defaults to `'host'`, so existing 3-arg
+ * callers (e.g. control-plane `ca/issue.ts`) are UNCHANGED. Pass `'device'` for device leaves.
+ */
+export function spiffeIdFor(
+  accountId: string,
+  id: string,
+  domain = trustDomain(),
+  kind: SpiffeKind = 'host',
+): SpiffeId {
+  if (accountId.length === 0 || id.length === 0) {
+    throw new SpiffeError('accountId and id are required')
   }
-  const id = `spiffe://relay.${domain}/account/${accountId}/host/${hostId}`
-  return SpiffeIdSchema.parse(id)
+  const uri = `spiffe://relay.${domain}/account/${accountId}/${kind}/${id}`
+  return SpiffeIdSchema.parse(uri)
 }
 
 const PARSE_RE =
-  /^spiffe:\/\/relay\.[a-z0-9.-]+\/account\/([A-Za-z0-9_-]+)\/host\/([A-Za-z0-9_-]+)$/
+  /^spiffe:\/\/relay\.[a-z0-9.-]+\/account\/([A-Za-z0-9_-]+)\/(host|device)\/([A-Za-z0-9_-]+)$/
 
-export function parseSpiffeId(uri: SpiffeId): { accountId: string; hostId: string } {
+export function parseSpiffeId(uri: SpiffeId): { accountId: string; id: string; kind: SpiffeKind } {
   const parsed = SpiffeIdSchema.safeParse(uri) // rejects path-traversal / wildcard / malformed
   if (!parsed.success) throw new SpiffeError('invalid SPIFFE-ID (malformed / traversal / wildcard)')
   const m = PARSE_RE.exec(uri)
   if (m === null) throw new SpiffeError('unparseable SPIFFE-ID')
-  return { accountId: m[1]!, hostId: m[2]! }
+  return { accountId: m[1]!, kind: m[2]! as SpiffeKind, id: m[3]! }
 }

relay-auth/src/agent/verify-mtls.ts

@@ -102,17 +102,20 @@ export async function verifyAgentCert(
   if (now > cert.notAfter) return { ok: false, reason: 'expired' }
   if (cert.spiffeUri === null) return { ok: false, reason: 'no_spiffe_san' }
 
-  let ids: { accountId: string; hostId: string }
+  let ids: ReturnType<typeof parseSpiffeId>
   try {
     ids = parseSpiffeId(cert.spiffeUri)
   } catch {
     return { ok: false, reason: 'bad_spiffe_id' }
   }
+  // Host channel is host-only. A /device/ cert must never be accepted here (its enforcement
+  // gate is nginx :8470), so an id that collides with an enrolled hostId can't cross tenants.
+  if (ids.kind !== 'host') return { ok: false, reason: 'not_host_cert' }
 
-  const host = await hosts.getById(ids.hostId)
+  const host = await hosts.getById(ids.id)
   if (host === null) return { ok: false, reason: 'host_not_enrolled' } // INV4: not in registry
   if (host.accountId !== ids.accountId) return { ok: false, reason: 'spiffe_account_mismatch' }
   if (host.status === 'revoked') return { ok: false, reason: 'host_revoked' }
 
-  return { ok: true, hostId: ids.hostId, accountId: ids.accountId }
+  return { ok: true, hostId: ids.id, accountId: ids.accountId }
 }

relay-auth/src/index.ts

@@ -76,6 +76,7 @@ export {
 
 // T9 mTLS / SPIFFE
 export { spiffeIdFor, parseSpiffeId, trustDomain, SpiffeError } from './agent/spiffe.js'
+export type { SpiffeKind } from './agent/spiffe.js'
 export {
   verifyAgentCert,
   defaultParseX509,

relay-auth/src/types.ts

@@ -97,7 +97,7 @@ export interface AuditEvent {
   readonly remoteAddrHash: string
 }
 
-export type SpiffeId = string // 'spiffe://relay.<domain>/account/<accountId>/host/<hostId>'
+export type SpiffeId = string // 'spiffe://relay.<domain>/account/<accountId>/(host|device)/<id>'
 
 export interface RateLimitPolicy {
   readonly connectPerMin: number
@@ -227,11 +227,13 @@ export const RateLimitPolicySchema = z
   .strict()
 
 /**
- * SPIFFE-ID validator: accepts the `spiffe://relay.<domain>/account/<a>/host/<h>` form and
- * REJECTS path-traversal (`..`) or wildcard (`*`). Segment chars are restricted (no `/`).
+ * SPIFFE-ID validator: accepts BOTH the host arm `spiffe://relay.<domain>/account/<a>/host/<h>`
+ * and the device arm `.../account/<a>/device/<d>` (FIX H-cp-2 / H-native-6, added in lockstep
+ * with the control-plane device issuer). REJECTS path-traversal (`..`) or wildcard (`*`); the
+ * kind segment is exactly `host` or `device`. Segment chars are restricted (no `/`).
  */
 const SPIFFE_ID_RE =
-  /^spiffe:\/\/relay\.[a-z0-9.-]+\/account\/[A-Za-z0-9_-]+\/host\/[A-Za-z0-9_-]+$/
+  /^spiffe:\/\/relay\.[a-z0-9.-]+\/account\/[A-Za-z0-9_-]+\/(?:host|device)\/[A-Za-z0-9_-]+$/
 export const SpiffeIdSchema = z
   .string()
   .regex(SPIFFE_ID_RE, 'invalid SPIFFE-ID form')

relay-auth/test/capability.test.ts

@@ -59,6 +59,25 @@ describe('capability token (§4.3)', () => {
     expect(tok.sub).toBe('acct-A')
   })
 
+  it('issues and verifies the new enroll right — issue.ts consumes it via CapabilityRightSchema (FIX C-native-1)', async () => {
+    const cnfJkt = await jwkThumbprint((await makeEphemeral()).publicRaw)
+    const raw = await issueCapabilityToken(
+      {
+        principal: principal('acct-A'),
+        aud: AUD,
+        host: uuid(),
+        rights: ['enroll'],
+        ttlSeconds: 45,
+        cnfJkt,
+      },
+      signingKey,
+      NOW,
+    )
+    const tok = await verifyCapabilityToken(raw, AUD, NOW + 1)
+    expect(tok.rights).toEqual(['enroll'])
+    expect(hasRight(tok, 'enroll')).toBe(true)
+  })
+
   it('rejects an expired token', async () => {
     const raw = await issueFor(signingKey, { ttl: 30 })
     await expect(verifyCapabilityToken(raw, AUD, NOW + 31)).rejects.toMatchObject({ reason: 'expired' })

relay-auth/test/mtls.test.ts

@@ -26,7 +26,7 @@ describe('SPIFFE-ID scheme (T9)', () => {
   it('formats and round-trips account/host', () => {
     const id = spiffeIdFor('acct-A', 'host-1', DOMAIN)
     expect(id).toBe('spiffe://relay.example.com/account/acct-A/host/host-1')
-    expect(parseSpiffeId(id)).toEqual({ accountId: 'acct-A', hostId: 'host-1' })
+    expect(parseSpiffeId(id)).toEqual({ accountId: 'acct-A', id: 'host-1', kind: 'host' })
   })
 
   it('rejects a path-traversal / wildcard SPIFFE-ID', () => {
@@ -73,6 +73,15 @@ describe('agent cert verification (INV4/INV14)', () => {
     const r = await verifyAgentCert('leaf', 'ca', NOW, hosts, certParser(cert))
     expect(r).toMatchObject({ ok: false, reason: 'chain_invalid' })
   })
+
+  it('refuses a device-kind cert on the host channel even if the id collides with an enrolled host (kind guard)', async () => {
+    // Trust-broadening guard: a /device/ SAN whose id happens to equal an enrolled hostId
+    // (same account) must NOT be accepted by the host-agent verifier. The host channel is
+    // host-only; device certs are enforced at nginx :8470, not here.
+    const cert = { ...validCert, spiffeUri: spiffeIdFor('acct-A', 'host-1', DOMAIN, 'device') }
+    const r = await verifyAgentCert('leaf', 'ca', NOW, hosts, certParser(cert))
+    expect(r).toMatchObject({ ok: false, reason: 'not_host_cert' })
+  })
 })
 
 describe('defaultParseX509 real X.509 path validation (INV4/INV14)', () => {

relay-auth/test/spiffe.test.ts

@@ -0,0 +1,81 @@
+/**
+ * A2a · SPIFFE-ID device-arm contract edit (FIX H-cp-2 / H-native-6).
+ * The host arm MUST keep working; a new /device/ arm is added in lockstep with the
+ * control-plane device issuer. The cross-track test pins issuer↔verifier so the two
+ * cannot drift (a device SAN the CP stamps must parse under relay-auth's parser).
+ */
+import { describe, it, expect } from 'vitest'
+import { spiffeIdFor, parseSpiffeId, SpiffeError } from '../src/agent/spiffe.js'
+import { SpiffeIdSchema } from '../src/types.js'
+
+const DOMAIN = 'example.com'
+
+describe('spiffeIdFor / parseSpiffeId — host arm (backward compatible)', () => {
+  it('default kind produces the exact existing host URI and round-trips', () => {
+    const id = spiffeIdFor('acct-A', 'host-1', DOMAIN)
+    expect(id).toBe('spiffe://relay.example.com/account/acct-A/host/host-1')
+    expect(parseSpiffeId(id)).toEqual({ accountId: 'acct-A', id: 'host-1', kind: 'host' })
+  })
+
+  it('3-arg call (accountId, id, domain) still works and defaults kind=host', () => {
+    const id = spiffeIdFor('acct-A', 'host-9', DOMAIN)
+    expect(parseSpiffeId(id).kind).toBe('host')
+  })
+
+  it('explicit kind=host matches the 3-arg default form', () => {
+    expect(spiffeIdFor('acct-A', 'host-1', DOMAIN, 'host')).toBe(
+      spiffeIdFor('acct-A', 'host-1', DOMAIN),
+    )
+  })
+})
+
+describe('spiffeIdFor / parseSpiffeId — device arm (new)', () => {
+  it('device kind produces a /device/ URI that passes the schema and round-trips', () => {
+    const id = spiffeIdFor('acct-A', 'dev-1', DOMAIN, 'device')
+    expect(id).toBe('spiffe://relay.example.com/account/acct-A/device/dev-1')
+    expect(SpiffeIdSchema.safeParse(id).success).toBe(true)
+    expect(parseSpiffeId(id)).toEqual({ accountId: 'acct-A', id: 'dev-1', kind: 'device' })
+  })
+
+  it('CROSS-TRACK: a raw device SAN as the CP issuer stamps it parses under relay-auth', () => {
+    // This is the exact string form control-plane/src/ca/device-issue.ts will place in the
+    // URI SAN. Assert relay-auth's schema + parser accept it and that it equals the shared
+    // builder's output — proving issuer and verifier cannot drift.
+    const account = 'acct-XYZ'
+    const deviceId = 'did-abc_123'
+    const stampedSan = `spiffe://relay.${DOMAIN}/account/${account}/device/${deviceId}`
+    expect(SpiffeIdSchema.safeParse(stampedSan).success).toBe(true)
+    expect(parseSpiffeId(stampedSan)).toEqual({
+      accountId: account,
+      id: deviceId,
+      kind: 'device',
+    })
+    expect(spiffeIdFor(account, deviceId, DOMAIN, 'device')).toBe(stampedSan)
+  })
+})
+
+describe('spiffeIdFor / parseSpiffeId — malformed / traversal / wildcard rejected', () => {
+  it('rejects path-traversal in either arm', () => {
+    expect(() => parseSpiffeId('spiffe://relay.example.com/account/../host/x')).toThrow(SpiffeError)
+    expect(() => parseSpiffeId('spiffe://relay.example.com/account/../device/x')).toThrow(
+      SpiffeError,
+    )
+  })
+
+  it('rejects wildcard in either arm', () => {
+    expect(() => parseSpiffeId('spiffe://relay.example.com/account/*/host/x')).toThrow(SpiffeError)
+    expect(() => parseSpiffeId('spiffe://relay.example.com/account/a/device/*')).toThrow(SpiffeError)
+  })
+
+  it('rejects an unknown kind segment (only host|device allowed)', () => {
+    expect(SpiffeIdSchema.safeParse('spiffe://relay.example.com/account/a/user/x').success).toBe(
+      false,
+    )
+    expect(() => parseSpiffeId('spiffe://relay.example.com/account/a/user/x')).toThrow(SpiffeError)
+  })
+
+  it('rejects empty accountId / id', () => {
+    expect(() => spiffeIdFor('', 'dev-1', DOMAIN, 'device')).toThrow(SpiffeError)
+    expect(() => spiffeIdFor('acct-A', '', DOMAIN, 'device')).toThrow(SpiffeError)
+  })
+})