Documentation » ActivityPub » Groups, events, and invitations

Groups are like users, except they can't follow anything. Groups have walls that work the same way as user walls. Both Join and Follow activities work for joining groups, as well as Leave and Undo{Follow} for leaving. Outgoing activities are Follow and Undo{Follow} in order to maximize the compatibility.

Groups have administrators that are listed in the attributedTo field:

  "attributedTo": [
    {
      "type": "Person",
      "title": "Group admins can have user-visible titles",
      "id": "http://smithereen.local:8080/users/1"
    }
  ]

These links must point to a Person object and will be ignored otherwise.

Any actions of the group administrators are federated as if the group actor itself performed them.

A group has one of three access types, specified in sm:accessType field:

  • open: all content is public. Anyone can join and/or participate (unless blocked, of course). Joining the group is not required to post in it or interact with its content. This also is the default if no sm:accessType field is present.
  • closed: the profile and the member list are public, but the content is private and visible to members only. You become a member after either sending a join request that is then manually reviewed and accepted by the group staff (the usual Join/Accept{Join} flow) or being invited by an existing group member (see below for the group invitations).
  • private: nothing is public, including the profile. The only way to join is to be invited. Also, only group staff can send invitations.

Access control in non-public groups

To control access to the content in closed and private groups, Smithereen employs two mechanisms: signed GET requests and so-called "actor tokens".

To fetch an object from the server that hosts the group (including the Group actor itself for private groups), you need to sign your GET request with an HTTP signature using the key of any actor from a server that has members in the group. Smithereen itself always uses the service actor for this purpose, /activitypub/serviceActor. The rationale for this is that most ActivityPub servers only fetch and store a single copy of each object for all users to whom it may concern, and are responsible themselves for enforcing the visibility rules, if any, either way.

The process of fetching an object from other server involves an actor token. An actor token is a cryptographically signed temporary proof of membership in a group. Since it would be impractical to provide a revocation mechanism, an actor token has a limited validity time in order to account for cases when someone has left a group or was removed from it. It is a JSON object with the following fields:

  • issuer: ID of the actor that generated this token
  • actor: ID of the actor that the token is issued to (and must be presented with a valid HTTP signature of)
  • issuedAt: timestamp when the token was generated, ISO-8601 instant (same format as ActivityPub timestamps)
  • validUntil: timestamp when the token expires, ISO-8601 instant
  • signatures: array of signature objects, currently with only one possible, and required, element defined:
    • algorithm: must be the string rsa-sha256
    • keyId: key ID, same as in HTTP signatures (e.g. https://example.com/groups/1#main-key)
    • signature: the RSA-SHA256 signature itself encoded as base64, see below for details

To obtain an actor token, make a signed GET request to the endpoint specified in sm:actorToken under endpoints in the actor object.

To use an actor token when fetching an object, pass it as Authorization: ActivityPubActorToken {...} HTTP header.

To generate a source string for signature:

  1. Iterate over the keys in the actor token JSON object, skipping signature, and transform them into the format key: value. Add these strings to an array.
  2. Sort the resulting array lexicographically.
  3. Join the strings with newline character (\n, U+000A).
  4. Convert the resulting string to a UTF-8 byte array.

To generate an actor token:

  1. Verify that the requesting actor, as per HTTP signature, has access to the group (there are members with the same domain). If it does not, return a 403 error and stop.
  2. Create a JSON object with the fields above (except signature). It is recommended that the validity period is 30 minutes, and it must not exceed 2 hours.
  3. Generate a signature source string as above, sign it, and wrap it into an object with signature, algorithm, and keyId fields.
  4. Add the object as a single element in the signatures array.

To verify an actor token:

  1. Check that the HTTP signature is valid, and that actor in the token object matches the actor ID from keyId in the HTTP signature.
  2. In the signatures array, find an object that has algorithm set to rsa-sha256 to get the signature value. If there isn't any, return a 403 and stop.
  3. Check the validity time: issuedAt must be in the past, validUntil must be in the future, and the difference between them must not exceed 2 hours. It is recommended to apply some margin to these checks to account for imprecisely set clocks. Smithereen uses 5 minutes.
  4. Generate the signature source string as above and verify the signature.
  5. Check that the object the requester is accessing is, in fact, part of a collection owned by issuer.

Events & tentative membership

An event is an extension of group. An event is identified as such by having an Event object in its attachments:

{
  "type": "Group",
  "id": "https://friends.grishka.me/groups/70",
  "attachment": [
    {
      "type": "Event",
      "startTime": "2022-07-15T09:00:00Z"
    }
  ],
  "name": "Встреча с Гришкой в Макдональдсе",
  /* ... more fields ... */
}

The Event object must have startTime and may have endTime.

Events can only have either open or private access type. It is possible to join an event tentatively ("I'm not sure I will attend"). Tentative membership adds the following:

  • sm:tentativeMembers collection in the actor. Contains tentative members.
  • sm:TentativeJoin activity type:
    • For non-members, joins them to the event tentatively and accepts invitation, if any.
    • For members, changes their decision by moving them from followers to sm:tentativeMemebers. (The reverse is done with regular Join/Follow.)
  • sm:tentativeMembership element in litepub:capabilities to indicate support for this feature.

Invitations

It is possible to invite a friend (i.e. mutual follow) to a group by sending an Invite{Group} activity both to the group and to the user (there will be a privacy setting for this in the future).

  • Anyone can invite to a public group.
  • Only members can invite to a closed group.
  • Only staff (listed under attributedTo) can invite to a private group.

It is important to send a copy of the Invite activity to the group itself so the group knows to expect that person to join. This is especially important for non-public groups because they would not accept that join otherwise.

Group staff can cancel a pending invitation by sending Undo{Invite{Group}} to the invitee from the group actor. To accept the invitation, the invitee simply joins the group (Join/Follow/sm:TentativeJoin). To decline the invitation, the invitee sends a Reject{Invite{Group}} to the group actor.