Four layers of permissions, and why three of them are not enough

Still useful, just not sufficient. It answers what kind of user this is: platform operator, tenant owner, staff, external client. It decides which application they see at all.

Not every customer buys every module. A contractor on a basic plan should not see equipment management at all — not a disabled button, not an empty page. Grants live on the tenant, so the platform operator controls what a customer's whole organisation can reach.

This is where most systems stop, and it is the layer customers actually want to configure. The tenant owner builds their own roles from individual permissions, because only they know that at their company the storekeeper approves material issue but not purchase.

The layer people forget, and the one that causes data leaks. Two supervisors may have identical permissions and still must not see each other's sites. That is not a permission question, it is a data-scope question — which rows, not which screens.

Field visibility is the same idea one level down. A supervisor may need the labour attendance record but not the wage rate on it. Same row, different columns.

// Tenant isolation belongs in middleware, never in each handler.
// One forgotten filter in one endpoint leaks another customer's data.
app.use(builderScope);

function builderScope(req, res, next) {
  req.scope = { builderId: req.user.builderId };
  next();
}

Each layer narrows the one above it and can never widen it. A custom role cannot grant a module the tenant has not bought; row scope cannot expose another tenant's data. Enforce that direction strictly and the model stays reasonable to audit as it grows.