Files
stack/docs/plans/2026-10-20_sso-phase1.md

2.8 KiB

Brief: Q175 phase 1, the Console verifies SSO itself (--sso)

Sage, 2026-10-20, for Q175 (Jason's ruling), mos-0971/0973/0977 and Vikunja #412. Gitea #1690. MVP T1 item 2. Owner Launchpad, reviewer Webby (mos-0981), gate owner Sage. Base: refactor at the brief commit.

The design is approved: agents/sage/work/q175-sso/DESIGN.md at d55d86bb0 (blob eba861f5d2), Filbert r3 approve plus the D1/D2 ack, Mos C1 confirmation in mos-0977, whose straggler-check condition is in the phase 2 window at b416d2ede. Build phase 1 exactly as the design says. If the code shows the design is wrong somewhere, stop and tell Sage, Webby and Filbert before building around it.

Scope (phase 1 only, design section 5 item 1)

  • oauth4webapi 3.8.8, pinned exactly (design section 2). No other new dependency.
  • The OIDC relying party in the Console: /auth/login, /auth/callback, /auth/logout, /auth/signed-out, the callback steps 1-7, our own checks on top of the library, and sessions, cookies and Host rules (design sections 1 and 3).
  • The shared loader, scripts/mosaic-config.mjs, accepts an optional console key and checks only its shape. The slot file checks and the read run in the Console's --sso start, and the slot resolves from the config dir (section 4, D1, D2).
  • The degraded start for an unreachable provider, and the unreachable/refused classes (Q-B, section 4).
  • --sso for cli.mjs serve and webui-service.sh, with its refusals against the old flags.
  • The tester listener rules (section 6).
  • The page: both fetch paths in packages/webui/src/public/app.js (:111 and :305) treat a 401 sign-in required as signed out, and the notice links to /auth/login?return=<path> (C2).
  • Logging as the design says, including the Q-E subject-unknown line.

Out of scope: the phase 2 window, the live config.json key, phase 3 removals, the proxy-forwarded token (section 7), and any change to the live Console.

Tests and mutants

Design section 9: tests 1-25, the positive paths, and every listed mutant, each killed by its named test. All tests run against the fake OP in packages/webui/tests/helpers/fake-oidc.mjs. No test reaches a real provider or Authentik, and no test touches ~/.mosaic-dev, ~/.config/mosaic-dev, the live units or a slot file. Test 25 goes in scripts/test-config.sh.

Boundaries

  • No request of any kind to auth.diversecanvas.com, mosaic.woltje.com or the live 127.0.0.1:7332 (mos-0971, design section 8).
  • No credential value is read, printed or logged.
  • npm install runs only inside the worktree that has its own package.json, never in a directory that would walk up to home.

Gate

Webby approves the manifest. Filbert approved the design and answers design questions. The webui and cli suites, scripts/test-config.sh and every scripts/test-*.sh are green on Sage's gate, and the design's mutants are killed.