nix(authelia): start with a disabled placeholder user when the user set is empty

authelia 4.39.20 exits at startup on `users: {}` ("users: non zero value
required"), and the first-boot unit seeded exactly that, so a swarm with
no users crash-looped authelia and answered 502 until `swarmctl user add`
ran.

The first-boot unit now writes one subject, `swarm.placeholder`, when
the users database is absent, empty, or exactly `users: {}`:

- `disabled: true` — authelia returns "user not found" for a disabled
  user before any password check (file_user_provider.go,
  CheckUserPassword).
- password: an argon2id digest with an all-zero key. It decodes (authelia
  rejects a non-digest at startup) and no known password hashes to it.
- the `.` keeps it out of agent names (`[a-z0-9-]`), and `swarmctl user
  add` refuses it as already existing. Neither writer removes users, and
  both round-trip `disabled`.

A file with any user in it is never touched.

The docs that described the crash-loop (sso.md, gateway.md, setup.md,
the sso-unavailable error page) now describe the placeholder; the
writers' load_store docs and the seed fixtures follow. module-eval
nats-authelia asserts the seed branch.

nix/host-modules/hive-gateway/error-pages.nix

@@ -56,21 +56,15 @@ in
     '';
   };
 
-  # Shown when the authelia vhost's upstream refuses the connection.
-  # Leads with the bootstrap because that is overwhelmingly the cause:
-  # authelia treats an empty user store as a FATAL startup error, so an
-  # enabled-but-unbootstrapped swarm crash-loops behind a vhost that is
-  # working perfectly, and the raw 502 points at the proxy instead.
+  # Shown when the authelia vhost's upstream refuses the connection: authelia
+  # is down behind a working gateway, and the raw 502 points at the proxy.
   ssoUnavailable = mkPage {
     name = "sso-unavailable";
     title = "sso unavailable";
     accent = "#f9e2af";
     body = ''
       <p>The swarm's identity provider isn't answering. The gateway is fine — nothing is listening behind it.</p>
-      <p class="hint">Most likely: <strong>no users exist yet.</strong> Authelia refuses to start with an empty user store, so it never finishes booting. Add the first account on the host running it:</p>
-      <pre>swarmctl user add &lt;username&gt; \
-      --display-name &lt;Name&gt; --email &lt;addr&gt; --group admins</pre>
-      <p class="hint">Otherwise check the container: <code>journalctl -M swarm-authelia -u authelia-swarm</code>. This page recovers on reload once the provider is up.</p>
+      <p class="hint">Check the container: <code>journalctl -M swarm-authelia -u authelia-swarm</code>. This page recovers on reload once the provider is up.</p>
     '';
   };
 

nix/host-modules/swarm-authelia.nix

@@ -255,6 +255,25 @@ let
   clientsDir = "${stateDir}/oidc-clients";
   clientsFile = "${stateDir}/oidc-clients.yml";
 
+  # The users database an empty user set is replaced with. authelia exits at
+  # startup on `users: {}`, so the file always holds at least this subject,
+  # and it can never log in: authelia answers a `disabled` user as "not
+  # found" before checking any password, and the digest decodes but its key
+  # is all zeros, which no known password hashes to.
+  #
+  # The `.` keeps the name out of agent names (`[a-z0-9-]`), and once this
+  # file is written `swarmctl user add` refuses the name as already taken.
+  # The writers round-trip `disabled`, so it survives every later write.
+  placeholderUser = "swarm.placeholder";
+  placeholderUsersFile = pkgs.writeText "authelia-users-placeholder.yml" ''
+    users:
+      ${placeholderUser}:
+        displayname: placeholder (cannot log in)
+        email: ${placeholderUser}@hyperhive.local
+        disabled: true
+        password: '$argon2id$v=19$m=65536,t=3,p=4$AAAAAAAAAAAAAAAAAAAAAA$AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
+  '';
+
   # Rendered at RUNTIME, not evaluated: the digest is read from disk by
   # the script, so nothing secret ever enters a nix expression (and
   # therefore the store). Everything else here is public metadata that
@@ -438,10 +457,10 @@ in
         program. `swarm-controller` cannot write this file itself — a
         different uid owns it — so the bridge is the only writer,
         running inside this same container as this file's actual owner.
-        This module only guarantees the file *exists* and is valid YAML
-        at first boot, so authelia starts with no subjects rather than
-        failing to start — a provider with nobody in it yet is the
-        correct state before anything has provisioned users.
+        When the user set is empty this module writes a single
+        disabled placeholder subject, `${placeholderUser}`, so authelia
+        starts and serves its login page; nobody can log in until
+        `swarmctl user add` creates the first account.
       '';
     };
 
@@ -845,14 +864,14 @@ in
               done
               ${oidcGenScript}
 
-              # A users database that exists and parses, with nobody in
-              # it. authelia refuses to start without one, and the
-              # alternative to an empty file is a placeholder account —
-              # which is a credential nobody meant to create.
+              # authelia exits at startup on an empty user set, so an empty
+              # database gets the disabled placeholder subject instead. A
+              # file holding exactly `users: {}` is an empty set too; neither
+              # writer ever produces one, so replacing it drops no user.
               users=${lib.escapeShellArg deployCfg.authelia.usersFile}
-              if [ ! -s "$users" ]; then
-                echo "users: {}" > "$users"
-                echo "seeded empty users database at $users"
+              if [ ! -s "$users" ] || [ "$(cat "$users")" = "users: {}" ]; then
+                install -m 0600 ${placeholderUsersFile} "$users"
+                echo "seeded $users with the disabled placeholder ${placeholderUser}"
               fi
               chmod 0600 "$users"
             '';

nix/module-eval/nats-authelia.nix

@@ -224,6 +224,20 @@ let
       name = "a consumer of authelia's host client-secret dir renders it from the deploy namespace";
       ok = lib.hasInfix "/var/lib/nixos-containers/swarm-authelia/var/lib/authelia-swarm/oidc-clients/" autheliaOldPath.systemd.services.swarm-nats-auth-secrets.script;
     }
+    {
+      # authelia exits at startup on `users: {}`, so an empty database, and a
+      # file holding exactly that document, must be replaced by the disabled
+      # placeholder rather than left for authelia to read.
+      name = "an empty authelia users database is seeded with the disabled placeholder";
+      ok =
+        let
+          s =
+            autheliaColocated.containers.swarm-authelia.config.systemd.services.authelia-swarm-secrets.script;
+        in
+        lib.hasInfix ''if [ ! -s "$users" ] || [ "$(cat "$users")" = "users: {}" ]; then'' s
+        && lib.hasInfix "-authelia-users-placeholder.yml \"$users\"" s
+        && !(lib.hasInfix ''echo "users: {}"'' s);
+    }
     {
       # Config NAMES the IdP; it never computes where the IdP is. Both arms
       # matter together: the address is the swarm's name on a hive that runs