Brave Real Blocker

A powerful ad-blocking and stealth library for Brave Real Browser, based on uBlock Origin filtering logic. This package replaces the traditional uBlock Origin extension with a native Node.js implementation using @cliqz/adblocker and custom scriptlet injections.

Ecosystem Chain

brave-real-browser-mcp-server (Top Level - MCP Server)
    └── brave-real-puppeteer-core (Stealth patches)
        └── brave-real-launcher (Browser launch)
            └── brave-real-blocker (Ad/Tracker blocking - Singleton) ← You are here

Features

5 Protection Layers

| Layer | Description | |-------|-------------| | Ad Blocking | uBlock Origin compatible filter lists with 45+ sources | | Stealth Mode | Advanced fingerprinting protection (Canvas, WebGL, AudioContext noise) | | Scriptlet Injection | Blocks forced clicks, auto-tab loops, forced redirects | | Cosmetic Filtering | Removes "Sponsored" labels, ad placeholders, cookie banners | | Redirect Blocking | Prevents forced tab openings, cleans tracking parameters |

Filter Lists (45+ Sources)

| Category | Lists | |----------|-------| | Core uBlock Origin | 9 lists (filters, badware, privacy, annoyances, etc.) | | EasyList Family | 6 lists (easylist, easyprivacy, cookie, antiadblock, etc.) | | AdGuard | 7 lists (base, mobile, tracking, popup, dns, etc.) | | Anti-Adblock Killers | 3 lists | | Popup/Redirect Blockers | 4 lists | | Privacy & Tracking | 4 lists (peter_lowes, disconnect_me, etc.) | | Malware Protection | 3 lists | | Cookie/GDPR | 2 lists | | Regional Filters | 10+ lists (India, Germany, France, China, Russia, Japan, etc.) |

Built-in Rules (200+)

• 18+ popup/popunder ad network domains blocked
• 4 cryptocurrency miner domains blocked
• 11+ streaming/file hosting site specific rules
• Cookie consent banner selectors
• Anti-adblock detection bypass rules

Installation

npm install brave-real-blocker

Usage

Automatic (via Ecosystem Chain)

When using brave-real-browser-mcp-server or brave-real-launcher, the blocker is automatically enabled on all pages via the singleton pattern.

import { connect } from 'brave-real-browser-mcp-server';

const { browser, page, blocker } = await connect({
    enableBlocker: true // Default: true
});

// Blocker is auto-enabled on all pages!
await page.goto('https://example.com');

Manual (with Puppeteer)

import { BraveBlocker } from 'brave-real-blocker';
import puppeteer from 'puppeteer-core';

(async () => {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    const blocker = new BraveBlocker({
        enableAdBlocking: true,
        enableStealth: true,
        enableScriptlets: true,
        enableCosmeticFiltering: true,
        enableRedirectBlocking: true,
        enableFilterAutoUpdate: true
    });
    
    await blocker.init(); // Downloads latest filter lists
    await blocker.enable(page);

    await page.goto('https://example.com');
})();

Singleton Pattern

The blocker uses a singleton pattern to ensure only one instance exists across the entire workspace:

import { 
    initBraveBlockerSingleton, 
    getBraveBlockerSingleton,
    isBraveBlockerInitialized 
} from 'brave-real-blocker';

// Initialize once
const blocker = await initBraveBlockerSingleton({
    enableStealth: true
});

// Get from anywhere
if (isBraveBlockerInitialized()) {
    const sameBlocker = getBraveBlockerSingleton();
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | enableAdBlocking | boolean | true | Enables network request blocking (Ads/Trackers) | | enableStealth | boolean | true | Enables anti-fingerprinting and bot evasion | | enableScriptlets | boolean | true | Enables scriptlet injection to block forced clicks/popups | | enableCosmeticFiltering | boolean | true | Hides cosmetic elements like "Sponsored" labels | | enableRedirectBlocking | boolean | true | Prevents forced tab openings, cleans tracking URLs | | enableFilterAutoUpdate | boolean | true | Auto-updates filter lists (7 day cache) | | customFiltersPath | string | - | Path to custom filter list file |

Test Results

| Test Site | Score | |-----------|-------| | AdBlock Tester | 100/100 (11 services, 22 checks) | | CanYouBlockIt Extreme | CLEAN (no ads visible) | | Bot Detection (SannySoft) | All PASSED |

Testing

Run unit tests:

npm run test

Run visual verification on real sites:

npm run visual-test

Architecture

This package is part of the Brave Real Browser ecosystem:

brave-real-browser-mcp-server
    ↓ uses brave-real-launcher
brave-real-puppeteer-core
    ↓ re-exports from brave-real-launcher
brave-real-launcher
    ↓ imports from brave-real-blocker
brave-real-blocker (Singleton)
    ↓ type-only import from brave-real-puppeteer-core

The singleton pattern ensures:

• Only one blocker instance across entire workspace
• Filter lists downloaded once and cached
• Automatic enabling on all new pages via ecosystem chain

License

MIT