@enbox/dwn-server 0.0.7 → 0.0.9

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/admin-store.ts

@@ -161,10 +161,14 @@ export class AdminStore {
 
   /**
    * Returns the total data storage in bytes for a tenant.
+   *
+   * Uses `messageStoreMessages.dataSize` rather than `dataRefs.dataSize` so that
+   * **all** data is accounted for — including small payloads (<=30 KB) that the
+   * DWN SDK stores inline as `encodedData` and never writes to the data store.
    */
   public async getTenantStorageSize(did: string): Promise<number> {
     const result = await this.db
-      .selectFrom('dataRefs')
+      .selectFrom('messageStoreMessages')
       .select(this.db.fn.sum<number>('dataSize').as('totalBytes'))
       .where('tenant', '=', did)
       .executeTakeFirstOrThrow();
@@ -212,7 +216,7 @@ export class AdminStore {
         .select(this.db.fn.countAll<number>().as('count'))
         .executeTakeFirstOrThrow(),
       this.db
-        .selectFrom('dataRefs')
+        .selectFrom('messageStoreMessages')
         .select(this.db.fn.sum<number>('dataSize').as('totalBytes'))
         .executeTakeFirstOrThrow(),
       this.db

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/connect/connect-server.ts

@@ -0,0 +1,150 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+
+import { CryptoUtils } from '@enbox/crypto';
+
+import { SqlTtlCache } from './sql-ttl-cache.js';
+
+/**
+ * The Connect Request object.
+ */
+export type ConnectRequest = any; // TODO: define type in common repo for reuse (https://github.com/enboxorg/enbox/issues/138)
+
+/**
+ * The Connect Response object, which is also an OIDC ID token
+ */
+export type ConnectResponse = any; // TODO: define type in common repo for reuse (https://github.com/enboxorg/enbox/issues/138)
+
+/**
+ * The result of the setConnectRequest() method.
+ */
+export type SetConnectRequestResult = {
+  /**
+   * The Request URI that the wallet should use to retrieve the request object.
+   */
+  request_uri: string;
+
+  /**
+   * The time in seconds that the Request URI is valid for.
+   */
+  expires_in: number;
+};
+
+/**
+ * The Connect Server is responsible for handling the DWeb Connect flow.
+ */
+export class ConnectServer {
+  public static readonly ttlInSeconds = 600;
+
+  private baseUrl: string;
+  private cache: SqlTtlCache;
+
+  /**
+   * Creates a new instance of the Connect Server.
+   * @param params.baseUrl The the base URL of the connect server including the port.
+   *                       This is given to the Identity Provider (wallet) to fetch the Connect Request object.
+   * @param params.sqlDialect The SQL dialect to use for the TTL cache. Must point to a database
+   *                          where server migrations have already been run.
+   */
+  public static async create({ baseUrl, sqlDialect }: {
+    baseUrl: string;
+    sqlDialect: Dialect;
+  }): Promise<ConnectServer> {
+    const connectServer = new ConnectServer({ baseUrl });
+
+    // Initialize TTL cache.
+    connectServer.cache = await SqlTtlCache.create(sqlDialect);
+
+    return connectServer;
+  }
+
+  private constructor({ baseUrl }: {
+    baseUrl: string;
+  }) {
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Stores the given Connect Request object, which is also an OAuth 2 Pushed Authorization Request (PAR) object.
+   * This is the initial call to the connect server to start the DWeb Connect flow.
+   */
+  public async setConnectRequest(request: ConnectRequest): Promise<SetConnectRequestResult> {
+    // Generate a request URI
+    const requestId = CryptoUtils.randomUuid();
+    const request_uri = `${this.baseUrl}/connect/authorize/${requestId}.jwt`;
+
+    // Store the Request Object.
+    this.cache.insert(`request:${requestId}`, request, ConnectServer.ttlInSeconds);
+
+    return {
+      request_uri,
+      expires_in: ConnectServer.ttlInSeconds,
+    };
+  }
+
+  /**
+   * Returns the Connect Request object. The request ID can only be used once.
+   */
+  public async getConnectRequest(requestId: string): Promise<ConnectRequest | undefined> {
+    const request = await this.cache.get(`request:${requestId}`);
+
+    // Delete the Request Object from cache once it has been retrieved.
+    // IMPORTANT: only delete if the object exists, otherwise there could be a race condition
+    // where the object does not exist in this call but becomes available immediately after,
+    // we would end up deleting it before it is successfully retrieved.
+    if (request !== undefined) {
+      this.cache.delete(`request:${requestId}`);
+    }
+
+    return request;
+  }
+
+  /**
+   * Sets the Connect Response object, which is also an OIDC ID token.
+   */
+  public async setConnectResponse(state: string, response: ConnectResponse): Promise<any> {
+    this.cache.insert(`response:${state}`, response, ConnectServer.ttlInSeconds);
+  }
+
+  /**
+   * Gets the Connect Response object. The `state` string can only be used once.
+   */
+  public async getConnectResponse(state: string): Promise<ConnectResponse | undefined> {
+    const response = await this.cache.get(`response:${state}`);
+
+    // Delete the Response object from the cache once it has been retrieved.
+    // IMPORTANT: only delete if the object exists, otherwise there could be a race condition
+    // where the object does not exist in this call but becomes available immediately after,
+    // we would end up deleting it before it is successfully retrieved.
+    if (response !== undefined) {
+      this.cache.delete(`response:${state}`);
+    }
+
+    return response;
+  }
+
+  /**
+   * Stops the TTL cache cleanup timer. Must be called during shutdown to
+   * prevent leaked timers.
+   */
+  public close(): void {
+    this.cache.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deprecated aliases — migration aid
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use {@link ConnectRequest} instead. Will be removed in a future version. */
+export type Web5ConnectRequest = ConnectRequest;
+
+/** @deprecated Use {@link ConnectResponse} instead. Will be removed in a future version. */
+export type Web5ConnectResponse = ConnectResponse;
+
+/** @deprecated Use {@link SetConnectRequestResult} instead. Will be removed in a future version. */
+export type SetWeb5ConnectRequestResult = SetConnectRequestResult;
+
+/** @deprecated Use {@link ConnectServer} instead. Will be removed in a future version. */
+export const Web5ConnectServer = ConnectServer;
+/** @deprecated Use {@link ConnectServer} instead. Will be removed in a future version. */
+export type Web5ConnectServer = ConnectServer;