17 Commits

Author SHA1 Message Date
Cedric 0876eecf50 ci: improve dev pipeline with Dokploy webhook and Docker layer caching 2026-05-10 21:27:28 +02:00
Cedric 5549691d50 ci: test pipeline 2026-05-10 21:24:18 +02:00
Cedric 46c8df45d6 ci: test pipeline 2026-05-10 21:24:10 +02:00
Cedric 50d274f36a chore: resolve merge conflicts, keep Spring Boot 4.0.6 version
Kept our version over remote (security hardening PR #12) for all conflicts:
- pom.xml: Spring Boot 4.0.6 vs 3.4.1, new test deps
- SecurityConfig: new csrf/package API for SB4
- GlobalExceptionHandler: full handler set with SLF4J logging
- AppUserController/ExpenseListController: clean delegation to GlobalExceptionHandler
- Test files: SB4 package paths, extra test coverage

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-10 20:29:49 +02:00
Cedric ba4f365f06 chore: merge feature/security-hardening into main
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-10 20:25:12 +02:00
Cedric a5e5824a44 docs: write recent changes section 2026-05-10 20:18:58 +02:00
Cedric 7189e4fb08 docs: write error handling section 2026-05-10 20:18:28 +02:00
Cedric 2782823c3d docs: write data models section 2026-05-10 20:17:55 +02:00
Cedric ddf64305a5 docs: write expense lists endpoint section 2026-05-10 20:17:22 +02:00
Cedric 2b84ed0de8 docs: write home and users endpoint sections 2026-05-10 20:14:22 +02:00
Cedric 18e740bb73 docs: write rate limiting section 2026-05-10 20:13:58 +02:00
Cedric 9b93cd97a6 docs: write authentication section 2026-05-09 23:56:14 +02:00
Cedric 8fb1820bc7 docs: write API overview section 2026-05-09 23:50:42 +02:00
Cedric 9c35bb8435 docs: scaffold API.md with section headings 2026-05-09 23:49:56 +02:00
Cedric 19c7e1915f security hardening (#12)
Reviewed-on: #12
Co-authored-by: Cedric Hornberger <ceddi.hornberger@gmx.de>
Co-committed-by: Cedric Hornberger <ceddi.hornberger@gmx.de>
2026-05-05 17:13:53 +02:00
Cedric 229a6a8a43 docker-compose.yml aktualisiert 2026-03-04 15:16:11 +01:00
Cedric 76e878ff5c docker-compose.yml aktualisiert 2026-02-04 20:25:38 +01:00
2 changed files with 734 additions and 28 deletions
+30 -28
View File
@@ -12,43 +12,45 @@ jobs:
steps: steps:
# 1. Checkout the code # 1. Checkout the code
- name: Checkout code - name: Checkout code
uses: actions/checkout@v2 uses: actions/checkout@v4
# 2. Set up Java and Maven # 2. Set up Java and Maven (includes Maven, no separate install needed)
- name: Set up JDK (Eclipse Temurin) - name: Set up JDK (Eclipse Temurin)
uses: actions/setup-java@v3 uses: actions/setup-java@v4
with: with:
distribution: "temurin" distribution: "temurin"
java-version: "17" java-version: "17"
cache: maven cache: maven
# 3. Verify Maven installation # 3. Build the Spring Boot application
- name: Install Maven
run: |
sudo apt-get update
sudo apt-get install -y maven
mvn -version
# 4. Build the Spring Boot application
- name: Build Spring Boot Application - name: Build Spring Boot Application
run: | run: mvn clean package -DskipTests
mvn clean package -DskipTests
# 5. Set up Docker # 4. Set up Docker Buildx (enables layer caching)
- name: Set up Docker - name: Set up Docker Buildx
run: | uses: docker/setup-buildx-action@v3
docker --version
# 6. Build the Docker image # 5. Docker login
- name: Build and Package Docker Image
run: |
docker build -t tea.zendric.de/cedric/xpensely-server:latest .
# 7. Docker login
- name: Login to Docker Registry - name: Login to Docker Registry
uses: docker/login-action@v3
with:
registry: tea.zendric.de
username: ${{ secrets.TEAUSER }}
password: ${{ secrets.TEAPASSWORD }}
# 6. Build and push Docker image with layer caching
- name: Build and Push Docker Image
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: tea.zendric.de/cedric/xpensely-server:latest
cache-from: type=registry,ref=tea.zendric.de/cedric/xpensely-server:buildcache
cache-to: type=registry,ref=tea.zendric.de/cedric/xpensely-server:buildcache,mode=max
# 7. Trigger Dokploy to redeploy the dev server automatically
- name: Trigger Dokploy Redeploy
run: | run: |
echo "${{ secrets.TEAPASSWORD }}" | docker login tea.zendric.de -u ${{ secrets.TEAUSER }} --password-stdin curl -X POST "${{ secrets.DOKPLOY_WEBHOOK_URL }}" \
# 8. Push Docker image -H "Authorization: Bearer ${{ secrets.DOKPLOY_TOKEN }}" \
- name: Push the Docker Image to registry --fail
run: |
docker push tea.zendric.de/cedric/xpensely-server:latest
+704
View File
@@ -0,0 +1,704 @@
# Xpensely Server — API Reference
> Last updated: 2026-05-09 · Branch: `feature/security-hardening`
## Table of Contents
1. [Overview](#1-overview)
2. [Authentication](#2-authentication)
3. [Rate Limiting](#3-rate-limiting)
4. [Endpoints](#4-endpoints)
- 4.1 [Home](#41-home)
- 4.2 [Users](#42-users)
- 4.3 [Expense Lists](#43-expense-lists)
5. [Data Models](#5-data-models)
6. [Error Handling](#6-error-handling)
7. [Recent Changes — `feature/security-hardening`](#7-recent-changes)
---
## 1. Overview
Xpensely Server is a Spring Boot REST API that manages shared expense lists for pairs of users. It uses Google OAuth2 JWT tokens for authentication. All protected endpoints require a valid Bearer token in the `Authorization` header.
**Base URL (local dev):** `http://localhost:8080`
**Content-Type:** `application/json` for all request and response bodies.
**Public endpoints (no auth required):**
| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Health check — returns `"Welcome"` |
| POST | `/api/users/createUser` | Register a new user |
| GET | `/api/users/byName` | Look up a user by username |
All other endpoints require authentication (see [Section 2](#2-authentication)).
## 2. Authentication
The server uses **OAuth2 Resource Server** authentication with **Google ID JWT tokens**.
### How it works
1. The client authenticates with Google and receives a Google ID JWT.
2. Every protected API request must include this token in the header:
```
Authorization: Bearer <google-id-jwt>
```
3. The server validates the JWT signature and extracts the `sub` claim (Google User ID).
4. The `sub` value is used to look up the registered `AppUser` in the database via `AuthenticatedUserResolver`.
5. If no `AppUser` exists for that Google ID, the request is rejected with **403 Forbidden**.
### Test profile
When the application runs under the `test` Spring profile (`-Dspring.profiles.active=test`), **all security is disabled** — every endpoint is accessible without a token. This is used for automated tests only.
### User registration flow
Before a user can call any protected endpoint they must first be registered:
1. Authenticate with Google to obtain a Google ID JWT.
2. Call `POST /api/users/createUser` with the JWT's `sub` value as `googleId` and a chosen `username`.
3. All subsequent protected calls use the same JWT — the server resolves the caller automatically.
## 3. Rate Limiting
All requests pass through a `RateLimitFilter` (implemented with **Bucket4j**).
| Setting | Value |
|---------|-------|
| Limit | 60 requests per minute |
| Window | Rolling 1-minute bucket |
| Key (authenticated) | JWT `sub` claim (Google User ID) |
| Key (unauthenticated) | `X-Forwarded-For` header, falling back to remote IP |
When the limit is exceeded the server responds with:
```
HTTP 429 Too Many Requests
```
No `Retry-After` header is currently returned. Clients should back off and retry after 60 seconds.
> **Note:** Rate limiting applies in the `!test` profile only. Tests run without rate limiting.
## 4. Endpoints
### 4.1 Home
#### `GET /`
Health check. No authentication required.
**Response:** `200 OK`
```
Welcome
```
---
### 4.2 Users
Base path: `/api/users`
---
#### `POST /api/users/createUser` — Register a user
**Auth required:** No
**Request body:**
```json
{
"username": "alice",
"googleId": "118400012345678901234"
}
```
| Field | Type | Constraints |
|-------|------|-------------|
| `username` | String | Required. 330 chars. Pattern: `^[a-zA-Z0-9_.\-]+$` |
| `googleId` | String | Required. Non-blank. Must match the JWT `sub` from Google. |
**Success response:** `200 OK` — returns the created [AppUser](#appuser) object.
**Error responses:**
| Status | Condition |
|--------|-----------|
| 400 | Validation failure (field errors returned as `{"fieldName": "message"}`) |
| 409 | `username` already taken |
---
#### `GET /api/users` — Get user by ID
**Auth required:** Yes
**Query params:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | Long | Yes | Database ID of the user |
**Success response:** `200 OK` — returns [AppUser](#appuser).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 404 | No user found for `id` |
---
#### `GET /api/users/byName` — Get user by username
**Auth required:** No
**Query params:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | String | Yes | Exact username (case-sensitive) |
**Success response:** `200 OK` — returns [AppUser](#appuser).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 404 | No user found for `username` |
---
#### `GET /api/users/byGoogleId` — Get user by Google ID
**Auth required:** Yes
**Query params:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | String | Yes | Google `sub` claim |
**Success response:** `200 OK` — returns [AppUser](#appuser).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 404 | No user found for that Google ID |
---
#### `DELETE /api/users` — Delete a user
**Auth required:** Yes
**Query params:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | Long | Yes | Database ID of the user to delete |
**Success response:** `200 OK` — returns the deleted [AppUser](#appuser).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 404 | No user found for `id` |
---
### 4.3 Expense Lists
Base path: `/api/expenselist`
All endpoints in this group require authentication. The authenticated caller is resolved from the JWT and used for ownership checks.
---
#### `GET /api/expenselist/mine` — Get caller's expense lists
Returns all expense lists where the caller is the owner **or** has been shared the list.
**Auth required:** Yes
**Request body:** None
**Success response:** `200 OK` — array of [ExpenseList](#expenselist).
```json
[
{
"id": 1,
"name": "Holiday Trip",
"inviteCode": null,
"owner": { "id": 1, "username": "alice" },
"sharedWith": null,
"expenses": [],
"customCategories": []
}
]
```
---
#### `GET /api/expenselist/byId` — Get expense list by ID
**Auth required:** Yes
**Query params:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | Long | Yes | Expense list database ID |
The caller must be the owner or the shared user of the list.
**Success response:** `200 OK` — returns [ExpenseList](#expenselist).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 403 | Caller is neither owner nor shared user |
| 404 | No list found for `id` |
---
#### `POST /api/expenselist/create` — Create an expense list
**Auth required:** Yes
**Request body:**
```json
{
"name": "Road Trip 2026"
}
```
| Field | Type | Constraints |
|-------|------|-------------|
| `name` | String | Required. Max 100 chars. |
The authenticated caller becomes the `owner` of the new list. The list is initialised with the default Xpensely standard categories.
**Success response:** `201 Created` — returns the created [ExpenseList](#expenselist).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 400 | Validation failure |
---
#### `DELETE /api/expenselist/{id}` — Delete an expense list
**Auth required:** Yes
**Path params:**
| Param | Type | Description |
|-------|------|-------------|
| `id` | Long | Expense list database ID |
Only the **owner** may delete a list. Deleting a list cascades to all its expenses and custom categories.
**Success response:** `204 No Content`
**Error responses:**
| Status | Condition |
|--------|-----------|
| 403 | Caller is not the owner |
| 404 | No list found for `id` |
---
#### `POST /api/expenselist/{id}/add` — Add an expense to a list
**Auth required:** Yes
**Path params:**
| Param | Type | Description |
|-------|------|-------------|
| `id` | Long | Expense list database ID |
**Request body:**
```json
{
"title": "Dinner",
"owner": "alice",
"amount": 42.50,
"personalUseAmount": 21.25,
"otherPersonAmount": 21.25,
"date": "2026-05-09",
"category": "Food"
}
```
| Field | Type | Constraints |
|-------|------|-------------|
| `title` | String | Required. Max 100 chars. |
| `owner` | String | Required. Username of the person who paid. |
| `amount` | Double | Required. Min 0.01. |
| `personalUseAmount` | Double | Optional. Caller's share. |
| `otherPersonAmount` | Double | Optional. Other person's share. |
| `date` | String (ISO-8601) | Required. Format: `YYYY-MM-DD`. |
| `category` | String | Required. Non-blank category name. |
**Success response:** `200 OK` — returns the created [Expense](#expense).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 400 | Validation failure |
| 403 | Caller is not a member (owner or sharedWith) of the list |
| 404 | List not found |
---
#### `PUT /api/expenselist/{id}/update` — Update an expense
**Auth required:** Yes
**Path params:**
| Param | Type | Description |
|-------|------|-------------|
| `id` | Long | Expense list database ID |
**Request body:**
```json
{
"id": 7,
"title": "Dinner (updated)",
"ownerName": "alice",
"amount": 50.00,
"personalUseAmount": 25.00,
"otherPersonAmount": 25.00,
"date": "2026-05-09",
"category": "Food"
}
```
| Field | Type | Constraints |
|-------|------|-------------|
| `id` | Long | Required. ID of the expense to update. |
| `title` | String | Required. Max 100 chars. |
| `ownerName` | String | Required. Username of the payer. |
| `amount` | Double | Required. Min 0.01. |
| `personalUseAmount` | Double | Optional. |
| `otherPersonAmount` | Double | Optional. |
| `date` | String (ISO-8601) | Required. `YYYY-MM-DD`. |
| `category` | String | Required. |
Caller must be a member of the list. Expense must belong to the specified list.
**Success response:** `200 OK` — returns the updated [Expense](#expense).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 400 | Validation failure or expense does not belong to this list |
| 403 | Caller is not a member of the list |
| 404 | List or expense not found |
---
#### `DELETE /api/expenselist/{id}/delete` — Remove an expense from a list
**Auth required:** Yes
**Path params:**
| Param | Type | Description |
|-------|------|-------------|
| `id` | Long | Expense list database ID |
**Query params:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `expenseId` | Long | Yes | ID of the expense to remove |
Caller must be a member of the list.
**Success response:** `200 OK` — returns the deleted [Expense](#expense).
**Error responses:**
| Status | Condition |
|--------|-----------|
| 403 | Caller is not a member of the list |
| 404 | List or expense not found |
---
#### `POST /api/expenselist/{listId}/invite` — Generate an invite code
Generates (or refreshes) a 6-character uppercase invite code for the list, valid for **1 week**.
**Auth required:** Yes
**Path params:**
| Param | Type | Description |
|-------|------|-------------|
| `listId` | Long | Expense list database ID |
Caller must be the **owner** of the list.
**Success response:** `200 OK` — returns the invite code as a plain string.
```
AB3X7Q
```
**Error responses:**
| Status | Condition |
|--------|-----------|
| 403 | Caller is not the owner |
| 404 | List not found |
---
#### `POST /api/expenselist/accept-invite` — Accept an invite
Joins the caller to a shared expense list using an invite code.
**Auth required:** Yes
**Request body:**
```json
{
"inviteCode": "AB3X7Q"
}
```
| Field | Type | Constraints |
|-------|------|-------------|
| `inviteCode` | String | Required. Exactly 6 characters. |
**Success response:** `200 OK` — returns the [ExpenseList](#expenselist) the caller joined.
**Error responses:**
| Status | Condition |
|--------|-----------|
| 400 | Validation failure or invite code not found / expired |
| 403 | Caller is already the owner of this list |
---
## 5. Data Models
### AppUser
Returned by all `/api/users` endpoints. Sensitive fields (`googleId`, `createdAt`) are hidden from API responses via `@JsonIgnore`.
```json
{
"id": 1,
"username": "alice"
}
```
| Field | Type | Notes |
|-------|------|-------|
| `id` | Long | Auto-generated primary key |
| `username` | String | Unique. 330 chars. |
---
### ExpenseList
```json
{
"id": 1,
"name": "Road Trip",
"inviteCode": "AB3X7Q",
"owner": { "id": 1, "username": "alice" },
"sharedWith": { "id": 2, "username": "bob" },
"xpenselyStandardCategories": {
"id": 1,
"categories": [
{ "id": 1, "name": "Food", "colorCode": "#FF5733" }
]
},
"customCategories": [],
"expenses": []
}
```
| Field | Type | Notes |
|-------|------|-------|
| `id` | Long | Auto-generated primary key |
| `name` | String | Display name of the list |
| `inviteCode` | String \| null | 6-char code; `null` if not yet generated or expired |
| `owner` | AppUser | User who created the list |
| `sharedWith` | AppUser \| null | Second member of the list; `null` until an invite is accepted |
| `xpenselyStandardCategories` | XpenselyStandardCategories | Default category set assigned at creation |
| `customCategories` | XpenselyCustomCategory[] | User-defined categories, ordered A→Z |
| `expenses` | Expense[] | All expenses, ordered by date ASC then id ASC |
> `inviteCodeExpiration` is hidden from API responses (`@JsonIgnore`).
---
### Expense
```json
{
"id": 7,
"title": "Dinner",
"owner": { "id": 1, "username": "alice" },
"amount": 42.50,
"personalUseAmount": 21.25,
"otherPersonAmount": 21.25,
"category": "Food",
"date": "2026-05-09"
}
```
| Field | Type | Notes |
|-------|------|-------|
| `id` | Long | Auto-generated |
| `title` | String | Description of the expense |
| `owner` | AppUser | Who paid |
| `amount` | Double | Total amount. Min 0.01. |
| `personalUseAmount` | Double \| null | Caller's share |
| `otherPersonAmount` | Double \| null | Other member's share |
| `category` | String | Category name (free text — must match a category on the list) |
| `date` | String (ISO-8601) | `YYYY-MM-DD` |
> The `expenseList` back-reference is excluded via `@JsonBackReference` to prevent circular serialisation.
---
### XpenselyStandardCategories
A named group of standard categories assigned to every new expense list.
```json
{
"id": 1,
"categories": [
{ "id": 1, "name": "Food", "colorCode": "#FF5733" },
{ "id": 2, "name": "Transport", "colorCode": "#3498DB" }
]
}
```
---
### XpenselyCustomCategory
A user-defined category attached to a specific expense list.
```json
{
"id": 5,
"name": "Souvenirs",
"colorCode": "#9B59B6"
}
```
| Field | Type | Notes |
|-------|------|-------|
| `id` | Long | Auto-generated |
| `name` | String | Category label |
| `colorCode` | String | 7-char hex string e.g. `#RRGGBB` |
> The `expenseList` back-reference is excluded via `@JsonBackReference`.
## 6. Error Handling
All errors are returned as JSON. The `GlobalExceptionHandler` (`@RestControllerAdvice`) maps exceptions to HTTP status codes consistently across every endpoint.
### Error response format
Most errors:
```json
{
"error": "Human-readable message"
}
```
Validation errors (`400`):
```json
{
"username": "size must be between 3 and 30",
"googleId": "must not be blank"
}
```
### Status code reference
| HTTP Status | Condition | Source |
|-------------|-----------|--------|
| 400 Bad Request | Input validation failed (missing/invalid fields) | `MethodArgumentNotValidException` via `@Valid` |
| 400 Bad Request | Business rule violation (e.g. expense not in this list) | `IllegalArgumentException` |
| 403 Forbidden | User not registered in the system | `AuthenticatedUserResolver``ResponseStatusException(FORBIDDEN)` |
| 403 Forbidden | Ownership check failed (e.g. deleting someone else's list) | `ResponseStatusException(FORBIDDEN)` in controller |
| 404 Not Found | Entity does not exist (user, list, expense) | `ResourceNotFoundException` |
| 409 Conflict | Username already taken | `UsernameAlreadyExistsException` |
| 429 Too Many Requests | Rate limit exceeded | `RateLimitFilter` (returned directly, not via exception handler) |
| 500 Internal Server Error | Unexpected runtime or generic exception | `RuntimeException` / `Exception` — message is hidden from client |
## 7. Recent Changes — `feature/security-hardening`
This section summarises API-visible changes introduced on the `feature/security-hardening` branch (commits `3d456f2``b1324e3``8b96433``f0de751`). A developer or agent reading this document should be aware of these differences compared to the `main` branch.
---
### New: Centralised error handling (`GlobalExceptionHandler`)
**File:** `src/main/java/.../controller/GlobalExceptionHandler.java`
All error responses now follow the consistent JSON shape described in [Section 6](#6-error-handling). Previously, individual controllers returned ad-hoc responses, including HTTP 417 and raw stack trace output. Both have been removed. SLF4J logging has been added for server-side error visibility.
---
### New: `AuthenticatedUserResolver`
**File:** `src/main/java/.../security/AuthenticatedUserResolver.java`
A new component that extracts the Google ID from the JWT `sub` claim and resolves the corresponding `AppUser`. Injected into all protected controller methods. Returns `403 Forbidden` if the token is valid but the user has never called `POST /api/users/createUser`.
---
### New: `RateLimitFilter` — 60 req/min
**File:** `src/main/java/.../security/RateLimitFilter.java`
Rate limiting was not present on `main`. See [Section 3](#3-rate-limiting) for full details.
---
### New: `CreateExpenseListRequest` DTO with validation
**File:** `src/main/java/.../model/CreateExpenseListRequest.java`
`POST /api/expenselist/create` previously accepted a raw `ExpenseList` body. It now requires a `CreateExpenseListRequest` with a single validated `name` field (`@NotBlank`, `@Size(max=100)`). Clients must update their request body shape.
---
### Updated: Validation constraints tightened on existing DTOs
| DTO | Field | Change |
|-----|-------|--------|
| `AppUserCreateRequest` | `username` | Added `@Pattern(regexp="^[a-zA-Z0-9_.\-]+$")` — special characters (other than `_`, `.`, `-`) now rejected |
| `InviteRequest` | `inviteCode` | Added `@Size(min=6, max=6)` — non-6-char codes now rejected at binding |
| `ExpenseInput` | `amount` | Added `@DecimalMin("0.01")` — zero and negative amounts now rejected |
| `ExpenseChangeRequest` | `amount` | Added `@DecimalMin("0.01")` — zero and negative amounts now rejected |
---
### Updated: `SecurityConfig` — test-profile isolation
**File:** `src/main/java/.../security/SecurityConfig.java`
Two separate `SecurityFilterChain` beans now exist:
- `@Profile("test")` — all endpoints permitted, CSRF disabled (for automated tests only).
- `@Profile("!test")` — full JWT/OAuth2 enforcement (production behaviour).
Previously a single config was used for both, which made tests fragile.
---
### Fixed: `ExpenseListService` — JPQL and exception consistency
- Single `@Param` used in all JPQL queries (multi-param variant was broken).
- `ResourceNotFoundException` is now thrown consistently instead of returning `null` or a generic `RuntimeException`.
- `addExpenseToList` delegates directly to `ExpenseList.addExpense()` rather than looping.
---
### Fixed: `UserService` — null returns replaced with exceptions
All not-found paths in `UserService` now throw `ResourceNotFoundException` instead of returning `null`. Callers that previously needed to null-check responses will now receive a `404` response.