Read the session key from the SESSION_KEY environment variable (#480)

* Read the session key from the SESSION_KEY environment variable

The Fernet key that encrypts the session cookie was generated fresh on
every start, so each deploy or restart signed everyone out. The key now
comes from SESSION_KEY, set in the cabotage UI like the other secrets.
When it is missing, the app still generates a random key, which keeps
local development working, and logs a warning.

* Name SESSION_KEY in the error when its value is not a Fernet key

A malformed value used to fail inside EncryptedCookieStorage with a
message that did not say which variable was wrong. Also tightens the
readme wording and drops an import the tests no longer need.

* Point SESSION_KEY errors at the readme instead of embedding the command

The generate command now lives in its own readme section under Deploy.
The startup error and the missing-key warning just say what is wrong
and refer to that section.

* Assert the readme pointer in the session key tests

Without this the tests stayed green when the pointer was removed.

Author: Mariatta

blurb_it/__main__.py

@@ -2,6 +2,7 @@
 
 import base64
 import json
+import logging
 import os
 
 import aiohttp
@@ -308,14 +309,36 @@ async def handle_add_blurb_post(request: Request) -> Response:
         raise web.HTTPFound(location=request.app.router["add_blurb"].url_for())
 
 
-if __name__ == "__main__":  # pragma: no cover
-    fernet_key = fernet.Fernet.generate_key()
-    secret_key = base64.urlsafe_b64decode(fernet_key)
+def get_session_key() -> str:
+    """Return the Fernet key that encrypts the session cookie.
+
+    The key comes from the ``SESSION_KEY`` environment variable so that it
+    stays the same across restarts and deploys. Without it a random key is
+    generated, which is fine for local development, but then every restart
+    invalidates all existing sessions and signs everyone out.
+    """
+    session_key = os.environ.get("SESSION_KEY")
+    if session_key:
+        try:
+            fernet.Fernet(session_key)
+        except ValueError as exc:
+            raise ValueError(
+                "SESSION_KEY is not a valid session key. "
+                "See the Deploy section of the readme."
+            ) from exc
+        return session_key
+    logging.warning(
+        "SESSION_KEY is not set; using a random session key, so sessions "
+        "will not survive a restart. See the Deploy section of the readme."
+    )
+    return fernet.Fernet.generate_key().decode()
+
 
+if __name__ == "__main__":  # pragma: no cover
     app = web.Application(
         middlewares=[
             middleware.error_middleware,
-            session_middleware(EncryptedCookieStorage(secret_key)),
+            session_middleware(EncryptedCookieStorage(get_session_key())),
         ]
     )
 

readme.rst

@@ -61,8 +61,25 @@ Configuration variables, set in the cabotage UI:
 - ``GH_APP_ID``, ``GH_PRIVATE_KEY``: the GitHub App ID and private key.
 - ``APP_URL``: the public hostname, without scheme. Must match the OAuth App
   callback URL.
+- ``SESSION_KEY``: the key that encrypts the session cookie. See
+  `Generating the session key`_ below.
 - ``SENTRY_DSN``: where errors are reported.
 
+Generating the session key
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``SESSION_KEY`` is a Fernet key. Generate it once, in any environment that
+has the ``cryptography`` package installed:
+
+.. code-block:: console
+
+   $ python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+
+Copy the whole printed line into ``SESSION_KEY``. Keep it the same across
+deploys: changing it signs everyone out. Without it the app generates a
+random key at startup, with the same effect on every restart. If the value is
+not a valid Fernet key, the app refuses to start.
+
 
 Requirements and dependencies
 =============================

tests/test_main.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import base64
+import logging
 import pathlib
 
 import aiohttp
@@ -613,3 +614,38 @@ async def get_installation(gh, jwt, username):
     # Assert
     assert resp.status == 503
     assert "GitHub is not responding right now" in await resp.text()
+
+
+def test_get_session_key_from_env(monkeypatch, caplog) -> None:
+    expected = fernet.Fernet.generate_key().decode()
+    monkeypatch.setenv("SESSION_KEY", expected)
+
+    session_key = __main__.get_session_key()
+
+    assert session_key == expected
+    assert "SESSION_KEY is not set" not in caplog.text
+    # The key must be usable as-is by the cookie storage.
+    EncryptedCookieStorage(session_key)
+
+
+def test_get_session_key_random_when_unset(monkeypatch, caplog) -> None:
+    monkeypatch.delenv("SESSION_KEY", raising=False)
+
+    with caplog.at_level(logging.WARNING):
+        session_key = __main__.get_session_key()
+
+    assert session_key != __main__.get_session_key()
+    assert "SESSION_KEY is not set" in caplog.text
+    assert "See the Deploy section of the readme." in caplog.text
+    EncryptedCookieStorage(session_key)
+
+
+def test_get_session_key_rejects_invalid_value(monkeypatch) -> None:
+    monkeypatch.setenv("SESSION_KEY", "not-a-fernet-key")
+
+    with pytest.raises(
+        ValueError,
+        match=r"SESSION_KEY is not a valid session key\. "
+        r"See the Deploy section of the readme\.",
+    ):
+        __main__.get_session_key()