captcha-service/README.md

🔢 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:

VERIFY_CODE_EXPIRE_SECONDS = 120   # code expiry (s)
RATE_LIMIT_SECONDS = 60            # request interval limit (s)
TOKEN_EXPIRE_SECONDS = 300         # token expiry (s)

Run

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.