fronted/scanner: client-side CDN front discovery (draft)

[myleshorton]

Draft — companion to lantern-box#TBD (meek outbound).

Summary

Adds a client-side probe-based scanner that turns the existing fronted.yaml.gz masquerades — plus opportunistic CloudFront-range samples and Akamai hostname-regex draws — into a ranked list of (IP, outer SNI, inner Host) tuples that work from this client's network position right now.

Why this can't be a server-curated list: censorship in IR moves faster than our config-push cadence, and per Samim Mirhosseini (developer behind patterniha/MITM-DomainFronting, in this Slack thread) the working fronts are "different for each person depending on what ISP they use, their location and time of day". The right discovery loop is per-client, not per-deploy.

Architecture

Layer 1 — client-side probe (this PR)

Probe(ctx, Candidate, Options) Result performs the full check that any one front actually works for this client:

1. TCP connect to Candidate.IPAddress:443 via the supplied Dialer
2. uTLS handshake with ServerName = Candidate.SNI (empty = no SNI sent, Akamai style; non-empty = sent verbatim, CloudFront style)
3. Cert chain verified against Candidate.VerifyHostname
4. HTTPS GET to Candidate.TestURL with Host: Candidate.InnerHost
5. Returns OK only on 2xx — TLS-only success would confirm reachability without confirming the inner Host routes to the right backend

Scan(ctx, []Candidate, Options) []Result runs Probe concurrently with configurable budget.

Layer 2 — candidate generation

Three feeders into the candidate pool, each suited to a different CDN's edge model:

• CandidatesFromConfig(*domainfront.Config) flattens the existing fronted.yaml.gz masquerades. Pre-validated (IP, SNI) pairs; this is the primary input.
• CloudFrontCandidates(n, snis, ...) for discovering CloudFront edges beyond the curated list. Embedded snapshot of AWS's 204 CloudFront IPv4 prefixes (cloudfront_prefixes.txt); weighted random sampling pairs IPs with caller-supplied outer SNIs. Expected hit rate is partial — each CloudFront edge serves a subset of distributions per POP, so the probe filters mismatches. Acceptable for discovery.
• AkamaiCandidates(ctx, hostnames, SystemResolver{}, ...) for discovering Akamai edges via the OS/ISP resolver. Critical: this is the correct path even in IR — the ISP returns real Akamai IPs (Akamai isn't blocked, hosts too much Iranian critical infra) and those IPs are geographically near the client's network. DoH endpoints themselves are blocked in IR.
• GenerateAkamaiHostnames(n) produces draws from a([1-9]|1[0-9])([0-9]{2})\.(dsc)?(b|d|g|g2|na|r|w7)\.akamai\.net — same regex pattern shipped in Psiphon's server entries and adopted by MahsaNG / Shir-o-Khorshid. ~3,500 hostnames in the regex space, all resolve through the same Akamai general edge property.

For Akamai, VerifyHostname is always set to the canonical a248.e.akamai.net regardless of which regex hostname was used to discover the IP — the regex hostnames aren't in the cert's SAN list, but the edge's default cert always validates against a248.e.akamai.net. This was a non-obvious bug in the initial draft; live-network testing exposed it (cert-mismatch failures with regex-generated VerifyHostnames).

Sequence

sequenceDiagram
    participant App as radiance client
    participant Scn as fronted/scanner
    participant SYS as System Resolver (ISP)
    participant CDN as CDN edge (Akamai/CloudFront)

    Note over App: needs working front
    App->>Scn: Scan(candidates)
    par per candidate
        Scn->>SYS: LookupHost(a248.e.akamai.net) [Akamai feeder]
        SYS-->>Scn: real edge IPs
    end
    loop concurrent probes
        Scn->>CDN: TCP + uTLS(SNI=⟂ or masquerade)
        Scn->>CDN: GET TestURL with Host: api.iantem.io
        CDN-->>Scn: 200 OK / 403 / TLS-mismatch
    end
    Scn-->>App: RankWorking() — sorted by latency

Loading

Test coverage

22 unit tests, all green:

• Probe success / TCP fail / TLS hostname mismatch / HTTP 500 → not OK
• Scan concurrency + RankWorking latency ordering
• CandidatesFromConfig flattening
• CloudFrontPrefixes weighted sampling
• Akamai regex output matches the pattern
• Front candidate dedup, partial DNS failure handling

Plus opt-in (SCANNER_INTEGRATION=1) live-network tests:

• TestLive_AkamaiSystemResolver: ~100% hit rate (16/16 in latest run; IPs spanning 3 different POP clusters)
• TestLive_CloudFrontRandomIPs: diagnostic only — hit rate is partial as expected
• TestLive_CloudFrontKnownMasquerades: diagnostic — confirms how fronted.yaml.gz stale entries filter out

What's NOT in this PR

• Consumer wiring: no existing radiance code calls the scanner yet. This PR delivers the primitive; integration with kindling/domainfront (refresh its working-pool from scanner output) or the lantern-box meek outbound (feed scanner-discovered fronts as Fronts config) happens separately.
• Bandit aggregation across users: covered by getlantern/engineering#3525. This client-side scanner is the authoritative source per Samim's design; the server-side aggregation is an optional accelerator on top.
• Meek transport using these fronts: see lantern-box's meek outbound PR (sibling).

Reference

• getlantern/engineering#3524 — fronting plumbing
• getlantern/engineering#3525 — bandit-aggregated front list (this scanner is the discovery primitive)
• getlantern/engineering#3526 — first-class meek transport

🤖 Generated with Claude Code