Decision Receipts

Every record envelope — action, retrieval, and human-adjudication decisions alike — is attested by a decision receipt: an Ed25519 signature over the decision’s canonical payload, stored separately from the envelope it proves. Receipts are then Merkle-batched under an HSM-signed root, timestamped by an independent authority, and chained into an append-only transparency log. This page specifies the exact cryptography so you — or your auditor — can verify it independently.

Receipt issuance is plan-dependent. Decisions on every plan are still recorded in the queryable audit logs.

What a receipt contains

Field	Encoding	Meaning
`signature`	base64url	Ed25519 signature over the canonical payload bytes
`public_key`	base64url	The signing public key, as SPKI DER (44 bytes decoded)
`payload_hash`	hex (64 chars)	SHA-256 of the canonical payload bytes — the Merkle leaf input
`canonical_payload`	JSON	The exact alphabetically-key-sorted payload that was signed

Once the receipt is committed to a batch it also carries its Merkle coordinates: the batch it belongs to, its leaf index, and its leaf hash. The dashboard’s record verification page surfaces all of these fields for any record.

When receipts are issued

Signing is asynchronous — scheduled immediately after the envelope persists, entirely off the decision hot path. Your agents never wait on cryptography; a decision’s latency is identical with receipts on or off. Asynchronous does not mean best-effort. Unbatched receipts are the durable batching queue: if a batching sweep fails, the next sweep picks up the same receipts. A record’s verification result reports attestationStatus: "timestamp_pending" between signing and batch commitment — typically a minute or two — and "signed" once the full chain verifies.

The exact cryptography

Canonicalization

The signed payload is the envelope’s event object, serialized deterministically:

Object keys are sorted alphabetically, recursively (arrays keep their order; primitives pass through unchanged).
The sorted structure is serialized with compact JSON.stringify — no whitespace.
The signature and hash operate on the UTF-8 bytes of that string.

Hash and signature

payload_hash = SHA-256 over the canonical bytes, hex-encoded.
signature = Ed25519 over the canonical payload bytes themselves — not over the hash.

The most common verification mistake is signing-recipe drift: verifying the Ed25519 signature against the SHA-256 hash, decoding fields as standard base64 instead of base64url, or parsing public_key as a raw 32-byte key instead of SPKI DER. Any one of these makes every genuine receipt appear forged. The sample below matches the real recipe.

Key management

In production the signing key is mandatory — the signer refuses to fall back to an ephemeral key, so a receipt that exists is always verifiable against the published key. Receipts produced by the hardened strategies record which one signed them (a receipt with no recorded strategy was signed by the default strategy), and an optional hardened mode signs every receipt inside the HSM itself so the private key never enters an application process (for those receipts, the signed message is the 32-byte payload_hash digest rather than the canonical bytes — batch roots are signed the same way). The receipt’s stored public_key is authoritative for verification, so key rotation never invalidates history.

Verify with one call (recommended)

Ask the platform to re-derive and re-check the entire attestation chain for a record:

curl "https://api.visiqlabs.com/record/envelopes/9f4c1a3e-8f2b-4c1d-9e5a-2b7c8d0f1a42/verify" \
  -H "Authorization: Bearer <management-token>"

{
  "recordId": "9f4c1a3e-8f2b-4c1d-9e5a-2b7c8d0f1a42",
  "verified": true,
  "attestationPending": false,
  "attestationStatus": "signed",
  "checks": {
    "integrity":       { "pass": true, "detail": "recomputed SHA-256 matches receipt (58a9c1d2e3f40516…)" },
    "leafSignature":   { "pass": true, "detail": "Ed25519 leaf signature valid for the canonical decision payload (env signer)" },
    "merkleInclusion": { "pass": true, "detail": "leaf #142 proven in Merkle root via 8-step recomputed proof" },
    "kmsRootSignature":{ "pass": true, "detail": "chain_hash signature confirmed LIVE by AWS KMS (HSM key active)", "liveKmsVerified": true },
    "timestamp":       { "pass": true, "detail": "RFC-3161 token verified against DigiCert chain; attested 2026-07-03T17:23:12Z", "source": "batch-root" },
    "ingestAnchor":    { "pass": true, "detail": "ingest anchor verified: event == content_hash == receipt (1f6b3c9a2d4e5f70…)" }
  },
  "evidence": {
    "source": "action",
    "decision": "deny",
    "emittedAt": "2026-07-03T17:22:41.118Z",
    "payloadHash": "58a9c1d2e3f40516…",
    "merkleRoot": "b47e2f91c3a8d605…",
    "leafIndex": 142,
    "tsaGenTime": "2026-07-03T17:23:12Z",
    "chainPosition": { "batchSeq": 3121, "prevRoot": "77d1a0be94c2f358…", "chainSigned": true }
  }
}

Checks fail closed: a check that cannot be completed reports pass: false with a reason — never a silent pass — with one deliberate exception: the ingest anchor on legacy records that predate anchor recording. verified is true only when all applicable checks pass. The Merkle inclusion proof is recomputed on demand from the batch’s retained leaf set — it must reproduce the signed root exactly — and the root check performs a live AWS KMS Verify round-trip, confirming the HSM key itself vouches for the signature. These endpoints sit on the management surface: harness keys used by your agents are deliberately confined to the operational SDK routes and receive 403 here. The dashboard’s record verification page runs the identical checks — click any record pill under Harness → Runtime Enforcement. For scripted access, see Platform Automation.

Verify offline (TypeScript)

Receipts also verify with no VisIQ dependency at all — Node’s built-in crypto is enough. Copy the event and receipt fields from the record’s verification page in the dashboard:

import { createHash, createPublicKey, verify } from "node:crypto";

// The envelope's event object, exactly as recorded.
const event = {
  target_app: "stripe",
  action: "issue_refund",
  context: { amount: 500, currency: "USD" },
};

// The receipt fields, as shown on the record's verification page.
const receipt = {
  signature: "<base64url Ed25519 signature>",
  public_key: "<base64url SPKI DER public key>",
  payload_hash: "<64-char hex SHA-256>",
};

// 1. Canonicalize: sort object keys alphabetically, recursively.
//    Arrays keep their order; primitives pass through.
function canonicalize(value: unknown): unknown {
  if (value === null || typeof value !== "object") return value;
  if (Array.isArray(value)) return value.map(canonicalize);
  const sorted: Record<string, unknown> = {};
  for (const key of Object.keys(value).sort()) {
    sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
  }
  return sorted;
}
const canonicalBytes = Buffer.from(JSON.stringify(canonicalize(event)), "utf8");

// 2. The payload hash is SHA-256 over the canonical bytes.
const payloadHash = createHash("sha256").update(canonicalBytes).digest("hex");
if (payloadHash !== receipt.payload_hash) {
  throw new Error("payload hash mismatch — the event was altered");
}

// 3. The Ed25519 signature covers the canonical bytes themselves.
//    Ed25519 uses one-shot verify with algorithm null (no digest step).
const publicKey = createPublicKey({
  key: Buffer.from(receipt.public_key, "base64url"),
  format: "der",
  type: "spki",
});
const ok = verify(
  null,
  canonicalBytes,
  publicKey,
  Buffer.from(receipt.signature, "base64url"),
);
console.log(ok ? "receipt verified" : "SIGNATURE INVALID — record tampered or forged");

This verifies the default signing strategy. A receipt whose recorded signing strategy is the HSM-per-receipt mode signs the 32-byte payload_hash digest instead — substitute Buffer.from(receipt.payload_hash, "hex") as the message in step 3. The one-call endpoint above handles both automatically.

Merkle inclusion and the checkpoint chain

Receipts are batched into an RFC 6962-style Merkle tree with domain-separated hashing:

Leaf hash = SHA-256( 0x00 ‖ payload_hash_bytes )
Node hash = SHA-256( 0x01 ‖ left ‖ right )
An unpaired trailing node is promoted unchanged to the next level — never hashed with a copy of itself.

The batch root is signed once with the HSM-backed key, and one RFC 3161 timestamp covers the root — so a single signature and a single timestamp attest every receipt in the batch via its inclusion proof. That is what makes 100% signing-and-timestamping coverage hold at any decision volume. Batches then form an append-only hash chain: each batch carries a monotonic sequence number, a commitment to the previous batch’s root, and a running accumulator

chain_hash[k] = SHA-256( 0x02 ‖ chain_hash[k-1] ‖ root_hash[k] )

with the batch signature covering chain_hash — so one trusted tip signature vouches for the entire history. Deleting a batch leaves a gap, reordering breaks the accumulator, and editing any root breaks the recomputation. Two management-API endpoints expose this to any authenticated caller (the feed itself is tenant-neutral — it contains only roots, signatures, and counts):

GET /record/checkpoints — the transparency-log checkpoint feed: signed roots, signatures, leaf counts, and timestamp times, newest first. Also browsable in the dashboard under Settings → Checkpoint feed (organization scope).
GET /record/chain/consistency — walks a chain segment and proves, purely by recomputation, that no batch was deleted, reordered, or tampered with.

Checkpoints are additionally published to write-once (WORM) object storage under compliance-mode object locking — an externally held copy that neither VisIQ nor its cloud provider can alter or delete before retention expires. A silent rewrite of history is therefore detectable even by us: the audit trail does not ask you to trust the party that operates it.

RFC 3161 trusted timestamps

Each batch root is countersigned by DigiCert’s timestamp authority. The DER-encoded timestamp token binds the root hash to a time asserted by DigiCert — an independent third party — and verification checks the token against DigiCert’s certificate chain. Combined with the chain above, this proves a decision existed no later than the attested time, on evidence that does not depend on VisIQ’s clocks or word. For long-horizon audits, batches can also carry frozen revocation evidence for the timestamp certificate chain, so tokens remain independently verifiable years later, after certificates expire or responders disappear.

Quickstart

Action Governance

Retrieval Governance

Audit Trail

Discovery

API Examples

Platform Automation

Partners

Decision Receipts

What a receipt contains

When receipts are issued

The exact cryptography

Canonicalization

Hash and signature

Key management

Verify with one call (recommended)

Verify offline (TypeScript)

Merkle inclusion and the checkpoint chain

RFC 3161 trusted timestamps

Next steps

Audit Trail

Platform Automation

​What a receipt contains

​When receipts are issued

​The exact cryptography

​Canonicalization

​Hash and signature

​Key management

​Verify with one call (recommended)

​Verify offline (TypeScript)

​Merkle inclusion and the checkpoint chain

​RFC 3161 trusted timestamps

​Next steps

Audit Trail

Platform Automation

What a receipt contains

When receipts are issued

The exact cryptography

Canonicalization

Hash and signature

Key management

Verify with one call (recommended)

Verify offline (TypeScript)

Merkle inclusion and the checkpoint chain

RFC 3161 trusted timestamps

Next steps