docs: update docs for ACL tiers and webhook
All checks were successful
CI / test (3.11) (push) Successful in 1m37s
CI / test (3.12) (push) Successful in 1m35s
CI / test (3.13) (push) Successful in 1m20s

- USAGE.md: permission tiers section, webhook config/API/example
- CHEATSHEET.md: ACL tiers and webhook quick-ref sections
- ROADMAP.md: mark webhook and ACL items done
- TODO.md: mark webhook and ACL items done
- TASKS.md: new sprint for ACL + webhook work
This commit is contained in:
user
2026-02-21 17:59:22 +01:00
parent c483beb555
commit e9528bd879
5 changed files with 155 additions and 26 deletions

View File

@@ -75,21 +75,27 @@ code changes -- restart the container or use `!reload` for plugins.
!h # Shorthand (any unambiguous prefix works)
```
## Admin
## Permission Tiers
```
!whoami # Show your hostmask + admin status
!admins # Show admin patterns + detected opers (admin)
user < trusted < oper < admin
```
```toml
# config/derp.toml
[bot]
admins = ["*!~user@trusted.host", "ops!*@*.ops.net"]
admins = ["*!~root@*.ops.net"] # admin tier
operators = ["*!~staff@trusted.host"] # oper tier
trusted = ["*!~user@known.host"] # trusted tier
```
IRC operators are auto-detected via WHO on connect and on user JOIN
(debounced 2s to handle netsplit floods). Hostmask patterns use fnmatch.
```
!whoami # Show your hostmask + permission tier
!admins # Show configured tiers + detected opers (admin)
```
IRC operators are auto-detected via WHO (admin tier). Hostmask patterns
use fnmatch. `admin=True` on commands still works (maps to tier="admin").
## Channel Management (admin)
@@ -449,6 +455,33 @@ Shows top 3 results as `Title -- URL`. Channel only. Max query length: 200 chars
Intervals: `5m`, `1h30m`, `2d`, `90s`, or raw seconds. Min 1m, max 7d.
Max 20 jobs/channel. Persists across restarts. Channel only.
## Webhook (admin)
```toml
# config/derp.toml
[webhook]
enabled = true
host = "127.0.0.1"
port = 8080
secret = "your-shared-secret"
```
```bash
# Send message to IRC channel via webhook
SECRET="your-shared-secret"
BODY='{"channel":"#ops","text":"Deploy done"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST http://127.0.0.1:8080/ \
-H "X-Signature: sha256=$SIG" -d "$BODY"
```
```
!webhook # Show listener status (admin)
```
POST JSON: `{"channel":"#chan","text":"msg"}`. Optional `"action":true`.
Auth: HMAC-SHA256 via `X-Signature` header. Starts on IRC connect.
## Plugin Template
```python