argus-trail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8012d44e5a16eb856aec00b306bc64e780d96c13f34e729e25b0ed0087aca325
+  data.tar.gz: 2990ef7c7ce767ce3f3a61874b4ddb185c44c7e50cce740e7628dfd0edf531ae
+SHA512:
+  metadata.gz: 0ac4bd48b2f65ac648d8ba978a5dc8e119f9e189403ae2ef0a97b350f400ff7ae35c4ee14b3e2271446b7083a6876daaaf6a9d2fd02a4ec50225a09e49da6a90
+  data.tar.gz: 711cee8042f3d5200792b1297f770cd0a016b67e017fe65f19f8d85c0b1f10688263300fdfe0298837c34dc170c476b39a73728b51ff50420c70de3d75725840

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+# Argus::Trail
+
+A mountable Rails engine that gives any app configurable roles and
+permissions — actors can hold any number of roles — plus a unified,
+immutable audit log of every role assignment/revocation and every
+permission granted/revoked on a role, with ready-made, paginated HTML admin
+screens.
+
+See [`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md) for a detailed,
+step-by-step walkthrough (including troubleshooting for a couple of easy
+integration traps) — this README is the quick-start version.
+
+Stays out of your way on the things it doesn't need to own:
+- **No hardcoded role/permission names** — you define whatever `Role`/`Permission` rows you want.
+- **No fixed actor class** — works with whatever you call your `User`/`Account` model.
+- **No schema change to your actor table** — roles live in the engine's own polymorphic join table, so actors can hold 0..N roles.
+- **No required auth library** — works standalone; auto-integrates with [Pundit](https://github.com/varvet/pundit) if it's in your Gemfile.
+- **No required pagination library** — auto-integrates with [Kaminari](https://github.com/kaminari/kaminari) if it's in your Gemfile, otherwise falls back to a small built-in pager.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "argus-trail"
+```
+
+```bash
+bundle install
+bin/rails generate argus:trail:install
+bin/rails db:migrate
+```
+
+The install generator writes `config/initializers/argus_trail.rb`, creates
+the engine's own tables (`argus_trail_roles`, `argus_trail_permissions`,
+`argus_trail_role_permissions`, `argus_trail_role_assignments`,
+`argus_trail_audit_entries`), and mounts the engine at `/admin/access` in
+`config/routes.rb`. There's no migration on your own actor/user table —
+`argus_trail_role_assignments` is a polymorphic join table the engine owns
+end to end.
+
+## Wiring up your app
+
+**1. Opt your user model in:**
+
+```ruby
+class User < ApplicationRecord
+  include Argus::Trail::Actor
+end
+```
+
+This adds `has_many :roles` (through the engine's join table),
+`has_permission?(name)` (true if *any* assigned role has that permission),
+and `sync_roles!` — diffs the requested role ids against the ones the actor
+currently holds and writes one `AuditEntry` per assignment
+(`role_assigned`) or revocation (`role_revoked`):
+
+```ruby
+user.sync_roles!([ admin_role.id, support_role.id ], changed_by: current_user)
+```
+
+An actor can hold any number of roles at once; assigning a single role is
+just the `new_role_ids.size == 1` case of the same call.
+
+**2. Tell the engine who's making changes**, once, in your `ApplicationController`:
+
+```ruby
+before_action { Argus::Trail.current_actor = current_user }
+```
+
+**3. Authorize the admin screens.** If you have Pundit, define policies —
+Argus::Trail uses Pundit's normal lookup, so these are just regular
+policies:
+
+```ruby
+class Argus::Trail::RolePolicy < ApplicationPolicy
+  def index? = user.admin?
+  # ...
+end
+```
+
+Do the same for `Argus::Trail::PermissionPolicy` and
+`Argus::Trail::AuditEntryPolicy`. Without Pundit — e.g. if your app uses
+CanCanCan, Action Policy, or nothing at all — set `config.authorize_with` to
+a proc instead; it always takes priority over Pundit, so this works even if
+Pundit happens to also be in your Gemfile:
+
+```ruby
+# config/initializers/argus_trail.rb
+Argus::Trail.configure do |config|
+  config.authorize_with = ->(controller, record_or_class) { controller.current_user&.admin? }
+end
+```
+
+See [`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md#8-step-6--authorization)
+for a wiring example per authorization gem (Pundit, CanCanCan, Action
+Policy, plain proc). With neither Pundit nor `authorize_with` configured,
+the engine fails closed and raises an actionable error rather than silently
+allowing access.
+
+## Recording role changes on an actor
+
+Use `Actor#sync_roles!` (instead of assigning `role_ids=`/`roles=` directly)
+so assignments and revocations land in the audit log:
+
+```ruby
+user.sync_roles!(params[:role_ids], changed_by: current_user)
+```
+
+## Recording permission changes on a role
+
+Use `Role#sync_permissions!` (instead of assigning `permission_ids=`
+directly) so grants and revokes land in the audit log:
+
+```ruby
+role.sync_permissions!(params[:permission_ids], changed_by: current_user)
+```
+
+## Customizing the views
+
+```bash
+bin/rails generate argus:trail:views
+```
+
+Copies every view into `app/views/argus/trail` (and the layout into
+`app/views/layouts/argus/trail`) for full override. The shipped layout is
+self-contained (Tailwind via CDN) so it renders correctly with zero host
+asset-pipeline setup; set `config.layout` to render inside one of your own
+layouts instead.
+
+Already running ActiveAdmin and would rather manage roles/permissions there
+instead? `Role`/`Permission`/`AuditEntry` are plain ActiveRecord models, so
+`ActiveAdmin.register` works directly — see
+[`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md#19-optional-registering-with-activeadmin)
+for copy-pasteable registrations and the one gotcha to know about (ActiveAdmin's
+default checkboxes bypass the audit trail unless you call
+`sync_permissions!`/`sync_roles!` explicitly).
+
+## Configuration reference
+
+```ruby
+Argus::Trail.configure do |config|
+  config.actor_class_name           = "User"   # your user/account model
+  config.role_class_name            = "Argus::Trail::Role"       # rename if it collides with another gem/model
+  config.permission_class_name      = "Argus::Trail::Permission"
+  config.role_permission_class_name = "Argus::Trail::RolePermission"
+  config.changed_by_resolver = -> { Argus::Trail.current_actor }
+  config.authorize_with      = nil      # see "Authorize the admin screens" above
+  config.current_actor_method = :current_user
+  config.per_page             = 30
+  config.layout                = nil    # e.g. "application"
+end
+```
+
+`role_class_name`/`permission_class_name`/`role_permission_class_name` only
+rename the classes — they still map to the engine's own
+`argus_trail_roles`/`argus_trail_permissions`/`argus_trail_role_permissions`
+tables. This is for renaming (e.g. your app already has its own `Role`
+model for something unrelated), **not** for pointing the engine at an
+existing Role/Permission table with a different schema — see
+[`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md#14-configuration-reference)
+for the full mapping and caveats.
+
+## Development
+
+```bash
+bundle install
+bin/rails db:migrate
+bin/rails test
+```
+
+`test/dummy` is a minimal Rails app (with a `User` model already including
+`Argus::Trail::Actor`, and Pundit policies) used to exercise the engine.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/argus/trail/application_controller.rb

@@ -0,0 +1,45 @@
+module Argus
+  module Trail
+    # Inherits from the *host* app's ApplicationController (not
+    # ActionController::Base) — the standard mountable-engine trick that gets
+    # current_user/session/CSRF/flash/Devise helpers/layout for free.
+    class ApplicationController < ::ApplicationController
+      include Pundit::Authorization if defined?(Pundit)
+
+      layout -> { Argus::Trail.config.layout || "argus/trail/application" }
+
+      helper_method :current_actor
+
+      private
+
+      def current_actor
+        send(Argus::Trail.config.current_actor_method)
+      end
+
+      # Call with a record (show/edit/update/destroy) or a class (index/new/create).
+      # Resolution order: an explicitly configured proc always wins; otherwise, if
+      # Pundit is bundled, delegate to it (host must define policies, e.g.
+      # Argus::Trail::RolePolicy — same lookup Pundit already does for any
+      # namespaced record); otherwise fail closed with an actionable error.
+      def authorize_access!(record_or_class)
+        handler = Argus::Trail.config.authorize_with
+        return handler.call(self, record_or_class) if handler
+        return authorize(record_or_class) if defined?(Pundit)
+
+        raise Argus::Trail::Configuration::MissingAuthorization
+      end
+
+      # Scope a relation down to what the current actor may see. Only Pundit's
+      # policy_scope narrows results; a custom authorize_with is a yes/no gate,
+      # not a scope, so it leaves the relation as-is.
+      def authorized_scope(scope_class)
+        return authorized_scope_via_pundit(scope_class) if Argus::Trail.config.authorize_with.nil? && defined?(Pundit)
+        scope_class.all
+      end
+
+      def authorized_scope_via_pundit(scope_class)
+        policy_scope(scope_class)
+      end
+    end
+  end
+end

data/app/controllers/argus/trail/audit_entries_controller.rb

@@ -0,0 +1,19 @@
+module Argus
+  module Trail
+    class AuditEntriesController < ApplicationController
+      def index
+        authorize_access!(AuditEntry)
+
+        @entries = authorized_scope(AuditEntry)
+                     .includes(:subject, :changed_by, :role, :permission)
+                     .recent
+
+        @entries = @entries.where(subject_type: params[:subject_type]) if params[:subject_type].present?
+        @entries = @entries.where(subject_id: params[:subject_id]) if params[:subject_id].present?
+        @entries = @entries.where(role_id: params[:role_id]) if params[:role_id].present?
+
+        @pages = Argus::Trail::Pagination.paginate(@entries, page: params[:page], per: Argus::Trail.config.per_page)
+      end
+    end
+  end
+end

data/app/controllers/argus/trail/permissions_controller.rb

@@ -0,0 +1,65 @@
+module Argus
+  module Trail
+    class PermissionsController < ApplicationController
+      before_action :set_permission, only: [ :show, :edit, :update, :destroy ]
+
+      def index
+        authorize_access!(permission_class)
+        @permissions = authorized_scope(permission_class).includes(:roles).order(:name)
+      end
+
+      def show
+      end
+
+      def new
+        @permission = permission_class.new
+        authorize_access!(@permission)
+      end
+
+      def create
+        @permission = permission_class.new(permission_params)
+        authorize_access!(@permission)
+
+        if @permission.save
+          redirect_to permission_path(@permission), notice: "Permission '#{@permission.name}' created."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit
+      end
+
+      def update
+        if @permission.update(permission_params)
+          redirect_to permission_path(@permission), notice: "Permission '#{@permission.name}' updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        if @permission.roles.any?
+          redirect_to permissions_path,
+                      alert: "Cannot delete permission '#{@permission.name}' — it is assigned to #{@permission.roles.count} role(s)."
+        else
+          @permission.destroy
+          redirect_to permissions_path, notice: "Permission '#{@permission.name}' deleted."
+        end
+      end
+
+      private
+
+      def set_permission
+        @permission = permission_class.find(params[:id])
+        authorize_access!(@permission)
+      end
+
+      def permission_params
+        params.require(:permission).permit(:name, :description)
+      end
+
+      def permission_class = Argus::Trail.config.permission_class
+    end
+  end
+end

data/app/controllers/argus/trail/roles_controller.rb

@@ -0,0 +1,73 @@
+module Argus
+  module Trail
+    class RolesController < ApplicationController
+      before_action :set_role, only: [ :show, :edit, :update, :destroy ]
+      before_action :set_permissions, only: [ :new, :edit, :create, :update ]
+
+      def index
+        authorize_access!(role_class)
+        @roles = authorized_scope(role_class).includes(:permissions).order(:name)
+      end
+
+      def show
+      end
+
+      def new
+        @role = role_class.new
+        authorize_access!(@role)
+      end
+
+      def create
+        @role = role_class.new(role_params)
+        authorize_access!(@role)
+
+        if @role.save
+          @role.sync_permissions!(params[:permission_ids], changed_by: current_actor)
+          redirect_to role_path(@role), notice: "Role '#{@role.name}' created."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit
+      end
+
+      def update
+        if @role.update(role_params)
+          @role.sync_permissions!(params[:permission_ids], changed_by: current_actor)
+          redirect_to role_path(@role), notice: "Role '#{@role.name}' updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        if @role.actors.any?
+          redirect_to roles_path,
+                      alert: "Cannot delete role '#{@role.name}' — it is assigned to #{@role.actors.count} record(s)."
+        else
+          @role.destroy
+          redirect_to roles_path, notice: "Role '#{@role.name}' deleted."
+        end
+      end
+
+      private
+
+      def set_role
+        @role = role_class.find(params[:id])
+        authorize_access!(@role)
+      end
+
+      def set_permissions
+        @permissions = permission_class.order(:name)
+      end
+
+      def role_params
+        params.require(:role).permit(:name, :description)
+      end
+
+      def role_class = Argus::Trail.config.role_class
+      def permission_class = Argus::Trail.config.permission_class
+    end
+  end
+end

data/app/helpers/argus/trail/application_helper.rb

@@ -0,0 +1,34 @@
+module Argus
+  module Trail
+    module ApplicationHelper
+      BADGE_PALETTE = [
+        "bg-red-100 text-red-800",
+        "bg-yellow-100 text-yellow-800",
+        "bg-green-100 text-green-800",
+        "bg-blue-100 text-blue-800",
+        "bg-purple-100 text-purple-800",
+        "bg-pink-100 text-pink-800",
+        "bg-indigo-100 text-indigo-800"
+      ].freeze
+
+      # Deterministic name -> palette mapping so any role name gets a stable
+      # badge color, without a hardcoded admin/manager/bde case statement.
+      def role_badge_class(name)
+        return "bg-gray-100 text-gray-700" if name.blank?
+        BADGE_PALETTE[name.to_s.sum % BADGE_PALETTE.size]
+      end
+
+      def event_type_label(event_type)
+        event_type.to_s.humanize
+      end
+
+      def argus_trail_paginate(pages)
+        if pages.is_a?(Argus::Trail::Pagination::SimplePage)
+          render partial: "argus/trail/pagination/simple_pager", locals: { pages: pages }
+        else
+          paginate(pages)
+        end
+      end
+    end
+  end
+end

data/app/models/argus/trail/application_record.rb

@@ -0,0 +1,7 @@
+module Argus
+  module Trail
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/argus/trail/audit_entry.rb

@@ -0,0 +1,38 @@
+module Argus
+  module Trail
+    # Immutable log of every role assignment/revocation on an actor, and every
+    # permission granted/revoked on a role. `subject` is the actor for
+    # role_assigned/role_revoked events, or the Role for
+    # permission_granted/permission_revoked events.
+    class AuditEntry < ApplicationRecord
+      attribute :metadata, :json
+
+      belongs_to :subject, polymorphic: true
+      belongs_to :changed_by, polymorphic: true, optional: true
+      belongs_to :role, class_name: Argus::Trail.config.role_class_name, optional: true
+      belongs_to :permission, class_name: Argus::Trail.config.permission_class_name, optional: true
+
+      validates :event_type, presence: true
+
+      scope :recent, -> { order(created_at: :desc) }
+
+      def role_name = role&.name || metadata&.dig("role_name")
+      def permission_name = permission&.name || metadata&.dig("permission_name")
+
+      def changed_by_label
+        return "System" if changed_by.nil?
+        changed_by.try(:argus_trail_display_name) ||
+          changed_by.try(:name) ||
+          changed_by.try(:email) ||
+          "#{changed_by.class.name} ##{changed_by.id}"
+      end
+
+      def subject_label
+        subject.try(:argus_trail_display_name) ||
+          subject.try(:name) ||
+          subject.try(:email) ||
+          "#{subject.class.name} ##{subject.id}"
+      end
+    end
+  end
+end

data/app/models/argus/trail/permission.rb

@@ -0,0 +1,11 @@
+module Argus
+  module Trail
+    class Permission < ApplicationRecord
+      has_many :role_permissions, class_name: Argus::Trail.config.role_permission_class_name, dependent: :destroy
+      has_many :roles, through: :role_permissions
+
+      validates :name, presence: true, uniqueness: true
+      validates :description, presence: true
+    end
+  end
+end

data/app/models/argus/trail/role.rb

@@ -0,0 +1,53 @@
+module Argus
+  module Trail
+    class Role < ApplicationRecord
+      has_many :role_permissions, class_name: Argus::Trail.config.role_permission_class_name, dependent: :destroy
+      has_many :permissions, through: :role_permissions
+
+      # The join table itself is polymorphic (no migration needed on the
+      # host's actor table), but a has_many :through needs one concrete type
+      # to instantiate results as, hence source_type here.
+      has_many :role_assignments, class_name: "Argus::Trail::RoleAssignment", dependent: :destroy
+      has_many :actors, through: :role_assignments, source: :actor, source_type: Argus::Trail.config.actor_class_name
+
+      validates :name, presence: true, uniqueness: true
+      validates :description, presence: true
+
+      # Diffs the requested permission ids against the role's current ones and
+      # writes one AuditEntry per addition/removal, so the audit log captures
+      # exactly which permissions were granted or revoked (not just "something changed").
+      def sync_permissions!(new_permission_ids, changed_by: Argus::Trail.config.changed_by_resolver.call)
+        new_ids = Array(new_permission_ids).map(&:to_i).reject(&:zero?)
+        current_ids = permission_ids
+
+        added_ids   = new_ids - current_ids
+        removed_ids = current_ids - new_ids
+
+        transaction do
+          self.permission_ids = new_ids
+
+          Argus::Trail.config.permission_class.where(id: added_ids).find_each do |permission|
+            record_permission_change("permission_granted", permission, changed_by)
+          end
+
+          Argus::Trail.config.permission_class.where(id: removed_ids).find_each do |permission|
+            record_permission_change("permission_revoked", permission, changed_by)
+          end
+        end
+      end
+
+      private
+
+      def record_permission_change(event_type, permission, changed_by)
+        AuditEntry.create!(
+          event_type:    event_type,
+          subject:       self,
+          role_id:       id,
+          permission_id: permission.id,
+          changed_by:    changed_by,
+          metadata:      { "role_name" => name, "permission_name" => permission.name }
+        )
+      end
+    end
+  end
+end

data/app/models/argus/trail/role_assignment.rb

@@ -0,0 +1,13 @@
+module Argus
+  module Trail
+    # Join model between an actor (any class that includes Argus::Trail::Actor)
+    # and a Role — polymorphic so any number of actor classes/tables can hold
+    # roles without the engine needing a foreign key on each one.
+    class RoleAssignment < ApplicationRecord
+      belongs_to :actor, polymorphic: true
+      belongs_to :role, class_name: Argus::Trail.config.role_class_name
+
+      validates :role_id, uniqueness: { scope: [ :actor_type, :actor_id ] }
+    end
+  end
+end

data/app/models/argus/trail/role_permission.rb

@@ -0,0 +1,10 @@
+module Argus
+  module Trail
+    class RolePermission < ApplicationRecord
+      belongs_to :role, class_name: Argus::Trail.config.role_class_name
+      belongs_to :permission, class_name: Argus::Trail.config.permission_class_name
+
+      validates :permission_id, uniqueness: { scope: :role_id }
+    end
+  end
+end