fiddy/docs/app_dev_plan/01_auth.md

App Dev Plan

Current focus

Auth (register/login/logout) with DB-backed sessions and HttpOnly cookies.

Goals

• Custom email/password auth using the existing users + sessions tables.
• Server-side session validation only (no client-side RBAC trust).
• Minimal, secure cookies with expiration based on SESSION_TTL_DAYS.
• Keep UI simple and mobile-first.
• Add/adjust unit tests for auth flows.

Proposed implementation

Server routes (Next.js App Router)

Create API routes:

• POST /api/auth/register
  • Body: { email, password, displayName? }
  • Validations: email format, password length >= 8
  • Hash password, create user, create session, set HttpOnly cookie
• POST /api/auth/login
  • Body: { email, password }
  • Verify password, create session, set HttpOnly cookie
• POST /api/auth/logout
  • Clears cookie and deletes session from DB

Server helpers

Add helpers for:

• Password hashing/verification (bcrypt)
• Session token generation and SHA-256 hashing for storage
• Session cookie settings (name + ttl from env)
• Shared DB pool (pg)

UI pages

Update:

• app/login/page.tsx: basic form, error handling, POST to /api/auth/login
• app/register/page.tsx: basic form, error handling, POST to /api/auth/register

Tests

Add unit tests covering:

• Registration creates user + session
• Login rejects invalid credentials
• Logout removes session

Files to be created/modified

• apps/web/app/api/auth/register/route.ts
• apps/web/app/api/auth/login/route.ts
• apps/web/app/api/auth/logout/route.ts
• apps/web/lib/auth.ts
• apps/web/lib/db.ts
• apps/web/app/login/page.tsx
• apps/web/app/register/page.tsx
• apps/web/package.json (deps + test runner)

Env usage

Required:

• DATABASE_URL
• DATABASE_SSL (true/false)
• SESSION_COOKIE_NAME
• SESSION_TTL_DAYS

Notes

• All session checks will be server-side only.
• No receipt bytes will ever be returned in list endpoints (future scope).

Status

Implemented

• API routes:
  • POST /api/auth/register
  • POST /api/auth/login
  • POST /api/auth/logout
• Helpers:
  • apps/web/lib/auth.ts
  • apps/web/lib/db.ts
• UI:
  • apps/web/app/login/page.tsx
  • apps/web/app/register/page.tsx
• Tests:
  • apps/web/__tests__/auth.test.ts
• Dependencies added in apps/web/package.json.

Test output

Initial run: 0 tests discovered. Updated test script to node --test --import tsx/register __tests__/auth.test.ts. This failed due to ERR_PACKAGE_PATH_NOT_EXPORTED from tsx/register. Switched to tsx __tests__/auth.test.ts.