Skip to main content

Subscription entitlements (module access)

Effective access = RBAC permission AND organization entitlement. These are separate questions, answered by separate code:

LayerAnswersWhere
RBACMay this person do this?@PreAuthorize on each handler; roles → permissions
EntitlementDoes this organization have this module?@RequiresModule + ModuleEntitlementInterceptor
Access modeIs 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:

ModulePayroll Essentials (starter)People Suite (growth)Enterprise
PAYROLL, EMPLOYEE_RECORDS, TIMESHEETS✓✓✓
LEAVE, OVERTIME, BONUSES (incl. reimbursements)–✓✓
RECRUITMENT, CRM, INVENTORY (incl. Sales & Purchasing), ACCOUNTINGadd-onadd-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)​

  1. Platform operator (no tenant): not checked.
  2. 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.
  3. EARLY_ACCESS mode: every module ENTITLED. No subscription is implied.
  4. Running trial: every module ENTITLED.
  5. 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 marked readOnlySafe pass; 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. ReportingController per report.
  • 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. EntitlementBoundaryTest keeps 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, /billing works, and previously used modules are READ_ONLY. Data is kept.
    • Only an administrative suspension locks everyone out.
  • 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 is ENTITLEMENTS_NEW_TENANT_ACCESS_MODE. It defaults to PLAN_ENTITLEMENTS and is set to EARLY_ACCESS explicitly in the compose files during Early Access. Remove that line at General Availability.
  • 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_change is 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.ts maps 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_ENTITLED response shows one toast and refreshes entitlements.
  • /billing shows "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.