{"_id":"@577-industries/hashchain-audit","name":"@577-industries/hashchain-audit","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@577-industries/hashchain-audit","version":"1.0.0","description":"Tamper-evident audit trail with SHA-256 hash chaining, Ed25519 signatures, and Merkle tree anchoring","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit"},"keywords":["audit","hash-chain","merkle-tree","ed25519","tamper-evident","cryptographic","ledger","integrity"],"author":{"name":"577 Industries"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/577-industries/hashchain-audit.git"},"homepage":"https://www.577industries.com/forge","devDependencies":{"@types/node":"^25.4.0","tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@577-industries/hashchain-audit@1.0.0","gitHead":"593325866611d0676242c93fe63d6083cc35d242","bugs":{"url":"https://github.com/577-industries/hashchain-audit/issues"},"_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-jQ0WFPG9A2ZwxrZrk7+KAG462cbPTDWCisXTvSwuBOP4EgRpWgYRTIQRR2R3Uu+nF4DMf/utOBMKbuz6c2vJ4g==","shasum":"f437a27fb7121a066792c7dc7fbb47a5faf3a442","tarball":"https://registry.npmjs.org/@577-industries/hashchain-audit/-/hashchain-audit-1.0.0.tgz","fileCount":7,"unpackedSize":43440,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAt+bftP/zMb9WpxYxoG3KZQUXulAOJrFk5A3JVrkdtAAiEA6jd48v4bWs/N2+ir34mxsfU9umo73Y6Lp5mgZpK1Gsk="}]},"_npmUser":{"name":"577industries","email":"t.waweru@577industries.com"},"directories":{},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hashchain-audit_1.0.0_1773252949196_0.036074071555814324"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T18:15:49.045Z","1.0.0":"2026-03-11T18:15:49.401Z","modified":"2026-03-11T18:15:49.733Z"},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"description":"Tamper-evident audit trail with SHA-256 hash chaining, Ed25519 signatures, and Merkle tree anchoring","homepage":"https://www.577industries.com/forge","keywords":["audit","hash-chain","merkle-tree","ed25519","tamper-evident","cryptographic","ledger","integrity"],"repository":{"type":"git","url":"git+https://github.com/577-industries/hashchain-audit.git"},"author":{"name":"577 Industries"},"bugs":{"url":"https://github.com/577-industries/hashchain-audit/issues"},"license":"Apache-2.0","readme":"# @577-industries/hashchain-audit\r\n\r\n[![npm version](https://img.shields.io/npm/v/@577-industries/hashchain-audit)](https://www.npmjs.com/package/@577-industries/hashchain-audit)\r\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\r\n\r\nA 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`.\r\n\r\nImplements the core algorithm described in the **\"Hash-Chained Audit Ledger\"** patent (March 2026) by 577 Industries.\r\n\r\n## How It Works\r\n\r\n```\r\n  Entry N-1          Entry N            Verification\r\n  ─────────         ─────────          ─────────────\r\n  hash(N-1) ──────► prevHash           Recompute each\r\n                    action    ──┐       hash from its\r\n                    actor       ├─► SHA-256 ──► entryHash\r\n                    timestamp   │               │\r\n                    details   ──┘           Ed25519 ──► signature\r\n                                                │\r\n                              Merkle Root ◄─────┘ (periodic anchor)\r\n```\r\n\r\n## Quick Start\r\n\r\n```bash\r\nnpm install @577-industries/hashchain-audit\r\n```\r\n\r\n```typescript\r\nimport { AuditLedger, generateKeyPair } from \"@577-industries/hashchain-audit\";\r\n\r\n// Generate signing keys (or provide your own PEM)\r\nconst keys = generateKeyPair();\r\nconst ledger = new AuditLedger({ privateKey: keys.privateKey });\r\n\r\n// Append entries — each is hash-chained to the previous\r\nawait ledger.append(\"user.login\", \"alice@example.com\");\r\nawait ledger.append(\"record.update\", \"alice@example.com\", {\r\n  entityType: \"invoice\",\r\n  entityId: \"inv-123\",\r\n  details: { amount: 5000 },\r\n});\r\n\r\n// Verify chain integrity\r\nconst result = await ledger.verify();\r\nconsole.log(result.valid);   // true\r\nconsole.log(result.checked); // 2\r\n\r\n// Create a Merkle anchor for range verification\r\nconst anchor = await ledger.createAnchor();\r\nconst anchorResult = await ledger.verifyAnchor(anchor);\r\nconsole.log(anchorResult.valid); // true\r\n```\r\n\r\n## API Reference\r\n\r\n### `AuditLedger`\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `new AuditLedger(config?)` | Create a ledger with optional signing key and storage adapter |\r\n| `append(action, actor, options?)` | Append a hash-chained (and optionally signed) entry |\r\n| `verify()` | Verify the entire chain's integrity |\r\n| `createAnchor()` | Create a Merkle tree anchor over recent entries |\r\n| `verifyAnchor(anchor)` | Verify a Merkle anchor by recomputing the root |\r\n| `getEntries(options?)` | Retrieve entries with optional limit/offset |\r\n\r\n### Crypto Utilities\r\n\r\n| Function | Description |\r\n|----------|-------------|\r\n| `generateKeyPair()` | Generate Ed25519 key pair (PEM-encoded) |\r\n| `computeHash(...)` | SHA-256 pipe-delimited hash |\r\n| `signHash(hash, key)` | Ed25519 signature |\r\n| `verifySignature(hash, sig, key)` | Verify Ed25519 signature |\r\n\r\n### Pluggable Storage\r\n\r\nImplement `StorageAdapter` for custom persistence:\r\n\r\n```typescript\r\ninterface StorageAdapter {\r\n  getLastEntry(): Promise<AuditEntry | null>;\r\n  append(entry: AuditEntry): Promise<void>;\r\n  getEntries(options?): Promise<AuditEntry[]>;\r\n  getEntriesSince(entryId: string): Promise<AuditEntry[]>;\r\n}\r\n```\r\n\r\nBuilt-in: `InMemoryStorage` (default).\r\n\r\n## Architecture\r\n\r\nThree cryptographic layers:\r\n\r\n1. **Hash Chain** — Each entry's hash includes the previous entry's hash, creating a tamper-evident chain\r\n2. **Digital Signatures** — Ed25519 signatures on each hash prove authenticity\r\n3. **Merkle Anchors** — Periodic Merkle tree roots enable efficient range verification\r\n\r\nBased on the [\"Hash-Chained Audit Ledger\" patent](https://www.577industries.com/forge) by 577 Industries.\r\n\r\n---\r\n\r\nExtracted from [FORGE OS](https://www.577industries.com) by **577 Industries**.\r\n","readmeFilename":"README.md","_rev":"1-27f3c93c6302d1a9f5b1ca66920d16ad"}