Skip to content

Latest commit

 

History

History
1408 lines (1105 loc) · 85.3 KB

DOCUMENTATION.md

File metadata and controls

1408 lines (1105 loc) · 85.3 KB

Tailchrome: complete technical documentation

Tailscale in the browser without changing system VPN settings. For a short overview and install links, see the project README.

Version: 0.1.15 (extension and native host) | Manifest V3 Browsers: Chrome, Firefox, and Chromium-family browsers with the same Chrome Web Store build (Brave, Edge, Vivaldi, Opera; Arc on macOS) Platforms: macOS (amd64, arm64), Linux (amd64 packages; amd64/arm64 raw helpers), Windows (amd64 MSI; amd64/arm64 raw helpers). Chrome and Firefox Flatpak are separate Linux install paths (Chrome, Firefox) License: MIT Website: tesseras.org/tailchrome Chrome Web Store: Chrome Web Store Firefox Add-ons: Firefox Add-ons (AMO) Privacy Policy: privacy-policy.md


Table of Contents

  1. Overview
  2. Architecture
  3. Feature Set
  4. Native Messaging Protocol
  5. Extension Internals
  6. Native Host Internals
  7. Proxy System
  8. State Management
  9. Popup UI
  10. Browser Differences
  11. Installation and Setup
  12. Project Structure
  13. Build System
  14. CI/CD Pipeline
  15. Test Infrastructure
  16. Configuration Reference
  17. Security Model
  18. Data Handling and Privacy
  19. Store Listings
  20. Contributing

Overview

Tailchrome runs a full Tailscale node in each browser profile. System networking is unchanged. Two components cooperate:

  • A TypeScript Manifest V3 extension sets browser proxy rules and renders the popup, side panel, or sidebar UI.
  • A Go native messaging host (tsnet) runs the node and listens on a local SOCKS5/HTTP proxy.

They exchange JSON over the browser native messaging protocol. Browser tailnet traffic uses the local proxy, so Tailchrome works with or without the Tailscale system app.

Each browser profile has its own Tailscale identity. Different profiles can use different tailnets at the same time.


Architecture

+---------------------------------------------+
|  POPUP UI                                    |
|  (popup.ts, views/*.ts, components/*.ts)     |
|  - Connected view with peer list             |
|  - Exit node picker                          |
|  - Profile switcher                          |
|  - Disconnected / NeedsLogin / NeedsInstall  |
+-------------------+--------------------------+
                    | chrome.runtime.Port ("popup")
                    | PopupMessage / BackgroundMessage
                    v
+---------------------------------------------+
|  BACKGROUND SERVICE WORKER                   |
|  (background.ts)                             |
|  - StateStore (TailscaleState)               |
|  - NativeHostConnection (auto-reconnect)     |
|  - BadgeManager (icon/text updates)          |
|  - ProxyManager (Chrome PAC / Firefox API)   |
|  - Context menu handlers                     |
|  - Keepalive timer                           |
+-------------------+--------------------------+
                    | chrome.runtime.connectNative()
                    | 4-byte LE length + JSON
                    | NativeRequest / NativeReply
                    v
+---------------------------------------------+
|  NATIVE HOST (Go)                            |
|  - tsnet.Server per browser profile          |
|  - IPN bus watcher (real-time state)         |
|  - SOCKS5 + HTTP proxy on 127.0.0.1:0       |
|  - Tailscale web client at 100.100.100.100   |
|  - Profile management (create/switch/delete) |
|  - Taildrop file sender                      |
+---------------------------------------------+
                    |
                    | WireGuard / DERP / Control
                    v
              Tailscale Network

Data Flow

  1. Startup: Extension opens native messaging connection. Host starts, binds a SOCKS5/HTTP proxy on a random local port, and sends procRunning with the port number and version.
  2. Init: Extension sends init with a browser-profile UUID (initID) and an optional wantRunning hint. Host creates (or reuses) a tsnet.Server with state stored at ~/.config/tailscale-browser-ext/<initID>/. Because tsnet.Start forces WantRunning=true, the host applies WantRunning=false right after starting a fresh server when the hint is false — this is what keeps the node down at browser launch when auto-connect is off.
  3. State watching: Host starts a goroutine (watchIPNBus) that monitors the IPN notification bus for state, prefs, netmap, browse-to-URL, and health changes. On any change, it fetches full status and sends a StatusUpdate to the extension.
  4. Proxy routing: The background service worker receives the status, passes it to the ProxyManager, which configures browser-level proxy rules (PAC script on Chrome, proxy.onRequest on Firefox).
  5. Popup: When the user opens the popup, it connects via a chrome.runtime.Port named "popup". The background immediately sends current TailscaleState. User actions dispatch BackgroundMessage types which the background translates to NativeRequest commands.

Feature Set

Core Networking

  • Browse tailnet devices by IP or MagicDNS name from the browser.
  • Each browser profile has its own Tailscale node and identity.
  • Route all browser traffic through any exit node on your tailnet. When a suitable Mullvad exit exists, the picker shows a Recommended row labeled "Best available Mullvad VPN".
  • Per-profile split tunneling with Bypass and Only domain rules. Rules match suffixes and apply after mandatory Tailscale routes (MagicDNS, 100.64.0.0/10, subnet routes), so tailnet traffic is unchanged.
  • MagicDNS resolves tailnet device names.
  • Split DNS uses nameservers from Tailscale or Headscale, including nameservers reached through subnet routes.
  • Subnet routing reaches IPv4 and IPv6 resources behind subnet routers (detected from peer info).
  • With an exit node enabled, you can optionally allow LAN access.

Device Management

  • The peer list groups online and offline peers, supports search, and updates the DOM incrementally.
  • Copy a peer's Tailscale IP or DNS name to the clipboard in one click.
  • Open a peer's web UI in a new tab.
  • Open SSH-capable peers in the Tailscale web SSH client at http://100.100.100.100/ssh/<hostname>.
  • Set a per-device custom port or URL for quick open actions.

File Transfer

  • Send files to other tailnet devices with Taildrop.
  • The context menu item "Send page URL to Tailscale device" sends the current page URL as a text file via Taildrop.
  • File send progress appears in persistent toast notifications.

Identity & Configuration

  • Create, switch, and delete multiple Tailscale profiles (identities).
  • Point a profile at a self-hosted HTTP(S) control server such as Headscale. Changing servers starts a fresh login on the new server and keeps the previous account in Profiles. The previous server does not need to be reachable.
  • Shields Up blocks all incoming connections.
  • Run as Exit Node advertises this browser node as an exit node.
  • Login and logout authenticate with Tailscale. Login URLs must match allowed origins.
  • Sign in with a pre-authorized auth key instead of a browser login. The key registers only the current browser profile, can carry tags for a narrow ACL, and is never saved by the extension or helper.
  • Operational health warnings appear in a collapsible banner. The upstream experimental-build notice is informational only. Other warnings, including peer-list truncation, stay visible. The extension filters the experimental notice text from older compatible helpers.

UX

  • The extension icon shows online, offline, or warning state, with a text badge when an exit node is active. Experimental-build notices do not change connected or exit-node badges. Helper and routing failures still show warnings.
  • Reconnect to the native host with exponential backoff (1s base, 30s max).
  • After a package install, helper discovery retries on a session-persisted schedule. Current-user registration repair is offered only if discovery still fails.
  • Missing registration, permission denial, startup failure, unexpected stop, helper-reported errors, and explicit protocol incompatibility each have distinct recovery copy.
  • Copy or export a bounded, allowlisted helper diagnostic report with sensitive values redacted. Nothing is submitted automatically.
  • A helper or release version mismatch alone is informational. Authenticated proxy support is required. Optional commands depend on advertised helper capabilities.
  • The last selected exit node is restored after reconnect.
  • Toasts in the popup cover file send, errors, and suggestions.
  • Arrow keys navigate the peer list.
  • The UI adjusts hints on macOS.
  • Open as side panel switches the UI from popup to Chrome side panel or Firefox sidebar. One quick-settings row controls it on Chrome and Firefox.
  • Auto-connect on start (quick settings) brings the tailnet up on the first status after init when the backend is Stopped or NoState. A session-scoped flag preserves an explicit disconnect across service-worker restarts in the same browser session. The background listens for runtime.onStartup so launch does not wait for the popup to open. Init includes a session-scoped wantRunning hint (launch preference or last explicit toggle) so the host can keep the node down when auto-connect is off, despite tsnet defaulting to up on start. If the node still comes up (helper without the field, or a failed prefs edit), the background sends down once per host connection and does not override a newer user action. Switching or creating a profile clears recorded run intent; the new profile's saved prefs decide run state.

Parity and backlog

This section lists current behavior only. Missing or partial features versus the native Tailscale client, plus architectural limits, are documented in FEATURE_PARITY.md. Maintain parity claims there; update this link if that file moves or is renamed.


Native Messaging Protocol

Communication uses the Chrome native messaging wire format: a 4-byte little-endian length prefix followed by a JSON payload. Maximum message size is 1 MB (Chrome-enforced limit).

Commands (Extension -> Host)

Command Fields Description
init initID: string, wantRunning?: boolean Initialize tsnet.Server for browser profile UUID; optional hint for whether the node should run after startup
login -- Request a fresh Tailscale login URL
login-auth-key authKey: string Register the logged-out profile with an auth key
up -- Set WantRunning=true
down -- Set WantRunning=false
get-status -- Request full status update
ping -- Keepalive; host replies with pong
set-exit-node nodeID: string Set exit node (empty string to clear)
set-prefs prefs: Partial<PrefsView> Apply partial preference changes
list-profiles -- List all Tailscale profiles
switch-profile profileID: string Switch to a different profile
new-profile -- Create and switch to a new empty profile
delete-profile profileID: string Delete a profile
send-file nodeID, fileName, fileData (base64), fileSize, transferID?, chunkIndex?, chunkCount? Send file via Taildrop (supports chunked transfer)
suggest-exit-node -- Request optimized exit node suggestion
ping-peer nodeID: string Ping a specific peer (diagnostic)
bug-report note?: string Generate bug report
netcheck -- Return the helper's current netcheck availability diagnostic
logout -- Log out of current Tailscale account

Replies (Host -> Extension)

Reply Field When Sent Payload
procRunning Immediately on host startup { port, pid, version, proxyAuth, supportsNetcheck?, supportsPingPeer?, supportsLogin?, supportsCustomControlURL?, supportsAuthKeyLogin?, error? }
init After init command { error? }
pong After ping {}
status After state changes or get-status Full StatusUpdate object
profiles After profile commands { current, profiles[] }
exitNodeSuggestion After suggest-exit-node { id, hostname, location? }
fileSendProgress During file send { targetNodeID, name, percent, done, error? }
diagnostic After ping-peer, netcheck, or bug-report { title, body }
error On command failure { cmd, message }

bug-report is accepted by the Go host protocol. The current TypeScript NativeRequest union and extension do not send it.

StatusUpdate Structure

interface StatusUpdate {
  backendState: "NoState" | "NeedsMachineAuth" | "NeedsLogin" |
                "InUseOtherUser" | "Stopped" | "Starting" | "Running";
  running: boolean;
  tailnet: string | null;
  magicDNSSuffix: string;
  splitDNSDomains?: string[];       // Restricted suffixes; absent on older helpers
  dnsRoutes?: string[];             // Authoritative restricted routes; absent when unknown
  selfNode: SelfNode | null;
  needsLogin: boolean;
  browseToURL: string;              // Login URL from control plane
  authURL?: string;                 // Alternate login URL surfaced by the host
  exitNode: ExitNodeInfo | null;
  peers: PeerInfo[];
  peersTruncated?: boolean;          // True if the 1 MiB reply cap omitted peers
  totalPeers?: number;               // Full count before truncation
  prefs: TailscalePrefs | null;
  health: string[];
  error: string | null;
}

When NeedsLogin is active, the extension opens a validated browseToURL immediately when available. If the URL is missing and the helper advertises supportsLogin, the extension sends login, waits for a fresh browseToURL or authURL, validates the URL, and then opens it.

If the helper advertises supportsAuthKeyLogin, the login view also offers "Use an auth key". The extension sends login-auth-key with the key, and the helper passes it to the backend for the current profile only, then registers without a browser URL. The key is never written to storage, prefs, or logs. If the coordination server rejects the key, the helper replies with a login-auth-key error that omits the key and drops it from the backend so it is not retried. Key sign-in does not need protected browsing to be released, because the helper reaches the coordination server directly.

set-prefs.prefs.controlURL uses an empty string for Tailscale's default control plane and an HTTP(S) URL for a custom server. The helper validates the URL and preferences before switching to an empty local profile. The new profile clears server-scoped exit-node state and requires a fresh login. The previous account remains in Profiles, and failures attempt to restore its identity and preferences. Switching does not require remote logout. Settings for the pending login survive a helper restart.

If a status payload would exceed the browser's 1 MiB native-message limit, the helper removes peers from the end until it fits and sets peersTruncated plus totalPeers. The popup displays a health warning instead of silently losing all status updates on very large tailnets.

Each PeerInfo includes: id, hostname, dnsName, tailscaleIPs[], os, online, active, exitNode, exitNodeOption, isSubnetRouter, subnets[], tags[], rxBytes, txBytes, lastSeen, lastHandshake, keyExpiry, location?, taildropTarget, sshHost, userId, userName, userLoginName, userProfilePicURL.


Extension Internals

Packages

The extension is a pnpm monorepo with two packages:

Package Path Purpose
@tailchrome/extension packages/extension/ WXT app for Chrome/Firefox packaging, browser-specific proxy managers, entrypoints
@tailchrome/shared packages/shared/ Shared TypeScript: types, state management, popup logic, background core, proxy utils

The shared package contains all the platform-agnostic logic. The extension package contains browser-specific entrypoints, proxy managers, and WXT configuration.

Key Modules

**packages/shared/src/background/**

File Purpose
background.ts Core service worker: native host management, popup communication, state subscriptions, context menus, diagnostics, and keepalive
native-host.ts Serialized native-host connection lifecycle, typed connection events, evidence-based disconnect classification, and exponential reconnect backoff
state-store.ts StateStore with no-op deduplication, subscriptions, and native status mapping
../helper-diagnostics.ts Pure diagnostic sanitizer, allowlist, bounds, and local report formatter
badge-manager.ts Extension icon/badge updates for online, offline, warning, and exit-node states
proxy-utils.ts IPv4/CIDR helpers, MagicDNS/split-domain sanitization, subnet collection, and proxy decisions
ipv6-subnets.ts IPv6 literal/CIDR validation and a shared subnet matcher for Firefox and generated Chrome PAC scripts
routing-protection.ts Persisted, account-scoped routing policy and fail-closed behavior across helper or worker restarts
proxy-session.ts In-memory helper proxy credentials and authenticated session handoff to browser-specific managers
domain-split.ts Split-tunneling config storage and normalization
auto-connect.ts Auto-connect preference, per-session handled flag, and session connection intent (wantRunning init hint)
timer-service.ts Browser-neutral timer interface and native-timer implementation
chrome-alarm-timer-service.ts Chrome alarm-backed one-shot timers that survive MV3 worker suspension
startup-wake.ts Synchronous browser-start wake listener registration
ui-surface.ts Popup/side-panel preference storage and browser-specific toolbar behavior

**packages/shared/src/popup/**

File Purpose
popup.ts Custom-URL hydration, background connection, view routing, and live/deferred sub-view state
helper-diagnostics.ts On-demand copy/download UI for the shared local helper report
utils.ts Clipboard, toast notifications, keyboard navigation, formatting, and platform detection
custom-urls.ts Per-device custom port/URL storage using chrome.storage.local
peer-filters.ts Device-list filtering rules
icons.ts SVG icon definitions

**packages/shared/src/popup/views/**

File Purpose
connected.ts Main connected view: identity, quick/advanced settings, split tunneling, peer search/list, and footer
exit-nodes.ts Exit-node picker: local recommendation, search, grouping, flags, and live updates
profiles.ts Profile switcher: create, switch, and delete actions
disconnected.ts Starting, reconnecting, stopped, and helper-error recovery states
needs-login.ts Login prompt, auth key sign-in, and coordination-server settings
needs-install.ts Package installation and registration-repair entry point
install-helpers.ts Runtime platform/architecture selection, per-user setup, terminal commands, and registration recovery

**packages/shared/src/popup/components/**

File Purpose
peer-list.ts Peer list with online/offline grouping and incremental DOM updates
peer-item.ts Peer row: live details, copy/open/ping/SSH/Taildrop actions, and custom URL editor
coordination-server-row.ts Reusable custom control-server editor with capability gating
ui-surface-row.ts Popup versus side-panel/sidebar setting
header.ts Logo and accessible connection toggle
health-warnings.ts Collapsible health warning banner
toggle-switch.ts Reusable accessible toggle component

**packages/extension/src/background/**

File Purpose
chrome.ts Chrome background bootstrap, durable reconnect timer, and proxy-auth wiring
chrome-proxy-manager.ts Mandatory PAC generation, ownership verification, and fail-closed routing
chrome-proxy-auth.ts Per-helper HTTP proxy credentials and Chrome authentication callbacks
firefox.ts Firefox background bootstrap and alarm-based keepalive
firefox-proxy-manager.ts proxy.onRequest listener with authenticated, fail-closed SOCKS routing

**packages/extension/entrypoints/**

File Purpose
background.ts Routes to Chrome or Firefox background initialization
popup/main.ts Popup entry; imports shared popup module
popup/index.html Popup HTML shell
popup/style.css Popup styles

Constants

Defined in packages/shared/src/constants.ts:

Constant Value Purpose
TAILSCALE_SERVICE_IP 100.100.100.100 Tailscale service/web client address
TAILSCALE_IPV6_PREFIX fd7a:115c:a1e0: Tailscale node IPv6 routing prefix
KEEPALIVE_INTERVAL_MS 25000 Ping interval to keep service worker alive
RECONNECT_BASE_MS 1000 Reconnection backoff base
RECONNECT_MAX_MS 30000 Reconnection backoff ceiling
ADMIN_URL https://login.tailscale.com/admin Tailscale admin console
DEFAULT_CONTROL_URL https://controlplane.tailscale.com Default coordination server

Native Host Internals

The native host is a Go binary at host/ using tailscale.com/tsnet pinned to v1.103.0-pre.0.20260819151608-90ed0bcf4bc2. This revision includes the UDP DNS routing fix and the security fixes from v1.102.3; see Split DNS.

Files

File Purpose
main.go Entry point, proxy startup, and native messaging mode
cli.go Explicit install/uninstall/version command parsing and legacy setup compatibility
host.go Framing loop, synchronized tsnet session lifecycle, request dispatch, prefs/login/diagnostic handlers, and bounded status replies
authkey_login.go Auth key sign-in: key validation, redaction, rejection reporting, and discarding rejected keys
protocol.go Wire protocol types and 1 MiB message limit
status.go Retrying IPN bus watcher, debounced refresh, cached notification state, and StatusUpdate construction
proxy.go / proxy_policy.go SOCKS5/HTTP multiplexing, authenticated destination policy, lazy quad-100 web client, and buffered CONNECT tunneling
dns.go / exit_dns.go Restricted split-DNS forwarding and exit-node DNS behavior
profiles.go Profile management through the current local-client snapshot
saved_prefs.go Loads saved profile preferences before tsnet startup and persists settings for pending logins
control_url.go Changes coordination servers using a fresh local profile, with rollback to the previous account
taildrop.go Chunk reassembly, asynchronous cancellable PushFile, progress, and cleanup
install.go / install_*.go Cross-platform native host installation and cleanup, including Chrome/Firefox Flatpak sandbox state and registration
peers.go Peer/status conversion from Tailscale types
exitnode.go Exit-node selection and suggestion handlers
*_test.go Framing, proxy, peer conversion, status/prefs, Taildrop, installer, and platform-specific regression coverage

Lifecycle

  1. Browser launches the host via native messaging (stdin/stdout). Not a terminal -- goes directly to messaging mode.
  2. Proxy starts on 127.0.0.1:0. The port is sent back to the extension via procRunning.
  3. Extension sends init with a profile identifier restricted to 1-64 ASCII letters, numbers, underscores, or hyphens. Host creates a tsnet.Server at ~/.config/tailscale-browser-ext/<ID>/ and atomically installs it as the current session.
  4. IPN bus watcher monitors state, prefs, netmap, browse-to-URL, and health changes. Errors trigger bounded exponential retries; each change schedules a debounced full StatusUpdate from the same session snapshot.
  5. Host reads commands in a loop from stdin, dispatches to handlers, and writes replies to stdout.
  6. On stdin EOF (browser closed), the host cancels the watcher and active Taildrop transfers, closes the tsnet server, and exits cleanly.

Before starting tsnet, the host reads the selected account's saved preferences and supplies its coordination server, hostname, and advertised tags. It restores subnet-route acceptance, DNS, Shields Up, LAN access, SSH, and advertised routes before publishing the session to the proxy and status watcher. New browser profiles accept subnet routes by default. The extension supplies the startup connection intent and restores its selected exit node after the account is running. An unreadable preference record stops initialization instead of replacing the saved settings with defaults.

Proxy Architecture

The proxy uses Tailscale's proxymux.SplitSOCKSAndHTTP() to multiplex a single listener:

  • SOCKS5 traffic is handled by tailscale.com/net/socks5, with authentication and the helper's destination policy applied before dialing.
  • HTTP traffic is handled by an httputil.ReverseProxy with the same authentication and destination checks.
  • Requests to 100.100.100.100 are routed to the Tailscale web client (web.Server in ManageServerMode). Proxy authentication is checked first; the web client then enforces its own session, capability and CSRF checks.
  • HTTPS CONNECT requests are hijacked for bidirectional tunneling through tsnet.

All three proxy paths resolve restricted DNS domains through configured IP nameservers, validating both the nameserver route and returned IPs against the current session's routing policy before dialing. The IPN watcher sends authoritative restricted domains as dnsRoutes, retaining splitDNSDomains for compatibility; disabling corpDNS or removing a route clears the corresponding browser routing. An omitted dnsRoutes field indicates that configuration is not yet known and preserves existing protection. See Split DNS for setup and nameserver routing requirements.

The loopback proxy requires a fresh random credential on every helper launch. Chrome uses authenticated HTTP proxying; Firefox uses authenticated SOCKS5. Credentials stay in the background proxy manager and are excluded from popup state, storage, and diagnostics. The helper also validates destinations against its current network map and preferences before dialing. See SECURITY.md.

Auto-Installation

Running the raw host without a command in a terminal retains legacy setup: it copies itself to the historical per-user helper directory and registers all supported browsers. New installers place the executable at their stable path and invoke install --binary-path PATH. This direct command registers Chrome, Firefox, and detected optional browsers without making another executable copy. See helper installation for explicit browser selection and legacy compatibility.


Proxy System

DNS

Known peer short names, full MagicDNS names, and restricted DNS domains use the helper. Split DNS follows the most specific domain route from Tailscale or Headscale and supports IPv4/IPv6 nameserver addresses over authorized routes, including TCP-only and UDP-only nameservers. Encrypted resolver URLs are not supported. Routes without a supported IP nameserver fail instead of falling back to system DNS.

Ordinary browsing keeps the browser/system resolver. Proxied exit-node traffic uses the exit node's DNS unless a restricted resolver is configured to stay in use with that exit node. Excluded domains keep their normal resolver. Restricted DNS routes require the MagicDNS setting to be enabled.

Chrome: PAC Script

Chrome uses a dynamically generated PAC (Proxy Auto-Config) script set via chrome.proxy.settings.set(). The PAC script routes traffic based on:

  1. Tailnet destinations -> proxy: the service IP (100.100.100.100), full MagicDNS names, exact known peer short names, restricted DNS domains, CGNAT addresses (100.64.0.0/10), Tailscale IPv6 addresses (fd7a:115c:a1e0::/48), and approved IPv4/IPv6 subnet addresses. Domain rules match both the domain and its subdomains. isInNet() is used only for IPv4 literals; IPv6 uses a shared numeric prefix matcher. Neither subnet matcher resolves hostnames through local DNS.
  2. Other traffic with a selected exit node -> proxy subject to the user's Bypass or Only domain rules; protected requests are blocked while the exit node or helper is unavailable.
  3. Otherwise -> DIRECT.

The Chrome PAC target is PROXY 127.0.0.1:<port>, with HTTP proxy authentication supplied by the background handler.

Chrome restricts which requests extension handlers can observe, including requests initiated by other extensions. Before enabling protected routes for a new helper session, Tailchrome makes its own authenticated HEAD request to http://tailchrome-proxy-auth.invalid/ through the helper. This populates Chrome's proxy credential cache for subsequent HTTPS CONNECT requests, including other extensions' API calls. During this exchange, only the probe reaches the helper; other protected destinations remain blocked. A failed or timed-out probe leaves them blocked. The probe endpoint requires the same credential and returns an empty, uncached response without contacting tsnet. Older authenticated helpers can return a destination error after authenticating; that also populates the cache. Credentials remain in background memory and Chrome's auth cache, and are replaced when the helper session changes.

This credential is generated by Tailchrome for each helper process. It is separate from Tailscale login, same-user proof tokens, and RunWebClient; changing that preference does not disable proxy authentication. Users should not enter their Tailscale password in a proxy authentication dialog. An individual tunnel failure does not by itself establish that the proxy settings or all protected browsing have failed.

Successful PAC settings are reused until routing changes. Worker suspension preserves the browser settings; reconnecting replaces the helper endpoint after confirmation.

Firefox: proxy.onRequest

Firefox uses the browser.proxy.onRequest API with an event listener that evaluates each request URL:

  1. Same routing logic as Chrome (service IP, CGNAT, Tailscale IPv6, MagicDNS, peer short names, subnets, restricted DNS domains, exit node)
  2. Protected requests use an authenticated SOCKS proxy with proxyDNS: true in a chain ending in null, preventing browser proxy fallback. Other requests use the normal browser connection.
  3. IPv4 matching uses numeric comparison (ipToNum()) instead of PAC's isInNet(); IPv6 subnet matching uses the same implementation embedded in the Chrome PAC.

Routing protection: Both browsers retain a sanitized routing snapshot across restarts, including restricted DNS domains but excluding helper ports and credentials. Exit-node choices are scoped to the account and coordination server. Helper loss or an unavailable exit node blocks protected requests while preserving split-tunnel exceptions. Chrome uses mandatory PAC settings and checks effective proxy ownership.

Both browsers exclude new IPv4 and IPv6 subnet routes that overlap the helper's forbidden address ranges, including broad prefixes containing those ranges. Rejected routes do not divert otherwise direct traffic into the helper. IPv4 routes saved by older versions remain protected during outages and authentication setup, but rejected prefixes are excluded from active subnet routing; selected exit-node rules still apply.

The popup reports routing failures separately from the Tailscale connection. Choose Disconnect and browse normally to release protection when the helper cannot respond.


State Management

StateStore

StateStore (packages/shared/src/background/state-store.ts) is a minimal Redux-like store:

interface TailscaleState {
  routingPolicy?: RoutingPolicy;   // Effective active/blocked/direct routing decision
  routingHealth?: RoutingHealth;   // Browser proxy ownership and availability
  selectedExitNodeID?: string | null;
  stateVersion: number;        // Monotonically increasing counter
  hostConnected: boolean;
  initialized: boolean;
  proxyPort: number | null;
  proxyEnabled: boolean;
  backendState: BackendState;
  tailnet: string | null;
  selfNode: SelfNode | null;
  peers: PeerInfo[];
  exitNode: ExitNodeInfo | null;
  magicDNSSuffix: string | null;
  splitDNSDomains: string[];
  dnsRoutes?: string[];
  browseToURL: string | null;
  prefs: TailscalePrefs | null;
  health: string[];
  pendingExitNodeID: string | null; // Optimistic selection until host confirmation
  currentProfile: ProfileInfo | null;
  profiles: ProfileInfo[];
  exitNodeSuggestion: ExitNodeSuggestion | null;
  domainSplit: { mode: "bypass" | "only"; domains: string[] };
  error: string | null;
  hostVersion: string | null;
  helperFailure: HelperFailure | null;
  helperDiagnostic: HelperDiagnostic | null;
  helperVersionNotice: HelperVersionNotice | null;
  repairRegistrationAvailable: boolean;
  supportsNetcheck: boolean;
  supportsPingPeer: boolean;
  supportsLogin: boolean;
  supportsCustomControlURL: boolean;
  supportsAuthKeyLogin: boolean;
  reconnecting: boolean;
  autoConnectOnStart: boolean;
}
  • update(partial) shallow-compares supplied fields, then merges and increments stateVersion only when something changed
  • applyStatusUpdate(status) maps a StatusUpdate from the host into state fields
  • subscribe(callback) registers a listener called on every state change
  • Listeners receive the full state; ProxyManager, BadgeManager, and popup broadcast all subscribe

Message Types

PopupMessage (background -> popup):

  • { type: "state", state: TailscaleState } -- full state push
  • { type: "toast", message, level: "info"|"error", persistent? } -- notification

BackgroundMessage (popup -> background):

  • Connection and recovery: release-routing, toggle, login, disconnect-and-login, login-auth-key, logout, and retry-native-host
  • Routing and preferences: set-exit-node, clear-exit-node, set-pref, set-advertise-routes, set-domain-split, and set-auto-connect-on-start
  • Profiles and diagnostics: switch-profile, new-profile, delete-profile, ping-peer, and netcheck
  • Files and navigation: send-file, suggest-exit-node, open-admin, and open-web-client

Helper activation state

helperFailure is evidence-based and uses these stable categories:

Failure kind Evidence Recovery surface
helper-unavailable Browser reports that the native-messaging host is absent Platform release package installation, followed by registration repair only after discovery retries fail
helper-not-allowed Browser reports that the host exists but this extension is not allowed Registration repair is promoted immediately
helper-start-failed The browser found the host, but startup failed before a healthy connection Retry, package repair, and local diagnostics
helper-stopped A previously healthy helper connection closed Automatic reconnect plus manual retry
helper-reported-error The helper started and returned an explicit startup/protocol error Retry, package repair, and local diagnostics
helper-incompatible The helper omits a valid supported authenticated-proxy session (helper-proxy-auth-required) Update the helper and extension together; a version string alone never causes this state

Starting a package or verified repair records a retry deadline in chrome.storage.session. Attempts run after 2, 5, 10, 20, and 30 seconds and are restored after a Manifest V3 worker restart. Successful initialization clears the retry and repair state. If a package/fallback retry sequence ends with helper-unavailable or helper-not-allowed, repairRegistrationAvailable promotes current-user registration repair; a manual retry or any other failure category does not.

helperVersionNotice compares the installed helper version with the extension release only to show a dismissible notice. It never replaces the active popup view. Optional commands such as login, custom coordination servers, netcheck, and peer ping remain controlled by the capabilities advertised in procRunning. Only an explicit future-protocol incompatibility blocks setup.

Helper diagnostic details are sanitized as they cross the native connection boundary. The report is created only when the user clicks copy or export. Its schema is versioned and capped at 8 KiB; it contains extension/helper/release versions, operating system, architecture, browser family, connection flags, failure kind/code, sanitized detail, advertised capabilities, and repair availability. It deliberately does not spread the full extension state into the report.


Popup UI

The popup is a vanilla TypeScript UI (no framework) rendered into the extension popup HTML. Views are functions that return DOM elements.

View Routing

popup.ts routes to views based on TailscaleState:

Condition View
helper-unavailable, helper-not-allowed, or helper-incompatible needs-install
backendState === "NeedsLogin" needs-login
backendState === "Running" connected
Startup failure, unexpected stop, helper-reported error, retry, or any other state disconnected

A helper version notice is inserted above whichever normal view is active; it does not participate in routing.

Connected View Layout

+----------------------------------+
| [Tailscale logo]  [Toggle ON/OFF]|
+----------------------------------+
| Status: Connected to <tailnet>   |
| IP: 100.x.y.z                    |
+----------------------------------+
| [Health warning banner]          |
+----------------------------------+
|   Exit Node: [current / None]   >|
|   Split tunneling: [mode]       >|
|   Shields Up           [toggle]  |
|   MagicDNS             [toggle]  |
|   Auto-connect on start [toggle] |
|   Advanced             [toggle]  |
|     Run as Exit Node   [toggle]  |
|     Local node page: Open       >|
|     Coordination server         >|
|   Advertise subnets    [toggle]  |
|   Profile: [name] (optional)   > |
|   Open as side panel   [toggle]  |
+----------------------------------+
| [Search devices…] (6+ peers)     |
+----------------------------------+
| ONLINE (3)                       |
|   > laptop  100.10.1.1  linux    |
|   > server  100.10.1.2  linux    |
|   > phone   100.10.1.3  android  |
| OFFLINE (1)                      |
|   > desktop 100.10.1.4  windows  |
+----------------------------------+
| Native helper <version>          |
| [Admin Console]  [Logout]        |
| [Star the repo!]                 |
+----------------------------------+

Exit node sub-view: Opening Exit node shows the full picker (search, suggested node, Mullvad grouping where applicable). Allow LAN access is a checkbox there—not in Quick Settings. Advertise subnets expands its own editor, independently of Advanced. Each peer item expands to show Copy IP, Copy DNS, Open, SSH (if capable), Send File (if a Taildrop target), and a custom URL editor. A Profile row is added when state.profiles is non-empty and opens the profile switcher. Admin Console appears only for Tailscale's default coordination server, and the helper-version footer row appears only after the host reports a version.

The device list previews five devices, with online devices first. View all and Show fewer expand or collapse it; search always includes the full list. Click an IP address to copy it without opening the device's actions. Search is offered for six or more devices, excluding Mullvad exit infrastructure.

The status bar distinguishes confirmed browser routing from the node's connection. The profile switcher retains the confirmed Active profile while showing a pending switch, disables conflicting actions, and offers retry guidance if the helper fails or does not confirm within 20 seconds.


Browser Differences

Feature Chrome Firefox
Manifest version V3 V3
Proxy mechanism chrome.proxy.settings (PAC script) browser.proxy.onRequest (listener)
Background type Service worker (persistent with keepalive) Event page (suspended aggressively)
Keepalive Native interval; one-shot reconnects also use a durable chrome.alarms backup browser.alarms every 25s
State persistence Sanitized local routing snapshot, session intent, and alarm-backed reconnect Same routing snapshot and session intent; proxy listener starts blocked on wake
Native host ID com.tailscale.browserext.chrome com.tailscale.browserext.firefox
Permissions proxy, storage, nativeMessaging, contextMenus, alarms, sidePanel Same except sidePanel
Min version -- Firefox 142+
Distribution Chrome Web Store Firefox Add-ons (AMO)
Extension ID bhfeceecialgilpedkoflminjgcjljll (CWS) tailchrome@tesseras.org (gecko)

Firefox-Specific Behaviors

  • Alarms keepalive: Firefox suspends event pages after ~30s of inactivity. A browser.alarms alarm fires every 25s to send a keepalive ping and prevent suspension.
  • Synchronous listener registration: Proxy, runtime connection, storage, install, context-menu, alarm, startup, and sidebar listeners are all registered during initial script evaluation. Storage restoration begins first but never delays event-listener registration.
  • Proxy listener registration: The proxy.onRequest listener is registered at extension load and persists across suspensions. It starts in blocked mode, then follows the effective policy after the shared routing snapshot is restored and live helper state arrives.
  • Persisted protection: routingProtectionV1 stores a sanitized, account-scoped routing snapshot in local storage. It excludes helper ports and credentials; Firefox obtains fresh proxy credentials from the native connection before protected requests can use the helper.
  • Data collection disclosure: Firefox AMO requires explicit data collection permissions declared in the manifest via gecko.data_collection_permissions.

Installation and Setup

End User Installation

Install the extension, register the native helper, then log in. Step-by-step commands, version pairing (v0.1.14+ authenticated proxy), repair, and Flatpak are documented in helper installation. The README lists quick install one-liners.

Chrome (and Chromium-family browsers using the same store listing):

  1. Install from the Chrome Web Store
  2. Complete per-user helper setup from the popup (macOS helper app, Windows MSI or architecture-aware PowerShell installer, or Linux terminal command). Assets come from GitHub Releases. Homebrew and system packages are optional (packaging docs).
  3. Log in to Tailscale

Firefox:

  1. Install from Firefox Add-ons or the matching GitHub Release
  2. Use the same helper setup flow as Chrome
  3. Log in to Tailscale

Native Host Installation

The v0.1.14 helper separates binary placement from browser registration. tailchrome install registers the installed executable directly, prints paths, and supports custom extension IDs and browser targets. Chrome and Firefox are registered for first use; optional browsers use installation footprints unless explicitly requested. Linux registration honors XDG configuration paths.

The Unix and PowerShell installers select a release and architecture, verify the artifact, replace the stable user-owned executable safely, and invoke this command. Latest stable is the general default; an explicit version remains available. macOS app, MSI, Homebrew and Linux system packages retain ownership of their own executable. Install and registration repair use the same entry point. Windows signature status follows the release's recorded signing mode; see the policy.

Legacy installer flags remain compatible and retain their historical staging behavior. Existing native-host names and extension IDs are unchanged. The new uninstall command removes registrations owned by its executable; the installer or package manager removes the executable. Node state is preserved.

See helper installation for exact commands, executable paths, legacy behavior, safe upgrades, uninstall and Chrome/Firefox Flatpak setup. The matching release's installer assets must exist before distributing its extension.

State Directory

Per-profile Tailscale state is stored at:

~/.config/tailscale-browser-ext/<browser-profile-UUID>/

Each browser profile generates a UUID on first connection, stored in chrome.storage.local as profileId.

Native installations keep this historical location even when browser manifest registration uses XDG paths. Chrome and Firefox Flatpak use their sandbox's writable XDG configuration directory for separate node state. Installing the sandbox helper does not migrate or delete native node identities.


Project Structure

tailchrome/
+-- packages/
|   +-- extension/                    # WXT app (browser-specific)
|   |   +-- entrypoints/
|   |   |   +-- background.ts        # Background entry (routes to chrome/firefox)
|   |   |   +-- popup/               # Popup HTML, CSS, entry
|   |   +-- src/background/
|   |   |   +-- chrome.ts            # Chrome bootstrap and proxy-auth wiring
|   |   |   +-- firefox.ts           # Firefox bootstrap and keepalive
|   |   |   +-- chrome-proxy-manager.ts
|   |   |   +-- chrome-proxy-auth.ts
|   |   |   +-- firefox-proxy-manager.ts
|   |   +-- config/
|   |   |   +-- firefox-disclosure.ts # AMO data collection declaration
|   |   +-- public/                   # Icons (online/offline/warning states)
|   |   +-- wxt.config.ts            # WXT manifest & build config
|   |   +-- package.json
|   |
|   +-- shared/                       # Platform-agnostic code
|       +-- src/
|       |   +-- types.ts              # All TypeScript type definitions
|       |   +-- constants.ts          # Configuration constants
|       |   +-- helper-diagnostics.ts # Allowlisted local report formatter
|       |   +-- background/           # Service worker core logic
|       |   |   +-- background.ts     # Main background initialization
|       |   |   +-- native-host.ts    # Native host connection manager
|       |   |   +-- state-store.ts    # State management
|       |   |   +-- badge-manager.ts  # Icon/badge updates
|       |   |   +-- proxy-utils.ts    # IP/CIDR/DNS utilities
|       |   |   +-- routing-protection.ts # Persisted fail-closed routing policy
|       |   |   +-- proxy-session.ts  # Authenticated helper proxy session
|       |   |   +-- timer-service.ts  # Timer abstraction
|       |   |   +-- chrome-alarm-timer-service.ts # MV3 durable reconnect timeout
|       |   |   +-- domain-split.ts   # Split-tunneling persistence
|       |   |   +-- auto-connect.ts   # Startup connection preference
|       |   |   +-- startup-wake.ts   # Browser launch listener
|       |   |   +-- ui-surface.ts     # Popup/side-panel behavior
|       |   +-- popup/                # Popup UI views & components
|       |   |   +-- popup.ts          # View router
|       |   |   +-- helper-diagnostics.ts # Copy/export actions
|       |   |   +-- utils.ts
|       |   |   +-- custom-urls.ts
|       |   |   +-- icons.ts
|       |   |   +-- views/
|       |   |   |   +-- connected.ts      # Main connected view
|       |   |   |   +-- exit-nodes.ts     # Exit node picker
|       |   |   |   +-- profiles.ts       # Profile switcher
|       |   |   |   +-- disconnected.ts   # Error recovery view
|       |   |   |   +-- needs-login.ts    # Login view
|       |   |   |   +-- needs-install.ts  # Install guide view
|       |   |   |   +-- install-helpers.ts
|       |   |   +-- components/
|       |   |   |   +-- peer-list.ts
|       |   |   |   +-- peer-item.ts
|       |   |   |   +-- coordination-server-row.ts
|       |   |   |   +-- ui-surface-row.ts
|       |   |   |   +-- header.ts
|       |   |   |   +-- health-warnings.ts
|       |   |   |   +-- toggle-switch.ts
|       |   +-- __test__/             # Test fixtures and mocks
|       +-- package.json
|
+-- host/                             # Native messaging host (Go)
|   +-- main.go                       # Entry point
|   +-- cli.go                        # Explicit install/uninstall/version CLI
|   +-- host.go                       # Host struct, message loop, handlers
|   +-- protocol.go                   # Wire protocol types
|   +-- status.go                     # IPN bus watcher
|   +-- proxy.go                      # SOCKS5/HTTP proxy
|   +-- proxy_policy.go               # Authenticated destination policy
|   +-- dns.go / exit_dns.go          # Split and exit-node DNS forwarding
|   +-- profiles.go                   # Profile management
|   +-- taildrop.go                   # File transfer
|   +-- install.go                    # Manifest installation
|   +-- install_darwin.go             # macOS paths
|   +-- install_linux.go              # Linux paths
|   +-- install_flatpak_*.go          # Chrome/Firefox Flatpak sandbox registration
|   +-- install_windows.go            # Windows paths + registry
|   +-- peers.go                      # Peer info extraction
|   +-- exitnode.go                   # Exit node handlers
|   +-- *_test.go                     # Framing, proxy, status, peer, transfer, install tests
|   +-- go.mod / go.sum
|
+-- config/
|   +-- extension-ids.json            # Extension & native host IDs
|
+-- packaging/                        # Platform packages and native manifests
|   +-- homebrew/                     # Formula/cask maintenance docs
|   +-- linux/                        # nFPM DEB/RPM definition and builder
|   +-- macos/                        # PKG builder and per-user repair app
|   +-- windows/                      # WiX MSI and native ARM64 smoke
+-- Casks/tailchrome.rb               # Published macOS Homebrew cask
+-- Formula/tailchrome.rb             # Source-built macOS/Linux formula
|
+-- scripts/
|   +-- e2e/                         # Puppeteer runner, fixtures, native-host mock, scenarios
|   +-- install.sh                   # Verified macOS/Linux per-user installer
|   +-- install.ps1                  # Verified Windows amd64/ARM64 per-user installer
|   +-- install.test.sh              # Hermetic installer tests
|   +-- install.test.ps1             # Portable PowerShell installer fixtures
|   +-- test-flatpak.sh              # In-sandbox Chrome/Firefox native-messaging smoke
|   +-- update-homebrew.mjs          # Release-driven cask/formula updater
|   +-- verify-windows-signatures.ps1 # Authenticode and embedded-EXE verifier
|   +-- validate-extension-ids.mjs   # Extension/native manifest drift check
|   +-- validate-release-tag.mjs     # Cross-file release version check
+-- store-assets/                     # Store listing images
+-- docs/
|   +-- privacy-policy.md
|   +-- firefox-amo-launch.md
|   +-- firefox-amo-review-notes.md
|   +-- firefox-smoke-test.md
|   +-- FEATURE_PARITY.md
|   +-- STORE_LISTING.md
|   +-- puppeteer-testing-suite.md
|   +-- helper-installation.md
|   +-- split-dns.md
|   +-- DOCUMENTATION.md              # This file
|   +-- CONTRIBUTING.md
|   +-- SOURCE_CODE_REVIEW.md         # Firefox AMO reviewer guide
|   +-- SECURITY.md
|   +-- WINDOWS_CODE_SIGNING_POLICY.md
|   +-- RELEASE_CHECKLIST.md
|   +-- CODE_OF_CONDUCT.md
|
+-- .github/workflows/
|   +-- ci.yml                        # PR checks
|   +-- flatpak-smoke.yml             # Chrome/Firefox Flatpak helper smoke on PRs
|   +-- release.yml                   # Immutable tagged candidate builds
|   +-- publish-helper-release.yml    # Protected exact-candidate publication
|   +-- publish.yml                   # Store submission
|   +-- update-homebrew.yml           # Post-release tap update proposal
|
+-- Makefile                          # Top-level build targets
+-- package.json                      # Root workspace scripts
+-- pnpm-workspace.yaml               # Monorepo config
+-- tsconfig.base.json                # Shared TS config
+-- README.md
+-- LICENSE                           # MIT

Build System

Prerequisites

  • Go 1.26.6+ (per host/go.mod)
  • Node.js 22+
  • pnpm (via corepack)
  • Desktop Chrome or Firefox for testing

Commands

Command Description
pnpm install --frozen-lockfile Install JS dependencies
pnpm build:chrome Build Chrome extension via WXT
pnpm build:firefox Build Firefox extension via WXT
pnpm zip:chrome Create chrome.zip for distribution
pnpm zip:firefox Create firefox.zip + firefox-sources.zip
pnpm lint:firefox Validate Firefox extension with web-ext lint
pnpm review:firefox Full Firefox review gate (build + lint + zip + publish validation)
pnpm typecheck Run TypeScript type checking
pnpm test Run all tests (vitest)
pnpm test:installer Run hermetic verified-installer shell tests
pnpm test:homebrew Run Homebrew release-updater tests
pnpm validate:ids Validate extension ID consistency
pnpm validate:release-tag <tag> Validate release tag format
make host Build native host for current platform
make host-all Build host binaries for all platforms
make host-linux-amd64 Build the Linux package input
make host-linux-arm64 Build the Linux ARM64 raw helper
make host-windows-amd64 Build the Windows amd64 raw helper
make host-windows-arm64 Build the Windows ARM64 raw helper
make macos-pkg Build the macOS system package and per-user app (macOS only)
make windows-msi Build an unsigned development MSI (Windows with WiX only)
make linux-packages Build the Linux DEB and RPM packages with nFPM
make dev Chrome watch mode via WXT
make all Build extension + host
make clean Clean all build outputs

Build Outputs

Output Location
Chrome extension packages/extension/.output/chrome-mv3/
Chrome extension (dev, make dev) packages/extension/.output/chrome-mv3-dev/
Firefox extension packages/extension/.output/firefox-mv3/
Chrome ZIP packages/extension/.output/chrome.zip
Firefox ZIP packages/extension/.output/firefox.zip
Firefox sources ZIP packages/extension/.output/firefox-sources.zip
Host binary dist/tailscale-browser-ext
Host cross-compile dist/tailscale-browser-ext-{os}-{arch}

WXT Configuration

WXT (packages/extension/wxt.config.ts) handles:

  • Manifest V3 generation for Chrome and Firefox
  • Icon definitions (online, offline, warning states at 16/32/48/128px)
  • Chrome extension key for stable development ID
  • Firefox gecko settings (addon ID, strict_min_version: "142.0", data collection permissions)
  • Source ZIP configuration for AMO review (allowlisted paths only)
  • Vite alias @tailchrome/shared -> packages/shared/src

CI/CD Pipeline

CI (ci.yml) -- Runs on Pull Requests

The workflow runs extension unit/type/ID checks, verified-installer tests, the Chrome browser smoke suite, extension builds, the Firefox build/lint/review gate, actionlint, and ShellCheck on every pull request. A SHA-pinned path filter enables host/packaging work only when relevant files change:

  • host-build (Linux): dependency download, go vet, race-enabled Go tests, and the native host build
  • host-windows-tests: Windows-specific Go tests and PowerShell installer fixtures
  • windows-arm64-smoke: native ARM64 executable and installer checks
  • homebrew (when tap/updater files change): formula source build, install, registration, test, and uninstall on Linux and macOS; macOS also validates the published signed cask
  • package-linux: amd64/arm64 raw builds with architecture checks plus .deb and .rpm generation with pinned nFPM and ownership-boundary inspection
  • macos-package-smoke: unsigned package smoke build that asserts the launchable /Applications/Tailchrome Helper.app payload
  • windows-signature-verifier: fixed-SDK positive/negative Authenticode verifier fixtures
  • workflow-static-validation: actionlint over every workflow and ShellCheck over installer and packaging scripts

Flatpak smoke (flatpak-smoke.yml) -- Pull Requests or Manual Dispatch

This separate workflow creates clean user-scoped Chrome and Firefox Flatpak installations, installs the helper into each sandbox, verifies native-message framing from inside the sandbox, uninstalls it, and retains diagnostics even on failure.

Candidate (release.yml) -- Runs on v* Tags or Manual Dispatch

The candidate workflow resolves the exact tagged source commit and uses that immutable SHA in every downstream checkout. It:

  1. Validates extension IDs, the release tag, and the tag-to-source relationship
  2. Builds chrome.zip, firefox.zip, firefox-sources.zip
  3. Builds raw helpers for macOS, Linux, and Windows, each for amd64 and arm64
  4. Verifies Firefox source ZIP: extracts sources, rebuilds from scratch, diff -qr against original to ensure reproducibility
  5. Signs/notarizes the macOS binaries, app, and package and verifies every layer
  6. Builds and inspects Linux .deb/.rpm packages and includes the Unix and PowerShell bootstraps
  7. In signed mode, verifies both raw Windows EXEs, the outer x64 MSI, and its embedded amd64 EXE against the configured signing policy; explicit unsigned mode records its exception
  8. Requires native ARM64 runtime evidence and Defender evidence for both raw Windows EXEs and the MSI in both signing modes
  9. Assembles the complete allowlisted matrix, generates SHA256SUMS.txt only after final signing/packaging, creates build-provenance attestations, and stores the immutable candidate for 90 days

The candidate workflow has no release-write permission and never publishes assets. The currently documented external Windows signer selection and publisher subject are intentionally fail-closed; see WINDOWS_CODE_SIGNING_POLICY.md.

Helper publication (publish-helper-release.yml) -- Manual Dispatch Only

Publication accepts a candidate run ID, tag, and checksum-manifest digest. It resolves and pins the source SHA from the validated tag and candidate run, then verifies that the candidate came from this repository's candidate workflow, succeeded for that immutable source, is still available, matches the exact asset allowlist and checksums, and has valid signatures. It also verifies the candidate attestations before the protected windows-release-clearance environment approval.

After approval, publication is retry-safe: it creates or reuses a draft release, refuses conflicting existing bytes, uploads only missing identical assets without clobbering, re-verifies the complete draft, and publishes it explicitly. The reviewer-approved bytes and published bytes therefore share the same candidate manifest digest. Defender/Malwarebytes findings apply only to those exact hashes; an ordinary SmartScreen unknown-reputation warning is tracked separately from a malware or PUA detection. The complete operator procedure and asset matrix are in RELEASE_CHECKLIST.md.

Publish (publish.yml) -- Manual Dispatch Only

Two jobs with environment-gated approvals:

  1. submit-chrome (environment: chrome-web-store)
  • Downloads chrome.zip from GitHub Release
  • Verifies SHA256 checksum
  • Submits via pnpm wxt submit --chrome-zip
  1. submit-firefox (environment: firefox-amo)
  • Downloads firefox.zip + firefox-sources.zip
  • Verifies checksums
  • Validates Firefox publish gate
  • Submits via pnpm wxt submit --firefox-zip --firefox-sources-zip --firefox-channel listed
  • Supports dry_run mode

Homebrew update (update-homebrew.yml) -- Reusable or Manual

After a stable helper release is published, this workflow verifies the release tag and checksum-manifest digest, computes the tagged source-archive checksum, updates the cask and source formula, reruns updater and Ruby syntax checks, and opens a reviewable pull request. It uploads the patch as a manual fallback if pull-request creation is unavailable.


Test Infrastructure

Framework

Vitest with Chrome API mocks (packages/shared/src/__test__/chrome-mock.ts).

Test Files

Background tests:

Test File Covers
background.test.ts Service worker core: native message handling, popup communication, exit node restore, context menus, keepalive
native-host.test.ts Connection lifecycle, reconnection with exponential backoff, error handling
state-store.test.ts State management: update(), applyStatusUpdate(), subscribe(), version incrementing
badge-manager.test.ts Icon/badge updates for all state combinations
proxy-utils.test.ts IP conversion, CIDR parsing, MagicDNS sanitization, subnet collection
routing-protection.test.ts Persisted routing snapshots, account scoping, fail-closed transitions, and explicit release
proxy-session.test.ts Helper proxy credential lifecycle and session replacement
auto-connect.test.ts Backend eligibility, local preference, session handled flag, and persisted connection intent
timer-service.test.ts Timer abstraction contract
chrome-alarm-timer-service.test.ts MV3 alarm-backed reconnect timeout and one-shot deduplication
ui-surface.test.ts Side panel toggle plumbing: persistence, applyUiSurface, sidebar opener registration

Proxy tests:

Test File Covers
chrome-proxy-manager.test.ts PAC generation, mandatory blocked routing, ownership verification, and deduplication
chrome-proxy-auth.test.ts Chrome HTTP proxy credential challenges and isolation
chrome.test.ts Chrome bootstrap and PAC preservation across worker suspension
firefox-proxy-manager.test.ts Authenticated/fail-closed SOCKS routing, DNS and split-tunnel decisions, direct mode, and no-fallback proxy chains
firefox.test.ts Firefox-specific keepalive via alarms

Popup tests:

Test File Covers
popup.test.ts View routing for all state combinations
peer-item.test.ts Peer component rendering and actions
peer-filters.test.ts Peer search, online/offline grouping
custom-urls.test.ts Custom URL storage
utils.test.ts HTML escaping, clipboard, toast, platform detection, location helpers
ui-surface-row.test.ts "Open as side panel" quick-settings row
views/connected.test.ts Accessible quick-setting navigation and preservation of unsaved split rules
views/disconnected.test.ts Reconnecting-state precedence
views/exit-nodes.test.ts Exit node picker: search, Recommended row, Mullvad grouping, selection logic
views/install-helpers.test.ts Platform/architecture asset selection, pinned installer commands, and retry/repair UI
types.test.ts Shared type guards / fixture sanity

Native host tests (Go):

Test File Covers
protocol_test.go Invalid/oversized frame recovery, status truncation, and profile-ID validation
proxy_test.go Quad-100 routing and buffered CONNECT bytes
proxy_policy_test.go, proxy_integration_test.go Destination authorization, authenticated proxying, web client, and identity-transition gates
dns*_test.go, exit_dns_test.go Restricted split DNS, subnet nameservers, exit DNS, cancellation, and fail-closed behavior
peers_test.go Peer IP, route, identity, tag, key-expiry, and capability conversion
status_test.go Status/prefs mapping and cached browse/login state
taildrop_test.go Chunk assembly/progress, validation, cleanup, and active-transfer cancellation
install_test.go, install_windows_test.go CLI parsing, manifest/registry installation, extension-ID formatting, and cleanup
install_flatpak_test.go Chrome/Firefox Flatpak ownership, rollback, sandbox containment, locking, CLI flags, and cleanup
control_url_test.go Control-server normalization and validation

Installer and platform smoke tests:

Test File Covers
scripts/install.test.sh Hermetic Unix installer downloads, verification, upgrade, rollback, and uninstall
scripts/install.test.ps1 Portable Windows architecture selection, verification, replacement, rollback, and uninstall
scripts/test-flatpak.sh Chrome or Firefox Flatpak sandbox installation, native procRunning/pong framing, and cleanup; it does not test the store extension, login, or browser routing
scripts/update-homebrew.test.mjs Cask/formula version and checksum updates, validation, downgrade rejection, and idempotence

Running Tests

pnpm test              # Run all unit tests once
pnpm test:installer    # Run the Unix verified-installer fixtures
pnpm test:homebrew     # Run Homebrew updater tests
pnpm e2e:chrome        # Puppeteer end-to-end suite (Chrome)
pnpm e2e:firefox       # Puppeteer end-to-end suite (Firefox)
pnpm e2e:full          # Full Puppeteer suite, both browsers
cd host && go test ./... # Native host Go tests

The Puppeteer harness lives in scripts/e2e/; see puppeteer-testing-suite.md for layout, fixtures, and the smoke vs. full suites.


Configuration Reference

Extension IDs (config/extension-ids.json)

{
  "chromeExtensionId": "bhfeceecialgilpedkoflminjgcjljll",
  "firefoxAddonId": "tailchrome@tesseras.org",
  "chromeNativeHostId": "com.tailscale.browserext.chrome",
  "firefoxNativeHostId": "com.tailscale.browserext.firefox"
}

Manifest Permissions

Permission Purpose
proxy Configure browser proxy settings
storage Persist profileId, exit node, custom URLs
nativeMessaging Communicate with native host
contextMenus Right-click "Send page URL" menu
alarms Firefox keepalive and Chrome suspension-safe reconnect timeout
sidePanel Chrome toolbar integration for the optional docked UI
<all_urls> (host permission) Proxy interception for all URLs

Browser Storage Keys

Key Storage Purpose
profileId chrome.storage.local Browser profile UUID for tsnet isolation
customUrls chrome.storage.local Per-device custom open targets
domainSplitConfig chrome.storage.local Split-tunneling mode (bypass/only) and domain list
autoConnectOnStart chrome.storage.local Opt-in preference for auto-connecting the tailnet on browser start
uiSurface chrome.storage.local Toolbar surface: popup or sidePanel/Firefox sidebar
autoConnectHandled chrome.storage.session Per-session flag that prevents auto-connect from overriding an explicit manual disconnect
desiredWantRunning chrome.storage.session Per-session connection intent sent as the wantRunning hint with host init
lastSessionWantRunning chrome.storage.local Temporary fallback intent across extension reload/update; cleared at the next browser startup
helperActivationRetry chrome.storage.session Source, retry index, and absolute helper-discovery deadline
helperRegistrationRepairAvailable chrome.storage.session Whether package/fallback discovery exhausted and repair should be promoted
routingProtectionV1 chrome.storage.local Sanitized account-scoped routing snapshots and transition state for fail-closed restoration; excludes helper ports and credentials

Security Model

Login URL Validation

For Tailscale's default control plane, login URLs from the native host (browseToURL or authURL) are validated against this allowlist before opening:

  • https://login.tailscale.com
  • https://controlplane.tailscale.com
  • https://tailscale.com

For a configured custom coordination server, delegated login URLs may use another origin. The URL must still be valid HTTP(S), and an HTTPS coordination server may only delegate to HTTPS. A stale default-Tailscale login URL is held briefly while the new server emits its current URL.

Helper compatibility

The extension does not infer protocol incompatibility from semantic versions. A version difference alone produces a dismissible notice. Optional features are enabled from the capabilities advertised by the connected helper.

Authenticated-proxy support is mandatory starting with v0.1.14. The helper must provide a valid procRunning.proxyAuth session using the supported protocol version and a valid proxy port. Missing or invalid session credentials produce helper-incompatible with diagnostic code helper-proxy-auth-required, and the extension does not enable that proxy.

Upgrade the helper and extension together from v0.1.13 or earlier. The older helper does not provide proxy credentials; the older extension uses unauthenticated SOCKS and cannot authenticate to the new helper. Consequently, neither mixed pair can provide normal protected browsing. Publish the matching helper assets before the store rollout, and complete both updates before resuming protected browsing. A version-only compatibility test must use a helper fixture that supplies the required authenticated session.

Helper artifacts

SHA256SUMS.txt covers every final release asset after signing, notarization, and packaging. When GitHub CLI is available, gh attestation verify <asset> --repo dantraynor/tailchrome verifies the artifact's build provenance. On macOS, use pkgutil --check-signature for the package and codesign --verify --deep --strict plus spctl for the embedded app. On Windows, use Get-AuthenticodeSignature or SignTool; the release gate additionally verifies both raw EXEs, the byte-identical amd64 MSI-embedded EXE, and the outer MSI against one exact publisher subject and timestamp policy.

Signed Windows publication requires a configured signing provider and its exact publisher subject. Missing credentials, policy values, signatures, timestamps, nested identity, or security evidence fail the signed candidate. The documented unsigned mode must be selected explicitly; it never follows automatically from a signing failure. See WINDOWS_CODE_SIGNING_POLICY.md and SECURITY.md for verification and false-positive reporting.

Proxy Scope

  • Only browser traffic is proxied -- system networking is never modified
  • The proxy binds to 127.0.0.1 only (not exposed to the network)
  • Suspending Chrome's MV3 worker does not clear Tailchrome's mandatory PAC. Chrome removes its proxy setting only when Tailchrome's effective policy becomes direct, immediately for an explicit routing release or after a requested disconnect is confirmed. Firefox keeps its proxy.onRequest listener installed and returns direct in that mode
  • If an already protected route loses the helper, its authentication session, or its selected exit node, protected requests remain fail-closed (while split-tunnel exceptions remain direct) instead of falling through
  • HTTP and SOCKS5 proxy connections require credentials generated for the helper process and delivered to the extension through native messaging

Web Client Authorization

The Tailscale web client (100.100.100.100) checks its management session and the viewer's capabilities independently of proxy authentication. Mutating web requests retain Tailscale's same-origin checks using Sec-Fetch-Site or Origin. The Sec-Tailscale: browser-ext header does not replace those checks.

Web logout and native account changes stop new web requests and drain active handlers before changing identity. An authorized web logout clears the old profile's cached state and web authorization at the LocalAPI boundary, before logout executes. The host serializes this operation with native commands and shutdown; a browser disconnect does not release the gate while a submitted mutation is still running.

Native Messaging

Native messaging is restricted to the declared extension IDs in the native host manifest. The Chrome manifest uses allowed_origins, Firefox uses allowed_extensions.


Data Handling and Privacy

Data Stored Locally

Data Where Purpose
profileId Browser local storage Per-profile Tailscale node isolation
customUrls Browser local storage Custom per-device URLs
domainSplitConfig Browser local storage Split-tunneling mode and domain list (entered by the user)
autoConnectOnStart Browser local storage "Auto-connect on start" preference (off by default)
uiSurface Browser local storage Popup versus side-panel/sidebar preference
autoConnectHandled Browser session storage Per-session flag to honor an explicit manual disconnect
desiredWantRunning Browser session storage Per-session helper startup intent
lastSessionWantRunning Browser local storage Temporary update/reload fallback for connection intent; cleared on browser startup
helperActivationRetry Browser session storage Pending package/fallback discovery retry deadline
helperRegistrationRepairAvailable Browser session storage Session-scoped registration-repair promotion
routingProtectionV1 Browser local storage Sanitized account-scoped routing snapshots and transition state; excludes helper ports and credentials
~/.config/tailscale-browser-ext/<UUID>/ Filesystem tsnet state directory (keys, config)

Data Transmitted

When enabled, Tailchrome transmits:

  • Browsing activity and website content needed for proxy/exit-node traffic
  • Authentication data for login to Tailscale or the configured custom coordination server
  • Device and network metadata for peer discovery
  • User-initiated file contents for Taildrop transfers

Data is sent only to: the local native host, the user's tailnet and configured coordination plane (Tailscale by default), and sites the user accesses through Tailchrome.

Data NOT Collected

Tailchrome does not include analytics, crash telemetry, advertising identifiers, or marketing data.

Helper activation diagnostics do not change that promise. A report is generated only after the user clicks Copy diagnostic report or Export diagnostic report and remains local until the user chooses to paste or share the copied/exported file. The allowlist excludes tailnet/account identity, profile and peer data, browsing history and URLs, login/authentication data, credentials, file-transfer content, Tailscale state directories, extension storage contents, filesystem user names, and registry values containing user data. Plain-text native errors are sanitized for home paths, URLs, hosts, email addresses, IP addresses, tokens/secrets, UUIDs, and registry paths before they can be retained in the bounded report.

Full policy: docs/privacy-policy.md


Store Listings

Chrome Web Store

  • Category: Productivity
  • Short description: "Access your Tailscale tailnet directly from your browser. Per-profile VPN without touching system networking."
  • Extension ID: bhfeceecialgilpedkoflminjgcjljll

Firefox AMO

  • Listing status: Published on Firefox Add-ons (AMO).
  • Categories: Privacy & Security, Other
  • Addon ID: tailchrome@tesseras.org
  • Minimum Firefox version: 142.0
  • Source code disclosure: firefox-sources.zip included with each release for AMO reviewer verification

Full listing text: STORE_LISTING.md


Contributing

  1. Fork the repo and clone locally
  2. Install dependencies: Go 1.26.6+, Node.js 22+, pnpm (via corepack enable)
  3. pnpm install --frozen-lockfile
  4. Build: pnpm build:chrome, pnpm build:firefox, make host
  5. Load extension in browser for testing:
  • Chrome: chrome://extensions -> Developer Mode -> Load unpacked packages/extension/.output/chrome-mv3-dev/ (with make dev) or packages/extension/.output/chrome-mv3/ (after pnpm build:chrome)
  • Firefox: about:debugging#/runtime/this-firefox -> Load temporary addon packages/extension/.output/firefox-mv3/manifest.json
  1. Install native host by running the built binary directly

Guidelines

  • Open an issue first before submitting a PR
  • Keep PRs focused -- one feature or fix per PR
  • Write clear commit messages
  • Test changes in both Chrome and Firefox
  • Follow existing code patterns

Full guide: CONTRIBUTING.md


Appendix: Go Dependencies

Key dependencies in host/go.mod:

Dependency Version Purpose
tailscale.com v1.103.0-pre.0.20260819151608-90ed0bcf4bc2 tsnet, local client, IPN, socks5, proxymux, web client
golang.org/x/term v0.45.0 Terminal detection for auto-install
golang.org/x/sys v0.47.0 System calls