holesail-browser/README.md

# Holesail Browser

Browse P2P Holesail tunnels directly in your browser. Holesail Browser is a Chrome/Firefox extension paired with a native host that routes virtual host domains (e.g. `*.hole.sail` or any private TLD you choose) through Holesail tunnels — with automatic TLS, no port-forwarding, and no central servers.

## How it works

1. You add a virtual host in the dashboard: `myapp.hole.sail` → `hs://abc123...`
2. The extension sets a PAC script that routes `*.hole.sail` (and any other custom TLDs) → local CONNECT proxy (port 8442)
3. The CONNECT proxy pipes the raw TLS stream to the HTTPS proxy (port 8443)
4. The HTTPS proxy reads the TLS ClientHello, extracts the SNI hostname, and presents a per-TLD wildcard cert (signed by the local CA)
5. The Holesail tunnel connects P2P to the remote peer over the DHT

All traffic is end-to-end encrypted via the Noise protocol. The local CA is only used for the browser↔proxy TLS leg.

## Features

- **Virtual Hosts** — browse any `hs://` URL as `https://name.hole.sail/` or any custom private TLD (e.g. `https://api.my.internal/`)
- **Custom TLDs** — use any private two-tier TLD, not just `.hole.sail`; PAC script and certificates are updated automatically
- **Server Tunnels** — expose a local port as an `hs://` key (TCP or UDP); supports an optional label for easy identification
- **Service Tunnels** — forward a remote `hs://` peer to a local TCP port
- **SSH** — in-browser SSH terminal via xterm.js, over a Holesail tunnel; supports public key, saved password, and interactive auth
- **Remote Desktop** — VNC (noVNC) and RDP viewer in the browser, over a Holesail tunnel; passwords saved securely
- **Backups** — `tar.gz` snapshots of all state and certificates, with configurable retention
- **Auto CA** — generates and installs a local root CA; issues per-TLD wildcard certs on demand via JS-layer SNI
- **Persistent state** — all tunnels, connections, and settings survive restarts

## Installation

### macOS / Linux (recommended)

```bash
curl -fsSL https://git.ssh.surf/snxraven/holesail-browser/raw/branch/main/scripts/web-installer.sh | bash
```

### Windows

Download and run the PowerShell installer:

```powershell
irm https://git.ssh.surf/snxraven/holesail-browser/raw/branch/main/scripts/install.ps1 | iex
```

Or download `install.ps1` from the [latest release](https://git.ssh.surf/snxraven/holesail-browser/releases/tag/latest-main) and run it manually.

### What the installer does

1. Downloads the pre-built native host binary for your platform from the latest release
2. Installs it to `~/.holesail-browser/` (macOS/Linux) or `%LOCALAPPDATA%\holesail-browser\` (Windows)
3. Writes the native messaging manifest so Chrome/Firefox can find it
4. Downloads the extension `.zip` (Chrome) and `.xpi` (Firefox) to `~/Downloads`
5. On macOS: removes Gatekeeper quarantine and ad-hoc signs the binary and native addons

## Loading the extension

### Chrome / Edge

1. Open `chrome://extensions`
2. Enable **Developer mode** (top right)
3. Drag `~/Downloads/Holesail-Browser-1.0.0.zip` onto the page  
   *(or click **Load unpacked** after extracting the zip)*

### Firefox (regular)

Firefox requires extensions to be signed by Mozilla for permanent installation. Use the temporary add-on loader instead:

1. Open `about:debugging`
2. Click **This Firefox**
3. Click **Load Temporary Add-on...**
4. Select `~/Downloads/Holesail-Browser-1.0.0.zip` (or any file inside the extracted folder)

> **Note:** Temporary add-ons are removed when Firefox restarts. You will need to reload it each time.

### Firefox Developer Edition / Nightly (permanent, unsigned)

Developer Edition and Nightly allow disabling signature enforcement:

1. Open `about:config` → search for `xpinstall.signatures.required` → set it to `false`
2. Open `about:addons` → gear icon → **Install Add-on From File**
3. Select `~/Downloads/Holesail-Browser-1.0.0.xpi`

### Firefox (permanent, signed)

For a permanent install in regular Firefox, the extension must be signed by Mozilla via [addons.mozilla.org](https://addons.mozilla.org). Self-hosted distribution (no public listing required) is available — see [docs/INSTALLATION.md](docs/INSTALLATION.md) for details.

## First run

1. Click the Holesail Browser icon in your toolbar to open the **Overview** dashboard
2. Go to **Proxy & CA** → click **Install Root CA**
3. **Fully quit and reopen Chrome** (Cmd+Q on macOS) for the CA trust to take effect
4. Go to **Virtual Hosts** → add a hostname (e.g. `myapp.hole.sail`) and its `hs://` key
5. Navigate to `https://myapp.hole.sail/`

> **Note:** The CA must be installed and Chrome must be restarted before virtual host sites will load without a certificate warning. You can use any private two-tier TLD — not just `.hole.sail`.

## Dashboard pages

The dashboard uses a single topbar title per page. The **Overview** page is the landing page and features a sticky Quick Actions bar at the bottom with equal-height scrollable list cards for all data types.

| Page | Description |
|------|-------------|
| Overview | Status summary, stat cards, scrollable lists for all data types, Quick Actions |
| Virtual Hosts | Map `hs://` keys to hostnames on any private TLD |
| Server Tunnels | Expose local ports as `hs://` keys (TCP/UDP), with optional label |
| Service Tunnels | Forward remote `hs://` peers to local TCP ports |
| Proxy & CA | Proxy port settings, CA install/status |
| SSH | In-browser SSH terminal over Holesail |
| Remote Desktop | VNC/RDP viewer over Holesail |
| Backups | Create, restore, and manage backups |
| Logs | Live log stream from the native host |
| Settings | Proxy ports, timeouts, notifications, debug mode |

## File locations

| Path | Description |
|------|-------------|
| `~/.holesail-browser/holesail-browser-host` | Native host binary |
| `~/.holesail-browser/holesail-browser-storage/state.json` | All persistent state |
| `~/.holesail-browser/holesail-browser-certs/` | CA and domain certificates |
| `~/.holesail-browser/holesail-browser.log` | Native host log file |
| `~/.holesail-browser/holesail-browser-storage/backups/` | Backup archives |

## Troubleshooting

**Virtual host sites show a certificate error**

The root CA is not trusted, or Chrome was not restarted after installing it. Open the dashboard → Proxy & CA and check the CA status. If it shows "Not Installed", click **Install Root CA**, then fully quit and reopen Chrome (Cmd+Q).

If the CA shows "Installed" but you still see errors, the keychain may have a stale entry from a previous installation. Click **Install Root CA** again — it will detect the mismatch, remove the old entry, and install the correct one.

**`No tunnel for this hostname`**

The native host has no active tunnel for that hostname. Possible causes:
- The tunnel is still connecting — wait a few seconds and refresh
- The native host was restarted and is reconnecting — open the dashboard to check
- The hostname in the dashboard doesn't exactly match what you're browsing

**Native host not connecting / `hostConnected: false`**

- Make sure you haven't started `holesail-browser-host` manually from a terminal — only Chrome should spawn it via native messaging
- Check `~/.holesail-browser/holesail-browser.log` for errors
- Try reloading the extension at `chrome://extensions`

**macOS: "Apple cannot verify..." / Gatekeeper warning**

Run the installer again — it handles quarantine removal and ad-hoc signing automatically. If you moved the binary manually, run:

```bash
xattr -rd com.apple.quarantine ~/.holesail-browser/holesail-browser-host
codesign --force --sign - ~/.holesail-browser/holesail-browser-host
```

**`Access to the specified native messaging host is forbidden`**

The extension ID in the native messaging manifest doesn't match the installed extension. Re-run the installer, or manually update the `allowed_origins` field in the manifest JSON to match the extension ID shown in `chrome://extensions`.

## Building from source

```bash
git clone https://git.ssh.surf/snxraven/holesail-browser
cd holesail-browser
npm install
cd native-host && npm install && cd ..

# Build extension
npm run pack

# Build native host binary for current platform
npm run build:dist

# Build for all platforms
npm run build:dist:all
```

The built extension will be in `releases/Holesail-Browser-*.zip` and `.xpi`. Platform binaries will be in `releases/<platform>-<arch>/`.

## Platform support

| Platform | Architecture | Binary |
|----------|-------------|--------|
| macOS | Apple Silicon (arm64) | `darwin-arm64` |
| macOS | Intel (x64) | `darwin-x64` |
| Linux | x64 | `linux-x64` |
| Linux | ARM64 | `linux-arm64` |
| Windows | x64 | `win32-x64` (.exe) |

## Documentation

- [Architecture](docs/ARCHITECTURE.md) — system design, component overview, message flow
- [Installation](docs/INSTALLATION.md) — detailed install guide for all platforms
- [Tunneling](docs/TUNNELING.md) — virtual hosts, server tunnels, service tunnels
- [Virtual Hosts](docs/VIRTUAL-HOSTS.md) — custom TLDs, certificate generation, deep hostnames
- [SSH](docs/SSH.md) — in-browser SSH terminal
- [Remote Desktop](docs/REMOTE-DESKTOP.md) — VNC and RDP over Holesail
- [Backups](docs/BACKUP.md) — backup and restore
- [Security](docs/SECURITY.md) — CA model, encryption, threat model
- [Native Host Protocol](docs/NATIVE-HOST.md) — message types and API reference

## License

GNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](LICENSE) for the full text.