Review: Keycloak: Enable player self-registration on westside-basketball realm

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Sprint 6 decomposition context
• [x] Repo -- ldraney/pal-e-services
• [x] User Story -- WS-S38
• [x] Context -- clear motivation, two options laid out, recommendation given
• [x] File Targets -- two files listed
• [x] Feature Flag -- none (appropriate for IaC change)
• [x] Acceptance Criteria -- 4 items
• [x] Test Expectations -- 3 items plus terraform plan command
• [x] Constraints -- 3 items
• [x] Checklist -- present
• [x] Related -- 4 items with cross-references

Traceability

• [x] story:WS-S38 label -- present on board item
• [x] story note verified -- WS-S38 found in project-westside-basketball user-stories section under Parent: "As a parent, I want to create an account, log in through the iOS app, and be routed to my subscription status page so I can manage payments and see where I stand"
• [x] arch:app-store label -- present on board item
• [ ] arch note MISSING -- [SCOPE] No note found for arch-app-store in pal-e-docs. Create architecture note arch-app-store for the App Store component.
• [x] Forgejo issue -- ldraney/pal-e-services#154, open

File Targets

• [x] terraform/k3s.tfvars -- verified: symlink to ~/secrets/pal-e-services/k3s.tfvars. westside-basketball realm exists with registration_allowed = false. Change to true is straightforward.
• [ ] terraform/keycloak.tf -- ISSUE: file exists and handles realm config, but currently has NO keycloak_default_roles resource. AC #2 says "New self-registered users automatically get player role" but there is no mechanism to assign a default role to self-registered users. The keycloak_realm resource manages registration_allowed but not default role assignment. A new keycloak_default_roles resource is needed (provider supports it since v4.x). This also requires a new variable in variables.tf for default_roles per realm.

Repo Placement

Dependencies

• #1633 (next_up, sprint:6) -- "Drop stale basketball DB role + update Keycloak westside-ror references" touches the same Keycloak terraform files. Should be completed BEFORE this ticket to avoid merge conflicts. Not documented in issue.
• #1646 (backlog, depends:154) -- downstream, depends on this ticket. Properly documented.
• #1647 (backlog, depends:154) -- downstream spike, depends on this ticket. Properly documented.
• westside-basketball#83 (open) -- player-facing status page, needs player auth. Downstream consumer.
• westside-basketball#87 (open) -- role-based routing, needs player role. Downstream consumer.
• Related issue pal-e-services#152 (same as board #1633) -- should be done first to clean up westside-ror references before adding new realm features.

Acceptance Criteria

• [x] AC1: "Self-registration enabled" -- verifiable via terraform plan output
• [ ] AC2: "New self-registered users automatically get player role" -- NOT achievable with file targets as written. Requires keycloak_default_roles resource which is not in scope. Issue body needs to add this file target and the corresponding variable.
• [x] AC3: "Self-registration page renders correctly" -- verifiable manually
• [x] AC4: "Existing admin accounts unaffected" -- verifiable via terraform plan

Blast Radius

• Other realms unaffected -- change is scoped to westside-basketball realm only via tfvars.
• reset_password_allowed is currently false -- self-registered users will not be able to reset passwords. The issue doesn't mention enabling this, but self-registration without password reset creates a poor UX. Consider whether reset_password_allowed should also flip to true.
• SMTP config has placeholder password -- the SMTP block in k3s.tfvars has auth_password = "REPLACE_WITH_GMAIL_APP_PASSWORD". If SMTP isn't configured, email verification and password reset won't work. Self-registration without email verification is a security risk (bots). Issue should note whether SMTP is actually configured or if the placeholder was already replaced.
• No email verification required action specified -- Keycloak can require email verification on self-registration. The issue doesn't mention this. Without it, anyone can create accounts with fake emails.

Decomposition Assessment

Recommendations

• [BODY] Add file target: terraform/variables.tf -- add optional default_roles field to keycloak_realms variable type.
• [BODY] Add file target detail for terraform/keycloak.tf -- add keycloak_default_roles resource that assigns default realm roles to self-registered users.
• [BODY] Add dependency note: should be done after #1633 (pal-e-services#152) which cleans up westside-ror Keycloak references in the same files.
• [BODY] Address reset_password_allowed -- consider flipping to true alongside self-registration. Self-registered users without password reset is poor UX.
• [BODY] Address SMTP placeholder -- confirm whether Gmail app password is actually configured in the secrets file, or add AC to configure it.
• [BODY] Consider adding email verification required action for self-registered users to prevent bot accounts.
• [SCOPE] Create architecture note arch-app-store for the App Store component referenced by the arch:app-store label.