# ZoneGaze Relay

ZoneGaze Relay is the self-hostable fallback path for Device Link. It is for users who want Mac and Android devices to remain reachable from different networks without using ZoneGaze-hosted traffic, public relays, Firebase, TURN, or a cloud device directory.

## Guarantees
- The relay requires signed ZoneGaze device tokens.
- The relay checks every token against a user-owned device-group allow-list.
- Unknown, revoked, or cross-group devices are rejected.
- Packet payloads are treated as opaque ciphertext. The relay stores and forwards bytes; it does not decrypt app data.
- The relay is not a global directory. Devices must already know their paired device group.

## Current Package
The implementation lives in `platforms/device-link-relay`.

Run locally:

```bash
npm --prefix platforms/device-link-relay run build
node platforms/device-link-relay/dist/cli.js --host 0.0.0.0 --port 8098 --groups groups.json
```

After pairing at least one other device, copy the relay allow-list from the Matrix Devices screen and save it as `groups.json` on the machine that will run the relay:

```json
{
  "groups": [
    {
      "groupId": "group-example",
      "devices": [
        { "deviceId": "mac-device-id", "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n" },
        { "deviceId": "android-device-id", "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n" }
      ]
    }
  ]
}
```

## HTTP Surface
- `HEAD /` and `GET /.well-known/zonegaze-device-link-relay`: authenticated health checks.
- `POST /v1/packets`: enqueue an opaque encrypted packet for another paired device in the same group.
- `GET /v1/packets`: poll queued packets for the authenticated receiving device.

All requests require:

```http
Authorization: Bearer <base64url-json-claims>.<ed25519-signature>
x-zonegaze-device-id: <device-id>
x-zonegaze-relay-group: <group-id>
```

## Android Follow-Up
Android already owns local identity, native pairing, paired-device state, capability controls, and same-network NSD discovery. The Android relay slice still needs:

- Android Keystore signing for `DeviceLinkRelayAccessClaims`.
- Android-native relay allow-list export matching the Matrix Devices copy action.
- Native Iroh route integration before falling back to relay polling.
- Foreground/background UX for remote reachability and battery limits.
- Physical QA with MacBook and Android on same Wi-Fi, hotspot, separate networks, relay offline/online, revoked device, and two user groups on one relay.
