Security, Auth & Permissions

Relevant source files

The following files were used as context for generating this wiki page:

• main.py
• webapp/README.md
• code_review_2025_10/SECURITY_FINDINGS.md
• database/blocked_users_manager.py
• CLOUD.md
• GUIDES/ARCHITECTURE.md

Introduction

The security architecture of CodeBot is designed to protect user code snippets and system integrity through a multi-layered approach involving authentication, granular permissions, and proactive threat mitigation. The system supports two primary interfaces: a Telegram bot and a companion Web Application, each utilizing distinct but integrated security mechanisms to ensure consistent access control.

The scope of this module covers user authentication via Telegram and single-use tokens, administrative permission tiers (Regular, Premium, Admin), rate limiting strategies to prevent abuse, and a comprehensive user blocking system. Additionally, infrastructure security is managed through secret management and environment variables to prevent credential exposure.

Authentication Mechanisms

CodeBot employs several methods to verify user identity depending on the entry point (Bot or WebApp).

Telegram Auth & WebApp Tokens

For the WebApp, users can authenticate using the Telegram Login Widget or a one-time token generated by the bot.

• Telegram Widget: Uses Telegram's secure authentication API.
• Token-based Auth: Users issue a /webapp_login command in the bot to receive a unique token.
• Token Validity: WebApp tokens are saved in the webapp_tokens collection with a 5-minute expiration time.
• Session Persistence: The WebApp supports persistent login sessions ("Remember Me") for up to 30 days.

Sources: webapp/README.md:10-15, main.py:1260-1285

MCP (Model Context Protocol) Security

Users can connect their code snippets to AI tools like Claude using MCP. This involves issuing Personal Access Tokens (PAT) with specific scopes.

• Scopes: Supports read and write permissions.
• Confidentiality: Tokens are generated only in private chats to prevent leakage in group settings.
• Authorization: MCP requests must include the token in the Authorization: Bearer header.

Sources: main.py:270-300

Permissions & User Tiers

Code permissions are enforced through a hierarchical role-based system.

Role	Access Level	Description
Regular	Standard	Default user role with basic snippet management.
Premium	Enhanced	Extended limits for files and features.
Admin	Full Access	Access to ChatOps, system statistics, and user management (Ban/Unban).

Sources: webapp/README.md:14-15, main.py:1297-1300

Admin Authorization Flow

Administrative commands (like /ban, /blocked, /recycle_backfill) utilize a verification utility to check the user ID against a comma-separated list defined in the ADMIN_USER_IDS environment variable.

The diagram shows the logic gate applied to sensitive commands within main.py.
Sources: main.py:365-375, CLOUD.md:47-48

User Blocking & Safety

The system maintains a robust blocking manager to prevent malicious activity or spam.

Blocked Users Manager

The system handles blocks via two layers:

1. Environment Variables: IDs listed in BLOCKED_USER_IDS (managed in Render/CI) are permanent and cannot be removed via bot commands.
2. Database Storage: Dynamic blocks stored in the MongoDB blocked_users collection, which include reasons and timestamps.

Sources: database/blocked_users_manager.py:10-25, main.py:440-450

Access Guard Logic

A global _rate_limit_gate in the bot's application logic checks if a user is blocked before processing any further handlers. If a user is blocked, the request is terminated silently to avoid providing feedback to spammers.

Rate Limiting Architecture

To ensure system stability, CodeBot implements a multi-tiered rate limiting strategy using a moving-window algorithm.

Configuration Options

Variable	Default	Purpose
RATE_LIMIT_ENABLED	false	Global toggle for the rate limiter.
RATE_LIMIT_SHADOW_MODE	false	Logs potential blocks without enforcing them.
RATE_LIMIT_PER_MINUTE	30	Threshold for user actions.
RATE_LIMIT_STRATEGY	moving-window	Algorithm used for tracking requests.

Sources: CLOUD.md:66-72, main.py:1010-1025

Enforcement Layers

• Local Counter: A per-user in-memory counter stored in context.user_data for immediate, low-latency checks.
• Advanced Limiter: An optional Redis-backed backend using the limits library for persistent, multi-instance rate limiting.
• Soft Warnings: Users reaching 80% of their limit receive an advisory message before enforcement occurs.

Sources: main.py:1075-1115, GUIDES/ARCHITECTURE.md:200-215

Credential Security & Infrastructure

Hardened security practices are enforced at the code and deployment levels to protect sensitive credentials.

Secret Management

• Environment Variables: Credentials like BOT_TOKEN, MONGODB_URL, and SECRET_KEY must never be hardcoded and should be accessed via os.getenv or the config object.
• Pre-commit Hooks: The project utilizes detect-secrets to prevent accidental commits of credentials to Git history.
• Credential Rotation: Security findings mandate immediate rotation of MongoDB passwords if exposed in source files.

Sources: code_review_2025_10/SECURITY_FINDINGS.md:5-25, CLOUD.md:40-45

Database Connection Security

All MongoDB connections utilize TLS/SSL where appropriate, and specific administrative functions like ensure_lock_indexes and manage_mongo_lock ensure that only authorized instances can write to the synchronization layer.
Sources: main.py:650-670, main.py:840-860

Summary

The security, authentication, and permissions system in CodeBot provides a defensive perimeter against unauthorized access and resource abuse. By combining Telegram-native authentication with custom session management, role-based access control, and distributed rate limiting, the project maintains a secure environment for code management. Ongoing security audits and the transition toward environment-based secret management further strengthen the system's resilience against credential exposure.