feat(parser_app): verify gateway-signed payment markers

[pepe-anchor]

Why

parser_app is the enclave half of the x402 trust pair. Something outside this repo takes the payment and signs a VerifiedPaymentMarker; the enclave's job is to refuse to parse unless that marker was signed by the pinned gateway key and is bound to this exact request. Without the second half, a marker paid for one parse can be replayed against a different transaction.

Nothing here turns verification on. Every call site passes PaymentPolicy::Disabled, so behaviour is unchanged by this PR. What it does is put the enforcement point in place and settle two things that are free now and expensive later:

The wire number. ParseRequest field 4 shipped on main as include_intermediate_output (#414), while payment_marker was still claiming 4 on the unmerged #304. It takes 5 here. Renumbering an undeployed field costs nothing. Renumbering a deployed one costs a coordinated rollout.

The signed preimage. request_hash is what binds a marker to a request. Getting the set of bound fields right before anything signs against it is free. Changing it afterwards invalidates every marker in flight.

Provenance

The verifier is ported from the unmerged #304 onto current main, not rebased. #304 is stacked on #295, which is closed, so its base is a dead branch and it sits 132 commits behind main. Splitting it into reviewable pieces was the only way forward. Original implementation by @prasanna-anchorage on #304; this PR supersedes the payment_verify and payment_marker portions of it.

Tracked as PRS-581. Based on main, independent of the pivot PRs.

What

• ParseRequest.payment_marker takes field 5, leaving include_intermediate_output = 4 untouched.
• host_primitives::payment_marker: the VerifiedPaymentMarker / SignedVerifiedPaymentMarker types, VPM_VERSION, and request_hash. Borsh-encoded, because the encoding has to match wire-for-wire between whatever signs a marker and the enclave that verifies it.
• parser_app::payment_verify: PaymentPolicy (Disabled or Required) plus the signature and request-binding check, run as the first thing parse() does.
• parse() gains a &PaymentPolicy parameter. Callers updated: parser_app::service, parser_grpc_server::main (both pass &PaymentPolicy::Disabled), and parser_gateway::main picks up the new struct-literal field.

PaymentPolicy::from_env from #304 was dropped on purpose. This repo cannot set env vars in tests (edition 2024 plus forbid(unsafe) bans std::env::set_var), and the real binaries take config from CLI args. from_hex is the only constructor.

What request_hash covers, and what it doesn't

The preimage is:

SHA256( int32_LE(chain)
      || u32_LE(len(unsigned_payload))  || unsigned_payload
      || u32_LE(len(chain_metadata))    || chain_metadata
      || u8(include_intermediate_output) )

chain_metadata is the borsh encoding of the inner ChainMetadata, not the Option wrapper, so there is no discriminant byte.

What the binding gives you: a marker cannot be moved to a different request. All four inputs change what the enclave actually attests, so covering fewer of them would let a marker paid for one parse authorise another just by varying metadata.

What it does not give you: it does not make a marker single-use. The enclave holds no state and does not track redemption, so preventing the same payment from being spent twice belongs to whatever signs the markers, not here. Worth stating explicitly so nobody reads request_hash as a replay defence it isn't.

The length prefixes matter on their own. Without them the preimage is a bare concatenation, so ("AB", []) and ("A", [b'B']) hash identically and a marker bought for one request verifies against the other.

Prerequisite before PaymentPolicy::Required

The signer is not in this repo. The only non-test caller of request_hash here is the verifier, so the preimage is a contract with an external component, and that component has to move to the identical 4-field length-prefixed form before policy can flip to Required. Otherwise every real marker fails the binding check and paid parses break.

That is a rollout prerequisite, not a blocker for this PR, and it is exactly why the preimage moves now: nothing verifies markers today, so the change is free. Same argument as the field-5 renumbering above.

Hardening pass (92ed4c48)

The pre-push review loop found three real defects in the verification path this PR introduces. Fixed in a follow-up commit rather than folded in, so the original feature commit stays reviewable on its own.

request_hash under-bound the request. It covered only (chain, unsigned_payload). Now all four fields, length-prefixed, per the layout above.

signing_digest() had an unsound fallback. It swallowed borsh failures with unwrap_or_default(), so the digest became sha256(empty) on that path. One signature over that fixed fallback would verify against any marker that also failed to serialise. It returns Result now and the caller propagates.

The pinned key never matched a 0x-prefixed config value. pinned_hex_lower came from the raw config string while the signer emits unprefixed hex, so a 0x-prefixed GATEWAY_SIGNING_PUBKEY_HEX rejected every request. It is derived from the decoded key now, and decoding goes through visualsign::encodings::decode_hex per the repo's hex-handling rule (which also closes a 0X gap, since qos_hex::decode strips lowercase only).

Also drops the subtle dependency (both sides of that compare are public keys, not secrets), dedups the metadata-encoding and test-setup helpers, and corrects docs that claimed parser_app verifies x_payment_hash. It does not, and no proto field carries those bytes yet.

Rebase note (2026-08-25)

The NEAR series landed on main while this sat open, which made the field-5 argument concrete rather than hypothetical. NearMetadata near = 3 and the NEAR codegen attributes now merge alongside payment_marker = 5, with include_intermediate_output = 4 untouched.

The only conflict was src/generated/src/generated/descriptor.bin, which is generated. Resolved by re-running make -C src generated against the merged proto, not by hand-picking a side. Main's NEAR tests also added five new ParseRequest literals in integration/tests/parser.rs that predate field 5, so the branch stopped compiling; all five now pass payment_marker: vec![], matching the six sites the feature commit already updated. Folded into the same commit, since a commit that adds a field has to leave its call sites compiling.

Test evidence

make -C src lint       -> exit 0, 0 warnings
cargo fmt -- --check   -> clean
make -C src generated  -> no diff (codegen is deterministic)
make -C src test       -> 39 suites, 1617 passed, 0 failed

New regression tests:

• replay with a different chain_metadata
• replay with a toggled include_intermediate_output
• a forged marker claiming the pinned key but signed by another keypair, covered at both the payment_verify layer and the public parse() entry point
• a preimage boundary-collision test

That last one was added because a review pass showed the length-prefix fix was not pinned by anything: reverting the fix left all 12 existing tests green. Verified by mutation, reverting the length prefixes now fails request_hash_length_prefixes_defeat_field_boundary_collisions and only that test.

Rollback

Revert the commits and re-run make -C src generated. The proto field is additive and unused by any deployed caller, and PaymentPolicy is Disabled everywhere, so nothing on the wire or in behaviour depends on it yet.

[Copilot]

Pull request overview

Adds gateway-signed payment marker verification infrastructure while preserving existing behavior with payment enforcement disabled.

Changes:

• Adds Borsh payment marker types, request hashing, and P-256 verification.
• Adds ParseRequest.payment_marker as protobuf field 5.
• Updates parser callers, generated code, dependencies, and tests.

Reviewed changes

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

Show a summary per file

File	Description
proto/parser/parser.proto	Defines payment marker field 5.
src/generated/src/generated/parser.rs	Regenerates ParseRequest.
src/host_primitives/src/payment_marker.rs	Adds marker wire types and hashing.
src/host_primitives/src/lib.rs	Exports payment marker module.
src/host_primitives/Cargo.toml	Adds marker dependencies.
src/parser/app/src/payment_verify.rs	Implements payment policy and verification.
src/parser/app/src/routes/parse.rs	Verifies markers before parsing.
src/parser/app/src/service.rs	Passes the disabled policy.
src/parser/app/src/lib.rs	Exports verification module.
src/parser/app/Cargo.toml	Adds verification dependencies.
src/parser/grpc-server/src/main.rs	Passes the disabled policy.
src/parser/gateway/src/main.rs	Initializes the new request field.
src/integration/tests/parser.rs	Updates request fixtures.
src/Cargo.lock	Records dependency changes.

---

💡 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 15 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

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

Suppressed comments (3)

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

proto/parser/parser.proto:59

• The documented wire type is incorrect: the verifier deserializes SignedVerifiedPaymentMarker, not the inner VerifiedPaymentMarker. An external gateway following this proto comment would omit the signature wrapper and every marker would fail decoding. Name the wrapper explicitly here; regenerated Rust documentation will then match the actual contract.

  // Borsh-encoded VerifiedPaymentMarker signed by the gateway. parser_app

src/parser/app/src/routes/parse.rs:469

• These function-local imports deviate from this test module's established top-level import layout (routes/parse.rs:163-173; see also payment_verify.rs:190-193). Move both imports to the top of the test module so test dependencies remain centralized.

        use host_primitives::payment_marker::{
            SignedVerifiedPaymentMarker, VPM_VERSION, VerifiedPaymentMarker, request_hash,
        };
        use qos_p256::sign::P256SignPair;

src/parser/app/src/payment_verify.rs:76

• The policy tests only construct unprefixed keys via qos_hex::encode, so the newly supported 0x/0X input path is not protected against regression. Add a from_hex test using a prefixed generated public key and verify that it accepts a valid marker.

        let trimmed = hex_value.trim();
        let bytes = decode_hex(trimmed).map_err(|e| {

[prasanna-anchorage]

can we group these together in x402 crate or something so that we know that this is

[pepe-anchor]

Your comment cuts off at "so that we know that this is", answering what I think you meant.

Skipping the crate for now. Once the settlement fields moved behind PaymentDetails the envelope is scheme-agnostic on purpose, so x402 is the wrong name for it, and there's not much to gather anyway: one file, one consumer (parser_app), and #449's x402 code shares nothing with it.

Happy to split it out the moment there's a second consumer, a Rust signer or a golden-vector harness for the Go side. If you meant a payment module rather than a crate, I'll do that here.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 changed files in this pull request and generated 2 comments.

Suppressed comments (6)

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

src/parser/app/src/payment_verify.rs:34

• This says the policy is loaded from GATEWAY_SIGNING_PUBKEY_HEX, but this PR deliberately removed env-coupled loading and from_hex accepts configuration chosen by the embedding binary. Keeping the old env-specific contract can mislead future callers wiring Required.

/// Whether `parser_app` requires (and verifies) a `VerifiedPaymentMarker`
/// on every parse call. Loaded once at startup from
/// `GATEWAY_SIGNING_PUBKEY_HEX`.

src/parser/app/src/routes/parse.rs:473

• Test imports are kept at the test module scope in this file (see lines 163-169), rather than inside individual test functions. Move this import there or qualify these two calls so the new test follows that convention.

        use qos_p256::sign::P256SignPair;

src/host_primitives/src/payment_marker.rs:1

• The repository keeps source text ASCII-only for terminal compatibility; replace this em dash with an ASCII hyphen.

This issue also appears on line 8 of the same file.

//! VerifiedPaymentMarker — the signed proof the gateway hands to parser_app

src/parser/app/src/payment_verify.rs:385

• The repository keeps source text ASCII-only for terminal compatibility; replace this em dash with an ASCII hyphen.

        // Flip the last byte (inside the signature region — the signature

src/host_primitives/src/payment_marker.rs:229

• The “stable” assertion invokes request_hash twice, so it does not pin the externally consumed preimage contract; changing field order, endianness, or framing would leave all these sensitivity tests green while breaking every issued marker. Add a fixed cross-implementation vector covering non-empty payload and metadata plus the flag.

    fn request_hash_is_stable_and_sensitive_to_every_bound_field() {
        let h1 = request_hash(1, "0xdeadbeef", &[], false);
        let h2 = request_hash(1, "0xdeadbeef", &[], false);

src/host_primitives/src/payment_marker.rs:8

• The repository keeps source text ASCII-only for terminal compatibility; replace this em dash with an ASCII hyphen.

//! bytes — no schema drift.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 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.

proto/parser/parser.proto:63

• This comment implies payment_marker is always verified, but every runtime caller currently supplies PaymentPolicy::Disabled, which returns without reading the field. Qualify verification as conditional on PaymentPolicy::Required so API consumers do not mistake marker presence for validation.

  // Borsh-encoded VerifiedPaymentMarker signed by the gateway. parser_app
  // verifies this before processing. Empty for the open v1 routes and for

src/parser/app/src/payment_verify.rs:34

• This says the policy is loaded from GATEWAY_SIGNING_PUBKEY_HEX, but this module deliberately has no environment-backed constructor and all current callers pass Disabled. Describe Required as being constructed by caller-owned startup configuration instead, consistent with from_hex and the module documentation.

/// Whether `parser_app` requires (and verifies) a `VerifiedPaymentMarker`
/// on every parse call. Loaded once at startup from
/// `GATEWAY_SIGNING_PUBKEY_HEX`.

[Copilot]

Pull request overview

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

Suppressed comments (3)

src/host_primitives/src/payment_marker.rs:10

• This trust-model statement describes verification as current behavior, while payment_verify.rs:10 and all production call sites explicitly disable it. Qualify the statement with PaymentPolicy::Required so the security guarantee is not overstated.

//! Trust model: parser_app verifies the gateway's P256 signature against a

src/parser/app/src/payment_verify.rs:536

• request_hash has four bound inputs, including include_intermediate_output, so describing metadata as one-third of the preimage is stale and omits a security-relevant field.

        // `chain_metadata_bytes` (borsh(ChainMetadata)) is one-third of
        // `request_hash`'s preimage, alongside `unsigned_payload` and
        // `chain`, both of which already have hand-encoded pinned tests in

src/host_primitives/src/payment_marker.rs:8

• Repository guidance requires ASCII-only source for terminal compatibility. Replace this em dash with ASCII punctuation.

//! bytes — no schema drift.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

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

src/parser/app/src/payment_verify.rs:239

• The request hash is computed before the marker's signature is authenticated. In Required mode, an unauthenticated caller can supply the public pinned key, a self-computed matching hash, and a random signature, causing metadata serialization plus allocation and hashing of a preimage approaching the 25 MiB request limit before rejection. Verify the bounded VPM signature first, then compute and compare the full request hash only for an authenticated marker.

    let chain_metadata_bytes = chain_metadata_bytes(chain_metadata.as_ref())
        .map_err(|e| PaymentVerifyError::Internal(format!("chain_metadata borsh encode: {e:?}")))?;
    let expected = request_hash(
        *chain,
        unsigned_payload,
        &chain_metadata_bytes,
        *include_intermediate_output,
    );

[Copilot]

Pull request overview

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

Suppressed comments (1)

src/parser/app/src/payment_verify.rs:239

• Authenticate the marker before hashing request-controlled data. As ordered now, anyone can send an 8 KiB syntactically valid marker with a bad signature plus a near-limit payload/metadata and force chain_metadata_bytes and request_hash to allocate/copy/hash up to the full request before rejection. Move the pinned-key and P256 signature checks ahead of this request-binding calculation so forged markers take only bounded work.

    let chain_metadata_bytes = chain_metadata_bytes(chain_metadata.as_ref())
        .map_err(|e| PaymentVerifyError::Internal(format!("chain_metadata borsh encode: {e:?}")))?;
    let expected = request_hash(
        *chain,
        unsigned_payload,
        &chain_metadata_bytes,
        *include_intermediate_output,
    );