Research › How GroupLab is built
How GroupLab updates itself safely
On this page
GroupLab project. Researched and written with Claude. Testing and data collection by the developer. Written 2026-09-22; the data is from 2026-09-22.
No figure: This is about what happens between a download and an install, which has no picture. The update bar itself is in the tour.
What we found
A signature that covers a rebuilt copy of a file rather than the file itself breaks the day you add a field. That shipped, and every installed build refused every update until it was reverted.
How sure we are
This describes the code and a fault that really happened, with the commit that reverted it. It is not a security audit.
What an updater has to get right#
A program that downloads and runs code on your machine is the most dangerous thing in it. GroupLab checks three things before it installs anything.
The manifest is signed. Each build publishes a small file saying what the newest version is, and for every file its name, size and SHA-256. That file carries a signature, and GroupLab refuses a manifest whose signature does not verify.
Every download is hashed. A file whose SHA-256 does not match the manifest is refused, whatever the manifest said.
Both refusals are loud. They say what was wrong in plain words rather than failing quietly, because an updater that silently stops updating is an updater you find out about in six months.
The bug worth writing about#
The first version of the signature covered the manifest's meaning rather than its bytes. GroupLab read the file into a record and wrote that record back out in a canonical form, then checked those bytes against the signature.
That is a tempting design. It survives reformatting, different line endings, and a server that rewrites whitespace.
It has one fatal property: a build that does not know about a field drops it on the way back out. The bytes it checks are then not the bytes that were signed.
So when one field was added to the manifest, and a nightly published with it, every build already on somebody's machine read the new manifest, serialized it back without the field it had never heard of, compared the result against the signature, and refused:
update.check result=Refused refusal=BadSignature
Every installed build lost the ability to update itself, silently, in a way that looked exactly like "no update available" if you were not reading the log. The change was reverted the same night.
What replaced it#
The signature now covers the exact bytes that were published. The manifest carries its payload as an opaque blob; GroupLab verifies the signature over those bytes as received, and only then parses them. Fields it does not recognize are ignored rather than dropped and re-serialized.
That is the whole lesson, and it is not specific to this program: sign what you send, not what you understood. A verification step that involves rebuilding the thing you are verifying is not a verification step.
The old format is still published alongside the new one, for as long as any build that reads only the old one might still be installed, with the date it can be retired written down.
What GroupLab cannot promise#
If an update installs and then will not start, there is no automatic roll back.
The installer replaces the program folder in place. The previous build's files are gone once it has run. There is no second copy kept aside.
This is written down plainly rather than glossed, because the alternative, a second full copy of the program on disk, was considered and costs more than the risk is worth at present. The trigger for revisiting it is written down too: the first of a public beta opening, or a second person testing. If either happens, it gets built.
What you get instead is the previous version's installer, still downloadable, and instructions for using it.
No secret in the client#
There is no authentication on any of this, and no API key.
Any secret compiled into an open source program is public the moment it ships. A key in the installer would provide the feeling of security without the substance, and this project would rather say plainly that the protection is the signature and the hash, both of which work fine in the open.
What the tests hold#
- A manifest with extra unknown fields still verifies and parses on a build that has never heard of them. That is the exact case that broke before.
- A changed byte anywhere in the payload is refused.
- The old manifest's signed bytes are held against a recorded string, so they cannot drift by accident.
- The updater of an older published build, pinned at its real code, is run against freshly generated manifests and must still accept an update.
That last one exists because the fault was not in the new code. It was in the old code's ability to read what the new code produced, and no test that only runs the current version can see it.
On Android, one more check#
GroupLab Dev, the Android build installed from its APK, updates itself from the same signed manifest (entry 288). An Android package adds something the desktop installer does not have: the key it was signed with. Android refuses to install an update signed by anybody but the signer of the copy already there, and GroupLab checks that itself before handing the file over, as well as the SHA-256. A file that fails either check is deleted and never installed, so nobody is asked to install something that would then fail.
It never installs in the middle of work. Replacing an Android application closes it, so an automatic update waits until the camera is closed, no sheet is being read, nothing is unsaved, and GroupLab has left the screen. The copy from Google Play has none of this code at all: the updater is a separate build, the project refuses to build the Google Play package with it, and the nightly checks that package's manifest to make sure.
What this means#
You can leave updates on. The manifest is signed, and GroupLab refuses a download whose hashes do not match it, so the worst a tampered file can do is stop the update rather than install itself. Nothing is applied without you saying so.
Check the notes before you take a build, not after. The notes shown in the update bar are the same ones on the releases page, and they are written to be read by somebody deciding whether to install rather than by somebody who already has.
If an update fails, the old version is still the one you are running. That is deliberate. A failed update is an inconvenience; a half-applied one is a program that does not start, and this project would rather you be inconvenienced.
Sources#
- What is signed, what is checked, and what cannot be promised:
docs/UPDATES.md. - The failure and its fix:
docs/NOTES-FROM-PLANNING.md, entries 138 and 139.