Security and permissions — Документація

Limits for every overlay

An overlay from the Workshop is a web page Racelink did not write, so it is treated as one: it may do what a page needs to draw itself and nothing more.

Its own address: Each overlay runs at an address of its own, apart from Racelink and from every other overlay. It cannot read their storage or their pages.
Its own files: Scripts, styles, fonts and pictures load from the overlay’s package. Scripts from anywhere else never run, even with the internet allowed.
No frames, forms or plugins: An overlay cannot embed other sites, send forms or load plugins.
Racelink and nothing else: Its connections go to the Overlay API on this computer. The internet is closed until the player opens it for the hosts the overlay names.

The Overlay API itself answers only overlays and pages of your own computer during development: a website open in the player’s browser cannot read their telemetry.

What an overlay gets without asking

The telemetry of the game, its own settings, demo data, and the track maps, car logos and flags Racelink ships (assets). That is enough for nearly every overlay.

What the player allows

Anything more private, or outside Racelink, is a permission. The overlay names it in its manifest; the player sees a dialog with a separate checkbox for each, when they add the overlay, and may change the choice later in the overlay’s permissions.

media: What the computer plays: the track, its artist and artwork (system.media). Without it the field is null.
steamMessages: Private messages friends write the player in Steam (steam.chat). Without it access is "denied" and no messages come.
internet: HTTPS and WSS to the hosts listed, up to 20, such as api.example.com or *.example.com. See Data from the internet.

racelink.overlay.json

"permissions": { "media": true, "internet": ["api.example.com"] }

Each permission gives exactly the data it is named for. When Racelink gains a new kind of data, it gets a permission of its own: what a player allowed never grows by itself.
A new version of your overlay that asks for more asks the player again; until they agree, the new permission stays closed.
Demo data is never withheld, so previews look complete.
Racelink’s built-in overlays have every permission.

Check what is allowed

The player may allow any of them, some or none. overlay.permissions says what the overlay may do now, and the permissions event fires when the player changes it. Draw something useful either way.

src/main.ts

const showMusic = (allowed: boolean): void => {
  music.hidden = !allowed;
};
showMusic(overlay.permissions.media);
overlay.on('permissions', (permissions) => showMusic(permissions.media));

src/App.tsx

const [permissions, setPermissions] = useState(overlay.permissions);
useEffect(() => overlay.on('permissions', setPermissions), [overlay]);

return permissions.media ? <NowPlaying media={telemetry.system.media} /> : null;

Your instance and its token

Racelink opens each instance of your overlay with a token in the address. The SDK presents it and gets that instance’s settings and permissions in return. A page opened without a valid token — someone loading your files by hand — gets telemetry and demo data, but no settings and no permissions. You never handle the token yourself.

Building an overlay players trust

Ask for the least: a permission you do not need makes players hesitate.
Say in the Workshop description why you ask for each permission.
No secrets in the package. Anyone can open an overlay from the Workshop and read it, API keys included. Use services meant to be called from a browser.
Telemetry and settings stay on the player’s computer. If your overlay sends anything to a server, say what and why in the description.