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 MATIC
tokens to fund the transaction.
User's are identified by their Ethereum public key address. It is these addresses that are given permission to read/write/edit streams.
- The user that created the stream typically has all stream permissions.
- Stream permissions can be modified using the Streamr SDK or with the Streamr user interface
Here is the full list of permissions a user may have on a stream:
Permission | User can |
---|---|
PUBLISH | Publish data to a stream (write) |
SUBSCRIBE | Subscribe to stream (read) |
EDIT | Edit the stream details |
DELETE | Delete the stream |
GRANT | Share 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 = [
{ user: '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,
user: '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({
user: '0x12345...',
permissions: [StreamPermission.PUBLISH],
});
Revoke permission from a user
await stream.revokePermissions({
user: '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
andSUBSCRIBE
stream permissions can be made public, meaning that anyone couldSUBSCRIBE
and/orPUBLISH
to the stream. - If a stream has public
SUBSCRIBE
permissions, it means that anyone canSUBSCRIBE
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: [
{
user: '0x11111...',
permissions: [StreamPermission.EDIT]
}, {
user: '0x22222...'
permissions: [StreamPermission.GRANT]
}, {
public: true,
permissions: [StreamPermission.PUBLISH, StreamPermission.SUBSCRIBE]
}
]
})