# PureGuard browser extension (v0.2)

Chrome / Edge / Brave / Arc / Firefox extension with two protection layers:

1. **Domain blocklist** — 30,000 declarativeNetRequest rules that block known adult-content domains outright. Hits the network layer; the page never loads.
2. **Real-time AI scanner** — on-device NSFW classifier (NSFW.js / MobileNetV2, ~3.7MB model) that runs in a content script on every page, watches images and videos as they enter the viewport, and blurs / blocks anything classified as explicit or suggestive. **No data leaves your device.** This is what catches the breast-augmentation ads on Instagram, the lingerie placements in your X feed, the BBL "before/after" reels — content that's not on a blockable domain but is still the gateway PureGuard exists to stop.

**Privacy:** the extension does not request `tabs`, `webRequest`, `webNavigation`, or any permission that would let us read URLs or content. The blocklist matching happens inside Chrome natively. The AI scan runs entirely inside the content-script sandbox and we don't even know what page you're on.

## Install (unpacked, dev mode)

1. Open `chrome://extensions` (or `edge://extensions`)
2. Toggle **Developer mode** on (top-right)
3. Click **Load unpacked**
4. Select this folder: `/Users/sethcourson/Desktop/PureGuard/pureguard-extension/`
5. The PureGuard icon should appear in the toolbar; click it to see the popup

To test: try navigating to a known blocked domain (e.g. `pornhub.com`). You should be redirected to PureGuard's "Paused" page. Hit back, you're fine.

## Install (Chrome Web Store)

Coming soon. Once the icon is finalized and the privacy disclosure is filled out, this will be on the Chrome Web Store. Estimated review time: 7–14 days.

## Folder layout

| File | Purpose |
|---|---|
| `manifest.json` | Manifest V3 declaration |
| `background.js` | Service worker — receives `pg:cv-block` messages, counts blocks, daily reset |
| `content.js` | The on-device AI scanner: loads NSFW.js model lazily, watches `<img>` / `<video>` via IntersectionObserver, classifies on viewport entry, blurs/blocks above thresholds |
| `lib/tf.min.js` | TensorFlow.js (1.4MB) |
| `lib/nsfwjs.min.js` | NSFW.js wrapper (2.6MB UMD bundle) |
| `lib/model/model.json` | TF.js MobileNetV2 topology (236KB) |
| `lib/model/group1-shard1of1.bin` | TF.js MobileNetV2 weights (3.5MB binary) |
| `rules/blocklist.json` | 30,000 declarativeNetRequest rules from StevenBlack/hosts porn-only |
| `block/block.html` | "Paused" page when domain blocklist fires |
| `popup/popup.html` + `popup.js` | Toolbar popup — daily block count + status |
| `icons/` | 16/48/128 px icons (placeholder — replace with branded) |

## Tuning the AI scanner

Thresholds are constants at the top of `content.js`. NSFW.js classifies into five buckets: Drawing, Hentai, Neutral, Porn, Sexy. PureGuard combines them as:

```js
explicit  = score(Porn) + score(Hentai)   // hard block (heavy blur + dim)
sexy      = score(Sexy)                   // soft blur (paused video)
```

Defaults: `explicit ≥ 0.40` blocks, `sexy ≥ 0.55` blurs. Tune in v0.3 with telemetry from real usage. Lower = catches more (more false positives on fitness/fashion). Higher = catches less.

The scanner only runs on elements ≥80×80 px (avoids classifying icons and avatars), and caps concurrent inference at 2 to keep page interaction smooth on infinite-scroll feeds.

## What's blocked

The extension ships with a curated blocklist derived from the public [StevenBlack/hosts](https://github.com/StevenBlack/hosts) "porn-only" extension. After apex-domain dedup, the top 30,000 domains are bundled (Chrome's `declarativeNetRequest` static-rule budget is 30k per ruleset).

The full ~47,000-domain list is also published at `https://pureguard.ai/api/blocklist` for future versions that fetch dynamic updates.

## Permissions

| Permission | Why |
|---|---|
| `declarativeNetRequest` | The actual blocking. Chrome handles the rule matching natively — the extension does NOT see your URLs |
| `storage` | Persist daily block count locally |
| `alarms` | Reset the daily count every 24h |
| `https://pureguard.ai/*` (host) | Future: pull blocklist updates from the server |

The extension does **not** request `tabs`, `webNavigation`, `webRequest`, `<all_urls>`, or any other permission that would let it see your browsing history. By design.

## What it does NOT do (yet)

- Detect VPN / proxy bypass attempts (lives in the desktop client)
- Sync with a partner / accountability mode (backend supports it via `/api/partner/invite`; UI hookup in v0.3)
- Log block events to the server (intentional — privacy by default; opt-in telemetry in v0.4 once partner mode lights up)

## Bundle size & Chrome Web Store

Total extension is **~13MB** with the bundled model — fine for `Load Unpacked` development install. Chrome Web Store has a hard 10MB cap. To submit to the store, in v0.3 we'll switch the model to **fetch on first run from `https://pureguard.ai/api/cv-model/` and cache in IndexedDB**. That drops the shipped extension to ~6MB.

For now, sideload via Load Unpacked (or signed XPI for Firefox) is the recommended distribution.

## Updating the blocklist

The static rules ship with the extension. To regenerate from the latest StevenBlack list:

```bash
cd /Users/sethcourson/Desktop/PureGuard
curl -sL https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/porn-only/hosts > /tmp/sb.txt
# (run the rebuild script — currently inline in the original commit, will be promoted to scripts/build-blocklist.py if needed)
```

Bumping the extension `version` in `manifest.json` and re-zipping for the store is required for end users to receive updates.

## Mission

PureGuard is a ministry project of the [Prodigal Sons Project](https://www.prodigalsonsproject.org/). 100% of subscription profits, after Stripe processing fees, go to PSP. The extension itself is free and remains free.
