Subscription entitlements (module access)
Effective access = RBAC permission AND organization entitlement. These are separate questions, answered by separate code:
| Layer | Answers | Where |
|---|---|---|
| RBAC | May this person do this? | @PreAuthorize on each handler; roles → permissions |
| Entitlement | Does this organization have this module? | @RequiresModule + ModuleEntitlementInterceptor |
| Access mode | Is the organization in Early Access or on plan entitlements? | tenant.access_mode, set only by config or a platform operator |
Holding every permission (e.g. sysadmin_demo) never grants a module the organization lacks.
Having a module never grants a person a permission they lack.
Modules and plans
Modules are the ModuleCode enum. Plans and add-ons are configured in entitlements.* in
application.yml, the only place that lists what a plan includes:
| Module | Payroll Essentials (starter) | People Suite (growth) | Enterprise |
|---|---|---|---|
| PAYROLL, EMPLOYEE_RECORDS, TIMESHEETS | ✓ | ✓ | ✓ |
| LEAVE, OVERTIME, BONUSES (incl. reimbursements) | – | ✓ | ✓ |
| RECRUITMENT, CRM, INVENTORY (incl. Sales & Purchasing), ACCOUNTING | add-on | add-on | ✓ |
- Timesheets are in the entry plan because payroll is computed from hours.
- Add-ons are granted by the platform operator. There is no add-on purchase yet.
Core is never gated: auth, users, roles, permissions, audit, notifications, messages, announcements, saved
views, company profile, compliance, company documents, billing, the operator portal, webhooks and
public endpoints. ModuleCoverageTest fails the build if a controller is neither tagged with a module nor listed as core.
How access is resolved (EntitlementService)
- Platform operator (no tenant): not checked.
- Ended trial with no plan: nothing ENTITLED.
- This applies even in Early Access, where the operator extends trials on request. Otherwise an abandoned workspace would stay writable forever.
EARLY_ACCESSmode: every module ENTITLED. No subscription is implied.- Running trial: every module ENTITLED.
- Plan entitlements: the effective plan's modules plus active add-ons.
- The effective plan is the live provider subscription's plan; failing that, the operator's managed plan.
- A scheduled downgrade is in effect from its date by the clock, even if the renewal webhook hasn't arrived.
A module that isn't ENTITLED is:
- READ_ONLY if the organization was ever entitled to it (
tenant_module_usage). GET/HEAD and POSTs markedreadOnlySafepass; every change is refused. - LOCKED otherwise. Everything is refused.
tenant_module_usage measures "was once entitled", not "created records". A module Early
Access or a trial included, but that nobody opened, is still READ_ONLY afterwards. That's
intended: read-only on an empty module is harmless, and it saves "has data" queries in every module.
A refusal is 403 with code: MODULE_NOT_ENTITLED, plus module, accessState,
requiredPlan/requiredPlanLabel and addon. A permission refusal stays a plain 403 with no code.
Caching across instances
The slow inputs (subscription, add-ons, usage) are cached per tenant, keyed by
tenant.entitlement_version.
- Every request reads the tenant row by primary key and reloads if the version moved.
- Every change bumps the version in its own transaction (
SubscriptionChangeRecorder,TenantRepository.bumpEntitlementVersion). Changes include plan changes, cancellations, webhook updates, add-ons, mode and managed plan.
A revocation made on one instance is therefore honoured by every instance on its next request. There is no TTL and no shared cache. Time-based rules (trial end, downgrade date) are evaluated per request.
Where it is enforced
- HTTP:
ModuleEntitlementInterceptor(after the audit interceptor, before@PreAuthorize).- Controllers carry
@RequiresModule. - Mixed controllers tag methods instead, e.g.
ReportingControllerper report.
- Controllers carry
- Scheduled jobs:
TenantScopedExecutor.forEachEntitledTenant(module, …)skips tenants that aren't fully entitled. Used by inventory alerts and stock migration. - WebSocket: the inventory stock feed needs INVENTORY not LOCKED.
- Never in computation. Payroll keeps reading every existing timesheet, approved overtime and leave whatever the plan, so a downgrade can't change anyone's computed pay.
EntitlementBoundaryTestkeeps the entitlement package out of business services.- Consequence: leave or overtime still pending approval when a downgrade takes effect can't be approved afterwards.
Lifecycle
- Downgrade: scheduled for renewal (see
billing.md"Changing plans"). Nothing is restricted before the date. - Upgrade: immediate, so modules unlock at once.
- Trial: 14 days, full suite, no card, no charge at the end.
- An ended trial no longer locks the workspace. People sign in,
/billingworks, and previously used modules are READ_ONLY. Data is kept. - Only an administrative suspension locks everyone out.
- An ended trial no longer locks the workspace. People sign in,
- Access mode:
- The column default is
PLAN_ENTITLEMENTS(fail-safe). - V172 set every existing tenant to
EARLY_ACCESS. - New tenants get
entitlements.new-tenant-access-mode, which isENTITLEMENTS_NEW_TENANT_ACCESS_MODE. It defaults toPLAN_ENTITLEMENTSand is set toEARLY_ACCESSexplicitly in the compose files during Early Access. Remove that line at General Availability.
- The column default is
- Header badge:
- Shows Early Access (not "Managed plan" or "Paid plan") for an Early Access workspace with no purchase.
- Ignores a subscription from a provider the server no longer loads.
- Shows a trial the nightly sweep suspended as an ended trial.
- History:
subscription_changeis append-only. It records plan changes (scheduled, applied, cancelled), add-ons, access mode and managed plan, each with source (user,operator:<name>,webhook:polar) and effective date.
Operator API (/api/admin/tenants/{id}, platform.tenants.manage)
GET entitlements, GET subscription-changes, PUT access-mode {mode}, PUT managed-plan {planCode},
PUT addons/{module}, DELETE addons/{module}. These are also available in the tenant drawer on /admin/tenants.
Frontend
lib/module-routes.tsmaps page paths to modules.ModuleGate, wrapped around every workspace page:- LOCKED shows the locked page;
- READ_ONLY shows a banner on top of the page.
- The sidebar shows a lock and an "Available on …" hint. RBAC still decides visibility first.
- A
MODULE_NOT_ENTITLEDresponse shows one toast and refreshes entitlements. /billingshows "Access & modules": basis, module states and recent changes.
Known gaps
- Pages still render their write buttons in read-only modules. The server refuses the change, and the banner and toast explain why.
- Public careers (
/api/public/job-openings) is GLOBAL-scoped and lists every tenant's openings. Tenant isolation there needs a separate security review. Entitlement filtering wouldn't fix it. - The login-page trial-renewal path (
TENANT_TRIAL_EXPIRED,TrialRenewalPanel) is no longer reached for trials and can be removed in a follow-up.