Permissions & Modules

The EMS + CAPA suite follows ianaiERP's existing two-tier permission model:

1. Module entitlements (per tenant) — toggles a whole feature on or off for the tenant. Stored in common_keyvalue under the MODULE_PERMISSION key.
2. Granular permissions (per user) — fine-grained read/write bits. Stored on the user and merged with the tenant's enabled modules at request time.

A user can only exercise a granular permission if BOTH the user has the bit AND the tenant has the module enabled. This means a single user object stays the same when their tenant turns CAPA on or off — the merge happens server-side on every API call.

Module entitlements (tenant-level)

Each entitlement is independent. A tenant can enable any combination — the Equipment Hub renders graceful "Enable {Module}" empty states for widgets whose module is off.

How to enable an entitlement

Admin path (ianaiERP staff): edit the tenant's MODULE_PERMISSION JSON in common_keyvalue to add the relevant *_PERMITTED string to the enabled modules array.

User-facing path (for self-serve tenants on the Business plan): Settings → Subscription → enable the addon module.

What happens after enabling

1. The tenant's MODULE_PERMISSION row gets updated.
2. The next API call from any user in that tenant runs through the auth middleware, which reads the row and applies ModuleToPermissionMap to fill in the corresponding granular bits.
3. The sidebar refreshes, exposing the new menu items.
4. The Equipment Hub starts rendering the previously-gated widgets.

No restart needed; no per-user provisioning needed.

Granular permissions (user-level)

These are bit-level permissions stored on each user. The seven new ones added for the EMS suite:

Reuse of existing permissions:

• Spare-part item flags (is_spare_part, safety_stock_qty) reuse item_read / item_write.
• Asset hierarchy edits (parent reassign, move subtree) reuse asset_write.
• Work Center CAPA fields reuse support_write.

Module → Granular mapping

When a tenant enables an entitlement, the auth middleware automatically grants the corresponding granular bits to users who already have those granular permissions assigned:

This is gating, not granting — the user still needs the granular bit on their user record. The module entitlement just unblocks it.

Typical role recipes

These aren't built-in roles (ianaiERP doesn't have role presets yet) — they're patterns for assigning granular perms to users.

Plant manager

equipment_read, capa_read, maintenance_read
asset_read, item_read, support_read

Read-only everything in the suite. Sees the hub, the planner, the maintenance history. Can't make changes; can call attention to issues.

Production planner

equipment_read, capa_read, capa_write
asset_read, item_read, support_read

Can use the Capacity Planner to recompute and rebalance. Can't change asset status or maintenance events.

Maintenance lead

equipment_read, maintenance_read, maintenance_write
equipmentstatus_write
asset_read, item_read, item_write (for spare parts)
support_read

Creates PM plans, logs events, links spare parts, marks PMs done. Can flip asset runtime status (e.g. take something to MAINTENANCE before starting an event manually).

Floor operator (tablet)

equipment_read
equipmentstatus_write

Sees the hub, can flip asset runtime status. Cannot edit accounting fields, cannot create maintenance events (the auto-created BREAKDOWN event from a DOWN action is fine — they don't "create" it, the system does).

Finance / asset accountant

asset_read, asset_write
(no equipment_*)

Doesn't need the EMS suite at all. Works on /asset for acquisitions, depreciation, disposal.

Page-level gating in the UI

Each page checks both module + granular before rendering:

If either check fails, the page renders a NoPermissionBlur with a hint about what's missing.

Cross-module widget gating on the Hub

When a tenant has only some modules enabled, the Equipment Hub shows what it can:

This intentionally avoids hiding the cards — admins seeing the empty-state cards know what to enable.

Cross-permission action gating

For granular per-action checks (capa_write, maintenance_write, equipmentstatus_write), the UI reads from the merged-permission store:

const can = useUserState((state) => state.mergedPermission)

<Button disabled={!can?.capa_write}>Recompute</Button>

mergedPermission is the user's granular bits AND-ed with the tenant's enabled modules. Both must be true for the action to be enabled.

REST API auth

Every new HTTP path is registered in auth-ms's allowlist with the required granular perm:

Casbin enforces these per request. Calls without the bit return 403.

Troubleshooting

Related

• Introduction → Module entitlements — how the modules slot into the broader platform
• Asset Management → Permissions split — the asset_write vs equipmentstatus_write distinction
• Runtime Status — the operator-tier permission in practice