Document new 3PID invite expiration feature

docs/features/identity.md

@@ -1,6 +1,13 @@
 # Identity
 Implementation of the [Identity Service API r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html).
 
+- [Lookups](#lookups)
+- [Invitations](#invitations)
+  - [Expiration](#expiration)
+  - [Policies](#policies)
+  - [Resolution](#resolution)
+- [3PIDs Management](#3pids-management)
+
 ## Lookups
 If you would like to use the central matrix.org Identity server to ensure maximum discovery at the cost of potentially
 leaking all your contacts information, add the following to your configuration:
@@ -12,8 +19,62 @@ forward:
 **NOTE:** You should carefully consider enabling this option, which is discouraged.  
 For more info, see the [relevant issue](https://github.com/kamax-matrix/mxisd/issues/76).
 
-## Room Invitations
-Resolution can be customized using the following configuration:
+## Invitations
+### Expiration
+#### Overview
+Matrix does not provide a mean to remove/cancel pending 3PID invitations with the APIs. The current reference
+implementations also do not provide any mean to do so. This leads to 3PID invites forever stuck in rooms.
+
+To provide this functionality, mxisd uses a workaround: resolve the invite to a dedicated User ID, which can be
+controlled by mxisd or a bot/service that will then reject the invite.
+
+If this dedicated User ID is to be controlled by mxisd, the [Application Service](experimental/application-service.md)
+feature must be configured and integrated with your Homeserver.
+
+#### Configuration
+```yaml
+invite:
+  expiration:
+    enabled: true/false
+    after: 5
+    resolveTo: '@john.doe:example.org'
+```
+`enabled`
+- Purpose: Enable or disable the invite expiration feature.
+- Default: `true`
+
+`after` 
+- Purpose: Amount of minutes before an invitation expires.
+- Default: `10080` (7 days)
+
+`resolveTo`
+- Purpose: Matrix User ID to resolve the expired invitations to.
+- Default: Computed from `appsvc.user.inviteExpired` and `matrix.domain`
+
+### Policies
+#### Integration
+##### Reverse Proxy
+###### nginx
+```nginx
+location ~* ^/_matrix/client/r0/rooms/([^/]+)/invite$ {
+    proxy_pass		    http://127.0.0.1:8090;
+    proxy_set_header	Host $host;
+    proxy_set_header	X-Forwarded-For $remote_addr;
+}
+```
+
+##### Configuration
+```yaml
+invite:
+  policy:
+    ifSender:
+      hasRole:
+        - '<THIS_ROLE>'
+        - '<OR_THIS_ROLE>'
+```
+
+### Resolution
+Resolution of 3PID invitations can be customized using the following configuration:
 
 `invite.resolution.recursive`  
 - Default value: `true`  
@@ -26,5 +87,5 @@ Resolution can be customized using the following configuration:
 - Default value: `1`  
 - Description: How often, in minutes, mxisd should try to resolve pending invites.
 
-## 3PID addition to user profile
+## 3PIDs Management
 See the [3PID session documents](../threepids/session)

src/main/java/io/kamax/mxisd/config/InvitationConfig.java

@@ -34,7 +34,7 @@ public class InvitationConfig {
     public static class Expiration {
 
         private Boolean enabled;
-        private long after;
+        private long after = 60 * 24 * 7; // One calendar week (60min/1h * 24 = 1d * 7 = 1w)
         private String resolveTo;
 
         public Boolean isEnabled() {

src/main/java/io/kamax/mxisd/invitation/InvitationManager.java

@@ -172,12 +172,6 @@ public class InvitationManager {
 
             // Enabled by default
             cfg.getInvite().getExpiration().setEnabled(true);
-
-            // We'll resolve to our computed User ID
-            cfg.getInvite().getExpiration().setResolveTo(mxId);
-
-            // One calendar week (60min/1h * 24 = 1d * 7 = 1w)
-            cfg.getInvite().getExpiration().setAfter(60 * 24 * 7);
         }
 
         if (cfg.getInvite().getExpiration().isEnabled()) {