Adding `PermissionsApi` to agent and `permissions()` api to `Web5.dwn` with the ability to select delegate grants for `Web5.dwn` #824

LiranCohen · 2024-08-05T21:15:36Z

This PR makes use of a mocked Web5Connect flow to process/store, select and use the grants when necessary.

I'm treating this as a first-pass, there will come more refactoring which will allow for connecting/exporting an existing Identity, selecting form multiple identities, requesting additional grants from a connected Did, etc.

If any of the provided grants during connect fail to process for whatever reason, all of the provided grants will be rolled back and the provided Identity will be cleaned up/deleted so that a subsequent Connect can be initiated.

Additionally this PR puts a bandaid on the multiple identities issue. It will simply default to the first identity in the array if multiple are provided instead of failing.
Unexpected error: Expected 1 but found 2 stored identities. When calling Web5.connect()

A syncManager implementation will come after this PR, some of the current tests manually shuffle/install permissions and protocol installations between logical DWNs. When syncManager is updated a one-shot sync will take place after processing the grants in order to get up-to-date with the connected protocols.
Implement Grants in SyncManger

This PR creates an experimental grant API in @web5/api, in a subsequent effort there will be a more well defined general purpose PermissionsApi that will likely live in the agent, and a better defined grant API within @web5/api that will allow creation of requests, grants and revocations as well as querying/selecting.
Concise Grants APIs

When using the dwn.records API with grants, providing a protocol in the params is needed. In a subsequent PR this property will be required for all records usage as we are moving away from "flat space" records without a protocol assigned. This will have a lot of breaking tests and docs so it is best to do it in it's own PR to avoid bloat/urgency.
Require protocol for dwn.records API #825

There should also be a separate effort to think about how both protocolPath scoped, as well as context scoped grants. More specifically the user would need to provide the contextId and/or protocolPath when issuing a records.read() or records.delete(), which don't normally have these properties. The records.delete() can be replaced with the delete() method now available on the logical Record object, which would help this, but read would still need to be provided a better way of selecting grants.
Grants for a specific Context/Path

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-bot · 2024-08-05T21:15:40Z

🦋 Changeset detected

Latest commit: 9ab0463

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@web5/api	Minor
@web5/identity-agent	Minor
@web5/proxy-agent	Minor
@web5/user-agent	Minor
@web5/agent	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2024-08-06T20:44:43Z

TBDocs Report

✅ No errors or warnings

@web5/api

Project entry file: packages/api/src/index.ts

@web5/crypto

Project entry file: packages/crypto/src/index.ts

@web5/crypto-aws-kms

Project entry file: packages/crypto-aws-kms/src/index.ts

@web5/dids

Project entry file: packages/dids/src/index.ts

@web5/credentials

Project entry file: packages/credentials/src/index.ts

TBDocs Report Updated at 2024-08-14T22:45:41Z 9ab0463

codecov · 2024-08-06T22:33:30Z

Codecov Report

Attention: Patch coverage is 99.80707% with 3 lines in your changes missing coverage. Please review.

Project coverage is 93.30%. Comparing base (ac08f55) to head (9ab0463).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #824      +/-   ##
==========================================
+ Coverage   93.05%   93.30%   +0.24%     
==========================================
  Files         112      115       +3     
  Lines       31323    32555    +1232     
  Branches     2437     2560     +123     
==========================================
+ Hits        29148    30374    +1226     
- Misses       2137     2143       +6     
  Partials       38       38

Components	Coverage Δ
agent	`86.88% <100.00%> (+0.18%)`	⬆️
api	`99.53% <100.00%> (+0.22%)`	⬆️
common	`98.68% <ø> (ø)`
credentials	`94.95% <ø> (ø)`
crypto	`93.88% <ø> (ø)`
dids	`97.77% <ø> (ø)`
identity-agent	`96.42% <90.90%> (-0.28%)`	⬇️
crypto-aws-kms	`100.00% <ø> (ø)`
proxy-agent	`96.42% <90.90%> (-0.28%)`	⬇️
user-agent	`96.42% <90.90%> (-0.28%)`	⬇️

LiranCohen · 2024-08-08T17:28:09Z

packages/agent/tests/dwn-permissions-util.spec.ts

@@ -106,19 +106,21 @@ describe('DwnPermissionsUtil', () => {

      const protocol = 'http://example.com/protocol';

-      await GrantsUtil.createRecordsGrants({
+      const deviceXRecordGrants = await GrantsUtil.createRecordsGrants({


Remove the reliance on fetchGrants from this test, as it's out of scope for the util.

packages/api/src/web5.ts

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.

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 usedin 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.

* 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.

LiranCohen force-pushed the lirancohen/grants-web5 branch 3 times, most recently from 8a1f7bd to da23b82 Compare August 5, 2024 21:56

Base automatically changed from lirancohen/permission-grant-signing to main August 6, 2024 20:24

LiranCohen force-pushed the lirancohen/grants-web5 branch from ded4c68 to 7f68c27 Compare August 6, 2024 20:42

LiranCohen force-pushed the lirancohen/grants-web5 branch 2 times, most recently from fd5fe7f to 43b51dd Compare August 8, 2024 16:54

LiranCohen commented Aug 8, 2024

View reviewed changes

LiranCohen marked this pull request as ready for review August 8, 2024 17:29

LiranCohen requested review from csuwildcat, shamilovtim, nitro-neal, thehenrytsai and diehuxx as code owners August 8, 2024 17:29

LiranCohen changed the title ~~[WIP] Using grants in DwnApi~~ Using grants in DwnApi for @web5/api with a WalletConnect flow Aug 8, 2024

shamilovtim reviewed Aug 8, 2024

View reviewed changes

packages/api/src/web5.ts Outdated Show resolved Hide resolved

shamilovtim reviewed Aug 8, 2024

View reviewed changes

packages/api/src/web5.ts Outdated Show resolved Hide resolved

LiranCohen requested review from frankhinek and mistermoe as code owners August 8, 2024 19:32

LiranCohen requested a review from shamilovtim August 8, 2024 19:33

LiranCohen mentioned this pull request Aug 12, 2024

PermissionsApi for Agent, permissions API for Web5 #833

Merged

LiranCohen force-pushed the lirancohen/grants-web5 branch from 0cd1698 to e93f109 Compare August 14, 2024 02:46

LiranCohen force-pushed the lirancohen/grants-web5 branch from 2b9391c to 22d86bd Compare August 14, 2024 13:27

LiranCohen changed the title ~~Using grants in DwnApi for @web5/api with a WalletConnect flow~~ Adding PermissionsApi to agent and permissions() api to Web5.dwn with the ability to select delegate grants for Web5.dwn Aug 14, 2024

first pass at connect flow and grants api

7066ab9

LiranCohen added 3 commits August 14, 2024 18:31

package lock update after rebase

bec2b03

add additional comments around the signer for the permissions DWN api

9ab0463

LiranCohen force-pushed the lirancohen/grants-web5 branch from 2f086dc to 9ab0463 Compare August 14, 2024 22:43

csuwildcat approved these changes Aug 19, 2024

View reviewed changes

LiranCohen merged commit 0862ffc into main Aug 19, 2024
35 checks passed

LiranCohen deleted the lirancohen/grants-web5 branch August 19, 2024 16:51

github-actions bot mentioned this pull request Aug 19, 2024

Version Packages #848

Merged

This was referenced Sep 11, 2024

Version Packages #900

Closed

Version Packages #902

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding `PermissionsApi` to agent and `permissions()` api to `Web5.dwn` with the ability to select delegate grants for `Web5.dwn` #824

Adding `PermissionsApi` to agent and `permissions()` api to `Web5.dwn` with the ability to select delegate grants for `Web5.dwn` #824

LiranCohen commented Aug 5, 2024 •

edited

Loading

changeset-bot bot commented Aug 5, 2024 •

edited

Loading

github-actions bot commented Aug 6, 2024 •

edited

Loading

codecov bot commented Aug 6, 2024 •

edited

Loading

LiranCohen Aug 8, 2024

Adding PermissionsApi to agent and permissions() api to Web5.dwn with the ability to select delegate grants for Web5.dwn #824

Adding PermissionsApi to agent and permissions() api to Web5.dwn with the ability to select delegate grants for Web5.dwn #824

Conversation

LiranCohen commented Aug 5, 2024 • edited Loading

changeset-bot bot commented Aug 5, 2024 • edited Loading

🦋 Changeset detected

github-actions bot commented Aug 6, 2024 • edited Loading

@web5/api

@web5/crypto

@web5/crypto-aws-kms

@web5/dids

@web5/credentials

codecov bot commented Aug 6, 2024 • edited Loading

Codecov Report

LiranCohen Aug 8, 2024

Choose a reason for hiding this comment

Adding `PermissionsApi` to agent and `permissions()` api to `Web5.dwn` with the ability to select delegate grants for `Web5.dwn` #824

Adding `PermissionsApi` to agent and `permissions()` api to `Web5.dwn` with the ability to select delegate grants for `Web5.dwn` #824

LiranCohen commented Aug 5, 2024 •

edited

Loading

changeset-bot bot commented Aug 5, 2024 •

edited

Loading

github-actions bot commented Aug 6, 2024 •

edited

Loading

codecov bot commented Aug 6, 2024 •

edited

Loading