fix(device-auth): trust one client-cert header, and its trusted end (audit H7)

[passcod]

Fixes H7 (high) from the audit in #370, plus the larger hole review turned up underneath it.

1. Reading the wrong end of XFCC (the original H7)

In Envoy's x-forwarded-client-cert convention each trusted proxy appends its element, so the element describing the immediate TLS client of the terminating proxy is the last one. Everything before it describes hops further upstream — and the head of the list is whatever the original client chose to send. extract_cert_pem split on ,, clearly anticipating multiple elements, then took .next().

xfcc_client_cert now takes the last element's Cert=. Two details worth review:

• The split is quote-aware. Envoy quotes any value containing a separator (By="spiffe://mesh/a,b"), and a naive split cuts that element in two, making the quoted tail look like the last element. Element slicing is exactly what decides which hop we trust.
• A last element with no Cert= yields None rather than searching backwards — an earlier element is precisely the untrusted input this exists to ignore.

2. Trusting XFCC at all (found in review)

The bigger problem: XFCC was read unconditionally, with no check that the request came through Envoy, and preferred over mtls-certificate. Envoy isn't deployed and nginx doesn't use XFCC — so nginx has no reason to strip it, and a client could set it themselves and override the header nginx actually verifies.

That's exploitable rather than untidy because resolve authenticates via Device::from_key: a lookup on the certificate's public key, with no proof of possession. Sound when a proxy terminates mTLS and vouches for the peer; a public key is not a secret.

So there's now one setting naming the header to trust:

CANOPY_DEVICE_AUTH_CERT_HEADER = mtls   # default: mtls-certificate / ssl-client-cert (live nginx path)
                               | xfcc   # x-forwarded-client-cert (Envoy, post-cutover)

One value, one header — "trust both" and "trust neither" aren't states the configuration can express. An unrecognised value keeps the live path rather than guessing.

It's not a process global: ClientCertHeader lives in server state and reaches the extractor through FromRef, the idiom AuthDevice already uses for the pool and the tailnet directory. Configuration belongs in state, and it's also what lets a test choose.

3. The suite runs on XFCC

Production exercises the nginx header continuously; XFCC is the shape that goes live at the cutover and had no coverage outside unit tests. So the integration suite runs on XFCC — testing the new shape means removing the old one later is a delete, not a rewrite.

device_key_authentication_works_on_the_nginx_header keeps end-to-end coverage of the live path (and asserts XFCC is refused there). At the cutover, it goes along with ClientCertHeader::Mtls and the mtls-certificate branch.

Tests

Twelve unit tests in mtls.rs: the original six parser cases (including chained_elements_use_the_last_cert, the attack shape, and the quoted-value splitting), plus selection in both directions — xfcc_is_ignored_on_the_nginx_path, xfcc_cannot_override_the_nginx_header, the_nginx_headers_are_ignored_on_the_envoy_path, xfcc_is_honoured_on_the_envoy_path — and env parsing.

Note for whoever merges this

This branch is sensitive to landing late. Tests that arrive on main using mtls-certificate fail here once merged, because the suite authenticates over XFCC — and they merge cleanly and compile, so only running them finds it. That's already happened twice (once with main's products/entitlements and billing-tag tests). #429 adds another (credentials_during_a_rotation_is_503), so if that lands first this needs one more conversion pass. Worth merging sooner rather than later.

[passcod]

Fortunately the envoy ingress path isn't yet live.

[passcod]

Actually instead of two gates, let's have one gate that spells out the header to trust, and default it to the current prod path. That renders the both on both off check unnecessary as the situation becomes impossible.

[passcod]

Stacked this onto #429 — base is now claude/pr-370-fix-h5-rotation-slot, so the diff above is just this PR's own 20 files.

That retires the note at the bottom of the description. The recurring problem was that this branch flips the integration suite to XFCC, so any test arriving on the base with mtls-certificate fails here — and merges cleanly and compiles, so only a test run finds it. It happened with main's products/entitlements and billing-tag tests, and #429's credentials_during_a_rotation_is_503 was lined up to be the third. That one is converted here now, where the flip lives.

Order is fixed: #429 merges, GitHub retargets this to main, and it goes in behind it.

---

Generated by Claude Code