Skip to main content

License Capability Model

Muonroi implements a three-tier license capability system that controls runtime feature access. Every application starts in Free tier and can be upgraded to Licensed or Enterprise based on activation.

Overview​

The capability model enforces feature gates at runtime using:

  • LicenseState — carries tier, validity, and optional activation metadata
  • ILicenseGuard — provides feature checking and validation APIs
  • Feature strings — stable identifiers like "rule-engine", "multi-tenant", etc.

The system is designed to be fail-closed: if a feature check fails at startup, registration fails fast rather than silently degrading.


The Three Tiers​

Free Tier​

The default tier for all applications. Includes only core database and HTTP operations—no license key required.

Available features:

  • db.query — Database read operations
  • db.save — Persist changes to database
  • db.add — Add new records
  • db.update — Modify existing records
  • db.delete — Remove records
  • http.request — Make outbound HTTP calls
  • api.validate — Basic API validation

Use case: Prototype, hobby projects, community development.

Licensed Tier​

Unlocked with a valid license key. Adds developer productivity tooling and control plane integration.

Includes all Free features, plus:

  • vsix.publish — Publish VSIX packages from Visual Studio
  • vsix.watch — Watch VSIX files for live reload
  • vsix.explorer — Code explorer in VSIX extension
  • cp.publish — Publish rules to Control Plane

Use case: Teams building production applications with integrated development workflows.

Enterprise Tier​

Unlocked with an Enterprise license. Includes the full feature set with governance, multi-tenancy, and advanced security.

Includes all Licensed features, plus:

  • rule-engine — Execute dynamic business rules at runtime
  • multi-tenant — Isolate data and configuration per tenant
  • advanced-auth — Custom authorization policies (OpenFGA, OPA)
  • audit-trail — Immutable audit log with HMAC chain verification
  • anti-tampering — Startup code integrity checks and runtime guards
  • grpc — gRPC service communication
  • message-bus — Event distribution via message broker
  • distributed-cache — Shared cache (Redis) across instances
  • connectors — External system connectors (Stripe, Salesforce, etc.)
  • js-expressions — JavaScript expression evaluation in rules

Use case: Large organizations requiring multi-tenant SaaS platforms, regulatory compliance, and real-time rule execution.


Complete Feature Matrix​

FeatureFreeLicensedEnterprise
Database Operations
db.query✓✓✓
db.save✓✓✓
db.add✓✓✓
db.update✓✓✓
db.delete✓✓✓
HTTP & API
http.request✓✓✓
api.validate✓✓✓
Developer Tools
vsix.publish✓✓
vsix.watch✓✓
vsix.explorer✓✓
cp.publish✓✓
Business Logic
rule-engine✓
multi-tenant✓
advanced-auth✓
audit-trail✓
anti-tampering✓
Infrastructure
grpc✓
message-bus✓
distributed-cache✓
Integrations
connectors✓
js-expressions✓
PDF Product Line (add-on)
pdf.designeradd-onadd-on
pdf.registryadd-onadd-on
pdf.canaryadd-onadd-on

PDF capability keys are add-ons, not tier features. pdf.designer, pdf.registry, and pdf.canary are granted per-license-key regardless of tier and are not part of any tier's default feature set. Enable them with the grant/revoke endpoint or CLI — see License Server Admin → PDF Entitlements.

KeyComponent
pdf.designerPDF Designer commercial component (@muonroi/ui-engine-pdf-designer)
pdf.registryPDF template registry (control-plane backend + hot-reload)
pdf.canaryPDF canary quality-gate (SSIM scorer + rollback)

API Reference​

ILicenseGuard Interface​

The main service for runtime feature checking. Inject ILicenseGuard into any .NET service.

public interface ILicenseGuard
{
/// Gets the current license state (tier, validity, payload)
LicenseState Current { get; }

/// Gets the effective tier: Free, Licensed, or Enterprise
LicenseTier Tier { get; }

/// True if running in Free tier
bool IsFreeMode { get; }

/// Validates a feature is available. Throws if not allowed.
void EnsureValid(string actionType, string? actionName = null,
string? payloadHash = null, string? correlationId = null);

/// Checks if a feature is available. Returns bool (no throw).
bool HasFeature(string featureName);

/// Ensures a feature is licensed. Throws if unavailable.
void EnsureFeature(string featureName);

/// Records an action in the HMAC chain (for audit trail).
void RecordAction(LicenseActionContext context);

/// Gets the current rolling token for chain verification.
string GetChainToken();

/// Decrypts data using license-derived keys.
string DecryptSecurely(string purpose, string encryptedData,
Func<string, string, string> decryptor);
}

LicenseState Model​

Represents the complete license state at runtime.

public sealed class LicenseState
{
/// License is valid (not expired, not revoked)
public bool IsValid { get; init; }

/// License has exceeded its expiry date
public bool IsExpired { get; init; }

/// Error message if validation failed
public string? Error { get; init; }

/// Parsed license payload (key, tier, features)
public LicensePayload? Payload { get; init; }

/// Server-signed activation proof (tier, heartbeat nonce, expiry)
public ActivationProof? ActivationProof { get; init; }

/// Effective tier: Free, Licensed, or Enterprise
public LicenseTier Tier { get; init; }

/// License key identifier (from activation proof)
public string? LicenseId { get; init; }

/// Organization name (from activation proof)
public string? OrganizationName { get; init; }

/// Expiry date (from activation proof)
public DateTimeOffset? ExpiresAt { get; init; }

/// List of enabled feature strings
public string[]? Features { get; init; }

/// Checks if a specific feature is allowed
public bool HasFeature(string featureName)
=> LicenseCapabilityResolver.HasAccess(this, featureName);

/// Creates a Free tier license (always valid)
public static LicenseState CreateFree() { ... }
}

Usage Examples​

Check a Feature at Runtime​

Use HasFeature when you want to gracefully degrade:

public class OrderService(ILicenseGuard license)
{
public void ProcessOrder(Order order)
{
if (license.HasFeature("rule-engine"))
{
// Apply advanced business rules
var result = await _ruleEngine.ExecuteAsync(order);
}
else
{
// Fall back to basic processing
ApplyBasicValidation(order);
}
}
}

Require a Feature​

Use EnsureFeature when a feature is mandatory:

public class AuditService(ILicenseGuard license)
{
public void LogAction(string action, object data)
{
license.EnsureFeature("audit-trail"); // Throws if not Enterprise
_auditStore.Insert(new AuditEntry { Action = action, Data = data });
}
}

Check Tier Directly​

Access the tier for conditional logic:

public class ConfigService(ILicenseGuard license)
{
public void ConfigureTenancy()
{
if (license.Tier == LicenseTier.Enterprise)
{
services.AddMultiTenancy(); // Full isolation
}
else
{
services.AddBasicTenancy(); // Shared resources
}
}
}

Startup-Time Fail-Fast​

Ensure a feature exists before registration completes:

// Program.cs
services.AddLicenseProtection(configuration);
services.AddRuleEngine(); // Requires "rule-engine" feature

// If license doesn't include "rule-engine", throws at startup
services.EnsureFeatureOrThrow("rule-engine");

Runtime Enforcement​

Activation Flow​

  1. On Startup:

    • LicenseActivator reads license key from file or environment
    • POST /activate to License Server with machine fingerprint
    • Receive signed ActivationProof containing tier, nonce, heartbeat config
    • Save proof to licenses/activation_proof.json
  2. At Runtime:

    • EnsureValid checks: is license expired? Is it revoked?
    • Grace period applies if heartbeat fails (24 hours default)
    • HasFeature resolves capability via LicenseCapabilityResolver
    • If Enterprise: HMAC chain verification, anti-tampering checks
  3. Grace Period:

    • If heartbeat cannot reach License Server, degrade to Free tier
    • Give 24 hours for operator to fix connectivity
    • After 24h, license becomes invalid and fails hard

Feature Resolution Strategy​

HasFeature uses this logic:

  1. If tier is Enterprise, all features allowed (payload: ["*"])
  2. If tier is Licensed, check explicit Features list in payload
  3. If tier is Free, only allow features in FreeTierFeatures.All
  4. Backward compatibility: legacy feature aliases map to modern names

Example:

// Free tier — only core database/HTTP
guard.HasFeature("db.query") // true
guard.HasFeature("rule-engine") // false

// Licensed tier — depends on payload
guard.HasFeature("cp.publish") // depends on Features array

// Enterprise tier — everything
guard.HasFeature("anything") // true

Configuration​

appsettings.json​

{
"LicenseConfigs": {
"Mode": "Online",
"FingerprintScope": "MachineAndProject",
"LicenseFilePath": "licenses/license.key",
"ActivationProofPath": "licenses/activation_proof.json",
"FallbackToOnlineActivation": true,
"EnableChain": true,
"FailMode": "Hard",
"Online": {
"Endpoint": "https://license.truyentm.xyz",
"EnableHeartbeat": true,
"HeartbeatIntervalMinutes": 240,
"RevocationGraceHours": 24,
"TimeoutSeconds": 10
}
}
}

FingerprintScope controls which factors the runtime fingerprint is derived from:

ValueFactorsUse case
MachineAndProject (default)MachineName, OS description, OS architecture, CPU count, ApplicationName, ProjectSeed, FingerprintSaltProduction: bind a license to one specific machine
ProjectOnlyApplicationName, ProjectSeed, FingerprintSalt onlyDev / UAT / prod fleet: one key validates on any machine

Changing FingerprintScope after activation against MachineAndProject produces a different fingerprint and requires re-activation.

Program.cs Registration​

services.AddLicenseProtection(configuration);           // Base license checks
services.AddMEnterpriseGovernance(configuration); // Anti-tamper + HMAC chain

Best Practices​

1. Prefer HasFeature Over Tier Checks​

Good:

if (guard.HasFeature("audit-trail")) { ... }

Avoid:

if (guard.Tier == LicenseTier.Enterprise) { ... }  // Too specific

2. Fail Fast at Startup​

If a feature is mandatory, validate at registration time:

services.EnsureFeatureOrThrow("rule-engine");

3. Graceful Degradation​

For optional features, use HasFeature to offer fallback behavior:

if (license.HasFeature("multi-tenant"))
await _tenantsService.IsolateAsync();
else
await _defaultTenantService.PrepareAsync();

4. Log License Events​

On activation or expiry:

logger.LogInformation("License activated: {Tier} for {Organization}",
license.Current.Tier, license.Current.OrganizationName);

5. Honor the Grace Period​

Don't immediately fail on heartbeat timeout. Wait for the full grace period:

// Heartbeat fails
// Wait 24h before degrading to Free
// Operator has time to restore connectivity

Cross-References​