prosody-modules
06621ab30be0
mod_report_affiliations/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_report_affiliations/README.markdown @ 6219:06621ab30be0

mod_push2: Improve session activity tracking
author Stephen Paul Weber <singpolyma@singpolyma.net>
date Tue, 25 Mar 2025 20:54:09 -0500
parent 6062:fb2ba31a4e26
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6058
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Alpha'
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'XEP-0489: Reporting Account Affiliations'
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 rockspec:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6 build:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 modules:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 mod_report_affiliations.traits: traits.lib.lua
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 ---
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 This module implements [XEP-0489: Reporting Account Affiliations](https://xmpp.org/extensions/xep-0489.html).
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 It can help with spam on the network, especially if you run a public server
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 that allows registration.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 ## How it works
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 Here is the scenario: you run a public server. Despite your best efforts, and
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 following the [best practices](https://prosody.im/doc/public_servers), some
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 spammers still occasionally manage to register on your server. Because of
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 this, other servers on the network start filtering messages from all accounts
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 on your server.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 Enabling this module will include additional information in certain kinds of
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 outgoing traffic, which allows other servers to judge the sending account,
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 rather than the whole server.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 ### When is affiliation information shared?
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 Affiliation is shared when a user on your server:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 - sends a message to a user that has not (yet) authorized them
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 - sends a subscription request to a user
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 - sends a "directed presence" to a remote JID (for example, when joining a
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 group chat).
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 ### What information is shared?
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 The following information is included in matching traffic:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 - The affiliation of the account:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 - "guest" (the account is anonymous/temporary)
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 - "registered" (the account was self-registered)
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 - "member" (the account belongs to a recognised/trusted member of the server)
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 - "admin" (the account belongs to a server administrator)
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 For the "registered" affiliation, the following additional items are included:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 - When the account was created
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 - The "trust level" of the account
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 ### What is the trust level?
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 This is a score out of 100 which indicates how trusted the account is. It is
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 automatically calculated, and the calculation may include various factors
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 provided by installed modules. At this time, in a default installation, the
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 reported value is always 50.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 ## Configuration
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 ### Allowing queries
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 In most cases, Prosody will automatically include the affiliation information
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 when necessary. However it is also possible to provide affiliation on-demand,
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 in response to queries.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 To avoid leaking information about the server's registered users, queries are
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 restricted by default.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 You can configure a list of servers from which queries are permitted, by using
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 the 'report_affiliations_trusted_servers' option:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 ```lua
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 report_affiliations_trusted_servers = { "rtbl.example.net" }
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 ```
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 In this example, permission has been granted to an RTBL service, so that it
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 can query the server and avoid adding legitimate users to the blocklist, even
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 if it receives reports about them (obviously this is just an example, RTBLs
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 will decide their own policies).
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82 ### Tweaking roles
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84 Prosody automatically maps its standard roles to the affiliations defined by
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 the XEP. If your deployment uses custom roles, you can customize the mapping
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 by specifying the list of roles that should be mapped to a given affiliation.
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 This can be done using the following options:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89 - report_affiliations_admin_roles
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90 - report_affiliations_member_roles
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
91 - report_affiliations_registered_roles
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92 - report_affiliations_anonymous_roles
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
93
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
94 For example, to consider the 'company:staff' role as members, as well as the
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95 built-in prosody:member role, you might set the following:
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
96
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
97 ```lua
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
98 report_affiliations_member_roles = { "prosody:member", "company:staff" }
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
99 ```
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
100
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
101 ## Compatibility
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
102
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
103 Should work with 0.12, but has not been tested. 0.12 does not support the
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
104 "member" role, so all non-anonymous/non-admin accounts will be reported as
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
105 "registered".
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
106
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
107 Tested with trunk (2024-11-22).
e905ef16efb7 mod_report_affiliations: New module for XEP-0489: Reporting Account Affiliations
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
108