feat(parser_http_server): HTTP+JSON pivot for TVC public ingress

[pepe-anchor]

Why

Turnkey's TVC public ingress is HTTP only: Cloudflare in front of app-<uuid>.turnkey.cloud rejects gRPC with 403 (verified 2026-05-16). So switching the parse path onto the pivot needs a binary that speaks HTTP and JSON natively and calls parser_app::routes::parse in process, instead of gRPC over vsock.

This is the keystone of the PRS-581 stack. Two PRs are built directly on it in parallel (in-enclave X-Stamp auth, real NSM boot proof), so as much as it is a feature, it is the set of extension points those need.

What

Open v1 and v2 routes only, plus /health. No payment enforcement, no auth, no proto change in this PR.

The three seams it owns, and why each is shaped that way:

1. Handlers take raw Bytes, never Json<T>. An X-Stamp signature covers the exact request bytes; letting serde deserialize and re-serialize changes them (key order, whitespace) and invalidates every signature. parse_envelope(&[u8]) deserializes while the caller keeps the untouched slice. A test pins this so a future refactor cannot quietly undo it.
2. BootProofSource trait with a StaticBootProof implementation, so the NSM-backed one is a new file rather than a rewrite. awsAttestationDocB64 is an empty string here: empty, never faked, because a strict verifier must reject an unattested response outright.
3. Manifest fields are borsh, not the JSON on disk. /qos.manifest holds JSON at qos rev 365ba7ed, but qosManifestB64 and qosManifestEnvelopeB64 are borsh bytes: the Go verifier borsh-deserializes both, and the attestation doc's user_data is sha256(borsh(manifest)). Base64-ing the file bytes would produce fields nothing can verify. Verified against visualsign-turnkeyclient manifest/parser.go.

Also threads include_intermediate_output through for parity with the gateway's REST shape (#414). Every response, success and error, carries bootProof.

The branch also carries the two stagex commits from PRS-581 PR 02, so the pivot has an image to deploy: the matrix builds parser_http_server and parser_grpc_server, the root Makefile gains the rules both legs need, images/parser_grpc_server/Containerfile is added, and the concurrent release-note writes gain a best-effort retry so the legs mostly stop clobbering each other's deployment blocks (see the correction below, the mechanism is not a lock).

Rebase onto main after #446

#446 merged, so this branch is rebased onto current main and the merge commit is flattened away. Three commits now, no merge.

The rebase itself was textually clean: this branch never edited host_primitives/src/turnkey.rs or parser/gateway/src/main.rs, it only imports from them.

What it did leave behind was a semantic mismatch. The pivot was written against host_primitives::turnkey as of the fork point, which had error_response but not yet success_response (that landed in 87816dff, after the fork). So after the rebase handle_parse was still assembling the success wrapper field by field, which is exactly the second copy of the wire contract #446 existed to delete. Fixed in its own commit: the success path now goes through success_response, matching what parser_gateway does.

No wire change. success_response fills the same three fields and sets error: None, so the emitted JSON is byte-identical, and bootProof stays camelCase with exactly its six camelCase keys. Three separate tests pin that and all still pass (host_primitives::turnkey::boot_proof_wire_shape_is_exactly_six_camel_case_keys, parser_http_server's static_boot_proof_has_the_six_keys_and_a_real_ephemeral_pubkey, and the http_server integration test's key-set assertion on both the success and the 400 response).

Review pass, four more commits

A pre-push review round on top of the rebase. Nothing here changes the wire
shape or the three seams the stacked PRs plug into.

Every response now really does carry bootProof. The PR claimed that and
was wrong for three statuses. axum rejects an oversized body, an unmatched
route and a disallowed method before any handler runs, so 413, 404 and 405
went out as bare axum errors with no envelope. 413 is fixed with a middleware,
since DefaultBodyLimit rejects while reading the body and no handler sees it.
404 and 405 deliberately do not share that middleware: handle_parse
legitimately returns 404 itself for Code::NotFound with the parser's real
message, and a middleware keyed on status alone cannot tell that apart from an
unmatched route, so it would replace a genuine parse failure with "not found".
Those two go through Router::fallback and method_not_allowed_fallback,
which axum invokes only when no handler ran. The integration test asserts the
envelope on all four error paths now.

The parse call no longer blocks the reactor. parse is CPU bound, so
running it on the async task pinned a Tokio worker per concurrent request and
would starve the health check Turnkey polls on a 1 to 2 vCPU replica.
block_in_place matches what parser_app's Processor already does around
this same call on the vsock path.

Error messages stopped reflecting request bodies. serde_json's Display
for a type mismatch embeds the offending value, so a malformed request echoed
up to the full body back to an unauthenticated caller. The client gets a fixed
message; the detail goes to stderr, along with new logging on three internal
error paths that previously failed silently.

The TODO(#231) clippy exemptions are gone, not deferred: the ephemeral
key load propagates its error and SIGTERM registration falls back to ctrl-c,
so the crate-level unwrap/expect/panic allows could be deleted outright.

NEAR is compiled in. The default feature set said it mirrored
parser_app's and did not, so a NEAR request would have succeeded against
parser_app and failed against the pivot. That was a silent divergence, not a
deliberate trim.

Two correctness fixes to the notes this branch generates. The release notes
told an operator that /v2 is TVC-enforced when GATEWAY_SIGNING_PUBKEY_HEX
is set and that parser_gateway performs x402 verify and settle. Neither is
true yet: that variable is read nowhere in src, /v2 routes to the same open
handler as /v1, and there is no payment code in the tree. Both notes now
describe the scaffolding as scaffolding.

Correction to ac9e5a47's commit title. It says "serialize release-note
writes" and the mechanism does not serialize. The retry plus read-back is best
effort: it catches this leg's own write being clobbered before it reads back,
but a later leg writing from a stale read can still land after that read-back
succeeded and drop this leg's block. The in-file comment now says so plainly.
Blast radius is a cosmetic release body, not the build or deploy path, and a
manual re-run restores it. Left as best effort rather than adding If-Match or
per-target release assets, which is a real design change and out of scope here.
Not amending the commit message, since this branch has stacked children.

Also pins the borsh encoding of qosManifestB64 and qosManifestEnvelopeB64
with a round-trip test. Nothing asserted it, so swapping to the JSON that
actually sits on disk would have broken Go-side verification with every test
still green.

Test evidence

make -C src test  -> 1614 passed, 0 failed (all suites)
     host_primitives                    5 passed
     parser_http_server                 4 passed
     parser_gateway                    11 passed
     integration/http_server            1 passed
cargo fmt --all -- --check              -> clean
cargo clippy --all-targets -D warnings  -> clean
cargo build -p parser_http_server --features vsock -> compiles (production config)

cargo clippy -p parser_http_server --features vsock --all-targets -D warnings -> clean
cargo test   -p parser_http_server --features vsock                          -> clean

Those last two mattered: they were newly broken and are now fixed. A
qos_core dev-dependency added for the borsh round-trip test pulled in the
mock feature, which cannot be unified in one build graph with this crate's
vsock feature (qos_core's own compile_error! forbids vm plus mock).
Plain cargo build --features vsock still worked and CI never passes vsock,
so nothing was red, but the exact check this PR's acceptance criteria invite
would have failed with a confusing error pointing at qos_core. Fixed at the
source by building the test's ManifestEnvelope from explicit field literals
so the dev-dependency could be deleted.

The http_server integration test covers: health 200; a v1 parse whose
signature.publicKey matches the generated ephemeral key; bootProof with
exactly the six production keys; v2 identical to v1; a malformed body
returning 400; an unmatched route returning 404; a disallowed method returning
405; and a 65 KiB body returning 413. All four error paths assert the six
bootProof keys.

It fails fast if the server dies before binding, polling try_wait alongside
the port. wait_until_port_is_bound loops forever, so without that check a
pivot built for the enclave (which looks for the absolute in-enclave key path
and exits at startup) would hang CI instead of failing it. The client now also
carries a request timeout, so a server that accepts a connection and never
answers fails rather than hanging. Its generated key workdir is gitignored, so
a P256 private key cannot linger on a shared runner.

Rollback

Revert the commits. This adds a new binary that nothing calls yet and changes no existing behavior, so a revert is inert. Nothing is deployed by merging it.

Linear

PRS-581

Stacked on #446 (merged). Supersedes the pivot portion of #304.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an in-process HTTP/JSON ingress for Turnkey TVC, including boot-proof extension points and deployment packaging.

Changes:

• Adds open v1/v2 parse routes and health endpoint.
• Adds static boot-proof generation and HTTP integration coverage.
• Extends container builds and stagex release metadata.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/parser/http-server/src/main.rs	Implements HTTP ingress and parsing.
src/parser/http-server/src/boot_proof.rs	Adds boot-proof abstraction and manifest encoding.
src/parser/http-server/Cargo.toml	Configures server dependencies and features.
src/parser/http-server/build.rs	Injects build version metadata.
src/integration/tests/http_server.rs	Tests HTTP routes and response shape.
src/integration/Cargo.toml	Adds HTTP test dependency.
src/Cargo.toml	Registers the new workspace crate.
src/Cargo.lock	Locks new crate dependencies.
Makefile	Adds server image targets.
images/parser_http_server/Containerfile	Packages the HTTP pivot.
images/parser_grpc_server/Containerfile	Packages the gRPC server.
.github/workflows/stagex.yml	Builds images and publishes deployment notes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.

Suppressed comments (1)

src/parser/http-server/src/main.rs:355

• This only exercises parse_envelope directly, so it still passes if either route changes its extractor from raw Bytes to Json<TurnkeyRequestWrapper>. The handler-level compile regression described in the resolved review thread is absent from the current diff; restore a test that calls parse_v1(State(state), Bytes::from_static(...)) (and/or routes a raw body through the router) so the X-Stamp extension seam is actually pinned.

    fn envelope_is_parsed_from_raw_bytes_not_reserialized() {
        // A later PR verifies an X-Stamp signature over the exact request
        // bytes. If a handler ever takes `Json<T>` and re-serializes, the
        // bytes change (key order, whitespace, unicode escaping) and every
        // stamp fails. Locking the seam here means that PR adds one call and

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

src/parser/http-server/src/main.rs:135

• Logging {e} still records attacker-controlled values from the unauthenticated request: as noted above, a serde type mismatch can include the offending string verbatim, allowing each 400 to write nearly 64 KiB of request data (including transaction contents) into enclave logs. Log only bounded metadata such as the error location/category while keeping the client message generic.

            eprintln!("invalid request body: {e}");

.github/workflows/stagex.yml:140

• Including parser_gateway here generates the same paste-ready tvc deploy create instructions used for enclave pivots, even though the role note identifies it as host-side. Its image contains only the gateway, which defaults GRPC_ADDR to localhost and reports /health as unavailable without a separate gRPC backend (src/parser/gateway/src/main.rs:69-105,228-237), so following these generated instructions creates an unhealthy TVC deployment. Keep publishing its image, but restrict TVC deployment instructions to the actual pivot binaries (or give the gateway a separate non-TVC note).

        if: matrix.target.name == 'parser_app' || matrix.target.name == 'parser_gateway' || matrix.target.name == 'parser_http_server'