Skip to content
Ball2DDocs

Operate

Security model

What the SDK protects, what the service enforces, and what neither can promise.

A Ball2D host is trusted code running on your machine. This page describes where authority lives, so you can decide what to trust in your own room logic.

Authority

  • The service decides admission. Ball2D checks your API key, its expiry and revocation, and your account's room limits on its own servers. Nothing a client sends, including headers that claim to be an official SDK, grants access.
  • The host decides the match. Your server runs the simulation. Players send inputs; they cannot set scores, positions or other players' state.
  • Nobody inherits a room. If the host goes away, the room closes. A player never becomes the host.

Your API key

The key is a credential for your account. The SDK sends it only to the configured service origin in an Authorization header, requires HTTPS for any origin other than your own machine, and refuses redirects to another origin, so the key cannot be forwarded elsewhere. It never appears in player messages or room links. See Create an API key.

Player identity and names

Player names are chosen by players and are display text, not identities. A name that matches an account handle does not prove the player owns that account. Use player IDs for your logic and treat names as untrusted input: they can contain anything a person can type.

Chat is literal text. HTML, CSS and markup in messages or announcements are never interpreted, and players cannot make their messages look like a host announcement.

Direct messages

Direct messages between players are routed by the host, which can read them. They are not end-to-end encrypted. Your room can inspect and suppress them with onPlayerDirectChat.

What the SDK cannot promise

  • The runtime can be inspected. The package ships compiled JavaScript and WebAssembly without source maps or internal declarations. Anyone who installs it can still read and modify what runs on their machine. Do not rely on the package to hide secrets.
  • Revocation is not a remote kill switch. Revoking a key closes its rooms through the service and stops new admissions, but a modified host and its connected players could keep exchanging packets directly until that host stops.
  • Your room code is trusted. The SDK runs your callbacks in your process. It is not a sandbox for untrusted plugins.

Report a vulnerability

Report security issues privately through GitHub security advisories. Leave API keys, personal data and private room links out of reports.