Glossary
- Identities: the collection of User that represent the same Developer on multiple Forges
- Developer: a software developer who has an account on a Forge
- Forge: a software forge
- Fedeproxy Service: the publicly online service that runs fedeproxy
- User: a forge user under the control of a Fedeproxy Service
- User Pool: the collection of users that are in the scope of a fedeproxy instance
- Access Token: credentials to use the API of a forge on behalf of a user
- Local Storage: the file system of the machine where fedeproxy runs
- Fedeproxy User: the forge user that the Fedeproxy Service uses to store Identities & link to itself
- Issue: an item in the issue tracker of a Forge
- Federated Issue Identifier: Fedeproxy Service URL/@hash(forge URL)
- Federated Issue: an issue that follows (in the ActivityPub sense) another issue. The Fedeproxy Service sends ActivityPub messages when it is modified.
Fedeproxy Service instances
When installed, fedeproxy must be configured with a Forge and will spawn a Fedeproxy Service dedicated to this Forge.
When a Federated Issue is created with Issue A on Forge A and Issue B on Forge B, the Fedeproxy Service A will try to figure out the URL of the Fedeproxy Service B. If it fails to find one, it will spawn a Fedeproxy Service B and use it instead.
Fedeproxy Services running against the same Forge can be merged.
User Pool
Fedeproxy manages a pool of unused users in the forge. These users can be created:
- By fedeproxy via the REST API, as a cron job (with or without a root token) which adds the users in a repo of the Fedeproxy User
- Manually, for GitHub or GitLab because bots cannot conveniently create account, possibly via a crowdsource campaign
Installation
When fedeproxy starts the first time:
- it is given the email of the fedeproxy maintainer and the URL of the forge
- it gets a user from the User Pool to be the Fedeproxy User and assigns it the email of the maintainer
- it saves the Access Token to the user in Local Storage
- it uploads the User Pool in a private repository
Identities
Staged
An Identity is staged when it is not associated with an email. For
instance because they were created to represent the author of a
comment in an Issue.
Owned
An Identity is owned when the Developer does not know about it. If it
is controled by the Developer, it is not owned by the Fedeproxy
Service.
Storage
Fedeproxy Service creates a private repository for each User to store their Identities:
- Forge URL
- Fedproxy Service URL
- username
- mails
- staged
- owned
backups
On a regular basis fedeproxy sends a mail to the user with the list of
identities. The mail is sent to all users that are owned. The tokens /
passwords are not sent because they can ultimately be retrieved via a
password reset via mail. It is a disaster recovery precaution.
Send backup mail every time a new account is created.
Reclaiming a staged user
If User B was staged on Forge B to be the author of all actions carried out on Forge A by User A, how does the Developer controlling User A reclaim ownership of User B ?
- There exists an issue in the Fedeproxy User project “reclaim” for each staged user on Forge B
- The comment of the issue is a link to the OAuth2 web page of the Fedeproxy Service for Forge A
- When the user clicks it confirms that the Fedeproxy Service can get their email, Fedeproxy Service A sends it to Fedeproxy B after verifying that the referer of the request is indeed Forge B
Fedeproxy Service B could trigger a password reset on user B, or the Developer can do the same.
Disaster recovery
Fedeproxy Service maintainer
If the Local Storage is lost, it is the responsibility of the
maintainer to figure out the URL of the Fedeproxy User by searching
the forge, impersonating the user, getting an application token and
running the fedeproxy server with the Fedeproxy User and application
token to regain access.
Developer
Using the URL found in the Identities backups sent to them, the Developer
can regain manual control of a User on any given forge using a password reset (because
all users are associated with emails under the control of Developer).
Trust
Fedeproxy Service
By default a Fedeproxy Service does not impose any restriction on the creation of a User because it is cheap on self-hosted instances. If there is abuse those users can be removed after a period of inaction, just as is done with bots that create accounts on forges at the moment.
However user creation is much more expensive on forges such as GitHub or GitLab and a Fedeproxy Service that runs for such Forges should only allow user creation when it originates from a list of trusted Fedeproxy Services. If Fedeproxy Service A is not trusted by Fedproxy Service B on Forge B. A Fedeproxy Service A can request to follow another Fedeproxy Service B. If the Fedeproxy Service B accepts, it will create/allocate accounts originating from Fedeproxy Service A instead of declining.
Federated Issue
When a Developer A creates a Federated Issue on Forge A that follows an Issue B on Forge B, the Fedeproxy Service A service trusts Fedeproxy Service B. It assumes Developer A did their research and Forge B can be trusted with Issue B.
Share an email
When Developer A on Forge A asks Fedeproxy Service A to federate an Issue that is a URL on Forge B, it means they trust the Forge B to not be malicious and Fedeproxy Service A can therefore trust Fedeproxy Service B with the email of Developer A.
Fedeproxy Service A uses the REST API of Fedeproxy Service B to POST the email of User A and the name of User B that represents User A on Forge B. It also provides in the POST params a .well-known URL on Forge A that proves it is in control of User A. Once Fedeproxy Service B verifies the .well-known URL, it sets the email of User B.