Review: Spike: Revert ROPC, restore Auth Code flow with Keycloak theme + ASWebAuthenticationSession

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Spike
• [x] Lineage -- Supersedes #157, references #132, #134, #135, #151, #158
• [x] Repo -- ldraney/landscaping-assistant + ldraney/pal-e-services + turbo-ios (multi-repo documented)
• [x] Question -- Primary question + 6 sub-questions well-framed
• [x] Deliverables -- 5 concrete outputs listed
• [x] Time-box -- 4 hours
• [x] Context -- Thorough rationale for why ROPC is wrong
• [x] Constraints -- tofu apply restriction, prod state, user count
• [x] Related -- Cross-references to #157, #132, #158, pal-e-services #106, docs/keycloak-setup.md

Traceability

• [x] story:auth label present
• [ ] story note MISSING -- [SCOPE] Create user story entry "auth" on project-landscaping-assistant user-stories section. The user-stories table currently has: address-lookup, property-crud, service-tracking, special-notes, work-queue, weekly-tracking, schedule-upload. No "auth" entry exists despite many board items using the story:auth label.
• [x] arch:rails-app label present
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-rails-app for the Rails application component.
• [x] arch:ios label present
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-ios for the iOS (turbo-ios) component.
• [x] Forgejo issue -- ldraney/landscaping-assistant#159, open

File Targets

• [x] docs/keycloak-setup.md -- verified: exists, contains existing ROPC analysis from spike #132 that aligns with this spike's premise
• [x] config/initializers/omniauth.rb -- verified: exists, contains OmniAuth OIDC configuration (current prod code)
• [x] app/controllers/sessions_controller.rb -- verified: exists, uses OmniAuth auth hash (not ROPC), confirms prod is on Auth Code flow
• [x] docs/app-architecture.md -- verified: exists, line 282 already documents "ROPC was rejected per OAuth 2.1 deprecation"

Repo Placement

Dependencies

• Board item #1373 (issue #157, "Direct Access Grants rewrite") is in QA column -- this spike's outcome directly affects its disposition. If spike recommends revert, #157/#158 work is superseded.
• Board item #1339 (issue #117, "Crew tab") is in_progress -- no direct dependency.
• pal-e-services PR #106 (direct_access_grants_enabled terraform) -- mentioned in spike questions, merged but not applied. Spike will determine whether to revert.
• No blocking dependencies prevent this spike from starting.

Acceptance Criteria

• "Decision: revert #158 or re-implement" -- binary output, verifiable
• "Keycloak theme approach" -- docs artifact, verifiable by existence
• "ASWebAuthenticationSession wiring" -- code sketch or reference, verifiable
• "Updated auth flow mermaid diagram" -- visual artifact, verifiable
• "List of follow-up implementation tickets" -- verifiable by existence

Blast Radius

• Auth pattern is app-wide -- affects every authenticated request. However, this spike produces docs/decisions, not code changes, so blast radius is contained to the spike itself.
• keycloak-setup.md already documents ROPC rejection rationale from spike #132. This spike extends that analysis, not contradicts it.
• No other platform apps use ROPC for user auth (basketball-api uses it only for admin API against master realm).
• The follow-up implementation tickets (a spike deliverable) will carry the actual blast radius. Those tickets should be individually scoped and reviewed.

Decomposition Assessment

Recommendation

• [SCOPE] Create user story entry "auth" on project-landscaping-assistant user-stories section. Multiple board items (at least 15) reference story:auth but no backing user story exists on the project page.
• [SCOPE] Create architecture note arch-rails-app for the Rails application component.
• [SCOPE] Create architecture note arch-ios for the iOS (turbo-ios) component.