diff mod_report_forward/README.markdown @ 5854:fcfe490de8a4

mod_spam_report_forwarder: Rename to mod_report_forward This module is not only about spam reports.
author Matthew Wild <mwild1@gmail.com>
date Sun, 03 Mar 2024 16:03:27 +0000
parents mod_spam_report_forwarder/README.markdown@94472eb41d0a
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_report_forward/README.markdown	Sun Mar 03 16:03:27 2024 +0000
@@ -0,0 +1,77 @@
+---
+labels:
+- 'Stage-Beta'
+summary: 'Forward spam/abuse reports to a JID'
+---
+
+This module forwards spam/abuse reports (e.g. those submitted by users via
+XEP-0377 via mod_spam_reporting) to one or more JIDs.
+
+## Configuration
+
+Install and enable the module the same as any other:
+
+```lua
+modules_enabled = {
+    ---
+    "report_forward";
+    ---
+}
+```
+
+There are two main options. You can set `report_forward_to` which accepts a
+list of JIDs to send all reports to (default is empty):
+
+```lua
+report_forward_to = { "antispam.example.com" }
+```
+
+You can also control whether the module sends a report to the server from
+which the spam/abuse originated (default is `true`):
+
+```lua
+report_forward_to_origin = false
+```
+
+The module looks up an abuse report address using XEP-0157 (only XMPP
+addresses are accepted). If it fails to find any suitable destination, it will
+log a warning and not send the report.
+
+
+
+## Protocol
+
+This section is intended for developers.
+
+XEP-0377 assumes the report is embedded within another protocol such as
+XEP-0191, and doesn't specify a format for communicating "standalone" reports.
+This module transmits them inside a `<message>` stanza, and adds a `<jid/>`
+element (borrowed from XEP-0268):
+
+```xml
+<message from="prosody.example" to="destination.example">
+    <report xmlns="urn:xmpp:reporting:1" reason="urn:xmpp:reporting:spam">
+        <jid xmlns="urn:xmpp:jid:0">spammer@bad.example</jid>
+        <text>
+          Never came trouble to my house like this.
+        </text>
+    </report>
+</message>
+```
+
+It may also include the reported message, if this has been indicated by the
+user, wrapped in a XEP-0297 `<forwarded/>` element:
+
+```xml
+<message from="prosody.example" to="destination.example">
+  <report reason="urn:xmpp:reporting:spam" xmlns="urn:xmpp:reporting:1">
+    <jid xmlns="urn:xmpp:jid:0">spammer@bad.example</jid>
+    <text>Never came trouble to my house like this.</text>
+  </report>
+  <forwarded xmlns="urn:xmpp:forward:0">
+    <message from="spammer@bad.example" to="victim@prosody.example" type="chat" xmlns="jabber:client">
+      <body>Spam, Spam, Spam, Spam, Spam, Spam, baked beans, Spam, Spam and Spam!</body>
+    </message>
+  </forwarded>
+</message>
+```