# BroadcastClient.Agent (Device-side)

Device-side agent for on-demand VNC:

- starts VNC server (`tvnserver`) only when requested
- starts reverse SSH (`ssh -N -R 127.0.0.1:<allocated>:127.0.0.1:5900 ...`) only when requested
- stops reverse tunnel and (if started by the agent) stops VNC server when the session ends

## Config

Edit `appsettings.json` next to the executable.

Key fields:

- `WebApp:Url`
- `WebApp:AccessToken` (JWT for SignalR hub auth)
- `WebApp:AllowUntrustedCertificates` (default: `false`)
  - set to `true` only for private networks/dev when the WebApp certificate is not trusted by the device OS.
  - this disables TLS certificate validation and is insecure on public networks.
- `Agent:ApiKey` (recommended) if `WebApp:AccessToken` is empty: the agent will request a short-lived JWT from the WebApp.
- `Agent:DeviceId`
  - optional if `Agent:ApiKey` is set (the WebApp resolves canonical `BroadcastDevices.DeviceIdentifier` by APIKey)
  - required if your APIKey is missing/invalid or maps to multiple devices
- `Ssh:AutoAcceptHostKeyOnFirstUse` (default: `false`)
  - when `Ssh:StrictHostKeyChecking=true` and the gateway host key is not yet known, the agent will
    auto-accept the host key once and write it to the known_hosts file (TOFU).
  - set to `true` only when you intentionally want TOFU (first-use trust) instead of a pinned known_hosts.

### Host Key Pinning (recommended)

This repo ships a pinned `ssh_known_hosts` file next to the agent executable.

- Default path: `ssh_known_hosts` (in `AppContext.BaseDirectory`)
- With `Ssh:StrictHostKeyChecking=true` and `Ssh:AutoAcceptHostKeyOnFirstUse=false`, the agent will **fail closed**
  if the gateway host key changes or is not the pinned one.

### SSH Identity (required)

The tunnel account is key-based only. You must provide a private key that matches an entry in the gateway
`vnc_tunnel` account `authorized_keys`.

If `Ssh:IdentityFile` is empty, the agent will auto-detect (first match):

- `ssh/id_ed25519`
- `ssh/id_rsa`
- `id_ed25519`
- `id_rsa`

## Windows TightVNC SDK bundling (required)

This project copies `../sdk/vnc/**` into the build output as `sdk/vnc/...` so the agent can prefer the bundled `tvnserver.exe`.

## Build (example)

```powershell
dotnet build -c Release .\Tools\broadcastClient\Agent\BroadcastClient.Agent.csproj
```

For full operational details, see `docs/vnc-remote-control.md`.
