@bod.ee/db 0.9.0 → 0.10.1

package/src/server/Transport.ts

@@ -1,9 +1,12 @@
 import type { Server, ServerWebSocket } from 'bun';
 import type { BodDB } from './BodDB.ts';
 import type { RulesEngine } from './RulesEngine.ts';
+import type { KeyAuthEngine } from './KeyAuthEngine.ts';
+import { AUTH_PREFIX } from './KeyAuthEngine.ts';
 import type { ClientMessage } from '../shared/protocol.ts';
 import { Errors } from '../shared/errors.ts';
 import { normalizePath, pathKey } from '../shared/pathUtils.ts';
+import { increment, serverTimestamp, arrayUnion, arrayRemove } from '../shared/transforms.ts';
 
 interface VfsTransfer {
   path: string;
@@ -22,8 +25,12 @@ export interface WsData {
 export class TransportOptions {
   port: number = 4400;
   auth?: (token: string) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+  /** KeyAuth engine (auto-wired from BodDB) */
+  keyAuth?: KeyAuthEngine;
   /** Map URL paths to local file paths, e.g. { '/admin': './admin/ui.html' } */
   staticRoutes?: Record<string, string>;
+  /** Custom REST routes checked before 404. Return null to fall through. */
+  extraRoutes?: Record<string, (req: Request, url: URL) => Response | Promise<Response> | null>;
 }
 
 export class Transport {
@@ -85,6 +92,9 @@ export class Transport {
     if (req.method === 'PUT' && url.pathname.startsWith('/db/')) {
       return (async () => {
         const path = normalizePath(url.pathname.slice(4));
+        if (this.options.keyAuth && path.startsWith(AUTH_PREFIX)) {
+          return Response.json({ ok: false, error: `Write to ${AUTH_PREFIX} is reserved`, code: Errors.PERMISSION_DENIED }, { status: 403 });
+        }
         if (this.db.replication?.isReplica) {
           try {
             const body = await req.json();
@@ -108,6 +118,9 @@ export class Transport {
     if (req.method === 'DELETE' && url.pathname.startsWith('/db/')) {
       return (async () => {
         const path = normalizePath(url.pathname.slice(4));
+        if (this.options.keyAuth && path.startsWith(AUTH_PREFIX)) {
+          return Response.json({ ok: false, error: `Write to ${AUTH_PREFIX} is reserved`, code: Errors.PERMISSION_DENIED }, { status: 403 });
+        }
         if (this.db.replication?.isReplica) {
           try {
             await this.db.replication.proxyWrite({ op: 'delete', path });
@@ -252,6 +265,16 @@ export class Transport {
       if (filePath) return new Response(Bun.file(filePath));
     }
 
+    // Extra routes (custom REST handlers)
+    if (this.options.extraRoutes) {
+      for (const [pattern, handler] of Object.entries(this.options.extraRoutes)) {
+        if (url.pathname === pattern || url.pathname.startsWith(pattern + '/')) {
+          const result = handler(req, url);
+          if (result) return result;
+        }
+      }
+    }
+
     return new Response('Not Found', { status: 404 });
   }
 
@@ -281,6 +304,14 @@ export class Transport {
         const { id } = msg;
         const reply = (data: unknown, extra?: Record<string, unknown>) => ws.send(JSON.stringify({ id, ok: true, data, ...extra }));
         const error = (err: string, code: string) => ws.send(JSON.stringify({ id, ok: false, error: err, code }));
+        // Block external writes to _auth/ prefix (only KeyAuthEngine may write)
+        const guardAuthPrefix = (path: string) => {
+          if (self.options.keyAuth && normalizePath(path).startsWith(AUTH_PREFIX)) {
+            error(`Write to ${AUTH_PREFIX} is reserved`, Errors.PERMISSION_DENIED);
+            return true;
+          }
+          return false;
+        };
 
         try {
           switch (msg.op) {
@@ -305,6 +336,7 @@ export class Transport {
             }
 
             case 'set': {
+              if (guardAuthPrefix(msg.path)) return;
               if (self.db.replication?.isReplica) {
                 try { return reply(await self.db.replication.proxyWrite(msg)); }
                 catch (e: any) { return error(e.message, Errors.INTERNAL); }
@@ -317,6 +349,9 @@ export class Transport {
             }
 
             case 'update': {
+              for (const path of Object.keys(msg.updates)) {
+                if (guardAuthPrefix(path)) return;
+              }
               if (self.db.replication?.isReplica) {
                 try { return reply(await self.db.replication.proxyWrite(msg)); }
                 catch (e: any) { return error(e.message, Errors.INTERNAL); }
@@ -331,6 +366,7 @@ export class Transport {
             }
 
             case 'delete': {
+              if (guardAuthPrefix(msg.path)) return;
               if (self.db.replication?.isReplica) {
                 try { return reply(await self.db.replication.proxyWrite(msg)); }
                 catch (e: any) { return error(e.message, Errors.INTERNAL); }
@@ -433,6 +469,7 @@ export class Transport {
             }
 
             case 'push': {
+              if (guardAuthPrefix(msg.path)) return;
               if (self.db.replication?.isReplica) {
                 try { return reply(await self.db.replication.proxyWrite(msg)); }
                 catch (e: any) { return error(e.message, Errors.INTERNAL); }
@@ -664,6 +701,182 @@ export class Transport {
               return reply(moved);
             }
 
+            case 'auth-challenge': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              return reply(self.options.keyAuth.challenge());
+            }
+            case 'auth-verify': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              const result = self.options.keyAuth.verify(msg.publicKey, msg.signature, msg.nonce);
+              if (!result) return error('Authentication failed', Errors.AUTH_REQUIRED);
+              // Also set ws auth context
+              const ctx = self.options.keyAuth.validateToken(result.token);
+              if (ctx) ws.data.auth = ctx as unknown as Record<string, unknown>;
+              return reply(result);
+            }
+            case 'auth-link-device': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              // Password is the auth — engine.linkDevice verifies it
+              const linked = self.options.keyAuth.linkDevice(msg.accountFingerprint, msg.password, msg.devicePublicKey, msg.deviceName);
+              if (!linked) return error('Link failed (wrong password or account not found)', Errors.AUTH_REQUIRED);
+              return reply(linked);
+            }
+            case 'auth-change-password': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              // If authenticated, non-root can only change own password
+              if (ws.data.auth) {
+                const authCtx = ws.data.auth as { isRoot?: boolean; accountFingerprint?: string };
+                if (!authCtx.isRoot && authCtx.accountFingerprint !== msg.fingerprint) {
+                  return error('Can only change own password', Errors.PERMISSION_DENIED);
+                }
+              }
+              // Password is the auth — engine.changePassword verifies old password
+              const changed = self.options.keyAuth.changePassword(msg.fingerprint, msg.oldPassword, msg.newPassword);
+              if (!changed) return error('Password change failed (wrong password or device account)', Errors.AUTH_REQUIRED);
+              return reply(null);
+            }
+            case 'auth-create-account': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              // Root-only, or allowed when zero accounts exist (bootstrap)
+              if (ws.data.auth) {
+                const ctx = ws.data.auth as { isRoot?: boolean };
+                if (!ctx.isRoot) return error('Root only', Errors.PERMISSION_DENIED);
+              } else {
+                // Only allow unauthenticated if no accounts exist yet
+                const accounts = self.options.keyAuth.listAccounts();
+                if (accounts.length > 0) return error('Authentication required', Errors.AUTH_REQUIRED);
+              }
+              const result = self.options.keyAuth.createAccount(msg.password, msg.roles, msg.displayName, msg.devicePublicKey);
+              return reply(result);
+            }
+            case 'auth-register-device': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!self.options.keyAuth.options.allowOpenRegistration && !ws.data.auth) {
+                return error('Authentication required for registration', Errors.AUTH_REQUIRED);
+              }
+              const result = self.options.keyAuth.registerDevice(msg.publicKey, msg.displayName);
+              return reply(result);
+            }
+            case 'auth-revoke-session': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              self.options.keyAuth.revokeSession(msg.sid);
+              return reply(null);
+            }
+            case 'auth-revoke-device': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              self.options.keyAuth.revokeDevice(msg.accountFingerprint, msg.deviceFingerprint);
+              return reply(null);
+            }
+            case 'auth-create-role': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth || !(ws.data.auth as any).isRoot) return error('Root only', Errors.PERMISSION_DENIED);
+              self.options.keyAuth.createRole(msg.role);
+              return reply(null);
+            }
+            case 'auth-delete-role': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth || !(ws.data.auth as any).isRoot) return error('Root only', Errors.PERMISSION_DENIED);
+              self.options.keyAuth.deleteRole(msg.roleId);
+              return reply(null);
+            }
+            case 'auth-update-roles': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth || !(ws.data.auth as any).isRoot) return error('Root only', Errors.PERMISSION_DENIED);
+              self.options.keyAuth.updateAccountRoles(msg.accountFingerprint, msg.roles);
+              return reply(null);
+            }
+            case 'auth-list-accounts': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              return reply(self.options.keyAuth.listAccounts());
+            }
+            case 'auth-list-account-fingerprints': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              // Safe: returns only fingerprints + displayNames, no secrets
+              const accounts = self.options.keyAuth.listAccounts();
+              return reply(accounts.map((a: any) => ({ fingerprint: a.fingerprint, displayName: a.displayName })));
+            }
+            case 'auth-list-roles': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              return reply(self.options.keyAuth.listRoles());
+            }
+            case 'auth-list-devices': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              return reply(self.options.keyAuth.listDevices(msg.accountFingerprint));
+            }
+            case 'auth-list-sessions': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              return reply(self.options.keyAuth.listSessions(msg.accountFingerprint));
+            }
+            case 'auth-request-approval': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              return reply(self.options.keyAuth.requestApproval(msg.publicKey));
+            }
+            case 'auth-approve-device': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              const approverFp = (ws.data.auth as any).accountFingerprint;
+              if (!approverFp) return error('No account context', Errors.AUTH_REQUIRED);
+              const result = self.options.keyAuth.approveDevice(msg.requestId, approverFp);
+              if (!result) return error('Approval not found or already processed', Errors.NOT_FOUND);
+              return reply(result);
+            }
+            case 'auth-poll-approval': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              return reply(self.options.keyAuth.pollApproval(msg.requestId));
+            }
+            case 'auth-has-accounts': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              return reply({ hasAccounts: self.options.keyAuth.hasAccounts() });
+            }
+
+            case 'auth-account-info': {
+              if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
+              if (!ws.data.auth) return error('Authentication required', Errors.AUTH_REQUIRED);
+              const ctx = ws.data.auth as { accountFingerprint?: string };
+              const fp = msg.accountFingerprint || ctx.accountFingerprint;
+              if (!fp) return error('No account fingerprint', Errors.INVALID_PATH);
+              const info = self.options.keyAuth.getAccountInfo(fp);
+              if (!info) return error('Account not found', Errors.NOT_FOUND);
+              return reply(info);
+            }
+
+            case 'transform': {
+              const { path: tPath, type, value: tVal } = msg as any;
+              let sentinel: unknown;
+              switch (type) {
+                case 'increment': sentinel = increment(tVal as number); break;
+                case 'serverTimestamp': sentinel = serverTimestamp(); break;
+                case 'arrayUnion': sentinel = arrayUnion(...(Array.isArray(tVal) ? tVal : [tVal])); break;
+                case 'arrayRemove': sentinel = arrayRemove(...(Array.isArray(tVal) ? tVal : [tVal])); break;
+                default: return error(`Unknown transform: ${type}`, Errors.INTERNAL);
+              }
+              self.db.set(tPath, sentinel);
+              return reply(self.db.get(tPath));
+            }
+            case 'set-ttl': {
+              const { path: ttlPath, value: ttlVal, ttl } = msg as any;
+              self.db.set(ttlPath, ttlVal, { ttl });
+              return reply(null);
+            }
+            case 'sweep': {
+              return reply(self.db.sweep());
+            }
+            case 'get-rules': {
+              const ruleEntries = self.rules ? (self.rules as any).options?.rules ?? {} : {};
+              const summary = Object.entries(ruleEntries).map(([pattern, rule]: [string, any]) => ({
+                pattern,
+                read: rule.read === undefined ? null : rule.read === false ? false : rule.read === true ? true : rule.read.toString(),
+                write: rule.write === undefined ? null : rule.write === false ? false : rule.write === true ? true : rule.write.toString(),
+              }));
+              return reply(summary);
+            }
+
             default:
               return error('Unknown operation', Errors.INTERNAL);
           }

package/src/server/VFSEngine.ts

@@ -10,6 +10,54 @@ export interface VFSBackend {
   write(fileId: string, data: Uint8Array): Promise<void>;
   delete(fileId: string): Promise<void>;
   exists(fileId: string): Promise<boolean>;
+  /** Optional: create a directory on the physical filesystem */
+  mkdir?(dirPath: string): void;
+}
+
+// --- DiskBackend --- stores files as real directory structure on disk
+
+export class DiskBackend implements VFSBackend {
+  constructor(private root: string) {}
+
+  private resolvePath(filePath: string): string {
+    if (filePath.split('/').includes('..')) throw new Error(`Path traversal rejected: ${filePath}`);
+    return `${this.root}/${filePath}`;
+  }
+
+  async read(filePath: string): Promise<Uint8Array> {
+    const f = Bun.file(this.resolvePath(filePath));
+    if (!(await f.exists())) throw new Error(`File not found: ${filePath}`);
+    return new Uint8Array(await f.arrayBuffer());
+  }
+
+  async write(filePath: string, data: Uint8Array): Promise<void> {
+    const full = this.resolvePath(filePath);
+    const { mkdirSync } = require('fs');
+    const dir = full.substring(0, full.lastIndexOf('/'));
+    if (dir) try { mkdirSync(dir, { recursive: true }); } catch {}
+    await Bun.write(full, data);
+  }
+
+  async delete(filePath: string): Promise<void> {
+    const full = this.resolvePath(filePath);
+    const { unlink, rmdir } = require('fs/promises');
+    try { await unlink(full); } catch { return; }
+    // Cleanup empty parent dirs up to root
+    let dir = full.substring(0, full.lastIndexOf('/'));
+    while (dir.length > this.root.length) {
+      try { await rmdir(dir); } catch { break; }
+      dir = dir.substring(0, dir.lastIndexOf('/'));
+    }
+  }
+
+  async exists(filePath: string): Promise<boolean> {
+    return Bun.file(this.resolvePath(filePath)).exists();
+  }
+
+  mkdir(dirPath: string): void {
+    const { mkdirSync } = require('fs');
+    mkdirSync(this.resolvePath(dirPath), { recursive: true });
+  }
 }
 
 // --- LocalBackend ---
@@ -52,6 +100,8 @@ const META_KEY = '__meta';
 export class VFSEngineOptions {
   storageRoot: string = '.data/vfs';
   metaPrefix: string = '_vfs';
+  backend?: VFSBackend;
+  pathAsFileId?: boolean;
 }
 
 export class VFSEngine {
@@ -62,9 +112,13 @@ export class VFSEngine {
   constructor(db: BodDB, options?: Partial<VFSEngineOptions>) {
     this.options = { ...new VFSEngineOptions(), ...options };
     this.db = db;
-    this.backend = new LocalBackend(this.options.storageRoot);
-    const { mkdirSync } = require('fs');
-    try { mkdirSync(this.options.storageRoot, { recursive: true }); } catch {}
+    if (this.options.backend) {
+      this.backend = this.options.backend;
+    } else {
+      this.backend = new LocalBackend(this.options.storageRoot);
+      const { mkdirSync } = require('fs');
+      try { mkdirSync(this.options.storageRoot, { recursive: true }); } catch {}
+    }
   }
 
   private metaPath(virtualPath: string): string {
@@ -80,7 +134,7 @@ export class VFSEngine {
   async write(virtualPath: string, data: Uint8Array, mime?: string): Promise<FileStat> {
     const vp = normalizePath(virtualPath);
     const existing = this.db.get(this.metaPath(vp)) as Record<string, unknown> | null;
-    const fileId = (existing?.fileId as string) || generatePushId();
+    const fileId = this.options.pathAsFileId ? vp : ((existing?.fileId as string) || generatePushId());
 
     await this.backend.write(fileId, data);
 
@@ -134,15 +188,24 @@ export class VFSEngine {
     const name = vp.split('/').pop()!;
     const stat: FileStat = { name, path: vp, size: 0, mime: '', mtime: Date.now(), isDir: true };
     this.db.set(this.metaPath(vp), stat);
+    if (this.backend.mkdir) try { this.backend.mkdir(vp); } catch {}
     return stat;
   }
 
   async remove(virtualPath: string): Promise<void> {
     const vp = normalizePath(virtualPath);
-    const meta = this.db.get(this.metaPath(vp)) as Record<string, unknown> | null;
-    if (meta?.fileId) {
+    const meta = this.db.get(this.metaPath(vp)) as FileStat | null;
+
+    if (meta?.isDir) {
+      // Recursively delete children from backend before wiping metadata
+      const children = this.list(vp);
+      for (const child of children) {
+        await this.remove(child.path);
+      }
+    } else if (meta?.fileId) {
       await this.backend.delete(meta.fileId as string);
     }
+
     this.db.delete(this.containerPath(vp));
   }
 
@@ -152,8 +215,16 @@ export class VFSEngine {
     const meta = this.db.get(this.metaPath(srcPath)) as FileStat | null;
     if (!meta) throw new Error(`File not found: ${srcPath}`);
 
+    // For DiskBackend (pathAsFileId): physically move the file
+    if (this.options.pathAsFileId && meta.fileId && !meta.isDir) {
+      const data = await this.backend.read(meta.fileId);
+      await this.backend.write(dstPath, data);
+      await this.backend.delete(meta.fileId);
+    }
+
     const newName = dstPath.split('/').pop()!;
-    const updated: FileStat = { ...meta, name: newName, path: dstPath, mtime: Date.now() };
+    const fileId = this.options.pathAsFileId ? dstPath : meta.fileId;
+    const updated: FileStat = { ...meta, name: newName, path: dstPath, fileId, mtime: Date.now() };
     this.db.set(this.metaPath(dstPath), updated);
     this.db.delete(this.containerPath(srcPath));
     return updated;

package/src/shared/keyAuth.browser.ts

@@ -0,0 +1,80 @@
+/**
+ * Browser-compatible Ed25519 crypto for BodDB KeyAuth.
+ * Uses @noble/ed25519 (5KB, zero deps) with DER wrapping for server compatibility.
+ */
+import * as ed from '@noble/ed25519';
+
+// --- DER encoding prefixes (fixed ASN.1 headers for Ed25519) ---
+const SPKI_PREFIX = new Uint8Array([0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00]); // 12 bytes
+const PKCS8_PREFIX = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]); // 16 bytes
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+}
+
+function toBase64(buf: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < buf.length; i++) binary += String.fromCharCode(buf[i]);
+  return btoa(binary);
+}
+
+function fromBase64(str: string): Uint8Array {
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function toHex(buf: Uint8Array): string {
+  return Array.from(buf).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Wrap raw 32-byte public key in SPKI DER format */
+export function wrapPublicKey(raw: Uint8Array): Uint8Array {
+  return concat(SPKI_PREFIX, raw);
+}
+
+/** Extract raw 32-byte key from DER-encoded key */
+export function unwrapPublicKey(der: Uint8Array): Uint8Array {
+  return der.slice(SPKI_PREFIX.length);
+}
+
+export interface BrowserKeyPair {
+  /** DER-encoded public key (SPKI), base64 — compatible with server */
+  publicKeyBase64: string;
+  /** Raw 32-byte private key, base64 — for client-side storage only */
+  privateKeyBase64: string;
+  /** SHA-256 hex fingerprint of DER public key */
+  fingerprint: string;
+}
+
+/** Generate Ed25519 keypair. Returns DER-encoded public key (server-compatible) + raw private key. */
+export async function generateKeyPair(): Promise<BrowserKeyPair> {
+  const rawPriv = ed.utils.randomSecretKey();
+  const rawPub = await ed.getPublicKeyAsync(rawPriv);
+  const derPub = wrapPublicKey(rawPub);
+  const fp = await browserFingerprint(toBase64(derPub));
+  return {
+    publicKeyBase64: toBase64(derPub),
+    privateKeyBase64: toBase64(rawPriv),
+    fingerprint: fp,
+  };
+}
+
+/** Sign a nonce string with raw private key. Returns base64 DER-compatible signature. */
+export async function sign(nonce: string, privateKeyBase64: string): Promise<string> {
+  const rawPriv = fromBase64(privateKeyBase64);
+  const data = new TextEncoder().encode(nonce);
+  const sig = await ed.signAsync(data, rawPriv);
+  return toBase64(sig);
+}
+
+/** SHA-256 fingerprint of a base64 DER-encoded public key (hex string) */
+export async function browserFingerprint(publicKeyBase64: string): Promise<string> {
+  const derBytes = fromBase64(publicKeyBase64);
+  const hash = await crypto.subtle.digest('SHA-256', derBytes);
+  return toHex(new Uint8Array(hash));
+}

package/src/shared/keyAuth.ts

@@ -0,0 +1,177 @@
+import {
+  createHash, randomBytes, createCipheriv, createDecipheriv, pbkdf2Sync,
+  sign as cryptoSign, verify as cryptoVerify, generateKeyPairSync,
+} from 'crypto';
+
+// --- Types ---
+
+export interface KeyAuthAccount {
+  publicKey: string;       // base64
+  fingerprint: string;     // hex SHA-256 of publicKey
+  encryptedPrivateKey: string; // base64 (AES-256-GCM encrypted)
+  salt: string;            // base64 (PBKDF2 salt)
+  iv: string;              // base64 (AES-GCM IV)
+  authTag: string;         // base64 (AES-GCM auth tag)
+  displayName?: string;
+  roles: string[];
+  createdAt: number;
+  lastAuth: number;
+}
+
+export interface KeyAuthDevice {
+  publicKey: string;
+  fingerprint: string;
+  accountFingerprint: string;
+  certificate: string;     // base64 Ed25519 signature of (devicePubKey + accountFp + linkedAt)
+  name?: string;
+  linkedAt: number;
+  lastAuth: number;
+}
+
+export interface KeyAuthRole {
+  id: string;
+  name: string;
+  permissions: Array<{ path: string; read?: boolean; write?: boolean }>;
+}
+
+export interface KeyAuthSession {
+  fingerprint: string;      // device or root fingerprint
+  accountFingerprint: string;
+  roles: string[];
+  isRoot: boolean;
+  createdAt: number;
+  expiresAt: number;
+}
+
+export interface KeyAuthContext {
+  sid: string;
+  fingerprint: string;
+  accountFingerprint: string;
+  roles: string[];
+  isRoot: boolean;
+}
+
+export interface KeyAuthTokenPayload {
+  sid: string;
+  fp: string;
+  accountFp: string;
+  roles: string[];
+  root: boolean;
+  exp: number;
+}
+
+// --- Utils ---
+
+export function fingerprint(publicKeyBase64: string): string {
+  return createHash('sha256').update(Buffer.from(publicKeyBase64, 'base64')).digest('hex');
+}
+
+export function generateNonce(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+export function generateSessionId(): string {
+  return randomBytes(16).toString('base64url');
+}
+
+// --- Token encoding (self-signed, no JWT library) ---
+
+function base64url(buf: Buffer): string {
+  return buf.toString('base64url');
+}
+
+function fromBase64url(str: string): Buffer {
+  return Buffer.from(str, 'base64url');
+}
+
+export function encodeToken(payload: KeyAuthTokenPayload, serverPrivateKey: Uint8Array): string {
+  const payloadBytes = Buffer.from(JSON.stringify(payload));
+  const payloadB64 = base64url(payloadBytes);
+  const sig = cryptoSign(null, Buffer.from(payloadB64), {
+    key: Buffer.from(serverPrivateKey),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  return payloadB64 + '.' + base64url(sig);
+}
+
+export function decodeToken(token: string, serverPublicKey: Uint8Array): KeyAuthTokenPayload | null {
+  const dotIdx = token.indexOf('.');
+  if (dotIdx < 0) return null;
+  const payloadB64 = token.slice(0, dotIdx);
+  const sigB64 = token.slice(dotIdx + 1);
+  try {
+    const valid = cryptoVerify(null, Buffer.from(payloadB64), {
+      key: Buffer.from(serverPublicKey),
+      format: 'der',
+      type: 'spki',
+    }, fromBase64url(sigB64));
+    if (!valid) return null;
+    return JSON.parse(fromBase64url(payloadB64).toString());
+  } catch {
+    return null;
+  }
+}
+
+// --- Crypto: AES-256-GCM + PBKDF2 ---
+
+const PBKDF2_ITERATIONS = 100_000;
+const PBKDF2_KEYLEN = 32; // 256 bits
+const PBKDF2_DIGEST = 'sha256';
+
+export function encryptPrivateKey(privateKeyDer: Uint8Array, password: string): { encrypted: string; salt: string; iv: string; authTag: string } {
+  const salt = randomBytes(16);
+  const iv = randomBytes(12); // 96-bit for GCM
+  const derivedKey = pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
+  const cipher = createCipheriv('aes-256-gcm', derivedKey, iv);
+  const encrypted = Buffer.concat([cipher.update(privateKeyDer), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return {
+    encrypted: encrypted.toString('base64'),
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    authTag: authTag.toString('base64'),
+  };
+}
+
+export function decryptPrivateKey(encrypted: string, salt: string, iv: string, authTag: string, password: string): Uint8Array {
+  const derivedKey = pbkdf2Sync(password, Buffer.from(salt, 'base64'), PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
+  const decipher = createDecipheriv('aes-256-gcm', derivedKey, Buffer.from(iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(authTag, 'base64'));
+  const decrypted = Buffer.concat([decipher.update(Buffer.from(encrypted, 'base64')), decipher.final()]);
+  return new Uint8Array(decrypted);
+}
+
+// --- Ed25519 key generation ---
+
+export function generateEd25519KeyPair(): { publicKey: Uint8Array; privateKey: Uint8Array; publicKeyBase64: string } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'der' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'der' },
+  });
+  return {
+    publicKey: new Uint8Array(publicKey),
+    privateKey: new Uint8Array(privateKey),
+    publicKeyBase64: Buffer.from(publicKey).toString('base64'),
+  };
+}
+
+export function signData(data: Buffer, privateKeyDer: Uint8Array): Buffer {
+  return cryptoSign(null, data, {
+    key: Buffer.from(privateKeyDer),
+    format: 'der',
+    type: 'pkcs8',
+  });
+}
+
+export function verifySignature(data: Buffer, signature: Buffer, publicKeyDer: Uint8Array): boolean {
+  try {
+    return cryptoVerify(null, data, {
+      key: Buffer.from(publicKeyDer),
+      format: 'der',
+      type: 'spki',
+    }, signature);
+  } catch {
+    return false;
+  }
+}