The Licence That Proved Nothing: Signing a Key Across Two Languages

For most of sh0's life, a licence key looked like this:

sh0-biz-3f2a1c9e-88d4b077-1e5a9f30

And the server read the plan out of it like this:

rustlet plan = if key.starts_with("sh0-biz-") {
    "business"
} else if key.starts_with("sh0-scl-") {
    "scale"
} else {
    "pro"
};

Read that else again. Any string that was not recognised activated as Pro. hello-world bought you the paid tier. That half was closed a day earlier: unknown strings started returning a 400. But the deeper problem survived the fix, and it is the one worth writing about.

The key proved nothing. It carried a plan, and it carried no evidence that we had issued it. A customer who bought Pro at $19 and wanted Business at $99 did not need to attack anything. They needed to know that Business keys start with sh0-biz-, which is visible in the one they already own.

What a licence has to survive

The obvious fix is a signature. The non-obvious part is the constraint list around it, and the list is what makes the design.

sh0 is self-hosted. That is the entire product. A licence check that requires the internet is a licence check that fails in the exact deployment we sell to. So verification has to work offline, which means the proof travels inside the key and the verifier is the binary.

The key is pasted by a human, into a form, out of an email. It is one line and it has to survive being copied.

The issuer is Node — a SvelteKit site with Prisma. The verifier is Rust. Two languages, two JSON serialisers, two base64 implementations, and no shared code.

And a plan that is taken away has to be taken away for a reason we can defend. A server that loses Pro because a DNS lookup failed is worse than a server that keeps Pro it no longer pays for.

The format

SH0-LIC-1.<base64url(payload JSON)>.<base64url(Ed25519 signature)>

Three parts, a version tag first so a future key rotation is a format bump rather than a migration. The payload carries licence_id, plan, holder, issued_at, and an optional expires_at.

The decision that matters is one line long and easy to get wrong:

The signature covers the base64url payload as written, not the decoded JSON.

If you sign the decoded object, both sides must agree on how to serialise it: key order, whitespace, how a null is emitted, whether non-ASCII is escaped. JSON.stringify in Node and serde_json in Rust do not agree on all of that, and they do not have to. Sign the exact bytes that travel, and the question disappears. It is the same reason JWS signs the encoded segments.

The second decision is about order of operations:

rust// Signed bytes are the payload *as written*, not the decoded JSON.
ring::signature::UnparsedPublicKey::new(&ring::signature::ED25519, pubkey)
    .verify(payload_b64.as_bytes(), &signature)
    .map_err(|_| LicenceError::BadSignature)?;

// Only now is the payload worth reading: everything below this line has
// been proven to come from us.
let payload: LicencePayload = serde_json::from_slice(&payload_json)?;

Verify, then deserialise. Never the other way round. A deserialiser is a parser, a parser is attack surface, and there is no reason to point it at bytes a stranger chose.

Fail closed, and say so

The public key is a constant in the binary. What should happen when that constant is empty — a build where nobody pasted it in?

The tempting answer is "accept everything, it's only a licence." The correct answer is the opposite:

rust/// When the key is not configured in a build, every activation is **refused**
/// -- a licence system that cannot verify must not accept.
const LICENCE_PUBKEY_HEX: &str = "…";

A licence system that cannot verify must not accept. The dashboard says why, in five languages, instead of showing a generic error.

There is a smaller decision hiding in the same file. free is not a signable plan:

rust/// Plans a licence may carry. `free` is not among them: Free is the absence of
/// a licence, and signing one would be a way to *downgrade* a server remotely.
fn known_plan(plan: &str) -> bool {
    matches!(plan, "pro" | "scale" | "business")
}

If we could sign a free licence, we would have built a remote kill switch and handed the ability to anyone who ever gets the signing key. We cannot un-invent that once it exists in the format.

Revocation, and the rule that took the longest to write

A signed licence is valid until it expires. Refunds and chargebacks happen sooner than that, so the server asks sh0.dev once a day whether the licence it holds is still good.

Every failure mode of that question has the same answer:

rust/// Read one revocation answer. Any failure -- DNS, timeout, 500, a body we do
/// not recognise -- is `Unknown`, deliberately: the only thing that removes a
/// plan is an explicit `revoked`.

Timeout: keep the plan. 500: keep the plan. Unparseable body: keep the plan. Unknown licence id: **keep the plan** — that one is server-side, and it is the case a lazy implementation gets wrong. A restored backup, a typo, a licence issued by a different deployment, and suddenly 404 reads as "not valid" and a paying customer loses features. So the endpoint returns 404 and the client treats 404 as "I could not ask."

And one more line, in the log that fires when a plan really is removed:

Licence revoked upstream -- Pro features stop, running applications are untouched

Revocation stops paid features. It does not stop anything that is running. Whatever the commercial dispute, someone's production stays up.

Two languages, one test

Here is the failure this design invites. Both sides pass their own tests. Node signs, Node verifies its own signature, green. Rust verifies, Rust round-trips its own keys, green. Then production issues a key that every server on earth refuses, because one side used standard base64 and the other used base64url, or one signed the JSON and the other signed the encoding.

Nothing in either test suite can see that. So the interop test is a frozen vector: a licence produced by the Node signer, with a throwaway key generated for the purpose, checked into the Rust suite.

rust/// It exists because the two halves are written in different languages: a
/// base64 alphabet, a padding rule or a "sign the JSON rather than the encoded
/// payload" mismatch would pass every test on each side alone and refuse every
/// real licence in production.
#[test]
fn a_licence_signed_by_the_node_issuer_verifies_here() {

The vector carries an accented holder and an ISO timestamp with milliseconds — the two things a JavaScript issuer produces naturally and a Rust parser can be strict about.

What the adversarial review found

The implementation went to a read-only reviewer before the commit. It confirmed the crypto and the ordering. It also found five real defects, and the two worst were nowhere near the cryptography.

The private key was entering the Docker build context. .gitignore covered *.pem — correct, and the git history was clean. .dockerignore did not, and the Dockerfile does COPY . .. The published image was fine; the builder layer was not, and builder layers outlive their build in caches and registry cache exports. A signing key is the one secret that cannot be rotated quietly: replacing it means rebuilding every server in the field.

The delivery email broke on the new key. The old key was 34 characters. The new one is 330, and the template rendered it bold, 16px, centred, with letter-spacing and no word-break. An unbroken base64url string has nowhere to wrap. Gmail and Outlook would have shredded it — in the only channel that delivers the key, and the one our own error message points at: *"Copy it again from your order email."*

A third finding was subtler: expires_at was checked at activation and never again. A server restarts, reloads its plan from the database, and never looks at the date. The date was decorative. It is now re-checked at startup and on every daily pass — with the same rule as revocation, that an unreadable date costs nobody their plan.

Proving it

The tests were 27 green, including seven that drive a real HTTP server to prove that 500, 404, an unreadable body and an unreachable endpoint all leave the plan untouched. Green tests are not proof, though. So:

Two disposable VPS, Debian 12 and Ubuntu 24.04. Fresh install, 50 seconds each. A licence signed by the production key, on the production site, activated through the API on a real server. Plan becomes pro, holder shows. Revoke it upstream. Restart. Five minutes and twenty-five seconds later:

pro active  →  free revoked

And the deployed application answered 200 on every single poll while it happened.

Forged key refused. Tampered payload refused. Old prefix key — sh0-biz-1234-5678-9abc, the exact shape that used to buy Business — refused.

That last one is the whole story in one line.

What did not get built

The licence is still a bearer token. server_id is not populated, so a Business key activated on five servers works on five servers. That is not a regression — the prefix format had the same property — but it is now the widest hole in the model, and the design that closed the forgery hole did not close this one. Writing that down is part of the work.

Activation does not consult the revocation endpoint either. A revoked licence activates and works until the next daily check. That is a deliberate trade: asking the network at activation would contradict "a signed licence activates offline", which is the property the whole design exists to protect. It is an argument, not an oversight — and it belongs in the log next to the tests that pass.