@enbox/agent 0.0.1

package/src/prototyping/crypto/types/params-direct.ts

@@ -0,0 +1,95 @@
+import type { Jwk } from '@enbox/crypto';
+
+
+export interface BytesToPrivateKeyParams {
+  algorithm: AlgorithmIdentifier;
+  privateKeyBytes: Uint8Array;
+}
+
+export interface BytesToPublicKeyParams {
+  algorithm: AlgorithmIdentifier;
+  publicKeyBytes: Uint8Array;
+}
+
+/**
+ * Parameters for encryption and decryption operations.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface CipherParams {
+  /** A {@link Jwk} containing the key to be used for encryption or decryption. */
+  key: Jwk;
+
+  /** Data to be encrypted or decrypted. */
+  data: Uint8Array;
+
+  /** Additional algorithm-specific parameters for encryption or decryption. */
+  [key: string]: unknown;
+}
+
+/**
+ * Parameters for derivation of cryptographic keys.
+ */
+export interface DeriveKeyParams {
+  /** The algorithm identifier. */
+  algorithm: AlgorithmIdentifier;
+
+  /** The base key to be used for derivation as a byte array. */
+  baseKeyBytes: Uint8Array;
+
+  /** The algorithm identifier for the derived key. */
+  derivedKeyAlgorithm?: AlgorithmIdentifier;
+
+  /** Additional algorithm-specific parameters for key derivation. */
+  [key: string]: unknown;
+}
+
+/**
+ * Parameters for derivation of cryptographic byte arrays.
+ */
+export interface DeriveKeyBytesParams {
+  /** The base key to be used for derivation as a byte array. */
+  baseKeyBytes: Uint8Array;
+
+  /** The desired length of the derived key in bits. */
+  length: number;
+}
+
+export interface PrivateKeyToBytesParams {
+  privateKey: Jwk;
+}
+
+export interface PublicKeyToBytesParams {
+  publicKey: Jwk;
+}
+
+/**
+ * Parameters for wrapping a key.
+ */
+export interface WrapKeyParams {
+  /** A {@link Jwk} containing the key used to encrypt the unwrapped key. */
+  encryptionKey: Jwk;
+
+  /** A {@link Jwk} containing the private key to be wrapped. */
+  unwrappedKey: Jwk;
+
+  /** An object defining the algorithm-specific parameters for encrypting the `unwrappedKey`. */
+  encryptParams?: unknown
+}
+
+/**
+ * Parameters for unwrapping a key.
+ */
+export interface UnwrapKeyParams {
+  /** A {@link Jwk} containing the key used to decrypt the unwrapped key. */
+  decryptionKey: Jwk;
+
+  /** The wrapped private key as a byte array. */
+  wrappedKeyBytes: Uint8Array;
+
+  /** The algorithm identifier of the key encrypted in `wrappedKeyBytes`. */
+  wrappedKeyAlgorithm: string;
+
+  /** An object defining the algorithm-specific parameters for decrypting the `wrappedKeyBytes`. */
+  decryptParams?: unknown;
+}

package/src/prototyping/crypto/types/params-kms.ts

@@ -0,0 +1,76 @@
+import type { Jwk, KeyIdentifier } from '@enbox/crypto';
+
+/**
+ * Parameters for KMS-based encryption and decryption operations.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface KmsCipherParams {
+  /** Identifier for the private key in the KMS. */
+  keyUri: KeyIdentifier;
+
+  /** Data to be encrypted or decrypted. */
+  data: Uint8Array;
+}
+
+/**
+ * Parameters for KMS-based derivation of a cryptographic key from a given base key.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface KmsDeriveKeyParams {
+  /** Identifier for the base key used in derivation in the KMS. */
+  baseKeyUri: KeyIdentifier;
+
+  /** An object defining the algorithm-specific parameters for the derived key. */
+  derivedKeyParams: unknown
+}
+
+/**
+ * Parameters for KMS-based derivation of a byte array from a given base key.
+ *
+ * Intended for use with a Key Management System.
+ */
+export interface KmsDeriveKeyBytesParams {
+  /** Identifier for the base key used in derivation in the KMS. */
+  baseKeyUri: KeyIdentifier;
+
+  /** The desired length of the derived key in bits. */
+  length: number;
+}
+
+/**
+ * Parameters for unwrapping a key using a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsUnwrapKeyParams {
+  /** Identifier for the private key in the KMS used for decrypting the wrapped key. */
+  decryptionKeyUri: KeyIdentifier;
+
+  /** The wrapped private key as a byte array. */
+  wrappedKeyBytes: Uint8Array;
+
+  /** The algorithm identifier of the key encrypted in `wrappedKeyBytes`. */
+  wrappedKeyAlgorithm: string;
+
+  /** An object defining the algorithm-specific parameters for decrypting the `wrappedKeyBytes`. */
+  decryptParams?: unknown;
+}
+
+/**
+ * Parameters for wrapping a key using a KMS. Intended for use with a Key Management System.
+ */
+export interface KmsWrapKeyParams {
+  /** Identifier for the private key in the KMS used for encrypting the unwrapped key. */
+  encryptionKeyUri: KeyIdentifier;
+
+  /** A {@link Jwk} containing the private key to be wrapped. */
+  unwrappedKey: Jwk;
+
+  /** An object defining the algorithm-specific parameters for encrypting the `unwrappedKey`. */
+  encryptParams?: unknown
+}
+
+export interface KmsDeleteKeyParams {
+  /** Identifier for the key to be deleted in the KMS. */
+  keyUri: KeyIdentifier;
+}

package/src/prototyping/crypto/utils.ts

@@ -0,0 +1,41 @@
+import type { Cipher, KeyWrapper } from '@enbox/crypto';
+
+import type { KeyExporter, KeyImporter } from './types/key-io.js';
+
+export function isCipher<EncryptInput, DecryptInput>(
+  obj: unknown
+): obj is Cipher<EncryptInput, DecryptInput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'encrypt' in obj && typeof obj.encrypt === 'function'
+    && 'decrypt' in obj && typeof obj.decrypt === 'function'
+  );
+}
+
+export function isKeyExporter<ExportKeyInput, ExportKeyOutput>(
+  obj: unknown
+): obj is KeyExporter<ExportKeyInput, ExportKeyOutput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'exportKey' in obj && typeof obj.exportKey === 'function'
+  );
+}
+
+export function isKeyImporter<ImportKeyInput, ImportKeyExport>(
+  obj: unknown
+): obj is KeyImporter<ImportKeyInput, ImportKeyExport> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'importKey' in obj && typeof obj.importKey === 'function'
+  );
+}
+
+export function isKeyWrapper<WrapKeyInput, UnwrapKeyInput>(
+  obj: unknown
+): obj is KeyWrapper<WrapKeyInput, UnwrapKeyInput> {
+  return (
+    obj !== null && typeof obj === 'object'
+    && 'wrapKey' in obj && typeof obj.wrapKey === 'function'
+    && 'unwrapKey' in obj && typeof obj.unwrapKey === 'function'
+  );
+}

package/src/prototyping/dids/resolver-cache-memory.ts

@@ -0,0 +1,83 @@
+import type { DidResolverCache, DidResolutionResult } from '@enbox/dids';
+
+import ms from 'ms';
+import { TtlCache } from '@enbox/common';
+
+/**
+ * Configuration parameters for creating an in-memory cache for DID resolution results.
+ *
+ * Allows customization of the cache time-to-live (TTL) setting.
+ */
+export type DidResolverCacheMemoryParams = {
+  /**
+   * Optional. The time-to-live for cache entries, expressed as a string (e.g., '1h', '15m').
+   * Determines how long a cache entry should remain valid before being considered expired.
+   *
+   * Defaults to '15m' if not specified.
+   */
+  ttl?: string;
+}
+
+export class DidResolverCacheMemory implements DidResolverCache {
+  private cache: TtlCache<string, DidResolutionResult>;
+
+  constructor({ ttl = '15m' }: DidResolverCacheMemoryParams = {}) {
+    this.cache = new TtlCache({ ttl: ms(ttl) });
+  }
+
+  /**
+   * Retrieves a DID resolution result from the cache.
+   *
+   * If the cached item has exceeded its TTL, it's scheduled for deletion and undefined is returned.
+   *
+   * @param didUri - The DID string used as the key for retrieving the cached result.
+   * @returns The cached DID resolution result or undefined if not found or expired.
+   */
+  public async get(didUri: string): Promise<DidResolutionResult | void> {
+    if (!didUri) {
+      throw new Error('Key cannot be null or undefined');
+    }
+
+    return this.cache.get(didUri);
+  }
+
+  /**
+   * Stores a DID resolution result in the cache with a TTL.
+   *
+   * @param didUri - The DID string used as the key for storing the result.
+   * @param resolutionResult - The DID resolution result to be cached.
+   * @returns A promise that resolves when the operation is complete.
+   */
+  public async set(didUri: string, resolutionResult: DidResolutionResult): Promise<void> {
+    this.cache.set(didUri, resolutionResult);
+  }
+
+  /**
+   * Deletes a DID resolution result from the cache.
+   *
+   * @param didUri - The DID string used as the key for deletion.
+   * @returns A promise that resolves when the operation is complete.
+   */
+  public async delete(didUri: string): Promise<void> {
+    this.cache.delete(didUri);
+  }
+
+  /**
+   * Clears all entries from the cache.
+   *
+   * @returns A promise that resolves when the operation is complete.
+   */
+  public async clear(): Promise<void> {
+    this.cache.clear();
+  }
+
+  /**
+   * This method is a no-op but exists to be consistent with other DID Resolver Cache
+   * implementations.
+   *
+   * @returns A promise that resolves immediately.
+   */
+  public async close(): Promise<void> {
+    // No-op since there is no underlying store to close.
+  }
+}

package/src/prototyping/dids/utils.ts

@@ -0,0 +1,10 @@
+import type { PortableDid } from '@enbox/dids';
+
+export function isPortableDid(obj: unknown): obj is PortableDid {
+  // Validate that the given value is an object that has the necessary properties of PortableDid.
+  return !(!obj || typeof obj !== 'object' || obj === null)
+    && 'uri' in obj
+    && 'document' in obj
+    && 'metadata' in obj
+    && (!('keyManager' in obj) || obj.keyManager === undefined);
+}

package/src/rpc-client.ts

@@ -0,0 +1,162 @@
+import { CryptoUtils } from '@enbox/crypto';
+
+
+import type { DwnRpc, DwnRpcRequest, DwnRpcResponse } from './prototyping/clients/dwn-rpc-types.js';
+import type { DwnServerInfoRpc, ServerInfo } from './prototyping/clients/server-info-types.js';
+import type { JsonRpcResponse } from './prototyping/clients/json-rpc.js';
+
+import { createJsonRpcRequest } from './prototyping/clients/json-rpc.js';
+import { HttpDwnRpcClient } from './prototyping/clients/http-dwn-rpc-client.js';
+import { WebSocketDwnRpcClient } from './prototyping/clients/web-socket-clients.js';
+
+/**
+ * Interface that can be implemented to communicate with {@link Web5Agent | Web5 Agent}
+ * implementations via JSON-RPC.
+ */
+export interface DidRpc {
+  get transportProtocols(): string[]
+  sendDidRequest(request: DidRpcRequest): Promise<DidRpcResponse>
+}
+
+export enum DidRpcMethod {
+  Create = 'did.create',
+  Resolve = 'did.resolve'
+}
+
+export type DidRpcRequest = {
+  data: string;
+  method: DidRpcMethod;
+  url: string;
+}
+
+export type DidRpcResponse = {
+  data?: string;
+  ok: boolean;
+  status: RpcStatus;
+}
+
+export type RpcStatus = {
+  code: number;
+  message: string;
+};
+
+export interface Web5Rpc extends DwnRpc, DidRpc, DwnServerInfoRpc {}
+
+/**
+ * Client used to communicate with Dwn Servers
+ */
+export class Web5RpcClient implements Web5Rpc {
+  private transportClients: Map<string, Web5Rpc>;
+
+  constructor(clients: Web5Rpc[] = []) {
+    this.transportClients = new Map();
+
+    // include http and socket clients as default.
+    // can be overwritten for 'http:', 'https:', 'ws: or ':wss' if instantiated with other clients.
+    clients = [new HttpWeb5RpcClient(), new WebSocketWeb5RpcClient(), ...clients];
+
+    for (let client of clients) {
+      for (let transportScheme of client.transportProtocols) {
+        this.transportClients.set(transportScheme, client);
+      }
+    }
+  }
+
+  get transportProtocols(): string[] {
+    return Array.from(this.transportClients.keys());
+  }
+
+  async sendDidRequest(request: DidRpcRequest): Promise<DidRpcResponse> {
+    // URL() will throw if provided `url` is invalid.
+    const url = new URL(request.url);
+
+    const transportClient = this.transportClients.get(url.protocol);
+    if (!transportClient) {
+      const error = new Error(`no ${url.protocol} transport client available`);
+      error.name = 'NO_TRANSPORT_CLIENT';
+
+      throw error;
+    }
+
+    return transportClient.sendDidRequest(request);
+  }
+
+  sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse> {
+    // will throw if url is invalid
+    const url = new URL(request.dwnUrl);
+
+    const transportClient = this.transportClients.get(url.protocol);
+    if (!transportClient) {
+      const error = new Error(`no ${url.protocol} transport client available`);
+      error.name = 'NO_TRANSPORT_CLIENT';
+
+      throw error;
+    }
+
+    return transportClient.sendDwnRequest(request);
+  }
+
+  async getServerInfo(dwnUrl: string): Promise<ServerInfo> {
+    // will throw if url is invalid
+    const url = new URL(dwnUrl);
+
+    const transportClient = this.transportClients.get(url.protocol);
+    if(!transportClient) {
+      const error = new Error(`no ${url.protocol} transport client available`);
+      error.name = 'NO_TRANSPORT_CLIENT';
+
+      throw error;
+    }
+
+    return transportClient.getServerInfo(dwnUrl);
+  }
+}
+
+export class HttpWeb5RpcClient extends HttpDwnRpcClient implements Web5Rpc {
+  async sendDidRequest(request: DidRpcRequest): Promise<DidRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const jsonRpcRequest = createJsonRpcRequest(requestId, request.method, {
+      data: request.data
+    });
+
+    const httpRequest = new Request(request.url, {
+      method  : 'POST',
+      headers : {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(jsonRpcRequest),
+    });
+
+    let jsonRpcResponse: JsonRpcResponse;
+
+    try {
+      const response = await fetch(httpRequest);
+
+      if (response.ok) {
+        jsonRpcResponse = await response.json();
+
+        // If the response is an error, throw an error.
+        if (jsonRpcResponse.error) {
+          const { code, message } = jsonRpcResponse.error;
+          throw new Error(`JSON RPC (${code}) - ${message}`);
+        }
+      } else {
+        throw new Error(`HTTP (${response.status}) - ${response.statusText}`);
+      }
+    } catch (error: any) {
+      throw new Error(`Error encountered while processing response from ${request.url}: ${error.message}`);
+    }
+
+    return jsonRpcResponse.result as DidRpcResponse;
+  }
+}
+
+export class WebSocketWeb5RpcClient extends WebSocketDwnRpcClient implements Web5Rpc {
+  async sendDidRequest(_request: DidRpcRequest): Promise<DidRpcResponse> {
+    throw new Error(`not implemented for transports [${this.transportProtocols.join(', ')}]`);
+  }
+
+  async getServerInfo(_dwnUrl: string): Promise<ServerInfo> {
+    throw new Error(`not implemented for transports [${this.transportProtocols.join(', ')}]`);
+  }
+}

package/src/store-data-protocols.ts

@@ -0,0 +1,40 @@
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+export const IdentityProtocolDefinition: ProtocolDefinition = {
+  protocol  : 'http://identity.foundation/protocols/web5/identity-store',
+  published : false,
+  types     : {
+    portableDid: {
+      schema      : 'https://identity.foundation/schemas/web5/portable-did',
+      dataFormats : [
+        'application/json'
+      ]
+    },
+    identityMetadata: {
+      schema      : 'https://identity.foundation/schemas/web5/identity-metadata',
+      dataFormats : [
+        'application/json'
+      ]
+    }
+  },
+  structure: {
+    portableDid      : {},
+    identityMetadata : {}
+  }
+};
+
+export const JwkProtocolDefinition: ProtocolDefinition = {
+  protocol  : 'http://identity.foundation/protocols/web5/jwk-store',
+  published : false,
+  types     : {
+    privateJwk: {
+      schema      : 'https://identity.foundation/schemas/web5/private-jwk',
+      dataFormats : [
+        'application/json'
+      ]
+    },
+  },
+  structure: {
+    privateJwk: {}
+  }
+};