@enbox/api 0.0.1

package/src/web5.ts

@@ -0,0 +1,516 @@
+/**
+ * NOTE: Added reference types here to avoid a `pnpm` bug during build.
+ * https://github.com/TBD54566975/web5-js/pull/507
+ */
+/// <reference types="@enbox/dwn-sdk-js" />
+
+import type {
+  BearerIdentity,
+  DwnDataEncodedRecordsWriteMessage,
+  DwnMessagesPermissionScope,
+  DwnProtocolDefinition,
+  DwnRecordsPermissionScope,
+  HdIdentityVault,
+  Permission,
+  WalletConnectOptions,
+  Web5Agent,
+} from '@enbox/agent';
+
+import { Web5UserAgent } from '@enbox/user-agent';
+import { DwnInterface, DwnRegistrar, WalletConnect } from '@enbox/agent';
+
+import { DidApi } from './did-api.js';
+import { DwnApi } from './dwn-api.js';
+import { VcApi } from './vc-api.js';
+import { PermissionGrant } from './permission-grant.js';
+
+/** Override defaults configured during the technical preview phase. */
+export type TechPreviewOptions = {
+  /** Override default dwnEndpoints provided for technical preview. */
+  dwnEndpoints?: string[];
+};
+
+/** Override defaults for DID creation. */
+export type DidCreateOptions = {
+  /** Override default dwnEndpoints provided during DID creation. */
+  dwnEndpoints?: string[];
+}
+
+/**
+ * Represents a permission request for a protocol definition.
+ */
+export type ConnectPermissionRequest = {
+  /**
+   * The protocol definition for the protocol being requested.
+   */
+  protocolDefinition: DwnProtocolDefinition;
+
+  /**
+   * The permissions being requested for the protocol. If none are provided, the default is to request all permissions.
+   */
+  permissions?: Permission[];
+}
+
+/**
+ * Options for connecting to a Web5 agent. This includes the ability to connect to an external wallet.
+ *
+ * NOTE: the returned `ConnectPermissionRequest` type is different to the `ConnectPermissionRequest` type in the `@enbox/agent` package.
+ */
+export type ConnectOptions = Omit<WalletConnectOptions, 'permissionRequests'> & {
+  /** The user friendly name of the client/app to be displayed when prompting end-user with permission requests. */
+  displayName: string;
+
+  /**
+   * The permissions that are being requested for the connected DID.
+   * This is used to create the {@link ConnectPermissionRequest} for the wallet connect flow.
+   */
+  permissionRequests: ConnectPermissionRequest[];
+}
+
+/** Optional overrides that can be provided when calling {@link Web5.connect}. */
+export type Web5ConnectOptions = {
+  /**
+   * When specified, external wallet connect flow is triggered.
+   * This param currently will not work in apps that are currently connected.
+   * It must only be invoked at registration with a reset and empty DWN and agent.
+   */
+  walletConnectOptions?: ConnectOptions;
+
+  /**
+   * Provide a {@link Web5Agent} implementation. Defaults to creating a local
+   * {@link Web5UserAgent} if one isn't provided
+   **/
+  agent?: Web5Agent;
+
+  /**
+   * Provide an instance of a {@link HdIdentityVault} implementation. Defaults to
+   * a LevelDB-backed store with an insecure, static unlock password if one
+   * isn't provided. To allow the app user to enter a secure password of
+   * their choosing, provide an initialized {@link HdIdentityVault} instance.
+   **/
+  agentVault?: HdIdentityVault;
+
+  /** Specify an existing DID to connect to. */
+  connectedDid?: string;
+
+  /**
+   * The Web5 app `password` is used to protect data on the device the application is running on.
+   *
+   * Only the end user should know this password: it should not be stored on the device or
+   * transmitted over the network.
+   *
+   * This password is crucial for the security of an identity vault that stores the local Agent's
+   * cryptographic keys and decentralized identifier (DID). The vault's content is encrypted using
+   * the password, making it accessible only to those who know the password.
+   *
+   * App users should be advised to use a strong, unique passphrase that is not shared across
+   * different services or applications. The password should be kept confidential and not be
+   * exposed to unauthorized entities. Losing the password may result in irreversible loss of
+   * access to the vault's contents.
+   */
+  password?: string;
+
+  /**
+   * The `recoveryPhrase` is a unique, secure key for recovering the identity vault.
+   *
+   * This phrase is a series of 12 words generated securely and known only to the user. It plays a
+   * critical role in the security of the identity vault by enabling the recovery of the vault's
+   * contents, including cryptographic keys and the Agent's decentralized identifier (DID), across
+   * different devices or if the original device is compromised or lost.
+   *
+   * The recovery phrase is akin to a master key, as anyone with access to this phrase can restore
+   * and access the vault's contents. It’s combined with the app `password` to encrypt the vault's
+   * content.
+   *
+   * Unlike a password, the recovery phrase is not intended for regular use but as a secure backup
+   * method for vault recovery. Losing this phrase can result in permanent loss of access to the
+   * vault's contents, as it cannot be reset or retrieved if forgotten.
+   *
+   * Users should treat the recovery phrase with the highest level of security, ensuring it is
+   * never shared, stored online, or exposed to potential threats. It is the user's responsibility
+   * to keep this phrase safe to maintain the integrity and accessibility of their secured data. It
+   * is recommended to write it down and store it in a secure location, separate from the device and
+   * digital backups.
+   */
+  recoveryPhrase?: string;
+
+  /**
+   * Enable synchronization of DWN records between local and remote DWNs.
+   * Sync defaults to running every 2 minutes and can be set to any value accepted by `ms()`.
+   * To disable sync set to 'off'.
+   */
+  sync?: string;
+
+  /**
+   * Override defaults configured during the technical preview phase.
+   * See {@link TechPreviewOptions} for available options.
+   */
+  techPreview?: TechPreviewOptions;
+
+  /**
+   * Override defaults configured options for creating a DID during connect.
+   * See {@link DidCreateOptions} for available options.
+   */
+  didCreateOptions?: DidCreateOptions;
+
+  /**
+   * If the `registration` option is provided, the agent DID and the connected DID will be registered with the DWN endpoints provided by `techPreview` or `didCreateOptions`.
+   *
+   * If registration fails, the `onFailure` callback will be called with the error.
+   * If registration is successful, the `onSuccess` callback will be called.
+   */
+  registration? : {
+    /** Called when all of the DWN registrations are successful */
+    onSuccess: () => void;
+    /** Called when any of the DWN registrations fail */
+    onFailure: (error: any) => void;
+  }
+}
+
+/**
+ * Represents the result of the Web5 connection process, including the Web5 instance,
+ * the connected decentralized identifier (DID), and optionally the recovery phrase used
+ * during the agent's initialization.
+ */
+export type Web5ConnectResult = {
+  /** The Web5 instance, providing access to the agent, DID, DWN, and VC APIs. */
+  web5: Web5;
+
+  /** The DID that has been connected or created during the connection process. */
+  did: string;
+
+  /**
+   * The first time a Web5 agent is initialized, the recovery phrase that was used to generate the
+   * agent's DID and keys is returned. This phrase can be used to recover the agent's vault contents
+   * and should be stored securely by the user.
+   */
+  recoveryPhrase?: string;
+
+  /**
+   * The resulting did of a successful wallet connect. Only returned on success if
+   * {@link WalletConnectOptions} was provided.
+   */
+  delegateDid?: string;
+};
+
+/**
+ * Parameters that are passed to Web5 constructor.
+ *
+ * @see {@link Web5ConnectOptions}
+ */
+export type Web5Params = {
+  /**
+   * A {@link Web5Agent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
+   * user keys and identities, and is responsible to sign and verify messages.
+   */
+  agent: Web5Agent;
+
+  /** The DID of the tenant under which all DID, DWN, and VC requests are being performed. */
+  connectedDid: string;
+
+  /** The DID that will be signing Web5 messages using grants from the connectedDid */
+  delegateDid?: string;
+};
+
+/**
+ * The main Web5 API interface. It manages the creation of a DID if needed, the connection to the
+ * local DWN and all the web5 main foundational APIs such as VC, syncing, etc.
+ */
+export class Web5 {
+  /**
+   * A {@link Web5Agent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
+   * user keys and identities, and is responsible to sign and verify messages.
+   */
+  agent: Web5Agent;
+
+  /** Exposed instance to the DID APIs, allow users to create and resolve DIDs  */
+  did: DidApi;
+
+  /** Exposed instance to the DWN APIs, allow users to read/write records */
+  dwn: DwnApi;
+
+  /** Exposed instance to the VC APIs, allow users to issue, present and verify VCs */
+  vc: VcApi;
+
+  constructor({ agent, connectedDid, delegateDid }: Web5Params) {
+    this.agent = agent;
+    this.did = new DidApi({ agent, connectedDid });
+    this.dwn = new DwnApi({ agent, connectedDid, delegateDid });
+    this.vc = new VcApi({ agent, connectedDid });
+  }
+
+  /**
+   * Connects to a {@link Web5Agent}. Defaults to creating a local {@link Web5UserAgent} if one
+   * isn't provided.
+   *
+   * If `walletConnectOptions` are provided, a WalletConnect flow will be initiated to import a delegated DID from an external wallet.
+   * If there is a failure at any point during connecting and processing grants, all created DIDs and Identities as well as the provided grants
+   * will be cleaned up and an error thrown. This allows for subsequent Connect attempts to be made without any errors.
+   *
+   * @param options - Optional overrides that can be provided when calling {@link Web5.connect}.
+   * @returns A promise that resolves to a {@link Web5} instance and the connected DID.
+   */
+  static async connect({
+    agent,
+    agentVault,
+    connectedDid,
+    password,
+    recoveryPhrase,
+    sync,
+    techPreview,
+    didCreateOptions,
+    registration,
+    walletConnectOptions,
+  }: Web5ConnectOptions = {}): Promise<Web5ConnectResult> {
+    let delegateDid: string | undefined;
+    if (agent === undefined) {
+      let registerSync = false;
+      // A custom Web5Agent implementation was not specified, so use default managed user agent.
+      const userAgent = await Web5UserAgent.create({ agentVault });
+      agent = userAgent;
+
+      // Warn the developer and application user of the security risks of using a static password.
+      if (password === undefined) {
+        password = 'insecure-static-phrase';
+        console.warn(
+          '%cSECURITY WARNING:%c ' +
+          'You have not set a password, which defaults to a static, guessable value. ' +
+          'This significantly compromises the security of your data. ' +
+          'Please configure a secure, unique password.',
+          'font-weight: bold; color: red;',
+          'font-weight: normal; color: inherit;'
+        );
+      }
+
+      // Use the specified DWN endpoints or the latest TBD hosted DWN
+      const serviceEndpointNodes = techPreview?.dwnEndpoints ?? didCreateOptions?.dwnEndpoints ?? ['https://enbox-production.up.railway.app'];
+
+      // Initialize, if necessary, and start the agent.
+      if (await userAgent.firstLaunch()) {
+        recoveryPhrase = await userAgent.initialize({ password, recoveryPhrase, dwnEndpoints: serviceEndpointNodes });
+      }
+      await userAgent.start({ password });
+      // Attempt to retrieve the connected Identity if it exists.
+      const connectedIdentity: BearerIdentity = await userAgent.identity.connectedIdentity();
+      let identity: BearerIdentity;
+      let connectedProtocols: string[] = [];
+      if (connectedIdentity) {
+        // if a connected identity is found, use it
+        // TODO: In the future, implement a way to re-connect an already connected identity and apply additional grants/protocols
+        identity = connectedIdentity;
+      } else if (walletConnectOptions) {
+        if (sync === 'off') {
+          // Currently we require sync to be enabled when using WalletConnect
+          // This is to ensure a connected app is not in a disjointed state from any other clients/app using the connectedDid
+          throw new Error('Sync must not be disabled when using WalletConnect');
+        }
+
+        // Since we are connecting a new identity, we will want to register sync for the connectedDid
+        registerSync = true;
+
+        // No connected identity found and connectOptions are provided, attempt to import a delegated DID from an external wallet
+        try {
+          const { permissionRequests, ...connectOptions } = walletConnectOptions;
+          const walletPermissionRequests = permissionRequests.map(({ protocolDefinition, permissions }) => WalletConnect.createPermissionRequestForProtocol({
+            definition  : protocolDefinition,
+            permissions : permissions ?? [
+              'read', 'write', 'delete', 'query', 'subscribe'
+            ]}
+          ));
+
+          const { delegatePortableDid, connectedDid, delegateGrants } = await WalletConnect.initClient({
+            ...connectOptions,
+            permissionRequests: walletPermissionRequests,
+          });
+
+          // Import the delegated DID as an Identity in the User Agent.
+          // Setting the connectedDID in the metadata applies a relationship between the signer identity and the one it is impersonating.
+          identity = await userAgent.identity.import({ portableIdentity: {
+            portableDid : delegatePortableDid,
+            metadata    : {
+              connectedDid,
+              name   : 'Default',
+              uri    : delegatePortableDid.uri,
+              tenant : agent.agentDid.uri,
+            }
+          }});
+
+          // Attempts to process the connected grants to be used by the delegateDID
+          // If the process fails, we want to clean up the identity
+          // the connected grants will return a de-duped array of protocol URIs that are used to register sync for those protocols
+          connectedProtocols = await this.processConnectedGrants({ agent, delegateDid: delegatePortableDid.uri, grants: delegateGrants });
+        } catch (error:any) {
+          // clean up the DID and Identity if import fails and throw
+          // TODO: Implement the ability to purge all of our messages as a tenant
+          await this.cleanUpIdentity({ identity, userAgent });
+          throw new Error(`Failed to connect to wallet: ${error.message}`);
+        }
+      } else {
+        // No connected identity found and no connectOptions provided, use local Identities
+        // Query the Agent's DWN tenant for identity records.
+        const identities = await userAgent.identity.list();
+
+        // If an existing identity is not found found, create a new one.
+        const existingIdentityCount = identities.length;
+        if (existingIdentityCount === 0) {
+          // since we are creating a new identity, we will want to register sync for the created Did
+          registerSync = true;
+
+          // Generate a new Identity for the end-user.
+          identity = await userAgent.identity.create({
+            didMethod  : 'dht',
+            metadata   : { name: 'Default' },
+            didOptions : {
+              services: [
+                {
+                  id              : 'dwn',
+                  type            : 'DecentralizedWebNode',
+                  serviceEndpoint : serviceEndpointNodes,
+                  enc             : '#enc',
+                  sig             : '#sig',
+                }
+              ],
+              verificationMethods: [
+                {
+                  algorithm : 'Ed25519',
+                  id        : 'sig',
+                  purposes  : ['assertionMethod', 'authentication']
+                },
+                {
+                  algorithm : 'secp256k1',
+                  id        : 'enc',
+                  purposes  : ['keyAgreement']
+                }
+              ]
+            }
+          });
+
+        } else {
+          // If multiple identities are found, use the first one.
+          // TODO: Implement selecting a connectedDid from multiple identities
+          identity = identities[0];
+        }
+      }
+
+      // If the stored identity has a connected DID, use it as the connected DID, otherwise use the identity's DID.
+      connectedDid = identity.metadata.connectedDid ?? identity.did.uri;
+      // If the stored identity has a connected DID, use the identity DID as the delegated DID, otherwise it is undefined.
+      delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
+      if (registration !== undefined) {
+        // If a registration object is passed, we attempt to register the AgentDID and the ConnectedDID with the DWN endpoints provided
+        try {
+          for (const dwnEndpoint of serviceEndpointNodes) {
+            // check if endpoint needs registration
+            const serverInfo = await userAgent.rpc.getServerInfo(dwnEndpoint);
+            if (serverInfo.registrationRequirements.length === 0) {
+              // no registration required
+              continue;
+            }
+
+            // register the agent DID
+            await DwnRegistrar.registerTenant(dwnEndpoint, agent.agentDid.uri);
+
+            // register the connected Identity DID
+            await DwnRegistrar.registerTenant(dwnEndpoint, connectedDid);
+          }
+
+          // If no failures occurred, call the onSuccess callback
+          registration.onSuccess();
+        } catch(error) {
+          // for any failure, call the onFailure callback with the error
+          registration.onFailure(error);
+        }
+      }
+
+      // Enable sync, unless explicitly disabled.
+      if (sync !== 'off') {
+        // First, register the user identity for sync.
+        // The connected protocols are used to register sync for only a subset of protocols from the connectedDid's DWN
+
+        if (registerSync) {
+          await userAgent.sync.registerIdentity({
+            did     : connectedDid,
+            options : {
+              delegateDid,
+              protocols: connectedProtocols
+            }
+          });
+
+          if(walletConnectOptions !== undefined) {
+            // If we are using WalletConnect, we should do a one-shot sync to pull down any messages that are associated with the connectedDid
+            await userAgent.sync.sync('pull');
+          }
+        }
+
+        // Enable sync using the specified interval or default.
+        sync ??= '2m';
+        userAgent.sync.startSync({ interval: sync })
+          .catch((error: any) => {
+            console.error(`Sync failed: ${error}`);
+          });
+      }
+    }
+
+    const web5 = new Web5({ agent, connectedDid, delegateDid });
+
+    return { web5, did: connectedDid, delegateDid, recoveryPhrase };
+  }
+
+  /**
+   * Cleans up the DID, Keys and Identity. Primarily used by a failed WalletConnect import.
+   * Does not throw on error, but logs to console.
+   */
+  private static async cleanUpIdentity({ identity, userAgent }:{
+    identity: BearerIdentity,
+    userAgent: Web5UserAgent
+  }): Promise<void> {
+    try {
+      // Delete the DID and the Associated Keys
+      await userAgent.did.delete({
+        didUri    : identity.did.uri,
+        tenant    : identity.metadata.tenant,
+        deleteKey : true,
+      });
+    } catch(error: any) {
+      console.error(`Failed to delete DID ${identity.did.uri}: ${error.message}`);
+    }
+
+    try {
+      // Delete the Identity
+      await userAgent.identity.delete({ didUri: identity.did.uri });
+    } catch(error: any) {
+      console.error(`Failed to delete Identity ${identity.metadata.name}: ${error.message}`);
+    }
+  }
+
+  /**
+   * A static method to process connected grants for a delegate DID.
+   *
+   * This will store the grants as the DWN owner to be used later when impersonating the connected DID.
+   */
+  static async processConnectedGrants({ grants, agent, delegateDid }: {
+    grants: DwnDataEncodedRecordsWriteMessage[],
+    agent: Web5Agent,
+    delegateDid: string,
+  }): Promise<string[]> {
+    const connectedProtocols = new Set<string>();
+    for (const grantMessage of grants) {
+      // use the delegateDid as the connectedDid of the grant as they do not yet support impersonation/delegation
+      const grant = await PermissionGrant.parse({ connectedDid: delegateDid, agent, message: grantMessage });
+      // store the grant as the owner of the DWN, this will allow the delegateDid to use the grant when impersonating the connectedDid
+      const { status } = await grant.store(true);
+      if (status.code !== 202) {
+        throw new Error(`AgentDwnApi: Failed to process connected grant: ${status.detail}`);
+      }
+
+      const protocol = (grant.scope as DwnMessagesPermissionScope | DwnRecordsPermissionScope).protocol;
+      if (protocol) {
+        connectedProtocols.add(protocol);
+      }
+    }
+
+    // currently we return a de-duped set of protocols represented by these grants, this is used to register protocols for sync
+    // we expect that any connected protocols will include MessagesQuery and MessagesRead grants that will allow it to sync
+    return [...connectedProtocols];
+  }
+}