AI Implementation feature(857): Authenticated Shell: Header, Quick Tabs and Change Password (#14)
This commit was merged in pull request #14.
This commit is contained in:
+104
-16
@@ -1,9 +1,9 @@
|
||||
---
|
||||
type: api
|
||||
title: Auth Endpoints
|
||||
description: Login, refresh, logout, public self-registration, CSRF, first-admin registration, and registration throttling.
|
||||
tags: [api, auth, login, register, refresh, csrf]
|
||||
timestamp: 2026-07-21T18:28:00Z
|
||||
description: Login, refresh, logout, public self-registration, CSRF, /me, change-password, first-admin registration, and registration throttling.
|
||||
tags: [api, auth, login, register, refresh, csrf, me, change-password]
|
||||
timestamp: 2026-07-21T22:19:08Z
|
||||
---
|
||||
|
||||
# Endpoints
|
||||
@@ -14,6 +14,8 @@ timestamp: 2026-07-21T18:28:00Z
|
||||
| `POST` | `/api/v1/auth/login` | `@Public()` | Enforced — same pattern as `register`. CSRF skip was removed in this change. | Yes — `LoginBackoffService` per IP + username | `backend/src/modules/auth/auth.controller.ts` |
|
||||
| `POST` | `/api/v1/auth/refresh` | Public route, requires a valid refresh cookie. | Skipped (the request is a `POST` carrying an HttpOnly cookie, not a state-changing user action). | No | `backend/src/modules/auth/auth.controller.ts` |
|
||||
| `POST` | `/api/v1/auth/logout` | Authenticated (JWT). | Enforced. | No | `backend/src/modules/auth/auth.controller.ts` |
|
||||
| `GET` | `/api/v1/auth/me` | Authenticated (JWT). | n/a (`GET`). | No | `backend/src/modules/auth/auth.controller.ts` |
|
||||
| `POST` | `/api/v1/auth/change-password` | Authenticated (JWT). | Enforced. | No | `backend/src/modules/auth/auth.controller.ts` |
|
||||
| `GET` | `/api/v1/auth/csrf` | `@Public()` | n/a (`GET`). | No | `backend/src/modules/auth/auth.controller.ts` |
|
||||
| `POST` | `/api/v1/auth/register-first-admin` | `@Public()` | Skipped (path is in `CsrfMiddleware.SKIP_PATH_PREFIXES`). | Yes | `backend/src/modules/users/users.controller.ts` |
|
||||
|
||||
@@ -64,27 +66,103 @@ The refresh token is set as an `HttpOnly` cookie via `setRefreshCookie(res, sess
|
||||
* `AuthService.registerFirstAdmin(username, password, ip)` uses the same limiter before checking whether an administrator already exists.
|
||||
* The limiter is an in-memory Nest provider in `backend/src/common/services/registration-rate-limit.service.ts`; counters are process-local and reset when the API process restarts.
|
||||
|
||||
# `GET /api/v1/auth/me`
|
||||
|
||||
Authenticated-only projection of the current user, including derived rank
|
||||
and total points from the `solve` table.
|
||||
|
||||
| HTTP | `code` | When |
|
||||
|------|-----------------|-----------------------------------------------------|
|
||||
| 200 | — | Returns `{ id, username, role, rank, points }`. |
|
||||
| 401 | `UNAUTHORIZED` | No JWT on the request (handled by `JwtAuthGuard`). |
|
||||
|
||||
## Successful response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "<uuid>",
|
||||
"username": "player1",
|
||||
"role": "player",
|
||||
"rank": 3,
|
||||
"points": 275
|
||||
}
|
||||
```
|
||||
|
||||
* `rank` is `null` while the user has 0 points (no rank assigned).
|
||||
* `points` is `SUM(solve.pointsAwarded)` for that user.
|
||||
* `rank` is `1 + (count of users with strictly higher points total)`.
|
||||
|
||||
## Wiring
|
||||
|
||||
`AuthService.getMe(userId)` (`backend/src/modules/auth/auth.service.ts`)
|
||||
loads the `UserEntity` then delegates the rank/points math to
|
||||
`UsersRankService.rankOfUser(manager, userId)`
|
||||
(`backend/src/modules/users/users-rank.service.ts`).
|
||||
|
||||
# `POST /api/v1/auth/change-password`
|
||||
|
||||
Authenticated-only password change. Requires the current password
|
||||
(`mode='self'`); the admin-reset variant lives in a later Job.
|
||||
|
||||
| Field | Type | Constraints |
|
||||
|-----------------------|--------|-----------------------------------------------------------------------------------|
|
||||
| `oldPassword` | string | 1–256 chars. Required when `mode='self'`. |
|
||||
| `newPassword` | string | 1–256 chars; passes `validatePassword` (Argon2 policy) AND must differ from old. |
|
||||
| `confirmNewPassword` | string | Must equal `newPassword` (zod refine → `VALIDATION_FAILED`). |
|
||||
|
||||
Validated by `ChangePasswordDtoSchema` in `backend/src/modules/auth/dto/auth.dto.ts`.
|
||||
|
||||
## Successful response (204)
|
||||
|
||||
No body. The new password hash is persisted inside a `DataSource.transaction`
|
||||
that also revokes every active `refresh_token` row for the user
|
||||
(`revokedAt = now`), forcing the user to re-authenticate on other devices.
|
||||
|
||||
## Error envelope
|
||||
|
||||
| HTTP | `code` | When |
|
||||
|------|---------------------------|----------------------------------------------------------------------------------------|
|
||||
| 400 | `VALIDATION_FAILED` | zod body validation failed. |
|
||||
| 400 | `PASSWORDS_DO_NOT_MATCH` | `newPassword !== confirmNewPassword`. |
|
||||
| 400 | `PASSWORD_POLICY` | New password equals the old, or fails the Argon2 policy (`PASSWORD_MIN_LENGTH`, mixed-case requirement). |
|
||||
| 401 | `UNAUTHORIZED` | No JWT on the request. |
|
||||
| 401 | `INVALID_OLD_PASSWORD` | `argon2.verify(oldPasswordHash, oldPassword)` failed. |
|
||||
|
||||
## Wiring
|
||||
|
||||
`AuthService.changePassword(userId, dto)` runs inside a single
|
||||
`DataSource.transaction`:
|
||||
|
||||
1. Validate `newPassword === confirmNewPassword` → `PASSWORDS_DO_NOT_MATCH`.
|
||||
2. Reject `oldPassword === newPassword` → `PASSWORD_POLICY`.
|
||||
3. `argon2.verify(user.passwordHash, dto.oldPassword)` → `INVALID_OLD_PASSWORD` on miss.
|
||||
4. `validatePassword(dto.newPassword, config)` → rethrown as `PASSWORD_POLICY` on failure.
|
||||
5. Re-hash with Argon2id and `manager.save(user)`.
|
||||
6. UPDATE all `refresh_token` rows for the user where `revokedAt IS NULL`.
|
||||
|
||||
# Key Files
|
||||
|
||||
| File | Responsibility |
|
||||
|------|----------------|
|
||||
| `backend/src/modules/auth/auth.service.ts` | Validates registration policy, applies the limiter, creates users, and mints sessions. |
|
||||
| `backend/src/modules/auth/auth.service.ts` | Validates registration policy, applies the limiter, creates users, mints sessions, exposes `getMe()` and `changePassword()`. |
|
||||
| `backend/src/common/services/registration-rate-limit.service.ts` | Tracks timestamps and enforces the 10-per-minute per-IP limit. |
|
||||
| `backend/src/modules/auth/auth.controller.ts` | Exposes public registration and authentication routes. |
|
||||
| `backend/src/modules/auth/dto/auth.dto.ts` | Validates registration request fields. |
|
||||
| `backend/src/modules/auth/auth.controller.ts` | Exposes public registration and authentication routes plus authenticated `/me` and `/change-password`. |
|
||||
| `backend/src/modules/auth/dto/auth.dto.ts` | Validates registration, login, refresh, `/me`, and `change-password` request fields. |
|
||||
| `backend/src/modules/users/users-rank.service.ts` | Pure provider computing `{ rank, points }` over the `solve` table for a user. |
|
||||
| `backend/src/common/errors/error-codes.ts` | Canonical `ERROR_CODES` (now includes `INVALID_OLD_PASSWORD`, `PASSWORD_POLICY`, `PASSWORDS_DO_NOT_MATCH`). |
|
||||
|
||||
# Frontend consumer
|
||||
|
||||
`frontend/src/app/core/services/auth.service.ts` exposes `login()` and
|
||||
`register()`. Both:
|
||||
|
||||
1. Call `ensureCsrf()` → `GET /api/v1/auth/csrf` to materialise the `csrf`
|
||||
cookie if it isn't set yet.
|
||||
2. `POST` with `{ withCredentials: true, observe: 'response' }`.
|
||||
3. Return success or the standard [error envelope](/api/rest-overview.md).
|
||||
|
||||
The `LandingComponent` consumes both methods and maps failures to user-facing
|
||||
copy (see [Landing Page](/guides/landing-page.md)).
|
||||
`frontend/src/app/core/services/auth.service.ts` exposes `login()`,
|
||||
`register()`, `me()`, `changePassword()`, `logout()`, and
|
||||
`restoreSession()`. Each writes through the existing CSRF + auth
|
||||
interceptors and returns a discriminated result type (`LoginResult`,
|
||||
`RegisterResult`, `ChangePasswordResult`) for component-level error
|
||||
handling. The authenticated shell's
|
||||
[change-password modal](/guides/change-password.md) consumes
|
||||
`changePassword()` and maps failures via
|
||||
`formatChangePasswordError()` in
|
||||
`frontend/src/app/features/shell/change-password/password-feedback.ts`.
|
||||
|
||||
# Examples
|
||||
|
||||
@@ -96,8 +174,18 @@ copy (see [Landing Page](/guides/landing-page.md)).
|
||||
4. The first 10 attempts are processed normally; the 11th within 60 seconds returns HTTP `429` with code `RATE_LIMITED`.
|
||||
5. After the rolling window expires, a new attempt is accepted if other requirements pass.
|
||||
|
||||
## Tester flow: change-password happy path
|
||||
|
||||
1. Sign in via `/login`.
|
||||
2. Click the username dropdown in the shell header → "Change password".
|
||||
3. Enter the current password, a new password that meets the policy, and the same new password in "Confirm new password".
|
||||
4. Click **OK**. The modal closes and the success indicator (modal closes) is visible.
|
||||
5. The user's existing refresh tokens have been revoked, so a `refresh` from any other tab will return 401 and that tab will be sent to `/login` on the next guard tick.
|
||||
|
||||
# See also
|
||||
|
||||
- [REST API Overview](/api/rest-overview.md)
|
||||
- [Setup Endpoint](/api/setup.md)
|
||||
- [Landing Page Guide](/guides/landing-page.md)
|
||||
- [Authenticated Shell Guide](/guides/authenticated-shell.md)
|
||||
- [Change Password Guide](/guides/change-password.md)
|
||||
|
||||
Reference in New Issue
Block a user