Strict URL Whitelist

About

Strict URL Whitelist is a Chrome extension that enforces navigation only to explicitly approved URLs. It uses Chrome’s high-performance declarativeNetRequest API to allow or block requests based on domain, path, and optional query parameters — all defined through local configuration.

The extension is lightweight, script-free, and does not interact with page content. It applies all rules at the network level using a background service worker, ensuring reliable, zero-interaction enforcement.

Technical Architecture
Allowlisting Mechanism

Filtering is implemented through chrome.declarativeNetRequest.updateDynamicRules(), which allows near-instant control over navigation. The logic includes:
All main_frame requests are blocked by default using a global redirect rule.
A user-defined allowlist is stored in chrome.storage.local.
The background service worker observes configuration changes and updates rules dynamically.
Allowed requests are passed through immediately.
All unmatched requests are redirected to a blank white page using a data: URI.

This model ensures strict, predictable navigation control without requiring manual reloads or page interaction.

Rule Model
Each allowlist entry includes:
domain: Required — the hostname to allow (e.g., "example.com").
path: Optional — the path to match under the domain (e.g., "section/page" or "api/*").
query: Optional — an object of query parameters to match strictly (e.g., { token: "abc123" }).

If query parameters are present, they must exist in the actual URL with matching values. Extra query parameters are allowed but will not override required ones.

Rule Examples

Allow a full domain:
{
  "domain": "example.com",
  "path": "*"
}

Allow a specific section or route:
{
  "domain": "example.com",
  "path": "section/page"
}

Allow a strict query string match:
{
  "domain": "example.com",
  "path": "search",
  "query": { "q": "value" }
}

This allows:
✅ https://example.com/search?q=value
✅ https://example.com/search?foo=bar&q=value&extra=true
❌ https://example.com/search?q=wrong
❌ https://example.com/search (if q=value is required)

Example Usage
chrome.storage.local.set({
  allowedList: [
    {
      domain: "example.com",
      path: "search",
      query: { q: "allowed" }
    }
  ]
});

Storage & Synchronization

All allowlist entries are stored via chrome.storage.local.
Rules are regenerated automatically when the storage changes.
No manual reload or refresh is needed — updates apply instantly.

Service Worker Logic
Initializes the allowlist and rule set when installed or activated.
Responds to changes in allowedList by rebuilding the rule set.
No persistent background activity when idle.
No content scripts or page interaction.

Privacy & Compliance
✅ No external requests or remote code.
✅ No telemetry or analytics.
✅ No page injection or script access.
✅ Query parameters are processed locally and not shared.

Strict URL Whitelist provides a secure, low-overhead method of enforcing exact-match navigation control — including optional query enforcement — suitable for personal, enterprise, or restricted browsing environments.