docs: trusted_member_group_ids nil-vs-[] semantics + cooldown priority; v3.9.1 changelog

Author: Zakkaus

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [3.9.1] - 2026-06-23
+
+### Fixed
+Two access-control boundary fixes on the v3.9.0 trusted-member bypass (review follow-up):
+- **A per-group `trusted_member_group_ids` can now explicitly DISABLE the bypass with `[]`** — the
+  resolver distinguishes an OMITTED field (inherit the global) from an explicit empty array (opt out
+  for that group). Previously both inherited the global, so a sensitive group couldn't opt out of a
+  global trusted source.
+- **A trusted member now takes priority over the failure cooldown** — the trusted-member check runs
+  *before* the anti-spam cooldown, so a verified member of a trusted group who had a prior failed
+  verify is auto-approved (and their strikes cleared) instead of being silently declined by the
+  cooldown. A confirmed trusted member whose auto-approve fails proceeds to normal verification and is
+  NOT cooldown-declined; only a non-member / unconfirmable applicant is subject to the cooldown.
+- Tests: gate-level `TestJoinGate` (the cooldown ordering — the integration branch the per-function
+  test missed) and the explicit-`[]`-disables resolver + LoadConfig cases.
+
 ## [3.9.0] - 2026-06-23
 
 ### Added

README.md

@@ -97,7 +97,7 @@ Everything else lives in `config.json` (copy `config.example.json`):
 | `verify_retry_seconds` | a declined applicant must wait this long before re-applying (default 180; negative = no cooldown) |
 | `verify_max_fails` | failed verifications before an applicant is auto-banned (default 3; negative = never auto-ban) |
 | `required_channel_fail_open` | when the bot can't read the required channel's membership, let verified applicants through (`true`, default) or hold them back (`false`). Admins are alerted either way |
-| `trusted_member_group_ids` | **trusted-member bypass**: an applicant who is **already a member of any of these chats** is auto-approved without a quiz (e.g. a sub-group trusting the main group's members). **Global default; override per-group** in `groups`. Use real chat ids (groups are `-100…`); the bot must be in each listed chat to read membership (they're treated as known chats, never auto-left). Unlike a required channel this **fails closed** — if membership can't be confirmed, the applicant just does the normal verification |
+| `trusted_member_group_ids` | **trusted-member bypass**: an applicant who is **already a member of any of these chats** is auto-approved without a quiz (e.g. a sub-group trusting the main group's members). **Global default; per-group**: omit to inherit the global, `[]` to **disable** for that group, or list ids to override. Use real chat ids (groups are `-100…`); the bot must be in each listed chat to read membership (treated as known chats, never auto-left). A trusted member takes **priority over the failure cooldown** (they're approved + their strikes cleared even after a prior failed verify). Unlike a required channel this **fails closed** — if membership can't be confirmed the applicant just does the normal verification |
 | `admin_log_chat_id` | optional chat that receives a line per moderation / failed-approve event |
 | `overlays` | `/pkg` GitHub overlays `[{name,repo,branch}]` (default: gentoo-zh + guru) |
 | `news_url` | `/news` source index URL (default: gentoo.org news-items) |

README.zh-CN.md

@@ -82,7 +82,7 @@ GITHUB_TOKEN=ghp_xxx
 | `verify_retry_seconds` | 被拒申请人需等待多久才能重新申请(默认 180;负数 = 无冷却) |
 | `verify_max_fails` | 连续验证失败多少次后自动封禁(默认 3;负数 = 永不自动封禁) |
 | `required_channel_fail_open` | 当 bot 读不到必关频道成员状态时,放行已答题的申请人(`true`,默认)还是拦下(`false`)。两种情况都会告警管理员 |
-| `trusted_member_group_ids` | **可信成员免验证**:申请人若**已经是这些群之一的成员**,直接批准、跳过答题(例:子群信任主群的成员)。**全局默认,可在 `groups` 里按群覆盖**。用真实 chat id(群是 `-100…`);bot 必须在每个列出的群里才能读成员状态(它们会被当作已知聊天、不会被自动退出)。与必关频道不同,这里**fail-closed**——读不到成员身份就走正常验证,绝不直接放行 |
+| `trusted_member_group_ids` | **可信成员免验证**:申请人若**已经是这些群之一的成员**,直接批准、跳过答题(例:子群信任主群的成员)。**全局默认;按群**:省略=继承全局,写 `[]`=本群**关闭**,写 id 列表=覆盖全局。用真实 chat id(群是 `-100…`);bot 必须在每个列出的群里才能读成员状态(当作已知聊天、不会被自动退出)。可信成员**优先于失败冷却**(即使之前验证失败被冷却,也会被直接放行并清空 strike)。与必关频道不同,这里**fail-closed**——读不到成员身份就走正常验证,绝不直接放行 |
 | `admin_log_chat_id` | 可选:接收每次管理操作 / 批准失败的日志 |
 | `overlays` | `/pkg` 的 GitHub overlay `[{name,repo,branch}]`(默认 gentoo-zh + guru) |
 | `news_url` | `/news` 源索引 URL(默认 gentoo.org) |