open-loam 0.1.0

data/lib/generators/loam/install/templates/admin/perspectives_controller.rb

@@ -0,0 +1,98 @@
+module Admin
+  # Managing saved views (Loam::Perspective) for an entity. A view is CREATED by
+  # "save current view" on the entity index (capturing the live filters/sort); it
+  # starts private, owned by you. Here you rename it, widen its audience, make it
+  # the default, or delete it.
+  #
+  # Who may manage a view: its owner always; a manager for role/tenant-visibility
+  # ones. A private view of someone else's is invisible here by construction
+  # (Loam::Perspectives.visible_to never returns it).
+  class PerspectivesController < BaseController
+    before_action :set_perspective, only: %i[update destroy set_default]
+    before_action :authorize_manage!, only: %i[update destroy set_default]
+
+    rescue_from ActiveRecord::StaleObjectError do
+      redirect_to admin_perspectives_path(entity_type: params[:entity_type]),
+                  alert: "Someone else changed that view; nothing was saved. Reload and try again."
+    end
+
+    def index
+      @entity_type = params[:entity_type].to_s
+      @perspectives = Loam::Perspectives.visible_to(@entity_type, user: current_actor)
+    end
+
+    # From the entity index: save the CURRENT filters/sort as a new private view.
+    def create
+      perspective = Loam::Perspective.create!(
+        entity_type: params[:entity_type].to_s,
+        name: params[:name].presence || "Saved view",
+        visibility: "private",
+        owner_id: current_actor.id,
+        config: captured_config
+      )
+      redirect_to index_path_for(perspective), notice: "Saved the current view."
+    end
+
+    def update
+      # Widening a private view to role/tenant is a manager action; and changing
+      # the audience clears the default flag so it is re-chosen deliberately.
+      attributes = perspective_params
+      if attributes[:visibility].present? && attributes[:visibility] != @perspective.visibility
+        raise Loam::NotAuthorizedError if attributes[:visibility] != "private" && current_role != :manager
+
+        attributes[:is_default] = false
+      end
+
+      if @perspective.update(attributes)
+        redirect_to index_path_for(@perspective), notice: "View updated."
+      else
+        redirect_to index_path_for(@perspective), alert: @perspective.errors.full_messages.to_sentence
+      end
+    end
+
+    def set_default
+      @perspective.make_default!
+      redirect_to index_path_for(@perspective), notice: "Default view set."
+    end
+
+    def destroy
+      perspective = @perspective
+      perspective.destroy!
+      redirect_to index_path_for(perspective), notice: "View deleted."
+    end
+
+    private
+
+    def set_perspective
+      @perspective = Loam::Perspective.find(params[:id])
+    end
+
+    def authorize_manage!
+      raise Loam::NotAuthorizedError unless can_manage?(@perspective)
+    end
+
+    # Owner always; a manager for shared (role/tenant) views. A private view of
+    # another user is never even loaded here, so this only guards shared ones.
+    def can_manage?(perspective)
+      perspective.owner_id == current_actor.id || (perspective.visibility != "private" && current_role == :manager)
+    end
+
+    def perspective_params
+      params.require(:perspective).permit(:name, :visibility, :role)
+    end
+
+    # Config is built from the index's live params, never from trusted raw JSON.
+    # apply() whitelists columns regardless, so nothing here can smuggle a filter
+    # onto a plumbing column.
+    def captured_config
+      {
+        "filters" => { "q" => params[:q].presence }.compact,
+        "sort" => { "field" => params[:sort_field].presence, "dir" => params[:sort_dir].presence }.compact
+      }.reject { |_, value| value.blank? }
+    end
+
+    def index_path_for(perspective)
+      admin_perspectives_path(entity_type: perspective.entity_type)
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/perspectives_index.html.erb

@@ -0,0 +1,38 @@
+<h1>Saved views — <%%= @entity_type %></h1>
+
+<p>Named views of the <%%= @entity_type %> list. Save one from the <%%= @entity_type %>
+index; here you rename it, share it (widen its audience), make it the default,
+or delete it.</p>
+
+<%% if @perspectives.empty? %>
+  <p>No saved views yet.</p>
+<%% end %>
+
+<table>
+  <thead>
+    <tr><th>Name</th><th>Visibility</th><th>Default</th><th>Owner</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @perspectives.each do |perspective| %>
+      <tr>
+        <td><%%= perspective.name %></td>
+        <td><%%= perspective.visibility %><%%= " (#{perspective.role})" if perspective.role.present? %></td>
+        <td><%%= "default" if perspective.is_default? %></td>
+        <td><%%= User.find_by(id: perspective.owner_id)&.name || "—" %></td>
+        <td>
+          <%%# Only manageable views (yours, or shared ones if you're a manager) get controls. %>
+          <%% if perspective.owner_id == current_actor.id || (perspective.visibility != "private" && current_role == :manager) %>
+            <%%= form_with url: admin_perspective_path(perspective, entity_type: @entity_type), method: :patch, class: "inline" do %>
+              <%%= text_field_tag :"perspective[name]", perspective.name, size: 16 %>
+              <%%= select_tag :"perspective[visibility]", options_for_select(Loam::Perspective::VISIBILITIES, perspective.visibility) %>
+              <%%= text_field_tag :"perspective[role]", perspective.role, placeholder: "role", size: 8 %>
+              <%%= submit_tag "Save" %>
+            <%% end %>
+            <%%= button_to "Make default", set_default_admin_perspective_path(perspective, entity_type: @entity_type), form: { style: "display:inline" } %>
+            <%%= button_to "Delete", admin_perspective_path(perspective, entity_type: @entity_type), method: :delete, form: { style: "display:inline" } %>
+          <%% end %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/progress_jobs_controller.rb

@@ -0,0 +1,19 @@
+module Admin
+  # Long-running task progress (Loam::ProgressJob) — a tenant-scoped list of
+  # recent jobs with a live bar (the loam.progress.updated SSE event updates it).
+  # Your app starts jobs with Loam::Progress.start in its own background jobs;
+  # a running one can be cancelled cooperatively here.
+  class ProgressJobsController < BaseController
+    def index
+      @jobs = Loam::ProgressJob.recent.limit(20)
+    end
+
+    def cancel
+      job = Loam::ProgressJob.find(params[:id])
+      # Manager-or-owner: a member must not cancel another user's job.
+      raise Loam::NotAuthorizedError unless current_role == :manager || job.actor_id == current_actor&.id
+      job.cancel! if job.running?
+      redirect_to admin_progress_jobs_path, notice: "Job cancelled."
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/progress_jobs_index.html.erb

@@ -0,0 +1,31 @@
+<h1>Tasks</h1>
+
+<p>Long-running jobs report progress here live (no reload — pushed over SSE).
+Start one from your own code with <code>Loam::Progress.start(name:, total:)</code>.</p>
+
+<table>
+  <thead>
+    <tr><th>Name</th><th>Status</th><th>Progress</th><th>Message</th><th>ETA</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @jobs.each do |job| %>
+      <tr>
+        <td><%%= job.name %><%% if job.stale? %> <em>(stale)</em><%% end %></td>
+        <td><span id="progress-status-<%%= job.id %>"><%%= job.status %></span></td>
+        <td>
+          <div style="background:#eee; width:160px; height:12px; display:inline-block; vertical-align:middle">
+            <div id="progress-fill-<%%= job.id %>" style="background:#2e7d32; height:12px; width:<%%= job.percent %>%"></div>
+          </div>
+          <span id="progress-percent-<%%= job.id %>"><%%= job.percent %>%</span>
+        </td>
+        <td><%%= job.message %></td>
+        <td><%%= job.eta_seconds ? "#{job.eta_seconds}s" : "—" %></td>
+        <td>
+          <%% if job.running? %>
+            <%%= button_to "Cancel", cancel_admin_progress_job_path(job), form: { style: "display:inline" } %>
+          <%% end %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/record_locks_controller.rb

@@ -0,0 +1,17 @@
+module Admin
+  # Manager take-over of an advisory edit lock (Loam::RecordLocks). Only a
+  # manager may force-release someone else's lock; the record it points at is
+  # resolved through a whitelist (a Loam::TenantRecord subclass), never a raw
+  # constantize of user input.
+  class RecordLocksController < BaseController
+    before_action { require_role!(:manager) }
+
+    def destroy
+      klass = params[:lockable_type].to_s.safe_constantize
+      raise Loam::NotAuthorizedError unless klass && klass < Loam::TenantRecord
+
+      Loam::RecordLocks.force_release(klass.find(params[:lockable_id]))
+      redirect_back fallback_location: admin_root_path, notice: "Lock released — you can edit now."
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/scheduled_jobs_controller.rb

@@ -0,0 +1,69 @@
+module Admin
+  # Recurring schedules (Loam::ScheduledJob) — manager-only. List/create/edit/
+  # delete a tenant's schedules, toggle active, and "run now". The runner
+  # (`loam:scheduler:tick`, wired to system cron) is what fires them on schedule.
+  class ScheduledJobsController < BaseController
+    before_action { require_role!(:manager) }
+    before_action :set_job, only: %i[edit update destroy run_now]
+
+    def index
+      @jobs = Loam::ScheduledJob.order(:key)
+    end
+
+    def new
+      @job = Loam::ScheduledJob.new(scope: "tenant", active: true, schedule: "0 3 * * *")
+    end
+
+    def create
+      # scope is forced to "tenant": a tenant admin must never create a
+      # "system" schedule (which would run with no tenant context). System
+      # schedules are created only by the app/console.
+      @job = Loam::ScheduledJob.new(job_params.merge(scope: "tenant"))
+      @job.next_run_at ||= safe_next_run(@job)
+      if @job.save
+        redirect_to admin_scheduled_jobs_path, notice: "Schedule created."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def edit; end
+
+    def update
+      @job.assign_attributes(job_params)
+      @job.next_run_at = safe_next_run(@job) if @job.schedule_changed? || @job.timezone_changed?
+      if @job.save
+        redirect_to admin_scheduled_jobs_path, notice: "Schedule updated."
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @job.destroy!
+      redirect_to admin_scheduled_jobs_path, notice: "Schedule deleted."
+    end
+
+    def run_now
+      Loam::Scheduler.run_now(@job)
+      redirect_to admin_scheduled_jobs_path, notice: "#{@job.name} enqueued."
+    end
+
+    private
+
+    def set_job
+      @job = Loam::ScheduledJob.find(params[:id])
+    end
+
+    def job_params
+      params.require(:scheduled_job).permit(:key, :name, :job_class, :schedule, :timezone, :active)
+    end
+
+    # A malformed cron shouldn't 500 — let validation surface it instead.
+    def safe_next_run(job)
+      job.compute_next_run
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/scheduled_jobs_edit.html.erb

@@ -0,0 +1,5 @@
+<h1>Edit schedule</h1>
+
+<%%= render "form" %>
+
+<p><%%= link_to "Back", admin_scheduled_jobs_path %></p>

data/lib/generators/loam/install/templates/admin/scheduled_jobs_form.html.erb

@@ -0,0 +1,16 @@
+<%%# Loam::ScheduledJob is namespaced, so pin the URL + param scope. %>
+<%%= form_with model: @job, scope: :scheduled_job,
+      url: (@job.persisted? ? admin_scheduled_job_path(@job) : admin_scheduled_jobs_path) do |f| %>
+  <%% if @job.errors.any? %>
+    <ul><%% @job.errors.full_messages.each do |m| %><li><%%= m %></li><%% end %></ul>
+  <%% end %>
+
+  <p><%%= f.label :key %><br><%%= f.text_field :key %></p>
+  <p><%%= f.label :name %><br><%%= f.text_field :name %></p>
+  <p><%%= f.label :job_class, "Job class (an ActiveJob, e.g. DemoScheduledJob)" %><br><%%= f.text_field :job_class %></p>
+  <p><%%= f.label :schedule, "Schedule (cron '0 7 * * *' or 'interval:3600')" %><br><%%= f.text_field :schedule %></p>
+  <p><%%= f.label :timezone, "Timezone (IANA, blank = UTC)" %><br><%%= f.text_field :timezone %></p>
+  <p><%%= f.label :active %> <%%= f.check_box :active %></p>
+
+  <%%= f.submit %>
+<%% end %>

data/lib/generators/loam/install/templates/admin/scheduled_jobs_index.html.erb

@@ -0,0 +1,28 @@
+<h1>Schedules</h1>
+
+<p>Recurring jobs for this tenant. The runner (<code>loam:scheduler:tick</code>,
+wired to system cron) fires them on schedule. <%%= link_to "New schedule", new_admin_scheduled_job_path %></p>
+
+<table>
+  <thead>
+    <tr><th>Key</th><th>Job</th><th>Schedule</th><th>Scope</th><th>Next run</th><th>Last run</th><th>Active</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @jobs.each do |job| %>
+      <tr>
+        <td><%%= job.name %> <small>(<code><%%= job.key %></code>)</small></td>
+        <td><code><%%= job.job_class %></code></td>
+        <td><code><%%= job.schedule %></code><%%= " #{job.timezone}" if job.timezone.present? %></td>
+        <td><%%= job.scope %></td>
+        <td><%%= job.next_run_at&.strftime("%Y-%m-%d %H:%M UTC") %></td>
+        <td><%%= job.last_run_at&.strftime("%Y-%m-%d %H:%M UTC") || "—" %></td>
+        <td><%%= job.active? ? "yes" : "no" %></td>
+        <td>
+          <%%= button_to "Run now", run_now_admin_scheduled_job_path(job), form: { style: "display:inline" } %>
+          <%%= link_to "Edit", edit_admin_scheduled_job_path(job) %>
+          <%%= button_to "Delete", admin_scheduled_job_path(job), method: :delete, form: { style: "display:inline" } %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/scheduled_jobs_new.html.erb

@@ -0,0 +1,5 @@
+<h1>New schedule</h1>
+
+<%%= render "form" %>
+
+<p><%%= link_to "Back", admin_scheduled_jobs_path %></p>

data/lib/generators/loam/install/templates/admin/search_controller.rb

@@ -0,0 +1,49 @@
+module Admin
+  # One box, every entity. Results are grouped by entity and limited per group,
+  # so a broad query stays readable and cheap.
+  #
+  # Tenant isolation needs no work here: each model's `search` returns its own
+  # tenant-scoped relation, so this can only ever find records the current
+  # tenant owns.
+  class SearchController < BaseController
+    PER_ENTITY = 10
+
+    helper_method :search_result_label
+
+    def index
+      @query = params[:q].to_s.strip
+      @results = @query.blank? ? {} : search_all(@query)
+    end
+
+    # The first searchable column that has a value, plus the id — enough to
+    # recognise a record without Loam having to know what a "title" is.
+    def search_result_label(record)
+      value = record.class.loam_searchable_columns.filter_map { |column| record.public_send(column).presence }.first
+
+      [ value || record.model_name.human, "##{record.id}" ].join(" ")
+    end
+
+    private
+
+    def search_all(query)
+      searchable_models.filter_map do |model|
+        records = model.search(query).order(id: :desc).limit(PER_ENTITY).to_a
+        [ model, records ] if records.any?
+      end.to_h
+    end
+
+    # Every Loam entity that opted into search, in name order.
+    #
+    # This eager loads, unlike Admin::CommentsController, and for the opposite
+    # reason: there is no user-supplied class name to check here, we need the
+    # COMPLETE list of models — and in development classes load lazily, so a
+    # model nobody has touched yet would silently be missing from results.
+    def searchable_models
+      Rails.application.eager_load!
+
+      Loam::TenantRecord.descendants.select do |model|
+        model.name.present? && model.respond_to?(:loam_searchable?) && model.loam_searchable?
+      end.sort_by(&:name)
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/search_index.html.erb

@@ -0,0 +1,23 @@
+<h1>Search</h1>
+
+<%%= form_with url: admin_search_path, method: :get do |f| %>
+  <%%= text_field_tag :q, @query, autofocus: true, placeholder: "Search everything in this tenant" %>
+  <%%= f.submit "Search" %>
+<%% end %>
+
+<%% if @query.present? %>
+  <%% if @results.empty? %>
+    <p>Nothing matches <strong><%%= @query %></strong> in <%%= current_tenant.name %>.</p>
+  <%% end %>
+
+  <%% @results.each do |model, records| %>
+    <h2><%%= model.model_name.human.pluralize %></h2>
+    <ul>
+      <%% records.each do |record| %>
+        <li>
+          <%%= link_to search_result_label(record), [ :admin, record ] %>
+        </li>
+      <%% end %>
+    </ul>
+  <%% end %>
+<%% end %>

data/lib/generators/loam/install/templates/admin/sessions_controller.rb

@@ -0,0 +1,248 @@
+module Admin
+  # Email + password login for the admin, then (if the user has MFA) a TOTP
+  # challenge, then the tenant pick. A Loam user can belong to several tenants,
+  # so: authenticate → second factor → choose a tenant where they hold a
+  # membership. The second factor runs BEFORE any tenant is chosen, which is why
+  # the MFA secret is keyed to the user, not a tenant (Loam::MfaCredential).
+  #
+  # Not a BaseController subclass: everything there assumes an established
+  # Loam::Current, which is exactly what this controller is trying to build.
+  class SessionsController < ActionController::Base
+    layout "admin"
+
+    def new
+      return redirect_to mfa_challenge_admin_session_path if session[:mfa_pending]
+
+      @user = authenticated_user
+      @tenants = @user ? Loam::Membership.tenants_for(@user) : Loam::Tenant.none
+    end
+
+    def create
+      email = params[:email]
+
+      # Rate-limit BEFORE touching the password (Loam::AuthThrottle). Throttle by
+      # the submitted identifier whether or not the account exists, and give the
+      # SAME generic locked response either way — so a lockout can't become an
+      # account-existence oracle.
+      if Loam::AuthThrottle.locked?(email)
+        @error = throttle_message(email)
+        return render :new, status: :too_many_requests
+      end
+
+      user = User.authenticate_by(email: email, password: params[:password])
+
+      if user.nil?
+        Loam::AuthThrottle.record_failure(email, kind: "password", ip: request.remote_ip)
+        # One message for both cases on purpose: saying which half was wrong
+        # tells an attacker which emails exist.
+        @error = "Wrong email or password."
+        return render :new, status: :unauthorized
+      end
+
+      Loam::AuthThrottle.clear(email) # a successful login resets the counter
+      reset_session # a fresh session id at login: no fixation
+      session[:user_id] = user.id
+
+      # Password is only the first factor when MFA is active — hold the login in
+      # a "pending" state (no tenant, no access) until the code checks out.
+      if Loam::MfaCredential.active_for(user)
+        session[:mfa_pending] = true
+        redirect_to mfa_challenge_admin_session_path
+      else
+        complete_authentication(user)
+      end
+    end
+
+    # The TOTP challenge screen (only reachable mid-login, password already given).
+    def mfa_challenge
+      @user = mfa_challenge_user or return redirect_to new_admin_session_path
+    end
+
+    # TODO (follow-up): rate-limit / lock out repeated failed codes here (needs
+    # throttling infra) — a 6-digit TOTP is brute-forceable without it.
+    def mfa_verify
+      user = mfa_challenge_user or return redirect_to new_admin_session_path
+
+      # A 6-digit TOTP (with drift, several codes valid) is the prime brute-force
+      # target — lock it out on the user's identifier.
+      if Loam::AuthThrottle.locked?(user.email)
+        @user = user
+        @error = throttle_message(user.email)
+        return render :mfa_challenge, status: :too_many_requests
+      end
+
+      credential = Loam::MfaCredential.active_for(user)
+
+      if credential.verify_totp(params[:code]) || credential.consume_recovery_code(params[:code])
+        Loam::AuthThrottle.clear(user.email)
+        session.delete(:mfa_pending)
+        complete_authentication(user)
+      else
+        Loam::AuthThrottle.record_failure(user.email, kind: "totp", ip: request.remote_ip)
+        # One generic error — never reveal whether a code was close or a
+        # recovery code was already spent.
+        @user = user
+        @error = "That code is not valid."
+        render :mfa_challenge, status: :unauthorized
+      end
+    end
+
+    # SSO entry: the user types an email, home-realm discovery finds the tenant's
+    # IdP by domain, and we redirect to it. No provider for that domain? Fall
+    # back to password login. The `state` is our CSRF token for the round-trip.
+    def sso_start
+      email = params[:email].to_s
+      provider = Loam::Sso.provider_for(email: email)
+
+      if provider.nil?
+        return redirect_to new_admin_session_path(email: email),
+                           alert: "No SSO provider is configured for that email domain — sign in with your password."
+      end
+
+      state = SecureRandom.urlsafe_base64(24)
+      reset_session
+      session[:sso_state] = state
+      session[:sso_provider_id] = provider.id
+      session[:sso_tenant_id] = provider.tenant_id
+
+      url = Loam.as_tenant(provider.tenant) do
+        Loam::Sso.build(provider, redirect_uri: sso_callback_admin_session_url)
+                 .authorization_url(state: state, login_hint: email)
+      end
+      redirect_to url, allow_other_host: true
+    end
+
+    # The IdP redirects back here with a code + state. GET, so Rails' form CSRF
+    # does not apply — the `state` check IS the CSRF defense. Verify it first,
+    # then exchange the code and provision inside the provider's tenant.
+    def sso_callback
+      state = session.delete(:sso_state)
+      provider_id = session.delete(:sso_provider_id)
+      tenant_id = session.delete(:sso_tenant_id)
+
+      if state.blank? || !ActiveSupport::SecurityUtils.secure_compare(state, params[:state].to_s)
+        return redirect_to new_admin_session_path, alert: "SSO sign-in could not be verified. Please try again."
+      end
+
+      tenant = Loam::Tenant.find_by(id: tenant_id)
+      provider = tenant && Loam.as_tenant(tenant) { Loam::SsoProvider.find_by(id: provider_id) }
+      if provider.nil? || !provider.active?
+        return redirect_to new_admin_session_path, alert: "That SSO provider is no longer available."
+      end
+
+      user = Loam.as_tenant(tenant) do
+        claims = Loam::Sso.build(provider, redirect_uri: sso_callback_admin_session_url).exchange(code: params[:code])
+        Loam::Sso.provision(provider, claims)
+      end
+
+      reset_session
+      session[:user_id] = user.id
+      session[:sso_tenant_id] = tenant.id  # land in the IdP's tenant after any MFA
+
+      # SSO establishes primary auth; if the user also runs app-side MFA, still
+      # require the second factor (the safe choice — SSO does not waive it).
+      if Loam::MfaCredential.active_for(user)
+        session[:mfa_pending] = true
+        redirect_to mfa_challenge_admin_session_path
+      else
+        complete_authentication(user)
+      end
+    rescue Loam::Sso::Error
+      # An unverified email, a domain the provider does not own, or any other
+      # provisioning refusal: no session, nothing linked, one generic message.
+      reset_session
+      redirect_to new_admin_session_path,
+                  alert: "We couldn't sign you in with SSO. Please contact your administrator."
+    end
+
+    # Step two (or three): the tenant picker posts here.
+    def select_tenant
+      return redirect_to mfa_challenge_admin_session_path if session[:mfa_pending]
+
+      user = authenticated_user
+      return redirect_to new_admin_session_path if user.nil?
+
+      tenant = Loam::Membership.tenants_for(user).find_by(id: params[:tenant_id])
+
+      # A tenant the user has no membership in is simply not in that list, so
+      # picking one is impossible rather than merely forbidden.
+      return redirect_to new_admin_session_path, alert: "You are not a member of that tenant." if tenant.nil?
+
+      enter(user, tenant)
+    end
+
+    def destroy
+      reset_session
+      Loam::Current.reset
+      redirect_to new_admin_session_path
+    end
+
+    private
+
+    def authenticated_user
+      User.find_by(id: session[:user_id])
+    end
+
+    def throttle_message(identifier)
+      minutes = (Loam::AuthThrottle.remaining_lockout(identifier) / 60.0).ceil
+      "Too many attempts. Try again in about #{[ minutes, 1 ].max} minute(s)."
+    end
+
+    # The signed-in user mid-MFA, or nil. Both the pending flag AND the user id
+    # must be present, so the challenge is never an oracle reachable without a
+    # password.
+    def mfa_challenge_user
+      return nil unless session[:mfa_pending] && session[:user_id]
+
+      authenticated_user
+    end
+
+    # Both factors are satisfied here, so this counts as a fresh re-auth: stamp
+    # the sudo clock, so a step-up-gated action right after login does not
+    # immediately re-challenge.
+    def complete_authentication(user)
+      session[:sudo_at] = Time.now.to_i
+
+      # SSO knows exactly which tenant to enter (the IdP's), so honor it even for
+      # a multi-tenant user rather than showing the picker.
+      if (sso_tenant_id = session.delete(:sso_tenant_id))
+        tenant = Loam::Membership.tenants_for(user).find_by(id: sso_tenant_id)
+        return enter(user, tenant) if tenant
+      end
+
+      tenants = Loam::Membership.tenants_for(user)
+
+      if tenants.one?
+        enter(user, tenants.first)
+      elsif tenants.none?
+        reset_session
+        @error = "This account has no tenant memberships yet."
+        render :new, status: :forbidden
+      else
+        redirect_to new_admin_session_path
+      end
+    end
+
+    def enter(user, tenant)
+      session[:tenant_id] = tenant.id
+
+      if mfa_enrollment_required?(user, tenant)
+        redirect_to new_admin_mfa_path, alert: "Your role requires two-factor authentication — set it up to continue."
+      else
+        redirect_to admin_root_path
+      end
+    end
+
+    # A tenant may require MFA for certain roles (security.mfa_required_roles,
+    # resolved in that tenant). If the user's role is on the list and they have
+    # no active credential, they are sent to enrollment before they can work.
+    def mfa_enrollment_required?(user, tenant)
+      return false if Loam::MfaCredential.active_for(user)
+
+      Loam.as_tenant(tenant) do
+        role = Loam::Membership.find_by(user_id: user.id)&.role
+        role.present? && Array(Loam::Configs.get("security.mfa_required_roles", default: [])).include?(role)
+      end
+    end
+  end
+end