Receipt fixtures
Use these signed fixtures to test receipt verification without making a model call or sharing a receipt. The signing keys are derived from public test seeds. They are never used for production receipts. Keep the fixture JWKS out of production trust stores.
The public POST /api/v1/receipts/verify endpoint rejects these fixtures, and fetchReceiptByJti cannot retrieve them. Real receipts are never publicly retrievable. Read a receipt you own with GET /api/v1/receipts/{jti} under your own credentials. An API key needs the receipts.verify permission and can read receipts associated with that key.
Download the files
Save the files together. Run sha256sum -c SHA256SUMS from that directory to check the downloaded bytes.
| File | Contents |
|---|---|
| SHA256SUMS | SHA-256 of each fixture file. |
| jwks.json | Public P-256 keys fixture-gateway, fixture-client, and fixture-wrong. |
| expected-results.json | Test inputs, key selection, and expected results for the SDKs, browser verifier, and public endpoint. |
| gateway-v2.json | Flat gateway ES256 envelope. Verify with fixture-gateway. |
| gateway-v2.header.txt | Value of the X-CloakAPI-Receipt-v2 header for that envelope, with a trailing newline for the text file. Trim it, decode standard Base64, and parse the JSON. |
| stored-v1.json | Stored OpenReceipt v1 envelope for the same call and JTI. Verify with fixture-gateway. |
| authenticated-detail.json | Example response body from the authenticated detail route. Its outer jti is hyphenated. Extract envelope and keep its signed jti unchanged when verifying. |
| device-receipt.json | Standalone receipt from the browser SDK signer. Verify with the embedded device key. |
| countersigned-v3.json | Portal-format OpenReceipt v3 receipt paired with a gateway countersignature. Check the device signature, the witness signature, and their hash binding. |
| device-chain.json | Two valid device receipts with a continuous previous-hash link. |
| changed-claim.json | One byte in the v2 model claim changed after signing. |
| wrong-key.json | V2 claims with kid: "fixture-gateway", signed using fixture-wrong. |
| broken-chain.json | Two correctly signed device receipts. The second receipt points at the wrong hash. |
| different-witness.json | The valid v3 receipt paired with a valid witness over another receipt’s bytes. |
| merkle-tree.json | Three synthetic event records, a Merkle root, and a proof for leaf zero. |
| transparency-seeds.json | The synthetic chain inputs used to reproduce the inclusion response. |
| transparency-inclusion.json | Example body from GET /api/v1/transparency/inclusion for the countersigned receipt’s hash. Its anchor exists only in this fixture. |
Check signatures and failure cases
For v1 and v2, resolve the envelope’s kid in the fixture JWKS and construct a SEC1 uncompressed public point (04 || base64url_decode(x) || base64url_decode(y)). Pass the envelope and its key as a hex string to TypeScript’s verifyReceipt or the offline receipt verifier in Python, Go, Rust, PHP, .NET, Java, or Ruby. This example uses TypeScript:
import { readFileSync } from "node:fs";import { verifyReceipt } from "@cloakapi/sdk";
const json = (file) => JSON.parse(readFileSync(file, "utf8"));const envelope = json("gateway-v2.json");const { x, y } = json("jwks.json").keys.find(({ kid }) => kid === envelope.kid);const point = Buffer.concat([ Buffer.from([4]), Buffer.from(x, "base64url"), Buffer.from(y, "base64url"),]);console.log(verifyReceipt(envelope, point.toString("hex")));The original returns ok: true, kind: "pass". Repeat with changed-claim.json and wrong-key.json. Both return ok: false, kind: "fail", reason: "signature mismatch" using the key named by the envelope.
For a countersigned v3 entry, pass only receipt and the device key to the single-envelope SDK verifier. That checks the device signature and returns witness_checked: false. To check the whole entry, use the browser verifier’s verifyReceiptJson(rawJson, { jwksJson }) with both files supplied as JSON text. The verification methods page describes the available verification surfaces. With the widget source in a test page, give <cloakapi-verify> the raw receipt JSON and supply the fixture JWKS in the test harness response to its JWKS request. A widget running against the production JWKS cannot verify the fixture witness.
| Input | Expected result |
|---|---|
countersigned-v3.json | gatewayVerified: true, hashBound: true, witnessStatus: "verified" with the fixture JWKS. |
different-witness.json | The device and witness signatures still verify individually. hashBound: false and witnessStatus: "unverified" show that this witness does not cover this receipt. |
device-chain.json | The browser verifier accepts the ordered array. |
broken-chain.json | The browser verifier reports a previous-hash mismatch at the second entry. The single-envelope SDK verifier still accepts each signature. |
The device widget expects device receipts. Use the SDK offline verifier for the v1 and v2 gateway envelopes. On the public verify endpoint, a fixture v2 envelope would return HTTP 422, with reason: "one_or_more_checks_failed" and unknown_kid:fixture-gateway in the signature check detail. The result file also records the v1 signature failure and v3 schema rejection.
Check both transparency formats
For merkle-tree.json, encode each leaf_record as compact UTF-8 JSON with recursively sorted object keys and unescaped slashes and Unicode. Hash 0x00 || canonical_json(leaf_record) and compare it in hex with leaf_hash. For a parent, hash 0x01 || left || right after decoding the child hashes to bytes. Promote the third node unchanged when the first two are paired. For the proof at leaf_index: 0, start with its leaf hash and fold in the two right siblings in order. Compare the result in lowercase hex with root. The three records commit to the SHA-256 digests of the canonical signed v3, v1, and v2 envelopes, in that order.
For transparency-inclusion.json, use the separate sha256-chain-v1 format:
- Canonicalize the v3
receiptfromcountersigned-v3.jsonwith JCS, includingsig. The SHA-256 hex digest must match the witness’sreceipt_hash, the response’sreceipt_hash, and the included seed’spayload.receipt_hash. - Read
transparency-seeds.jsonin order from genesis. For each seed, sort the ASCII payload keys and encode compact JSON. Hash the UTF-8 concatenation of the parent hash as lowercase hex text (empty text at genesis), the compact payload JSON, and the suppliedhash_timestamp. Compare the digest in hex with that seed’sseed_hash. - Check that
pathstarts with the seed atseed_index(zero-based in this fixture’s feed) and walks eachparent_hashbackward tonull. Check thatanchored_atidentifies the fixture’s included seed time. Decodemerkle_rootfrom Base64url and compare it with the raw bytes of the response’sseed_hash.
The inclusion response uses the field name merkle_root for the encoded seed hash. The separate Merkle fixture has its own root and sibling proof. Both checks use synthetic inputs. They establish consistency within the fixture set.
Regenerate from source
The generator is repo/sdk/conformance/gen-receipt-fixtures.mjs. Use Node 22.15 or newer in the Node 22 series, PHP with OpenSSL, and a locally built cloak-receipt CLI. Run from the repository root on Linux:
cargo build --locked --manifest-path repo/Cargo.toml -p cloakapi-receipt-verifierCLOAK_RECEIPT_FIXTURE_CLI="${CARGO_TARGET_DIR:-$PWD/repo/target}/debug/cloak-receipt" \ node repo/sdk/conformance/gen-receipt-fixtures.mjsnode repo/sdk/conformance/gen-receipt-fixtures.mjs --checkThe public seed strings are cloakapi/receipt-fixtures/v1/gateway, cloakapi/receipt-fixtures/v1/client, and cloakapi/receipt-fixtures/v1/wrong. Hash the UTF-8 seed with SHA-256 and interpret the digest as a big-endian P-256 scalar. If it falls outside [1, n-1] for curve order n, hash the previous digest bytes and repeat. Only public key coordinates are stored. OpenSSL and WebCrypto may produce different ECDSA signature bytes on each run. --check validates the committed signatures and their dependent hashes and also exercises the signers. Set CLOAK_RECEIPT_FIXTURE_CLI during --check to re-run the v1 signer too. If regenerating for distribution, update the release-integrity entry for the new SHA256SUMS.