@enbox/dwn-server 0.0.6 → 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
   // ---------------------------------------------------------------------------