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

CHANGELOG.md

@@ -10,6 +10,8 @@
 
 ### Features
 
+- feat: |Admin| IP 黑名单设置新增 **IP 白名单（严格模式）**：启用后仅允许匹配白名单的 IP 访问受限流保护的 API（创建邮箱、发送邮件、外部发送邮件、用户注册、验证码校验），其他所有 IP 一律拒绝（#920）
+
 ### Bug Fixes
 
 - fix: |Admin| 修复 `/admin/address` 与 `/admin/users` 在使用完整邮箱（query 长度超过 50 字节）作为搜索条件时报错 `D1_ERROR: LIKE or GLOB pattern too complex` 的问题，长查询自动改用 `instr()` 绕开 D1 的 LIKE pattern 长度限制（#956）

CHANGELOG_EN.md

@@ -10,6 +10,8 @@
 
 ### Features
 
+- feat: |Admin| Add **IP Whitelist (strict mode)** to IP blacklist settings: when enabled, ONLY whitelisted IPs can access rate-limited APIs (create address, send mail, external send mail, user register, verify code); all other IPs are denied (#920)
+
 ### Bug Fixes
 
 - fix: |Admin| Fix `D1_ERROR: LIKE or GLOB pattern too complex` on `/admin/address` and `/admin/users` when searching by full email address (query length pushes the LIKE pattern over D1's 50-byte limit). Long queries now fall back to `instr()` to bypass the LIKE pattern length cap (#956)

e2e/tests/api/ip-whitelist.spec.ts

@@ -0,0 +1,232 @@
+import { test, expect } from '@playwright/test';
+import { WORKER_URL, createTestAddress } from '../../fixtures/test-helpers';
+
+const ADMIN_PASSWORD = 'e2e-admin-pass';
+
+test.describe('IP Whitelist Settings', () => {
+  test('get default IP whitelist settings returns disabled with empty list', async ({ request }) => {
+    const res = await request.get(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+    });
+    expect(res.ok()).toBe(true);
+    const settings = await res.json();
+    expect(settings.enableWhitelist).toBeFalsy();
+    expect(settings.whitelist).toEqual([]);
+  });
+
+  test('save and retrieve IP whitelist settings', async ({ request }) => {
+    // Save whitelist settings
+    const saveRes = await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: ['1.2.3.4', '^192\\.168\\.1\\.\\d+$'],
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+    expect(saveRes.ok()).toBe(true);
+    const saveBody = await saveRes.json();
+    expect(saveBody.success).toBe(true);
+
+    // Retrieve and verify
+    const getRes = await request.get(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+    });
+    expect(getRes.ok()).toBe(true);
+    const settings = await getRes.json();
+    expect(settings.enableWhitelist).toBe(true);
+    expect(settings.whitelist).toEqual(['1.2.3.4', '^192\\.168\\.1\\.\\d+$']);
+  });
+
+  test('whitelist rejects empty list when enabled', async ({ request }) => {
+    // Note: Frontend blocks this, but backend allows it (empty list = ignored)
+    // This test verifies backend behavior
+    const saveRes = await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: [],
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+    // Backend accepts empty whitelist (it will be ignored at runtime)
+    expect(saveRes.ok()).toBe(true);
+  });
+
+  test('whitelist validates array type', async ({ request }) => {
+    const saveRes = await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: 'not-an-array', // Invalid type
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+    expect(saveRes.ok()).toBe(false);
+    expect(saveRes.status()).toBe(400);
+  });
+
+  test('whitelist enforces max size limit', async ({ request }) => {
+    const largeList = Array.from({ length: 1001 }, (_, i) => `1.2.3.${i % 256}`);
+    const saveRes = await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: largeList,
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+    expect(saveRes.ok()).toBe(false);
+    expect(saveRes.status()).toBe(400);
+    const body = await saveRes.text();
+    expect(body).toContain('whitelist');
+    expect(body).toContain('1000');
+  });
+
+  test('backward compatibility: old frontend without whitelist fields', async ({ request }) => {
+    // Simulate old frontend that doesn't send enableWhitelist/whitelist
+    const saveRes = await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: true,
+        blacklist: ['10.0.0.1'],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        // enableWhitelist and whitelist omitted
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+    // Should succeed with defaults applied
+    expect(saveRes.ok()).toBe(true);
+
+    // Verify defaults were applied
+    const getRes = await request.get(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+    });
+    expect(getRes.ok()).toBe(true);
+    const settings = await getRes.json();
+    expect(settings.enableWhitelist).toBe(false);
+    expect(settings.whitelist).toEqual([]);
+  });
+
+  test('whitelist sanitizes patterns (trims and removes empty)', async ({ request }) => {
+    const saveRes = await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: ['  1.2.3.4  ', '', '   ', '5.6.7.8'],
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+    expect(saveRes.ok()).toBe(true);
+
+    const getRes = await request.get(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+    });
+    expect(getRes.ok()).toBe(true);
+    const settings = await getRes.json();
+    // Empty strings should be filtered out, whitespace trimmed
+    expect(settings.whitelist).toEqual(['1.2.3.4', '5.6.7.8']);
+  });
+});
+
+test.describe('IP Whitelist Runtime Behavior', () => {
+  test('whitelist with empty list allows requests (protection mode)', async ({ request }) => {
+    // Enable whitelist with empty list
+    await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: [],
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+
+    // Try to create address (rate-limited endpoint)
+    // Should succeed because empty whitelist is ignored
+    const res = await createTestAddress(request, 'whitelist-empty');
+    expect(res.jwt).toBeTruthy();
+    expect(res.address).toBeTruthy();
+  });
+
+  test('whitelist blocks requests when cf-connecting-ip is missing', async ({ request }) => {
+    // Enable whitelist with non-empty list
+    await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: true,
+        whitelist: ['1.2.3.4'],
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+
+    // Try to create address
+    // In e2e environment, cf-connecting-ip is likely missing
+    // Should be blocked with 403 (fail-closed)
+    const res = await request.post(`${WORKER_URL}/api/new_address`, {
+      data: { name: `whitelist-block-${Date.now()}`, domain: 'test.example.com' },
+    });
+
+    // Expect 403 if cf-connecting-ip is missing and whitelist is active
+    // OR success if cf-connecting-ip exists and matches
+    if (!res.ok()) {
+      expect(res.status()).toBe(403);
+      const body = await res.text();
+      expect(body).toContain('IP');
+    }
+  });
+
+  test.afterEach(async ({ request }) => {
+    // Reset whitelist to disabled after each test
+    await request.post(`${WORKER_URL}/admin/ip_blacklist/settings`, {
+      headers: { 'x-admin-auth': ADMIN_PASSWORD },
+      data: {
+        enabled: false,
+        blacklist: [],
+        asnBlacklist: [],
+        fingerprintBlacklist: [],
+        enableWhitelist: false,
+        whitelist: [],
+        enableDailyLimit: false,
+        dailyRequestLimit: 1000,
+      },
+    });
+  });
+});
+

frontend/src/views/admin/IpBlacklistSettings.vue

@@ -17,6 +17,12 @@ const { t } = useI18n({
             successTip: 'Save Success',
             enable_ip_blacklist: 'Enable IP Blacklist',
             enable_tip: 'Block IPs matching blacklist patterns from accessing rate-limited APIs',
+            enable_ip_whitelist: 'Enable IP Whitelist (Strict)',
+            enable_whitelist_tip: 'Strict mode: ONLY IPs matching the whitelist can access rate-limited APIs. All other IPs will be denied.',
+            ip_whitelist: 'IP Whitelist Patterns',
+            ip_whitelist_placeholder: 'Exact IP (e.g., 1.2.3.4) or anchored regex (e.g., ^192\\.168\\.1\\.\\d+$)',
+            tip_whitelist: 'IP Whitelist: Strict allowlist — plain entries must be EXACT IP matches (no substring). Use anchored regex (^...$) for ranges. Whitelisted IPs skip blacklist checks.',
+            whitelist_empty_warning: 'IP whitelist is enabled but the list is empty. This is ignored by the server to prevent lockout. Please add at least one entry before enabling.',
             ip_blacklist: 'IP Blacklist Patterns',
             ip_blacklist_placeholder: 'Enter pattern (e.g., 192.168.1 or ^10\\.0\\.0\\.5$)',
             asn_blacklist: 'ASN Organization Blacklist',
@@ -40,6 +46,12 @@ const { t } = useI18n({
             successTip: '保存成功',
             enable_ip_blacklist: '启用 IP 黑名单',
             enable_tip: '阻止匹配黑名单的 IP 访问限流 API',
+            enable_ip_whitelist: '启用 IP 白名单（严格模式）',
+            enable_whitelist_tip: '严格模式：仅允许匹配白名单的 IP 访问限流 API，其他所有 IP 将被拒绝',
+            ip_whitelist: 'IP 白名单匹配模式',
+            ip_whitelist_placeholder: '精确 IP(如 1.2.3.4)或锚定正则(如 ^192\\.168\\.1\\.\\d+$)',
+            tip_whitelist: 'IP 白名单: 严格放行名单——纯文本必须是精确 IP(不支持子串匹配), 批量放行请用锚定正则 ^...$. 命中白名单的 IP 将跳过黑名单检查.',
+            whitelist_empty_warning: 'IP 白名单已启用但列表为空，服务端将忽略该开关以防止锁死。请先添加至少一条白名单条目再启用。',
             ip_blacklist: 'IP 黑名单匹配模式',
             ip_blacklist_placeholder: '输入匹配模式（例如：192.168.1 或 ^10\\.0\\.0\\.5$）',
             asn_blacklist: 'ASN 组织（运营商）黑名单',
@@ -63,6 +75,8 @@ const enabled = ref(false)
 const ipBlacklist = ref([])
 const asnBlacklist = ref([])
 const fingerprintBlacklist = ref([])
+const enableWhitelist = ref(false)
+const ipWhitelist = ref([])
 const enableDailyLimit = ref(false)
 const dailyRequestLimit = ref(1000)
 
@@ -74,6 +88,8 @@ const fetchData = async () => {
         ipBlacklist.value = res.blacklist || []
         asnBlacklist.value = res.asnBlacklist || []
         fingerprintBlacklist.value = res.fingerprintBlacklist || []
+        enableWhitelist.value = res.enableWhitelist || false
+        ipWhitelist.value = res.whitelist || []
         enableDailyLimit.value = res.enableDailyLimit || false
         dailyRequestLimit.value = res.dailyRequestLimit || 1000
     } catch (error) {
@@ -84,6 +100,10 @@ const fetchData = async () => {
 }
 
 const save = async () => {
+    if (enableWhitelist.value && (!ipWhitelist.value || ipWhitelist.value.length === 0)) {
+        message.warning(t('whitelist_empty_warning'))
+        return
+    }
     try {
         loading.value = true
         await api.fetch(`/admin/ip_blacklist/settings`, {
@@ -93,6 +113,8 @@ const save = async () => {
                 blacklist: ipBlacklist.value || [],
                 asnBlacklist: asnBlacklist.value || [],
                 fingerprintBlacklist: fingerprintBlacklist.value || [],
+                enableWhitelist: enableWhitelist.value,
+                whitelist: ipWhitelist.value || [],
                 enableDailyLimit: enableDailyLimit.value,
                 dailyRequestLimit: dailyRequestLimit.value
             })
@@ -123,6 +145,7 @@ onMounted(async () => {
                 <n-alert :show-icon="false" :bordered="false" type="info">
                     <div style="line-height: 1.8;">
                         <div><strong>{{ t("tip_scope") }}</strong></div>
+                        <div>• {{ t("tip_whitelist") }}</div>
                         <div>• {{ t("tip_ip") }}</div>
                         <div>• {{ t("tip_asn") }}</div>
                         <div>• {{ t("tip_fingerprint") }}</div>
@@ -130,6 +153,31 @@ onMounted(async () => {
                     </div>
                 </n-alert>
 
+                <n-form-item-row :label="t('enable_ip_whitelist')">
+                    <n-switch v-model:value="enableWhitelist" :round="false" />
+                    <n-text depth="3" style="margin-left: 10px; font-size: 12px;">
+                        {{ t('enable_whitelist_tip') }}
+                    </n-text>
+                </n-form-item-row>
+
+                <n-form-item-row :label="t('ip_whitelist')">
+                    <n-select
+                        v-model:value="ipWhitelist"
+                        filterable
+                        multiple
+                        tag
+                        :placeholder="t('ip_whitelist_placeholder')"
+                        :disabled="!enableWhitelist">
+                        <template #empty>
+                            <n-text depth="3">
+                                {{ t('manualInputPrompt') }}
+                            </n-text>
+                        </template>
+                    </n-select>
+                </n-form-item-row>
+
+                <n-divider />
+
                 <n-form-item-row :label="t('enable_ip_blacklist')">
                     <n-switch v-model:value="enabled" :round="false" />
                     <n-text depth="3" style="margin-left: 10px; font-size: 12px;">

worker/src/admin_api/ip_blacklist_settings.ts

@@ -18,6 +18,8 @@ async function getIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Respo
         blacklist: [],
         asnBlacklist: [],
         fingerprintBlacklist: [],
+        enableWhitelist: false,
+        whitelist: [],
         enableDailyLimit: false,
         dailyRequestLimit: 1000
     });
@@ -30,6 +32,10 @@ async function saveIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Resp
     const msgs = i18n.getMessagesbyContext(c);
     const settings = await c.req.json<IpBlacklistSettings>();
 
+    // Backward compatibility: default new fields if absent (older frontends)
+    settings.enableWhitelist = settings.enableWhitelist ?? false;
+    settings.whitelist = settings.whitelist ?? [];
+
     // Validate settings
     if (typeof settings.enabled !== 'boolean') {
         return c.text(`${msgs.InvalidIpBlacklistSettingMsg}: enabled`, 400);
@@ -47,6 +53,14 @@ async function saveIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Resp
         return c.text(`${msgs.InvalidIpBlacklistSettingMsg}: fingerprintBlacklist`, 400);
     }
 
+    if (typeof settings.enableWhitelist !== 'boolean') {
+        return c.text(`${msgs.InvalidIpBlacklistSettingMsg}: enableWhitelist`, 400);
+    }
+
+    if (!Array.isArray(settings.whitelist)) {
+        return c.text(`${msgs.InvalidIpBlacklistSettingMsg}: whitelist`, 400);
+    }
+
     if (typeof settings.enableDailyLimit !== 'boolean') {
         return c.text(`${msgs.InvalidIpBlacklistSettingMsg}: enableDailyLimit`, 400);
     }
@@ -70,6 +84,10 @@ async function saveIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Resp
         return c.text(`${msgs.BlacklistExceedsMaxSizeMsg}: fingerprintBlacklist (${MAX_BLACKLIST_SIZE})`, 400);
     }
 
+    if (settings.whitelist.length > MAX_BLACKLIST_SIZE) {
+        return c.text(`${msgs.BlacklistExceedsMaxSizeMsg}: whitelist (${MAX_BLACKLIST_SIZE})`, 400);
+    }
+
     // Sanitize patterns (trim and remove empty strings)
     // Both regex and plain strings are allowed
     const sanitizedBlacklist = settings.blacklist
@@ -84,11 +102,17 @@ async function saveIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Resp
         .map(pattern => pattern.trim())
         .filter(pattern => pattern.length > 0);
 
+    const sanitizedWhitelist = settings.whitelist
+        .map(pattern => pattern.trim())
+        .filter(pattern => pattern.length > 0);
+
     const sanitizedSettings: IpBlacklistSettings = {
         enabled: settings.enabled,
         blacklist: sanitizedBlacklist,
         asnBlacklist: sanitizedAsnBlacklist,
         fingerprintBlacklist: sanitizedFingerprintBlacklist,
+        enableWhitelist: settings.enableWhitelist,
+        whitelist: sanitizedWhitelist,
         enableDailyLimit: settings.enableDailyLimit,
         dailyRequestLimit: settings.dailyRequestLimit
     };

worker/src/ip_blacklist.ts

@@ -10,6 +10,8 @@ export type IpBlacklistSettings = {
     blacklist?: string[];  // Array of regex patterns or plain strings
     asnBlacklist?: string[];  // Array of ASN organization patterns (e.g., "Google LLC", "Amazon")
     fingerprintBlacklist?: string[];  // Array of browser fingerprint patterns
+    enableWhitelist?: boolean;  // Enable IP whitelist (strict allowlist mode)
+    whitelist?: string[];  // Array of exact IPs or anchored regex; only matching IPs are allowed
     enableDailyLimit?: boolean;  // Enable daily request limit per IP
     dailyRequestLimit?: number;  // Maximum requests per IP per day
 }
@@ -78,6 +80,56 @@ function isBlacklisted(value: string | null | undefined, blacklist: string[], ca
     });
 }
 
+/**
+ * Whitelist-style match: strict allowlist, independent from blacklist semantics.
+ * Plain IPv4/IPv6 entries are matched EXACTLY (not as regex) to avoid unintended matches.
+ * Only explicit regex patterns (containing metacharacters beyond dots/colons) are treated as regex.
+ *
+ * Examples:
+ *   "1.2.3.4"              → exact match only (NOT treated as regex /1.2.3.4/)
+ *   "2001:db8::1"          → exact match only
+ *   "^192\\.168\\.1\\.\\d+$" → regex (contains anchors/escapes)
+ */
+function isWhitelisted(value: string | null | undefined, whitelist: string[] | undefined): boolean {
+    if (!value || !whitelist || whitelist.length === 0) {
+        return false;
+    }
+
+    const normalizedValue = value.trim();
+
+    return whitelist.some(pattern => {
+        const normalizedPattern = pattern.trim();
+        if (!normalizedPattern) {
+            return false;
+        }
+
+        // IPv4 detection: digits and dots only → exact match (bypass regex heuristic)
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(normalizedPattern)) {
+            return normalizedValue === normalizedPattern;
+        }
+
+        // IPv6 detection: hex digits and colons → exact match
+        if (/^[0-9a-fA-F:]+$/.test(normalizedPattern) && normalizedPattern.includes(':')) {
+            return normalizedValue === normalizedPattern;
+        }
+
+        // Regex detection: contains metacharacters beyond dots/colons
+        if (looksLikeRegex(normalizedPattern)) {
+            try {
+                const regex = new RegExp(normalizedPattern);
+                return regex.test(normalizedValue);
+            } catch (error) {
+                // Invalid regex in a whitelist = never match (fail closed)
+                console.warn(`Whitelist regex "${normalizedPattern}" failed to parse, treating as no-match`);
+                return false;
+            }
+        }
+
+        // Fallback: other plain strings → exact match
+        return normalizedValue === normalizedPattern;
+    });
+}
+
 /**
  * Get IP blacklist settings from database
  *
@@ -93,75 +145,134 @@ export async function getIpBlacklistSettings(
 }
 
 /**
- * Middleware to check access control (blacklist and rate limiting) for rate-limited endpoints
- * Returns 403/429 response if blocked, null if allowed or any error occurs
+ * Layer 1 — IP whitelist check (strict allowlist mode).
+ * Independent from blacklist. Fails closed when client IP is missing.
  *
- * @param c - Hono context
- * @returns Response if blocked, null otherwise (including errors)
+ * Returns:
+ *   - { response }     — request is blocked (403)
+ *   - { hit: true }    — whitelist active and the IP matched (trusted, skip blacklist)
+ *   - { hit: false }   — whitelist not active or list empty (proceed normally)
+ */
+function checkIpWhitelist(
+    c: Context<HonoCustomType>,
+    settings: IpBlacklistSettings,
+    reqIp: string | null
+): { response?: Response; hit: boolean } {
+    const active = !!(settings.enableWhitelist && settings.whitelist && settings.whitelist.length > 0);
+    if (!active) return { hit: false };
+
+    if (!reqIp) {
+        console.warn(`Blocked request without cf-connecting-ip under whitelist mode for path: ${c.req.path}`);
+        return { response: c.text(`Access denied: client IP unavailable`, 403), hit: false };
+    }
+
+    if (isWhitelisted(reqIp, settings.whitelist)) {
+        return { hit: true };
+    }
+
+    console.warn(`Blocked non-whitelisted IP: ${reqIp} for path: ${c.req.path}`);
+    return { response: c.text(`Access denied: IP ${reqIp} is not whitelisted`, 403), hit: false };
+}
+
+/**
+ * Layer 2 — Blacklist check (IP + ASN + fingerprint), gated by the single `enabled` flag.
+ * Returns a 403 Response if any blacklist hits, null otherwise.
+ */
+function checkBlacklist(
+    c: Context<HonoCustomType>,
+    settings: IpBlacklistSettings,
+    reqIp: string
+): Response | null {
+    if (!settings.enabled) return null;
+
+    // Check if IP is blacklisted (case-sensitive matching)
+    if (settings.blacklist && settings.blacklist.length > 0) {
+        if (isBlacklisted(reqIp, settings.blacklist, true)) {
+            console.warn(`Blocked blacklisted IP: ${reqIp} for path: ${c.req.path}`);
+            return c.text(`Access denied: IP ${reqIp} is blacklisted`, 403);
+        }
+    }
+
+    // Check ASN organization blacklist (case-insensitive)
+    if (settings.asnBlacklist && settings.asnBlacklist.length > 0) {
+        const asOrganization = c.req.raw.cf?.asOrganization;
+        if (asOrganization && isBlacklisted(asOrganization as string, settings.asnBlacklist, false)) {
+            console.warn(`Blocked blacklisted ASN: ${asOrganization} (IP: ${reqIp}) for path: ${c.req.path}`);
+            return c.text(`Access denied: ASN organization is blacklisted`, 403);
+        }
+    }
+
+    // Check browser fingerprint blacklist (case-sensitive)
+    if (settings.fingerprintBlacklist && settings.fingerprintBlacklist.length > 0) {
+        const fingerprint = c.req.raw.headers.get("x-fingerprint");
+        if (fingerprint && isBlacklisted(fingerprint, settings.fingerprintBlacklist, true)) {
+            console.warn(`Blocked blacklisted fingerprint: ${fingerprint} (IP: ${reqIp}) for path: ${c.req.path}`);
+            return c.text(`Access denied: Browser fingerprint is blacklisted`, 403);
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Layer 3 — Daily request limit per IP. Always runs (protects backend resources).
+ */
+async function checkDailyLimit(
+    c: Context<HonoCustomType>,
+    settings: IpBlacklistSettings,
+    reqIp: string
+): Promise<Response | null> {
+    if (!settings.enableDailyLimit || !settings.dailyRequestLimit || !c.env.KV) {
+        return null;
+    }
+
+    const daily_count_key = `limit|${reqIp}|${new Date().toISOString().slice(0, 10)}`;
+    const dailyLimit = settings.dailyRequestLimit;
+    const current_count = parseInt(await c.env.KV.get(daily_count_key) || "0", 10);
+
+    if (current_count && current_count >= dailyLimit) {
+        console.warn(`Blocked IP ${reqIp} exceeded daily limit of ${dailyLimit} requests for path: ${c.req.path}`);
+        return c.text(`IP=${reqIp} Exceeded daily limit of ${dailyLimit} requests`, 429);
+    }
+
+    // Increment counter with 24-hour expiration
+    await c.env.KV.put(daily_count_key, ((current_count || 0) + 1).toString(), { expirationTtl: 24 * 60 * 60 });
+    return null;
+}
+
+/**
+ * Middleware to check access control for rate-limited endpoints.
+ * Composes three independent layers in order:
+ *   Layer 1 — IP whitelist (strict allowlist; hit = trust, skip blacklist)
+ *   Layer 2 — Blacklist (IP / ASN / fingerprint)
+ *   Layer 3 — Daily request limit
+ *
+ * Returns 403/429 response if blocked, null if allowed or any error occurs.
  */
 export async function checkAccessControl(
     c: Context<HonoCustomType>
 ): Promise<Response | null> {
     try {
-        // Get IP blacklist settings from database
         const settings = await getIpBlacklistSettings(c);
-        if (!settings) {
-            return null;
-        }
+        if (!settings) return null;
 
-        // Get IP address from CloudFlare header
         const reqIp = c.req.raw.headers.get("cf-connecting-ip");
-        if (!reqIp) {
-            return null;
+
+        // Layer 1: whitelist
+        const whitelistResult = checkIpWhitelist(c, settings, reqIp);
+        if (whitelistResult.response) return whitelistResult.response;
+
+        // Without a client IP, skip IP-keyed layers below
+        if (!reqIp) return null;
+
+        // Layer 2: blacklist (skipped when whitelist trusted the IP)
+        if (!whitelistResult.hit) {
+            const blacklistResp = checkBlacklist(c, settings, reqIp);
+            if (blacklistResp) return blacklistResp;
         }
 
-        // Check if blacklist feature is enabled
-        if (settings.enabled) {
-            // Check if IP is blacklisted (case-sensitive matching)
-            if (settings.blacklist && settings.blacklist.length > 0) {
-                if (isBlacklisted(reqIp, settings.blacklist, true)) {
-                    console.warn(`Blocked blacklisted IP: ${reqIp} for path: ${c.req.path}`);
-                    return c.text(`Access denied: IP ${reqIp} is blacklisted`, 403);
-                }
-            }
-
-            // Check ASN organization blacklist
-            if (settings.asnBlacklist && settings.asnBlacklist.length > 0) {
-                const asOrganization = c.req.raw.cf?.asOrganization;
-                // Check ASN with case-insensitive matching
-                if (asOrganization && isBlacklisted(asOrganization as string, settings.asnBlacklist, false)) {
-                    console.warn(`Blocked blacklisted ASN: ${asOrganization} (IP: ${reqIp}) for path: ${c.req.path}`);
-                    return c.text(`Access denied: ASN organization is blacklisted`, 403);
-                }
-            }
-
-            // Check browser fingerprint blacklist
-            if (settings.fingerprintBlacklist && settings.fingerprintBlacklist.length > 0) {
-                const fingerprint = c.req.raw.headers.get("x-fingerprint");
-                // Check fingerprint with case-sensitive matching
-                if (fingerprint && isBlacklisted(fingerprint, settings.fingerprintBlacklist, true)) {
-                    console.warn(`Blocked blacklisted fingerprint: ${fingerprint} (IP: ${reqIp}) for path: ${c.req.path}`);
-                    return c.text(`Access denied: Browser fingerprint is blacklisted`, 403);
-                }
-            }
-        }
-
-        // Check daily request limit (independent of blacklist feature)
-        if (settings.enableDailyLimit && settings.dailyRequestLimit && c.env.KV) {
-            const daily_count_key = `limit|${reqIp}|${new Date().toISOString().slice(0, 10)}`;
-            const dailyLimit = settings.dailyRequestLimit;
-            const current_count = parseInt(await c.env.KV.get(daily_count_key) || "0", 10);
-
-            if (current_count && current_count >= dailyLimit) {
-                console.warn(`Blocked IP ${reqIp} exceeded daily limit of ${dailyLimit} requests for path: ${c.req.path}`);
-                return c.text(`IP=${reqIp} Exceeded daily limit of ${dailyLimit} requests`, 429);
-            }
-
-            // Increment counter with 24-hour expiration
-            await c.env.KV.put(daily_count_key, ((current_count || 0) + 1).toString(), { expirationTtl: 24 * 60 * 60 });
-        }
-
-        return null;
+        // Layer 3: daily limit (always enforced)
+        return await checkDailyLimit(c, settings, reqIp);
     } catch (error) {
         // Log error but don't block request
         console.error('Error checking IP blacklist and rate limit:', error);