Ed25519 Entitlements for License Validation

Most licensing systems are built around one question: does this key exist in the database? That question matters, but it is incomplete for a desktop product. A local app has to make authorization decisions while it is running, while it is refreshing state in the background, and sometimes while the network is unreliable.

If the website simply returned an unsigned response that said valid: true, the desktop would have to trust the transport and the local cache forever. That is not a strong enough boundary for a commercial desktop app. The better pattern is to let the server do the authoritative database work, then sign the result so the client can verify it without turning every local decision into a fresh database call.

That is the role of KeyRing's entitlement envelope. It turns a server-side licensing decision into a compact, verifiable artifact.

The validation request is intentionally narrow. The desktop sends the license key and its machine ID. It does not send prompts, provider API keys, conversation content, generated files, or AI responses.

On the website, the license validation route applies multiple checks before anything is signed. It rate-limits by IP and by license-key plus machine-ID pair. It rejects invalid key formats. It looks up the license, checks that the license is active, checks expiry, verifies subscription state where a subscription exists, and enforces the machine binding rule.

If the license has not been bound yet, the first successful validation binds it to that machine. If it is already bound to another machine, validation fails and the user has to contact support to transfer it. That is the part that prevents a paid license from becoming a shared string passed around between installs.

Only after those checks pass does the website build and sign the entitlement payload.

The signed payload includes the issuer and audience so the desktop knows who created the entitlement and who it was meant for. It includes the license ID, user ID, tier, machine ID, billing or license period boundaries, issued-at timestamp, unique jti, and payload version.

It also includes entitlement_expires_at. In the current implementation, this is a short-lived 48-hour window from signing time. The desktop refreshes entitlement state on a regular cycle instead of relying on a long-lived token that remains useful for an entire billing period.

The envelope also includes a key ID, the algorithm name Ed25519, the payload, and the base64url-encoded signature. The desktop public-key verifier uses the key ID to select a trusted public key and verify the signature over canonical JSON.

On the desktop side, KeyRing loads the trusted entitlement public keys from configuration injected at startup. When an entitlement is present, the verifier canonicalizes the payload, verifies the Ed25519 signature, and then checks the claims.

Signature verification is only the first gate. A valid signature over the wrong audience is still rejected. A valid signature for a different machine is rejected. A valid signature that has expired is rejected. The local gate is deliberately specific because the desktop is the enforcement point for provider calls.

That enforcement matters because KeyRing is local-first. The app is not relaying prompts through a KeyRing server that could enforce every request centrally. The desktop runtime needs a local authorization artifact it can verify without putting KeyRing in the user's AI data path.

Ed25519 is a strong fit for this kind of entitlement because the trust direction is one-way. The website signs. The desktop verifies. The desktop does not need the private key and should never have it.

That also makes key rotation practical. The envelope includes a key ID. The desktop has a trusted public-key map. When KeyRing rotates signing keys, the validation service can sign with a new key ID and the desktop can verify against the corresponding public key once that key is trusted in the runtime configuration.

The important product outcome is simple: a user cannot edit their local entitlement from Basic to Pro, swap the machine ID, or extend the expiry without invalidating the signature.

The point of a signed entitlement is not just to make the happy path cleaner. It also makes failure behavior explicit. If the signature fails, the key ID is unknown, issuer or audience is wrong, the machine binding does not match, or the entitlement has expired, the verifier returns a structured failure reason.

The desktop enforcement layer uses that state before protected provider calls. In production enforcement mode, the application requires a currently valid signed entitlement for those workflows. That keeps local-first architecture from becoming local-only trust.

This is the balance KeyRing is aiming for: the website handles commercial trust, the desktop handles user workflow, and AI traffic still goes directly from the user's machine to the provider.