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

#### `PermissionsApi`
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.

#### `dwn.connected`
A Private API usedin a connected state to find and cache the correct grants to use for the request.

#### `dwn.permissions`
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:
#### `PermissionRequest`
 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.
 
#### `PermissionGrant`
 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.

#### `GrantRevocation`
 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/gold-lamps-obey.md

@@ -0,0 +1,5 @@
+---
+"@web5/api": patch
+---
+
+Introduce a `grants` API for `Web5.dwn`

.changeset/polite-days-wash.md

@@ -0,0 +1,8 @@
+---
+"@web5/identity-agent": patch
+"@web5/proxy-agent": patch
+"@web5/user-agent": patch
+"@web5/agent": patch
+---
+
+Introduce a `PermissionsApi` for Web5Agents

packages/agent/src/dwn-api.ts

@@ -2,7 +2,6 @@ import type { Readable } from '@web5/common';
 
 import {
   Cid,
-  DataEncodedRecordsWriteMessage,
   DataStoreLevel,
   Dwn,
   DwnConfig,
@@ -11,10 +10,6 @@ import {
   GenericMessage,
   Message,
   MessageStoreLevel,
-  PermissionGrant,
-  PermissionScope,
-  PermissionsProtocol,
-  RecordsWrite,
   ResumableTaskStoreLevel
 } from '@tbd54566975/dwn-sdk-js';
 
@@ -449,43 +444,4 @@ export class AgentDwnApi {
 
     return dwnMessageWithBlob;
   }
-
-  /**
-   * NOTE EVERYTHING BELOW THIS LINE IS TEMPORARY
-   * TODO: Create a `grants` API to handle creating permission requests, grants and revocations
-   * */
-
-  public async createGrant({ grantedFrom, dateExpires, grantedTo, scope, delegated }:{
-    dateExpires: string,
-    grantedFrom: string,
-    grantedTo: string,
-    scope: PermissionScope,
-    delegated?: boolean
-  }): Promise<{
-    recordsWrite: RecordsWrite,
-    dataEncodedMessage: DataEncodedRecordsWriteMessage,
-    permissionGrantBytes: Uint8Array
-  }> {
-    return await PermissionsProtocol.createGrant({
-      signer: await this.getSigner(grantedFrom),
-      grantedTo,
-      dateExpires,
-      scope,
-      delegated
-    });
-  }
-
-  public async createRevocation({ grant, author }:{
-    author: string,
-    grant: PermissionGrant
-  }): Promise<{
-    recordsWrite: RecordsWrite,
-    dataEncodedMessage: DataEncodedRecordsWriteMessage,
-    permissionRevocationBytes: Uint8Array
-  }> {
-    return await PermissionsProtocol.createRevocation({
-      signer: await this.getSigner(author),
-      grant,
-    });
-  }
 }

packages/agent/src/index.ts

@@ -3,18 +3,19 @@ export * from './types/dwn.js';
 export type * from './types/identity.js';
 export type * from './types/identity-vault.js';
 export type * from './types/key-manager.js';
+export type * from './types/permissions.js';
 export type * from './types/sync.js';
 export type * from './types/vc.js';
 
 export * from './bearer-identity.js';
 export * from './crypto-api.js';
 export * from './did-api.js';
 export * from './dwn-api.js';
-export * from './dwn-permissions-util.js';
 export * from './dwn-registrar.js';
 export * from './hd-identity-vault.js';
 export * from './identity-api.js';
 export * from './local-key-manager.js';
+export * from './permissions-api.js';
 export * from './rpc-client.js';
 export * from './store-data.js';
 export * from './store-did.js';