chainproof 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,233 @@
+# chainproof
+
+Hash-chained, Ed25519-signed append-only logs for TypeScript. Tamper-evident audit trails as a reusable primitive.
+
+## Why chainproof?
+
+Any system that needs a provable, tamper-evident history of events — audit logs, receipt chains, compliance trails, change tracking — needs three things:
+
+1. **Hash linking** — each entry commits to the previous one, so deletions and reordering are detectable
+2. **Signatures** — each entry is cryptographically signed, so forgery requires the private key
+3. **Verification** — anyone with the public key can verify the entire chain without trusting the writer
+
+chainproof gives you all three in a single library. No database required — just append entries and verify.
+
+## Install
+
+```bash
+npm install chainproof
+```
+
+## Quick Start
+
+```typescript
+import { ChainLog, generateKeyPair } from 'chainproof'
+
+// Generate Ed25519 key pair
+const keyPair = generateKeyPair().unwrap()
+
+// Create a chain and append entries
+const chain = new ChainLog(keyPair)
+
+chain.append({ tool: 'Edit', file: 'server.ts', user: 'alice' })
+chain.append({ tool: 'Bash', command: 'pnpm test', user: 'alice' })
+chain.append({ tool: 'Deploy', target: 'production', user: 'bob' })
+
+// Verify the entire chain
+const result = chain.verifyIntegrity()
+console.log(result)
+// { valid: true, chainLength: 3, lastValidSeq: 2, message: 'Chain verified: 3 entries' }
+
+// Tamper with an entry — verification catches it
+const tampered = chain.entries.map((e, i) =>
+  i === 0 ? { ...e, data: { tool: 'FORGED', file: 'evil.ts', user: 'alice' } } : e
+)
+const check = ChainLog.verify(tampered, keyPair.publicKey)
+console.log(check.valid)   // false
+console.log(check.message) // 'Seq 0: invalid signature'
+```
+
+## How It Works
+
+Each entry in the chain contains:
+
+| Field | Description |
+|-------|-------------|
+| `id` | UUIDv7 (time-ordered, RFC 9562) |
+| `seq` | Monotonic sequence number |
+| `timestamp` | Unix timestamp |
+| `data` | Your payload (generic `T`) |
+| `dataHash` | SHA-256 of canonical JSON of `data` |
+| `prevHash` | SHA-256 of previous entry's canonical bytes |
+| `signature` | Ed25519 signature (base64) |
+
+**Genesis**: The first entry links to `SHA-256("chainproof:genesis")`.
+
+**Canonical form**: Entries are serialized with sorted keys and the `signature` field excluded before hashing and signing. This ensures deterministic verification regardless of JSON key ordering.
+
+**Tamper detection**:
+- Modify any field → signature verification fails
+- Delete an entry → next entry's `prevHash` no longer matches
+- Reorder entries → hash chain breaks
+- Forge an entry → requires the private key
+
+## Usage
+
+### Chain Operations
+
+```typescript
+import { ChainLog, generateKeyPair } from 'chainproof'
+
+const keyPair = generateKeyPair().unwrap()
+const chain = new ChainLog<{ action: string; user: string }>(keyPair)
+
+// Append returns Result<ChainEntry<T>, ChainError>
+const entry = chain.append({ action: 'create', user: 'alice' })
+if (entry.isOk()) {
+  console.log(entry.value.id)        // '019d1263-...'
+  console.log(entry.value.seq)       // 0
+  console.log(entry.value.signature) // 'base64...'
+}
+
+// Access entries
+console.log(chain.length)    // 1
+console.log(chain.entries)   // readonly ChainEntry<T>[]
+console.log(chain.lastHash)  // SHA-256 of last entry
+```
+
+### Verification
+
+```typescript
+// Verify using the chain's own key pair
+const result = chain.verifyIntegrity()
+
+// Or verify externally with just the public key
+const result = ChainLog.verify(entries, publicKey)
+
+// Result shape
+// { valid: boolean, chainLength: number, lastValidSeq: number, message: string }
+```
+
+### JSONL Serialization
+
+```typescript
+// Serialize to JSONL (one JSON entry per line)
+const jsonl = chain.toJsonl()
+
+// Restore from JSONL
+const restored = ChainLog.fromJsonl(jsonl, keyPair)
+if (restored.isOk()) {
+  console.log(restored.value.length) // same as original
+}
+```
+
+### File Storage
+
+```typescript
+import { appendToFile, readFromFile, saveChainToFile, loadChainFromFile } from 'chainproof'
+
+// Append entries one at a time (ideal for live logging)
+const entry = chain.append({ action: 'deploy' }).unwrap()
+await appendToFile('/var/log/audit.jsonl', entry)
+
+// Read entries from file
+const entries = await readFromFile('/var/log/audit.jsonl')
+
+// Save/load entire chain
+await saveChainToFile('/var/log/audit.jsonl', chain)
+const loaded = await loadChainFromFile('/var/log/audit.jsonl', keyPair)
+```
+
+### Key Management
+
+```typescript
+import {
+  generateKeyPair,
+  saveKeyPair,
+  loadKeyPair,
+  exportPublicKey,
+  importPublicKey
+} from 'chainproof'
+
+// Generate and save keys (private key gets 0o600 permissions)
+const keyPair = generateKeyPair().unwrap()
+await saveKeyPair(keyPair, '/etc/myapp/keys')
+// Creates: /etc/myapp/keys/chain.key (private, 0o600)
+//          /etc/myapp/keys/chain.pub (public, 0o644)
+
+// Load keys from disk
+const loaded = await loadKeyPair('/etc/myapp/keys')
+
+// Export public key for external verifiers
+const pem = exportPublicKey(keyPair.publicKey)
+// Share this PEM — anyone can verify the chain without the private key
+
+// Import a public key for verification
+const pubKey = importPublicKey(pem).unwrap()
+const result = ChainLog.verify(entries, pubKey)
+```
+
+### Low-Level API
+
+```typescript
+import { sha256, sign, verify, canonicalJson, createEntry, entryHash, genesisHash, uuid7 } from 'chainproof'
+
+// SHA-256 hashing
+sha256('hello') // '2cf24dba...'
+
+// Canonical JSON (sorted keys, deterministic)
+canonicalJson({ z: 1, a: 2 }) // '{"a":2,"z":1}'
+
+// Ed25519 sign/verify
+const sig = sign(keyPair.privateKey, 'data').unwrap()
+const valid = verify(keyPair.publicKey, 'data', sig).unwrap() // true
+
+// UUIDv7 (time-ordered)
+uuid7() // '019d1263-7a2b-7c58-...'
+
+// Manual entry creation
+const entry = createEntry({ action: 'test' }, 0, genesisHash(), keyPair)
+const hash = entryHash(entry.unwrap())
+```
+
+## Error Handling
+
+All fallible operations return `Result<T, ChainError>` or `ResultAsync<T, ChainError>` from [@valencets/resultkit](https://github.com/valencets/resultkit).
+
+```typescript
+interface ChainError {
+  readonly code: ChainErrorCode
+  readonly message: string
+}
+
+// Error codes: INVALID_KEY, SIGN_FAILED, VERIFY_FAILED, CHAIN_BROKEN, IO_FAILED, PARSE_FAILED
+```
+
+## Cryptographic Primitives
+
+| Primitive | Purpose | Implementation |
+|-----------|---------|----------------|
+| **SHA-256** | Hash chain links, data hashing | `node:crypto` (built-in) |
+| **Ed25519** | Entry signing and verification | `node:crypto` (built-in) |
+| **UUIDv7** | Time-ordered entry IDs | Custom (RFC 9562) |
+| **Base64** | Signature encoding | Built-in |
+
+No native addons. No npm crypto dependencies. Just `node:crypto`.
+
+## Design Principles
+
+1. **Append-only** — entries are never modified or deleted
+2. **Externally verifiable** — anyone with the public key can verify (no shared secret)
+3. **Deterministic** — canonical JSON serialization ensures consistent hashing
+4. **Minimal** — one runtime dependency (`@valencets/resultkit`)
+5. **Generic** — `ChainLog<T>` works with any serializable payload type
+
+## Requirements
+
+- Node.js >= 22
+- TypeScript >= 5.9
+- ESM only (`"type": "module"`)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chainproof",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Hash-chained, Ed25519-signed append-only logs for TypeScript. Tamper-evident audit trails as a reusable primitive.",
   "exports": {