declarativeNetRequestWithHostAccess

3 min read

declarativeNetRequestWithHostAccess

The declarativeNetRequestWithHostAccess permission allows extensions to use declarative Net Request (DNR) rules that interact with specific host URLs, combining DNR capabilities with host permissions.

What It Grants

This permission enables DNR rules that require access to specific hosts, including:

Difference from declarativeNetRequest

Feature declarativeNetRequest declarativeNetRequestWithHostAccess
Basic blocking ✅ ✅
Redirect to extension path ✅ ✅
Redirect to specific URL ❌ ✅
Modify request/response headers Limited Full
Host permission warnings No Yes

The standard declarativeNetRequest permission allows blocking requests and redirects to extensionPath URLs without host permissions. However, redirecting to specific URLs or modifying headers for particular hosts requires this permission.

Manifest Configuration

{
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://*.example.com/*"
  ]
}

The host permissions must explicitly list the domains your rules will interact with.

User Warning

When users install an extension with this permission, they will see a warning indicating that the extension can:

This is because the permission effectively grants host-level access combined with request modification capabilities.

When It’s Needed

Use declarativeNetRequestWithHostAccess when:

  1. Creating redirect rules that point to specific external URLs
  2. Modifying request or response headers for particular hosts
  3. Using urlTransform rules with custom URLs
  4. Applying rules to *://*/* patterns combined with host-specific conditions

When It’s NOT Needed

You can use basic declarativeNetRequest without this permission for:

@theluckystrike/webext-permissions

This permission can be validated using @theluckystrike/webext-permissions:

import { hasPermission } from '@theluckystrike/webext-permissions';

const hasDnrWithHostAccess = await hasPermission('declarativeNetRequestWithHostAccess');

Example Use Case

An extension that redirects all requests from site-a.com to site-b.com would require:

{
  "permissions": ["declarativeNetRequestWithHostAccess"],
  "host_permissions": [
    "https://site-a.com/*",
    "https://site-b.com/*"
  ]
}

With a rule like:

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": { "url": "https://site-b.com" }
  },
  "condition": {
    "urlFilter": "site-a.com",
    "resourceTypes": ["main_frame"]
  }
}

Frequently Asked Questions

When do I need host permissions with declarativeNetRequest?

Host permissions are needed if you want to modify requests to specific websites or need access to request headers for the rules.

Can I block requests without host permissions?

Yes, using static rulesets that don’t require host access can block requests to any domain. —

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

No previous article
No next article