@enbox/agent 0.0.1

package/src/utils-internal.ts

@@ -0,0 +1,157 @@
+import type { Jwk, KeyIdentifier, KmsExportKeyParams, KmsGetPublicKeyParams, KmsSignParams } from '@enbox/crypto';
+
+import { Ed25519, LocalKeyManager, computeJwkThumbprint } from '@enbox/crypto';
+
+import type { Web5PlatformAgent } from './types/agent.js';
+
+/**
+ * Internal utility functions used by the Web5 platform agent that are not intended for public use
+ * and are not exported in the public API.
+ */
+
+/**
+ * Separator used to join the tenant DID and the DID URI that is used to prefix all lookups in the
+ * Agent data stores, including the DWN-backed store's index and the in-memory store's map.
+ */
+export const TENANT_SEPARATOR = '^';
+
+export class DeterministicKeyGenerator extends LocalKeyManager {
+  private _predefinedKeys: Map<KeyIdentifier, Jwk>;
+  private _keyGenerator: IterableIterator<KeyIdentifier>;
+
+  constructor() {
+    super();
+    this._predefinedKeys = new Map();
+    this._keyGenerator = this._predefinedKeys.keys();
+  }
+
+  public async addPredefinedKeys({ privateKeys }: { privateKeys: Jwk[] }): Promise<void> {
+    const predefinedKeys: { [keyUri: KeyIdentifier]: Jwk } = {};
+
+    for (const key of privateKeys) {
+      // If the key ID is undefined, set it to the JWK thumbprint.
+      key.kid ??= await computeJwkThumbprint({ jwk: key });
+
+      // Compute the key URI for the key.
+      const keyUri = await this.getKeyUri({ key });
+
+      // Store the key.
+      predefinedKeys[keyUri] = key;
+    }
+
+    // Store the keys.
+    this._predefinedKeys = new Map(Object.entries(predefinedKeys));
+
+    // Reset the key generator to use the new keys.
+    this._keyGenerator = this._predefinedKeys.keys();
+  }
+
+  public async exportKey({ keyUri }:
+    KmsExportKeyParams
+  ): Promise<Jwk> {
+    // Get the private key from the key store.
+    const privateKey = this._predefinedKeys.get(keyUri);
+
+    // Throw an error if the key is not found.
+    if (!privateKey) {
+      throw new Error(`DeterministicKeyGenerator.exportKey: Key not found: ${keyUri}`);
+    }
+
+    return privateKey;
+  }
+
+  public async generateKey(_params: {
+    algorithm: 'Ed25519' | 'secp256k1' | 'secp256r1'
+  }): Promise<KeyIdentifier> {
+    // Get the next key from the array of predefined keys.
+    const { value: keyUri, done } = this._keyGenerator.next();
+
+    // Throw an error if the generator is empty and there are no more keys to return.
+    if (done) {
+      throw new Error('Ran out of predefined keys');
+    }
+
+    return keyUri;
+  }
+
+  public async getPublicKey({ keyUri }:
+      KmsGetPublicKeyParams
+  ): Promise<Jwk> {
+    // Get the private key from the key store.
+    const privateKey = this._predefinedKeys.get(keyUri);
+
+    // Throw an error if the key is not found.
+    if (!privateKey) {
+      throw new Error(`DeterministicKeyGenerator.getPublicKey: Key not found: ${keyUri}`);
+    }
+
+    // Get the public key properties from the private JWK.
+    const { d, ...publicKey } = privateKey;
+
+    return publicKey;
+  }
+
+  public async sign({ keyUri, data }:
+    KmsSignParams
+  ): Promise<Uint8Array> {
+    // Get the private key from the key store.
+    const privateKey = this._predefinedKeys.get(keyUri);
+
+    // Throw an error if the key is not found.
+    if (!privateKey) {
+      throw new Error(`DeterministicKeyGenerator.sign: Key not found: ${keyUri}`);
+    }
+
+    // Sign the data.
+    const signature = await Ed25519.sign({ data, key: privateKey });
+
+    return signature;
+  }
+}
+
+/**
+ * Determines the tenant identifier (DID) for data store operations based on the provided
+ * parameters.
+ *
+ * The function identifies the tenant using a priority order:
+ * 1. directly provided tenant DID,
+ * 2. the agent's DID,
+ * 3. or a specified DID URI.
+ *
+ * This approach ensures operations are isolated by DID, supporting multi-tenancy.
+ *
+ * @param params - The parameters for determining the tenant.
+ * @param params.agent - The Web5 platform agent instance.
+ * @param [params.tenant] - An optional tenant DID. If provided, it takes precedence.
+ * @param [params.didUri] - An optional DID URI to use if no tenant DID or agent DID is available.
+ * @returns A promise that resolves to the tenant DID.
+ * @throws Throws an error if it fails to determine the tenant from the provided inputs.
+ */
+export async function getDataStoreTenant({ agent, tenant, didUri }: {
+  agent: Web5PlatformAgent;
+  tenant?: string;
+  didUri?: string;
+}): Promise<string> {
+  // Check if a tenant identifier (DID) is explicitly provided and return it immediately if so.
+  // This is the highest priority to ensure explicit tenant isolation.
+  if (tenant) return tenant;
+
+  // If the agent's DID is available, return it as the tenant identifier.
+  // This allows using the agent's own identity as a fallback tenant.
+  if (agent.agentDid) return agent.agentDid.uri;
+
+  // Throw an error if neither tenant, agent.agentDid, nor didUri are provided,
+  // as it's not possible to determine the tenant identifier without any of these.
+  if (!didUri) {
+    throw new Error(`Failed to determine tenant DID: 'agent.agentDid', 'tenant', and 'didUri' are undefined`);
+  }
+
+  // Return the DID URI as the tenant identifier if both `tenant` and `agent.agentDid` are undefined
+  // but a `didUri` is provided. This assumes the agent has the necessary permissions and keys
+  // associated with the provided DID for data store operations.
+  //
+  // Note: This assumes the Agent's key manager has the private key for the given DID URI. No
+  // explicit check is made here for performance reasons, relying on downstream processes to
+  // validate access rights.
+  return didUri;
+}

package/src/utils.ts

@@ -0,0 +1,181 @@
+import type { DidUrlDereferencer } from '@enbox/dids';
+import { Jws, PaginationCursor, RecordsDeleteMessage, RecordsWriteMessage } from '@enbox/dwn-sdk-js';
+
+import { Readable } from '@enbox/common';
+import { utils as didUtils } from '@enbox/dids';
+import { ReadableWebToNodeStream } from 'readable-web-to-node-stream';
+import { DateSort, DwnInterfaceName, DwnMethodName, Message, RecordsWrite } from '@enbox/dwn-sdk-js';
+
+export function blobToIsomorphicNodeReadable(blob: Blob): Readable {
+  return webReadableToIsomorphicNodeReadable(blob.stream() as ReadableStream<any>);
+}
+
+export async function getDwnServiceEndpointUrls(didUri: string, dereferencer: DidUrlDereferencer): Promise<string[]> {
+  // Attempt to dereference the DID service with ID fragment #dwn.
+  const dereferencingResult = await dereferencer.dereference(`${didUri}#dwn`);
+
+  if (dereferencingResult.dereferencingMetadata.error) {
+    throw new Error(`Failed to dereference '${didUri}#dwn': ${dereferencingResult.dereferencingMetadata.error}`);
+  }
+
+  if (didUtils.isDwnDidService(dereferencingResult.contentStream)) {
+    const { serviceEndpoint } = dereferencingResult.contentStream;
+    const serviceEndpointUrls = typeof serviceEndpoint === 'string'
+    // If the service endpoint is a string, format it as a single-element array.
+      ? [serviceEndpoint]
+      : Array.isArray(serviceEndpoint) && serviceEndpoint.every(endpoint => typeof endpoint === 'string')
+      // If the service endpoint is an array of strings, use it as is.
+        ? serviceEndpoint as string[]
+        // If the service endpoint is neither a string nor an array of strings, return an empty array.
+        : [];
+
+    if (serviceEndpointUrls.length > 0) {
+      return serviceEndpointUrls;
+    }
+  }
+
+  // If the DID service with ID fragment #dwn was not found or is not valid, return an empty array.
+  return [];
+}
+
+export function getRecordAuthor(record: RecordsWriteMessage | RecordsDeleteMessage): string | undefined {
+  return Message.getAuthor(record);
+}
+
+/**
+ * Get the `protocolRole` string from the signature payload of the given RecordsWriteMessage or RecordsDeleteMessage.
+ */
+export function getRecordProtocolRole(message: RecordsWriteMessage | RecordsDeleteMessage): string | undefined {
+  const signaturePayload = Jws.decodePlainObjectPayload(message.authorization.signature);
+  return signaturePayload?.protocolRole;
+}
+
+export function isRecordsWrite(obj: unknown): obj is RecordsWrite {
+  // Validate that the given value is an object.
+  if (!obj || typeof obj !== 'object' || obj === null) return false;
+
+  // Validate that the object has the necessary properties of RecordsWrite.
+  return (
+    'message' in obj && typeof obj.message === 'object' && obj.message !== null &&
+    'descriptor' in obj.message && typeof obj.message.descriptor === 'object' && obj.message.descriptor !== null &&
+    'interface' in obj.message.descriptor && obj.message.descriptor.interface === DwnInterfaceName.Records &&
+    'method' in obj.message.descriptor && obj.message.descriptor.method === DwnMethodName.Write
+  );
+}
+
+/**
+ * Get the CID of the given RecordsWriteMessage.
+ */
+export function getRecordMessageCid(message: RecordsWriteMessage): Promise<string> {
+  return Message.getCid(message);
+}
+
+/**
+ *  Get the pagination cursor for the given RecordsWriteMessage and DateSort.
+ *
+ * @param message The RecordsWriteMessage for which to get the pagination cursor.
+ * @param dateSort The date sort that will be used in the query or subscription to which the cursor will be applied.
+ */
+export async function getPaginationCursor(message: RecordsWriteMessage, dateSort: DateSort): Promise<PaginationCursor> {
+  const value = dateSort === DateSort.CreatedAscending || dateSort === DateSort.CreatedDescending ?
+    message.descriptor.dateCreated : message.descriptor.datePublished;
+
+  if (value === undefined) {
+    throw new Error('The dateCreated or datePublished property is missing from the record descriptor.');
+  }
+
+  return {
+    messageCid: await getRecordMessageCid(message),
+    value
+  };
+}
+
+export function webReadableToIsomorphicNodeReadable(webReadable: ReadableStream<any>) {
+  return new ReadableWebToNodeStream(webReadable);
+}
+
+/**
+ * Polling function with interval, TTL accepting a custom fetch function
+ * @template T - the return you expect from the fetcher
+ * @param fetchFunction an http fetch function
+ * @param [interval=3000] how frequently to poll
+ * @param [ttl=300_000] how long until polling stops
+ * @returns T - the result of fetch
+ */
+export function pollWithTtl(
+  fetchFunction: () => Promise<Response>,
+  interval = 3000,
+  ttl = 300_000,
+  abortSignal?: AbortSignal
+): Promise<Response | null> {
+  const endTime = Date.now() + ttl;
+  let timeoutId: NodeJS.Timeout | null = null;
+  let isPolling = true;
+  return new Promise((resolve, reject) => {
+    if (abortSignal) {
+      abortSignal.addEventListener('abort', () => {
+        isPolling = false;
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        console.log('Polling aborted by user');
+        resolve(null);
+      });
+    }
+
+    async function poll() {
+      if (!isPolling) return;
+
+      const remainingTime = endTime - Date.now();
+
+      if (remainingTime <= 0) {
+        isPolling = false;
+        console.log('Polling stopped: TTL reached');
+        resolve(null);
+        return;
+      }
+
+      console.log(`Polling... (Remaining time: ${Math.ceil(remainingTime / 1000)}s)`);
+
+      try {
+        const response = await fetchFunction();
+
+        if (response.ok) {
+          isPolling = false;
+
+          if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+          }
+
+          console.log('Polling stopped: Success condition met');
+          resolve(response);
+          return;
+        }
+      } catch (error) {
+        console.error('Error fetching data:', error);
+        reject(error);
+      }
+
+      if (isPolling) {
+        timeoutId = setTimeout(poll, interval);
+      }
+    }
+
+    poll();
+  });
+}
+
+/** Concatenates a base URL and a path ensuring that there is exactly one slash between them */
+export function concatenateUrl(baseUrl: string, path: string): string {
+  // Remove trailing slash from baseUrl if it exists
+  if (baseUrl.endsWith('/')) {
+    baseUrl = baseUrl.slice(0, -1);
+  }
+
+  // Remove leading slash from path if it exists
+  if (path.startsWith('/')) {
+    path = path.slice(1);
+  }
+
+  return `${baseUrl}/${path}`;
+}