Add path-based asset backend proxy routing

[ChristianPavilonis]

Summary

• Add configurable [[proxy.asset_routes]] path-prefix routing so selected first-party asset paths can proxy to a different backend origin than publisher.origin_url.
• Route matching is transparent for normal inbound requests, limited to GET/HEAD, uses longest-prefix-wins, and preserves the full incoming path/query while swapping only the origin.
• Keep built-in and integration routes ahead of asset routes, and bypass the publisher consent/cookie/rewrite pipeline for matched asset requests by serving them as lean raw pass-through proxies.

Changes

File	Change
docs/superpowers/specs/2026-04-28-multi-backend-asset-proxy-design.md	Add the detailed design/spec for path-based multi-backend asset proxy routing.
crates/trusted-server-core/src/settings.rs	Add ProxyAssetRoute, proxy.asset_routes config support, asset-route normalization/validation, duplicate-prefix warnings, and longest-prefix matching helpers.
crates/trusted-server-core/src/proxy.rs	Add the raw asset proxy handler and target URL / Host header helpers for forwarding matched asset requests to alternate origins.
crates/trusted-server-adapter-fastly/src/main.rs	Wire asset-route matching into top-level request routing after explicit routes and before publisher fallback.
crates/trusted-server-adapter-fastly/src/route_tests.rs	Add route-precedence and consent-bypass tests for asset-route behavior.
trusted-server.toml	Document the new [[proxy.asset_routes]] configuration shape with a commented example.

Closes

Closes #663

Test plan

• cargo test --workspace
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo fmt --all -- --check
• JS tests: cd crates/js/lib && npx vitest run
• JS format: cd crates/js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Manual testing via fastly compute serve
• Other:

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — use expect("should ...")
• Uses tracing macros (not println!)
• New code has tests
• No secrets or credentials committed

[aram356]

Summary

Path-based asset proxy routing closely follows the spec, with a clean separation from the publisher pipeline and a conservative forwarded-header set. Concerns are concentrated around (1) origin_url validation that lets path/query through silently, (2) missing test coverage for spec-stated invariants — most importantly that asset failures must not silently fall back to publisher.origin_url, and (3) one CLAUDE.md doc-comment compliance gap.

Blocking

🔧 wrench

• Missing doc comments on ProxyAssetRoute (crates/trusted-server-core/src/settings.rs:336-339)
• origin_url validation accepts URLs with path/query that are silently dropped at runtime (crates/trusted-server-core/src/settings.rs:740-766)
• No test that asset-origin failures stop at 502 without falling back to publisher.origin_url (crates/trusted-server-adapter-fastly/src/route_tests.rs, around the asset_routes_* tests) — spec §9 forbids the fallback; the impl is correct but unpinned by tests.

Non-blocking

🤔 thinking

• Strict-Transport-Security from asset origin forwarded unchanged (crates/trusted-server-core/src/proxy.rs:657-663) — same class of risk as upstream Set-Cookie, which is correctly stripped. Either strip HSTS too or document explicitly.
• Spec-listed test gaps: HEAD passthrough, non-GET/HEAD bypass, redirect pass-through, query-string-ignored-for-matching. All small additions given existing helpers.
• String-prefix matching can match non-segment boundaries (prefix = "/static" matches /staticfile.js). Spec is explicit, but every example uses a trailing /. Worth a sentence in the toml comment and field doc.

♻️ refactor

• Idiomatic method-set check in route_request (crates/trusted-server-adapter-fastly/src/main.rs:153-156) — replace the match &method { &Method::GET | &Method::HEAD => ... } with matches!(...).then(...).flatten().
• Test-stub duplication: StaticResponseHttpClient could move into platform::test_support by extending StubHttpClient with push_response_with_headers.
• Validation split between Proxy::normalize and Proxy::prepare_runtime is inconsistent with the rest of Settings, which uses #[validate] attributes. Either consolidate or comment the rationale.

🌱 seedling

• WASM heap pressure for large asset bodies (crates/trusted-server-adapter-fastly/src/platform.rs:223-237 → fastly_response_to_platform calls take_body_bytes(); crates/trusted-server-core/src/proxy.rs:657 re-buffers via set_body(Vec<u8>)). Same as PublisherResponse::PassThrough, so not a regression — but this PR is specifically targeting asset traffic, where bodies are routinely larger than HTML. Track as a streaming pass-through follow-up mirroring PublisherResponse::Stream. (Anchored in the body since platform.rs is unchanged in this PR.)

⛏ nitpick

• Validation error wording (crates/trusted-server-core/src/settings.rs:716, validate_no_trailing_slash): the spec says "must not include a trailing slash"; the error message says "origin_url must not end with '/'". Aligning the wording reads slightly better in operator-facing errors. The function itself is unchanged in this PR but is reached via the new validate_proxy_origin_url. (Anchored in the body since the line is outside the diff.)
• Redundant to_ascii_lowercase() on target_url.scheme() — already lowercase from URL parsing. See inline comment.
• Set-Cookie strip test only verifies a single header is removed; should test multiple. See inline comment.

CI Status

• fmt: PASS
• clippy: PASS
• rust tests: PASS (858 tests, 0 failures locally; CI green)
• vitest: PASS
• format-typescript: PASS
• format-docs: PASS
• browser & integration tests: PASS
• CodeQL / Analyze: PASS

[ChristianPavilonis]

Tested proxying, it does work, however proxying to a s3 bucket that requires authentication isn't implemented.

[aram356]

Summary

Asset-proxy routing closely follows the spec, every prior blocking comment has been addressed with a paired test, and CI is green. Two blockers remain: (1) path_pattern regex is recompiled on every request despite a working OnceLock pattern ten lines up in the same file, and (2) the spec checked in by this PR explicitly lists path rewrite as out of scope but the PR adds path rewrite. Two follow-up question/scope items, plus a handful of non-blockers around header handling and validation tightness.

Blocking

🔧 wrench

• path_pattern regex recompiled on every request (crates/trusted-server-core/src/settings.rs:435-447) — Handler ten lines up caches via OnceLock. prepare_runtime already compiles for fail-fast and throws the result away. Hot-path WASM perf hole for the Cloudinary-style example shipped in trusted-server.toml.
• Spec contradicts implementation in the same PR (docs/superpowers/specs/2026-04-28-multi-backend-asset-proxy-design.md:55-58) — spec says path rewrite and regex matching are out of scope, but the PR adds both. Update the spec or split the rewrite into a follow-up.

❓ question

• Why is the publisher Host-override change in this PR? (crates/trusted-server-core/src/settings.rs:18-20) — separate publisher-pipeline feature stacked on top of asset-routing. Independent surface, independent rollback risk.

Non-blocking

🤔 thinking

• validate_host_header_value is too permissive (crates/trusted-server-core/src/settings.rs:898-907) — passes spaces, slashes, query strings. Used both as a literal Host: header and to format a URL.
• Clear-Site-Data not stripped from asset responses (crates/trusted-server-core/src/proxy.rs:660-661) — same threat class as HSTS / Set-Cookie which are correctly stripped.
• X-Forwarded-For listed but always empty (crates/trusted-server-core/src/proxy.rs:28) — sanitize_forwarded_headers strips XFF at the edge before routing. Asset CDNs see Trusted Server's IP only.

♻️ refactor

• Dead-code error path in target_path_for (crates/trusted-server-core/src/settings.rs:459-466) — unreachable .ok_or_else(...) with a misleading error message.
• from_url_with_first_byte_timeout_and_override_host (crates/trusted-server-core/src/backend.rs:303-318) — 51-character method name; the API is asking for a builder. Out of scope for this PR.

🌱 seedling

• Backend-name collision via replace(['.', ':'], \"_\") (crates/trusted-server-core/src/backend.rs:144-149) — operator-controlled so practical risk is near-zero, but a hash or non-replacing escape would be more defensive.

⛏ nitpick

• matched_asset_route computed eagerly (crates/trusted-server-adapter-fastly/src/main.rs:153-155) — only used in the catch-all branch. Move inside the _ => arm.
• Double Host header in publisher.rs (crates/trusted-server-core/src/publisher.rs:528) — BackendConfig::override_host is already authoritative; the manual set_header is redundant.
• POST-bypass test could be stronger (crates/trusted-server-adapter-fastly/src/route_tests.rs:399-410) — assert_ne!(OK) is true for any non-200; pin BAD_GATEWAY like the other tests.

CI Status

• fmt: PASS
• clippy: PASS
• rust tests: PASS (875 tests on this worktree, 0 failures)
• vitest: PASS
• format-typescript: PASS
• format-docs: PASS
• browser & integration tests: PASS
• CodeQL / Analyze: PASS