Licensing Phase A Built
Licensing decides what each merchant is entitled to run. Operators define reusable plans (trial, subscription, perpetual) carrying typed feature flags and seat limits; the system issues a license from a plan, binds it to a merchant or user, tracks its lifecycle, and validates it at runtime - returning a signed certificate that the rest of the product trusts offline to gate features and devices. It is used by platform operators (who manage plans and licenses), merchants (who run on a license and self-serve a free trial), and every other service (which enforces the resulting entitlements).
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-15 |
| Tier | Core |
| Status | Built |
| Phase | P1 (Plans + Licenses + Validation), P2 (Activation + Free Trial + Certificate distribution) |
| Priority | HIGH |
| Primary users | Platform Operator · Merchant Owner · Other services (entitlement enforcement) |
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Reusable plans: trial, subscription, perpetual | Billing, invoicing, and dunning |
| Typed feature flags and seat quotas per plan | Payment / subscription-charge integration |
| Public plan catalog for sign-up surfaces | Usage metering and heartbeat tracking |
| License issuance, renew, suspend, reinstate, revoke | Per-feature runtime enforcement (each consuming service does its own) |
| Self-service free-trial issuance | License management UI (frontend concern) |
| Device activation (fingerprint binding, seat limit) | Certificate verification (done by every other service offline) |
| Runtime validation returning a signed certificate | Eager expiry sweeping (expiry is lazy, on validation) |
| Per-license overrides of plan defaults | |
| Append-only license event audit log |
3. Capabilities
| Capability | What the user can do |
|---|---|
| Plan management | Define reusable plans (trial / subscription / perpetual) with duration, grace period, and seat limit |
| Feature flags & quotas | Attach typed flags (boolean / number / text / json) to a plan to switch features on/off and set numeric quotas |
| Plan catalog | Expose the list of active plans, with their features, to sign-up and upgrade surfaces |
| License issuance | Issue a license from a plan, bound to a merchant or user, with a unique license key |
| License lifecycle | Renew, suspend, reinstate, and revoke a license, each audited and re-certified |
| Free trial | A merchant self-serves a single free-trial license without operator action |
| Device activation | Bind a license to specific devices by fingerprint, capped by the plan's seat limit |
| Runtime validation | Validate a license key and receive its status, resolved features, and a signed certificate |
| Per-license override | Override a plan's seat limit or feature values for one specific license |
| Audit trail | Every lifecycle action is recorded in an append-only event log |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Commerce | A license is bound to a merchant (or user) principal; merchant identity comes from Commerce |
| Permissions | Plan and license management actions are gated by licensing-scoped permissions |
| Sale / Inventory / other modules | Consume the signed certificate to gate features and seat quotas; Licensing gates their access |
5. Backend Packages
Implementation detail lives in the developer docs - this section only maps the module to the service that powers it.
| Package | Role | Developer docs |
|---|---|---|
@nx/licensing | Owns the entire licensing domain: plans, feature flags, license lifecycle, activation, validation, and certificate signing | licensing |
Licensing owns no schema of its own - all five tables (
Policy,PolicyFeature,License,Activation,LicenseEvent) live in@nx/coreand are re-exported. The package signs an Ed25519 certificate and caches it; every other service verifies that certificate offline.
Engineering Mapping (Feature ⇄ Package)
The horizontal axis of the Feature Spine - each business feature (
<AREA>in the URD) maps to its engineering home. Reciprocal: the package docs link back here.
| Feature | Dev package | Status |
|---|---|---|
PLN Plans & Feature Flags | @nx/licensing | Built |
LIC License Lifecycle | @nx/licensing | Built |
VAL Runtime Validation & Entitlements | @nx/licensing | Built |
ACT Device Activation | @nx/licensing | Built |
6. Key User Flows
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Platform Operator | Manage plans and feature flags; issue, renew, suspend, reinstate, revoke licenses; manage activations | - |
| Merchant Owner | Browse the plan catalog; self-serve one free trial; validate their own license | Manage plans; issue or revoke licenses for others |
| Other services | Validate a license key and read the resulting certificate | Mutate plans, licenses, or activations |
8. Status & Roadmap
Module status: Built. The backend (
@nx/licensing) ships five controllers and three services covering the full plan → license → activation → validation flow, with Ed25519-signed certificates distributed via cache.
| Phase | Capabilities |
|---|---|
| P1 | Plans (trial / subscription / perpetual), typed feature flags + seat limits, plan catalog, license issuance + lifecycle (renew/suspend/reinstate/revoke), runtime validation, event audit log |
| P2 | Self-service free trial, device activation with seat enforcement, per-license override, Ed25519 certificate signing + offline verification across services |
| P3 | Eager expiry sweeping, license-event REST surface, calendar-aware durations, usage metering (all planned, not built) |
9. Related Pages
- URD
- PRDs
- Developer docs:
@nx/licensing - Related modules: Commerce · Permissions