fep

FEP-5219: Groups and permissions

Summary

This document describes a permission system for ActivityPub groups.

It is inspired by XEP-0045: Multi-User Chat, which defines a comprehensive permission system for XMPP group chats.

Motivation

The most widely used ActivityPub group implementation is described in FEP-1b12 (Group federation). That document was focused on public groups, and private FEP-1b12 groups were later proposed in Lemmy RFC-0005 (Private Communities). However, the mechanism for controlling user permissions in such groups has not been clearly defined.

This FEP formalizes the mechanisms that are already used in FEP-1b12 groups, and extends them to accommodate new group types, such as semi-private groups and group chats. It defines a new collection that allows consumers to read all permissions in a single pass. The proposed permission system can also be used in other contexts, such as when designating server moderators or establishing organizational hierarchies.

Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

Affiliation

Affiliation is a long-lived association with a group.

An affiliation can correspond to an individual privilege or to a bundle of privileges (e.g. “moderator”). The default set of affiliations includes:

It is also possible to have no affiliation with a group (none).

The group actor itself is considered to have an admin affiliation.

[!IMPORTANT] The operators of the server where a group actor is hosted have super-admin privileges because they can change any part of the group actor document, including its affiliations collection.

Affiliations can be specified using the affiliations collection attached to a Group actor. It is an ordered collection where each item is a Relationship object that represents a relationship between a user and a group. This object has the following fields:

The affiliations collection is sorted from most privilege to least privilege. When two actors have the same privileges but different power levels, the actor with a higher power level MUST be placed first.

Access to the affiliations collection MAY be limited if the group is not public.

When adding a Relationship for an affiliation that is not in the default set, a fallback representation SHOULD also be included. This fallback representation MUST specify an affiliation from the default set that has equal or fewer privileges compared to the custom affiliation.

After following a group, an actor MUST retrieve its affiliations collection. Further changes in affiliations will be announced using FEP-1b12 Announce activities.

Consumers MUST ignore relationships that represent unsupported affiliations.

Example of an affiliations collection:

{
  "id": "https://social.example/group/affiliations",
  "type": "OrderedCollection",
  "attributedTo": "https://social.example/group",
  "items": [
    {
      "id": "https://social.example/group/affiliations/1",
      "type": "Relationship",
      "attributedTo": "https://social.example/group",
      "subject": "https://social.example/alice",
      "object": "https://social.example/group",
      "relationship": "admin",
      "to": "https://www.w3.org/ns/activitystreams#Public"
    },
    {
      "id": "https://social.example/group/affiliations/2",
      "type": "Relationship",
      "attributedTo": "https://social.example/group",
      "subject": "https://social.example/bob",
      "object": "https://social.example/group",
      "relationship": "member",
      "to": "https://www.w3.org/ns/activitystreams#Public"
    }
  ],
  "to": "https://www.w3.org/ns/activitystreams#Public"
}

Participation

Participation refers to the ability to read or write to a group.

There are two levels of participation:

The participation status is distinct from affiliation. Affiliations MAY be preserved when users un-follow or leave the group.

A group where anyone can participate is a public group.

A group where only members can participate is a private group.

A group which anyone can follow but where only members can participate is a semi-private group.

To become a follower, a user sends a Follow activity to a group actor.

Group actors MUST have a followers property pointing to the collection of group followers.

To become a participant, a user sends a Join activity to a group actor. The Follow activity has the same side effects in public and private groups and MAY be used instead of Join.

Semi-private group actors MUST have a participants property pointing to the collection of group participants. In public and private groups, the collection of participants is identical to the collection of followers and the property MAY be omitted.

Group actors SHOULD have canView and canCreate properties:

Privileges

Privilege Activity Admin Moderator Member None Outcast
View posts in a public group - Yes Yes Yes Yes Yes
View posts in a semi-private group - Yes Yes Yes Yes Yes
View posts in a private group - Yes Yes Yes No No
Create posts in a public group Create Yes Yes Yes Yes No
Create posts in a semi-private group Create Yes Yes Yes No No
Create posts in a private group Create Yes Yes Yes No No
Remove posts of other participants Delete Yes Yes No No No
Remove participants Reject Yes Yes No No No
Ban participants Block Yes Yes No No No
Add or remove members Grant or Revoke Yes Yes No No No
Add or remove moderators Grant or Revoke Yes No No No No
Update group metadata Update Yes No No No No
Delete group Delete Yes No No No No

This list of privileges is not exhaustive. Additional privileges MAY be associated with the affiliations from the default set.

A privilege MAY be represented as a custom affiliation.

All participants are allowed to update and delete their own posts, and to remove themselves from the group. Actions that affect other participants MAY be authorized if the actor has the necessary privileges.

Activities

Addressing

Group activities (such as FEP-1b12 Announce activities) are normally addressed to the group’s followers collection or to its participants collection.

However, activities can also be addressed to actors with a specific affiliation (e.g. to administrators).

A group actor MAY advertise these collections using the audiences property. The value of this property is a map where keys are affiliation names and values are collection identifiers.

Example:

{
  "id": "https://social.example/group",
  "type": "Group",
  "audiences": {
    "admin": "https://social.example/group/admins",
    "moderator": "https://social.example/group/moderators",
    "member": "https://social.example/group/members"
  }
}

Managing affiliations

The affiliations collection is modified using Grant and Revoke activities.

A Grant activity MUST have the following properties:

Example:

{
  "id": "https://social.example/activities/1",
  "type": "Grant",
  "actor": "https://social.example/group",
  "relationship": "member",
  "target": "https://social.example/bob",
  "result": {
    "id": "https://social.example/group/affiliations/2",
    "type": "Relationship",
    "attributedTo": "https://social.example/group",
    "subject": "https://social.example/bob",
    "object": "https://social.example/group",
    "relationship": "member",
    "to": "https://www.w3.org/ns/activitystreams#Public"
  },
  "to": "https://social.example/group/followers"
}

A Revoke activity MUST have the following properties:

Example:

{
  "id": "https://social.example/activities/2",
  "type": "Revoke",
  "actor": "https://social.example/group",
  "relationship": "member",
  "target": "https://social.example/bob",
  "to": "https://social.example/group/followers"
}

Compatibility

The affiliations collection supersedes the collection of moderators defined in FEP-1b12. Actors in this collection have an admin affiliation.

Consumers MUST use the affiliations collection when both collections are present.

Add and Remove activities targeting FEP-1b12 moderators collection are equivalent to Grant and Revoke activities where the value of a relationship property is admin.

The canView and canCreate properties supersede the manuallyApprovesFollowers and postingRestrictedToMods properties.

If the value of the manuallyApprovesFollowers property on a group actor is true, this MUST be interpreted as an indicator of a private group.

If the value of the postingRestrictedToMods property on a group actor is true, this MAY be interpreted as an indicator of a semi-private group.

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.