cdsr: initial import of deployed stack (runtime 4.133.0, pinned extensions, SSOT vault)

q5vault/operations/auth-tls.md

@@ -0,0 +1,99 @@
+---
+title: 🔐 Auth & TLS
+description: Authelia access rule, nginx four-block topology, shared certificate lineage, proof commands, and rollback/debug order for the code-server SSO-gated stack.
+source: verified deployment on the loca operator host, 2026-08-19
+reviewed: 2026-08-19
+---
+
+# 🔐 Auth & TLS
+
+## Authelia access rule
+
+File: `/home/loca/dev/services/authelia/config/configuration.yml` (root:root 644)
+
+Edit procedure — stage in `/tmp` then install atomically:
+```bash
+sudo -n install -m 644 -o root -g root /tmp/configuration.yml /home/loca/dev/services/authelia/config/configuration.yml
+```
+
+YAML added inside `access_control.rules`:
+```yaml
+    - domain: "cdsr.loca.zone"
+      policy: one_factor
+```
+
+The rule sits alongside existing rules for `auth.loca.zone`, `admin.loca.zone`, `omp.loca.zone`, `pwiz.loca.zone`, `trlm.loca.zone`.
+
+## Why the wiki has no rule
+
+Authelia runs with `default_policy: bypass`. An explicit rule for `wiki.cdsr.loca.zone` is intentionally omitted — the wiki remains public by omission while the app host becomes protected by explicit allowlisting.
+
+## Apply procedure
+
+```bash
+cd /home/loca/dev/services/authelia
+sudo -n docker compose config
+sudo -n docker compose restart
+sudo -n docker compose ps
+```
+
+Authelia v4.39.20 restarts clean on loopback `127.0.0.1:51091`. Session cookie domain `loca.zone`, `authelia_url https://auth.loca.zone`, expiration 1h, inactivity 5m.
+
+## Nginx topology
+
+File: `/etc/nginx/sites-available/cdsr.loca.zone` (symlinked into `sites-enabled`), installed from `deploy/cdsr.nginx.conf`.
+
+Four server blocks after Certbot:
+- `cdsr.loca.zone:443` — reverse proxy to `http://127.0.0.1:52224`
+  - includes `snippets/security-headers-app.conf`
+  - includes `snippets/authelia-location.conf`
+  - `location /` protected by `snippets/authelia-authrequest.conf`
+  - `proxy_http_version 1.1`, websocket headers (`Upgrade`, `Connection`), `proxy_read_timeout 86400`
+- `wiki.cdsr.loca.zone:443` — static root `/home/loca/dev/wikis/cdsr/current`
+  - includes `snippets/security-headers.conf`
+  - 1y immutable cache for `css|js|png|webp|ico|json|woff2?|svg|map`
+  - `try_files $uri $uri.html $uri/ =404`
+- `cdsr.loca.zone:80` — ACME challenge from `/var/www/html` + 301 to HTTPS
+- `wiki.cdsr.loca.zone:80` — ACME challenge from `/var/www/html` + 301 to HTTPS
+
+## TLS certificate
+
+Single lineage `cdsr.loca.zone` covering both hosts:
+```bash
+sudo -n certbot certonly --webroot -w /var/www/html --non-interactive --agree-tos -m admin@loca.zone --cert-name cdsr.loca.zone -d cdsr.loca.zone -d wiki.cdsr.loca.zone
+```
+
+Expiry: 2026-11-17, auto-renew scheduled. Certs at `/etc/letsencrypt/live/cdsr.loca.zone/{fullchain,privkey}.pem`.
+
+If a partial lineage already exists, rerun with the same `--cert-name` and `--expand` instead of minting a second lineage.
+
+`sudo -n nginx -t` emits a harmless pre-existing `ssl_stapling` warning about `flxr.loca.zone` — expected and safe to ignore.
+
+## Proof commands
+
+```bash
+# app host — unauthenticated redirect into Authelia
+curl -sSI https://cdsr.loca.zone/
+# -> HTTP/1.1 302
+# -> Location: https://auth.loca.zone/?rd=https%3A%2F%2Fcdsr.loca.zone%2F&rm=HEAD
+
+# wiki host — public, no auth redirect
+curl -sSI https://wiki.cdsr.loca.zone/
+# -> HTTP/1.1 200
+# -> serves static content directly
+```
+
+## Rollback / debug order if auth breaks
+
+1. `sudo -n nginx -t` — config clean (ignore the pre-existing flxr ssl_stapling warning)
+2. Confirm app 443 block includes both snippets:
+   - `include snippets/authelia-location.conf`
+   - `location / { include snippets/authelia-authrequest.conf; ... }`
+3. Confirm Authelia rule present:
+   - `grep -A2 'domain: "cdsr.loca.zone"' /home/loca/dev/services/authelia/config/configuration.yml`
+4. Check Authelia container:
+   - `cd /home/loca/dev/services/authelia && sudo -n docker compose ps`
+   - `cd /home/loca/dev/services/authelia && sudo -n docker compose logs --tail=50 authelia`
+5. Prove code-server itself is healthy (bypasses all auth/TLS):
+   - `curl -sf http://127.0.0.1:52224/healthz`
+   - should return `{"status":"alive",...}` when an editor session is active