start on docs

docs/admin/domain_blocks.md

@@ -2,7 +2,7 @@
 
 GoToSocial supports 'blocking'/'suspending' domains that you don't want your instance to federate with. In our documentation, the two terms 'block' and 'suspend' are used interchangeably with regard to domains, because they mean the same thing: preventing your instance and the instance running on the target domain from communicating with one another, effectively cutting off federation between the two instances.
 
-You can view, create, and remove domain blocks and domain allows using the [instance admin panel](./settings.md#federation).
+You can view, create, and remove domain blocks and domain allows using the [instance admin panel](./settings.md#domain-permissions).
 
 This document focuses on what domain blocks actually *do* and what side effects are processed when you create a new domain block.
 

docs/admin/domain_permission_subscriptions.md

@@ -0,0 +1,135 @@
+# Domain Permission Subscriptions
+
+Via the [admin settings panel](./settings.md#subscriptions), you can create and manage domain permission subscriptions.
+
+Domain permission subscriptions allow you to specify a URL at which a permission list is hosted. Every 24hrs at 11pm (by default), your instance will fetch and parse each subscribed list, and create domain permissions (or domain permission drafts) based on entries in the lists.
+
+## Limitations
+
+Currently, via blocklist subscriptions it is only possible to create "suspend" level domain blocks; other severities are not yet supported. Entries of severity "silence" or "limit" etc. on subscribed blocklists will be skipped.
+
+## Priority
+
+When you specify multiple domain permission subscriptions, they will be fetched and parsed in order of priority, from highest priority (255) to lowest priority (0).
+
+Permissions discovered on lists higher up in the priority ranking will override permissions on lists lower down in the priority ranking.
+
+aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+
+## Orphan Permissions
+
+aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+
+## Fun Stuff To Do With Domain Permission Subscriptions
+
+### 1. Create an allowlist-federation cluster.
+
+Domain permission subscriptions make it possible to easily create allowlist-federation clusters, ie., a group of instances can essentially form their own mini-fediverse, wherein each instance runs in [allowlist federation mode](./federation_modes.md#allowlist-federation-mode), and subscribes to a cooperatively-managed allowlist hosted somewhere.
+
+For example, instances `instance-a.example.org`, `instance-b.example.org`, and `instance-c.example.org` decide that they only want to federate with each other.
+
+Using some version management platform like GitHub, they host a plaintext-formatted allowlist at something like `https://raw.githubusercontent.com/our-cluster/allowlist/refs/heads/main/allows.txt`.
+
+The contents of the plaintext-formatted allowlist are as follows:
+
+```text
+instance-a.example.org
+instance-b.example.org
+instance-c.example.org
+```
+
+Each instance admin sets their federation mode to `allowlist`, and creates a subscription to create allows from `https://raw.githubusercontent.com/our-cluster/allowlist/refs/heads/main/allows.txt`, which results in domain allow entries being created for their own domain, and for each other domain in the cluster.
+
+At some point, someone from `instance-d.example.org` asks (out of band) whether they can be added to the cluster. The existing admins agree, and update their plaintext-formatted allowlist to read:
+
+```text
+instance-a.example.org
+instance-b.example.org
+instance-c.example.org
+instance-d.example.org
+```
+
+The next time each instance fetches the list, a new domain allow entry will be created for `instance-d.example.org`, and it will be able to federate with the other domains on the list.
+
+### 2. Cooperatively manage a blocklist.
+
+Domain permission subscriptions make it easy to collaborate on and subscribe to shared blocklists of domains that host illegal / fashy / otherwise undesired accounts and content.
+
+For example, the admins of instances `instance-e.example.org`, `instance-f.example.org`, and `instance-g.example.org` decide that they are tired of duplicating work by playing whack-a-mole with bad actors. To make their lives easier, they decide to collaborate on a shared blocklist.
+
+Using some version management platform like GitHub, they host a blocklist at something like `https://raw.githubusercontent.com/baddies/blocklist/refs/heads/main/blocks.csv`.
+
+When someone discovers a new domain hosting an instance they don't like, they can open a pull request or similar against the list, to add the questionable instance to the domain.
+
+For example, someone gets an unpleasant reply from a new instance `fashy-arseholes.example.org`. Using their collaboration tools, they propose adding `fashy-arseholes.example.org` to the blocklist. After some deliberation and discussion, the domain is added to the list.
+
+The next time each of `instance-e.example.org`, `instance-f.example.org`, and `instance-g.example.org` fetch the block list, a block entry will be created for ``fashy-arseholes.example.org``.
+
+### 3. Subscribe to a blocklist, but ignore some of it.
+
+Say that `instance-g.example.org` in the previous section decides that they agree with most of the collaboratively-curated blocklist, but they actually would like to keep federating with ``fashy-arseholes.example.org`` for some godforsaken reason.
+
+This can be done in one of two ways:
+
+1. The admin of `instance-g.example.org` creates an explicit domain allow entry for `fashy-arseholes.example.org` on their own instance. Because their instance is running in `blocklist` federation mode, [the explicit allow overrides the domain block entry](./federation_modes.md#in-blocklist-mode), and so the domain remains unblocked.
+2. Before the blocklist is re-fetched, the admin of `instance-g.example.org` creates a [domain permission exclude](./settings.md#excludes) entry for ``instance-g.example.org``. The domain ``instance-g.example.org`` then becomes exempt/excluded from automatic permission creation, and so the block for ``instance-g.example.org`` on the shared blocklist does not get created in the database of ``instance-g.example.org`` the next time the list is fetched.
+
+### 4. Subscribe directly to another instance's blocklist.
+
+Because GoToSocial is able to fetch and parse JSON-formatted lists of domain permissions, it is possible to subscribe directly to another instance's list of blocked domains via their `/api/v1/instance/domain_blocks` (Mastodon) or `/api/v1/instance/peers?filter=suspended` (GoToSocial) endpoint (if exposed).
+
+For example, the Mastodon instance `peepee.poopoo.example.org` exposes their block list publicly, and the owner of the GoToSocial instance `instance-h.example.org` decides they quite like the cut of the Mastodon moderator's jib. They create a domain permission subscription of type JSON, and set the URI to `https://peepee.poopoo.example.org/api/v1/instance/domain_blocks`. Every 24 hours, their instance will go fetch the blocklist JSON from the Mastodon instance, and create permissions based on entries discovered therein.
+
+## Example lists per content type
+
+Shown below are examples of the different permission list formats that GoToSocial is able to understand and parse.
+
+Each list contains three domains, `bumfaces.net`, `peepee.poopoo`, and `nothanks.com`.
+
+### CSV
+
+CSV lists use content type `text/csv`.
+
+Mastodon domain permission exports generally use this format.
+
+```csv
+#domain,#severity,#reject_media,#reject_reports,#public_comment,#obfuscate
+bumfaces.net,suspend,false,false,big jerks,false
+peepee.poopoo,suspend,false,false,harassment,false
+nothanks.com,suspend,false,false,,false
+```
+
+### JSON (application/json)
+
+JSON lists use content type `application/json`.
+
+```json
+[
+  {
+    "domain": "bumfaces.net",
+    "suspended_at": "2020-05-13T13:29:12.000Z",
+    "public_comment": "big jerks"
+  },
+  {
+    "domain": "peepee.poopoo",
+    "suspended_at": "2020-05-13T13:29:12.000Z",
+    "public_comment": "harassment"
+  },
+  {
+    "domain": "nothanks.com",
+    "suspended_at": "2020-05-13T13:29:12.000Z"
+  }
+]
+```
+
+### Plaintext (text/plain)
+
+Plaintext lists use content type `text/plain`.
+
+Note that it is not possible to include any fields like "obfuscate" or "public comment" in plaintext lists, as they are simply a newline-separated list of domains.
+
+```text
+bumfaces.net
+peepee.poopoo
+nothanks.com
+```

docs/admin/settings.md

@@ -34,11 +34,11 @@ Clicking on the username of the reported account opens that account in the 'Acco
 
 You can use this section to search for an account and perform moderation actions on it.
 
-### Federation
+### Domain Permissions
 
 ![List of suspended instances, with a field to filter/add new blocks. Below is a link to the bulk import/export interface](../public/admin-settings-federation.png)
 
-In the federation section you can create, delete, and review explicit domain blocks and domain allows.
+In the domain permissions section you can create, delete, and review domain blocks, domain allows, drafts, excludes, and subscriptions.
 
 For more detail on federation settings, and specifically how domain allows and domain blocks work in combination, please see [the federation modes section](./federation_modes.md), and [the domain blocks section](./domain_blocks.md).
 
@@ -46,20 +46,99 @@ For more detail on federation settings, and specifically how domain allows and d
 
 You can enter a domain to suspend in the search field, which will filter the list to show you if you already have a block for it.
 
-Clicking 'suspend' gives you a form to add a public and/or private comment, and submit to add the block. Adding a suspension will suspend all the currently known accounts on the instance, and prevent any new interactions with any user on the blocked instance.
+Clicking 'suspend' gives you a form to add a public and/or private comment, and submit to add the block.
+
+Adding a domain block will suspend all currently known accounts from that domain, and prevent any new interactions with the blocked domain.
 
 #### Domain Allows
 
 The domain allows section works much like the domain blocks section, described above, only for explicit domain allows rather than domain blocks.
 
-#### Bulk import/export
+#### Import/export
 
-Through the link at the bottom of the Federation section (or going to `/settings/admin/federation/import-export`) you can do bulk import/export of blocklists and allowlists.
+In this section you can do bulk import/export of domain permissions in JSON, CSV, or plaintext formats.
 
 ![List of domains included in an import, providing ways to select some or all of them, change their domains, and update the use of subdomains.](../public/admin-settings-federation-import-export.png)
 
 Upon importing a list, either through the input field or from a file, you can review the entries in the list before importing a subset. You'll also be warned for entries that use subdomains, providing an easy way to change them to the main domain.
 
+#### Drafts
+
+In this section you can create, search through, accept, and reject domain permission drafts.
+
+Domain permission drafts are domain permissions that have been proposed (either via manual creation or as an entry from a subscribed block / allow list), but have not yet come into force.
+
+Until it is accepted, a domain permission draft will not have any effect on federation with the domain it targets. Upon acceptance, it will be converted into either a domain block or a domain allow, and start being enforced.
+
+#### Excludes
+
+In this section, you can create, search through, and remove domain permission excludes.
+
+Domain permission excludes prevent permissions for a domain (and all subdomains) from being automatically managed by domain permission subscriptions.
+
+For example, if you create an exclude entry for the domain `example.org`, then a blocklist or allowlist subscription will exclude entries for `example.org` and any of its subdomains (`sub.example.org`, `another.sub.example.org` etc.) when creating domain permission drafts and domain blocks/allows.
+
+This functionality allows you to manually manage permissions for excluded domains, in cases where you know you definitely do or don't want to federate with a given domain, no matter what entries are contained in a domain permission subscription.
+
+Note that by itself, creation of an exclude entry for a given domain does not affect federation with that domain at all, it is only useful in combination with permission subscriptions.
+
+#### Subscriptions
+
+In this section, you can create, search through, edit, test, and remove domain permission subscriptions.
+
+Domain permission subscriptions allow you to specify a URL at which a permission list is hosted. Every 24hrs at 11pm (by default), your instance will fetch and parse each subscribed list, and create domain permissions (or domain permission drafts) based on entries in the lists.
+
+##### Title
+
+You can optionally use the title field to set a title for the subscription, as a reminder for yourself and other admins.
+
+For example, you might subscribe to a list at `https://lists.example.org/baddies.csv` and set the title of the subscription to something that reflects the contents of that list, such as "Basic block list (worst of the worst)", or similar.
+
+##### Subscription Priority
+
+When you specify multiple domain permission subscriptions, they will be fetched and parsed in order of priority, from highest priority (255) to lowest priority (0).
+
+Permissions discovered on lists higher up in the priority ranking will override permissions on lists lower down in the priority ranking.
+
+For more information on priority, please see the separate [domain permission subscriptions](./domain_permission_subscriptions.md) document.
+
+##### Permission Type
+
+You can use this dropdown to select whether permissions discovered at the list URL should be created as domain blocks, or domain allows.
+
+##### Content Type
+
+You can use this dropdown to select the content type of the list at the subscribed URL.
+
+Use CSV for Mastodon-style permission lists, plain for plaintext lists of domain names, or JSON for json-exported lists.
+
+##### Basic Auth
+
+Check this box to provide a basic auth username and/or password credential for the subscribed list, which will be sent along with each request to fetch the list.
+
+##### Adopt Orphan Permissions
+
+If you check this box, then any existing domain permissions will become managed by this subscription in the following circumstances:
+
+1. They don't already have a subscription ID (ie., they're not managed by any domain permission subscription).
+2. They match a domain permission included in the list at the URL of this subscription.
+
+For more information on orphan permissions, please see the separate [domain permission subscriptions](./domain_permission_subscriptions.md) document.
+
+##### Create Permissions as Drafts
+
+With this box checked (default), any permissions created by this subscription will be created as **drafts** which require manual approval to come into force.
+
+It is recommended to leave this box checked unless you absolutely trust the subscribed list, to avoid inadvertent blocking or allowing of domains you'd rather not block or allow.
+
+##### Test a Subscription
+
+To test whether a subscription can be successfully parsed, first create the subscription, then in the detailed view for that subscription, click on the "Test" button.
+
+If your instance is able to fetch and parse permissions at the subscription URI, then you will see a list of these after clicking "Test". Otherwise, you will see an error message.
+
+![Screenshot of the detailed view of a subscription, with arrows pointing to the test section near the bottom.](../public/admin-settings-federation-subscription-test.png)
+
 ## Administration
 
 Instance administration settings.

mkdocs.yml

@@ -138,6 +138,7 @@ nav:
       - "admin/signups.md"
       - "admin/federation_modes.md"
       - "admin/domain_blocks.md"
+      - "admin/domain_permission_subscriptions.md"
       - "admin/request_filtering_modes.md"
       - "admin/robots.md"
       - "admin/cli.md"