Skip to main content

Permissions

Stream permissioning relates to who gets to read, write and edit streams on the Network. This access control is enforced by the on-chain stream registry. Since every permission update is a modification to the on-chain registry, it requires a small amount of POL tokens to fund the transaction.

Users on Streamr have a cryptographic Identity, specified by a public/private key pair. It is such keys that are given permission to read/write/edit streams.

Good to know:

Here is the full list of permissions a user may have on a stream:

PermissionUser can
PUBLISHPublish data to a stream (write)
SUBSCRIBESubscribe to stream (read)
EDITEdit the stream details
DELETEDelete the stream
GRANTShare stream permissions

Querying stream permissions​

Using the Streamr SDK, the full list of permissions for a stream can be queried as follows:

const permissions = await stream.getPermissions();

The returned value is an array of permissions containing an item for each user, and possibly one for public permissions:

permissions = [
  { userId: '0x12345...', permissions: ['subscribe', 'publish'] },
  { public: true, permissions: ['subscribe'] },
];

You can query the existence of a user's permission with hasPermission(). Usually you want to use allowPublic: true flag so that the existence of a public permission is also checked:

await stream.hasPermission({
    permission: StreamPermission.PUBLISH,
    userId: '0x12345...',
    allowPublic: true
}

You can import the StreamPermission enum with:

const { StreamPermission } = require('@streamr/sdk');

StreamPermission.PUBLISH;
StreamPermission.SUBSCRIBE;
StreamPermission.EDIT;
StreamPermission.DELETE;
StreamPermission.GRANT;

You may also use the Streamr CLI tool to query permissions

Grant & revoke user permissions​

Grant publish permission to a user​

await stream.grantPermissions({
  userId: '0x12345...',
  permissions: [StreamPermission.PUBLISH],
});

Revoke permission from a user​

await stream.revokePermissions({
  userId: '0x12345...',
  permissions: [StreamPermission.PUBLISH],
});

Grant & revoke public permission​

A stream that is publicly readable is typically referred to as a public stream, but it doesn't necessasily mean its publicly writable. On the other hand, streams referred to as private maintain a set of publishers and subscribers whereas public streams do not. Regardless of the type of stream, every data point pushed to a stream is always signed by the private key of the publisher.

  • The PUBLISH and SUBSCRIBE stream permissions can be made public, meaning that anyone could SUBSCRIBE and/or PUBLISH to the stream.
  • If a stream has public SUBSCRIBE permissions, it means that anyone can SUBSCRIBE to that stream.
  • Public PUBLISH permission is typically not recommended as it means anyone could write data to your stream.

Grant public permission to subscribe​

await stream.grantPermissions({
  public: true,
  permissions: [StreamPermission.SUBSCRIBE],
});

Revoke public permission to subscribe​

await stream.revokePermissions({
  public: true,
  permissions: [StreamPermission.SUBSCRIBE],
});

Set multiple permissions​

The method streamr.setPermissions can be used to set an exact set of permissions for one or more streams. Note that if there are existing permissions for the same users in a stream, the previous permissions are overwritten. Also note that this method cannot be used on the stream object, but via the Streamr instance.

await streamr.setPermissions({
    streamId,
    assignments: [
        {
            userId: '0x11111...',
            permissions: [StreamPermission.EDIT]
        }, {
            userId: '0x22222...'
            permissions: [StreamPermission.GRANT]
        }, {
            public: true,
            permissions: [StreamPermission.PUBLISH, StreamPermission.SUBSCRIBE]
        }
    ]
})