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

review-1384-2026-06-07-re Review

review ready

Project

Verdict: APPROVED

Re-review of board item #1384. Prior review (review-1384-2026-06-07) found 4 issues; all have been addressed.

Template Completeness

[x] Type -- Spike
[x] Lineage -- Standalone, operational need stated
[x] Repo -- Multiple repos listed with primary identified (ldraney/paldocs)
[x] Question -- Clear top-level question with 8 sub-questions covering client setup, roles, visibility model, enforcement, sessions, public access, agent access, migration
[x] Deliverables -- docs/auth-visibility-architecture.md + follow-up tickets
[x] Time-box -- 1 session
[x] Related -- project-paldocs, sop-keycloak-client-creation, board-paldocs, #22 dependency, arch-rails-app prior art, arch-keycloak-paldocs stub all referenced

Traceability

[x] story:auth label present
[x] story note verified -- story-paldocs-auth exists with Superadmin and Member user stories, scoped to Keycloak-based auth and visibility
[x] story listed on project page -- project-paldocs user-stories section includes story-paldocs-auth entry
[x] arch:keycloak label present
[x] arch note verified -- arch-keycloak (platform-wide, pal-enterprises) exists; arch-keycloak-paldocs (project-specific stub) also exists with pending decisions and prior art references
[x] arch listed on project page -- project-paldocs architecture section includes arch-keycloak-paldocs entry
[x] Forgejo issue -- ldraney/paldocs#23, open

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 investigates across multiple repos (paldocs, pal-e-docs, pal-e-services, pal-e-deployments) -- appropriate to file on the primary consumer repo. No Keycloak/OIDC code exists in the paldocs repo yet (confirmed via grep), consistent with spike being investigative.

Dependencies

[x] #22 (Deploy paldocs to production) -- documented in issue body Related section. Currently in next_up. Auth spike findings will inform deployment configuration (public vs gated). Dependency relationship is clear.
[x] #1344 (Postgres trigger) -- in_progress, no dependency conflict.
[x] Prior art (arch-rails-app) -- documented in issue body Related section. pal-enterprises already implements omniauth + Keycloak OIDC pattern.

Acceptance Criteria

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

Blast Radius

Low for the spike itself (investigation only, no code changes). Decisions made here will have high downstream impact on follow-up implementation tickets, but that blast radius is appropriately deferred. No existing auth/visibility code in the paldocs repo to conflict with.

Decomposition Assessment

No decomposition needed. Time-boxed investigation spike with a single deliverable doc and follow-up ticket creation. 1 session, 1 primary output. Well within the 5-minute rule for agent execution.

Prior Review Issues -- Resolution Status

[x] RESOLVED: story-paldocs-auth note created -- contains Superadmin and Member user stories with proper scope and related links
[x] RESOLVED: arch-keycloak-paldocs stub note created -- contains pending decisions, prior art references (arch-keycloak, arch-rails-app, sop-keycloak-client-creation), and spike linkage
[x] RESOLVED: Issue body updated with #22 dependency -- Referenced in Related section with context about auth decisions affecting deployment
[x] RESOLVED: Issue body updated with arch-rails-app prior art -- Referenced in Related section as starting point for investigation

Recommendation

No action needed. All prior review issues have been addressed. Ticket is ready to advance.