Federation Design Plan

Problem

Currently, there is not a public plan for how federation is supposed to work. Various elements of federation have been discussed in the Fluxer Developers server, but all of these are theoretical. Federation will take a while to create properly. It will likely be a collaborative effort by many contributors, not just the core Fluxer dev team. An open process discussing the various pros/cons of certain elements of the federation process would be, in my view, the best approach. I've taken some time to plan out, at a very high level, how various elements of federation may want to work. This is based on conversations that took place with Fluxer Developers and my own rough thoughts. I should be clear: this does not reflect at all how the Fluxer devs are currently planning to implement federation. This is just based off of my own ideas and discussions I've observed/had in the Fluxer Developers channel. This is by no means complete or comprehensive. This is a work in progress for sure and doesn't consider all elements that should be considered in the design of Federation. I would love to have a discussion about all of these aspects and perhaps work with the community and the Fluxer Dev team to come up with an official set of features and an implementation plan for how federation will work.

Proposed solution

Federation Design Plan

Objective of Federation

The objective of federation within Fluxer is:

• To create an interconnected network of independently operated rich-media chat servers, where users across communities may interact with each other with as little friction as possible, while maintaining sovereignty over their own data.

It IS NOT to:

• Prevent government interference with the operation of an instance;

• Replicate data across a federated network in an effort to eliminate censorship altogether by making data impossible to delete once submitted; or

• Maintain complete anonymity and/or secrecy of conversations, attachments, or identities tied to user accounts.

Definitions

All capitalized terms not otherwise defined herein have the following meanings:

• “Foreign Guild” means a guild that is hosted on an Instance other than the Guild Instance.

• “Guest Instance” means an instance that is not the Home Instance of a particular user. There may be one or many Guest Instances that a user may connect to and participate in.

• “Guest User” means a user who is connected to and participating in, but whose account does not otherwise exist, on a particular Instance.

• “Guild Instance” means the Instance on which a guild was created.

• “Home Instance” means the Instance where the user’s account is created.

• “Home User” means a user who is connected to and participating in their Home Instance.

• “Instance” means a fully independent, self-hosted deployment of the Fluxer platform.

Authentication

• Each user connects to and authenticates with their Home Instance. A client will need to be told what Instance to authenticate against by way of the domain name.
• The domain of an Instance will have an SRV record that points to the API server and port of the particular Instance so that no configuration is necessary for the client.

• The format of a username will be name#[discriminator@domain.tld](mailto:discriminator@domain.tld). The @domain.tld can be elided within a local Instance only. The Instance will assume @domain.tld for any reference to a username without it already included.

Premium Features and Limits

• Certain profile premium features are Instance agnostic. This means that if the Home Instance has enabled these features for a user, they are visible anywhere across the federated space. The Instance agnostic premium features are:
  • Animated avatar
  • Animated banner
  • Custom discriminator
  • Custom notification sounds
  • Global expressions
  • Per-guild profiles
  • Voice entrance sounds

• Limits, as defined within the Home Instance, apply to a Home User only.

• Separate limits may be defined by an administrator to apply to Guest Users. A different set of limits can apply to Guest Users by applying different traits, the same as with Home Users. By default, unless configured differently, Guest Users receive the same limits as Home Users.

• Additional limits are to be added for federation purposes:
  • Can use reactions from other instances (yes or no)
  • Maximum number of cross-instance reactions per message
  • Maximum number of cross-instance users per direct message conversation

Guilds, Messages, Attachments, Uploads, Reactions

• Guilds are always housed on the creator’s Home Instance.

• In the case of a transfer of guild ownership to a Guest User, the guild would continue to remain on the Home Instance.
  • Optionally, an Instance administrator may prevent transferring guilds to Guest Users altogether. This is a setting on the Instance itself.

• All messages, attachments, and uploads are stored on the Guild Instance.

• A guild’s limits are defined by the limit rules of the Guild Instance in combination with the guild owner’s limits on the same Instance. For example, if a Guest User becomes the owner of a guild, the limits of the Guest User as set out in the Guild Instance would now apply.

• A Guest User’s upload limits, message lengths, embeds, reactions, etc., apply as defined in the Guild Instance for Guest Users.

• A Guest User may use, if permitted, reactions from Foreign Guilds. These reactions are linked on the message and the Guild Instance is responsible for looking them up and making them visible to target clients.
  • The reaction image itself will be cached on the Guild Instance if it meets file size requirements. Otherwise, the reaction will be removed from the message as it will be considered invalid.

Inter-Instance Communication

• With the exception of media and API requests, a user always communicates to other Instances through their Home Instance.
• Each Home Instance that has users who desire to connect to Guest Instances will establish a one or more inter-Instance communications channel to the Guest Instance. These channels will aggregate all traffic between two Instances that is normally reserved for the gateway, such as presence information, state updates, new messages, etc. Each Instance will then pass on the information relevant to a particular user through their individual gateway channel.
  • This approach prevents the need for each client to potentially create dozens of gateway connections if they are, for example, members of guilds across dozens of Instances.

• API requests (GETs/POSTs/etc.) will continue to happen with the client connecting directly to the API service of the Guest Instance and making the request.

• API requests to Guest Instances are authenticated using a bearer token signed by the Home Instance. The Guest Instance will validate the bearer token against the well-known signing keys of the Home Instance.

Guest User Accounts

• Each Guest User connecting to a Guest Instance, provided that federation is permitted and the Guest User may access the Guest Instance, will automatically have a local account created for them.

• This local account will have its own user ID and other information based on claims provided by the Home Instance.

• This local account may be deleted, disabled, or moderated like any other Home User account, by the Guest Instance administrators. A disabled account will prevent that user from connecting to the Instance.

• All messages sent and all attachments uploaded, are tied to this local account.

Direct Messages

• DMs are replicated on both the Guest Instance and the Home Instance. Each Instance will independently have a snapshot of the contents of each Direct Message. In the case of group DMs, the messages are replicated across all participating Instances.

• For attachments, the uploading user’s Home Instance stores the attachment. Each participating Instance replicates only the target media URL of the Home Instance, thus directing clients to the poster’s Home Instance to retrieve the attachment.

• A user will only send a POST request to the API service of their Home Instance to send a message. The Home Instance will use its inter-server communications channel to deliver the message to all the other Instances involved in the DM chat.

Federation Whitelist/Blacklist

• Federation is disabled by default. This prevents users from: (1) connecting to Foreign Guilds; or (2) receiving connections from Guest Users.

• If enabled, Federation may be turned on in one of two different ways.
  • Allow all but blacklist — Accept federating with any Instance unless that domain is on the pre-defined blacklist.
  • Deny all but whitelist — Decline federating with any Instance unless that domain is on the pre-defined whitelist.

• If blacklisted, that Guest Instance’s users will not be able to communicate with any Home User, nor may any Home User join any Foreign Guilds housed on the Guest Instance.

Offline and Abandoned Guest Instances

• If a Guest Instance is offline or otherwise uncontactable (e.g., either the Guest or Home Instance is on a blacklist), Home Users will see the any guilds housed on the Guest Instance as being disconnected.

• The Home Instance will continue to make efforts to connect to the Guest Instance over a defined period of time with successive back-offs (e.g., 30 days).

• Once the Home Instance deems the Guest Instance permanently offline, it can automatically remove membership from all guilds associated with the offline Instance and delete any of its cached data, including reactions, and references to attachments that are only housed on the Guest Instance.

• At some further defined point in time, a Home Instance may remove the user accounts of a permanently offline Guest Instance. These removals would be treated by the platform in the same way as if a Home Account were deleted. This is considered the “Permanent Deletion Event”.

• If the Guest Instance is revived at some point:
  • It will be discovered as revived if and when a Home User successfully adds a guild on the Guest Instance.
  • At that time, the Home Instance will inform the Guest Instance that it has considered it permanently offline. This causes the Guest Instance to remove all of the Home Instance’s data from its database in the same way as the Home Instance did when it considered the Guest Instance permanently offline.
  • Once this action occurs in the background, the Home User will be added to the guild in the Guest Instance as a new member.

Instance Authentication and Key Rotation

• Each Instance generates a cryptographic keypair that identifies it. Upon first federating with another Instance, the public key components are exchanged.

• Together with domain SRV record, these two elements serve to fully authenticate an instance as authoritative for any users at that particular domain.

• The public key is used to authenticate each instance with the other when performing cross-instance communications.

• The private key is also used to sign the bearer tokens provided to clients for sending requests to Guest Instances.

• The keypair may be rotated. The new public key may be distributed to the other Instances using the cross-server communications channel. Upon the day and time desired by an Instance, it may invalidate old an old keypair and designate a new one as valid.

• If an Instance attempts to communicate with an invalid keypair, its communications will be rejected.

• Even if an Instance goes offline and is abandoned as described earlier in this document, the public key remains cached. Any revived Instance will be expected to communicate with the last known good keypair. These cached public keys will only be removed by a Permanent Deletion Event. After this, if an Instance wishes to refederate, it may use an entirely new keypair, as there would be no other links to the former Instance.
• The admins of an Instance may at any time clear the last known-good public key and permit an Instance to reconnect with a newly generated keypair.

Push Notifications

• Since there will be one official Fluxer mobile app, there will be a need for consolidated push notification delivery to occur from all self-hosted Instances.

• Push notifications to the mobile app may be disabled by an Instance. If disabled, the mobile app would only retrieve the badge count and notifications upon active connection with the Home Instance.
  • Potentially, the app may be configured to, as a background task, retrieve the badge count and pending notifications from the Home Instance on a certain interval.

• When a user first creates an account on their Home Instance, or when a Home User first joins a Foreign Guild, they will be prompted whether they would like to receive notifications from the target Instance.

• If approved, the following occurs:
  • The app sends a request to Fluxer’s central push notifications service indicating that it is subscribing to notifications from a particular Instance.
  • Fluxer’s push service looks up the SRV record of the target Instance and retrieves the well-known configuration of the Instance.
  • If validated, Fluxer’s push service provides a token to the client, which is then passed on by the client to the target Instance.

• The target Instance can send push requests directly to Fluxer’s central push service using the token described earlier, which would then be forwarded to the mobile app through the respective Google/Apple push services.

• The payload of the push notification will include the domain of the Instance making the notification, thus the mobile client would know which guilds are eligible to have the notification attributed. This prevents spoofing notifications for unrelated Instances.

Notes (optional)

No response

Checks

• [x] I searched for existing discussions and didn't find a duplicate.