[WIP] SyncEngine for specific protocols + delegate sync. (#836)

* first pass at connect flow and grants api

* PermissionsApi for Agent, `permissions` API for `Web5` (#833)

This refactors a lot of what's in #824 with regards to creating/fetching grants.

Satisfies: #827

Introduces a `PermissionsApi` interface and an `AgentPermissionsApi` concrete implementation.

The interface implements the following methods `fetchGrants`, `fetchRequests`, `isGrantRevoked`, `createGrant`, `createRequest`, `createRevocation` as convenience methods for dealing with the built-in permission protocol records.

The `AgentPermissionsApi` implements an additional static method `matchGrantFromArray` which was moved from a `PermissionsUtil` class, which is used to find the appropriate grant to use when authoring a message.

A Private API used in a connected state to find and cache the correct grants to use for the request.

A Permissions API which implements `request`, `grant`, `queryRequests`, and `queryGrants` that a user can utilize

The `Web5` permissions api introduces 3 helper classes to represent permissions:
 Class to represent a permission request record. It implements convenience methods similar to the `Record` class where you can `store()`, `import()` or `send()` the underlying request record. Additionally a `grant()` method will create a `PermissionGrant` object.

 Class to represent a grant record. It implements convenience methods similar to the `Record` class where you can `store()`, `import()` or `send()` the underlying grant record. Additionally a `revoke()` method will create a `GrantRevocation` object, and `isRevoked()` will check if the underlying grant has been revoked.

 Class to represent a permission grant revocation record. It implements convenience methods similar to the `Record` class where you can `store()`  or `send()` the underlying revocation record.

.changeset/blue-roses-cough.md

@@ -0,0 +1,8 @@
+---
+"@web5/agent": minor
+"@web5/identity-agent": minor
+"@web5/proxy-agent": minor
+"@web5/user-agent": minor
+---
+
+Add ability to Sync a subset of protocols as a delegate

.changeset/green-dolls-provide.md

@@ -0,0 +1,5 @@
+---
+"@web5/api": minor
+---
+
+Finalize ability to WalletConnect with sync involved

audit-ci.json

@@ -5,6 +5,7 @@
     "ip",
     "mysql2",
     "braces",
-    "GHSA-rv95-896h-c2vc"
+    "GHSA-rv95-896h-c2vc",
+    "GHSA-952p-6rrq-rcjv"
   ]
 }

packages/agent/src/cached-permissions.ts

@@ -0,0 +1,66 @@
+import { TtlCache } from '@web5/common';
+import { AgentPermissionsApi } from './permissions-api.js';
+import { Web5Agent } from './types/agent.js';
+import { PermissionGrantEntry } from './types/permissions.js';
+import { DwnInterface } from './types/dwn.js';
+
+export class CachedPermissions {
+
+  /** the default value for whether a fetch is cached or not */
+  private cachedDefault: boolean;
+
+  /** Holds the instance of {@link AgentPermissionsApi} that helps when dealing with permissions protocol records */
+  private permissionsApi: AgentPermissionsApi;
+
+  /** cache for fetching a permission {@link PermissionGrant}, keyed by a specific MessageType and protocol */
+  private cachedPermissions: TtlCache<string, PermissionGrantEntry> = new TtlCache({ ttl: 60 * 1000 });
+
+  constructor({ agent, cachedDefault }:{ agent: Web5Agent, cachedDefault?: boolean }) {
+    this.permissionsApi = new AgentPermissionsApi({ agent });
+    this.cachedDefault = cachedDefault ?? false;
+  }
+
+  public async getPermission<T extends DwnInterface>({ connectedDid, delegateDid, delegate, messageType, protocol, cached = this.cachedDefault }: {
+    connectedDid: string;
+    delegateDid: string;
+    messageType: T;
+    protocol?: string;
+    cached?: boolean;
+    delegate?: boolean;
+  }): Promise<PermissionGrantEntry> {
+    // Currently we only support finding grants based on protocols
+    // A different approach may be necessary when we introduce `protocolPath` and `contextId` specific impersonation
+    const cacheKey = [ connectedDid, delegateDid, messageType, protocol ].join('~');
+    const cachedGrant = cached ? this.cachedPermissions.get(cacheKey) : undefined;
+    if (cachedGrant) {
+      return cachedGrant;
+    }
+
+    const permissionGrants = await this.permissionsApi.fetchGrants({
+      author  : delegateDid,
+      target  : delegateDid,
+      grantor : connectedDid,
+      grantee : delegateDid,
+    });
+
+    // get the delegate grants that match the messageParams and are associated with the connectedDid as the grantor
+    const grant = await AgentPermissionsApi.matchGrantFromArray(
+      connectedDid,
+      delegateDid,
+      { messageType, protocol },
+      permissionGrants,
+      delegate
+    );
+
+    if (!grant) {
+      throw new Error(`CachedPermissions: No permissions found for ${messageType}: ${protocol}`);
+    }
+
+    this.cachedPermissions.set(cacheKey, grant);
+    return grant;
+  }
+
+  public async clear(): Promise<void> {
+    this.cachedPermissions.clear();
+  }
+}

packages/agent/src/dwn-api.ts

@@ -5,6 +5,7 @@ import {
   DataStoreLevel,
   Dwn,
   DwnConfig,
+  DwnInterfaceName,
   DwnMethodName,
   EventLogLevel,
   GenericMessage,
@@ -23,8 +24,11 @@ import type {
   DwnMessageInstance,
   DwnMessageParams,
   DwnMessageReply,
+  DwnMessagesPermissionScope,
   DwnMessageWithData,
+  DwnPermissionScope,
   DwnRecordsInterfaces,
+  DwnRecordsPermissionScope,
   DwnResponse,
   DwnSigner,
   MessageHandler,
@@ -70,6 +74,14 @@ export function isRecordsType(messageType: DwnInterface): messageType is DwnReco
     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

packages/agent/src/index.ts

@@ -8,6 +8,7 @@ export type * from './types/sync.js';
 export type * from './types/vc.js';
 
 export * from './bearer-identity.js';
+export * from './cached-permissions.js';
 export * from './crypto-api.js';
 export * from './did-api.js';
 export * from './dwn-api.js';

packages/agent/src/store-data.ts

@@ -165,7 +165,7 @@ export class DwnDataStore<TStoreObject extends Record<string, any> = Jwk> implem
 
     // If the write fails, throw an error.
     if (!(message && status.code === 202)) {
-      throw new Error(`${this.name}: Failed to write data to store for: ${id}`);
+      throw new Error(`${this.name}: Failed to write data to store for ${id}: ${status.detail}`);
     }
 
     // Add the ID of the newly created record to the index.

packages/agent/src/sync-api.ts

@@ -1,4 +1,4 @@
-import type { SyncEngine } from './types/sync.js';
+import type { SyncEngine, SyncIdentityOptions } from './types/sync.js';
 import type { Web5PlatformAgent } from './types/agent.js';
 
 export type SyncApiParams = {
@@ -41,10 +41,14 @@ export class AgentSyncApi implements SyncEngine {
     this._syncEngine.agent = agent;
   }
 
-  public async registerIdentity(params: { did: string; }): Promise<void> {
+  public async registerIdentity(params: { did: string; options: SyncIdentityOptions }): Promise<void> {
     await this._syncEngine.registerIdentity(params);
   }
 
+  public sync(direction?: 'push' | 'pull'): Promise<void> {
+    return this._syncEngine.sync(direction);
+  }
+
   public startSync(params: { interval: string; }): Promise<void> {
     return this._syncEngine.startSync(params);
   }