Docs · Integrity

Decision ledger integrity (sha256 hash chain)

Every JSON ledger export carries a sha256 chain over its rows. Recompute the chain in order and compare the final hash to chainTip. Any row that was added, removed, reordered, or edited after export will produce a different chainTip.

Tamper-evident decision ledger

What this protects against

CSV exports are convenient but easy to mutate after the fact. The JSON export adds a self-contained integrity model so auditors and SIEM ingest can prove the file they received is the file Axiru produced.

  • Detect silent row edits (decision flipped from BLOCK to ALLOW, actor renamed, timestamp adjusted).
  • Detect row insertion or deletion anywhere in the export.
  • Detect reordering, since the chain is sensitive to position.
  • Pin the exact export instance via the exportId and chainTip in your case management system.

How to get a JSON export

From the audit-log page, choose Decision ledger → JSON + hash chain. Programmatically:

GET /api/exports/ledger?format=json
            &from=2026-05-01&to=2026-05-31

Response headers:
  content-type: application/json; charset=utf-8
  content-disposition: attachment; filename="axiru-ledger-2026-05-24.json"
  x-axiru-chain-tip: 9f1e7c...
  x-axiru-export-id: 4b2a09d8c1f3e7a6

Envelope shape

{
  "exportId": "4b2a09d8c1f3e7a6",
  "generatedAt": "2026-05-24T12:00:00.000Z",
  "orgId": "org_...",
  "window": { "from": "2026-05-01", "to": "2026-05-31" },
  "integrity": {
    "algorithm": "sha256-chain-v1",
    "chainTip": "9f1e7c...",
    "rowCount": 312,
    "verificationNote": "Each row's hash = sha256(prevHash + '|' + canonical(row)). ..."
  },
  "rows": [
    {
      "intent": "intent_...",
      "policy_evaluation": "Refund policy v3 • match: amount_over_5k",
      "decision": "REQUIRE_APPROVAL",
      "actor": "agent_billing_bot",
      "timestamp": "2026-05-01T09:14:22.000Z",
      "execution_result": "queued_for_approval",
      "prevHash": "",
      "hash": "a1b2c3..."
    }
  ]
}

Canonical row form

Before hashing, each row is reduced to a deterministic string with a fixed field order, joined by the pipe character:

canonical(row) =
  id | timestamp | decision | actor | policyLabel | matchedRule | executionResult

The order is fixed. Reordering fields, renaming them, or changing any value produces a different canonical string and therefore a different hash.

Chaining algorithm

prevHash = ""                       // first row
for row in rows (chronological order):
  thisHash = sha256( prevHash + "|" + canonical(row) )
  row.prevHash = prevHash
  row.hash     = thisHash
  prevHash     = thisHash

chainTip = prevHash                  // (or sha256("") if rows is empty)

Verification example (Node.js)

import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";

const envelope = JSON.parse(readFileSync("axiru-ledger.json", "utf8"));

function canonical(r) {
  return [
    r.intent,
    r.timestamp,
    r.decision,
    r.actor,
    // policyLabel and matchedRule are joined in policy_evaluation as
    // "<label> • <rule>", split on the separator to recover them.
    r.policy_evaluation.split(" • ")[0],
    r.policy_evaluation.split(" • ").slice(1).join(" • "),
    r.execution_result,
  ].join("|");
}

let prev = "";
for (const row of envelope.rows) {
  if (row.prevHash !== prev) {
    throw new Error("chain break: prevHash mismatch at " + row.intent);
  }
  const want = createHash("sha256").update(prev + "|" + canonical(row)).digest("hex");
  if (row.hash !== want) {
    throw new Error("row tampered: " + row.intent);
  }
  prev = row.hash;
}

const chainTip = prev || createHash("sha256").update("").digest("hex");
if (chainTip !== envelope.integrity.chainTip) {
  throw new Error("chainTip mismatch, export is not intact");
}

console.log("ok: " + envelope.rows.length + " rows verified, chainTip " + chainTip);

Scope and honest limits

  • Software-only integrity. This is a Merkle-style chain inside the exported file. It is not a notarized blockchain commitment. Customers who need external notarization can submit the chainTip to Sigstore, Chronicle, an internal transparency log, or a timestamping authority.
  • Replay requires the rows. Verification needs the same row set the export was produced from. The chain detects changes within the export, not changes to the underlying data that happened before the export was generated.
  • Stable ordering. Rows are sorted chronologically before hashing. Two exports of the same window should produce the same chainTip if and only if the underlying decision rows are identical.
  • Algorithm tag. The envelope declares algorithm: "sha256-chain-v1". Future algorithms will use a new tag. Always check it before verifying.

Suggested SIEM ingest pattern

  1. On ingest, read x-axiru-chain-tip and x-axiru-export-id from the response headers and store them alongside the file.
  2. Verify the chain immediately and reject the file if verification fails.
  3. Index each row in your SIEM with its hash and prevHash for downstream cross-checks.
  4. Optional: submit chainTip to an external transparency log so two parties can prove which export they each hold.

See also: Dashboard → Audit log for the in-app download buttons, and Trust overview for the broader security model.

Next step

Export, verify, retain.

Every JSON ledger export carries its own integrity proof. Hand it to your auditor with the verification snippet, no Axiru round-trip required.

Start with a free replay. Turn on live enforcement later.

We use cookies for analytics and marketing measurement. You can reject non-essential cookies at any time.

Privacy policy