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.

[aram356]

Summary

Adds authenticated trusted client-IP forwarding for Fastly with peer fallback, cross-adapter trust-header stripping, and validated configuration. No blocking defects found in the resolution path: authentication precedes IP parsing, the comparison is constant-time over fixed-size digests, malformed or duplicated input fails closed to the peer address, no secret or header value is logged, and the config-blob rollback hazard is regression-tested against a modeled base-revision schema. The findings below are hardening and maintainability items.

2 of the inline comments below carry a one-click GitHub suggestion. Use Commit suggestion (or Add suggestion to batch) to apply them as commits on the PR branch. The remaining comments describe concerns in prose because the change is design-level or spans files outside the diff.

Non-blocking

♻️ refactor

• Reserve all internal trust headers, not just the TLS bridge pair - see inline at crates/trusted-server-core/src/settings.rs:2672

⛏ nitpick

• Duplicate /.worktrees/ entry - see inline at .gitignore:55

🤔 thinking

• Trust-header sanitization depends on unstated middleware ordering - see inline at crates/trusted-server-adapter-axum/src/middleware.rs:40

🌱 seedling

• No operator-visible signal when the trust handshake degrades - see inline at crates/trusted-server-adapter-fastly/src/platform.rs:730

CI Status

• cargo fmt: PASS (required)
• cargo test: PASS (required)
• format-typescript: PASS (required)
• format-docs: PASS (required)
• cargo test (axum native): PASS
• cargo test (ts CLI, native): PASS
• cargo test (cross-adapter parity): PASS
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• browser integration tests: PASS
• prepare integration artifacts: PASS
• vitest: PASS
• CodeQL: PASS
• Analyze (rust): PASS
• Analyze (javascript-typescript): PASS (both runs)
• Analyze (actions): PASS