@bod.ee/db 0.10.2 → 0.12.1

package/src/client/BodClient.ts

@@ -15,6 +15,8 @@ export class BodClientOptions {
   reconnect: boolean = true;
   reconnectInterval: number = 1000;
   maxReconnectInterval: number = 30000;
+  /** Timeout for individual requests in ms (0 = no timeout) */
+  requestTimeout: number = 30000;
 }
 
 /** Interface for persisting device keys. Default: localStorage (browser) or in-memory (Node). */
@@ -115,11 +117,18 @@ export class BodClient {
             const token = await this.options.auth();
             await this.send('auth', { token });
           }
-          // Re-subscribe all active subscriptions
-          for (const key of this.activeSubs) {
-            const [event, ...pathParts] = key.split(':');
-            const path = pathParts.join(':');
-            await this.send('sub', { path, event });
+          // Re-subscribe all active subscriptions (batch)
+          if (this.activeSubs.size > 0) {
+            const subs = [...this.activeSubs].map(key => {
+              const [event, ...pathParts] = key.split(':');
+              return { path: pathParts.join(':'), event };
+            });
+            try {
+              await this.send('batch-sub', { subscriptions: subs });
+            } catch {
+              // Fallback to individual subs if server doesn't support batch-sub
+              for (const sub of subs) await this.send('sub', sub);
+            }
           }
           // Re-subscribe stream subs
           for (const key of this.activeStreamSubs) {
@@ -239,7 +248,18 @@ export class BodClient {
         return reject(new Error('Not connected'));
       }
       const id = this.nextId();
-      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      let timer: ReturnType<typeof setTimeout> | null = null;
+      const cleanup = () => { if (timer) { clearTimeout(timer); timer = null; } };
+      this.pending.set(id, {
+        resolve: (v: unknown) => { cleanup(); resolve(v as Record<string, unknown>); },
+        reject: (e: Error) => { cleanup(); reject(e); },
+      });
+      if (this.options.requestTimeout > 0) {
+        timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error(`Request timeout after ${this.options.requestTimeout}ms`));
+        }, this.options.requestTimeout);
+      }
       this.ws.send(JSON.stringify({ id, op, ...params }));
     });
   }
@@ -809,6 +829,10 @@ export class VFSClient {
     return await this.client._send('vfs-list', { path }) as FileStat[];
   }
 
+  async tree(path: string, opts?: { hiddenPaths?: string[]; hideDotfiles?: boolean }): Promise<any[]> {
+    return await this.client._send('vfs-tree', { path, ...opts }) as any[];
+  }
+
   async delete(path: string): Promise<void> {
     await this.client._send('vfs-delete', { path });
   }

package/src/client/BodClientCached.ts

@@ -182,7 +182,7 @@ export class BodClientCached {
 
   vfs(): CachedVFSClient {
     if (!this._vfs) {
-      this._vfs = new CachedVFSClient(this.client.vfs(), this.options.maxAge);
+      this._vfs = new CachedVFSClient(this.client.vfs(), this.options.maxAge, this.idb);
       this._vfsUnsub = this.client.onChild('_vfs', () => {
         // _vfs events are coarse (top-level key only), clear all VFS caches
         this._vfs?.clear();
@@ -252,18 +252,34 @@ export class CachedVFSClient {
   constructor(
     private raw: VFSClient,
     private maxAge: number,
+    private idb: IDBDatabase | null = null,
   ) {}
 
   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(() => {});
+      this.raw.stat(path).then(r => {
+        this.statCache.set(path, { data: r, cachedAt: Date.now() });
+        this.idbSetVfs(`vfs:stat:${path}`, { data: r, cachedAt: Date.now() });
+      }).catch(() => {});
       return cached.data;
     }
+    // Check IDB before network
+    const idbEntry = await this.idbGetVfs(`vfs:stat:${path}`);
+    if (idbEntry && Date.now() - idbEntry.cachedAt < this.maxAge) {
+      this._stats.hits++;
+      this.statCache.set(path, idbEntry);
+      this.raw.stat(path).then(r => {
+        this.statCache.set(path, { data: r, cachedAt: Date.now() });
+        this.idbSetVfs(`vfs:stat:${path}`, { data: r, cachedAt: Date.now() });
+      }).catch(() => {});
+      return idbEntry.data as FileStat | null;
+    }
     this._stats.misses++;
     const result = await this.raw.stat(path);
     this.statCache.set(path, { data: result, cachedAt: Date.now() });
+    this.idbSetVfs(`vfs:stat:${path}`, { data: result, cachedAt: Date.now() });
     return result;
   }
 
@@ -271,15 +287,34 @@ export class CachedVFSClient {
     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(() => {});
+      this.raw.list(path).then(r => {
+        this.listCache.set(path, { data: r, cachedAt: Date.now() });
+        this.idbSetVfs(`vfs:list:${path}`, { data: r, cachedAt: Date.now() });
+      }).catch(() => {});
       return cached.data;
     }
+    // Check IDB before network
+    const idbEntry = await this.idbGetVfs(`vfs:list:${path}`);
+    if (idbEntry && Date.now() - idbEntry.cachedAt < this.maxAge) {
+      this._stats.hits++;
+      this.listCache.set(path, idbEntry as { data: FileStat[]; cachedAt: number });
+      this.raw.list(path).then(r => {
+        this.listCache.set(path, { data: r, cachedAt: Date.now() });
+        this.idbSetVfs(`vfs:list:${path}`, { data: r, cachedAt: Date.now() });
+      }).catch(() => {});
+      return idbEntry.data as FileStat[];
+    }
     this._stats.misses++;
     const result = await this.raw.list(path);
     this.listCache.set(path, { data: result, cachedAt: Date.now() });
+    this.idbSetVfs(`vfs:list:${path}`, { data: result, cachedAt: Date.now() });
     return result;
   }
 
+  async tree(path: string, opts?: { hiddenPaths?: string[]; hideDotfiles?: boolean }): Promise<any[]> {
+    return this.raw.tree(path, opts);
+  }
+
   async upload(path: string, data: Uint8Array, mime?: string): Promise<FileStat> {
     const r = await this.raw.upload(path, data, mime);
     this.invalidatePath(path);
@@ -296,6 +331,7 @@ export class CachedVFSClient {
     this.invalidatePath(path);
     // Also invalidate the dir's own list (was empty/nonexistent before)
     this.listCache.delete(path);
+    this.idbDeleteVfs(`vfs:list:${path}`);
     return r;
   }
 
@@ -313,14 +349,17 @@ export class CachedVFSClient {
   invalidatePath(filePath: string) {
     this._stats.invalidations++;
     this.statCache.delete(filePath);
+    this.idbDeleteVfs(`vfs:stat:${filePath}`);
     const parent = filePath.includes('/') ? filePath.slice(0, filePath.lastIndexOf('/')) : '';
     this.listCache.delete(parent);
+    this.idbDeleteVfs(`vfs:list:${parent}`);
   }
 
   clear() {
     this._stats.pushClears++;
     this.listCache.clear();
     this.statCache.clear();
+    this.idbClearVfs();
   }
 
   /** Cache stats for diagnostics. Use in browser: `__bodCache.vfs().stats` */
@@ -334,4 +373,53 @@ export class CachedVFSClient {
       statCacheSize: this.statCache.size,
     };
   }
+
+  // --- IDB helpers for VFS cache ---
+
+  private idbGetVfs(key: string): Promise<{ data: unknown; cachedAt: number } | null> {
+    if (!this.idb) return Promise.resolve(null);
+    try {
+      const tx = this.idb.transaction('entries', 'readonly');
+      const req = tx.objectStore('entries').get(key);
+      return new Promise(resolve => {
+        req.onsuccess = () => {
+          const entry = req.result;
+          resolve(entry ? { data: entry.data, cachedAt: entry.cachedAt } : null);
+        };
+        req.onerror = () => resolve(null);
+      });
+    } catch { return Promise.resolve(null); }
+  }
+
+  private idbSetVfs(key: string, value: { data: unknown; cachedAt: number }): void {
+    if (!this.idb) return;
+    try {
+      const tx = this.idb.transaction('entries', 'readwrite');
+      tx.objectStore('entries').put({ path: key, data: value.data, cachedAt: value.cachedAt, updatedAt: Date.now() });
+    } catch {}
+  }
+
+  private idbDeleteVfs(key: string): void {
+    if (!this.idb) return;
+    try {
+      const tx = this.idb.transaction('entries', 'readwrite');
+      tx.objectStore('entries').delete(key);
+    } catch {}
+  }
+
+  private idbClearVfs(): void {
+    if (!this.idb) return;
+    try {
+      // Delete all vfs: prefixed entries
+      const tx = this.idb.transaction('entries', 'readwrite');
+      const store = tx.objectStore('entries');
+      const req = store.openCursor();
+      req.onsuccess = () => {
+        const cursor = req.result;
+        if (!cursor) return;
+        if (typeof cursor.key === 'string' && cursor.key.startsWith('vfs:')) cursor.delete();
+        cursor.continue();
+      };
+    } catch {}
+  }
 }

package/src/server/BodDB.ts

@@ -11,6 +11,7 @@ import { ReplicationEngine, type ReplicationOptions, type WriteEvent } from './R
 import { VFSEngine, type VFSEngineOptions } from './VFSEngine.ts';
 import { KeyAuthEngine, type KeyAuthEngineOptions } from './KeyAuthEngine.ts';
 import { validatePath } from '../shared/pathUtils.ts';
+import { Logger, type LogConfig } from '../shared/logger.ts';
 
 export interface TransactionProxy {
   get(path: string): unknown;
@@ -46,6 +47,8 @@ export class BodDBOptions {
   port?: number;
   auth?: TransportOptions['auth'];
   transport?: Partial<TransportOptions>;
+  /** Logging config — disabled by default */
+  log?: LogConfig;
 }
 
 export class BodDB {
@@ -59,6 +62,7 @@ export class BodDB {
   readonly vfs: VFSEngine | null = null;
   readonly keyAuth: KeyAuthEngine | null = null;
   readonly options: BodDBOptions;
+  readonly log: Logger;
   replication: ReplicationEngine | null = null;
   private _replaying = false;
   private _onWriteHooks: Array<(ev: WriteEvent) => void> = [];
@@ -66,11 +70,16 @@ export class BodDB {
   get transport(): Transport | null { return this._transport; }
   private sweepTimer: ReturnType<typeof setInterval> | null = null;
   private _statsInterval: ReturnType<typeof setInterval> | null = null;
+  private _statsStmtCount: any = null;
   private _lastCpuUsage = process.cpuUsage();
   private _lastCpuTime = performance.now();
+  private _lastStats: Record<string, unknown> | null = null;
 
   constructor(options?: Partial<BodDBOptions>) {
     this.options = { ...new BodDBOptions(), ...options };
+    this.log = new Logger(this.options.log);
+    const _log = this.log.forComponent('db');
+    _log.info(`Initializing BodDB (path: ${this.options.path})`);
     this.storage = new StorageEngine({ path: this.options.path });
     this.subs = new SubscriptionEngine();
     this.stream = new StreamEngine(this.storage, this.subs, { compact: this.options.compact });
@@ -88,6 +97,7 @@ export class BodDB {
       ? BodDB.loadRulesFileSync(rulesConfig)
       : (rulesConfig ?? {});
     this.rules = new RulesEngine({ rules: resolvedRules, defaultDeny: this.options.defaultDeny });
+    _log.debug(`Rules loaded (${Object.keys(resolvedRules).length} paths, defaultDeny: ${!!this.options.defaultDeny})`);
 
     // Auto-create indexes from config
     if (this.options.indexes) {
@@ -96,21 +106,25 @@ export class BodDB {
           this.storage.createIndex(basePath, field);
         }
       }
+      _log.debug(`Indexes created: ${JSON.stringify(this.options.indexes)}`);
     }
 
     // Initialize FTS if configured
     if (this.options.fts) {
       this.fts = new FTSEngine(this.storage.db, this.options.fts);
+      _log.info('FTS5 engine enabled');
     }
 
     // Initialize vectors if configured
     if (this.options.vectors) {
       this.vectors = new VectorEngine(this.storage.db, this.options.vectors);
+      _log.info(`Vector engine enabled (dimensions: ${this.options.vectors.dimensions})`);
     }
 
     // Initialize VFS if configured
     if (this.options.vfs) {
       (this as { vfs: VFSEngine }).vfs = new VFSEngine(this, this.options.vfs);
+      _log.info(`VFS enabled (root: ${this.options.vfs.storageRoot})`);
     }
 
     // Initialize KeyAuth if configured
@@ -119,11 +133,13 @@ export class BodDB {
       if (this.options.keyAuth.rootPublicKey) {
         this.keyAuth!.initRoot(this.options.keyAuth.rootPublicKey);
       }
+      _log.info('KeyAuth engine enabled');
     }
 
     // Start TTL sweep
     if (this.options.sweepInterval > 0) {
       this.sweepTimer = setInterval(() => this.sweep(), this.options.sweepInterval);
+      _log.debug(`TTL sweep interval: ${this.options.sweepInterval}ms`);
     }
 
     // Init replication
@@ -134,7 +150,10 @@ export class BodDB {
         const compactOpts = this.options.replication.compact ?? { keepKey: 'path', maxCount: 10000 };
         this.stream.options.compact = { ...this.stream.options.compact, _repl: compactOpts };
       }
+      _log.info(`Replication enabled (role: ${this.replication.isPrimary ? 'primary' : 'replica'})`);
     }
+
+    _log.info('BodDB ready');
   }
 
   /** Load rules from a JSON or TS file synchronously */
@@ -195,6 +214,7 @@ export class BodDB {
   }
 
   get(path: string): unknown {
+    if (path === '_admin/stats' && this._lastStats) return this._lastStats;
     return this.storage.get(path);
   }
 
@@ -204,7 +224,7 @@ export class BodDB {
 
   set(path: string, value: unknown, options?: { ttl?: number }): void {
     const p = validatePath(path);
-    const existedBefore = this.subs.hasChildSubscriptions ? this.snapshotExisting(p) : new Set<string>();
+    const existedBefore = this.subs.hasChildSubscriptions ? this.snapshotExisting(p) : undefined;
     const changed = this.storage.set(path, value);
     if (options?.ttl) {
       this.storage.setExpiry(path, options.ttl);
@@ -218,12 +238,15 @@ export class BodDB {
   /** Manually trigger TTL sweep + stream auto-compact, returns expired paths */
   sweep(): string[] {
     const expired = this.storage.sweep();
-    if (expired.length > 0 && this.subs.hasSubscriptions) {
-      this.subs.notify(expired, (p) => this.storage.get(p));
-    }
-    // Fire delete events for expired paths (replication)
-    for (const p of expired) {
-      this._fireWrite({ op: 'delete', path: p });
+    if (expired.length > 0) {
+      if (this.subs.hasSubscriptions) {
+        this.subs.notify(expired, (p) => this.storage.get(p));
+      }
+      // Fire delete events for expired paths (replication)
+      for (const p of expired) {
+        this._fireWrite({ op: 'delete', path: p });
+      }
+      this.log.forComponent('storage').debug(`Sweep: ${expired.length} expired paths removed`);
     }
     this.stream.autoCompact();
     this.mq.sweep();
@@ -250,7 +273,7 @@ export class BodDB {
 
   delete(path: string): void {
     const p = validatePath(path);
-    const existedBefore = this.subs.hasChildSubscriptions ? this.snapshotExisting(p) : new Set<string>();
+    const existedBefore = this.subs.hasChildSubscriptions ? this.snapshotExisting(p) : undefined;
     this.storage.delete(path);
     if (this.subs.hasSubscriptions) {
       this.subs.notify([p], (pp) => this.storage.get(pp), existedBefore);
@@ -261,7 +284,7 @@ export class BodDB {
   /** Push a value with auto-generated time-sortable key (stored as single JSON row, not flattened) */
   push(path: string, value: unknown, opts?: { idempotencyKey?: string }): string {
     const p = validatePath(path);
-    const existedBefore = this.subs.hasChildSubscriptions ? this.snapshotExisting(p) : new Set<string>();
+    const existedBefore = this.subs.hasChildSubscriptions ? this.snapshotExisting(p) : undefined;
     const { key, changedPaths, duplicate } = this.storage.push(path, value, opts);
     if (!duplicate && this.subs.hasSubscriptions) {
       this.subs.notify(changedPaths, (pp) => this.storage.get(pp), existedBefore);
@@ -350,13 +373,21 @@ export class BodDB {
       },
     };
 
+    this.replication?.beginBatch();
     const sqliteTx = this.storage.db.transaction(() => fn(proxy));
-    const result = sqliteTx();
+    let result: T;
+    try {
+      result = sqliteTx();
+    } catch (e) {
+      this.replication?.discardBatch();
+      throw e;
+    }
 
     if (this.subs.hasSubscriptions && allChanged.length > 0) {
       this.subs.notify(allChanged, (p) => this.storage.get(p), allExistedBefore);
     }
     for (const ev of txWriteEvents) this._fireWrite(ev);
+    this.replication?.flushBatch();
     return result;
   }
 
@@ -366,53 +397,95 @@ export class BodDB {
     const { statSync } = require('fs');
     const { cpus, totalmem } = require('os');
     let lastOsCpus = cpus();
+    // Clean up old flattened _admin/stats/* leaf rows (migrated to single JSON row)
+    this.storage.db.prepare("DELETE FROM nodes WHERE path LIKE '_admin/stats/%'").run();
+
+    // Reuse prepared statement across start/stop cycles
+    if (!this._statsStmtCount) {
+      this._statsStmtCount = this.storage.db.prepare('SELECT COUNT(*) as n FROM nodes WHERE mq_status IS NULL');
+    }
+    const stmtCount = this._statsStmtCount;
+    const statsPath = '_admin/stats';
+
+    // Reuse a single stats object to minimize allocations
+    const statsData: Record<string, unknown> = {
+      process: {}, db: {}, system: {},
+      subs: 0, clients: 0, repl: null, ts: 0,
+    };
+    const proc = statsData.process as Record<string, number>;
+    const dbStats = statsData.db as Record<string, number>;
+    const sys = statsData.system as Record<string, number>;
+
+    // Heavy calls (cpus, statSync, stmtCount) run every 5s; lightweight calls every 1s
+    let tick = 0;
+    const MB = 1 / (1024 * 1024);
+    sys.cpuCores = cpus().length;
+    sys.totalMemMb = Math.round(totalmem() * MB);
 
     this._statsInterval = setInterval(() => {
-      if (!this.subs.subscriberCount('_admin')) return;
+      if (!this._transport) return;
+      tick++;
 
       const now = performance.now();
       const cpu = process.cpuUsage();
       const elapsedUs = (now - this._lastCpuTime) * 1000;
-      const cpuPercent = +((cpu.user - this._lastCpuUsage.user + cpu.system - this._lastCpuUsage.system) / elapsedUs * 100).toFixed(1);
+      proc.cpuPercent = Math.round((cpu.user - this._lastCpuUsage.user + cpu.system - this._lastCpuUsage.system) / elapsedUs * 1000) / 10;
       this._lastCpuUsage = cpu;
       this._lastCpuTime = now;
 
       const mem = process.memoryUsage();
-      let nodeCount = 0;
-      try { nodeCount = (this.storage.db.query('SELECT COUNT(*) as n FROM nodes WHERE mq_status IS NULL').get() as any).n; } catch {}
-      let dbSizeMb = 0;
-      try { dbSizeMb = +(statSync(this.options.path).size / 1024 / 1024).toFixed(2); } catch {}
-
-      // System CPU
-      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);
+      proc.heapUsedMb = Math.round(mem.heapUsed * MB * 100) / 100;
+      proc.rssMb = Math.round(mem.rss * MB * 100) / 100;
+      proc.uptimeSec = Math.floor(process.uptime());
+
+      // Expensive calls: only every 5 ticks
+      if (tick % 5 === 0) {
+        try { dbStats.nodeCount = (stmtCount.get() as any).n; } catch {}
+        try { dbStats.sizeMb = Math.round(statSync(this.options.path).size * MB * 100) / 100; } catch {}
+        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;
+        sys.cpuPercent = totalDelta > 0 ? Math.round((1 - idleDelta / totalDelta) * 1000) / 10 : 0;
       }
-      lastOsCpus = cur;
-      const sysCpu = totalDelta > 0 ? +((1 - idleDelta / totalDelta) * 100).toFixed(1) : 0;
-
-      this.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: 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(),
-      });
+
+      statsData.subs = this.subs.subscriberCount();
+      statsData.clients = this._transport?.clientCount ?? 0;
+      statsData.repl = this.replication?.stats() ?? null;
+      statsData.ts = Date.now();
+
+      // Push directly to WS clients — bypass SubscriptionEngine entirely
+      this._lastStats = statsData;
+      if (this._transport) this._transport.broadcastStats(statsData, Date.now());
+
     }, 1000);
+    this.log.forComponent('stats').info('Stats publisher started');
+  }
+
+  /** Stop the stats publisher. */
+  stopStatsPublisher(): void {
+    if (!this._statsInterval) return;
+    clearInterval(this._statsInterval);
+    this._statsInterval = null;
+    this._lastStats = null;
+    this.subs.pushValue('_admin/stats', null);
+    this.log.forComponent('stats').info('Stats publisher stopped');
   }
 
+  get statsEnabled(): boolean { return this._statsInterval !== null; }
+
   /** 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.keyAuth ? this.keyAuth.authCallback() : undefined);
     this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, port, auth, keyAuth: this.keyAuth ?? undefined });
     this.startStatsPublisher();
+    this.log.forComponent('transport').info(`Server starting on port ${port}`);
     return this._transport.start();
   }
 
@@ -467,13 +540,11 @@ export class BodDB {
   }
 
   private snapshotExisting(path: string): Set<string> {
-    const existing = new Set<string>();
-    if (this.storage.exists(path)) existing.add(path);
+    const paths = [path];
     const parts = path.split('/');
     for (let i = 1; i < parts.length; i++) {
-      const childPath = parts.slice(0, i + 1).join('/');
-      if (this.storage.exists(childPath)) existing.add(childPath);
+      paths.push(parts.slice(0, i + 1).join('/'));
     }
-    return existing;
+    return this.storage.existsMany(paths);
   }
 }

package/src/server/KeyAuthEngine.ts

@@ -19,6 +19,12 @@ export class KeyAuthEngineOptions {
   clockSkew: number = 30;
   /** Allow unauthenticated device registration (default true) */
   allowOpenRegistration: boolean = true;
+  /** PBKDF2 iterations for password-based key derivation (default 100000) */
+  pbkdf2Iterations: number = 100_000;
+  /** Max failed auth attempts before lockout (0 = disabled) */
+  maxAuthFailures: number = 0;
+  /** Lockout duration in seconds after max failures */
+  authLockoutSeconds: number = 60;
 }
 
 /** Reserved prefix — _auth/ writes blocked for external clients */
@@ -80,7 +86,7 @@ export class KeyAuthEngine {
    *  If this is the first account ever created, it is auto-elevated to root. */
   createAccount(password: string, roles: string[] = [], displayName?: string, devicePublicKey?: string): { publicKey: string; fingerprint: string; isRoot: boolean; deviceFingerprint?: string } {
     const kp = generateEd25519KeyPair();
-    const enc = encryptPrivateKey(kp.privateKey, password);
+    const enc = encryptPrivateKey(kp.privateKey, password, this.options.pbkdf2Iterations);
     const fp = fingerprint(kp.publicKeyBase64);
 
     // First account becomes root automatically
@@ -145,6 +151,14 @@ export class KeyAuthEngine {
 
   /** Verify a signed nonce. Returns token + expiry or null. */
   verify(publicKeyBase64: string, signatureBase64: string, nonce: string): { token: string; expiresAt: number } | null {
+    const fp = fingerprint(publicKeyBase64);
+
+    // Rate limit check
+    if (this.options.maxAuthFailures > 0) {
+      const rlData = this.db.get(`_auth/rateLimit/${fp}`) as { count: number } | null;
+      if (rlData && rlData.count >= this.options.maxAuthFailures) return null;
+    }
+
     // Check nonce exists (one-time use)
     const nonceData = this.db.get(`_auth/nonces/${nonce}`);
     if (!nonceData) return null;
@@ -154,9 +168,10 @@ export class KeyAuthEngine {
     // Verify signature
     const pubKeyDer = Buffer.from(publicKeyBase64, 'base64');
     const sig = Buffer.from(signatureBase64, 'base64');
-    if (!verifySignature(Buffer.from(nonce), sig, new Uint8Array(pubKeyDer))) return null;
-
-    const fp = fingerprint(publicKeyBase64);
+    if (!verifySignature(Buffer.from(nonce), sig, new Uint8Array(pubKeyDer))) {
+      this._recordAuthFailure(fp);
+      return null;
+    }
 
     // Check if root
     const root = this.db.get('_auth/root') as { fingerprint: string } | null;
@@ -200,6 +215,8 @@ export class KeyAuthEngine {
       sid, fp, accountFp, roles, root: isRoot, exp: expiresAt,
     };
     const token = encodeToken(payload, this.serverPrivateKey);
+    // Clear rate limit on success
+    if (this.options.maxAuthFailures > 0) this.db.delete(`_auth/rateLimit/${fp}`);
     return { token, expiresAt };
   }
 
@@ -213,7 +230,7 @@ export class KeyAuthEngine {
     let accountPrivateKey: Uint8Array;
     try {
       accountPrivateKey = decryptPrivateKey(
-        account.encryptedPrivateKey, account.salt, account.iv, account.authTag, password,
+        account.encryptedPrivateKey, account.salt, account.iv, account.authTag, password, this.options.pbkdf2Iterations,
       );
     } catch {
       return null; // Wrong password
@@ -269,12 +286,12 @@ export class KeyAuthEngine {
 
     let privateKey: Uint8Array;
     try {
-      privateKey = decryptPrivateKey(account.encryptedPrivateKey, account.salt, account.iv, account.authTag, oldPassword);
+      privateKey = decryptPrivateKey(account.encryptedPrivateKey, account.salt, account.iv, account.authTag, oldPassword, this.options.pbkdf2Iterations);
     } catch {
       return false;
     }
 
-    const enc = encryptPrivateKey(privateKey, newPassword);
+    const enc = encryptPrivateKey(privateKey, newPassword, this.options.pbkdf2Iterations);
     privateKey.fill(0); // Wipe
 
     // Atomic: single update call writes all fields together
@@ -460,6 +477,14 @@ export class KeyAuthEngine {
     return { accountFp, roles: account.roles ?? [] };
   }
 
+  /** Record a failed auth attempt for rate limiting */
+  private _recordAuthFailure(fp: string): void {
+    if (this.options.maxAuthFailures <= 0) return;
+    const rlData = this.db.get(`_auth/rateLimit/${fp}`) as { count: number } | null;
+    const count = (rlData?.count ?? 0) + 1;
+    this.db.set(`_auth/rateLimit/${fp}`, { count }, { ttl: this.options.authLockoutSeconds });
+  }
+
   /** Invalidate all sessions for a given device fingerprint */
   private _invalidateDeviceSessions(deviceFp: string): void {
     const sessions = this.db.getShallow('_auth/sessions');