The Proof Is the Key, Not Its Hash: Renewing a Signed Licence Without a Migration

sh0 sells monthly subscriptions and, until recently, issued perpetual licences. One month at $19 bought the Pro plan forever. The fix everyone reaches for first is "put an expiry date in the key", and we did: the licence is an Ed25519-signed document carrying paid_through and expires_at. Then we left the feature switched off, because a dated key with no renewal path is worse than the leak. It cuts off a customer on day 38 while Stripe is happily taking their money.

This post is about the missing half: how a server that never phones home except once a day gets its renewed key without anyone pasting anything, and why the design the session prompt suggested would have broken at the exact moment it was needed.

The three pieces

Renewal needs three things that did not exist:

1. An endpoint on the website where a server can fetch the current key for a licence it holds.
2. A Stripe webhook handler for invoice.paid that re-signs the licence for the new period.
3. Code in the sh0 binary that fetches, verifies, and swaps the stored key.

Pieces 2 and 3 are plumbing. Piece 1 is where the design decision lives, because the endpoint serves key material. The existing GET /api/licences/:id/status is public on purpose: it returns nothing but a status, and a licence id travels in cleartext in every daily call, so anybody who learns one must not be able to turn it into a key.

The design the prompt suggested, and why it fails

The prompt written for this session proposed the obvious proof of possession: the server already stores a SHA-256 of its key, so send that hash in a header and let the site compare it with the hash of the key it has on file.

Walk through a renewal with that design. Day 30: Stripe renews, the webhook re-signs the licence, the site now stores key N+1. Day 31: the server wakes up for its daily check holding key N. It sends hash(N). The site computes hash(N+1). Mismatch. 401. The server keeps key N, which expires on day 37, and on day 38 a paying customer loses their plan.

The hash stops matching at precisely the instant the endpoint exists to serve. Fixing it means the site must remember every hash it ever issued for a licence, which is a Prisma migration and a history table. A single "previous hash" column is not enough either: a server that was offline across two billing cycles holds key N when the site has N+2, and it is locked out for good.

What decided it: the raw key was already there

While replaying the prompt's claims against the code, one line in the activation handler settled the question:

rust// Store raw key for cloud registration
let _ = sh0_db::Setting::set(&pool, "license_key_raw", &raw_key);

Written months ago for a feature that never read it back. Every activated server in the field has its raw key on disk. So the proof of possession can be the key itself: the server sends its current signed document as a bearer token, and the site verifies its own Ed25519 signature over it and checks that the licence_id inside matches the URL.

This is stateless. No migration, no history table, and it works for every server activated before the endpoint existed. A key issued a year ago is still a document only we could have signed, so a server that missed twelve renewals is served exactly like one that asks every day.

Two deliberate choices follow from it. The site does not check expiry on the presented key, because the key is being presented precisely because it is expiring. And a revoked licence gets a 403 with no key material, because the status endpoint already told the server and this endpoint must not become a second opinion.

On the wire, the key travels over TLS to the issuer that already holds it. The hash design would have sent a bearer credential too, just a shorter one. No security was traded for the simplicity.

The server side has its own trap

The sh0 daily pass used to load the active licence. That is right for enforcement and wrong for renewal: the licence most in need of a renewed key is the one the expiry sweep already retired. A server offline across its grace window, coming back to a paid-up subscription, would have stayed on Free forever because the pass never looked at an expired row.

The pass now reads the latest licence regardless of status, retires it if expired, tries renewal, and only then asks about revocation. Revoked and replaced rows are final and are never touched.

Accepting a fetched key follows the same rule as activation: signature first, before anything in the payload is read. Then the id must match, and the document must be issued strictly after the one we hold. That last check refuses a replayed answer and a site bug that re-serves an older document. Every refusal keeps the key we have, the same way every network failure keeps the plan.

Three end-to-end tests drive the whole pass against an in-memory SQLite pool and a local HTTP stub signing with an ephemeral keypair: an expired licence comes back active with the new key stored; a document for another licence leaves it retired; a stale raw key left behind by an earlier licence is never presented.

What did not ship, and then what proved it

The session that wrote the three pieces ended with the flag still off. The prompt said to turn it on "only when the three pieces are proven together", and the register rule is that "fixed in code" is not a state: an item is proven, or it is open. Three pieces and a dozen green tests, none of them run on a real target, is exactly the situation that rule exists for. So the issue stayed open, with a Preuve due: line naming the observation, the target and what was missing.

What was missing was a build. The next session, the same day, ran the campaign in the order that matters. First the release candidate went onto the witness server, with the public latest release left untouched. Only then was the flag switched on at the site, so that no server in the field could receive a dated key before it had the code to renew one. Then the invoice.paid webhook was subscribed and read back.

The plan had assumed a Stripe test clock. It did not survive contact: the site runs on live keys, and test mode never reaches it. The campaign used the real checkout instead, with a zero-dollar subscription, and forced the next billing cycle by moving the trial end a few minutes ahead. Stripe issued a real subscription_cycle invoice, it was paid at zero, and invoice.paid fired.

The site re-signed the licence on its own: a new key, different byte for byte from the first, dated to the end of the new period plus the grace week. The server was restarted rather than left to wait a day for its next pass, and a few minutes later its log said:

INFO sh0_api::licence: Licence renewed -- new key stored, no action was needed from anyone

The server now holds the new document, and the raw key on disk is the new key, byte for byte. The counter-case was played on a second licence: the subscription was cancelled, the site revoked the licence within seconds, and at its next pass the server logged Licence revoked upstream -- Pro features stop, running applications are untouched and fell back to Free.

One thing the campaign could not play live: a card that fails. Test cards need test mode, which the site does not run. That path is covered by the proof of the expiry sweep on another issue and by unit tests, and the register says so instead of pretending otherwise.

The issue closed on the day it was written up, on an observation with a timestamp, not on the code. The witness server keeps its zero-dollar subscription and stays activated, so the loop is now exercised every month through the real path. That is the point of the rule: the article you have just read could have ended at "the code is written", and it would have been the less interesting half.