Rework SDK HTTP transport: bind L2 to a maintained request client (SSRF-safe by default); scope zero-dependency policy to L1

[KonstantinMirin]

Summary

The SDK's HTTP transport for WBA directory resolution is hand-rolled in each language, and that layer has produced a recurring stream of security findings (a fresh SSRF-guard bypass or transport-wiring bug almost every review round). The root cause is a policy scope error: the zero-dependency policy was applied to L2 (I/O) as well as L1 (the trust core), which forced us to reimplement an HTTP client — badly — in order to bolt an SSRF check onto it. This issue proposes reworking the transport so L2 binds to a maintained HTTP client with an SSRF check at the connection seam, safe by default, while L1 stays pure and dependency-free.

Background: the attack we're guarding

A caller supplies a Signature-Agent header (a host it controls). To verify the request's signature we must fetch that host's public-key directory (/.well-known/http-message-signatures-directory) before the ed25519 check — we can't verify until we've fetched the key. So an unauthenticated caller controls a URL the server fetches from inside its own network: classic pre-auth SSRF (e.g. Signature-Agent: http://169.254.169.254/… to reach cloud metadata). The fetch happening at all is the win condition, regardless of whether verification later fails.

Why the current approach keeps failing

An application-layer SSRF denylist enumerates an open-ended set (reserved ranges × schemes × redirect tricks × address encodings). Every round found another spelling of "internal":

• CGNAT 100.64.0.0/10 and 0.0.0.0/8 missed by stdlib IsPrivate/is_private
• IPv6 zone-id bypass (fe80::1%eth0) skipping netip.Prefix.Contains
• 302 → ftp:// slipping through a redirect into an unguarded handler
• v4-mapped / NAT64 / 6to4 / v4-compatible forms
• a non-2xx crash from hand-assembling urllib's handler chain (dropped HTTPDefaultErrorHandler)

These aren't sloppiness — they're the nature of the denylist, made worse by the fact that we abandoned the maintained HTTP client (status/redirect/1xx/decompression state machine) and now own all of it, in three languages.

Why not "make egress control the primary defense"

Egress control (proxy / network policy / IMDSv2) is the right primary defense for a service you operate. It is not sufficient for an OSS SDK: the artifact runs in deployments we don't control or audit. "Safe only if the operator also deployed a proxy" is not safe-by-default — the reachable pre-auth SSRF is present in the code we ship, so it is a vulnerability against this repo, and "the operator should have configured egress" is not a defense to a report. The correctness must live in the shipped code. Egress remains valuable as recommended operator hardening (defense-in-depth), just not load-bearing for our correctness.

Proposed design

Scope the zero-dependency policy to L1 only.

• L1 — pure, zero-dep, no I/O. Crypto, JCS canonicalization, signature-base, protocol types, validation. This is the trust core; dependency-freedom genuinely matters here (auditability, no transitive supply chain). Keep it hermetic.
• L2 — opinionated, may depend. Composition + I/O. Ship a transport component bound to a recommended, maintained HTTP client, pre-configured for SSRF safety, documented (library + config). The injection seam stays open for consumers who bring their own client, but the default L2 transport is the safe, bound one — so out-of-the-box is safe and not hand-rolled.

The binding is the same shape in every language: a maintained client owns the response/redirect/1xx machine; we add one SSRF check at the connection seam.

SDK	Client	SSRF seam
Go	net/http (already)	Dialer.Control (already) — this is the reference; it had the fewest problems precisely because it never left the maintained client
Python	httpx	custom transport / connection-level pin
TS	undici (official Node client)	custom connect/lookup

Consequences:

• Status/redirect/1xx/decompression correctness comes from the library. if status != 200 becomes an explicit domain decision on top of a correct client, not a substitute for one.
• We stop maintaining a CIDR table and a redirect state machine by hand.
• The recurring per-language bypasses collapse to "configure the library's check," which is one small, testable surface.

Packaging: the safe transport is the default of the L2 package (mandatory dep there); L1 remains a separate dependency-free package. A "core" + "batteries-included" split.

Honest caveat

A maintained SSRF check is still a denylist that chases ranges — binding to a library removes our fragility, not the category's. So we should still recommend egress control to operators as defense-in-depth. Ownership split: code = our safe-by-default correctness; egress = the operator's optional hardening.

Scope of work

• Amend the dependency policy to state its scope is L1 (trust core), and that L2 may take vetted runtime dependencies.
• Python: replace the hand-rolled OpenerDirector/urllib transport (sdk/python/ramp_sdk/resolvers/_http.py) with an httpx-bound L2 transport + connection-level SSRF pin.
• TS: replace the raw http.request transport (sdk/ts/resolvers/http.ts) with an undici-bound transport + connect/lookup SSRF hook.
• Go: confirm the existing net/http + Dialer.Control client already conforms; keep as reference.
• Keep the shared SSRF address/scheme conformance corpora and the transport-wiring behavioral tests (non-2xx, redirect-refusal) green against the new transports.
• Document, in the security/threat-model docs, egress control + IMDSv2 as recommended operator defense-in-depth (explicitly not a substitute for the in-code guard).

References

The recurring findings that motivated this all live on the SDK-extraction PR (#17): SEC-NEW-1 (CGNAT/0.0.0.0/8), SEC3-NEW-1 (IPv6 zone-id), SEC3-NEW-2 (FTP redirect), and the non-2xx opener crash. Each was fixed in place; this issue proposes removing the class rather than continuing to patch it.

[KonstantinMirin]

SDK surface-change assessment

Scoping the blast radius of the L1→L2 move before touching code. Bottom line: small public surface, concentrated entirely in the fetching resolvers; the crypto/verify/sign trust core is untouched.

Notably, TS already does this — sdk/ts/resolvers/index.ts carries the intent in a comment ("IO in the TS SDK… live OUTSIDE the IO-free core/src tree… to keep the transport-neutrality invariant on core"), and the fetching resolvers are exported at a separate subpath @ramp-protocol/sdk-l1/resolvers. We're finishing that split, not inventing it.

Unchanged — the ~90% surface

The I/O-free core almost everyone imports stays put, same signatures: verify, sign, signurl, offer-sign, thumbprint, acceptance, the KeyResolver interface, and StaticKeyResolver. No consumer of the core is affected.

Changed — only the fetching resolvers

SDK	Import-path break?	Detail
TS	No (subpath stays)	Resolvers already live outside the IO-free core at ./resolvers. Import path unchanged; internals swap http.request → undici; add one exported guard symbol; likely drop the now-internal blockedAddress/allowedScheme exports.
Python	No, if we keep the re-export	from ramp_sdk import WBAKeyResolver stays a top-level re-export while the implementation moves to an L2 module. Real change = +httpx dep, +1 guard symbol.
Go	Yes — contained	3 constructors (NewWBAKeyResolver, NewWellKnownKeyResolver, NewWellKnownEndpointResolver) + their option/result types move helpers → a new L2 package; consumers update the import path. NewStaticKeyResolver + the KeyResolver interface stay in helpers. No signature changes.

Why Go can't avoid its break: a shim preserving helpers.NewWBAKeyResolver would have to call the new package, which reintroduces net/http into helpers and defeats the "L1 pure" goal. So Go takes a clean import-path break on ~3 constructors (+ their types), no behavior change.

The most visible change is the dependency, not the API

+httpx (Python) and +undici (TS) appear in lockfiles/installs; Go adds nothing (stdlib). That's the line a consumer actually notices — and it's the deliberate maintained-client-vs-hand-rolled trade this issue proposes.

Net

Trust core untouched · TS already ~80% there · Python stays import-compatible via re-export · Go has one contained import-path break on three constructors. Internal churn (moving files/tests/imports across the boundary) is larger but is not consumer surface. Pre-v1 with essentially one controlled downstream (the app repo), so even the Go break is cheap.

Suggested sequencing

1. Go first — pure layering extraction (no dep), establishes the L1/L2 boundary and is the only SDK with a real break, so best nailed first.
2. Python + TS — same extraction, then swap the transport to httpx/undici with the injectable guard in the native slot; default stays safe-by-default (0 lines), custom client stays safe in 1 line.
3. Shared SSRF corpora + transport-wiring tests move with the code and stay green.