# Decisions

- 2026-02-25 m+git@andri.dk — Validate upstream TLS certificates (removed `InsecureSkipVerify`). The proxy is the user's trust boundary; it must verify upstream server identity.
- 2026-02-25 m+git@andri.dk — Don't manipulate `Accept-Encoding`. The proxy forwards the client's encoding preferences to upstream and handles CSS injection based on the response `Content-Encoding`. Gzip and brotli HTML are decompressed for injection; other encodings pass through without injection. Non-HTML resources are never touched.
- 2026-02-25 m+git@andri.dk — Skip CSS injection for HEAD requests. HEAD responses have no body per HTTP spec.
- 2026-02-25 m+git@andri.dk — Hostname-only rules with `$options` (e.g. `||host^$third-party`) bypass the fast-path hostname map and go through compiled rules to preserve option evaluation.
- 2026-02-25 m+git@andri.dk — `$match-case` rules receive both the original-case and lowercased URL so they match correctly through the optimized `ShouldBlockRequest` path.
- 2026-02-25 m+git@andri.dk — Domain-indexed rule lookup: `||domain` rules are partitioned into `map[string][]*Rule` keyed by domain suffix. At match time, walk up the hostname hierarchy instead of scanning all rules.
- 2026-02-25 m+git@andri.dk — Literal-skip pattern matching: use `strings.Index` to jump to candidate positions for leading literals and post-wildcard literals, avoiding byte-by-byte scanning.
- 2026-02-25 m+git@andri.dk — Cache `ElementHidingForDomain` results in `sync.Map` since the ruleset is immutable after loading.
- 2026-02-25 m+git@andri.dk — Serve decompressed HTML to client after CSS injection (no re-compression). Proxy-to-client hop is typically localhost.
- 2026-02-25 m+git@andri.dk — Added `github.com/andybalholm/brotli` (pure Go, zero transitive runtime deps) for brotli decompression in CSS injection. First third-party dependency — warranted because brotli is the dominant encoding for HTML on modern CDNs and the stdlib has no brotli support.
- 2026-02-25 m+git@andri.dk — WebSocket upgrade supported for both ws:// and wss://. Upgrade headers are re-added after hop-by-hop stripping, then bidirectional copy bridges client and upstream after 101.
- 2026-02-25 m+git@andri.dk — Cert cache has no eviction. Certs are generated with 24h validity. Acceptable for personal use.
- 2026-02-26 m+git@andri.dk — ~~Element hiding via HTML element replacement.~~ Superseded: element hiding is now CSS-only (see 2026-02-26 entry below).
- 2026-02-26 m+git@andri.dk — Added `golang.org/x/net` (zero transitive runtime deps, Go team maintained) for HTML tokenization in src-based resource stripping.
- 2026-02-26 m+git@andri.dk — Blocked CONNECT requests return 403 Forbidden instead of 204 No Content. Browsers hang on 204 because they expect a tunnel; 403 makes them fail fast.
- 2026-02-26 m+git@andri.dk — Removed Playwright from the project. Playwright's screenshot and snapshot commands wait for `document.fonts.ready`, which never resolves when the MITM proxy blocks ad-network domains that serve fonts. curl is a better fit for proxy testing.
- 2026-02-26 m+git@andri.dk — Re-added playwright-cli for browser testing. Previous HTTPS timeouts were caused by environment variable configuration not being picked up. Fixed by using a declarative config file (`playwright-cli-proxy.json`) with `contextOptions.ignoreHTTPSErrors` and `contextOptions.proxy` instead of env vars.
- 2026-02-26 m+git@andri.dk — Elements that load external resources (script, iframe, object, embed) are stripped during HTML rewriting when their resource URL resolves to a blocked address. Defense-in-depth alongside network-level blocking: stripping the element from the DOM prevents the browser from attempting the load. `srcBlockableTags` maps tag name to URL attribute (`src` for most, `data` for object). Void elements (embed) skip the `skipUntilClose` step. Relative and protocol-relative URLs are resolved against the page origin. Inline scripts (no `src`) are not affected.
- 2026-02-26 m+git@andri.dk — Disabled HTTP/2 on upstream transport (`TLSNextProto` set to empty map). Go's default `http.Transport` negotiates HTTP/2 via ALPN, which caused indefinite hangs on certain Cloudflare-hosted domains (`s3-bm-adtech.berlingskemedia.net`, `s3-common-jscdn.berlingskemedia.net`). The proxy serializes requests over HTTP/1.1 on the client side, so HTTP/2 multiplexing provides no benefit. Forcing HTTP/1.1 upstream eliminates the hang and matches what most MITM proxies do.
- 2026-02-26 m+git@andri.dk — Preserve original attribute case in HTML rewriting. `golang.org/x/net/html.Tokenizer.Raw()` returns reconstructed HTML with lowercased attribute names after `TagAttr()` is called. This broke React hydration on SSR sites (e.g. `charSet` → `charset`, `viewBox` → `viewbox`). Fix: save `Raw()` output before consuming attributes and use the saved bytes for pass-through writes.
- 2026-02-26 m+git@andri.dk — ~~CSS injection + element replacement for all element hiding selectors.~~ Superseded: element hiding is now CSS-only (see 2026-02-26 entry below).
- 2026-02-26 m+git@andri.dk — Resource type detection for adblock content-type options (`$script`, `$image`, `$stylesheet`, `$xmlhttprequest`, `$subdocument`, `$media`, `$font`, `$object`, `$websocket`, `$document`). Previously these options were silently ignored, causing rules like `/adengine.js$script` to block all request types instead of just scripts — over-blocking that breaks sites. Detection uses `Sec-Fetch-Dest` header (primary, all modern browsers), `Accept` header heuristics (fallback), and URL file extension (last resort). Unknown resource type (no signal available) matches any type constraint for backward compatibility. `$popup` is parsed but not enforceable at proxy level (fails open). `$generichide` deferred to follow-up.
- 2026-02-26 m+git@andri.dk — `-blocklist` flag supports remote URLs (`http://`, `https://`) in addition to local file paths. Downloaded once at startup using a dedicated `http.Client` with 30-second timeout. No caching or periodic refresh — same semantics as local files. Refactored `LoadFile` to use `LoadReader(io.Reader)` so all loading paths share the same line-by-line parsing. Go's `http.DefaultTransport` handles gzip decompression transparently.
- 2026-02-26 m+git@andri.dk — Benchmarked `ShouldBlockRequest` with full EasyList (89K lines, 55K hostnames, 9K URL rules). Results on Apple M3: non-blocked URL 64µs, blocked-by-hostname 1.6µs, blocked-by-domain-rule 45µs, blocked-by-generic-rule 58µs. Zero allocations. No optimization needed — rule matching adds <1% to page load time.
- 2026-02-26 m+git@andri.dk — Added `modernc.org/sqlite` (pure Go, no CGO) for persistent storage of passkey credentials, sessions, and user-created blocking rules. Binary grows ~7MB (9MB → 16MB). Chose pure-Go over CGO SQLite to keep zero C compiler requirement.
- 2026-02-26 m+git@andri.dk — Added `fxamacker/cbor/v2` (minimal, zero transitive deps) for CBOR decoding in WebAuthn attestation parsing. Only ES256 (P-256 ECDSA) with "none" attestation is supported — covers all modern passkey authenticators.
- 2026-02-26 m+git@andri.dk — Passkey (WebAuthn) authentication with no usernames or passwords. A credential IS the user identity. The credential ID is the foreign key for sessions and rules. Open registration — anyone on the network can register a passkey. Trust boundary is the network.
- 2026-02-26 m+git@andri.dk — Minimal WebAuthn server implementation using stdlib crypto + fxamacker/cbor instead of a full WebAuthn library. Server generates challenges (crypto/rand), parses CBOR attestation objects to extract COSE public keys, and verifies ECDSA signatures. ~250 lines vs thousands in go-webauthn/webauthn.
- 2026-02-26 m+git@andri.dk — Dual-port architecture: HTTP proxy on port 8080 (unchanged), HTTPS portal on port 8443 (new). WebAuthn requires a secure context (HTTPS), and LAN clients access the proxy from non-localhost IPs. The portal's TLS cert is signed by the proxy's own CA, which clients already trust.
- 2026-02-26 m+git@andri.dk — Session-token auth for the rule management API. Portal issues a Bearer token after passkey authentication. Tokens are 32 bytes from crypto/rand, stored in SQLite with 30-day expiry. The injected script (future phase) will embed the token in a closure to prevent third-party page scripts from accessing it.
- 2026-02-26 m+git@andri.dk — Bootstrap script injected inline into every HTML response (not as external `<script src>`). Avoids CSP issues on strict sites and removes the need to intercept `/__ublproxy__/` paths on arbitrary domains. The bootstrap is ~40 lines, minified into an IIFE. Keyboard shortcut: Alt+Shift+B.
- 2026-02-26 m+git@andri.dk — Client IP → session token mapping (`sessionMap`) for script injection. When a user authenticates on the portal, their session token is associated with their client IP. The proxy looks up the token when injecting the bootstrap script. Simple and correct for home/office LAN proxy where each device has a unique IP. No session = no script injection.
- 2026-02-26 m+git@andri.dk — The full element picker UI is lazy-loaded via `fetch()` from the portal's `/api/picker.js` endpoint when the user presses Alt+Shift+B. The picker code is executed with `new Function()` to keep portal URL and session token in scope. Auth is required (Bearer token in header), preventing unauthorized access to the picker code.
- 2026-02-26 m+git@andri.dk — Element picker UI uses Shadow DOM (closed mode) to isolate styles from the host page. All picker CSS lives inside the shadow root, preventing conflicts in both directions. The highlight overlay uses `position:fixed` with `pointer-events:none` and `document.elementFromPoint()` for hover detection.
- 2026-02-26 m+git@andri.dk — CSS selector generation priority: `#id` > `.class` (if unique) > `tag.class` > `tag[attr]` > parent path with `nth-child`. Prefers short selectors that match adblock element hiding syntax. Uses `CSS.escape()` for safety with special characters in IDs and class names.
- 2026-02-26 m+git@andri.dk — Rule hot-reload via `atomic.Pointer[blocklist.RuleSet]`. When a user creates, deletes, or toggles a rule via the API, the full RuleSet is rebuilt from static blocklists + all enabled database rules, then atomically swapped. Readers never block. Rebuilds are serialized with a mutex to prevent concurrent rebuilds. The API handler triggers reloads via a callback (`onRulesChanged`) fired asynchronously in a goroutine so the HTTP response isn't delayed.
- 2026-02-26 m+git@andri.dk — CORS: reflect the `Origin` request header instead of using a hardcoded portal origin. Injected scripts run on arbitrary proxied pages (e.g. `https://example.com`) and make cross-origin requests to the portal API. All API endpoints require a Bearer token (not cookies), so reflecting the origin doesn't weaken security — an attacker without the token can't use the API regardless of CORS policy. `Vary: Origin` header included for correct caching.
- 2026-02-26 m+git@andri.dk — Element hiding is now CSS-only (`display: none !important`). Previously, simple selectors also stripped matched elements from the DOM via HTML tokenizer rewriting. This caused blank pages when generic EasyList selectors (e.g. `##[data-ad-cls]`, `##.ad-banner`) matched direct children of `<body>` that were legitimate page wrappers. CSS-only hiding matches browser adblocker behavior (uBlock Origin uses CSS for element hiding). Src-based stripping of `script`/`iframe`/`object`/`embed` with blocked URLs is kept — these load external resources and stripping them prevents the browser from even attempting the request. Deleted `SelectorMatch`, `ClassifySelector`, `matchesAny`, `matchesAnyWithAttrs` and related dead code.
- 2026-02-26 m+git@andri.dk — Added passkey registration and login UI to the portal page. Inline vanilla JavaScript handles the full WebAuthn flow: base64url↔ArrayBuffer conversion, `navigator.credentials.create()` for registration, `navigator.credentials.get()` for login, and session token storage in `localStorage`. Session validity is checked on page load via `GET /api/rules`. No external JS dependencies.
- 2026-02-26 m+git@andri.dk — WebAuthn requires a domain name as RP ID — IP addresses are explicitly disallowed by the W3C spec (browsers return `SecurityError`). Added `--hostname` flag (default `"localhost"`) to set the portal's domain identity for WebAuthn RPID, origin, and TLS cert. Users on a LAN can set `--hostname=myhost.local` and configure DNS/hosts accordingly.
- 2026-02-26 m+git@andri.dk — Listen on all interfaces by default (`--addr=0.0.0.0`) so LAN clients can use the proxy. The LAN IP is auto-detected for the portal TLS certificate SANs (so `https://<LAN-IP>:8443` works for CA cert download, etc.), but the portal's WebAuthn identity is always the `--hostname` value.
- 2026-02-26 m+git@andri.dk — Portal TLS certificate includes multiple SANs: the `--hostname` value (DNS), `localhost` (DNS), `127.0.0.1` (IP), and the auto-detected LAN IP (IP). This allows TLS-valid access from any address, even though WebAuthn only works from the canonical hostname.
- 2026-02-26 m+git@andri.dk — MITM certs for loopback IPs (`127.0.0.1`) now include `localhost` as a DNS SAN alongside the IP SAN. Browsers check the typed hostname against cert SANs, so visiting `https://localhost` with a cert that only has an IP SAN for `127.0.0.1` fails validation.
- 2026-02-26 m+git@andri.dk — Extracted portal HTML from Go string constant to `static/portal.html` with `go:embed`. Same deployment (single binary), but proper syntax highlighting and editor support.
- 2026-02-26 m+git@andri.dk — Per-user blocklist subscriptions stored in `blocklist_subscriptions` table. Users can add/remove/toggle blocklist URLs via the portal UI. Subscription URLs are merged with CLI `--blocklist` flags during rule reload. CLI flags remain as system-wide defaults; user subscriptions are additive.
- 2026-02-26 m+git@andri.dk — Blocklist download cache in `blocklist_cache` SQLite table. Remote URLs are downloaded once and cached for 24 hours. `reloadRules()` reads from cache instead of re-fetching on every rule change. Stale cache is used as fallback if re-download fails. "Refresh All" button clears cache and triggers re-download. Cache stored in SQLite (not filesystem) to keep everything in one place.
- 2026-02-26 m+git@andri.dk — Portal page now shows authenticated users a rule management panel (list/add/toggle/delete rules) and a blocklist subscription panel (list/add/toggle/delete subscriptions, refresh all, suggested lists). Both panels are hidden when not authenticated. No external JS dependencies.
- 2026-02-26 m+git@andri.dk — Per-user layered rule architecture. Split `rules atomic.Pointer[RuleSet]` into `baselineRules` (always-active, from `--blocklist`) and `userRules sync.Map` (per-credential, lazily loaded from DB). Layered evaluation: user `@@` exceptions override baseline blocks, then user blocks, then baseline blocks. User `#@#` element hiding exceptions suppress baseline `##` selectors. API mutations invalidate only the affected user's cached RuleSet. *(Originally also included `--default-subscription` in baseline — removed 2026-02-27.)*
- 2026-02-26 m+git@andri.dk — Session map extended from `IP→token` to `IP→{Token, CredentialID}`. The credential ID identifies which user is on which IP, enabling per-user rule lookup at all proxy layers (CONNECT, HTTP, element hiding injection).
- 2026-02-26 m+git@andri.dk — ~~`--default-subscription` CLI flag (repeatable). Defaults to EasyList + EasyPrivacy if none specified.~~ Removed 2026-02-27. Replaced by users managing their own subscriptions via the portal UI.
- 2026-02-26 m+git@andri.dk — Baseline rules loaded synchronously at startup (`reloadBaseline()` called after DB setup). Ensures rules are ready before any traffic arrives. Remote subscriptions use DB cache with 24h TTL, so subsequent starts are fast.
- 2026-02-27 m+git@andri.dk — Switched CLI flag parsing from stdlib `flag` to `github.com/urfave/cli/v3` (zero production dependencies). Every flag now has a corresponding `UBLPROXY_*` environment variable via `Sources: cli.EnvVars(...)`, making the proxy Docker-friendly without an entrypoint wrapper script. Removed the custom `stringSlice` type — urfave/cli has built-in `StringSliceFlag` for repeatable flags.
- 2026-02-27 m+git@andri.dk — Added multi-stage Dockerfile. Build stage uses `golang:1.25-alpine` with `CGO_ENABLED=0`. Runtime stage uses `alpine:latest` (~5MB) with system CA certificates for outgoing HTTPS. Data directory mounted at `/data` holds the CA cert/key and SQLite database. Ports 8080/8443 are configurable via `UBLPROXY_HTTP_PORT`/`UBLPROXY_HTTPS_PORT` env vars or CLI flags.
- 2026-02-27 m+git@andri.dk — Moved setup and usage docs from README to QUICK_START.md. README is now a short project overview with links. Added "restart your browser" note to CA trust instructions in setup.html and QUICK_START.md — browsers cache certificate trust state and won't recognize a newly trusted CA until restarted.
- 2026-02-27 m+git@andri.dk — Host-level `@@` exception rules now trigger passthrough tunneling instead of MITM. When `isHostExcepted` returns true at CONNECT time, the proxy dials the upstream server and bidirectionally copies raw TCP bytes — the client's TLS session goes directly to the upstream without interception. No new flags, syntax, or DB tables needed; uses existing `@@||domain^` rules evaluated through the same layered system (per-user exceptions override baseline). Useful for banking and other sensitive sites where MITM is undesirable.
- 2026-02-27 m+git@andri.dk — Removed `--default-subscription` flag entirely. Baseline (`--blocklist`) applies to all traffic including unauthenticated. Authenticated users manage their own subscriptions (EasyList, EasyPrivacy, etc.) via the portal's Subscriptions page, which includes a "Popular Lists" section with one-click add buttons. Removed `is_default` column and ALTER TABLE migration from `blocklist_subscriptions`.
- 2026-02-27 m+git@andri.dk — In-memory activity log (ring buffer, capacity 1000). Records blocked, passthrough, and element-hidden events at key proxy decision points. API endpoints: `GET /api/activity?limit=N` (recent events) and `GET /api/activity/stats` (counts by type). Ephemeral — resets on restart. No database storage, no disk I/O overhead.
- 2026-02-27 m+git@andri.dk — Multi-page portal UI replacing single-page `portal.html`. Four pages: Dashboard (auth + stats), Rules (CRUD + search + syntax help), Subscriptions (default lists with badges + user lists + suggested), Activity (filtered feed, auto-refresh). Shared styles in `shared.css` and shared auth/nav logic in `shared.js`. All files embedded via `go:embed`. Vanilla HTML/CSS/JS — no framework, no build step.
- 2026-02-27 m+git@andri.dk — Static files served from `/static/*` using an embedded file map in `portal.go`. Files include `shared.css` and `shared.js`. 5-minute cache with `Cache-Control: public, max-age=300`.
- 2026-02-27 m+git@andri.dk — Mobile device support (iOS/Android). iOS and Android do not support the `HTTPS` PAC proxy type, so the HTTP port (8080) now also accepts CONNECT tunnels and HTTP forwarding for mobile clients. A separate `/mobile.pac` file returns `PROXY host:port` (plain HTTP) instead of `HTTPS host:port`. The bootstrap script (element picker + session token) is not injected on plain HTTP connections to prevent leaking the session token over unencrypted traffic — detection uses `r.TLS == nil`. CSS element hiding and resource stripping still apply normally. Added `github.com/skip2/go-qrcode` (pure Go, zero transitive runtime deps) for a QR code on the setup page linking to the HTTP setup URL.
- 2026-02-28 m+git@andri.dk — PAC files bypass captive portal / connectivity check domains (`captive.apple.com`, `connectivitycheck.gstatic.com`, `connectivitycheck.android.com`, `clients3.google.com`, `www.msftconnecttest.com`, `dns.msftncsi.com`, `detectportal.firefox.com`). These domains return `DIRECT` so the OS can verify internet connectivity after wifi connects. Without this, the proxy (or its blocklists) could interfere with the expected responses, causing the OS to show a captive portal page or report "no internet".
- 2026-02-28 m+git@andri.dk — Removed 18 redundant tests (~320 lines net). Lines of code are a liability. Four strict subsets (e.g. `TestIframeStrippingWithScriptStripping` subsumed by `TestAllBlockableElementsTogether`), five HTTPS transport duplicates consolidated into one `TestHTTPSHTMLRewriting` (the rewriting logic is transport-independent), five unit/integration overlaps where both layers tested identical behavior, and four low-value tests (CSS on void elements, trivial byte comparison, etc.).
- 2026-02-28 m+git@andri.dk — Moved `pkg/` to `internal/`. This is an application, not a library — `internal/` enforces that `blocklist`, `store`, and `webauthn` packages can't be imported by external code.
- 2026-02-28 m+git@andri.dk — Extracted `ca.go` + `cert.go` into `internal/ca/` and `mobileconfig.go` into `internal/mobileconfig/`. These had zero dependencies on any `main`-package type — genuinely independent domain concepts (CA management, cert caching, Apple profile generation). Decided against extracting API code (`api*.go`) into `internal/api/` — the API handlers are deeply interleaved with the proxy (sessions, activity log, rule reload callbacks) and would require plumbing-only packages to break import cycles. File-level separation (`api_*.go` prefix) is sufficient for a single-binary proxy.
- 2026-02-28 m+git@andri.dk — GitHub Actions CI/CD. `ci.yml` runs `go test ./...` on pull requests. `release.yml` runs on every push to main: tests, cross-compiles binaries for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, creates a GitHub Release (prerelease for commits, full release for `v*` tags), and builds+pushes multi-arch Docker images to `ghcr.io`. Version embedded via `-ldflags "-X main.version=..."` — tag name for tagged builds, short SHA for trunk builds. `ublproxy --version` now works.
- 2026-02-28 m+git@andri.dk — PAC scripts bypass all private/reserved network ranges (RFC 1918 `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, link-local `169.254.0.0/16`) and `*.local` mDNS hostnames. No reason to proxy local traffic — blocklists target public ad/tracking domains. Uses `isInNet()` on IP-literal hosts (no `dnsResolve()` overhead) and `shExpMatch()` for `*.local`. Fixes portal inaccessible when `--hostname` is a `.local` domain or when accessing via LAN IP — the PAC was directing portal traffic back through the proxy, causing a self-CONNECT loop.
- 2026-02-28 m+git@andri.dk — Unified desktop and mobile PAC templates into a single `pacTmpl`. The only difference is the proxy directive (`HTTPS` vs `PROXY`), now parameterized via `pacData.ProxyDirective`. Eliminates duplicated bypass logic that had to be maintained in two places.
- 2026-02-28 m+git@andri.dk — Admin role for credential-based authorization. `is_admin INTEGER NOT NULL DEFAULT 0` column on `credentials` table. First registered credential is auto-promoted to admin. Existing databases are migrated with `ALTER TABLE ADD COLUMN` (ignore duplicate column error) and an idempotent `UPDATE` that promotes the earliest credential if no admin exists. `GET /api/whoami` returns admin status for the current session — replaces the `GET /api/rules` session probe in `shared.js`. Activity feed (`GET /api/activity`) restricted to admin only; activity stats remain accessible to all authenticated users. Admin Users page (`/users`) with `GET /api/users` (list) and `PATCH /api/users/:id` (toggle admin). Admins cannot modify their own admin status. Nav links use `data-admin` attribute (alongside existing `data-auth`) for admin-only visibility, managed by `shared.js` based on the whoami response.
- 2026-02-28 m+git@andri.dk — Transparent proxy mode (`--transparent` flag). Switches ublproxy from explicit proxy to transparent proxy on the same ports. HTTP port intercepts redirected plain HTTP traffic; HTTPS port intercepts redirected TLS traffic. Firewall rules (iptables/nftables/pf, outside ublproxy's scope) redirect VLAN port 80/443 traffic to the proxy ports. Explicit proxy features (CONNECT tunnels, PAC files) are disabled in this mode.
- 2026-02-28 m+git@andri.dk — SNI-based destination detection for transparent HTTPS. Instead of platform-specific `SO_ORIGINAL_DST` syscalls, the proxy peeks at the TLS ClientHello to extract the SNI hostname. For HTTP, the `Host` header determines the destination. This makes the code fully cross-platform with no OS-specific syscalls. Trade-off: connections without SNI (extremely rare) cannot be proxied.
- 2026-02-28 m+git@andri.dk — Captive portal integration for CA certificate onboarding. In transparent mode, HTTP requests from devices that haven't completed a successful TLS handshake are checked against known OS captive portal detection hosts (Apple, Android, Windows, Firefox, Ubuntu, GNOME, Debian). Matching requests are redirected to the setup page, triggering the OS captive portal UI. Devices are marked as trusted after their first successful TLS handshake with a MITM certificate.
- 2026-02-28 m+git@andri.dk — CA trust tracking via `caTrustTracker`. In-memory `map[string]bool` keyed by client IP. Marked as trusted when a client successfully completes a TLS handshake with a proxy-generated MITM certificate (proving they trust the CA). Untrusted clients get captive portal redirects on HTTP. No persistence — resets on restart (clients will re-prove trust on their next HTTPS connection).
- 2026-02-28 m+git@andri.dk — Transparent passthrough uses SNI extraction + raw TCP relay. When an `@@` excepted host is detected via SNI, the proxy replays the peeked ClientHello bytes to the upstream server and does bidirectional copy. The client's TLS handshake completes directly with upstream — functionally identical to explicit-mode passthrough.
- 2026-02-28 m+git@andri.dk — Blocked hosts in transparent mode close the TCP connection immediately (before TLS handshake). Unlike explicit mode where a 403 response is returned over the CONNECT tunnel, transparent mode cannot send an HTTP error before TLS negotiation. The client sees a connection reset.
- 2026-02-28 m+git@andri.dk — `replayConn` wraps a `net.Conn` with a `bufio.Reader` to replay peeked ClientHello bytes during the TLS handshake. The `extractSNI` function peeks at the TLS record without consuming bytes; `replayConn.Read` reads from the buffered reader first, then from the underlying connection. This avoids copying or buffering the entire ClientHello separately.
- 2026-02-28 m+git@andri.dk — Transparent HTTPS portal handler now passes `proxy.api` to `portalHandler`. Without it, any `/api/*` request on the transparent-mode portal would nil-pointer panic because the `api` field was zero-valued.
- 2026-02-28 m+git@andri.dk — Transparent HTTP forwarding now handles WebSocket upgrades. `forwardHTTPUpgrade` mirrors `proxyHandler.handleHTTPUpgrade` — re-adds hop-by-hop upgrade headers, hijacks both sides on 101, and does bidirectional copy. Without this, WebSocket connections through the transparent HTTP proxy would fail with a `RoundTrip` error.
- 2026-02-28 m+git@andri.dk — Fixed `singleConnListener` race condition. The old implementation returned an error immediately from the second `Accept`, causing `http.Server.Serve` to return before the in-flight request handler finished writing the response. The fix wraps the connection in `notifyCloseConn` which signals a channel on close; the second `Accept` blocks on that channel so `Serve` doesn't exit prematurely. Also added `IdleTimeout: 5s` to the portal's `http.Server` so connections don't block forever after the last response.