# Security Model

WinBridge AI is a local-first control bridge. The Mac runs the control plane and
Windows runs a polling PowerShell agent. Any connected agent can execute queued
PowerShell scripts, so access to the pairing URL must be treated as sensitive.

## Defaults

- The server listens on `0.0.0.0` so Windows machines on the same LAN can reach
  it.
- Authentication is enabled by default.
- Users enter a six-digit pairing code; successful browser pairing creates an
  HttpOnly, SameSite session cookie backed by the strong internal token.
- Failed pairing attempts are limited to five per remote address per minute.
- A local pairing token is generated at `<data-dir>/state/pairing-token`.
- Web console, API routes, file routes, and Windows agent callbacks require the token.
- The token is embedded into the generated Windows commands.
- Runtime state, logs, screenshots, and generated SSH keys stay under the user
  data directory (`~/.local/state/winbridge` on macOS/Linux or
  `%LOCALAPPDATA%\winbridge` on Windows).

## Operator Rules

- Use WinBridge AI only on networks you trust.
- Do not paste the pairing code or pairing URL into chats, tickets,
  logs, or public documents.
- Stop the server when the Windows session is complete.
- Delete `<data-dir>/state/pairing-token` to rotate the local token.
- Delete `<data-dir>/state/ssh/` or remove the Windows `authorized_keys` entry to revoke
  optional SSH access.

## Explicit Token Configuration

The default generates both a strong internal token and a six-digit browser code.
You can provide a stable browser code when automating startup:

```bash
winbridge start --code 123456
```

You can also provide a stable internal token:

```bash
WINBRIDGE_PAIRING_TOKEN="choose-a-long-random-token" winbridge start
```

Equivalent CLI form:

```bash
winbridge start --token "choose-a-long-random-token"
```

## Explicit Bypass

Only use this on an isolated, trusted network:

```bash
WINBRIDGE_AUTH_DISABLED=1 npm start
```

## Not Yet Implemented

- TLS for non-LAN operation.
- Per-agent permissions.
- Signed persistent Windows agent identity.
- Secret redaction in logs.
- Human approval gates for dangerous commands.

Those should land before positioning this as a remote internet control product.
