166 lines
3.8 KiB
Markdown
166 lines
3.8 KiB
Markdown
# TeleWatchdog
|
|
|
|
TeleWatchdog is a `Cloudflare Workers` Telegram join-request watchdog for private groups.
|
|
|
|
It reviews join requests with a simple pipeline:
|
|
|
|
1. Check whether the applicant has an avatar.
|
|
2. Check whether the applicant has a bio.
|
|
3. If either is missing, require verification.
|
|
4. If both exist, ask an AI model for a binary decision.
|
|
5. If the AI returns `approve`, accept the join request immediately.
|
|
6. Otherwise, send a verification message with a Telegram Web App button.
|
|
|
|
Users who need verification can choose either:
|
|
|
|
- `Cloudflare Turnstile`
|
|
- `Telegram WebApp BiometricManager`
|
|
|
|
If verification is not completed within 10 minutes, a scheduled task declines the request and cleans up the stored state.
|
|
|
|
## Features
|
|
|
|
- Telegram `chat_join_request` webhook support
|
|
- Cloudflare Worker deployment model
|
|
- Telegram Web App verification page
|
|
- Turnstile verification
|
|
- Telegram biometric verification via `BiometricManager`
|
|
- AI-based binary profile review
|
|
- Automatic cleanup of expired verification records
|
|
- Automatic deletion of verification messages after success or timeout
|
|
|
|
## Stack
|
|
|
|
- `Cloudflare Workers`
|
|
- `Cloudflare KV`
|
|
- `Telegram Bot API`
|
|
- `Cloudflare Turnstile`
|
|
- OpenAI-compatible chat completion API
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
src/index.ts Main Worker implementation
|
|
package.json Project metadata and scripts
|
|
tsconfig.json TypeScript config
|
|
wrangler.toml.example Example Wrangler config
|
|
```
|
|
|
|
## Required Secrets
|
|
|
|
Set these with `wrangler secret put`:
|
|
|
|
- `BOT_TOKEN`
|
|
- `TG_WEBHOOK_SECRET`
|
|
- `AI_BASE_URL`
|
|
- `AI_API_KEY`
|
|
- `TURNSTILE_SECRET`
|
|
|
|
## Required Variables
|
|
|
|
Set these in `wrangler.toml`:
|
|
|
|
- `AI_MODEL`
|
|
- `TURNSTILE_SITE_KEY`
|
|
- `VERIFICATION_ORIGIN`
|
|
|
|
## KV Setup
|
|
|
|
Create a KV namespace:
|
|
|
|
```bash
|
|
npx wrangler kv namespace create PENDING_JOINS
|
|
```
|
|
|
|
Copy the returned namespace id into your `wrangler.toml`.
|
|
|
|
## Local Setup
|
|
|
|
```bash
|
|
npm install
|
|
copy wrangler.toml.example wrangler.toml
|
|
```
|
|
|
|
Then edit `wrangler.toml` and add your real values.
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
npx wrangler deploy
|
|
```
|
|
|
|
## Telegram Webhook
|
|
|
|
After deployment, configure the webhook to point to:
|
|
|
|
```text
|
|
https://your-worker-domain/telegram/webhook
|
|
```
|
|
|
|
Example PowerShell:
|
|
|
|
```powershell
|
|
$botToken = "YOUR_BOT_TOKEN"
|
|
$secret = "YOUR_TG_WEBHOOK_SECRET"
|
|
$body = @{
|
|
url = "https://your-worker-domain/telegram/webhook"
|
|
secret_token = $secret
|
|
allowed_updates = @("chat_join_request")
|
|
} | ConvertTo-Json -Compress
|
|
|
|
Invoke-RestMethod -Method Post -Uri "https://api.telegram.org/bot$botToken/setWebhook" -ContentType "application/json" -Body $body
|
|
```
|
|
|
|
## Telegram Permissions
|
|
|
|
The bot must:
|
|
|
|
- be added to the target group
|
|
- be an administrator
|
|
- have permission to approve join requests
|
|
|
|
The group must be configured to require approval for join requests.
|
|
|
|
## Verification Flow
|
|
|
|
### Auto-approve path
|
|
|
|
- user has avatar
|
|
- user has bio
|
|
- AI returns `approve`
|
|
- request is approved immediately
|
|
- no message is sent to the user
|
|
|
|
### Verification path
|
|
|
|
- avatar missing, or
|
|
- bio missing, or
|
|
- AI returns `challenge`, or
|
|
- AI request fails
|
|
|
|
Then:
|
|
|
|
- a single verification message is sent
|
|
- user opens the Telegram Web App
|
|
- user completes Turnstile or biometric verification
|
|
- the bot approves the request
|
|
- the verification message is deleted
|
|
- KV records are deleted
|
|
|
|
### Timeout path
|
|
|
|
- request stays pending for 10 minutes
|
|
- scheduled Worker declines the join request
|
|
- verification message is deleted
|
|
- KV records are deleted
|
|
|
|
## Notes
|
|
|
|
- Telegram biometric verification here uses `Telegram.WebApp.BiometricManager`, not WebAuthn.
|
|
- Telegram Web App `initData` is verified server-side before accepting either verification method.
|
|
- Public repository users should create their own Worker domain, Turnstile site, KV namespace, and AI credentials.
|
|
|
|
## License
|
|
|
|
Add your preferred license before publishing if needed.
|