Add configurable trusted client-IP header support for Fastly

[prk-Jr]

Summary

• Preserve the original reader IP when Trusted Server is deployed behind another Fastly service, so geolocation, EC derivation, and request processing do not use the fronting edge node.
• Authenticate the forwarded client IP with an operator-configured shared secret, fail safely to the immediate peer, and strip both trust headers before routing.
• Require the shared secret to be at least 32 ASCII graphic bytes and reject whitespace, non-ASCII values, and the published placeholder at startup.
• Remove configured trust headers on Fastly, Axum, Cloudflare, and Spin so a shared multi-adapter configuration cannot expose the authentication value to publisher or integration handlers. Only Fastly uses this configuration for client-IP resolution.
• Document secure front-door setup, validation rules, current secret-storage behavior, and the Fastly no-code routing limitation.

Changes

File	Change
.gitignore	Ignore repository-local worktrees.
crates/trusted-server-core/src/settings.rs	Add validated, redacted trusted-client-IP configuration and constant-time authentication. Enforce a 32-byte ASCII-graphic minimum secret and reject the published placeholder via reject_placeholder_secrets.
crates/trusted-server-core/src/http_util.rs	Treat Fastly-Client-IP as spoofable after authenticated consumption and provide a shared sanitizer for configured trust headers.
crates/trusted-server-adapter-fastly/src/platform.rs	Resolve exactly one authenticated IPv4 or IPv6 header value with peer fallback. Log fallback categories at debug level without logging the secret or address.
crates/trusted-server-adapter-fastly/src/compat.rs	Strip configured and static trust headers before conversion and routing. Keep resolution and sanitization behind resolve_and_sanitize_client_ip so their ordering cannot be reversed.
crates/trusted-server-adapter-fastly/src/main.rs	Resolve once and propagate the selected address through authoritative ClientInfo.
crates/trusted-server-adapter-fastly/src/middleware.rs	Use authoritative ClientInfo for response geolocation, including authoritative absence.
crates/trusted-server-adapter-fastly/src/app.rs	Assert that the resolved ClientInfo address reaches request-scoped services and the EC finalization context.
crates/trusted-server-adapter-axum/src/middleware.rs	Strip configured trust headers before routing. Client-IP resolution remains unchanged.
crates/trusted-server-adapter-cloudflare/src/middleware.rs	Strip configured trust headers before routing. Client-IP resolution remains unchanged.
crates/trusted-server-adapter-spin/src/middleware.rs	Strip configured trust headers before routing. Client-IP resolution remains unchanged.
trusted-server.example.toml	Add commented trusted-client-IP configuration.
docs/guide/configuration.md	Document fields, validation, environment overrides, fallback, cross-adapter sanitization, and current config-blob storage.
docs/guide/fastly.md	Document secure Fastly service chaining and no-code routing limitations, including the unset requirement and keeping the front-door copy of the secret out of inline VCL.
docs/superpowers/specs/2026-08-19-trusted-client-ip-header-design.md	Record the security and data-flow design.
docs/superpowers/plans/2026-08-19-trusted-client-ip-header.md	Record the reviewed implementation and verification plan.

Secret storage

Redacted<String> prevents the shared secret from appearing in debug output and validation errors, but it does not move the value into a platform secret store. With the current configuration architecture, ts config push serializes shared_secret into the Trusted Server application-config blob.

Fastly recommends Secret Store, rather than Config Store, for sensitive values. Migrating this field requires changing the shared configuration schema to hold a secret-store reference and resolving that reference in the Fastly request path. The broader migration of existing Trusted Server passphrases and secrets is tracked by #846 and remains outside this PR.

The fronting copy is a separate concern: a Fastly VCL/CDN service cannot read a Compute Secret Store. That service must obtain the identical value through a VCL-accessible mechanism such as a tightly restricted private/write-only edge dictionary, and must overwrite both incoming trust headers before forwarding.

Fronting VCL deployment requirement

Code configuration alone does not enable trusted client-IP forwarding. The public/fronting VCL service—not the Trusted Server Compute service—must discard client-supplied trust headers and recreate them on the first visit:

sub vcl_recv {
  if (fastly.ff.visits_this_service == 0 && req.restarts == 0) {
    unset req.http.Fastly-Client-IP;
    unset req.http.X-TS-Client-IP-Auth;

    set req.http.Fastly-Client-IP = client.ip;
    set req.http.X-TS-Client-IP-Auth =
      table.lookup(ts_private_config, "trusted_client_ip_secret");
  }
}

This pasteable example is for a dedicated VCL service whose requests all go to Trusted Server. A shared service must apply the setup only on its Trusted Server route, strip client-supplied authentication on other routes, and never send the dictionary value to unrelated backends. If another CDN precedes Fastly, restrict direct access and use that CDN's protected reader-IP value instead of client.ip. The dictionary value must exactly match trusted_client_ip.shared_secret.

Scope note: X-Forwarded-For

This PR does not change cross-adapter handling of client-supplied X-Forwarded-For. An earlier partial hardening change was removed after review because it covered Fastly and Spin but not Cloudflare and Axum. Consistent reconstruction of X-Forwarded-For from authoritative ClientInfo should be handled separately.

Closes

Closes #1041
Fixes #1040

Test plan

• cargo test-fastly
• cargo test-axum
• cargo test-cloudflare
• cargo test-spin
• cargo clippy-fastly
• cargo clippy-axum
• cargo clippy-cloudflare
• cargo clippy-cloudflare-wasm
• cargo clippy-spin-native
• cargo clippy-spin-wasm
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run using repository-pinned Node 24.12.0
• JS format: cd crates/trusted-server-js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM release build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Local Viceroy runtime: authenticated forwarded IP selects the configured Sydney geo fixture; missing or incorrect authentication falls back to the peer-IP San Francisco fixture without rejecting the request.
• Live Fastly service-chain validation against the production/staging two-hop topology.

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code
• Uses repository log macros, not println!
• New code has tests
• No real secrets or credentials committed

[ChristianPavilonis]

Summary

Requesting changes for one high-severity config rollout and rollback compatibility issue. The trusted client-IP runtime behavior and validation otherwise looked sound at the reviewed revision.

[ChristianPavilonis]

🔧 P1: Disabled configuration breaks older binaries during rollout or rollback

When [trusted_client_ip] is absent, this field is None, but #[serde(default)] only affects deserialization. Derived serialization still writes "trusted_client_ip": null into every blob produced by ts config push. TrustedServerAppConfig::serialize delegates directly to Settings::serialize, while the base revision's Settings uses deny_unknown_fields and does not know this key.

Pushing an otherwise unchanged config before upgrading all instances, or rolling back after that push, makes old instances reject the blob and return startup-error HTTP 500 responses even though the feature was never enabled. The existing AuctionConfig compatibility logic explicitly omits default new fields for this reason.

Please omit None during serialization and add a regression test proving a default payload lacks this key and remains accepted by a schema matching the base revision. If the field is configured, document that operators must restore a compatible blob before rolling back.

Suggested change

	#[serde(default)]
	#[serde(default, skip_serializing_if = "Option::is_none")]