Telegram Dissemination Bot

Deliverable AGT-002. Structure per cc02-standards/SYSTEM-STANDARD.md. Every component traces to a design basis (NEED/REQ) and to an acceptance criterion.

1. Purpose and Design Basis

1.1 Scope and Objective

The Telegram Dissemination Bot is a secure, automated notification component that broadcasts formatted daily intelligence briefs and critical alert notifications directly to mobile devices utilized by executive protection operators in the field.

1.2 Design Basis

This system provides an automated, low-latency pathway to deliver intelligence briefs from AGT-001 to mobile operators. It runs as a non-interactive daemon on the secure hosting VPS, consuming new brief files and pushing them via the Telegram bot API.

1.3 Needs

• NEED-AGT-002-01: The Ops Manager (BR) needs secure, instant delivery of daily briefs to mobile operators in the field to replace unencrypted email updates.
  • Source: BR (Operations Manager) security and efficiency concern.
  • Context: Operators are on the move and require mobile-friendly, encrypted, instant notifications of daily briefs.
• NEED-AGT-002-02: The Systems Engineer (CS) requires restricted access to the Telegram bot API so that it can only post to authorized channel IDs and prevents reverse command execution.
  • Source: CS (Systems Engineer) security architecture plan.
  • Context: Compromised bot tokens could allow malicious actors to inject commands or query internal servers.

1.4 Requirements

• REQ-AGT-002-01 (Traceability: NEED-AGT-002-01): On receipt of a daily brief file, the Telegram Dissemination Bot shall distribute the formatted markdown text to the operational channel within 60 seconds [VR-AGT-002-01].
  • Verification Method: Test (T)
• REQ-AGT-002-02 (Traceability: NEED-AGT-002-01): In the event of a message delivery failure (return code non-zero), the Telegram Dissemination Bot shall retry sending to the backup channel twice at 5-minute intervals [VR-AGT-002-02].
  • Verification Method: Demonstration (D)
• REQ-AGT-002-03 (Traceability: NEED-AGT-002-02): The Telegram Dissemination Bot shall restrict posts to predefined and allowlisted channel and group IDs [VR-AGT-002-03].
  • Verification Method: Inspection (I)

2. Architecture As Built

The Telegram Dissemination Bot is a lightweight daemon (Python 3.12, utilizing watchdog and requests libraries) that runs as a systemd service. It monitors the briefs directory for new markdown files emitted by AGT-001. Upon detecting a new file, it verifies the content, formats it for Telegram’s markdown parsing rules, and publishes it via HTTP POST requests to the Telegram Bot API. Outbound routing is restricted to a statically configured list of chat IDs.

Data flow:

1. The monitored briefs directory registers a new file-creation event via a filesystem watch.
2. The file loader loads the brief, validates its format, and ensures its size is under the Telegram message limit, splitting the payload if necessary.
3. The whitelist filter verifies that the target chat IDs are present in the secure local configuration.
4. The client sender invokes the Telegram Bot API HTTP POST interface to broadcast the payload to the channel.
5. On a non-zero API response, the client sender triggers the retry loop to the backup channel.

+-------------------------------------------------------------------------+
| AGT-002 Telegram Dissemination Bot                                      |
|                                                                         |
|  [AGT-001 Daily Brief] ---> [Brief File Monitor] ---> [Telegram Client] |
|                                                             |           |
+-------------------------------------------------------------|-----------+
                                                              v
                                                    Telegram Gateway API
                                                              |
                                                              v
                                                     [Field Operators]

3. Components and Bill of Materials

Component	Spec	Vendor / Link	Price	Tier	Status	Traceability
Bot Script	Python-based client script with requests library	Internal	$0.00	-	SELECTED	REQ-AGT-002-01
Hosting	Shared VPS instance	Hetzner	existing	-	SELECTED	REQ-AGT-002-01
Telegram Gateway Link	API integration wrapper (SYS-006 platform)	Internal	$0.00	-	SELECTED	REQ-AGT-002-03

4. Build and Deployment

4.1 Bot Registration

1. Register a secure Telegram Bot token via the BotFather utility on the Telegram application.
2. Record the unique API token and chat IDs for the operational channels.

4.2 Daemon Installation

1. Initialize the python virtual environment and sync dependencies using uv: uv sync.
2. Deploy the bot service as a systemd daemon on the primary VPS.
3. Configure environmental parameters inside the /etc/default/tg-bot configuration file.
4. Set up the whitelist configuration at /etc/tg-bot/whitelist.yaml with the authorized channel and backup channel IDs.
5. Configure a file-system directory monitor to watch the briefs/ directory for new compilations.
6. Deploy the systemd service unit file to /etc/systemd/system/tg-bot.service and enable the daemon: systemctl daemon-reload && systemctl enable --now tg-bot.service.

5. Hardening Baseline

• Credential Isolation: Store the Telegram API token inside /etc/default/tg-bot with file permissions restricted to chmod 0400 under root [REQ-AGT-002-03].
• Whitelist Enforcement: Bind the message dispatch destination to pre-configured chat and channel IDs only; reject any dynamic destination overrides [REQ-AGT-002-03].
• Interactive Disablement: Configure the bot profile to run in outbound-only broadcast mode, disabling message receiving callbacks.
• Service Isolation: Restrict directory execution and write permissions for the monitored folder to the daemon execution user only; configure systemd service constraints (ProtectSystem=strict, PrivateTmp=true, NoNewPrivileges=true) to isolate the daemon process.

6. Integration Points

Interface	Type	Direction	Contract
Ingest Brief	File (Markdown)	Consumed	Matches the ART-daily-brief schema output from AGT-001
Telegram Broadcast	API	Produced	Disseminated to EP Mobile Operators via the SYS-006 platform

7. Acceptance Tests

Criterion	Method	Expected Result	Reference
REQ-AGT-002-01	Test	Format and send brief to test chat ID within 60 seconds of folder trigger.	VR-AGT-002-01
REQ-AGT-002-02	Demonstration	Simulate API timeout and verify the bot executes the two retries at 5-minute intervals.	VR-AGT-002-02
REQ-AGT-002-03	Inspection	Verify configuration whitelist limits messages to specified group ID.	VR-AGT-002-03

8. Run and Maintenance Handover

• Service Status: Check status via systemctl status tg-bot.
• Maintenance: Monthly validation of channel whitelist members.
• Ownership: Systems Engineer (CS).

END OF SYSTEM

Model wiring

Generated from cell frontmatter at publish time.

• Inputs: AGT-001
• Related: AGT-003