atomic_admin 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60791227d9b0ddf9a2e98443268dce766a3c635ef35c6241cbc3b6d9e06b5b54
-  data.tar.gz: 8b9aee59dbefa5bd6760b35b0cf2d4a5739ad846efee3f24296bbc28c5515861
+  metadata.gz: 06d8fa97576a29d8803456608d9081661ea90977713458d6386c9c55a8bb0356
+  data.tar.gz: e87935716e8a596854cb453f328fa30f9a0444b74954112993ee066269d3adfb
 SHA512:
-  metadata.gz: 581634bdb7d6c05bcada251d601ba9c8fe97bb7a33ed8a203653a229936efa379b0205230bc586eed4d06e5565924e4449ec17b383e544cf316df93df1de8c53
-  data.tar.gz: 2d4df264ae0d3694b05abb991cb5ecec3fd18a29eb02f1c2e80357b7d9736c18b7eaf3ee6626d61b5a3f4d8cf110a38ebabd71abaaa65afbfbcf804a090fa19a
+  metadata.gz: de38f6db4e56f1ed6c0c24d58ac995ab00538843573476c4866af0bd4b281bae251109eb102a4f46438fd165b9f8858a52cf62f270e192f1f508f70133391ca6
+  data.tar.gz: 2f1485e9a3c9ac1d61a10eb01bb04fab78d68a7ef8e1d40149796b36db0f071f3ff28b6bf9444974c1819349a6e6f77f3b95a6cea0d496558fb3568ba37f671a

data/app/controllers/atomic_admin/api/admin/v1/role_capabilities_controller.rb

@@ -0,0 +1,3 @@
+module AtomicAdmin::Api::Admin::V1
+  RoleCapabilitiesController = AtomicAdmin::V1::RoleCapabilitiesController
+end

data/app/controllers/atomic_admin/v1/role_capabilities_controller.rb

@@ -0,0 +1,188 @@
+module AtomicAdmin::V1
+  # The API behind Skipper's `capabilities` interaction: a matrix of
+  # capabilities by roles, where each cell is what the role grants by default
+  # or an override row (ALLOW, DENY or PROHIBIT) at one scope. A scope is
+  # everywhere ("global"), one account ("account:<account id>") or one course
+  # ("course:<context id>").
+  #
+  # Rows are read and written through the host app's RoleCapability model
+  # (role, capability, mode, context_id, account_id) and Role model (name). The
+  # catalog, role defaults and account and course names come from the
+  # interaction's provider, an AtomicAdmin::RoleCapabilities::Provider
+  # subclass. See docs/interactions.md.
+  class RoleCapabilitiesController < AdminController
+    GLOBAL_SCOPE = "global".freeze
+    MODES = %w[ALLOW DENY PROHIBIT].freeze
+
+    around_action :switch_tenants
+
+    # The catalog, every role with what it grants by default, every override
+    # row for the catalog's capabilities, and the accounts and courses those
+    # rows are scoped to.
+    def show
+      rows = catalog_rows(RoleCapability.includes(:role).to_a)
+
+      render json: {
+        groups: provider.capability_groups,
+        capabilities: provider.capability_catalog,
+        modes: MODES,
+        tiers: provider.role_tiers,
+        roles: provider.listed_roles.map { |role| role_json(role) },
+        custom_roles: provider.custom_roles,
+        rows: rows.map { |row| row_json(row) },
+        scopes: scopes_json_for(rows),
+        notes: provider.notes,
+      }
+    end
+
+    # Replaces one role's override rows at one scope. A missing overrides key
+    # clears them.
+    #
+    #   PATCH { role: { name: "canvas:Grade Viewer" }, scope: "account:12",
+    #           overrides: { "reply_create" => "PROHIBIT", ... } }
+    def update
+      name = role_name_param
+      return render_unprocessable("role.name is required") if name.blank?
+
+      scope_key = params[:scope].presence || GLOBAL_SCOPE
+      context_id, account_id = parse_scope(scope_key)
+      if context_id.nil? && account_id.nil? && scope_key != GLOBAL_SCOPE
+        return render_unprocessable("scope must be global, account:<account id> or course:<context id>")
+      end
+      if context_id && provider.course_scopes([context_id]).empty?
+        return render_unprocessable("No course with context id #{context_id} has launched this tool")
+      end
+
+      overrides = params.key?(:overrides) ? overrides_param : {}
+      return render_unprocessable("overrides must map capability names to modes") if overrides.nil?
+
+      overrides = overrides.compact_blank
+      unknown = overrides.keys - provider.capability_names
+      return render_unprocessable("Unknown capabilities: #{unknown.join(', ')}") if unknown.any?
+
+      invalid_modes = overrides.values.uniq - MODES
+      return render_unprocessable("Unknown modes: #{invalid_modes.join(', ')}") if invalid_modes.any?
+
+      role = provider.role_for_update(name)
+      return render_unprocessable("Unknown role: #{name}") if role.nil?
+
+      provider.replace_overrides!(role, overrides, context_id:, account_id:)
+      saved = catalog_rows(RoleCapability.where(role:, context_id:, account_id:).includes(:role).to_a)
+
+      render json: {
+        role: role_json(role),
+        scope: scope_key,
+        overrides: saved.to_h { |row| [row.capability, row.mode] },
+      }
+    rescue ActiveRecord::RecordInvalid => e
+      render_unprocessable(e.record.errors.full_messages.join(", "))
+    end
+
+    # Accounts and courses matching a search, for the scope picker.
+    #
+    #   GET ?q=law
+    def scopes
+      render json: { scopes: provider.search_scopes(params[:q].to_s.strip) }
+    end
+
+    private
+
+    def application_instance
+      @application_instance ||= ApplicationInstance.find(params[:application_instance_id])
+    end
+
+    def provider
+      @provider ||= interaction.provider_class.new(application_instance:)
+    end
+
+    # The routes are only drawn when a capabilities interaction is registered.
+    def interaction
+      AtomicAdmin.application_instance_interactions.for_type(:capabilities).first
+    end
+
+    def switch_tenants(&)
+      Apartment::Tenant.switch(application_instance.tenant, &)
+    end
+
+    def render_unprocessable(message)
+      render json: { error: message }, status: 422
+    end
+
+    # Only rows for the catalog's capabilities. Other rows stay stored but are
+    # not this editor's to show or save back.
+    def catalog_rows(rows)
+      rows.select { |row| provider.capability_names.include?(row.capability.to_s) }
+    end
+
+    def role_json(role)
+      tier = provider.role_tier(role)&.to_s
+      {
+        id: role.id,
+        name: role.name,
+        display_name: provider.role_display_name(role),
+        kind: provider.role_kind(role),
+        custom: provider.custom_role?(role),
+        tier:,
+        tier_label: provider.role_tiers.find { |t| t[:key].to_s == tier }&.dig(:label),
+        defaults: (provider.role_defaults(role).map(&:to_s) & provider.capability_names).sort,
+      }
+    end
+
+    def row_json(row)
+      { role: row.role.name, scope: scope_key_for(row), capability: row.capability.to_s, mode: row.mode }
+    end
+
+    def scope_key_for(row)
+      if row.context_id
+        "course:#{row.context_id}"
+      elsif row.account_id
+        "account:#{row.account_id}"
+      else
+        GLOBAL_SCOPE
+      end
+    end
+
+    # [context_id, account_id] for a scope key; [nil, nil] for global and for
+    # anything malformed (the caller tells the two apart). Context ids are
+    # opaque, so only the first ":" separates the type.
+    def parse_scope(key)
+      type, id = key.to_s.split(":", 2)
+      return [nil, nil] if id.blank?
+
+      case type
+      when "course" then [id, nil]
+      when "account" then provider.valid_account_id?(id) ? [nil, id] : [nil, nil]
+      else [nil, nil]
+      end
+    end
+
+    # Names for the scopes the rows use. A course that is gone keeps its rows
+    # listed under an unnamed scope.
+    def scopes_json_for(rows)
+      account_ids = rows.filter_map(&:account_id).uniq
+      context_ids = rows.filter_map(&:context_id).uniq
+      courses = provider.course_scopes(context_ids).index_by { |scope| scope[:id] }
+
+      provider.account_scopes(account_ids) +
+        context_ids.map { |id| courses[id] || provider.course_scope_json(id) }
+    end
+
+    # `role` must be an object with a name; anything else is treated as missing.
+    def role_name_param
+      role = params[:role]
+      role.respond_to?(:key?) ? role[:name].to_s.strip : ""
+    end
+
+    # { capability => mode } with string or nil values, or nil when the shape
+    # is wrong.
+    def overrides_param
+      overrides = params[:overrides]
+      return nil unless overrides.respond_to?(:to_unsafe_h)
+
+      overrides = overrides.to_unsafe_h
+      return nil unless overrides.values.all? { |mode| mode.nil? || mode.is_a?(String) }
+
+      overrides
+    end
+  end
+end

data/config/routes.rb

@@ -42,6 +42,14 @@ AtomicAdmin::Engine.routes.draw do
               end
             end
 
+            # Backs the `capabilities` interaction; the host supplies its
+            # provider. See AtomicAdmin::V1::RoleCapabilitiesController.
+            if AtomicAdmin.application_instance_interactions.for_type(:capabilities).any?
+              resource :role_capabilities, only: [:show, :update] do
+                get :scopes
+              end
+            end
+
             AtomicAdmin.application_instance_interactions.for_type(:resource).each do |interaction|
               controller_name = interaction.key.to_s.pluralize
               resources controller_name do

data/lib/atomic_admin/interaction/capabilities.rb

@@ -0,0 +1,15 @@
+module AtomicAdmin::Interaction
+  # Skipper's Role Capabilities editor. `provider` is an
+  # AtomicAdmin::RoleCapabilities::Provider subclass, or its name; it is
+  # looked up on each request so it reloads in development.
+  class Capabilities < AtomicAdmin::Interaction::Base
+    def initialize(provider:, **kwargs)
+      super(**kwargs)
+      @provider = provider
+    end
+
+    def provider_class
+      @provider.is_a?(String) ? @provider.constantize : @provider
+    end
+  end
+end

data/lib/atomic_admin/interaction/manager.rb

@@ -8,6 +8,7 @@ module AtomicAdmin::Interaction
       resource: AtomicAdmin::Interaction::Resource,
       launch: AtomicAdmin::Interaction::Launch,
       readonly: AtomicAdmin::Interaction::Readonly,
+      capabilities: AtomicAdmin::Interaction::Capabilities,
     }.freeze
 
     def initialize

data/lib/atomic_admin/interaction.rb

@@ -4,6 +4,7 @@ require_relative 'interaction/analytics'
 require_relative 'interaction/resource'
 require_relative 'interaction/launch'
 require_relative 'interaction/readonly'
+require_relative 'interaction/capabilities'
 require_relative 'interaction/manager'
 
 module AtomicAdmin::Interaction

data/lib/atomic_admin/role_capabilities/provider.rb

@@ -0,0 +1,154 @@
+module AtomicAdmin
+  module RoleCapabilities
+    # What a host app supplies for the `capabilities` interaction: the
+    # capability catalog, what each role grants by default, and how accounts
+    # and courses are named and found. Subclass it, implement
+    # `capability_catalog` and `role_defaults`, override any other hook, and
+    # name the class in the interaction's `provider:` option.
+    #
+    # AtomicAdmin::V1::RoleCapabilitiesController builds one per request with
+    # the application instance, inside that instance's tenant, and reads and
+    # writes the host's RoleCapability rows (role, capability, mode,
+    # context_id, account_id) itself.
+    class Provider
+      attr_reader :application_instance
+
+      def initialize(application_instance:)
+        @application_instance = application_instance
+      end
+
+      # Required. The capabilities this application instance can grant, in
+      # display order: [{ name:, group:, label:, description: }].
+      def capability_catalog
+        raise NotImplementedError, "#{self.class.name} must implement capability_catalog"
+      end
+
+      # Required. The capability names one role grants when it has no override
+      # rows.
+      def role_defaults(_role)
+        raise NotImplementedError, "#{self.class.name} must implement role_defaults"
+      end
+
+      # The catalog's groups in order: [{ key:, label: }].
+      def capability_groups
+        capability_catalog.map { |capability| capability[:group].to_s }.uniq.map do |group|
+          { key: group, label: group.humanize }
+        end
+      end
+
+      # The default sets roles fall into, highest first: [{ key:, label: }].
+      # Columns are ordered by tier.
+      def role_tiers
+        []
+      end
+
+      # The key of the role's tier, or nil for a role that grants nothing by
+      # default.
+      def role_tier(_role)
+        nil
+      end
+
+      # Every role that gets a column.
+      def listed_roles
+        Role.order(:name).to_a
+      end
+
+      # The column title for a role whose name is not a standard LTI role URI
+      # (Skipper shortens those itself).
+      def role_display_name(role)
+        role.name
+      end
+
+      # What kind of role it is ("Canvas custom role"), or nil to let Skipper
+      # work it out from an LTI role URI.
+      def role_kind(_role)
+        nil
+      end
+
+      # Whether the role is an LMS custom role added by name.
+      def custom_role?(_role)
+        false
+      end
+
+      # nil, or how roles that have not launched yet can be added by name:
+      # { label: "Canvas custom role", prefix: "canvas:", example: "Grade Viewer" }.
+      # Skipper stores a typed name as prefix + name.
+      def custom_roles
+        nil
+      end
+
+      # The role an update names, or nil to refuse it.
+      def role_for_update(name)
+        Role.find_by(name:)
+      end
+
+      # Whether an id from an "account:<id>" scope key can be an account id.
+      def valid_account_id?(account_id)
+        account_id.present?
+      end
+
+      # Scope entries for these account ids, in the same order. Build them
+      # with account_scope_json.
+      def account_scopes(account_ids)
+        account_ids.map { |id| account_scope_json(id) }
+      end
+
+      # Scope entries for the courses among these context ids that have
+      # launched the tool; leave the rest out. Build them with
+      # course_scope_json. Course scopes cannot be saved until this is
+      # implemented.
+      def course_scopes(_context_ids)
+        []
+      end
+
+      # Accounts and courses matching a search term.
+      def search_scopes(_term)
+        []
+      end
+
+      # Short notes shown under the matrix, such as how defaults combine.
+      def notes
+        []
+      end
+
+      # Replaces the role's rows for the catalog's capabilities at one scope.
+      # Rows for capabilities outside the catalog are left alone.
+      def replace_overrides!(role, overrides, context_id:, account_id:)
+        RoleCapability.transaction do
+          RoleCapability.where(role:, capability: capability_names, context_id:, account_id:).delete_all
+          overrides.each do |capability, mode|
+            RoleCapability.create!(role:, capability:, mode:, context_id:, account_id:)
+          end
+        end
+      end
+
+      def capability_names
+        @capability_names ||= capability_catalog.map { |capability| capability[:name].to_s }
+      end
+
+      # `path` names the account's ancestors and the account itself, root
+      # first.
+      def account_scope_json(account_id, label: nil, path: [])
+        {
+          key: "account:#{account_id}",
+          type: "account",
+          id: account_id.to_s,
+          label: label.presence || "Account #{account_id}",
+          path:,
+        }
+      end
+
+      # `account` is the course's account scope, from account_scope_json, if
+      # known.
+      def course_scope_json(context_id, label: nil, account: nil)
+        {
+          key: "course:#{context_id}",
+          type: "course",
+          id: context_id.to_s,
+          label: label.presence || "Course #{context_id}",
+          account:,
+        }
+      end
+    end
+  end
+end

data/lib/atomic_admin/version.rb

@@ -1,3 +1,3 @@
 module AtomicAdmin
-  VERSION = "2.2.1".freeze
+  VERSION = "2.3.0".freeze
 end

data/lib/atomic_admin.rb

@@ -3,6 +3,7 @@ require "atomic_admin/engine"
 require "atomic_admin/jwt_token"
 require "atomic_admin/schema"
 require "atomic_admin/interaction"
+require "atomic_admin/role_capabilities/provider"
 require "atomic_admin/filtering"
 
 module AtomicAdmin

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atomic_admin
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Nick Benoit
 - Sean Collings
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -113,6 +112,7 @@ files:
 - app/controllers/atomic_admin/api/admin/v1/applications_controller.rb
 - app/controllers/atomic_admin/api/admin/v1/lti_installs_controller.rb
 - app/controllers/atomic_admin/api/admin/v1/lti_platforms_controller.rb
+- app/controllers/atomic_admin/api/admin/v1/role_capabilities_controller.rb
 - app/controllers/atomic_admin/api/admin/v1/sites_controller.rb
 - app/controllers/atomic_admin/api/admin/v1/tenant_client_id_strategies_controller.rb
 - app/controllers/atomic_admin/api/admin/v1/tenant_deployments_controller.rb
@@ -123,6 +123,7 @@ files:
 - app/controllers/atomic_admin/v1/applications_controller.rb
 - app/controllers/atomic_admin/v1/lti_installs_controller.rb
 - app/controllers/atomic_admin/v1/lti_platforms_controller.rb
+- app/controllers/atomic_admin/v1/role_capabilities_controller.rb
 - app/controllers/atomic_admin/v1/sites_controller.rb
 - app/controllers/atomic_admin/v1/tenant_client_id_strategies_controller.rb
 - app/controllers/atomic_admin/v1/tenant_deployments_controller.rb
@@ -139,6 +140,7 @@ files:
 - lib/atomic_admin/interaction.rb
 - lib/atomic_admin/interaction/analytics.rb
 - lib/atomic_admin/interaction/base.rb
+- lib/atomic_admin/interaction/capabilities.rb
 - lib/atomic_admin/interaction/json_form.rb
 - lib/atomic_admin/interaction/launch.rb
 - lib/atomic_admin/interaction/manager.rb
@@ -147,6 +149,7 @@ files:
 - lib/atomic_admin/jwt_token.rb
 - lib/atomic_admin/jwt_token/jwks_decoder.rb
 - lib/atomic_admin/jwt_token/secret_decoder.rb
+- lib/atomic_admin/role_capabilities/provider.rb
 - lib/atomic_admin/schema.rb
 - lib/atomic_admin/schema/application_instance_configuration_schema.rb
 - lib/atomic_admin/schema/application_instance_create_schema.rb
@@ -165,7 +168,6 @@ metadata:
   homepage_uri: https://github.com/atomicjolt/atomic_admin/
   source_code_uri: https://github.com/atomicjolt/atomic_admin/
   changelog_uri: https://github.com/atomicjolt/atomic_admin/
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -180,8 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Engine to provide apis that power the Atomic Jolt admin app
 test_files: []