From fb6779694b138df328debf89b8a6388a4d336ebf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andri=20=C3=93skarsson?= <m+git@andri.dk>
Date: Thu, 26 Feb 2026 22:06:40 +0100
Subject: [PATCH] Update docs to reflect HTTPS proxy port, CLI flags, and
 CSS-only element hiding

---
 .claude/skills/playwright-cli/SKILL.md | 24 +++------
 .claude/skills/proxy-test/SKILL.md     | 33 ++++--------
 AGENTS.md                              |  2 +-
 CONTRIBUTING.md                        | 72 +++++++++++++++-----------
 README.md                              | 21 +++++---
 5 files changed, 72 insertions(+), 80 deletions(-)

diff --git a/.claude/skills/playwright-cli/SKILL.md b/.claude/skills/playwright-cli/SKILL.md
index 6c2b6cb..7617ba1 100644
--- a/.claude/skills/playwright-cli/SKILL.md
+++ b/.claude/skills/playwright-cli/SKILL.md
@@ -57,21 +57,9 @@ grep "||.*example" examples/is.rules
 grep "^##" examples/is.rules
 ```
 
-### 3. Verify element replacement
+### 3. Verify element hiding CSS injection
 
-Matched elements are replaced with `<!-- ublproxy: replaced .selector -->` comments in the DOM:
-
-```bash
-playwright-cli -s=proxy eval "() => {
-  const html = document.documentElement.innerHTML;
-  const matches = html.match(/<!-- ublproxy: replaced [^>]+ -->/g);
-  return { found: (matches || []).length, replacements: matches || [] };
-}"
-```
-
-### 4. Verify CSS fallback injection
-
-Complex selectors fall back to CSS `display: none` injection. Check for injected `<style>` tags:
+Element hiding injects `display: none !important` CSS rules into HTML responses. Check for injected `<style>` tags:
 
 ```bash
 playwright-cli -s=proxy eval "() => {
@@ -85,7 +73,7 @@ playwright-cli -s=proxy eval "() => {
 }"
 ```
 
-### 5. Verify request blocking
+### 4. Verify request blocking
 
 Check network log for failed requests to blocked domains:
 
@@ -99,14 +87,14 @@ Requests to blocked domains should appear as failed. Compare with the no-proxy s
 playwright-cli -s=no-proxy network
 ```
 
-### 6. Take comparison screenshots
+### 5. Take comparison screenshots
 
 ```bash
 playwright-cli -s=proxy screenshot --filename=tmp/with-proxy.png
 playwright-cli -s=no-proxy screenshot --filename=tmp/without-proxy.png
 ```
 
-### 7. Cleanup
+### 6. Cleanup
 
 ```bash
 playwright-cli -s=proxy close
@@ -226,5 +214,5 @@ After each command, playwright-cli provides a snapshot of the current browser st
 - **HTTPS timeouts** -- the proxy config (`playwright-cli-proxy.json`) sets `ignoreHTTPSErrors: true`. Verify the config file exists and is passed via `--config`.
 - **Navigation timeout** -- the target site may be down. Try `curl --max-time 5 https://example.is` to verify.
 - **Cloudflare challenge** -- some sites block headless browsers. The page title will be "Just a moment...". Try a different site.
-- **No element replacements** -- the page may use zstd compression (not yet supported) or the selectors may no longer match the current site markup.
+- **No element hiding CSS** -- the page may use zstd compression (not yet supported) or the selectors may no longer match the current site markup.
 - **Stale sessions** -- if browsers become unresponsive, run `playwright-cli kill-all`.
diff --git a/.claude/skills/proxy-test/SKILL.md b/.claude/skills/proxy-test/SKILL.md
index e1862c9..5a8860e 100644
--- a/.claude/skills/proxy-test/SKILL.md
+++ b/.claude/skills/proxy-test/SKILL.md
@@ -6,7 +6,7 @@ allowed-tools: Bash(curl:*), Bash(mise:*), Bash(diff:*)
 
 # Verifying Proxy Behavior with curl
 
-Test ublproxy's ad-blocking (request blocking, element replacement, and CSS fallback injection) by comparing curl responses with and without the proxy.
+Test ublproxy's ad-blocking (request blocking and element hiding CSS injection) by comparing curl responses with and without the proxy.
 
 ## Prerequisites
 
@@ -39,32 +39,24 @@ grep "^##" examples/is.rules
 Blocked hostnames return 403 for HTTPS (CONNECT) requests:
 
 ```bash
-curl -v --proxy http://127.0.0.1:8080 -k https://blocked-domain.com 2>&1 | grep "< HTTP"
+curl -v --proxy https://127.0.0.1:8443 --proxy-insecure -k https://blocked-domain.com 2>&1 | grep "< HTTP"
 # Expected: HTTP/1.1 403 Forbidden
 ```
 
-### 3. Verify element replacement
+### 3. Verify element hiding CSS injection
 
-Matched elements are replaced with `<!-- ublproxy: replaced .selector -->` comments. Check for them in the HTML output:
+Element hiding injects `display: none !important` CSS rules into HTML responses. Check for the injected style tag:
 
 ```bash
-curl -s --proxy http://127.0.0.1:8080 -k https://example.is | grep 'ublproxy: replaced'
+curl -s --proxy https://127.0.0.1:8443 --proxy-insecure -k https://example.is | grep 'display: none'
 ```
 
-### 4. Verify CSS fallback injection
-
-Complex selectors that can't be matched on a single element fall back to CSS `display: none` injection. Check for the injected style tag:
-
-```bash
-curl -s --proxy http://127.0.0.1:8080 -k https://example.is | grep 'display: none'
-```
-
-### 5. Compare proxy vs direct
+### 4. Compare proxy vs direct
 
 Save responses and diff them to see exactly what the proxy changed:
 
 ```bash
-curl -s --proxy http://127.0.0.1:8080 -k https://example.is > tmp/with-proxy.html
+curl -s --proxy https://127.0.0.1:8443 --proxy-insecure -k https://example.is > tmp/with-proxy.html
 curl -s https://example.is --compressed > tmp/without-proxy.html
 diff tmp/without-proxy.html tmp/with-proxy.html
 ```
@@ -79,13 +71,10 @@ mise run dev -- --blocklist examples/is.rules
 grep "1819.is" examples/is.rules
 
 # Compare responses
-curl -s --proxy http://127.0.0.1:8080 -k https://1819.is > tmp/with-proxy.html
+curl -s --proxy https://127.0.0.1:8443 --proxy-insecure -k https://1819.is > tmp/with-proxy.html
 curl -s https://1819.is --compressed > tmp/without-proxy.html
 
-# Check for element replacements
-grep 'ublproxy: replaced' tmp/with-proxy.html
-
-# Check for CSS fallback injection
+# Check for element hiding CSS injection
 grep 'display: none' tmp/with-proxy.html
 
 # Diff to see all changes
@@ -95,6 +84,6 @@ diff tmp/without-proxy.html tmp/with-proxy.html
 ## Troubleshooting
 
 - **"proxy is not running"** — start the proxy first with `mise run dev -- --blocklist examples/is.rules`
-- **Connection refused** — verify the proxy is listening: `curl --proxy http://127.0.0.1:8080 http://example.com`
-- **No element replacements or CSS injection** — the page may not be HTML, or the response may use zstd compression (not yet supported). Check `Content-Encoding` with `curl -D-`.
+- **Connection refused** — verify the proxy is listening: `curl --proxy https://127.0.0.1:8443 --proxy-insecure -k https://example.com`
+- **No CSS injection** — the page may not be HTML, or the response may use zstd compression (not yet supported). Check `Content-Encoding` with `curl -D-`.
 - **Elements not found** — the site may have been redesigned since the blocklist rules were written. The selectors may no longer match anything in the server-rendered HTML (some elements are only added by JavaScript at runtime).
diff --git a/AGENTS.md b/AGENTS.md
index 09945c0..2194b19 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,6 +5,6 @@
 Temporary files (screenshots, traces, recordings, etc.) must be stored in `tmp/`. This directory is gitignored. Never write temporary files to the project root or other directories.
 
 ```bash
-curl -s --proxy http://127.0.0.1:8080 -k https://example.com > tmp/response.html
+curl -s --proxy https://127.0.0.1:8443 --proxy-insecure -k https://example.com > tmp/response.html
 playwright-cli -s=proxy screenshot --filename=tmp/screenshot.png
 ```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c78ca85..82e6543 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,7 +21,7 @@ mise run dev    # build and start the proxy
 Pass flags through to the underlying command with `--`:
 
 ```sh
-mise run dev -- --port 9090
+mise run dev -- --https-port 9090
 mise run test -- -v -run TestPortal
 ```
 
@@ -47,10 +47,14 @@ mise run dev
 
 | Flag | Default | Description |
 |---|---|---|
-| `--addr` | `127.0.0.1` | Address to listen on |
-| `--port` | `8080` | Port to listen on |
+| `--addr` | `0.0.0.0` | Address to listen on |
+| `--http-port` | `8080` | HTTP port for setup page and CA certificate download |
+| `--https-port` | `8443` | HTTPS port for proxy, portal, and API |
+| `--hostname` | `localhost` | Portal hostname for WebAuthn and TLS cert (must be a domain, not an IP) |
 | `--ca-dir` | `~/.ublproxy/` | Directory for CA certificate and key |
+| `--db` | `~/.ublproxy/ublproxy.db` | Path to SQLite database |
 | `--blocklist` | *(none)* | Path or URL to a blocklist file (can be specified multiple times) |
+| `--default-subscription` | EasyList + EasyPrivacy | Default blocklist subscription URL, always active for all users (can be specified multiple times) |
 
 On first run, a CA certificate and key are generated in the `--ca-dir` directory. You need to trust the CA certificate (`ca.crt`) in your OS or browser for HTTPS interception to work without warnings.
 
@@ -64,14 +68,11 @@ mise run dev -- --blocklist examples/is.rules
 ```
 
 ```sh
-# Plain HTTP
-curl --proxy http://127.0.0.1:8080 http://example.com
-
 # HTTPS (trusting the generated CA)
-curl --proxy http://127.0.0.1:8080 --cacert ~/.ublproxy/ca.crt https://example.com
+curl --proxy https://127.0.0.1:8443 --proxy-cacert ~/.ublproxy/ca.crt --cacert ~/.ublproxy/ca.crt https://example.com
 
 # HTTPS (skip certificate verification — quick and dirty)
-curl --proxy http://127.0.0.1:8080 -k https://example.com
+curl --proxy https://127.0.0.1:8443 --proxy-insecure -k https://example.com
 ```
 
 ### Verifying request blocking
@@ -79,25 +80,16 @@ curl --proxy http://127.0.0.1:8080 -k https://example.com
 Blocked hostnames return 403 for HTTPS (CONNECT) requests:
 
 ```sh
-curl -v --proxy http://127.0.0.1:8080 -k https://ads.example.com 2>&1 | grep "< HTTP"
+curl -v --proxy https://127.0.0.1:8443 --proxy-insecure -k https://ads.example.com 2>&1 | grep "< HTTP"
 # Expected: HTTP/1.1 403 Forbidden
 ```
 
-### Verifying element replacement
-
-Matched elements are replaced with `<!-- ublproxy: replaced .selector -->` comments. Check for them in the HTML output:
-
-```sh
-curl -s --proxy http://127.0.0.1:8080 -k https://some-site.com \
-  | grep 'ublproxy: replaced'
-```
-
-### Verifying CSS fallback
+### Verifying element hiding
 
-Complex selectors that can't be matched on a single element fall back to CSS `display: none` injection. Check for the injected style tag:
+Element hiding uses CSS injection (`display: none !important`). Check for the injected style tag:
 
 ```sh
-curl -s --proxy http://127.0.0.1:8080 -k https://some-site.com \
+curl -s --proxy https://127.0.0.1:8443 --proxy-insecure -k https://some-site.com \
   | grep 'display: none'
 ```
 
@@ -105,7 +97,7 @@ curl -s --proxy http://127.0.0.1:8080 -k https://some-site.com \
 
 ```sh
 # Through the proxy
-curl -s --proxy http://127.0.0.1:8080 -k https://some-site.com > tmp/with-proxy.html
+curl -s --proxy https://127.0.0.1:8443 --proxy-insecure -k https://some-site.com > tmp/with-proxy.html
 
 # Direct
 curl -s https://some-site.com --compressed > tmp/without-proxy.html
@@ -121,7 +113,7 @@ mise run dev -- --blocklist examples/is.rules --blocklist examples/dk.rules
 
 ### Using remote blocklists
 
-The `--blocklist` flag accepts URLs. Lists are downloaded once at startup (30-second timeout).
+The `--blocklist` flag accepts URLs. Lists are downloaded once at startup (5-second timeout).
 
 ```sh
 mise run dev -- --blocklist https://easylist.to/easylist/easylist.txt --blocklist examples/dk.rules
@@ -159,8 +151,8 @@ Interact with sessions using `playwright-cli -s=proxy <command>` or `playwright-
 playwright-cli -s=proxy screenshot --filename=tmp/with-proxy.png
 playwright-cli -s=no-proxy screenshot --filename=tmp/without-proxy.png
 
-# Check for element replacements in the DOM
-playwright-cli -s=proxy eval "document.documentElement.innerHTML.match(/<!-- ublproxy: replaced [^>]+ -->/g)"
+# Check for element hiding CSS in the page
+playwright-cli -s=proxy eval "[...document.querySelectorAll('style')].map(s => s.textContent).filter(t => t.includes('display: none'))"
 
 # Close sessions when done
 playwright-cli close-all
@@ -182,20 +174,38 @@ Proxy code lives in `package main` in the project root. The `pkg/` directory con
 
 | File | Responsibility |
 |---|---|
-| `main.go` | CLI flag parsing, startup |
+| `main.go` | CLI flag parsing, wiring, startup |
 | `ca.go` | CA certificate loading, generation, and persistence to disk |
 | `cert.go` | Per-host TLS certificate generation and in-memory cache |
-| `proxy.go` | Top-level HTTP handler, dispatches to HTTP or CONNECT handler |
+| `proxy.go` | Proxy handler, baseline/per-user rule loading, request dispatch |
 | `http.go` | Plain HTTP request forwarding, hop-by-hop header stripping |
 | `connect.go` | CONNECT method handling, TLS MITM, request forwarding |
-| `elemhide_inject.go` | HTML element replacement and CSS fallback injection |
-| `portal.go` | Direct-access page with CA cert download and install instructions |
+| `portal.go` | Portal and setup page serving (embeds static HTML) |
+| `portal_https.go` | HTTPS listener, TLS termination, request routing |
+| `api.go` | API handler, routing, CORS, and auth middleware |
+| `api_auth.go` | WebAuthn registration and login API endpoints |
+| `api_rules.go` | Per-user blocking rule CRUD API |
+| `api_subscriptions.go` | Per-user blocklist subscription API |
+| `elemhide_inject.go` | Element hiding CSS injection into HTML responses |
+| `inject.go` | Bootstrap script and picker injection into HTML responses |
+| `websocket.go` | WebSocket upgrade detection and tunnel support |
+| `session_map.go` | Client IP to session/credential mapping |
 | `log.go` | Request and error logging to stderr |
-| `proxy_test.go` | End-to-end tests for both HTTP and HTTPS proxy flows |
-| `pkg/blocklist/` | Blocklist parsing (adblock + hosts-file), hostname matching, element hiding |
+| `proxy_test.go` | End-to-end proxy tests |
+| `inject_test.go` | Script injection tests |
+| `api_test.go` | API endpoint tests |
+| `pkg/blocklist/` | Blocklist parsing (adblock + hosts-file), hostname matching, element hiding, resource type detection |
+| `pkg/store/` | SQLite persistence for credentials, sessions, rules, subscriptions, and cache |
+| `pkg/webauthn/` | Minimal WebAuthn server (ES256/P-256 with "none" attestation) |
+| `static/portal.html` | Portal management UI |
+| `static/setup.html` | Setup page for CA certificate installation |
+| `static/bootstrap.js` | Injected bootstrap script (keyboard shortcut, picker loader) |
+| `static/picker.js` | Element picker UI (Shadow DOM isolated) |
 | `scripts/build` | Build task |
 | `scripts/test` | Test task |
 | `scripts/dev` | Build + run task for development |
+| `scripts/browser` | Open a Playwright browser through the proxy |
+| `scripts/browser-no-proxy` | Open a Playwright browser without the proxy (for comparison) |
 
 ## Code style
 
diff --git a/README.md b/README.md
index 9865347..d733ba0 100644
--- a/README.md
+++ b/README.md
@@ -8,17 +8,20 @@ A proxy-server that filters ads from HTTPS/TLS traffic using adblock rules, with
 # Build
 go build -o ublproxy .
 
-# Run with EasyList
-ublproxy --blocklist https://easylist.to/easylist/easylist.txt
+# Run (EasyList + EasyPrivacy enabled by default)
+./ublproxy
 ```
 
-The proxy listens on `http://127.0.0.1:8080`. Configure your browser or OS to use it as an HTTP proxy.
+The proxy runs on two ports:
 
-An HTTPS portal runs on `https://127.0.0.1:8443` for account registration and rule management.
+- **HTTP `http://0.0.0.0:8080`** — Setup page and CA certificate download
+- **HTTPS `https://0.0.0.0:8443`** — Proxy, management portal, and API
+
+Configure your browser or OS to use `https://127.0.0.1:8443` as an HTTPS proxy.
 
 ### CA certificate
 
-The proxy generates a CA certificate to intercept HTTPS traffic. Visit `http://127.0.0.1:8080/` in your browser (while using the proxy) to download and install the CA certificate. Your browser/OS must trust this certificate for HTTPS filtering to work.
+The proxy generates a CA certificate to intercept HTTPS traffic. Visit `http://127.0.0.1:8080/` in your browser to download and install the CA certificate. Your browser/OS must trust this certificate for HTTPS filtering to work.
 
 ## Custom rules
 
@@ -73,12 +76,14 @@ Rules follow [adblock filter syntax](https://adblockplus.org/filter-cheatsheet).
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `-addr` | `127.0.0.1` | Address to listen on |
-| `-port` | `8080` | HTTP proxy port |
-| `-portal-port` | `8443` | HTTPS portal port |
+| `-addr` | `0.0.0.0` | Address to listen on |
+| `-http-port` | `8080` | HTTP port for setup page and CA certificate download |
+| `-https-port` | `8443` | HTTPS port for proxy, portal, and API |
+| `-hostname` | `localhost` | Portal hostname for WebAuthn and TLS cert (must be a domain, not an IP) |
 | `-ca-dir` | `~/.ublproxy` | Directory for CA certificate and key |
 | `-db` | `~/.ublproxy/ublproxy.db` | Path to SQLite database |
 | `-blocklist` | (none) | Path or URL to a blocklist file (repeatable) |
+| `-default-subscription` | EasyList + EasyPrivacy | Default blocklist subscription URL, always active for all users (repeatable) |
 
 ## Known limitations
 
-- 
2.51.2