Authorisation: Key Group
While this section is almost fully complete and even implemented, it might be a little rough at the edges: We're still working on a fun to use high-level API!
key_group schema is a way to group a set of public keys so that they can act as a single identity. Every member key can have different permissions limiting the extent to which they can publish operations as this single identity. Keys can only be added to a key group with a confirmation from both the key itself and an existing member key with the according permissions. Key groups can also be extended with other key groups, which extends the set of keys in the former with those from the latter. Key groups can serve as a building block for many other concepts in p2panda including identity (handles/usernames), multi-device usage, permissions and moderation.
- A key group can be created using a key pair.
- A key can be added to a key group, making it a member.
- A key can be removed from a key group.
- A key group can be added to a key group, making it a member.
- Specific permissions can be defined for members of a key group.
- A membership can be limited to publishing operations in specific schemas.
- A membership can be limited to specific operation actions (e.g. excluding
DELETEactions). 8- Specific permissions can be defined for individual keys of a key group.
- Developers can make key groups the owners of a schema's documents by creating an authorised schema.
- Key group members can publish operations for documents that define the key group as their owner.
- Key group members can not publish operations for that key group's documents when their key group membership doesn't define the required permissions.
- Authorised schemas define a key group as the owner of documents created with them.
- Use an authorised schema when you want to enable all key group members with according permissions to update or delete that document.
- Documents created from authorised schemas are called authorised documents.
- Schemas are authorised schemas if they contain a single field of type
- either the document view id of a key group,
- or the document view id of another authorised document.
- Every document of an authorised schema has a set of authorised public keys. This set can be created by looking at the document pointed at by the
- if it points at an authorised document, continue from there
- if a key group is found: that key group's keys are the document's authorised public keys.
- Operations of authorised schemas are only materialised if they were created by a key pair included in the authorised public keys of the operations's document and if that key pair membership has the required permissions for the operation.
- The name of a key group should be chosen so that its purpose can be understood.
By adding an
inverse: boolean field here we could allow a) anyone to change a document (wow chaos) b) exclude specific keys from editing a document.
? member: owner(key_group_v1)
A key group membership request is created in order to add its authoring public key to a key group. It says "Hey! Would you mind adding me to this key group?"
member field allows specifying a key group that requests membership instead of the public key that published this operation. A key group membership request that defines a
member should only be considered valid if its authoring public key has a membership in that key group with
can_authorise set to
member is defined and the membership has
can_authorise set to false, the member key group can still change the key set of the parent key group by changing its own members. This could be prevented by making
member a pinned relation.
# defines the owner of this membership
# points at the original membership request
# if set, limit this membership to the schema id specified
? schema: string
# set true to accept the request, can be set to `false` with a later update
# if true, this membership can authorise membership requests for the key group, add the key group to other key groups and edit membership limits.
# if true, this membership can create documents owned by the key group
# if true, this membership can update documents owned by the key group
# if true, this membership can delete documents owned by the key group
A key group membership is created to accept or reject a group membership request.
If accepted, the public key that created the key group membership request is now included in the key group's key set. If the membership request defines a
member key group, that key group's key set is included instead.
If rejected, all key group membership requests by the same public key and the same
member value should be considered invalid.
Schema Field Definition: Field Type
- The field definition looks similar to
- The schema id this relation references must be an authorised schema. Any schema field definition for which this does not hold is invalid.
Example: Chat Schema
In this example we want to represent chat messages and their authors. Authors should have a name and a profile picture. We also want to make sure that only key pairs controlled by the author can publish chat messages that are linked to the auth(or)'s name and picture.
Instances of the new
account schema have an
owner pointing at a key group that contains all public keys of a user and a
picture that contains the profile picture as a base64-encoded
We can use the name field on the key group as an account user name.
Because it has an
owner, operations for this
account schema are only valid if they are signed by one of the keys contained in the key group referred to in the
Now we can create the schema for chat messages. It combines the chat message's content with a link to an instance of the
Again, because this uses
owner, operations for this schema are only valid when signed by one of the keys referred to by the
How could a query for this schema look like? This is a GraphQL schema for a query that retrieves
chat-message instances, as well as the name and picture of their authors.