From 005ae3c6a08218eb6163a5dbc1ef979aeee3f805 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andri=20=C3=93skarsson?= Date: Tue, 3 Nov 2026 05:44:37 +0000 Subject: [PATCH 1/3] Document Windows Hello limitation and passkey registration workarounds ublproxy only supports ES256 passkeys. Chromium on Windows only offers Windows Hello when RS256 is also accepted, so Windows Chrome/Edge users need a phone, security key, password manager, or Firefox to register. Refs #3 --- DECISIONS.md | 1 + QUICK_START.md | 9 +++++++++ README.md | 1 + 3 files changed, 11 insertions(+) diff --git a/DECISIONS.md b/DECISIONS.md index bfa067f..57a75ad 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -99,3 +99,4 @@ - 2026-03-06 m+git@andri.dk — Built-in DNS resolver (`--dns-port`) for host-level ad blocking on devices that cannot install a CA certificate (smart TVs, game consoles, IoT). Reuses the existing `RuleSet.IsHostBlocked()` fast-path (O(1) hostname map with domain hierarchy walk) and per-user session mapping (client IP → credential ID). Blocked hostnames return `0.0.0.0` (A) / `::` (AAAA) with 60s TTL; non-blocked queries are forwarded to a configurable upstream resolver (`--dns-upstream`, default `1.1.1.1:53`). Non-address query types (MX, SRV, etc.) for blocked hosts return empty authoritative answers. Uses `github.com/miekg/dns` library. Opt-in: disabled by default (port 0), no impact on existing proxy behaviour. DNS blocks appear in the activity feed as `dns-blocked`. - 2026-03-06 m+git@andri.dk — Replaced single overview Mermaid diagram and two sequence diagrams with three mode-specific Mermaid graphs (explicit proxy, transparent proxy, DNS resolver). Each shows the topology for that mode. README uses inline mermaid code blocks (rendered by GitHub). Website uses pre-rendered SVGs generated from `.mmd` source files via `@mermaid-js/mermaid-cli` (`mmdc -t dark -b transparent`). Source of truth is the `.mmd` files in `web/`. - 2026-03-06 m+git@andri.dk — Automated SVG diagram regeneration. `mise run diagrams` task regenerates all SVGs from `.mmd` sources locally. CI `diagrams` job regenerates SVGs and fails if they differ from what's committed, catching forgotten rebuilds in PRs. SVGs remain committed (not generated at deploy time) so local previews work without a build step. +- 2026-11-03 aos@apacta.com — Keep WebAuthn ES256-only; do not add RS256 (issue #3). Chromium on Windows only offers Windows Hello when `pubKeyCredParams` includes RS256 (-257), but supporting it means parsing COSE RSA keys and verifying PKCS#1 v1.5 signatures in our hand-rolled WebAuthn code, plus a second stored key format. We chose to avoid the extra security-sensitive code, and we have no Windows machine to test Windows Hello against. Windows Chrome/Edge users register with a phone (hybrid/QR), hardware key, passkey-capable password manager, or Firefox. Documented in README "Known limitations" and QUICK_START. diff --git a/QUICK_START.md b/QUICK_START.md index b7d8703..806cc31 100644 --- a/QUICK_START.md +++ b/QUICK_START.md @@ -176,6 +176,15 @@ graph TB Visit `https://:/` and register a passkey. No username or password — the passkey is your identity. Anyone on the network can register. +> **Windows (Chrome / Edge):** Windows Hello is not offered. ublproxy only supports ES256 passkeys, and Chromium only shows Windows Hello when the site also accepts RS256. Register with one of these instead: +> +> - **A phone** — pick "iPhone, iPad, or Android device" in the dialog and scan the QR code (passkey stored on the phone, needs Bluetooth on the PC) +> - **A hardware security key** (YubiKey, etc.) +> - **A password manager** that stores passkeys (e.g. 1Password, Bitwarden browser extension) +> - **Firefox**, which handles platform authenticators differently +> +> You can also skip the portal entirely and configure blocking server-side with `--blocklist`. + ### 2. Pick elements to block Browse any website through the proxy and press **Alt+Shift+B** to open the element picker. diff --git a/README.md b/README.md index 4ad4108..19ccd48 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,7 @@ It's important to be aware, that by using this solution, you're essentially decr - **No re-compression**: After decompressing HTML (gzip/brotli/zstd) for CSS injection, HTML is served uncompressed to the client. This is fine when the proxy runs on localhost. - **Session-to-IP mapping**: Sessions are bound to client IP. Multiple users behind the same NAT IP share a single session slot (last login wins). - **Mobile proxy connection is unencrypted**: iOS and Android don't support HTTPS proxy connections. Mobile devices use a plain HTTP CONNECT proxy on port 8080. The CONNECT metadata (target hostname) is visible on the LAN, though the tunneled content is TLS-encrypted. The element picker is disabled on mobile connections to avoid leaking the session token. +- **No Windows Hello in Chrome/Edge**: Only ES256 passkeys are supported. Chromium on Windows only offers Windows Hello when RS256 is accepted, so Windows users must register with a phone, security key, passkey-capable password manager, or Firefox. See [Quick Start](QUICK_START.md#1-register-an-account). ## Comparison with DNS-based blockers From 0cf5f8aaaf3a2694fc1868bd31d4e98f8aef5413 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andri=20=C3=93skarsson?= Date: Tue, 3 Nov 2026 06:13:52 +0000 Subject: [PATCH 2/3] CI: run mermaid-cli without Chrome sandbox ubuntu-latest restricts unprivileged user namespaces via AppArmor, so Puppeteer's Chrome fails to launch with 'No usable sandbox'. Pass a puppeteer config with --no-sandbox; we only render our own .mmd files. --- .github/workflows/ci.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0f7cdad..606361c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,10 +26,14 @@ jobs: node-version: "22" - run: npm install -g @mermaid-js/mermaid-cli - name: Regenerate SVGs + # ubuntu-latest restricts unprivileged user namespaces via AppArmor, + # so Chrome's sandbox can't start. Rendering our own .mmd files on a + # throwaway runner doesn't need it. run: | + echo '{"args":["--no-sandbox"]}' > "$RUNNER_TEMP/puppeteer.json" for src in web/arch-*.mmd; do out="${src%.mmd}.svg" - mmdc -i "$src" -o "$out" -c web/mermaid-config.json -b transparent + mmdc -i "$src" -o "$out" -c web/mermaid-config.json -p "$RUNNER_TEMP/puppeteer.json" -b transparent done - name: Check for uncommitted changes run: | From 0f6b6d8bb0a8a6b8eaa57db16010155c775e9827 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andri=20=C3=93skarsson?= Date: Tue, 3 Nov 2026 08:34:15 +0000 Subject: [PATCH 3/3] Build diagram SVGs at deploy time; pin mermaid-cli 12.2.0 The committed SVGs could never match a CI render: Chrome measures monospace text with the machine's font and bakes the sizes into the SVG, so identical .mmd sources render differently on macOS and Ubuntu. - Gitignore web/arch-*.svg and render them in pages.yml before upload - CI diagrams job now only checks that every .mmd renders - Pin @mermaid-js/mermaid-cli to 12.2.0 in mise.toml, ci.yml, pages.yml - Update mermaid-diagram skill and DECISIONS.md --- .claude/skills/mermaid-diagram/SKILL.md | 16 ++++++++-------- .github/workflows/ci.yml | 16 ++++++---------- .github/workflows/pages.yml | 14 ++++++++++++++ .gitignore | 4 +++- DECISIONS.md | 3 ++- mise.toml | 2 +- web/arch-dns.svg | 1 - web/arch-explicit.svg | 1 - web/arch-transparent.svg | 1 - 9 files changed, 34 insertions(+), 24 deletions(-) delete mode 100644 web/arch-dns.svg delete mode 100644 web/arch-explicit.svg delete mode 100644 web/arch-transparent.svg diff --git a/.claude/skills/mermaid-diagram/SKILL.md b/.claude/skills/mermaid-diagram/SKILL.md index 48501ea..2d5b098 100644 --- a/.claude/skills/mermaid-diagram/SKILL.md +++ b/.claude/skills/mermaid-diagram/SKILL.md @@ -6,7 +6,7 @@ allowed-tools: Bash(mise:*), Bash(mmdc:*), Read, Write, Edit, Glob # Mermaid Diagrams -Architecture diagrams are authored as Mermaid `.mmd` files and pre-rendered to SVGs for the static website. The README uses inline mermaid code blocks (rendered natively by GitHub). +Architecture diagrams are authored as Mermaid `.mmd` files and rendered to SVGs for the static website when it is deployed. The README uses inline mermaid code blocks (rendered natively by GitHub). ## Source files @@ -17,7 +17,7 @@ Architecture diagrams are authored as Mermaid `.mmd` files and pre-rendered to S | `web/arch-dns.mmd` | DNS resolver mode diagram | | `web/mermaid-config.json` | Custom theme matching the website palette | -The `.mmd` files are the **source of truth**. The `.svg` files are generated artifacts. The README contains the same mermaid syntax inline as fenced code blocks. +The `.mmd` files are the **source of truth**. The `.svg` files are generated artifacts: they are gitignored and never committed. The Pages deploy (`.github/workflows/pages.yml`) renders them from the `.mmd` sources, and CI only checks that every `.mmd` renders. The README contains the same mermaid syntax inline as fenced code blocks. When updating a diagram, update **both** the `.mmd` file and the corresponding mermaid code block in `README.md`. @@ -27,7 +27,7 @@ The mermaid CLI (`mmdc`) is installed via mise: ```toml # mise.toml -"npm:@mermaid-js/mermaid-cli" = "latest" +"npm:@mermaid-js/mermaid-cli" = "12.2.0" # keep in sync with .github/workflows/{ci,pages}.yml ``` Ensure it's installed: @@ -38,7 +38,7 @@ mise install ## Generating SVGs -Generate a single diagram: +SVGs are only needed locally to preview `web/index.html`; don't commit them. Regenerate all of them with `mise run diagrams`, or a single diagram: ```bash mise exec -- mmdc \ @@ -152,14 +152,14 @@ GitHub renders these natively. The syntax should match the `.mmd` files exactly. 2. Generate a preview PNG: `mise exec -- mmdc -i web/arch-foo.mmd -o tmp/arch-foo.png -c web/mermaid-config.json -b transparent` 3. Inspect the PNG with the Read tool 4. Iterate until it looks right -5. Generate the final SVG: `mise exec -- mmdc -i web/arch-foo.mmd -o web/arch-foo.svg -c web/mermaid-config.json -b transparent` -6. Update the matching mermaid code block in `README.md` -7. If adding a new diagram, add an `` tag in `web/index.html` +5. Update the matching mermaid code block in `README.md` +6. If adding a new diagram, add an `` tag in `web/index.html` +7. Commit the `.mmd` change only. The SVG is built at deploy time ## Adding a new diagram 1. Create `web/arch-newmode.mmd` with the mermaid source -2. Generate SVG: `mise exec -- mmdc -i web/arch-newmode.mmd -o web/arch-newmode.svg -c web/mermaid-config.json -b transparent` +2. Preview it locally with `mise run diagrams` (generates the gitignored SVG) 3. Add to `web/index.html` inside the `.arch-modes` grid: ```html
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 606361c..58dd97d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,27 +18,23 @@ jobs: - run: go test ./... diagrams: + # Only checks that every .mmd source renders. The SVGs themselves are + # built at deploy time (pages.yml), so there's nothing to compare against. runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "22" - - run: npm install -g @mermaid-js/mermaid-cli - - name: Regenerate SVGs + # Keep in sync with mise.toml and pages.yml + - run: npm install -g @mermaid-js/mermaid-cli@12.2.0 + - name: Render diagrams # ubuntu-latest restricts unprivileged user namespaces via AppArmor, # so Chrome's sandbox can't start. Rendering our own .mmd files on a # throwaway runner doesn't need it. run: | echo '{"args":["--no-sandbox"]}' > "$RUNNER_TEMP/puppeteer.json" for src in web/arch-*.mmd; do - out="${src%.mmd}.svg" + out="$RUNNER_TEMP/$(basename "${src%.mmd}").svg" mmdc -i "$src" -o "$out" -c web/mermaid-config.json -p "$RUNNER_TEMP/puppeteer.json" -b transparent done - - name: Check for uncommitted changes - run: | - if ! git diff --quiet web/arch-*.svg; then - echo "::error::SVG diagrams are out of date. Run 'mise run diagrams' and commit the result." - git diff --stat web/arch-*.svg - exit 1 - fi diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 1da9cf3..7fae137 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -23,6 +23,20 @@ jobs: steps: - uses: actions/checkout@v4 - uses: actions/configure-pages@v5 + - uses: actions/setup-node@v4 + with: + node-version: "22" + # Keep in sync with mise.toml and ci.yml + - run: npm install -g @mermaid-js/mermaid-cli@12.2.0 + - name: Build diagram SVGs + # SVGs are generated artifacts (gitignored); render them from the + # .mmd sources. --no-sandbox: see the note in ci.yml. + run: | + echo '{"args":["--no-sandbox"]}' > "$RUNNER_TEMP/puppeteer.json" + for src in web/arch-*.mmd; do + out="${src%.mmd}.svg" + mmdc -i "$src" -o "$out" -c web/mermaid-config.json -p "$RUNNER_TEMP/puppeteer.json" -b transparent + done - uses: actions/upload-pages-artifact@v3 with: path: web diff --git a/.gitignore b/.gitignore index 99950d4..61a9a4b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,6 @@ ublproxy mise.local.toml .playwright-cli/ tmp/ -.DS_Store \ No newline at end of file +.DS_Store +# Generated from web/arch-*.mmd at deploy time (mise run diagrams locally) +web/arch-*.svg diff --git a/DECISIONS.md b/DECISIONS.md index 57a75ad..fdf392e 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -98,5 +98,6 @@ - 2026-03-06 m+git@andri.dk — Reordered `getUserRules` to check in-memory cache before the `p.store == nil` guard. Previously, pre-cached user rules (e.g. loaded during rule reload) were inaccessible when the store was nil, which made the function order-dependent on initialization. - 2026-03-06 m+git@andri.dk — Built-in DNS resolver (`--dns-port`) for host-level ad blocking on devices that cannot install a CA certificate (smart TVs, game consoles, IoT). Reuses the existing `RuleSet.IsHostBlocked()` fast-path (O(1) hostname map with domain hierarchy walk) and per-user session mapping (client IP → credential ID). Blocked hostnames return `0.0.0.0` (A) / `::` (AAAA) with 60s TTL; non-blocked queries are forwarded to a configurable upstream resolver (`--dns-upstream`, default `1.1.1.1:53`). Non-address query types (MX, SRV, etc.) for blocked hosts return empty authoritative answers. Uses `github.com/miekg/dns` library. Opt-in: disabled by default (port 0), no impact on existing proxy behaviour. DNS blocks appear in the activity feed as `dns-blocked`. - 2026-03-06 m+git@andri.dk — Replaced single overview Mermaid diagram and two sequence diagrams with three mode-specific Mermaid graphs (explicit proxy, transparent proxy, DNS resolver). Each shows the topology for that mode. README uses inline mermaid code blocks (rendered by GitHub). Website uses pre-rendered SVGs generated from `.mmd` source files via `@mermaid-js/mermaid-cli` (`mmdc -t dark -b transparent`). Source of truth is the `.mmd` files in `web/`. -- 2026-03-06 m+git@andri.dk — Automated SVG diagram regeneration. `mise run diagrams` task regenerates all SVGs from `.mmd` sources locally. CI `diagrams` job regenerates SVGs and fails if they differ from what's committed, catching forgotten rebuilds in PRs. SVGs remain committed (not generated at deploy time) so local previews work without a build step. +- 2026-03-06 m+git@andri.dk — ~~Automated SVG diagram regeneration. `mise run diagrams` task regenerates all SVGs from `.mmd` sources locally. CI `diagrams` job regenerates SVGs and fails if they differ from what's committed, catching forgotten rebuilds in PRs. SVGs remain committed (not generated at deploy time) so local previews work without a build step.~~ Superseded: SVGs are now built at deploy time (see 2026-11-03 entry below). - 2026-11-03 aos@apacta.com — Keep WebAuthn ES256-only; do not add RS256 (issue #3). Chromium on Windows only offers Windows Hello when `pubKeyCredParams` includes RS256 (-257), but supporting it means parsing COSE RSA keys and verifying PKCS#1 v1.5 signatures in our hand-rolled WebAuthn code, plus a second stored key format. We chose to avoid the extra security-sensitive code, and we have no Windows machine to test Windows Hello against. Windows Chrome/Edge users register with a phone (hybrid/QR), hardware key, passkey-capable password manager, or Firefox. Documented in README "Known limitations" and QUICK_START. +- 2026-11-03 aos@apacta.com — Diagram SVGs are built at deploy time instead of being committed. The CI check comparing committed SVGs to a fresh render could never pass reliably: Chrome measures `monospace` text with whatever font the machine has, and those measurements are baked into the SVG, so a Mac and an Ubuntu runner produce different files from identical `.mmd` sources. `web/arch-*.svg` is now gitignored; `pages.yml` renders them before uploading the site, and the CI `diagrams` job only checks that every `.mmd` renders. `@mermaid-js/mermaid-cli` is pinned to 12.2.0 in `mise.toml`, `ci.yml` and `pages.yml` (bump all three together). In CI, mmdc runs Chrome with `--no-sandbox` because `ubuntu-latest` blocks the unprivileged user namespaces Chrome's sandbox needs; acceptable since it only renders our own sources on a throwaway runner. Local preview of `web/index.html` needs `mise run diagrams` first. diff --git a/mise.toml b/mise.toml index 664ca4a..b286579 100644 --- a/mise.toml +++ b/mise.toml @@ -1,7 +1,7 @@ [tools] go = "1.25" "npm:@playwright/cli" = "latest" -"npm:@mermaid-js/mermaid-cli" = "latest" +"npm:@mermaid-js/mermaid-cli" = "12.2.0" # keep in sync with .github/workflows/{ci,pages}.yml [task_config] includes = ["scripts"] diff --git a/web/arch-dns.svg b/web/arch-dns.svg deleted file mode 100644 index 2a35f82..0000000 --- a/web/arch-dns.svg +++ /dev/null @@ -1 +0,0 @@ -

forward

ublproxy :53

Blocklist
Engine

Smart TV

IoT

Upstream
DNS

\ No newline at end of file diff --git a/web/arch-explicit.svg b/web/arch-explicit.svg deleted file mode 100644 index d8cb8b4..0000000 --- a/web/arch-explicit.svg +++ /dev/null @@ -1 +0,0 @@ -

ublproxy :8443 / :8080

Blocklist
Engine

CA + Cert
Cache

Desktop

Laptop

Phone

Internet

\ No newline at end of file diff --git a/web/arch-transparent.svg b/web/arch-transparent.svg deleted file mode 100644 index 115b892..0000000 --- a/web/arch-transparent.svg +++ /dev/null @@ -1 +0,0 @@ -

redirect
:80 + :443

Device

Firewall

ublproxy

Internet

\ No newline at end of file