sealtrail

sealtrail

Tamper-proof audit trails for developers. Log, verify, and prove every action with cryptographic hash chains.

Installation

npm install sealtrail
# or
yarn add sealtrail
# or
pnpm add sealtrail

Quick Start

import { SealTrail } from "sealtrail";

const st = new SealTrail({ apiKey: "stl_live_..." });

// Log an audit event
const event = await st.events.log({
  actor: "user_123",
  action: "document.signed",
  resource: "doc_456",
  context: { ip: "192.168.1.1" },
});

console.log(event.hash); // cryptographic proof

Features

• Zero dependencies — uses globalThis.fetch (Node 18+, Bun, Deno)
• Fully typed — complete TypeScript definitions
• Automatic retries — exponential backoff on 429, 5xx, and 409 (chain conflicts)
• Auto-pagination — async iterator for large result sets
• Typed errors — catch specific error classes (RateLimitError, ValidationError, etc.)

API Reference

Client

const st = new SealTrail({
  apiKey: "stl_live_...",     // required
  baseUrl: "https://...",     // default: "https://api.sealtrail.dev"
  timeout: 30_000,            // request timeout in ms
  maxRetries: 3,              // retry attempts on retryable errors
  debug: false,               // log requests to console.debug
  fetch: customFetch,         // custom fetch for edge runtimes
});

Events

// Log an event
const event = await st.events.log({
  actor: "user_123",
  action: "document.signed",
  resource: "doc_456",        // optional
  context: { ip: "..." },    // optional metadata
  chain: "documents",         // optional, default: "default"
});

// Get a single event
const event = await st.events.get("evt_abc123");

// List events with filters
const { data, nextCursor } = await st.events.list({
  actor: "user_123",
  action: "document.signed",
  limit: 50,
  after: "2025-01-01T00:00:00Z",
});

// Auto-paginate through all events
for await (const event of st.events.listAutoPaginate({ actor: "user_123" })) {
  console.log(event.id, event.action);
}

// Verify an event's cryptographic integrity
const result = await st.events.verify("evt_abc123");
console.log(result.valid);       // true/false
console.log(result.chainIntact); // hash chain verification

Export

// Export events as CSV for compliance reporting
const csv = await st.events.export({
  format: "csv",
  after: "2026-01-01T00:00:00Z",
  before: "2026-04-01T00:00:00Z",
  actor: "user_123",           // optional filter
});
// csv is a raw string: "id,actor,action,...\nevt_abc,user_123,..."

// Export events as JSON with metadata
const json = await st.events.export({
  format: "json",
  after: "2026-01-01T00:00:00Z",
  before: "2026-04-01T00:00:00Z",
});
console.log(json.export.count);  // number of events
console.log(json.data);          // AuditEvent[]

Chains

// List all chains
const chains = await st.chains.list();

// Get chain status
const chain = await st.chains.status("chain_id");
console.log(chain.eventCount, chain.lastPosition);

Error Handling

import { SealTrail, RateLimitError, ValidationError } from "sealtrail";

try {
  await st.events.log({ actor: "user_123", action: "test" });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfter);
  } else if (err instanceof ValidationError) {
    console.log("Invalid input:", err.details);
  }
}

All error classes: AuthenticationError (401), ForbiddenError (403), NotFoundError (404), ValidationError (400), RateLimitError (429), QuotaExceededError (429), ConflictError (409), InternalError (5xx).

Requirements

• Node.js 18+ / Bun / Deno (any runtime with globalThis.fetch)
• Zero dependencies

Documentation

Full docs and guides at sealtrail.dev/docs

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT - Zero Loop Labs