hr_lite 0.5.3 → 0.6.0

data/app/controllers/hr_lite/application_controller.rb

@@ -10,10 +10,48 @@ module HrLite
     before_action :hr_set_current_actor
     around_action :hr_use_time_zone
 
-    helper_method :hr_current_user, :hr_admin?, :hr_leadership?, :hr_superadmin?, :hr_display_name
+    helper_method :hr_current_user, :hr_admin?, :hr_leadership?, :hr_superadmin?, :hr_display_name,
+                  :hr_can?, :hr_reaches?, :hr_access
 
     private
 
+    # --- authorization -----------------------------------------------------
+
+    def hr_access
+      HrLite::Access.for(hr_current_user)
+    end
+
+    # May the signed-in person do this at all, at `scope` or wider?
+    def hr_can?(key, scope: :self)
+      hr_access.can?(key, scope: scope)
+    end
+
+    # May they do it to THIS person's records? The question the module could
+    # not ask before roles, and whose absence let any admin approve anybody's
+    # leave.
+    def hr_reaches?(key, subject_user)
+      hr_access.reaches?(key, subject_user)
+    end
+
+    # Gate a whole controller or action. `scope` is the weakest scope that can
+    # reach the screen at all — a manager reaching a team screen still has
+    # every ROW checked separately by `hr_require_reach!`.
+    def hr_require_permission!(key, scope: :self)
+      hr_access_denied unless hr_can?(key, scope: scope)
+    end
+
+    # Gate one record. Deliberately a 404, not a 403: whether a particular
+    # person exists is not something a stranger gets to learn from us.
+    def hr_require_reach!(key, subject_user)
+      raise ActiveRecord::RecordNotFound unless hr_reaches?(key, subject_user)
+    end
+
+    # Narrow a relation to the rows this permission reaches, so an index
+    # never renders a row the member action would refuse.
+    def hr_scope(relation, key, column: :user_id)
+      hr_access.scope_relation(relation, key, column: column)
+    end
+
     def hr_authenticate!
       send(HrLite.config.authenticate_method)
     end

data/app/helpers/hr_lite/application_helper.rb

@@ -24,9 +24,12 @@ module HrLite
       { label: "Audit",     path: :admin_audit_logs_path,       match: [ "/admin/audit_logs" ] }
     ].freeze
 
-    # Money tier — only config.superadmin_emails see these.
+    # Money screens, plus role management: granting somebody payroll is the
+    # same act as holding it, so it sits with the pay rather than with the
+    # other governing screens.
     SUPERADMIN_NAV_ITEMS = [
-      { label: "Payroll", path: :admin_payroll_runs_path, match: [ "/admin/payroll_runs", "/admin/salary_slips" ] }
+      { label: "Payroll", path: :admin_payroll_runs_path, match: [ "/admin/payroll_runs", "/admin/salary_slips" ] },
+      { label: "Roles",   path: :admin_roles_path,        match: [ "/admin/roles" ] }
     ].freeze
 
     # Only items whose routes exist yet (the nav grows with each phase).

data/app/models/hr_lite/role.rb

@@ -0,0 +1,66 @@
+module HrLite
+  # A named bundle of grants. Roles are DATA — the seeded six are a starting
+  # point an install is expected to edit, not a fixed ladder in code.
+  class Role < ApplicationRecord
+    include Audited
+
+    # Seeded by name. `Employee` in particular is load-bearing: it is what a
+    # new hire is given so that self-service works on day one.
+    EMPLOYEE = "Employee".freeze
+    MANAGER = "Manager".freeze
+    HR = "HR".freeze
+    FINANCE = "Finance".freeze
+    LEADERSHIP = "Leadership".freeze
+    SUPER_ADMIN = "Super Admin".freeze
+
+    has_many :role_grants, dependent: :destroy
+    has_many :role_assignments, dependent: :destroy
+
+    validates :name, presence: true, uniqueness: { case_sensitive: false }
+    before_destroy :protect_system_role
+    validate :system_role_keeps_its_name, on: :update
+
+    scope :alphabetical, -> { order(:name) }
+
+    # Every key this role grants, mapped to its scope. The shape the access
+    # resolver merges.
+    def grant_map
+      role_grants.to_h { |grant| [ grant.permission_key, grant.scope ] }
+    end
+
+    # Replaces the whole grant set in one transaction — the roles screen posts
+    # the complete picture, so a permission absent from the form is a
+    # permission being taken away, not one left alone.
+    def replace_grants!(grants)
+      transaction do
+        role_grants.destroy_all
+        grants.each do |key, scope|
+          next if scope.blank? || scope.to_s == "none"
+
+          role_grants.create!(permission_key: Permissions.validate!(key), scope: scope.to_s)
+        end
+      end
+      reload
+    end
+
+    def system? = self[:system]
+
+    private
+
+    def protect_system_role
+      return unless system?
+
+      errors.add(:base, "#{name} is a built-in role and cannot be deleted")
+      throw :abort
+    end
+
+    # The name is the identifier the seed, the upgrade path and the specs all
+    # use. Permissions on a system role are free to change; what it is called
+    # is not.
+    def system_role_keeps_its_name
+      return unless system? && name_changed?
+
+      errors.add(:name, "cannot be changed on a built-in role")
+    end
+  end
+end

data/app/models/hr_lite/role_assignment.rb

@@ -0,0 +1,18 @@
+module HrLite
+  # Who holds which role. Assignments are audited because granting somebody
+  # the money tier is exactly the kind of change that has to be explainable
+  # afterwards.
+  class RoleAssignment < ApplicationRecord
+    include Audited
+
+    belongs_to :role
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :granted_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :user_id, uniqueness: { scope: :role_id }
+
+    scope :for_user, ->(user) { where(user_id: user.id) }
+
+    def hr_lite_audit_label = "#{HrLite.display_name(user)} — #{role.name}"
+  end
+end

data/app/models/hr_lite/role_grant.rb

@@ -0,0 +1,15 @@
+module HrLite
+  # One (role, permission, scope) triple. The permission key is validated
+  # against the declared registry, so a typo is a refused write rather than a
+  # grant that silently never matches anything.
+  class RoleGrant < ApplicationRecord
+    belongs_to :role
+
+    validates :permission_key, presence: true,
+                               inclusion: { in: Permissions::KEYS, message: "is not a known permission" },
+                               uniqueness: { scope: :role_id }
+    validates :scope, inclusion: { in: Permissions::SCOPES.map(&:to_s) }
+
+    def covers?(needed_scope) = Permissions.scope_covers?(scope, needed_scope)
+  end
+end

data/app/services/hr_lite/access.rb

@@ -0,0 +1,111 @@
+module HrLite
+  # The one place that answers "may this person do this, and to whose rows".
+  #
+  # Two questions, deliberately separated:
+  #
+  #   can?(user, "leave.approve")            — may they at all, at any scope
+  #   scope_for(user, "leave.approve")       — :self, :team, :all or nil
+  #   reaches?(user, "leave.approve", other) — may they, for THIS person
+  #
+  # A controller that only asks the first question is the bug this class
+  # exists to prevent: before roles, any admin could approve anybody's leave
+  # because nothing ever asked whose leave it was.
+  class Access
+    # Resolution touches three tables and every screen asks several times per
+    # request, so it is memoized per user for the life of the request.
+    def self.for(user)
+      # An unsaved user holds nothing: roles are rows keyed by user id, and
+      # there is no id yet to key them by.
+      return new(nil, {}) if user.nil? || user.id.nil?
+
+      Current.access_cache ||= {}
+      Current.access_cache[user.id] ||= new(user, resolve(user))
+    end
+
+    # The strongest scope held for each key across all of the user's roles.
+    # Two roles granting the same key keep the WIDER of the two — roles add
+    # up, they do not narrow each other.
+    def self.resolve(user)
+      grants = RoleGrant.joins(role: :role_assignments)
+                        .where(hr_lite_role_assignments: { user_id: user.id })
+                        .pluck(:permission_key, :scope)
+
+      grants.each_with_object({}) do |(key, scope), map|
+        held = map[key]
+        map[key] = scope if held.nil? || Permissions.scope_covers?(scope, held)
+      end
+    end
+
+    def initialize(user, permission_map)
+      @user = user
+      @map = permission_map
+    end
+
+    attr_reader :user
+
+    def scope_for(key)
+      @map[Permissions.validate!(key)]&.to_sym
+    end
+
+    def can?(key, scope: :self)
+      held = scope_for(key)
+      held.present? && Permissions.scope_covers?(held, scope)
+    end
+
+    # Whether this permission reaches a particular person's rows. `self`
+    # reaches only the holder; `team` reaches their direct and indirect
+    # reports; `all` reaches everyone.
+    def reaches?(key, subject_user)
+      return false if user.nil? || subject_user.nil?
+
+      case scope_for(key)
+      when :all then true
+      when :team then subject_user.id == user.id || report_ids.include?(subject_user.id)
+      when :self then subject_user.id == user.id
+      else false
+      end
+    end
+
+    # User ids this person's `team` scope covers, for scoping a whole
+    # relation rather than checking one row at a time. `all` returns nil,
+    # meaning "do not filter" — a caller that treats nil as an empty list
+    # would show leadership nothing, so the callers use `scope_relation`.
+    def visible_user_ids(key)
+      case scope_for(key)
+      when :all then nil
+      when :team then [ user.id, *report_ids ]
+      when :self then [ user.id ]
+      else []
+      end
+    end
+
+    # Narrows a relation to the rows this permission reaches. The column is
+    # named because not every table calls it user_id.
+    def scope_relation(relation, key, column: :user_id)
+      ids = visible_user_ids(key)
+      ids.nil? ? relation : relation.where(column => ids)
+    end
+
+    # Everyone below this person in the reporting chain. Walked breadth-first
+    # with a seen set — EmployeeProfile validates the chain is acyclic, but a
+    # cycle written directly to the database must not spin here forever.
+    def report_ids
+      @report_ids ||= begin
+        by_manager = EmployeeProfile.where.not(manager_id: nil).pluck(:manager_id, :user_id)
+                                    .group_by(&:first)
+                                    .transform_values { |pairs| pairs.map(&:last) }
+        found = []
+        seen = [ user.id ].to_set
+        queue = by_manager[user.id]&.dup || []
+
+        while (id = queue.shift)
+          next unless seen.add?(id)
+
+          found << id
+          queue.concat(by_manager[id] || [])
+        end
+        found
+      end
+    end
+  end
+end

data/app/views/hr_lite/admin/roles/_form.html.erb

@@ -0,0 +1,47 @@
+<section class="hrl-card">
+  <%= form_with model: role, url: url, method: method, local: true do |f| %>
+    <%= render "hr_lite/shared/form_errors", record: role %>
+
+    <div class="hrl-field">
+      <%= f.label :name %>
+      <% if role.system? %>
+        <%= f.text_field :name, disabled: true %>
+        <span class="hrl-small hrl-muted">
+          Built-in roles keep their name — the upgrade path and the seed both
+          identify them by it. The permissions below are yours to change.
+        </span>
+      <% else %>
+        <%= f.text_field :name %>
+      <% end %>
+    </div>
+    <div class="hrl-field">
+      <%= f.label :description, "Description (shown on the roles list)" %>
+      <%= f.text_field :description %>
+    </div>
+
+    <% HrLite::Permissions.grouped.each do |group, keys| %>
+      <fieldset>
+        <legend><%= group %></legend>
+        <% keys.each do |key| %>
+          <% held = role.grant_map[key] || "none" %>
+          <div class="hrl-field">
+            <%= label_tag "grants_#{key.tr('.', '_')}", HrLite::Permissions.description(key) %>
+            <%= select_tag "grants[#{key}]",
+                  options_for_select([
+                    [ "Not granted", "none" ],
+                    [ "Their own records", "self" ],
+                    [ "Their team's records", "team" ],
+                    [ "Everyone's records", "all" ]
+                  ], held),
+                  id: "grants_#{key.tr('.', '_')}" %>
+          </div>
+        <% end %>
+      </fieldset>
+    <% end %>
+
+    <div class="hrl-form-actions">
+      <%= f.submit "Save", class: "hrl-btn hrl-btn--primary" %>
+      <a class="hrl-btn" href="<%= hr_lite.admin_roles_path %>">Cancel</a>
+    </div>
+  <% end %>
+</section>

data/app/views/hr_lite/admin/roles/edit.html.erb

@@ -0,0 +1,53 @@
+<% content_for(:page_title) { @role.name } %>
+<div class="hrl-page__head">
+  <h1 class="hrl-page__title"><%= @role.name %></h1>
+  <% unless @role.system? %>
+    <div class="hrl-page__actions">
+      <%= button_to "Delete role", hr_lite.admin_role_path(@role), method: :delete,
+            class: "hrl-btn hrl-btn--danger",
+            form: { data: { turbo_confirm: "Delete #{@role.name}? Everyone holding it loses that access." } } %>
+    </div>
+  <% end %>
+</div>
+
+<%= render "form", role: @role, url: hr_lite.admin_role_path(@role), method: :patch %>
+
+<section class="hrl-card">
+  <h2 class="hrl-card__title">Who holds this role</h2>
+  <% assignments = @role.role_assignments.includes(:user).sort_by { |a| hr_display_name(a.user).downcase } %>
+  <% if assignments.empty? %>
+    <p class="hrl-muted">Nobody yet.</p>
+  <% else %>
+    <div class="hrl-table-wrap">
+      <table class="hrl-table hrl-table--stack">
+        <thead><tr><th>Person</th><th>Added</th><th></th></tr></thead>
+        <tbody>
+          <% assignments.each do |assignment| %>
+            <tr>
+              <td data-label="Person"><%= hr_display_name(assignment.user) %></td>
+              <td data-label="Added"><%= assignment.created_at.to_date.strftime("%d %b %Y") %></td>
+              <td data-label="">
+                <%= button_to "Remove", hr_lite.admin_role_assignment_path(@role, assignment),
+                      method: :delete, class: "hrl-btn",
+                      form: { data: { turbo_confirm: "Remove #{hr_display_name(assignment.user)} from #{@role.name}?" } } %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+
+  <%= form_with url: hr_lite.admin_role_assignments_path(@role), method: :post, local: true do %>
+    <div class="hrl-field">
+      <%= label_tag :user_id, "Add somebody to this role" %>
+      <% held = @role.role_assignments.map(&:user_id) %>
+      <%= select_tag :user_id,
+            options_for_select(HrLite.employees.reject { |u| held.include?(u.id) }
+                                     .map { |u| [ hr_display_name(u), u.id ] }) %>
+    </div>
+    <div class="hrl-form-actions">
+      <%= submit_tag "Add", class: "hrl-btn hrl-btn--primary" %>
+    </div>
+  <% end %>
+</section>

data/app/views/hr_lite/admin/roles/index.html.erb

@@ -0,0 +1,49 @@
+<% content_for(:page_title) { "Roles" } %>
+<div class="hrl-page__head">
+  <h1 class="hrl-page__title">Roles &amp; permissions</h1>
+  <div class="hrl-page__actions">
+    <a class="hrl-btn hrl-btn--primary" href="<%= hr_lite.new_admin_role_path %>">Add role</a>
+  </div>
+</div>
+
+<section class="hrl-card">
+  <p class="hrl-muted hrl-small">
+    A permission is what somebody may do; its scope is whose records they may
+    do it to — only their own, their reports', or everyone's.
+  </p>
+  <div class="hrl-table-wrap">
+    <table class="hrl-table hrl-table--stack">
+      <thead><tr><th>Role</th><th>People</th><th>Reaches</th><th></th></tr></thead>
+      <tbody>
+        <% @roles.each do |role| %>
+          <tr>
+            <td data-label="Role">
+              <strong><%= role.name %></strong>
+              <% if role.system? %><span class="hrl-badge hrl-badge--muted">Built-in</span><% end %>
+              <% if role.description.present? %>
+                <div class="hrl-small hrl-muted"><%= role.description %></div>
+              <% end %>
+            </td>
+            <td data-label="People" class="hrl-num"><%= role.role_assignments.size %></td>
+            <td data-label="Reaches">
+              <% company_wide = role.role_grants.count { |g| g.scope == "all" } %>
+              <% team = role.role_grants.count { |g| g.scope == "team" } %>
+              <%= role.role_grants.size %> permission<%= "s" unless role.role_grants.size == 1 %>
+              <%# Joined rather than concatenated: a role with team grants and
+                  no company-wide ones rendered a leading "·" with nothing
+                  in front of it. %>
+              <% reach = [ ("#{company_wide} company-wide" if company_wide.positive?),
+                           ("#{team} own team" if team.positive?) ].compact %>
+              <% if reach.any? %>
+                <span class="hrl-small hrl-muted"><%= reach.join(" · ") %></span>
+              <% end %>
+            </td>
+            <td data-label="">
+              <a class="hrl-small" href="<%= hr_lite.edit_admin_role_path(role) %>">Edit</a>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</section>

data/app/views/hr_lite/admin/roles/new.html.erb

@@ -0,0 +1,3 @@
+<% content_for(:page_title) { "New role" } %>
+<div class="hrl-page__head"><h1 class="hrl-page__title">New role</h1></div>
+<%= render "form", role: @role, url: hr_lite.admin_roles_path, method: :post %>

data/config/routes.rb

@@ -46,6 +46,9 @@ HrLite::Engine.routes.draw do
     resources :regularization_requests, only: %i[index show] do
       member { post :approve; post :reject }
     end
+    resources :roles, except: :show do
+      resources :assignments, only: %i[create destroy], controller: "role_assignments"
+    end
     resources :leave_types, except: :show
     resources :office_locations, except: :show
     resources :holidays, only: %i[index create update destroy] do

data/db/migrate/20260817183347_create_hr_lite_roles_and_grants.rb

@@ -0,0 +1,49 @@
+class CreateHrLiteRolesAndGrants < ActiveRecord::Migration[8.1]
+  # Roles replace the three configured lambdas (admin_check, leadership_emails,
+  # superadmin_emails). Two of those matched a MUTABLE email string — a
+  # permission stored in a column the host lets people edit.
+  #
+  # Permissions themselves are not a table: the vocabulary is declared in
+  # HrLite::Permissions::REGISTRY, so a grant is a (role, key, scope) row and
+  # an unknown key cannot be stored. That keeps seeding idempotent, and makes
+  # retiring a permission a code change with a spec rather than silent data.
+  def change
+    create_table :hr_lite_roles do |t|
+      t.string :name, null: false
+      t.string :description
+      # Roles the engine seeds and refers to by name. Renaming or deleting one
+      # is refused by the model — the upgrade path off the email lists lands
+      # people in these, and the roles screen has to keep meaning something.
+      t.boolean :system, null: false, default: false
+      t.timestamps
+    end
+    add_index :hr_lite_roles, :name, unique: true
+
+    create_table :hr_lite_role_grants do |t|
+      t.references :role, null: false, index: false,
+                   foreign_key: { to_table: :hr_lite_roles, on_delete: :cascade }
+      t.string :permission_key, null: false
+      # self | team | all — see HrLite::Permissions. Stored per grant so one
+      # key covers "own leave", "my reports' leave" and "everyone's leave".
+      t.string :scope, null: false, default: "self"
+      t.timestamps
+    end
+    # One scope per (role, permission): a role either reaches a set of rows or
+    # it does not, and two rows for one key would make that a lookup race.
+    add_index :hr_lite_role_grants, %i[role_id permission_key], unique: true
+    add_check_constraint :hr_lite_role_grants, "scope IN ('self', 'team', 'all')",
+                         name: "hr_lite_role_grants_scope_check"
+
+    create_table :hr_lite_role_assignments do |t|
+      # No FK to the host user table — its name is host-specific, the same
+      # reason every other user_id in this engine is a bare bigint.
+      t.bigint :user_id, null: false
+      t.references :role, null: false, index: false,
+                   foreign_key: { to_table: :hr_lite_roles, on_delete: :cascade }
+      t.bigint :granted_by_id
+      t.timestamps
+    end
+    add_index :hr_lite_role_assignments, %i[user_id role_id], unique: true
+    add_index :hr_lite_role_assignments, :role_id
+  end
+end

data/db/migrate/20260817183629_seed_hr_lite_roles_from_email_tiers.rb

@@ -0,0 +1,82 @@
+class SeedHrLiteRolesFromEmailTiers < ActiveRecord::Migration[8.1]
+  # The upgrade path off the email lists. On an install that is already
+  # running, this is the migration that decides whether anyone loses access,
+  # so it is deliberately generous: everybody who could reach something
+  # before can reach at least as much afterwards.
+  #
+  #   config.superadmin_emails  -> Super Admin
+  #   config.leadership_emails  -> Leadership
+  #   admin_check == true       -> HR
+  #   everybody else            -> Employee
+  #
+  # It reads the host's OWN configuration, so nothing has to be typed twice,
+  # and it says out loud what it did — an upgrade that silently grants the
+  # money tier to the wrong person is the failure worth being loud about.
+  def up
+    require "hr_lite/role_seeds"
+    created = HrLite::RoleSeeds.call
+    say "Seeded roles: #{created.join(', ')}" if created.any?
+
+    # A host that has already assigned roles by hand is not re-derived from
+    # email lists — that would undo their work.
+    if HrLite::RoleAssignment.exists?
+      say "Role assignments already exist — leaving them alone."
+      return
+    end
+
+    roles = HrLite::Role.where(name: [
+      HrLite::Role::EMPLOYEE, HrLite::Role::HR,
+      HrLite::Role::LEADERSHIP, HrLite::Role::SUPER_ADMIN
+    ]).index_by(&:name)
+
+    # The legacy predicates, read directly rather than through HrLite.admin?
+    # — which by now answers off roles, and would say no to everyone.
+    superadmins = HrLite.normalize_email_list(HrLite.config.superadmin_emails)
+    leaders = HrLite.normalize_email_list(HrLite.config.leadership_emails)
+    # Pre-0.5.0 behaviour, still live on hosts that never set the money list:
+    # an empty superadmin list meant "the same people as leadership".
+    superadmins = leaders if superadmins.empty?
+
+    assigned = Hash.new { |hash, key| hash[key] = [] }
+
+    HrLite.config.employees_scope.call.find_each do |user|
+      address = user.respond_to?(:email) ? user.email.to_s.downcase.strip : ""
+      names = [ HrLite::Role::EMPLOYEE ]
+      names << HrLite::Role::SUPER_ADMIN if address.present? && superadmins.include?(address)
+      names << HrLite::Role::LEADERSHIP if address.present? && leaders.include?(address)
+      names << HrLite::Role::HR if legacy_admin?(user)
+
+      names.uniq.each do |name|
+        role = roles[name] or next
+
+        HrLite::RoleAssignment.create!(user_id: user.id, role: role)
+        assigned[name] << HrLite.display_name(user)
+      end
+    end
+
+    if assigned.empty?
+      say "No users matched employees_scope — assign roles from the Roles screen."
+    else
+      assigned.each { |name, people| say "#{name}: #{people.sort.join(', ')}" }
+    end
+    say "Set `config.legacy_tier_checks = true` to keep the old email lists in " \
+        "charge for now; it is honoured until 0.7.0."
+  end
+
+  # Assignments only — the roles themselves stay, because dropping them would
+  # take every hand-made grant with them.
+  def down
+    HrLite::RoleAssignment.delete_all
+  end
+
+  private
+
+  # admin_check is a host lambda over the host's own user model; a host whose
+  # users do not answer it must not break the whole upgrade.
+  def legacy_admin?(user)
+    !!HrLite.config.admin_check.call(user)
+  rescue StandardError => e
+    say "admin_check raised for #{HrLite.display_name(user)} (#{e.class}) — treated as not HR."
+    false
+  end
+end

data/lib/generators/hr_lite/install/templates/initializer.rb

@@ -7,13 +7,19 @@ HrLite.configure do |c|
   c.current_user_method = :current_user
   c.authenticate_method = :authenticate_user!
 
-  # Operations tier (team attendance, leave decisions, overview board).
-  c.admin_check = ->(user) { user.respond_to?(:admin?) && user.admin? }
-
-  # Governing tier — ONLY these people change policy, employee profiles,
-  # salary structures, payroll and appraisals. Keep it in an env var so
-  # changing leadership never needs a deploy.
-  c.leadership_emails = ENV.fetch("HR_LEADERSHIP_EMAILS", "").split(",").map(&:strip)
+  # Access is a role table, not configuration — `rake hr_lite:seed` creates
+  # the built-in roles and you assign people from /admin/roles. The first
+  # person needs Super Admin, which the upgrade migration grants on an
+  # existing install; on a fresh one, from a console:
+  #
+  #   HrLite::RoleAssignment.create!(
+  #     user_id: User.find_by!(email: "you@example.com").id,
+  #     role: HrLite::Role.find_by!(name: HrLite::Role::SUPER_ADMIN))
+  #
+  # Upgrading from pre-0.6.0 and not ready to move? Uncomment this and keep
+  # your leadership_emails / superadmin_emails / admin_check as they were.
+  # It is honoured until 0.7.0.
+  # c.legacy_tier_checks = true
 
   # Where the portal is reachable (subdomain or path). Enables email link
   # buttons and HrLite.public_url / HrLite.public_url? for deep links.

data/lib/hr_lite/configuration.rb

@@ -10,7 +10,8 @@ module HrLite
                   :leadership_emails, :leadership_check, :extra_stylesheets,
                   :superadmin_emails, :superadmin_check,
                   :mailer_from, :public_url_base, :notification_matrix, :back_link,
-                  :onboard_user, :offboard_user, :invite_url_for
+                  :onboard_user, :offboard_user, :invite_url_for,
+                  :legacy_tier_checks
 
     attr_reader :leave_year_start_month
 
@@ -45,6 +46,12 @@ module HrLite
       @time_zone             = "Asia/Kolkata"
       @currency_symbol      = "₹"
       @on_designation_change = ->(user, designation) { }
+      # Access came from three lambdas before 0.6.0, two of which matched the
+      # user's EMAIL — a mutable, host-owned, unverified column that a host
+      # then had to remember never to let anyone edit. Roles replace them.
+      # This flag hands authority back to the old lambdas for a host that has
+      # not finished migrating; honoured for one minor version, gone in 0.7.0.
+      @legacy_tier_checks    = false
       @leadership_emails     = []
       @leadership_check      = ->(user) { HrLite.email_listed?(user, HrLite.config.leadership_emails) }
       # Money tier: salary structures, payroll, slips, appraisals. Empty

data/lib/hr_lite/current.rb

@@ -3,5 +3,9 @@ module HrLite
   # readable from any model callback without threading it through.
   class Current < ActiveSupport::CurrentAttributes
     attribute :actor
+    # Resolved permissions, keyed by user id. Every screen asks several times
+    # per request and resolution joins three tables; CurrentAttributes is
+    # reset between requests, so a role change takes effect on the next one.
+    attribute :access_cache
   end
 end