@enbox/agent 0.0.1

package/src/prototyping/clients/json-rpc-socket.ts

@@ -0,0 +1,169 @@
+import { CryptoUtils } from '@enbox/crypto';
+import IsomorphicWebSocket from 'isomorphic-ws';
+import { JsonRpcId, JsonRpcRequest, JsonRpcResponse, createJsonRpcSubscriptionRequest, parseJson } from './json-rpc.js';
+
+// These were arbitrarily chosen, but can be modified via connect options
+const CONNECT_TIMEOUT = 3_000;
+const RESPONSE_TIMEOUT = 30_000;
+
+export interface JsonRpcSocketOptions {
+  /** socket connection timeout in milliseconds */
+  connectTimeout?: number;
+  /** response timeout for rpc requests in milliseconds */
+  responseTimeout?: number;
+  /** optional connection close handler */
+  onclose?: () => void;
+  /** optional socket error handler */
+  onerror?: (error?: any) => void;
+}
+
+/**
+ * JSON RPC Socket Client for WebSocket request/response and long-running subscriptions.
+ *
+ * NOTE: This is temporarily copied over from https://github.com/TBD54566975/dwn-server/blob/main/src/json-rpc-socket.ts
+ * This was done in order to avoid taking a dependency on the `dwn-server`, until a future time when there will be a `clients` package.
+ */
+export class JsonRpcSocket {
+  private messageHandlers: Map<JsonRpcId, (event: { data: any }) => void> = new Map();
+
+  private constructor(private socket: IsomorphicWebSocket, private responseTimeout: number) {}
+
+  static async connect(url: string, options: JsonRpcSocketOptions = {}): Promise<JsonRpcSocket> {
+    const { connectTimeout = CONNECT_TIMEOUT, responseTimeout = RESPONSE_TIMEOUT, onclose, onerror } = options;
+
+    const socket = new IsomorphicWebSocket(url);
+
+    if (!onclose) {
+      socket.onclose = ():void => {
+        console.info(`JSON RPC Socket close ${url}`);
+      };
+    } else {
+      socket.onclose = onclose;
+    }
+
+    if (!onerror) {
+      socket.onerror = (error?: any):void => {
+        console.error(`JSON RPC Socket error ${url}`, error);
+      };
+    } else {
+      socket.onerror = onerror;
+    }
+
+    return new Promise<JsonRpcSocket>((resolve, reject) => {
+      socket.addEventListener('open', () => {
+        const jsonRpcSocket = new JsonRpcSocket(socket, responseTimeout);
+
+        socket.addEventListener('message', (event: { data: any }) => {
+          const jsonRpcResponse = parseJson(event.data) as JsonRpcResponse;
+          const handler = jsonRpcSocket.messageHandlers.get(jsonRpcResponse.id);
+          if (handler) {
+            handler(event);
+          }
+        });
+
+        resolve(jsonRpcSocket);
+      });
+
+      socket.addEventListener('error', (error: any) => {
+        reject(error);
+      });
+
+      setTimeout(() => reject, connectTimeout);
+    });
+  }
+
+  close(): void {
+    this.socket.close();
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket and waits for a single response.
+   */
+  async request(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    return new Promise((resolve, reject) => {
+      request.id ??= CryptoUtils.randomUuid();
+
+      const handleResponse = (event: { data: any }):void => {
+        const jsonRpsResponse = parseJson(event.data) as JsonRpcResponse;
+        if (jsonRpsResponse.id === request.id) {
+          // if the incoming response id matches the request id, we will remove the listener and resolve the response
+          this.messageHandlers.delete(request.id);
+          return resolve(jsonRpsResponse);
+        }
+      };
+
+      // add the listener to the map of message handlers
+      this.messageHandlers.set(request.id, handleResponse);
+      this.send(request);
+
+      // reject this promise if we don't receive any response back within the timeout period
+      setTimeout(() => {
+        this.messageHandlers.delete(request.id!);
+        reject(new Error('request timed out'));
+      }, this.responseTimeout);
+    });
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket and keeps a listener open to read associated responses as they arrive.
+   * Returns a close method to clean up the listener.
+   */
+  async subscribe(request: JsonRpcRequest, listener: (response: JsonRpcResponse) => void): Promise<{
+    response: JsonRpcResponse;
+    close?: () => Promise<void>;
+   }> {
+
+    if (!request.method.startsWith('rpc.subscribe.')) {
+      throw new Error('subscribe rpc requests must include the `rpc.subscribe` prefix');
+    }
+
+    if (!request.subscription) {
+      throw new Error('subscribe rpc requests must include subscribe options');
+    }
+
+    const subscriptionId = request.subscription.id;
+    const socketEventListener = (event: { data: any }):void => {
+      const jsonRpcResponse = parseJson(event.data.toString()) as JsonRpcResponse;
+      if (jsonRpcResponse.id === subscriptionId) {
+        if (jsonRpcResponse.error !== undefined) {
+          // remove the event listener upon receipt of a JSON RPC Error.
+          this.messageHandlers.delete(subscriptionId);
+          this.closeSubscription(subscriptionId);
+        }
+        listener(jsonRpcResponse);
+      }
+    };
+
+    this.messageHandlers.set(subscriptionId, socketEventListener);
+
+    const response = await this.request(request);
+    if (response.error) {
+      this.messageHandlers.delete(subscriptionId);
+      return { response };
+    }
+
+    // clean up listener and create a `rpc.subscribe.close` message to use when closing this JSON RPC subscription
+    const close = async (): Promise<void> => {
+      this.messageHandlers.delete(subscriptionId);
+      await this.closeSubscription(subscriptionId);
+    };
+
+    return {
+      response,
+      close
+    };
+  }
+
+  private closeSubscription(id: JsonRpcId): Promise<JsonRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const request = createJsonRpcSubscriptionRequest(requestId, 'close', id, {});
+    return this.request(request);
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket. You must subscribe to a message listener separately to capture the response.
+   */
+  send(request: JsonRpcRequest):void {
+    this.socket.send(JSON.stringify(request));
+  }
+}

package/src/prototyping/clients/json-rpc.ts

@@ -0,0 +1,113 @@
+export type JsonRpcId = string | number | null;
+export type JsonRpcParams = any;
+export type JsonRpcVersion = '2.0';
+
+export interface JsonRpcRequest {
+  jsonrpc: JsonRpcVersion;
+  id?: JsonRpcId;
+  /** JSON RPC Subscription Extension Parameters */
+  subscription?: { id: JsonRpcId }
+  method: string;
+  params?: any;
+}
+
+export interface JsonRpcError {
+  code: JsonRpcErrorCodes;
+  message: string;
+  data?: any;
+}
+
+export enum JsonRpcErrorCodes {
+  // JSON-RPC 2.0 pre-defined errors
+  InvalidRequest = -32600,
+  MethodNotFound = -32601,
+  InvalidParams = -32602,
+  InternalError = -32603,
+  ParseError = -32700,
+  TransportError = -32300,
+
+  // App defined errors
+  BadRequest = -50400, // equivalent to HTTP Status 400
+  Unauthorized = -50401, // equivalent to HTTP Status 401
+  Forbidden = -50403, // equivalent to HTTP Status 403,
+  Conflict = -50409, // equivalent to HTTP Status 409
+}
+
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+
+export interface JsonRpcSuccessResponse {
+  jsonrpc: JsonRpcVersion;
+  id: JsonRpcId;
+  result: any;
+  error?: never;
+}
+
+export interface JsonRpcErrorResponse {
+  jsonrpc: JsonRpcVersion;
+  id: JsonRpcId;
+  result?: never;
+  error: JsonRpcError;
+}
+
+export const createJsonRpcErrorResponse = (
+  id: JsonRpcId,
+  code: JsonRpcErrorCodes,
+  message: string,
+  data?: any,
+): JsonRpcErrorResponse => {
+  const error: JsonRpcError = { code, message, data };
+  return {
+    jsonrpc: '2.0',
+    id,
+    error,
+  };
+};
+
+export const createJsonRpcRequest = (
+  id: JsonRpcId,
+  method: string,
+  params?: JsonRpcParams,
+): JsonRpcRequest => {
+  return {
+    jsonrpc: '2.0',
+    id,
+    method,
+    params,
+  };
+};
+
+export const createJsonRpcSubscriptionRequest = (
+  id: JsonRpcId,
+  method: string,
+  subscriptionId: JsonRpcId,
+  params?: any
+): JsonRpcRequest => {
+  return {
+    jsonrpc      : '2.0',
+    id,
+    method       : `rpc.subscribe.${method}`,
+    params,
+    subscription : {
+      id: subscriptionId,
+    }
+  };
+};
+
+export const createJsonRpcSuccessResponse = (
+  id: JsonRpcId,
+  result: any,
+): JsonRpcSuccessResponse => {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result,
+  };
+};
+
+export function parseJson(text: string): object | null {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

package/src/prototyping/clients/server-info-types.ts

@@ -0,0 +1,21 @@
+import { KeyValueStore } from '@enbox/common';
+
+export type ServerInfo = {
+  /** the maximum file size the user can request to store */
+  maxFileSize: number,
+  /**
+   * an array of strings representing the server's registration requirements.
+   *
+   * ie. ['proof-of-work-sha256-v0', 'terms-of-service']
+   * */
+  registrationRequirements: string[],
+  /** whether web socket support is enabled on this server */
+  webSocketSupport: boolean,
+}
+
+export interface DwnServerInfoCache extends KeyValueStore<string, ServerInfo| undefined> {}
+
+export interface DwnServerInfoRpc {
+  /** retrieves the DWN Sever info, used to detect features such as WebSocket Subscriptions */
+  getServerInfo(url: string): Promise<ServerInfo>;
+}

package/src/prototyping/clients/web-socket-clients.ts

@@ -0,0 +1,100 @@
+import type { DwnRpc, DwnRpcRequest, DwnRpcResponse, DwnSubscriptionHandler } from './dwn-rpc-types.js';
+import type { GenericMessage, MessageSubscription, UnionMessageReply } from '@enbox/dwn-sdk-js';
+
+import { CryptoUtils } from '@enbox/crypto';
+import { createJsonRpcRequest, createJsonRpcSubscriptionRequest } from './json-rpc.js';
+import { JsonRpcSocket, JsonRpcSocketOptions } from './json-rpc-socket.js';
+
+interface SocketConnection {
+  socket: JsonRpcSocket;
+  subscriptions: Map<string, MessageSubscription>;
+}
+
+export class WebSocketDwnRpcClient implements DwnRpc {
+  public get transportProtocols() { return ['ws:', 'wss:']; }
+  // a map of dwn host to WebSocket connection
+  private static connections = new Map<string, SocketConnection>();
+
+  async sendDwnRequest(request: DwnRpcRequest, jsonRpcSocketOptions?: JsonRpcSocketOptions): Promise<DwnRpcResponse> {
+
+    // validate that the dwn URL provided is a valid WebSocket URL
+    const url = new URL(request.dwnUrl);
+    if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+      throw new Error(`Invalid websocket protocol ${url.protocol}`);
+    }
+
+    // check if there is already a connection to this host, if it does not exist, initiate a new connection
+    const hasConnection = WebSocketDwnRpcClient.connections.has(url.host);
+    if (!hasConnection) {
+      try {
+        const socket = await JsonRpcSocket.connect(url.toString(), jsonRpcSocketOptions);
+        const subscriptions = new Map();
+        WebSocketDwnRpcClient.connections.set(url.host, { socket, subscriptions });
+      } catch(error) {
+        throw new Error(`Error connecting to ${url.host}: ${(error as Error).message}`);
+      }
+    }
+
+    const connection = WebSocketDwnRpcClient.connections.get(url.host)!;
+    const { targetDid, message, subscriptionHandler } = request;
+
+    if (subscriptionHandler) {
+      return WebSocketDwnRpcClient.subscriptionRequest(connection, targetDid, message, subscriptionHandler);
+    }
+
+    return WebSocketDwnRpcClient.processMessage(connection, targetDid, message);
+  }
+
+  private static async processMessage(connection: SocketConnection, target: string, message: GenericMessage): Promise<DwnRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const request = createJsonRpcRequest(requestId, 'dwn.processMessage', { target, message });
+
+    const { socket } = connection;
+    const response = await socket.request(request);
+
+    const { error, result } = response;
+    if (error !== undefined) {
+      throw new Error(`error sending DWN request: ${error.message}`);
+    }
+
+    return result.reply as DwnRpcResponse;
+  }
+
+  private static async subscriptionRequest(connection: SocketConnection, target:string, message: GenericMessage, messageHandler: DwnSubscriptionHandler): Promise<DwnRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const subscriptionId = CryptoUtils.randomUuid();
+    const request = createJsonRpcSubscriptionRequest(requestId, 'dwn.processMessage', subscriptionId, { target, message });
+
+    const { socket, subscriptions } = connection;
+    const { response, close } = await socket.subscribe(request, (response) => {
+      const { result, error } = response;
+      if (error) {
+
+        // if there is an error, close the subscription and delete it from the connection
+        const subscription = subscriptions.get(subscriptionId);
+        if (subscription) {
+          subscription.close();
+        }
+
+        subscriptions.delete(subscriptionId);
+        return;
+      }
+
+      const { event } = result;
+      messageHandler(event);
+    });
+
+    const { error, result } = response;
+    if (error) {
+      throw new Error(`could not subscribe via jsonrpc socket: ${error.message}`);
+    }
+
+    const { reply } = result as { reply: UnionMessageReply };
+    if (reply.subscription && close) {
+      subscriptions.set(subscriptionId, { ...reply.subscription, close });
+      reply.subscription.close = close;
+    }
+
+    return reply;
+  }
+}

package/src/prototyping/common/object.ts

@@ -0,0 +1,15 @@
+export function hasDuplicateProperties(...objects: Array<Record<string, any> | undefined>): boolean {
+  const propertySet = new Set<string>();
+  const objectsWithoutUndefined = objects.filter(Boolean); // Remove any undefined values
+
+  for (const obj of objectsWithoutUndefined) {
+    for (const key in obj) {
+      if (propertySet.has(key)) {
+        return true; // Return true if a duplicate property is found
+      }
+      propertySet.add(key);
+    }
+  }
+
+  return false; // Return false if no duplicates are found
+}

package/src/prototyping/common/type-utils.ts

@@ -0,0 +1,6 @@
+/**
+ * Infer the type of a type parameter.
+ *
+ * This is useful when you want to infer the type of a type parameter in a generic function.
+ */
+export type InferType<T> = T extends infer U ? U : never;

package/src/prototyping/crypto/algorithms/aes-gcm.ts

@@ -0,0 +1,211 @@
+import type {
+  Jwk,
+  Cipher,
+  KeyConverter,
+  KeyGenerator,
+  DecryptParams,
+  EncryptParams,
+  GenerateKeyParams,
+} from '@enbox/crypto';
+
+import { AesGcm, AES_GCM_TAG_LENGTHS, CryptoAlgorithm } from '@enbox/crypto';
+
+import type { BytesToPrivateKeyParams, PrivateKeyToBytesParams } from '../types/params-direct.js';
+
+/**
+ * The `AesGcmGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the AES-GCM algorithm.
+ */
+export interface AesGcmGenerateKeyParams extends GenerateKeyParams {
+  /** Specifies the algorithm variant for key generation in AES-GCM mode.
+   * The value determines the length of the key to be generated and must be one of the following:
+   * - `"A128GCM"`: Generates a 128-bit key.
+   * - `"A192GCM"`: Generates a 192-bit key.
+   * - `"A256GCM"`: Generates a 256-bit key.
+   */
+  algorithm: 'A128GCM' | 'A192GCM' | 'A256GCM';
+}
+
+/**
+ * The `AesGcmParams` interface defines the algorithm-specific parameters that should be passed
+ * into the `encrypt()` and `decrypt()` methods when using the AES-GCM algorithm.
+ */
+export interface AesGcmParams {
+  /**
+   * The `additionalData` property is used for authentication alongside encrypted data but isn't
+   * encrypted itself. It must match in both encryption and decryption; a mismatch will cause
+   * decryption to fail. This feature allows for the authentication of data without encrypting it.
+   *
+   * The `additionalData` property is optional and omitting it does not compromise encryption
+   * security.
+   */
+  additionalData?: Uint8Array;
+
+  /**
+   * The initialization vector (IV) must be unique for every encryption operation carried out with a
+   * given key. The IV need not be secret, but it must be unpredictable: that is, the IV must not be
+   * reused with the same key. The IV must be 12 bytes (96 bits) in length in accordance with the
+   * AES-GCM specification recommendedation to promote interoperability and efficiency.
+   *
+   * Note: It is OK to transmit the IV in the clear with the encrypted message.
+   */
+  iv: Uint8Array;
+
+  /**
+   * This property determines the size in bits of the authentication tag generated in the encryption
+   * operation and used for authentication in the corresponding decryption. In accordance with the
+   * AES-GCM specification, the tag length must be 96, 104, 112, 120 or 128.
+   *
+   * The `tagLength` property is optional and defaults to 128 bits if omitted.
+   */
+  tagLength?: typeof AES_GCM_TAG_LENGTHS[number];
+}
+
+/**
+ * The `AesGcmAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the AES algorithm in Galois/Counter Mode (GCM). This class implements both
+ * {@link Cipher | `Cipher`} and { @link KeyGenerator | `KeyGenerator`} interfaces, providing
+ * key generation, encryption, and decryption features.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export class AesGcmAlgorithm extends CryptoAlgorithm
+  implements Cipher<AesGcmParams, AesGcmParams>,
+             KeyConverter,
+             KeyGenerator<AesGcmGenerateKeyParams, Jwk> {
+
+  public async bytesToPrivateKey({ privateKeyBytes }: BytesToPrivateKeyParams): Promise<Jwk> {
+    // Convert the byte array to a JWK.
+    const privateKey = await AesGcm.bytesToPrivateKey({ privateKeyBytes });
+
+    // Set the `alg` property based on the key length.
+    privateKey.alg = { 16: 'A128GCM', 24: 'A192GCM', 32: 'A256GCM' }[privateKeyBytes.length];
+
+    return privateKey;
+  }
+
+  /**
+   * Decrypts the provided data using AES-GCM.
+   *
+   * @remarks
+   * This method performs AES-GCM decryption on the given encrypted data using the specified key.
+   * It requires an initialization vector (IV), the encrypted data along with the decryption key,
+   * and optionally, additional authenticated data (AAD). The method returns the decrypted data as a
+   * Uint8Array. The optional `tagLength` parameter specifies the size in bits of the authentication
+   * tag used when encrypting the data. If not specified, the default tag length of 128 bits is
+   * used.
+   *
+   * @example
+   * ```ts
+   * const aesGcm = new AesGcmAlgorithm();
+   * const encryptedData = new Uint8Array([...]); // Encrypted data
+   * const iv = new Uint8Array([...]); // Initialization vector used during encryption
+   * const additionalData = new Uint8Array([...]); // Optional additional authenticated data
+   * const key = { ... }; // A Jwk object representing the AES key
+   * const decryptedData = await aesGcm.decrypt({
+   *   data: encryptedData,
+   *   iv,
+   *   additionalData,
+   *   key,
+   *   tagLength: 128 // Optional tag length in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for the decryption operation.
+   *
+   * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+   */
+  public async decrypt(params:
+    DecryptParams & AesGcmParams
+  ): Promise<Uint8Array> {
+    const plaintext = AesGcm.decrypt(params);
+
+    return plaintext;
+  }
+
+  /**
+   * Encrypts the provided data using AES-GCM.
+   *
+   * @remarks
+   * This method performs AES-GCM encryption on the given data using the specified key.
+   * It requires an initialization vector (IV), the encrypted data along with the decryption key,
+   * and optionally, additional authenticated data (AAD). The method returns the encrypted data as a
+   * Uint8Array. The optional `tagLength` parameter specifies the size in bits of the authentication
+   * tag generated in the encryption operation and used for authentication in the corresponding
+   * decryption. If not specified, the default tag length of 128 bits is used.
+   *
+   * @example
+   * ```ts
+   * const aesGcm = new AesGcmAlgorithm();
+   * const data = new TextEncoder().encode('Messsage');
+   * const iv = new Uint8Array([...]); // Initialization vector
+   * const additionalData = new Uint8Array([...]); // Optional additional authenticated data
+   * const key = { ... }; // A Jwk object representing an AES key
+   * const encryptedData = await aesGcm.encrypt({
+   *   data,
+   *   iv,
+   *   additionalData,
+   *   key,
+   *   tagLength: 128 // Optional tag length in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for the encryption operation.
+   *
+   * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+   */
+  public async encrypt(params:
+    EncryptParams & AesGcmParams
+  ): Promise<Uint8Array> {
+    const ciphertext = AesGcm.encrypt(params);
+
+    return ciphertext;
+  }
+
+  /**
+   * Generates a symmetric key for AES in Galois/Counter Mode (GCM) in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method generates a symmetric AES key for use in GCM mode, based on the specified
+   * `algorithm` parameter which determines the key length. It uses cryptographically secure random
+   * number generation to ensure the uniqueness and security of the key. The key is returned in JWK
+   * format.
+   *
+   * The generated key includes the following components:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence.
+   * - `k`: The symmetric key component, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   *
+   * @example
+   * ```ts
+   * const aesGcm = new AesGcmAlgorithm();
+   * const privateKey = await aesGcm.generateKey({ algorithm: 'A256GCM' });
+   * ```
+   *
+   * @param params - The parameters for the key generation.
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public async generateKey({ algorithm }:
+    AesGcmGenerateKeyParams
+  ): Promise<Jwk> {
+    // Map algorithm name to key length.
+    const length = { A128GCM: 128, A192GCM: 192, A256GCM: 256 }[algorithm] as 128 | 192 | 256;
+
+    // Generate a random private key.
+    const privateKey = await AesGcm.generateKey({ length });
+
+    // Set the `alg` property based on the specified algorithm.
+    privateKey.alg = algorithm;
+
+    return privateKey;
+  }
+
+  public async privateKeyToBytes({ privateKey }: PrivateKeyToBytesParams): Promise<Uint8Array> {
+    // Convert the JWK to a byte array.
+    const privateKeyBytes = await AesGcm.privateKeyToBytes({ privateKey });
+
+    return privateKeyBytes;
+  }
+}