decentralized-identity · dcrousso · Mar 29, 2023 · Apr 3, 2023 · Apr 3, 2023 · Apr 3, 2023
@@ -249,6 +249,15 @@ Controls whether to prompt the user to start a new connection if a connection ha
 
 Defaults to `false`.
 
+
+##### **`permissionRequests`**
+
+Allows for restricting the scope of access to the underlying DWeb Node.
+
+If provided, `permissionRequests` must be an array of [`scope`](https://identity.foundation/decentralized-web-node/spec/#permissionsrequest) objects.
+
+Defaults to `undefined`.
+
 #### **Events**
 
 After calling `connect`, at least one of the following events will be dispatched on the `Web5` instance:
@@ -301,7 +310,99 @@ document.querySelector('#connect_button').addEventListener('click', async event
     console.error(event);
   });
 
-  web5.connect();
+  web5.connect({
+    permissionRequests: [
+      {
+        interface: 'Records',
+        method: 'Write',
+        protocol: 'https://decentralized-music.org/protocol'
+      }
+    ]
+  });
+});
+```
+
+### **`web5.changePermissions(permissionRequests)`**
+
+Enables an app to change the permissions of their connection to a user's local identity app, or an in-app DID to represent the user (e.g. if the user does not have an identity app).
+
+> NOTE: This method **_MUST_** be called _after_ `web5.connect()`.
+
+#### **`permissionRequests`**
+
+Allows for restricting the scope of access to the underlying DWeb Node.
+
+`permissionRequests` must be an array of [`scope`](https://identity.foundation/decentralized-web-node/spec/#permissionsrequest) objects.
+
+> NOTE: `permissionRequests` are not additive, so all desired permissions must be provided together.
+
+#### **Events**
+
+After calling `changePermissions`, at least one of the following events will be dispatched on the `Web5` instance:
+
+##### **`'open'`**
+
+A `'open'` event is dispatched if a local identity app is found, containing a verification pin and port number used for the connection.
+
+- **`event.detail.pin`**  - *`number`*: 1-4 digit numerical code that must be displayed to the user to ensure they are connecting to the desired local identity app.
+
+##### **`'change'`**
+
+A `'change'` event is dispatched if the user accepts the change.
+
+##### **`'close'`**
+
+A `'close'` event is dispatched if the user refuses to accept or respond to the change attempt for any reason.
+
+##### **`'error'`**
+
+An `'error'` event is dispached if anything goes wrong (e.g. `Web5` was unable to find any local identity apps).
+
+#### **Example** 
+
+```javascript
+document.querySelector('#connect_button').addEventListener('click', async event => {
+
+  event.preventDefault();
+
+  const web5 = new Web5();
+
+  web5.addEventListener('open', (event) => {
+    const { pin } = event.detail
+    document.querySelector('#pin_code_text').textContent = pin;
+  });
+
+  web5.addEventListener('change', (event) => {
+    alert('Change succeeded!');
+  });
+
+  web5.addEventListener('close', (event) => {
+    alert('Change was denied');
+  });
+
+  web5.addEventListener('error', (event) => {
+    console.error(event);
+  });
+
+  web5.changePermissions([
+    {
+      interface: 'Records',
+      method: 'Write',
+      protocol: 'https://decentralized-music.org/protocol'
+    },
+    {
+      interface: 'Records',
+      method: 'Write',
+      protocol: 'https://decentralized-music.org/protocol',
+      schema: 'https://decentralized-music.org/protocol/playlist'
+    },
+    {
+      interface: 'Records',
+      method: 'Write',
+      protocol: 'https://decentralized-music.org/protocol',
+      schema: 'https://decentralized-music.org/protocol/track'
+    }
+  ]);
 });
 ```
 

@@ -39,6 +39,7 @@
 
 <body style="background: #000; color: #fff;">
   <button type="button" id="connect_button">DID Connect</button>
+  <button type="button" id="update_button">DID Update</button>
   <div>
     <span>Security Code: </span><strong id="security_code"></strong>
   </div>
@@ -246,6 +247,9 @@
     myDid = event.detail.did;
     alert('Connection succeeded!');
   });
+  web5.addEventListener('change', (event) => {
+    alert('Update succeeded!');
+  });
   web5.addEventListener('close', (event) => {
     alert('Connection was denied');
   });
@@ -256,7 +260,35 @@
   connect_button.addEventListener('click', async event => {
     event.preventDefault();
 
-    web5.connect();
+    web5.connect({
+      permissionRequests: [
+        { interface: 'Records', method: 'Write', schema: 'foo/text' },
+        { interface: 'Records', method: 'Query', schema: 'foo/text' },
+        { interface: 'Records', method: 'Write', protocol: 'test', schema: 'test/post' },
+        { interface: 'Records', method: 'Query', protocol: 'test', schema: 'test/post' }
+      ]
+    });
+  });
+
+  update_button.addEventListener('click', async event => {
+    event.preventDefault();
+
+    web5.changePermissions([
+      { interface: 'Records', method: 'Write', schema: 'foo/text' },
+      { interface: 'Records', method: 'Query', schema: 'foo/text' },
+      { interface: 'Records', method: 'Write', schema: 'foo/json' },
+      { interface: 'Records', method: 'Query', schema: 'foo/json' },
+      { interface: 'Records', method: 'Write', schema: 'foo/avatar' },
+      { interface: 'Records', method: 'Query', schema: 'foo/avatar' },
+      { interface: 'Records', method: 'Write', protocol: 'test', schema: 'test/post' },
+      { interface: 'Records', method: 'Query', protocol: 'test', schema: 'test/post' },
+
+      // tests for permissions UI
+      { interface: 'Records', method: 'Write', schema: 'https://json-schema.org/learn/examples/address.schema.json' },
+      { interface: 'Records', method: 'Write', schema: 'https://json-schema.org/learn/examples/calendar.schema.json' },
+      { interface: 'Records', method: 'Write', schema: 'https://json-schema.org/learn/examples/card.schema.json' },
+      { interface: 'Records', method: 'Write', schema: 'https://json-schema.org/learn/examples/geographical-location.schema.json' }
+    ]);
   });
 
   async function logConsole(obj, message = '') {