brief: bundled Pocket ID for users with no OIDC provider, design (Q203, Vikunja #458, mos-1202)

docs/plans/2026-10-21_bundled-pocket-id.md

@@ -0,0 +1,72 @@
+# Brief: bundled Pocket ID for users with no OIDC provider (Q203, Vikunja #458), design
+
+Sage, 2026-10-21, for Mos's order mos-1202 item 2. Vikunja #458, parent #412 (SSO). Owner Launchpad,
+reviewer Webby, gate owner Sage. After row 252. This row is a design. The deliverable is
+`agents/launchpad/work/queue-ROW/DESIGN.md`. Build rows come from it after the design is approved.
+
+## What Jason asked for
+
+DECISIONS Q203, relayed by Mos in mos-1202, verbatim: "Let's use O6. If a user does not have an OIDC
+provider to configure, we will need to use a bundled Pocket ID instances to handle this traffic."
+
+O6, as Mos put it to Jason: "keep the REQ-WEB-2 wording OIDC-only. Identity is the (issuer, subject) pair
+from the Console's own verified OIDC sign-in. Local accounts come from a provider, and the Console never
+holds passwords." PRD 1.9 (f48725cfc) has REQ-WEB-2 on those terms.
+
+Mos's reading of the second sentence, labelled as his, following lead decision 44 items 5 and 6
+(`docs/plans/2026-09-26_lead-decisions.md:655-663`):
+- The installer offers two choices: point the Console at one or more existing OIDC providers, or deploy a
+  bundled Pocket ID.
+- The stack installs that Pocket ID and writes it as the Console's one providers entry. No Pocket ID source
+  goes in the repository, and the Console gets no sign-in path apart from the Q175 relying party.
+- Pocket ID is passkey-only. Agents keep per-role service tokens.
+- dragon-lin keeps Authentik. This is outside the 10-27 MVP.
+
+The PRD requirement for Q203 is drafted separately and goes to Mos first. Until it lands, cite Q203 and
+this brief. The PRD's v1 scope list still has "Pocket ID and SSO" out of v1, and its technical notes say
+"Pocket ID is wired in after v1". This row doesn't change either.
+
+## Where things stand
+
+- Row 192 (landed 4429a104f) is the Console's OIDC relying party, `--sso`, with the Q175 start checks.
+  Row 200 adds `stack-release.sh activate --sso`, and row 238 its `--instance` hint.
+- REQ-INST-1 sets what an optional install component is: pinned, health-checked, removable, and switched
+  on in the organization file or system config. SearXNG is the first one.
+- Researcher's note `agents/researcher/work/2026-10-04_vikunja-pocketid.md` covers Pocket ID v2.17.0
+  (BSD-2, passkey-only, client credentials). Check the version against what is current before pinning.
+
+## What the design must settle
+
+1. The choice. Where the installer asks, how "existing providers" and "bundled Pocket ID" are recorded,
+   and what each writes into `console.sso`. With the bundled choice, Pocket ID is the only providers
+   entry.
+2. The component, against REQ-INST-1: the pinned release and how its digest is checked, how it runs
+   (unit, user, data directory under the instance's data root), its health check, and removal. No Pocket ID
+   source in the repository.
+3. The Q175 start checks against the bundled instance. The Console must start against it with no
+   relaxation: discovery, PKCE S256, asymmetric signing algorithms only, issuer match, registered redirect
+   and post-logout URIs. Name any Pocket ID default that would fail a check, and the setting that fixes it.
+4. The client. Who creates the Console's OIDC client in Pocket ID, and how its secret reaches the slot
+   file. No agent reads or prints the value. Secrets never enter the repository or an image.
+5. The first person. Pocket ID is passkey-only, so say how the installing user enrolls a passkey, and how
+   their subject gets into `console.sso`. On Jason's instances only his subject goes there (mos-1197).
+6. Reach. WebAuthn needs a secure origin and a fixed relying-party id. State what the bundled instance
+   needs (host name, TLS, proxy) and keep loopback-only the default. Anything that changes who can reach the
+   Console or Pocket ID from outside is Jason's, so the design names those steps as his.
+7. Agents. Per-role service tokens are unchanged. Pocket ID issues nothing an agent uses.
+8. Instances. Each named instance gets its own Pocket ID or shares one. Say which and why, given one
+   system config per instance.
+9. Tests on stand-ins only: a fake provider shaped like Pocket ID (discovery, JWKS, token endpoint), as row
+   192's tests do. No test downloads or starts a real Pocket ID.
+10. The build rows, each with its own gate, in landing order.
+
+## Boundaries
+
+- Design only. No code, no install anywhere, no download of Pocket ID onto any host.
+- dragon-lin keeps Authentik. No change to .53 or .54 (mos-1167).
+- No external accounts, no DNS or certificate requests, no Traefik change. Those are Jason's.
+
+## Gate
+
+Webby approves DESIGN.md. Sage checks it against Q203, O6, REQ-WEB-2 and REQ-INST-1, and sends any choice
+that would change what an existing requirement allows or forbids to Mos before the build rows are added.