What Is Inside a Keylight Lease: The Ed25519 Format Explained

Originally published on the Keylight blog.

Most license systems answer "is this key valid?" by asking a server. Keylight answers it with math, locally, in milliseconds — because the license itself is a signed document your app can verify without a network call. Understanding what is inside that document, and why the signature protects it, is the fastest way to understand how Keylight's security model holds together.

Why signed leases beat opaque license strings + database lookups

The classic licensing approach is a lookup: the customer enters a key, your server checks it against a database, and the server says yes or no. An opaque license string — just a token or a checksum-passing sequence — means nothing by itself. The string carries no self-describing information; the app has to phone home to learn what it is allowed to do.

A signed lease flips the model. The lease is a self-describing document: it encodes who the customer is, which product they purchased, which features they have, and when the license expires. The Ed25519 signature over the document is proof that Keylight's server minted it for exactly those values. Your app ships with the public key baked into the binary and verifies the signature locally — no server call, no round-trip, no database to query or spoof.

The customer holds the document, but they cannot change what it says. The validity no longer lives in whether a server recognizes a token; it lives in a signature only Keylight's private key can produce. This is why the lease works offline, survives network outages, and still enforces your commercial limits correctly. For a broader introduction to why this model replaced opaque license strings, see how license keys work for desktop apps.

The lease payload, field by field

The canonical lease the SDK exposes after verification looks like this:

{
  "id": "lk_01hx9z4bqncktjvx6a2r3p8wy",
  "customerId": "cus_Qk3mN9vTpLx2Zr",
  "productId": "prod_macos_pro",
  "activationLimit": 3,
  "activationCount": 1,
  "features": ["pro", "export"],
  "issuedAt": "2026-05-15T09:12:00Z",
  "expiresAt": null,
  "revoked": false,
  "sig": "MEUCIQDkP3...base64url...=="
}

Every field carries specific meaning that the SDK reads and enforces:

id — a unique, immutable lease identifier. This is what Keylight uses to look up the lease server-side during revalidation. It never changes after issuance.

customerId — the Keylight customer record this lease was issued to, set at mint time from the Stripe payment. Ties the lease to a specific purchase.

productId — which product and tier this lease covers. If you have multiple products or multiple plans, the SDK reads this to know which entitlement bucket applies.

activationLimit — the maximum number of concurrent device activations. A standard license might allow 3; an enterprise tier might allow unlimited (represented as a very high number). This value is set at issuance based on the product tier purchased.

activationCount — the current number of active devices as of the last server sync. Keylight tracks this server-side and updates it on each activation and deactivation. This is a read-only tracking field exposed to your app via the lease object; it is not checked by LeaseVerifier.verify. The activation cap is enforced server-side when a device calls /activate — the verifier only checks signature, key ID, and expiry.

features — an array of entitlement strings the app reads to decide which capabilities to unlock. Your app checks whether "pro" or "export" appears here before enabling those features. This is the mechanism that lets you sell different tiers from a single binary. The strings are stored sorted so that the client and server always reconstruct an identical payload regardless of insertion order.

issuedAt — the ISO timestamp when the lease was minted. Used internally for clock-drift calculations and audit logging.

expiresAt — null for a lifetime license; an ISO timestamp for subscription or time-limited leases. The SDK rejects a lease that has expired beyond its skew tolerance window, even if the signature is valid.

revoked — a boolean flag set to true when a refund or chargeback is processed. On the next revalidation, the SDK picks this up and transitions the app to an invalid state. Because verification is offline-first, revocation is not instantaneous — a customer with no network access keeps using their cached lease until the app revalidates. This is the honest tradeoff: instant revocation would require a server call on every launch, which breaks offline usage.

sig — the Ed25519 signature over a compact wire payload, not over the JSON above. The JSON is the lease object as the SDK exposes it to your app. Internally, signing operates on a more compact wire payload — a pipe-delimited string with eight positional fields: v3|kid|licenseKeyHash|instanceId|issuedAt|expiresAt|status|entitlements. This is what the Ed25519 signature actually covers; the SDK reconstructs and verifies that string before exposing the structured lease to your code.

The fields covered by the signature are kid, licenseKeyHash, instanceId, issuedAt (integer seconds), expiresAt (integer seconds), status, and entitlements (sorted, comma-joined). Modifying any of them produces a signature mismatch and the lease is rejected immediately. Fields like customerId, productId, activationLimit, and activationCount are part of the API/customer-facing model but are not positional fields in the signed wire payload.

For a full treatment of how offline validation uses this structure, see how offline license validation works.

How Ed25519 signing protects every field

Ed25519 is a public-key signature algorithm. The important property for licensing is this: given only the public key (which your app ships with), it is computationally infeasible to produce a valid signature. The public key can verify signatures but cannot generate them.

Keylight's servers hold the private key — it never leaves Keylight's infrastructure. Your app ships with the matching public key baked into the binary. An attacker who extracts the public key from your binary still cannot mint a valid lease: they would need the private key to produce a signature the public key accepts, and the math does not help them get there. Embedding the public key in the app is safe by design.

Why Ed25519 over RSA? Three practical reasons. Ed25519 signatures are about 88 bytes; RSA-2048 signatures are around 344 bytes. Ed25519 verification is faster — relevant when your app verifies the lease on every launch. And Ed25519 has no parameter choices that can be gotten subtly wrong the way RSA key generation can. For desktop licensing where verification happens repeatedly and binary size matters, these add up.

What tampering does in practice: the SDK reconstructs the v3 pipe-delimited string from the lease's kid, licenseKeyHash, instanceId, issuedAt, expiresAt, status, and sorted-joined entitlements fields, then calls isValidSignature against the decoded sig. If any of those eight fields was changed after signing — even one character — the reconstructed string differs from the one that was signed, the check fails, and the SDK rejects the lease. There is no partial match, no tolerance for minor edits. The lease is either intact or it is rejected.

On the wire, Keylight uses the v3 pipe-delimited format. The SDK parses that format, derives the canonical payload string, and verifies the signature before populating the structured lease object. Your code never sees the raw wire format; it only sees a verified, structured lease — or a verification failure.

What the SDK does on verification, and what it deliberately does not do

LeaseVerifier.verify is the function the SDK calls on every lease read. It is explicit about its scope. Here is what it checks:

1. Signature validity — reconstructs the v3 pipe-delimited payload and verifies the Ed25519 signature against the trusted public key for this tenant. A lease with a missing or empty signature is rejected immediately, before any other check.

2. Key ID (kid) membership — the lease carries a kid identifying which signing keypair was used. LeaseVerifier.verify looks up kid in the tenant's trusted keyset (a dictionary keyed by kid) and rejects the lease if it is absent — even if the signature itself is mathematically valid against some other key. This is how a compromised signing key gets invalidated: ship an app update that drops the compromised kid from the trusted keyset.

3. Expiry — checks expiresAt against the current time with a skewTolerance window (default 300 s / 5 minutes) to absorb minor clock drift. A lease past its expiry window is rejected. Callers do not need to check expiry separately; the verifier handles it.

Here is how the SDK calls this at launch:

// Inside the SDK on app launch:
let isValid = LeaseVerifier.verify(
    lease: cachedLease,
    trustedKeys: configuration.trustedPublicKeys
)

The trustedKeys argument is your configuration's trustedPublicKeys — the dictionary of kid → Curve25519.Signing.PublicKey values from your KeylightConfiguration. The function returns a plain Bool — it does not throw.

What LeaseVerifier.verify explicitly does not do is equally important to understand:

It does not enforce activation count. The activationCount field is exposed in the lease object so your app can display it, but LeaseVerifier.verify does not compare it against activationLimit. Activation enforcement happens server-side when a device calls /activate; the verifier only checks signature, kid, and expiry.

It does not protect your binary against reverse engineering. A developer with a disassembler can find LicenseManager.isEntitled and patch the branch. The SDK source is public. The signed lease stops someone from forging entitlements by editing a file; it does not stop someone from patching the binary that reads it. Keylight is a commercial licensing system, not DRM.

It does not prevent use of a valid cached lease before revocation propagates. If a customer's lease was valid at last sync and the customer has no network access, the lease remains valid locally until the app revalidates online. This is the fail-open tradeoff of offline-first verification — and it is deliberate. The alternative (fail-closed, requiring a server call on every launch) locks out legitimate customers with no internet access.

It does not protect against a compromised private key. If Keylight's private key were compromised, an attacker could mint arbitrary valid leases. The trust anchor is the private key staying on Keylight's servers. Keylight's threat model is explicit: Keylight stops casual abuse and enforces commercial limits. It is not the last line of defense against a skilled attacker, and it does not claim to be.

The signed lease is a commercial licensing mechanism, not DRM. It raises the economic floor for abuse — editing the lease file does not work, sharing one key across more devices than the activation limit allows gets caught on the next revalidation — but it is not tamper-resistant in the DRM sense. For the full picture of the entitlement model and how the SDK integrates it, see the license keys feature page.

The field-by-field anatomy is the part most license-key guides skip, and it is where the security of the model actually lives. If there are aspects of the signing or verification flow you want to dig into further, send us your feedback and we'll extend this post.

FAQ

What is an Ed25519 lease?

It is a small JSON document — covering the customer, product, expiry, activation limit, and features — signed by an Ed25519 private key held on Keylight servers. The app verifies the signature locally using the matching public key.

Can the customer modify their own lease?

They can edit the file, but the signature will no longer match. The Keylight SDK rejects any lease whose signature does not verify against the embedded public key.

Why Ed25519 and not RSA?

Ed25519 produces smaller signatures (~88 bytes vs ~344 for RSA-2048), is faster to verify, and avoids the parameter-choice footguns RSA introduces. For desktop licensing where the app verifies the signature on every launch, the size and speed matter.