# 🔢 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).