Learn More, Plain Version

Plain track. Full link list and technical depth: docs/technical/references.md.

How the "signed job" trick works

Every job gets run through a math function (called HMAC-SHA256) together with a secret key that only the house PCs know. The result is a short string — a "signature" — that's basically impossible to fake without knowing the key, but trivially easy to check if you do know it. The listener does that same math on every job it receives and checks the answer matches. If it doesn't, the job is refused.

Learn more about the underlying idea: what is HMAC? — the short version is "a way to prove a message came from someone who holds a shared secret, and wasn't altered in transit," which is exactly what's needed here since the OneDrive folder the jobs travel through isn't trusted on its own.

One subtlety worth knowing: when the listener checks a signature, it doesn't just compare the two strings directly — comparing byte by byte and stopping at the first mismatch would let an attacker slowly guess the right answer by timing how long the check takes to fail. The code uses a comparison that always takes the same amount of time no matter how wrong the guess is. This is a well-known best practice, not something unique to this project — see timing attacks for why it matters.

Why the "how heavy is this job" label is signed too

Imagine someone could drop files into the shared job folder but didn't have the secret key. They could still write a job and just claim it was "harmless" so it slides past the "don't disturb me while gaming" check. Signing that label closes exactly that door — the label becomes part of what gets checked for tampering, the same as everything else in the job.

Why there's a version number that ISN'T signed

Software changes over time, and one house PC might be running slightly older code than another. The system needs a way to say "you're speaking a version I don't understand yet" without that message itself looking like a forged or tampered job. So there's a small version-number tag on every job that's checked before the signature — if it's too new, the listener says so plainly ("update this box") instead of just failing the signature check and leaving you to guess why.

Why the "are you busy" check never remembers anything

The system that decides "should this job actually run right now" always looks at what's happening at that exact instant — never a five-second-old memory of what was happening. That's on purpose: a stale memory could say "still gaming" when you've actually stopped, or worse, "not gaming" for a few seconds right after you've started (before the memory catches up), which is exactly the moment a heavy job could sneak in and start disrupting you. Checking fresh every time closes that gap entirely, at the cost of doing a little more work per job — a trade worth making here.

There IS a separate, slower-updating status (refreshed every few seconds) used only for a dashboard-style "is this PC busy" display elsewhere — that one deliberately waits about a minute and a half after gaming stops (two minutes after streaming stops) before flipping back to "free," so the dashboard doesn't flicker for a half-second alt-tab. That's a display nicety; it never touches the actual "can this job run" decision.

How it knows you're gaming

It reads a small piece of information Steam itself keeps track of on your PC — basically a note that says "here's the ID number of the game currently running, or zero if nothing is." It's the same kind of lightweight check overlay tools and streaming software already use to know when a game has launched. It's not perfect — a game that isn't distributed through Steam and isn't on a manually-kept allow list won't be detected yet — but that gap is written down as a known limitation rather than a silent one.