# Verify plays, batches and uptime

What a play, a batch and an uptime statement prove, and how to check Mestra's signatures offline with its public keys.

Mestra signs three things you can check without calling Mestra: the receipt on a play's file, the receipt on a batch of plays, and a screen's uptime statement for a day. All three use the same published keys. This page says what each proves, what it doesn't, and how to check it.

The public keys are at `https://app.withmestra.com/.well-known/mestra-receipt-keys.json`. No sign-in is needed and the document can be cached.

```json
{"keys": [{"keyId": "2026-11", "algorithm": "Ed25519", "publicKey": "…", "validFrom": "2026-11-01T00:00:00Z", "retiredAt": "2027-02-01T00:00:00Z", "signing": false}]}
```

`publicKey` is the 32-byte Ed25519 public key, base64url without padding. Old keys stay listed with `signing` false and a `retiredAt`, so a signature made before a key was replaced still checks. The key in use has no `retiredAt`.

## What a play proves

A play row is the screen's own report that it showed the file with this `sha256`, starting at `playedAt` in `zone`, for `durationMs`. Mestra stores it as sent, after checking that the entry is the screen's and the file is one of the organisation's files.

**The play itself is not signed.** It is the screen's claim, sent over its signed-in connection. Nothing proves the screen really showed the file.

A play's `check.state` is one of:

| State       | Meaning                                                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signed`    | The file passed its checks and has a receipt, which the row includes. Everything below applies.                                                     |
| `checked`   | The file passed a check made before receipts began, with no rule set, or while the server had no signing key. There is nothing to verify offline.   |
| `unchecked` | No passing check of that exact file was found when the play arrived. The play is shown, never hidden. Treat it as unapproved until you have looked. |

## Check a signature

All three signed things are checked the same way, with a different prefix on the signed message.

1. Find the key whose `keyId` equals the signed object's. No such key: reject. The object's `createdAt` must fall in the key's window, from `validFrom` up to but not including `retiredAt`.
2. Remove `signature` from the object and canonicalize what is left with RFC 8785 (JSON Canonicalization Scheme): members sorted, no spaces, numbers and strings written the one standard way. The order and spacing of the object as sent never matter.
3. The signed message is the prefix line below, a newline, then those bytes. Verify the Ed25519 signature over it. The signature is base64url with no padding and no line breaks.

| What                                         | Prefix             |
| -------------------------------------------- | ------------------ |
| A file's receipt (`check.receipt` on a play) | `mestra-receipt/1` |
| A batch of plays (`batch.receipt`)           | `mestra-plays/1`   |
| An uptime statement (`receipt` on a day)     | `mestra-uptime-v1` |

Each prefix is different, so a signature for one kind of document never passes as another.

## Check a play's file receipt

A play's `check.receipt` is Mestra's signature over a statement that this exact file passed rule-set version `ruleSetVersionId` for organisation `orgId`. It proves the file's approval, not the play. It is the check Mestra found when the play arrived, so its `createdAt` can be later than `playedAt`. A valid receipt does not show the file was approved before it aired.

```json
{
  "version": 1,
  "keyId": "2026-11",
  "orgId": "…",
  "jobId": "…",
  "formatKey": "square",
  "fileSha256": "…",
  "ruleSetVersionId": "…",
  "passed": true,
  "checksDigest": "…",
  "createdAt": "2026-11-07T03:04:05.000000Z",
  "signature": "…"
}
```

1. `play.sha256` must equal `play.check.receipt.fileSha256`.
2. Check the signature as above, with the prefix `mestra-receipt/1`.
3. Pin what you trust. Check that `orgId` is your organisation and that `ruleSetVersionId` is a version you accept. A valid signature on another organisation's or another version's receipt proves nothing about yours.
4. If you hold the file, its SHA-256 must equal `play.sha256`.

If any step fails, treat the row as unverified. `checksDigest` is the hex SHA-256 of the canonical form of the checks the file was measured with, so you can also tie a receipt to checks you hold.

## Check a batch

Each play names the batch it arrived in: `batch` (null for a play stored before batches), whose `id` names it. [`GET /player/plays/batches/{id}`](https://withmestra.com/docs/api/plays/#getmestraplaybatch) returns `{batch, plays}`: the batch's own plays and `batch.receipt`. A batch shows once its plays do. Before then, for another organisation's batch, or for a screen outside a limited key's scope, it answers `404` with the code `unknown_batch`. A batch whose booking was deleted afterwards can no longer be rebuilt, because deleting a booking removes its plays: it answers `404` with the code `batch_incomplete`. That is not tampering.

**What it proves.** Mestra received exactly these plays from this screen at this time and has not changed them since. It doesn't prove anyone saw the content, or that the screen's report is true. Together with the file receipt it shows an approved file, reported played by this screen, kept unaltered since. The play itself is still the screen's claim.

A batch stored while the server had no signing key has `batch.signed` false and `batch.receipt` null. The plays are listed and there is nothing to verify offline.

To check one:

1. Fetch the batch.
2. Build a line from each row in `plays`, with exactly these members and the row's values: `id`, `screenId`, `publicationId`, `itemId`, `entryId`, `sha256`, `playedAtLocal`, `zone`, `durationMs`, and `outOfStep` only when it is true (leave it out when the row has none or false).
3. Recompute the digest. Write each line in canonical JSON (RFC 8785), order the lines by `id`, join them with a newline and take the hex SHA-256. It must equal `batch.receipt.playsDigest`, and `batch.receipt.plays` must equal the number of rows.
4. Check the signature, with the prefix `mestra-plays/1`. The receipt has exactly ten members: `version`, `keyId`, `orgId`, `screenId`, `batchId`, `receivedAt`, `plays`, `playsDigest`, `createdAt` and `signature`. One more or fewer is invalid.
5. Pin the identity. `receipt.orgId` is your organisation, `receipt.screenId` is the screen you expect, `receipt.batchId` is the batch you asked for, and every row's `screenId` is that screen.

If any step fails, treat the batch as unverified. If you don't trust a play, compare it with what the screen reported, not only with Mestra's copy.

## Check an uptime statement

[`GET /player/devices/{id}/uptime`](https://withmestra.com/docs/api/uptime/#getmestrascreenuptime) gives each closed day of a screen with a `receipt`: Mestra's signed statement of that day.

```json
{"version": 1, "keyId": "...", "kind": "uptime", "orgId": "...", "deviceId": "...",
 "day": "2027-09-01", "zone": "Australia/Sydney", "revision": 1, "countedS": 86400, "downS": 600,
 "sitePowerS": 0, "holdingS": 0, "standbyS": 0, "silentS": 0, "offlineUnverifiedS": 0, "disputedMinutes": 0, "lateMinutes": 0,
 "firstHash": "...", "lastHash": "...", "signedBy": "tpm",
 "createdAt": "2027-09-02T00:01:00.000000Z", "signature": "..."}
```

1. Check the signature, with the prefix `mestra-uptime-v1`.
2. Pin `kind` to `uptime`, `orgId` to your organisation and `deviceId` to the screen you mean.
3. To know you hold the latest statement, fetch the day from the API and compare `revision`. A day is signed again, with a higher `revision` and a later `createdAt`, when an hour that belongs to it arrives late. An older statement stays valid as a signature.

**What it says.** On `day`, in `zone`, Mestra counted `countedS` seconds for the screen, of which `downS` it wasn't showing what it should, and `sitePowerS` of those were lost to the site's power. Uptime is (`countedS` - `downS`) / `countedS`. Excluding site power it is (`countedS` - `downS`) / (`countedS` - `sitePowerS`). Totals over days, sites or the organisation add the seconds first and divide once. They are never an average of percentages.

| Field                   | Meaning                                                                                                                                                                                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `holdingS`              | The part of `downS` the panel spent showing the stop show from its own storage while it restarted.                                                                                                                                                                                                                     |
| `standbyS`              | Time the standby player showed a live item. It is counted as up.                                                                                                                                                                                                                                                       |
| `silentS`               | The part of `downS` that comes from Mestra's own record, not the screen's: time Mestra heard nothing from the screen and the screen sent no record for, such as a PC off for days. Time the screen later sends signed hours for is never counted here, so an outage on Mestra's side doesn't count against a screen.   |
| `offlineUnverifiedS`    | Content the screen claimed while Mestra heard nothing from it. It counts as up and rests on the screen's own signed record. It is reported apart.                                                                                                                                                                      |
| `disputedMinutes`       | Minutes whose record contradicts what Mestra held (the screen reported content while it was stopped or halted, or called itself halted without a halt Mestra saw), or whose hour was rewritten or didn't link into the chain. A disputed minute is never up: it is in `countedS` and `downS` whatever the screen said. |
| `lateMinutes`           | Minutes that arrived more than two hours after their hour ended: the screen's own report of time it was offline, reported apart, and no longer a dispute.                                                                                                                                                              |
| `signedBy`              | Which device key signed the hours the day rests on: `tpm` when every hour was signed by a key made in the screen's TPM and proven by it, `software` when every hour was signed but not all by a TPM key. Absent when an hour was unsigned.                                                                             |
| `firstHash`, `lastHash` | The hashes of the first and last hourly record the day rests on. Both are empty for a day that rests only on Mestra's record.                                                                                                                                                                                          |

Each hour is sealed by the screen into a hash chain that Mestra checks when it arrives.

**What it doesn't prove.** The minutes are the screen's own report. Mestra checks the chain and the seal but can't see the panel. A stolen device key, or a wrongly set clock, can send a clean chain.
