Zero-trust screen pairing: security patterns for unattended hardware

Pairing is the weakest moment in a screen's life, because it is the only one where a short code is the whole proof of identity. A code that stays valid for days, or that can be redeemed twice, is a code somebody else can claim — and a screen can only ever belong to one workspace, so a claim is a takeover.

Pairing codes here are six characters drawn from an alphabet without the easily confused letters and digits, they expire, and redeeming one is a single step: the first claim wins and the code is spent. If nobody claims it in time, the player shows a new one.

The player displays a code and waits. Whoever is signed in to the workspace enters it, and the server issues a key for that one screen. The device collects the key through the code and that copy is deleted as soon as it has been handed over; only a hash of it is kept for later checks.

On the device that key goes into platform secure storage — Android Keystore or the iOS Keychain — rather than a plain preferences file, and it is what every later sync, heartbeat, and playback report is authenticated with.

// Redeeming a pairing code. The first claim wins, and the key it mints is
// stored hashed — see devices.service#hashApiKey.
export async function redeemPairingCode(code: string, tenantId: string) {
  return db.transaction(async (tx) => {
    const pairingCode = await pairingCodesRepository.findByCodeForUpdate(code, tx);

    if (!pairingCode) throw new PairingCodeNotFoundError();
    if (pairingCode.expiresAt.getTime() < Date.now()) {
      throw new PairingCodeExpiredError();
    }
    if (pairingCode.status !== "pending") throw new PairingCodeSpentError();

    const device = await devicesService.createDevice(tenantId, tx);
    await pairingCodesRepository.markRedeemed(pairingCode.id, device.id, tx);

    return { deviceId: device.id, apiKey: device.apiKeyPlaintext };
  });
}

Hardware gets moved, replaced, or stolen, and when that happens the question is not whether the screen is online but whether its key should still work. Rotating a screen's key mints a new one and invalidates the old immediately: the previous hash simply stops matching.

The screen finds out on its next sync or heartbeat, when the request comes back unauthorised, and drops back to pairing so somebody with a workspace account can claim it deliberately. Deleting a screen also removes it from the schedules that targeted it, so nothing keeps publishing to a box that is gone.