# LA4KB V3: independent request-hash and receipt verification

This profile applies **only** to the public typed build
`v3t-1013d7ecf712`, contract `la4kb-v3-typed-candidate-1`, scope manifest
SHA-256 `b54f293d40f263dce4da055ec750e87683bf1e559d340de953452c5c80a17c7a`,
Python 3.12.10, Unicode database 15.0.0 and the deployed Pydantic 2.12.4
model. A later build requires its own
reviewed profile and vectors. The verifier deliberately rejects another build.

## What is committed

The submitted JSON is first admitted by the V3 typed contract. Admission
rejects duplicate JSON object keys, precision-losing decimals, unknown
contract fields, and invalid typed identities. This page describes hashing
an **admitted** request; the standalone verifier is not a replacement for the
complete admission validator or for checking the truth of the evidence.

For an admitted request, V3 hashes the UTF-8 bytes of:

```python
json.dumps(
    ChallengeRequestV3Typed.model_validate(request).model_dump(),
    sort_keys=True, separators=(",", ":"), ensure_ascii=True,
)
```

The hash is SHA-256 in lowercase hexadecimal. It is **not** a hash of the raw
HTTP body. Whitespace and object-key order in that body do not change it.

The top-level model has these fields, including defaults when omitted:

| Field | Omitted value |
| --- | --- |
| `contract_version` | required |
| `scope_schema_id` | required |
| `client_reference` | `null` |
| `claim` | required, kept as a JSON object |
| `evidence_items` | `[]` |
| `provenance` | `null` |
| `origin_category` | `null` |
| `researcher_attribution` | `null` |

When `provenance` is an object, its omitted keys become `null`:
`declared_origin`, `agent_name`, `model_declared`, `researcher_handle`,
`notes`, and `campaign_id`. `claim` and each `evidence_items` object are
kept as parsed JSON dictionaries; V3 does **not** fill their omitted nested
fields before this hash. The typed admission path validates these dictionaries
but does not write its opaque engine tokens back into the hashed request.

Python's JSON rendering matters. `200` and `200.0` remain different hash
inputs. Non-ASCII text is escaped by `ensure_ascii=True`; non-BMP characters
use surrogate-pair escapes. A separate V1/V2 canonicalization document cannot
be substituted for this V3 profile.

The result hash is SHA-256 of canonical JSON for
`{client_reference: receipt.client_reference or "", engine_build, job_id,
verdict: receipt.verdict or "NONE"}`. The result Ed25519 signature covers the
UTF-8 string `engine_build:job_id:result_hash`. A second Ed25519 signature
covers the domain-prefixed canonical JSON binding of `version`,
`payload_hash`, `result_hash`, `engine_build`, and `job_id`. The verifier first
recomputes the request hash from the independently supplied request, then
checks the result hash and both signatures. It pins the public key
`de8b53138bfe735d65a9842f6d695feb663f194c7f67de4a07df859b092ba252`
for this build rather than trusting any key supplied with a receipt.
Because the signed result normalizes an absent client reference to the empty
string, the verifier additionally requires the receipt's typed
`client_reference` to match the supplied request exactly. A number, boolean,
missing field or empty string cannot replace a `null` reference. It also
requires a completed V3 verdict string before checking the signature.

Receipt lifecycle metadata such as `status`, `origin_category`, `entry_surface`
and times is outside these signatures. In contrast, `origin_category` **in
the submitted request** contributes to its `payload_hash`. A successful
verification proves the declared request and signed result are bound under
this build; it does not authenticate the evidence source or prove a claim
about the world.

## Published vectors and use

`conformance/v3_typed/public_payload_hash_vectors_v3t-1013d7ecf712.json`
contains five requests, their exact canonical JSON strings, expected hashes,
and real signed receipts returned by this public build. They cover omitted
defaults, explicit nulls, integer versus float, Unicode plus partial
provenance, and a second claim. The omitted-default and explicit-null vectors
produce the same hash. The integer and float forms do not.

Public copies: [standalone verifier](https://break-la4kb.eidrax.com/examples/verify_v3_receipt.py)
and [five signed vectors](https://break-la4kb.eidrax.com/examples/v3-public-payload-hash-vectors.json).

Save a request, its completed receipt, and the response from
`GET /api/v3/pubkey` as three JSON files. Then run:

```text
python3.12 tools/verify_v3_receipt.py request.json receipt.json pubkey.json
```

Exit code 0 means the recomputed request hash, result tuple, pinned public
key, and both signatures agree. Any disagreement returns a nonzero exit code.
The supplied request must be the admitted V3 request, not a paraphrase or a
different JSON value. A changed unsigned receipt field can still accompany a
valid signed core; the output names examples of these fields.

## Alcance en español

Para el build indicado, el verificador toma el **pedido original admitido**,
reconstruye los valores por defecto de la raíz y de `provenance`, serializa
con Python 3.12.10 y calcula SHA-256. Compara ese hash con el recibo antes de
verificar el resultado y las dos firmas Ed25519 con una clave pública fijada.
Los cinco vectores incluyen pedidos y recibos reales. La firma no certifica
la veracidad de la fuente ni los metadatos operativos del recibo. Otro build
requiere revisar y publicar su propio perfil.
