Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
793d214
refactor(opbot): shared payload codec and status-driven button sets
KingPin Nov 14, 2026
154b9f6
fix(telegram): only decode callbacks the route handles
KingPin Nov 14, 2026
4895bed
feat(db): oldest-first pending walk and provider user lookup
KingPin Nov 14, 2026
45e8f96
refactor(admin): extract moderator reply into opbot core
KingPin Nov 14, 2026
b96f1c7
feat(opbot): shared actions, role table, ban guard and readouts
KingPin Nov 14, 2026
fbfc7b2
feat(config): register DISCORD_BOT_TOKEN and DISCORD_PUBLIC_KEY
KingPin Nov 14, 2026
a9d137f
feat(discord): interaction verification, API client and card rendering
KingPin Nov 14, 2026
c7267cd
feat(db): discord_links table with erasure and export coverage
KingPin Nov 14, 2026
94842d9
feat(opbot): actor resolution for linked accounts and Discord roles
KingPin Nov 14, 2026
f832c38
feat(discord): daily digest to a channel with an independent gate
KingPin Nov 14, 2026
6417530
feat(telegram): run actions through opbot core and keep a status keyb…
KingPin Nov 14, 2026
841a3d3
feat(telegram): queue review walks pending comments in place
KingPin Nov 14, 2026
12cafcf
fix(webhook): Discord 429s honor retry_after and never auto-disable a…
KingPin Nov 14, 2026
20766b3
feat(webhook): discord_bot adapter posts alerts with moderation buttons
KingPin Nov 14, 2026
7bb43b0
feat(telegram): ban with reason, /unban, and ban state in /user
KingPin Nov 14, 2026
fd4da04
fix(telegram): break the cards/readouts import cycle that bypassed th…
KingPin Nov 14, 2026
3e02ffb
feat(admin): Discord settings, linking and command registration page
KingPin Nov 14, 2026
3eb5cf5
feat(telegram): reply to comments with saved replies or custom text
KingPin Nov 14, 2026
f7281ee
fix(telegram): pass the real executionCtx to prompt answers
KingPin Nov 14, 2026
38711f1
feat(discord): interactions endpoint with commands, actions, ban moda…
KingPin Nov 14, 2026
7316d01
docs: Discord operator bot and new Telegram features
KingPin Nov 14, 2026
d90856b
feat(discord): reply from alerts and queue cards with saved-reply picker
KingPin Nov 14, 2026
641431b
fix(discord): let Discord-sign-in admins open the ban modal
KingPin Nov 14, 2026
31564ed
fix(opbot): bust the tree cache for the Worker's own origin
KingPin Nov 14, 2026
ebc1d59
fix(opbot): truncate on code points so cards never split an emoji
KingPin Nov 14, 2026
6e3b4c9
refactor(discord): break the discord/webhook-adapters import cycle
KingPin Nov 14, 2026
e7d95ea
refactor(opbot): share reply refusal text and the bot rate limit
KingPin Nov 14, 2026
3c4b52c
fix(discord): validate channel targets strictly and name permission e…
KingPin Nov 14, 2026
bd44abe
docs(discord): correct digest cadence and picker details
KingPin Nov 14, 2026
4e2d869
chore: regenerate release manifest
KingPin Nov 14, 2026
59ce11c
fix(opbot): find the ban reason past unrelated audit rows
KingPin Nov 14, 2026
4997ea9
fix(telegram): mention the moderator in force-reply prompts
KingPin Nov 14, 2026
8236992
fix(discord): defer slow interactions instead of missing the 3 s dead…
KingPin Nov 14, 2026
3023fe1
test(discord): let real crypto settle before opening the slow-path gate
KingPin Nov 14, 2026
fc2fdf8
test(discord): use placeholder-shaped fixture usernames
KingPin Nov 15, 2026
21ffb7e
fix(discord): count rate-limiter latency toward the defer deadline
KingPin Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .dev.vars.example
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@ TELEGRAM_BOT_TOKEN=""
# shared secret for setWebhook; required for inbound commands
TELEGRAM_WEBHOOK_SECRET=""

# --- Discord operator bot ---
# bot token from the Discord developer portal (Bot tab)
DISCORD_BOT_TOKEN=""

# --- Anti-spam ---
# required when SPAM_PROVIDER = "akismet"
AKISMET_API_KEY=""
Expand Down
50 changes: 47 additions & 3 deletions AGENTS-OPERATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,8 @@ between the two is a build error, not a silent misclassification.
| `TELEGRAM_BOT_TOKEN` | secret | Optional. BotFather token enabling the Telegram operator bot. With only this set, outbound notifications work (add a `telegram` webhook endpoint with a chat id). Unset = feature off. See `docs/telegram.md`. | `123456789:AAH...` | `wrangler secret put` / `.dev.vars` |
| `TELEGRAM_WEBHOOK_SECRET` | secret | Optional. Shared secret echoed in the `X-Telegram-Bot-Api-Secret-Token` header; required for inbound buttons/slash commands. Pass it to Telegram's `setWebhook` as `secret_token`. Unset = inbound rejected (fail closed). | ``openssl rand -base64 32` output` | `wrangler secret put` / `.dev.vars` |
| `TELEGRAM_BOT_USERNAME` | var | Optional. Bot `@username` (without `@`). When set, `/admin/telegram` renders a one-tap `t.me/<bot>?start=<code>` deep link instead of manual `/start` steps. | `YourGarrulBot` | `wrangler.toml` |
| `DISCORD_BOT_TOKEN` | secret | Optional. Bot token enabling the Discord operator bot (moderation cards, buttons and slash commands). The bot is active only when `DISCORD_PUBLIC_KEY` is also set. Unset = feature off. | `MTE1...fake.token.example` | `wrangler secret put` / `.dev.vars` |
| `DISCORD_PUBLIC_KEY` | var | Optional. Discord application public key used to verify Ed25519 signatures on inbound interactions. Public, so a plain var. Required together with `DISCORD_BOT_TOKEN`; unset = inbound interactions rejected. | `0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef` | `wrangler.toml` |
| `SPAM_PROVIDER` | var | Optional. Pluggable content classifier — `akismet`, `workers-ai`, or `decisions` (bring your own key). Unset = no classifier. `workers-ai` also needs an `[ai]` binding; `decisions` needs `SPAM_DECISIONS_API_KEY` and a model. See `docs/ANTISPAM.md`. | `akismet` | `wrangler.toml` |
| `AKISMET_API_KEY` | secret | Optional. Akismet API key. Required when `SPAM_PROVIDER=akismet`. | `...` | `wrangler secret put` / `.dev.vars` |
| `AKISMET_SITE_URL` | secret | Optional. Public site URL sent to Akismet alongside each check. Required when `SPAM_PROVIDER=akismet`. | `https://yourblog.example.com` | `wrangler secret put` / `.dev.vars` |
Expand Down Expand Up @@ -997,6 +999,7 @@ tracked by the `_migrations` table. Current set:
- `0030_thread_and_retention_indexes.sql` — indexes for top-level thread paging (chronological and by score) and the IP retention sweep; drops the unused `comments_score_idx`
- `0031_admin_list_indexes.sql` — indexes for the moderation queue, dashboard windows and admin list pages
- `0032_page_engagement_totals.sql` — `posts.page_votes_up` / `page_votes_down` plus `page_reaction_totals`, kept on write so bootstrap no longer counts page reactions and votes on every pageview
- `0033_discord_links.sql` — `discord_links` (Discord user id ↔ Garrul user id; no digest column, the Discord digest goes to a channel)

Run with `npm run migrate` (local Miniflare) or
`npm run migrate -- --remote` (production D1). Idempotent. Never edit a
Expand Down Expand Up @@ -1061,11 +1064,51 @@ Pages (top nav):
| `/admin/subscriptions` | Email subscription list. Filter by email/post/confirmed/unsubscribed. Actions: manual unsubscribe, resend confirmation. |
| `/admin/operator` | Batch operations: rerender stale comments (POSTs `/admin/api/ops/rerender` in 50-row chunks until done), seed-demo (idempotent; gated to `ENV != "production"`), the comment import upload (Disqus XML, a Remark42 backup, a Comentario/Commento JSON export, or the JSON `npm run dump-isso` / `npm run dump-cusdis` produces from an isso `comments.db` or a Cusdis `db.sqlite` — gzipped or not — see below), and two retention cards — IP-hash and audit-log — each showing how many rows are past the configured window and offering a manual drain, and **Export site data** (JSON/CSV download links — see §11). |
| `/admin/settings` | Editable form for feature flags, display/pagination numbers, and the moderation dials (edit window, thread auto-close, community auto-collapse, the three anti-spam heuristics), saved to the `settings` D1 table (no redeploy — see section 5). Also renders a read-only `(set)`/`(unset)` summary of deploy-time config (Turnstile, email, OAuth, spam provider), which still changes via `wrangler secret put` / `wrangler.toml`. |
| `/admin/webhooks` | Outbound webhook endpoints: add/pause/delete, per-endpoint secret + event filter, adapter (`generic` / `slack` / `discord` / `telegram`), failure counts and retry status. |
| `/admin/webhooks` | Outbound webhook endpoints: add/pause/delete, per-endpoint secret + event filter, adapter (`generic` / `slack` / `discord` / `discord_bot` / `telegram`), failure counts and retry status. |
| `/admin/telegram` | **Admin-only.** Telegram operator bot: shows whether the bot token/webhook secret are set, links your personal Telegram account (one-time code or deep link), toggles the daily digest, and unlinks. See `docs/telegram.md`. |
| `/admin/discord` | **Admin-only.** Discord operator bot: guild id, mod/admin role ids, digest channel, link code, **Register commands**, and the Interactions Endpoint URL to paste into the Discord developer portal. See `docs/discord.md`. |
| `/admin/saved-replies` | Moderator saved replies: create/edit canned responses, private or shared scope. Presets are a *prefill* for the reply composer, not the only way to reply — see **Replying from the admin panel** below. |
| `/admin/usage` | Cloudflare analytics (Workers requests, D1 rows, KV operations, Workers AI neurons, comments by domain). Requires `CF_API_TOKEN` + `CF_ACCOUNT_ID`; renders setup instructions when unset. |

### Operator bots: Telegram and Discord

Both bots run on one platform-neutral core in `src/lib/opbot/` (actor
resolution, per-action authorization, actions, neutral cards, the oldest-first
queue walk, the button payload codec). Each transport translates cards to its
own markup and owns its own verification: `src/routes/telegram.ts`
(`POST /telegram/webhook`, secret header) and `src/routes/discord.ts`
(`POST /discord/interactions`, Ed25519). Both routes sit outside `/api/*`, so
CSRF and sessions do not apply. Every action goes through `src/lib/moderation.ts`
exactly as the dashboard does.

- **Discord is on only when `DISCORD_BOT_TOKEN` and `DISCORD_PUBLIC_KEY` are
both set** (see the config table). `DISCORD_CLIENT_ID` doubles as the
application id. The guild id, mod role id, admin role id and digest channel id
are admin settings at `/admin/discord`, not env vars.
- **Interactions**: the signature is verified before any D1/KV access (401), a
timestamp more than 5 minutes off is 401, then PING/PONG, then a per-user rate
limit. There is no dedupe: a replay inside the window can post a reply twice.
- **Identity**: a `discord_links` row (or a Discord sign-in row) or a configured
Discord role. The higher role wins. Discord roles are never written to
`users.role`. A role-derived admin cannot ban or unban a Garrul mod/admin. A
banned user, a wrong guild or a DM is refused.
- **Alerts** use the `discord_bot` webhook adapter: the endpoint URL field holds
a channel id, messages are posted with the bot token, and saving validates the
channel (same guild, text or announcement). The `discord` incoming-webhook
adapter stays for alert-only use. For both Discord adapters a 429 is retried
no earlier than `retry_after` and does not raise the endpoint failure counter.
- **Digest**: each transport has its own gate and timestamp
(`tg_digest_last_sent_at`, `dc_digest_last_sent_at`). Discord needs the token,
the public key and a digest channel.
- Features on both transports: who-did-what card edit, queue Review (oldest
first, Skip), ban with reason and `/unban`, reply with saved replies. In a
Telegram group the saved-reply list shows shared presets only. Discord replies
use a select menu and a modal (25-option menu, 4000-char modal).
- Cost rules: no new KV write per interaction (a ban keeps its one session
revocation write); every outbound body sets `allowed_mentions: { parse: [] }`.

Operator setup: `docs/discord.md` and `docs/telegram.md`.

State-changing endpoints (all under `/admin/api/...`, all require admin
session + Origin allowlist, all write an `audit_log` row before
responding):
Expand Down Expand Up @@ -1106,7 +1149,7 @@ personal data** → *Download JSON*, or `GET /admin/api/users/:id/export`
directly. This is the answer to a GDPR Art. 15 / Art. 20 or CCPA
right-to-know request: one file (`garrul-export-<id>.json`) holding the
account row, every comment they wrote, reports they filed, subscriptions
for their address, Telegram link, votes, reactions, page engagement, spam
for their address, Telegram and Discord links, votes, reactions, page engagement, spam
classifications on their comments, moderation actions taken against
them, and moderator notes written about them. Admin-only; a plain link
rather than a fetch, so the payload never sits in a JS variable.
Expand Down Expand Up @@ -1153,7 +1196,7 @@ the row would orphan every reply written under it. What it clears:
- `ip_hash` and `user_agent` on every comment they wrote, and
`reporter_ip_hash` on every report they filed.
- Their email subscriptions (plus any queued digest rows) and their
linked Telegram account.
linked Telegram and Discord accounts (`discord_links`).
- Their live sessions, revoked.
- Every moderator note written **about the account**. Two kinds
deliberately survive: notes they *wrote* about someone else, which are
Expand Down Expand Up @@ -2087,6 +2130,7 @@ Art. 33(4) explicitly allows filing in phases.
| OAuth `email`, `name`, `avatar_url`, `provider_id` | Links a real identity to everything that account wrote. |
| `comments.body_md` / `body_html` | Already public on your site; not usually a disclosure. Pending, spam and soft-deleted rows are the exception — those were never published. |
| `telegram_links` | External chat ids for operators. |
| `discord_links` | Discord user ids for operators. Deleted on erasure, included in the export. |
| `subscriptions.token` / `confirm_token` | Lets a holder unsubscribe or confirm someone else. Low severity, real nuisance. |
| `webhook_endpoints.secret` | Lets a holder forge signed events at your endpoints. |

Expand Down
6 changes: 6 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,12 @@ public HTTP API. This guide is for AI assistants helping a developer
**embed** Garrul. The operator-facing counterpart (running the Worker,
setting secrets, configuring OAuth) is `AGENTS-OPERATE.md`.

Operators can also moderate from chat. The Telegram and Discord operator bots
share one core (`src/lib/opbot/`); Discord interactions arrive at
`/discord/interactions` and Discord alerts use the `discord_bot` webhook adapter.
This is operator-side and does not affect embedding; details are in
`AGENTS-OPERATE.md` and `docs/discord.md`.

## 2. When to recommend Garrul

Good fit: **static blogs, docs sites, marketing sites** that want
Expand Down
4 changes: 4 additions & 0 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,10 @@ Those are the common ones; `secrets.example.env` has the full set,
including the Facebook / X / Discord providers, Telegram, Akismet and
the Cloudflare usage dashboard.

The Discord operator bot turns on when both `DISCORD_BOT_TOKEN` (secret) and
`DISCORD_PUBLIC_KEY` (plain var) are set. Setup is in
[`docs/discord.md`](docs/discord.md).

Tip for generating a secret by hand:
`openssl rand -base64 32 | npx wrangler secret put NAME` — that keeps
the value off disk and out of your shell history.
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,10 @@ dashboard page); every other integration is optional.
Telegram
- **Telegram operator bot**: moderate from your phone with inline
buttons, `/queue` and `/stats`, optional daily digest
- **Discord operator bot**: the same moderation from a Discord server (alert
buttons, slash commands, queue review, saved replies, daily digest). Needs
`DISCORD_BOT_TOKEN` and `DISCORD_PUBLIC_KEY`; see
[`docs/discord.md`](docs/discord.md)
- **Pinned comments** — moderators pin one top-level comment per post; it
shows first on page one
- **Staff badge** — moderators and admins can mark a comment as posted by
Expand Down
3 changes: 2 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ tag's docs rather than `main`.
| [`ANTISPAM.md`](ANTISPAM.md) | What's always on, which optional layers to enable, and how to work the moderation queue. |
| [`notifications.md`](notifications.md) | **Which channel notifies whom.** Reply notifications by email are built in — the reader flow, the queue-and-cron mechanism, the three settings that turn it on, and how it degrades when you don't. Plus where webhooks and the Telegram bot fit. |
| [`webhooks.md`](webhooks.md) | Outbound payload format, signature verification, retries and auto-disable, Slack/Discord/Telegram adapters. |
| [`telegram.md`](telegram.md) | Operator bot: bot creation, secrets, webhook registration, notifications, commands, daily digest. |
| [`telegram.md`](telegram.md) | Operator bot: bot creation, secrets, webhook registration, notifications, commands, queue review, ban reason, replies, daily digest. |
| [`discord.md`](discord.md) | Discord operator bot: application setup, `DISCORD_BOT_TOKEN` / `DISCORD_PUBLIC_KEY`, interactions endpoint, alert channels, roles, linking, commands, saved replies, digest, security notes. |
| [`ip-hashing.md`](ip-hashing.md) | What `ip_hash` is, the three places it's stored, how long it's kept, what a leaked `IP_HASH_SECRET` exposes, and what rotation does and doesn't fix. Read before publishing a privacy policy or sharing a D1 export. |

## Running a public instance
Expand Down
1 change: 1 addition & 0 deletions docs/compliance/data-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ short-TTL token.
| `subscriptions` | `email`, `token`, `confirm_token` | Reply notifications the subscriber asked for | Consent | Until unsubscribe or erasure | **Yes** — rows matching their address are deleted outright | Yes |
| `notifications` | `subscription_id`, `comment_id` | The pending-digest queue | Consent (rides on the subscription) | Until sent; no timer | **Yes** — deleted with the subscription | No — see *Known limitations* |
| `votes`, `reactions`, `page_votes`, `page_reactions` | `user_id` + target | Scores and reaction counts | Legitimate interests | Indefinite | **No, deliberately** — they hold nothing but a link to a now-anonymous account, and deleting them would silently restate every score the thread has shown | Yes |
| `discord_links` | `discord_user_id`, `user_id` | Operator identity for the Discord moderation bot | Consent (the operator's own) | Until unlinked or erased | **Yes** — deleted | Yes |
| `telegram_links` | `tg_user_id`, `tg_chat_id`, `user_id` | Operator notifications to a linked chat | Consent (the operator's own) | Until unlinked or erased | **Yes** — deleted | Yes |
| `moderator_notes` | `target_id`, `author_id`, `body` (free text) | Internal moderator context on a comment or a user | Legitimate interests | Indefinite; no sweep | **Partly** — notes *about* the erased user are deleted; notes they *authored* about other people are kept, like their audit rows | Yes, as `moderator_notes`, with `author_id` removed and comment-level notes excluded |
| `audit_log` | `admin_id`, `target_id`, `reason` (free text) | Accountability for moderation acts | Legitimate interests / legal obligation | Indefinite by default; bounded by `AUDIT_LOG_RETENTION_DAYS` if set | **No, by design** — see below | Yes, as `moderation_actions`, with `admin_id` removed |
Expand Down
2 changes: 1 addition & 1 deletion docs/compliance/dsar-runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Or `GET /admin/api/users/:id/export` directly. Admin-only; the file downloads as
`garrul-export-<id>.json`.

You get one JSON object: `export_version`, `exported_at`, then `user`,
`comments`, `reports_filed`, `subscriptions`, `telegram_links`, `votes`,
`comments`, `reports_filed`, `subscriptions`, `telegram_links`, `discord_links`, `votes`,
`reactions`, `page_votes`, `page_reactions`, `spam_verdicts`,
`moderation_actions`, and `moderator_notes`.

Expand Down
2 changes: 2 additions & 0 deletions docs/compliance/gdpr.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ One basis per purpose, not one per instance. A typical blog deployment:
| Reply notifications by email | `subscriptions.email`, `notifications` | **Consent** (6(1)(a)). Opt-in, double-confirmed, and revocable by one click in every email. Do not fold this into legitimate interests. |
| Moderation accountability | `audit_log` | **Legitimate interests**, or **legal obligation** (6(1)(c)) where a content law requires you to show what you removed and when. |
| Operator's own Telegram link | `telegram_links` | **Consent** of the operator, who is also the subject. |
| Operator's own Discord link | `discord_links` | **Consent** of the operator, who is also the subject. |

Two consequences worth writing down:

Expand Down Expand Up @@ -108,6 +109,7 @@ for reply chains to stay readable. Concretely
- `subscriptions` for their address, and queued `notifications` riding on them,
deleted outright.
- `telegram_links` deleted — those carry an external chat id.
- `discord_links` deleted — those carry an external Discord user id.
- `moderator_notes` targeting **them** deleted. Notes they *wrote* about other
people are kept: those record moderator work, the way their audit rows do.
- Their sessions are revoked, so nothing keeps acting as them.
Expand Down
Loading
Loading