@bod.ee/db 0.9.0 → 0.10.1

package/cli.ts

@@ -2,7 +2,6 @@
 import { BodDB } from './index.ts';
 import { existsSync, mkdirSync } from 'fs';
 import { dirname, resolve } from 'path';
-import { cpus, totalmem } from 'os';
 
 const args = process.argv.slice(2);
 const flags: Record<string, string> = {};
@@ -31,11 +30,13 @@ for (let i = 0; i < args.length; i++) {
 
 // Load config file
 let options: Record<string, unknown> = {};
+let setup: ((db: InstanceType<typeof BodDB>) => void | Promise<void>) | undefined;
 if (configPath) {
   const abs = resolve(configPath);
   if (configPath.endsWith('.ts') || configPath.endsWith('.js')) {
     const mod = await import(abs);
     options = { ...(mod.default ?? mod.config ?? mod) };
+    if (typeof mod.setup === 'function') setup = mod.setup;
   } else if (configPath.endsWith('.json')) {
     const text = require('fs').readFileSync(abs, 'utf-8');
     const parsed = JSON.parse(text);
@@ -56,7 +57,8 @@ if (dbPath !== ':memory:') {
 }
 
 const db = await BodDB.create(options as any);
-const server = db.serve();
+if (setup) await setup(db);
+const server = db.serve(options.transport as any);
 const port = server?.port ?? options.port ?? 4400;
 
 // Start replication if configured
@@ -84,47 +86,6 @@ console.log([
   '',
 ].join('\n'));
 
-// Admin stats (for admin UI stats bar)
-if (options.transport?.staticRoutes) {
-  const { statSync } = require('fs');
-  let lastCpu = process.cpuUsage();
-  let lastTime = performance.now();
-  let lastOsCpus = cpus();
-  const systemCpuPercent = (): number => {
-    const cur = cpus();
-    let idleDelta = 0, totalDelta = 0;
-    for (let i = 0; i < cur.length; i++) {
-      const prev = lastOsCpus[i]?.times ?? cur[i].times;
-      const c = cur[i].times;
-      idleDelta += c.idle - prev.idle;
-      totalDelta += (c.user + c.nice + c.sys + c.irq + c.idle) - (prev.user + prev.nice + prev.sys + prev.irq + prev.idle);
-    }
-    lastOsCpus = cur;
-    return totalDelta > 0 ? +((1 - idleDelta / totalDelta) * 100).toFixed(1) : 0;
-  };
-  setInterval(() => {
-    if (!db.subs.subscriberCount('_admin')) return;
-    const now = performance.now();
-    const cpu = process.cpuUsage();
-    const elapsedUs = (now - lastTime) * 1000;
-    const cpuPercent = +((cpu.user - lastCpu.user + cpu.system - lastCpu.system) / elapsedUs * 100).toFixed(1);
-    lastCpu = cpu; lastTime = now;
-    const mem = process.memoryUsage();
-    const nodeCount = (db.storage.db.query('SELECT COUNT(*) as n FROM nodes WHERE mq_status IS NULL').get() as any).n;
-    let dbSizeMb = 0;
-    try { dbSizeMb = +(statSync(resolve(dbPath)).size / 1024 / 1024).toFixed(2); } catch {}
-    db.set('_admin/stats', {
-      process: { cpuPercent, heapUsedMb: +(mem.heapUsed / 1024 / 1024).toFixed(2), rssMb: +(mem.rss / 1024 / 1024).toFixed(2), uptimeSec: Math.floor(process.uptime()) },
-      db: { nodeCount, sizeMb: dbSizeMb },
-      system: { cpuCores: cpus().length, totalMemMb: +(totalmem() / 1024 / 1024).toFixed(0), cpuPercent: systemCpuPercent() },
-      subs: db.subs.subscriberCount(),
-      clients: db.transport?.clientCount ?? 0,
-      repl: db.replication?.stats() ?? null,
-      ts: Date.now(),
-    });
-  }, 1000);
-}
-
 // Graceful shutdown
 process.on('SIGINT', () => { db.close(); process.exit(0); });
 process.on('SIGTERM', () => { db.close(); process.exit(0); });

package/client.ts

@@ -1,3 +1,5 @@
-export { BodClient, BodClientOptions, ValueSnapshot, ClientQueryBuilder, StreamReader, MQReader, MQMessageSnapshot, VFSClient } from './src/client/BodClient.ts';
-export type { ChildEvent, StreamEventSnapshot, FileStat } from './src/client/BodClient.ts';
-export { CachedClient, CachedClientOptions } from './src/client/CachedClient.ts';
+export { BodClient, BodClientOptions, ValueSnapshot, ClientQueryBuilder, StreamReader, MQReader, MQMessageSnapshot, VFSClient, AuthFacade } from './src/client/BodClient.ts';
+export type { ChildEvent, StreamEventSnapshot, FileStat, DeviceKeyStorage } from './src/client/BodClient.ts';
+export { BodClientCached, BodClientCachedOptions } from './src/client/BodClientCached.ts';
+export { generateKeyPair, sign, browserFingerprint, wrapPublicKey } from './src/shared/keyAuth.browser.ts';
+export type { BrowserKeyPair } from './src/shared/keyAuth.browser.ts';

package/config.ts

@@ -1,8 +1,14 @@
 import type { BodDBOptions } from './src/server/BodDB.ts';
 
+// ── Configuration ─────────────────────────────────────────────────────────────
+const PORT = 4444;
+const DB_PATH = './.tmp/bod.db';
+const VFS_ROOT = './.tmp/vfs';
+// ──────────────────────────────────────────────────────────────────────────────
+
 export default {
-  path: './.tmp/bod.db',
-  port: 4400,
+  port: PORT,
+  path: DB_PATH,
   sweepInterval: 60000,
   rules: {
     '': { read: true, write: true },
@@ -14,7 +20,8 @@ export default {
   fts: {},
   vectors: { dimensions: 384 },
   mq: { visibilityTimeout: 30, maxDeliveries: 5 },
-  vfs: { storageRoot: './.tmp/vfs' },
+  vfs: { storageRoot: VFS_ROOT },
+  keyAuth: {},
   compact: {
     'events/logs': { maxAge: 86400 },
   },

package/index.ts

@@ -13,9 +13,14 @@ export { StreamEngine, StreamEngineOptions } from './src/server/StreamEngine.ts'
 export { MQEngine, MQEngineOptions } from './src/server/MQEngine.ts';
 export type { MQMessage } from './src/server/MQEngine.ts';
 export type { StreamEvent, CompactOptions, CompactResult, StreamSnapshot } from './src/server/StreamEngine.ts';
+export { VFSEngine, VFSEngineOptions, DiskBackend, LocalBackend } from './src/server/VFSEngine.ts';
+export type { VFSBackend } from './src/server/VFSEngine.ts';
 export { FileAdapter, FileAdapterOptions } from './src/server/FileAdapter.ts';
 export { ReplicationEngine, ReplicationOptions, ReplicationSource } from './src/server/ReplicationEngine.ts';
 export type { ReplEvent, WriteEvent } from './src/server/ReplicationEngine.ts';
+export { KeyAuthEngine, KeyAuthEngineOptions } from './src/server/KeyAuthEngine.ts';
+export type { KeyAuthAccount, KeyAuthDevice, KeyAuthRole, KeyAuthSession, KeyAuthContext, KeyAuthTokenPayload } from './src/shared/keyAuth.ts';
+export { fingerprint, generateEd25519KeyPair, signData, verifySignature, encryptPrivateKey, decryptPrivateKey } from './src/shared/keyAuth.ts';
 export { compileRule } from './src/server/ExpressionRules.ts';
 export { increment, serverTimestamp, arrayUnion, arrayRemove, ref } from './src/shared/transforms.ts';
 export * from './src/shared/protocol.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bod.ee/db",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "module": "index.ts",
   "type": "module",
   "exports": {
@@ -16,7 +16,10 @@
     "yaml": "^2.8.2"
   },
   "scripts": {
-    "admin": "bun --watch run admin/server.ts",
+    "build": "echo 'no build step'",
+    "gen:models": "echo 'no gen:models step'",
+    "admin": "bun run admin/admin.ts",
+    "demo": "bun --watch run cli.ts admin/demo.config.ts",
     "admin:remote": "bun run admin/proxy.ts",
     "serve": "bun run cli.ts",
     "start": "bun run cli.ts config.ts",
@@ -34,5 +37,8 @@
   },
   "peerDependencies": {
     "typescript": "^5"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^3.0.0"
   }
 }

package/src/client/BodClient.ts

@@ -4,11 +4,26 @@ import { pathKey } from '../shared/pathUtils.ts';
 export class BodClientOptions {
   url: string = 'ws://localhost:4400';
   auth?: () => string | Promise<string>;
+  /** Ed25519 key pair for KeyAuth challenge-response. signFn signs (nonce: string) => base64 signature. */
+  keyAuth?: { publicKey: string; signFn: (nonce: string) => string | Promise<string> };
+  /**
+   * Auto device auth: generate keypair, register on server, authenticate — all transparent.
+   * Requires `@noble/ed25519` (browser) or Node crypto. Set to `true` or pass options.
+   * Keypair stored in localStorage (browser) or in-memory (Node).
+   */
+  autoAuth?: boolean | { displayName?: string; storage?: DeviceKeyStorage };
   reconnect: boolean = true;
   reconnectInterval: number = 1000;
   maxReconnectInterval: number = 30000;
 }
 
+/** Interface for persisting device keys. Default: localStorage (browser) or in-memory (Node). */
+export interface DeviceKeyStorage {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+}
+
 type PendingRequest = {
   resolve: (data: unknown) => void;
   reject: (err: Error) => void;
@@ -26,15 +41,28 @@ export class BodClient {
   private activeStreamSubs = new Set<string>(); // tracks 'path:groupId' keys
   private vfsDownloadCbs = new Map<string, Set<(chunk: { data: string; seq: number; done: boolean }) => void>>();
   private closed = false;
+  private _browserAuth: typeof import('../shared/keyAuth.browser.ts') | null = null;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private reconnectDelay: number;
   private connectPromise: Promise<void> | null = null;
+  private _authToken: string | null = null;
+  private _deviceFingerprint: string | null = null;
+
+  /** Auth convenience methods */
+  readonly auth: AuthFacade;
 
   constructor(options?: Partial<BodClientOptions>) {
     this.options = { ...new BodClientOptions(), ...options };
     this.reconnectDelay = this.options.reconnectInterval;
+    this.auth = new AuthFacade(this);
   }
 
+  /** Device fingerprint (available after autoAuth or registerDevice) */
+  get deviceFingerprint(): string | null { return this._deviceFingerprint; }
+
+  /** Current auth token (available after autoAuth or manual authenticate) */
+  get authToken(): string | null { return this._authToken; }
+
   async connect(): Promise<void> {
     if (this.ws?.readyState === WebSocket.OPEN) return;
     if (this.connectPromise) return this.connectPromise;
@@ -48,8 +76,42 @@ export class BodClient {
         this.reconnectDelay = this.options.reconnectInterval;
 
         try {
-          // Auth if configured
-          if (this.options.auth) {
+          // AutoAuth: bootstrap device identity if configured
+          if (this.options.autoAuth && !this.options.keyAuth) {
+            const kp = await this._ensureDeviceKeys();
+            this.options.keyAuth = {
+              publicKey: kp.publicKey,
+              signFn: kp.signFn,
+            };
+            // Register device on server (idempotent)
+            await this.send('auth-register-device', {
+              publicKey: kp.publicKey,
+              displayName: typeof this.options.autoAuth === 'object' ? this.options.autoAuth.displayName : undefined,
+            });
+          }
+          // KeyAuth challenge-response
+          if (this.options.keyAuth) {
+            // Try cached token first
+            if (this._authToken) {
+              try {
+                await this.send('auth', { token: this._authToken });
+              } catch {
+                this._authToken = null;
+              }
+            }
+            if (!this._authToken) {
+              const challenge = await this.send('auth-challenge', {}) as { nonce: string; serverId: string };
+              const signature = await this.options.keyAuth.signFn(challenge.nonce);
+              const result = await this.send('auth-verify', {
+                publicKey: this.options.keyAuth.publicKey,
+                signature,
+                nonce: challenge.nonce,
+              }) as { token: string; expiresAt: number };
+              this._authToken = result.token;
+            }
+          }
+          // Auth if configured (legacy token-based)
+          else if (this.options.auth) {
             const token = await this.options.auth();
             await this.send('auth', { token });
           }
@@ -414,6 +476,162 @@ export class BodClient {
       if (this.vfsDownloadCbs.get(transferId)?.size === 0) this.vfsDownloadCbs.delete(transferId);
     };
   }
+
+  /** @internal — resolve device keys from storage or generate new ones */
+  async _ensureDeviceKeys(): Promise<{ publicKey: string; signFn: (nonce: string) => Promise<string> }> {
+    this._browserAuth ??= await import('../shared/keyAuth.browser.ts');
+    const browserAuth = this._browserAuth;
+    const storage = this._getStorage();
+    const existing = storage.get('boddb-device-pubkey');
+    if (existing) {
+      const privKey = storage.get('boddb-device-privkey')!;
+      this._deviceFingerprint = storage.get('boddb-device-fp') ?? null;
+      return {
+        publicKey: existing,
+        signFn: (nonce: string) => browserAuth.sign(nonce, privKey),
+      };
+    }
+    // Generate new keypair
+    const kp = await browserAuth.generateKeyPair();
+    storage.set('boddb-device-pubkey', kp.publicKeyBase64);
+    storage.set('boddb-device-privkey', kp.privateKeyBase64);
+    storage.set('boddb-device-fp', kp.fingerprint);
+    this._deviceFingerprint = kp.fingerprint;
+    return {
+      publicKey: kp.publicKeyBase64,
+      signFn: (nonce: string) => browserAuth.sign(nonce, kp.privateKeyBase64),
+    };
+  }
+
+  private _getStorage(): DeviceKeyStorage {
+    if (typeof this.options.autoAuth === 'object' && this.options.autoAuth.storage) {
+      return this.options.autoAuth.storage;
+    }
+    // Default: localStorage (browser) or in-memory (Node)
+    if (typeof localStorage !== 'undefined') {
+      return {
+        get: (k) => localStorage.getItem(k),
+        set: (k, v) => localStorage.setItem(k, v),
+        remove: (k) => localStorage.removeItem(k),
+      };
+    }
+    // In-memory fallback
+    if (!this._memStorage) this._memStorage = new Map();
+    return {
+      get: (k) => this._memStorage!.get(k) ?? null,
+      set: (k, v) => this._memStorage!.set(k, v),
+      remove: (k) => this._memStorage!.delete(k),
+    };
+  }
+  private _memStorage: Map<string, string> | null = null;
+}
+
+export class AuthFacade {
+  constructor(private client: BodClient) {}
+
+  /** Register a device-generated public key as an account (idempotent) */
+  async registerDevice(publicKey: string, displayName?: string): Promise<{ fingerprint: string }> {
+    return this.client._send('auth-register-device', { publicKey, displayName }) as Promise<{ fingerprint: string }>;
+  }
+
+  /** Challenge-response auth flow. Returns token + expiresAt. */
+  async authenticate(publicKey: string, signFn: (nonce: string) => string | Promise<string>): Promise<{ token: string; expiresAt: number }> {
+    const challenge = await this.client._send('auth-challenge', {}) as { nonce: string; serverId: string };
+    const signature = await signFn(challenge.nonce);
+    return this.client._send('auth-verify', { publicKey, signature, nonce: challenge.nonce }) as Promise<{ token: string; expiresAt: number }>;
+  }
+
+  /** Link a new device to an existing account */
+  async linkDevice(accountFingerprint: string, password: string, devicePublicKey: string, deviceName?: string): Promise<{ fingerprint: string }> {
+    return this.client._send('auth-link-device', { accountFingerprint, password, devicePublicKey, deviceName }) as Promise<{ fingerprint: string }>;
+  }
+
+  /** Revoke a session */
+  async revokeSession(sid: string): Promise<void> {
+    await this.client._send('auth-revoke-session', { sid });
+  }
+
+  /** Revoke a device */
+  async revokeDevice(accountFingerprint: string, deviceFingerprint: string): Promise<void> {
+    await this.client._send('auth-revoke-device', { accountFingerprint, deviceFingerprint });
+  }
+
+  /** Change account password */
+  async changePassword(fingerprint: string, oldPassword: string, newPassword: string): Promise<void> {
+    await this.client._send('auth-change-password', { fingerprint, oldPassword, newPassword });
+  }
+
+  /** Create a password-based account. First account auto-becomes root.
+   *  Pass devicePublicKey to auto-link the calling device. */
+  async createAccount(password: string, roles?: string[], displayName?: string, devicePublicKey?: string): Promise<{ publicKey: string; fingerprint: string; isRoot: boolean; deviceFingerprint?: string }> {
+    return this.client._send('auth-create-account', { password, roles, displayName, devicePublicKey }) as Promise<{ publicKey: string; fingerprint: string; isRoot: boolean; deviceFingerprint?: string }>;
+  }
+
+  /** Create a role (requires root) */
+  async createRole(role: { id: string; name: string; permissions: Array<{ path: string; read?: boolean; write?: boolean }> }): Promise<void> {
+    await this.client._send('auth-create-role', { role });
+  }
+
+  /** Delete a role (requires root) */
+  async deleteRole(roleId: string): Promise<void> {
+    await this.client._send('auth-delete-role', { roleId });
+  }
+
+  /** Update account roles (requires root) */
+  async updateRoles(accountFingerprint: string, roles: string[]): Promise<void> {
+    await this.client._send('auth-update-roles', { accountFingerprint, roles });
+  }
+
+  /** List all accounts */
+  async listAccounts(): Promise<unknown[]> {
+    return this.client._send('auth-list-accounts', {}) as Promise<unknown[]>;
+  }
+
+  /** List all roles */
+  async listRoles(): Promise<unknown[]> {
+    return this.client._send('auth-list-roles', {}) as Promise<unknown[]>;
+  }
+
+  /** List devices linked to an account */
+  async listDevices(accountFingerprint: string): Promise<unknown[]> {
+    return this.client._send('auth-list-devices', { accountFingerprint }) as Promise<unknown[]>;
+  }
+
+  /** List sessions, optionally filtered by account */
+  async listSessions(accountFingerprint?: string): Promise<unknown[]> {
+    return this.client._send('auth-list-sessions', { accountFingerprint }) as Promise<unknown[]>;
+  }
+
+  /** Request QR cross-device approval (new device calls this) */
+  async requestApproval(publicKey: string): Promise<{ requestId: string }> {
+    return this.client._send('auth-request-approval', { publicKey }) as Promise<{ requestId: string }>;
+  }
+
+  /** Approve a pending device request (authenticated device calls this) */
+  async approveDevice(requestId: string): Promise<{ fingerprint: string; token: string; expiresAt: number }> {
+    return this.client._send('auth-approve-device', { requestId }) as Promise<{ fingerprint: string; token: string; expiresAt: number }>;
+  }
+
+  /** List account fingerprints + displayNames (no auth required, no secrets) */
+  async listAccountFingerprints(): Promise<{ fingerprint: string; displayName?: string }[]> {
+    return this.client._send('auth-list-account-fingerprints', {}) as Promise<{ fingerprint: string; displayName?: string }[]>;
+  }
+
+  /** Check if any accounts exist (no auth required) */
+  async hasAccounts(): Promise<boolean> {
+    const result = await this.client._send('auth-has-accounts', {}) as { hasAccounts: boolean };
+    return result.hasAccounts;
+  }
+
+  /** Get public account info (no secrets). Defaults to own account. */
+  async getAccountInfo(accountFingerprint?: string): Promise<{ fingerprint: string; displayName?: string; roles: string[]; isRoot: boolean; createdAt: number }> {
+    return this.client._send('auth-account-info', { accountFingerprint }) as Promise<{ fingerprint: string; displayName?: string; roles: string[]; isRoot: boolean; createdAt: number }>;
+  }
+
+  /** Poll approval status */
+  async pollApproval(requestId: string): Promise<{ status: string; token?: string; expiresAt?: number }> {
+    return this.client._send('auth-poll-approval', { requestId }) as Promise<{ status: string; token?: string; expiresAt?: number }>;
+  }
 }
 
 export class ValueSnapshot {

package/src/client/{CachedClient.ts → BodClientCached.ts}

@@ -1,8 +1,9 @@
-import { BodClient, ValueSnapshot } from './BodClient.ts';
+import { BodClient, ValueSnapshot, VFSClient } from './BodClient.ts';
 import type { ChildEvent } from './BodClient.ts';
+import type { FileStat } from '../shared/protocol.ts';
 import { ancestors } from '../shared/pathUtils.ts';
 
-export class CachedClientOptions {
+export class BodClientCachedOptions {
   maxAge: number = 7 * 24 * 60 * 60 * 1000; // 7 days in ms
   maxMemoryEntries: number = 500;
   dbName: string = 'boddb-cache';
@@ -16,15 +17,17 @@ interface CacheEntry {
   cachedAt: number;
 }
 
-export class CachedClient {
-  readonly options: CachedClientOptions;
+export class BodClientCached {
+  readonly options: BodClientCachedOptions;
   readonly client: BodClient;
   private memory = new Map<string, CacheEntry>();
   private subscribedPaths = new Set<string>();
   private idb: IDBDatabase | null = null;
+  private _vfs: CachedVFSClient | null = null;
+  private _vfsUnsub: (() => void) | null = null;
 
-  constructor(client: BodClient, options?: Partial<CachedClientOptions>) {
-    this.options = { ...new CachedClientOptions(), ...options };
+  constructor(client: BodClient, options?: Partial<BodClientCachedOptions>) {
+    this.options = { ...new BodClientCachedOptions(), ...options };
     this.client = client;
   }
 
@@ -177,7 +180,21 @@ export class CachedClient {
     await Promise.all(promises);
   }
 
+  vfs(): CachedVFSClient {
+    if (!this._vfs) {
+      this._vfs = new CachedVFSClient(this.client.vfs(), this.options.maxAge);
+      this._vfsUnsub = this.client.onChild('_vfs', () => {
+        // _vfs events are coarse (top-level key only), clear all VFS caches
+        this._vfs?.clear();
+      });
+    }
+    return this._vfs;
+  }
+
   close(): void {
+    if (this._vfsUnsub) { this._vfsUnsub(); this._vfsUnsub = null; }
+    this._vfs?.clear();
+    this._vfs = null;
     this.memory.clear();
     this.subscribedPaths.clear();
     this.idb?.close();
@@ -226,3 +243,95 @@ export class CachedClient {
     } catch {}
   }
 }
+
+export class CachedVFSClient {
+  private listCache = new Map<string, { data: FileStat[]; cachedAt: number }>();
+  private statCache = new Map<string, { data: FileStat | null; cachedAt: number }>();
+  private _stats = { hits: 0, misses: 0, invalidations: 0, pushClears: 0 };
+
+  constructor(
+    private raw: VFSClient,
+    private maxAge: number,
+  ) {}
+
+  async stat(path: string): Promise<FileStat | null> {
+    const cached = this.statCache.get(path);
+    if (cached && Date.now() - cached.cachedAt < this.maxAge) {
+      this._stats.hits++;
+      this.raw.stat(path).then(r => this.statCache.set(path, { data: r, cachedAt: Date.now() })).catch(() => {});
+      return cached.data;
+    }
+    this._stats.misses++;
+    const result = await this.raw.stat(path);
+    this.statCache.set(path, { data: result, cachedAt: Date.now() });
+    return result;
+  }
+
+  async list(path: string): Promise<FileStat[]> {
+    const cached = this.listCache.get(path);
+    if (cached && Date.now() - cached.cachedAt < this.maxAge) {
+      this._stats.hits++;
+      this.raw.list(path).then(r => this.listCache.set(path, { data: r, cachedAt: Date.now() })).catch(() => {});
+      return cached.data;
+    }
+    this._stats.misses++;
+    const result = await this.raw.list(path);
+    this.listCache.set(path, { data: result, cachedAt: Date.now() });
+    return result;
+  }
+
+  async upload(path: string, data: Uint8Array, mime?: string): Promise<FileStat> {
+    const r = await this.raw.upload(path, data, mime);
+    this.invalidatePath(path);
+    return r;
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.raw.delete(path);
+    this.invalidatePath(path);
+  }
+
+  async mkdir(path: string): Promise<FileStat> {
+    const r = await this.raw.mkdir(path);
+    this.invalidatePath(path);
+    // Also invalidate the dir's own list (was empty/nonexistent before)
+    this.listCache.delete(path);
+    return r;
+  }
+
+  async move(src: string, dst: string): Promise<FileStat> {
+    const r = await this.raw.move(src, dst);
+    this.invalidatePath(src);
+    this.invalidatePath(dst);
+    return r;
+  }
+
+  async download(path: string): Promise<Uint8Array> {
+    return this.raw.download(path);
+  }
+
+  invalidatePath(filePath: string) {
+    this._stats.invalidations++;
+    this.statCache.delete(filePath);
+    const parent = filePath.includes('/') ? filePath.slice(0, filePath.lastIndexOf('/')) : '';
+    this.listCache.delete(parent);
+  }
+
+  clear() {
+    this._stats.pushClears++;
+    this.listCache.clear();
+    this.statCache.clear();
+  }
+
+  /** Cache stats for diagnostics. Use in browser: `__bodCache.vfs().stats` */
+  get stats() {
+    const total = this._stats.hits + this._stats.misses;
+    return {
+      ...this._stats,
+      total,
+      hitRate: total ? Math.round(this._stats.hits / total * 100) + '%' : 'n/a',
+      listCacheSize: this.listCache.size,
+      statCacheSize: this.statCache.size,
+    };
+  }
+}

package/src/server/BodDB.ts

@@ -9,6 +9,7 @@ import { StreamEngine, type CompactOptions } from './StreamEngine.ts';
 import { MQEngine, type MQEngineOptions } from './MQEngine.ts';
 import { ReplicationEngine, type ReplicationOptions, type WriteEvent } from './ReplicationEngine.ts';
 import { VFSEngine, type VFSEngineOptions } from './VFSEngine.ts';
+import { KeyAuthEngine, type KeyAuthEngineOptions } from './KeyAuthEngine.ts';
 import { validatePath } from '../shared/pathUtils.ts';
 
 export interface TransactionProxy {
@@ -38,6 +39,10 @@ export class BodDBOptions {
   replication?: Partial<ReplicationOptions>;
   /** VFS config */
   vfs?: Partial<VFSEngineOptions>;
+  /** KeyAuth config */
+  keyAuth?: Partial<KeyAuthEngineOptions> & { rootPublicKey?: string };
+  /** When true, deny operations that don't match any rule (default: open) */
+  defaultDeny?: boolean;
   port?: number;
   auth?: TransportOptions['auth'];
   transport?: Partial<TransportOptions>;
@@ -52,6 +57,7 @@ export class BodDB {
   readonly fts: FTSEngine | null = null;
   readonly vectors: VectorEngine | null = null;
   readonly vfs: VFSEngine | null = null;
+  readonly keyAuth: KeyAuthEngine | null = null;
   readonly options: BodDBOptions;
   replication: ReplicationEngine | null = null;
   private _replaying = false;
@@ -81,7 +87,7 @@ export class BodDB {
     const resolvedRules = typeof rulesConfig === 'string'
       ? BodDB.loadRulesFileSync(rulesConfig)
       : (rulesConfig ?? {});
-    this.rules = new RulesEngine({ rules: resolvedRules });
+    this.rules = new RulesEngine({ rules: resolvedRules, defaultDeny: this.options.defaultDeny });
 
     // Auto-create indexes from config
     if (this.options.indexes) {
@@ -107,6 +113,14 @@ export class BodDB {
       (this as { vfs: VFSEngine }).vfs = new VFSEngine(this, this.options.vfs);
     }
 
+    // Initialize KeyAuth if configured
+    if (this.options.keyAuth) {
+      (this as { keyAuth: KeyAuthEngine }).keyAuth = new KeyAuthEngine(this, this.options.keyAuth);
+      if (this.options.keyAuth.rootPublicKey) {
+        this.keyAuth!.initRoot(this.options.keyAuth.rootPublicKey);
+      }
+    }
+
     // Start TTL sweep
     if (this.options.sweepInterval > 0) {
       this.sweepTimer = setInterval(() => this.sweep(), this.options.sweepInterval);
@@ -347,7 +361,7 @@ export class BodDB {
   }
 
   /** Start publishing process/db stats to `_admin/stats` (only when subscribers exist). */
-  private _startStatsPublisher(): void {
+  startStatsPublisher(): void {
     if (this._statsInterval) return;
     const { statSync } = require('fs');
     const { cpus, totalmem } = require('os');
@@ -386,6 +400,8 @@ export class BodDB {
         db: { nodeCount, sizeMb: dbSizeMb },
         system: { cpuCores: cur.length, totalMemMb: +(totalmem() / 1024 / 1024).toFixed(0), cpuPercent: sysCpu },
         subs: this.subs.subscriberCount(),
+        clients: this._transport?.clientCount ?? 0,
+        repl: this.replication?.stats() ?? null,
         ts: Date.now(),
       });
     }, 1000);
@@ -394,9 +410,9 @@ export class BodDB {
   /** Start standalone WebSocket + REST server on its own port */
   serve(options?: Partial<TransportOptions>) {
     const port = options?.port ?? this.options.port;
-    const auth = options?.auth ?? this.options.auth;
-    this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, port, auth });
-    this._startStatsPublisher();
+    const auth = options?.auth ?? this.options.auth ?? (this.keyAuth ? this.keyAuth.authCallback() : undefined);
+    this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, port, auth, keyAuth: this.keyAuth ?? undefined });
+    this.startStatsPublisher();
     return this._transport.start();
   }
 
@@ -419,9 +435,9 @@ export class BodDB {
    * ```
    */
   getHandlers(options?: Partial<TransportOptions>) {
-    const auth = options?.auth ?? this.options.auth;
-    this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, auth });
-    this._startStatsPublisher();
+    const auth = options?.auth ?? this.options.auth ?? (this.keyAuth ? this.keyAuth.authCallback() : undefined);
+    this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, auth, keyAuth: this.keyAuth ?? undefined });
+    this.startStatsPublisher();
     return {
       handleFetch: this._transport.handleFetch.bind(this._transport),
       websocketConfig: this._transport.websocketConfig,