Feature/transaction evidence

[EugeneDymo]

No description provided.

[noxlesh]

Code review — diff-scoped, RAMP-239

Multi-agent review of this PR's diff against main (base 702806c3, head 6afc5853), narrowed to RAMP-239's intent. Ten reviewers over the ten in-scope files; generated output under gen/go, gen/*/wire/{models.py,schemas.ts} and conformance/corpus/ was excluded as the drift gates own it, though it was read to judge what the generators now emit.

RAMP-239's acceptance criteria 2-4 (the README section, docs/HANDOFF-aws-demo.md, make quality) belong to reference-implementation, so on-task here means the GetTransactionEvidence contract: the admin messages and their constraints, the cross-language coverage, and the reference page. Nothing below asks for a README change.

What was run on this head: go test ./conformance/... passes, go run ./conformance/corpusgen produces no drift, ./scripts/check-doc-conformance.sh is clean, python3 scripts/gen-parity-matrix.py --check passes. The gen/ drift gate was not run — it needs buf 1.66.1 and the machine has 1.71.0 — and no item below depends on it.

Should fix

1. The offline verification recipe checks the row against keys the row itself carries.
TransactionEvidence's comment states the recipe as
ed25519.Verify(exchange_signing_public_key, offer_canonical_bytes, hex-decoded offer_sig)
and the matching call for the agent side (proto/ramp/admin/v1/admin.proto:189-196,
repeated in website/src/content/docs/reference/proto-admin.mdx:69). Every input
to both checks comes from the same message. A reader who follows the recipe
proves the three values agree with each other. It does not prove that either key
belongs to the Exchange or to the agent. Anyone who can rewrite the response or
the evidence store builds a different offer, signs its canonical bytes with a
freshly generated key, writes that public key into
exchange_signing_public_key, and both documented checks return true. This
plane has no request signing and no response signing, so the banner's mitigation
restricts who can call the RPC, not who can rewrite its answer. The ticket's
goal — that tampering at any layer breaks the assertions — does not hold for
this case. The anchoring step already exists in the protocol: a key is
identified by its RFC 7638 thumbprint, computable from the raw 32 bytes the row
carries (proto/ramp/v1/ramp.proto:51), and the Exchange publishes a
revoked-thumbprint list (ramp.v1.KeyRevocationList, proto/ramp/v1/ramp.proto:2693).
Extend the recipe in the proto comment and in the reference page: a verifier MUST
check the thumbprint of exchange_signing_public_key against the Exchange's
published key set and its revocation list, and MUST do the same for
agent_public_key against the directory named in agent_discovery_url. Say
plainly that without that step the two checks prove internal consistency only.

2. The recipe has no executable test.
The proto states an exact verification procedure, and nothing in the repository
runs it. conformance/corpus/cases.json carries 38 vectors for
TransactionEvidence, and every one of them is a field-rule mutant with filler
key material (strings.Repeat("k", 32), conformance/corpusgen/main.go:122
and :129) —
no vector holds a real signature over real canonical bytes. So the claim that
this message re-verifies offline is stated in the contract and proven nowhere.
Add a conformance test that builds an evidence row with a real Ed25519 keypair,
signs the canonical bytes, asserts both verifications pass, then flips one byte
of offer_canonical_bytes and asserts the verification fails. The negative half
is what pins the tamper claim.

3. Three protocol rules are stated on the read plane instead of on the ramp.v1 fields that mint the values.
TransactionEvidence.offer_sig and .agent_acceptance_signature require
^[0-9A-Fa-f]{128}$ (proto/ramp/admin/v1/admin.proto:236 and :255), and
TransactionEvidence.transaction_id requires {min_len: 1, max_len: 255}
(:210). On the agent plane the same values carry nothing comparable:
ramp.v1.Offer.signature has no rule (proto/ramp/v1/ramp.proto:544),
ramp.v1.AgentAcceptance.signature has only min_len = 1 (:1724),
ramp.v1.AgentAcceptancePayload.offer_sig has no rule (:1751), and none of
the three transaction_id fields in ramp.proto (:1875, :2199, :2836)
has one. Two things follow. The generated Pydantic and Zod types accept a
malformed signature on the plane where the value arrives from an untrusted
caller, and refuse it only when it is read back as evidence. And a transaction
whose id is 300 characters long satisfies the whole agent plane while its own
evidence row fails the generated schema — the forensic read breaks for exactly
the transaction an operator wants to investigate. The branch applies the
opposite principle two fields away: requester_id and requester_domain are
left unbounded, with the reason spelled out at admin.proto:277-281 — a bound
the agent plane does not enforce can make the row fail its own validation for a
transaction that legitimately executed. State each rule once on the ramp.v1
field the value enters through, then restate it on the admin field with the
Same rule as <field> directive so the new gate covers the pair, and regenerate
the corpus so all three languages refuse a malformed value at ingest. One cost
to plan for: the doc examples carry placeholder signatures such as
"base64-ed25519-credit-offer-sig..."
(website/src/content/docs/protocol/walkthrough-due-diligence.mdx:252) and
conformance/docexamples_validate_test.go validates them, so they need real
128-character hex placeholders in the same change.

4. The transaction-id entropy requirement is enforced in no layer.
This branch makes transaction_id the only selector for the evidence read and
adds the requirement as prose: ids MUST carry UUIDv4-class entropy
(proto/ramp/v1/ramp.proto:1869-1874), with the admin banner restating that
enumeration resistance depends on it (proto/ramp/admin/v1/admin.proto:19-26).
The field carries no protovalidate rule, so transaction_id: "1" is a valid
RAMP id and a valid evidence request in Go, in Python and in TypeScript. What
that buys an attacker is worth stating exactly: the request carries only
{ver, transaction_id} with no tenant scope, the plane is deployment-scoped
across tenants (admin.proto:219-220), and there is no per-operator identity in
v1. An Exchange that mints sequential ids therefore hands anyone who reaches the
listener a walk over every tenant's evidence — full signed offers, both
signatures, both public keys, requester identity and domain. Put the rule in the
schema: (buf.validate.field).string.uuid = true on
ramp.v1.TransactionResultItem.transaction_id, which pins what the reference
implementation already does, then update the corpusgen seed to a real UUID and
commit the regenerated corpus so Python and TypeScript inherit the refusal. If
non-UUID ids must stay legal across Exchange implementations, then the banner
has to say that nothing enforces the entropy requirement and that the network
boundary is the only enforced control — the wording claims a control the
contract does not have.

5. The response cannot carry the signed-URL signature assertion the ticket asks for.
The ticket's chain has two cross-party signature comparisons: the offer
signature, and the signed-URL signature against the prefix the edge logs.
TransactionState carries signed_url_hash, the sha256 of the whole URL
(proto/ramp/admin/v1/admin.proto:347), and no signature, so the second
comparison has no input. A sha256 of the full URL is not a prefix of the URL's
signature, so a client of this contract cannot reproduce that row. The comment
at admin.proto:300 argues that the full URL is a live bearer capability until
expiry, which is a sound reason to leave the URL out; it does not cover leaving
the signature out, and a detached signature on its own is not a retrieval
capability. Add the stored signature to TransactionState with the same hex
rule the offer signature ends up carrying. If the deployed edge does log a
url_hash and the hash join is the intended replacement for the prefix
comparison, say that in the signed_url_hash comment, because the contract is
then asserting something about the edge's log format that nothing in this repo
states.

6. bytes.min_len keeps protoschema's loose translation while bytes.len is tightened.
The branch adds conformance/bytesgen and tighten_bytes_len to turn
bytes.len = N into an exact base64 pattern, and that part works. The same
branch adds two fields with bytes.min_len = 1 —
TransactionEvidence.offer_canonical_bytes (proto/ramp/admin/v1/admin.proto:229)
and .agent_acceptance_canonical_bytes (:258) — which keep the untranslated
form: z.string().regex(/^[A-Za-z0-9+\/]*={0,2}$/).min(2) in TypeScript, and
constr(pattern=r'^[A-Za-z0-9+/]*={0,2}$', min_length=2) in Python. The string
"==" is two characters, matches the pattern, passes the minimum, and carries
zero bytes. Go's protojson refuses to parse it — verified:
invalid value for bytes field offerCanonicalBytes: "==" — so both generated
clients accept a value the server cannot even decode. The root is that
exactLen reads only b.Len (conformance/bytesgen/main.go:64) and
tighten_bytes_len skips a field it cannot match without a word. Cover
bytes.min_len in the same manifest, or fail the run on a bytes rule shape the
pipeline cannot translate — which is the convention this same branch establishes
for string.min_bytes in conformance/requiredgen/main.go:92.

7. The tightened pattern rejects the base64url alphabet that protojson accepts.
tighten_bytes_len hardcodes the standard alphabet,
^[A-Za-z0-9+/]{43}=?$ (scripts/sdk-types/merge_schema.py:308), and that
pattern reaches both clients for agent_public_key,
exchange_signing_public_key and signed_url_hash. Go's protojson accepts
either alphabet for a bytes field and switches to base64.URLEncoding as soon
as the value contains - or _. Verified with a probe against the generated Go
type: all four spellings of a 32-byte key — standard and URL-safe, padded and
unpadded — parse and decode to 32 bytes, while the pattern matches only the two
standard forms. For random 32-byte key material the URL-safe spelling contains
- or _ roughly three times in four, so this is the common case rather than a
corner. One scoping point, because the reviewers split on it: the standard-only
alphabet is protoschema's default and every other bytes field in the contract
already carries it, so the restriction is not introduced here. What is new is
this function re-authoring the whole pattern for these three fields, and a
docstring that claims the rewrite pins "the EXACT encoded forms of N bytes"
while it enumerates two of four. Emit both alphabets as one alternation,
building the two arms from one loop so the length arithmetic stays written once,
and sweep the inherited patterns in the same pass. If rejecting base64url is
deliberate, say so in the docstring and drop the completeness wording.

8. Nothing tests what the new tightening emits, and its padding length is derived twice.
Inside tighten_bytes_len the rem branch chooses the padding regex, and line
310 re-derives the same padding length in a separate conditional
(chars + (2 if rem == 1 else (1 if rem == 2 else 0))). Nothing checks the two
agree. The corpus cannot cover the difference: corpusgen sets bytes through
protoreflect and protojson always emits the padded form, so every corpus value
for these three fields is 44 characters — verified, the set is
{(field, 44, ends-with-'='), (field, 44, no-'=')} with no 43-character entry.
Change pad = "=?" to pad = "=" and every test still passes, while the
clients then reject the unpadded 43-character key that Go accepts. Two of the
three remainder branches have no field to exercise them at all. Add a behavioral
test under gen/python/tests/ and its gen/ts/tests/ parallel, in the shape of
test_numeric_wire_forms.py: assert the padded and unpadded forms are both
accepted and the 44-character unpadded form (33 bytes) is rejected, and state in
the docstring why the corpus cannot carry these cases. The deeper root is that
the base64 arithmetic is written in the Python bridge at all — bytesgen is the
authoritative view of the rule and could emit the exact encoded lengths, leaving
merge_schema.py to apply what it is told.

9. The new drift gate for restated rules is not armed for copies this branch adds.
conformance/samerule_test.go exists to keep an inline rule copy equal to its
source, and the branch uses it on four fields. Two copies it also adds are not
enrolled. TransactionEvidence.tenant_id restates {min_len: 1, max_len: 255}
(proto/ramp/admin/v1/admin.proto:214), the third identical tenant_id rule in
that file after :80 and :101, with no directive and no entry in
knownCopies. And agent_acceptance_signature's directive points sideways at
ramp.admin.v1.TransactionEvidence.offer_sig (:254) rather than at a ramp.v1
field, because there is no rule in ramp.v1 to anchor to — which is item 3
seen from the gate's side. Add the directive to tenant_id and repoint the
signature copy once item 3 lands. The gate itself has a second gap worth
closing in the same pass: it can only find copies that opted in, so a detector
that reports two fields with byte-identical rules and no directive would arm it
for the next author automatically.

10. requiredgen's new byte-length guard cannot fire for a presence-tracked field.
The guard panics on a string.min_bytes or string.max_bytes rule and explains
why: protoschema renders those as a character count, so a multibyte value the Go
server rejects passes the generated clients
(conformance/requiredgen/main.go:92-93). It sits inside zeroRejected, below
two early returns: if fr.GetRequired() { return true } at line 73 and
if fd.HasPresence() { return false } at line 76. Neither presence nor an
explicit required has anything to do with the character-versus-byte problem,
and both shapes are common in this contract, so adding
optional string x = 1 [(buf.validate.field).string.max_bytes = 8] — or the
same rule beside required = true — passes the whole gate and ships the
divergence the guard was written to stop.
Move the check out of zeroRejected into its own scan over every contract
field — it is an assertion about the schema, not an answer to "is the zero value
invalid".

11. Three new pieces disagree about whether string.max_bytes may exist.
requiredgen panics on the rule. corpusgen grew two mutants for it, including
the multibyte one, and hasConstraint now counts max_bytes as a constraint
(conformance/corpusgen/main.go:643 and :781). The class 6 coverage test demands
a multibyte max_bytes mutant whenever the schema carries the rule
(conformance/corpus_coverage_test.go:262-266). No field in proto/ carries
max_bytes, so the panic wins and the other two never run: the mutants are
dead code and the coverage branch reports a check it never performs. Pick one
position. Either the rule stays forbidden until the pipeline can enforce a byte
count — then drop the mutants and the coverage branch — or implement the
byte-count refine in merge_schema.py, remove the panic, and add a field that
exercises the path.

12. The new zero-edge guard does not close the class its own comment names.
corpusgen now fails the run when a constrained field produces no edges, and
the comment says this is how the first bytes rules shipped uncovered
(conformance/corpusgen/main.go:191-196). The guard only sees fields that
already passed hasConstraint, and the bytes rules were invisible precisely
because hasConstraint did not recognise them — so the same class of miss still
passes silently. The residue the guard does catch is narrow: an int64.gt rule,
where hasConstraint returns true and the Int64Kind arm handles only gte.
Move the check to the boundary that matters: walk every field whose
protovalidate rules resolve to anything at all, and fail on one that
hasConstraint skips, so a rule shape the generator does not know is a build
failure instead of a silent absence.

13. Three new corpus cases are labelled as length boundaries while the JSON they emit omits the field.
TransactionEvidence/offer_canonical_bytes/too_short,
.../agent_acceptance_canonical_bytes/too_short and
TransactionRequest/items/too_few all carry a name that says "a value below the
floor". Verified against the committed corpus: the first two emit an object with
that key absent, and the third emits {"idempotency_key": ...} with no items
key. proto-JSON has no present-but-empty form for either shape, so the case
pins "omitted is rejected", and both clients reject the omission for a different
reason — the field is required. The two labels are written at
conformance/corpusgen/main.go:677 and :713. The branch introduces the fix for
exactly this in the same file: not_in_zero_omitted for a zero-valued enum
(conformance/corpusgen/main.go:570-578), visible in the corpus as
ReportingObligationState/state/not_in_zero_omitted. Apply the same naming to
the bytes and repeated edges it adds, so the case id states what the case
actually tests.

14. The new wire surface is recorded in neither changelog.
The branch adds a service method, five messages and one enum to ramp.admin.v1,
plus a new normative MUST on ramp.v1.TransactionResultItem.transaction_id.
proto/CHANGELOG.md and its website mirror
website/src/content/docs/reference/changelog.mdx are untouched. Both kinds of
change have precedent in the file that was not touched:
proto/CHANGELOG.md:378 is the entry for the ramp.admin.v1 package itself,
and the first Unreleased entry is a comment-only change classified
"(no wire change; conformance-affecting)" — the exact class the entropy
requirement falls into. A consumer re-pinning this tree learns about a new RPC
and a new MUST only by reading the proto. Add two Unreleased entries and copy
them into the website mirror, which carries every entry today. The trust-model
decisions this branch makes — a read keyed by transaction id alone, hash-only
delivery join, public keys travelling in the row instead of key ids — belong in
docs/design-history.md for the same reason.

15. The "always EdDSA" invariant is carried by comments, not by the schema.
offer_sig_algorithm and agent_acceptance_signature_algorithm are documented
as server-derived with exactly one legal value, and the comment explains why the
label must not be echoed from the wire: an echoed label sits outside signature
coverage and could claim anything (proto/ramp/admin/v1/admin.proto:245,
:262). The rule that reaches the generated clients is min_len = 1, so
"RS256" and "none" validate in all three languages, and a consumer that
reads the label to choose a verification routine gets nothing from the schema.
The same claim is now written in five comments and six hand-written SDK
constants, and the branch adds a three-line comment in the corpusgen seed to
explain which of two labels belongs here
(conformance/corpusgen/main.go:117-121). Express the value once:
(buf.validate.field).string.const = "EdDSA" on both fields. That needs one
matching change in corpusgen — hasConstraint does not recognise const or
in, so the fields would otherwise drop out of constrained and reach the
corpus with no mutant, which is the blind spot item 12 is about.

16. The request_id / request_id_minted pairing can be violated in every language.
Both fields are optional with no rule, and the comment states the invariant in
prose: both absent or both present is a store-level constraint the server
guarantees, field-level rules cannot express the pairing, and this file carries
no message-level CEL (proto/ramp/admin/v1/admin.proto:308-322). So the one
shape the pair must never take — request_id present,
request_id_minted absent — validates in Go, in Pydantic and in Zod, and the
corpus has no vector for the pair at all. The comment two lines below says why
that shape is harmful: the flag is what separates a server-minted correlation id
from a caller-supplied one, and an absent bool reads as false to a renderer,
which is the caller-influenced answer. The claim that field-level rules cannot
express the pairing is true; the conclusion that nothing can is not. Make it
structural — one optional sub-message holding both fields, with min_len = 1 on
the id — so absent means "no correlation id was recorded" and present means both
facts are there. That keeps the file's field-level-only policy, reaches the
generated types, and gives corpusgen something to mutate.

17. bytesgen is the third copy of the manifest-generator program, and the collision guard is in only one.
requiredgen, uniquegen and now bytesgen share the same body: resolve field
rules over conformance.EachMessage, key a map by bare message name, write
indented JSON. Only requiredgen calls conformance.AssertUniqueBareNames(),
and its comment explains that the manifest keys by bare name so a cross-package
duplicate would silently overwrite. go run ./conformance/bytesgen out.json has
no such guard, and merge_schema.py would then apply the tightening to the
wrong message. exactLen also treats a rule-resolution error as "this field
has no exact length" (conformance/bytesgen/main.go:60-61), so a resolver
failure removes a field from the manifest instead of failing the run. Extract
the shared body into one helper in conformance/ that all three call, with the
collision assertion and the error handling in it once.

18. merge_schema.py's argument slice hardcodes the count.
main(*sys.argv[1:7]) (scripts/sdk-types/merge_schema.py:424) had to widen
from [1:6] in step with the new parameter and the new argument in
scripts/gen-sdk-types.sh:55. Three places must agree and the failure is silent
both ways: every manifest parameter defaults to None and each pass is guarded
by if <path>:, so a dropped or extra argument disables a tightening pass and
the script still exits 0 after printing its success line. The loose base64
window would then ship from a run where every check passed. Use
main(*sys.argv[1:]) so a count mismatch raises TypeError and fails the
pipeline under set -euo pipefail.

19. The class 6 coverage guard is looser than it reads, and its own comment is stale.
Two defects in the new guard. The multibyte scan walks every string in the case
JSON and returns on the first value whose byte length exceeds its character
length (conformance/corpus_coverage_test.go:265-266), so a multibyte value in
any unrelated field satisfies an assertion about the field under test. Anchor
the scan to the field the case mutates. And the class count is stated in two
places: the file header was edited from "These five classes" to "These classes"
(:6), while TestCorpusCoverage's own comment still says "the five
field-level rule classes" (:114) after a sixth was added. Make it name the
classes the test actually has.

20. The new gate compares rules but ignores presence, and reports a resolution failure as drift.
samerule_test.go compares two fields with proto.Equal over their resolved
rules. Presence decides whether a rule bites at all: protovalidate skips an
unset presence-tracked field, so optional string x and plain string x with
byte-identical rules behave differently, and the gate calls them equal. Compare
HasPresence() alongside the rules, or state in the file comment that the gate
covers rule text only. Separately, when ResolveFieldRules fails on the source
field the error is discarded (conformance/samerule_test.go:73) and the
mismatch surfaces as "restated rule DRIFTED", which sends the next author
looking for a rule change that did not happen. Report the resolution failure as
itself.

21. The evidence row's largest fields have a floor and no ceiling.
offer_json, offer_canonical_bytes and agent_acceptance_canonical_bytes all
carry a non-empty minimum and no maximum
(proto/ramp/admin/v1/admin.proto:225, :229, :258), while every other
string in the file is bounded at 255. A response is therefore unbounded in size
for a reader that trusts the schema, and the generated Pydantic and Zod types
will materialize whatever arrives. Bound them at the largest offer the contract
allows, or state in the comment why an unbounded row is intended.

Notes

• conformance/samerule_test.go is the right mechanism for a rule the toolchain
  forces to be an inline copy, and the corpus coverage classes are the right
  place to pin a rule shape the generator once skipped. Both of the items above
  that touch them are about arming them further, not about the approach.
• Outside the ticket, on lines this branch changed: the new corpusgen seed block
  is not gofmt-clean (conformance/corpusgen/main.go:107; the file was clean at
  702806c3, and the gate has no gofmt step, so the next author's editor will
  mix a formatting diff into their change), and stringValues is the third
  structurally identical recursive JSON walker in
  conformance/corpus_coverage_test.go. Both are real and both are in this
  branch's own new code; they are recorded here rather than above because they
  do not touch the evidence contract.
• On unchanged lines, so not this branch's doing: every other bytes field in the
  contract carries protoschema's standard-alphabet-only pattern, so item 7's
  fix has siblings to sweep; ramp.v1.Offer.signature_algorithm calls the value
  a JWS algorithm at proto/ramp/v1/ramp.proto:547 while :1719 and
  sdk/go/helpers/offer.go:38 make the signature a bare hex-encoded detached
  Ed25519 value; conformance/reachability_test.go was already not gofmt-clean
  at the base commit; and requiredgen.zeroRejected inspects only
  GetGreaterThan(), so an integer rule with an upper bound that excludes zero
  keeps its default: 0 and the new assert_defaults_valid guard skips it
  because the node is not a string.