# USB Server

USB-Sharing ueber Netzwerk mit Relay-Server fuer NAT-Traversal.

## Architektur

```
┌──────────────────┐         ┌──────────────┐         ┌──────────────────┐
│  Client (share)  │──ws/wss─│ Relay Server │─ws/wss──│  Client (use)    │
│  gibt USB-Geraete│         │ (Docker)     │         │  empfaengt USB-  │
│  frei            │         │ gruppiert    │         │  Geraete         │
│  Web-UI :8080    │         │ nach Hash    │         │  Web-UI :8080    │
└────────┬─────────┘         └──────────────┘         └────────┬─────────┘
         │                                                     │
    Physische USB                                     Virtuelle USB
    Geraete                                           (vhci-hcd)
```

**Relay-Server:** Einfacher WebSocket-Vermittler. Braucht keine Konfiguration - verbindet alle Clients die den gleichen Hash haben. Als Docker-Container deploybar.

**Client:** Kann in zwei Modi betrieben werden:
- **Share-Modus:** Gibt alle lokalen USB-Geraete frei. Geraete werden erst dann vom System getrennt wenn ein Use-Client sie anfordert.
- **Use-Modus:** Zeigt verfuegbare Geraete von allen Share-Clients an. Geraete koennen einzeln verbunden/getrennt werden.

**Gruppierung:** 3 zufaellige Tokens werden zu einem SHA256-Hash kombiniert. Alle Clients mit dem gleichen Hash gehoeren zusammen.

## Quick Start

### 1. Relay-Server starten

```bash
# Mit Docker
docker compose up -d

# Oder direkt
make relay
./bin/usb-relay --port 8443
```

### 2. Tokens generieren

Auf dem ersten Client:

```bash
./bin/usb-client generate-token
```

Ausgabe:
```
Token 1: aB3dE...
Token 2: xY7zW...
Token 3: mN4pQ...
Hash:    a1b2c3d4e5...
```

Die 3 Tokens auf alle weiteren Clients kopieren.

### 3. USB-Geraete freigeben (Share-Modus)

```bash
./bin/usb-client share --relay ws://relay-server:8443
```

### 4. USB-Geraete empfangen (Use-Modus)

```bash
./bin/usb-client use --relay ws://relay-server:8443
```

Web-UI oeffnen: http://localhost:8080

## Installation

### Voraussetzungen

**Linux (Share-Modus):**
- Root-Rechte (fuer USB-Geraetezugriff)

**Linux (Use-Modus):**
- Kernel-Modul `vhci-hcd`:
  ```bash
  sudo modprobe vhci-hcd
  ```
- Fuer automatisches Laden bei Boot:
  ```bash
  echo "vhci-hcd" | sudo tee /etc/modules-load.d/vhci-hcd.conf
  ```

### Bauen

```bash
# Benoetigt Go 1.21+
make all

# Fuer Windows (Cross-Compilation):
make client-windows
```

### Docker (Relay-Server)

```bash
docker compose up -d
```

Der Relay lauscht auf Port 8443.

## CLI Befehle

```
usb-client generate-token          # 3 Tokens + Hash generieren
usb-client share [optionen]        # Share-Modus starten
usb-client use [optionen]          # Use-Modus starten
usb-client list                    # Lokale USB-Geraete auflisten
usb-client gui                     # Nur Web-UI starten
usb-client config                  # Konfiguration anzeigen
usb-client config set [optionen]   # Konfiguration aendern
usb-client install-service         # Als systemd-Service installieren
usb-client uninstall-service       # Service deinstallieren
```

### Optionen

```
--config <pfad>    Config-Datei (Standard: ~/.usb-server/config.json)
--relay <adresse>  Relay-Server (z.B. ws://localhost:8443)
--hash <hash>      Gruppen-Hash
--name <name>      Client-Name
--web-port <port>  Web-UI Port (Standard: 8080)
--no-gui           Web-UI deaktivieren
```

## Web-UI

Die Web-UI ist unter http://localhost:8080 erreichbar und bietet:

- **Geraete-Tab:** Liste aller verfuegbaren/verbundenen USB-Geraete
- **Einstellungen:** Relay-Adresse, Modus, Name konfigurieren
- **Token:** Tokens generieren oder eintragen
- **Service:** Als Systemdienst installieren/deinstallieren

## Konfiguration

Die Konfiguration wird in `~/.usb-server/config.json` gespeichert:

```json
{
  "relay_addr": "ws://localhost:8443",
  "hash": "a1b2c3d4...",
  "mode": "use",
  "name": "Mein-PC",
  "web_port": 8080,
  "token1": "...",
  "token2": "...",
  "token3": "...",
  "auto_connect": [
    {"vendor_id": "1234", "product_id": "5678"},
    {"bus_id": "1-1.4"}
  ]
}
```

## Als Service installieren

```bash
# Service installieren (braucht root)
sudo ./bin/usb-client install-service

# Service Status pruefen
systemctl status usb-client

# Service deinstallieren
sudo ./bin/usb-client uninstall-service
```

## Sicherheit

- **Transport-Verschluesselung:** Verwende `wss://` (WebSocket over TLS) fuer den Relay-Server bei Einsatz ueber das Internet.
- **Gruppierung:** Die 3 Tokens dienen als gemeinsames Geheimnis. Nur wer alle 3 Tokens kennt kann den Hash berechnen.
- **Relay:** Der Relay-Server sieht nur den Hash, nicht die Tokens.

Fuer TLS am Relay-Server empfiehlt sich ein Reverse-Proxy (nginx/traefik) mit Let's Encrypt:

```nginx
server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    location /ws {
        proxy_pass http://localhost:8443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## Technische Details

- **Sprache:** Go (single binary, keine Runtime-Abhaengigkeiten)
- **USB/IP:** Natives USB/IP-Protokoll (kein externes `usbip`-Paket noetig)
- **USB-Zugriff:** Direkte usbdevfs-ioctls (kein CGO/libusb)
- **VHCI:** Direkte sysfs-Schnittstelle zum vhci-hcd Kernel-Modul
- **Relay:** WebSocket mit JSON-Kontrollnachrichten und Binary-Tunneldaten
- **Tunnel:** USB/IP-Protokolldaten werden durch WebSocket-Binary-Frames getunnelt

## Verzeichnisstruktur

```
cmd/usb-relay/       - Relay-Server Binary
cmd/usb-client/      - Client Binary (share + use Modi)
internal/relay/      - WebSocket Relay & Hub
internal/protocol/   - Nachrichtentypen
internal/client/     - Client Core, Share & Use Manager
internal/usbip/      - USB/IP Protokoll, Server, VHCI
internal/usb/        - USB Enumeration & usbdevfs
internal/token/      - Token-Generierung
internal/config/     - Konfiguration
internal/web/        - Web-UI (embedded)
internal/service/    - Systemd Service
```

## Lizenz

Proprietaere Software. Alle Rechte vorbehalten.
Siehe [LICENSE](LICENSE) fuer Details.

### Third-Party Lizenzen

Diese Software verwendet Open-Source-Bibliotheken. Siehe [NOTICE](NOTICE) fuer Details.