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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 20 additions & 8 deletions .github/workflows/flatpak-smoke.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Chrome Flatpak helper smoke
name: Flatpak helper smoke

on:
pull_request:
Expand All @@ -11,6 +11,14 @@ jobs:
sandbox-helper:
runs-on: ubuntu-latest
timeout-minutes: 25
strategy:
fail-fast: false
matrix:
include:
- browser: chrome
app_id: com.google.Chrome
- browser: firefox
app_id: org.mozilla.firefox
env:
CGO_ENABLED: "0"
steps:
Expand All @@ -19,23 +27,27 @@ jobs:
with:
go-version-file: host/go.mod
cache-dependency-path: host/go.sum
- name: Prepare a clean Chrome Flatpak installation
- name: Prepare a clean ${{ matrix.browser }} Flatpak installation
run: |
sudo apt-get update
sudo apt-get install --yes flatpak dbus-x11
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user --noninteractive --assumeyes flathub com.google.Chrome
flatpak install --user --noninteractive --assumeyes flathub "$APP_ID"
# The smoke script intentionally refuses to touch an app instance it
# did not start. Seed only the clean config directory it needs; the
# did not start. Seed only the clean app directory it needs; the
# helper launch below is the first process started in the sandbox.
install -d -m 700 "$HOME/.var/app/com.google.Chrome/config/google-chrome"
install -d -m 700 "$HOME/.var/app/$APP_ID"
env:
APP_ID: ${{ matrix.app_id }}
- name: Verify helper framing inside the sandbox
run: dbus-run-session -- bash scripts/test-flatpak.sh
run: dbus-run-session -- bash scripts/test-flatpak.sh "$BROWSER"
env:
BROWSER: ${{ matrix.browser }}
- name: Retain smoke diagnostics
if: always()
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: flatpak-helper-smoke-log
path: .context/flatpak-smoke.log
name: flatpak-helper-smoke-log-${{ matrix.browser }}
path: .context/flatpak-smoke-${{ matrix.browser }}.log
include-hidden-files: true
if-no-files-found: warn
4 changes: 2 additions & 2 deletions docs/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,8 @@ creation requires the notes file; protected publication uses the notes from the
tagged source for both a new release and a resumed draft.

- PRs run extension tests, Chrome checks, the full Firefox review gate, Go
tests on Linux and Windows, per-user installer tests, and a Chrome Flatpak
helper smoke test. Relevant packaging changes also run native Windows ARM64
tests on Linux and Windows, per-user installer tests, and Chrome/Firefox Flatpak
helper smoke tests. Relevant packaging changes also run native Windows ARM64
helper and installer smoke checks, a macOS package smoke build with per-user
launcher tests and Bash installer fixtures using stock macOS Bash and BSD
utilities, Windows signature-verifier fixtures, and Linux package
Expand Down
24 changes: 12 additions & 12 deletions docs/DOCUMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Tailscale in the browser without changing system VPN settings. For a short overv

**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 Flatpak is a separate Linux install path ([helper installation](helper-installation.md#chrome-flatpak))
**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](helper-installation.md#chrome-flatpak), [Firefox](helper-installation.md#firefox-flatpak))
**License:** MIT
**Website:** [tesseras.org/tailchrome](https://tesseras.org/)
**Chrome Web Store:** [Chrome Web Store](https://chromewebstore.google.com/detail/tailchrome/bhfeceecialgilpedkoflminjgcjljll)
Expand Down Expand Up @@ -389,7 +389,7 @@ The native host is a Go binary at `host/` using `tailscale.com/tsnet` pinned to
| `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 Flatpak sandbox state and registration |
| `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 |
Expand Down Expand Up @@ -745,7 +745,7 @@ behavior. Existing native-host names and extension IDs are unchanged. The new
or package manager removes the executable. Node state is preserved.

See [helper installation](helper-installation.md) for exact commands, executable
paths, legacy behavior, safe upgrades, uninstall and Chrome Flatpak setup. The
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
Expand All @@ -759,7 +759,7 @@ Per-profile Tailscale state is stored at:
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 Flatpak uses its sandbox's writable XDG
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.

Expand Down Expand Up @@ -844,7 +844,7 @@ tailchrome/
| +-- install.go # Manifest installation
| +-- install_darwin.go # macOS paths
| +-- install_linux.go # Linux paths
| +-- install_flatpak_*.go # Chrome Flatpak sandbox registration
| +-- install_flatpak_*.go # Chrome/Firefox Flatpak sandbox registration
| +-- install_windows.go # Windows paths + registry
| +-- peers.go # Peer info extraction
| +-- exitnode.go # Exit node handlers
Expand All @@ -868,7 +868,7 @@ tailchrome/
| +-- 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 native-messaging smoke
| +-- 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
Expand All @@ -894,7 +894,7 @@ tailchrome/
|
+-- .github/workflows/
| +-- ci.yml # PR checks
| +-- flatpak-smoke.yml # Chrome Flatpak helper smoke on PRs
| +-- 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
Expand Down Expand Up @@ -1001,10 +1001,10 @@ change:
- **workflow-static-validation**: actionlint over every workflow and ShellCheck
over installer and packaging scripts

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

This separate workflow creates a clean user-scoped Chrome Flatpak installation,
installs the helper into its sandbox, verifies native-message framing from
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
Expand Down Expand Up @@ -1140,7 +1140,7 @@ pull-request creation is unavailable.
| `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 Flatpak ownership, rollback, sandbox containment, locking, CLI flags, 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:**
Expand All @@ -1149,7 +1149,7 @@ pull-request creation is unavailable.
| --- | --- |
| `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 Flatpak sandbox installation, native `procRunning`/`pong` framing, and cleanup; it does not test the store extension, login, or browser routing |
| `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 |


Expand Down
2 changes: 1 addition & 1 deletion docs/RELEASE_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,5 +144,5 @@ while this follow-up is completed.
- [ ] macOS ZIP launch establishes a stable signed app location and rolls back a failed upgrade.
- [ ] New package/script uninstallers preserve the replacement owner's registrations. When migrating from v0.1.13 or older, remove the old package first or rerun the new helper's registration after removal.
- [ ] Custom XDG/browser-data paths and first-use browser registration work.
- [ ] Chrome Flatpak install, helper launch, login, routing, upgrade and uninstall pass on a Linux machine supporting its namespaces; native registrations and state remain intact.
- [ ] Chrome and Firefox Flatpak install, helper launch, login, routing, upgrade and uninstall pass on a Linux machine supporting its namespaces; native registrations and state remain intact.
- [ ] The popup command/download flow retries discovery even after the popup closes.
35 changes: 33 additions & 2 deletions docs/helper-installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,5 +216,36 @@ Flatpak launch, login, routing, and upgrade validation on a Linux machine that
supports Flatpak namespaces; filesystem fixture tests alone are insufficient.
`scripts/test-flatpak.sh` exercises the helper protocol inside the sandbox on a
clean test account. It does not establish store-extension discovery or login.
The manual **Chrome Flatpak helper smoke** workflow runs that check on a clean
Linux runner without widening the app's sandbox permissions.
The **Flatpak helper smoke** workflow runs that check for Chrome and Firefox
on a clean Linux runner without widening either app's sandbox permissions.

## Firefox Flatpak

Firefox Flatpak (`org.mozilla.firefox`) works the same way and is also opt-in.
Launch it once, install the Tailchrome add-on inside it, fully close Firefox,
then run the helper outside the sandbox:

```text
tailchrome install --firefox-flatpak
```

The helper is staged at `~/.var/app/org.mozilla.firefox/tailchrome/host/` and
the manifest is written to
`~/.var/app/org.mozilla.firefox/.mozilla/native-messaging-hosts/`, which Firefox
sees as `~/.mozilla/native-messaging-hosts/` inside its sandbox. No
`flatpak override --filesystem=home` is needed. The manifest only allows the
AMO add-on ID; `--extension-dir` is Chrome-only. Node state lives in the
sandbox's `config/tailscale-browser-ext` directory, separate from native
Firefox.

If you previously copied `com.tailscale.browserext.firefox.json` into that
directory by hand, remove the copy first; the installer will not overwrite a
manifest it does not own. You can also undo the broad override with
`flatpak override --user --nofilesystem=home org.mozilla.firefox`. The sandbox
helper uses its own node state, so sign in once more after switching.

Fully close Firefox before upgrading or removing its sandbox helper:

```text
tailchrome uninstall --firefox-flatpak
```
55 changes: 40 additions & 15 deletions host/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,27 @@ type parsedCommand struct {
}

type registrationOptions struct {
BinaryPath string
ChromeID string
FirefoxID string
Browsers []string
AllBrowsers bool
UserDataDir string
ChromeFlatpak bool
ExtensionDir string
BinaryPath string
ChromeID string
FirefoxID string
Browsers []string
AllBrowsers bool
UserDataDir string
ChromeFlatpak bool
FirefoxFlatpak bool
ExtensionDir string
}

// flatpakTarget returns the Flatpak browser selected by --chrome-flatpak or
// --firefox-flatpak. The parsers reject selecting both.
func (o registrationOptions) flatpakTarget() (flatpakBrowser, bool) {
switch {
case o.ChromeFlatpak:
return chromeFlatpak, true
case o.FirefoxFlatpak:
return firefoxFlatpak, true
}
return flatpakBrowser{}, false
}

type stringList []string
Expand Down Expand Up @@ -115,6 +128,7 @@ func parseInstallCommand(args []string) (parsedCommand, error) {
fs.BoolVar(&opts.AllBrowsers, "all-browsers", false, "register every supported browser")
fs.StringVar(&opts.UserDataDir, "user-data-dir", "", "custom Chromium user-data directory")
fs.BoolVar(&opts.ChromeFlatpak, "chrome-flatpak", false, "install the helper for Chrome Flatpak")
fs.BoolVar(&opts.FirefoxFlatpak, "firefox-flatpak", false, "install the helper for Firefox Flatpak")
fs.StringVar(&opts.ExtensionDir, "extension-dir", "", "unpacked Chromium extension directory for Chrome Flatpak")
if err := fs.Parse(args); err != nil {
return parsedCommand{}, err
Expand All @@ -132,12 +146,19 @@ func parseInstallCommand(args []string) (parsedCommand, error) {
}
opts.ExtensionDir = filepath.Clean(opts.ExtensionDir)
}
if opts.ChromeFlatpak {
if opts.BinaryPath != "" || len(opts.Browsers) != 0 || opts.AllBrowsers || opts.UserDataDir != "" || opts.FirefoxID != firefoxExtensionID {
return parsedCommand{}, errors.New("--chrome-flatpak cannot be combined with native browser selection flags")
if opts.ChromeFlatpak && opts.FirefoxFlatpak {
return parsedCommand{}, errors.New("--chrome-flatpak and --firefox-flatpak cannot be combined; run install once per browser")
}
if opts.ChromeFlatpak || opts.FirefoxFlatpak {
flag := "--chrome-flatpak"
if opts.FirefoxFlatpak {
flag = "--firefox-flatpak"
}
if opts.BinaryPath != "" || len(opts.Browsers) != 0 || opts.AllBrowsers || opts.UserDataDir != "" {
return parsedCommand{}, fmt.Errorf("%s cannot be combined with native browser selection flags", flag)
}
if opts.ChromeID != chromeWebStoreExtensionID {
return parsedCommand{}, errors.New("--chrome-flatpak requires the stable Tailchrome Chrome extension ID")
if opts.ChromeID != chromeWebStoreExtensionID || opts.FirefoxID != firefoxExtensionID {
return parsedCommand{}, fmt.Errorf("%s requires the stable Tailchrome extension IDs", flag)
}
return parsedCommand{Kind: commandInstall, Opts: opts}, nil
}
Expand All @@ -163,6 +184,7 @@ func parseUninstallCommand(args []string) (parsedCommand, error) {
fs.StringVar(&opts.BinaryPath, "binary-path", "", "absolute path to the invoking executable")
fs.StringVar(&opts.UserDataDir, "user-data-dir", "", "custom Chromium user-data directory")
fs.BoolVar(&opts.ChromeFlatpak, "chrome-flatpak", false, "uninstall the Chrome Flatpak helper")
fs.BoolVar(&opts.FirefoxFlatpak, "firefox-flatpak", false, "uninstall the Firefox Flatpak helper")
fs.StringVar(&opts.ExtensionDir, "extension-dir", "", "unpacked Chromium extension directory for Chrome Flatpak")
if err := fs.Parse(args); err != nil {
return parsedCommand{}, err
Expand All @@ -173,9 +195,12 @@ func parseUninstallCommand(args []string) (parsedCommand, error) {
if opts.ExtensionDir != "" {
return parsedCommand{}, errors.New("uninstall does not accept --extension-dir; use --chrome-flatpak")
}
if opts.ChromeFlatpak {
if opts.ChromeFlatpak && opts.FirefoxFlatpak {
return parsedCommand{}, errors.New("--chrome-flatpak and --firefox-flatpak cannot be combined; run uninstall once per browser")
}
if opts.ChromeFlatpak || opts.FirefoxFlatpak {
if opts.BinaryPath != "" || opts.UserDataDir != "" {
return parsedCommand{}, errors.New("--chrome-flatpak cannot be combined with native uninstall flags")
return parsedCommand{}, errors.New("Flatpak uninstall cannot be combined with native uninstall flags")
}
return parsedCommand{Kind: commandUninstall, Opts: opts}, nil
}
Expand Down
Loading
Loading