pal-e-docs

Review: spike: Keycloak auth + visibility-based access control for paldocs

review-1384-2026-06-07 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Spike
  • [x] Lineage -- Standalone, operational need stated
  • [x] Repo -- Multiple repos listed with primary identified
  • [x] Question -- Clear top-level question with 8 sub-questions
  • [x] Deliverables -- docs/auth-visibility-architecture.md + follow-up tickets
  • [x] Time-box -- 1 session
  • [x] Related -- project, SOP, and board referenced

Traceability

  • [x] story:auth label present
  • [ ] story note MISSING -- [SCOPE] No "story:auth" entry exists in project-paldocs user-stories section. Create user story entry on project-paldocs.
  • [x] arch:keycloak label present
  • [ ] arch note MISSING -- [SCOPE] arch-keycloak note does not exist in pal-e-docs. This is a recurring gap flagged in at least 3 prior reviews (review-1141, review-938, review-1182). Create architecture note arch-keycloak for the Keycloak component.
  • [x] Forgejo issue -- ldraney/paldocs#23, open
  • [x] sop-keycloak-client-creation -- referenced and verified to exist (active SOP)

File Targets

N/A -- Spike type. Deliverable is a new doc to be created (docs/auth-visibility-architecture.md). No existing file targets to verify.

Repo Placement

OK. Issue filed on ldraney/paldocs (listed as primary). Spike is investigative across multiple repos (paldocs, pal-e-docs, pal-e-services, pal-e-deployments) -- appropriate to file on the primary consumer repo.

Dependencies

  • Item #1369 "Deploy paldocs to production" is in next_up. Auth decisions from this spike should inform the deployment configuration (whether to gate behind Keycloak before going public). This dependency is NOT documented in the issue body.
  • Item #1344 "Postgres trigger" is in_progress -- no dependency conflict.
  • Prior art exists: pal-enterprises Rails app already uses omniauth + Keycloak (see arch-rails-app). The spike should reference this as a starting point.

Acceptance Criteria

Spike deliverables are clear and verifiable: (1) docs/auth-visibility-architecture.md merged via docs-only PR, (2) follow-up tickets created. Time-box of 1 session provides a hard stop. An agent can verify completion by checking for the doc file and new board items.

Blast Radius

Low for the spike itself (investigation only). The decisions made here will have high blast radius on follow-up implementation -- affecting pal-e-docs API (visibility filtering), paldocs Rails app (auth middleware), pal-e-services (Terraform Keycloak client), and pal-e-deployments (secrets). But that blast radius is appropriately deferred to follow-up tickets.

Decomposition Assessment

No decomposition needed. This is a time-boxed investigation spike with a single deliverable doc. 1 session, 1 primary output. Well within the 5-minute rule for agent execution.

Recommendations

  • [SCOPE] Create user story entry "story:auth" on project-paldocs user-stories section. Suggested text: "As an admin, I can control which notes are visible to members vs public, so that sensitive operational docs remain private."
  • [SCOPE] Create architecture note arch-keycloak for the Keycloak component. This is a platform-wide gap that has been flagged in 3+ prior reviews. Should cover: realm structure, client pattern, role hierarchy, integration conventions.
  • [BODY] Add dependency note to Related section: "board-paldocs #1369 (Deploy paldocs to production) -- auth spike findings should inform deployment config (public vs gated)."
  • [BODY] Add reference to prior art: "arch-rails-app (pal-enterprises) -- existing Rails + omniauth-keycloak pattern to reference."