# 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

```bash
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.

```typescript
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)

```typescript
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:

```typescript
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:
```bash
npm run test
```

Run visual verification on real sites:
```bash
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