@gtcx/audit

Hash-chained, tamper-evident audit logging for the GTCX protocol stack.

Installation

pnpm add @gtcx/audit

API

createPersistentAuditLog({ store, signer? })

Creates a persistent audit log backed by a pluggable AuditStore. Each entry is hash-chained to the previous one for tamper detection. Optionally signs entries with a CryptoProvider.

import { createPersistentAuditLog, MemoryAuditStore } from '@gtcx/audit';

const log = createPersistentAuditLog({ store: new MemoryAuditStore() });

const entry = await log.append({
  timestamp: Date.now(),
  source: 'trade-service',
  actor: 'did:gtcx:org_acme',
  action: 'asset.transfer',
  resource: 'asset:gold-001',
  outcome: 'success',
});

log.verify(fromSequence?, toSequence?)

Verifies hash-chain integrity across a range of audit entries.

const result = await log.verify();
// { valid: true, entriesVerified: 42 }

log.checkpoint(signer?)

Creates a signed checkpoint capturing the current root hash and entry count.

MemoryAuditStore

In-memory AuditStore implementation for testing and development.

createFileAuditStore(config)

File-system-backed audit store for persistent local storage.

createEncryptedAuditStore(config)

Wraps any AuditStore with AES-256-GCM encryption at rest.

createPostgresAuditStore({ client | pool, schemaName?, tableName? })

Postgres-backed AuditStore for distributed/production deployments.

• Uses explicit transactions for append()
• Supports client (single connection) or pool (recommended)
• Supports range reads via getRange() for efficient chain verification

Testing

pnpm vitest run packages/audit/

License

BSL 1.1 -- converts to Apache 2.0 on January 1, 2030.