Skip to content

Commit c6904a4

Browse files
ToHubLabToHubLab
authored
Create README for Verification Cog early version
Add README for Verification Cog with features, installation, and usage instructionsfor the early version
1 parent 7513cfc commit c6904a4

1 file changed

Lines changed: 266 additions & 0 deletions

File tree

‎verification/README-early-preview.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Verification Cog for Red-DiscordBot
2+
3+
A Red-DiscordBot cog that verifies new members via a button or reaction, challenges them with a math or text task, and grants a role — with a full setup wizard, custom emoji support, security checks, and a live management menu.
4+
5+
---
6+
7+
## ✨ Features
8+
9+
| Feature | Description |
10+
|---|---|
11+
| ⚙️ **Interactive Setup Wizard** | 4-step wizard: channel → role → mode → confirm — one single message, no spam |
12+
| 🔘 **Button Mode** | Users verify via a button directly on a message the bot posts |
13+
| 💬 **Reaction Mode** | Use any existing message — the bot adds a reaction emoji to trigger verification |
14+
| 🎨 **Emoji Picker** | Choose from 24 standard emojis — or extend them via a JSON data file |
15+
| 🧮 **Math Challenges** | Random addition, subtraction, and multiplication problems |
16+
| ✍️ **Text Challenges** | Prompts like `Type 'ToHubLab' to verify` or `Write 'Color' to verify` |
17+
| 🎭 **Auto Role Assignment** | Grants the configured verification role upon success |
18+
| ⏳ **3-Strike Lockout** | Wrong answers lock the user out for 10 minutes with a live progress bar |
19+
| 🔐 **Security Check** | If the role is manually removed, users answer 2 security questions to re-verify |
20+
| 🧹 **Auto-Cleanup** | Setup, status, reset, and cancel messages auto-delete after a few seconds |
21+
| 🔄 **Background Sync** | Every 5 minutes, reactions and roles are synced to prevent drift |
22+
| 📊 **Live Status Menu** | `.verifymenu` shows the current config with buttons to change things |
23+
| 📋 **Verified Users List** | `.verifysetup verified` — ephemeral, paginated (5 per page), with Prev/Next |
24+
| 📁 **JSON Data File** | Emoji options, text challenges, and security questions all live in one file |
25+
| 🔧 **Persistent Buttons** | Verification buttons keep working after bot restarts |
26+
| 🔒 **Admin Only** | Configuration commands require `Manage Server` |
27+
| 🐙 **Credits** | Built-in link to [ToHubLab on GitHub](https://github.com/ToHubLab) |
28+
29+
---
30+
31+
## 📦 Installation
32+
33+
```text
34+
[p]repo add ToHubLab-Cogs https://github.com/ToHubLab/ToHubLab-Cogs
35+
```
36+
37+
```text
38+
[p]cog install ToHubLab-Cogs verification
39+
```
40+
41+
```text
42+
[p]load verification
43+
```
44+
45+
---
46+
47+
## 🚀 Quick Start
48+
49+
```text
50+
[p]verifysetup start
51+
```
52+
53+
Follow the wizard:
54+
55+
1. **Select the verification channel**
56+
2. **Select the role** to grant on success
57+
3. **Choose a mode**:
58+
- 📝 *Send new message* — bot posts a message with a **Verify** button
59+
- 💬 *Use existing message* — pick a message ID and a reaction emoji
60+
4. **Confirm & Create**
61+
62+
Then verify your setup with:
63+
64+
```text
65+
[p]verifysetup status
66+
```
67+
68+
---
69+
70+
## 🛠️ Commands
71+
72+
| Command | Description |
73+
|---|---|
74+
| `[p]verifysetup start` | Runs the interactive setup wizard |
75+
| `[p]verifysetup status` | Shows the current config (auto-deletes after 8s) |
76+
| `[p]verifysetup reset` | Resets the setup and cleans up everything |
77+
| `[p]verifysetup cleanup [#channel]` | Deletes orphaned verification messages |
78+
| `[p]verifysetup reloaddata` | Reloads `verification_data.json` from disk |
79+
| `[p]verifysetup sync` | Manually runs the reaction/role sync |
80+
| `[p]verifysetup verified` | Paginated list of verified users (ephemeral, 5 per page) |
81+
| `[p]verifymenu` | Opens the interactive management menu |
82+
83+
All commands require **Manage Server** permission.
84+
85+
---
86+
87+
## 📁 Project Structure
88+
89+
The cog is organized into focused modules with clear responsibilities.
90+
The main cog file handles commands and events, while every helper lives
91+
in its own file under `helpers/`.
92+
93+
```text
94+
verification/
95+
├── __init__.py Package entry point
96+
├── info.json Cog metadata for Red
97+
├── verification.py Main cog (commands, listeners, sync)
98+
├── README.md This file
99+
├── LICENSE MIT License
100+
└── helpers/
101+
├── __init__.py Centralized re-exports
102+
├── constants.py All constants and default data
103+
├── utils.py Emoji normalization + challenge generator
104+
├── embeds.py All embed builders
105+
├── data_manager.py JSON file I/O (data + verified users)
106+
├── modals.py All modals
107+
├── verify_views.py User-facing views
108+
├── setup_views.py Setup wizard and its views
109+
└── menu_views.py .verifymenu views
110+
```
111+
112+
### Why modular?
113+
114+
- **Single Responsibility** — each file handles one concern
115+
- **Easier to extend** — adding an embed only touches `embeds.py`
116+
- **No circular imports** — helpers import strictly what they need
117+
- **Testable in isolation** — every helper can be unit-tested
118+
- **Cleaner cog** — `verification.py` stays small (~500 lines)
119+
120+
---
121+
122+
## 📁 Data Files
123+
124+
On first load, the cog creates two files in its data directory:
125+
126+
```text
127+
<Red-Daten-Ordner>/Verification/verification_data.json
128+
<Red-Daten-Ordner>/Verification/verified_users.json
129+
```
130+
131+
### `verification_data.json`
132+
133+
Contains all customizable content. Edit it and run
134+
`[p]verifysetup reloaddata` to apply changes.
135+
136+
```json
137+
{
138+
"emoji_options": [
139+
["✅", "Check Mark Button"],
140+
["👍", "Thumbs Up"]
141+
],
142+
"text_challenges": [
143+
["Write 'Color' to verify", "color"],
144+
["Type 'ToHubLab' to verify", "tohublab"]
145+
],
146+
"security_questions": [
147+
["How many letters are in the word 'verify'?", "6"],
148+
["What color is the sky on a clear day?", "blue"]
149+
]
150+
}
151+
```
152+
153+
### `verified_users.json`
154+
155+
A read-only mirror of verified user IDs per guild. It is written
156+
automatically after each successful verification.
157+
158+
```json
159+
{
160+
"1234567890": [111111111111111111, 222222222222222222]
161+
}
162+
```
163+
164+
---
165+
166+
## 🔑 Requirements
167+
168+
The bot needs the following permissions in the verification channel:
169+
170+
| Permission | Why |
171+
|---|---|
172+
| **Send Messages** | Post verification messages |
173+
| **Embed Links** | Embed support |
174+
| **Add Reactions** | Reaction mode |
175+
| **Read Message History** | Reaction mode + cleanup |
176+
| **Manage Messages** | Delete old setup/status messages |
177+
| **Manage Roles** | Grant the verification role |
178+
179+
> ⚠️ The verification role must be **below** the bot's highest role
180+
> in the server role hierarchy.
181+
182+
---
183+
184+
## 🎯 How It Works
185+
186+
### Button Mode
187+
188+
1. User clicks the **Verify** button on the verification message
189+
2. A modal opens with a math or text challenge
190+
3. Correct answer → role granted
191+
4. Wrong answer → failed attempt counted
192+
5. After 3 wrong answers → 10-minute lockout with progress bar
193+
194+
### Reaction Mode
195+
196+
1. User reacts with the configured emoji
197+
2. Bot posts a short prompt in the same channel with an **Enter Answer** button
198+
3. Button click opens the challenge modal
199+
4. Correct answer → role granted and reaction kept
200+
5. Wrong answer → reaction removed so the user can retry
201+
6. Cancel or timeout → reaction removed automatically
202+
203+
### Security Check
204+
205+
If an admin manually removes the verification role from a verified user,
206+
the next time they try to verify they must first answer **two security
207+
questions**. On success, they are removed from the verified list and can
208+
run through verification again.
209+
210+
### Background Sync
211+
212+
Every 5 minutes the cog reconciles the reaction list and the role list:
213+
214+
| Situation | Action |
215+
|---|---|
216+
| Member has the role but **no reaction** | Role is removed |
217+
| Member has a reaction but **no role** and is on the verified list | Reaction is removed |
218+
| Member has a reaction but **no role** and is mid-verification | Nothing (in progress) |
219+
220+
This prevents drift between the reaction counter and the actual role
221+
assignment.
222+
223+
---
224+
225+
## 🎨 Customization
226+
227+
Everything user-facing can be customized without touching the code:
228+
229+
- **Emojis** — add or remove entries in `emoji_options`
230+
- **Text challenges** — add custom prompts in `text_challenges`
231+
- **Security questions** — add your own questions in `security_questions`
232+
- **Timings** — edit the constants at the top of `helpers/constants.py`
233+
- **Embed colors** — adjust in `helpers/embeds.py`
234+
235+
After editing `verification_data.json`, run:
236+
237+
```text
238+
[p]verifysetup reloaddata
239+
```
240+
241+
---
242+
243+
## 🐛 Troubleshooting
244+
245+
| Problem | Solution |
246+
|---|---|
247+
| Users can't verify | Check that the verification role is **below** the bot's role |
248+
| Reaction mode not working | Make sure the bot has **Add Reactions** + **Read Message History** |
249+
| Counter stays at 1 | Run `[p]verifysetup sync` to reconcile |
250+
| Messages not deleting | Bot needs **Manage Messages** |
251+
| Data file not reloading | Run `[p]verifysetup reloaddata` |
252+
253+
---
254+
255+
## 🐙 Credits
256+
257+
Made by [ToHubLab](https://github.com/ToHubLab)
258+
259+
- **GitHub** — [github.com/ToHubLab](https://github.com/ToHubLab)
260+
- **Support & Updates** — [discord.finn-bot.rf.gd](http://discord.finn-bot.rf.gd)
261+
262+
---
263+
264+
## 📜 License
265+
266+
MIT — see [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)