Septor

Immutable hash-chained audit trails for insurance compliance.

Septor provides a tamper-evident event log where every event is cryptographically linked to its predecessor using SHA-256 hash chains. If any event is modified or deleted, chain verification fails.

Install

npm install septor

SDK Usage

import { Septor } from 'septor';

const septor = new Septor({
  apiUrl: 'https://septor.insureco.io',
  namespace: 'flood-rater'
});

Emit an Event

const result = await septor.emit('policy.created', {
  entityId: 'POL-2024-001',
  data: {
    premium: 1200,
    coverage: 'comprehensive',
    holder: 'Acme Corp'
  },
  metadata: {
    who: '[email protected]',
    why: 'New policy issuance'
  }
});

console.log(result.data.eventId);    // "evt_abc123..."
console.log(result.data.eventHash);  // "a1b2c3d4..."
console.log(result.data.chainIndex); // 0

Query Events

const result = await septor.query({
  entityId: 'POL-2024-001',
  eventType: 'policy.*',
  limit: '100'
});

for (const event of result.data.events) {
  console.log(event.eventType, event.metadata.who, event.createdAt);
}

Verify Chain Integrity

const result = await septor.verify('POL-2024-001');

if (result.data.valid) {
  console.log('Chain intact:', result.data.totalEvents, 'events');
} else {
  console.error('Chain broken at index:', result.data.brokenAt);
}

Get Full Chain

const result = await septor.getChain('POL-2024-001');

console.log(result.data.chain);      // Array of all events in order
console.log(result.data.valid);      // true/false
console.log(result.data.totalEvents); // number

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiUrl | string | Yes | Septor API base URL | | namespace | string | Yes | Namespace to scope events (e.g., service name) | | apiKey | string | No | Bearer token for authenticated requests |

Environment URLs

| Environment | URL | |-------------|-----| | Production | https://septor.insureco.io | | Sandbox | https://septor.sandbox.tawa.insureco.io | | Local | http://localhost:8473 |

CLI Usage

# Emit an event
npx septor emit policy.created \
  -n flood-rater \
  -e POL-2024-001 \
  -d '{"premium": 1200}' \
  -w [email protected] \
  --url https://septor.insureco.io

# Query events
npx septor query \
  -n flood-rater \
  -e POL-2024-001 \
  --url https://septor.insureco.io

# Verify chain integrity
npx septor verify POL-2024-001 \
  -n flood-rater \
  --url https://septor.insureco.io

# Initialize a project with Septor config
npx septor init

Event Naming Conventions

Use dot-separated names: <domain>.<action>.<detail>

policy.created
policy.updated.premium
policy.cancelled
claim.filed
claim.approved
claim.payment.issued
user.login
user.permissions.changed
document.uploaded
document.signed

The Seven Elements

Every Septor event captures the seven elements of a complete audit record:

| Element | Field | Description | |---------|-------|-------------| | Who | metadata.who | The actor (user email, service name, API key) | | What | eventType | The action that occurred | | When | metadata.when | Server timestamp + optional client timestamp | | Where | metadata.where | IP address and user agent | | How | metadata.how | HTTP method and endpoint used | | Why | metadata.why | Optional business reason | | Data | data | The event payload |

Types

The package exports full TypeScript types:

import {
  Septor,
  SeptorConfig,
  EmitEventPayload,
  EmitEventResponse,
  QueryFilters,
  QueryEventsResponse,
  VerifyChainResponse,
  SeptorEvent
} from 'septor';

How Hash Chains Work

Each event stores a SHA-256 hash computed from:

• Event type
• Entity ID
• Event data
• Previous event's hash
• Metadata

This creates a linked chain. Modifying any historical event changes its hash, which breaks the chain for all subsequent events. Verification walks the chain from the first event and recomputes each hash to confirm integrity.

License

ISC