@enbox/dwn-server 0.0.1

package/src/storage.ts

@@ -0,0 +1,213 @@
+import type { DidResolver } from '@enbox/dids';
+import type {
+  DataStore,
+  DwnConfig,
+  EventLog,
+  EventStream,
+  MessageStore,
+  ResumableTaskStore,
+  TenantGate,
+} from '@enbox/dwn-sdk-js';
+import type { Dialect } from '@enbox/dwn-sql-store';
+import type { DwnServerConfig } from './config.js';
+
+import * as fs from 'fs';
+import Cursor from 'pg-cursor';
+import Database from 'better-sqlite3';
+import pg from 'pg';
+import { createPool as MySQLCreatePool } from 'mysql2';
+import { PluginLoader } from './plugin-loader.js';
+
+import {
+  DataStoreLevel,
+  EventLogLevel,
+  MessageStoreLevel,
+  ResumableTaskStoreLevel,
+} from '@enbox/dwn-sdk-js';
+import {
+  DataStoreSql,
+  EventLogSql,
+  MessageStoreSql,
+  MysqlDialect,
+  PostgresDialect,
+  ResumableTaskStoreSql,
+  SqliteDialect,
+} from '@enbox/dwn-sql-store';
+
+export enum StoreType {
+  DataStore,
+  MessageStore,
+  EventLog,
+  ResumableTaskStore,
+}
+
+export enum BackendTypes {
+  LEVEL = 'level',
+  SQLITE = 'sqlite',
+  MYSQL = 'mysql',
+  POSTGRES = 'postgres',
+}
+
+export type DwnStore = DataStore | EventLog | MessageStore | ResumableTaskStore;
+
+export async function getDwnConfig(
+  config  : DwnServerConfig,
+  options : {
+    didResolver? : DidResolver,
+    tenantGate?  : TenantGate,
+    eventStream? : EventStream,
+  }
+): Promise<DwnConfig> {
+  const { tenantGate, eventStream, didResolver } = options;
+  const dataStore: DataStore = await getStore(config.dataStore, StoreType.DataStore);
+  const eventLog: EventLog = await getStore(config.eventLog, StoreType.EventLog);
+  const messageStore: MessageStore = await getStore(config.messageStore, StoreType.MessageStore);
+  const resumableTaskStore: ResumableTaskStore = await getStore(config.resumableTaskStore, StoreType.ResumableTaskStore);
+
+  return { didResolver, eventStream, eventLog, dataStore, messageStore, resumableTaskStore, tenantGate };
+}
+
+function getLevelStore(
+  storeURI: URL,
+  storeType: StoreType,
+): DwnStore {
+  switch (storeType) {
+    case StoreType.DataStore:
+      return new DataStoreLevel({
+        blockstoreLocation: storeURI.host + storeURI.pathname + '/DATASTORE',
+      });
+    case StoreType.MessageStore:
+      return new MessageStoreLevel({
+        blockstoreLocation: storeURI.host + storeURI.pathname + '/MESSAGESTORE',
+        indexLocation: storeURI.host + storeURI.pathname + '/INDEX',
+      });
+    case StoreType.EventLog:
+      return new EventLogLevel({
+        location: storeURI.host + storeURI.pathname + '/EVENTLOG',
+      });
+    case StoreType.ResumableTaskStore:
+      return new ResumableTaskStoreLevel({
+        location: storeURI.host + storeURI.pathname + '/RESUMABLE-TASK-STORE',
+      });
+    default:
+      throw new Error('Unexpected level store type');
+  }
+}
+
+function getSqlStore(
+  connectionUrl: URL,
+  storeType: StoreType,
+): DwnStore {
+  const dialect = getDialectFromUrl(connectionUrl);
+
+  switch (storeType) {
+    case StoreType.DataStore:
+      return new DataStoreSql(dialect);
+    case StoreType.MessageStore:
+      return new MessageStoreSql(dialect);
+    case StoreType.EventLog:
+      return new EventLogSql(dialect);
+    case StoreType.ResumableTaskStore:
+      return new ResumableTaskStoreSql(dialect);
+    default:
+      throw new Error(`Unsupported store type ${storeType} for SQL store.`);
+  }
+}
+
+/**
+ * Check if the given string is a file path.
+ */
+function isFilePath(configString: string): boolean {
+  const filePathPrefixes = ['/', './', '../'];
+  return filePathPrefixes.some(prefix => configString.startsWith(prefix));
+}
+
+async function getStore(storeString: string, storeType: StoreType.DataStore): Promise<DataStore>;
+async function getStore(storeString: string, storeType: StoreType.EventLog): Promise<EventLog>;
+async function getStore(storeString: string, storeType: StoreType.MessageStore): Promise<MessageStore>;
+async function getStore(storeString: string, storeType: StoreType.ResumableTaskStore): Promise<ResumableTaskStore>;
+async function getStore(storeConfigString: string, storeType: StoreType): Promise<DwnStore> {
+  if (isFilePath(storeConfigString)) {
+    return await loadStoreFromFilePath(storeConfigString, storeType);
+  }
+  // else treat the `storeConfigString` as a connection string
+  
+  const storeURI = new URL(storeConfigString);
+
+  switch (storeURI.protocol.slice(0, -1)) {
+    case BackendTypes.LEVEL:
+      return getLevelStore(storeURI, storeType);
+
+    case BackendTypes.SQLITE:
+    case BackendTypes.MYSQL:
+    case BackendTypes.POSTGRES:
+      return getSqlStore(storeURI, storeType);
+
+    default:
+      throw invalidStorageSchemeMessage(storeURI.protocol);
+  }
+}
+
+/**
+ * Loads a DWN store plugin of the given type from the given file path.
+ */
+async function loadStoreFromFilePath(
+  filePath: string,
+  storeType: StoreType,
+): Promise<DwnStore> {
+  switch (storeType) {
+    case StoreType.DataStore:
+      return await PluginLoader.loadPlugin<DataStore>(filePath);
+    case StoreType.EventLog:
+      return await PluginLoader.loadPlugin<EventLog>(filePath);
+    case StoreType.MessageStore:
+      return await PluginLoader.loadPlugin<MessageStore>(filePath);
+    case StoreType.ResumableTaskStore:
+      return await PluginLoader.loadPlugin<ResumableTaskStore>(filePath);
+    default:
+      throw new Error(`Loading store for unsupported store type ${storeType} from path ${filePath}`);
+  }
+}
+
+export function getDialectFromUrl(connectionUrl: URL): Dialect {
+  switch (connectionUrl.protocol.slice(0, -1)) {
+    case BackendTypes.SQLITE:
+      const path = connectionUrl.host + connectionUrl.pathname;
+      console.log('SQL-lite relative path:', path ? path : undefined); // NOTE, using ? for lose equality comparison
+
+      if (connectionUrl.host && !fs.existsSync(connectionUrl.host)) {
+        console.log('SQL-lite directory does not exist, creating:', connectionUrl.host);
+        fs.mkdirSync(connectionUrl.host, { recursive: true });
+      }
+
+      // Use in-memory database if no path is provided (for tests)
+      const dbPath = path || ':memory:';
+
+      return new SqliteDialect({
+        database: async () => new Database(dbPath),
+      });
+    case BackendTypes.MYSQL:
+      return new MysqlDialect({
+        pool: async () => MySQLCreatePool(connectionUrl.toString()),
+      });
+    case BackendTypes.POSTGRES:
+      return new PostgresDialect({
+        pool: async () => new pg.Pool({ connectionString: connectionUrl.toString() }),
+        cursor: Cursor,
+      });
+  }
+}
+
+function invalidStorageSchemeMessage(protocol: string): string {
+  const schemes = [];
+  for (const [_, value] of Object.entries(BackendTypes)) {
+    schemes.push(value);
+  }
+  return (
+    'Unknown storage protocol ' +
+    protocol.slice(0, 1) +
+    '! Please use one of: ' +
+    schemes.join(', ') +
+    '. For details, see README'
+  );
+}

package/src/web5-connect/sql-ttl-cache.ts

@@ -0,0 +1,137 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+import { Kysely } from 'kysely';
+
+/**
+ * The SqlTtlCache is responsible for storing and retrieving cache data with TTL (Time-to-Live).
+ */
+export class SqlTtlCache {
+  private static readonly cacheTableName = 'cacheEntries';
+  private static readonly cleanupIntervalInSeconds = 60;
+
+  private sqlDialect: Dialect;
+  private db: Kysely<CacheDatabase>;
+  private cleanupTimer: NodeJS.Timeout;
+
+  private constructor(sqlDialect: Dialect) {
+    this.db = new Kysely<CacheDatabase>({ dialect: sqlDialect });
+    this.sqlDialect = sqlDialect;
+  }
+
+  /**
+   * Creates a new SqlTtlCache instance.
+   */
+  public static async create(sqlDialect: Dialect): Promise<SqlTtlCache> {
+    const cacheManager = new SqlTtlCache(sqlDialect);
+
+    await cacheManager.initialize();
+
+    return cacheManager;
+  }
+
+  private async initialize(): Promise<void> {
+
+    // create table if it doesn't exist
+    const tableExists = await this.sqlDialect.hasTable(this.db, SqlTtlCache.cacheTableName);
+    if (!tableExists) {
+      await this.db.schema
+        .createTable(SqlTtlCache.cacheTableName)
+        .ifNotExists() // kept to show supported by all dialects in contrast to ifNotExists() below, though not needed due to tableExists check above
+        // 512 chars to accommodate potentially large `state` in Web5 Connect flow
+        .addColumn('key', 'varchar(512)', (column) => column.primaryKey())
+        .addColumn('value', 'text', (column) => column.notNull())
+        .addColumn('expiry', 'integer', (column) => column.notNull())
+        .execute();
+  
+      await this.db.schema
+        .createIndex('index_expiry')
+        // .ifNotExists() // intentionally kept commented out code to show that it is not supported by all dialects (ie. MySQL)
+        .on(SqlTtlCache.cacheTableName)
+        .column('expiry')
+        .execute();
+    }
+
+    // Start the cleanup timer
+    this.startCleanupTimer();
+  }
+
+  /**
+   * Starts a timer to periodically clean up expired cache entries.
+   */
+  private startCleanupTimer(): void {
+    this.cleanupTimer = setInterval(async () => {
+      await this.cleanUpExpiredEntries();
+    }, SqlTtlCache.cleanupIntervalInSeconds * 1000);
+  }
+
+  /**
+   * Inserts a cache entry.
+   * @param ttl The time-to-live in seconds.
+   */
+  public async insert(key: string, value: object, ttl: number): Promise<void> {
+    const expiry = Date.now() + (ttl * 1000);
+
+    const objectString = JSON.stringify(value);
+
+    await this.db
+      .insertInto(SqlTtlCache.cacheTableName)
+      .values({ key, value: objectString, expiry })
+      .execute();
+  }
+
+  /**
+   * Retrieves a cache entry if it is not expired and cleans up expired entries.
+   */
+  public async get(key: string): Promise<object | undefined> {
+    const result = await this.db
+      .selectFrom(SqlTtlCache.cacheTableName)
+      .select('key')
+      .select('value')
+      .select('expiry')
+      .where('key', '=', key)
+      .execute();
+
+    if (result.length === 0) {
+      return undefined;
+    }
+
+    const entry = result[0];
+
+    // if the entry is expired, don't return it and delete it
+    if (Date.now() >= entry.expiry) {
+      this.delete(key); // no need to await
+      return undefined;
+    }
+
+    return JSON.parse(entry.value);
+  }
+
+  /**
+   * Deletes a cache entry.
+   */
+  public async delete(key: string): Promise<void> {
+    await this.db
+      .deleteFrom(SqlTtlCache.cacheTableName)
+      .where('key', '=', key)
+      .execute();
+  }
+
+  /**
+   * Cleans up expired cache entries.
+   */
+  public async cleanUpExpiredEntries(): Promise<void> {
+    await this.db
+      .deleteFrom(SqlTtlCache.cacheTableName)
+      .where('expiry', '<', Date.now())
+      .execute();
+  }
+}
+
+interface CacheEntry {
+  key: string;
+  value: string;
+  expiry: number;
+}
+
+interface CacheDatabase {
+  cacheEntries: CacheEntry;
+}

package/src/web5-connect/web5-connect-server.ts

@@ -0,0 +1,122 @@
+import { getDialectFromUrl } from "../storage.js";
+import { CryptoUtils } from '@enbox/crypto';
+import { SqlTtlCache } from "./sql-ttl-cache.js";
+
+/**
+ * The Web5 Connect Request object.
+ */
+export type Web5ConnectRequest = any; // TODO: define type in common repo for reuse (https://github.com/TBD54566975/dwn-server/issues/138)
+
+/**
+ * The Web5 Connect Response object, which is also an OIDC ID token
+ */
+export type Web5ConnectResponse = any; // TODO: define type in common repo for reuse (https://github.com/TBD54566975/dwn-server/issues/138)
+
+/**
+ * The result of the setWeb5ConnectRequest() method.
+ */
+export type SetWeb5ConnectRequestResult = {
+  /**
+   * 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 Web5 Connect Server is responsible for handling the Web5 Connect flow.
+ */
+export class Web5ConnectServer {
+  public static readonly ttlInSeconds = 600;
+
+  private baseUrl: string;
+  private cache: SqlTtlCache;
+
+  /**
+   * Creates a new instance of the Web5 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 Web5 Connect Request object.
+   * @param params.sqlTtlCacheUrl The URL of the SQL database to use as the TTL cache.
+   */
+  public static async create({ baseUrl, sqlTtlCacheUrl }: {
+    baseUrl: string;
+    sqlTtlCacheUrl: string;
+  }): Promise<Web5ConnectServer> {
+    const web5ConnectServer = new Web5ConnectServer({ baseUrl });
+
+    // Initialize TTL cache.
+    const sqlDialect = getDialectFromUrl(new URL(sqlTtlCacheUrl));
+    web5ConnectServer.cache = await SqlTtlCache.create(sqlDialect);
+
+    return web5ConnectServer;
+  }
+
+  private constructor({ baseUrl }: {
+    baseUrl: string;
+  }) {
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Stores the given Web5 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 Web5 Connect flow.
+   */
+  public async setWeb5ConnectRequest(request: Web5ConnectRequest): Promise<SetWeb5ConnectRequestResult> {
+    // 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, Web5ConnectServer.ttlInSeconds);
+  
+    return {
+      request_uri,
+      expires_in  : Web5ConnectServer.ttlInSeconds,
+    };
+  }
+
+  /**
+   * Returns the Web5 Connect Request object. The request ID can only be used once.
+   */
+  public async getWeb5ConnectRequest(requestId: string): Promise<Web5ConnectRequest | 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 Web5 Connect Response object, which is also an OIDC ID token.
+   */
+  public async setWeb5ConnectResponse(state: string, response: Web5ConnectResponse): Promise<any> {
+    this.cache.insert(`response:${state}`, response, Web5ConnectServer.ttlInSeconds);
+  }
+
+  /**
+   * Gets the Web5 Connect Response object. The `state` string can only be used once.
+   */
+  public async getWeb5ConnectResponse(state: string): Promise<Web5ConnectResponse | 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;
+  }
+}

package/src/ws-api.ts

@@ -0,0 +1,45 @@
+
+import type {
+  Dwn,
+} from '@enbox/dwn-sdk-js';
+
+import type { Server } from 'http';
+
+import { WebSocketServer } from 'ws';
+
+import type { ConnectionManager } from './connection/connection-manager.js';
+import { InMemoryConnectionManager } from './connection/connection-manager.js';
+
+export class WsApi {
+  #wsServer: WebSocketServer;
+  dwn: Dwn;
+  #connectionManager: ConnectionManager
+
+  constructor(server: Server, dwn: Dwn, connectionManager?: ConnectionManager) {
+    this.dwn = dwn;
+    this.#connectionManager = connectionManager || new InMemoryConnectionManager(dwn);
+    this.#wsServer = new WebSocketServer({ server });
+  }
+
+  get server(): WebSocketServer {
+    return this.#wsServer;
+  }
+
+  /**
+   * Handler for starting a WebSocket.
+   * Sets listeners for `connection`, `close` events.
+   */
+  #setupWebSocket(): void {
+    this.#wsServer.on('connection', (socket, request) => this.#connectionManager.connect(socket, request));
+    this.#wsServer.on('close', () => this.#connectionManager.closeAll());
+  }
+
+  start(): void {
+    this.#setupWebSocket();
+  }
+
+  async close(): Promise<void> {
+    this.#wsServer.close();
+    await this.#connectionManager.closeAll();
+  }
+}