attestive-verify

Standalone verifier for tamper-evident, hash-chained decision logs. Zero runtime dependencies beyond Node's built-in node:crypto.

The problem this solves

Some systems keep a log of decisions an AI agent (or any automated system) made — what it saw, what it decided, when. The hard part isn't writing that log. It's proving, later, to someone who doesn't trust the system that produced it, that the log hasn't been quietly edited, that no entry has been deleted, and that the order hasn't been rearranged.

A hash-chained decision log solves the tampering problem the same way a blockchain or a Git commit history does, without needing any of the distributed-consensus machinery: every record's hash is computed from its own content plus the previous record's hash. Change any field in any past record — even by one character — and its hash no longer matches what gets recomputed from its (now-different) content. Because every later record's previousHash was computed from the original hash, the break propagates forward through the entire rest of the chain. Delete a record from the middle, and the gap in sequence numbers is immediately visible. Reorder two records, and their hash links no longer line up.

This package is the thing that checks all of that. It takes an array of records — however you got them, however they're stored — and tells you whether the chain is intact.

Why this is a separate package with zero dependencies

The verification only actually proves anything if the verifier itself can be trusted independently of whoever produced the log. If verifying required importing the vendor's SDK, calling their API, or trusting their database, you'd be back to "trust us" — exactly what a tamper-evidence claim is supposed to make unnecessary.

So this package:

• Has no dependency on any backend, database, or network call. It is a pure function over an array of JSON-shaped objects.
• Has no dependency on any vendor SDK. Its only import is Node's built-in node:crypto, for SHA-256.
• Can be read in full in a few minutes. There is one file (src/verify-chain.ts) and it does one thing.

You can — and should — read the source before trusting it. That's the point.

Install

npm install attestive-verify

Usage

import { verifyChain } from "attestive-verify";
import fs from "node:fs";

const records = JSON.parse(fs.readFileSync("exported-decisions.json", "utf8"));
const result = verifyChain(records);

if (!result.valid) {
  for (const issue of result.issues) {
    console.error(`sequence ${issue.sequenceNumber} (${issue.recordId}): ${issue.problem}`);
  }
  process.exit(1);
}

console.log(`${result.recordsChecked} records verified, chain intact.`);

What a record looks like

verifyChain expects an array of objects matching this shape (exported from the package as DecisionRecord):

interface DecisionRecord {
  id: string;
  sequenceNumber: number;
  organizationId: string;
  agentId: string;
  decisionType: string;
  inputEvidence: Record<string, unknown>;
  output: unknown;
  humanReviewed: boolean;
  humanReviewerId?: string;
  frameworkCitations: FrameworkCitation[];
  timestamp: string;       // ISO 8601
  previousHash: string;    // hex SHA-256 of the prior record, or 64 zeros for the first
  recordHash: string;      // hex SHA-256 of this record's own content + previousHash
}

If you're generating logs in this shape yourself (not using a companion SDK), the hash for each record is sha256(JSON.stringify(orderedFields)) where orderedFields is every field above except recordHash, in a fixed key order, with humanReviewerId defaulting to null when absent. See computeRecordHash in the source for the exact canonical ordering — it has to match exactly, or a correctly-produced record will fail to verify.

What verifyChain checks

For each record, in ascending sequenceNumber order:

1. Sequence numbers are contiguous, starting at 0. A gap means a record was deleted or two records collided on the same number.
2. previousHash matches the prior record's recordHash (or 64 zeros — the genesis hash — for the very first record). A mismatch means the chain was broken: a record was deleted, reordered, or replaced.
3. recordHash matches what's recomputed from the record's own content. A mismatch means this specific record was edited after it was originally hashed.

The result:

interface VerificationResult {
  valid: boolean;
  recordsChecked: number;
  issues: VerificationIssue[];
}

interface VerificationIssue {
  sequenceNumber: number;
  recordId: string;
  problem: string;
}

An empty array verifies as trivially valid (recordsChecked: 0). Records are sorted by sequenceNumber internally before checking, so feeding them in an arbitrary order doesn't itself cause a false failure — an actual reordering attack is still caught, because it breaks the hash links, not because of input order.

What this deliberately does not do

• No network calls, ever.
• No opinion on storage — bring your own database, file, or JSON export.
• No opinion on whether a decision was correct — this checks integrity (did it happen, unaltered, in this order), not judgment.
• No mutation — verifyChain never writes anything, including to the records you pass in.

Development

npm install
npm test         # runs against source directly (tests/*.test.ts)
npm run typecheck
npm run build    # compiles src/ to dist/, then sanity-checks the compiled output

Worth knowing if you're modifying this package inside its parent monorepo (Attestive): this package's hashing logic is a deliberate standalone copy of the logic used to write records elsewhere in that project (copied, not imported — importing would defeat the point of having zero dependencies). A drift check guarding against the two copies silently diverging exists, but it lives in the parent monorepo's own tests/ directory (tests/verify-chain-cross-check.test.ts), not in this package — it imports the parent's SDK code directly, which only exists there, so it can't live anywhere that git subtree split would carry into this standalone repo. If you're working from a clone of this repo alone, that check isn't something you'll see or need to run; it's a monorepo-side safeguard for whoever maintains both copies in sync.

License

MIT — see LICENSE.