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>
This commit is contained in:
Yaojia Wang
358
control-plane/src/api/renew.ts
Normal file
358
control-plane/src/api/renew.ts
Normal file
@@ -0,0 +1,358 @@
|
||||
/**
|
||||
* A6 (FIX H-host-3) — leaf RENEWAL routes (registerable fastify plugin; testable standalone via
|
||||
* `app.inject`, wired into `main.ts` later). Both routes are authenticated by the CURRENT valid client
|
||||
* certificate the mTLS terminator (nginx / frps) already verified — NEVER by anything in the request
|
||||
* body. Deny-by-default, uniform reject.
|
||||
*
|
||||
* POST /renew [mTLS current frp-client cert]
|
||||
* Identity (accountId, subdomain, current pubkey) is extracted from the PRESENTED cert's SANs
|
||||
* (SPIFFE URI `.../host/<sub>` via relay-auth `parseSpiffeId`, subject key from the cert), NOT the
|
||||
* body. Look the host up BY THAT SUBDOMAIN, require active + account-consistent, then re-issue via
|
||||
* the host signer with the CURRENT cert's key as the subject key — so the delegated gate enforces
|
||||
* the SAME-KEY rule (no key swap) and stamps `host.subdomain` (the SAME subdomain — no smuggling).
|
||||
* 201 { cert, caChain, notAfter }.
|
||||
*
|
||||
* POST /device/:id/renew [mTLS current device cert]
|
||||
* Identity (accountId, deviceId, current pubkey) from the presented device cert's SANs. Look the
|
||||
* device record up by :id, require active + account/deviceId/key-consistent with the presented
|
||||
* cert, then re-issue via the device signer (stamps `record.subdomainScope`). 201.
|
||||
*
|
||||
* CRITICAL (A4 anti-smuggling lesson): a renew can NEVER change the subdomain, account, or key. The
|
||||
* identity comes from the authenticated current cert + the existing registry record; the body carries
|
||||
* ONLY the new CSR. The re-issued SAN is built from the registry record, never from client input.
|
||||
*
|
||||
* `reflect-metadata` must load before `@peculiar/x509` (tsyringe polyfill) — keep the side-effect first.
|
||||
*/
|
||||
import 'reflect-metadata'
|
||||
import * as x509 from '@peculiar/x509'
|
||||
import { webcrypto, X509Certificate as NodeX509Certificate } from 'node:crypto'
|
||||
import { z } from 'zod'
|
||||
import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify'
|
||||
import { parseSpiffeId, type SpiffeKind } from 'relay-auth/src/agent/spiffe.js'
|
||||
import { verifyChain } from 'relay-auth/src/agent/verify-mtls.js'
|
||||
import type { HostRegistry } from '../registry/hosts.js'
|
||||
import type { DeviceRegistry } from '../registry/devices.js'
|
||||
import type { LeafRenewer } from '../ca/rotate.js'
|
||||
import { decodeCsrWire } from '../ca/csr.js'
|
||||
import { bytesToBase64, timingSafeEqualBytes } from '../util/bytes.js'
|
||||
|
||||
x509.cryptoProvider.set(webcrypto)
|
||||
|
||||
/** Default per-identity renewal budget (window). Renewal is ~2/3-TTL cadence — abuse is a signal. */
|
||||
export const DEFAULT_RENEW_RATE_MAX = 30
|
||||
/** Renewal rate window (ms). */
|
||||
export const DEFAULT_RENEW_RATE_WINDOW_MS = 60 * 60 * 1000
|
||||
/**
|
||||
* Hard cap on distinct identities the in-memory limiter tracks. Without a bound the `hits` Map grows
|
||||
* one entry per unique presented identity forever (memory-DoS); at the cap we sweep fully-expired
|
||||
* windows and, if still over, evict the least-recently-seen entries. Evicting an idle entry only
|
||||
* resets a limiter that was about to expire anyway, so the rate guarantee for active identities holds.
|
||||
*/
|
||||
export const RENEW_RATE_MAX_IDENTITIES = 10_000
|
||||
/** Max base64 length of a submitted CSR (a P-256 PKCS#10 is well under 1 KB; this is generous slack). */
|
||||
export const MAX_CSR_B64_LEN = 8192
|
||||
/**
|
||||
* Default header the mTLS terminator forwards the verified client cert in (base64 DER). The terminator
|
||||
* MUST set this from `$ssl_client_cert` AND strip any client-supplied copy — a client can never provide
|
||||
* its own current cert. Production wiring can swap in a socket-peer-cert resolver instead.
|
||||
*/
|
||||
export const DEFAULT_CLIENT_CERT_HEADER = 'x-client-cert'
|
||||
|
||||
/** Uniform reject: 401 = no/invalid current cert (unauthenticated); 403 = cert valid but not allowed. */
|
||||
export class RenewRejectError extends Error {
|
||||
constructor(public readonly status: 401 | 403) {
|
||||
super('renew rejected') // uniform message — never leak which check failed
|
||||
this.name = 'RenewRejectError'
|
||||
}
|
||||
}
|
||||
|
||||
/** Per-identity renewal rate exceeded → 429. */
|
||||
export class RenewRateLimitError extends Error {
|
||||
constructor() {
|
||||
super('renew rate limited')
|
||||
this.name = 'RenewRateLimitError'
|
||||
}
|
||||
}
|
||||
|
||||
/** The authenticated identity extracted from a presented client cert (never from the body). */
|
||||
interface CertIdentity {
|
||||
readonly accountId: string
|
||||
/** SPIFFE id segment: the subdomain for a host cert, the deviceId for a device cert. */
|
||||
readonly id: string
|
||||
readonly kind: SpiffeKind
|
||||
/** SubjectPublicKeyInfo DER of the current cert's subject key (the SAME-KEY anchor). */
|
||||
readonly publicKeySpki: Uint8Array
|
||||
}
|
||||
|
||||
/** Seam for the current mTLS client cert. The terminator provides it; tests inject it. */
|
||||
export interface PresentedClientCert {
|
||||
/** DER of the client cert the mTLS layer verified for THIS request, or null if none was presented. */
|
||||
presentedCertDer(req: FastifyRequest): Uint8Array | null
|
||||
}
|
||||
|
||||
/** Per-identity sliding-window rate limiter for renewals. */
|
||||
export interface RenewRateLimiter {
|
||||
/** Throws `RenewRateLimitError` when `identity` is over its renewal budget. */
|
||||
check(identity: string): void
|
||||
/** Number of identities currently tracked (bounded) — for tests/observability. */
|
||||
size(): number
|
||||
}
|
||||
|
||||
export interface RenewRateLimitOpts {
|
||||
readonly max?: number
|
||||
readonly windowMs?: number
|
||||
/** Clock (ms) — injectable for tests. */
|
||||
readonly now?: () => number
|
||||
}
|
||||
|
||||
/** Optional cap override — defaults to `RENEW_RATE_MAX_IDENTITIES`. */
|
||||
export interface RenewRateLimitBoundOpts extends RenewRateLimitOpts {
|
||||
readonly maxIdentities?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* In-process sliding-window renewal limiter (mirrors `registry/devices.ts` `checkRateLimit`), with a
|
||||
* bounded `hits` Map (memory-DoS guard). Each check drops the identity's timestamps older than the
|
||||
* window; when the Map reaches `maxIdentities` it sweeps every fully-expired identity and, if still at
|
||||
* the cap, evicts the least-recently-seen entries so the Map can never grow without bound.
|
||||
*/
|
||||
export function createRenewRateLimiter(opts: RenewRateLimitBoundOpts = {}): RenewRateLimiter {
|
||||
const max = opts.max ?? DEFAULT_RENEW_RATE_MAX
|
||||
const windowMs = opts.windowMs ?? DEFAULT_RENEW_RATE_WINDOW_MS
|
||||
const maxIdentities = opts.maxIdentities ?? RENEW_RATE_MAX_IDENTITIES
|
||||
const now = opts.now ?? (() => Date.now())
|
||||
const hits = new Map<string, number[]>()
|
||||
|
||||
/** Drop identities whose entire window has expired; if still at the cap, evict oldest-seen entries. */
|
||||
function boundMap(cutoff: number): void {
|
||||
for (const [id, arr] of hits) {
|
||||
const recent = arr.filter((t) => t > cutoff)
|
||||
if (recent.length === 0) hits.delete(id)
|
||||
else hits.set(id, recent)
|
||||
}
|
||||
if (hits.size < maxIdentities) return
|
||||
// All remaining windows are still active but we are at the cap — evict the least-recently-seen
|
||||
// (smallest max-timestamp) down to below the cap. This bounds memory under a distinct-identity flood.
|
||||
const byRecency = [...hits.entries()].sort((a, b) => Math.max(...a[1]) - Math.max(...b[1]))
|
||||
const evict = hits.size - maxIdentities + 1
|
||||
for (let i = 0; i < evict && i < byRecency.length; i++) hits.delete(byRecency[i]![0])
|
||||
}
|
||||
|
||||
return {
|
||||
check(identity) {
|
||||
const ts = now()
|
||||
const cutoff = ts - windowMs
|
||||
// Sweep before inserting a NEW identity so the Map can never exceed the cap.
|
||||
if (!hits.has(identity) && hits.size >= maxIdentities) boundMap(cutoff)
|
||||
const recent = (hits.get(identity) ?? []).filter((t) => t > cutoff)
|
||||
if (recent.length >= max) {
|
||||
hits.set(identity, recent) // persist the pruned window; do NOT record this rejected attempt
|
||||
throw new RenewRateLimitError()
|
||||
}
|
||||
recent.push(ts)
|
||||
hits.set(identity, recent)
|
||||
},
|
||||
size() {
|
||||
return hits.size
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Default `PresentedClientCert` reading the base64-DER cert the mTLS terminator forwarded in a header.
|
||||
* The terminator is trusted to set the header from the VERIFIED client cert and to strip any inbound
|
||||
* copy; this resolver never trusts a client-supplied value on an unterminated path.
|
||||
*/
|
||||
export function headerPresentedCert(headerName: string = DEFAULT_CLIENT_CERT_HEADER): PresentedClientCert {
|
||||
const name = headerName.toLowerCase()
|
||||
return {
|
||||
presentedCertDer(req) {
|
||||
const raw = req.headers[name]
|
||||
const value = Array.isArray(raw) ? raw[0] : raw
|
||||
if (typeof value !== 'string' || value.length === 0) return null
|
||||
try {
|
||||
return new Uint8Array(Buffer.from(value, 'base64'))
|
||||
} catch {
|
||||
return null
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Trust-anchor verification of the presented current cert (defense in depth: the mTLS terminator has
|
||||
* already verified it, but this route must not trust a cert the terminator would never have accepted).
|
||||
* Mirrors relay-auth `verify-mtls` `verifyChain`: full path validation to a self-signed CA anchor in
|
||||
* the supplied set (the frp-client-CA for host renews, the device-CA for device renews) PLUS the
|
||||
* cert's own notBefore/notAfter validity window. ANY failure throws `RenewRejectError(401)`.
|
||||
*/
|
||||
function assertPresentedCertTrusted(
|
||||
der: Uint8Array,
|
||||
caAnchorsDer: readonly Uint8Array[],
|
||||
nowMs: number,
|
||||
): void {
|
||||
let leaf: NodeX509Certificate
|
||||
let anchors: NodeX509Certificate[]
|
||||
try {
|
||||
leaf = new NodeX509Certificate(Buffer.from(der))
|
||||
anchors = caAnchorsDer.map((a) => new NodeX509Certificate(Buffer.from(a)))
|
||||
} catch {
|
||||
throw new RenewRejectError(401)
|
||||
}
|
||||
if (!verifyChain(leaf, anchors)) throw new RenewRejectError(401)
|
||||
const notBefore = new Date(leaf.validFrom).getTime()
|
||||
const notAfter = new Date(leaf.validTo).getTime()
|
||||
if (Number.isNaN(notBefore) || Number.isNaN(notAfter)) throw new RenewRejectError(401)
|
||||
if (nowMs < notBefore || nowMs > notAfter) throw new RenewRejectError(401)
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract the authenticated identity from a presented client cert. Parses the DER, reads the SPIFFE URI
|
||||
* SAN through relay-auth's OWN `parseSpiffeId` (so it can never drift from the verifier), requires the
|
||||
* expected kind, and returns the subject public key SPKI. ANY failure → 401 (unauthenticated). This is
|
||||
* the ONLY identity source — no client-supplied field is ever consulted. When `verify` is supplied (the
|
||||
* kind's CA anchor set + clock), the presented cert is additionally chain- and expiry-validated against
|
||||
* that anchor BEFORE its identity is trusted; production wiring MUST supply anchors.
|
||||
*/
|
||||
function parsePresentedCertIdentity(
|
||||
der: Uint8Array,
|
||||
expectedKind: SpiffeKind,
|
||||
verify?: { readonly caAnchorsDer: readonly Uint8Array[]; readonly nowMs: number },
|
||||
): CertIdentity {
|
||||
let leaf: x509.X509Certificate
|
||||
try {
|
||||
leaf = new x509.X509Certificate(der)
|
||||
} catch {
|
||||
throw new RenewRejectError(401)
|
||||
}
|
||||
if (verify !== undefined) assertPresentedCertTrusted(der, verify.caAnchorsDer, verify.nowMs)
|
||||
const san = leaf.getExtension(x509.SubjectAlternativeNameExtension)
|
||||
const uri = san?.names.toJSON().find((n) => n.type === 'url')?.value
|
||||
if (uri === undefined) throw new RenewRejectError(401)
|
||||
let parsed: { accountId: string; id: string; kind: SpiffeKind }
|
||||
try {
|
||||
parsed = parseSpiffeId(uri)
|
||||
} catch {
|
||||
throw new RenewRejectError(401)
|
||||
}
|
||||
if (parsed.kind !== expectedKind) throw new RenewRejectError(401)
|
||||
return {
|
||||
accountId: parsed.accountId,
|
||||
id: parsed.id,
|
||||
kind: parsed.kind,
|
||||
publicKeySpki: new Uint8Array(leaf.publicKey.rawData),
|
||||
}
|
||||
}
|
||||
|
||||
const RenewBodySchema = z.object({ csr: z.string().min(1).max(MAX_CSR_B64_LEN) }).strict()
|
||||
|
||||
export interface RenewDeps {
|
||||
readonly hosts: HostRegistry
|
||||
readonly devices: DeviceRegistry
|
||||
readonly renewer: LeafRenewer
|
||||
/** Current-cert seam (mTLS terminator provides it). Defaults to the header resolver. */
|
||||
readonly presentedCert?: PresentedClientCert
|
||||
/** Per-identity renewal rate limiter. Defaults to an in-process sliding window. */
|
||||
readonly rateLimiter?: RenewRateLimiter
|
||||
/**
|
||||
* frp-client-CA anchor DER(s). When supplied, the presented current HOST cert is chain- and
|
||||
* expiry-validated against these before its identity is trusted (defense in depth). Production
|
||||
* wiring MUST supply them; omitted only by legacy callers/tests that inject an already-trusted cert.
|
||||
*/
|
||||
readonly hostCaAnchorsDer?: readonly Uint8Array[]
|
||||
/** device-CA anchor DER(s) — same role for the DEVICE renew path. */
|
||||
readonly deviceCaAnchorsDer?: readonly Uint8Array[]
|
||||
}
|
||||
|
||||
/** Map any thrown error to a uniform HTTP reject — never leak which internal check failed. */
|
||||
function sendError(reply: FastifyReply, err: unknown): void {
|
||||
if (err instanceof RenewRejectError) {
|
||||
void reply.code(err.status).send({ error: 'rejected' })
|
||||
return
|
||||
}
|
||||
if (err instanceof RenewRateLimitError) {
|
||||
void reply.code(429).send({ error: 'rate_limited' })
|
||||
return
|
||||
}
|
||||
// LeafSignError / DeviceLeafSignError / ZodError / decode failures / anything else → uniform 400.
|
||||
void reply.code(400).send({ error: 'rejected' })
|
||||
}
|
||||
|
||||
export function buildRenewRouter(deps: RenewDeps): FastifyPluginAsync {
|
||||
const presentedCert = deps.presentedCert ?? headerPresentedCert()
|
||||
const rateLimiter = deps.rateLimiter ?? createRenewRateLimiter()
|
||||
|
||||
return async (app) => {
|
||||
app.post('/renew', async (req, reply) => {
|
||||
try {
|
||||
const der = presentedCert.presentedCertDer(req)
|
||||
if (der === null) throw new RenewRejectError(401)
|
||||
const identity = parsePresentedCertIdentity(
|
||||
der,
|
||||
'host',
|
||||
deps.hostCaAnchorsDer ? { caAnchorsDer: deps.hostCaAnchorsDer, nowMs: Date.now() } : undefined,
|
||||
)
|
||||
rateLimiter.check(`host:${identity.accountId}:${identity.id}`)
|
||||
|
||||
// Identity is the SUBDOMAIN from the cert — resolve the host the registry actually holds for it.
|
||||
// A revoked, unknown, or account-inconsistent binding is forbidden (deny-by-default). 403.
|
||||
const host = await deps.hosts.getHostBySubdomain(identity.id)
|
||||
if (host === null || host.status === 'revoked' || host.accountId !== identity.accountId) {
|
||||
throw new RenewRejectError(403)
|
||||
}
|
||||
|
||||
const body = RenewBodySchema.parse(req.body)
|
||||
// Pass the CURRENT cert's key as the subject key → the delegated gate enforces CSR key ==
|
||||
// current cert key (SAME-KEY, no swap) AND registered key == current cert key; it stamps
|
||||
// host.subdomain (SAME subdomain — the body cannot smuggle a different one).
|
||||
const leaf = await deps.renewer.renewHostLeaf(host.hostId, identity.publicKeySpki, decodeCsrWire(body.csr))
|
||||
await reply.code(201).send({
|
||||
cert: bytesToBase64(leaf.cert),
|
||||
caChain: leaf.caChain.map((c) => bytesToBase64(c)),
|
||||
notAfter: leaf.notAfter.toISOString(),
|
||||
})
|
||||
} catch (err) {
|
||||
sendError(reply, err)
|
||||
}
|
||||
})
|
||||
|
||||
app.post('/device/:id/renew', async (req, reply) => {
|
||||
try {
|
||||
const der = presentedCert.presentedCertDer(req)
|
||||
if (der === null) throw new RenewRejectError(401)
|
||||
const identity = parsePresentedCertIdentity(
|
||||
der,
|
||||
'device',
|
||||
deps.deviceCaAnchorsDer ? { caAnchorsDer: deps.deviceCaAnchorsDer, nowMs: Date.now() } : undefined,
|
||||
)
|
||||
const id = (req.params as { id: string }).id
|
||||
rateLimiter.check(`device:${identity.id}`)
|
||||
|
||||
// The registry record for :id is the identity source of truth. Require it active AND that the
|
||||
// presented cert genuinely belongs to it: same account, same deviceId as the path, same key.
|
||||
const record = await deps.devices.getDevice(id)
|
||||
if (
|
||||
record === null ||
|
||||
record.status === 'revoked' ||
|
||||
record.accountId !== identity.accountId ||
|
||||
identity.id !== id ||
|
||||
!timingSafeEqualBytes(record.ecPubkeySpki, identity.publicKeySpki)
|
||||
) {
|
||||
throw new RenewRejectError(403)
|
||||
}
|
||||
|
||||
const body = RenewBodySchema.parse(req.body)
|
||||
// The delegated gate re-checks CSR key == record.ecPubkeySpki (== current cert key, verified
|
||||
// above) → SAME-KEY; it stamps record.subdomainScope (SAME scope — no smuggling).
|
||||
const leaf = await deps.renewer.renewDeviceLeaf(id, decodeCsrWire(body.csr))
|
||||
await reply.code(201).send({
|
||||
cert: bytesToBase64(leaf.cert),
|
||||
caChain: leaf.caChain.map((c) => bytesToBase64(c)),
|
||||
notAfter: leaf.notAfter.toISOString(),
|
||||
})
|
||||
} catch (err) {
|
||||
sendError(reply, err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user