env:init: stop wiping the JWT keypair; add self-healing jwt:ensure

env:init deleted ./jwt/*.pem whenever it rotated JWT_PASSPHRASE, on the
assumption that `task install`'s generate-keypair --skip-if-exists would
regenerate. Upgrade paths that use `task up` (not install) — e.g. clone -> v3 —
never regenerate, so the wipe stranded them with no keypair and login 500'd
("Unable to create a signed JWT").

env:init no longer touches the keypair; it only warns when a rotated passphrase
orphans an existing one. Key lifecycle moves to a new idempotent `jwt:ensure`
task: it runs lexik:jwt:check-config and regenerates (--overwrite) ONLY on a
missing/invalid/mismatched keypair, so a valid keypair (and its issued tokens)
survives. `task install` now calls jwt:ensure instead of generate-keypair.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: turegjorup

README.md

@@ -1259,6 +1259,7 @@ Operations
   logs:disk            Docker log disk usage per container + retention policy (Linux only)
   console              Run any bin/console command in os2display  (e.g. `task console -- list`)
   console:run          Run a one-off bin/console in a throwaway container (migrate before `up`)
+  jwt:ensure           Ensure the JWT keypair exists/matches JWT_PASSPHRASE; regenerate on mismatch
   cache:clear          Clear the application cache               (alias: cc)
   php:opcache          Report on the FPM pool's OPcache health (RAW=1 for JSON)
   tenant:add           Add a tenant group (interactive)          (alias: tenant_add)

Taskfile.yml

@@ -45,9 +45,8 @@ tasks:
       - "{{.COMPOSE}} up --force-recreate --detach --remove-orphans --wait"
       - echo "Clearing the cache"
       - task: cache:clear
-      - echo "Create jwt key pair"
-      - task: console
-        vars: { CLI_ARGS: "lexik:jwt:generate-keypair --skip-if-exists" }
+      - echo "Ensure the JWT keypair exists and matches JWT_PASSPHRASE"
+      - task: jwt:ensure
       - task: tenant:add
       - echo "CREATE AN ADMIN USER. CHOOSE THE TENANT YOU JUST CREATED."
       - task: user:add
@@ -174,6 +173,22 @@ tasks:
     cmds:
       - "{{.COMPOSE}} run --rm {{if .EXEC_FLAGS}}{{.EXEC_FLAGS}} {{end}}os2display bin/console {{.CLI_ARGS}}"
 
+  jwt:ensure:
+    desc: |
+      Ensure a JWT keypair exists and matches JWT_PASSPHRASE — (re)generate ONLY
+      if it's missing, unreadable, or doesn't validate. Safe to run on every
+      install/upgrade: a valid keypair is left untouched, so existing tokens
+      survive; an absent or mismatched one is regenerated (which invalidates
+      issued tokens — screens must re-authenticate). Requires the stack up.
+    cmds:
+      - |
+        if {{.COMPOSE}} exec -T os2display bin/console lexik:jwt:check-config >/dev/null 2>&1; then
+          echo "JWT keypair OK — leaving it untouched."
+        else
+          echo "JWT keypair missing or invalid for the current JWT_PASSPHRASE — regenerating."
+          {{.COMPOSE}} exec -T --user deploy os2display bin/console lexik:jwt:generate-keypair --overwrite
+        fi
+
   cache:clear:
     desc: Clear the application cache
     aliases: [cc]

UPGRADE.md

@@ -231,9 +231,10 @@ admin commands sometimes do.
 task install                  # pulls the rest of the images, runs `bin/console app:update`
                               # (Doctrine migrations + cache:warmup) in a one-off container
                               # BEFORE bringing the web tier up, then brings up the full
-                              # stack, generates the JWT keypair if missing, and interactively
-                              # prompts for tenant + admin user (skip these if you already
-                              # have them — your old data is still there).
+                              # stack, ensures the JWT keypair matches JWT_PASSPHRASE
+                              # (regenerating only on mismatch), and interactively prompts
+                              # for tenant + admin user (skip these if you already have
+                              # them — your old data is still there).
 ```
 
 `task install` reuses the existing data: the bundled mariadb's named volume from 1.x carries

scripts/env-init.sh

@@ -14,13 +14,13 @@
 #     variable rc3+ uses inside DATABASE_URL. Either way, the bundled
 #     value can't drift behind the stack and Doctrine picks the right
 #     SQL dialect.
-#   - ./jwt/{private,public}.pem: wiped if present, because rotating
-#     JWT_PASSPHRASE orphans whatever keypair the previous install
-#     generated. `task install`'s `lexik:jwt:generate-keypair
-#     --skip-if-exists` then regenerates fresh against the new
-#     passphrase. Skipping this wipe lets the runtime fail login with
-#     "Unable to create a signed JWT from the given configuration"
-#     (auth succeeds, signing fails).
+#   - ./jwt/{private,public}.pem: left ALONE. This script never deletes
+#     operator key material — a wipe here is invisible to upgrade paths
+#     that don't run `task install` (e.g. clone -> v3 via `task up`),
+#     stranding them with no keypair. Instead, when a fresh .env.symfony
+#     rotates JWT_PASSPHRASE, we warn that any existing keypair no longer
+#     matches; `task jwt:ensure` (run by `task install`, and available
+#     standalone) validates the keypair and regenerates only on mismatch.
 #
 # This is the single bootstrap entry point. `task install` / `task up` /
 # `task update` precondition on `.env.symfony` existing — running this is
@@ -105,31 +105,24 @@ rm -f .env.symfony.bak
 
 # JWT_PASSPHRASE was just rotated to a fresh random value. Any pre-
 # existing keypair at ./jwt/{private,public}.pem was encrypted with
-# whatever passphrase preceded this run — it's now orphaned and
-# `task install`'s `lexik:jwt:generate-keypair --skip-if-exists`
-# won't notice the mismatch, so login would 500 with "Unable to
-# create a signed JWT from the given configuration." (auth succeeds,
-# JWT signing fails). Wipe the orphans here; `task install`
-# regenerates fresh against the new passphrase.
-#
-# Route the rm through a transient alpine container: the keypair is
-# written by the os2display container's UID 1042 `deploy` user, so
-# on Linux hosts a host-side `rm` fails with "Permission denied"
-# unless the operator runs as UID 1042 or has sudo. Docker Desktop
-# (macOS/Windows) brokers ownership at the VM boundary, so a host
-# `rm` would work there — but the container path is portable.
-JWT_WIPED=""
+# whatever passphrase preceded this run, so it no longer matches. We do
+# NOT delete it here — `task jwt:ensure` (run by `task install`) validates
+# the keypair against the passphrase and regenerates only on mismatch, so
+# the fix works whether or not `task install` is the next step. Just flag
+# the orphan so the operator isn't surprised.
+JWT_ORPHANED=""
 if [ -f jwt/private.pem ] || [ -f jwt/public.pem ]; then
-  docker run --rm -v "$PWD/jwt:/jwt" alpine rm -f /jwt/private.pem /jwt/public.pem
-  JWT_WIPED="yes"
+  JWT_ORPHANED="yes"
 fi
 
 echo
 echo ".env.symfony created from $IMAGE."
 echo "  APP_SECRET / JWT_PASSPHRASE: random 32-byte hex (auto-generated)"
 echo "  DATABASE_URL serverVersion:  ${MARIADB_TAG}-MariaDB (matched to compose pin)"
-if [ -n "$JWT_WIPED" ]; then
-  echo "  ./jwt/*.pem:                 wiped (orphaned by rotated JWT_PASSPHRASE)"
+if [ -n "$JWT_ORPHANED" ]; then
+  echo "  ./jwt/*.pem:                 kept, but no longer match the rotated"
+  echo "                               JWT_PASSPHRASE — 'task jwt:ensure' (run by"
+  echo "                               'task install') regenerates them on mismatch."
 fi
 echo
 echo "Edit .env.symfony for any ADMIN_*, CLIENT_*, OIDC_*, or DATABASE_URL"