Receipt verification

A receipt is verified from its .kbundle file alone: in the dashboard (in your browser), with @kblockai/sdk/verify, or with the Rust kblock CLI. All three run the same seven checks and produce the same report. This page helps when the result is not the one you expect: an INVALID or NOT THIS GATEWAY verdict, a report with errors, or a bundle the Cloud API cannot serve.

Start with Read the report: the first failing check names the cause. Then go to the matching section below. To learn how to run a verification in the first place, see Verify a receipt.

Find your symptom

Read the report

Every verifier reports seven checks, in this order: Bundle format, Identity chains, Signature chain, Receipt coverage, Graph integrity, Workflow & authorization, Receipt summary. Each one is VALID, INVALID or SKIPPED. A receipt is valid only when all seven are VALID and there are no errors.

Read it with three rules:

1. The first INVALID check is the cause. Later checks build on earlier ones, so a failure often stops verification. SKIPPED means "not reached", not "passed" and not a second failure. A SKIPPED check can therefore appear above the failing one: an ID_MISMATCH found while the file is read leaves Identity chains SKIPPED above the failing Signature chain, and Signature chain is completed only after Receipt coverage, so a coverage failure leaves it SKIPPED too.
2. Each error has a code, usually the object it concerns, and a message. The code is stable and is what the sections below use. The message names the details, such as the object IDs involved.
3. The text report shortens long values. The CLI's text output and renderText cut check details, messages and other text taken from the bundle with … so that they end before column 80, and say so in a note. For the full values, use the CLI's --json or report.toJSON() in the SDK.

In the dashboard, the same report is the Verification in this browser panel: the Checks list ("N of 7 passed"), the Errors and Warnings notices, and What this verification cannot establish for the notes.

The verifier never throws for a bad bundle: every problem is in the report. This program prints the cause, the findings and the issuer of a bundle. It compares the issuer with the Gateway KID in KBLOCK_GATEWAY_KID, an environment variable of your own that holds the Gateway KID K-Block gives you:

import { readFile } from "node:fs/promises";
import { verifyBundleJson } from "@kblockai/sdk/verify";

const file = process.argv[2] ?? "receipt.kbundle";
// The Gateway KID, the identity K-Block's Gateway signs with: the dashboard shows it after
// you create a gateway API key; if it does not, contact K-Block support.
const gatewayKid = (process.env.KBLOCK_GATEWAY_KID ?? "").trim();

const report = verifyBundleJson(await readFile(file, "utf8"));

// The first INVALID check is the cause; SKIPPED checks were not reached.
const cause = report.checks.find((check) => check.status === "INVALID");
console.log(cause === undefined ? "All checks passed." : `First failing check: ${cause.name}`);
for (const e of report.errors) console.log(`error ${e.code} ${e.object ?? ""}: ${e.message}`);
for (const w of report.warnings) console.log(`warning ${w.code}: ${w.message}`);
for (const n of report.notes) console.log(`note: ${n}`);

// A valid report does not say who issued the receipt: compare the issuer yourself.
console.log(`issuer: ${report.issuer ?? "(not read)"}`);
const fromYourGateway = report.valid && gatewayKid !== "" && report.issuer === gatewayKid;
if (report.valid && !fromYourGateway) console.log("The bundle verifies, but not as a receipt of your gateway.");
process.exit(fromYourGateway ? 0 : 1);

See Verify a receipt for every part of the report, and Receipt fields for the fields of the receipt itself.

The receipt is not from your gateway

A valid report proves that a bundle is internally consistent and correctly signed by the identities it contains. Anyone can build such a bundle with their own keys. Whether the K-Block Gateway issued it is a separate check: the receipt's issuer must be your Gateway KID. Every K-Block Cloud receipt is issued under the gateway identity, also the receipts the Cloud API issues for rejections, cancellations and recovered executions.

Symptoms.

• The dashboard shows NOT THIS GATEWAY and the notice Not issued by this deployment's gateway, for example "The receipt was issued by kid:kb:…, not by this deployment's gateway kid:kb:… …". The Issuer row is marked "not this deployment's gateway".
• The notice can also name a step instead: the dashboard requires the pinned gateway to have signed the receipt's task, proposal, execution and result too.
• In your own code or with the CLI, the report is valid but report.issuer (the Issued by: line) is not the KID you expect.

Causes and fixes.

Finding the right KID. The dashboard shows the Gateway KID right after you create a gateway API key on the API keys page ("The Gateway signs receipts as this identity"); if it does not show it, contact K-Block support. The KID on the API keys page is the one the dashboard pins, so it is wrong too when the pin is wrong: when it disagrees with the Gateway KID that K-Block gave you, trust the one K-Block gave you and contact K-Block support. GET /api/v1/gateway/identity on the Cloud API returns the currently registered kid and its identity documents, but that answer comes from the same service whose receipts you are checking, so prefer a value you recorded yourself. Nothing warns about a wrong pin in advance: it shows only in the browser, on receipt pages, in the form that signs a delegation and on approval requests. See Identities and KIDs.

A caution such as "The task was requested on behalf of …, which is not this organization's current principal (…); it may be a previous principal" is not a failure. It appears on receipts issued before the organization's principal was replaced, and the verdict stays VALID.

No gateway KID is pinned

CONSISTENT means every check passed against the identity documents inside the bundle, but the dashboard has not been told which Gateway identity to trust, so it cannot tell whether your gateway issued the receipt. The Issuer row is marked "gateway not pinned".

Compare the issuer KID with the Gateway KID that K-Block gave you, or verify the bundle with the SDK and compare its issuer with that KID, as in the program above. The dashboard normally has a pinned Gateway identity, so if it keeps showing CONSISTENT, contact K-Block support. Once the dashboard has a pinned Gateway identity, it shows VALID or NOT THIS GATEWAY instead.

The bundle was changed

Every K-Object's ID is a hash of its content, and every object is signed. Changing any signed byte is therefore detected. The verifier's test vectors show what each kind of change produces:

On a receipt's page, the dashboard also compares the SHA-256 of the bundle it downloaded with the hash recorded at issuance. A difference makes the verdict INVALID with the notice Bundle hash mismatch: "The bundle's SHA-256 differs from the hash recorded when the receipt was issued."

Two changes are not tampering, but still change the file:

• Reformatting. Pretty-printing the JSON or changing its line endings keeps the bundle verifiable, because objects are hashed in their canonical form. The file's SHA-256 changes, though, so it no longer matches the SHA-256 on the receipt page or the x-kblock-bundle-sha256 header of the download.
• A byte order mark. If a tool saved the file with a UTF-8 byte order mark at the start, verifyBundleJson refuses it with MALFORMED_JSON "expected value at position 0" (the program above reads the file with Node.js, which keeps the mark). Some Windows tools add one when they save a text file. Remove the mark, or download the bundle again.

Fix. Download the bundle again with Download .kbundle on the receipt page, or from GET /api/v1/orgs/<org-id>/receipts/<receipt-id>/bundle, save the bytes unchanged, and verify the fresh copy. Compare its SHA-256 with the value on the receipt page. If the fresh copy verifies, the other copy was changed after it was downloaded. If it does not, contact K-Block support with the receipt ID and the report.

The file is not a bundle this verifier reads

A Bundle format failure stops verification: the checks after it show SKIPPED.

This release reads bundle format 0.1 with Protocol v0.1 objects only, and it is the only format K-Block Cloud issues. A different version means the file was edited or was not produced by this K-Block release. See Limits and supported versions.

Fix. Look at the first members of the file: a K-Block bundle starts with "kblock_bundle": "0.1" and has the members receipt, objects and identities. Download the bundle again if you are not sure the copy is intact.

In the dashboard, Verify a receipt file accepts files up to 16 MiB. A larger file is refused before verification with "The file is larger than 16384 KiB."

An object is missing from the bundle

A receipt commits to an exact set of objects: the signed steps on the path from the TASK to the receipt's head, the delegations behind them and their revocations, attestations about those steps, and the identity document of every signer. The verifier compares the bundle with that commitment.

For example, an excerpt of the text report of a bundle whose APPROVAL was removed (the removed_approval case of the verifier's test vectors):

Bundle format:            VALID
Identity chains:          VALID
Signature chain:          SKIPPED
Receipt coverage:         INVALID
    ↳ covered objects differ (missing: ["ko_xvrzn2u4xjn335vs2qlml4pfnrgygngyy…
Graph integrity:          SKIPPED
Workflow & authorization: SKIPPED
Receipt summary:          SKIPPED

The interaction details are not shown because the receipt did not verify.

Errors:
  RECEIPT_MISMATCH [ko_jer2b6…ng7q] covered objects differ (missing: ["ko_xvr…
Note: Values ending in … are shortened; the JSON report (--json) has them in full.

RESULT: INVALID

Cause. The file was put together or edited by hand, cut short, or merged from several bundles. A bundle downloaded unchanged from K-Block Cloud is complete.

Fix. Download the bundle again and verify the downloaded file without changing it.

The Cloud API cannot serve the bundle

Every time a receipt page loads and every time a bundle is downloaded, K-Block Cloud reads the stored bundle and checks it against the SHA-256 recorded at issuance. It never serves a bundle that fails this check. Because the receipt page is built from the bundle, the whole page fails with "Could not load the receipt"; a failure of Verify in this browser or Download .kbundle shows "Could not fetch the bundle".

When K-Block cannot read the stored receipt file (the file is missing, or K-Block's receipt storage failed), or the file no longer matches its recorded hash (it was changed or damaged, so K-Block refuses to serve it), the error says "K-Block could not complete this request because of a problem on its side." It goes on "If this keeps happening, contact K-Block support and give them the request ID below." and shows the Request ID. The Cloud API answers HTTP 500.

One case shows a code:

Fix. Nothing in the dashboard, the SDK or the CLI repairs a stored bundle. Reload the page later; if the error continues, contact K-Block support and give them the receipt ID and the request ID shown in the error (and the code, for INVALID_STATE). Tell them also whether every receipt fails, or only the receipts of executed calls while those of rejections and cancellations still load: that difference helps K-Block find the cause.

MISMATCH on a receipt page

MISMATCH means the downloaded bundle verifies, but its receipt, thread, organization or action is not the one the page shows. The notice The bundle does not match this receipt lists each difference, for example "The verified organization (…) does not match the organization this page shows (…)."

This should not happen with a bundle the Cloud API serves for the page. Do not rely on the bundle as this receipt, and contact K-Block support with the receipt ID and the notice.

The two dashboard verdicts disagree

A receipt page shows two verdicts side by side. They answer different questions:

• Cloud valid, browser CONSISTENT or NOT THIS GATEWAY. Expected when the pin is missing or wrong: only the browser applies it. See The receipt is not from your gateway.
• Cloud invalid, browser VALID. The Cloud API knows identity documents the bundle does not contain, for example a later key-compromise report or an equivocation. Open Raw reports, then Cloud verification report: its errors and equivocated_identities say why. Do not rely on the receipt until K-Block support has explained it: contact them with the receipt ID and the Cloud verification report.

Report recorded at issuance, also under Raw reports, is the verification made when the receipt was issued, for comparison.

Warnings and notes on a valid receipt

Warnings and notes do not make a receipt invalid. They tell you what the verification could not establish.

The text report (the CLI's and renderText's) also ends with the same reminder every time: K-Block proves who signed what, in which order and under which authority, not that real-world effects occurred unless a trusted attester signed that claim. That is a limit of every receipt, not a finding about this one.

Command-line errors

The kblock verify command exits with 0 for a valid receipt, 1 for an invalid one and 2 when it cannot reach a verdict. Exit code 2 comes with a line error: … on standard error, for example when:

• the bundle file cannot be read;
• a --trust value is not a valid KID (kid:kb: followed by the base32 digest);
• an --identities file cannot be read, is not strict JSON, or holds something other than a K-Block object or an array of them;
• a --workflow definition cannot be read or registered.

The CLI does not compare the issuer with your gateway: check the Issued by: line yourself. See Verify a receipt for how to run it and its options.

Next steps