Metadata-Version: 2.4
Name: hirogate
Version: 0.1.0
Summary: Hiro — WebSocket relay gateway server
Project-URL: Homepage, https://www.hiroleague.com
Project-URL: Documentation, https://docs.hiroleague.com
Project-URL: Repository, https://github.com/hiro-league/hiroleague
Project-URL: Issues, https://github.com/hiro-league/hiroleague/issues
Author-email: Michel Habib <michelhabib@gmail.com>
License: MIT
Keywords: gateway,home,relay,server,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: cryptography>=43
Requires-Dist: hiro-channel-sdk~=0.1.0
Requires-Dist: hiro-commons~=0.1.0
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic>=2
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Requires-Dist: websockets>=12
Description-Content-Type: text/markdown

# hirogate

**Hiro Gateway** — WebSocket relay server.

Accepts connections from Hiro desktop servers and online apps, performs
challenge/response authentication, and relays messages between authenticated
devices identified by `device_id`.

## Dev setup

`hirogate` is part of the `hiroserver` uv workspace. No separate tool install is needed — it runs directly from the workspace venv via `uv run`.

After cloning or pulling updated code, run from the repo root:

```bash
./dev-sync.sh
```

Or manually:

```bash
cd hiroserver
uv sync
```

## Quick Start

```bash
# Create a named gateway instance (mandatory values at creation)
uv run hirogate instance create home --port 8765 --desktop-pubkey "<base64-public-key>" --set-default

# Start the instance later using only its name/default
uv run hirogate start --instance home
# or simply:
uv run hirogate
```

## Instance model

Each gateway runs as a named instance with persistent config:

- `name` (instance identity)
- `host` and `port` (bind address)
- `desktop_public_key` trust root
- `log_dir` (optional override)

Instance commands:

```bash
hirogate instance list
hirogate instance show home
hirogate instance set-default home
hirogate instance remove home --purge
```

## How it works

1. Every new socket receives an auth challenge nonce.
2. A desktop client authenticates using its master key (`auth_mode=desktop`) against
   the desktop trust root configured at startup (`--desktop-pubkey`).
3. A device client authenticates with desktop attestation + nonce signature
   (`auth_mode=device`).
4. Once authenticated, messages are relayed by `device_id`.

## Message Format

```json
{
  "target_device_id": "uuid-of-the-target-device",
  "payload": { ... }
}
```

If `target_device_id` is omitted, the message is broadcast to all connected devices.
