@enbox/agent 0.0.1

package/src/agent-did-resolver-cache.ts

@@ -0,0 +1,95 @@
+import { DidResolutionResult, DidResolverCache, DidResolverCacheLevel, DidResolverCacheLevelParams } from '@enbox/dids';
+import { Web5PlatformAgent } from './types/agent.js';
+import { logger } from '@enbox/common';
+
+
+/**
+ * AgentDidResolverCache keeps a stale copy of the Agent's managed Identity DIDs and only evicts and refreshes upon a successful resolution.
+ * This allows for quick and offline access to the internal DIDs used by the agent.
+ */
+export class AgentDidResolverCache extends DidResolverCacheLevel implements DidResolverCache {
+
+  /**
+   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
+   * the `AgentDidApi`. 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;
+
+  /** A map of DIDs that are currently in-flight. This helps avoid going into an infinite loop */
+  private _resolving: Map<string, boolean> = new Map();
+
+  constructor({ agent, db, location, ttl }: DidResolverCacheLevelParams & { agent?: Web5PlatformAgent }) {
+    super ({ db, location, ttl });
+    this._agent = agent;
+  }
+
+  get agent() {
+    if (!this._agent) {
+      throw new Error('Agent not initialized');
+    }
+    return this._agent;
+  }
+
+  set agent(agent: Web5PlatformAgent) {
+    this._agent = agent;
+  }
+
+  /**
+   * Get the DID resolution result from the cache for the given DID.
+   *
+   * If the DID is managed by the agent, or is the agent's own DID, it will not evict it from the cache until a new resolution is successful.
+   * This is done to achieve quick and offline access to the agent's own managed DIDs.
+   */
+  async get(did: string): Promise<DidResolutionResult | void> {
+    try {
+      const str = await this.cache.get(did);
+      const cachedResult = JSON.parse(str);
+      if (!this._resolving.has(did) && Date.now() >= cachedResult.ttlMillis) {
+        this._resolving.set(did, true);
+
+        // if a DID is stored in the DID Store, then we don't want to evict it from the cache until we have a successful resolution
+        // upon a successful resolution, we will update both the storage and the cache with the newly resolved Document.
+        const storedDid = await this.agent.did.get({ didUri: did, tenant: this.agent.agentDid.uri });
+        if ('undefined' !==  typeof storedDid) {
+          try {
+            const result = await this.agent.did.resolve(did);
+
+            // if the resolution was successful, update the stored DID with the new Document
+            if (!result.didResolutionMetadata.error && result.didDocument) {
+
+              const portableDid = {
+                ...storedDid,
+                document : result.didDocument,
+                metadata : result.didDocumentMetadata,
+              };
+
+              try {
+                // this will throw an error if the DID is not managed by the agent, or there is no difference between the stored and resolved DID
+                // We don't publish the DID in this case, as it was received by the resolver.
+                await this.agent.did.update({ portableDid, tenant: this.agent.agentDid.uri, publish: false });
+              } catch(error: any) {
+                // if the error is not due to no changes detected, log the error
+                if (error.message && !error.message.includes('No changes detected, update aborted')) {
+                  logger.error(`Error updating DID: ${error.message}`);
+                }
+              }
+            }
+          } finally {
+            this._resolving.delete(did);
+          }
+        } else {
+          this._resolving.delete(did);
+          this.cache.nextTick(() => this.cache.del(did));
+        }
+      }
+      return cachedResult.value;
+    } catch(error: any) {
+      if (error.notFound) {
+        return;
+      }
+      throw error;
+    }
+  }
+}

package/src/bearer-identity.ts

@@ -0,0 +1,42 @@
+import { BearerDid } from '@enbox/dids';
+import { IdentityMetadata, PortableIdentity } from './types/identity.js';
+
+/**
+ * Represents a Web5 Identity with its DID and metadata.
+ */
+export class BearerIdentity {
+  /** {@inheritDoc BearerDid} */
+  public did: BearerDid;
+
+  /** {@inheritDoc DidMetadata} */
+  public metadata: IdentityMetadata;
+
+  constructor({ did, metadata }: {
+    did: BearerDid;
+    metadata: IdentityMetadata;
+  }) {
+    this.did = did;
+    this.metadata = metadata;
+  }
+
+  /**
+   * Converts a `BearerIdentity` object to a portable format containing the DID and metadata
+   * associated with the Identity.
+   *
+   * @example
+   * ```ts
+   * // Assuming `identity` is an instance of BearerIdentity.
+   * const portableIdentity = await identity.export();
+   * // portableIdentity now contains the and metadata.
+   * ```
+   *
+   * @returns A `PortableIdentity` containing the DID and metadata associated with the
+   *          `BearerIdentity`.
+   */
+  public async export(): Promise<PortableIdentity> {
+    return {
+      portableDid : await this.did.export(),
+      metadata    : { ...this.metadata },
+    };
+  }
+}

package/src/connect.ts

@@ -0,0 +1,296 @@
+
+import type { PushedAuthResponse } from './oidc.js';
+import type { DwnPermissionScope, DwnProtocolDefinition, Web5Agent, Web5ConnectAuthResponse } from './index.js';
+
+import {
+  Oidc,
+} from './oidc.js';
+import { pollWithTtl } from './utils.js';
+
+import { Convert, logger } from '@enbox/common';
+import { CryptoUtils } from '@enbox/crypto';
+import { DidJwk } from '@enbox/dids';
+import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
+
+/**
+ * Initiates the wallet connect process. Used when a client wants to obtain
+ * a did from a provider.
+ */
+async function initClient({
+  displayName,
+  connectServerUrl,
+  walletUri,
+  permissionRequests,
+  onWalletUriReady,
+  validatePin,
+}: WalletConnectOptions) {
+  // ephemeral client did for ECDH, signing, verification
+  // TODO: use separate keys for ECDH vs. sign/verify. could maybe use secp256k1.
+  const clientDid = await DidJwk.create();
+
+  // TODO: properly implement PKCE. this implementation is lacking server side validations and more.
+  // https://github.com/TBD54566975/web5-js/issues/829
+  // Derive the code challenge based on the code verifier
+  // const { codeChallengeBytes, codeChallengeBase64Url } =
+  //   await Oidc.generateCodeChallenge();
+  const encryptionKey = CryptoUtils.randomBytes(32);
+
+  // build callback URL to pass into the auth request
+  const callbackEndpoint = Oidc.buildOidcUrl({
+    baseURL  : connectServerUrl,
+    endpoint : 'callback',
+  });
+
+  // build the PAR request
+  const request = await Oidc.createAuthRequest({
+    client_id          : clientDid.uri,
+    scope              : 'openid did:jwk',
+    redirect_uri       : callbackEndpoint,
+    // custom properties:
+    // code_challenge        : codeChallengeBase64Url,
+    // code_challenge_method : 'S256',
+    permissionRequests : permissionRequests,
+    displayName,
+  });
+
+  // Sign the Request Object using the Client DID's signing key.
+  const requestJwt = await Oidc.signJwt({
+    did  : clientDid,
+    data : request,
+  });
+
+  if (!requestJwt) {
+    throw new Error('Unable to sign requestObject');
+  }
+  // Encrypt the Request Object JWT using the code challenge.
+  const requestObjectJwe = await Oidc.encryptAuthRequest({
+    jwt: requestJwt,
+    encryptionKey,
+  });
+
+  // Convert the encrypted Request Object to URLSearchParams for form encoding.
+  const formEncodedRequest = new URLSearchParams({
+    request: requestObjectJwe,
+  });
+
+  const pushedAuthorizationRequestEndpoint = Oidc.buildOidcUrl({
+    baseURL  : connectServerUrl,
+    endpoint : 'pushedAuthorizationRequest',
+  });
+
+  const parResponse = await fetch(pushedAuthorizationRequestEndpoint, {
+    body    : formEncodedRequest,
+    method  : 'POST',
+    headers : {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+  });
+
+  if (!parResponse.ok) {
+    throw new Error(`${parResponse.status}: ${parResponse.statusText}`);
+  }
+
+  const parData: PushedAuthResponse = await parResponse.json();
+
+  // a deeplink to a web5 compatible wallet. if the wallet scans this link it should receive
+  // a route to its web5 connect provider flow and the params of where to fetch the auth request.
+  logger.log(`Wallet URI: ${walletUri}`);
+  const generatedWalletUri = new URL(walletUri);
+  generatedWalletUri.searchParams.set('request_uri', parData.request_uri);
+  generatedWalletUri.searchParams.set(
+    'encryption_key',
+    Convert.uint8Array(encryptionKey).toBase64Url()
+  );
+
+  // call user's callback so they can send the URI to the wallet as they see fit
+  onWalletUriReady(generatedWalletUri.toString());
+
+  const tokenUrl = Oidc.buildOidcUrl({
+    baseURL    : connectServerUrl,
+    endpoint   : 'token',
+    tokenParam : request.state,
+  });
+
+  // subscribe to receiving a response from the wallet with default TTL. receive ciphertext of {@link Web5ConnectAuthResponse}
+  const authResponse = await pollWithTtl(() => fetch(tokenUrl));
+
+  if (authResponse) {
+    const jwe = await authResponse?.text();
+
+    // get the pin from the user and use it as AAD to decrypt
+    const pin = await validatePin();
+    const jwt = await Oidc.decryptAuthResponse(clientDid, jwe, pin);
+    const verifiedAuthResponse = (await Oidc.verifyJwt({
+      jwt,
+    })) as Web5ConnectAuthResponse;
+
+    return {
+      delegateGrants      : verifiedAuthResponse.delegateGrants,
+      delegatePortableDid : verifiedAuthResponse.delegatePortableDid,
+      connectedDid        : verifiedAuthResponse.iss,
+    };
+  }
+}
+
+/**
+ * Initiates the wallet connect process. Used when a client wants to obtain
+ * a did from a provider.
+ */
+export type WalletConnectOptions = {
+  /** The user friendly name of the client/app to be displayed when prompting end-user with permission requests. */
+  displayName: string;
+
+  /** The URL of the intermediary server which relays messages between the client and provider. */
+  connectServerUrl: string;
+
+  /**
+   * The URI of the Provider (wallet).The `onWalletUriReady` will take this wallet
+   * uri and add a payload to it which will be used to obtain and decrypt from the `request_uri`.
+   * @example `web5://` or `http://localhost:3000/`.
+   */
+  walletUri: string;
+
+  /**
+   * The protocols of permissions requested, along with the definition and
+   * permission scopes for each protocol. The key is the protocol URL and
+   * the value is an object with the protocol definition and the permission scopes.
+   */
+  permissionRequests: ConnectPermissionRequest[];
+
+  /**
+   * The Web5 API provides a URI to the wallet based on the `walletUri` plus a query params payload valid for 5 minutes.
+   * The link can either be used as a deep link on the same device or a QR code for cross device or both.
+   * The query params are `{ request_uri: string; encryption_key: string; }`
+   * The wallet will use the `request_uri to contact the intermediary server's `authorize` endpoint
+   * and pull down the {@link Web5ConnectAuthRequest} and use the `encryption_key` to decrypt it.
+   *
+   * @param uri - The URI returned by the web5 connect API to be passed to a provider.
+   */
+  onWalletUriReady: (uri: string) => void;
+
+  /**
+   * Function that must be provided to submit the pin entered by the user on the client.
+   * The pin is used to decrypt the {@link Web5ConnectAuthResponse} that was retrieved from the
+   * token endpoint by the client inside of web5 connect.
+   *
+   * @returns A promise that resolves to the PIN as a string.
+   */
+  validatePin: () => Promise<string>;
+};
+
+/**
+ * The protocols of permissions requested, along with the definition and permission scopes for each protocol.
+ */
+export type ConnectPermissionRequest = {
+  /**
+   * The definition of the protocol the permissions are being requested for.
+   * In the event that the protocol is not already installed, the wallet will install this given protocol definition.
+   */
+  protocolDefinition: DwnProtocolDefinition;
+
+  /** The scope of the permissions being requested for the given protocol */
+  permissionScopes: DwnPermissionScope[];
+};
+
+/**
+ * Shorthand for the types of permissions that can be requested.
+ */
+export type Permission = 'write' | 'read' | 'delete' | 'query' | 'subscribe' | 'configure';
+
+/**
+ * The options for creating a permission request for a given protocol.
+ */
+export type ProtocolPermissionOptions = {
+  /** The protocol definition for the protocol being requested */
+  definition: DwnProtocolDefinition;
+
+  /** The permissions being requested for the protocol */
+  permissions: Permission[];
+};
+
+/**
+ * Creates a set of Dwn Permission Scopes to request for a given protocol.
+ *
+ * If no permissions are provided, the default is to request all relevant record permissions (write, read, delete, query, subscribe).
+ * 'configure' is not included by default, as this gives the application a lot of control over the protocol.
+ */
+function createPermissionRequestForProtocol({ definition, permissions }: ProtocolPermissionOptions): ConnectPermissionRequest {
+  const requests: DwnPermissionScope[] = [];
+
+  // Add the ability to query for the specific protocol
+  requests.push({
+    protocol  : definition.protocol,
+    interface : DwnInterfaceName.Protocols,
+    method    : DwnMethodName.Query,
+  });
+
+  // In order to enable sync, we must request permissions for `MessagesQuery`, `MessagesRead` and `MessagesSubscribe`
+  requests.push({
+    protocol  : definition.protocol,
+    interface : DwnInterfaceName.Messages,
+    method    : DwnMethodName.Read,
+  }, {
+    protocol  : definition.protocol,
+    interface : DwnInterfaceName.Messages,
+    method    : DwnMethodName.Query,
+  }, {
+    protocol  : definition.protocol,
+    interface : DwnInterfaceName.Messages,
+    method    : DwnMethodName.Subscribe,
+  });
+
+  // We also request any additional permissions the user has requested for this protocol
+  for (const permission of permissions) {
+    switch (permission) {
+      case 'write':
+        requests.push({
+          protocol  : definition.protocol,
+          interface : DwnInterfaceName.Records,
+          method    : DwnMethodName.Write,
+        });
+        break;
+      case 'read':
+        requests.push({
+          protocol  : definition.protocol,
+          interface : DwnInterfaceName.Records,
+          method    : DwnMethodName.Read,
+        });
+        break;
+      case 'delete':
+        requests.push({
+          protocol  : definition.protocol,
+          interface : DwnInterfaceName.Records,
+          method    : DwnMethodName.Delete,
+        });
+        break;
+      case 'query':
+        requests.push({
+          protocol  : definition.protocol,
+          interface : DwnInterfaceName.Records,
+          method    : DwnMethodName.Query,
+        });
+        break;
+      case 'subscribe':
+        requests.push({
+          protocol  : definition.protocol,
+          interface : DwnInterfaceName.Records,
+          method    : DwnMethodName.Subscribe,
+        });
+        break;
+      case 'configure':
+        requests.push({
+          protocol  : definition.protocol,
+          interface : DwnInterfaceName.Protocols,
+          method    : DwnMethodName.Configure,
+        });
+        break;
+    }
+  }
+
+  return {
+    protocolDefinition : definition,
+    permissionScopes   : requests,
+  };
+}
+
+export const WalletConnect = { initClient, createPermissionRequestForProtocol };