Files
stack/docs/plans/2026-10-22_sso-phase2-window.md

8.2 KiB

Plan: Q175 phase 2 window, the live Console switches to --sso

Sage, 2026-10-22. Draft 3 for Mos, after mos-1266. It names 86f95bb27, live since 04:03:00Z on 10-22. Sources: agents/sage/work/q175-sso/DESIGN.md sections 5 and 10 (phase 2 order, rollback, Jason-gated steps), Mos's C1 condition (mos-0977, b416d2ede), Jason's phase 2 answers (Q209, mos-1216, mos-1217), mos-1195, mos-1197 and mos-1245. Rows 192 (phase 1), 200 (activate --sso), its N1 follow-up and 273 (activate --send and --no-sso) have landed. Vikunja #412, Gitea #385.

The tool gap is closed

Draft 2 found two missing scripts/stack-release.sh flags: activate --send and activate --no-sso. Row 273 added both (mos-1246, F39). It landed as 0bbf0f6d1 (Gitea #1778), and the 86f95bb27 re-pin put it live (activation 20261022T040256Z-86f95bb27f6c). --send refuses unless the run's Console flags hold --sso, given or carried. --no-sso takes the Console flags from the rollback set of the activation that turned --sso on, and it drops --send. Neither flag ran in that re-pin, so step 5 and rollback 1 are their first live use. Darkwing's gate on 0bbf0f6d1 ran stack-release.test.mjs 218/218, including T53, T57 and T58.

When

Only when Jason starts the window (mos-1197). Nothing below runs before his start. The re-pin condition is met: W12 passed on 86f95bb27 at 04:26:43Z on 10-22, and Mos closed that window in mos-1266. This plan names 86f95bb27, which carries phase 1 and row 273, so its loader accepts a config with or without console. If another re-pin lands before Jason starts, the plan names the copy live at that point, and step 3 runs against it.

Who

  • Sage or Darkwing runs the agent steps under Q173: backup first, STATE report after.
  • Mos or Jason starts and restarts the Console (decision 102).
  • Jason signs in, sends and signs out.
  • Config writes 1 and 2 (steps 4 and 8) are an agent's, console key only, each with a backup first and a validate after. Mos's message to Jason at the window start names them. If Jason says he'll write them himself, steps 4 and 8 become his and nothing else changes (mos-1245 (a)).

Values

  • Provider: the existing Authentik mosaic-stack provider (A5). Issuer https://auth.diversecanvas.com/application/o/mosaic-stack/. Redirect https://mosaic.woltje.com/auth/callback. The Logout URI field holds /auth/signed-out.
  • clientId fvchAepp9ZGoVq8l7YKej3Gbh5dyf8vNv9ORpDaU (mos-1217, not a secret).
  • clientSecret { "slot": "console-sso-authentik" }. The slot file is ~/.config/mosaic-dev/secrets/mosaic-stack/console-sso-authentik, set to 0600 by Mos at 21:25:06Z on 10-21 (A6).
  • subjects: Jason's sub only, name jason.woltje (mos-1197). The loader refuses an empty list (sso-config.mjs:62), and the Console reads the config only at start. So the first write carries one placeholder subject. The real sub replaces it after his first sign-in, followed by a restart (A8).

Steps

  1. Backups: the bus store, the release pointer, the Console unit and config.json, each copied 0600 into a new dated directory, with sha256 recorded. The pointer backup records the pre-window Console flags the rollback restores.
  2. Slot shape check (A6), without printing or copying the value: stat shows mode 0600 and the owner; wc -l is 1; tr -cd '\r' <slot | wc -c is 0; the last byte is a newline (tail -c1 | od -An -c).
  3. Straggler check (C1): list every running process, unit and timer that reads config.json, with the copy it runs from (/proc/<pid>/exe and cwd links, systemctl --user list-units, list-timers). Each one must run from 86f95bb27, or be shown never to re-read config. Step 4 waits until the list is clean.
  4. Config write 1 (agent, backup from step 1): add console.sso with the values above and one subject { "sub": "pending-first-sign-in", "name": "jason.woltje" }. scripts/mosaic-config.mjs validate reads it back before anything starts.
  5. First scripts/stack-release.sh activate 86f95bb27 mosaic-stack --sso --send --plan. Its from line must name 86f95bb27 (--expect-from is for --units external only, so the live user units refuse it as a usage error). Then the same command without --plan, the same way earlier re-pins handled the Console. The tester stays the private socket from row 196 (--tester-socket). The --plan output names every flag it drops (--public-host, --auth-header, --allow-user) and every flag it carries. The run stops if --sso or --send is missing or a forward-auth flag remains. Mos or Jason starts the Console. No agent starts it.
  6. The start line shows one provider, the issuer and subjects 1. No secret value, no sub.
  7. Jason's first sign-in (A8). It refuses subject-unknown. An agent reads sub= from that one log line, checks that iss= is the issuer above, and records that the refused sub is not the placeholder. The sub goes into the window record, not into any message.
  8. Config write 2 (agent, new backup first): replace the placeholder with Jason's sub, so the list holds that one subject only. Validate. Mos or Jason restarts the Console. The start line shows subjects 1.
  9. Jason signs in, sends one message and signs out.
  10. Unsigned write refused (mos-1195), within Q173 (mos-1245 (c)): an agent acts as an anonymous client, not as Jason. It POSTs one Console write to 127.0.0.1:7332 with no cookie and no auth header, and the body names a tester-owned thread, so a wrong 2xx reaches no live seat. It expects 401 sign-in required with the bus event count unchanged, and it writes nothing else. No agent sends X-authentik-username to the live Console (design section 8).
  11. Forged header refused: on a scratch Console from the same copy (serve --sso --port <scratch>, MOSAIC_CONFIG at a scratch config with a scratch dataRoot and a dummy slot, issuer an unreachable loopback host, no --send and no tester), a request with X-authentik-username and no cookie gets 401. Mos or Jason may run the same check on live instead (B6).
  12. Sign-out landing (A5): after step 9, did Authentik land on /auth/signed-out, or did it refuse post_logout_redirect_uri? sso.mjs deletes the session before redirecting, so a miss changes only the landing page. On a miss, Mos turns it into one small ask to Jason, and the window still counts as passed.
  13. STATE report: pointer, copy, schema, Console flags from the unit, the start line, results of steps 7-12, backup paths and digests. Gitea #385 gets the STATE comment. The --sso flag carries forward on later re-pins (mos-1197).

Stops

  • Any refusal in steps 2-6 or 8: stop, keep the backups, and roll back as below. Never edit around it.
  • While the placeholder is the only subject, any sign-in that creates a session is a stop and a rollback (mos-1245 (b)).
  • Step 10: any result other than 401 with the event count unchanged is a stop, and it goes to Mos.
  • Two failures in the window: stop and report to Mos (mos-0823).

Rollback

  1. Same-copy re-activate (mos-1245 R1): scripts/stack-release.sh activate 86f95bb27 mosaic-stack --no-sso --plan, then the same without --plan. R1 asked for --expect-from 7247d80c7, but --expect-from is for --units external only and the live units are user units, so the plan's from line must name 86f95bb27 instead. The --plan output must show the pre-window Console flags from the step 1 pointer backup: --port 7332 --public-host mosaic.woltje.com --auth-header X-authentik-username --allow-user jason.woltje --tester-socket, exactly. --no-sso drops --send (mos-1246 F39), so there's no --send. A plan that differs is a stop. Mos or Jason restarts the Console.
  2. Restore config.json from the step 1 backup, which removes console. 86f95bb27 loads config with or without the key, so the order of 1 and 2 doesn't matter on this copy.
  3. STATE after the rollback reads config.json, the unit's Console flags and the pointer.
  4. Last resort only, and it goes to Mos first: scripts/stack-release.sh rollback goes to the previous distinct copy, 7247d80c7. Both copies are at schema 3j and 7247d80c7 carries phase 1, so it's a pointer flip with no --restore. Its --plan must show the pre-window Console flags above. Any restore goes to Mos and ends the window (mos-1226).