umputun / tg-spam / 25134669663

83%

push

github

feat: short-message flood detection for unapproved users (#400)

* docs(claude): add wiring-layers checklist for new config parameters

Codifies the requirement that any new configurable parameter (CLI flag, env
var, or tunable knob) must be wired through CLI/env definition, DB-backed
config, web settings UI, e2e UI test, and README. Recurring source of
partially-broken features when one layer is missed.

* feat: add max-short-msg-count short-message flood detection

Adds an opt-in spam check that bans an unapproved user when their locator
message count minus approved count crosses --max-short-msg-count, and the
current message is short. Closes the gap left by content-based checks for
spammers probing the channel with innocuous one-word messages ("hi",
"hello", "yo") that individually evade similarity, classifier, LLM, and
duplicate detectors.

State is derived from the existing messages table via the
idx_messages_gid_user_id_time index — no new in-memory counter, no cache,
restart-resilient by construction. The check is implemented as an internal
method on Detector (isShortMsgFlood), gated by an outer guard so disabled
mode does no work, and bypasses LLM consensus by design (behavioral signal
not subject to content-based override).

Wired through all required layers per CLAUDE.md: CLI flag and env var
(--max-short-msg-count / MAX_SHORT_MSG_COUNT), DB-backed Settings with
zero-aware semantics, web settings UI form field plus read-only display,
e2e UI round-trip test, and README documentation. Respects training, dry,
and soft-ban modes via the existing pipeline. Disabled by default
(MaxShortMsgCount=0) and incompatible with paranoid mode (validated at
startup).

Related to #399

* docs(plans): max-short-msg-count implementation plan

Captures the design decisions, wiring layers, edge cases, and task
breakdown for the short-message flood detection feature. Filed under
completed/ since the implementation has landed.

Related to #399

* fix: trim README s... (continued)

95 of 97 new or added lines in 5 files covered. (97.94%)

8452 of 10132 relevant lines covered (83.42%)

227.44 hits per line