Home / Reference implementations / Evidence receipt

Evidence receipt

Draft Illustrative reference — implements the Stable receipt format v1. Not a production implementation (in-memory chain, no persistence).

Receipt issuance and verification for the evidence model: canonical JSON, SHA-256 hashing, hash-chained receipts, and the client-side verification protocol. Verification needs no trusted server — only the receipt data and the spec.

Illustrative referenceevidence-receipt.js — save as one file and run with node evidence-receipt.js.
// Illustrative reference: evidence receipt issuance + verification (Node.js, stdlib only).
// Implements receipt format v1 from the evidence model spec.
const crypto = require("node:crypto");

function sha256Hex(text) {
  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
}

// Canonical JSON: sorted keys at every level, no insignificant whitespace.
function canonicalize(value) {
  if (Array.isArray(value)) {
    return "[" + value.map(canonicalize).join(",") + "]";
  }
  if (value !== null && typeof value === "object") {
    const keys = Object.keys(value).sort();
    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize(value[k])).join(",") + "}";
  }
  return JSON.stringify(value);
}

function receiptHash(receipt) {
  const { receipt_hash, ...body } = receipt; // hash covers everything except itself
  return sha256Hex(canonicalize(body));
}

// One append-only chain per tenant; here a single in-memory chain for the demo.
const chain = [];

function issueReceipt(fields) {
  const prev = chain.length > 0 ? chain[chain.length - 1].receipt_hash : null;
  const receipt = {
    receipt_id: "rcpt_" + crypto.randomBytes(8).toString("hex"),
    receipt_format: "ametios.receipt/v1",
    prev_receipt_hash: prev,
    ...fields,
  };
  receipt.receipt_hash = receiptHash(receipt);
  chain.push(receipt);
  return receipt;
}

function verifyReceipt(receipt) {
  return receiptHash(receipt) === receipt.receipt_hash;
}

function verifyChain(receipts) {
  for (let i = 0; i < receipts.length; i++) {
    if (!verifyReceipt(receipts[i])) {
      return { ok: false, at: i, reason: "bad receipt hash" };
    }
    const expectedPrev = i === 0 ? null : receipts[i - 1].receipt_hash;
    if (receipts[i].prev_receipt_hash !== expectedPrev) {
      return { ok: false, at: i, reason: "chain link broken" };
    }
  }
  return { ok: true };
}

// --- Demo: issue three receipts, verify the chain, then show tamper detection ---
function demo() {
  const base = {
    tenant: { organization: "org_local", workspace: "ws_dev", environment: "staging" },
    actor: { actor_id: "svc_demo", actor_class: "service" },
    policy_bundle: "demo",
    policy_version: "0.1.0",
  };
  issueReceipt({ ...base, action_id: "act_1", decision: "allow" });
  issueReceipt({ ...base, action_id: "act_2", decision: "deny" });
  issueReceipt({ ...base, action_id: "act_3", decision: "allow" });

  console.log("chain of", chain.length, "receipts; verify:", JSON.stringify(verifyChain(chain)));

  // Tamper with the middle receipt: the chain must fail at index 1 or 2.
  const tampered = JSON.parse(JSON.stringify(chain));
  tampered[1].decision = "allow";
  console.log("tampered chain verify:", JSON.stringify(verifyChain(tampered)));
}

if (require.main === module) demo();

module.exports = { canonicalize, receiptHash, issueReceipt, verifyReceipt, verifyChain };

Used by the quickstart: step 6 of the quickstart verifies a saved receipt with verifyReceipt from this file. Related: evidence model (the format this implements), governed webhook (which issues receipts).