sietch

An offline-first database library with CRDT-based sync, post-quantum encryption, and a PostgreSQL/AGE/pgvector server backend. Inspired by GunJS and TopGun.

Features

• Offline-first — full CRUD without network, automatic sync when online
• CRDT sync — Yjs-powered conflict-free replication across peers and servers
• Persistent sync streams — one long-lived bidirectional channel per peer with automatic reconnection
• P2P networking — libp2p transport with NAT traversal (Circuit Relay v2)
• Post-quantum encryption — hybrid Ed25519+ML-DSA-44 signing, X25519+ML-KEM-768 key exchange
• Per-subtree ACL — server-signed reference nodes with three tiers (open / policy / crypto)
• Reactive cursors — observe() returns deep proxies, observeSubtree() tracks entry lifecycle
• Graph + vector — local full-text search + graph traversal, server-side AGE graph + pgvector
• Transparent eviction — two-tier (memory → disk → network), with pinning support
• Zero-config — sensible defaults, createStore() works out of the box

Install

pnpm add sietch

Quick Start

import { createStore } from 'sietch';

// Create an offline-first store
const db = await createStore();

// Write data
await db.put('greeting.msg', 'hello world');

// Read data
const result = await db.get('greeting.msg');
console.log(result.value); // 'hello world'

// Subscribe to changes
db.subscribe('greeting', (entries) => {
  console.log('greeting subtree changed:', entries);
});

// Connect to a server for sync
await db.connectServer('/ip4/127.0.0.1/tcp/9090/ws');

Reactive Cursors

// Deep reactive proxy — reads and writes
const cursor = db.observe<{ title: string; done: boolean }>('todos.item1');
console.log(cursor.data.title);  // reads from CRDT
cursor.data.done = true;         // writes to CRDT, syncs automatically
cursor.dispose();

// Subtree cursor — tracks entries
const todos = db.observeSubtree<{ title: string }>('todos');
todos.onAdd((key, entry) => console.log('added:', key, entry.data.title));
todos.onRemove((key) => console.log('removed:', key));
todos.dispose();

Server Mode

import { createStore } from 'sietch';

const server = await createStore();
await server.listen({ port: 9090 });

Architecture

| Client Module | Purpose | |---|---| | Store | Public API facade | | Yjs Engine | CRDT engine (subdocument per subtree) | | ACL Module | Per-subtree access control | | Crypto Module | PQ hybrid signing, KEX, symmetric encryption | | Identity Module | Keypair lifecycle, device linking | | Sync Engine | libp2p transport, persistent sync streams | | Storage Backend | OPFS/IndexedDB/memory abstraction | | Eviction Manager | Two-tier eviction with LRU | | Query/Index Engine | Full-text search + graph traversal | | Observability | Structured logging (pino), event channels |

| Server Module | Purpose | |---|---| | Sync Service | Yjs relay with selective replication | | ACL Authority | Sign/validate ACL reference nodes | | Auth Service | Email-based device linking | | Query Bridge | Yjs → PostgreSQL/AGE/pgvector pipeline |

Project Status

394 tests across 22 test files, 83/83 requirements covered.

License

MIT