cg_api_secure-webshare/docs/MODERATION.md

Moderation & Punishment System

This document describes the punishment system implemented in the bot.

---

Database Schema

Defined in migrations/004_punishments.sql.

CREATE TABLE punishments (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    chat_id INTEGER NOT NULL,
    target_user_id INTEGER NOT NULL,
    action_type TEXT NOT NULL, -- 'ban', 'mute', 'kick'
    duration_seconds INTEGER,  -- NULL = permanent / indefinite
    reason TEXT,
    created_by INTEGER NOT NULL,
    created_at TEXT NOT NULL DEFAULT datetime('now'),
    revoked_at TEXT,
    revoked_by INTEGER,
    active INTEGER NOT NULL DEFAULT 1
);

CREATE INDEX idx_punishments_chat_target ON punishments(chat_id, target_user_id);
CREATE INDEX idx_punishments_active ON punishments(active);

Field Reference

Field	Type	Description
id	INTEGER	Primary key.
chat_id	INTEGER	The Telegram group/chat where the punishment was applied.
target_user_id	INTEGER	The punished user's Telegram ID.
action_type	TEXT	One of ban, mute, or kick.
duration_seconds	INTEGER	Duration before auto-expiration. NULL means permanent / indefinite.
reason	TEXT	Optional moderator-provided reason.
created_by	INTEGER	Telegram ID of the moderator who issued the punishment.
created_at	TEXT	ISO timestamp when the punishment was created.
revoked_at	TEXT	ISO timestamp when the punishment was manually or automatically revoked.
revoked_by	INTEGER	Telegram ID of the revoker, or 0 for the system (auto-expiry).
active	INTEGER	1 if the punishment is still in effect, 0 if revoked.

---

Command Reference

All punishment commands require the caller to be an administrator or owner of the group.

Duration-based Punishments

Command	Syntax	Description
/sban	/sban @user <dur> <unit> [reason]	Ban the user for a specific duration.
/smute	/smute @user <dur> <unit> [reason]	Mute the user for a specific duration.

Permanent / Indefinite Punishments

Command	Syntax	Description
/mute	/mute @user [reason]	Mute the user indefinitely (duration_seconds = NULL).
/pban	/pban @user [reason]	Permanently ban the user (duration_seconds = NULL).
/kick	/kick @user [reason]	Kick the user from the group. Always recorded with NULL duration.

Revoke Commands

Command	Syntax	Description
/rmute	/rmute @user	Revoke the active mute for this user and restore chat permissions.
/rban	/rban @user	Revoke the active ban for this user and unban them.

Target Resolution

The @user argument is resolved in the following order:

1. Numeric user ID.
2. @username — matched against chat administrators.

If the target cannot be resolved, the bot replies with "Could not resolve target user."

---

Duration Units Reference

The parse_duration function in crates/cgcx-bot/src/main.rs accepts the following units (case-insensitive):

Unit(s)	Seconds	Example
s, sec, secs, second, seconds	1	/sban @user 30 s spam
m, min, mins, minute, minutes	60	/smute @user 10 m offtopic
h, hr, hrs, hour, hours	3,600	/sban @user 24 h raid
d, day, days	86,400	/sban @user 7 d trolling
w, week, weeks	604,800	/smute @user 2 w
mo, month, months	2,592,000 (30 days)	/sban @user 1 mo
y, year, years	31,536,000 (365 days)	/pban @user 1 y

---

How Expiration Works (Background Task)

When the bot starts, a background Tokio task is spawned that runs every 60 seconds:

1. Query — Calls PunishmentRepo::list_expired(), which selects rows where:

   • active = 1
   • duration_seconds IS NOT NULL
   • datetime(created_at, '+' || duration_seconds || ' seconds') <= datetime('now')

2. Action per expired punishment:

   • ban — Calls unban_chat_member(chat_id, target_user_id) to lift the ban.
   • mute — Calls restrict_chat_member with restored permissions:
     • SEND_MESSAGES
     • SEND_MEDIA_MESSAGES
     • SEND_OTHER_MESSAGES
     • ADD_WEB_PAGE_PREVIEWS
   • Other types — No automatic Telegram action is taken.

3. Record update — Calls repo.revoke(p.id, 0):

   • Sets active = 0
   • Sets revoked_at = datetime('now')
   • Sets revoked_by = 0 (system)

---

How Revoke Works

Manual Revoke (/rmute, /rban)

1. The bot resolves the target user.
2. Queries get_active_for_chat_target(chat_id, target_user_id, action_type) to find the active punishment.
3. If found:
   • /rmute — Restores the user's chat permissions via restrict_chat_member(...).
   • /rban — Unbans the user via unban_chat_member(...).
   • Calls repo.revoke(p.id, admin_user_id) to mark the punishment inactive.
4. If no active punishment is found, the bot replies with "No active mute/ban found for this user."

Revoke via PunishmentRepo::revoke(id, revoked_by)

UPDATE punishments
SET active = 0,
    revoked_at = datetime('now'),
    revoked_by = ?1
WHERE id = ?2;

This is used both for:

• Automatic expiration (revoked_by = 0)
• Manual moderator revocation (revoked_by = moderator_user_id)