An offline anchor
for online updates.

The scenario we built for.

Picture this: your app polls a download server every morning to see whether a new version is available. The server hands back a JSON blob with a version number, a SHA-256, a URL. The app downloads, verifies the hash, installs. Standard auto-update flow, in production at countless places.

Now picture the server is compromised. The attacker has a shell, can edit files, can swap binaries. What stops them from serving a malicious release that your app gladly installs tomorrow morning?

• Not TLS. The attacker controls the server; the certificate is theirs to use.
• Not the SHA-256. They computed it over the file they crafted. Hash and file agree.
• Not the ClamAV scan. They can edit the scan status field. The JSON says clean because they wrote clean.

The only thing that stops a compromised server from owning every client is a signature the server cannot forge — one whose verification key was decided long before the breach. That is the trust layer.

One key the client pins. One key the server uses. One manifest per release.

The client pins one thing: the root public key. Everything else — which signing keys are valid this month, which versions are current — is delivered over the wire and verified on the way in.

The shape of the signed trust list:

{
  "trust": {
    "trust_version": 1,
    "expires_at": "2028-05-12T20:29:04Z",
    "signed_at": "2026-05-13T20:29:04Z",
    "valid_keys": [
      { "key_id": "5af2613e6e92c56d",
        "pubkey_b64": "mg6FbywzvR…",
        "valid_from": "2026-05-13T20:29:04Z" }
    ],
    "revoked_keys": []
  },
  "signature": "BASE64 — Ed25519 over canonical(trust) with root privkey"
}

And the shape of a release manifest:

{
  "manifest": {
    "project": "breznflow",
    "version": "1.2.3",
    "sha256": "abc123…",
    "size_bytes": 184320,
    "counter": 7,
    "signed_at": "2026-05-14T09:21:33Z",
    "key_id": "5af2613e6e92c56d",
    "url": "/breznflow/v/1.2.3"
  },
  "signature": "BASE64 — Ed25519 over canonical(manifest) with signing privkey"
}

Four attacks, four signed fields.

None of these depend on TLS. The trust layer assumes the transport can be observed, modified, and impersonated. The signature is what carries trust, not the channel.

Rotate the signing key without shipping a client update.

Long-lived secrets are bad operational hygiene. The signing key sits on the server, so a server breach exposes it. The point of the trust layer is that this exposure does not become a client-side disaster.

1. Operator generates a new signing keypair on the server through the admin UI at /admin/signing.
2. Server starts signing new manifests with the new key. The old key is marked inactive but its key_id stays in the trust list — older manifests already signed with it remain verifiable.
3. Operator opens the trust-tool on the laptop, drafts a new trust.json: bumps trust_version, adds the new signing pubkey to valid_keys, optionally moves the old one to revoked_keys if it is to be invalidated.
4. Operator signs the new trust list with the root privkey, uploads it to the server.
5. Clients pick up the new trust list on the next refresh (cache TTL: 5 minutes). From that point, signatures by the new key verify; signatures by revoked keys do not.

No client code change. No app re-release. The pinning never moved — only the list of who is currently allowed to sign on the root's behalf.

What happens after a server breach.

Assume the worst: an attacker pulled the signing privkey out of server memory before you noticed. They can now sign forged manifests at will, as long as the trust list still lists their stolen key as valid. Recovery is a coordinated revocation, done from the laptop.

1. Generate a fresh signing keypair on the server (after the server itself is rebuilt clean — that is its own playbook).
2. Draft a new trust list in the trust-tool: bump trust_version, move the compromised key_id to revoked_keys, add the new pubkey to valid_keys.
3. Sign it with the root privkey on the offline laptop. The root privkey was never on the breached server, so it remains untainted.
4. Upload the new trust list. Clients pick it up within 5 minutes. From that moment, any manifest signed by the stolen key is refused — even if the attacker still holds it.

Replay protection comes for free: trust_version is monotonic, so a client that already saw version 5 will refuse to downgrade to version 4 even if the attacker can resurface an older, signed-by-root copy.

The expires_at field is the dead-man switch. If the operator vanishes and never re-signs, clients freeze rather than keep accepting forever. Default validity: two years. The operator must re-sign before that — a small chore that proves the root privkey is still under control.

A small Python CLI that lives next to the laptop, not the server.

The trust-tool is a single-file CLI in the repo at tools/trust-tool/. It runs on Linux, macOS, and Windows, depends only on standard cryptography primitives, and is what the operator actually touches when rotation, revocation, or initial setup is needed.

The privkey file format is documented in the same directory's README.md. You can decrypt it with any Python script that knows cryptography — the format is not magic, just disciplined.

What the auto-updater actually checks.

The repo ships a reference verifier at tests/integration/test_trust_e2e.py that walks every step of the protocol against the live server using only the raw cryptography library — no Jenni-specific code on the client side. Re-implement it in your language of choice; the protocol is small.

1. On install, pin the root pubkey. Ship it as a 32-byte constant in your app. Never accept it over the network.
2. Daily (or whenever you check for updates), fetch /api/signing/trust. Verify the signature against the pinned root pubkey. Compare trust_version to the largest version you have already accepted; refuse if smaller.
3. Check expires_at. If the trust list has expired, refuse all manifests until a fresh trust list arrives.
4. Fetch the project manifest. Look up the key_id in valid_keys (not revoked_keys). Verify the manifest signature with the pubkey from the trust list.
5. Compare counter to the largest counter you have already accepted for this project. Refuse if smaller-or-equal.
6. Download the ZIP from the signed url. Compute SHA-256. Compare to the signed sha256. Refuse on mismatch.
7. Persist max trust_version and max counter per project. These are the entire client-side state for rollback protection.

That is the whole verification surface. Three signatures, two monotonic counters, one expiration check, one hash comparison. Easy to audit, easy to port, easy to test offline against fixture files.

Things the trust layer doesn't try to be.