@enbox/agent 0.1.2 → 0.1.4

package/src/prototyping/crypto/types/key-manager.ts

@@ -1,83 +0,0 @@
-import type {
-  KeyIdentifier,
-  KmsDigestParams,
-  KmsGenerateKeyParams,
-  KmsGetKeyUriParams,
-  KmsGetPublicKeyParams,
-  KmsSignParams,
-  KmsVerifyParams,
-} from '@enbox/crypto';
-
-import type { DsaApi } from './crypto-api.js';
-import type { KmsCipherParams } from './params-kms.js';
-// import type { Web5PlatformAgent } from '../../../types/agent.js';
-
-export interface KeyManagerParams {
-  CipherInput?: unknown;
-  GenerateKeyInput?: unknown;
-  GenerateKeyOutput?: unknown;
-  GetPublicKeyInput?: unknown;
-  SignInput?: unknown;
-  VerifyInput?: unknown;
-}
-
-export interface DefaultKeyManagerParams {
-  CipherInput: KmsCipherParams;
-  GenerateKeyInput: KmsGenerateKeyParams;
-  GenerateKeyOutput: KeyIdentifier;
-  GetPublicKeyInput: KmsGetPublicKeyParams;
-  SignInput: KmsSignParams;
-  VerifyInput: KmsVerifyParams;
-}
-
-/**
- * The `KeyManager` interface integrates key generation and signing capabilities.
- *
- * Concrete implementations of this interface are intended to be used as a Key Management System
- * (KMS), which is responsible for generating and storing cryptographic keys. The KMS is also
- * responsible for performing cryptographic operations using the keys it manages. The KMS can be
- * a local software based KMS, a cloud service, or a hardware device.
- *
- * Guidelines for implementing this interface:
- * - Must use JSON Web Keys ({@link Jwk | JWK}) as the key format.
- * - Must IANA registered JSON Object Signing and Encryption
- *   {@ link https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms | (JOSE)}
- *   names for algorithm, curves, etc. whenever possible.
- * - All I/O that interacts with private or secret keys must be done via reference using a
- *   {@link KeyIdentifier | `KeyIdentifier`}. Implementations can use any string as the key
- *   identifier (e.g. JWK thumbprint, UUID generated by hosted KMS, etc.).
- * - Must support key generation an signing operations.
- * - May be extended to support other cryptographic operations.
- * - Implementations of the `CryptoApi` interface can be passed as an argument to the public API
- *   methods of Web5 libraries that involve key material (e.g., DID creation, VC signing, arbitrary
- *   data signing/verification, etc.).
- *
- * @example
- * ```ts
- * // Example of using the KeyManager interface with default types
- * class DefaultKeyManager implements KeyManager {} // Uses default types
- *
- * // Example of using the KeyManager interface with custom types
- * class CustomKeyManager implements KeyManager<{
- *   GenerateKeyInput: CustomGenerateKeyParams, // Custom type
- *   KmsGetPublicKeyParams: CustomGetPublicKeyParams, // Custom type
- *   KmsSignParams: CustomSignParams, // Custom type
- *   // Omitting KmsVerifyParams to use the default
- * }> {
- *   // Implementation here
- * }
- * ```
- *
- * @typeParam T - The type of the key manager parameters.
- */
-export interface KeyManager<T extends KeyManagerParams = DefaultKeyManagerParams>
-  extends DsaApi<T['GenerateKeyInput'], T['GenerateKeyOutput'], T['GetPublicKeyInput'], KmsDigestParams, T['SignInput'], T['VerifyInput']> {
-
-  /**
-   *
-   * @param params - The parameters for getting the key URI.
-   * @param params.key - The key to get the URI for.
-   * @returns The key URI.
-   */
-  getKeyUri(params: KmsGetKeyUriParams): Promise<KeyIdentifier>;
-}

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

@@ -1,95 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,83 +0,0 @@
-import type { DidResolutionResult, DidResolverCache } 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

@@ -1,10 +0,0 @@
-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

@@ -1,160 +0,0 @@
-import type { JsonRpcResponse } from './prototyping/clients/json-rpc.js';
-import type { DwnRpc, DwnRpcRequest, DwnRpcResponse } from './prototyping/clients/dwn-rpc-types.js';
-import type { DwnServerInfoRpc, ServerInfo } from './prototyping/clients/server-info-types.js';
-
-import { createJsonRpcRequest } from './prototyping/clients/json-rpc.js';
-import { CryptoUtils } from '@enbox/crypto';
-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 (const client of clients) {
-      for (const 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(', ')}]`);
-  }
-}