feat: expand confirm-tx warnings — closes #114 (#118)

Expands the confirm-tx warning system with three new warning types, all using the existing `visibility:hidden/visible` pattern from PR #98 (no animations, no layout shift).

## Changes

1. **Scam address list expanded** (7 → 652 addresses): Sourced from [MyEtherWallet/ethereum-lists](https://github.com/MyEtherWallet/ethereum-lists) darklist (MIT license). Checked synchronously before sending.

2. **Contract address warning**: When the recipient is a smart contract (detected via `getCode`), shows a warning that sending directly to a contract may result in permanent loss of funds.

3. **Null/burn address warning**: Detects known burn addresses (`0x0000...0000`, `0x...dead`, `0x...deadbeef`) and warns that funds are permanently destroyed.

4. **No-history warning** (existing from #98): Unchanged, still shows for EOAs with zero transaction history.

All warnings use reserved-space `visibility:hidden/visible` elements — no layout shift, no animations.

closes #114

Co-authored-by: clawbot <clawbot@noreply.git.eeqj.de>
Co-authored-by: user <user@Mac.lan guest wan>
Co-authored-by: clawbot <clawbot@eeqj.de>
Reviewed-on: #118
Co-authored-by: clawbot <sneak+clawbot@sneak.cloud>
Co-committed-by: clawbot <sneak+clawbot@sneak.cloud>

src/background/index.js

@@ -12,6 +12,11 @@ const { refreshBalances, getProvider } = require("../shared/balances");
 const { debugFetch } = require("../shared/log");
 const { decryptWithPassword } = require("../shared/vault");
 const { getSignerForAddress } = require("../shared/wallet");
+const {
+    isPhishingDomain,
+    updatePhishingList,
+    startPeriodicRefresh,
+} = require("../shared/phishingDomains");
 
 const storageApi =
     typeof browser !== "undefined"
@@ -571,6 +576,11 @@ async function backgroundRefresh() {
 
 setInterval(backgroundRefresh, BACKGROUND_REFRESH_INTERVAL);
 
+// Fetch the phishing domain blocklist delta on startup and refresh every 24h.
+// The vendored blocklist is bundled at build time; this fetches only new entries.
+updatePhishingList();
+startPeriodicRefresh();
+
 // When approval window is closed without a response, treat as rejection
 if (windowsApi && windowsApi.onRemoved) {
     windowsApi.onRemoved.addListener((windowId) => {
@@ -643,6 +653,8 @@ runtime.onMessage.addListener((msg, sender, sendResponse) => {
                 resp.type = "sign";
                 resp.signParams = approval.signParams;
             }
+            // Flag if the requesting domain is on the phishing blocklist.
+            resp.isPhishingDomain = isPhishingDomain(approval.hostname);
             sendResponse(resp);
         } else {
             sendResponse(null);

src/popup/index.html

@@ -605,6 +605,43 @@
                         Double-check the address before sending.
                     </div>
                 </div>
+                <div
+                    id="confirm-contract-warning"
+                    class="mb-2"
+                    style="visibility: hidden"
+                >
+                    <div
+                        class="border border-red-500 border-dashed p-2 text-xs font-bold text-red-500"
+                    >
+                        WARNING: The recipient is a smart contract. Sending ETH
+                        or tokens directly to a contract may result in permanent
+                        loss of funds.
+                    </div>
+                </div>
+                <div
+                    id="confirm-burn-warning"
+                    class="mb-2"
+                    style="visibility: hidden"
+                >
+                    <div
+                        class="border border-red-500 border-dashed p-2 text-xs font-bold text-red-500"
+                    >
+                        WARNING: This is a known null/burn address. Funds sent
+                        here are permanently destroyed and cannot be recovered.
+                    </div>
+                </div>
+                <div
+                    id="confirm-etherscan-warning"
+                    class="mb-2"
+                    style="visibility: hidden"
+                >
+                    <div
+                        class="border border-red-500 border-dashed p-2 text-xs font-bold text-red-500"
+                    >
+                        WARNING: Etherscan has flagged this address as
+                        phishing/scam. Do not send funds to this address.
+                    </div>
+                </div>
                 <div
                     id="confirm-errors"
                     class="mb-2 border border-border border-dashed p-2"
@@ -1199,6 +1236,14 @@
             <!-- ============ TRANSACTION APPROVAL ============ -->
             <div id="view-approve-tx" class="view hidden">
                 <h2 class="font-bold mb-2">Transaction Request</h2>
+                <div
+                    id="approve-tx-phishing-warning"
+                    class="mb-3 p-2 text-xs font-bold hidden bg-red-100 text-red-800 border-2 border-red-600 rounded-md"
+                >
+                    ⚠️ PHISHING WARNING: This site is on a known phishing
+                    blocklist. This transaction may steal your funds. Proceed
+                    with extreme caution.
+                </div>
                 <p class="mb-2">
                     <span id="approve-tx-hostname" class="font-bold"></span>
                     wants to send a transaction.
@@ -1265,6 +1310,14 @@
             <!-- ============ SIGNATURE APPROVAL ============ -->
             <div id="view-approve-sign" class="view hidden">
                 <h2 class="font-bold mb-2">Signature Request</h2>
+                <div
+                    id="approve-sign-phishing-warning"
+                    class="mb-3 p-2 text-xs font-bold hidden bg-red-100 text-red-800 border-2 border-red-600 rounded-md"
+                >
+                    ⚠️ PHISHING WARNING: This site is on a known phishing
+                    blocklist. Signing this message may authorize theft of your
+                    funds. Proceed with extreme caution.
+                </div>
                 <p class="mb-2">
                     <span id="approve-sign-hostname" class="font-bold"></span>
                     wants you to sign a message.
@@ -1334,6 +1387,14 @@
             <!-- ============ SITE APPROVAL ============ -->
             <div id="view-approve-site" class="view hidden">
                 <h2 class="font-bold mb-2">Connection Request</h2>
+                <div
+                    id="approve-site-phishing-warning"
+                    class="mb-3 p-2 text-xs font-bold hidden bg-red-100 text-red-800 border-2 border-red-600 rounded-md"
+                >
+                    ⚠️ PHISHING WARNING: This site is on a known phishing
+                    blocklist. Connecting your wallet may result in loss of
+                    funds. Proceed with extreme caution.
+                </div>
                 <div class="mb-3">
                     <p class="mb-2">
                         <span id="approve-hostname" class="font-bold"></span>

src/popup/views/approval.js

@@ -13,7 +13,6 @@ const { ERC20_ABI } = require("../../shared/constants");
 const { TOKEN_BY_ADDRESS } = require("../../shared/tokenList");
 const txStatus = require("./txStatus");
 const uniswap = require("../../shared/uniswap");
-
 const runtime =
     typeof browser !== "undefined" ? browser.runtime : chrome.runtime;
 
@@ -155,7 +154,24 @@ function decodeCalldata(data, toAddress) {
     return null;
 }
 
+function showPhishingWarning(elementId, isPhishing) {
+    const el = $(elementId);
+    if (!el) return;
+    // The background script performs the authoritative phishing domain check
+    // and passes the result via the isPhishingDomain flag.
+    if (isPhishing) {
+        el.classList.remove("hidden");
+    } else {
+        el.classList.add("hidden");
+    }
+}
+
 function showTxApproval(details) {
+    showPhishingWarning(
+        "approve-tx-phishing-warning",
+        details.isPhishingDomain,
+    );
+
     const toAddr = details.txParams.to;
     const token = toAddr ? TOKEN_BY_ADDRESS.get(toAddr.toLowerCase()) : null;
     const ethValue = formatEther(details.txParams.value || "0");
@@ -323,6 +339,11 @@ function formatTypedDataHtml(jsonStr) {
 }
 
 function showSignApproval(details) {
+    showPhishingWarning(
+        "approve-sign-phishing-warning",
+        details.isPhishingDomain,
+    );
+
     const sp = details.signParams;
 
     $("approve-sign-hostname").textContent = details.hostname;
@@ -382,6 +403,11 @@ function show(id) {
             showSignApproval(details);
             return;
         }
+        // Site connection approval
+        showPhishingWarning(
+            "approve-site-phishing-warning",
+            details.isPhishingDomain,
+        );
         $("approve-hostname").textContent = details.hostname;
         $("approve-address").innerHTML = approvalAddressHtml(
             state.activeAddress,

src/popup/views/confirmTx.js

@@ -25,8 +25,11 @@ const { getSignerForAddress } = require("../../shared/wallet");
 const { decryptWithPassword } = require("../../shared/vault");
 const { formatUsd, getPrice } = require("../../shared/prices");
 const { getProvider } = require("../../shared/balances");
-const { isScamAddress } = require("../../shared/scamlist");
-const { ERC20_ABI } = require("../../shared/constants");
+const {
+    getLocalWarnings,
+    getFullWarnings,
+} = require("../../shared/addressWarnings");
+const { ERC20_ABI, isBurnAddress } = require("../../shared/constants");
 const { log } = require("../../shared/log");
 const makeBlockie = require("ethereum-blockies-base64");
 const txStatus = require("./txStatus");
@@ -167,23 +170,17 @@ function show(txInfo) {
         $("confirm-balance").textContent = valueWithUsd(bal + " ETH", balUsd);
     }
 
-    // Check for warnings
-    const warnings = [];
-    if (isScamAddress(txInfo.to)) {
-        warnings.push(
-            "This address is on a known scam/fraud list. Do not send funds to this address.",
-        );
-    }
-    if (txInfo.to.toLowerCase() === txInfo.from.toLowerCase()) {
-        warnings.push("You are sending to your own address.");
-    }
+    // Check for warnings (synchronous local checks)
+    const localWarnings = getLocalWarnings(txInfo.to, {
+        fromAddress: txInfo.from,
+    });
 
     const warningsEl = $("confirm-warnings");
-    if (warnings.length > 0) {
-        warningsEl.innerHTML = warnings
+    if (localWarnings.length > 0) {
+        warningsEl.innerHTML = localWarnings
             .map(
                 (w) =>
-                    `<div class="border border-border border-dashed p-2 mb-1 text-xs font-bold">WARNING: ${w}</div>`,
+                    `<div class="border border-border border-dashed p-2 mb-1 text-xs font-bold">WARNING: ${w.message}</div>`,
             )
             .join("");
         warningsEl.style.visibility = "visible";
@@ -247,8 +244,16 @@ function show(txInfo) {
     state.viewData = { pendingTx: txInfo };
     showView("confirm-tx");
 
-    // Reset recipient warning to hidden (space always reserved, no layout shift)
+    // Reset async warnings to hidden (space always reserved, no layout shift)
     $("confirm-recipient-warning").style.visibility = "hidden";
+    $("confirm-contract-warning").style.visibility = "hidden";
+    $("confirm-burn-warning").style.visibility = "hidden";
+    $("confirm-etherscan-warning").style.visibility = "hidden";
+
+    // Show burn warning via reserved element (in addition to inline warning)
+    if (isBurnAddress(txInfo.to)) {
+        $("confirm-burn-warning").style.visibility = "visible";
+    }
 
     estimateGas(txInfo);
     checkRecipientHistory(txInfo);
@@ -295,19 +300,21 @@ async function estimateGas(txInfo) {
 }
 
 async function checkRecipientHistory(txInfo) {
-    const el = $("confirm-recipient-warning");
     try {
         const provider = getProvider(state.rpcUrl);
-        // Skip warning for contract addresses — they may legitimately
-        // have zero outgoing transactions (getTransactionCount returns
-        // the nonce, i.e. sent-tx count only).
-        const code = await provider.getCode(txInfo.to);
-        if (code && code !== "0x") {
-            return;
-        }
-        const txCount = await provider.getTransactionCount(txInfo.to);
-        if (txCount === 0) {
-            el.style.visibility = "visible";
+        const asyncWarnings = await getFullWarnings(txInfo.to, provider, {
+            fromAddress: txInfo.from,
+        });
+        for (const w of asyncWarnings) {
+            if (w.type === "contract") {
+                $("confirm-contract-warning").style.visibility = "visible";
+            }
+            if (w.type === "new-address") {
+                $("confirm-recipient-warning").style.visibility = "visible";
+            }
+            if (w.type === "etherscan-phishing") {
+                $("confirm-etherscan-warning").style.visibility = "visible";
+            }
         }
     } catch (e) {
         log.errorf("recipient history check failed:", e.message);

src/shared/addressWarnings.js

@@ -0,0 +1,114 @@
+// Address warning module.
+// Provides local and async (RPC-based) warning checks for Ethereum addresses.
+// Returns arrays of {type, message, severity} objects.
+
+const { isScamAddress } = require("./scamlist");
+const { isBurnAddress } = require("./constants");
+const { checkEtherscanLabel } = require("./etherscanLabels");
+const { log } = require("./log");
+
+/**
+ * Check an address against local-only lists (scam, burn, self-send).
+ * Synchronous — no network calls.
+ *
+ * @param {string} address - The target address to check.
+ * @param {object} [options] - Optional context.
+ * @param {string} [options.fromAddress] - Sender address (for self-send check).
+ * @returns {Array<{type: string, message: string, severity: string}>}
+ */
+function getLocalWarnings(address, options = {}) {
+    const warnings = [];
+    const addr = address.toLowerCase();
+
+    if (isScamAddress(addr)) {
+        warnings.push({
+            type: "scam",
+            message:
+                "This address is on a known scam/fraud list. Do not send funds to this address.",
+            severity: "critical",
+        });
+    }
+
+    if (isBurnAddress(addr)) {
+        warnings.push({
+            type: "burn",
+            message:
+                "This is a known null/burn address. Funds sent here are permanently destroyed and cannot be recovered.",
+            severity: "critical",
+        });
+    }
+
+    if (options.fromAddress && addr === options.fromAddress.toLowerCase()) {
+        warnings.push({
+            type: "self-send",
+            message: "You are sending to your own address.",
+            severity: "warning",
+        });
+    }
+
+    return warnings;
+}
+
+/**
+ * Check an address against local lists AND via RPC queries.
+ * Async — performs network calls to check contract status and tx history.
+ *
+ * @param {string} address - The target address to check.
+ * @param {object} provider - An ethers.js provider instance.
+ * @param {object} [options] - Optional context.
+ * @param {string} [options.fromAddress] - Sender address (for self-send check).
+ * @returns {Promise<Array<{type: string, message: string, severity: string}>>}
+ */
+async function getFullWarnings(address, provider, options = {}) {
+    const warnings = getLocalWarnings(address, options);
+
+    let isContract = false;
+    try {
+        const code = await provider.getCode(address);
+        if (code && code !== "0x") {
+            isContract = true;
+            warnings.push({
+                type: "contract",
+                message:
+                    "This address is a smart contract, not a regular wallet.",
+                severity: "warning",
+            });
+        }
+    } catch (e) {
+        log.errorf("contract check failed:", e.message);
+    }
+
+    // Skip tx count check for contracts — they may legitimately have
+    // zero inbound EOA transactions.
+    if (!isContract) {
+        try {
+            const txCount = await provider.getTransactionCount(address);
+            if (txCount === 0) {
+                warnings.push({
+                    type: "new-address",
+                    message:
+                        "This address has never sent a transaction. Double-check it is correct.",
+                    severity: "info",
+                });
+            }
+        } catch (e) {
+            log.errorf("tx count check failed:", e.message);
+        }
+    }
+
+    // Etherscan label check (best-effort async — network failures are silent).
+    // Runs for ALL addresses including contracts, since many dangerous
+    // flagged addresses on Etherscan (drainers, phishing contracts) are contracts.
+    try {
+        const etherscanWarning = await checkEtherscanLabel(address);
+        if (etherscanWarning) {
+            warnings.push(etherscanWarning);
+        }
+    } catch (e) {
+        log.errorf("etherscan label check failed:", e.message);
+    }
+
+    return warnings;
+}
+
+module.exports = { getLocalWarnings, getFullWarnings };

src/shared/constants.js

@@ -20,6 +20,19 @@ const ERC20_ABI = [
     "function approve(address spender, uint256 amount) returns (bool)",
 ];
 
+// Known null/burn addresses that permanently destroy funds.
+const BURN_ADDRESSES = new Set([
+    "0x0000000000000000000000000000000000000000",
+    "0x0000000000000000000000000000000000000001",
+    "0x000000000000000000000000000000000000dead",
+    "0xdead000000000000000000000000000000000000",
+    "0x00000000000000000000000000000000deadbeef",
+]);
+
+function isBurnAddress(address) {
+    return BURN_ADDRESSES.has(address.toLowerCase());
+}
+
 module.exports = {
     DEBUG,
     DEBUG_MNEMONIC,
@@ -28,4 +41,6 @@ module.exports = {
     DEFAULT_BLOCKSCOUT_URL,
     BIP44_ETH_PATH,
     ERC20_ABI,
+    BURN_ADDRESSES,
+    isBurnAddress,
 };

src/shared/etherscanLabels.js

@@ -0,0 +1,102 @@
+// Etherscan address label lookup via page scraping.
+// Extension users make the requests directly to Etherscan — no proxy needed.
+// This is a best-effort enrichment: network failures return null silently.
+
+const ETHERSCAN_BASE = "https://etherscan.io/address/";
+
+// Patterns in the page title that indicate a flagged address.
+// Title format: "Fake_Phishing184810 | Address: 0x... | Etherscan"
+const PHISHING_LABEL_PATTERNS = [/^Fake_Phishing/i, /^Phish:/i, /^Exploiter/i];
+
+// Patterns in the page body that indicate a scam/phishing warning.
+const SCAM_BODY_PATTERNS = [
+    /used in a\s+(?:\w+\s+)?phishing scam/i,
+    /used in a\s+(?:\w+\s+)?scam/i,
+    /wallet\s+drainer/i,
+];
+
+/**
+ * Parse the Etherscan address page HTML to extract label info.
+ * Exported for unit testing (no fetch needed).
+ *
+ * @param {string} html - Raw HTML of the Etherscan address page.
+ * @returns {{ label: string|null, isPhishing: boolean, warning: string|null }}
+ */
+function parseEtherscanPage(html) {
+    // Extract <title> content
+    const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+    let label = null;
+    let isPhishing = false;
+    let warning = null;
+
+    if (titleMatch) {
+        const title = titleMatch[1].trim();
+        // Title: "LABEL | Address: 0x... | Etherscan" or "Address: 0x... | Etherscan"
+        const labelMatch = title.match(/^(.+?)\s*\|\s*Address:/);
+        if (labelMatch) {
+            const candidate = labelMatch[1].trim();
+            // Only treat as a label if it's not just "Address" (unlabeled addresses)
+            if (candidate.toLowerCase() !== "address") {
+                label = candidate;
+            }
+        }
+    }
+
+    // Check label against phishing patterns
+    if (label) {
+        for (const pat of PHISHING_LABEL_PATTERNS) {
+            if (pat.test(label)) {
+                isPhishing = true;
+                warning = `Etherscan labels this address as "${label}" (Phish/Hack).`;
+                break;
+            }
+        }
+    }
+
+    // Check page body for scam warning banners
+    if (!isPhishing) {
+        for (const pat of SCAM_BODY_PATTERNS) {
+            if (pat.test(html)) {
+                isPhishing = true;
+                warning = label
+                    ? `Etherscan labels this address as "${label}" and reports it was used in a scam.`
+                    : "Etherscan reports this address was flagged for phishing/scam activity.";
+                break;
+            }
+        }
+    }
+
+    return { label, isPhishing, warning };
+}
+
+/**
+ * Fetch an address page from Etherscan and check for scam/phishing labels.
+ * Returns a warning object if the address is flagged, or null.
+ * Network failures return null silently (best-effort check).
+ *
+ * @param {string} address - Ethereum address to check.
+ * @returns {Promise<{type: string, message: string, severity: string}|null>}
+ */
+async function checkEtherscanLabel(address) {
+    try {
+        const resp = await fetch(ETHERSCAN_BASE + address, {
+            headers: { Accept: "text/html" },
+        });
+        if (!resp.ok) return null;
+        const html = await resp.text();
+        const result = parseEtherscanPage(html);
+        if (result.isPhishing) {
+            return {
+                type: "etherscan-phishing",
+                message: result.warning,
+                severity: "critical",
+            };
+        }
+        return null;
+    } catch {
+        // Network errors are expected — Etherscan may rate-limit or block.
+        return null;
+    }
+}
+
+module.exports = { parseEtherscanPage, checkEtherscanLabel };

src/shared/phishingDomains.js

@@ -0,0 +1,215 @@
+// Domain-based phishing detection using a vendored blocklist with delta updates.
+//
+// A community-maintained phishing domain blocklist is vendored in
+// phishingBlocklist.json and bundled at build time. At runtime, we fetch
+// the live list periodically and keep only the delta (new entries not in
+// the vendored list) in memory. This keeps runtime memory usage small.
+//
+// The domain-checker checks the in-memory delta first (fresh/recent scam
+// sites), then falls back to the vendored list.
+//
+// If the delta is under 256 KiB it is persisted to localStorage so it
+// survives extension/service-worker restarts.
+
+const vendoredConfig = require("./phishingBlocklist.json");
+
+const BLOCKLIST_URL =
+    "https://raw.githubusercontent.com/MetaMask/eth-phishing-detect/main/src/config.json";
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DELTA_STORAGE_KEY = "phishing-delta";
+const MAX_DELTA_BYTES = 256 * 1024; // 256 KiB
+
+// Vendored set — built once from the bundled JSON.
+const vendoredBlacklist = new Set(
+    (vendoredConfig.blacklist || []).map((d) => d.toLowerCase()),
+);
+
+// Delta set — only entries from live list that are NOT in vendored.
+let deltaBlacklist = new Set();
+let lastFetchTime = 0;
+let fetchPromise = null;
+let refreshTimer = null;
+
+/**
+ * Load delta entries from localStorage on startup.
+ * Called once during module initialization in the background script.
+ */
+function loadDeltaFromStorage() {
+    try {
+        const raw = localStorage.getItem(DELTA_STORAGE_KEY);
+        if (!raw) return;
+        const data = JSON.parse(raw);
+        if (data.blacklist && Array.isArray(data.blacklist)) {
+            deltaBlacklist = new Set(
+                data.blacklist.map((d) => d.toLowerCase()),
+            );
+        }
+    } catch {
+        // localStorage unavailable or corrupt — start empty
+    }
+}
+
+/**
+ * Persist delta to localStorage if it fits within MAX_DELTA_BYTES.
+ */
+function saveDeltaToStorage() {
+    try {
+        const data = {
+            blacklist: Array.from(deltaBlacklist),
+        };
+        const json = JSON.stringify(data);
+        if (json.length < MAX_DELTA_BYTES) {
+            localStorage.setItem(DELTA_STORAGE_KEY, json);
+        } else {
+            // Too large — remove stale key if present
+            localStorage.removeItem(DELTA_STORAGE_KEY);
+        }
+    } catch {
+        // localStorage unavailable — skip silently
+    }
+}
+
+/**
+ * Load a pre-parsed config and compute the delta against the vendored list.
+ * Used for both live fetches and testing.
+ *
+ * @param {{ blacklist?: string[] }} config
+ */
+function loadConfig(config) {
+    const liveBlacklist = (config.blacklist || []).map((d) => d.toLowerCase());
+
+    // Delta = entries in the live list that are NOT in the vendored list
+    deltaBlacklist = new Set(
+        liveBlacklist.filter((d) => !vendoredBlacklist.has(d)),
+    );
+
+    lastFetchTime = Date.now();
+    saveDeltaToStorage();
+}
+
+/**
+ * Generate hostname variants for subdomain matching.
+ * "sub.evil.com" yields ["sub.evil.com", "evil.com"].
+ *
+ * @param {string} hostname
+ * @returns {string[]}
+ */
+function hostnameVariants(hostname) {
+    const h = hostname.toLowerCase();
+    const variants = [h];
+    const parts = h.split(".");
+    // Parent domains: a.b.c.d -> b.c.d, c.d
+    for (let i = 1; i < parts.length - 1; i++) {
+        variants.push(parts.slice(i).join("."));
+    }
+    return variants;
+}
+
+/**
+ * Check if a hostname is on the phishing blocklist.
+ * Checks delta first (fresh/recent scam sites), then vendored list.
+ *
+ * @param {string} hostname - The hostname to check.
+ * @returns {boolean}
+ */
+function isPhishingDomain(hostname) {
+    if (!hostname) return false;
+    const variants = hostnameVariants(hostname);
+
+    // Check delta blacklist first (fresh/recent scam sites), then vendored
+    for (const v of variants) {
+        if (deltaBlacklist.has(v) || vendoredBlacklist.has(v)) return true;
+    }
+    return false;
+}
+
+/**
+ * Fetch the latest blocklist and compute delta against vendored data.
+ * De-duplicates concurrent fetches. Results are cached for CACHE_TTL_MS.
+ *
+ * @returns {Promise<void>}
+ */
+async function updatePhishingList() {
+    // Skip if recently fetched
+    if (Date.now() - lastFetchTime < CACHE_TTL_MS && lastFetchTime > 0) {
+        return;
+    }
+
+    // De-duplicate concurrent calls
+    if (fetchPromise) return fetchPromise;
+
+    fetchPromise = (async () => {
+        try {
+            const resp = await fetch(BLOCKLIST_URL);
+            if (!resp.ok) throw new Error("HTTP " + resp.status);
+            const config = await resp.json();
+            loadConfig(config);
+        } catch {
+            // Silently fail — vendored list still provides coverage.
+            // We'll retry next time.
+        } finally {
+            fetchPromise = null;
+        }
+    })();
+
+    return fetchPromise;
+}
+
+/**
+ * Start periodic refresh of the phishing list.
+ * Should be called once from the background script on startup.
+ */
+function startPeriodicRefresh() {
+    if (refreshTimer) return;
+    refreshTimer = setInterval(updatePhishingList, REFRESH_INTERVAL_MS);
+}
+
+/**
+ * Return the total blocklist size (vendored + delta) for diagnostics.
+ *
+ * @returns {number}
+ */
+function getBlocklistSize() {
+    return vendoredBlacklist.size + deltaBlacklist.size;
+}
+
+/**
+ * Return the delta blocklist size for diagnostics.
+ *
+ * @returns {number}
+ */
+function getDeltaSize() {
+    return deltaBlacklist.size;
+}
+
+/**
+ * Reset internal state (for testing).
+ */
+function _reset() {
+    deltaBlacklist = new Set();
+    lastFetchTime = 0;
+    fetchPromise = null;
+    if (refreshTimer) {
+        clearInterval(refreshTimer);
+        refreshTimer = null;
+    }
+}
+
+// Load persisted delta on module initialization
+loadDeltaFromStorage();
+
+module.exports = {
+    isPhishingDomain,
+    updatePhishingList,
+    startPeriodicRefresh,
+    loadConfig,
+    getBlocklistSize,
+    getDeltaSize,
+    hostnameVariants,
+    _reset,
+    // Exposed for testing only
+    _getVendoredBlacklistSize: () => vendoredBlacklist.size,
+    _getDeltaBlacklist: () => deltaBlacklist,
+};