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 0f7cdad..58dd97d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,23 +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"
- mmdc -i "$src" -o "$out" -c web/mermaid-config.json -b transparent
+ 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 bfa067f..fdf392e 100644
--- a/DECISIONS.md
+++ b/DECISIONS.md
@@ -98,4 +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/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
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 @@
-
\ 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 @@
-
\ 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 @@
-
\ No newline at end of file