Skip to content
Sign in Create account

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.

FileContents
SHA256SUMSSHA-256 of each fixture file.
jwks.jsonPublic P-256 keys fixture-gateway, fixture-client, and fixture-wrong.
expected-results.jsonTest inputs, key selection, and expected results for the SDKs, browser verifier, and public endpoint.
gateway-v2.jsonFlat gateway ES256 envelope. Verify with fixture-gateway.
gateway-v2.header.txtValue 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.jsonStored OpenReceipt v1 envelope for the same call and JTI. Verify with fixture-gateway.
authenticated-detail.jsonExample response body from the authenticated detail route. Its outer jti is hyphenated. Extract envelope and keep its signed jti unchanged when verifying.
device-receipt.jsonStandalone receipt from the browser SDK signer. Verify with the embedded device key.
countersigned-v3.jsonPortal-format OpenReceipt v3 receipt paired with a gateway countersignature. Check the device signature, the witness signature, and their hash binding.
device-chain.jsonTwo valid device receipts with a continuous previous-hash link.
changed-claim.jsonOne byte in the v2 model claim changed after signing.
wrong-key.jsonV2 claims with kid: "fixture-gateway", signed using fixture-wrong.
broken-chain.jsonTwo correctly signed device receipts. The second receipt points at the wrong hash.
different-witness.jsonThe valid v3 receipt paired with a valid witness over another receipt’s bytes.
merkle-tree.jsonThree synthetic event records, a Merkle root, and a proof for leaf zero.
transparency-seeds.jsonThe synthetic chain inputs used to reproduce the inclusion response.
transparency-inclusion.jsonExample 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.

InputExpected result
countersigned-v3.jsongatewayVerified: true, hashBound: true, witnessStatus: "verified" with the fixture JWKS.
different-witness.jsonThe device and witness signatures still verify individually. hashBound: false and witnessStatus: "unverified" show that this witness does not cover this receipt.
device-chain.jsonThe browser verifier accepts the ordered array.
broken-chain.jsonThe 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:

  1. Canonicalize the v3 receipt from countersigned-v3.json with JCS, including sig. The SHA-256 hex digest must match the witness’s receipt_hash, the response’s receipt_hash, and the included seed’s payload.receipt_hash.
  2. Read transparency-seeds.json in 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 supplied hash_timestamp. Compare the digest in hex with that seed’s seed_hash.
  3. Check that path starts with the seed at seed_index (zero-based in this fixture’s feed) and walks each parent_hash backward to null. Check that anchored_at identifies the fixture’s included seed time. Decode merkle_root from Base64url and compare it with the raw bytes of the response’s seed_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-verifier
CLOAK_RECEIPT_FIXTURE_CLI="${CARGO_TARGET_DIR:-$PWD/repo/target}/debug/cloak-receipt" \
node repo/sdk/conformance/gen-receipt-fixtures.mjs
node repo/sdk/conformance/gen-receipt-fixtures.mjs --check

The 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.