Interaction Controls

Often, it is desirable to post a Note, but control who is allowed to interact with it (e.g. send replies, like, dislike, etc.). This has traditionally not been possible in most federated networks: the Interaction Controls extension adds this possibility.

Usage

The entity defined in this document must be inserted in the pub.versia:interaction_controls key of a Note's extensions field.

Example Usage

{
    "id": "456df8ed-daf1-4062-abab-491071c7b8dd",
    "type": "Note",
    "created_at": "2024-04-09T01:38:51.743Z",
    "content": {
        "text/plain": {
            "content": "Hello, world :happy_face:!"
        }
    },
    ...
    "extensions": { 
        "pub.versia:interaction_controls": {
            "reply": {
                "allowed": ["followers"],
            },
        }
    }
}

Entity Definition

Name
interaction_type
Description
Describes permissions for a specific interaction.
type InteractionGroup = | "everyone" | "followers" | "followed" | "group" | "mutuals"; type InteractionPermissions = { allowed?: InteractionGroup[]; disallowed?: InteractionGroup[]; }
Permissions can either be whitelist (allowed property) or blacklist (disallowed property). Both options are mutually exclusive.
In order of priority:
- everyone: Includes every single User in the federation.
- mentioned: Includes every mentioned User.
- followers: Includes every follower of the author.
- following: Includes every User that the author follows.
- mutuals: Includes every mutual of the author (that is, every User that is both a follower and followed by the author).
- group: Includes every User in the Group that this Note was posted to, if any. If Note is not posted to a Group, this value has no effect.
Permission groups are evaluated from highest to lowest priority: if two groups conflict each other, the group with the highest priority must be used.

Example

{
    "reply": {
        "allowed": [
            "group"
        ],
    },
    "pub.versia:likes#Like": {
        "disallowed": [
            "everyone"
        ]
    }
}

Usage

Interaction Types

The following interaction types are defined as part of the core Versia spec:

reply: Sending a Note with replies_to including this Note.
quote: Sending a Note with quotes including this Note.

Extensions may choose to register their own interaction types (such as pub.versia:likes#Like for the Like Extension). The naming scheme for interaction types is identical to Extensions's type property, but with a hashtag (#) in place of a forward slash (/).

Handling Permission Errors

Implementations that find a user attempting to create an interaction they are not allowed to MAY return a 403 Forbidden HTTP status code when processing the Note during federation, or use the Instance Messaging extension. The Note must be discarded.

It is important for implementations to backfill any related Collections/URI Collections (e.g. user followers) in order to not incorrectly reject Notes based off of outdated data.

To avoid server load from constant Collection refreshing, implementations could only refetch associated Collections when forbidden interactions are detected, then recalculate permissions again.