@bod.ee/db 0.10.2 → 0.12.1

package/.claude/settings.local.json

@@ -29,7 +29,11 @@
       "WebFetch(domain:caniuse.com)",
       "WebFetch(domain:github.com)",
       "WebFetch(domain:api.github.com)",
-      "WebFetch(domain:raw.githubusercontent.com)"
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(lsof:*)",
+      "Bash(ps:*)",
+      "Bash(sleep 1:*)",
+      "WebFetch(domain:bun.com)"
     ]
   }
 }

package/.claude/skills/config-file.md

@@ -42,7 +42,9 @@ export default {
   mq: { visibilityTimeout: 30, maxDeliveries: 5 },
   compact: { 'events/logs': { maxAge: 86400 } },
   vfs: { storageRoot: './files' },
-  keyAuth: { sessionTtl: 86400, nonceTtl: 60, rootPublicKey: '<base64>' },
+  keyAuth: { sessionTtl: 86400, nonceTtl: 60, rootPublicKey: '<base64>', pbkdf2Iterations: 100000, maxAuthFailures: 5, authLockoutSeconds: 60 },
+  transport: { maxConnections: 10000, maxMessageSize: 1_048_576, maxSubscriptionsPerClient: 500 },
+  log: { enabled: true, level: 'info', components: ['transport', 'stats', 'storage'] }, // or components: '*' for all
   replication: {
     role: 'primary',
     sources: [

package/.claude/skills/developing-bod-db.md

@@ -99,6 +99,14 @@ Push paths are append-only logs. `StreamEngine` adds consumer group offsets (`_s
 ### KeyAuth (Ed25519 Identity & IAM)
 `KeyAuthEngine` — self-sovereign auth using Ed25519 key pairs. Identity hierarchy: Root (filesystem key, god mode) → Account (password-encrypted private key in DB, portable) → Device (delegate, linked via password unlock). Challenge-response auth: server issues nonce (TTL + one-time), client signs with device/account key, server verifies + creates session. Self-signed tokens: `base64url(payload).base64url(Ed25519_sign)`. Device reverse-index at `_auth/deviceIndex/{dfp}` for O(1) lookup. `_auth/` prefix protected from external writes in Transport. Password change = re-encrypt same key pair (fingerprint stable). IAM: roles with path-based permissions.
 
+### Optimization Patterns
+- **SQL push-down**: `StorageEngine.query()` auto-detects push rows (single JSON, not flattened) and uses `json_extract()` in SQL WHERE/ORDER/LIMIT. Falls back to JS for flattened data. Op whitelist prevents SQL injection.
+- **Broadcast groups**: `Transport._addBroadcastSub()` — one DB subscription per path shared across all WS clients. Serialize once, send buffer to all.
+- **Batch re-subscribe**: `batch-sub` wire op registers N subs in one message. Client uses on reconnect with fallback.
+- **Async notifications**: `SubscriptionEngine.queueNotify()` coalesces via `queueMicrotask`. Opt-in `asyncNotify: true`.
+- **existsMany**: Single SQL query with OR conditions to batch-check path existence.
+- **Replication batching**: `beginBatch()/flushBatch()` buffers events during transactions, emits after commit.
+
 ### FileAdapter
 Scans directory recursively on `start()`. Optional `fs.watch` for live sync. Stores metadata (size, mtime, mime) at `basePath/<relPath>`. Content read/write-through methods.
 
@@ -132,10 +140,11 @@ Path patterns with `$wildcard` capture. Most specific match wins. Supports boole
 - **Phase 10** (DONE): VFS — VFSEngine, LocalBackend, REST + WS transport, VFSClient SDK
 - **Phase 11** (DONE): BodClientCached — two-tier cache (memory + IndexedDB), stale-while-revalidate, updatedAt protocol
 - **Phase 12** (DONE): KeyAuth — Ed25519 identity & IAM, challenge-response, accounts, devices, sessions, roles
+- **Phase 13** (DONE): Optimization — request timeouts, connection/sub caps, SQL query push-down, broadcast groups, async batched notifications, batch re-subscribe, cursor-based materialize, replication event batching, auth rate limiting
 
 ## Testing
 
-- `bun test` — 266 tests across 23 files
+- `bun test` — 334 tests across 24 files
 - Each engine/feature gets its own test file in `tests/`
 - Test happy path, edge cases, error cases
 - Use `{ sweepInterval: 0 }` in tests to disable background sweep

package/.claude/skills/using-bod-db.md

@@ -183,6 +183,7 @@ const client = new BodClient({
   url: 'ws://localhost:4400',
   auth: () => 'my-token',
   reconnect: true,
+  requestTimeout: 30000, // ms, rejects pending requests after timeout (default: 30s)
 });
 
 await client.connect();
@@ -290,8 +291,15 @@ ws.send(JSON.stringify({ id: '17', op: 'fts-index', path: 'posts/p1', fields: ['
 ws.send(JSON.stringify({ id: '18', op: 'vector-search', query: [0.1, 0.2], path: 'docs', limit: 5 }));
 ws.send(JSON.stringify({ id: '19', op: 'vector-store', path: 'docs/d1', embedding: [0.1, 0.2] }));
 
+// Batch re-subscribe (reconnect optimization — all subs in one message)
+ws.send(JSON.stringify({ id: '20', op: 'batch-sub', subscriptions: [
+  { path: 'users/u1', event: 'value' },
+  { path: 'posts', event: 'child' },
+]}));
+// → { id: '20', ok: true, data: { subscribed: 2 } }
+
 // Stream extended ops
-ws.send(JSON.stringify({ id: '20', op: 'stream-snapshot', path: 'events/orders' }));
+ws.send(JSON.stringify({ id: '21', op: 'stream-snapshot', path: 'events/orders' }));
 ws.send(JSON.stringify({ id: '21', op: 'stream-materialize', path: 'events/orders', keepKey: 'orderId' }));
 ws.send(JSON.stringify({ id: '22', op: 'stream-compact', path: 'events/orders', maxAge: 86400 }));
 ws.send(JSON.stringify({ id: '23', op: 'stream-reset', path: 'events/orders' }));
@@ -393,6 +401,15 @@ const snap = db.stream.snapshot('events/orders');
 const view = db.stream.materialize('events/orders', { keepKey: 'orderId' });
 // view = { o1: {orderId:'o1', status:'completed'}, o2: {...}, ... }
 
+// Cursor-based materialize (for large topics — paginated)
+let allData: Record<string, unknown> = {};
+let cursor: string | undefined;
+do {
+  const r = db.stream.materialize('events/orders', { keepKey: 'orderId', batchSize: 1000, cursor });
+  Object.assign(allData, r.data);
+  cursor = r.nextCursor;
+} while (cursor);
+
 // Safety: compaction never folds events beyond the minimum consumer group offset
 ```
 

package/CLAUDE.md

@@ -58,13 +58,21 @@ config.ts                  — demo instance config (open rules, indexes, fts, v
 - **MQ (Message Queue)**: SQS-style work queue. `db.mq.push(queue, value)` / `.fetch(queue, count)` / `.ack(queue, key)` / `.nack(queue, key)`. Each message claimed by exactly one worker (visibility timeout). Columns: `mq_status` (pending/inflight/dead), `mq_inflight_until`, `mq_delivery_count`. `sweep()` reclaims expired inflight; exhausted messages (>maxDeliveries) move to DLQ at `<queue>/_dlq/<key>` with `mq_status='dead'`. Ack = DELETE (keeps queue lean). `purge(queue)` deletes pending only; `purge(queue, { all: true })` deletes all (pending + inflight + DLQ). Per-queue options via `queues` config (longest prefix match). Client: `MQReader` / `MQMessageSnapshot`.
 - **FileAdapter**: scans directory, syncs metadata to DB, optional fs.watch, content read/write-through.
 - **SSE fallback**: `GET /sse/<path>?event=value|child` returns `text/event-stream`. Initial `: ok` comment flushes the stream connection.
-- **Perf**: `snapshotExisting` and `notify` are skipped when no subscriptions are active. `exists()` uses `LIMIT 1`.
-- **Transport**: WS messages follow `protocol.ts` types. REST at `/db/<path>`. Auth via `op:'auth'` message. Subs cleaned up on disconnect.
-- **BodClient**: id-correlated request/response over WS. Auto-reconnect with exponential backoff. Re-subscribes all active subs on reconnect. `ValueSnapshot` with `.val()`, `.key`, `.path`, `.exists()`, `.updatedAt`. `getSnapshot(path)` returns ValueSnapshot with `updatedAt` from server.
+- **Perf**: `snapshotExisting` uses `existsMany()` (single SQL query with OR conditions). `notify` skipped when no subscriptions active. `exists()` uses `LIMIT 1`. Subscription callbacks wrapped in try-catch (one bad callback can't break others).
+- **Query SQL push-down**: For push rows (single JSON values), queries use `json_extract(value, '$.field')` in SQL WHERE/ORDER/LIMIT. Auto-detected via sampling first row. Flattened rows fall back to JS-based filtering.
+- **Broadcast groups**: Transport shares one DB subscription per path across all WS clients. `JSON.stringify()` once, `ws.send(buffer)` for all clients. Reduces serialization from O(N) to O(1) per notification.
+- **Async batched notifications**: `SubscriptionEngine.queueNotify()` coalesces multiple writes in same tick via `queueMicrotask()`. Opt-in via `asyncNotify: true` in `SubscriptionEngineOptions`.
+- **Batch re-subscribe**: `{ op: 'batch-sub', subscriptions: [{path, event}] }` — single message to register N subscriptions. Client uses this on reconnect. Fallback to individual subs if server returns error.
+- **Cursor-based materialize**: `stream.materialize(topic, { batchSize, cursor })` returns `{ data, nextCursor? }` for paginated materialization of large streams.
+- **Transport**: WS messages follow `protocol.ts` types. REST at `/db/<path>`. Auth via `op:'auth'` message. Subs cleaned up on disconnect. Connection cap (`maxConnections: 10000`), message size limit (`maxMessageSize: 1MB`), per-client sub cap (`maxSubscriptionsPerClient: 500`). Configurable via `TransportOptions`.
+- **Replication batching**: Transaction writes are buffered via `ReplicationEngine.beginBatch()/flushBatch()` — emits all repl events after transaction commit instead of per-write.
+- **Auth rate limiting**: `KeyAuthEngine` supports `maxAuthFailures` + `authLockoutSeconds` — failed auth attempts tracked at `_auth/rateLimit/{fp}` with TTL. Cleared on success. `pbkdf2Iterations` configurable (default 100000).
+- **BodClient**: id-correlated request/response over WS. Auto-reconnect with exponential backoff. Re-subscribes all active subs on reconnect via `batch-sub` (single message). `ValueSnapshot` with `.val()`, `.key`, `.path`, `.exists()`, `.updatedAt`. `getSnapshot(path)` returns ValueSnapshot with `updatedAt` from server. `requestTimeout` (default 30s) auto-rejects pending requests.
 - **BodClientCached**: two-tier cache wrapper around BodClient. Memory (Map, LRU eviction) + IndexedDB persistence. Stale-while-revalidate: subscribed paths always fresh, unsubscribed return stale + background refetch. Writes (`set/update/delete`) invalidate path + ancestors. `init()` opens IDB + sweeps expired. `warmup(paths[])` bulk-loads from IDB. Passthrough for `push/batch/query/search/mq/stream/vfs` via `cachedClient.client`.
 - **MCP**: `MCPAdapter` wraps a `BodClient` as a JSON-RPC MCP server (stdio + HTTP). Connects to a running BodDB instance over WebSocket — no embedded DB. Entry point: `mcp.ts`. Tools: CRUD (6), FTS (2), vectors (2), streams (4), MQ (7) = 21 tools. Use `--stdio` for Claude Code/Desktop, `--http` for remote agents.
 - **VFS (Virtual File System)**: `VFSEngine` — files stored outside SQLite via pluggable `VFSBackend` interface. `LocalBackend` stores at `<storageRoot>/<fileId>` using `Bun.file`/`Bun.write`. Metadata at `_vfs/<virtualPath>/` (size, mime, mtime, fileId, isDir) — gets subs/rules/replication for free. `fileId = pushId` so move/rename is metadata-only. REST: `POST/GET/DELETE /files/<path>`, `?stat=1`, `?list=1`, `?mkdir=1`, `PUT ?move=<dst>`. WS chunked fallback: base64-encoded `vfs-upload-init/chunk/done`, `vfs-download-init` → `vfs-download-chunk` push messages. Client: `VFSClient` via `client.vfs()` — `upload/download` (REST) + `uploadWS/downloadWS` (WS) + `stat/list/mkdir/delete/move`.
 - **Replication**: `ReplicationEngine` — single primary + N read replicas + multi-source feed subscriptions. Star topology. Primary emits write events to `_repl` stream via `onWrite` hooks. Replicas bootstrap via `streamMaterialize('_repl', { keepKey: 'path' })`, then subscribe for ongoing events. Write proxy: replica forwards writes to primary via BodClient, primary applies + emits, replica consumes. `_replaying` flag prevents re-emission loops. `_emitting` guard prevents recursion from `db.push('_repl')`. Updates flattened to per-path set events for correct compaction keying. Sweep delete events replicated. Excluded prefixes: `_repl`, `_streams`, `_mq`, `_auth`. **Sources**: `ReplicationSource[]` — subscribe to specific paths from multiple remote DBs. Each source is an independent BodClient that filters `_repl` events by path prefix, with optional `localPrefix` remapping (e.g. remote `users/u1` → local `db-a/users/u1`). Sources connect in parallel; individual failures don't block others. Sources are independent of role — a DB can be primary AND consume sources.
+- **KeyAuth integration guide**: `docs/keyauth-integration.md` — flows for signup, signin, new device, autoAuth, IAM roles, common mistakes.
 - **KeyAuth**: `KeyAuthEngine` — portable Ed25519 identity & IAM. Identity hierarchy: Root (server-level, key on filesystem), Account (portable, password-encrypted private key in DB or device-generated), Device (delegate, linked via password unlock). Challenge-response auth: server sends nonce → client signs with Ed25519 → server verifies + creates session. Self-signed tokens (no JWT lib): `base64url(payload).base64url(Ed25519_sign)`. Data model at `_auth/` prefix (protected from external writes). Device reverse-index at `_auth/deviceIndex/{dfp}` for O(1) lookup. Password change is atomic (single `db.update()`). IAM: roles with path-based permissions, account role assignment. `_auth/` excluded from replication. Transport guards: `auth-link-device` and `auth-change-password` require authenticated session; non-root users can only change own password. **Device registration**: `registerDevice(publicKey)` — client-generated keypair, no password, idempotent; `allowOpenRegistration: false` requires authenticated session. **Browser crypto**: `keyAuth.browser.ts` uses `@noble/ed25519` with DER↔raw key bridge for server compatibility. **BodClient autoAuth**: `autoAuth: true` auto-generates keypair (localStorage), registers, authenticates — zero-config device identity. `client.auth.*` convenience methods for all auth ops. **IAM transport ops**: `auth-create-role`, `auth-delete-role`, `auth-update-roles` (root only), `auth-list-accounts`, `auth-list-roles`. Device accounts (no encrypted key) safely reject `linkDevice`/`changePassword`.
 
 ## MCP Server
@@ -122,3 +130,4 @@ bun test tests/storage.test.ts  # single file
 - [x] Phase 10: VFS — Virtual File System (VFSEngine, LocalBackend, REST + WS transport, VFSClient)
 - [x] Phase 11: BodClientCached — two-tier cache (memory + IndexedDB), stale-while-revalidate, updatedAt protocol
 - [x] Phase 12: KeyAuth — Ed25519 identity & IAM (KeyAuthEngine, accounts, devices, challenge-response, sessions, roles, self-signed tokens)
+- [x] Phase 13: Optimization — request timeouts, connection/sub caps, SQL query push-down, broadcast groups, async batched notifications, batch re-subscribe, cursor-based materialize, replication event batching, auth rate limiting, configurable PBKDF2

package/admin/admin.ts

@@ -21,11 +21,20 @@ const UI_PATH = join(import.meta.dir, 'ui.html');
 export function startAdminUI(options?: { port?: number; serverUrl?: string }) {
   const uiPort = options?.port ?? DEFAULT_UI_PORT;
   const serverUrl = options?.serverUrl ?? DEFAULT_SERVER_URL;
+  // Derive HTTP base URL from WS URL (ws:// → http://, wss:// → https://)
+  const httpBase = serverUrl.replace(/^ws(s?):\/\//, 'http$1://');
 
   const server = Bun.serve({
     port: uiPort,
     async fetch(req) {
       const url = new URL(req.url);
+
+      // Proxy API calls to the BodDB server
+      if (url.pathname.startsWith('/db/') || url.pathname.startsWith('/files/') || url.pathname.startsWith('/sse/')) {
+        const target = httpBase + url.pathname + url.search;
+        return fetch(target, { method: req.method, headers: req.headers, body: req.body });
+      }
+
       if (url.pathname === '/' || url.pathname === '/ui.html') {
         let html = await Bun.file(UI_PATH).text();
         html = html.replace(

package/admin/demo.config.ts

@@ -23,6 +23,7 @@ export default {
   vectors: { dimensions: 384 },
   vfs: { storageRoot: VFS_ROOT },
   keyAuth: {},
+  log: { enabled: true, level: 'info', components: '*' },
   replication: {
     role: 'primary',
     sources: [{

package/admin/ui.html

@@ -45,7 +45,8 @@
 
   /* Right pane */
   #right-pane { flex: 1; display: flex; flex-direction: column; overflow: hidden; }
-  .tabs { display: flex; background: #161616; border-bottom: 1px solid #2a2a2a; overflow-x: auto; overflow-y: hidden; scrollbar-width: thin; }
+  .tabs { display: flex; background: #161616; border-bottom: 1px solid #2a2a2a; overflow-x: auto; overflow-y: hidden; scrollbar-width: none; }
+  .tabs::-webkit-scrollbar { display: none; }
   .tab { padding: 7px 16px; cursor: pointer; border-bottom: 2px solid transparent; color: #666; font-size: 12px; white-space: nowrap; flex-shrink: 0; }
   .tab.active { color: #fff; border-bottom-color: #569cd6; }
   .panel { display: none; flex: 1; overflow-y: auto; padding: 12px; flex-direction: column; gap: 10px; }
@@ -134,6 +135,7 @@
     <div class="metric-top"><span class="metric-label">Uptime</span><span class="metric-value dim" id="s-uptime">—</span></div>
     <div style="margin-top:4px;font-size:10px;color:#555" id="s-ts">—</div>
     <div style="margin-top:4px"><span class="metric-label">WS<span id="ws-dot"></span></span> <span style="font-size:10px;color:#555"><span id="s-clients">0</span> clients · <span id="s-subs">0</span> subs</span></div>
+    <div style="margin-top:6px"><button id="stats-toggle" class="sm" onclick="toggleStats()" title="Toggle server stats collection">Stats: ON</button></div>
   </div>
 </div>
 
@@ -1210,6 +1212,21 @@ async function measurePing() {
 }
 setInterval(measurePing, 2000);
 
+let _statsEnabled = true;
+async function toggleStats() {
+  try {
+    const result = await db._send('admin-stats-toggle', { enabled: !_statsEnabled });
+    _statsEnabled = result.enabled;
+    const btn = document.getElementById('stats-toggle');
+    btn.textContent = 'Stats: ' + (_statsEnabled ? 'ON' : 'OFF');
+    btn.style.color = _statsEnabled ? '#4ec9b0' : '#f48771';
+    if (!_statsEnabled) {
+      // Clear displays
+      for (const id of ['s-cpu','s-heap','s-rss','s-nodes']) document.getElementById(id).textContent = '—';
+    }
+  } catch (e) { console.warn('Stats toggle failed:', e); }
+}
+
 db.on('_admin/stats', (snap) => {
   const s = snap.val();
   if (!s) return;
@@ -1437,7 +1454,7 @@ function renderChildren(children, parentPath) {
       html += `<div class="tree-leaf" data-path="${escHtml(path)}" onclick="selectPath('${path.replace(/'/g, "\\'")}')"><span class="tree-key">${escHtml(ch.key)}</span>${ttlBadge}<span class="tree-val">${escHtml(String(display ?? ''))}</span></div>`;
     } else {
       const isOpen = _restoredOpenPaths.has(path);
-      html += `<details data-path="${escHtml(path)}"${isOpen ? ' open' : ''}><summary onclick="selectPath('${path.replace(/'/g, "\\'")}')">${escHtml(ch.key)}${ttlBadge}</summary><div class="tree-children" data-parent="${escHtml(path)}"></div></details>`;
+      html += `<details data-path="${escHtml(path)}"${isOpen ? ' open' : ''}><summary><span onclick="selectPath('${path.replace(/'/g, "\\'")}')">${escHtml(ch.key)}${ttlBadge}</span></summary><div class="tree-children" data-parent="${escHtml(path)}"></div></details>`;
     }
   }
   return html;
@@ -2598,6 +2615,19 @@ async function doMqDemo() {
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Fetch that always returns { ok, error?, data?, status } — never throws on non-2xx or non-JSON */
+async function apiFetch(url, opts) {
+  let res;
+  try { res = await fetch(url, opts); } catch (e) { return { ok: false, error: e.message }; }
+  const ct = res.headers.get('content-type') || '';
+  if (ct.includes('application/json')) {
+    try { return await res.json(); } catch (e) { return { ok: false, error: 'Invalid JSON: ' + e.message }; }
+  }
+  const text = await res.text().catch(() => res.statusText);
+  return { ok: false, error: res.status + ' ' + (text || res.statusText) };
+}
+
 function showStatus(id, msg, ok, ms) {
   const el = document.getElementById(id);
   el.className = 'status ' + (ok ? 'ok' : 'err');
@@ -2704,8 +2734,7 @@ async function vfsNavigate(path) {
   const tbl = document.getElementById('vfs-table');
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + (vfsPath || '') + '?list=1');
-    const json = await res.json();
+    const json = await apiFetch('/files/' + (vfsPath || '') + '?list=1');
     const ms = performance.now() - t0;
     if (!json.ok) { tbl.innerHTML = '<div style="padding:12px;color:#f44">Error: ' + (json.error || 'Failed') + '</div>'; return; }
     const items = json.data || [];
@@ -2799,8 +2828,7 @@ async function vfsUploadHere() {
   const path = (vfsPath ? vfsPath + '/' : '') + file.name;
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path, { method: 'POST', body: file, headers: { 'Content-Type': file.type || 'application/octet-stream' } });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path, { method: 'POST', body: file, headers: { 'Content-Type': file.type || 'application/octet-stream' } });
     showStatus('vfs-explorer-status', json.ok ? 'Uploaded ' + file.name : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-explorer-status', e.message, false, performance.now() - t0); }
   fileInput.value = '';
@@ -2836,11 +2864,10 @@ async function vfsSyncFolder() {
     const batch = files.slice(i, i + 5);
     const results = await Promise.allSettled(batch.map(async (f) => {
       const file = await f.handle.getFile();
-      const res = await fetch('/files/' + basePath + '/' + f.path, {
+      const json = await apiFetch('/files/' + basePath + '/' + f.path, {
         method: 'POST', body: file,
         headers: { 'Content-Type': file.type || 'application/octet-stream' }
       });
-      const json = await res.json();
       if (!json.ok) throw new Error(json.error);
     }));
     for (const r of results) r.status === 'fulfilled' ? ok++ : fail++;
@@ -2857,8 +2884,7 @@ async function vfsMkdirHere() {
   const path = (vfsPath ? vfsPath + '/' : '') + name;
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path + '?mkdir=1', { method: 'POST' });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path + '?mkdir=1', { method: 'POST' });
     showStatus('vfs-explorer-status', json.ok ? 'Created ' + name : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-explorer-status', e.message, false, performance.now() - t0); }
   vfsNavigate(vfsPath);
@@ -2885,8 +2911,7 @@ async function vfsRename() {
   const dst = (vfsPath ? vfsPath + '/' : '') + newName;
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + vfsSelected.fullPath + '?move=' + encodeURIComponent(dst), { method: 'PUT' });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + vfsSelected.fullPath + '?move=' + encodeURIComponent(dst), { method: 'PUT' });
     showStatus('vfs-explorer-status', json.ok ? 'Renamed → ' + newName : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-explorer-status', e.message, false, performance.now() - t0); }
   vfsNavigate(vfsPath);
@@ -2896,8 +2921,7 @@ async function vfsDeleteSel() {
   if (!vfsSelected) return;
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + vfsSelected.fullPath, { method: 'DELETE' });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + vfsSelected.fullPath, { method: 'DELETE' });
     showStatus('vfs-explorer-status', json.ok ? 'Deleted ' + vfsSelected.name : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-explorer-status', e.message, false, performance.now() - t0); }
   vfsSelected = null;
@@ -2914,8 +2938,7 @@ async function doVfsUpload() {
   const file = fileInput.files[0];
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path, { method: 'POST', body: file, headers: { 'Content-Type': file.type || 'application/octet-stream' } });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path, { method: 'POST', body: file, headers: { 'Content-Type': file.type || 'application/octet-stream' } });
     const ms = performance.now() - t0;
     if (json.ok) {
       for (const id of ['vfs-download-path','vfs-stat-path','vfs-delete-path','vfs-move-src']) document.getElementById(id).value = path;
@@ -2948,8 +2971,7 @@ async function doVfsStat() {
   if (!path) return showStatus('vfs-stat-status', 'Path required', false);
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path + '?stat=1');
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path + '?stat=1');
     const ms = performance.now() - t0;
     const el = document.getElementById('vfs-stat-result');
     if (json.ok) { el.style.display = 'block'; el.textContent = JSON.stringify(json.data, null, 2); }
@@ -2963,8 +2985,7 @@ async function doVfsList() {
   if (!path) return showStatus('vfs-list-status', 'Path required', false);
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path + '?list=1');
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path + '?list=1');
     const ms = performance.now() - t0;
     const el = document.getElementById('vfs-list-result');
     if (json.ok) { el.style.display = 'block'; el.textContent = JSON.stringify(json.data, null, 2); }
@@ -2978,8 +2999,7 @@ async function doVfsMkdir() {
   if (!path) return showStatus('vfs-mkdir-status', 'Path required', false);
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path + '?mkdir=1', { method: 'POST' });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path + '?mkdir=1', { method: 'POST' });
     showStatus('vfs-mkdir-status', json.ok ? `Created: ${path}` : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-mkdir-status', e.message, false, performance.now() - t0); }
 }
@@ -2990,8 +3010,7 @@ async function doVfsMove() {
   if (!src || !dst) return showStatus('vfs-move-status', 'Both paths required', false);
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + src + '?move=' + encodeURIComponent(dst), { method: 'PUT' });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + src + '?move=' + encodeURIComponent(dst), { method: 'PUT' });
     showStatus('vfs-move-status', json.ok ? `Moved → ${json.data.path}` : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-move-status', e.message, false, performance.now() - t0); }
 }
@@ -3001,8 +3020,7 @@ async function doVfsDelete() {
   if (!path) return showStatus('vfs-delete-status', 'Path required', false);
   const t0 = performance.now();
   try {
-    const res = await fetch('/files/' + path, { method: 'DELETE' });
-    const json = await res.json();
+    const json = await apiFetch('/files/' + path, { method: 'DELETE' });
     showStatus('vfs-delete-status', json.ok ? `Deleted: ${path}` : (json.error || 'Failed'), json.ok, performance.now() - t0);
   } catch (e) { showStatus('vfs-delete-status', e.message, false, performance.now() - t0); }
 }
@@ -3098,12 +3116,11 @@ function kaSend(op, params = {}) {
 async function loadKeyAuth() {
   if (!db.connected) { setTimeout(loadKeyAuth, 300); return; }
   try {
-    const [server, accounts, roles] = await Promise.all([
+    // Always fetch server info (unauthenticated read) + fingerprints (no auth needed)
+    const [server, fingerprints] = await Promise.all([
       db.get('_auth/server'),
-      kaSend('auth-list-accounts'),
-      kaSend('auth-list-roles'),
+      kaSend('auth-list-account-fingerprints'),
     ]);
-    _kaAccounts = accounts || [];
 
     // Server info
     const sEl = document.getElementById('ka-server');
@@ -3113,23 +3130,36 @@ async function loadKeyAuth() {
       sEl.textContent = 'KeyAuth not enabled.\nAdd keyAuth: {} to config.ts';
     }
 
+    // Try authenticated endpoints (full accounts + roles); fall back to fingerprints-only
+    let accounts = null, roles = null;
+    try {
+      [accounts, roles] = await Promise.all([
+        kaSend('auth-list-accounts'),
+        kaSend('auth-list-roles'),
+      ]);
+    } catch {}
+
+    const authenticated = !!accounts;
+    _kaAccounts = accounts || (fingerprints || []).map(f => ({ ...f, roles: [] }));
+
     // Accounts list
     const aEl = document.getElementById('ka-accounts');
     if (_kaAccounts.length) {
       aEl.innerHTML = _kaAccounts.map(a => {
         const fp = a.fingerprint;
         const name = a.displayName || '—';
-        const rls = (a.roles || []).join(', ') || 'none';
-        const isDevice = !a.encryptedPrivateKey;
+        const rls = authenticated ? ((a.roles || []).join(', ') || 'none') : '';
+        const isDevice = authenticated && !a.encryptedPrivateKey;
         const expanded = _kaExpandedFp === fp;
         return `<div style="border:1px solid #333;border-radius:4px;padding:6px;margin-bottom:4px;cursor:pointer" onclick="kaExpandAccount('${fp}')">
-          <span style="font-weight:bold">${name}</span> [${rls}] ${isDevice ? '<span style="color:#888">(device)</span>' : ''}
+          <span style="font-weight:bold">${name}</span>${rls ? ' [' + rls + ']' : ''} ${isDevice ? '<span style="color:#888">(device)</span>' : ''}
           <span style="color:#666;font-size:11px;float:right">${fp.slice(0,12)}… ${expanded?'▼':'▶'}</span>
           <div id="ka-detail-${fp}" style="display:${expanded?'block':'none'};margin-top:6px;padding-top:6px;border-top:1px solid #333"></div>
         </div>`;
       }).join('');
+      if (!authenticated) aEl.innerHTML += '<div style="color:#888;font-size:12px;margin-top:4px">Authenticate to see roles &amp; details</div>';
       // If expanded, load detail
-      if (_kaExpandedFp) kaLoadDetail(_kaExpandedFp);
+      if (_kaExpandedFp && authenticated) kaLoadDetail(_kaExpandedFp);
     } else {
       aEl.innerHTML = '<div class="result">No accounts yet.</div>';
     }
@@ -3142,7 +3172,7 @@ async function loadKeyAuth() {
         return `<div style="margin-bottom:2px">${r.id}: ${r.name||r.id} → ${perms||'none'} <button class="sm" onclick="kaDeleteRole('${r.id}')" style="float:right">×</button></div>`;
       }).join('');
     } else {
-      rEl.textContent = 'No roles.';
+      rEl.textContent = authenticated ? 'No roles.' : 'Authenticate to view roles';
     }
 
     // Populate dropdowns
@@ -3150,8 +3180,8 @@ async function loadKeyAuth() {
     sel.innerHTML = _kaAccounts.map(a => `<option value="${a.fingerprint}">${a.displayName||a.fingerprint.slice(0,12)}</option>`).join('');
     const authSel = document.getElementById('ka-auth-fp');
     const prevFp = authSel.value;
-    const pwAccounts = _kaAccounts.filter(a => !!a.encryptedPrivateKey);
-    authSel.innerHTML = '<option value="">— select account —</option>' + pwAccounts.map(a => `<option value="${a.fingerprint}"${a.fingerprint===prevFp?' selected':''}>${a.displayName||a.fingerprint.slice(0,12)} [${(a.roles||[]).join(',')||'none'}]</option>`).join('');
+    const pwAccounts = authenticated ? _kaAccounts.filter(a => !!a.encryptedPrivateKey) : _kaAccounts;
+    authSel.innerHTML = '<option value="">— select account —</option>' + pwAccounts.map(a => `<option value="${a.fingerprint}"${a.fingerprint===prevFp?' selected':''}>${a.displayName||a.fingerprint.slice(0,12)}${authenticated ? ' [' + ((a.roles||[]).join(',')||'none') + ']' : ''}</option>`).join('');
   } catch (e) {
     document.getElementById('ka-server').textContent = 'Error: ' + e.message;
   }

package/docs/keyauth-integration.md

@@ -0,0 +1,141 @@
+# KeyAuth Integration Guide
+
+BodDB's auth system has two identity layers — **accounts** (portable, password-protected) and **devices** (device-bound, no password). Understanding which to use is critical.
+
+---
+
+## Identity Model
+
+| Type | Private key lives | Auth method | Portable? |
+|------|------------------|-------------|-----------|
+| **Account** | Encrypted in DB (password-protected) | Password (to unlock/link) | Yes — any device |
+| **Device** | Client only (localStorage / memory) | Challenge-response (Ed25519) | No — tied to this client |
+
+**Root** — first account ever created is auto-elevated to root. Server-level privileges.
+
+---
+
+## When to use what
+
+**Use `autoAuth: true` (device-only)** when:
+- You need zero-config anonymous identity (e.g. telemetry, guest sessions)
+- Identity loss is acceptable (clearing localStorage = new identity)
+- No cross-device portability needed
+
+**Use account + linked device** when:
+- Users have passwords and expect to sign in from multiple devices
+- Identity must survive localStorage wipe
+- You need IAM roles assigned to a persistent identity
+
+---
+
+## Flows
+
+### Signup (new user, first device)
+
+```ts
+const client = new BodClient({ url: 'ws://localhost:4400' });
+await client.connect();
+
+// 1. Generate device keypair (client-side, stored in localStorage)
+const kp = await generateDeviceKeypair(); // your key generation
+
+// 2. Create account — auto-links this device
+const account = await client.auth.createAccount(
+  password,
+  [],           // roles (root assigns later)
+  'alice',      // displayName
+  kp.publicKey  // auto-links device → no separate linkDevice call needed
+);
+// account.isRoot === true if this is the very first account on the server
+
+// 3. Authenticate with the device keypair
+const { token } = await client.auth.authenticate(kp.publicKey, kp.signFn);
+```
+
+### Sign in (same device, returning user)
+
+```ts
+// Device keypair is already in localStorage — just authenticate
+const { token } = await client.auth.authenticate(kp.publicKey, kp.signFn);
+// Send token on subsequent requests (handled automatically by BodClient)
+```
+
+### Sign in from a new device
+
+```ts
+// On the NEW device:
+const newKp = await generateDeviceKeypair();
+
+// Link it to the existing account (requires password)
+await client.auth.linkDeviceByName('alice', password, newKp.publicKey, 'MacBook Pro');
+// or by fingerprint:
+await client.auth.linkDevice(accountFingerprint, password, newKp.publicKey, 'MacBook Pro');
+
+// Now authenticate with the new device — no password needed again
+const { token } = await client.auth.authenticate(newKp.publicKey, newKp.signFn);
+```
+
+### autoAuth (zero-config device identity)
+
+```ts
+// Keypair auto-generated + stored in localStorage, registered + authenticated on connect
+const client = new BodClient({ url: 'ws://localhost:4400', autoAuth: true });
+await client.connect();
+// client.deviceFingerprint and client.authToken are set automatically
+```
+
+> ⚠️ `autoAuth` creates a device-only identity. There is no account behind it — no password, no cross-device portability. Clearing localStorage permanently loses this identity.
+
+---
+
+## Common mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Using `autoAuth` for user accounts | Identity lost on localStorage clear | Use `createAccount` + `linkDevice` |
+| Calling `createAccount` without `devicePublicKey` | Have to call `linkDevice` separately | Pass `devicePublicKey` to `createAccount` |
+| Not knowing account fingerprint on new device | Can't call `linkDevice` | Use `linkDeviceByName(displayName, ...)` instead |
+| Assuming `autoAuth` device has an account | Device accounts reject `linkDevice`/`changePassword` | They're standalone — no account behind them |
+
+---
+
+## Server setup
+
+```ts
+import { BodDB } from 'bod-db';
+import { KeyAuthEngine } from 'bod-db/server';
+
+const db = new BodDB({
+  keyAuth: {
+    allowOpenRegistration: false, // require auth session to register devices (recommended)
+    maxAuthFailures: 10,
+    authLockoutSeconds: 300,
+  }
+});
+```
+
+`allowOpenRegistration: true` (default) allows any client to register a device without being authenticated first — fine for open apps, restrict for closed ones.
+
+---
+
+## IAM roles
+
+Roles are assigned to **accounts** (not devices). Devices inherit the account's roles via the linked account fingerprint.
+
+```ts
+// Root only
+await client.auth.createRole({
+  id: 'editor',
+  name: 'Editor',
+  permissions: [
+    { path: 'posts/$postId', read: true, write: true },
+    { path: 'users/$uid/profile', read: true },
+  ]
+});
+
+// Assign to account (root only)
+await client.auth.updateRoles(accountFingerprint, ['editor']);
+```
+
+Rules engine receives `auth.roles`, `auth.fingerprint`, `auth.accountFingerprint` in context.

package/index.ts

@@ -26,3 +26,5 @@ export { increment, serverTimestamp, arrayUnion, arrayRemove, ref } from './src/
 export * from './src/shared/protocol.ts';
 export * from './src/shared/errors.ts';
 export { normalizePath, validatePath, ancestors, parentPath, pathKey, prefixEnd, flatten, reconstruct } from './src/shared/pathUtils.ts';
+export { Logger } from './src/shared/logger.ts';
+export type { LogConfig, LogLevel } from './src/shared/logger.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bod.ee/db",
-  "version": "0.10.2",
+  "version": "0.12.1",
   "module": "index.ts",
   "type": "module",
   "exports": {