Phase 3: Auth, Schema, and Data Access ​

Status: Complete Spec ID prefix: AUTHPhase: 3 Completed: 2026-02-20

Overview ​

Establishes the authentication system, Spring Boot backend, and data access layer that connect the frontend to persistent storage. Authentication uses GitHub OAuth via Spring Security OAuth2 Client + Spring Session JDBC, with PostgreSQL user records created on first sign-in. The data access layer follows a repository pattern -- interfaces in @nthtime/data-access are implemented by thin Next.js proxy routes that forward requests to Spring Boot with session cookies. The frontend uses TanStack React Query for all data fetching.

Dependencies ​

• [FOUND-01] (Nx monorepo)
• [DSST-01] through [DSST-07] (shared types)

User Flows ​

GitHub Sign-In ​

1. User clicks sign-in button
2. Next.js redirects to Spring Boot OAuth2 authorization endpoint
3. Spring Boot redirects to GitHub
4. GitHub callback -> Next.js /api/auth/callback/github -> forwarded to Spring Boot
5. Spring Boot creates/resolves AppUser + AuthAccount, sets JSESSIONID via Spring Session JDBC
6. Next.js forwards Set-Cookie to browser

Data Fetching (Frontend) ​

1. React component calls a hook (e.g., usePackList())
2. Hook uses TanStack React Query to fetch from /api/v1/packs
3. Next.js API route proxies to Spring Boot, forwarding JSESSIONID cookie
4. Spring Boot validates session via Spring Session JDBC, executes query
5. Result flows back through proxy to React Query cache

Acceptance Criteria ​

Authentication ​

• [ ] AUTH-01 -- GitHub OAuth sign-in creates or resolves an AppUser + AuthAccount in PostgreSQL via Spring Security OAuth2.
• [ ] AUTH-02 -- Session stored in PostgreSQL via Spring Session JDBC; JSESSIONID cookie used for authentication.
• [ ] AUTH-03 -- Feature flag NEXT_PUBLIC_FF_AUTH controls whether auth UI is rendered (defaults to enabled).

Database Schema ​

• [ ] AUTH-04 -- packs table (JPA entity Pack) with columns: name, slug, description, language, framework, version, author, tags, authorUserId, visibility, createdAt, updatedAt with indexes on slug and author.
• [ ] AUTH-05 -- challenges table (JPA entity Challenge) with JSONB columns for assertions and referenceSolution, plus columns for packId, slug, title, prompt, difficulty, tags, timeEstimateSeconds, hints, order with indexes on pack and pack+slug, plus a tsvector search index on title.
• [ ] AUTH-06 -- attempts table (JPA entity Attempt) with JSONB for assertionResults, plus userId, challengeId, passed, hintsUsed, timeSeconds with indexes on user+challenge, user, and challenge.
• [ ] AUTH-07 -- user_settings table (JPA entity UserSettings) with per-user feedback flags, keybindings, darkMode, formatter config, and fileStubs.

Session-Based Authentication ​

• [ ] AUTH-08 -- All Next.js API routes proxy to Spring Boot via spring-boot-proxy.ts, forwarding JSESSIONID cookie.
• [ ] AUTH-09 -- Spring Security validates session on every request; unauthenticated requests return 401.

Data Access Layer ​

• [ ] AUTH-10 -- PackRepository interface defines listPacks, getChallenges, getChallenge, getChallengeByPackAndSlug, and search methods.
• [ ] AUTH-11 -- AttemptRepository interface defines createAttempt and listAttempts methods.
• [ ] AUTH-12 -- SettingsRepository interface defines getSettings and updateSettings methods.
• [ ] AUTH-13 -- AuthorRepository interface defines CRUD methods for author packs and challenges.

Rate Limiting ​

• [ ] AUTH-14 -- Bucket4j rate limiter (Spring Boot) restricts attempt creation to 10/min and settings updates to 20/min per user.
• [ ] AUTH-15 -- Author write operations rate-limited to 30/min.

Technical Context ​

Key Files ​

Patterns and Decisions ​

• Repository pattern -- interfaces in @nthtime/data-access decouple frontend from backend specifics. Implemented by Spring Data JPA repositories in services/api.
• TanStack React Query -- chosen for control over caching, refetching, and optimistic updates. The provider stack is QueryProvider only (no SessionProvider).
• Proxy pattern -- Next.js /api/v1/* routes are thin proxies that forward requests to Spring Boot /api/* with JSESSIONID cookie forwarding via spring-boot-proxy.ts.
• Session architecture -- JSESSIONID cookie, Spring Session JDBC stores sessions in PostgreSQL. No JWTs or service tokens.

Spring Boot Endpoints ​

API Routes ​

Test Coverage ​

Unit Tests ​

Spring Boot Tests ​

Open Questions ​

• None at this time.