Diffing required vs granted entitlements on upgrade
When a new app version needs entitlements the customer's license never granted, a raw "feature locked" is a dead end. Here is how to diff required against granted and tell them exactly what to buy.
A customer on your 3.x line upgrades to 4.0. The new release adds SSO, an audit-log exporter, and a higher project ceiling — three things their current license, minted against the 3.x tier template, was never issued to cover. They launch, click Export audit log, and get a flat FeatureLockedException. They click SSO settings and get another. Each failed click is a separate support ticket, and none of them answers the only question the customer actually has: what do I need to buy to make this version whole?
The problem is not the gate. Fail-closed gating on each feature is correct and you should keep it. The problem is that per-feature IsEnabled checks answer the wrong-sized question. They tell you, at the moment of use, whether one capability is on. They never tell you, up front, the shape of the gap between what this version of the app needs and what this license grants. That shape is a set difference, and computing it once at startup turns a trickle of mystery lockouts into one honest sentence.
An entitlement is a named capability; a version requires a set of them
If you have read entitlements versus feature flags, you know a Keyright entitlement is a named capability baked into the signed license — a boolean like audit-export, or a numeric limit like max-projects: 50. The license carries the set the customer was granted. What it does not carry, and should not, is the set your current build requires — because that set changes every time you ship.
So declare it in the app. A capability manifest is a small, static description of every entitlement a given version depends on, versioned alongside the code that depends on it. It ships inside the assembly; it is not a secret and not a license artifact.
public sealed record Requirement(string Key, RequirementKind Kind, long Min = 0);
public enum RequirementKind { Flag, Limit }
public static class AppManifest
{
// Everything THIS build needs the license to grant. Grows as the product grows.
public static readonly IReadOnlyList<Requirement> Required = new[]
{
new Requirement("audit-export", RequirementKind.Flag),
new Requirement("sso", RequirementKind.Flag),
new Requirement("max-projects", RequirementKind.Limit, Min: 25),
};
}
When you add a feature in 4.0 that leans on sso, you add one line here in the same commit. The manifest is the single place that knows “this version needs these capabilities,” and it lives next to the code, so it can never drift out of sync with a release the way an external config would.
The granted set comes from the validated license
The other half of the diff is what the license actually grants, and that is pure local computation. The SDK validated the signed license offline against your embedded public key at startup; reading its entitlements is just inspecting the result.
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = AcmeKeys.LicensePublicKey, // public key only; safe to ship
ServiceUrl = "https://licensing.acme.example",
});
LicenseInfo info = client.Validate(); // never throws; fails closed to Free on any problem
Validate() never reaches the network on the hot path, never throws, and on any failure returns a LicenseInfo in the Free edition whose entitlement set is empty. That last property matters for the diff: an invalid or missing license does not crash the comparison, it simply grants nothing, so every requirement shows up as missing — which is exactly the report you want in that case.
The diff is set arithmetic
Now walk the required set against the granted license and collect what is not satisfied. A flag is satisfied when the license enables it; a limit is satisfied when the license’s ceiling meets or exceeds the minimum this version needs.
public sealed record Gap(Requirement Need, long? Granted);
public static IReadOnlyList<Gap> Diff(LicenseInfo info, IEnumerable<Requirement> required)
{
var gaps = new List<Gap>();
foreach (var r in required)
{
switch (r.Kind)
{
case RequirementKind.Flag:
if (!info.Entitlements.IsEnabled(r.Key))
gaps.Add(new Gap(r, Granted: null));
break;
case RequirementKind.Limit:
long granted = info.Entitlements.GetLimit(r.Key); // 0 when absent
if (granted < r.Min)
gaps.Add(new Gap(r, Granted: granted));
break;
}
}
return gaps;
}
Because IsEnabled and GetLimit both fail closed — an unknown flag reads as off, an absent limit reads as 0 — the diff is correct even against a Free or malformed license without a single special case. The gap list is the answer: empty means this version is fully covered; non-empty is a precise, buyable shopping list.
Report it once, at startup
Run the diff when the app boots and surface the whole gap in one place — a banner, a blocking dialog, a log line for a headless host — instead of letting the user trip each lock individually. The message names what is missing and points at the upgrade, which is the action that resolves all of it at once.
var gaps = EntitlementDiff.Diff(info, AppManifest.Required);
if (gaps.Count > 0)
{
var lines = gaps.Select(g => g.Granted is null
? $" • {g.Need.Key} (not included in your license)"
: $" • {g.Need.Key}: need {g.Need.Min}, your license allows {g.Granted}");
_log.LogWarning(
"This version of acme-suite needs entitlements your current license ({Tier}) does " +
"not cover:\n{Gaps}\nUpgrade your license to enable them: {Url}",
info.Tier, string.Join('\n', lines), "https://acme.example/account/license");
_startup.ShowUpgradeNotice(gaps); // one notice, the full shopping list, a real next step
}
Note what this does not do: it does not disable the app. A gap means some 4.0 features are unavailable, not that the product is unlicensed. Everything the license does grant keeps working; the feature-level gates stay exactly where they were and still fail closed at the point of use. The diff is an upgrade prompt, not a kill switch — the two live at different layers and never substitute for each other.
Make the diff a preflight check too
The same manifest pays off before a byte of the new version reaches a customer. A partner shipping to a fleet, or your own CI, can mint a probe license at the current tier and assert that the diff is empty — catching “4.0 silently needs an entitlement the Pro tier template never grants” at build time instead of in a support queue.
[Fact]
public void ProTier_covers_everything_v4_requires()
{
LicenseInfo pro = TestIssuer.Mint(product: "acme-suite", tier: "Pro");
var gaps = EntitlementDiff.Diff(pro, AppManifest.Required);
Assert.True(gaps.Count == 0,
"Pro tier is missing: " + string.Join(", ", gaps.Select(g => g.Need.Key)));
}
If that test goes red when you add a feature, you have a decision to make before release: widen the tier template so Pro grants the new entitlement, or accept that the feature is an upsell to a higher tier. Either way you made the call deliberately, with the gap in front of you, rather than discovering it from the first customer who upgraded and found a locked button.
The shape of the gap is the product of the diff
Per-feature gating tells a user that a door is locked. Diffing the manifest against the license tells them which doors, why, and what one purchase opens all of them — the difference between a frustrating trickle of lockouts and a single, honest, actionable prompt. Keep the fail-closed gates: they are your enforcement. Add the startup diff on top: it is your explanation. One is how the software protects the business; the other is how the business keeps the customer from rage-quitting an upgrade they would happily have paid for.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.