Small documentation fixes

 - Removes mentions of the `mas-cli templates save` command
 - Removes the old `experimental` flags
 - Removes the old `policy.data.passwords` configs
 - Document the `policy.data.client_registration` flags
 - Remove references to the pre-built macOS binaries
 - Explains how to get syn2mas
 - State that you need to prepare the database before importing data
 - Clean up the reverse proxy documentation
 - Clarify that you don't need to provede templates/policy/assets
   manually when running the docker image

Author: sandhose

docs/reference/cli/templates.md

@@ -1,37 +1,15 @@
 # `templates`
 
-Helps customizing templates.
+## `templates check`
 
-## `templates save <path>`
-
-Save the builtin template in the specified folder.
-
-```console
-$ mas-cli templates save ./templates
-INFO mas_core::templates: Wrote template path="./templates/login.html"
-INFO mas_core::templates: Wrote template path="./templates/register.html"
-INFO mas_core::templates: Wrote template path="./templates/index.html"
-INFO mas_core::templates: Wrote template path="./templates/reauth.html"
-INFO mas_core::templates: Wrote template path="./templates/form_post.html"
-INFO mas_core::templates: Wrote template path="./templates/error.html"
-INFO mas_core::templates: Wrote template path="./templates/base.html"
-```
-
-By default this command won't overwrite existing files, but this behavior can be changed by adding the `--overwrite` flag.
-
-## `templates check <path>`
-
-Check the validity of the templates in the specified folder.
+Check the validity of the templates loaded by the config.
 It compiles the templates and then renders them with different contexts.
 
 ```console
-$ mas-cli templates check ./templates
-INFO mas_core::templates: Loading builtin templates
+$ mas-cli templates check
 INFO mas_core::templates: Loading templates from filesystem path=./templates/**/*.{html,txt}
 INFO mas_core::templates::check: Rendering template name="login.html" context={"csrf_token":"fake_csrf_token","form":{"fields_errors":{},"form_errors":[],"has_errors":false}}
 INFO mas_core::templates::check: Rendering template name="register.html" context={"__UNUSED":null,"csrf_token":"fake_csrf_token"}
 INFO mas_core::templates::check: Rendering template name="index.html" context={"csrf_token":"fake_csrf_token","current_session":{"active":true,"created_at":"2021-09-24T13:26:52.962135085Z","id":1,"last_authd_at":"2021-09-24T13:26:52.962135316Z","user_id":2,"username":"john"},"discovery_url":"https://example.com/.well-known/openid-configuration"}
 ...
 ```
-
-Builtin templates are still loaded by default when running this command, but this can be skipped by adding the `--skip-builtin` flag.

docs/reference/configuration.md

@@ -253,6 +253,11 @@ passwords:
   # If disabled, users will only be able to log in using upstream OIDC providers
   enabled: true
 
+  # Minimum complexity required for passwords, estimated by the zxcvbn algorithm
+  # Must be between 0 and 4, default is 3
+  # See https://github.com/dropbox/zxcvbn#usage for more information
+  minimum_complexity: 3
+
   # List of password hashing schemes being used
   # /!\ Only change this if you know what you're doing
   # TODO: document this section better
@@ -345,20 +350,13 @@ policy:
     # Dynamic Client Registration
     client_registration:
       # don't require URIs to be on the same host. default: false
-      allow_host_mismatch: true
+      allow_host_mismatch: false
       # allow non-SSL and localhost URIs. default: false
-      allow_insecure_uris: true
-
-    # Registration using passwords
-    passwords:
-      # minimum length of a password. default: 0
-      min_length: 8
-      # require at least one lowercase character in a password. default: false
-      require_lowercase: true
-      # require at least one uppercase character in a password. default: false
-      require_uppercase: true
-      # require at least one number in a password. default: false
-      require_number: true
+      allow_insecure_uris: false
+      # don't require clients to provide a client_uri. default: false
+      allow_missing_client_uri: false
+      # don't require clients to provide a contacts field. default: false
+      allow_missing_contacts: false
 ```
 
 ## `rate_limiting`
@@ -638,16 +636,4 @@ experimental:
 
   # Time-to-live of compatibility access tokens in seconds, when refresh tokens are supported. Defaults to 300, 5 minutes.
   #compat_token_ttl: 300
-
-  # Whether to enable self-service password registration. Defaults to `true` if password authentication is enabled.
-  #password_registration_enabled: false
-
-  # Whether users are allowed to change their email addresses. Defaults to `true`.
-  #email_change_allowed: false
-
-  # Whether users are allowed to change their display names. Defaults to `true`.
-  #displayname_change_allowed: false
-
-  # Whether users are allowed to change their passwords. Defaults to `true`.
-  #password_change_allowed: false
 ```

docs/setup/general.md

@@ -18,7 +18,7 @@ mas-cli config generate > config.yaml
 If you're using the docker container, the command `mas-cli` can be invoked with `docker run`:
 
 ```sh
-docker run ghcr.io/matrix-org/matrix-authentication-service:main config generate > config.yaml
+docker run ghcr.io/matrix-org/matrix-authentication-service config generate > config.yaml
 ```
 
 This applies to all of the `mas-cli` commands in this document.

docs/setup/installation.md

@@ -2,12 +2,10 @@
 
 ## Pre-built binaries
 
-Pre-built binaries can be found attached on each release, for Linux and macOS, on both `x86_64` and `aarch64` architectures.
+Pre-built binaries can be found attached on each release, for Linux on both `x86_64` and `aarch64` architectures.
 
 - [`mas-cli-aarch64-linux.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-aarch64-linux.tar.gz)
 - [`mas-cli-x86_64-linux.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-x86_64-linux.tar.gz)
-- [`mas-cli-aarch64-macos.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-aarch64-macos.tar.gz)
-- [`mas-cli-x86_64-macos.tar.gz`](https://github.com/matrix-org/matrix-authentication-service/releases/latest/download/mas-cli-x86_64-macos.tar.gz)
 
 Each archive contains:
 
@@ -27,7 +25,7 @@ Example shell commands to download and extract the `mas-cli` binary:
 
 ```sh
 ARCH=x86_64 # or aarch64
-OS=linux # or macos
+OS=linux
 VERSION=latest # or a specific version, like "v0.1.0"
 
 # URL to the right archive
@@ -41,13 +39,12 @@ curl -sL "$URL" | tar xzC /path/to/mas
 /path/to/mas/mas-cli --help
 ```
 
-**Note for macOS users**: the binaries are not signed, so if the archive is downloaded from a browser, it may be necessary to run `xattr -d com.apple.quarantine mas-cli` to remove the quarantine attribute on the binary.
-
 
 ## Using the Docker image
 
-A pre-built Docker image is available here: [`ghcr.io/matrix-org/matrix-authentication-service:main`](https://ghcr.io/matrix-org/matrix-authentication-service:main)
+A pre-built Docker image is available here: [`ghcr.io/matrix-org/matrix-authentication-service:latest`](https://ghcr.io/matrix-org/matrix-authentication-service:latest)
 
+The `latest` tag is built using the latest release.
 The `main` tag is built from the `main` branch, and each commit on the `main` branch is also tagged with a stable `sha-<commit sha>` tag.
 
 The image can also be built from the source:

docs/setup/migration.md

@@ -18,6 +18,14 @@ There will be tools to help with the migration process itself. But these aren't
 
 The deployment is non-trivial so it is important to read through and understand the steps involved and make a plan before starting.
 
+### Get `syn2mas`
+
+The easiest way to get `syn2mas` is through [`npm`](https://www.npmjs.com/package/@matrix-org/syn2mas):
+
+```sh
+npm install -g @matrix-org/syn2mas
+```
+
 ### Run the migration advisor
 
 You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver.
@@ -38,6 +46,15 @@ If you are using an upstream SSO provider then you will need to provision the up
 
 Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool.
 
+### Prepare the MAS database
+
+Once the database is created, it still needs to have its schema created and synced with the configuration.
+This can be done with the following command:
+
+```sh
+mas-cli config sync
+```
+
 ### Do a dry-run of the import to test
 
 ```sh

docs/setup/reverse-proxy.md

@@ -17,15 +17,13 @@ http:
         - name: oauth
         - name: compat
         - name: graphql
-        # Uncomment to serve the assets by the service
-        #- name: assets
-        #  path: ./share/assets/
+        - name: assets
 
       binds:
         # Bind on a local port
         - host: localhost
           port: 8080
-          
+
         # OR bind on a Unix domain socket
         #- socket: /var/run/mas.sock
 
@@ -37,9 +35,9 @@ http:
       #proxy_protocol: true
 ```
 
-## Example nginx configuration
+## Base nginx configuration
 
-Note that the assets can be served directly by nginx, and the `assets` resource can be removed from the service configuration.
+A basic configuration for `nginx`, which proxies traffic to the service would look like this:
 
 ```nginx
 server {
@@ -51,32 +49,21 @@ server {
     ssl_certificate_key path/to/privkey.pem;
 
     location / {
+        proxy_http_version 1.1;
         proxy_pass http://localhost:8080;
         # OR via the Unix domain socket
         #proxy_pass http://unix:/var/run/mas.sock;
-        
-        proxy_http_version 1.1;
 
-        # Optional: use the PROXY protocol
+        # Forward the client IP address
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        # or, using the PROXY protocol
         #proxy_protocol on;
     }
-    
-    # Optional: serve the assets directly
-    location /assets/ {
-        root /path/to/share/assets/;
-        
-        # Serve pre-compressed assets
-        gzip_static on;
-        # With the ngx_brotli module installed
-        # https://github.com/google/ngx_brotli
-        #brotli_static on;
-        
-        # Cache assets for a year
-        expires 365d;
-    }
 }
 ```
 
+## Compatibility layer
+
 For the compatibility layer, the following endpoints need to be proxied to the service:
 
  - `/_matrix/client/*/login`
@@ -91,16 +78,17 @@ server {
     listen [::]:443 ssl http2;
 
     server_name matrix.example.com;
-    
+
     # Forward to the auth service
     location ~ ^/_matrix/client/(.*)/(login|logout|refresh) {
+        proxy_http_version 1.1;
         proxy_pass http://localhost:8080;
         # OR via the Unix domain socket
         #proxy_pass http://unix:/var/run/mas.sock;
-        
-        proxy_http_version 1.1;
 
-        # Optional: use the PROXY protocol
+        # Forward the client IP address
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        # or, using the PROXY protocol
         #proxy_protocol on;
     }
 
@@ -116,4 +104,99 @@ server {
         proxy_http_version 1.1;
     }
 }
-```
+```
+
+## Preserve the client IP
+
+For rate-limiting and logging purposes, MAS needs to know the client IP address, which can be lost when using a reverse proxy.
+There are two ways to preserve the client IP address
+
+### `X-Forwarded-For` header
+
+MAS can infer the client IP address from the `X-Forwarded-For` header.
+It will trust the value for this header only if the request comes from a trusted reverse proxy.
+
+The range of IPs that can be trusted is configured using the `trusted_proxies` configuration option, which has the default private IP ranges.
+
+```yaml
+http:
+  trusted_proxies:
+  - 192.168.0.0/16
+  - 172.16.0.0/12
+  - 10.0.0.0/10
+  - 127.0.0.1/8
+  - fd00::/8
+  - ::1/128
+```
+
+With nginx, this can be achieved by setting the `proxy_set_header` directive to `X-Forwarded-For $proxy_add_x_forwarded_for`.
+
+### Proxy protocol
+
+MAS supports the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to preserve the client IP address.
+To enable it, enable the `proxy_protocol` option on the listener:
+
+```yaml
+http:
+  listeners:
+    - name: web
+      resources:
+        - name: discovery
+        - name: human
+        - name: oauth
+        - name: compat
+        - name: graphql
+        - name: assets
+      binds:
+        - address: "[::]:8080"
+      proxy_protocol: true
+```
+
+With nginx, this can be achieved by setting the `proxy_protocol` directive to `on` in the `location` block.
+
+## Serve assets directly
+
+To avoid unnecessary round-trips, the assets can be served directly by nginx, and the `assets` resource can be removed from the service configuration.
+
+```yaml
+http:
+  listeners:
+    - name: web
+      resources:
+        - name: discovery
+        - name: human
+        - name: oauth
+        - name: compat
+        - name: graphql
+        # MAS doesn't need to serve the assets anymore
+        #- name: assets
+      binds:
+        - address: "[::]:8080"
+      proxy_protocol: true
+```
+
+Make sure the assets directory served by nginx is up to date.
+
+```nginx
+server {
+    # --- SNIP ---
+
+    location / {
+        # --- SNIP ---
+    }
+
+    # Make nginx serve the assets directly
+    location /assets/ {
+        root /path/to/share/assets/;
+
+        # Serve pre-compressed assets
+        gzip_static on;
+        # With the ngx_brotli module installed
+        # https://github.com/google/ngx_brotli
+        #brotli_static on;
+
+        # Cache assets for a year
+        expires 365d;
+    }
+}
+```

docs/setup/running.md

@@ -21,6 +21,11 @@ Other than the binary, the service needs a few files to run:
 
 Be sure to check the [installation instructions](./installation.md) for more information on how to get these files, and make sure the configuration file is updated accordingly.
 
+**If you are using [the docker image](./installation.md#using-the-docker-image)**, everything is already included in the image at the right place, so in most cases you don't need to do anything.
+
+**If you are using [the pre-built binaries](./installation.md#pre-built-binaries)**, those files are shipped alongside them in the `share` directory.
+The default configuration will look for them from the current working directory, meaning that you don't have to adjust the paths, as long as you are running the service from the parent directory of the `share` directory.
+
 ## Configure the HTTP server
 
 The service can be configured to have multiple HTTP listeners, serving different resources.