Merge branch 'main' into bobaivigitalpoint-ui/userapi-1347-1350

Author: nanaf6203-bit

docs/api/auth-caching.md

@@ -0,0 +1,7 @@
+# Auth API Redis caching
+
+`GET /auth/me/dashboard`-style dashboard data (`AuthService.getDashboard`) is cached per user for 30 seconds through `AuthCacheService`, which uses the shared `CacheService` (Redis when configured).
+
+- Key: `auth:dashboard:<userId>`; TTL 30s, so data can be up to 30 seconds stale.
+- Read-through only: cache errors, or no cache being available, fall back to computing the response, so caching can never fail a request.
+- Token, session and API-key checks are deliberately **not** cached, because revocation has to take effect immediately.

docs/api/auth-db-optimization.md

@@ -0,0 +1,7 @@
+# Auth API database query optimisation
+
+Changes in `AuthService`:
+
+- **Refresh-token reuse detection** counted tokens in a family by fetching every row just to log the number; it now uses `count()`.
+- **Logout everywhere** fetched all of a user's blacklisted refresh tokens only for `.length`; it now uses `count()`.
+- **Dashboard** ran a query for the user's ten latest properties whose result was never used (removed), and fetched up to three API key rows to report their number. It now uses `apiKey.count()`, so `apiKeysCount` is the real number of keys rather than being capped at 3.

docs/api/auth-error-handling.md

@@ -0,0 +1,5 @@
+# Auth API error handling
+
+`POST /auth/password-reset/request` no longer fails when the reset email cannot be sent. Previously a mail-provider error propagated as a `500`, which let a caller tell registered addresses (500) from unknown ones (silent success). The failure is now caught and logged (`auth.password_reset_email_failed`, with the user id and a hash of the email, never the address or token), and the response is the same as for an unknown address.
+
+The reset token is still created, so a retry from the user produces a fresh token and email.

docs/api/auth-health.md

@@ -0,0 +1,8 @@
+# Auth API health check
+
+`GET /auth/health` (no authentication) reports whether the Auth API can do its job.
+
+- `200` with `{ status: "up", checkedAt, checks: { database: { status, latencyMs } } }`
+- `503` with the same shape and `status: "down"` when the database check fails or takes longer than 2 seconds.
+
+Only the database is checked because sessions and refresh tokens depend on it. Error details are never returned. This is separate from the platform-wide `/healthz` and `/readyz` probes.

docs/api/auth-injection-hardening.md

@@ -0,0 +1,10 @@
+# Auth API injection hardening
+
+`CredentialInjectionPipe` runs on `POST /auth/register`, `/auth/login` and `/auth/refresh` and answers `400` for:
+
+- object-valued fields (e.g. `{"email": {"$ne": null}}`) and nested objects in arrays,
+- keys starting with `$` or containing `.`,
+- NUL bytes,
+- SQL comment or stacked-statement markers (`--`, `/*`, `; drop ...`) in free-text fields. Password, token and code fields are exempt because they may legitimately contain those characters.
+
+Database access already goes through Prisma's parameterised queries; the pipe rejects hostile input before it reaches the service.

docs/api/auth-input-sanitization.md

@@ -0,0 +1,9 @@
+# Auth API input sanitization
+
+`RegisterDto` and `LoginDto` normalise input through class-transformer (the global `ValidationPipe` already runs with `transform: true`):
+
+- `email`: Unicode NFKC normalisation, control characters removed, surrounding whitespace trimmed. The case is **not** changed, so existing accounts keep matching.
+- `firstName` / `lastName`: additionally strip HTML tags and collapse whitespace.
+- Passwords and tokens are never altered.
+
+Sanitising happens before validation, so `"  user@example.com "` is accepted as `user@example.com` and a name consisting only of tags becomes empty and fails `@IsNotEmpty`. Helpers live in `src/auth/sanitize.util.ts`.

docs/api/auth-metrics.md

@@ -0,0 +1,10 @@
+# Auth API Prometheus metrics
+
+Exposed on the existing `/metrics` endpoint:
+
+| Metric | Type | Labels |
+| --- | --- | --- |
+| `auth_requests_total` | counter | `operation` (controller handler name), `outcome` (`success`, `client_error`, `server_error`) |
+| `auth_request_duration_seconds` | histogram | `operation` |
+
+`AuthMetricsInterceptor` records both for every `AuthController` handler. Labels are bounded (a fixed set of handler names and three outcomes), so cardinality does not grow with user input. Example alert: rate of `auth_requests_total{outcome="server_error"}` above a threshold.

docs/api/auth-openapi.md

@@ -0,0 +1,5 @@
+# Auth API OpenAPI documentation
+
+The main `AuthController` operations now carry `@ApiOperation` summaries and `@ApiResponse` entries (success plus the documented 400/401/404/429 cases) so they appear described in Swagger: register, login, refresh, logout, logout-all, me, change-password, password-reset request/reset and verify-email.
+
+Open the Swagger UI exposed by the app and look under the **Authentication** tag. Protected operations show the `access-token` bearer scheme through the existing `@ApiBearerAuth` decorators.

docs/api/auth-pagination.md

@@ -0,0 +1,7 @@
+# Auth API pagination
+
+`GET /auth/api-keys` accepts `page` (>= 1) and `limit` (1-100, default 20).
+
+- With neither parameter the response is the plain array it has always been, so existing clients are unaffected.
+- With either, the response is `{ data, meta: { page, limit, total, totalPages, hasNext } }`, newest first, with `id` as a tie-breaker so pages are stable.
+- Invalid values (page 0, limit above 100, non-numbers) return `400`.

docs/api/auth-rate-limiting.md

@@ -0,0 +1,14 @@
+# Auth API rate limiting
+
+`AuthRouteRateLimitGuard` + `@AuthRouteLimit({ max, windowMs })` limit sensitive unauthenticated routes per client address (hashed before storage). Each client has its own counter per route, so one abusive client cannot lock out everyone else.
+
+| Route | Limit |
+| --- | --- |
+| `POST /auth/register` | 5 per hour |
+| `POST /auth/refresh` | 30 per 15 min |
+| `POST /auth/password-reset/request` | 5 per hour |
+| `POST /auth/password-reset/reset` | 10 per hour |
+| `POST /auth/verify-email` | 10 per 15 min |
+| `POST /auth/email/resend` | 3 per hour |
+
+Over the limit the response is `429` with a `Retry-After` header. Login keeps its existing account/IP lockout (`LoginRateLimitService`). Note: the `ENDPOINT_RATE_LIMITS` table is a single bucket shared by all clients, so it was not used here.