Clavem

Entitlement

An entitlement is the specific set of things a license permits its holder to do, such as which product they may use, which features are on, which versions they may run, how many devices and for how long.

How it works

A license answers one question: did this person buy? An entitlement answers the next: what do they get? A sale can grant a product, a tier, a version range, a number of devices and a period. The app reads those facts from the license and maps them to behaviour. How that mapping is stored decides whether it can be forged. A value in a local settings file can be edited. A value inside a signed token cannot, without the seller’s private key.

What Clavem carries

Clavem has no entitlement list and no feature-flag field. The entitlement is spread over a few fields, and only some are signed. This is the real payload of the public demo license’s token:

{ "v": 1, "lid": 1, "pid": 1, "kh": "7e0e4148136b6dae", "status": "active",
  "valid": true, "email": "ada@example.com", "iat": 1795126842, "refresh_by": 1796336442 }
Part of the entitlement Field In the signed token
Product pid Yes
Valid now valid, status Yes
Until when exp, absent when perpetual Yes
Device count activation_limit No, API response only
Variant name meta.variant_name No, API response only

The last two are in the validate response, but nothing signs them. An app that trusts them offline trusts a file the customer can edit.

A worked mapping

Each tier becomes its own Clavem product, so the signed pid says which tier the customer bought. An example with made-up prices and ids:

Stripe price Clavem product Validity Device limit The app turns on
$29 one-time Inkwell Basic, pid 75 Perpetual 1 Editor, PNG export
$59 one-time Inkwell Pro, pid 76 Perpetual 3 Basic, plus PDF export and sync
$5 a month Inkwell Pro Monthly, pid 77 Follows subscription 3 Same as Pro while paid

In Clavem you map a Stripe price to a Clavem product, and a mapping to one price wins over a mapping to its whole Stripe product. Each product has its own Ed25519 key pair, and a token from one does not verify against another’s public key, so the app tries each public key:

const TIERS = [
  { name: 'basic', pid: 75, publicKey: BASIC_PUBLIC_KEY },
  { name: 'pro', pid: 76, publicKey: PRO_PUBLIC_KEY },
];

async function tierOf(token) {
  for (const t of TIERS) {
    const claims = await verifyToken(token, t.publicKey);
    if (claims && isLicensed(claims, t.pid)) return t.name;
  }
  return 'free';
}

verifyToken and isLicensed are on the offline verification page. This code ran against tokens signed with two test keys: a token from the second key came back pro, and a malformed token came back free.

Entitlement versus license

Keep the two apart when you design. If you want an upgrade from Basic to Pro, the customer needs a Pro license, not an edit to the Basic one, because the product, and therefore the signing key, is different. A signed token proves a license. Your mapping decides the entitlement.

How Clavem handles it

Clavem issues the license, enforces the device limit and expiry, and signs the answer. It does not store features. Changing a device limit or expiry on one license is a PATCH in the API reference, as in a goodwill extension. See license expiry and device limit.

Questions

What is the difference between a license and an entitlement?

The license is the record that a purchase happened, identified by a key. The entitlement is what that record grants. Two licenses can have different entitlements, for example a Basic and a Pro purchase.

Where should feature checks read the entitlement from?

From data your app can trust. A signed token can be trusted offline. An unsigned API response is fine for showing information but should not be the only thing that turns paid features on.