# Riftbreaker Twitch Chaos Bridge

Experimental Windows tray bridge for the Riftbreaker Twitch Chaos Workshop mod.

## Requirements

- Windows 10 or 11 with .NET Framework 4.8.
- The Riftbreaker and the matching Twitch Chaos mod enabled.
- A disposable save while testing disaster triggers.

LRDB permits arbitrary Lua evaluation and is not a production-safe interface. The bridge enables it while running and writes `set debug_lua 0` during orderly shutdown. If the bridge is killed or the PC loses power, cleanup is not guaranteed. Disabling the setting does not remove LRDB from an already-running game process; close Riftbreaker as well.

## Run

Start `RiftbreakerTwitchChaosBridge.exe` before starting Riftbreaker. The executable:

1. enables `debug_lua` directly in the user's `developer.cfg`;
2. listens only on `ws://127.0.0.1:17810/v1`;
3. connects to Riftbreaker's LRDB endpoint when the game starts;
4. exposes status, pairing, and exit controls through its tray icon.

Right-click the tray icon to:

- inspect current Riftbreaker status;
- **Open app** with this tray run's pairing code, which the web app consumes automatically;
- copy the per-run pairing code for manual or diagnostic clients;
- copy redacted diagnostics;
- **Exit** and disable the debugger for the next game launch.

If Riftbreaker was already running when the bridge changed the setting, restart the game.

## Local WebSocket protocol

Release builds accept only Origin `https://riftbreaker.mael.tech`, path `/v1`, and one controlling client. Authenticate first with the six-digit code generated for the current tray app run:

```json
{"version":1,"type":"authenticate","code":"123456"}
```

Use the returned `sessionToken` on status and trigger messages. Trigger messages accept only allowlisted disaster IDs, bounded request IDs, and an expiry no more than five minutes in the future:

```json
{
  "version": 1,
  "type": "trigger",
  "sessionToken": "...",
  "requestId": "request-001",
  "disasterId": "earthquake",
  "expiresAt": "2026-09-30T20:05:30Z"
}
```

The transport queue is bounded to 32 entries. Ambiguous LRDB failures are reported as `outcome_unknown` and are never replayed automatically.

## Build

Install the .NET 8 SDK. It is used only to build; the resulting application targets the Windows-provided .NET Framework 4.8.

Windows:

```text
tray-app\scripts\build.cmd
```

WSL/Linux:

```bash
./tray-app/scripts/build.sh
```

Output is under `tray-app/dist/`. Release builds merge the pinned Fleck dependency into the normal managed executable; no runtime extraction or packer is used.

### Install a development build into Windows

The checked-in installer builds, verifies, and atomically copies the portable files to:

```text
%LOCALAPPDATA%\RiftbreakerTwitchChaos\app
```

From WSL/Git Bash:

```bash
./tray-app/scripts/install-dev.sh
# Build, install, and start it:
./tray-app/scripts/install-dev.sh -Start
```

From Windows Terminal/Command Prompt:

```text
tray-app\scripts\install-dev.cmd
tray-app\scripts\install-dev.cmd -Start
```

The installer refuses to overwrite a running bridge. Exit the existing process through its tray menu first. It validates the source, staged, and installed executable against `SHA256SUMS.txt`; it does not invoke or modify the Riftbreaker mod tooling.

### Disposable-save end-to-end test

Install and launch the development build before starting Riftbreaker. Install mod `0.0.4`, load a disposable gameplay save, right-click the tray icon, and select **Copy pairing code**.

Then exercise the local protocol without waiting for hosted-site integration:

```text
tray-app\scripts\test-client.cmd status -PairingCode 123456
tray-app\scripts\test-client.cmd trigger earthquake -PairingCode 123456
```

WSL/Git Bash wrapper:

```bash
./tray-app/scripts/test-client.sh status -PairingCode 123456
./tray-app/scripts/test-client.sh trigger earthquake -PairingCode 123456
```

The pairing code remains constant until the tray app exits, so it can authenticate reconnects and separate test-client invocations during that run. A new tray process generates a new code. Always use a disposable save for trigger tests, then exit through the tray menu so debugger cleanup runs.

The normal build is deliberately unsigned and prints a warning. Production publishing requires an Authenticode certificate:

```powershell
tray-app\scripts\publish.ps1 -CertificateThumbprint <thumbprint>
```

Do not distribute an unsigned development artifact as a production release. No project can guarantee zero antivirus false positives; see [`../docs/tray-app.md`](../docs/tray-app.md) for the signing and reputation gates.

## Current limitations

- Production use of LRDB has not passed the security go/no-go gate.
- Browser mixed-content behavior from the HTTPS site to loopback `ws://` still requires interactive verification.
- Mod `0.0.4` adds the per-map session ID expected by the bridge, but map-transition behavior still needs live acceptance testing.
- Authenticode signing requires external certificate credentials and is not performed by source builds.