[jwrosewell]

Summary

• Keep headers that describe the deployment off a publisher's pages.
• Row 15 of the stack listed in the pluggable modules issue (Pluggable, competition-neutral modules with a technical permission model #777), on feature/14-robots-txt. James Rogers (Jamesr51d) approved this change at a43a05a on the fork's pull request Headers that describe the deployment stay off a publisher's pages jwrosewell/trusted-server#10, closed when the review moved here.

Changes

Area	Change
crates/trusted-server-core/src	12 files, 989 lines added, 273 removed
crates/trusted-server-adapter-fastly/src	3 files, 68 lines added, 91 removed
crates/trusted-server-adapter-axum/src	2 files, 59 lines added, 16 removed
crates/trusted-server-adapter-spin/src	2 files, 58 lines added, 20 removed
crates/trusted-server-adapter-cloudflare/src	2 files, 55 lines added, 14 removed
docs/guide	3 files, 30 lines added, 10 removed
crates/trusted-server-modules/src	1 file, 8 lines added, 2 removed
trusted-server.example.toml	1 file, 6 lines added, 5 removed
crates/trusted-server-adapter-axum/tests	1 file, 4 lines added, 8 removed
CHANGELOG.md	1 file, 3 lines added, 1 removed

Closes

Closes #1273

Spec

Spec: diagnostic-headers

Test plan

CI on this pull request at 21b0bae passed all 32 checks.

• cargo test-fastly && cargo test-axum
• cargo clippy-fastly && cargo clippy-axum
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run
• JS format: cd crates/trusted-server-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: the full workflow set of this repository, run on this pull request at 21b0bae

Checklist

• Changes follow AGENTS.md conventions
• No unwrap() in production code (clippy denies unwrap_used in CI)
• Uses log macros as AGENTS.md asks (not println!)
• New code has tests
• No secrets or credentials committed

---

Stacks on robots.txt from modules (#1355).

What changes

A response no longer carries X-Served-By, X-Cache or X-Cache-Hits, unless this server answered a request for a path beneath /_ts.

Header	What it tells whoever reads it
X-Served-By	Which node answered
X-Cache	Whether a cache answered
X-Cache-Hits	How many times that cache has answered with the object

No adapter writes a version on a response. What the build was made from is in the attestation document (#1353), under build, and the platform's version number of the service under platform.serviceVersion, which is where a deployment is asked about itself. A deployment that wants the versions on its pages names core's service_version middleware in a [[serve]] entry. The middleware writes X-TS-Version, the git version the build compiled in from TRUSTED_SERVER__GIT_VERSION or local git, when the build knows one, and X-TS-Service-Version, the version the adapter reports for the service, when it reports one, on every page the entry covers and on nothing else.

[[serve]]
media_type = "text/html"
middleware = ["service_version"]

How it works

pub const ROUTE_NAMESPACE: &str = "/_ts";

pub fn strip_deployment_headers<T>(path: &str, namespace: &str, response: &mut Response<T>)
pub fn remove_deployment_headers<T>(response: &mut Response<T>)

• Who answered decides beneath /_ts. The publisher fallback removes the three from whatever the origin sends, on every path. The finalize middleware of each of the four adapters then removes them from every response outside the namespace. So a request for an unrouted /_ts/anything, which the fallback sends to the origin, does not get the origin's headers back.
• A path is in the namespace only at a boundary. /_ts and /_ts/permissions are. /_tsx and /_ts-archive are a publisher's pages, and are stripped like any other.
• The removal comes before the finalize step. A header that finalizing writes is kept, an operator's [response_headers] among them. An operator who wants X-Cache on every page can still set it there.

pub type ResponseHeader = (HeaderName, HeaderValue);

pub struct MiddlewareAction {
    pub response_headers: Vec<ResponseHeader>,
    // ...
}

pub struct MiddlewareContext<'a> {
    pub platform: &'a PlatformIdentity,
    // ...
}

• A serve middleware may write a response header. Core writes the headers a serve chain returns on the reader's response at each place a serve pass runs, being the assembled copy of a stored page, the streamed copy and the inline copy of a page that is not stored. A fetch middleware that writes one is refused when the chain is planned, because what a fetch middleware leaves is stored for every reader.
• Every middleware is told the platform, as the adapter reports it for the attestation evidence, through the registry, which each adapter tells once at startup.
• service_version is core's own middleware. No section selects it, an entry names it, and it writes X-TS-Version, the git version the build compiled in, and X-TS-Service-Version, the platform's version number of the service, each only when its version is known.

Why

A response to a reader carries what the page needs and nothing about the deployment, so that the response stays as clean and free of clutter as it can be. The headers above describe how the site is built, to anyone who asks for any page, without that being a decision anyone made. Three arrive from the publisher's origin or a cache on the way to it, and the version was written by the adapter itself.

A question about a deployment has addresses of its own. The inspection pages (#1350) answer beneath /_ts, and so does attestation (#1353) unless its endpoint is moved, and what each shows is the publisher's decision. The rule here is the same one. What describes the deployment is answered where a deployment is asked about itself, and is left off everything else. A deployment that has a reason to put the service version on its pages says so in its settings, with the middleware, and the decision is then its own.

What breaks

• An operator who reads X-Cache or X-Served-By from a page fetched through this server, to see whether the origin's cache answered, no longer sees them. The origin still sends them, and they can be read at the origin.
• A check that read X-TS-Version from a page no longer finds it, whichever adapter served the page and whichever version it carried. It reads the attestation document, where build says what the build was made from and platform.serviceVersion is the platform's number, or the deployment names service_version in a [[serve]] entry.

How it was verified

Not exercised: a response the Fastly entry point sends outside the middleware, being the router's own 405 and the two debug endpoints, is not stripped. It carries nothing from an origin.

References #1273.