@enbox/agent 0.0.1

package/src/dwn-api.ts

@@ -0,0 +1,462 @@
+import type { Readable } from '@enbox/common';
+
+import {
+  Cid,
+  DataStoreLevel,
+  Dwn,
+  DwnConfig,
+  DwnInterfaceName,
+  DwnMethodName,
+  EventEmitterStream,
+  EventLogLevel,
+  GenericMessage,
+  Message,
+  MessageStoreLevel,
+  ResumableTaskStoreLevel
+} from '@enbox/dwn-sdk-js';
+
+import { NodeStream } from '@enbox/common';
+import { CryptoUtils } from '@enbox/crypto';
+import { DidDht, DidJwk, DidResolverCacheLevel, UniversalResolver } from '@enbox/dids';
+
+import type { Web5PlatformAgent } from './types/agent.js';
+import type {
+  DwnMessage,
+  DwnMessageInstance,
+  DwnMessageParams,
+  DwnMessageReply,
+  DwnMessagesPermissionScope,
+  DwnMessageWithData,
+  DwnPermissionScope,
+  DwnRecordsInterfaces,
+  DwnRecordsPermissionScope,
+  DwnResponse,
+  DwnSigner,
+  MessageHandler,
+  ProcessDwnRequest,
+  SendDwnRequest
+} from './types/dwn.js';
+
+import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
+import { blobToIsomorphicNodeReadable, getDwnServiceEndpointUrls, isRecordsWrite, webReadableToIsomorphicNodeReadable } from './utils.js';
+
+export type DwnMessageWithBlob<T extends DwnInterface> = {
+  message: DwnMessage[T];
+  data?: Blob;
+}
+
+export type DwnApiParams = {
+  agent?: Web5PlatformAgent;
+  dwn: Dwn;
+}
+
+export interface DwnApiCreateDwnParams extends Partial<DwnConfig> {
+  dataPath?: string;
+}
+
+export function isDwnRequest<T extends DwnInterface>(
+  dwnRequest: ProcessDwnRequest<DwnInterface>, messageType: T
+): dwnRequest is ProcessDwnRequest<T> {
+  return dwnRequest.messageType === messageType;
+}
+
+export function isDwnMessage<T extends DwnInterface>(
+  messageType: T, message: GenericMessage
+): message is DwnMessage[T] {
+  const incomingMessageInterfaceName = message.descriptor.interface + message.descriptor.method;
+  return incomingMessageInterfaceName === messageType;
+}
+
+export function isRecordsType(messageType: DwnInterface): messageType is DwnRecordsInterfaces {
+  return messageType === DwnInterface.RecordsDelete ||
+    messageType === DwnInterface.RecordsQuery ||
+    messageType === DwnInterface.RecordsRead ||
+    messageType === DwnInterface.RecordsSubscribe ||
+    messageType === DwnInterface.RecordsWrite;
+}
+
+export function isRecordPermissionScope(scope: DwnPermissionScope): scope is DwnRecordsPermissionScope {
+  return scope.interface === DwnInterfaceName.Records;
+}
+
+export function isMessagesPermissionScope(scope: DwnPermissionScope): scope is DwnMessagesPermissionScope {
+  return scope.interface === DwnInterfaceName.Messages;
+}
+
+export class AgentDwnApi {
+  /**
+   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
+   * the `AgentDwnApi`. This agent is used to interact with other Web5 agent components. It's vital
+   * to ensure this instance is set to correctly contextualize operations within the broader Web5
+   * Agent framework.
+   */
+  private _agent?: Web5PlatformAgent;
+
+  /**
+   * The DWN instance to use for this API.
+   */
+  private _dwn: Dwn;
+
+  constructor({ agent, dwn }: DwnApiParams) {
+    // If an agent is provided, set it as the execution context for this API.
+    this._agent = agent;
+
+    // Set the DWN instance for this API.
+    this._dwn = dwn;
+  }
+
+  /**
+   * Retrieves the `Web5PlatformAgent` execution context.
+   *
+   * @returns The `Web5PlatformAgent` instance that represents the current execution context.
+   * @throws Will throw an error if the `agent` instance property is undefined.
+   */
+  get agent(): Web5PlatformAgent {
+    if (this._agent === undefined) {
+      throw new Error('AgentDwnApi: Unable to determine agent execution context.');
+    }
+
+    return this._agent;
+  }
+
+  set agent(agent: Web5PlatformAgent) {
+    this._agent = agent;
+  }
+
+  /**
+   * Public getter for the DWN instance used by this API.
+   *
+   * Notes:
+   * - This getter is public to allow advanced developers to access the DWN instance directly.
+   *   However, it is recommended to use the `processRequest` method to interact with the DWN
+   *   instance to ensure that the DWN message is constructed correctly.
+   * - The getter is named `node` to avoid confusion with the `dwn` property of the
+   *   `Web5PlatformAgent`. In other words, so that a developer can call `agent.dwn.node` to access
+   *   the DWN instance and not `agent.dwn.dwn`.
+   */
+  get node(): Dwn {
+    return this._dwn;
+  }
+
+  public static async createDwn({
+    dataPath, dataStore, didResolver, eventLog, eventStream, messageStore, tenantGate, resumableTaskStore
+  }: DwnApiCreateDwnParams): Promise<Dwn> {
+    dataStore ??= new DataStoreLevel({ blockstoreLocation: `${dataPath}/DWN_DATASTORE` });
+
+    didResolver ??= new UniversalResolver({
+      didResolvers : [DidDht, DidJwk],
+      cache        : new DidResolverCacheLevel({ location: `${dataPath}/DID_RESOLVERCACHE` }),
+    });
+
+    eventLog ??= new EventLogLevel({ location: `${dataPath}/DWN_EVENTLOG` });
+
+    messageStore ??= new MessageStoreLevel(({
+      blockstoreLocation : `${dataPath}/DWN_MESSAGESTORE`,
+      indexLocation      : `${dataPath}/DWN_MESSAGEINDEX`
+    }));
+
+    resumableTaskStore ??= new ResumableTaskStoreLevel({ location: `${dataPath}/DWN_RESUMABLETASKSTORE` });
+
+    eventStream ??= new EventEmitterStream();
+
+    return await Dwn.create({ dataStore, didResolver, eventLog, eventStream, messageStore, tenantGate, resumableTaskStore });
+  }
+
+  public async processRequest<T extends DwnInterface>(
+    request: ProcessDwnRequest<T>
+  ): Promise<DwnResponse<T>> {
+    // Constructs a DWN message. and if there is a data payload, transforms the data to a Node
+    // Readable stream.
+    const { message, dataStream } = await this.constructDwnMessage({ request });
+
+    // Extracts the optional subscription handler from the request to pass into `processMessage.
+    const { subscriptionHandler } = request;
+
+    // Conditionally processes the message with the DWN instance:
+    // - If `store` is not explicitly set to false, it sends the message to the DWN node for
+    //   processing, passing along the target DID, the message, and any associated data stream.
+    // - If `store` is set to false, it immediately returns a simulated 'accepted' status without
+    //   storing the message/data in the DWN node.
+    const reply: DwnMessageReply[T] = (request.store !== false)
+      ? await this._dwn.processMessage(request.target, message, { dataStream: dataStream as any, subscriptionHandler })
+      : { status: { code: 202, detail: 'Accepted' } };
+
+    // Returns an object containing the reply from processing the message, the original message,
+    // and the content identifier (CID) of the message.
+    return {
+      reply,
+      message,
+      messageCid: await Message.getCid(message),
+    };
+  }
+
+  public async sendRequest<T extends DwnInterface>(
+    request: SendDwnRequest<T>
+  ): Promise<DwnResponse<T>> {
+    // First, confirm the target DID can be dereferenced and extract the DWN service endpoint URLs.
+    const dwnEndpointUrls = await getDwnServiceEndpointUrls(request.target, this.agent.did);
+    if (dwnEndpointUrls.length === 0) {
+      throw new Error(`AgentDwnApi: DID Service is missing or malformed: ${request.target}#dwn`);
+    }
+
+    let messageCid: string | undefined;
+    let message: DwnMessage[T];
+    let data: Blob | undefined;
+    let subscriptionHandler: MessageHandler[T] | undefined;
+
+    // If `messageCid` is given, retrieve message and data, if any.
+    if ('messageCid' in request) {
+      ({ message, data } = await this.getDwnMessage({
+        author      : request.author,
+        messageCid  : request.messageCid,
+        messageType : request.messageType
+      }));
+      messageCid = request.messageCid;
+
+    } else {
+      // Otherwise, construct a new message.
+      ({ message } = await this.constructDwnMessage({ request }));
+      if (request.dataStream && !(request.dataStream instanceof Blob)) {
+        throw new Error('AgentDwnApi: DataStream must be provided as a Blob');
+      }
+      data = request.dataStream;
+      subscriptionHandler = request.subscriptionHandler;
+    }
+
+    // Send the RPC request to the target DID's DWN service endpoint using the Agent's RPC client.
+    const reply = await this.sendDwnRpcRequest({
+      targetDid: request.target,
+      dwnEndpointUrls,
+      message,
+      data,
+      subscriptionHandler
+    });
+
+    // If the message CID was not given in the `request`, compute it.
+    messageCid ??= await Message.getCid(message);
+
+    // Returns an object containing the reply from processing the message, the original message,
+    // and the content identifier (CID) of the message.
+    return { reply, message, messageCid };
+  }
+
+  private async sendDwnRpcRequest<T extends DwnInterface>({
+    targetDid, dwnEndpointUrls, message, data, subscriptionHandler
+  }: {
+      targetDid: string;
+      dwnEndpointUrls: string[];
+      message: DwnMessage[T];
+      data?: Blob;
+      subscriptionHandler?: MessageHandler[T];
+    }
+  ): Promise<DwnMessageReply[T]> {
+    const errorMessages: { url: string, message: string }[] = [];
+
+    if (message.descriptor.method === DwnMethodName.Subscribe && subscriptionHandler === undefined) {
+      throw new Error('AgentDwnApi: Subscription handler is required for subscription requests.');
+    }
+
+    // Try sending to author's publicly addressable DWNs until the first request succeeds.
+    for (let dwnUrl of dwnEndpointUrls) {
+      try {
+        if (subscriptionHandler !== undefined) {
+          // we get the server info to check if the server supports WebSocket for subscription requests
+          const serverInfo = await this.agent.rpc.getServerInfo(dwnUrl);
+          if (!serverInfo.webSocketSupport) {
+            // If the server does not support WebSocket, add an error message and continue to the next URL.
+            errorMessages.push({
+              url     : dwnUrl,
+              message : 'WebSocket support is not enabled on the server.'
+            });
+            continue;
+          }
+
+          // If the server supports WebSocket, replace the subscription URL with a socket transport.
+          // For `http` we use the unsecured `ws` protocol, and for `https` we use the secured `wss` protocol.
+          const parsedUrl = new URL(dwnUrl);
+          parsedUrl.protocol = parsedUrl.protocol === 'http:' ? 'ws:' : 'wss:';
+          dwnUrl = parsedUrl.toString();
+        }
+
+        const dwnReply = await this.agent.rpc.sendDwnRequest({
+          dwnUrl,
+          targetDid,
+          message,
+          data,
+          subscriptionHandler
+        });
+
+        return dwnReply;
+      } catch(error: any) {
+        errorMessages.push({
+          url     : dwnUrl,
+          message : (error instanceof Error) ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    throw new Error(`Failed to send DWN RPC request: ${JSON.stringify(errorMessages)}`);
+  }
+
+  private async constructDwnMessage<T extends DwnInterface>({ request }: {
+    request: ProcessDwnRequest<T>
+  }): Promise<DwnMessageWithData<T>> {
+    // if the request has a granteeDid, ensure the messageParams include the proper grant parameters
+    if (request.granteeDid && !this.hasGrantParams(request.messageParams)) {
+      throw new Error('AgentDwnApi: Requested to sign with a permission but no grant messageParams were provided in the request');
+    }
+
+    const rawMessage = request.rawMessage;
+    let readableStream: Readable | undefined;
+    // TODO: Consider refactoring to move data transformations imposed by fetch() limitations to the HTTP transport-related methods.
+    // if the request is a RecordsWrite message, we need to handle the data stream and update the messageParams accordingly
+    if (isDwnRequest(request, DwnInterface.RecordsWrite)) {
+      const messageParams = request.messageParams;
+
+      if (request.dataStream && !messageParams?.data) {
+        const { dataStream } = request;
+        let isomorphicNodeReadable: Readable;
+
+        if (dataStream instanceof Blob) {
+          isomorphicNodeReadable = blobToIsomorphicNodeReadable(dataStream);
+          readableStream = blobToIsomorphicNodeReadable(dataStream);
+
+        } else if (dataStream instanceof ReadableStream) {
+          const [ forCid, forProcessMessage ] = dataStream.tee();
+          isomorphicNodeReadable = webReadableToIsomorphicNodeReadable(forCid);
+          readableStream = webReadableToIsomorphicNodeReadable(forProcessMessage);
+        }
+
+        if (!rawMessage) {
+          // @ts-ignore
+          messageParams.dataCid = await Cid.computeDagPbCidFromStream(isomorphicNodeReadable);
+          // @ts-ignore
+          messageParams.dataSize ??= isomorphicNodeReadable['bytesRead'];
+        }
+      }
+    }
+
+    let dwnMessage: DwnMessageInstance[T];
+    const dwnMessageConstructor = dwnMessageConstructors[request.messageType];
+
+    // if there is no raw message provided, we need to create the dwn message
+    if (!rawMessage) {
+
+      // If we need to sign as an author delegate or with permissions we need to get the grantee's signer
+      // The messageParams should include either a permissionGrantId, or a delegatedGrant message
+      const signer = request.granteeDid ?
+        await this.getSigner(request.granteeDid) :
+        await this.getSigner(request.author);
+
+      dwnMessage = await dwnMessageConstructor.create({
+        // TODO: Implement alternative to type assertion.
+        ...request.messageParams!,
+        signer
+      });
+
+    } else {
+      dwnMessage = await dwnMessageConstructor.parse(rawMessage);
+      if (isRecordsWrite(dwnMessage) && request.signAsOwner) {
+        // if we are signing as owner, we use the author's signer
+        const signer = await this.getSigner(request.author);
+        await dwnMessage.signAsOwner(signer);
+      } else if (request.granteeDid && isRecordsWrite(dwnMessage) && request.signAsOwnerDelegate) {
+        // if we are signing as owner delegate, we use the grantee's signer and the provided delegated grant
+        const signer = await this.getSigner(request.granteeDid);
+
+        //if we have reached here, the presence of the grant params has already been checked
+        const messageParams = request.messageParams as DwnMessageParams[DwnInterface.RecordsWrite];
+        await dwnMessage.signAsOwnerDelegate(signer, messageParams.delegatedGrant!);
+      }
+    }
+
+    return { message: dwnMessage.message as DwnMessage[T], dataStream: readableStream };
+  }
+
+  private hasGrantParams<T extends DwnInterface>(params?: DwnMessageParams[T]): boolean {
+    return params !== undefined &&
+      (('permissionGrantId' in params && params.permissionGrantId !== undefined) ||
+      ('delegatedGrant' in params && params.delegatedGrant !== undefined));
+  }
+
+  private async getSigner(author: string): Promise<DwnSigner> {
+    // If the author is the Agent's DID, use the Agent's signer.
+    if (author === this.agent.agentDid.uri) {
+      const signer = await this.agent.agentDid.getSigner();
+
+      return {
+        algorithm : signer.algorithm,
+        keyId     : signer.keyId,
+        sign      : async (data: Uint8Array) => {
+          return await signer.sign({ data });
+        }
+      };
+
+    } else {
+      // Otherwise, use the author's DID to determine the signing method.
+      try {
+        const signingMethod = await this.agent.did.getSigningMethod({ didUri: author });
+
+        if (!signingMethod.publicKeyJwk) {
+          throw new Error(`Verification method '${signingMethod.id}' does not contain a public key in JWK format`);
+        }
+
+        // Compute the key URI of the verification method's public key.
+        const keyUri = await this.agent.keyManager.getKeyUri({ key: signingMethod.publicKeyJwk });
+
+        // Verify that the key is present in the key manager. If not, an error is thrown.
+        const publicKey = await this.agent.keyManager.getPublicKey({ keyUri });
+
+        // Bind the Agent's Key Manager to the signer.
+        const keyManager = this.agent.keyManager;
+
+        return {
+          algorithm : CryptoUtils.getJoseSignatureAlgorithmFromPublicKey(publicKey),
+          keyId     : signingMethod.id,
+          sign      : async (data: Uint8Array) => {
+            return await keyManager.sign({ data, keyUri: keyUri! });
+          }
+        };
+      } catch (error: any) {
+        throw new Error(`AgentDwnApi: Unable to get signer for author '${author}': ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * FURTHER REFACTORING NEEDED BELOW THIS LINE
+   */
+
+  private async getDwnMessage<T extends DwnInterface>({ author, messageCid }: {
+    author: string;
+    messageType: T;
+    messageCid: string;
+  }): Promise<DwnMessageWithBlob<T>> {
+    const signer = await this.getSigner(author);
+
+    // Construct a MessagesRead message to fetch the message.
+    const messagesRead = await dwnMessageConstructors[DwnInterface.MessagesRead].create({
+      messageCid: messageCid,
+      signer
+    });
+
+    const result = await this._dwn.processMessage(author, messagesRead.message);
+
+    if (result.status.code !== 200) {
+      throw new Error(`AgentDwnApi: Failed to read message, response status: ${result.status.code} - ${result.status.detail}`);
+    }
+
+    const messageEntry = result.entry!;
+    const message = messageEntry.message as DwnMessage[T];
+
+    let dwnMessageWithBlob: DwnMessageWithBlob<T> = { message };
+    // If the message is a RecordsWrite, data will be present in the form of a stream
+
+    if (isRecordsWrite(messageEntry) && messageEntry.data) {
+      const dataBytes = await NodeStream.consumeToBytes({ readable: messageEntry.data });
+      dwnMessageWithBlob.data = new Blob([ dataBytes ], { type: messageEntry.message.descriptor.dataFormat });
+    }
+
+    return dwnMessageWithBlob;
+  }
+}

package/src/dwn-registrar.ts

@@ -0,0 +1,127 @@
+import { Sha256, CryptoUtils } from '@enbox/crypto';
+import { concatenateUrl } from './utils.js';
+import { Convert } from '@enbox/common';
+
+/**
+ * A client for registering tenants with a DWN.
+ */
+export class DwnRegistrar {
+  /**
+   * Registers a new tenant with the given DWN.
+   * NOTE: Assumes the user has already accepted the terms of service.
+   * NOTE: Currently the DWN Server from `dwn-server` does not require user signature.
+   * TODO: bring in types from `dwn-server`.
+   */
+  public static async registerTenant(dwnEndpoint: string, did: string): Promise<void> {
+
+    const registrationEndpoint = concatenateUrl(dwnEndpoint, 'registration');
+    const termsOfUseEndpoint = concatenateUrl(registrationEndpoint, 'terms-of-service');
+    const proofOfWorkEndpoint = concatenateUrl(registrationEndpoint, 'proof-of-work');
+
+    // fetch the terms-of-service
+    const termsOfServiceGetResponse = await fetch(termsOfUseEndpoint, {
+      method: 'GET',
+    });
+
+    if (termsOfServiceGetResponse.status !== 200) {
+      const statusCode = termsOfServiceGetResponse.status;
+      const statusText = termsOfServiceGetResponse.statusText;
+      const errorText = await termsOfServiceGetResponse.text();
+      throw new Error(`Failed fetching terms-of-service: ${statusCode} ${statusText}: ${errorText}`);
+    }
+    const termsOfServiceFetched = await termsOfServiceGetResponse.text();
+
+    // fetch the proof-of-work challenge
+    const proofOfWorkChallengeGetResponse = await fetch(proofOfWorkEndpoint, {
+      method: 'GET',
+    });
+    const { challengeNonce, maximumAllowedHashValue} = await proofOfWorkChallengeGetResponse.json();
+
+    // create registration data based on the hash of the terms-of-service and the DID
+    const registrationData = {
+      did,
+      termsOfServiceHash: await DwnRegistrar.hashAsHexString(termsOfServiceFetched),
+    };
+
+    // compute the proof-of-work response nonce based on the the proof-of-work challenge and the registration data.
+    const responseNonce = await DwnRegistrar.findQualifiedResponseNonce({
+      challengeNonce,
+      maximumAllowedHashValue,
+      requestData: JSON.stringify(registrationData),
+    });
+
+    // send the registration request to the server
+    const registrationRequest = {
+      registrationData,
+      proofOfWork: {
+        challengeNonce,
+        responseNonce,
+      },
+    };
+
+    const registrationResponse = await fetch(registrationEndpoint, {
+      method  : 'POST',
+      headers : { 'Content-Type': 'application/json' },
+      body    : JSON.stringify(registrationRequest),
+    });
+
+    if (registrationResponse.status !== 200) {
+      const statusCode = registrationResponse.status;
+      const statusText = registrationResponse.statusText;
+      const errorText = await registrationResponse.text();
+      throw new Error(`Registration failed: ${statusCode} ${statusText}: ${errorText}`);
+    }
+  }
+
+  /**
+   * Computes the SHA-256 hash of the given array of strings.
+   */
+  public static async hashAsHexString(input: string): Promise<string> {
+    const hashAsBytes = await Sha256.digest({ data: Convert.string(input).toUint8Array()});
+    const hashAsHex = Convert.uint8Array(hashAsBytes).toHex();
+    return hashAsHex;
+  }
+
+  /**
+   * Finds a response nonce that qualifies the difficulty requirement for the given proof-of-work challenge and request data.
+   */
+  public static async findQualifiedResponseNonce(input: {
+    maximumAllowedHashValue: string;
+    challengeNonce: string;
+    requestData: string;
+  }): Promise<string> {
+    const startTime = Date.now();
+
+    const { maximumAllowedHashValue, challengeNonce, requestData } = input;
+    const maximumAllowedHashValueAsBigInt = BigInt(`0x${maximumAllowedHashValue}`);
+
+    let iterations = 1;
+    let responseNonce;
+    let qualifiedSolutionNonceFound = false;
+    do {
+      responseNonce = await this.generateNonce();
+      const computedHash = await DwnRegistrar.hashAsHexString(challengeNonce + responseNonce + requestData);
+      const computedHashAsBigInt = BigInt(`0x${computedHash}`);
+
+      qualifiedSolutionNonceFound = computedHashAsBigInt <= maximumAllowedHashValueAsBigInt;
+
+      iterations++;
+    } while (!qualifiedSolutionNonceFound);
+
+    // Log final/successful iteration.
+    console.log(
+      `iterations: ${iterations}, time lapsed: ${Date.now() - startTime} ms`,
+    );
+
+    return responseNonce;
+  }
+
+  /**
+   * Generates 32 random bytes expressed as a HEX string.
+   */
+  public static async generateNonce(): Promise<string> {
+    const randomBytes = CryptoUtils.randomBytes(32);
+    const hexString = Convert.uint8Array(randomBytes).toHex().toUpperCase();
+    return hexString;
+  }
+}