fix(tunnel): recover an expired leaf over plain HTTPS, not mTLS

Correction to the previous commit. Its recovery vhost could not work: nginx
will not forward an expired client certificate in ANY `ssl_verify_client` mode.
`optional` answers a bare `400 The SSL certificate error` before any location
runs, and `optional_no_ca` only tolerates CHAIN failures — see nginx's
`ngx_ssl_verify_error_optional()`, which covers self-signed / unknown-issuer /
unverifiable-leaf and NOT `X509_V_ERR_CERT_HAS_EXPIRED`. Verified live against
the deployed :8472 server, which rejected the real expired leaf.

So recovery drops mTLS instead of trying to bend it:

- agent: `buildTlsOptions` and the mTLS renew transport go back to being
  strictly fail-closed on expiry — the relaxation is gone from the TLS layer
  entirely. The rotator now decides per attempt: valid → mTLS `/renew`,
  expired-inside-grace → plain `/recover`, expired-beyond-grace → terminal
  `onExhausted` with no request issued at all.
- new `recoverCert` POSTs `{cert, csr}` with no client certificate. Possession
  of the private key is still proven: the CSR is self-signed by it and the host
  signer already enforces CSR PoP plus `CSR key == registered key`, so a
  replayed (public) cert without the key yields at most a certificate the
  attacker cannot authenticate with.
- control-plane: `/renew` is strict again (grace 0, matching the terminator).
  The grace lives on the new `POST /recover`, which reads the cert from the BODY
  and ignores the `x-client-cert` header, then runs the identical trust
  pipeline: X.509 path validation to the frp-client-CA anchors, SPIFFE parse,
  `notBefore` (never graced), registry `active` + account match. Revocation
  still bites.
- deploy: no new vhost, no new SNI, no DNS. One `location = /recover` merged
  into the existing enroll vhost, documented in
  `deploy/nginx/enroll-recover-location.md` with the nginx source citation.

The load-bearing new test is "a self-signed cert with a FORGED SPIFFE SAN is
refused → 401": nginx no longer validates the chain on this path, so that
assertion is what keeps `/recover` from being a cert vending machine.

Verified: agent 289/289, control-plane 290/290, tsc clean on both.
This commit is contained in:
Yaojia Wang
2026-07-29 09:52:17 +02:00
parent f3f4d8baa6
commit 5509c81eee
13 changed files with 559 additions and 472 deletions

View File

@@ -6,9 +6,7 @@ import type { AgentConfig } from '../src/config/agentConfig.js'
import { generateIdentity } from '../src/keys/identity.js'
import { openKeystore } from '../src/keys/keystore.js'
import {
CertExpiredBeyondGraceError,
CertExpiredError,
DEFAULT_EXPIRED_RENEW_GRACE_MS,
NotEnrolledError,
buildTlsOptions,
dialRelay,
@@ -67,82 +65,6 @@ describe('buildTlsOptions (T12, INV14/INV4)', () => {
})
})
/**
* Expired-leaf RENEWAL grace. The tunnel dial stays fail-closed forever; only the /renew recovery
* path may opt in, and only inside a bounded window — otherwise an expired leaf deadlocks the agent
* (mTLS renew needs a cert, and the only cert has expired) and the host is bricked until a re-pair.
*/
describe('buildTlsOptions expired-renewal grace (deadlock recovery)', () => {
const expiredBy = (ms: number) => () => ({ validTo: new Date(Date.now() - ms) })
const DAY = 86_400_000
it('stays fail-closed by DEFAULT — no grace opt-in ⇒ CertExpiredError', () => {
const { dir, ks } = enrolledKs()
expect(() => buildTlsOptions(ks, { certParser: expiredBy(DAY) })).toThrow(CertExpiredError)
rmSync(dir, { recursive: true, force: true })
})
it('expired INSIDE the grace window → returns options so /renew can authenticate', () => {
const { dir, ks } = enrolledKs()
const tls = buildTlsOptions(ks, {
certParser: expiredBy(8 * DAY),
expiredGraceMs: DEFAULT_EXPIRED_RENEW_GRACE_MS,
})
expect(tls.cert).toBe('CERTPEM')
expect(tls.rejectUnauthorized).toBe(true)
rmSync(dir, { recursive: true, force: true })
})
it('expired BEYOND the grace window → CertExpiredBeyondGraceError (re-pair required)', () => {
const { dir, ks } = enrolledKs()
expect(() =>
buildTlsOptions(ks, {
certParser: expiredBy(31 * DAY),
expiredGraceMs: DEFAULT_EXPIRED_RENEW_GRACE_MS,
}),
).toThrow(CertExpiredBeyondGraceError)
rmSync(dir, { recursive: true, force: true })
})
it('grace of 0 is not a bypass — an expired leaf still throws', () => {
const { dir, ks } = enrolledKs()
expect(() => buildTlsOptions(ks, { certParser: expiredBy(1000), expiredGraceMs: 0 })).toThrow(
CertExpiredError,
)
rmSync(dir, { recursive: true, force: true })
})
it('a still-valid cert is unaffected by the grace option', () => {
const { dir, ks } = enrolledKs()
const tls = buildTlsOptions(ks, {
certParser: future,
expiredGraceMs: DEFAULT_EXPIRED_RENEW_GRACE_MS,
})
expect(tls.cert).toBe('CERTPEM')
rmSync(dir, { recursive: true, force: true })
})
it('the TUNNEL dial never gets grace — an expired leaf still refuses to dial', () => {
const { dir, ks } = enrolledKs()
let constructed = 0
class NeverCtor implements RawTlsWs {
constructor() {
constructed += 1
}
send(): void {}
close(): void {}
on(): void {}
once(): void {}
}
// `dialRelay` has no grace seam at all: it fails fast (synchronously) before any socket exists.
expect(() =>
dialRelay(CFG, ks, { Ctor: NeverCtor as unknown as TlsWsConstructor, certParser: past }),
).toThrow(CertExpiredError)
expect(constructed).toBe(0)
rmSync(dir, { recursive: true, force: true })
})
})
describe('dialRelay (T12)', () => {
it('constructs the wss client with the TLS options and resolves on open', async () => {
const { dir, ks } = enrolledKs()