86 lines
2.2 KiB
Markdown
86 lines
2.2 KiB
Markdown
# 🔢 Captcha Service — Verification Code Generation & Verification
|
|
|
|
> A Flask captcha/verification-code service with cookie binding, token flow, rate limiting, and code expiry.
|
|
|
|
**Captcha Service** implements a complete verification-code (captcha) flow: issue a code bound to a client cookie, verify it, and issue a short-lived token for further authorization. Includes rate limiting and expiry for security.
|
|
|
|
---
|
|
|
|
## ✨ Features
|
|
|
|
| Feature | Description |
|
|
|---------|-------------|
|
|
| 🍪 **Cookie Binding** | Codes are bound to client cookies & IP |
|
|
| 🔢 **Code Generation** | Generates verification codes with configurable expiry (default 120s) |
|
|
| 🔑 **Token Flow** | Issues short-lived tokens (default 300s) after code verification |
|
|
| ⏱️ **Rate Limiting** | Prevents spam (default 60s between requests) |
|
|
| 🏥 **Health Check** | `/health` endpoint for monitoring |
|
|
|
|
---
|
|
|
|
## 🔌 API Endpoints
|
|
|
|
### POST `/apply`
|
|
Apply for a captcha (obtain a code).
|
|
- **Params**: client cookie / info
|
|
- **Returns**: captcha code & cookie binding
|
|
|
|
### POST `/request_code`
|
|
Request a verification code.
|
|
- **Params**: cookie / IP / target
|
|
- **Returns**: code (subject to rate limit)
|
|
|
|
### POST `/verify`
|
|
Verify a code.
|
|
- **Params**: cookie, code
|
|
- **Returns**: success / failure
|
|
|
|
### POST `/check_token`
|
|
Validate an issued token.
|
|
- **Params**: token
|
|
- **Returns**: token validity + bound info
|
|
|
|
### GET `/health`
|
|
Health check.
|
|
- **Returns**: `{status: ok}`
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Python 3.7+
|
|
- `flask`
|
|
|
|
### Configure
|
|
|
|
Edit the config section in `captcha_service.py`:
|
|
```python
|
|
VERIFY_CODE_EXPIRE_SECONDS = 120 # code expiry (s)
|
|
RATE_LIMIT_SECONDS = 60 # request interval limit (s)
|
|
TOKEN_EXPIRE_SECONDS = 300 # token expiry (s)
|
|
```
|
|
|
|
### Run
|
|
|
|
```bash
|
|
python captcha_service.py
|
|
```
|
|
|
|
---
|
|
|
|
## 🗂️ Storage (in-memory)
|
|
|
|
| Store | Purpose |
|
|
|-------|---------|
|
|
| `COOKIE_STORE` | Tracks cookies → cudid / ip / created_at |
|
|
| `CODE_STORE` | Holds issued codes with expiry & last-request |
|
|
| `TOKEN_STORE` | Holds issued tokens with expiry & usage status |
|
|
| `REQUEST_RECORD` | Rate-limiting record by cookie / IP |
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
Licensed under the **MIT License**. See [LICENSE](LICENSE).
|