├── LICENSE ├── README.md ├── debug └── v0.1 │ └── debug_provider.md ├── discovery ├── README.md ├── account_search │ └── v0.1 │ │ └── account_search.md ├── data_sharing │ └── v0.1 │ │ └── data_sharing.md └── trends │ └── v0.1 │ └── trends.md ├── general └── v0.1 │ ├── README.md │ ├── introduction.md │ ├── protocol_basics.md │ ├── provider_info.md │ ├── provider_openapi.yml │ ├── provider_specifications.md │ ├── registration.md │ └── server_openapi.yml └── images ├── debug_logs.svg ├── debug_provider_details.svg ├── fasp_registration_requests.svg ├── instances_federating.svg ├── instances_using_providers.svg ├── select_capabilities.svg ├── server_sign_up.svg └── server_sign_up_success.svg /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | 123 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Provider Specifications 2 | 3 | This repo collects drafts of specifications for "Fediverse Auxiliary Service Providers". It also serves as a hub for discussions around these specifications. 4 | 5 | ## What are "Fediverse Auxiliary Service Providers"? 6 | 7 | Fediverse Auxiliary Service Providers (FASPs) are independent services that can interact with Fediverse server software to provide services that augment capabilities that are in the server software, are not available in the server software, or cannot be achieved by a single server. 8 | 9 | Some examples for these services would be: 10 | 11 | * Search and Discovery 12 | * SPAM detection 13 | * Blocklist synchronization 14 | * Link preview generation 15 | * Helpdesk integration 16 | 17 | ![Fediverse instances using difference auxiliary service providers](images/instances_using_providers.svg) 18 | 19 | Read a more thorough explanation in the [Provider Instance Interaction Specification introduction](general/v0.1/introduction.md). 20 | 21 | ## List of Specifications 22 | 23 | ### General 24 | 25 | [Provider Instance Interaction](general/v0.1/) specifies the initial setup of the fediverse server and FASP relationship and their general interactions. This should be common to all FASPs and forms the basis for the other specifications below. 26 | 27 | ### Debug 28 | 29 | The specification of a very basic debug FASP to help with developing FASP integration into existing fediverse software. 30 | 31 | ### Search and Discovery 32 | 33 | To learn more about the initial plans for search and discovery please visit the [website of the "Fediverse Discovery Provider" project](https://fediscovery.org). 34 | 35 | Specifications: 36 | 37 | * [Data Sharing](discovery/data_sharing/v0.1/data_sharing.md) 38 | 39 | ## Contributing 40 | 41 | We welcome contributions from all fediverse software implementers. 42 | 43 | If you find a major problem with one of the specifications, please open an issue. 44 | 45 | If you would like to correct spelling, grammar etc., please create a pull request. 46 | 47 | If you have questions, plan a larger PR (maybe your own FASP specification?) or simply want to discuss anything related to auxiliary service providers, please open a discussion. 48 | 49 | ## License 50 | 51 | This work is marked with CC0 1.0 Universal 52 | -------------------------------------------------------------------------------- /debug/v0.1/debug_provider.md: -------------------------------------------------------------------------------- 1 | # Debug Provider Specification 2 | 3 | ## Overview 4 | 5 | Specification identifier: `debug` 6 | 7 | The debug provider is a 8 | [Fediverse Auxiliary Service Provider](../../general/v0.1/) 9 | that is meant to ease integration of FASP into fediverse software. 10 | 11 | It is meant to aid in developing provider integrations into existing 12 | fediverse software and to debug issues with provider setup in general. 13 | 14 | ## Capabilities 15 | 16 | ### `callback` 17 | 18 | Capability identifier: `callback` 19 | 20 | Description: 21 | 22 | > The `callback` capability offers a single API endpoint in the provider. 23 | > When called it makes the provider call an API on the server in 24 | > return. The calls are logged to help debug issues with the 25 | > provider/instance setup. 26 | 27 | #### Provider API Endpoints 28 | 29 | The provider allows an instance to make a HTTP `POST` call to 30 | `/debug/v0/callback/logs`. 31 | 32 | Example call: 33 | 34 | ```http 35 | POST /debug/v0/callback/logs 36 | ``` 37 | 38 | The request body MAY be empty or contain a single JSON object. 39 | 40 | The provider MUST log: 41 | 42 | * that the request has been made, 43 | * at what time it was made, 44 | * the IP address of the instance that made the request and 45 | * if present the JSON object from the request body 46 | 47 | The provider must then make the API call described in the next section 48 | to the instance. 49 | 50 | The provider MUST return a HTTP status code `201` (Created). 51 | 52 | #### Instance API Endpoints 53 | 54 | The instance allows the provider to make a HTTP `POST` call to 55 | `/debug/v0/callback/responses`. 56 | 57 | Example call: 58 | 59 | ```http 60 | POST /debug/v0/callback/responses 61 | ``` 62 | 63 | The request body MAY be empty, unless the instance included a JSON 64 | object in its call to the provider. In this case the provider MUST 65 | include this object in the request body unchanged. 66 | 67 | The instance SHOULD log: 68 | 69 | * that the request has been made, 70 | * at what time it was made, 71 | * the IP address of the provider that made the request and 72 | * if present the JSON object from the request body 73 | 74 | This is a strong "SHOULD" but not a "MUST" because skipping this step 75 | might make the implementation inside the instance's software easier 76 | while still providing some value. 77 | 78 | The instance MUST return a HTTP status code `201` (Created). 79 | 80 | #### User Interface Requirements 81 | 82 | The provider MUST offer the instance admin a user interface that 83 | displays the logged information. 84 | 85 | ![A simple table displaying logged requests with instance URL, IP, a timestamp and the payload](../../images/debug_logs.svg) 86 | 87 | The instance MUST provide a button or link to initiate the API call to 88 | the provider. It SHOULD provide a way for the instance admin to see the 89 | logged callbacks from the provider. 90 | 91 | ![A simple provider details view including a button to trigger the debug call and a table with logged callbacks](../../images/debug_provider_details.svg) 92 | 93 | ## Data Protection 94 | 95 | This provider does not receive any personally identifiable or otherwise 96 | sensitive information. 97 | -------------------------------------------------------------------------------- /discovery/README.md: -------------------------------------------------------------------------------- 1 | # Fediscovery: Fediverse Discovery Providers 2 | 3 | This directory contains the basic specifications for discovery 4 | providers, FASPs that facilitate better search and discovery for the 5 | fediverse. 6 | 7 | ## Motivation 8 | 9 | Each server that participates in the fediverse is largely independent 10 | when it comes to discovery. A real user search, discovery of content, 11 | trends and recommendations are not easily possible across the network. 12 | 13 | More often than not, the search and discovery experience is limited 14 | to content from the instance a user is on. This poses a problem, 15 | especially on small instances. 16 | 17 | See [the website](https://www.fediscovery.org) for details. 18 | 19 | ## Specifications 20 | 21 | * [Data Sharing](data_sharing/v0.1/) 22 | 23 | All discovery providers need a way to request content from fediverse 24 | servers. This specification describes both an API to subscribe to new 25 | content as well as an API to retrieve existing content. 26 | 27 | * [Trends](trends/v0.1/) 28 | 29 | This describes the `trends` capability for providers that help 30 | discovering content that is currently trending. 31 | 32 | * [Account Search](account_search/v0.1/) 33 | 34 | This describes the `account_search` capability for providers that 35 | offer search for fediverse accounts. 36 | 37 | * Account Recommendation (Coming soon) 38 | 39 | * Status/Post Search (Tentatively planned) 40 | -------------------------------------------------------------------------------- /discovery/account_search/v0.1/account_search.md: -------------------------------------------------------------------------------- 1 | # "Fediscovery": Account Search Specification 2 | 3 | ## Overview 4 | 5 | Specification identifier: `account_search` 6 | 7 | An important part of discovery is finding people to follow. This 8 | capability offers a very simple API to search for accounts that have 9 | opted-in to being disvovered. 10 | 11 | ## Performing Full-Fext Searches for Accounts 12 | 13 | To perform a full-text search for accounts FASP allow fediverse servers 14 | to make an HTTP `GET` call to the `/account_search/v0/search` endpoint. 15 | 16 | The following parameters can be used: 17 | 18 | * `term`: This parameter MUST be present and include the text that is to 19 | be searched for. 20 | * `limit`: This parameter MAY optionally be present to give a positive 21 | integer number representing the maximum nmber of results FASP should 22 | return. If omitted this value defaults to `20`. 23 | 24 | Example call to search for "teapot" and request at most 10 results: 25 | 26 | ```http 27 | GET /account_search/v0/search?term=teapot&limit=10 28 | ``` 29 | 30 | If a `term` was present in the request, the response MUST include an 31 | HTTP status code `200` (OK) and a JSON array that includes the URIs 32 | (IDs) of the ActivityPub actor belonging to accounts matching the 33 | requests. These results MUST be sorted by relevance in descending order. 34 | 35 | If the `term` is missing from the request, the response MUST include an 36 | HTTP status code `422` (Unprocessable Content). 37 | 38 | Example response array: 39 | 40 | ```json 41 | [ 42 | "https://fedi.example.com/actor/23", 43 | "https://other.example.com/user/245/actor" 44 | ] 45 | ``` 46 | 47 | In case there are more search results than specified by `limit` FASP MAY 48 | allow to paginate more results. To signal that there are more results 49 | FASP MUST include an HTTP `Link` header as described in 50 | [RFC-5988](https://tools.ietf.org/html/rfc5988.html). This header MUST 51 | include the URL of the next page of results with a relation type (`rel`) 52 | of `next`. 53 | 54 | ## Privacy Policy Information 55 | 56 | With the API specified above fediverse servers do not share any personally 57 | identifiable or otherwise sensitive information with FASP per se. 58 | 59 | But they will probably send search terms entered by actual users of 60 | their platform to FASP. While these cannot be traced back to the user it 61 | might still be something worth noting in the privacy policy. 62 | 63 | Fediverse server administrators may add something along the lines of 64 | this to their privacy policy: 65 | 66 | > sends search terms entered by users to a third-party search 67 | > service, . This service returns relevant data from the fediverse 68 | > that uses to improve search results. No user identifier or 69 | > other PII is shared with . cannot trace back search terms 70 | > to the user who entered them. 71 | -------------------------------------------------------------------------------- /discovery/data_sharing/v0.1/data_sharing.md: -------------------------------------------------------------------------------- 1 | # "Fediscovery": Data Sharing Specification 2 | 3 | ## Overview 4 | 5 | Specification identifier: `data_sharing` 6 | 7 | In order to be able to present results, discovery providers need to be 8 | able to request content from connected fediverse servers. Two different 9 | concerns need to be distinguished: Retrieving new content as it is 10 | created and retrieving historic content to backfill search indexes. 11 | 12 | ## Restrictions On Content Being Shared 13 | 14 | A single FASP will never be used by all fediverse servers. To ensure it 15 | still gets a broad view not limited to a small number of servers, 16 | fediverse servers MUST share not only local but also remote content with 17 | the FASP. 18 | 19 | Since this may result in multiple servers sharing the same content with 20 | a single FASP, FASPs MUST deduplicate content. 21 | 22 | As a single server is not authoritative for all the content shared and 23 | to save bandwidth only URIs of content are actually exchanged with the 24 | FASP. The FASP is then responsible for retrieving the content and 25 | working with it. The exact details of this differ between capabilties 26 | and are described in the respective sections. 27 | 28 | A fediverse server MUST make sure it only shares content that it is 29 | actually allowed to share. It MUST NOT share any content that is not 30 | public. 31 | 32 | Some fediverse software projects (including Mastodon) have more 33 | differentiated visibility settings and offer public visibility of posts 34 | that is somewhat restricted. In the case of Mastodon this is called 35 | "quiet public" or "unlisted". Posts with this visibility are publicly 36 | available but should not be included in search. If a fediverse server 37 | supports this kind of restricted public visibility it MUST NOT share 38 | this kind of content with FASP. 39 | 40 | FASP MUST check the `to:` property on content it retrieves to make sure 41 | it is really meant for public consumption. 42 | 43 | In the case of account and post data, a fediverse server MUST make sure 44 | to only share content where the creator has opted in to discovery. 45 | 46 | The FASP in turn MUST also ensure that creators have opted in to 47 | discovery before storing and indexing content. 48 | 49 | Both parties MUST use the mechanism described in 50 | [FEP-5feb](https://codeberg.org/fediverse/fep/src/branch/main/fep/5feb/fep-5feb.md) 51 | to determine if a creator has opted in to discovery. 52 | 53 | For account data, both parties MUST ensure the `discoverable` flag is 54 | set to `true`. 55 | 56 | ## Subscribing To, Requesting And Receiving Content 57 | 58 | ### Managing Subscriptions (FASP => Fediverse Server) 59 | 60 | In order to subscribe to new content, FASPs can subscribe to events 61 | by making a `POST` call to the `/data_sharing/v0/event_subscriptions` 62 | endpoint on the fediverse server. 63 | 64 | Example call: 65 | 66 | ```http 67 | POST /data_sharing/v0/event_subscriptions 68 | ``` 69 | 70 | The request body MUST contain a JSON object defining what events to 71 | subscribe to. This object MUST contain the keys `category` and 72 | `subscriptionType`. It MAY contain the keys `maxBatchSize` and/or 73 | `threshold`. The keys are defined as follows: 74 | 75 | * `category`: One of `content`, `account`. This is the category of 76 | objects the FASP is interested in. 77 | * `subscriptionType`: One of `lifecycle`, `trends`. `lifecycle` 78 | means the FASP would like to be notified when new objects of the given 79 | type are created, when objects are updated and when objects are 80 | deleted. `trends` means that the FASP would like to be notified of 81 | objects that had recent interactions. `trends` is only applicable if 82 | the `category` given is `content`. 83 | * `maxBatchSize`: The maximum number of events the FASP would like to 84 | receive in a single request. This is optional. 85 | * `threshold`: If `subscriptionType` is `trends` then this object can be used to 86 | further specify when the event should be reported. Valid keys for this 87 | object are: 88 | * `timeframe`: Number of minutes in which interactions should fire an 89 | event, defaults to `15` 90 | * `shares`: Number of shares in the given timeframe, defaults to `3` 91 | * `likes`: Number of likes in the given timeframe, defaults to `3` 92 | * `replies`: Number of replies in the given timeframe, defaults to `3` 93 | 94 | Example object: 95 | 96 | ```json 97 | { 98 | "category": "content", 99 | "subscriptionType": "trends", 100 | "maxBatchSize": 10, 101 | "threshold": { 102 | "timeframe": 15, 103 | "shares": 3 104 | } 105 | } 106 | ``` 107 | 108 | The fediverse server MUST validate the request. If it is invalid it MUST 109 | return an HTTP status code `422` (Unprocessable Content). 110 | 111 | If it is valid the response from the fediverse server MUST include an 112 | HTTP status code `201` (Created) and a JSON object including the `id` of 113 | the generated subscription. The latter can be used to unsubscribe later. 114 | 115 | Example response object: 116 | 117 | ```json 118 | { 119 | "subscription": { 120 | "id": "3446" 121 | } 122 | } 123 | ``` 124 | 125 | To unsubscribe the FASP can make an HTTP `DELETE` call to the 126 | `/data_sharing/v0/event_subscriptions/:id` endpoint, where `:id` is replaced 127 | with the ID received when the original subscription was created. 128 | 129 | Example call: 130 | 131 | ```http 132 | DELETE /data_sharing/v0/event_subscriptions/3446 133 | ``` 134 | 135 | The response MUST be an HTTP status code `204` (No Content). 136 | 137 | ### Requesting Historic Content / Backfilling (FASP => Fediverse Server) 138 | 139 | FASP can request historic content from fediverse servers. Individual 140 | requests are always for a limited number of individual records and will 141 | be fulfilled asynchronously using the same delivery mechanism as event 142 | subscriptions. This way both parties have control over how to spread out 143 | the additional load generated by backfill requests. 144 | 145 | To request historic content to index a FASP can make an HTTP `POST` call 146 | to the `/data_sharing/v0/backfill_requests` endpoint. 147 | 148 | Example call: 149 | 150 | ```http 151 | POST /data_sharing/v0/backfill_requests 152 | ``` 153 | 154 | The request body MUST contain a JSON object with the following keys: 155 | 156 | * `category`: One of `content`, `account`. This is the category 157 | of objects the FASP is interested in. 158 | * `maxCount`: An integer representing the maximum number of objects the 159 | FASP would like to receive. 160 | 161 | Example object: 162 | 163 | ```json 164 | { 165 | "category": "content", 166 | "maxCount": 100 167 | } 168 | ``` 169 | 170 | The response from the fediverse server MUST include an HTTP status code 171 | `201` (Created) and a JSON object including the `id` of the generated 172 | backfill request. 173 | 174 | Example response object: 175 | 176 | ```json 177 | { 178 | "backfillRequest": { 179 | "id": "672" 180 | } 181 | } 182 | ``` 183 | 184 | Data received as a result of a backfill request will indicate if more 185 | content for this request is available (see the next section for 186 | details). In this case FASP can make an HTTP `POST` request to the 187 | `/data_sharing/v0/backfill_requests/{id}/continuation` endpoint, where 188 | `{id}` is the identifier of the backfill request as received from the 189 | server. The request body MUST be empty. 190 | 191 | Example call: 192 | 193 | ```http 194 | POST /data_sharing/v0/backfill_requests/672/continuation 195 | ``` 196 | 197 | The response from the fediverse server MUST include an HTTP status code 198 | `204` (No Content) if more content for the backfill request is 199 | available. If no more content is available or if the `id` is not known 200 | it MUST instead use the status code `404` (Not Found). 201 | 202 | FASP SHOULD NOT issue this request until they received content that 203 | indicates that more is available for a given backfill request. 204 | 205 | ### Sending Content (Fediverse Server => FASP) 206 | 207 | Both the occurrence of an event that a FASP has subscribed to and the 208 | fulfillment of a backfill request, MUST be announced to the FASP by the 209 | fediverse server with an HTTP `POST` call to the FASP's 210 | `/data_sharing/v0/announcements` endpoint. 211 | 212 | Example call: 213 | 214 | ```http 215 | POST /data_sharing/v0/announcements 216 | ``` 217 | 218 | The request body MUST include a JSON object including the keys 219 | `source`, `objectType` and `objectUris`. 220 | 221 | * `source` lets the FASP know in reply to which of its request this 222 | announcement is sent. It MUST include an object with either the 223 | key `subscription` or `backfillRequest`. This in turn MUST include 224 | an object with the key `id` containing the identifier of the given 225 | source. 226 | * `category` MUST mirror the category given in the original 227 | subscription or backfill request. 228 | * `objectUris` is an array of URIs representing the objects. 229 | * `eventType` MUST be present for events and be one of `new`, `update`, 230 | `delete` or `trending`. The first three are for subscriptions to the 231 | `lifecycle` type and the latter for the `trends` type. 232 | This key MUST NOT be present for responses to backfill requests. 233 | * `moreObjectsAvailable` MUST be present on responses to backfill 234 | requests. If set to `false` it means that no more objects of this 235 | category are available and no future backfill requests should be made. 236 | 237 | Requests MUST include at least one object URI, but the fediverse server 238 | MAY save requests and batch events together. In that case it MUST 239 | respect the `maxBatchSize` it received with the subscription. 240 | 241 | In case of backfill requests the fediverse server can decide to send the 242 | requested number of objects in a single request or split it up into 243 | smaller requests to reduce the load. In that case the optional `cursor` 244 | MUST only be included with the final request, but only if more data 245 | would be available. 246 | 247 | Example payload: 248 | 249 | ```json 250 | { 251 | "source": { 252 | "subscription": { 253 | "id": "58152" 254 | } 255 | }, 256 | "category": "content", 257 | "eventType": "new", 258 | "objectUris": [ 259 | "https://fediverse-server.example.com/@example/2342", 260 | "https://fediverse-server.example.com/@other/8726" 261 | ] 262 | } 263 | ``` 264 | 265 | The response MUST be an HTTP status code `204` (No Content). 266 | 267 | ## Retrieving Content From Its Origin (FASP => Wider Fediverse) 268 | 269 | As displayed in the sections above, FASP will only receive object URIs 270 | from connected fediverse servers. They will then need to fetch the 271 | actual content themselves. 272 | 273 | To do so, they need to send HTTP `GET` requests to the object URIs with 274 | an `Accept` header with the `application/ld+json; 275 | profile="https://www.w3.org/ns/activitystreams"` media type as specified 276 | by [ActivityPub](https://www.w3.org/TR/activitypub/#retrieving-objects). 277 | 278 | These requests MUST be signed. To achieve a maximum of compatibility 279 | with existing fediverse software, FASP MUST support request signing with 280 | both "HTTP Message Signatures" as defined by 281 | [RFC-9421](https://tools.ietf.org/html/rfc9421.html) as well as the 282 | earlier draft version "HTTP Signatures" as defined by 283 | [cavage-12](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures). 284 | 285 | To find out which version a given fediverse server supports, FASP should 286 | implement "double-knocking": They should first attempt a request using 287 | "HTTP Message Signatures" and if the fediverse server replies with an 288 | HTTP status code of `401` or `403` make a second attempt with the older 289 | draft version, "HTTP Signatures". 290 | 291 | To save on future requests, FASP SHOULD implement a per fediverse server 292 | cache to save the information which version of the standard was accepted 293 | and use that one directly when accessing objects the next time. In case 294 | a server supports the older version, "HTTP Signatures", the newer one 295 | MUST be retried periodically, i.e. the cache should be invalidated. 296 | 297 | More information about HTTP signatures and "double-knocking" can be 298 | found in this report: 299 | [ActivityPub and HTTP Signatures](https://swicg.github.io/activitypub-http-signature/). 300 | 301 | In both protocol versions, FASP MUST act as an "server/instance actor". 302 | This means that the `keyId` given MUST be a URI that can be used to 303 | fetch the JSON-LD representation of an ActivityPub Actor that represents 304 | the FASP. This actor information MUST include the public key that can 305 | be used to verify the signature. 306 | 307 | The URI's path MUST be `/actor` and a minimal JSON response might look 308 | like this: 309 | 310 | ```json 311 | { 312 | "@context": [ 313 | "https://www.w3.org/ns/activitystreams", 314 | "https://w3id.org/security/v1", 315 | ], 316 | "id": "https://fasp.example.com/actor", 317 | "type": "Application", 318 | "inbox": "https://fasp.example.com/inbox", 319 | "outbox": "https://fasp.example.com/outbox", 320 | "preferredUsername": "fasp", 321 | "publicKey": { 322 | "id": "https://fasp.example.com/actor#main-key", 323 | "owner": "https://fasp.example.com/actor", 324 | "publicKeyPem": "" 325 | } 326 | } 327 | ``` 328 | 329 | `https://fasp.example.com` MUST be replaced with an URL of the actual 330 | FASP, `` with its public key used for signing. Note that 331 | is is *not* one of the private keys used to authenticate with a 332 | registered fediverse server as defined in [FASP/Fediverse Server 333 | Interaction](../../general/v0.1/) but part of a separate key pair FASP 334 | MUST generate for this purpose. 335 | 336 | FASP MUST include the content shown above in their actor JSON but MAY 337 | add further information. 338 | 339 | ActivityPub mandates that an `inbox` and `outbox` URL are present. A 340 | minimal implementation of an outbox could simply always return an empty 341 | collection while a minimal inbox could receive but immediately discard 342 | activities posted to it. Note that fediverse servers might post 343 | activities to the inbox that could be useful for FASP. But if and how 344 | these endpoints are implemented in FASP is out of scope for this 345 | specification. 346 | 347 | FASP MUST give a `preferredUsername` as some fediverse servers require 348 | this. This also means they need to support "WebFinger" lookups for this 349 | username as defined in 350 | [RFC-7033](https://datatracker.ietf.org/doc/html/rfc7033). 351 | 352 | In the example above this would mean that the FASP would need to respond 353 | to an HTTP `GET` request to 354 | `https://fasp.example.com/.well-known/webfinger?resource=acct:fasp@fasp.example.com` 355 | accepting a `Content-Type` of `application/jrd+json` with something like 356 | this: 357 | 358 | ```json 359 | { 360 | "subject": "acct:fasp@fasp.example.com", 361 | "aliases": [ 362 | "https://fasp.example.com/actor" 363 | ], 364 | "links": [ 365 | { 366 | "rel": "self", 367 | "type": "application/activity+json", 368 | "href": "https://fasp.example.com/actor" 369 | } 370 | ] 371 | } 372 | ``` 373 | 374 | Once indexed or persisted in any way, FASP MUST periodically re-check 375 | both content and account data. At least once every week FASP MUST 376 | revalidate that the content / account is still publicly available and 377 | still allowed to be indexed. If the content has been changed these 378 | changes MUST be applied in the FASPs data storage as well. If FASP have 379 | been notified of changes through their subscriptions they MAY suspend 380 | the periodical check for this object for the next week. 381 | -------------------------------------------------------------------------------- /discovery/trends/v0.1/trends.md: -------------------------------------------------------------------------------- 1 | # "Fediscovery": Trends 2 | 3 | ## Overview 4 | 5 | Specification identifier: `trends` 6 | 7 | The `trends` capability allows fediverse servers to query FASP for 8 | content, hashtags and links that are currently trending. 9 | 10 | ## Trends and Discovery 11 | 12 | A huge part of discovery in social media is for users to be able to see 13 | what other people are currently posting, including but not limited to: 14 | 15 | * A post "going viral", meaning it is being replied to, liked and shared 16 | a lot 17 | * A hashtag being used unusually often within a given timeframe 18 | * A link being included in a lot in different posts 19 | 20 | Many fediverse software products already include ways to compute and 21 | display these trends. But a single fediverse server is always limited to 22 | the content it knows about. A discovery FASP can potentially see more 23 | fediverse-wide activity and thus provide fediverse servers with more 24 | interesting trends data. 25 | 26 | This specification defines an API for fediverse servers to query FASP 27 | for this trends data. 28 | 29 | It does not specify how exactly trends are computed. FASP MAY use all 30 | the data that is available to them, including the data obtained via 31 | [data sharing](../../data_sharing/v0.1/data_sharing.md), to compute 32 | trends. 33 | 34 | Different implementations of this specifications MAY even compete on the 35 | actual algorithm(s) they use. 36 | 37 | FASP SHOULD document how they compute trends so that fediverse server 38 | administrators can make an informed decision when choosing between 39 | different discovery FASP. 40 | 41 | ## Representation of Content, Hashtags and Links 42 | 43 | Content refers to ActivityPub objects that have a unique identifier, 44 | their URI. 45 | 46 | Uniquely identifying hashtags and links is more complex. 47 | 48 | Hashtags are represented by their name, a UTF-8 encoded string beginning 49 | with `#`. Different hashtag names might refer to the same concept, 50 | especially if they only differ in their use of upper and lower case 51 | characters. For example `#activitypub` and `#ActivityPub` can be 52 | considered to be the same. 53 | 54 | Links are HTTP(S) URLs. Syntactically different URLs can refer to the same 55 | resource. A simple example is again case-sensitivity as the domain part 56 | of an HTTP(S) URL is case-insensitive. So `https://example.com/test` and 57 | `https://EXAMPLE.com/test` both refer to the same resource. 58 | 59 | Fediverse servers already have to deal with this problem and will in 60 | most cases have some concept of "normalization" for both hashtags and 61 | links. This "normalization" is not part of any standard and different 62 | fediverse software can have different and even incompatible 63 | implementations of this. 64 | 65 | That is why when sharing trending hashtags and links with fediverse 66 | servers, FASP do not need to take special care how to represent them and 67 | can freely choose the representation (e.g. the first one they 68 | encountered or a normalized version). Fediverse servers SHOULD handle 69 | them just like they handle these representations in other contexts. 70 | 71 | When computing trends however, FASP SHOULD consider normalization to 72 | minimize the risk of obvious duplicates and individual spellings of the 73 | same hashtag not meeting the threshold of what constitutes a trend, 74 | while the aggregated numbers clearly would. 75 | 76 | For hashtags possible strategies for this besides case-insensitive 77 | handling of names include "ASCII folding" and using existing character 78 | transliteration rules. As all of these approaches have their downsides 79 | and can lead to two different words being erroneously treated as the 80 | same it is up to FASP to decide which strategy to use. 81 | 82 | For links [RFC-3986](https://tools.ietf.org/html/rfc3986.html) describes 83 | different normalization techniques in section 6. 84 | 85 | ## Availability of Content for Hashtags and Links 86 | 87 | When a fediverse server requests trending hashtags or links it will in 88 | most cases want to display them to users and have a way for users to see 89 | how and where those have been used. Since FASP have a wider view of the 90 | fediverse it might be the case that the fediverse server has no content 91 | at all that references a trending hashtag or link. Or it might not have 92 | recent content that does so. 93 | 94 | To help fediverse servers in this situation discovery FASP include a 95 | couple of example URIs of content with every result of a query for 96 | hashtags and links trends. This allows fediverse servers to quickly fill 97 | their local caches with some content for the received trends. See the 98 | sections "Requesting Trending Hashtags" and "Requesting Trending Links" 99 | below for details. 100 | 101 | ## Requesting Trends 102 | 103 | ### Common Request Options 104 | 105 | All requests for trends from a fediverse server to FASP are HTTP `GET` 106 | requests that allow - with one exception - using the same optional 107 | parameters: 108 | 109 | * `withinLastHours`: This MUST be a positive integer specifying the 110 | number of hours up to the current time for which to compute trends. 111 | The minimum value of `1` means records trending within the last hour. 112 | FASP MUST support values up to `168` (i.e. one week) but MAY allow 113 | larger values. If omitted defaults to `24`. 114 | * `maxCount`: This MUST be a positive integer specifying the maximum 115 | number of results that should be returned. If omitted defaults to 116 | `20`. 117 | * `language`: A [BCP47](https://tools.ietf.org/html/bcp47) language tag 118 | to only receive results in or relevant for the specific language. If 119 | omitted results can be in or relevant for any language. FASP MUST 120 | perform "basic filtering" as described by 121 | [RFC-4647](https://tools.ietf.org/html/rfc4647.html) to determine 122 | matching languages. 123 | 124 | ### Common Response Attribute 125 | 126 | All responses include a list of results. Individual result objects 127 | share the following common key and value: 128 | 129 | * `rank`: A positive integer less than or equal `100` representing the 130 | rank of this result. `100` is the highest rank, meaning "most trending". 131 | Calculation of the rank is not part of this specification, but within 132 | the same FASP software, ranks MUST be comparable. If a fediverse 133 | server uses several FASP to query for trends that all run the same 134 | software, it MUST be possible to merge results according to rank to 135 | get the correct order. 136 | 137 | ### Requesting Trending Content 138 | 139 | To request trending content fediverse servers can make an HTTP `GET` 140 | request to the `/trends/v0/content` endpoint on the FASP. 141 | 142 | Example call: 143 | 144 | ```http 145 | GET /trends/v0/content 146 | ``` 147 | 148 | Optionally all the parameters from the previous section "Common Request 149 | Options" can be used. 150 | 151 | Another example, limiting the results to be trending in the last two 152 | hours and to no more than 10 results: 153 | 154 | ```http 155 | GET /trends/v0/content?withinLastHours=2&maxCount=10 156 | ``` 157 | 158 | FASP MUST respond with an HTTP status code `200` (OK) and a JSON object 159 | that contains a single key, `content`. The value of that key is an array 160 | of objects. 161 | 162 | These objects include the following keys: 163 | 164 | * `uri`: The URI of the content object. 165 | * `rank`: See previous section "Common Response Attributes". 166 | 167 | These objects MUST be sorted by `rank` in descending order. 168 | 169 | Example response for a request for trending content from the last three 170 | hours: 171 | 172 | ```json 173 | { 174 | "content": [ 175 | { 176 | "uri": "https://fedi1.example.com/status/23", 177 | "rank": 100 178 | }, 179 | { 180 | "uri": "https://fedi3.example.com/posts/17", 181 | "rank": 74 182 | }, 183 | { 184 | "uri": "https://fedi2.example.com/users/1/posts/56", 185 | "rank": 55 186 | } 187 | ] 188 | } 189 | ``` 190 | 191 | ### Requesting Trending Hashtags 192 | 193 | To request trending hashtags fediverse servers can make an HTTP `GET` 194 | request to the `/trends/v0/hashtags` endpoint on the FASP. 195 | 196 | Example call: 197 | 198 | ```http 199 | GET /trends/v0/hashtags 200 | ``` 201 | 202 | Optionally all the parameters from the previous section "Common Request 203 | Options" can be used. 204 | 205 | Another example, limiting the results to be relevant to the french 206 | language: 207 | 208 | ```http 209 | GET /trends/v0/hashtags?language=fr 210 | ``` 211 | 212 | FASP MUST respond with an HTTP status code `200` (OK) and a JSON object 213 | that contains a single key, `hashtags`. The value of that key is an array 214 | of objects. 215 | 216 | These objects include the following keys: 217 | 218 | * `name`: The name of the hashtag. 219 | * `rank`: See previous section "Common Response Attributes". 220 | * `examples`: An array of URIs of content that uses the hashtag. See 221 | section "Availability of Content for Hashtags and Links" above for a 222 | rationale. 223 | 224 | These objects MUST be sorted by `rank` in descending order. 225 | 226 | Example response for a request for trending hashtags from the last three 227 | hours: 228 | 229 | ```json 230 | { 231 | "hashtags": [ 232 | { 233 | "name": "#fediscovery", 234 | "rank": 100, 235 | "examples": [ 236 | "https://fedi1.example.com/status/23", 237 | "https://fedi3.example.com/posts/17", 238 | "https://fedi2.example.com/users/1/posts/56" 239 | ] 240 | }, 241 | { 242 | "name": "#cats", 243 | "rank": 72, 244 | "examples": [ 245 | "https://fedi3.example.com/posts/89", 246 | "https://fedi1.example.com/status/976", 247 | "https://fedi2.example.com/users/83/posts/26" 248 | ] 249 | } 250 | ] 251 | } 252 | ``` 253 | 254 | ### Requesting Trending Links 255 | 256 | To request trending links fediverse servers can make an HTTP `GET` 257 | request to the `/trends/v0/links` endpoint on the FASP. 258 | 259 | Example call: 260 | 261 | ```http 262 | GET /trends/v0/links 263 | ``` 264 | 265 | Optionally all the parameters from the previous section "Common Request 266 | Options" can be used. 267 | 268 | Another example, requesting at most the top 5 links from the last week: 269 | 270 | ```http 271 | GET /trends/v0/links?maxCount=5&withinLastHours=168 272 | ``` 273 | 274 | FASP MUST respond with an HTTP status code `200` (OK) and a JSON object 275 | that contains a single key, `links`. The value of that key is an array 276 | of objects. 277 | 278 | These objects include the following keys: 279 | 280 | * `url`: The URL of the link. 281 | * `rank`: See previous section "Common Response Attributes". 282 | * `examples`: An array of URIs of content that includes the link. See 283 | section "Availability of Content for Hashtags and Links" above for a 284 | rationale. 285 | 286 | These objects MUST be sorted by `rank` in descending order. 287 | 288 | Example response for a request for trending links from the last three 289 | hours: 290 | 291 | ```json 292 | { 293 | "links": [ 294 | { 295 | "url": "https://blog.example.com/posts/23", 296 | "rank": 100, 297 | "examples": [ 298 | "https://fedi1.example.com/status/23", 299 | "https://fedi3.example.com/posts/17", 300 | "https://fedi2.example.com/users/1/posts/56" 301 | ] 302 | }, 303 | { 304 | "url": "https://news.example.com/articles/45", 305 | "rank": 72, 306 | "examples": [ 307 | "https://fedi3.example.com/posts/89", 308 | "https://fedi1.example.com/status/976", 309 | "https://fedi2.example.com/users/83/posts/26" 310 | ] 311 | } 312 | ] 313 | } 314 | ``` 315 | 316 | ## Privacy Policy Information 317 | 318 | With the APIs specified above fediverse servers do not share any personally 319 | identifiable or otherwise sensitive information with FASP. 320 | -------------------------------------------------------------------------------- /general/v0.1/README.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Providers: Fediverse Server Interaction 2 | 3 | This directory contains the basic specifications for the interaction 4 | between a Fediverse Auxiliary Service Provider ("FASP") and a fediverse 5 | server. 6 | 7 | ## Table of Contents 8 | 9 | * [01: Introduction](introduction.md) 10 | 11 | Introducing the concept of Fediverse Auxiliary Service Providers and 12 | the basics for this specification. 13 | 14 | * [02: Protocol Basics](protocol_basics.md) 15 | 16 | The basic building blocks of the protocol and HTTP 17 | interactions between FASPs and fediverse servers that are common to all 18 | types of FASPs. 19 | 20 | * [03: Registration](registration.md) 21 | 22 | Registering a fediverse server with a FASP, 23 | covering protocol and UX aspects. 24 | 25 | * [04: Provider info](provider_info.md) 26 | 27 | Important metadata that FASPs must offer via API to allow 28 | fediverse servers to query their service. 29 | 30 | * [05: Provider Specification](provider_specifications.md) 31 | 32 | Common requirements for all FASP specifications. 33 | 34 | ## OpenAPI 35 | 36 | There are two experimental OpenAPI specification files, 37 | [FASP API](provider_openapi.yml) and [Server API](server_openapi.yml), 38 | included with this specification. 39 | -------------------------------------------------------------------------------- /general/v0.1/introduction.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Providers: Fediverse Server Interaction 2 | 3 | ## 01: Introduction 4 | 5 | This document introduces the concept of Fediverse Auxiliary Service 6 | Providers ("FASPs"), third-party services that fediverse server software can use to 7 | perform a variety of tasks, and defines the way such FASPs are configured 8 | within fediverse server software and how the two communicate. 9 | 10 | ### Fediverse Auxiliary Service Providers 11 | 12 | The fediverse is a decentralized network of servers running different software 13 | that can interoperate by using the ActivityPub protocol. 14 | 15 | ![Fediverse instances communicating with each other](../../images/instances_federating.svg) 16 | 17 | The different sofware offerings have different use cases, e.g. 18 | micro-blogging or photo sharing, and different requirements. Fediverse servers, even when 19 | using the same software, may differ in many ways (e.g. number of users, 20 | funding, number of administrative / moderation staff etc.). 21 | 22 | Some tasks that are useful to many fediverse servers regardless of 23 | the software used are either hard or even impossible for a single 24 | instance to perform. Or, every instance performing that task independently has serious 25 | downsides. 26 | 27 | Examples of such tasks are: 28 | 29 | * Search and discovery: No single fediverse server has a complete view of the 30 | full network, and if it had, that would be very expensive for each server, and result 31 | in a lot of duplicated content across the network. 32 | * Link preview generation: All fediverse servers fetching a web page to generate 33 | a link preview once a single post with a link is being federated 34 | results in the target web site being deluged with requests in a short 35 | timeframe. 36 | * SPAM detection: This is not an easy problem to solve and every single 37 | fediverse software having to implement their own solution seems 38 | wasteful. Also, it really helps to fight this efficiently if able 39 | to work on data from multiple fediverse servers. 40 | 41 | FASPs are software services that can 42 | assist fediverse servers in performing one or more of these tasks. A server 43 | administrator can decide to connect to one or more FASPs, either to 44 | perform different tasks or to complement each other when performing the 45 | same task. 46 | 47 | ![Fediverse instances using difference auxiliary service providers](../../images/instances_using_providers.svg) 48 | 49 | To learn more about search and discovery related FASPs, please visit 50 | the [website of the "Fediverse Discovery Providers" project](https://fediscovery.org). 51 | 52 | To learn more about trust and safety related use cases, please refer to 53 | [this blog post](https://renchap.com/blog/post/evolving_mastodon_trust_and_safety/). 54 | 55 | ### Fediverse Server Interaction 56 | 57 | Regardless of their exact capabilities, *all* FASPs have a common 58 | way of interacting with fediverse servers. This document 59 | specifies these common interactions up to the point where specific 60 | capabilities can be used. These specific capabilities (search, spam 61 | detection etc.) are the subject of their own respective specifications 62 | which all build on this one. 63 | 64 | The common interactions are: 65 | 66 | 1. Registration with the FASP 67 | 2. Setup of the FASP within the fediverse software 68 | 3. Display and selection of FASP capabilities 69 | 4. The ability of the fediverse server to authenticate with the 70 | FASP and call its APIs 71 | 5. The ability of the FASP to authenticate with the fediverse server and 72 | call its APIs 73 | 74 | Please note that 4. and 5. are not the same. Some interactions might not 75 | need both directions, but many do. Imagine a search FASP, where the 76 | fediverse server can perform a search by calling into the FASP (4.), but the 77 | FASP might also call into the fediverse server to request historic data to 78 | index (5.). Compute-intensive services might be triggerd by a fediverse server 79 | (4.) but only call-back later (5.) with the results once the computation 80 | has finished. 81 | 82 | --- 83 | 84 | Next: [02: Protocol Basics](protocol_basics.md) 85 | -------------------------------------------------------------------------------- /general/v0.1/protocol_basics.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Providers: Fediverse Server Interaction 2 | 3 | ## 02: Protocol Basics 4 | 5 | This document introduces some basic API endpoints FASPs and 6 | fediverser servers need to implement. All other endpoints depend on what services 7 | the FASP offers and are documented in the respective 8 | FASP specifications. 9 | 10 | There are some common aspects that are mandatory for all FASPs or 11 | shared between many. 12 | 13 | ### Definition of Terms and Conventions 14 | 15 | The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in 16 | this document are to be interpreted as described in 17 | [RFC-2119](https://tools.ietf.org/html/rfc2119.html). 18 | 19 | All examples and descriptions of API calls include path names that are 20 | intended to be relative to a given base URL. Base URLs are discovered / 21 | exchanged during [registration](registration.md). For the sake of 22 | brevity all examples here and in provider specifications assume the base 23 | URL to not contain any paths. Implementations MUST consider the base URL 24 | and prefix all API paths accordingly if the base URL contains any path 25 | segments. 26 | 27 | ### General Approach and Building Blocks 28 | 29 | This specification aims to define as little new protocol as possible. 30 | Instead, existing protocols and technologies that many fediverse 31 | software projects already use should be re-used wherever 32 | possible. This approach SHOULD be taken by all FASP specifications 33 | that build on this one. 34 | 35 | Communication between fediverse server and FASP MUST use HTTPS in production 36 | or production-like settings. This requirement MAY be relaxed in 37 | development environments. 38 | 39 | Custom API calls are HTTPS calls sending, if necessary, JSON data 40 | (`Content-Type: application/json`) and receiving JSON data. 41 | 42 | ### Base URL 43 | 44 | As mentioned above both FASP and fediverse software MUST implement the 45 | API endpoints specified here relative to a base URL of their own 46 | choosing. This allows existing fediverse software and existing software 47 | projects that want to add the ability to act as FASP to implement this 48 | without confliciting with their existing API endpoints. 49 | 50 | To make the initial registrations of a FASP with a fediverse server 51 | easier, fediverse software MUST include their base URL as part of the 52 | `metadata` of their `nodeinfo` accessible via the `.well-known/nodeinfo` 53 | endpoint. 54 | 55 | 56 | Example `nodeinfo`: 57 | 58 | ```json 59 | { 60 | "version": "2.0", 61 | "software": { 62 | "name": "fediexample", 63 | "version": "6.2.7" 64 | }, 65 | "protocols": [ 66 | "activitypub" 67 | ], 68 | "services": { 69 | "outbound": [], 70 | "inbound": [] 71 | }, 72 | "openRegistrations": false, 73 | "metadata": { 74 | "nodeName": "fedi", 75 | "faspBaseUrl": "https://fedi.example.com/fasp" 76 | } 77 | } 78 | ``` 79 | 80 | ### Request Integrity 81 | 82 | In order to allow both parties to verify the integrity of message 83 | contents, all requests MUST contain a `content-digest` HTTP header as 84 | defined by [RFC-9530](https://tools.ietf.org/html/rfc9530.html). 85 | 86 | The hashing algorith used MUST be SHA-256. 87 | 88 | ### Authentication 89 | 90 | As described in [03: Registration](registration.md) both FASP and 91 | fediverse server generate a unique public/private keypair and exchange 92 | the public keys and an associated identifier with each other. 93 | 94 | API requests are being authenticated by HTTP Message Signatures as defined in 95 | [RFC-9421](https://tools.ietf.org/html/rfc9421.html). 96 | 97 | The signature algorithm used is "EdDSA Using Curve edwards25519". 98 | Signatures cover signature parameters, the derived components `@method` 99 | and `@target-uri` and the HTTP header `content-digest` (see previous 100 | section). 101 | 102 | When signing requests, the `keyid` parameter MUST be the identifier 103 | exchanged during registration, so the other side can infer the 104 | corresponding public key. 105 | 106 | The required signature parameters are `created` and `keyid`. 107 | 108 | Example headers: 109 | 110 | ```http 111 | Content-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=: 112 | Signature-Input: sig1=("@method" "@target-uri" "content-digest"); created=1728467285; 113 | keyid="b2ks6vm8p23w" 114 | Signature: sig1=:+CcncFjyE+JAuwJO8MOEhRdyfShQz59e9bWDYGN3hoBorVp69k4V2PvS7zJiAoX3QchMlc47sUF4DsptUN+rDQ==: 115 | ``` 116 | 117 | The signature MUST be verified by the receiving party using the public 118 | key belonging to the transmitted identifier (`keyid` parameter). 119 | 120 | To ensure the integrity of the request, the derived components `@method` 121 | and `@target-uri` SHOULD be verified. Additionally the integrity of the 122 | `content-digest` HTTP header and its validity SHOULD be checked. 123 | 124 | It SHOULD be verified that the `created` timestamp is within an 125 | acceptable range, allowing for time drift between servers. 126 | 127 | If this validation fails the response MUST use the HTTP status code 128 | `401` (Unauthorized). 129 | 130 | Responses to API requests MUST be signed in the same way, except that 131 | they MUST use the derived component `@status` and the `content-digest` 132 | HTTP header to generate the signature base. 133 | 134 | ### Rate Limiting 135 | 136 | FASPs MAY impose rate limiting on API endpoints, e.g. if the requested capability is 137 | resource intensive. These rate limits are not part of a FASP 138 | specification as they may differ between implementations or even 139 | between installations. 140 | 141 | If rate limits are imposed, FASP MUST return the HTTP status code `429` 142 | (Too Many Requests) on rate-limited responses and provide a 143 | `Retry-After` HTTP header (as defined by 144 | [RFC-9110](https://tools.ietf.org/html/rfc9110.html)) with the number of 145 | seconds the fediverse server needs to wait before it can retry this 146 | particular request. 147 | 148 | Fediverse server software SHOULD be able to handle these responses and 149 | respect the `Retry-After` header. 150 | 151 | --- 152 | 153 | Next: [03: Registration](registration.md) 154 | -------------------------------------------------------------------------------- /general/v0.1/provider_info.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Providers: Fediverse Server Interaction 2 | 3 | ## 04: FASP Information 4 | 5 | Every FASP must offer a FASP information API endpoint that can be queried to obtain information about the FASP. 6 | 7 | This endpoint can be queried using a `GET` call to `/provider_info`. 8 | 9 | Example call: 10 | 11 | ```http 12 | GET /provider_info 13 | ``` 14 | 15 | Example response: 16 | 17 | ```json 18 | { 19 | "name": "Example FASP", 20 | "privacyPolicy": [ 21 | { 22 | "url": "https://fasp.example.com/privacy.html", 23 | "language": "en" 24 | } 25 | ], 26 | "capabilities": [ 27 | { 28 | "id": "trends", 29 | "version": "1.0" 30 | }, 31 | { 32 | "id": "account_search", 33 | "version": "1.0" 34 | } 35 | ], 36 | "signInUrl": "https://fasp.example.com/sign_in", 37 | "contactEmail": "support@fasp.example.com", 38 | "fediverseAccount": "@fasp@fedi.example.com" 39 | } 40 | ``` 41 | 42 | The FASP info MUST contain the keys `name`, `privacyPolicy` and 43 | `capabilities`. The key `signInUrl` MUST be present if the FASP offers a 44 | way for a fediverse server administrator to sign in (e.g. to edit settings, show 45 | statistics etc.). Otherwise it MAY be absent. 46 | 47 | The values are defined as follows: 48 | 49 | * `name`: This MUST be a non-empty string containing the name of this FASP. 50 | This is the name of this installation of the FASP software. It will be 51 | displayed to fediverse server administrators and SHOULD be as descriptive as possible 52 | for them to identify the FASP. 53 | * `privacyPolicy`: This MUST be an array. In case the provider does not 54 | receive any kind of personally identifiable information or other data that 55 | might be considered sensitive this MAY be empty. Otherwise it MUST contain 56 | one object containing the keys `url` and `language` for each language the 57 | privacy policy is available in: 58 | * `url`: URL of the publicly available privacy policy. Fediverse server administrators 59 | may link to this in their own privacy policy. 60 | * `language`: An ISO-639-1 language code representing the language of the privacy 61 | policy. 62 | * `capabilities`: This MUST be an array including one object for every 63 | capability the FASP implements. These objects contain the keys `id` and 64 | `version`: 65 | * `id`: This is the identifier of the capability. See FASP 66 | specifications for the list of capabilites and their identifiers. 67 | * `version`: The version of the specification for this capability that this 68 | FASP supports. 69 | * `signInUrl`: If present it MUST contain a string representing the URL where 70 | a fediverse server administrator can sign in to the FASP. 71 | * `contactEmail`: MAY be optionally included to communicate an email 72 | address to contact the FASP's operator(s). 73 | * `fediverseAccount`: MAY be optionally included to point to a 74 | fediverse account that can be followed to receive updates about the 75 | FASP. 76 | 77 | --- 78 | 79 | Next: [05: Provider Specifications](provider_specifications.md) 80 | -------------------------------------------------------------------------------- /general/v0.1/provider_openapi.yml: -------------------------------------------------------------------------------- 1 | openapi: 3.1.0 2 | info: 3 | title: Fediverse Auxiliary Service Providers - General provider API 4 | description: |- 5 | This file describes the basic API every "Fediverse Auxiliary 6 | Service Provider" needs to provide. 7 | 8 | See 9 | [the full specification](https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/tree/main/general/v0.1) 10 | for all the details. 11 | version: '0.1' 12 | externalDocs: 13 | description: Fediverse Auxiliary Service Provider Specifications 14 | url: https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications 15 | tags: 16 | - name: provider_info 17 | description: Information about the provider 18 | externalDocs: 19 | description: Find out more 20 | url: https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/tree/main/general/v0.1/provider_info.md 21 | paths: 22 | /provider_info: 23 | get: 24 | tags: 25 | - provider_info 26 | summary: Provider information 27 | description: Necessary information an instance needs to know about the provider 28 | operationId: showProviderInfo 29 | responses: 30 | '200': 31 | description: successful operation 32 | content: 33 | application/json: 34 | schema: 35 | $ref: '#/components/schemas/ProviderInfo' 36 | security: 37 | - provider_auth: [] 38 | components: 39 | schemas: 40 | ProviderInfo: 41 | type: object 42 | properties: 43 | name: 44 | type: string 45 | examples: ["Example provider"] 46 | privacy_policy: 47 | type: array 48 | items: 49 | $ref: '#/components/schemas/PrivacyPolicy' 50 | capabilities: 51 | type: array 52 | items: 53 | $ref: '#/components/schemas/Capability' 54 | sign_in_url: 55 | type: string 56 | format: uri 57 | examples: ["https://provider.example.com/sign_in"] 58 | PrivacyPolicy: 59 | type: object 60 | properties: 61 | url: 62 | type: string 63 | format: url 64 | examples: ["https://provider.example.com/privacy_policy.html"] 65 | language: 66 | type: string 67 | examples: ["en", "en-GB", "de-CH"] 68 | Capability: 69 | type: object 70 | properties: 71 | id: 72 | type: string 73 | examples: ["trends", "account_search"] 74 | version: 75 | type: string 76 | examples: ["0.1", "1.0", "2.4"] 77 | securitySchemes: 78 | provider_auth: 79 | type: http 80 | scheme: signature 81 | description: "HTTP Message Signatures based authentication as described in https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/blob/main/general/v0.1/protocol_basics.md" 82 | -------------------------------------------------------------------------------- /general/v0.1/provider_specifications.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Providers: Fediverse Server Interaction 2 | 3 | ## 05: FASP Specifications 4 | 5 | All FASP specifications MUST be based on this document and MUST NOT 6 | change any of the requirements stated. 7 | 8 | ### Mandatory Content 9 | 10 | Every FASP specification MUST include the following: 11 | 12 | * An identifier for the specification 13 | * A version number (see next section for details) 14 | * Optional specification dependencies 15 | * The names, identifiers and descriptions of the capabilities offered 16 | * The FASP's HTTP API endpoints 17 | * The HTTP API an instance needs to implement for the fediverse server 18 | to use (or a note that none is required) 19 | * A summary of personally identifiable information or other data that 20 | might be considered sensitive that a FASP may receive 21 | 22 | ### Identifiers 23 | 24 | Both the full specification and individual capabilities MUST have an 25 | unique identifier suitable for use in URLs. 26 | 27 | Identifiers are UTF-8 strings containing only lower-case characters and 28 | no whitespace characters. It succinctly describes the specification or 29 | capability in english using as few words as possible (ideally only a 30 | single word). If more than one word is needed they MUST be separated by 31 | an underline character (`_`). 32 | 33 | Identifiers MUST be unique, which means they must not be defined in any 34 | other provider specification. 35 | 36 | Examples of valid identifiers: 37 | 38 | * `debug` 39 | * `discovery` 40 | * `trends` 41 | * `account_search` 42 | * `media_storage` 43 | * `spam_detection` 44 | 45 | ### Versioning 46 | 47 | Every FASP specification MUST have a version number consisting of a 48 | major and a minor number, delimited by a single `.` (dot). 49 | 50 | Any change to a specification that runs the risk of being incompatible 51 | to existing implementations MUST increase the major version number. 52 | 53 | Clarifications, additions of examples etc. that are not expected to impact 54 | existing implementations SHOULD increase the minor version number. 55 | 56 | Formatting changes, spelling and grammar corrections MAY increase the 57 | minor version number. 58 | 59 | If only the details for a single capability change but the specification 60 | includes several capabilities this means the version number would change 61 | for all capabilities even for those that remain unchanged. If this 62 | happens it might be a signal that the capabilities are not closely 63 | related after all and should be extracted to their own separate 64 | specifications. 65 | 66 | ### Specification Dependencies 67 | 68 | Specifications MAY depend on other specifications. Some specifications 69 | could include shared, overarching APIs that are useful in more than one 70 | capability. In these cases other dependencies may simply state that they 71 | depend on this. Dependencies MUST always refer to a specific version of 72 | another specification. 73 | 74 | If a specification declares a dependency on another, implementers MUST 75 | also implement this other specification. 76 | 77 | ### Capabilities 78 | 79 | Every FASP specification MAY define one or more capabilities. 80 | Capabilities are units of functionality that a fediverse server admin 81 | can enable or disable. 82 | 83 | If a specification defines more than one capability, the capabilities 84 | SHOULD be strongly related. This is the case for example when all 85 | capabilities rely on some shared functionality or if an update to the 86 | specification of one capability is expected to require an update of the 87 | other as well. 88 | 89 | For every capability defined, the specification MUST include a unique 90 | identifier. See section "Identifiers" above for more details. 91 | 92 | For every capability defined, the specification MUST also include a one 93 | paragraph description in English that can be used by fediverse software 94 | to explain the capabilities to fediverse server administrators. It MAY 95 | include translations into other languages as well. 96 | 97 | ### HTTP API endpoints 98 | 99 | All specified API endpoints, be it on FASP or fediverse servers, MUST 100 | use paths relative to the base URL (see [Protocol 101 | Basics](protocol_basics.md)). 102 | 103 | When specifying URL paths or when giving examples of URL paths the base 104 | path from the base URL MAY be omitted. 105 | 106 | All relative paths MUST begin with the specification identifier as the 107 | first segment. 108 | 109 | The second segment MUST be the major version number prefixed with the 110 | lower-case letter `v`. 111 | 112 | Endpoints relating to a particular capability MUST use the capability 113 | identifier as the third path segment. 114 | 115 | FASP specifications MAY include both API endpoints that are common to 116 | all capabilities and thus use paths that are only prefixed with the 117 | specification identifier and API endpoints specific to one capability 118 | only. These must also include the capability identifier. 119 | 120 | For the first case, an overarching functionality used by more than one 121 | capability, the pattern for paths looks like this: 122 | 123 | ``` 124 | //v/ 125 | ``` 126 | 127 | For the second case, functionality belonging to one specific capability, 128 | the pattern looks like this: 129 | 130 | ``` 131 | //v// 132 | ``` 133 | 134 | For example, a hypothetical `spam_detection` specification could have 135 | different capabilities for classifying different types of content (post 136 | text, accounts, images etc.) that use a shared vocabulary. 137 | 138 | Getting the vocabulary via an endpoint would be a common functionality 139 | not tied to any one of the capabilities and could thus result in the 140 | following path: 141 | 142 | ``` 143 | /spam_detection/v2/vocabulary 144 | ``` 145 | 146 | And an endpoint that is tied to and only used for the 147 | `image_classification` capability could have the following path: 148 | 149 | ``` 150 | /spam_detection/v2/image_classification/classification 151 | ``` 152 | 153 | ### Privacy Policy Information 154 | 155 | FASPs may receive personally identifiable information and other data 156 | that some people might consider sensitive. This must then become part of 157 | a fediverse server's privacy policy to inform users of what data is being 158 | processed, by whom, and how. 159 | 160 | Since FASP specifications define exactly what data the FASP can 161 | receive, they MUST include a summary noting which of this data is to be 162 | considered sensitive and why it needs to be processed by the FASP. 163 | 164 | This summary MUST make it easy to copy this directly into the privacy 165 | policies of fediverse servers. 166 | -------------------------------------------------------------------------------- /general/v0.1/registration.md: -------------------------------------------------------------------------------- 1 | # Fediverse Auxiliary Service Providers: Fediverse Server Interaction 2 | 3 | ## 03: Registration 4 | 5 | ### Registering with a FASP 6 | 7 | When an administrator of a fediverse server software decides to start using a 8 | FASP, they MAY be required to register with the provider. Every FASP 9 | MAY have different requirements when it comes to fediverse server 10 | registration. Different technical, 11 | organisational or legal requirements may apply. Thus, this document does 12 | not impose any hard requirements on that process, except for the end 13 | result. 14 | 15 | A FASP SHOULD document the process a fediverse server should use to register, 16 | even when FASP registration is closed or by invitation only. 17 | 18 | A FASP SHOULD list its capabilities and MAY name fediverse software 19 | that is known to be compatible. 20 | 21 | A FASP MAY provide a web-based form to register. Please see below 22 | for an example. 23 | 24 | During registration the provider MAY request data from the fediverse server 25 | administrator. This MAY include but is not limited to the following: 26 | 27 | * Email address and/or other contact data of the adminstrator 28 | * A password of other means of authentication, so the administrator can 29 | sign-in again later 30 | * Acceptance of terms of service, data processing agreement, and/or privacy policy 31 | 32 | As part of the registration process the fediverse server administrator 33 | MUST provide the URL of their server. The FASP MUST use this URL to 34 | discover the base URL for FASP interaction using the 35 | `.well-known/nodeinfo` mechanism as described in [protocol basics](protocol_basics.md). 36 | 37 | A successful registration results in the FASP creating an Ed25519 38 | keypair and an unique identifier (ID) for the fediverse server. 39 | 40 | After registration, FASP MUST make an HTTP `POST` request to the 41 | fediverse server's `/registration` endpoint. 42 | 43 | The payload of that request is a JSON object with the following keys and 44 | values: 45 | 46 | * `name`: The name of the FASP - this MUST have been presented to the 47 | administrator during registration to make it recognizable. 48 | * `baseUrl`: The base URL of the FASP 49 | * `serverId`: The identifier for the server that the FASP generated 50 | * `publicKey`: The public key of the FASP, base64 encoded 51 | 52 | An example payload: 53 | 54 | ``` 55 | { 56 | "name": "Example FASP", 57 | "baseUrl": "https://fasp.example.com", 58 | "serverId": "b2ks6vm8p23w", 59 | "publicKey": "FbUJDVCftINc9FlgRu2jLagCVvOa7I2Myw8aidvkong=" 60 | } 61 | ``` 62 | 63 | As a result the fediverse server MUST persist this information as a 64 | request for FASP registration and generate an unique ID for the FASP and 65 | its own Ed25519 keypair for authenticating with the FASP. It MUST then 66 | reply with an HTTP status code `201` (Created) and a JSON object that 67 | contains the following keys and values: 68 | 69 | * `faspId`: The identifier the server generated for the FASP 70 | * `publicKey`: The public key of the fediverse server, base64 encoded 71 | * `registrationCompletionUri`: An URI to redirect to in order to finish the 72 | registration 73 | 74 | An example payload: 75 | 76 | ```json 77 | { 78 | "faspId": "dfkl3msw6ps3", 79 | "publicKey": "KvVQVgD4/WcdgbUDWH7EVaYX9W7Jz5fGWt+Wg8h+YvI=", 80 | "registrationCompletionUri": "https://fedi.example.com/admin/fasps" 81 | } 82 | ``` 83 | 84 | The FASP MUST persist this data and present the administrator with a 85 | page that explains how to finish the registration on their server. 86 | 87 | To that end it MAY present a link to the `registrationCompletionUri` it 88 | received. 89 | 90 | It MUST display a fingerprint of the FASP's public key for comparison 91 | purposes. The fingerprint is the Base64 encoded SHA-256 hash of the 92 | public key. 93 | 94 | The fediverse server MUST present a list of FASP registration requests 95 | to the administrator. This list MUST be accessible via regular means, 96 | i.e. a navigation item in the administration area. 97 | 98 | The `registrationCompletionUri` MAY lead to this list, optionally highlighting 99 | or expanding the registration in question. Alternatively it MAY lead to page 100 | that only displays the registration in question. 101 | 102 | For each registration request the fediverse server MUST display the 103 | `name` the FASP sent and the fingerprint of its public key. 104 | 105 | The administrator MUST be able to either accept or decline a 106 | registration request. 107 | 108 | The following is a sketch of how this may look in the abstract: 109 | 110 | Step 1: A fediverse server admin is presented with a registration form 111 | 112 | ![A bare-bones sign-up form asking for email, server base URL and acceptance of terms of service](../../images/server_sign_up.svg) 113 | 114 | Step 2: Upon successful registration, the fingerprint of the public key 115 | and a link / button to the fediverse server is displayed 116 | 117 | ![A webpage displaying a public key fingerprint with a button to go to the fediverse server](../../images/server_sign_up_success.svg) 118 | 119 | Step 3: The fediverse servers displays FASP registration requests, 120 | allows to compare name and fingerprint and then to either accept or deny 121 | the requests. 122 | 123 | ![A list of FASP registration requests that can be expanded. The one 124 | expanded entry shows the fingerprint and buttons to either accept or 125 | deny the request.](../../images/fasp_registration_requests.svg) 126 | 127 | ### Selecting Capabilities 128 | 129 | FASPs might implement any number of specificatons. As a last step in the 130 | setup process the fediverse server administrator needs to select which 131 | capabilities of the FASP they want to use. 132 | 133 | In order to display available capabilities the fediverse server MUST 134 | call the FASP info API endpoint (see 135 | [04: Provider Info](provider_info.md) for a detailed description). 136 | 137 | The response includes a list of capability identifiers (see 138 | [05: Provider Specification](provider_specifications.md) for details) 139 | and supported version numbers. 140 | 141 | The fediverse software MUST present the administrator with the 142 | capabilities that the FASP supports. 143 | 144 | ![A web form on the instance that allows to select capabilities that both parties support](../../images/select_capabilities.svg) 145 | 146 | When the administrator enables a capability the fediverse server MUST 147 | notify FASP by making an HTTP `POST` call to the 148 | `/capabilities///activation` endpoint. 149 | `` and `` MUST be replaced with the identifier and 150 | version of the capability. 151 | 152 | Example call: 153 | 154 | ```http 155 | POST /capabilities/debug/2/activation 156 | ``` 157 | 158 | FASP MUST respond with an HTTP status code `204` (No Content) if the 159 | message was successfully received and with an HTTP status code `404` 160 | (Not Found) if the capability is not known or not supported by this 161 | FASP. 162 | 163 | When an administrator disables a capability that was formerly enabled 164 | the fediverse server MUST make an HTTP `DELETE` call to the same 165 | endpoint. 166 | 167 | Example call: 168 | 169 | ```http 170 | DELETE /capabilities/trends/1/activation 171 | ``` 172 | 173 | FASP MUST respond with an HTTP status code `204`. 174 | 175 | FASP MUST NOT make any calls to a fediverse server's APIs belonging to a 176 | capability that is not enabled. 177 | 178 | --- 179 | 180 | Next: [04: Provider Info](provider_info.md) 181 | -------------------------------------------------------------------------------- /general/v0.1/server_openapi.yml: -------------------------------------------------------------------------------- 1 | openapi: 3.1.0 2 | info: 3 | title: Fediverse Auxiliary Service Providers - General fediverse server API 4 | description: |- 5 | This file describes the basic API every fediverse server that wants 6 | to interface with "Fediverse Auxiliary Service Provider" needs to 7 | provide. 8 | 9 | See 10 | [the full specification](https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/tree/main/general/v0.1) 11 | for all the details. 12 | version: '0.1' 13 | externalDocs: 14 | description: Fediverse Auxiliary Service Provider Specifications 15 | url: https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications 16 | tags: 17 | - name: provider_registration 18 | description: FASP registration with the fediverse server 19 | externalDocs: 20 | description: Find out more 21 | url: https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/tree/main/general/v0.1/registration.md 22 | paths: 23 | /registration: 24 | post: 25 | tags: 26 | - provider_registration 27 | summary: Provider registration 28 | description: Endpoint for a FASP to send registration information as part of the registration process between FASP and fediverse server. 29 | operationId: createRegistration 30 | requestBody: 31 | content: 32 | application/json: 33 | schema: 34 | $ref: '#/components/schemas/ProviderRegistrationInfo' 35 | responses: 36 | '201': 37 | description: successful operation 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/ServerRegistrationInfo' 42 | security: 43 | - provider_auth: [] 44 | components: 45 | schemas: 46 | ProviderRegistrationInfo: 47 | type: object 48 | properties: 49 | name: 50 | type: string 51 | examples: ["Example FASP"] 52 | baseUrl: 53 | type: string 54 | format: url 55 | examples: ["https://fasp.example.com/subdir/"] 56 | serverId: 57 | type: string 58 | examples: ["b2ks6vm8p23w", "admin@fediverse-server.example.com"] 59 | publicKey: 60 | type: string 61 | examples: ["FbUJDVCftINc9FlgRu2jLagCVvOa7I2Myw8aidvkong="] 62 | ServerRegistrationInfo: 63 | type: object 64 | properties: 65 | faspId: 66 | type: string 67 | examples: ["dfkl3msw6ps3", "example-fasp"] 68 | publicKey: 69 | type: string 70 | examples: ["KvVQVgD4/WcdgbUDWH7EVaYX9W7Jz5fGWt+Wg8h+YvI="] 71 | registrationCompletionUri: 72 | type: string 73 | format: url 74 | examples: ["https://fedi.example.com/admin/fasps"] 75 | securitySchemes: 76 | provider_auth: 77 | type: http 78 | scheme: signature 79 | description: "HTTP Message Signatures based authentication as described in https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/blob/main/general/v0.1/protocol_basics.md" 80 | -------------------------------------------------------------------------------- /images/debug_logs.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 15 | 16 | 17 | Debug LogsInstanceIPTimestampPayloadinstance.example.com 192.168.0.12 2024-09-24 09:20:31 UTC{"test": "hello"}other.example.com 10.10.234.54 2024-09-23 11:27:38 UTCinstance.example.com 192.168.0.12 2024-09-22 10:55:11 UTCother.example.com 10.10.234.54 2024-09-23 10:11:01 UTC{"a": "b"} -------------------------------------------------------------------------------- /images/debug_provider_details.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 15 | 16 | 17 | Auxiliary Service ProviderIPTimestampPayload192.168.0.14 2024-09-24 09:20:31 UTC{"test": "hello"}192.168.0.14 2024-09-23 10:11:01 UTC{"a": "b"}Name: debug.example.comCapabilities: debugDebug Callbacks:Initiate Debug Call -------------------------------------------------------------------------------- /images/instances_federating.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /images/select_capabilities.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 19 | 20 | 21 | Select CapabilitiesSaveSelect which capabilities of theprovideryou would like to use.provider.example.comTrendsAggregate and compute trends.Account SearchIndex and search user accounts. -------------------------------------------------------------------------------- /images/server_sign_up.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 15 | 16 | 17 | admin@fedi.example.comYour emailhttps://fedi.example.com/auxFASP base URL of your serverI accept the terms ofthis serviceSubmit**************Your passwordServer Sign-Up -------------------------------------------------------------------------------- /images/server_sign_up_success.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 15 | 16 | 17 | Sign-up successful!Complete Registration Please complete the registrationon your server.Make sure you are signed in toyour server before clicking onthe link below, or navigate toyour FASP settings manually.DO NOT blindly accept FASPregistration requests. To makesure the request is genuineplease compare the followingfingerprint with what is beingdisplayed on your server:TDv+IcK2AqAe/DDF9iNc4Y13jeaqf9HCkfbLf1X8aI4= --------------------------------------------------------------------------------