Add form_secret_path config option (#18090)

I [was
told](https://github.com/element-hq/synapse/pull/17983#issuecomment-2593370897)
about another config option with a secret, so I got `form_secret` a
companion: `form_secret_path`

This PR makes NixOS and Kubernetes users a little bit happy. Includes
docs and tests.

### Pull Request Checklist

<!-- Please read
https://element-hq.github.io/synapse/latest/development/contributing_guide.html
before submitting your pull request -->

* [x] Pull request is based on the develop branch
* [x] Pull request includes a [changelog
file](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#changelog).
The entry should:
- Be a short description of your change which makes sense to users.
"Fixed a bug that prevented receiving messages from other servers."
instead of "Moved X method from `EventStore` to `EventWorkerStore`.".
  - Use markdown where necessary, mostly for `code blocks`.
  - End with either a period (.) or an exclamation mark (!).
  - Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by
@github_username." or "Contributed by [Your Name]." to the end of the
entry.
* [x] [Code
style](https://element-hq.github.io/synapse/latest/code_style.html) is
correct
(run the
[linters](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#run-the-linters))

changelog.d/18090.feature

@@ -0,0 +1 @@
+Add `form_secret_path` config option.

docs/usage/configuration/config_documentation.md

@@ -3238,6 +3238,22 @@ Example configuration:
 ```yaml
 form_secret: <PRIVATE STRING>
 ```
+---
+### `form_secret_path`
+
+An alternative to [`form_secret`](#form_secret):
+allows the secret to be specified in an external file.
+
+The file should be a plain text file, containing only the secret.
+Synapse reads the secret from the given file once at startup.
+
+Example configuration:
+```yaml
+form_secret_path: /path/to/secrets/file
+```
+
+_Added in Synapse 1.125.0._
+
 ---
 ## Signing Keys
 Config options relating to signing keys

synapse/config/key.py

@@ -96,6 +96,11 @@ Conflicting options 'macaroon_secret_key' and 'macaroon_secret_key_path' are
 both defined in config file.
 """
 
+CONFLICTING_FORM_SECRET_OPTS_ERROR = """\
+Conflicting options 'form_secret' and 'form_secret_path' are both defined in
+config file.
+"""
+
 logger = logging.getLogger(__name__)
 
 
@@ -201,12 +206,19 @@ class KeyConfig(Config):
 
         # a secret which is used to calculate HMACs for form values, to stop
         # falsification of values
-        self.form_secret = config.get("form_secret", None)
+        form_secret = config.get("form_secret", None)
-        if self.form_secret and not allow_secrets_in_config:
+        if form_secret and not allow_secrets_in_config:
             raise ConfigError(
                 "Config options that expect an in-line secret as value are disabled",
                 ("form_secret",),
             )
+        form_secret_path = config.get("form_secret_path", None)
+        if form_secret_path:
+            if form_secret:
+                raise ConfigError(CONFLICTING_FORM_SECRET_OPTS_ERROR)
+            self.form_secret = read_file(form_secret_path, "form_secret_path").strip()
+        else:
+            self.form_secret = form_secret
 
     def generate_config_section(
         self,

tests/config/test_load.py

@@ -138,6 +138,7 @@ class ConfigLoadingFileTestCase(ConfigFileTestCase):
             "turn_shared_secret_path: /does/not/exist",
             "registration_shared_secret_path: /does/not/exist",
             "macaroon_secret_key_path: /does/not/exist",
+            "form_secret_path: /does/not/exist",
             "experimental_features:\n  msc3861:\n    client_secret_path: /does/not/exist",
             "experimental_features:\n  msc3861:\n    admin_token_path: /does/not/exist",
             *["redis:\n  enabled: true\n  password_path: /does/not/exist"]
@@ -165,6 +166,10 @@ class ConfigLoadingFileTestCase(ConfigFileTestCase):
                 "macaroon_secret_key_path: {}",
                 lambda c: c.key.macaroon_secret_key,
             ),
+            (
+                "form_secret_path: {}",
+                lambda c: c.key.form_secret.encode("utf-8"),
+            ),
             (
                 "experimental_features:\n  msc3861:\n    client_secret_path: {}",
                 lambda c: c.experimental.msc3861.client_secret().encode("utf-8"),
@@ -186,7 +191,7 @@ class ConfigLoadingFileTestCase(ConfigFileTestCase):
         self, config_line: str, get_secret: Callable[[RootConfig], str]
     ) -> None:
         self.generate_config_and_remove_lines_containing(
-            ["registration_shared_secret", "macaroon_secret_key"]
+            ["form_secret", "macaroon_secret_key", "registration_shared_secret"]
         )
         with tempfile.NamedTemporaryFile(buffering=0) as secret_file:
             secret_file.write(b"53C237")