@bod.ee/db 0.9.0 → 0.10.1

package/.claude/settings.local.json

@@ -23,7 +23,13 @@
       "Bash(lsof -ti:4400,4401 2>/dev/null | xargs kill -9 2>/dev/null)",
       "WebFetch(domain:151.145.81.254)",
       "WebFetch(domain:db-main.bod.ee)",
-      "Bash(md5:*)"
+      "Bash(md5:*)",
+      "Bash(lsof -ti :4400 | xargs kill -9 2>/dev/null)",
+      "WebFetch(domain:stack.convex.dev)",
+      "WebFetch(domain:caniuse.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:api.github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)"
     ]
   }
 }

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

@@ -42,6 +42,7 @@ export default {
   mq: { visibilityTimeout: 30, maxDeliveries: 5 },
   compact: { 'events/logs': { maxAge: 86400 } },
   vfs: { storageRoot: './files' },
+  keyAuth: { sessionTtl: 86400, nonceTtl: 60, rootPublicKey: '<base64>' },
   replication: {
     role: 'primary',
     sources: [

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

@@ -18,6 +18,7 @@ src/shared/pathUtils.ts         — path validation, flatten/reconstruct, ancest
 src/shared/protocol.ts          — wire message types (ClientMessage, ServerMessage, BatchOp)
 src/shared/errors.ts            — BodError class, error codes
 src/shared/transforms.ts        — sentinel classes, factory fns, resolveTransforms
+src/shared/keyAuth.ts           — KeyAuth types + Ed25519/AES-256-GCM crypto utils
 src/server/StorageEngine.ts     — SQLite CRUD, leaf flattening, prefix queries, transforms, TTL, push
 src/server/SubscriptionEngine.ts — value + child subs, ancestor walk, added/changed/removed
 src/server/QueryEngine.ts       — fluent builder delegating to StorageEngine.query
@@ -33,7 +34,8 @@ src/server/FileAdapter.ts       — file system sync, watch, metadata, content r
 src/server/ReplicationEngine.ts  — primary/replica replication: write hooks, _repl stream, bootstrap, proxy
 src/server/VFSEngine.ts         — virtual file system: backend abstraction, LocalBackend, metadata in DB
 src/client/BodClient.ts         — WS client: CRUD, batch, push, subs, streams, VFS, auto-reconnect
-src/client/CachedClient.ts      — two-tier cache (memory + IndexedDB): stale-while-revalidate, sub-aware
+src/server/KeyAuthEngine.ts      — Ed25519 identity & IAM: accounts, devices, challenge-response, sessions
+src/client/BodClientCached.ts      — two-tier cache (memory + IndexedDB): stale-while-revalidate, sub-aware
 src/react/hooks.ts              — useValue, useChildren, useQuery, useMutation
 client.ts                       — client entry point
 react.ts                        — React hooks entry point
@@ -91,8 +93,11 @@ Push paths are append-only logs. `StreamEngine` adds consumer group offsets (`_s
 ### VFS (Virtual File System)
 `VFSEngine` — pluggable `VFSBackend` interface (`read/write/delete/exists`). `LocalBackend` stores files at `<storageRoot>/<fileId>` via `Bun.file`/`Bun.write`. fileId = pushId (move/rename = metadata-only). Metadata stored at `_vfs/<path>/__meta` (uses `__meta` key to avoid collision with children in leaf-flattened storage). Gets subscriptions, rules, replication for free. REST transport at `/files/<path>`, WS chunked fallback (base64, 48KB chunks). Client: `VFSClient` via `client.vfs()`.
 
-### CachedClient
-`CachedClient` wraps `BodClient` with two-tier cache: in-memory `Map` (LRU, insertion-ordered eviction) + IndexedDB (`entries` object store, keyPath `path`). `get()` uses stale-while-revalidate: subscribed paths return immediately (sub keeps cache fresh), unsubscribed return stale + background `getSnapshot()`. Writes (`set/update/delete`) invalidate path + all ancestors via `pathUtils.ancestors()`. `init()` opens IDB + sweeps expired. `warmup()` bulk-loads synchronously in single IDB transaction. `close()` cleans up. Protocol: `StorageEngine.getWithMeta()` returns `{ data, updatedAt }`, `ValueSnapshot.updatedAt` carries it to client.
+### BodClientCached
+`BodClientCached` wraps `BodClient` with two-tier cache: in-memory `Map` (LRU, insertion-ordered eviction) + IndexedDB (`entries` object store, keyPath `path`). `get()` uses stale-while-revalidate: subscribed paths return immediately (sub keeps cache fresh), unsubscribed return stale + background `getSnapshot()`. Writes (`set/update/delete`) invalidate path + all ancestors via `pathUtils.ancestors()`. `init()` opens IDB + sweeps expired. `warmup()` bulk-loads synchronously in single IDB transaction. `close()` cleans up. Protocol: `StorageEngine.getWithMeta()` returns `{ data, updatedAt }`, `ValueSnapshot.updatedAt` carries it to client.
+
+### 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.
 
 ### 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.
@@ -125,11 +130,12 @@ Path patterns with `$wildcard` capture. Most specific match wins. Supports boole
 - **Phase 8** (DONE): MCP server — MCPAdapter, stdio + HTTP, BodClient-based, 21 tools
 - **Phase 9** (DONE): Replication — ReplicationEngine, primary + read replicas, write proxy, bootstrap, _repl stream
 - **Phase 10** (DONE): VFS — VFSEngine, LocalBackend, REST + WS transport, VFSClient SDK
-- **Phase 11** (DONE): CachedClient — two-tier cache (memory + IndexedDB), stale-while-revalidate, updatedAt protocol
+- **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
 
 ## Testing
 
-- `bun test` — 228 tests across 22 files
+- `bun test` — 266 tests across 23 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

@@ -212,18 +212,18 @@ snap.val();       // { name: 'Alice' }
 snap.updatedAt;   // 1708900000000 (ms timestamp from server)
 ```
 
-## CachedClient (Browser Cache)
+## BodClientCached (Browser Cache)
 
 Two-tier cache wrapper around BodClient: in-memory Map (LRU) + IndexedDB persistence.
 Stale-while-revalidate: subscribed paths always fresh, unsubscribed return stale + background refetch.
 
 ```typescript
-import { BodClient, CachedClient } from 'bod-db/client';
+import { BodClient, BodClientCached } from 'bod-db/client';
 
 const client = new BodClient({ url: 'ws://localhost:4400' });
 await client.connect();
 
-const cached = new CachedClient(client, {
+const cached = new BodClientCached(client, {
   maxAge: 7 * 24 * 60 * 60 * 1000, // IDB entry TTL (7 days)
   maxMemoryEntries: 500,             // LRU eviction cap
   dbName: 'boddb-cache',             // IndexedDB database name
@@ -469,7 +469,7 @@ await replica.replication!.start();
 - Replicas bootstrap full state on first connect, then consume live events
 - Push keys preserved across replicas (deterministic)
 - Auto-compaction on `_repl` stream (keepKey: 'path', maxCount: 10000)
-- Excluded prefixes: `_repl`, `_streams`, `_mq` (internal data not replicated)
+- Excluded prefixes: `_repl`, `_streams`, `_mq`, `_auth` (internal data not replicated)
 
 ### Multi-Source Feed Subscriptions
 
@@ -552,6 +552,125 @@ PUT    /files/<path>?move=dst  — move/rename
 DELETE /files/<path>           — delete
 ```
 
+## KeyAuth (Ed25519 Identity & IAM)
+
+Portable, zero-dependency authentication. Your identity is an Ed25519 key pair.
+
+```typescript
+// Server — enable KeyAuth
+const db = new BodDB({
+  keyAuth: {},  // auto-generates server key pair
+  // or with root:
+  // keyAuth: { rootPublicKey: rootPubKeyBase64 },
+});
+db.serve();
+
+// Create accounts (server-side) — first account auto-becomes root
+const { publicKey, fingerprint, isRoot, deviceFingerprint } = db.keyAuth!.createAccount(
+  'password', ['editor'], 'Alice', devicePubKeyBase64 // optional: auto-link calling device
+);
+
+// Link a device (password is the auth — no session required)
+db.keyAuth!.linkDevice(fingerprint, 'password', devicePubKeyBase64, 'My Laptop');
+
+// Manage roles
+db.keyAuth!.createRole({ id: 'editor', name: 'Editor', permissions: [{ path: 'posts', read: true, write: true }] });
+db.keyAuth!.updateAccountRoles(fingerprint, ['editor']);
+
+// Change password (fingerprint stays stable)
+db.keyAuth!.changePassword(fingerprint, 'old-pw', 'new-pw');
+
+// Revoke device or session
+db.keyAuth!.revokeDevice(accountFp, deviceFp);
+db.keyAuth!.revokeSession(sid);
+```
+
+### Client Auth — Device Identity (recommended for browser apps)
+
+```typescript
+import { BodClient } from 'bod-db/client';
+
+// Zero-config: auto-generates Ed25519 keypair, stores in localStorage, registers, authenticates
+const client = new BodClient({
+  url: 'ws://localhost:4400',
+  autoAuth: true, // or { displayName: 'My App' }
+});
+await client.connect(); // fully authenticated — no user interaction needed
+console.log(client.deviceFingerprint); // SHA-256 of public key
+```
+
+### Client Auth — Manual (explicit keypair control)
+
+```typescript
+import { BodClient, generateKeyPair, sign } from 'bod-db/client';
+
+const kp = await generateKeyPair(); // browser-compatible Ed25519
+const client = new BodClient({
+  url: 'ws://localhost:4400',
+  keyAuth: {
+    publicKey: kp.publicKeyBase64,
+    signFn: (nonce) => sign(nonce, kp.privateKeyBase64),
+  },
+});
+await client.connect();
+
+// Convenience auth methods
+await client.auth.registerDevice(kp.publicKeyBase64, 'My Device');
+await client.auth.linkDevice(accountFp, password, devicePubKey);
+await client.auth.revokeSession(sid);
+await client.auth.changePassword(fp, oldPw, newPw);
+await client.auth.hasAccounts();                 // → boolean (no auth needed)
+await client.auth.listAccountFingerprints();     // → [{ fingerprint, displayName }] (no auth needed)
+await client.auth.getAccountInfo(accountFp?);    // → { fingerprint, displayName, roles, isRoot, createdAt } (auth needed)
+```
+
+### Wire Protocol
+
+```typescript
+// Register device (client-generated keypair, no password)
+ws.send(JSON.stringify({ id: '0', op: 'auth-register-device', publicKey: '...', displayName: '...' }));
+// → { id: '0', ok: true, data: { fingerprint: '...' } }
+
+// Challenge
+ws.send(JSON.stringify({ id: '1', op: 'auth-challenge' }));
+// → { id: '1', ok: true, data: { nonce: '...', serverId: '...' } }
+
+// Verify (sign nonce with Ed25519)
+ws.send(JSON.stringify({ id: '2', op: 'auth-verify', publicKey: '...', signature: '...', nonce: '...' }));
+// → { id: '2', ok: true, data: { token: '...', expiresAt: 1234567890 } }
+
+// Create account (first account auto-becomes root; unauthenticated only when zero accounts exist)
+ws.send(JSON.stringify({ id: '3', op: 'auth-create-account', password: '...', displayName: '...', devicePublicKey: '...' }));
+// → { ..., data: { publicKey, fingerprint, isRoot, deviceFingerprint? } }
+
+// Link device (password is the auth — no session required)
+ws.send(JSON.stringify({ id: '4', op: 'auth-link-device', accountFingerprint: '...', password: '...', devicePublicKey: '...' }));
+
+// Change password (password is the auth; if authenticated, non-root can only change own)
+ws.send(JSON.stringify({ id: '5', op: 'auth-change-password', fingerprint: '...', oldPassword: '...', newPassword: '...' }));
+
+// Check if accounts exist (no auth required)
+ws.send(JSON.stringify({ id: '6', op: 'auth-has-accounts' }));
+// → { ..., data: { hasAccounts: true } }
+
+// List account fingerprints (no auth required, no secrets)
+ws.send(JSON.stringify({ id: '7', op: 'auth-list-account-fingerprints' }));
+// → { ..., data: [{ fingerprint: '...', displayName: '...' }] }
+
+// Get account info (authenticated, defaults to own account)
+ws.send(JSON.stringify({ id: '8', op: 'auth-account-info', accountFingerprint: '...' }));
+// → { ..., data: { fingerprint, displayName, roles, isRoot, createdAt } }
+```
+
+### Security
+
+- `_auth/` prefix protected: external writes blocked via Transport
+- Server private key: filesystem only (never DB/wire)
+- Account private key: AES-256-GCM encrypted, decrypted only in memory, wiped after use
+- Nonce: deleted immediately after use + short TTL (prevents replay)
+- Device reverse-index: O(1) device→account lookup
+- Password change: atomic (single `db.update()`)
+
 ## Best Practices
 
 1. **Paths are your schema** — design upfront (`users/$uid/settings/theme`)
@@ -565,4 +684,5 @@ DELETE /files/<path>           — delete
 9. **`port: 0` in tests** — random available port
 10. **Streams for event processing** — consumer groups with offset tracking, replay on reconnect
 11. **Idempotent push** — dedup with `idempotencyKey` to prevent duplicate events
-12. **CachedClient for browsers** — wrap BodClient for instant reads + cross-reload persistence via IndexedDB
+12. **BodClientCached for browsers** — wrap BodClient for instant reads + cross-reload persistence via IndexedDB
+13. **KeyAuth for portable identity** — Ed25519 key pairs, no external auth services needed

package/CLAUDE.md

@@ -24,8 +24,11 @@ src/server/FileAdapter.ts  — file system sync: scan, watch, metadata, content
 src/server/MCPAdapter.ts   — MCP (Model Context Protocol) server: JSON-RPC dispatch, tool registry, stdio + HTTP transports
 src/server/VFSEngine.ts     — virtual file system: VFSBackend interface, LocalBackend (disk), metadata in DB
 src/server/ReplicationEngine.ts — replication: primary/replica + multi-source feed subscriptions, write proxy
-src/client/BodClient.ts    — WS client: connect, auth, CRUD, batch, push, subscriptions, auto-reconnect
-src/client/CachedClient.ts — two-tier cache (memory + IndexedDB): stale-while-revalidate, sub-aware, write invalidation
+src/server/KeyAuthEngine.ts — Ed25519 identity & IAM: accounts, devices, challenge-response, sessions, roles
+src/shared/keyAuth.ts      — KeyAuth types + crypto utils (Ed25519, AES-256-GCM, PBKDF2, self-signed tokens)
+src/shared/keyAuth.browser.ts — Browser-compatible Ed25519 via @noble/ed25519 + DER↔raw key bridge
+src/client/BodClient.ts    — WS client: connect, auth, CRUD, batch, push, subscriptions, auto-reconnect, autoAuth
+src/client/BodClientCached.ts — two-tier cache (memory + IndexedDB): stale-while-revalidate, sub-aware, write invalidation
 src/react/hooks.ts         — useValue, useChildren, useQuery, useMutation
 client.ts                  — client entry point (import from 'bod-db/client')
 react.ts                   — React hooks entry point (import from 'bod-db/react')
@@ -42,7 +45,7 @@ config.ts                  — demo instance config (open rules, indexes, fts, v
 - **Subscription notify**: writes produce changedPaths → notify exact + all ancestors (deduped). Child events track added/changed/removed via pre-write existence snapshot.
 - **Path validation**: all public APIs use `validatePath()` — rejects empty paths, normalizes slashes.
 - **Options pattern**: `new XOptions()` defaults merged with partial user options.
-- **Rules**: path patterns with `$wildcard` capture, most-specific match wins. Context: `auth`, `params`, `data`, `newData`. Supports functions, booleans, expression strings, and JSON/TS config files.
+- **Rules**: path patterns with `$wildcard` capture, most-specific match wins. Context: `auth`, `params`, `data`, `newData`. Supports functions, booleans, expression strings, and JSON/TS config files. `defaultDeny: true` blocks unmatched paths (default: open).
 - **Expression rules**: safe tokenizer → recursive descent parser → AST evaluator. Supports `auth.x`, `$wildcard`, `data`/`newData`, comparisons, logical ops, negation, parens. No eval.
 - **Transforms**: sentinel values (`increment`, `serverTimestamp`, `arrayUnion`, `arrayRemove`, `ref`) resolved against current data before write.
 - **Refs**: `ref(path)` stores `{ _ref: path }`. Resolved at read time via `storage.get(path, { resolve: true })`.
@@ -58,10 +61,11 @@ config.ts                  — demo instance config (open rules, indexes, fts, v
 - **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.
-- **CachedClient**: 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`.
+- **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`. **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.
+- **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**: `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
 
@@ -116,4 +120,5 @@ bun test tests/storage.test.ts  # single file
 - [x] Phase 8: MCP server (MCPAdapter — stdio + HTTP, BodClient-based, 21 tools)
 - [x] Phase 9: Replication (ReplicationEngine — primary + read replicas, write proxy, bootstrap, _repl stream, multi-source feed subscriptions)
 - [x] Phase 10: VFS — Virtual File System (VFSEngine, LocalBackend, REST + WS transport, VFSClient)
-- [x] Phase 11: CachedClient — two-tier cache (memory + IndexedDB), stale-while-revalidate, updatedAt protocol
+- [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)

package/README.md

@@ -120,15 +120,15 @@ client.onChild('users', (e) => console.log(e.type, e.key));
 client.disconnect();
 ```
 
-## CachedClient (Browser Cache)
+## BodClientCached (Browser Cache)
 
 ```typescript
-import { BodClient, CachedClient } from 'bod-db/client';
+import { BodClient, BodClientCached } from 'bod-db/client';
 
 const client = new BodClient({ url: 'ws://localhost:4400' });
 await client.connect();
 
-const cached = new CachedClient(client, {
+const cached = new BodClientCached(client, {
   maxMemoryEntries: 500,  // LRU eviction cap
   maxAge: 7 * 24 * 3600000, // IDB TTL (7 days)
 });

package/admin/admin.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env bun
+/**
+ * BodDB Admin UI — lightweight static server.
+ * Connects to any running BodDB instance.
+ *
+ * Usage:
+ *   bun run admin                          # http://localhost:4500 → ws://localhost:4444
+ *   bun run admin --url ws://remote:4400   # connect to remote
+ *   bun run admin --port 8080              # serve UI on port 8080
+ */
+import { join } from 'path';
+
+// ── Configuration ─────────────────────────────────────────────────────────────
+const DEFAULT_SERVER_URL = 'ws://localhost:4444';
+const DEFAULT_UI_PORT = 4500;
+// ──────────────────────────────────────────────────────────────────────────────
+
+const UI_PATH = join(import.meta.dir, 'ui.html');
+
+/** Start the admin UI static server. Returns the Bun server instance. */
+export function startAdminUI(options?: { port?: number; serverUrl?: string }) {
+  const uiPort = options?.port ?? DEFAULT_UI_PORT;
+  const serverUrl = options?.serverUrl ?? DEFAULT_SERVER_URL;
+
+  const server = Bun.serve({
+    port: uiPort,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === '/' || url.pathname === '/ui.html') {
+        let html = await Bun.file(UI_PATH).text();
+        html = html.replace(
+          '</head>',
+          `<script>window.__BODDB_URL__ = ${JSON.stringify(serverUrl)};</script>\n</head>`,
+        );
+        return new Response(html, { headers: { 'Content-Type': 'text/html' } });
+      }
+      return new Response('Not found', { status: 404 });
+    },
+  });
+
+  console.log(`Admin UI → http://localhost:${server.port} → ${serverUrl}`);
+  return server;
+}
+
+// ── CLI entry point ───────────────────────────────────────────────────────────
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  let serverUrl: string | undefined;
+  let port: number | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--url' && args[i + 1]) serverUrl = args[++i];
+    if (args[i] === '--port' && args[i + 1]) port = parseInt(args[++i], 10);
+  }
+
+  startAdminUI({ port, serverUrl });
+}

package/admin/demo.config.ts

@@ -0,0 +1,132 @@
+import type { BodDB } from '../src/server/BodDB.ts';
+import type { BodDBOptions } from '../src/server/BodDB.ts';
+import { join } from 'path';
+import { rules } from './rules.ts';
+import { generateEd25519KeyPair } from '../src/shared/keyAuth.ts';
+
+// ── Configuration ─────────────────────────────────────────────────────────────
+const PORT = 4445;
+const DB_PATH = join(import.meta.dir, '../.tmp/bod-db-admin.sqlite');
+const VFS_ROOT = join(import.meta.dir, '../.tmp/vfs');
+const SOURCE_PORT = PORT + 1;
+const ADMIN_UI_PORT = PORT + 2;
+// ──────────────────────────────────────────────────────────────────────────────
+
+let sourceDb: BodDB;
+
+export default {
+  port: PORT,
+  path: DB_PATH,
+  rules,
+  sweepInterval: 60000,
+  fts: {},
+  vectors: { dimensions: 384 },
+  vfs: { storageRoot: VFS_ROOT },
+  keyAuth: {},
+  replication: {
+    role: 'primary',
+    sources: [{
+      url: `ws://localhost:${SOURCE_PORT}`,
+      paths: ['catalog', 'alerts'],
+      localPrefix: 'source',
+      id: 'admin-demo-source',
+    }],
+  },
+  transport: {
+    extraRoutes: {
+      '/replication/source-write': (req: Request) => {
+        if (req.method !== 'POST') return null;
+        return (async () => {
+          const { path, value } = await req.json() as { path: string; value: unknown };
+          sourceDb.set(path, value);
+          return Response.json({ ok: true });
+        })();
+      },
+      '/replication/source-delete': (req: Request, url: URL) => {
+        if (req.method !== 'DELETE') return null;
+        const path = url.pathname.slice('/replication/source-delete/'.length);
+        sourceDb.delete(path);
+        return Response.json({ ok: true });
+      },
+    },
+  },
+} satisfies Partial<BodDBOptions & { transport: any }>;
+
+export async function setup(db: BodDB) {
+  // ── Source DB (demo replication source) ─────────────────────────────────────
+  const { BodDB: BodDBClass } = await import('../src/server/BodDB.ts');
+  sourceDb = new BodDBClass({ path: ':memory:', sweepInterval: 0, replication: { role: 'primary' } });
+  sourceDb.replication!.start();
+  sourceDb.serve({ port: SOURCE_PORT });
+
+  sourceDb.set('catalog/widgets', { name: 'Widget A', price: 29.99, stock: 150 });
+  sourceDb.set('catalog/gadgets', { name: 'Gadget B', price: 49.99, stock: 75 });
+  sourceDb.set('catalog/gizmos', { name: 'Gizmo C', price: 19.99, stock: 300 });
+  sourceDb.set('alerts/sys-1', { level: 'warn', msg: 'CPU spike detected', ts: Date.now() });
+  sourceDb.set('alerts/sys-2', { level: 'info', msg: 'Backup completed', ts: Date.now() });
+  console.log(`Source DB: :memory: on port ${SOURCE_PORT}`);
+
+  // ── Seed KeyAuth roles & accounts ───────────────────────────────────────────
+  if (db.keyAuth && !db.get('_auth/roles/admin')) {
+    db.keyAuth.createRole({ id: 'admin', name: 'Admin', permissions: [{ path: '', read: true, write: true }] });
+    db.keyAuth.createRole({ id: 'editor', name: 'Editor', permissions: [{ path: 'posts/$id', read: true, write: true }] });
+    db.keyAuth.createRole({ id: 'viewer', name: 'Viewer', permissions: [{ path: '', read: true }] });
+    const alice = db.keyAuth.createAccount('demo123', ['admin'], 'Alice');
+    db.keyAuth.createAccount('demo123', ['editor'], 'Bob');
+    // Register a device-only "Bot" account (viewer role)
+    const botKp = generateEd25519KeyPair();
+    db.keyAuth.registerDevice(botKp.publicKeyBase64, 'Bot', ['viewer']);
+    // Link a device under Alice ("Alice's Phone")
+    const phoneKp = generateEd25519KeyPair();
+    db.keyAuth.linkDevice(alice.fingerprint, 'demo123', phoneKp.publicKeyBase64, "Alice's Phone");
+    console.log('[KeyAuth] Seeded roles: admin, editor, viewer + accounts: Alice (admin), Bob (editor), Bot (viewer/device)');
+  }
+
+  // ── Seed demo data ──────────────────────────────────────────────────────────
+  if (!db.get('users/alice')) {
+    db.set('users/alice', { name: 'Alice', age: 30, role: 'admin' });
+    db.set('users/bob', { name: 'Bob', age: 25, role: 'user' });
+    db.set('users/carol', { name: 'Carol', age: 28, role: 'user' });
+    db.set('settings/theme', 'dark');
+    db.set('settings/lang', 'en');
+    db.push('logs', { level: 'info', msg: 'Server started', ts: Date.now() });
+    db.set('counters/likes', 0);
+    db.set('counters/views', 0);
+    db.index('users/alice', 'Alice is an admin user who manages the system');
+    db.index('users/bob', 'Bob is a regular user who writes articles');
+    db.index('users/carol', 'Carol is a user interested in design and UX');
+    db.set('_fts/users_alice', { path: 'users/alice', content: 'Alice is an admin user who manages the system', indexedAt: Date.now() });
+    db.set('_fts/users_bob', { path: 'users/bob', content: 'Bob is a regular user who writes articles', indexedAt: Date.now() });
+    db.set('_fts/users_carol', { path: 'users/carol', content: 'Carol is a user interested in design and UX', indexedAt: Date.now() });
+    const makeEmb = (seed: number) => Array.from({ length: 384 }, (_, i) => Math.sin((i + seed) * 0.1) * 0.5);
+    db.vectors!.store('users/alice', makeEmb(0));
+    db.vectors!.store('users/bob', makeEmb(10));
+    db.vectors!.store('users/carol', makeEmb(20));
+    db.set('_vectors/users_alice', { path: 'users/alice', dimensions: 384, storedAt: Date.now() });
+    db.set('_vectors/users_bob', { path: 'users/bob', dimensions: 384, storedAt: Date.now() });
+    db.set('_vectors/users_carol', { path: 'users/carol', dimensions: 384, storedAt: Date.now() });
+    db.push('events/orders', { orderId: 'o1', amount: 99, status: 'completed' });
+    db.push('events/orders', { orderId: 'o2', amount: 42, status: 'pending' });
+    db.push('events/orders', { orderId: 'o3', amount: 150, status: 'completed' });
+    db.mq.push('queues/jobs', { type: 'email', to: 'alice@example.com', subject: 'Welcome' });
+    db.mq.push('queues/jobs', { type: 'sms', to: '+1234567890', body: 'Your code is 1234' });
+    db.mq.push('queues/jobs', { type: 'webhook', url: 'https://example.com/hook', payload: { event: 'signup' } });
+    if (db.vfs) {
+      db.vfs.mkdir('docs');
+      db.vfs.write('docs/readme.txt', new TextEncoder().encode('Welcome to BodDB VFS!\nThis is a demo file.'));
+      db.vfs.write('docs/config.json', new TextEncoder().encode(JSON.stringify({ theme: 'dark', lang: 'en' }, null, 2)), 'application/json');
+      db.vfs.mkdir('images');
+    }
+  }
+
+  // ── Start replication ───────────────────────────────────────────────────────
+  db.replication!.start().then(() => {
+    console.log(`[REPL] source feed connected → syncing catalog + alerts from :${SOURCE_PORT}`);
+  }).catch(e => console.error('[REPL] source feed failed:', e));
+
+  // ── Admin UI ────────────────────────────────────────────────────────────────
+  const { startAdminUI } = await import('./admin.ts');
+  startAdminUI({ port: ADMIN_UI_PORT, serverUrl: `ws://localhost:${PORT}` });
+
+  process.on('beforeExit', () => sourceDb.close());
+}

package/admin/rules.ts

@@ -4,9 +4,12 @@ import type { PathRule } from '../src/server/RulesEngine.ts';
  * Edit this file to configure access rules for the admin server.
  * Pattern syntax: exact segments or $wildcard (e.g. users/$uid)
  * Context: { auth, path, params, data, newData }
+ * auth = KeyAuthContext: { fingerprint, accountFingerprint, roles[], isRoot, sid }
  */
 export const rules: Record<string, PathRule> = {
+  '':              { read: true },
   '_admin/$any':   { read: true, write: false },
-  'users/$uid':    { write: ({ auth, params }) => auth?.role === 'admin' || ['alice', 'bob'].includes(params.uid) },
+  'users/$uid':    { write: ({ auth }) => !!auth },
   'settings/$key': { write: ({ auth }) => !!auth },
+  'admin/$any':    { read: ({ auth }) => !!(auth as any)?.isRoot, write: ({ auth }) => !!(auth as any)?.isRoot },
 };