Diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_report_affiliations/README.markdown	Fri Nov 22 19:05:49 2024 +0000
@@ -0,0 +1,114 @@
+---
+labels:
+- 'Stage-Alpha'
+summary: 'XEP-0489: Reporting Account Affiliations'
+rockspec:
+  build:
+    modules:
+      mod_report_affiliations.traits: traits.lib.lua
+---
+
+
+This module implements [XEP-0489: Reporting Account Affiliations](https://xmpp.org/extensions/xep-0489.html).
+It can help with spam on the network, especially if you run a public server
+that allows registration.
+
+## How it works
+
+Here is the scenario: you run a public server. Despite your best efforts, and
+following the [best practices](https://prosody.im/doc/public_servers), some
+spammers still occasionally manage to register on your server. Because of
+this, other servers on the network start filtering messages from all accounts
+on your server.
+
+Enabling this module will include additional information in certain kinds of
+outgoing traffic, which allows other servers to judge the sending account,
+rather than the whole server.
+
+### When is affiliation information shared?
+
+Affiliation is shared when a user on your server:
+
+- sends a message to a user that has not (yet) authorized them
+- sends a subscription request to a user
+- sends a "directed presence" to a remote JID (for example, when joining a
+  group chat).
+
+### What information is shared?
+
+The following information is included in matching traffic:
+
+- The affiliation of the account:
+  - "guest" (the account is anonymous/temporary)
+  - "registered" (the account was self-registered)
+  - "member" (the account belongs to a recognised/trusted member of the server)
+  - "admin" (the account belongs to a server administrator)
+
+For the "registered" affiliation, the following additional items are included:
+
+- When the account was created
+- The "trust level" of the account
+
+### What is the trust level?
+
+This is a score out of 100 which indicates how trusted the account is. It is
+automatically calculated, and the calculation may include various factors
+provided by installed modules. At this time, in a default installation, the
+reported value is always 50.
+
+## Configuration
+
+### Allowing queries
+
+In most cases, Prosody will automatically include the affiliation information
+when necessary. However it is also possible to provide affiliation on-demand,
+in response to queries.
+
+To avoid leaking information about the server's registered users, queries are
+restricted by default.
+
+You can configure a list of servers from which queries are permitted, by using
+the 'report_affiliations_trusted_servers' option:
+
+```lua
+report_affiliations_trusted_servers = { "rtbl.example.net" }
+```
+
+In this example, permission has been granted to an RTBL service, so that it
+can query the server and avoid adding legitimate users to the blocklist, even
+if it receives reports about them (obviously this is just an example, RTBLs
+will decide their own policies).
+
+### Tweaking roles
+
+Prosody automatically maps its standard roles to the affiliations defined by
+the XEP. If your deployment uses custom roles, you can customize the mapping
+by specifying the list of roles that should be mapped to a given affiliation.
+This can be done using the following options:
+
+- report_affiliations_admin_roles
+- report_affiliations_member_roles
+- report_affiliations_registered_roles
+- report_affiliations_anonymous_roles
+
+For example, to consider the 'company:staff' role as members, as well as the
+built-in prosody:member role, you might set the following:
+
+```lua
+report_affiliations_member_roles = { "prosody:member", "company:staff" }
+```
+
+## Compatibility
+
+Should work with 0.12, but has not been tested. 0.12 does not support the
+"member" role, so all non-anonymous/non-admin accounts will be reported as
+"registered".
+
+Tested with trunk (2024-11-22).
+
+
+------------------------------------------------------------------------
+
+**Note:** mod\_anti\_spam is not yet ready for use.
+
+------------------------------------------------------------------------