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