feat: refactor Telegram whitelist logic and add comprehensive test coverage

rezhajulio · rezhajulio · commit 24b40475c3d3 · 2026-01-07T01:14:38.000+07:00
- Extract Telegram path/username whitelisting into separate WHITELISTED_TELEGRAM_PATHS constant
  - Separate domain-based (t.me domain) from path-based (channel username) whitelisting
  - Enable more granular control over allowed Telegram channels for new user probation

- Improve is_url_whitelisted() function in anti_spam.py
  - Add explicit handling for t.me and telegram.me hosts with path-based validation
  - Case-insensitive path matching for Telegram channel names
  - Reject root paths (/) and empty paths

- Add comprehensive pytest coverage for URL whitelist validation
  - 48 test cases covering 487 lines of test code
  - Increases anti_spam.py coverage from 35% to 54%
  - Test categories:
    * Telegram link validation (protocols, message links, case sensitivity, ports)
    * Domain whitelist coverage (GitHub, documentation, AI/ML, cloud, package repos)
    * URL parsing edge cases (query parameters, fragments, special characters)
    * Helper function coverage (is_forwarded, has_link, extract_urls, etc.)

- Add AGENTS.md documenting project structure and development workflow
- Update .gitignore to track AGENTS.md
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,4 @@ __pycache__/
 .pytest_cache/
 data/
 .vscode
-AGENTS.md
+# AGENTS.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,52 @@
+# AGENTS.md - PythonID Telegram Bot
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_check.py
+
+# Run a single test function
+uv run pytest tests/test_check.py::TestHandleCheckCommand::test_check_command_non_admin
+
+# Run tests with coverage
+uv run pytest --cov=bot --cov-report=term-missing
+
+# Run the bot
+uv run pythonid-bot
+```
+
+## Architecture
+
+- **src/bot/**: Main application package
+  - **main.py**: Entry point with JobQueue integration — register new handlers here
+  - **config.py**: Pydantic settings (`get_settings()` cached via `lru_cache`)
+  - **constants.py**: Centralized message templates and utilities
+  - **handlers/**: Telegram update handlers (message.py, dm.py, captcha.py, verify.py, anti_spam.py, topic_guard.py, check.py)
+  - **services/**: Business logic (user_checker.py, scheduler.py, bot_info.py, telegram_utils.py, captcha_recovery.py)
+  - **database/**: SQLModel schemas (models.py) and SQLite operations (service.py) — use `get_database()` singleton
+- **tests/**: pytest-asyncio tests with mocked telegram API
+- **data/bot.db**: SQLite database (auto-created via `SQLModel.metadata.create_all`)
+
+## Code Style
+
+- **Python 3.11+** with type hints; imports grouped: stdlib → third-party → local
+- **Async/await**: All handlers are async functions
+- **PTB v20+**: Use `ContextTypes.DEFAULT_TYPE` for context type hints, not legacy `Dispatcher`/`Updater`
+- **SQLModel**: Use `session.exec(select(Model).where(...)).first()` syntax; no Alembic migrations
+- **Logging**: Use `logfire` for structured logging, not `print()` or stdlib `logging`
+- **Error handling**: Catch specific exceptions (e.g., `TimedOut`), log errors, return gracefully
+- **No comments**: Avoid inline comments unless code is complex
+- **Docstrings**: Module-level docstrings required, function docstrings for public APIs
+
+## Testing
+
+- **Async mode**: `asyncio_mode = auto` in pyproject.toml — do NOT use `@pytest.mark.asyncio` decorators
+- **Fixtures**: Check existing fixtures in test files (`mock_update`, `mock_context`, `mock_settings`)
+- **Mocking**: Use `AsyncMock` and `MagicMock` for telegram API; no real network calls
diff --git a/src/bot/constants.py b/src/bot/constants.py
@@ -266,6 +266,263 @@ def format_hours_display(hours: int) -> str:
     "core.telegram.org",
     
     # Indonesian Tech Communities
-    "t.me",
     "dicoding.com",
 ])
+
+# Whitelisted Telegram paths/usernames for new user probation
+# Only these specific t.me paths are allowed (exact match on first path segment)
+# e.g., "PythonID" allows "t.me/PythonID", "t.me/PythonID/123", but not "t.me/PythonIDSpam"
+# Values should be lowercased for case-insensitive matching
+WHITELISTED_TELEGRAM_PATHS = frozenset([    
+    # Cloud & Platforms
+    "juaragcp",
+    "awsdatausergroupid",
+    "awsusergroupid",
+    "azureindo",
+    "gcpuserid",
+    "gcp_id",
+    
+    # AI & Data Science
+    "artificialintelligence_indonesia",
+    "businessintelligenceid",
+    "dataengineeringid",
+    "datascienceindonesia",
+    "iaiforum",
+    "machinelearningid",
+    "nlp_lounge",
+    "pytorchid",
+    "scrapeid",
+    "tableauprofessionals",
+    "tensorflowid",
+    
+    # Databases
+    "sqlserverid",
+    "mongodb_id",
+    "mongo_db",
+    "mysqlid",
+    "postgresql_id",
+    
+    # General Programming & Developer Groups
+    "bandungdevcom",
+    "belajarcoding",
+    "belajarngodingbareng",
+    "gnurindonesia",
+    "belajargolangmariadb",
+    "belajarhtmlcss",
+    "bogordev",
+    "borneokoding",
+    "tgbotid",
+    "otodidak_ngoding",
+    "crbdev",
+    "codingfess",
+    "cscript",
+    "femalegeek",
+    "freekelasgithub",
+    "frontendid",
+    "gresikdev",
+    "iamindonesia",
+    "idstack",
+    "infotechprogrammer",
+    "itnusantara",
+    "djemberdev",
+    "kabayan_coding",
+    "kelasmobilemalang",
+    "backendid",
+    "komunitasbk",
+    "komunitasrpaindonesia",
+    "kongkowitmedan",
+    "kongkowitpekanbaru",
+    "kotakodebetachat",
+    "kulkultech",
+    "odooindonesia",
+    "pasuruandev",
+    "programersemarangraya",
+    "rantaudev",
+    "santrenkoding",
+    "sarccomuniverse",
+    "sidoarjodev",
+    "sinaudev",
+    "soft_eng_id",
+    "sparkarindonesia",
+    "surabayadev",
+    "lamongandev",
+    "tamankodekode",
+    "tiadevcommunity",
+    "teknologi_umum_v2",
+    "idwordpress",
+    "smk_dev",
+    
+    # DevOps & Infrastructure
+    "ansibleid",
+    "cloudcomputingindonesia",
+    "dockeridn",
+    "iddevops",
+    "kubernetesindonesia",
+    "okdindonesia",
+    "devopsjogja",
+    
+    # Firebase
+    "firebaseindonesia",
+    
+    # FreeBSD
+    "setanmerahid",
+    
+    # Game Development
+    "gamerang",
+    "gdevelopid",
+    "godot_indonesia",
+    "lombokgamedev",
+    
+    # IoT
+    "kelasrobotgrup",
+    "arduinoindonesiancommunity",
+    "edukasielektronika",
+    "raspberrypi_id",
+    
+    # iOS
+    "ikaskus",
+    "initialestore",
+    "libimobiledevice",
+    
+    # Jokes
+    "linux_memes",
+    "programmerjokes",
+    
+    # Linux
+    "archlinuxid",
+    "artixlinux_id",
+    "gnulinuxindonesia",
+    "belajarlinuxbareng",
+    "blankonlinux",
+    "centosid",
+    "debianid",
+    "deepin_indonesia",
+    "dotfiles_id",
+    "elementaryid",
+    "fedoraid",
+    "gnomeid",
+    "gnuweeb",
+    "kalilinuxid",
+    "kdeid",
+    "linuxmalang",
+    "linuxjember",
+    "lfsid",
+    "langitketujuh_id",
+    "mint_id",
+    "linuxgroupid",
+    "manjaroid",
+    "nixosid",
+    "opensuse_id",
+    "linuxsolo",
+    "parrotsecurityindonesia",
+    "rhel_id",
+    "ubuntu_indo",
+    "voidlinux_id",
+    
+    # macOS
+    "macosid",
+    
+    # Office Productivity
+    "excelid",
+    "belajarlibreofficeindonesia",
+    
+    # Open Source & Security
+    "osint_indonesia",
+    "doscomedia",
+    "forensicaid",
+    "itsecurityindonesia",
+    "linuxhackingid",
+    "orangsiber",
+    "reversingid",
+    "cybersecurity_id",
+    "hacktheboxindo",
+    
+    # Programming Languages (Specific)
+    "dotnetusergroup",
+    "dotnetcore_id",
+    "xamarinindonesia",
+    "androiddevbdg",
+    "androiddevelopernasional",
+    "teknorialcom",
+    "android_lombok",
+    "androiddevsurabaya",
+    "jcomposeindonesia",
+    "androidsemarang",
+    "source_code_android",
+    "yacgroup",
+    "agilecirclesid",
+    "agileindonesia",
+    "assemblyid",
+    "bashidorg",
+    "ccpp_indonesia",
+    "idcplc",
+    "crystalid",
+    "dart_web",
+    "flutter_id",
+    "flutter_jkt",
+    "fluttermakassar",
+    "lombokflutter",
+    "elixir_id",
+    "gophers_id",
+    "golangjogja",
+    "golangsurabaya",
+    "rustacean_id",
+    "jvmindonesia",
+    "adonisid",
+    "angularid",
+    "deno_id",
+    "indonesiaionic",
+    "js_id",
+    "jogjajs",
+    "lombokjs",
+    "nativescript_id",
+    "nestjs_indonesia",
+    "nextjs_id",
+    "nodejsid",
+    "bun_id",
+    "react_idn",
+    "reactnativeindo",
+    "surabayajs",
+    "svelte_id",
+    "vuejsindonesia",
+    "kotlin_crb",
+    "kotlinindonesia",
+    "delphiindonesia",
+    "pascalid",
+    "codeigniterindonesia",
+    "laravelindonesia",
+    "phpidforbusiness",
+    "phpidforstudent",
+    "phpjogloraya",
+    "symfonyid",
+    "botphp",
+    "yiiframeworkindonesia",
+    "bandung_py",
+    "djangoid",
+    "fastapiid",
+    "flaskid",
+    "lombok_py",
+    "mkspy",
+    "pyjogja",
+    "pythonid", # Duplicate of "pythonid" but kept for completeness of list
+    "python",
+    "pythonlearnerr",
+    "python_learners_group",
+    "surabayapy",
+    "railsid",
+    "ruby_id",
+    "swiftid",
+    "typescriptindonesia",
+    "sapabapindonesia",
+    "gis_id",
+    "leafletid",
+    "qgisindonesia",
+    
+    # QA
+    "sqa_id",
+    "qamalang",
+    
+    # Text Editors
+    "emacsid",
+    "vimid",
+])
diff --git a/src/bot/handlers/anti_spam.py b/src/bot/handlers/anti_spam.py
@@ -20,6 +20,7 @@
     NEW_USER_SPAM_WARNING,
     RESTRICTED_PERMISSIONS,
     WHITELISTED_URL_DOMAINS,
+    WHITELISTED_TELEGRAM_PATHS,
     format_hours_display,
 )
 from bot.database.service import get_database
@@ -139,6 +140,22 @@ def is_url_whitelisted(url: str) -> bool:
         # Remove port if present
         if ':' in hostname:
             hostname = hostname.rsplit(':', 1)[0]
+            
+        # Specific logic for Telegram links
+        # Check against WHITELISTED_TELEGRAM_PATHS instead of WHITELISTED_URL_DOMAINS
+        if hostname in {"t.me", "telegram.me"}:
+            path = parsed.path
+            if not path or path == "/":
+                return False
+                
+            # Extract the first segment of the path (the username/channel name)
+            # e.g., "/PythonID/123" -> "pythonid"
+            parts = path.strip("/").split("/")
+            if not parts:
+                return False
+                
+            first_segment = parts[0].lower()
+            return first_segment in WHITELISTED_TELEGRAM_PATHS
 
         # Check suffixes of the hostname against the set
         # e.g., "sub.example.github.com" checks:
diff --git a/tests/test_whitelist.py b/tests/test_whitelist.py
