BlockNSFW

Open-source browser extension for blocking adult websites and reducing unsafe content exposure across browsing, search, and selected social surfaces.

Project status:

• Published as Chrome and Firefox extension
• Already used by thousands of users
• Source-first repo with Chrome and Firefox build scripts

Current version: 2.0.2

Install

• Chrome Web Store
• Firefox Add-ons (AMO)
• Microsoft Edge Add-ons

Badges

• Chrome Web Store: https://chromewebstore.google.com/detail/blocknsfw-%E2%80%93-porn-adult-co/fiecjgpoilkhmoieaboolkfmgbnhlhop
• Firefox Add-ons: https://addons.mozilla.org/en-US/firefox/addon/blocknsfw-porn-adult-content/
• Microsoft Edge Add-ons: https://microsoftedge.microsoft.com/addons/detail/blocknsfw-%E2%80%93-porn-adult-/imccbmfplknoadpaoopicfdpnnimgdab
• License: MIT
• CI status: https://github.com/codepurse/BlockNSFW/actions/workflows/build.yml (the build.yml workflow runs the focused test suite and web-ext lint on every push)

What It Does

BlockNSFW combines several protection layers:

• Network-level blocking: the curated list ships as a static declarativeNetRequest ruleset, so a blocked host's images, media, frames and scripts are refused by the browser before any request is sent. Navigation still routes through the content script, which is what makes the blocked page and its audit entry possible.
• Filtering inside embedded frames, not just the top page, with the work scaled to the frame so ordinary pages stay fast.
• Domain blocking with local fallback rules plus cached remote blocklist updates. IDN / punycode hostnames (e.g. xn--porn-tqa.net) are retained at runtime, not silently dropped.
• Hostname smart filter that scans both the ASCII / punycode form and the decoded Unicode form of a hostname, with multilingual adult-hostword coverage (Chinese, Korean, Russian, Arabic, Thai, plus transliterated Latin).
• Page and visible-content filtering through a Manifest V3 content script
• On-device AI image detection (opt-in). Two models: a bundled NSFW.js MobileNetV2, or Marqo's ViT-384 whose weights are fetched once on first use. Images are never uploaded.
• On-device AI text classification (opt-in, beta). Currently requires corroboration from the image scanner before it will block a page on its own.
• Search SafeSearch enforcement on Google, Bing, DuckDuckGo, Yahoo, Brave, Ecosia, Qwant, AOL Search, Presearch, and Yandex
• Optional DNS-based blocking through one of three filtering resolvers — Cloudflare for Families, AdGuard DNS Family, CleanBrowsing — or any DNS-over-HTTPS endpoint you supply
• Ruleset subscriptions: follow a blocklist someone else maintains, in uBlacklist's format. Subscribed lists can only ever add blocks, never remove them.
• PIN and access-code locks over the settings that would weaken protection
• Reddit NSFW subreddit checks for Reddit-specific filtering paths
• Optional Facebook Reels and Instagram Reels blocking toggles
• First-run onboarding, local stats, streak tracking, whitelist management, and audit views
• Back up and restore everything in one file (Settings › About › Your data); a backup never holds the PIN, the Pact or a Supporter code
• Manual community reports for blocked / missed sites

Architecture

Main files:

• manifest.json - Chrome/Chromium MV3 manifest
• manifest.firefox.json - Firefox MV3 manifest
• background.js - blocklist loading, DNS checks, dynamic rules, stats, audit storage
• content.js - page filtering, SafeSearch enforcement, Reddit checks, DOM scanning
• shared/hostname.js - browser-safe punycode / IDN helpers (RFC 3492)
• shared/host-keywords.js - shared smart-blocking keyword list and strict host matcher
• popup.html / popup.js - quick toggle, stats, shortcuts
• options.html / options.js - full settings UI, whitelist tools, audit/stats access
• blocked.html / blocked.js - blocked page
• audit.html / audit.js - audit view
• stats.html / stats.js - statistics view
• data/HOSTS.txt - curated source blocklist (self-hosted in data/ under MIT)
• data/WHITELIST.txt - curated global whitelist
• data/SOURCE_NOTES.txt - data-file provenance, curation policy, missed-site flow
• blocklist.json - bundled fallback blocklist (regenerated from data/HOSTS.txt)
• build-chrome.ps1 / build-firefox.ps1 - release bundle scripts

Tech stack:

• Manifest V3
• Vanilla JavaScript / HTML
• No Node build step required

Additional maintainer docs:

• ARCHITECTURE.md
• RELEASE_CHECKLIST.md
• THIRD_PARTY_NOTICES.md

Privacy and Network Behavior

Most filtering decisions happen locally in the browser, but this project is not fully offline.

Network requests may occur for these features:

• Remote blocklist and whitelist updates from GitHub-hosted text files
• A twice-daily update check against a small version.json in this repository
• Optional DNS filtering through whichever resolver you select — Cloudflare for Families, AdGuard DNS Family, CleanBrowsing, or a custom DNS-over-HTTPS endpoint you provide. Queries go straight from your browser to that resolver; nothing passes through our servers. A preset that stops answering fails over to a second one on a different network; a custom resolver deliberately does not
• Ruleset subscriptions, which fetch whichever URLs you have subscribed to, once a day
• The optional ViT-384 image model's weights, fetched once from a GitHub-hosted URL if you select that model. The traffic goes one way — your images are never uploaded
• Reddit subreddit NSFW checks through Reddit endpoints
• Optional manual community reports through Appwrite-hosted backend

Privacy details live in PRIVACY_POLICY.md. Public docs should stay aligned with real code behavior.

Browser Support

Supported:

• Chrome 101+ (requestDomains, used by the static ruleset, landed in 101)
• Firefox 113+
• Chromium-based browsers that support MV3 and required permissions

More detail: BROWSER_COMPATIBILITY.md

Local Development

Load unpacked in Chromium browsers

1. Open chrome://extensions/ or equivalent browser extensions page.
2. Enable Developer Mode.
3. Click Load unpacked.
4. Select repo root containing manifest.json.

Load temporary add-on in Firefox

1. Open about:debugging#/runtime/this-firefox.
2. Click Load Temporary Add-on...
3. Select dist\firefox\manifest.json after running Firefox build script.

Build Release Bundles

Chrome:

powershell -ExecutionPolicy Bypass -File .\build-chrome.ps1
powershell -ExecutionPolicy Bypass -File .\build-chrome.ps1 -Zip

Firefox:

powershell -ExecutionPolicy Bypass -File .\build-firefox.ps1
powershell -ExecutionPolicy Bypass -File .\build-firefox.ps1 -Zip

A build from this repository alone is the open-source build: every protection, without the Supporter extras (see "Open source, and the Supporter extras" below). -Zip makes a store package and needs the extras; add -OpenSource to package without them. A store package also refuses to build while Supporter is still in Polar's sandbox (RELEASE_CHECKLIST.md, section 0); -Zip -Sandbox makes a test package, never for a store. Every zip is read back by scripts/check-package.js before the build calls it done, and gets a build note (dist\blocknsfw-*.build.txt) with its SHA-256 and the commits it was built from.

Build output:

• dist\chrome\
• dist\firefox\

Manual Smoke Test

Before release:

1. Load Chrome build and Firefox build.
2. Confirm popup opens and main toggle works.
3. Confirm options page opens and settings persist.
4. Confirm blocked page, audit page, and stats page open correctly.
5. Confirm SafeSearch rules apply on at least one supported engine.
6. Confirm whitelist add/remove flow works.
7. Confirm no obvious console errors after fresh install.

Firefox Rendering Benchmark

The repository includes a real-browser performance harness that launches clean Firefox profiles under Xvfb, remotely drives them over WebDriver BiDi, and compares a deterministic dynamic-feed workload with the extension absent and installed:

npm run perf:firefox

See scripts/perf/README.md for shorter smoke runs, workload controls, and JSON output.

Contributing

See .github/CONTRIBUTING.md.

If you want to report:

• blocking misses or false positives
• browser-specific regressions
• privacy/security concerns
• UX issues in popup/options flows

open an issue with steps, URLs/domains involved, browser version, and feature flags used.

Roadmap

Near-term priorities:

• tighten open-source launch polish
• add focused regression coverage for high-risk blocking logic
• improve release automation and browser-specific validation

License

MIT. See LICENSE.

Open source, and the Supporter extras

Everything that protects is open source and in this repository: the blocklists, the AI image and text filters, SafeSearch and DNS, Gateways, the Pact, Storm Mode and risk hours, your own words, all five blocked-page designs, the first week of the path, statistics, and the Supporter page and its code check. A build from here blocks exactly what the store version blocks. (In the store versions Classic is the free design and the other four come with Supporter; a build from here offers all five.)

The Supporter extras are not open source: days 8 to 30 of the path, the evening check-in, Your good days, When it's hardest, Your month and Your year, the photo and the voice message for the hard moment, your progress on every computer (through the browser's own sync), and Supporter looks. They live in a private repository and ship only in the versions on the Chrome Web Store, Microsoft Edge Add-ons and Firefox Add-ons. extras/ holds empty stand-ins for them (extras/README.md), so a build from here says plainly where an extra would be. The extras never decide what is blocked and make no network requests.

Notes Before Public Launch

• Add store listing links once public repo announcement is ready
• Keep generated dist/ output out of version control
• Keep docs consistent with actual network behavior and permissions
• Remote blocklist source is self-hosted in data/ under MIT (see THIRD_PARTY_NOTICES.md); background.js REMOTE_BLOCKLIST_URL and REMOTE_WHITELIST_URL point at the public codepurse/BlockNSFW raw URLs
• Appwrite manual-report backend is maintained out-of-tree; its public-launch status and the data it receives are documented in THIRD_PARTY_NOTICES.md and PRIVACY_POLICY.md