docs: capture exploration — wavepath framework asks as phases 19.2 to 19.6

.planning/ROADMAP.md

@@ -34,6 +34,11 @@ Decimal phases appear between their surrounding integers in numeric order.
 - [ ] **Phase 18: Payment Gateway** - Port Golem15.PaymentGateway and its Stripe operator, with Horoskopia as the acceptance consumer
 - [ ] **Phase 19: Chat and ChatChannels** - Port Golem15.Chat and Golem15.ChatChannels on lighthouse
 - [ ] **Phase 19.1: Chat satellites** - Port chatbots, chatvideo, forum, herald and userfriends
+- [ ] **Phase 19.2: Chat polish against WavePath clients** - Replay WavePath's chat traffic through `tide` against the ported chat plugins until green
+- [ ] **Phase 19.3: Framework transport and infrastructure for WavePath** - Cookie refresh, credentialed CORS, cache and Redis rate limits, S3 option, OpenAPI page, Turnstile
+- [ ] **Phase 19.4: OIDC provider on wristband** - Discovery, JWKS with key rotation, id_token, userinfo, consent and pairwise subjects
+- [ ] **Phase 19.5: Social login in sm-user-plugin** - Google and Facebook login with the SPA one-time-code handoff
+- [ ] **Phase 19.6: Two-factor auth and device flow in sm-user-plugin** - TOTP, WebAuthn, email and recovery codes, trusted devices, device authorization
 - [ ] **Phase 20: Płytarium cutover** - Parity harness green, both real clients run unchanged in production
 
 ## Phase Details
@@ -1114,7 +1119,7 @@ Plans:
 **Mode:** mvp
 **Depends on:** Phase 11
 **Repos:** `sm-chat-plugin` and `sm-chatchannels-plugin` (new, under `git.golem15.com/golem15/`); `summercms.go` only if `lighthouse` is missing a feature
-**Port sources:** `/media/nvme/dev/jz/wavepath.org/plugins/golem15/{chat,chatchannels}`. Wavepath is the heaviest user. Check its copy (with `root_id` threading) against the starter's before choosing the source.
+**Port sources:** `/media/nvme/dev/jz/wavepath.org/plugins/golem15/{chat,chatchannels}`. Port the Wavepath copy (with `root_id` threading and `thread_summaries`); decided 2026-10-11, see `.planning/notes/wavepath-framework-asks-division.md`.
 **Requirements**: TBD
 **Success Criteria** (what must be TRUE):
 
@@ -1148,11 +1153,107 @@ Plans:
 Plans:
 - [ ] TBD (run $gsd-plan-phase 19.1 to break down)
 
+### Phase 19.2: Chat polish against WavePath clients (INSERTED)
+
+**Goal:** The ported chat and chat satellites carry WavePath's chat traffic exactly as PHP does. The chat routes that WavePath's clients call are recorded with `tide`, replayed against the Go plugins and fixed until green, so that chat, the core feature of WavePath, is not the risk in the WavePath migration.
+**Mode:** mvp
+**Depends on:** Phase 19, Phase 19.1
+**Repos:** `sm-chat-plugin`, `sm-chatchannels-plugin` and the satellite repos; `summercms.go` only for `lighthouse` or `tide` gaps
+**Requirements**: TBD
+**Success Criteria** (what must be TRUE):
+
+  1. A `tide` corpus of the chat, channel, thread, video-room and push routes, recorded from the PHP backend through `vue-wavepath-app`, `wavepath-mcp` and `hubot-wavepath`, replays green against the Go plugins.
+  2. Realtime events on the `chat`, `video` and `presence:` namespaces match the PHP broadcasts recorded by the `tide` Centrifugo recorder.
+  3. Behaviour stays neutral to the other consumers of these plugins (QuestStream, Horoskopia, Portal). Framework READMEs and docs still name no application.
+  4. The new code has unit tests, delivered in the phase's last plan.
+
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /msd-plan-phase 19.2 to break down)
+
+### Phase 19.3: Framework transport and infrastructure for WavePath (INSERTED)
+
+**Goal:** The framework has the transport and infrastructure pieces a multi-client, multi-instance application needs: JWT cookie refresh across subdomains, credentialed CORS, a cache module with a Redis-backed rate-limit store, an S3 blob option, an OpenAPI page and Turnstile verification.
+**Mode:** mvp
+**Depends on:** Phase 11
+**Repos:** `summercms.go`
+**Requirements**: TBD
+**Success Criteria** (what must be TRUE):
+
+  1. `bouncer` refresh issues a new httpOnly `token` cookie whose `Domain`, `SameSite` and `Secure` attributes are configurable to match PHP, and blacklists the old JTI. The 60-minute TTL and 14-day refresh window are config keys, and credentialed CORS for a configured SPA origin is available as middleware.
+  2. A cache module ships with memory and Redis drivers, and `surf` gains a Redis-backed `Store`, so rate limits hold across instances. The Redis client dependency has a decision note before code lands.
+  3. An S3 blob driver can be selected through framework config, so the application does not import it. `/api-docs` and `/api-docs.json` can be served. Turnstile verification middleware is available.
+  4. The touched modules' READMEs and `docs/` pages are updated. The new code has unit tests, delivered in the phase's last plan.
+
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /msd-plan-phase 19.3 to break down)
+
+### Phase 19.4: OIDC provider on wristband (INSERTED)
+
+**Goal:** `wristband` is a full OpenID Connect provider that existing relying parties can switch to without noticing: discovery, JWKS with asymmetric signing and key rotation, `id_token`, userinfo, resumable authorization with account switching, a consent store and pairwise subjects. The existing issuer, signing keys and client secrets carry over.
+**Mode:** mvp
+**Depends on:** Phase 8, Phase 19.3
+**Repos:** `summercms.go`
+**Requirements**: TBD
+**Success Criteria** (what must be TRUE):
+
+  1. A decision note settles whether the full OIDC provider extends the hand-written `wristband` server or puts zitadel/oidc v3 behind it, before code lands.
+  2. `/.well-known/openid-configuration`, the JWKS endpoint, userinfo and `id_token` in the token response work with RS256 or ES256 keys. Rotation publishes the old and the new key together.
+  3. The authorization flow supports resuming a request, switching account, the consent list and revocation, and pairwise and public subjects. A scheduled prune job removes expired codes, tokens and requests.
+  4. An existing issuer, its signing keys and client secrets can be imported so that relying parties keep working. The phase gets a security review.
+  5. The `wristband` README and `docs/` pages are updated. The new code has unit tests, delivered in the phase's last plan.
+
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /msd-plan-phase 19.4 to break down)
+
+### Phase 19.5: Social login in sm-user-plugin (INSERTED)
+
+**Goal:** `sm-user-plugin` signs users in with Google and Facebook through `/oauth/{provider}` and its callback, with a provider registry open to more providers, the SPA one-time-code handoff and the pending-registration branch, matching the PHP user plugin's contract.
+**Mode:** mvp
+**Depends on:** Phase 19.3
+**Repos:** `sm-user-plugin`; `summercms.go` only if a provider client belongs in the framework
+**Requirements**: TBD
+**Success Criteria** (what must be TRUE):
+
+  1. `/oauth/google` and `/oauth/facebook` and their callbacks keep the PHP paths, because desktop shells hard-code them.
+  2. SPA mode (`?mode=spa&frontend_callback=…`) redirects with a one-time code that `oauth-complete` exchanges. A new social user who still needs profile completion goes through `oauth-register-complete`.
+  3. Identities are linked on login and listed and unlinked through the existing identity routes. Both applications that consume the plugin still build and pass their tests.
+  4. The new code has unit tests, delivered in the phase's last plan.
+
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /msd-plan-phase 19.5 to break down)
+
+### Phase 19.6: Two-factor auth and device flow in sm-user-plugin (INSERTED)
+
+**Goal:** `sm-user-plugin` has the PHP user plugin's second factors and device login: TOTP, WebAuthn, email codes, recovery codes and trusted devices, a challenge step during login, and QR/code device authorization.
+**Mode:** mvp
+**Depends on:** Phase 19.3
+**Repos:** `sm-user-plugin`
+**Requirements**: TBD
+**Success Criteria** (what must be TRUE):
+
+  1. TOTP setup, confirm and disable; WebAuthn registration and login challenges; email codes; recovery codes; and trusted devices all work against the PHP contract. The WebAuthn dependency has a decision note before code lands.
+  2. Login with a second factor enabled returns the unauthenticated challenge step, rate-limited by the `2fa-verify` bucket.
+  3. Device authorization (`devices/initiate`, `devices/status/{token}`, `devices/authorize`, and the device list and revoke) works on the `DeviceAuthSession` model.
+  4. The models TwoFactorMethod, TwoFactorChallenge, TwoFactorRecoveryCode, TrustedDevice, WebAuthnCredential and DeviceAuthSession and their migrations are ported. The phase gets a security review. The new code has unit tests, delivered in the phase's last plan.
+
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /msd-plan-phase 19.6 to break down)
+
 ### Phase 20: Płytarium cutover
 
 **Goal**: The parity harness is green on every manifest route and `vue-fonoteka-app` and `fonoteka-mcp` run unchanged against the Go backend in daily use in production — the Płytarium definition of done.
 **Mode:** mvp
-**Depends on**: Phase 2, Phase 8, Phase 9, Phase 10, Phase 12, Phase 12.1, Phase 13, Phase 14, Phase 14.1, Phase 14.2, Phase 15, Phase 16
+**Depends on**: Phase 2, Phase 8, Phase 9, Phase 10, Phase 12, Phase 12.1, Phase 13, Phase 14, Phase 14.1, Phase 14.2, Phase 15, Phase 16, Phases 19 to 19.6 (decided 2026-10-11: the 19.x WavePath readiness work lands before the cutover)
 **Repos:** fonoteka.go, summercms.go
 **Requirements**: API-09, QA-05
 **Success Criteria** (what must be TRUE):
@@ -1167,7 +1268,7 @@ Plans:
 ## Progress
 
 **Execution Order:**
-Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.1 → 14.2 → 14.2.1 → 14.3 → 15 → 16 → 17 → 18 → 18.1 → 19 → 19.1 → 20
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.1 → 14.2 → 14.2.1 → 14.3 → 15 → 16 → 17 → 18 → 18.1 → 19 → 19.1 → 19.2 → 19.3 → 19.4 → 19.5 → 19.6 → 20
 (Phase 2 depends on Phase 1's command kernel; the two are no longer parallel.)
 
 | Phase | Plans Complete | Status | Completed |
@@ -1198,6 +1299,11 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 18.1. Payment Gateway Subscriptions | 0/TBD | Not started | - |
 | 19. Chat and ChatChannels | 0/TBD | Not started | - |
 | 19.1. Chat satellites | 0/TBD | Not started | - |
+| 19.2. Chat polish against WavePath clients | 0/TBD | Not started | - |
+| 19.3. Framework transport and infrastructure for WavePath | 0/TBD | Not started | - |
+| 19.4. OIDC provider on wristband | 0/TBD | Not started | - |
+| 19.5. Social login in sm-user-plugin | 0/TBD | Not started | - |
+| 19.6. Two-factor auth and device flow in sm-user-plugin | 0/TBD | Not started | - |
 | 20. Płytarium cutover | 0/TBD | Not started | - |
 
 ## Backlog

.planning/notes/wavepath-framework-asks-division.md

@@ -0,0 +1,45 @@
+---
+title: How the WavePath framework asks divide between SummerCMS and WavePath
+date: 2026-10-11
+context: /msd-explore on the WavePath hand-off list `/media/nvme/dev/jz/wavepath.org/.planning/notes/summercms-framework-asks-for-wavepath.md`. Seed `SEED-261007-0tb`.
+---
+
+# How the WavePath framework asks divide between SummerCMS and WavePath
+
+WavePath's agent wrote a list of what it needs from SummerCMS (section A) and what it will do itself (section B). Section B stays on the WavePath side as its migration milestone. Section A lands here as the 19.x phases, all before the Płytarium cutover (Phase 20).
+
+## Decisions
+
+- **The 19.x block comes before the cutover.** Chat first, then chat polish, then the other framework and user-plugin asks. Phase 20 waits for 19 to 19.6. The WavePath migration milestone opens after Phase 20.
+- **Chat is ported from the WavePath copy**, with `root_id` threading and `thread_summaries`. This settles the open chat-source question for Phase 19.
+- **The seed's trigger is now "Phase 20 complete".** The WavePath milestone no longer waits for the Horoskopia port.
+
+## Where each ask lands
+
+| Ask | Where |
+|---|---|
+| A9: chat and chatchannels | Phase 19 |
+| A9: chatbots, chatvideo (LiveKit, reconcile job), forum, herald (web push), userfriends | Phase 19.1 |
+| Chat parity against WavePath's clients | Phase 19.2 |
+| A3 cookie refresh and CORS, A6 cache and Redis `surf.Store`, A8 S3 option, `/api-docs`, Turnstile | Phase 19.3 (`summercms.go`) |
+| A1 OIDC provider | Phase 19.4 (`wristband`) |
+| A2 social login | Phase 19.5 (`sm-user-plugin`) |
+| A4 2FA, A5 device flow | Phase 19.6 (`sm-user-plugin`) |
+| A7 `summer import:winter` | Phase 20 (D-02 runner), with the WavePath stress cases below |
+
+## Corrections to the hand-off list
+
+- **The user plugin is already shared.** `sm-user-plugin` (`git.golem15.com/golem15/sm-user-plugin`) is its own repo, checked out by both fonoteka.go and sm-bm-app. Phases 19.5 and 19.6 add to it directly. Both consuming apps must still build after each change.
+- **Plugin-registrable token scopes (A8) are dropped for now.** `sm-user-plugin` already mints scoped tokens (`MintAPIToken`, `HasScope`). Its allowed list (`read`, `write`, `ai`) is a static package variable. WavePath's `wave.scope.public:*` scopes belong to its own `wave_token` guard and `golem15_wavepath_api_tokens` table, which section B ports on the WavePath side. Add a `RegisterAPITokenScope` hook only if WavePath confirms that its user-plugin tokens carry custom scopes.
+
+## `import:winter` stress cases from WavePath (for Phase 20)
+
+- The source is MariaDB. That is the same MySQL wire protocol, but check type coercion.
+- About 90 tables, including large chat and channel message tables. Batching must handle them.
+- APP_KEY-encrypted columns go through the Laravel-decrypt hook.
+- Zero-knowledge encryption-key blobs are copied byte for byte and never decoded.
+- `system_files` across 16 attaching models, and 9 `system_settings` rows.
+
+## Scope reminder
+
+The WavePath backend is about 350 routes, about 90 tables and 164 migrations across `wavepath` and its shared plugins. The PHP routes are not frozen, so re-count when the milestone opens.

.planning/phases/19.2-chat-polish-against-wavepath-clients/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/19.3-framework-transport-and-infrastructure-for-wavepath/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/19.4-oidc-provider-on-wristband/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/19.5-social-login-in-sm-user-plugin/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/19.6-two-factor-auth-and-device-flow-in-sm-user-plugin/.gitkeep

@@ -0,0 +1 @@
+

.planning/research/questions.md

@@ -4,6 +4,11 @@
 
 - **Does PaymentGateway need `winter/location`?** It is installed in 19 projects. Check whether PaymentGateway shipping addresses, the shop or user profiles read its countries and states. If they do, Phase 18 needs a Go equivalent (a framework module or an `sm-location-plugin`). Phase: 18.
 - **Does Horoskopia define the full Phase 18 acceptance contract?** Which `vue-horoskopia-app` requests reach PaymentGateway or subscription code? Do they cover the order and refund paths, or only subscriptions? Are other order flows tested only through hand-written host tests? Phase: 18.
-- **Which chat source should Phase 19 port?** Wavepath's chat has `root_id` threading and `thread_summaries`. Compare it with the starter's `wn-chat-plugin` and the other 16 copies, and pick the newest as the 1:1 source. Phase: 19.
+- ~~**Which chat source should Phase 19 port?**~~ **Settled 2026-10-11:** port the Wavepath copy, with `root_id` threading and `thread_summaries`. See `.planning/notes/wavepath-framework-asks-division.md`. Phase: 19.
 - **Does any Płytarium route need userfriends?** PHP fonoteka has `golem15/userfriends`, but fonoteka.go has no port, and Phase 14 reached 175/175 routes without one. Confirm before porting it for Wavepath in Phase 19.1, so there is one shared copy. Phase: 19.1.
 - **How should Herald's Web Push be done in Go?** Herald uses `minishlink/web-push`. Choose a Go Web Push/VAPID library (or a stdlib implementation) and record it in a decision note before Phase 19.1 code lands. Phase: 19.1.
+
+## From the WavePath framework asks exploration (2026-10-11)
+
+- **Should the full OIDC provider extend the hand-written `wristband` server, or put zitadel/oidc v3 behind it?** Phase 8 hand-wrote `wristband` on the standard library (`.planning/notes/oauth2-wristband-direct-port.md`). Phase 19.4 adds discovery, JWKS with RS256/ES256 rotation, `id_token`, userinfo, consent and pairwise subjects. That is protocol and security code where a maintained library is preferred, and zitadel/oidc v3 is already named in the stack. Settle it in a decision note before code lands. Phase: 19.4.
+- **Do WavePath's user-plugin tokens carry custom scopes?** If they do, `sm-user-plugin` needs a `RegisterAPITokenScope` hook in place of the static `AllowedAPITokenScopes`. Ask the WavePath side. Phase: 19.3 or the WavePath milestone.

.planning/seeds/SEED-261007-0tb-wavepath-port.md

@@ -3,7 +3,7 @@ id: SEED-261007-0tb
 status: dormant
 planted: 2026-10-07
 planted_during: Phase 16 (context gathered)
-trigger_when: The Horoskopia port (SEED-261007-j2b) is complete, and Phases 19 and 19.1 (chat and the chat satellites) are done.
+trigger_when: Phase 20 (Płytarium cutover) is complete. Phases 19 to 19.6 already deliver the framework and shared-plugin work WavePath needs.
 scope: Large
 ---
 
@@ -15,27 +15,30 @@ Wavepath (`/media/nvme/dev/jz/wavepath.org`) is the largest Golem15 app and the
 
 ## When to Surface
 
-**Trigger:** after the Horoskopia port, with Phases 19 and 19.1 done. This stretch is about preparing the shared plugins, not migrating apps, and a stabilization phase after Phase 20 may come first.
+**Trigger:** once Phase 20 is complete. Phases 19 to 19.6 come first and cover WavePath's framework asks (chat, chat polish, transport and infrastructure, OIDC, social login, 2FA and device flow). The milestone no longer waits for the Horoskopia port (changed 2026-10-11).
 
 ## Scope Estimate
 
 **Large:** a milestone, probably larger than Płytarium:
 
-- **App plugin:** `wavepath` has 30.6k PHP LOC and **255 routes**, compared with Płytarium's 175. Expect 2–3 API phases plus a cutover phase.
+- **App plugin:** `wavepath` has 30.6k PHP LOC and **255 routes**, compared with Płytarium's 175. The whole backend surface the clients use is about **350 routes** (wavepath 255, user 46, journal 11, oauthserver 10, chatvideo 6, userfriends 5, feedback 3, and a few small ones), with about 90 tables and 164 migrations. PHP routes are not frozen, so re-count when the milestone opens. Expect 3–4 API phases plus a cutover phase.
+- **Database:** WavePath moves from MariaDB to Postgres as part of the port, through `summer import:winter`. This replaces WavePath's planned Laravel 12 upgrade.
 - **Clients:** `vue-wavepath-app`, `wavepath-mcp`, `tauri-wavepath-desktop`, `electron-wavepath` and `hubot-wavepath`. All of them define the parity contract.
 - **Required shared plugins:**
   - Ported: user.
   - Phase 19: chat, chatchannels.
   - Phase 19.1: chatbots, chatvideo, forum, herald, userfriends.
   - Already covered by framework `lighthouse`: websockets.
-- **OAuth:** `oauthserver` (5.5k LOC, 10 routes, OIDC) sits on the framework's `wristband` package. OIDC parts (id_token, userinfo) may be new to `wristband`.
+- **OAuth:** `oauthserver` (5.5k LOC, 10 routes, OIDC) sits on the framework's `wristband` package. Phase 19.4 makes `wristband` a full OIDC provider.
+- **Division of work:** WavePath's agent listed what it needs from SummerCMS and what it does itself. See `/media/nvme/dev/jz/wavepath.org/.planning/notes/summercms-framework-asks-for-wavepath.md` and `.planning/notes/wavepath-framework-asks-division.md`.
 - **Also mounted:** feedback (ported), journal (ported), sitemap and faq (Phase 17), and paymentgateway/pgstripe. Wavepath's own code never references PaymentGateway, so check whether it can be dropped.
 
 ## Breadcrumbs
 
 - `.planning/notes/core-plugin-port-inventory.md`
 - `.planning/notes/oauth2-wristband-direct-port.md`
-- `.planning/ROADMAP.md`: Phases 19 and 19.1
+- `.planning/notes/wavepath-framework-asks-division.md`
+- `.planning/ROADMAP.md`: Phases 19 to 19.6 and 20
 - `.planning/research/questions.md`: chat source version, Herald Web Push dependency
 
 ## Notes