# HoneyBadger Mesh for Windows

The installer shows a one-time geographic privacy reminder. It can open Windows
Location settings, but never changes location, browser, advertising, Wi-Fi or
Bluetooth permissions without user consent. Run
`Show-HoneyBadgerPrivacy.ps1 -Force` from the installation directory to review
the guidance again.

This client runs `hbmd` as the signed-in Windows user through a highest-privilege scheduled task. It starts at logon, can create the WireGuard tunnel with administrator rights, and keeps the local named pipe owned by the same user that runs `hbm`.

## Requirements

- Windows 10/11 or Windows Server with PowerShell 5.1+
- Official [WireGuard for Windows](https://www.wireguard.com/install/)
- An Administrator PowerShell for install/uninstall
- `hbmd.exe` built with `-tags wgreal`; the stub build does not create a VPN

## Build a bundle

From the repository root:

```powershell
powershell -ExecutionPolicy Bypass -File .\clients\windows\Package.ps1 -Arch amd64
```

The bundle is written below `clients\windows\dist`. `Package.ps1` also emits SHA-256 hashes.

For a release bundle, pass a code-signing certificate thumbprint. The packager
finds it in the current-user or local-machine certificate store, signs both
executables and all PowerShell entry points, verifies every signature, and only
then writes hashes:

```powershell
.\clients\windows\Package.ps1 -Arch amd64 `
  -CodeSigningCertificateThumbprint '0123456789ABCDEF...' `
  -TimestampServer 'http://your-authenticode-timestamp-service'
```

## Install

Open an Administrator PowerShell in the bundle directory. Read the enrollment key without placing it in shell history:

```powershell
$key = Read-Host 'Auth key' -AsSecureString
.\Install-HoneyBadgerMesh.ps1 `
  -Coord 'https://coord.example.com' `
  -AuthKey $key `
  -TunnelDNS '1.1.1.1' `
  -EnableGui
```

If WireGuard is not installed, install it first or pass its official signed installer with `-WireGuardInstaller`. The installer signature is checked before execution.

MagicDNS is enabled by default. The installer starts the local resolver on
`127.0.0.1:53`; WireGuard for Windows installs that address on the tunnel
adapter and restores the prior resolver state when the service stops. Existing
physical-adapter DNS servers are retained as upstreams when no exit is active.
Use `-TunnelDNS host[:port]` to force out-of-zone queries through an exit-side
resolver, or `-DisableMagicDNS` to opt out.

Useful optional switches include `-Relay host:port`, `-VerifyKey BASE64`, `-AcceptRoutes`, `-ForceRelay`, `-SplitTunnelPath rules.json`, and `-KillSwitch`. The GUI, when enabled, binds only to `127.0.0.1:8088` by default.

To make the Windows machine an exit node, install with `-RunAsExitNode`. The
daemon enables IPv4 forwarding on `hbm0` and creates only the named
`HoneyBadgerMesh` WinNAT instance for `100.64.0.0/10`; shutdown and uninstall
remove that instance without touching Hyper-V or other application NATs. This
requires the scheduled task's administrator rights.

`-KillSwitch` preserves `/0` routes so the official WireGuard tunnel service activates its Windows firewall kill switch. Without it, defaults are split into `/1` routes, allowing configured direct-route exceptions. Windows direct-route exceptions and `-KillSwitch` are mutually exclusive because the official firewall intentionally blocks bypass traffic.

The auth key is protected with current-user DPAPI. Config, binaries, logs, and device state are placed below the current user's LocalAppData with ACLs limited to that user, Administrators, and LocalSystem. The scheduled task uses `Interactive` logon at `Highest` privilege; it does not run before that user logs on.

Open a new terminal after installation:

```powershell
hbm status
hbm exit list
hbm exit use <name>
```

Logs are in `%LOCALAPPDATA%\HoneyBadgerMesh\state\logs\hbmd.log`. The optional GUI is at <http://127.0.0.1:8088>.

## Upgrade or remove

Run the install command again to replace binaries and update the task while retaining the encrypted auth key when `-AuthKey` is omitted.

```powershell
.\Uninstall-HoneyBadgerMesh.ps1
# Also delete the device identity and enrollment state:
.\Uninstall-HoneyBadgerMesh.ps1 -PurgeState
```

Uninstall keeps WireGuard for Windows because other tunnels may depend on it.

## Current limits

- WinNAT requires a Windows edition with the `NetNat` PowerShell cmdlets; the installer reports setup failure instead of silently advertising a broken exit.
- The scheduled task is intentionally per-user and starts at logon, not at boot.
- The publisher must supply its own trusted Authenticode certificate and timestamp service; unsigned development bundles remain supported.
