@vorionsys/proof-plane

Immutable audit trail for AI agent operations. Provides hash-chained, cryptographically signed event logging for compliance, debugging, and trust verification.

Installation

npm install @vorionsys/proof-plane

Quick Start

import { createProofPlane, createInMemoryEventStore } from '@vorionsys/proof-plane';

const store = createInMemoryEventStore();
const proofPlane = createProofPlane({
  signedBy: 'my-service',
  store,
});

// Log events
await proofPlane.logIntentReceived(intent);
await proofPlane.logDecisionMade(decision);

// Query events by correlation ID
const trace = await proofPlane.getTrace(correlationId);

// Verify hash chain integrity
const verification = await proofPlane.verifyChain();
console.log(verification.valid); // true

Features

• Hash-Chained Events: Every event links to the previous via SHA-256, forming a tamper-evident chain
• Cryptographic Signatures: Ed25519 event signing with key pair generation and batch verification
• Pluggable Storage: Abstract ProofEventStore interface - bring your own database
• Event Emitter: Typed event system with batch emit support
• Trace Queries: Retrieve full event traces by correlation ID
• Chain Verification: Verify integrity of the entire hash chain with detailed reports
• API Routes: Pre-built Express/Fastify route handlers for proof endpoints

Subpath Imports

// Core proof plane
import { createProofPlane, ProofPlane } from '@vorionsys/proof-plane';

// Event stores
import { InMemoryEventStore } from '@vorionsys/proof-plane/events';

// Proof plane internals
import { ProofPlane } from '@vorionsys/proof-plane/proof-plane';

// API route handlers
import { createProofRoutes } from '@vorionsys/proof-plane/api';

API Reference

ProofPlane

const plane = createProofPlane({
  signedBy: 'service-name',   // Identifier for the signing service
  store: eventStore,           // ProofEventStore implementation
});

// Log lifecycle events
await plane.logIntentReceived(intent);
await plane.logDecisionMade(decision);

// Query
const trace = await plane.getTrace(correlationId);
const events = await plane.queryEvents({ limit: 100, offset: 0 });

// Verify chain
const result = await plane.verifyChain();
// { valid: boolean, checkedCount: number, errors: string[] }

Hash Chain

import {
  sha256,
  computeEventHash,
  verifyEventHash,
  verifyChain,
  verifyChainWithDetails,
} from '@vorionsys/proof-plane';

const hash = sha256(data);
const eventHash = computeEventHash(event);
const isValid = verifyEventHash(event);
const chainResult = verifyChainWithDetails(events);

Event Signatures

import {
  generateSigningKeyPair,
  signEvent,
  verifyEventSignature,
  EventSigningService,
} from '@vorionsys/proof-plane';

// Generate keys
const keyPair = await generateSigningKeyPair();

// Sign an event
const signature = await signEvent(event, keyPair.privateKey);

// Verify
const isValid = await verifyEventSignature(event, signature, keyPair.publicKey);

// Or use the service
const signer = createSigningService({ keyPair });
const signed = await signer.sign(event);

Event Store

Implement the ProofEventStore interface for custom storage:

import type { ProofEventStore, EventQueryOptions } from '@vorionsys/proof-plane';

class MyEventStore implements ProofEventStore {
  async append(event) { /* ... */ }
  async getByCorrelationId(id) { /* ... */ }
  async query(options: EventQueryOptions) { /* ... */ }
  async getStats() { /* ... */ }
  async getChain(options) { /* ... */ }
}

API Routes

import { createProofRoutes, registerProofRoutes } from '@vorionsys/proof-plane';

// Fastify
registerProofRoutes(fastifyApp, { store });

// Express
import { createProofExpressRouter } from '@vorionsys/proof-plane';
app.use('/proof', createProofExpressRouter({ store }));

TypeScript

import type {
  ProofPlaneConfig,
  ProofPlaneLogger,
  ProofEventStore,
  EventQueryOptions,
  EventQueryResult,
  EventStats,
  EventEmitterConfig,
  EventListener,
  EmitResult,
  ChainVerificationResult,
  SigningKeyPair,
  SignatureVerificationResult,
} from '@vorionsys/proof-plane';

License

MIT