"type": "res",

"id": "…",

"ok": true,

"payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }

"payload": {

"type": "hello-ok",

"protocol": 3,

"server": { "version": "…", "connId": "…" },

"features": { "methods": ["…"], "events": ["…"] },

"snapshot": { "…": "…" },

"policy": {

"maxPayload": 26214400,

"maxBufferedBytes": 52428800,

"tickIntervalMs": 15000

}

}

}

```

`server`, `features`, `snapshot`, and `policy` are all required by the schema

(`src/gateway/protocol/schema/frames.ts`). `auth` and `canvasHostUrl` are optional.

When a device token is issued, `hello-ok` also includes:

```json

## Versioning

- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.

- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema/protocol-schemas.ts`.

- Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches.

- Schemas + models are generated from TypeBox definitions:

- `pnpm protocol:gen`

- `pnpm protocol:gen:swift`

- `pnpm protocol:check`

### Client constants

The reference client in `src/gateway/client.ts` uses these defaults. Values are

stable across protocol v3 and are the expected baseline for third-party clients.

| Constant | Default | Source |

| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |

| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |

| Request timeout (per RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |

| Preauth / connect-challenge timeout | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) |

| Initial reconnect backoff | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |

| Max reconnect backoff | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |

| Fast-retry clamp after device-token close | `250` ms | `src/gateway/client.ts` |

| Force-stop grace before `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |

| `stopAndWait()` default timeout | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |

| Default tick interval (pre `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |

| Tick-timeout close | code `4000` when silence exceeds `tickIntervalMs * 2` | `src/gateway/client.ts` |

| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |

The server advertises the effective `policy.tickIntervalMs`, `policy.maxPayload`,

and `policy.maxBufferedBytes` in `hello-ok`; clients should honor those values

rather than the pre-handshake defaults.

## Auth

- Shared-secret gateway auth uses `connect.params.auth.token` or

approved scope set for that token. This preserves read/probe/status access

that was already granted and avoids silently collapsing reconnects to a

narrower implicit admin-only scope.

- Normal connect auth precedence is explicit shared token/password first, then

explicit `deviceToken`, then stored per-device token, then bootstrap token.

- Client-side connect auth assembly (`selectConnectAuth` in

`src/gateway/client.ts`):

- `auth.password` is orthogonal and is always forwarded when set.

- `auth.token` is populated in priority order: explicit shared token first,

then an explicit `deviceToken`, then a stored per-device token (keyed by

`deviceId` + `role`).

- `auth.bootstrapToken` is sent only when none of the above resolved an

`auth.token`. A shared token or any resolved device token suppresses it.

- Auto-promotion of a stored device token on the one-shot

`AUTH_TOKEN_MISMATCH` retry is gated to **trusted endpoints only** —

loopback, or `wss://` with a pinned `tlsFingerprint`. Public `wss://`

without pinning does not qualify.

- Additional `hello-ok.auth.deviceTokens` entries are bootstrap handoff tokens.

Persist them only when the connect used bootstrap auth on a trusted transport

such as `wss://` or loopback/local pairing.