hr_lite 0.5.3 → 0.6.0

data/lib/hr_lite/permissions.rb

@@ -0,0 +1,79 @@
+module HrLite
+  # The whole vocabulary of the engine's authorization, in one place.
+  #
+  # A permission is a KEY plus a SCOPE. The key says what the action is
+  # ("approve leave"); the scope says whose rows it reaches:
+  #
+  #   self  — only this person's own records
+  #   team  — the people who report to them (EmployeeProfile#manager_id)
+  #   all   — everyone in the company
+  #
+  # That is why there is no `leave.approve_own` / `leave.approve_team` /
+  # `leave.approve_all` triple: one key with three possible scopes says the
+  # same thing without three times the surface to get wrong.
+  #
+  # Keys are DATA — a role grants them from the database. They are declared
+  # here so that a typo in a controller is a boot-time failure rather than a
+  # permission that silently never matches.
+  module Permissions
+    SCOPES = %i[self team all].freeze
+
+    # Ordered weakest to strongest. `all` satisfies a `team` requirement,
+    # `team` satisfies `self`; never the other way round.
+    SCOPE_RANK = { self: 0, team: 1, all: 2 }.freeze
+
+    # key => [ group, description ]. The group is what the roles screen
+    # renders as a heading; the description is the sentence beside the
+    # checkbox, so it is written for the person granting it.
+    REGISTRY = {
+      "profile.view" => [ "People", "See employee profiles" ],
+      "profile.manage" => [ "People", "Create and edit employee profiles, onboard and offboard" ],
+      "attendance.view" => [ "Attendance", "See attendance records" ],
+      "attendance.manage" => [ "Attendance", "Correct punches and decide regularization tickets" ],
+      "leave.request" => [ "Leave", "Apply for leave and comp-off" ],
+      "leave.view" => [ "Leave", "See leave requests and balances" ],
+      "leave.approve" => [ "Leave", "Approve, reject and cancel leave and comp-off" ],
+      "leave.manage" => [ "Leave", "Adjust balances, configure leave types and holidays" ],
+      "payroll.view" => [ "Payroll", "See payroll runs and salary slips" ],
+      "payroll.manage" => [ "Payroll", "Create, compute, finalize, unlock and publish payroll" ],
+      "payroll.export" => [ "Payroll", "Download the payout register, including bank details" ],
+      "salary.view" => [ "Payroll", "See salary structures" ],
+      "salary.manage" => [ "Payroll", "Set and revise salary structures" ],
+      "appraisal.view" => [ "Growth", "See appraisals" ],
+      "appraisal.manage" => [ "Growth", "Write, share and act on appraisals and promotions" ],
+      "resignation.view" => [ "Lifecycle", "See resignations" ],
+      "resignation.manage" => [ "Lifecycle", "Accept resignations and set the last working day" ],
+      "settings.manage" => [ "Administration", "Change company settings, offices and policy" ],
+      "audit.view" => [ "Administration", "Read the audit trail" ],
+      "audit.view_money" => [ "Administration", "Read audit rows about pay, appraisals and promotions" ],
+      "role.manage" => [ "Administration", "Create roles and grant permissions" ]
+    }.freeze
+
+    KEYS = REGISTRY.keys.freeze
+
+    def self.valid?(key) = REGISTRY.key?(key.to_s)
+
+    # Raises rather than returning false: an unknown key in a controller is a
+    # typo that would otherwise read as "nobody may do this", which fails in
+    # the safe direction but silently, and is then very hard to find.
+    def self.validate!(key)
+      return key.to_s if valid?(key)
+
+      raise ArgumentError, "Unknown HrLite permission #{key.inspect}. " \
+                           "Declare it in HrLite::Permissions::REGISTRY first."
+    end
+
+    def self.group(key) = REGISTRY.fetch(key.to_s).first
+    def self.description(key) = REGISTRY.fetch(key.to_s).last
+
+    def self.grouped
+      REGISTRY.group_by { |_key, (group, _)| group }
+              .transform_values { |pairs| pairs.map(&:first) }
+    end
+
+    # Does `held` satisfy a requirement for `needed`?
+    def self.scope_covers?(held, needed)
+      SCOPE_RANK.fetch(held.to_sym) >= SCOPE_RANK.fetch(needed.to_sym)
+    end
+  end
+end

data/lib/hr_lite/role_seeds.rb

@@ -0,0 +1,81 @@
+module HrLite
+  # The six roles an install starts with. They are a STARTING POINT, not a
+  # ladder in code: an install is expected to edit the grants, and `roles:seed`
+  # never overwrites a role that already exists.
+  #
+  # Read the scopes as the interesting part. Manager and HR hold the same
+  # leave.approve key — the difference between them is `team` and `all`, which
+  # is the whole reason scope lives on the grant.
+  module RoleSeeds
+    # A method, not a constant: the keys are Role constants, and this file is
+    # required while the gem loads, long before Active Record models exist.
+    def self.definitions
+      {
+      Role::EMPLOYEE => {
+        description: "Self-service only: own attendance, leave, documents and payslips.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "self",
+          "attendance.view" => "self", "payroll.view" => "self",
+          "profile.view" => "self", "appraisal.view" => "self",
+          "resignation.view" => "self"
+        }
+      },
+      Role::MANAGER => {
+        description: "Everything an employee has, plus their reports' attendance and leave.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "team", "leave.approve" => "team",
+          "attendance.view" => "team", "attendance.manage" => "team",
+          "payroll.view" => "self", "profile.view" => "team",
+          "appraisal.view" => "self", "resignation.view" => "self"
+        }
+      },
+      Role::HR => {
+        description: "Day-to-day operations for everyone: attendance, leave, holidays, tickets.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "all", "leave.approve" => "all",
+          "leave.manage" => "all", "attendance.view" => "all", "attendance.manage" => "all",
+          "profile.view" => "all", "payroll.view" => "self",
+          "appraisal.view" => "self", "resignation.view" => "all"
+        }
+      },
+      Role::FINANCE => {
+        description: "Payroll and pay data. No authority over people or policy.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "self",
+          "attendance.view" => "all", "profile.view" => "all",
+          "payroll.view" => "all", "payroll.manage" => "all", "payroll.export" => "all",
+          "salary.view" => "all", "salary.manage" => "all",
+          "audit.view" => "all", "audit.view_money" => "all"
+        }
+      },
+      Role::LEADERSHIP => {
+        description: "People and policy for everyone — deliberately NOT pay.",
+        grants: {
+          "leave.request" => "self", "leave.view" => "all", "leave.approve" => "all",
+          "leave.manage" => "all", "attendance.view" => "all", "attendance.manage" => "all",
+          "profile.view" => "all", "profile.manage" => "all",
+          "resignation.view" => "all", "resignation.manage" => "all",
+          "settings.manage" => "all", "audit.view" => "all", "payroll.view" => "self"
+        }
+      },
+      Role::SUPER_ADMIN => {
+        description: "Everything, including pay, appraisals and who holds which role.",
+        grants: Permissions::KEYS.to_h { |key| [ key, "all" ] }
+      }
+      }.freeze
+    end
+
+    # Creates any role that does not exist yet and leaves every existing one
+    # exactly as the install has tuned it — the same contract as the leave-type
+    # seed. Returns the names it created.
+    def self.call
+      definitions.filter_map do |name, definition|
+        next if Role.exists?(name: name)
+
+        role = Role.create!(name: name, description: definition[:description], system: true)
+        role.replace_grants!(definition[:grants])
+        name
+      end
+    end
+  end
+end

data/lib/hr_lite/version.rb

@@ -1,3 +1,3 @@
 module HrLite
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

data/lib/hr_lite.rb

@@ -4,6 +4,8 @@ require "hr_lite/configuration"
 require "hr_lite/current"
 require "hr_lite/leave_year"
 require "hr_lite/financial_year"
+require "hr_lite/permissions"
+require "hr_lite/role_seeds"
 require "hr_lite/mention_parser"
 require "hr_lite/notifications"
 require "hr_lite/seeds"
@@ -31,16 +33,49 @@ module HrLite
       config.user_class.constantize
     end
 
+    # --- authorization -----------------------------------------------------
+
+    # The question every gate now asks. `scope:` is what the CALLER needs;
+    # a holder with a wider scope satisfies it.
+    def can?(user, key, scope: :self)
+      Access.for(user).can?(key, scope: scope)
+    end
+
+    # Whether `user` may exercise `key` over `subject`'s rows. This is the
+    # question that did not exist before roles, and its absence is why any
+    # admin could approve anybody's leave.
+    def reaches?(user, key, subject)
+      Access.for(user).reaches?(key, subject)
+    end
+
+    def access_for(user) = Access.for(user)
+
+    # --- legacy tier predicates --------------------------------------------
+    #
+    # Kept because views, hosts and the notification fan-out all call them.
+    # They are now READ OFF ROLES rather than off a mutable email column; the
+    # configured lambdas survive only as an explicit opt-in for a host that
+    # has not migrated yet (see Configuration#legacy_tier_checks).
+
     def admin?(user)
-      user.present? && !!config.admin_check.call(user)
+      return false if user.blank?
+      return !!config.admin_check.call(user) if config.legacy_tier_checks
+
+      can?(user, "leave.approve", scope: :all) || can?(user, "attendance.manage", scope: :all)
     end
 
     def leadership?(user)
-      user.present? && !!config.leadership_check.call(user)
+      return false if user.blank?
+      return !!config.leadership_check.call(user) if config.legacy_tier_checks
+
+      can?(user, "profile.manage", scope: :all)
     end
 
     def superadmin?(user)
-      user.present? && !!config.superadmin_check.call(user)
+      return false if user.blank?
+      return !!config.superadmin_check.call(user) if config.legacy_tier_checks
+
+      can?(user, "payroll.manage", scope: :all)
     end
 
     # An access list, cleaned. "a@x.com,,b@x.com".split(",") — one stray
@@ -60,21 +95,39 @@ module HrLite
     end
 
     # Leadership members resolvable to actual user records (for bell
-    # notifications). Emails configured but absent from the user table are
-    # still reachable by email — see Notifications.
+    # notifications). On a legacy host, emails configured but absent from the
+    # user table are still reachable by email — see Notifications.
     def leadership_users
+      unless config.legacy_tier_checks
+        return users_holding("profile.manage", scope: :all)
+      end
+
       emails = normalize_email_list(config.leadership_emails)
       return user_klass.none if emails.empty?
 
       user_klass.where("LOWER(#{user_klass.table_name}.email) IN (?)", emails)
     end
 
-    # Every domain event that bells the admins calls this. Loading and
-    # instantiating the entire users table to run admin_check per row is fine
-    # at ten staff and silly at a thousand — so it starts from employees_scope
-    # (which a host narrows to real staff) rather than every row that exists.
+    # Everyone whose roles grant `key` at `scope` or wider. One query over
+    # the grant tables rather than instantiating every user and asking.
+    def users_holding(key, scope: :all)
+      wide = Permissions::SCOPE_RANK.select { |_, rank| rank >= Permissions::SCOPE_RANK.fetch(scope) }
+      ids = RoleAssignment.joins(role: :role_grants)
+                          .where(hr_lite_role_grants: {
+                            permission_key: Permissions.validate!(key), scope: wide.keys.map(&:to_s)
+                          })
+                          .distinct.pluck(:user_id)
+      user_klass.where(id: ids)
+    end
+
+    # Every domain event that bells the admins calls this. On roles it is one
+    # query over the grant tables; on a legacy host it still has to run the
+    # host's lambda per row, which is why it starts from employees_scope
+    # (narrowed to real staff) rather than every row that exists.
     def admin_users
-      employees.select { |u| admin?(u) }
+      return employees.select { |u| admin?(u) } if config.legacy_tier_checks
+
+      users_holding("leave.approve", scope: :all).sort_by { |u| display_name(u).downcase }
     end
 
     # Everyone HR tracks (host-overridable to exclude bots/test accounts),

data/lib/tasks/hr_lite_tasks.rake

@@ -1,8 +1,16 @@
 namespace :hr_lite do
-  desc "Idempotently seed HR reference data (leave types, national holidays)"
+  desc "Idempotently seed HR reference data (leave types, national holidays, roles)"
   task seed: :environment do
     require "hr_lite/seeds"
-    created = HrLite::Seeds.run!
+    require "hr_lite/role_seeds"
+    created = HrLite::Seeds.run! + HrLite::RoleSeeds.call
     puts created.any? ? "hr_lite:seed created: #{created.join(', ')}" : "hr_lite:seed — nothing to do"
   end
+
+  desc "Idempotently seed the built-in roles only (never overwrites a tuned role)"
+  task roles: :environment do
+    require "hr_lite/role_seeds"
+    created = HrLite::RoleSeeds.call
+    puts created.any? ? "hr_lite:roles created: #{created.join(', ')}" : "hr_lite:roles — nothing to do"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hr_lite
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - kshitiz sinha
@@ -72,6 +72,8 @@ files:
 - app/controllers/hr_lite/admin/payroll_runs_controller.rb
 - app/controllers/hr_lite/admin/regularization_requests_controller.rb
 - app/controllers/hr_lite/admin/resignations_controller.rb
+- app/controllers/hr_lite/admin/role_assignments_controller.rb
+- app/controllers/hr_lite/admin/roles_controller.rb
 - app/controllers/hr_lite/admin/salary_slips_controller.rb
 - app/controllers/hr_lite/admin/salary_structures_controller.rb
 - app/controllers/hr_lite/admin/settings_controller.rb
@@ -120,9 +122,13 @@ files:
 - app/models/hr_lite/payroll_run.rb
 - app/models/hr_lite/regularization_request.rb
 - app/models/hr_lite/resignation.rb
+- app/models/hr_lite/role.rb
+- app/models/hr_lite/role_assignment.rb
+- app/models/hr_lite/role_grant.rb
 - app/models/hr_lite/salary_slip.rb
 - app/models/hr_lite/salary_structure.rb
 - app/models/hr_lite/setting.rb
+- app/services/hr_lite/access.rb
 - app/services/hr_lite/attendance_puncher.rb
 - app/services/hr_lite/attendance_summary.rb
 - app/services/hr_lite/calculators/esi.rb
@@ -170,6 +176,10 @@ files:
 - app/views/hr_lite/admin/payroll_runs/show.html.erb
 - app/views/hr_lite/admin/regularization_requests/index.html.erb
 - app/views/hr_lite/admin/regularization_requests/show.html.erb
+- app/views/hr_lite/admin/roles/_form.html.erb
+- app/views/hr_lite/admin/roles/edit.html.erb
+- app/views/hr_lite/admin/roles/index.html.erb
+- app/views/hr_lite/admin/roles/new.html.erb
 - app/views/hr_lite/admin/salary_slips/show.html.erb
 - app/views/hr_lite/admin/salary_structures/_form.html.erb
 - app/views/hr_lite/admin/salary_structures/edit.html.erb
@@ -243,6 +253,8 @@ files:
 - db/migrate/20260807184426_add_fy_opening_to_hr_lite_employee_profiles.rb
 - db/migrate/20260807184939_add_out_of_window_days_to_hr_lite_salary_slips.rb
 - db/migrate/20260817182124_add_status_constraints_and_appraisal_fk_to_hr_lite.rb
+- db/migrate/20260817183347_create_hr_lite_roles_and_grants.rb
+- db/migrate/20260817183629_seed_hr_lite_roles_from_email_tiers.rb
 - lib/generators/hr_lite/install/install_generator.rb
 - lib/generators/hr_lite/install/templates/AFTER_INSTALL
 - lib/generators/hr_lite/install/templates/initializer.rb
@@ -257,6 +269,8 @@ files:
 - lib/hr_lite/mention_parser.rb
 - lib/hr_lite/money.rb
 - lib/hr_lite/notifications.rb
+- lib/hr_lite/permissions.rb
+- lib/hr_lite/role_seeds.rb
 - lib/hr_lite/seeds.rb
 - lib/hr_lite/statutory_rate_card.rb
 - lib/hr_lite/version.rb