--- a/mod_s2s_v6mesh/README.md	Mon Mar 23 19:47:03 2026 +0100
+++ b/mod_s2s_v6mesh/README.md	Tue Mar 24 13:20:51 2026 +0000
@@ -63,29 +63,37 @@
 
 ### Connection security
 
-By default, Prosody requires TLS for server-to-server connections. However, it
+Prosody typically requires TLS for server-to-server connections. However, it
 is not possible to obtain CA-issued certificates for `.v6.alt` domains. This
-module disables certificate validation (it treats all certificates as trusted)
-for all `v6.alt` domains where the IP address matches the domain name that the
-remote server is claiming to be (the actual certificate contents are
-irrelevant and never checked, so self-signed certificates are fine).
+raises challenges around authentication of peers.
 
-Additionally, if the IP is within one of the CIDR ranges listed in the
-`s2s_v6mesh_secure_ranges` configuration option, then the module will tell
-Prosody to disable TLS encryption for the connection.
+By default, this module treats all certificates as trusted for all `v6.alt`
+domains where the IP address matches the domain name that the remote server is
+claiming to be (the actual certificate contents are irrelevant and never
+checked, so self-signed certificates are fine). This provides a decent balance
+between convenience and security.
+
+Connections using v6.alt are automatically safe from whole categories of
+attacks such as DNS spoofing/poisoning (because such domains do not use DNS
+resolvers). However, any attack which enables an attacker to route an IP
+address to their own machine, for example, may be susceptible to a
+machine-in-the-middle attack, which cannot be ruled out on the internet.
 
-**Warning:** Prosody will treat connections within any configured ranges as
-already totally secure, and **TLS will be disabled**. Be *very* sure you trust
-the underlying network's security layer before adding an IP range to this
-list, and never add IPs that use the public internet. If you want similar
-behaviour for other (non-`v6.alt`) domains, look at [mod_secure_interfaces](https://modules.prosody.im/mod_secure_interfaces)
-and configure it with your mesh interface's address. If in doubt, just don't
-set any secure ranges, and use self-signed certificates with TLS instead.
+For ultimate security across untrusted networks, use self-signed certificates
+and pin fingerprints in the configuration on both sides using
+[mod_s2s_auth_fingerprint](https://modules.prosody.im/mod_s2s_auth_fingerprint).
+
+If you do this, or if you only want v6.alt certificates to be trusted within
+explicitly configured network ranges, you can disable the default certificate
+trusting behaviour using `s2s_v6mesh_trust_all_certs = false`.
 
-Finally, because of the above mechanisms in place, it is strongly recommended
-to keep Prosody's default settings of `s2s_require_encryption = true` and
-`s2s_secure_auth = true` so that connections not covered by this module are
-always encrypted and authenticated properly.
+You can configure connection security and trust settings per range, using the
+`s2s_v6mesh_ranges` configuration option (more details below).
+
+Regardless of any other options, we always recommend keeping Prosody's default
+settings of `s2s_require_encryption = true` and `s2s_secure_auth = true` so
+that connections not covered by this module are always encrypted and
+authenticated properly.
 
 ### Connecting from clients
 
@@ -110,9 +118,27 @@
 
 ## Configuration
 
-  | Name                     | Default| Description
-  |--------------------------|--------|-------------------------------------------------------------------------
-  | s2s_v6mesh_secure_ranges | `{}`   | A list of IP ranges to treat as secure (bypassing TLS)
+  | Name                         | Default | Description
+  |------------------------------|-------- |-------------------------------------------------------------------------
+  | s2s_v6mesh_ranges            | `{}`    | A list of IP ranges and associated configuration (see below)
+  | s2s_v6mesh_trust_all_certs   | `true`  | Whether to trust all certs from verified v6.alt addresses (even in unconfigured ranges)
+
+### Range configuration
+
+By default, this module will use TLS, and trust any certificate from a v6.alt
+domain if the IP address matches. You can override this behaviour on a
+per-range basis:
+
+```lua
+s2s_v6mesh_ranges = {
+    ["200::/7"] = {
+        -- disable TLS requirement for this IP range (overrides s2s_require_encryption)
+        use_tls = false;
+        -- trust all certificates (even self-signed) within this range (overrides s2s_secure_auth)
+        trust_all_certs = true;
+    };
+}
+```
 
 ## Compatibility