feat(admin): add IP whitelist (strict allowlist mode) (#920) (#971)

* feat(admin): add IP whitelist (strict allowlist mode) (#920)

- Add enableWhitelist/whitelist fields to IpBlacklistSettings
- Implement three-layer access control: whitelist → blacklist → daily limit
- Whitelist uses exact match for IPv4/IPv6, regex for patterns
- Whitelisted IPs skip blacklist checks (trusted)
- Fail-closed when cf-connecting-ip missing under whitelist mode
- Frontend: independent whitelist toggle + empty list protection
- Backend: backward compatible (old frontends get defaults)
- E2E tests: config validation + runtime behavior
- Docs: CHANGELOG zh/en updated

Closes #920

* fix(admin): address PR review feedback on IP whitelist

- Add IPv4-mapped IPv6 (::ffff:x.x.x.x) exact match in isWhitelisted
- Include error.message in whitelist regex parse failure log
- Include actual/max size in whitelist size limit error message

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(admin): validate whitelist regex on save and preserve existing whitelist on partial update

- Reject invalid regex patterns in whitelist at save time to prevent runtime lockout
- Preserve existing enableWhitelist/whitelist from DB when older clients omit these fields

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(admin): revert P2 - keep simple ?? defaults for backward compat

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(admin): validate whitelist elements are strings before trimming

Prevents 500 error when whitelist contains non-string elements (e.g. numbers, null)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs(admin): add IP blacklist/whitelist documentation (zh + en)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(admin): fix fingerprint blacklist bypass when cf-connecting-ip absent, improve e2e tests

- Split checkBlacklist into checkFingerprintBlacklist (IP-independent) and checkIpAsnBlacklist
- Fingerprint check now runs before the !reqIp early-return to prevent bypass
- Add afterEach reset to config test group, extract RESET_SETTINGS constant
- Strengthen whitelist-blocks test to deterministic 403 assertion
- Add e2e tests: invalid regex rejection, non-string element rejection, fingerprint-blocks-without-IP

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(admin): suppress no-useless-escape lint warning in whitelist regex check

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

vitepress-docs/docs/en/guide/feature/admin.md

@@ -26,3 +26,32 @@ When searching for email addresses, pagination automatically resets to page 1.
 ## If your website is for private access only, you can disable this check
 
 `DISABLE_ADMIN_PASSWORD_CHECK = true`
+
+## IP Blacklist / Whitelist
+
+Configure access control in Admin Console → **IP Blacklist Settings**. Applies to: create address, send mail, external send mail API, user registration, and verify code endpoints.
+
+### IP Whitelist (Strict Mode)
+
+When enabled, **only** whitelisted IPs can access protected endpoints; all others receive 403.
+
+- Plain entries: exact match (no substring), e.g. `1.2.3.4`
+- Regex entries: use anchored patterns, e.g. `^192\.168\.1\.\d+$`
+- Whitelisted IPs skip blacklist checks
+- If whitelist is enabled but the list is empty, the server ignores the switch (fail-open to prevent lockout)
+
+### IP Blacklist
+
+When enabled, matching IPs receive 403. Supports substring text matching or regex.
+
+### ASN Organization Blacklist
+
+Block by ISP/provider name, case-insensitive. Supports text or regex matching.
+
+### Browser Fingerprint Blacklist
+
+Block by `x-fingerprint` request header. Supports exact or regex matching.
+
+### Daily Request Limit
+
+Limit the maximum number of requests per IP per day (1–1,000,000). Exceeding the limit returns 429. Counter resets every 24 hours (UTC date boundary).

vitepress-docs/docs/zh/guide/feature/admin.md

@@ -26,3 +26,32 @@
 ## 如果你的网站只可私人访问，可通过此禁用检查
 
 `DISABLE_ADMIN_PASSWORD_CHECK = true`
+
+## IP 黑名单 / 白名单
+
+在 Admin 控制台 → **IP 黑名单设置** 页面可配置访问控制，作用于以下接口：创建邮箱地址、发送邮件、外部发送邮件 API、用户注册、验证码校验。
+
+### IP 白名单（严格模式）
+
+启用后，**仅**匹配白名单的 IP 才能访问受保护接口，其他所有 IP 一律返回 403。
+
+- 纯文本条目：精确匹配（不支持子串），例如 `1.2.3.4`
+- 正则条目：使用锚定正则，例如 `^192\.168\.1\.\d+$`
+- 白名单命中的 IP 会跳过黑名单检查
+- 白名单启用但列表为空时，服务端忽略该开关（防止锁死）
+
+### IP 黑名单
+
+启用后，匹配黑名单的 IP 返回 403。支持文本子串匹配或正则表达式。
+
+### ASN 组织黑名单
+
+按运营商/ISP 拉黑，不区分大小写，支持文本匹配或正则。
+
+### 浏览器指纹黑名单
+
+按 `x-fingerprint` 请求头拉黑，支持精确匹配或正则。
+
+### 每日请求限流
+
+限制单个 IP 每天最多请求次数（1–1,000,000），超出返回 429。计数以 UTC 日期为周期，24 小时后自动重置。