Merge pull request #5 from matrix-org/jaywink/support-many-homeservers

Support resolving OpenID tokens against any given homeserver

Author: jaywink

.env.default

@@ -3,3 +3,4 @@ UVS_HOMESERVER_URL=https://matrix.org
 UVS_LISTEN_ADDRESS=127.0.0.1
 UVS_PORT=3000
 UVS_LOG_LEVEL=info
+UVS_OPENID_VERIFY_ANY_HOMESERVER=false

CHANGELOG.md

@@ -2,9 +2,20 @@
 
 ## unreleased
 
+### Added
+
+* Possibility to allow verifying any Matrix homeserver OpenID token. Default is still to
+  only verify tokens against the configured homeserver. Room membership verification
+  is still only done against the configured homeserver even if the token is for a user
+  on another homeserver. ([related issue](https://github.com/matrix-org/matrix-user-verification-service/issues/3))
+
+### Changes
+
+* Better documentation in readme.
+
 ## v1.1.0
 
-Added:
+### Added
 
 * Logging, defaults to `info` level, set different level with `UVS_LOG_LEVEL`.
 

README.md

@@ -1,6 +1,6 @@
 # Matrix User Verification Service
 
-Service to verify details of a user based on a Open ID Connect token.
+Service to verify details of a user based on an Open ID Connect token.
 
 Main features:
 
@@ -33,6 +33,136 @@ UVS_PORT=3000
 # (Optional) log level, defaults to 'info'
 # See choices here: https://github.com/winstonjs/winston#logging-levels
 UVS_LOG_LEVEL=info
+# (Optional) multiple homeserver mode, defaults to disabled
+# See below for more info.
+UVS_OPENID_VERIFY_ANY_HOMESERVER=false
+```
+
+#### OpenID token verification
+
+UVS can run in a single homeserver mode or be configured to trust any
+homeserver OpenID token. Default is to only trust the configured homeserver
+OpenID tokens.
+
+To enable multiple homeserver mode:
+
+    UVS_OPENID_VERIFY_ANY_HOMESERVER=true
+
+Note, room membership is still limited to only the configured `UVS_HOMESERVER_URL`.
+
+When running with the multiple homeserver mode, `matrix_server_name` becomes
+a required request body item for all `/verify` verification API requests.
+
+### API's available
+
+#### Verify OpenID token
+
+Verifies a user OpenID token.
+
+    POST /verify/user
+    Content-Type: application/json
+
+Request body:
+
+```json
+{
+  "token": "secret token"
+}
+```
+
+If `UVS_OPENID_VERIFY_ANY_HOMESERVER` is set to `true`, the API also
+requires a `matrix_server_name`, becoming:
+
+```json
+{
+  "matrix_server_name": "domain.tld",
+  "token": "secret token"
+}
+```
+
+Successful validation response:
+
+```json
+{
+  "results": {
+    "user": true
+  },
+  "user_id": "@user:domain.tld"
+}
+```
+
+Failed validation:
+
+```json
+{
+  "results": {
+    "user": false
+  },
+  "user_id": null
+}
+```
+
+#### Verify OpenID token and room membership
+
+Verifies a user OpenID token and membership in a room.
+
+    POST /verify/user_in_room
+    Content-Type: application/json
+
+Request body:
+
+```json
+{
+  "room_id": "!foobar:domain.tld",
+  "token": "secret token"
+}
+```
+
+If `UVS_OPENID_VERIFY_ANY_HOMESERVER` is set to `true`, the API also
+requires a `matrix_server_name`, becoming:
+
+```json
+{
+  "matrix_server_name": "domain.tld",
+  "room_id": "!foobar:domain.tld",
+  "token": "secret token"
+}
+```
+
+Successful validation response:
+
+```json
+{
+  "results": {
+    "room_membership": true,
+    "user": true
+  },
+  "user_id": "@user:domain.tld"
+}
+```
+
+Failed validation, in case token is not valid:
+
+```json
+{
+  "results": {
+    "room_membership": false,
+    "user": false
+  },
+  "user_id": null
+}
+```
+
+In the token was validated but user is not in room, the failed response is:
+
+```json
+{
+  "results": {
+    "room_membership": false,
+    "user": true
+  },
+  "user_id": "@user:domain.tld"
+}
 ```
 
 ### Running

package-lock.json

@@ -26,6 +26,7 @@
     "chai": "^4.2.0",
     "eslint": "^7.7.0",
     "mocha": "^8.1.1",
+    "mocked-env": "^1.3.2",
     "nodemon": "^2.0.4",
     "sinon": "^9.0.3"
   },