@enbox/dwn-server 0.0.7 → 0.0.8

package/src/admin/admin-passkey-store.ts

@@ -0,0 +1,190 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+
+import { Kysely, sql } from 'kysely';
+
+/**
+ * A registered WebAuthn credential (passkey) for admin access.
+ */
+export type AdminPasskeyRecord = {
+  /** Base64url-encoded credential ID. */
+  id : string;
+  /** Human-readable name for the passkey (e.g. "MacBook Touch ID"). */
+  name : string;
+  /** Base64url-encoded COSE public key. */
+  publicKey : string;
+  /** Monotonically increasing counter for replay protection. */
+  counter : number;
+  /** WebAuthn transports the credential supports (JSON-encoded string array). */
+  transports : string;
+  /** ISO-8601 timestamp when the passkey was registered. */
+  createdAt : string;
+  /** ISO-8601 timestamp of the most recent successful authentication. */
+  lastUsedAt : string | null;
+};
+
+/**
+ * SQL-backed credential store for WebAuthn passkeys used by the admin panel.
+ *
+ * Follows the same Kysely + Dialect pattern as {@link AuditLog} and
+ * {@link WebhookManager}. The `adminPasskeys` table is created automatically
+ * on first use.
+ *
+ * Future: migrate to DID/DWN-based auth (see https://github.com/enboxorg/enbox/issues/546).
+ */
+export class AdminPasskeyStore {
+  static readonly #tableName = 'adminPasskeys';
+
+  #db: Kysely<PasskeyDatabase>;
+
+  private constructor(dialect: Dialect) {
+    this.#db = new Kysely<PasskeyDatabase>({ dialect });
+  }
+
+  /**
+   * Creates and initializes an `AdminPasskeyStore` instance.
+   * Creates the `adminPasskeys` table if it does not already exist.
+   */
+  public static async create(dialect: Dialect): Promise<AdminPasskeyStore> {
+    const store = new AdminPasskeyStore(dialect);
+    await store.#initialize();
+    return store;
+  }
+
+  /**
+   * Verifies that the required table exists. Throws a clear error directing
+   * the caller to run server migrations first.
+   */
+  async #initialize(): Promise<void> {
+    try {
+      await sql`SELECT 1 FROM ${sql.table(AdminPasskeyStore.#tableName)} LIMIT 0`.execute(this.#db);
+    } catch {
+      throw new Error(
+        `AdminPasskeyStore: table '${AdminPasskeyStore.#tableName}' does not exist. Run server migrations before starting.`
+      );
+    }
+  }
+
+  /**
+   * Stores a new passkey credential.
+   */
+  public async save(record: AdminPasskeyRecord): Promise<void> {
+    await this.#db
+      .insertInto(AdminPasskeyStore.#tableName)
+      .values({
+        id         : record.id,
+        name       : record.name,
+        publicKey  : record.publicKey,
+        counter    : record.counter,
+        transports : record.transports,
+        createdAt  : record.createdAt,
+        lastUsedAt : record.lastUsedAt ?? null,
+      })
+      .execute();
+  }
+
+  /**
+   * Retrieves a passkey by its credential ID.
+   */
+  public async getById(id: string): Promise<AdminPasskeyRecord | undefined> {
+    const row = await this.#db
+      .selectFrom(AdminPasskeyStore.#tableName)
+      .selectAll()
+      .where('id', '=', id)
+      .executeTakeFirst();
+
+    if (!row) {
+      return undefined;
+    }
+
+    return this.#toRecord(row);
+  }
+
+  /**
+   * Returns all registered passkeys, ordered by creation date (newest first).
+   */
+  public async list(): Promise<AdminPasskeyRecord[]> {
+    const rows = await this.#db
+      .selectFrom(AdminPasskeyStore.#tableName)
+      .selectAll()
+      .orderBy('createdAt', 'desc')
+      .execute();
+
+    return rows.map((row): AdminPasskeyRecord => this.#toRecord(row));
+  }
+
+  /**
+   * Returns the count of registered passkeys.
+   */
+  public async count(): Promise<number> {
+    const result = await this.#db
+      .selectFrom(AdminPasskeyStore.#tableName)
+      .select(this.#db.fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow();
+
+    return Number(result.count);
+  }
+
+  /**
+   * Updates the counter and last-used timestamp after a successful authentication.
+   */
+  public async updateCounter(id: string, counter: number): Promise<void> {
+    await this.#db
+      .updateTable(AdminPasskeyStore.#tableName)
+      .set({
+        counter,
+        lastUsedAt: new Date().toISOString(),
+      })
+      .where('id', '=', id)
+      .execute();
+  }
+
+  /**
+   * Deletes a passkey by its credential ID.
+   * @returns `true` if the passkey was found and deleted.
+   */
+  public async delete(id: string): Promise<boolean> {
+    const result = await this.#db
+      .deleteFrom(AdminPasskeyStore.#tableName)
+      .where('id', '=', id)
+      .executeTakeFirstOrThrow();
+
+    return Number(result.numDeletedRows) > 0;
+  }
+
+  /**
+   * Closes the underlying database connection.
+   */
+  public async close(): Promise<void> {
+    await this.#db.destroy();
+  }
+
+  #toRecord(row: PasskeyRow): AdminPasskeyRecord {
+    return {
+      id         : row.id,
+      name       : row.name,
+      publicKey  : row.publicKey,
+      counter    : Number(row.counter),
+      transports : row.transports,
+      createdAt  : row.createdAt,
+      lastUsedAt : row.lastUsedAt ?? null,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Kysely type definitions
+// ---------------------------------------------------------------------------
+
+interface PasskeyRow {
+  id : string;
+  name : string;
+  publicKey : string;
+  counter : number;
+  transports : string;
+  createdAt : string;
+  lastUsedAt : string | null;
+}
+
+interface PasskeyDatabase {
+  adminPasskeys : PasskeyRow;
+}

package/src/admin/admin-session.ts

@@ -0,0 +1,116 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * A lightweight in-memory session entry.
+ */
+type SessionEntry = {
+  /** Opaque session token (hex string). */
+  token : string;
+  /** Timestamp (ms) when the session was created. */
+  createdAt : number;
+  /** Timestamp (ms) when the session expires. */
+  expiresAt : number;
+};
+
+/**
+ * Manages short-lived sessions for admin passkey authentication.
+ *
+ * Sessions are opaque hex tokens stored in an in-memory `Map`. They are
+ * validated in {@link validateAdminAuth} as an alternative to the static
+ * bearer token. Expired sessions are lazily pruned on every create/validate
+ * call and periodically via a cleanup interval.
+ *
+ * Future: migrate to DID/DWN-based auth (see https://github.com/enboxorg/enbox/issues/546).
+ */
+export class AdminSessionManager {
+  /** Default session time-to-live: 24 hours (in seconds). */
+  static readonly #DEFAULT_TTL_SECONDS = 86400;
+  /** Cleanup runs every 10 minutes. */
+  static readonly #CLEANUP_INTERVAL_MS = 10 * 60 * 1000;
+
+  #sessions: Map<string, SessionEntry> = new Map();
+  #ttlMs: number;
+  #cleanupInterval: ReturnType<typeof setInterval> | undefined;
+
+  constructor(ttlSeconds?: number) {
+    this.#ttlMs = (ttlSeconds ?? AdminSessionManager.#DEFAULT_TTL_SECONDS) * 1000;
+    this.#startCleanup();
+  }
+
+  /**
+   * Creates a new session and returns the opaque token.
+   */
+  public create(): string {
+    this.#prune();
+
+    const token = randomBytes(32).toString('hex');
+    const now = Date.now();
+    this.#sessions.set(token, {
+      token,
+      createdAt : now,
+      expiresAt : now + this.#ttlMs,
+    });
+
+    return token;
+  }
+
+  /**
+   * Validates a session token. Returns `true` if the token is valid and not expired.
+   */
+  public validate(token: string): boolean {
+    const entry = this.#sessions.get(token);
+    if (!entry) {
+      return false;
+    }
+
+    if (Date.now() >= entry.expiresAt) {
+      this.#sessions.delete(token);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Revokes a session token.
+   */
+  public revoke(token: string): void {
+    this.#sessions.delete(token);
+  }
+
+  /**
+   * Returns the number of active (non-expired) sessions.
+   */
+  public get size(): number {
+    return this.#sessions.size;
+  }
+
+  /**
+   * Stops the periodic cleanup timer.
+   */
+  public destroy(): void {
+    if (this.#cleanupInterval) {
+      clearInterval(this.#cleanupInterval);
+      this.#cleanupInterval = undefined;
+    }
+    this.#sessions.clear();
+  }
+
+  /**
+   * Removes all expired sessions.
+   */
+  #prune(): void {
+    const now = Date.now();
+    for (const [token, entry] of this.#sessions) {
+      if (now >= entry.expiresAt) {
+        this.#sessions.delete(token);
+      }
+    }
+  }
+
+  #startCleanup(): void {
+    this.#cleanupInterval = setInterval((): void => {
+      this.#prune();
+    }, AdminSessionManager.#CLEANUP_INTERVAL_MS);
+  }
+}

package/src/admin/audit-log.ts

@@ -1,7 +1,7 @@
 import type { Dialect } from '@enbox/dwn-sql-store';
 
-import { Kysely } from 'kysely';
 import log from 'loglevel';
+import { Kysely, sql } from 'kysely';
 
 import { escapeLikeWildcards } from '../lib/sql-utils.js';
 
@@ -96,53 +96,16 @@ export class AuditLog {
   }
 
   /**
-   * Creates the audit log table and indices if they do not exist.
+   * Verifies that the required table exists. Throws a clear error directing
+   * the caller to run server migrations first.
    */
   async #initialize(): Promise<void> {
-    await this.#db.schema
-      .createTable(AuditLog.#tableName)
-      .ifNotExists()
-      .addColumn('id', 'integer', (col) => col.primaryKey().autoIncrement())
-      .addColumn('timestamp', 'text', (col) => col.notNull())
-      .addColumn('actor', 'text', (col) => col.notNull())
-      .addColumn('action', 'text', (col) => col.notNull())
-      .addColumn('target', 'text')
-      .addColumn('detail', 'text')
-      .execute();
-
-    // Indices for common query patterns. Wrapped in try/catch because
-    // `CREATE INDEX IF NOT EXISTS` syntax varies across dialects.
-    try {
-      await this.#db.schema
-        .createIndex('index_audit_timestamp')
-        .ifNotExists()
-        .on(AuditLog.#tableName)
-        .column('timestamp')
-        .execute();
-    } catch {
-      // Index already exists.
-    }
-
-    try {
-      await this.#db.schema
-        .createIndex('index_audit_target')
-        .ifNotExists()
-        .on(AuditLog.#tableName)
-        .column('target')
-        .execute();
-    } catch {
-      // Index already exists.
-    }
-
     try {
-      await this.#db.schema
-        .createIndex('index_audit_action')
-        .ifNotExists()
-        .on(AuditLog.#tableName)
-        .column('action')
-        .execute();
+      await sql`SELECT 1 FROM ${sql.table(AuditLog.#tableName)} LIMIT 0`.execute(this.#db);
     } catch {
-      // Index already exists.
+      throw new Error(
+        `AuditLog: table '${AuditLog.#tableName}' does not exist. Run server migrations before starting.`
+      );
     }
   }
 

package/src/admin/index.ts

@@ -1,5 +1,7 @@
 export { ActivityLog } from './activity-log.js';
 export { AdminApi } from './admin-api.js';
+export { AdminPasskeyStore } from './admin-passkey-store.js';
+export { AdminSessionManager } from './admin-session.js';
 export { AdminStore } from './admin-store.js';
 export { AuditLog } from './audit-log.js';
 export { validateAdminAuth } from './admin-auth.js';
@@ -9,6 +11,7 @@ export type {
   AdminConnectionSnapshot,
   AdminHealthCheck,
   AdminMessageSummary,
+  AdminPasskeySummary,
   AdminProtocolSummary,
   AdminServerStats,
   AdminSubscriptionSnapshot,
@@ -30,5 +33,7 @@ export type {
   TenantQuotaStatus,
   TenantStats,
 } from './types.js';
+export type { AdminAuthResult } from './admin-auth.js';
+export type { AdminPasskeyRecord } from './admin-passkey-store.js';
 export type { AuditEvent, AuditEventInput, AuditQueryOptions, AuditRetentionConfig } from './audit-log.js';
 export type { WebhookPayload } from './webhook-manager.js';

package/src/admin/types.ts

@@ -350,3 +350,31 @@ export type AdminWebhookInput = {
   events : string[];
   secret? : string;
 };
+
+// ---------------------------------------------------------------------------
+// Passkey (WebAuthn) authentication
+// ---------------------------------------------------------------------------
+
+/**
+ * Summary of a registered passkey for the admin API response.
+ *
+ * Future: migrate to DID/DWN-based auth (see https://github.com/enboxorg/enbox/issues/546).
+ */
+export type AdminPasskeySummary = {
+  /** Base64url-encoded credential ID. */
+  id : string;
+  /** Human-readable name (e.g. "MacBook Touch ID"). */
+  name : string;
+  /** ISO-8601 timestamp when the passkey was registered. */
+  createdAt : string;
+  /** ISO-8601 timestamp of the most recent successful authentication. */
+  lastUsedAt : string | null;
+};
+
+/**
+ * Request body for registering a new passkey.
+ */
+export type AdminPasskeyRegisterInput = {
+  /** Human-readable name for the passkey. */
+  name? : string;
+};

package/src/admin/webhook-manager.ts

@@ -2,9 +2,9 @@ import type { Dialect } from '@enbox/dwn-sql-store';
 import type { AdminWebhook, AdminWebhookInput } from './types.js';
 
 import { createHmac } from 'crypto';
-import { Kysely } from 'kysely';
 import log from 'loglevel';
 import { v4 as uuidv4 } from 'uuid';
+import { Kysely, sql } from 'kysely';
 
 /**
  * Payload delivered to webhook endpoints.
@@ -50,16 +50,18 @@ export class WebhookManager {
     return manager;
   }
 
+  /**
+   * Verifies that the required table exists. Throws a clear error directing
+   * the caller to run server migrations first.
+   */
   async #initialize(): Promise<void> {
-    await this.#db.schema
-      .createTable(WebhookManager.#tableName)
-      .ifNotExists()
-      .addColumn('id', 'text', (col) => col.primaryKey())
-      .addColumn('url', 'text', (col) => col.notNull())
-      .addColumn('events', 'text', (col) => col.notNull()) // JSON array
-      .addColumn('secret', 'text')
-      .addColumn('createdAt', 'text', (col) => col.notNull())
-      .execute();
+    try {
+      await sql`SELECT 1 FROM ${sql.table(WebhookManager.#tableName)} LIMIT 0`.execute(this.#db);
+    } catch {
+      throw new Error(
+        `WebhookManager: table '${WebhookManager.#tableName}' does not exist. Run server migrations before starting.`
+      );
+    }
   }
 
   // ---------------------------------------------------------------------------

package/src/config.ts

@@ -122,6 +122,27 @@ export const config = {
    */
   adminMetricsUpdateIntervalSeconds: parseInt(process.env.DWN_ADMIN_METRICS_UPDATE_INTERVAL || '30'),
 
+  /**
+   * WebAuthn Relying Party ID for admin passkey authentication. Typically
+   * the hostname of the DWN server (e.g. `dev.aws.dwn.enbox.id`). When not
+   * set, the hostname is extracted from `DWN_BASE_URL` at runtime.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/546
+   */
+  adminWebAuthnRpId: process.env.DWN_ADMIN_WEBAUTHN_RP_ID || undefined,
+
+  /**
+   * Human-readable Relying Party name shown during passkey registration.
+   * Defaults to `"DWN Admin"`.
+   */
+  adminWebAuthnRpName: process.env.DWN_ADMIN_WEBAUTHN_RP_NAME || 'DWN Admin',
+
+  /**
+   * Session time-to-live (in seconds) for passkey-authenticated sessions.
+   * Defaults to 86400 (24 hours).
+   */
+  adminSessionTtlSeconds: parseInt(process.env.DWN_ADMIN_SESSION_TTL || '86400'),
+
   // ---------------------------------------------------------------------------
   // Per-tenant storage quotas
   // ---------------------------------------------------------------------------

package/src/dwn-server.ts

@@ -16,6 +16,8 @@ import type { ProviderAuthPlugin } from './registration/provider-auth-plugin.js'
 
 import { ActivityLog } from './admin/activity-log.js';
 import { AdminApi } from './admin/admin-api.js';
+import { AdminPasskeyStore } from './admin/admin-passkey-store.js';
+import { AdminSessionManager } from './admin/admin-session.js';
 import { AdminStore } from './admin/admin-store.js';
 import { AuditLog } from './admin/audit-log.js';
 import { config as defaultConfig } from './config.js';
@@ -29,7 +31,7 @@ import { RateLimiter } from './rate-limiter.js';
 import { RegistrationManager } from './registration/registration-manager.js';
 import { WebhookManager } from './admin/webhook-manager.js';
 import { WsApi } from './ws-api.js';
-import { getDialectFromUrl, getDwnConfig } from './storage.js';
+import { getDialectFromUrl, getDwnConfig, runServerMigrationsIfNeeded } from './storage.js';
 import { removeProcessHandlers, setProcessHandlers } from './process-handlers.js';
 
 /**
@@ -97,6 +99,8 @@ export class DwnServer {
   #ipRateLimiter: RateLimiter | undefined;
   #tenantRateLimiter: RateLimiter | undefined;
   #auditLog: AuditLog | undefined;
+  #passkeyStore: AdminPasskeyStore | undefined;
+  #sessionManager: AdminSessionManager | undefined;
   #externalHooks: MessageProcessedHook[];
   #externalRegistrationManager: RegistrationManager | undefined;
   #externalOpenAuthHandler: OpenAuthHandler | undefined;
@@ -140,6 +144,13 @@ export class DwnServer {
    */
   async #setupServer(): Promise<void> {
 
+    // Run server migrations (admin stores, registration, TTL cache) FIRST,
+    // before creating any stores that depend on the server schema. The
+    // returned dialect is reused for the TTL cache and admin stores so that
+    // in-memory SQLite shares a single database instance across migrations
+    // and stores.
+    const serverDialect = await runServerMigrationsIfNeeded(this.config);
+
     let registrationManager: RegistrationManager | undefined;
 
     if (!this.dwn) {
@@ -223,34 +234,45 @@ export class DwnServer {
     let adminStore: AdminStore | undefined;
     let auditLog: AuditLog | undefined;
     let webhookManager: WebhookManager | undefined;
+    let passkeyStore: AdminPasskeyStore | undefined;
+    let sessionManager: AdminSessionManager | undefined;
 
     if (this.config.adminToken) {
       const storageUrl = this.config.messageStore;
       adminStore = AdminStore.create(storageUrl);
       activityLog = new ActivityLog(this.config.adminActivityLogCapacity);
 
-      // Create the persistent audit log using the registration store's dialect
-      // (same DB) or the message store URL as fallback.
+      // Reuse the dialect returned by server migrations when available — this
+      // is critical for in-memory SQLite where every `getDialectFromUrl` call
+      // creates a separate database. For Postgres, `serverDialect` points at
+      // the same shared pool, so reusing it also avoids pool proliferation.
       if (this.config.registrationStoreUrl) {
+        const adminDialect = serverDialect ?? getDialectFromUrl(new URL(this.config.registrationStoreUrl));
+
         try {
-          const auditDialect = getDialectFromUrl(new URL(this.config.registrationStoreUrl));
-          auditLog = await AuditLog.create(auditDialect, {
+          auditLog = await AuditLog.create(adminDialect, {
             maxAgeDays : this.config.auditLogMaxAgeDays,
             maxRows    : this.config.auditLogMaxRows,
           });
         } catch (err) {
           log.warn('Failed to create audit log:', err);
         }
-      }
 
-      // Create webhook manager using the same dialect as the audit log.
-      if (this.config.registrationStoreUrl) {
         try {
-          const webhookDialect = getDialectFromUrl(new URL(this.config.registrationStoreUrl));
-          webhookManager = await WebhookManager.create(webhookDialect);
+          webhookManager = await WebhookManager.create(adminDialect);
         } catch (err) {
           log.warn('Failed to create webhook manager:', err);
         }
+
+        // Create passkey store and session manager for WebAuthn admin auth.
+        // @see https://github.com/enboxorg/enbox/issues/546
+        try {
+          passkeyStore = await AdminPasskeyStore.create(adminDialect);
+          sessionManager = new AdminSessionManager(this.config.adminSessionTtlSeconds);
+          log.info('Admin passkey authentication enabled');
+        } catch (err) {
+          log.warn('Failed to create passkey store:', err);
+        }
       }
 
       adminApi = AdminApi.create({
@@ -264,6 +286,8 @@ export class DwnServer {
         ipRateLimiter,
         tenantRateLimiter,
         webhookManager,
+        passkeyStore,
+        sessionManager,
       });
 
       // Record server start event in audit log.
@@ -279,6 +303,8 @@ export class DwnServer {
     this.#ipRateLimiter = ipRateLimiter;
     this.#tenantRateLimiter = tenantRateLimiter;
     this.#auditLog = auditLog;
+    this.#passkeyStore = passkeyStore;
+    this.#sessionManager = sessionManager;
 
     // Create open-auth handler if provider auth is enabled with a JWT secret
     // and authorize/token URLs point to this server (or are not set — defaulting to built-in).
@@ -307,7 +333,11 @@ export class DwnServer {
 
     this.#httpApi = await HttpApi.create(
       this.config, this.dwn, registrationManager, adminApi, activityLog,
-      { adminStore, registrationStore, ipRateLimiter, tenantRateLimiter, messageProcessedHooks, openAuthHandler },
+      {
+        adminStore, registrationStore, ipRateLimiter, tenantRateLimiter,
+        messageProcessedHooks, openAuthHandler, sessionManager,
+        ttlCacheDialect: serverDialect,
+      },
     );
 
     await this.#httpApi.start(this.config.port);
@@ -400,6 +430,14 @@ export class DwnServer {
       await this.#auditLog.close();
     }
 
+    // Clean up passkey store and session manager.
+    if (this.#passkeyStore) {
+      await this.#passkeyStore.close();
+    }
+    if (this.#sessionManager) {
+      this.#sessionManager.destroy();
+    }
+
     // Clean up rate limiters (stops their interval timers).
     if (this.#ipRateLimiter) {
       this.#ipRateLimiter.destroy();