@enbox/agent 0.0.1

package/src/test-harness.ts

@@ -0,0 +1,330 @@
+import type { KeyValueStore } from '@enbox/common';
+import type { AbstractLevel } from 'abstract-level';
+
+import { Level } from 'level';
+import { LevelStore, MemoryStore } from '@enbox/common';
+import { DataStoreLevel, Dwn, EventEmitterStream, EventLogLevel, MessageStoreLevel, ResumableTaskStoreLevel } from '@enbox/dwn-sdk-js';
+import { DidDht, DidJwk, DidResolutionResult, DidResolverCache } from '@enbox/dids';
+
+import type { Web5PlatformAgent } from './types/agent.js';
+
+import { AgentDidApi } from './did-api.js';
+import { AgentDidResolverCache } from './agent-did-resolver-cache.js';
+import { AgentDwnApi } from './dwn-api.js';
+import { AgentSyncApi } from './sync-api.js';
+import { Web5RpcClient } from './rpc-client.js';
+import { AgentCryptoApi } from './crypto-api.js';
+import { AgentIdentityApi } from './identity-api.js';
+import { BearerIdentity } from './bearer-identity.js';
+import { HdIdentityVault } from './hd-identity-vault.js';
+import { LocalKeyManager } from './local-key-manager.js';
+import { SyncEngineLevel } from './sync-engine-level.js';
+import { DwnDidStore, InMemoryDidStore } from './store-did.js';
+import { DwnKeyStore, InMemoryKeyStore } from './store-key.js';
+import { DwnIdentityStore, InMemoryIdentityStore } from './store-identity.js';
+import { DidResolverCacheMemory } from './prototyping/dids/resolver-cache-memory.js';
+import { AgentPermissionsApi } from './permissions-api.js';
+
+type PlatformAgentTestHarnessParams = {
+  agent: Web5PlatformAgent<LocalKeyManager>
+
+  agentStores: 'dwn' | 'memory';
+  didResolverCache: DidResolverCache;
+  dwn: Dwn;
+  dwnDataStore: DataStoreLevel;
+  dwnEventLog: EventLogLevel;
+  dwnMessageStore: MessageStoreLevel;
+  dwnResumableTaskStore: ResumableTaskStoreLevel;
+  syncStore: AbstractLevel<string | Buffer | Uint8Array>;
+  vaultStore: KeyValueStore<string, string>;
+  dwnStores: {
+    keyStore: DwnKeyStore;
+    identityStore: DwnIdentityStore;
+    didStore: DwnDidStore;
+    clear: () => void;
+  }
+}
+
+export class PlatformAgentTestHarness {
+  public agent: Web5PlatformAgent<LocalKeyManager>;
+
+  public agentStores: 'dwn' | 'memory';
+  public didResolverCache: DidResolverCache;
+  public dwn: Dwn;
+  public dwnDataStore: DataStoreLevel;
+  public dwnEventLog: EventLogLevel;
+  public dwnMessageStore: MessageStoreLevel;
+  public dwnResumableTaskStore: ResumableTaskStoreLevel;
+  public syncStore: AbstractLevel<string | Buffer | Uint8Array>;
+  public vaultStore: KeyValueStore<string, string>;
+
+  /**
+   * Custom DWN Stores for `keyStore`, `identityStore` and `didStore`.
+   * This allows us to clear the store cache between tests
+   */
+  public dwnStores: {
+    keyStore: DwnKeyStore;
+    identityStore: DwnIdentityStore;
+    didStore: DwnDidStore;
+    /** clears the protocol initialization caches */
+    clear: () => void;
+  };
+
+  constructor(params: PlatformAgentTestHarnessParams) {
+    this.agent = params.agent;
+    this.agentStores = params.agentStores;
+    this.didResolverCache = params.didResolverCache;
+    this.dwn = params.dwn;
+    this.dwnDataStore = params.dwnDataStore;
+    this.dwnEventLog = params.dwnEventLog;
+    this.dwnMessageStore = params.dwnMessageStore;
+    this.syncStore = params.syncStore;
+    this.vaultStore = params.vaultStore;
+    this.dwnResumableTaskStore = params.dwnResumableTaskStore;
+    this.dwnStores = params.dwnStores;
+  }
+
+  public async clearStorage(): Promise<void> {
+    // first stop any ongoing sync operations
+    await this.agent.sync.stopSync();
+
+    // @ts-expect-error since normally this property shouldn't be set to undefined.
+    this.agent.agentDid = undefined;
+    await this.didResolverCache.clear();
+    await this.dwnDataStore.clear();
+    await this.dwnEventLog.clear();
+    await this.dwnMessageStore.clear();
+    await this.dwnResumableTaskStore.clear();
+    await this.syncStore.clear();
+    await this.vaultStore.clear();
+    await this.agent.permissions.clear();
+    this.dwnStores.clear();
+
+    // Reset the indexes and caches for the Agent's DWN data stores.
+    // if (this.agentStores === 'dwn') {
+    //   const { didApi, identityApi } = PlatformAgentTestHarness.useDiskStores({ testDataLocation: '__TESTDATA__', agent: this.agent });
+    //   this.agent.crypto = cryptoApi;
+    //   this.agent.did = didApi;
+    //   this.agent.identity = identityApi;
+    // }
+
+    // Easiest way to start with fresh in-memory stores is to re-instantiate Agent components.
+    if (this.agentStores === 'memory') {
+      const { didApi, identityApi, permissionsApi, keyManager } = PlatformAgentTestHarness.useMemoryStores({ agent: this.agent });
+      this.agent.did = didApi;
+      this.agent.identity = identityApi;
+      this.agent.keyManager = keyManager;
+      this.agent.permissions = permissionsApi;
+    }
+  }
+
+  public async closeStorage(): Promise<void> {
+    await this.didResolverCache.close();
+    await this.dwnDataStore.close();
+    await this.dwnEventLog.close();
+    await this.dwnMessageStore.close();
+    await this.dwnResumableTaskStore.close();
+    await this.syncStore.close();
+    await this.vaultStore.close();
+  }
+
+  public async createAgentDid(): Promise<void> {
+    // Create a DID for the Agent.
+    this.agent.agentDid = await DidJwk.create({
+      options: { algorithm: 'Ed25519' }
+    });
+  }
+
+  public async createIdentity({ name, testDwnUrls }: {
+    name: string;
+    testDwnUrls: string[];
+  }): Promise<BearerIdentity> {
+    const bearerIdentity = await this.agent.identity.create({
+      didMethod  : 'dht',
+      didOptions : {
+        services: [
+          {
+            id              : 'dwn',
+            type            : 'DecentralizedWebNode',
+            serviceEndpoint : testDwnUrls,
+            enc             : '#enc',
+            sig             : '#sig',
+          }
+        ],
+        verificationMethods: [
+          {
+            algorithm : 'Ed25519',
+            id        : 'sig',
+            purposes  : ['assertionMethod', 'authentication']
+          },
+          {
+            algorithm : 'secp256k1',
+            id        : 'enc',
+            purposes  : ['keyAgreement']
+          }
+        ]
+      },
+      metadata: { name }
+    });
+
+    return bearerIdentity;
+  }
+
+  public static async setup({ agentClass, agentStores, testDataLocation }: {
+      agentClass: new (params: any) => Web5PlatformAgent<LocalKeyManager>
+      agentStores?: 'dwn' | 'memory';
+      testDataLocation?: string;
+    }): Promise<PlatformAgentTestHarness> {
+    agentStores ??= 'memory';
+    testDataLocation ??= '__TESTDATA__';
+
+    const testDataPath = (path: string) => `${testDataLocation}/${path}`;
+
+    // Instantiate Agent's Crypto API.
+    const cryptoApi = new AgentCryptoApi();
+
+    // Instantiate Agent's RPC Client.
+    const rpcClient = new Web5RpcClient();
+
+    const dwnStores = {
+      keyStore      : new DwnKeyStore(),
+      identityStore : new DwnIdentityStore(),
+      didStore      : new DwnDidStore(),
+      clear         : ():void => {
+        dwnStores.keyStore['_protocolInitializedCache']?.clear();
+        dwnStores.identityStore['_protocolInitializedCache']?.clear();
+        dwnStores.didStore['_protocolInitializedCache']?.clear();
+      }
+    };
+
+    const {
+      agentVault,
+      didApi,
+      identityApi,
+      keyManager,
+      didResolverCache,
+      vaultStore,
+      permissionsApi
+    } = (agentStores === 'memory')
+      ? PlatformAgentTestHarness.useMemoryStores()
+      : PlatformAgentTestHarness.useDiskStores({ testDataLocation, stores: dwnStores });
+
+    // Instantiate custom stores to use with DWN instance.
+    // Note: There is no in-memory store for DWN, so we always use LevelDB-based disk stores.
+    const dwnDataStore = new DataStoreLevel({ blockstoreLocation: testDataPath('DWN_DATASTORE') });
+    const dwnEventLog = new EventLogLevel({ location: testDataPath('DWN_EVENTLOG') });
+    const dwnEventStream = new EventEmitterStream();
+    const dwnResumableTaskStore = new ResumableTaskStoreLevel({ location: testDataPath('DWN_RESUMABLETASKSTORE') });
+
+    const dwnMessageStore = new MessageStoreLevel({
+      blockstoreLocation : testDataPath('DWN_MESSAGESTORE'),
+      indexLocation      : testDataPath('DWN_MESSAGEINDEX')
+    });
+
+    // Instantiate DWN instance using the custom stores.
+    const dwn = await AgentDwnApi.createDwn({
+      dataPath           : testDataLocation,
+      dataStore          : dwnDataStore,
+      didResolver        : didApi,
+      eventLog           : dwnEventLog,
+      eventStream        : dwnEventStream,
+      messageStore       : dwnMessageStore,
+      resumableTaskStore : dwnResumableTaskStore
+    });
+
+    // Instantiate Agent's DWN API using the custom DWN instance.
+    const dwnApi = new AgentDwnApi({ dwn });
+
+    // Instantiate Agent's Sync API using a custom LevelDB-backed store.
+    const syncStore = new Level(testDataPath('SYNC_STORE'));
+    const syncEngine = new SyncEngineLevel({ db: syncStore });
+    const syncApi = new AgentSyncApi({ syncEngine });
+
+    // Create Web5PlatformAgent instance
+    const agent = new agentClass({
+      agentVault,
+      cryptoApi,
+      didApi,
+      dwnApi,
+      identityApi,
+      keyManager,
+      permissionsApi,
+      rpcClient,
+      syncApi,
+    });
+
+    return new PlatformAgentTestHarness({
+      agent,
+      agentStores,
+      didResolverCache,
+      dwn,
+      dwnDataStore,
+      dwnEventLog,
+      dwnMessageStore,
+      dwnResumableTaskStore,
+      dwnStores,
+      syncStore,
+      vaultStore
+    });
+  }
+
+  private static useDiskStores({ agent, testDataLocation, stores }: {
+    agent?: Web5PlatformAgent;
+    stores: {
+      keyStore: DwnKeyStore;
+      identityStore: DwnIdentityStore;
+      didStore: DwnDidStore;
+    }
+    testDataLocation: string;
+  }) {
+    const testDataPath = (path: string) => `${testDataLocation}/${path}`;
+
+    const vaultStore = new LevelStore<string, string>({ location: testDataPath('VAULT_STORE') });
+    const agentVault = new HdIdentityVault({ keyDerivationWorkFactor: 1, store: vaultStore });
+
+    const { didStore, identityStore, keyStore } = stores;
+
+    // Setup DID Resolver Cache
+    const didResolverCache = new AgentDidResolverCache({
+      location: testDataPath('DID_RESOLVERCACHE')
+    });
+
+    const didApi = new AgentDidApi({
+      agent         : agent,
+      didMethods    : [DidDht, DidJwk],
+      resolverCache : didResolverCache,
+      store         : didStore
+    });
+
+    const identityApi = new AgentIdentityApi({ agent, store: identityStore });
+
+    const keyManager = new LocalKeyManager({ agent, keyStore: keyStore });
+
+    const permissionsApi = new AgentPermissionsApi({ agent });
+
+    return { agentVault, didApi, didResolverCache, identityApi, keyManager, permissionsApi, vaultStore };
+  }
+
+  private static useMemoryStores({ agent }: { agent?: Web5PlatformAgent<LocalKeyManager> } = {}) {
+    const vaultStore = new MemoryStore<string, string>();
+    const agentVault = new HdIdentityVault({ keyDerivationWorkFactor: 1, store: vaultStore });
+
+    // Setup DID Resolver Cache
+    const didResolverCache = new DidResolverCacheMemory();
+
+    const didApi = new AgentDidApi({
+      agent         : agent,
+      didMethods    : [DidDht, DidJwk],
+      resolverCache : didResolverCache,
+      store         : new InMemoryDidStore()
+    });
+
+    const keyManager = new LocalKeyManager({ agent, keyStore: new InMemoryKeyStore() });
+
+    const identityApi = new AgentIdentityApi<LocalKeyManager>({ agent, store: new InMemoryIdentityStore() });
+
+    const permissionsApi = new AgentPermissionsApi({ agent });
+
+    return { agentVault, didApi, didResolverCache, identityApi, keyManager, permissionsApi, vaultStore };
+  }
+}

package/src/types/agent.ts

@@ -0,0 +1,195 @@
+import type { BearerDid } from '@enbox/dids';
+
+import type { Web5Rpc } from '../rpc-client.js';
+import type { AgentDwnApi } from '../dwn-api.js';
+import type { AgentSyncApi } from '../sync-api.js';
+import type { AgentCryptoApi } from '../crypto-api.js';
+import type { AgentKeyManager } from './key-manager.js';
+import type { IdentityVault } from './identity-vault.js';
+import type { AgentIdentityApi } from '../identity-api.js';
+import type { AgentPermissionsApi } from '../permissions-api.js';
+import type { ProcessVcRequest, SendVcRequest, VcResponse } from './vc.js';
+import type { AgentDidApi, DidInterface, DidRequest, DidResponse } from '../did-api.js';
+import type { DwnInterface, DwnResponse, ProcessDwnRequest, SendDwnRequest } from './dwn.js';
+
+
+/**
+ * Defines the structure for response status in the context of an Agent's interaction within the
+ * Web5 framework.
+ *
+ * This type is utilized to convey the success or failure of an operation performed by the Agent,
+ * providing feedback that can be programmatically interpreted and acted upon.
+ *
+ * This standardized response structure ensures a consistent interface for handling operation
+ * outcomes, enabling clear communication of success or error states along with actionable insights
+ * when necessary.
+ */
+export type ResponseStatus = {
+  /**
+   * A boolean value indicating the overall success (`true`) or failure (`false`) of the operation.
+   * - `true`: Indicates that the operation was successful without errors.
+   * - `false`: Indicates that the operation failed, with the error details provided in the `status`
+   *            object.
+   */
+  ok: boolean;
+
+  status: {
+    /**
+     * A numerical code representing the specific outcome of the operation.
+     *
+     * This can be aligned with standard HTTP status codes for web-based operations or custom codes
+     * for specific business logic.
+     */
+    code: number;
+
+    /**
+     * A descriptive message corresponding to the status code that provides additional information
+     * about the operation's result.
+     *
+     * This message is particularly useful for logging, debugging, or displaying contextual messages
+     * to the end-user, offering insights into why an operation succeeded or failed.
+     */
+    message: string;
+  };
+};
+
+/**
+ * Defines the interface for a Web5 Agent, encapsulating the core functionality all implementations
+ * must include.
+ *
+ * The Agent is responsible for handling decentralized identifier (DID) requests, decentralized web
+ * node (DWN) requests, and verifiable credential (VC) requests.
+ *
+ * The `AgentDid` property represents the Web5 Agent's own DID, while the various process and send
+ * methods enable the Agent to handle and initiate requests pertaining to DIDs, DWNs, and VCs.
+ */
+export interface Web5Agent {
+  /**
+   * The Decentralized Identifier (DID) of this Web5 Agent.
+   */
+  agentDid: BearerDid;
+
+  /**
+   * Processes a DID request, handling it internally within the agent and returning a DID response,
+   * typically involving operations like DID creation or resolution.
+   */
+  processDidRequest<T extends DidInterface>(request: DidRequest<T>): Promise<DidResponse<T>>
+
+  /**
+   * Sends a DID request to another entity or service, expecting a DID response, often used for
+   * interactions involving DIDs occurring over a network or between different agents.
+   */
+  sendDidRequest<T extends DidInterface>(request: DidRequest<T>): Promise<DidResponse<T>>;
+
+  /**
+   * Processes a request related to a Decentralized Web Node (DWN) and returns a corresponding
+   * response.
+   */
+  processDwnRequest<T extends DwnInterface>(request: ProcessDwnRequest<T>): Promise<DwnResponse<T>>
+
+  /**
+   * Sends a request to a Decentralized Web Node (DWN) and awaits a response, often used for
+   * interactions involving DWNs occurring over a network or between different agents.
+   */
+  sendDwnRequest<T extends DwnInterface>(request: SendDwnRequest<T>): Promise<DwnResponse<T>>;
+
+  /**
+   * Processes a request for handling Verifiable Credentials (VCs), such as issuing or verifying
+   * them, and returns a response indicating the outcome.
+   */
+  processVcRequest(request: ProcessVcRequest): Promise<VcResponse>
+
+  /**
+   * Sends a request to issue, verify, or manage Verifiable Credentials (VCs), expecting a response
+   * that indicates the result of the operation. This method is often used for interactions
+   * involving VCs occurring over a network or between different agents.
+   */
+  sendVcRequest(request: SendVcRequest): Promise<VcResponse>;
+}
+
+/**
+ * Represents a Web5 Platform Agent, an extended and more feature-rich implementation of a
+ * {@link Web5Agent}.
+ *
+ * This Agent integrates a comprehensive set of APIs and functionalities, including cryptographic
+ * operations, DID management, DWN interaction, identity handling, and data synchronization.
+ *
+ * The platform agent provides a higher-level abstraction over the core Web5Agent functionalities,
+ * facilitating a robust platform for developing Web5 applications. It includes lifecycle management
+ * methods like initialization and startup, alongside a suite of specialized APIs and utilities.
+ *
+ * @typeParam TKeyManager - The type of Key Manager used to manage cryptographic keys.
+ */
+export interface Web5PlatformAgent<TKeyManager extends AgentKeyManager = AgentKeyManager> extends Web5Agent {
+  /**
+   * The cryptography API, essential for performing various cryptographic operations such
+   * as encryption, decryption, signing, and verification, ensuring secure data handling and
+   * communication within the Web5 Platform.
+   */
+  crypto: AgentCryptoApi;
+
+  /**
+   * The DID API, responsible for managing all DID-related functionalities, enabling the agent to
+   * create, resolve, update, and manage DIDs.
+   */
+  did: AgentDidApi<TKeyManager>;
+
+  /**
+   * The DWN API, enabling the Agent to interact with Decentralized Web Nodes (DWNs) and handle
+   * requests from Web5 applications.
+   */
+  dwn: AgentDwnApi;
+
+  /**
+   * The identity management API, handling identity-related operations and allowing the agent to
+   * manage Web5 identities, supporting operations like identity creation and update.
+   */
+  identity: AgentIdentityApi<TKeyManager>;
+
+  /**
+   * The Key Manager instance, central to the agent's cryptographic operations, managing key
+   * generation, storage, retrieval, and usage, ensuring secure cryptographic practices.
+   */
+  keyManager: TKeyManager;
+
+  /**
+   * The Permissions API, handling permission operations such as request, create, revocation, fetching and verifying revocation status.
+   */
+  permissions: AgentPermissionsApi;
+
+  /**
+   * The RPC (Remote Procedure Call) client interface, facilitating communication with other Web5
+   * Agents and services.
+   */
+  rpc: Web5Rpc;
+
+  /**
+   * The synchronization API, responsible for managing the consistency and real-time update of the
+   * agent's data with the state of the distributed network.
+   */
+  sync: AgentSyncApi;
+
+  /**
+   * An instance of {@link IdentityVault}, providing secure storage and management of a Web5 Agent's
+   * DID and cryptographic keys.
+   */
+  vault: IdentityVault;
+
+  /**
+   * Determines if it's the first time the Agent is being launched, typically used for initialization
+   * checks or first-time setup routines.
+   */
+  firstLaunch(): Promise<boolean>;
+
+  /**
+   * Initializes the agent with essential parameters (e.g., a passphrase) and prepares it for
+   * processing Web5 requests.
+   */
+  initialize(params: unknown): Promise<unknown>;
+
+  /**
+   * Starts the agent with the provided parameters, typically following initialization, to begin
+   * normal operation and readiness to process requests.
+   */
+  start(params: unknown): Promise<unknown>;
+}