@577-industries/hashchain-audit

A tamper-evident audit trail using three cryptographic layers: SHA-256 hash chaining, Ed25519 digital signatures, and Merkle tree anchoring. Zero runtime dependencies — uses Node.js built-in crypto.

Implements the core algorithm described in the "Hash-Chained Audit Ledger" patent (March 2026) by 577 Industries.

How It Works

  Entry N-1          Entry N            Verification
  ─────────         ─────────          ─────────────
  hash(N-1) ──────► prevHash           Recompute each
                    action    ──┐       hash from its
                    actor       ├─► SHA-256 ──► entryHash
                    timestamp   │               │
                    details   ──┘           Ed25519 ──► signature
                                                │
                              Merkle Root ◄─────┘ (periodic anchor)

Quick Start

npm install @577-industries/hashchain-audit

import { AuditLedger, generateKeyPair } from "@577-industries/hashchain-audit";

// Generate signing keys (or provide your own PEM)
const keys = generateKeyPair();
const ledger = new AuditLedger({ privateKey: keys.privateKey });

// Append entries — each is hash-chained to the previous
await ledger.append("user.login", "[email protected]");
await ledger.append("record.update", "[email protected]", {
  entityType: "invoice",
  entityId: "inv-123",
  details: { amount: 5000 },
});

// Verify chain integrity
const result = await ledger.verify();
console.log(result.valid);   // true
console.log(result.checked); // 2

// Create a Merkle anchor for range verification
const anchor = await ledger.createAnchor();
const anchorResult = await ledger.verifyAnchor(anchor);
console.log(anchorResult.valid); // true

API Reference

AuditLedger

| Method | Description | |--------|-------------| | new AuditLedger(config?) | Create a ledger with optional signing key and storage adapter | | append(action, actor, options?) | Append a hash-chained (and optionally signed) entry | | verify() | Verify the entire chain's integrity | | createAnchor() | Create a Merkle tree anchor over recent entries | | verifyAnchor(anchor) | Verify a Merkle anchor by recomputing the root | | getEntries(options?) | Retrieve entries with optional limit/offset |

Crypto Utilities

| Function | Description | |----------|-------------| | generateKeyPair() | Generate Ed25519 key pair (PEM-encoded) | | computeHash(...) | SHA-256 pipe-delimited hash | | signHash(hash, key) | Ed25519 signature | | verifySignature(hash, sig, key) | Verify Ed25519 signature |

Pluggable Storage

Implement StorageAdapter for custom persistence:

interface StorageAdapter {
  getLastEntry(): Promise<AuditEntry | null>;
  append(entry: AuditEntry): Promise<void>;
  getEntries(options?): Promise<AuditEntry[]>;
  getEntriesSince(entryId: string): Promise<AuditEntry[]>;
}

Built-in: InMemoryStorage (default).

Architecture

Three cryptographic layers:

1. Hash Chain — Each entry's hash includes the previous entry's hash, creating a tamper-evident chain
2. Digital Signatures — Ed25519 signatures on each hash prove authenticity
3. Merkle Anchors — Periodic Merkle tree roots enable efficient range verification

Based on the "Hash-Chained Audit Ledger" patent by 577 Industries.

Extracted from FORGE OS by 577 Industries.