Add TeleWatchdog Cloudflare Worker

README.md

@@ -0,0 +1,165 @@
+# 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.