@delali/sirannon-db 0.1.4 → 0.1.5

package/README.md

@@ -6,22 +6,22 @@
 [![types](https://img.shields.io/badge/types-TypeScript-blue)](https://www.npmjs.com/package/@delali/sirannon-db)
 [![license](https://img.shields.io/npm/l/@delali/sirannon-db)](https://github.com/assetcorp/sirannon-db/blob/main/LICENSE)
 
-Turn any SQLite database into a networked data layer with real-time subscriptions. One library gives you connection pooling, change data capture, migrations, scheduled backups, and a client SDK that talks over HTTP or WebSocket.
+Build a networked SQLite service with connection pooling, change data capture, migrations, backups, and a client SDK. Applications reach Sirannon over HTTP or WebSocket, while Sirannon nodes replicate primary-owned changes over gRPC. Coordinator mode adds etcd-backed authority and automatic failover.
 
 > *sirannon* means 'gate-stream' in Sindarin.
 
 ## Install
 
 ```bash
-pnpm add @delali/sirannon-db
+pnpm add -E @delali/sirannon-db
 ```
 
 Then install the SQLite driver for your platform:
 
 ```bash
-pnpm add better-sqlite3    # Node.js
-pnpm add wa-sqlite          # Browser (IndexedDB persistence)
-pnpm add expo-sqlite        # React Native (Expo)
+pnpm add -E better-sqlite3    # Node.js
+pnpm add -E wa-sqlite          # Browser (IndexedDB persistence)
+pnpm add -E expo-sqlite        # React Native (Expo)
 # Node 22+ built-in sqlite and Bun need no extra package
 ```
 
@@ -30,7 +30,7 @@ pnpm add expo-sqlite        # React Native (Expo)
 ### Node.js
 
 ```bash
-pnpm add @delali/sirannon-db better-sqlite3
+pnpm add -E @delali/sirannon-db better-sqlite3
 ```
 
 ```ts
@@ -58,7 +58,7 @@ const driver = nodeSqlite()
 ### Browser
 
 ```bash
-pnpm add @delali/sirannon-db wa-sqlite
+pnpm add -E @delali/sirannon-db wa-sqlite
 ```
 
 The browser driver persists data to IndexedDB through a WebAssembly SQLite build. Use `Database.create` directly since `Sirannon` registries are designed for server-side use.
@@ -82,7 +82,7 @@ const users = await db.query<{ id: number; name: string }>('SELECT * FROM users'
 ### React Native (Expo)
 
 ```bash
-pnpm add @delali/sirannon-db expo-sqlite
+pnpm add -E @delali/sirannon-db expo-sqlite
 ```
 
 ```ts
@@ -128,11 +128,11 @@ Sirannon-db separates the database engine from the library. You pick the driver
 
 | Driver | Import | Runtime | Install |
 | --- | --- | --- | --- |
-| better-sqlite3 | `@delali/sirannon-db/driver/better-sqlite3` | Node.js | `pnpm add better-sqlite3` |
+| better-sqlite3 | `@delali/sirannon-db/driver/better-sqlite3` | Node.js | `pnpm add -E better-sqlite3` |
 | Node built-in | `@delali/sirannon-db/driver/node` | Node.js >= 22 | None (use `--experimental-sqlite` flag) |
-| wa-sqlite | `@delali/sirannon-db/driver/wa-sqlite` | Browser | `pnpm add wa-sqlite` |
+| wa-sqlite | `@delali/sirannon-db/driver/wa-sqlite` | Browser | `pnpm add -E wa-sqlite` |
 | Bun | `@delali/sirannon-db/driver/bun` | Bun | None (uses `bun:sqlite`) |
-| Expo | `@delali/sirannon-db/driver/expo` | React Native | `pnpm add expo-sqlite` |
+| Expo | `@delali/sirannon-db/driver/expo` | React Native | `pnpm add -E expo-sqlite` |
 
 ```ts
 import { betterSqlite3 } from '@delali/sirannon-db/driver/better-sqlite3'
@@ -158,6 +158,9 @@ The package ships independent exports so you only bundle what you need:
 | `@delali/sirannon-db/file-migrations` | Load `.up.sql` / `.down.sql` files from a directory |
 | `@delali/sirannon-db/server` | HTTP + WebSocket server powered by uWebSockets.js |
 | `@delali/sirannon-db/client` | Browser/Node.js client SDK with auto-reconnect and subscription restore |
+| `@delali/sirannon-db/replication` | Replication engine, conflict resolvers, topologies, HLC |
+| `@delali/sirannon-db/transport/grpc` | gRPC replication transport with TLS support |
+| `@delali/sirannon-db/transport/memory` | In-memory transport for testing |
 
 ## Core features
 
@@ -435,52 +438,391 @@ await httpDb.transaction([
 httpClient.close()
 ```
 
+## Distributed replication
+
+Sirannon can replicate a SQLite database across multiple nodes with change propagation, new-node bootstrapping, write concerns, and coordinator-backed failover. The production path is primary-replica: one primary accepts writes, replicas serve reads and can forward writes, and coordinator mode manages authority when failover is enabled. When replication is not enabled, the replication engine does not run.
+
+```ts
+import { ReplicationEngine } from '@delali/sirannon-db/replication'
+import { InMemoryTransport, MemoryBus } from '@delali/sirannon-db/transport/memory'
+import { GrpcReplicationTransport } from '@delali/sirannon-db/transport/grpc'
+```
+
+### Client and replication transports
+
+Sirannon has two transport interfaces with different responsibilities:
+
+| Traffic | Interface | Built-in network transport |
+| --- | --- | --- |
+| Application queries, writes, and CDC subscriptions | Client `Transport` | HTTP or WebSocket |
+| Change batches, acknowledgements, write forwarding, and first sync between Sirannon nodes | `ReplicationTransport` | gRPC |
+
+`WebSocketTransport` conforms to the client `Transport` interface. It connects an application to the Sirannon server and does not conform to `ReplicationTransport`. Use `GrpcReplicationTransport` for production node-to-node replication, or `InMemoryTransport` for tests and single-process scenarios.
+
+### Primary-replica setup
+
+One node accepts writes and pushes changes to read replicas. Replicas forward writes to the primary when `writeForwarding` is enabled.
+
+```ts
+import { ReplicationEngine, PrimaryReplicaTopology } from '@delali/sirannon-db/replication'
+import { GrpcReplicationTransport } from '@delali/sirannon-db/transport/grpc'
+
+const transport = new GrpcReplicationTransport({
+  host: '0.0.0.0',
+  port: 4200,
+  tlsCert: './certs/primary.crt',
+  tlsKey: './certs/primary.key',
+  tlsCaCert: './certs/ca.crt',
+})
+
+const engine = new ReplicationEngine(db, writerConn, {
+  nodeId: 'primary-us-east-1',
+  topology: new PrimaryReplicaTopology('primary'),
+  transport,
+  snapshotConnectionFactory: () => driver.open(dbPath, { readonly: true }),
+  changeTracker: tracker,
+})
+
+await engine.start()
+
+await engine.execute('INSERT INTO orders (id, total) VALUES (?, ?)', [1, 4999])
+
+const rows = await engine.query<{ id: number }>('SELECT * FROM orders')
+```
+
+On the replica side:
+
+```ts
+const replicaEngine = new ReplicationEngine(replicaDb, replicaConn, {
+  nodeId: 'replica-eu-west-1',
+  topology: new PrimaryReplicaTopology('replica'),
+  transport: replicaTransport,
+  transportConfig: { endpoints: ['primary.example.com:4200'] },
+  writeForwarding: true,
+  changeTracker: replicaTracker,
+})
+
+await replicaEngine.start()
+```
+
+When `initialSync` is `true` (the default), a new replica automatically pulls a full snapshot from the primary before accepting reads. The replica blocks reads and writes until the sync completes and incremental catch-up reaches the configured lag threshold.
+
+### Coordinator-backed failover
+
+Coordinator mode stores primary authority, node sessions, replication-group state, and the in-sync set in a `ClusterCoordinator`. The TypeScript package includes an etcd adapter:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { createEtcdCoordinator } from '@delali/sirannon-db/replication/coordinator/etcd'
+
+const coordinator = createEtcdCoordinator({
+  hosts: ['https://etcd-1.internal:2379', 'https://etcd-2.internal:2379'],
+  keyPrefix: '/sirannon/orders',
+  credentials: {
+    rootCertificate: readFileSync('./certs/etcd-ca.crt'),
+    privateKey: readFileSync('./certs/orders-node.key'),
+    certChain: readFileSync('./certs/orders-node.crt'),
+  },
+})
+
+const engine = new ReplicationEngine(db, writerConn, {
+  nodeId: 'orders-node-a',
+  topology: new PrimaryReplicaTopology('primary'),
+  transport,
+  transportConfig: {
+    endpoints: ['orders-node-b.internal:4200', 'orders-node-c.internal:4200'],
+    protocolVersion: '1',
+  },
+  changeTracker: tracker,
+  snapshotConnectionFactory: () => driver.open(dbPath, { readonly: true }),
+  writeForwarding: true,
+  coordinator: {
+    clusterId: 'commerce-production',
+    groupId: 'orders',
+    endpoint: 'https://orders-node-a.internal/db/orders',
+    coordinator,
+    votingDataBearingNodeIds: ['orders-node-a', 'orders-node-b', 'orders-node-c'],
+    controller: true,
+  },
+})
+```
+
+Every coordinator-mode node needs a stable, persisted `nodeId`. `votingDataBearingNodeIds` creates the replication group when it does not exist; later nodes read the registered group from etcd. Production coordinator access requires HTTPS plus an authenticated identity. The in-memory coordinator and `allowInsecure: true` are for tests and local development.
+
+Automatic write failover needs at least three voting data-bearing nodes. With fewer than three voters, the controller cannot prove majority authority after losing a node and keeps writes unavailable.
+
+### Conflict resolution
+
+Normal writes are serialised through one primary per replication group. When a receiver applies a batch and finds the target row already present, it passes the local and incoming versions to the configured resolver. This is part of normal batch application, not a separate repair command.
+
+Three built-in strategies ship with the replication module:
+
+| Strategy | Class | Behaviour |
+| --- | --- | --- |
+| Last-Writer-Wins | `LWWResolver` | Selects the change with the higher HLC timestamp. Ties break by node ID. |
+| Field-Level Merge | `FieldMergeResolver` | Merges non-overlapping columns and uses per-column HLC metadata for overlapping columns. Falls back to whole-row LWW when column metadata is unavailable. |
+| Primary Wins | `PrimaryWinsResolver` | Selects the version authored by a configured primary node ID. Falls back to LWW when neither version came from that node. |
+
+Custom resolvers can be built by creating a class with a `resolve(ctx: ConflictContext): ConflictResolution` method.
+
+Coordinator mode quarantines a returning former primary when it contains local-only writes. It does not merge that history into the current primary or expose a force-promotion or high-level repair API. An operator must rebuild, restore, or otherwise remediate the faulted node before rejoining it.
+
+### First sync
+
+When a new node joins a running cluster, it needs the full dataset before it can process incremental changes. The sync protocol handles this automatically:
+
+1. The joiner connects and sends a sync request to the source
+2. The source opens a consistent read-only snapshot and sends schema DDL (CREATE TABLE, CREATE INDEX)
+3. The source streams table data in configurable batches (default 10,000 rows) with per-batch checksums
+4. After all data is transferred, the source sends a manifest with row counts and primary-key hashes
+5. The joiner verifies the manifest, transitions to catch-up mode, and applies incremental changes accumulated during the transfer
+6. Once the replication lag drops below `maxSyncLagBeforeReady`, the joiner starts serving reads
+
+The state machine is: `pending` -> `syncing` -> `catching-up` -> `ready`. You can monitor it via `engine.status().syncState`.
+
+For large databases where a network transfer is impractical, the out-of-band path lets you copy the SQLite file directly and start from a known sequence:
+
+```ts
+const engine = new ReplicationEngine(db, writerConn, {
+  initialSync: false,
+  resumeFromSeq: 50000n,
+  // ...
+})
+```
+
+### Write concerns
+
+Control how many replicas must acknowledge a write before it returns:
+
+```ts
+await engine.execute(
+  'INSERT INTO orders (id, total) VALUES (?, ?)',
+  [1, 4999],
+  { writeConcern: { level: 'majority', timeoutMs: 5000 } },
+)
+```
+
+In static mode, omitting `writeConcern` returns after the local commit. In coordinator mode, omitting it selects `'majority'`. You can request `'local'`, `'majority'`, or `'all'` explicitly. A coordinator-mode `'local'` write is not protected against loss during automatic failover.
+
+In coordinator mode, `majority` is calculated from configured voting data-bearing nodes in the replication group, including the primary's local durable commit. It is not calculated from the peers currently connected to this process. A successful coordinator-mode `majority` write survives automatic primary failover when only the failed primary is lost and an eligible in-sync replica remains.
+
+### Replication FAQ
+
+#### Is this SQLite over a shared network file system?
+
+No. Each node owns its own SQLite database file. Sirannon moves change batches through its replication transport and exposes database operations through the server and client layers. It does not rely on many machines opening the same SQLite file over NFS or another shared network file system.
+
+#### What is replicated?
+
+Sirannon replicates checksummed batches of `ReplicationChange` records. Each change carries the table, operation, row ID, primary key, HLC timestamp, transaction ID, node ID, old data, new data, and optional DDL statement.
+
+#### Is the protocol row-based, statement-based, operation-log based, or CRDT-like?
+
+It is operation-log based at the Sirannon layer. Data changes carry row images and primary-key metadata. DDL changes carry a validated DDL statement. The current production write path is not CRDT-like; it prevents normal write conflicts with a single writable primary.
+
+#### What ordering model does it use?
+
+Each change carries a Hybrid Logical Clock timestamp. The HLC gives deterministic causal ordering across nodes without relying on perfectly synchronised wall clocks. Batches also carry a sequence range, checksum, and, in coordinator mode, `groupId` and `primaryTerm`.
+
+#### What happens under partitions?
+
+Static mode does not own failover. If the static primary is lost, writes stay unavailable until an operator or external system promotes another node and reroutes clients.
+
+Coordinator mode uses a cluster coordinator, primary terms, leases, in-sync sets, and fail-closed write behaviour. A primary may accept writes only while it can prove current authority. Replicas reject stale batches, stale sync messages, and stale forwarded writes. Only an in-sync replica can be promoted.
+
+#### What topology do I need for automatic write failover?
+
+Use at least three voting data-bearing Sirannon nodes in one replication group. One node has no failover. Two nodes can replicate, but one survivor cannot prove majority authority after the other node is lost.
+
+#### Does Sirannon support schema changes across replicas?
+
+Yes, with a safety allowlist. Replicated DDL supports `CREATE TABLE`, `ALTER TABLE ... ADD COLUMN`, `DROP TABLE`, `CREATE INDEX`, and `DROP INDEX`. The receiver rejects multiple statements, `AS SELECT`, extension loading, `ATTACH`, dangerous file functions, and DDL outside the allowlist.
+
+#### How do foreign keys and unique constraints behave?
+
+SQLite enforces constraints on each node. The primary serialises normal writes, which prevents normal concurrent unique-key conflicts. First sync orders tables by foreign-key dependency, and controlled resync disables foreign keys only while wiping tables before reloading from the sync source. Incoming replicated data still has to satisfy the receiving database's constraints.
+
+#### Are reads consistent after writes?
+
+Read concern controls this. `local` reads the selected node's local state. `majority` reads data that has reached the replication group's majority commit point. `linearizable` reads from the current primary after it proves live authority for the current primary term. If the requested read concern cannot be satisfied, the read fails rather than returning a weaker result.
+
+#### Is this local-first or multi-writer today?
+
+The current production path is primary-replica. Conflict resolvers decide how a receiving node applies a change to an existing row; they do not provide local-first reconciliation or a multi-writer CRDT layer.
+
+### Transport options
+
+| Transport | Import | Use case |
+| --- | --- | --- |
+| gRPC | `@delali/sirannon-db/transport/grpc` | Production Node.js multi-node replication over the network with TLS support. |
+| In-Memory | `@delali/sirannon-db/transport/memory` | Testing and single-process multi-node scenarios. Messages delivered via microtask scheduling. |
+| Custom | Build your own | Any transport that satisfies the `ReplicationTransport` interface (Redis, NATS, MQTT, TCP, etc). |
+
+`ReplicationEngine.start()` derives `TransportConfig.localRole` from `topology.role`. In coordinator mode, it also supplies the current `groupId`, `primaryTerm`, and protocol version to the transport. Set these fields yourself only when you connect a `ReplicationTransport` without `ReplicationEngine`.
+
+`TransportConfig` accepts these fields:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `endpoints` | `string[]` | Peer addresses used to establish replication connections |
+| `localRole` | `'primary' \| 'replica'` | Local topology role; `ReplicationEngine` supplies this value |
+| `groupId` | `string` | Replication group carried in coordinator-mode handshakes; the engine supplies it from coordinator configuration |
+| `primaryTerm` | `bigint` | Current fencing term; the engine supplies it from coordinator state |
+| `protocolVersion` | `string` | Replication protocol version advertised to peers |
+| `metadata` | `Record<string, unknown>` | Optional custom transport metadata |
+
+### Replication configuration reference
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `nodeId` | `string` | auto-generated in static mode | Unique node identifier. Coordinator mode requires a stable, persisted value. |
+| `topology` | `Topology` | required | `PrimaryReplicaTopology` |
+| `transport` | `ReplicationTransport` | required | Transport for inter-node communication |
+| `transportConfig` | `TransportConfig` | `{}` | Peer endpoints and transport metadata. The engine supplies role and coordinator fencing fields when it starts. |
+| `writeForwarding` | `boolean` | `false` | Forward writes from replicas to the primary |
+| `defaultConflictResolver` | `ConflictResolver` | `LWWResolver` | Default conflict resolution strategy |
+| `conflictResolvers` | `Record<string, ConflictResolver>` | - | Per-table conflict resolution overrides |
+| `batchSize` | `number` | `100` | Changes per replication batch |
+| `batchIntervalMs` | `number` | `100` | Sender loop interval in ms |
+| `maxClockDriftMs` | `number` | `60000` | Maximum tolerated HLC drift before rejecting a batch |
+| `maxPendingBatches` | `number` | `10` | In-flight batches per peer before backpressure |
+| `maxBatchChanges` | `number` | `1000` | Maximum accepted changes in one inbound batch |
+| `ackTimeoutMs` | `number` | `5000` | Replication batch ack timeout |
+| `initialSync` | `boolean` | `true` | Pull a full snapshot when joining a cluster |
+| `syncBatchSize` | `number` | `10000` | Rows per sync batch during initial sync |
+| `maxConcurrentSyncs` | `number` | `2` | Maximum simultaneous sync sessions on the source |
+| `maxSyncDurationMs` | `number` | `1800000` | Source aborts sync after this duration (30 min) |
+| `maxSyncLagBeforeReady` | `number` | `100` | Catch-up lag threshold (in sequences) to transition to ready |
+| `syncAckTimeoutMs` | `number` | `30000` | Per-batch ack timeout during sync (30s) |
+| `catchUpDeadlineMs` | `number` | `600000` | Max time in catch-up phase before transitioning to ready (10 min) |
+| `resumeFromSeq` | `bigint` | - | Start replication from a specific sequence (out-of-band sync) |
+| `snapshotConnectionFactory` | `() => Promise<SQLiteConnection>` | - | Factory for read-only connections used during sync serving |
+| `changeTracker` | `ChangeTracker` | - | CDC trigger manager, required for initial sync |
+| `flowControl` | `{ maxLagSeconds?, onLagExceeded? }` | - | Replication lag monitoring callbacks |
+| `onBeforeForwardedQuery` | `(sql, params?) => void` | - | Validation or authorisation hook called before the primary executes each forwarded statement |
+| `coordinator` | `CoordinatorModeConfig` | - | Enables coordinator-backed authority and failover |
+| `snapshotThreshold` | `number` | - | Reserved configuration field; the current engine does not read it |
+
+### Coordinator configuration reference
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `clusterId` | `string` | required | Coordinator namespace for the Sirannon cluster |
+| `groupId` | `string` | required | Replication group containing copies of one database |
+| `endpoint` | `string` | - | Application endpoint advertised for client discovery |
+| `votingDataBearingNodeIds` | `string[]` | - | Voter set used to create an unregistered group and calculate coordinator write concerns |
+| `coordinator` | `ClusterCoordinator` | required | Coordinator adapter, such as the etcd adapter |
+| `sessionTtlMs` | `number` | `10000` | Node-session lease lifetime |
+| `controller` | `boolean \| CoordinatorControllerConfig` | enabled | Enables the controller loop or configures its lease holder, TTL, and tick interval |
+| `compatibility` | `CoordinatorCompatibilityMetadata` | - | Package, specification, and protocol versions used for promotion compatibility checks |
+
+`CoordinatorControllerConfig` accepts `enabled`, `holderId`, `leaseTtlMs`, and `tickIntervalMs`. The lease TTL defaults to 10,000 ms, and the controller tick interval defaults to 1,000 ms.
+
+### Replication errors
+
+| Error | Code | When |
+| --- | --- | --- |
+| `ReplicationError` | `REPLICATION_ERROR` | Base class for replication failures |
+| `SyncError` | `SYNC_ERROR` | First sync failures (node not ready, timeout, integrity mismatch) |
+| `ConflictError` | `CONFLICT_ERROR` | Unresolvable write conflict |
+| `TransportError` | `TRANSPORT_ERROR` | Inter-node communication failure |
+| `BatchValidationError` | `BATCH_VALIDATION_ERROR` | Checksum mismatch, clock drift, or oversized batch |
+| `TopologyError` | `TOPOLOGY_ERROR` | Write on a read-only node without forwarding |
+| `WriteConcernError` | `WRITE_CONCERN_ERROR` | Quorum not reached within timeout |
+
 ## Security
 
-Sirannon-db is designed to be secure by default in its core operations. This section covers what the library handles for you and what you're responsible for when deploying to production.
+Sirannon-db gives you secure primitives, but the network server is intentionally low-level: it can execute SQL sent by a client. Treat the server like a database endpoint, not like a public application API, unless you add an explicit application security boundary around it.
 
 ### Built-in protections
 
-- **Parameterized queries** - All SQL execution uses parameter binding through the driver layer, preventing SQL injection. User input never touches query strings directly.
-- **Identifier validation** - CDC table and column names are validated against a strict allowlist regex (`/^[a-zA-Z_][a-zA-Z0-9_]*$/`), and identifiers are escaped with double-quote wrapping.
-- **Path traversal prevention** - Migration and backup paths reject null bytes, `..` segments, and control characters before any filesystem access.
-- **Request size limits** - HTTP bodies and WebSocket payloads are capped at 1 MB, preventing memory exhaustion from oversized requests.
-- **Error isolation** - Errors returned to clients contain a machine-readable code and message. Stack traces and internal details are never leaked.
+- **Parameterised values** - Query and execute calls pass parameters through the driver layer. Keep user input in `params`; never concatenate user input into SQL strings.
+- **Identifier validation** - CDC table and column names are validated against a strict allowlist regex (`/^[a-zA-Z_][a-zA-Z0-9_]*$/`) and escaped with double quotes.
+- **Path traversal prevention** - Migration and backup paths reject null bytes, `..` segments, and control characters before filesystem access.
+- **Request size limits** - HTTP bodies and WebSocket payloads are capped at 1 MB to reduce memory-exhaustion risk.
+- **Error isolation** - Remote errors use a machine-readable code and message. Stack traces and internal details are not returned to clients.
 - **Connection isolation** - Read and write operations use separate connection pools. Read-only databases enforce immutability at the connection level.
 
-### Authentication and authorization
+### Deployment boundary
+
+For production, put Sirannon behind one of these boundaries:
 
-The server accepts arbitrary SQL from clients. When you expose it beyond localhost, always use the `onRequest` hook to authenticate and authorize requests.
+- A server-side application layer that exposes domain actions, not arbitrary SQL.
+- A private network boundary where only trusted services can reach the Sirannon server.
+- A custom `resolveExecutionTarget` or hook layer that allows only specific statements, tenants, and tables.
+
+Do not expose unrestricted `/db/:id/query`, `/db/:id/execute`, `/db/:id/transaction`, or `/db/:id` WebSocket routes directly to untrusted browsers.
+
+### HTTP authentication
+
+Use `onRequest` to authenticate HTTP database routes. The hook runs before database routes and can deny requests by returning `{ status, code, message }`. Health endpoints bypass this hook.
 
 ```ts
 const server = createServer(sirannon, {
   port: 9876,
-  onRequest: ({ headers, path, method, remoteAddress }) => {
-    if (headers.authorization !== `Bearer ${process.env.API_TOKEN}`) {
+  onRequest: ({ headers }) => {
+    if (headers.authorization !== `Bearer ${process.env.SIRANNON_API_TOKEN}`) {
       return { status: 401, code: 'UNAUTHORIZED', message: 'Invalid or missing token' }
     }
   },
 })
 ```
 
-The hook runs before every database route (HTTP and WebSocket upgrade). Return `void` to allow the request, or return a `{ status, code, message }` object to deny it. Health endpoints (`/health`, `/health/ready`) bypass this hook.
+Send HTTP credentials through `headers` on the client:
 
-### TLS and transport security
+```ts
+const client = new SirannonClient('https://db.example.com', {
+  transport: 'http',
+  headers: { Authorization: `Bearer ${token}` },
+})
+```
+
+### WebSocket authentication
+
+Browsers cannot attach arbitrary `Authorization` headers to `new WebSocket(...)`. For browser clients, authenticate the upgrade with a mechanism the browser can send, such as same-site cookies or a short-lived value in `Sec-WebSocket-Protocol`. Also validate the `Origin` header during the upgrade.
+
+```ts
+const expectedOrigin = 'https://app.example.com'
+const expectedProtocol = process.env.SIRANNON_WS_PROTOCOL
+
+const server = createServer(sirannon, {
+  port: 9876,
+  onRequest: ({ headers, method, path }) => {
+    const isWebSocketUpgrade = method === 'GET' && path.startsWith('/db/')
+    if (!isWebSocketUpgrade) {
+      return undefined
+    }
 
-> **Warning:** The built-in server binds plain HTTP and WebSocket without TLS. When you serve traffic outside a trusted network, terminate TLS upstream with a reverse proxy (nginx, Caddy, a cloud load balancer) or your clients' bearer tokens and query payloads will travel in cleartext.
+    if (headers.origin !== expectedOrigin) {
+      return { status: 403, code: 'FORBIDDEN_ORIGIN', message: 'Forbidden origin' }
+    }
+
+    const protocols = (headers['sec-websocket-protocol'] ?? '').split(',').map(value => value.trim())
+    if (!expectedProtocol || !protocols.includes(expectedProtocol)) {
+      return { status: 401, code: 'UNAUTHORIZED', message: 'Invalid WebSocket credentials' }
+    }
+  },
+})
+```
 
-Once TLS is in place, update your client URLs to use `https://` and `wss://`:
+Then pass the browser-compatible protocol through the client:
 
 ```ts
 const client = new SirannonClient('https://db.example.com', {
   transport: 'websocket',
-  headers: { Authorization: `Bearer ${token}` },
+  webSocketProtocols: [wsProtocol],
 })
 ```
 
-### CORS
+Protocol values must be valid `Sec-WebSocket-Protocol` tokens. If you derive them from secrets or signed data, encode them with a URL-safe format and keep them short-lived.
+
+### TLS and transport security
 
-CORS is disabled by default. Enable it only if browser clients need direct access, and restrict origins to trusted domains:
+The built-in server binds plain HTTP and WebSocket. For any traffic outside a trusted local network, terminate TLS upstream with a reverse proxy, load balancer, or platform edge and use `https://` and `wss://` client URLs. Without TLS, credentials, SQL text, parameters, and CDC payloads travel in cleartext.
+
+### CORS and browser access
+
+CORS is disabled by default. Enable it only if browser clients need direct HTTP access, and restrict origins to trusted domains:
 
 ```ts
 const server = createServer(sirannon, {
@@ -491,7 +833,36 @@ const server = createServer(sirannon, {
 })
 ```
 
-Passing `cors: true` allows all origins, which is fine for local development but should be avoided in production.
+Passing `cors: true` allows all origins and should be limited to local development. CORS does not protect WebSocket upgrades; validate WebSocket `Origin` in `onRequest`.
+
+### SQL access control
+
+Authentication only identifies the caller. It does not make arbitrary SQL safe. For internet-facing systems, enforce one of these patterns:
+
+- Prefer application endpoints that perform domain operations such as `createOrder`, `reserveInventory`, or `markPaid`.
+- If clients must use the Sirannon data API, wrap the database with `resolveExecutionTarget` and allow only known SQL statements and parameter shapes.
+- Use hooks for additional query checks, but do not rely on naive substring matching as a SQL firewall.
+- Keep tenant identifiers and ownership rules on the server side.
+
+### Secrets and logging
+
+- Do not place long-lived secrets in browser-visible configuration such as Vite `VITE_*` variables.
+- Prefer short-lived WebSocket credentials minted by your application server.
+- Redact `Authorization`, cookies, and WebSocket auth protocol values from access logs.
+- Avoid logging full SQL statements when they can contain sensitive data.
+
+### Security checklist
+
+- Bind the server to `127.0.0.1` or a private interface unless a proxy is enforcing TLS and access control.
+- Use HTTPS/WSS for non-local traffic.
+- Authenticate every HTTP database route and every WebSocket upgrade.
+- Validate WebSocket `Origin` against an explicit allowlist.
+- Keep SQL behind application actions or a strict allowlist.
+- Keep user input in SQL parameters, not interpolated strings.
+- Restrict CORS to known origins.
+- Add rate limits, audit logs, and abuse monitoring at the application or edge layer for public deployments.
+
+Further reading: [OWASP REST Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html), [OWASP WebSocket Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html), and [MDN WebSocket constructor](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket).
 
 ## Error handling
 
@@ -560,20 +931,21 @@ try {
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `transport` | `'websocket' \| 'http'` | `'websocket'` | Transport protocol |
-| `headers` | `Record<string, string>` | - | Custom HTTP headers |
+| `headers` | `Record<string, string>` | - | Custom HTTP headers; browser WebSocket handshakes do not use this option |
+| `webSocketProtocols` | `string \| string[]` | - | WebSocket subprotocols sent during the upgrade handshake |
 | `autoReconnect` | `boolean` | `true` | Reconnect on WebSocket disconnect |
 | `reconnectInterval` | `number` | `1000` | Reconnect delay in ms |
 
 ## Examples
 
-Self-contained example projects live in [`examples/`](examples/) and cover every runtime target:
+Self-contained example projects live in [`examples/`](examples/) and cover the current Node.js, browser, client-server, and distributed paths:
 
 | Example | Runtime | Driver | What it demonstrates |
 | --- | --- | --- | --- |
-| [`node-better-sqlite3`](examples/node-better-sqlite3/) | Node.js | better-sqlite3 | All core features: schema, migrations, CRUD, transactions, CDC, connection pools, metrics, multi-tenant, hooks, backup, shutdown |
-| [`node-native`](examples/node-native/) | Node.js >= 22 | built-in `node:sqlite` | Same features as above using the zero-dependency Node driver |
+| [`node`](examples/node/) | Node.js >= 22 | better-sqlite3 or built-in `node:sqlite` | All core features: schema, migrations, CRUD, transactions, CDC, connection pools, metrics, multi-tenant, hooks, backup, shutdown |
 | [`web-wa-sqlite`](examples/web-wa-sqlite/) | Browser (Vite) | wa-sqlite + IndexedDB | CRUD, transactions, CDC subscriptions in the browser |
 | [`web-client`](examples/web-client/) | Browser + Node.js | better-sqlite3 (server) | Client SDK connecting to a Sirannon server over HTTP and WebSocket |
+| [`distributed-entitlements`](examples/distributed-entitlements/) | Node.js + browser | better-sqlite3 | Three-node coordinator-backed replication over gRPC with etcd authority, local mTLS certificates, and Toxiproxy failure controls |
 
 ### Running the examples
 
@@ -587,21 +959,25 @@ pnpm --filter @delali/sirannon-db build
 Then pick an example:
 
 ```bash
-# Node.js with better-sqlite3
-cd packages/ts/examples/node-better-sqlite3
+# Node.js with better-sqlite3, the default driver
+cd packages/ts/examples/node
 pnpm start
 
 # Node.js with built-in sqlite
-cd packages/ts/examples/node-native
-pnpm start
+cd packages/ts/examples/node
+pnpm run start:node-native
 
 # Browser with wa-sqlite (opens Vite dev server)
 cd packages/ts/examples/web-wa-sqlite
-pnpm dev
+pnpm run dev
 
 # Client-server (starts both Sirannon server and Vite client)
 cd packages/ts/examples/web-client
-pnpm start
+pnpm run dev
+
+# Distributed entitlements (starts the Docker cluster and dashboard)
+cd packages/ts/examples/distributed-entitlements
+pnpm run dev
 ```
 
 ## Benchmarks

package/dist/backup-scheduler/index.d.ts

@@ -1,3 +1,3 @@
-export { a as BackupScheduler } from '../index-hXiis3N-.js';
-export { e as BackupScheduleOptions } from '../types-DtDutWRU.js';
+export { a as BackupScheduler } from '../index-CLdNrcPz.js';
+export { m as BackupScheduleOptions } from '../types-D-74JiXb.js';
 import '../types-BFSsG77t.js';