Skip to content

Commit 5b110bc

Browse files
Fabinatix97Fabinatix97
committed
Update README.md
1 parent 220296d commit 5b110bc

File tree

1 file changed

+312
-39
lines changed

1 file changed

+312
-39
lines changed

‎.github/README.md‎

Lines changed: 312 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,326 @@
1-
<!-- General project links -->
2-
[open-issues]: https://github.com/it-at-m/refarch-templates/issues
3-
[new-issue]: https://github.com/it-at-m/refarch-templates/issues/new/choose
4-
[milestones]: https://github.com/it-at-m/refarch-templates/milestones
5-
[project-board]: https://github.com/orgs/it-at-m/projects/16
6-
[documentation]: https://refarch-templates.oss.muenchen.de/
7-
[contribution-documentation]: https://refarch-templates.oss.muenchen.de/contribute.html
8-
[itm-opensource]: https://opensource.muenchen.de/
9-
[license]: ../LICENSE
10-
[code-of-conduct]: ./CODE_OF_CONDUCT.md
11-
12-
<!-- Project specific links -->
13-
[refarch-documentation]: https://refarch.oss.muenchen.de/
14-
[refarch-code]: https://github.com/it-at-m/refarch
15-
[spring-documentation]: https://spring.io/
16-
[vuejs-documentation]: https://vuejs.org/
17-
[getting-started-documentation]: https://refarch-templates.oss.muenchen.de/getting-started.html
18-
[develop-documentation]: https://refarch-templates.oss.muenchen.de/develop.html
19-
[document-documentation]: https://refarch-templates.oss.muenchen.de/document.html
20-
[organize-documentation]: https://refarch-templates.oss.muenchen.de/organize.html
21-
22-
<!-- Shields.io links -->
23-
[documentation-shield]: https://img.shields.io/badge/documentation-blue?style=for-the-badge
24-
[new-issue-shield]: https://img.shields.io/badge/new%20issue-blue?style=for-the-badge
25-
[made-with-love-shield]: https://img.shields.io/badge/made%20with%20%E2%9D%A4%20by-it%40M-yellow?style=for-the-badge
26-
[license-shield]: https://img.shields.io/github/license/it-at-m/refarch-templates?style=for-the-badge
27-
28-
# RefArch Templates
1+
# CaptchaService
292

303
[![Documentation][documentation-shield]][documentation]
314
[![New issue][new-issue-shield]][new-issue]
325
[![Made with love by it@M][made-with-love-shield]][itm-opensource]
336
[![GitHub license][license-shield]][license]
347

35-
This project acts as a template and provides starter files for web application projects based on the RefArch (reference architecture) of it@M.
8+
A Spring Boot microservice that provides proof-of-work CAPTCHA challenges using the [ALTCHA library](https://altcha.org/). This service offers an alternative to traditional image-based CAPTCHAs with adaptive difficulty management and multi-tenant support.
369

37-
To learn more about the architecture itself, checkout its [documentation][refarch-documentation] or [code][refarch-code].
10+
## Table of Contents
3811

39-
The templates are based on [Spring][spring-documentation] and [Vue.js][vuejs-documentation].
12+
- [Architecture](#architecture)
13+
- [Features](#features)
14+
- [Prerequisites](#prerequisites)
15+
- [Quick Start](#quick-start)
16+
- [Configuration](#configuration)
17+
- [API Documentation](#api-documentation)
18+
- [Database](#database)
19+
- [Monitoring](#monitoring)
20+
- [Contributing](#contributing)
21+
- [License](#license)
22+
- [Contact](#contact)
4023

41-
## Usage
24+
## Architecture
4225

43-
To get set up and learn more about the templates, please check out the [Getting Started][getting-started-documentation] page.
44-
Also check the respective pages with suggestions on how to [develop][develop-documentation], [document][document-documentation] and [organize][organize-documentation] your project.
26+
```mermaid
27+
graph TB
28+
%% External Client
29+
Client
30+
31+
%% External Services
32+
subgraph "External Services"
33+
PostgreSQL[(PostgreSQL<br/>Database)]
34+
end
35+
36+
%% Main CaptchaService Application
37+
subgraph "CaptchaService Application"
4538
46-
## Roadmap
39+
%% Monitoring & Management
40+
subgraph "Monitoring"
41+
Actuator["**Spring Actuator**<br/>/actuator/info<br/>/actuator/health<br/>/actuator/metrics"]
42+
end
4743
48-
See the [open issues][open-issues] for a full list of proposed features (and known issues).
49-
To get a better overview on what's currently being worked on, check out our [project board][project-board].
50-
We often also plan our issues in [milestones][milestones].
44+
%% API Endpoints Detail
45+
subgraph "CaptchaController"
46+
ChallengeEndpoint["**postChallenge()**<br/>Create CAPTCHA Challenge"]
47+
VerifyEndpoint["**postVerify()**<br/>Verify CAPTCHA Solution"]
48+
end
49+
50+
%% Service Layer
51+
subgraph "Service Layer"
52+
CaptchaService["**CaptchaService**<br/>Core CAPTCHA Logic"]
53+
DifficultyService["**DifficultyService**<br/>Adaptive Difficulty Management"]
54+
SiteAuthService["**SiteAuthService**<br/>Site Key/Secret Validation"]
55+
SourceAddressService["**SourceAddressService**<br/>IP Address Validation"]
56+
ExpiredDataService["**ExpiredDataService**<br/>Cleanup Scheduler"]
57+
end
58+
59+
%% Data Layer
60+
subgraph "Data Layer"
61+
CaptchaRequestRepo["**CaptchaRequestRepository**<br/>JPA Repository"]
62+
InvalidatedPayloadRepo["**InvalidatedPayloadRepository**<br/>JPA Repository"]
63+
64+
subgraph "JPA Entities"
65+
CaptchaRequestEntity["**CaptchaRequest**<br/>Entity"]
66+
InvalidatedPayloadEntity["**InvalidatedPayload**<br/>Entity"]
67+
end
68+
end
69+
70+
%% Properties/Configuration
71+
subgraph "Configuration Properties"
72+
CaptchaProperties["**CaptchaProperties**<br/>HMAC Key, Sites Config"]
73+
CaptchaSite["**CaptchaSite**<br/>Site-specific Settings"]
74+
DifficultyItem["**DifficultyItem**<br/>Difficulty Mappings"]
75+
end
76+
end
77+
78+
%% Request Flow
79+
Client --&gt;|POST /api/v1/challenge| ChallengeEndpoint
80+
Client --&gt;|POST /api/v1/verify| VerifyEndpoint
81+
Client --&gt; Monitoring
82+
83+
%% Controller to Services
84+
ChallengeEndpoint --&gt; CaptchaService
85+
VerifyEndpoint --&gt; CaptchaService
86+
ChallengeEndpoint --&gt; SiteAuthService
87+
VerifyEndpoint --&gt; SiteAuthService
88+
ChallengeEndpoint --&gt; SourceAddressService
89+
90+
%% Service Interactions
91+
CaptchaService --&gt; DifficultyService
92+
CaptchaService --&gt; CaptchaRequestRepo
93+
CaptchaService --&gt; InvalidatedPayloadRepo
94+
CaptchaService --&gt; AltchaLib
95+
96+
DifficultyService --&gt; CaptchaRequestRepo
97+
ExpiredDataService --&gt;|Scheduled Cleanup| CaptchaRequestRepo
98+
ExpiredDataService --&gt;|Scheduled Cleanup| InvalidatedPayloadRepo
99+
100+
%% Data Layer
101+
CaptchaRequestRepo --&gt; CaptchaRequestEntity
102+
InvalidatedPayloadRepo --&gt; InvalidatedPayloadEntity
103+
CaptchaRequestEntity -.->|JPA/Hibernate| PostgreSQL
104+
InvalidatedPayloadEntity -.->|JPA/Hibernate| PostgreSQL
105+
106+
%% Configuration Dependencies
107+
CaptchaService -.->|Uses| CaptchaProperties
108+
SiteAuthService -.->|Uses| CaptchaProperties
109+
SourceAddressService -.->|Uses| CaptchaProperties
110+
DifficultyService -.->|Uses| CaptchaProperties
111+
112+
%% Database Migration
113+
Flyway -.->|Schema Management| PostgreSQL
114+
115+
class CaptchaService,DifficultyService,SiteAuthService,SourceAddressService,ExpiredDataService service
116+
class CaptchaRequestRepo,InvalidatedPayloadRepo,CaptchaRequestEntity,InvalidatedPayloadEntity data
117+
class PostgreSQL,Client external
118+
class ChallengeEndpoint,VerifyEndpoint endpoint
119+
class CaptchaProperties,CaptchaSite,DifficultyItem properties
120+
```
121+
122+
## Features
123+
124+
- **Proof-of-Work CAPTCHA**: Uses ALTCHA library for crypto-based challenge verification
125+
- **Adaptive Difficulty**: Automatically adjusts challenge difficulty based on request patterns
126+
- **Multi-Tenant Support**: Site-specific configuration with individual keys and secrets
127+
- **Source Address Validation**: IP-based filtering and network address validation
128+
- **Scheduled Cleanup**: Automatic removal of expired challenges and invalidated payloads
129+
- **Monitoring**: Comprehensive health checks and metrics via Spring Actuator
130+
- **Database Persistence**: PostgreSQL storage with automated Flyway migrations
131+
132+
## Prerequisites
133+
134+
- Java 21 or later
135+
- Maven 3.8+
136+
- PostgreSQL 16+
137+
- Docker and Docker Compose (for local development)
138+
139+
## Quick Start
140+
141+
1. **Clone the repository**
142+
```bash
143+
git clone https://github.com/it-at-m/captchaservice.git
144+
cd captchaservice
145+
```
146+
147+
2. **Start the development stack**
148+
```bash
149+
cd stack
150+
docker compose up -d
151+
```
152+
153+
3. **Build and run the application**
154+
```bash
155+
cd captchaservice-backend
156+
bash runLocal.sh
157+
```
158+
159+
4. **Verify the service is running**
160+
```bash
161+
curl http://localhost:8080/actuator/health
162+
```
163+
164+
## Configuration
165+
166+
### Environment Variables
167+
168+
| Variable | Description | Default |
169+
|----------|-------------|---------|
170+
| `SPRING_DATASOURCE_URL` | PostgreSQL connection URL | `jdbc:postgresql://localhost:5432/captchaservice` |
171+
| `SPRING_DATASOURCE_USERNAME` | Database username | - |
172+
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |
173+
| `CAPTCHA_HMAC_KEY` | HMAC key for challenge signing | - |
174+
| `CAPTCHA_CAPTCHA_TIMEOUT_SECONDS` | Challenge validity period | `300` |
175+
| `CAPTCHA_SOURCE_ADDRESS_WINDOW_SECONDS` | Source address tracking window | `3600` |
176+
177+
### Site Configuration
178+
179+
Configure multiple sites in your `application.yml`:
180+
181+
```yaml
182+
captcha:
183+
hmac-key: secret # HMAC key for signing challenges
184+
captcha-timeout-seconds: 300 # How long a CAPTCHA challenge is valid
185+
source-address-window-seconds: 3600 # How long a source address is stored
186+
sites:
187+
site1: # Site key for site1
188+
site-secret: "secret1" # Site secret for site1
189+
max-verifies-per-payload: 1 # How many times a payload can be verified
190+
whitelisted_source-addresses:
191+
- "192.0.2.0/24" # Whitelisted IP address range
192+
site2:
193+
site-secret: "secret2"
194+
whitelisted_source-addresses:
195+
- "192.0.2.0/24" # Whitelisted IP address range
196+
difficulty-map:
197+
- min-visits: 1 # From the first visit on...
198+
max-number: 1000 # ...the difficulty is 1000
199+
- min-visits: 10 # From the 10th visit on...
200+
max-number: 10000 # ...the difficulty is 10000
201+
```
202+
203+
## API Documentation
204+
205+
### Create Challenge
206+
207+
**POST** `/api/v1/captcha/challenge`
208+
209+
Creates a new CAPTCHA challenge for the specified site.
210+
211+
**Request Body:**
212+
```json
213+
{
214+
"siteKey": "site1",
215+
"siteSecret": "secret1",
216+
"clientAddress": "192.168.1.100"
217+
}
218+
```
219+
220+
**Response:**
221+
```json
222+
{
223+
"algorithm": "SHA-256",
224+
"challenge": "abc123...",
225+
"maxNumber": 1000,
226+
"salt": "def456...",
227+
"signature": "ghi789..."
228+
}
229+
```
230+
231+
### Verify Solution
232+
233+
**POST** `/api/v1/captcha/verify`
234+
235+
Verifies a CAPTCHA solution payload.
236+
237+
**Request Body:**
238+
```json
239+
{
240+
"siteKey": "site1",
241+
"siteSecret": "secret1",
242+
"payload": {
243+
"algorithm": "SHA-256",
244+
"challenge": "abc123...",
245+
"number": 542,
246+
"salt": "def456...",
247+
"signature": "ghi789...",
248+
"took": 4400
249+
}
250+
}
251+
```
252+
253+
**Response:**
254+
```json
255+
{
256+
"valid": true
257+
}
258+
259+
// or if the solution is invalid
260+
261+
{
262+
"valid": false
263+
}
264+
```
265+
266+
### Error Responses
267+
268+
**401 Unauthorized** - Invalid site credentials
269+
```json
270+
{
271+
"status": 401,
272+
"error": "Authentication Error",
273+
}
274+
```
275+
276+
**400 Bad Request** - Invalid request format
277+
```json
278+
{
279+
"status": 400,
280+
"error": "Bad Request"
281+
}
282+
```
283+
284+
## Database
285+
286+
### Schema Management
287+
288+
Database schema is managed using Flyway migrations located in `src/main/resources/db/migration/`
289+
290+
### Manual Migration
291+
292+
```bash
293+
# Run migrations manually
294+
mvn flyway:migrate
295+
296+
# Check migration status
297+
mvn flyway:info
298+
299+
# Validate migrations
300+
mvn flyway:validate
301+
```
302+
303+
## Monitoring
304+
305+
### Health Checks
306+
307+
- **Liveness**: `GET /actuator/health/liveness`
308+
- **Readiness**: `GET /actuator/health/readiness`
309+
- **Overall Health**: `GET /actuator/health`
310+
311+
### Application Information
312+
313+
- **Info Endpoint**: `GET /actuator/info`
314+
- **Metrics**: `GET /actuator/metrics`
315+
316+
### Metrics
317+
318+
Prometheus metrics available at `/actuator/prometheus`:
319+
320+
- Application metrics
321+
- JVM metrics
322+
- Database connection pool metrics
323+
- Custom CAPTCHA metrics
51324

52325
## Contributing
53326

@@ -61,4 +334,4 @@ Distributed under the MIT License. See [LICENSE][license] file for more informat
61334

62335
## Contact
63336

64-
it@M - [email protected]
337+
it@M - [email protected]

0 commit comments

Comments
 (0)