ToBePlayed-Auth/readme.md

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).
• 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.

./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:

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

./mvnw clean verify

Runs unit, WebMvc, persistence and integration tests plus the ArchUnit rules. Needs Docker for Testcontainers.

Roadmap

• Rate limit /api/auth/login and /api/registration/**.
• 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.