Initial commit: Captcha Service v1.0.0

2026-08-28 10:15:33 +08:00
commit 5d0c5739ad
4 changed files with 502 additions and 0 deletions
@@ -0,0 +1,85 @@
+# 🔢 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).