Public Access
lobo
3a48ce0ff1
10 failed registrations per IP block it for 15 minutes (429 TOO_MANY_ATTEMPTS with Retry-After). Login and registration now take an attempt before the check, so a burst of parallel requests cannot pass the limit.
113 lines
4.7 KiB
Markdown
113 lines
4.7 KiB
Markdown
# To Be Played – Auth Service
|
||
|
||
Identity service of **To Be Played**, a Steam backlog tracker. It handles registration, login, user settings and the
|
||
public profile, and it signs the JWTs that the Core service trusts.
|
||
|
||
To Be Played is split into three repositories:
|
||
|
||
| Repository | Role |
|
||
|---|---|
|
||
| **ToBePlayed-Auth** (this one) | Users, login, settings, signs JWTs |
|
||
| ToBePlayed-Core | Steam library, backlog, wishlist, stats; verifies JWTs |
|
||
| ToBePlayed-Frontend | React single-page app |
|
||
|
||
## Features
|
||
|
||
- Registration with an invitation code, login with email and password (BCrypt).
|
||
- Brute-force protection in memory: 5 failed logins per email or 20 per IP, and 10 failed registrations per IP,
|
||
block for 15 minutes with `429 TOO_MANY_ATTEMPTS` and `Retry-After`. Unknown emails cost the same BCrypt time as a
|
||
wrong password, and every failed login gets the same error.
|
||
- JWT signed with **EdDSA (Ed25519)**. Auth holds the private key, Core only the public key, so Core can verify
|
||
tokens but never create them. Tokens carry a `kid` header for key rotation.
|
||
- User settings: display name (unique, case-insensitive), Steam ID, language, dark mode.
|
||
- Appearance settings synced across devices: accent color, corner style, wide layout, background and dashboard
|
||
banner from the user's own game art. Only whitelisted presets and Steam app ids are stored, never raw CSS or URLs.
|
||
- Opt-in public profile at `/u/<display name>`. Auth answers with a short-lived **profile ticket** (EdDSA JWT,
|
||
10 minutes, `typ=public-profile`) that Core accepts for the public library data only. The ticket is not a login:
|
||
both services reject every token with a `typ` claim on normal endpoints.
|
||
|
||
## API
|
||
|
||
| Method | Path | Auth |
|
||
|---|---|---|
|
||
| `POST` | `/api/registration/new` | public |
|
||
| `POST` | `/api/auth/login` | public |
|
||
| `GET` | `/api/users/me` | JWT |
|
||
| `PUT` | `/api/users/settings` | JWT |
|
||
| `PUT` | `/api/users/settings/appearance` | JWT |
|
||
| `GET` | `/api/public/profiles/{displayName}` | public |
|
||
| `GET` | `/api/stats/public` | public |
|
||
|
||
Endpoints use Spring's API versioning with a query parameter: `?version=1.0` (default `1.0`).
|
||
|
||
## Tech stack
|
||
|
||
- Java 25, Spring Boot 4.1 (Web MVC, Security, Data JPA, Validation, Cache with Caffeine), virtual threads
|
||
- PostgreSQL 17, Flyway migrations
|
||
- JJWT with Ed25519 keys
|
||
- Spring Boot Actuator + Micrometer (Prometheus)
|
||
- Tests: JUnit 5, Testcontainers (PostgreSQL), ArchUnit
|
||
- CI: Forgejo Actions, multi-stage Docker image
|
||
|
||
## Architecture
|
||
|
||
Package by feature (`modules/login`, `modules/registration`, `modules/user`, ...), and inside each feature three
|
||
layers:
|
||
|
||
| Layer | Package | Rule |
|
||
|---|---|---|
|
||
| API | `api` | REST controllers, request/response records, `ApiMapper`. Calls services, never repositories. |
|
||
| Domain | `model`, `service`, `exception` | Plain Java models and business logic. No dependency on API or persistence. |
|
||
| Persistence | `persistence` | JPA entities, Spring Data repositories, `EntityMapper`. Entities never reach the API layer. |
|
||
|
||
ArchUnit enforces these rules in `src/test/java/auth_service/architecture/ArchitectureTest.java`, so a layer
|
||
violation fails the build. Test base classes (`AbstractUnitTest`, `AbstractWebMvcTest`, `AbstractPersistenceTest`,
|
||
`AbstractIntegrationTest`) live in `auth_service.shared.test`; all integration tests share one PostgreSQL container.
|
||
|
||
## Run locally
|
||
|
||
Needs Java 25 and Docker.
|
||
|
||
```bash
|
||
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
|
||
```
|
||
|
||
Spring Boot's Docker Compose support starts PostgreSQL from `compose.yaml`, Flyway applies the migrations, and the
|
||
service listens on `http://localhost:8080`. Health: `/actuator/health`, metrics: `/actuator/prometheus`.
|
||
|
||
Configuration comes from environment variables:
|
||
|
||
| Variable | Purpose |
|
||
|---|---|
|
||
| `JWT_PRIVATE_KEY`, `JWT_PUBLIC_KEY` | Ed25519 keypair, Base64 of the DER bytes (PKCS#8 / X.509) |
|
||
| `JWT_KID` | Key id written into the token header |
|
||
| `AUTH_INVITATION_CODE` | Code required for registration |
|
||
| `DB_PASSWORD` | Local PostgreSQL password |
|
||
|
||
Generate a keypair:
|
||
|
||
```bash
|
||
openssl genpkey -algorithm ed25519 -out private.pem
|
||
openssl pkey -in private.pem -outform DER | base64 -w0 # JWT_PRIVATE_KEY
|
||
openssl pkey -in private.pem -pubout -outform DER | base64 -w0 # JWT_PUBLIC_KEY
|
||
```
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
./mvnw clean verify
|
||
```
|
||
|
||
Runs unit, WebMvc, persistence and integration tests plus the ArchUnit rules. Needs Docker for Testcontainers.
|
||
|
||
## Roadmap
|
||
|
||
- JWKS endpoint (`/.well-known/jwks.json`), so Core fetches the public key and keys rotate without a redeploy.
|
||
- Short-lived access token plus rotating refresh token in an httpOnly cookie, with CSRF protection. Today the token
|
||
lives 24 h in `localStorage` and cannot be revoked.
|
||
- Account deletion and data export.
|
||
|
||
## License
|
||
|
||
All rights reserved. The source is public for reading only.
|