The Allowlist, and Where It Lives

## Why it matters

A blocker that never lets anything through is fastest and cleanest, but the real web isn't clean. Some sites need adverts to survive. Some legitimate content loads as a third-party request that looks like an ad. Sometimes blocking breaks a page.

An allowlist is your escape hatch. You pick which sites to trust. For those sites, blocking turns off entirely. Nothing gets blocked, nothing gets logged. The list stays on your device: it never touches a server, never sends to an analytics company, never shows up in anyone's data.

## How it works

Your allowlist is a list of domain names where blocking is disabled. When you choose to allowlist a site, Scalpel creates one dynamic rule in declarativeNetRequest: an allowAllRequests rule keyed to the site's domain. Chrome then lets all requests from that site through, whether they're adverts, trackers, or anything else.

The rule is matched on the request's initiating URL, not the destination. So if you're on news.example.com and it loads something from ads.third-party.com, the rule checks whether news.example.com is on your allowlist. If it is, the request goes through. If it's not, it gets blocked.

Your allowlist persists across restarts. Each entry lives in chrome.storage.local until you remove it. The entries are only site addresses, nothing about your browsing, nothing sensitive.

## What does not matter

An allowlist is not a whitelist of "safe" adverts. There's no quality check or format standard. You add a site, and everything from that site is allowed. The advert might be intrusive, the tracker might be aggressive, but if you allowlisted the site, all of it loads.

Allowlisting one page does not allowlist similar pages. If you add news.example.com, only that domain is allowed. blog.example.com is still blocked. The rule is domain-specific.

Toggling blocking off with a global pause is different from allowlisting. A pause affects everywhere for that browsing session, then clears when you restart. An allowlist entry stays there until you remove it.

## Code example

When you allowlist news.example.com, Scalpel creates a dynamic rule:

{
  "id": 1721500123,
  "priority": 1,
  "action": {
    "type": "allow"
  },
  "condition": {
    "requestDomains": ["news.example.com"],
    "resourceTypes": ["main_frame"]
  }
}
Copy

This rule says: if the request is initiated from news.example.com, allow it (don't block anything). The rule survives a restart because it's stored in chrome.storage.local. When you remove the site from your allowlist, Scalpel deletes the rule from the declarativeNetRequest API, and blocking resumes immediately on the next page load.

## How Scalpel Ads Blocker shows it

Open the popup on a page and you'll see an "Allowlist this site" toggle or button. Click it and the domain is added to your allowlist. The popup refreshes and shows that blocking is off for this page. The badge on the toolbar icon changes to show OFF instead of a count.

If the page is already allowlisted, the button says "Stop blocking" or shows a toggle in the OFF position. Click it again to remove the site from your allowlist and resume blocking immediately.

Your full allowlist lives in the extension's settings panel. You can see every entry, search them, and remove ones you no longer need.