Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .claude/skills/mermaid-diagram/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`.

Expand All @@ -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:
Expand All @@ -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 \
Expand Down Expand Up @@ -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 `<img>` tag in `web/index.html`
5. Update the matching mermaid code block in `README.md`
6. If adding a new diagram, add an `<img>` 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
<div class="arch-mode-card">
Expand Down
22 changes: 11 additions & 11 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
14 changes: 14 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,6 @@ ublproxy
mise.local.toml
.playwright-cli/
tmp/
.DS_Store
.DS_Store
# Generated from web/arch-*.mmd at deploy time (mise run diagrams locally)
web/arch-*.svg
4 changes: 3 additions & 1 deletion DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
9 changes: 9 additions & 0 deletions QUICK_START.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,15 @@ graph TB

Visit `https://<host>:<https-port>/` 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.
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion mise.toml
Original file line number Diff line number Diff line change
@@ -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"]
Loading
Loading