Merge: PR #42 from sameboat-platform/feat/week-3-checkout

This pull request introduces several backend hardening features focused on authentication, session management, and documentation. The most important changes are the addition of password complexity enforcement during registration, in-memory login rate limiting with a new error code, scheduled session pruning, and comprehensive documentation updates reflecting these improvements. Integration tests have been added for all major new features.

Author: ArchILLtect

CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+### Added
+- Password complexity validation on registration (min 8 chars, includes upper/lower/digit) with validation message.
+- In-memory login rate limiting (5 attempts within 5 minutes by email+IP) returning HTTP 429 `RATE_LIMITED`.
+- Scheduled session pruning job (hourly) with JPQL bulk delete; transactional execution.
+- Integration tests: password complexity, rate limiting, session pruning.
+- Documentation: `docs/RISKS.md` and `docs/spikes/jwt-session-tradeoffs.md`.
+- Public version endpoint `GET /api/version` that returns the deployed version (from JAR manifest when available, falling back to `project.version`).
+- Spring profiles for development and production:
+  - `dev`: in-memory H2, relaxed cookies (host-only, `Secure=false`), and CORS including `http://localhost:5173`.
+  - `prod`: Postgres/Neon, secure cookies (domain + `Secure=true`), explicit CORS allowlist.
+- CORS configuration via `CorsConfig` and Security chain `.cors()`; credentials enabled and origins restricted to configured list.
+- CI release job on tag push (`v*`): builds JAR and attaches it to a GitHub Release using `softprops/action-gh-release@v1`.
+
+### Changed
+- `README.md`: Documented password policy, `RATE_LIMITED` error code, and updated sample passwords; linked to new docs.
+- `docs/api.md`: Updated error codes, register/login behavior, and added pruning notes.
+- `Architecture.md`: Reflected opaque sessions, rate limiting, password policy, and pruning.
+- `CONTRIBUTING.md`: Included `RATE_LIMITED` in error codes and noted password complexity under security.
+- Unified Actuator base path to `/actuator` across profiles; health and info remain exposed publicly via security rules. Legacy `/api/actuator/*` references were removed from tests/config where applicable.
+- Security rules clarified: public `GET /health`, `GET /actuator/health`, `GET /actuator/info`, auth endpoints `POST /api/auth/login|register|logout` (and legacy `/auth/*`) remain public; other endpoints require authentication (e.g., `GET /api/me`).
+- Input validation tightened on auth payloads (`@Valid` + Bean Validation). Validation errors are mapped by `GlobalExceptionHandler` to `400` with `{"error":"VALIDATION_ERROR"}`.
+- Documentation updates for profile usage, CORS, cookies, and deployment notes (Render/Neon).
+
+### Fixed
+- Session pruning ClassCastException by replacing derived delete with explicit JPQL bulk delete method and using `@Transactional` in pruner.
+- Added Flyway migration `V4__add_timezone_to_users.sql` to align schema with `UserEntity.timezone`, resolving startup error `column ... timezone does not exist`.
+- Addressed IDE warnings for the GitHub Release step by pinning the action and passing the `files` input; pipeline runs green on tags.
+
+---
+
+## [v0.1.0] - 2025-10-05 – Initial release
+### Added
+
+
+### Changed
+
+
+### Fixed
+
+
+---
+Reference: See `docs/weekly-plan/week-3/week-3-checkout-backend.md` for a narrative weekly summary.
+
+
+[Unreleased]: https://github.com/sameboat-platform/backend/compare/v0.1.0...HEAD
+[v0.1.0]: https://github.com/sameboat-platform/backend/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -41,11 +41,12 @@ Maintain ≥ 70% instruction coverage (Jacoco gate enforces this during `mvn ver
 
 ## 7. Error Handling & Codes
 Use / extend centralized handler `GlobalExceptionHandler`.
-Existing codes: VALIDATION_ERROR, BAD_REQUEST, BAD_CREDENTIALS, UNAUTHENTICATED, SESSION_EXPIRED, INTERNAL_ERROR.
+Existing codes: VALIDATION_ERROR, BAD_REQUEST, BAD_CREDENTIALS, UNAUTHENTICATED, SESSION_EXPIRED, RATE_LIMITED, INTERNAL_ERROR.
 Add new domain exceptions + codes only with accompanying tests and update the catalog in `copilot-instructions.md` section 21.
 
 ## 8. Security (SECURITY_BASELINE)
 - Validate all request DTOs (Jakarta Bean Validation).
+- Enforce password complexity for registration: min 8 chars and must include upper, lower, and digit.
 - Avoid exposing sensitive internal details in error messages.
 - Never log secrets or raw tokens.
 - Enforce least privilege (avoid broad queries when specific ones suffice).

README.md

@@ -8,7 +8,7 @@
 > git remote set-url origin git@github.com:sameboat-platform/sameboat-backend.git
 > ```
 
-> Quick Links: [Instructions (setup & migrations)](./docs/instructions.md) | [API Reference](./docs/api.md) | [Week 3 Plan](./docs/weekly-plan/week-3/week-3-plan.md) | [Contributing](./CONTRIBUTING.md) | Guard Rails: [Copilot Instructions](.github/copilot-instructions.md) | Journals: [Index](./docs/journals/README.md) · [Week 1](./docs/journals/Week1-Journal.md) · [Week 2](./docs/journals/Week2-Journal.md)
+> Quick Links: [Instructions (setup & migrations)](./docs/instructions.md) | [API Reference](./docs/api.md) | [Risks](./docs/RISKS.md) | [JWT vs Extended Sessions (Spike)](./docs/spikes/jwt_vs_extended_sessions.md) | [Week 3 Plan](./docs/weekly-plan/week-3/week-3-plan.md) | [Contributing](./CONTRIBUTING.md) | Guard Rails: [Copilot Instructions](.github/copilot-instructions.md) | Journals: [Index](./docs/journals/README.md) · [Week 1](./docs/journals/Week1-Journal.md) · [Week 2](./docs/journals/Week2-Journal.md)
 
 ## Getting Started (Contributors)
 Before writing code or using AI assistance:
@@ -187,6 +187,8 @@ Opaque session cookie `SBSESSION=<UUID>` (alias accepted: `sb_session`) issued o
 `POST /auth/login` (also `/api/auth/login`): returns full user envelope `{ "user": { ... } }`.
 - If `sameboat.auth.dev-auto-create=true` (test/dev), a non‑existent user with stub password is auto-created.
 - Passwords are stored with **BCrypt** (Spring `BCryptPasswordEncoder`).
+- Password complexity enforced: min 8 chars, must include upper, lower, and digit.
+- Login attempts are rate limited; excessive failures return `RATE_LIMITED` (HTTP 429).
 
 ### Logout
 `POST /auth/logout` clears server session and sends an expired cookie.
@@ -201,7 +203,7 @@ All non-2xx errors:
 ```json
 { "error": "<CODE>", "message": "Human readable explanation" }
 ```
-Current codes: `UNAUTHENTICATED`, `BAD_CREDENTIALS`, `SESSION_EXPIRED`, `EMAIL_EXISTS`, `VALIDATION_ERROR`, `BAD_REQUEST`, `INTERNAL_ERROR`.
+Current codes: `UNAUTHENTICATED`, `BAD_CREDENTIALS`, `SESSION_EXPIRED`, `EMAIL_EXISTS`, `VALIDATION_ERROR`, `BAD_REQUEST`, `RATE_LIMITED`, `INTERNAL_ERROR`.
 
 | Code | Typical Trigger |
 |------|-----------------|
@@ -211,6 +213,7 @@ Current codes: `UNAUTHENTICATED`, `BAD_CREDENTIALS`, `SESSION_EXPIRED`, `EMAIL_E
 | EMAIL_EXISTS | Duplicate registration attempt |
 | VALIDATION_ERROR | Bean validation (fields, sizes, empty patch body) |
 | BAD_REQUEST | Explicit IllegalArgument / future semantics |
+| RATE_LIMITED | Too many requests (e.g., repeated failed logins) |
 | INTERNAL_ERROR | Uncaught exception (trace id logged) |
 
 ## Quality Gates
@@ -255,15 +258,15 @@ Use any HTTP client or browser:
 
 ## Sample cURL
 ```bash
-# Register
+# Register (password must include upper, lower, digit and be >= 8 chars)
 curl -i -X POST http://localhost:8080/auth/register \
   -H 'Content-Type: application/json' \
-  -d '{"email":"dev@example.com","password":"abcdef","displayName":"Dev"}'
+  -d '{"email":"dev@example.com","password":"Abcdef12","displayName":"Dev"}'
 
 # Login
 curl -i -X POST http://localhost:8080/auth/login \
   -H 'Content-Type: application/json' \
-  -d '{"email":"dev@example.com","password":"abcdef"}'
+  -d '{"email":"dev@example.com","password":"Abcdef12"}'
 
 # Use cookie
 curl -i http://localhost:8080/me -H 'Cookie: SBSESSION=<uuid>'

TTD.md

@@ -87,18 +87,18 @@ Name it something clear like “Protect main (PR + CI)” and you’re done.
 ## 11. Completed Items Log (Append Here When Done)
 | Date | ID | PR | Notes |
 |------|----|----|-------|
+| 2025-10-16 | WK3-001 |  | Password complexity validation enforced (register); tests added; README/API updated |
+| 2025-10-16 | WK3-002 |  | Login rate limiting (5 attempts/5 min) with 429 RATE_LIMITED; tests added; logs at INFO |
+| 2025-10-16 | WK3-003 |  | Session pruning scheduler (hourly) with JPQL bulk delete; integration test added |
+| 2025-10-16 | WK3-006 |  | docs/RISKS.md created and linked; README references updated |
+| 2025-10-16 | WK3-007 |  | JWT vs. opaque sessions spike committed (docs/spikes/jwt-session-tradeoffs.md) |
 
 ---
 # 12. Week 3 Blocking Items (2025-10-05)
 | ID | Item | Description | Priority | Notes |
 |----|------|-------------|----------|-------|
-| WK3-001 | Password Complexity Validation | Enforce password rules (min 8 chars, 1 upper, 1 lower, 1 digit) and map violations to VALIDATION_ERROR | P1 | Add tests and document in API |
-| WK3-002 | Basic Rate Limiting | Implement naive rate limiting for auth endpoints (5 attempts/5 min/email/IP), return RATE_LIMITED | P1 | Add INFO log and tests |
-| WK3-003 | Session Pruning Job | Scheduled task to delete expired sessions hourly | P1 | Add integration test |
-| WK3-004 | Migration Test in CI | Ensure migration test runs in CI using Testcontainers/Postgres | P1 | Document in instructions.md |
-| WK3-005 | Unit Test Coverage | Add/improve unit tests for UserService, SessionService, password validator (≥75%) | P1 | Document coverage status |
-| WK3-006 | Docs: instructions.md, RISKS.md | Create and link instructions.md and RISKS.md | P1 | Link from README and project board |
-| WK3-007 | JWT Spike Doc | Prepare JWT spike decision doc (pros/cons, migration plan) | P2 | Link from README and project board |
+| WK3-004 | Migration Test in CI | Ensure migration test runs in CI using Testcontainers/Postgres | P1 | Deferred under BACKEND_CI_GUARD; evaluate adding profile/matrix next week |
+| WK3-005 | Unit Test Coverage | Add/improve unit tests for UserService, SessionService, password validator (≥75%) | P1 | Current gate 70% passing; raise to 75% after adding tests |
 
 ---
 ## Versioning & Continuous Delivery Checklist

docs/Architecture.md

@@ -2,7 +2,7 @@
 
 **FE (React+Vite) →** HTTP/JSON → **BE (Spring Boot 3, Java 21) →** JDBC → **Postgres (Neon)**
 
-- Auth: stub (session/JWT later)
+- Auth: opaque session cookie (UUID) with server-side lookup; registration enforces password complexity; login rate-limited; scheduled session pruning.
 - Core entities: users, stories, trust_events
 - Migrations: Flyway (V1 applied)
 - Envs: DB_URL only (OpenAI later)
@@ -15,7 +15,7 @@
 | Frontend (SPA) | Netlify | https://app.sameboatplatform.org | Calls API subdomain (CORS & cookies). |
 | Root Domains | Registrar / DNS | sameboatplatform.org (+ .com redirect) | `.com` 301 → `.org`. Configure APEX + `www` as needed. |
 | Database | Neon Postgres (managed) | TLS required (jdbc `sslmode=require`) | Branching for previews later. |
-| Session Cookie | Browser (Set by API) | Domain: `.sameboatplatform.org` | Name `SBSESSION`, `Secure`, `HttpOnly`, `SameSite=Lax`. |
+| Session Cookie | Browser (Set by API) | Domain: `.sameboatplatform.org` | Name `SBSESSION`, `Secure` (prod), `HttpOnly`, `SameSite=Lax`. |
 | CORS Allowlist | Spring Config | https://app.sameboatplatform.org | Credentials (cookies) allowed; keep list minimal. |
 
 ### Environment Variables (Prod Example)
@@ -38,10 +38,13 @@ SAMEBOAT_CORS_ALLOWED_ORIGINS=https://app.sameboatplatform.org
 - Enforce HTTPS at Render & Netlify; HTTP → HTTPS redirect.
 - TLS enforced to Neon with `sslmode=require`.
 - Only whitelisted origin gets credentialed CORS; avoid wildcard origins.
+- Registration password policy: min 8 chars, includes upper/lower/digit.
+- Rate limiting on login (5 attempts / 5 min) returns 429 RATE_LIMITED.
+- Scheduled session pruning removes expired rows (hourly); expiry also enforced at request time.
 
 ### Future Enhancements
 - Add staging environment: `staging-api.sameboatplatform.org` + Neon branch database.
 - CDN caching layer for static assets (handled by Netlify). API remains dynamic.
-- Potential WAF / rate limiting at edge (Render or external service) for auth endpoints.
+- Potential WAF / distributed rate limiting (e.g., Redis) for multi-instance auth endpoints.
 
 ---

docs/RISKS.md

@@ -0,0 +1,47 @@
+# Known Risks and Mitigations
+
+This document lists current risks in the backend and how we plan to mitigate them. It’s a living file; update as features evolve.
+
+## Authentication & Session Management
+- In-memory rate limiting
+  - Risk: Rate limiter state is reset on application restart (risk of brute force during a restart) and can produce false positives behind NAT/shared IPs.
+  - Mitigation: Threshold set conservatively (5 attempts/5 min). Consider moving to a distributed store (Redis) with IP + device fingerprinting for multi-instance environments. Add allowlist for known CI test users/domains.
+
+- Session pruning schedule
+  - Risk: If pruning job lags or fails, expired sessions could persist longer than intended, slightly increasing DB footprint.
+  - Mitigation: Pruner runs hourly with transactional bulk delete. Expiry is also enforced at request time, so stale rows don’t grant access.
+
+- Cookie security
+  - Risk: Misconfiguration of cookie domain/flags can expose sessions to subdomains or non-TLS contexts.
+  - Mitigation: Properties-driven; `Secure` and proper domain only in `prod`. CORS is strict to the SPA origin.
+
+## Input Validation & Error Handling
+- Password complexity
+  - Risk: Too lax passwords increase account takeover risk.
+  - Mitigation: Enforced via Bean Validation (min 8, includes upper/lower/digit). Consider adding symbol requirement and breached password checks in future.
+
+- Error envelope
+  - Risk: Overly detailed errors leak information.
+  - Mitigation: Centralized error envelope; `BAD_CREDENTIALS` is generic. Continue to avoid echoing sensitive inputs.
+
+## Data & Migrations
+- Flyway immutability
+  - Risk: Editing applied migrations causes drift.
+  - Mitigation: Guard scripts + CI gate. Always add new migrations.
+
+- Test vs. Prod DB behavior
+  - Risk: H2 and Postgres have subtle differences.
+  - Mitigation: Keep JPQL portable; use Testcontainers profile for schema verification.
+
+## Operational
+- Single-node assumptions
+  - Risk: In-memory components (rate limiter) don’t scale horizontally.
+  - Mitigation: Plan Redis-backed rate limiting and session store scale-out when moving to multi-instance.
+
+- Logging
+  - Risk: Over-logging auth events could create noise or risk PII.
+  - Mitigation: Minimal INFO logs; avoid payloads; consider structured logging in prod profile.
+
+---
+Related: docs/spikes/jwt-session-tradeoffs.md for token strategy considerations.
+

docs/api.md

@@ -1,25 +1,27 @@
 # SameBoat API Reference (Auth & User Profile Slice)
 
-Status: Week 2 vertical slice (dev stub for auth password). This document covers implemented endpoints and response contracts.
+Status: Week 3 backend hardening complete (password complexity, rate limiting, session pruning). This document covers implemented endpoints and response contracts.
 
 ## Conventions
 - All responses (success or error) are JSON.
 - Authentication: opaque session cookie (primary name `SBSESSION`, legacy/alias accepted: `sb_session`) containing a UUID.
-- Dev default TTL: 7 days. Prod profile (see `application-prod.yml`) sets Secure cookie, domain `.sameboat.<tld>`, TTL 14 days.
+- Dev default TTL: 7 days. Prod profile sets `Secure` cookie, domain `.sameboatplatform.org`, TTL 14 days.
 - Error envelope format:
   ```json
   { "error": "<CODE>", "message": "Human readable explanation" }
   ```
-- Bio max length is 500 characters (intentional spec choice for Week 2).
+- Bio max length is 500 characters (intentional spec choice).
 
-## Error Codes (401 / Auth Related)
+## Error Codes
 | Code | Meaning | Typical Source |
 |------|---------|----------------|
 | UNAUTHENTICATED | No / invalid / garbage cookie | EntryPoint / controllers |
 | BAD_CREDENTIALS | Bad email or password on login | /auth or /api/auth login |
 | SESSION_EXPIRED | Cookie valid but session expired | Filter -> EntryPoint |
 | EMAIL_EXISTS | Registration attempt with existing email (409) | /auth/register |
 | VALIDATION_ERROR | Body validation failure (400) | Controllers |
+| BAD_REQUEST | Explicit IllegalArgument (service) | Services / controllers |
+| RATE_LIMITED | Too many requests (e.g., repeated failed logins) (429) | /auth/login |
 | INTERNAL_ERROR | Unhandled exception (500) | Global handler |
 
 ## Data Models
@@ -40,7 +42,7 @@ Status: Week 2 vertical slice (dev stub for auth password). This document covers
 ```json
 { "error": "<CODE>", "message": "Human readable explanation" }
 ```
-Current `error` codes now include: `UNAUTHENTICATED`, `BAD_CREDENTIALS`, `SESSION_EXPIRED`, `EMAIL_EXISTS`, `VALIDATION_ERROR`, `BAD_REQUEST`, `INTERNAL_ERROR`.
+Current `error` codes now include: `UNAUTHENTICATED`, `BAD_CREDENTIALS`, `SESSION_EXPIRED`, `EMAIL_EXISTS`, `VALIDATION_ERROR`, `BAD_REQUEST`, `RATE_LIMITED`, `INTERNAL_ERROR`.
 
 ## Authentication
 ### POST /auth/login (also `/api/auth/login`)
@@ -58,15 +60,21 @@ Failure (401 BAD_CREDENTIALS):
 ```json
 { "error": "BAD_CREDENTIALS", "message": "Email or password is incorrect" }
 ```
+Failure (429 RATE_LIMITED):
+```json
+{ "error": "RATE_LIMITED", "message": "Too many attempts; try again later" }
+```
 
 ### POST /auth/register (also `/api/auth/register`)
-Registers a new user (email must be unique; password ≥ 6 chars). Returns a session cookie and minimal body containing the userId.
+Registers a new user (email must be unique). Returns a session cookie and minimal body containing the userId.
+
+Password policy: minimum 8 characters and must include at least one uppercase, one lowercase, and one digit.
 
 Request:
 ```json
 {
   "email": "dev@example.com",
-  "password": "abcdef",
+  "password": "Abcdef12",
   "displayName": "Dev"
 }
 ```
@@ -79,9 +87,9 @@ Responses:
   ```json
   { "error": "EMAIL_EXISTS", "message": "Email already registered" }
   ```
-- 400 VALIDATION_ERROR (e.g., password too short)
+- 400 VALIDATION_ERROR (e.g., password too weak)
   ```json
-  { "error": "VALIDATION_ERROR", "message": "password size must be between 6 and 100" }
+  { "error": "VALIDATION_ERROR", "message": "password must be at least 8 characters and include upper, lower, and digit" }
   ```
 
 ### POST /auth/logout (also `/api/auth/logout`)
@@ -122,6 +130,18 @@ Responses:
 - 400 Validation error → `VALIDATION_ERROR`
 - 401 If not authenticated / expired (distinct codes as above)
 
+## Public Utility
+### GET /api/version
+Returns the deployed backend version. Public and unauthenticated.
+
+Success (200):
+```json
+{ "version": "0.1.0" }
+```
+
+Notes:
+- In production, the value reflects the JAR manifest when available; falls back to `project.version` during development/test.
+
 ## Error Handling Summary
 | Scenario | Status | error code | Notes |
 |----------|--------|------------|-------|
@@ -131,6 +151,7 @@ Responses:
 | Registration duplicate | 409 | EMAIL_EXISTS | Email normalized & already present |
 | Validation failure | 400 | VALIDATION_ERROR | Field constraints |
 | Empty PATCH body | 400 | VALIDATION_ERROR | Enforced explicitly |
+| Rate limited login attempts | 429 | RATE_LIMITED | 5 failures within 5 minutes |
 | Generic uncaught exception | 500 | INTERNAL_ERROR | Trace id logged server-side |
 | Illegal argument (service) | 400 | BAD_REQUEST | Future usage |
 
@@ -139,19 +160,20 @@ Responses:
 - Validation: filter loads session by UUID; sets request attribute for expired → code `SESSION_EXPIRED`; missing/invalid → `UNAUTHENTICATED`.
 - Touch: `lastSeenAt` updated on authenticated requests.
 - Expiry: 7 days dev / 14 days prod.
+- Pruning: scheduled hourly job deletes expired sessions (server-side cleanup; expiry also enforced at request time).
 
 ## Example cURL Commands
 Login:
 ```bash
 curl -i -X POST http://localhost:8080/auth/login \
   -H "Content-Type: application/json" \
-  -d '{"email":"me@example.com","password":"dev"}'
+  -d '{"email":"me@example.com","password":"Abcdef12"}'
 ```
 Register:
 ```bash
 curl -i -X POST http://localhost:8080/auth/register \
   -H "Content-Type: application/json" \
-  -d '{"email":"me2@example.com","password":"abcdef","displayName":"Me Two"}'
+  -d '{"email":"me2@example.com","password":"Abcdef12","displayName":"Me Two"}'
 ```
 Expired (simulate): manually adjust DB row `expires_at` earlier and call `/me` with cookie to observe `SESSION_EXPIRED`.