activeadmin-device_authorization 0.1.3

data/lib/active_admin/device_authorization/configuration.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    # Host-facing knobs for RFC 8628 device authorization and bearer access tokens.
+    #
+    # Challenge lifetime and poll interval follow RFC 8628 (expires_in required;
+    # interval defaults to 5 when omitted). Access-token absolute and idle TTLs
+    # follow common OAuth practice (short-lived bearer; idle + absolute caps as
+    # in major IdP refresh/access policies). Either access-token TTL may be nil
+    # to disable that axis; both nil means revoke-only expiry.
+    class Configuration
+      DEFAULT_USER_CODE_ALPHABET = (
+        ("A".."Z").to_a + ("2".."9").to_a - %w[I O]
+      ).freeze
+
+      attr_accessor :resource_owner_class_name,
+        :client_class_name,
+        :grant_class_name,
+        :access_token_class_name,
+        :current_resource_owner,
+        :challenge_expires_in,
+        :poll_interval,
+        :slow_down_increment,
+        :access_token_absolute_ttl,
+        :access_token_idle_ttl,
+        :access_token_default_absolute_ttl,
+        :access_token_min_absolute_ttl,
+        :access_token_max_absolute_ttl,
+        :access_token_absolute_ttl_choices,
+        :user_code_character_count,
+        :user_code_group_size,
+        :user_code_alphabet,
+        :verification_path,
+        :oauth_path_prefix,
+        :path_namespace,
+        :scopes,
+        :default_scopes,
+        :scope_labels,
+        :grant_retention_period,
+        :token_retention_period,
+        :retention_batch_size,
+        :token_digest,
+        :on_consent_approved,
+        :on_consent_denied,
+        :on_token_issued,
+        # Callable(controller) -> truthy to continue approve, falsy if the host
+        # already redirected (step-up, etc.).
+        :before_approve,
+        # Callable(controller) for GET/POST step-up page_action when present.
+        :on_approve_step_up,
+        :rate_limit_device_authorization,
+        :rate_limit_token,
+        :register_active_admin_page,
+        :menu_parent,
+        :menu_priority,
+        :menu_label,
+        :verification_base_url
+
+      def initialize
+        @resource_owner_class_name = "AdminUser"
+        @client_class_name = "DeviceAuthorizationClient"
+        @grant_class_name = "DeviceAuthorizationGrant"
+        @access_token_class_name = "DeviceAuthorizationAccessToken"
+        @current_resource_owner = ->(controller) { controller.send(:current_admin_user) }
+
+        # RFC 8628 example uses 1800s; Doorkeeper device grant defaults to 300s.
+        # Ten minutes is a practical admin-consent window.
+        @challenge_expires_in = 10 * 60
+        @poll_interval = 5
+        @slow_down_increment = 5
+
+        @access_token_absolute_ttl = 4 * 60 * 60
+        @access_token_idle_ttl = 60 * 60
+        @access_token_default_absolute_ttl = 60 * 60
+        @access_token_min_absolute_ttl = 60 * 60
+        @access_token_max_absolute_ttl = 4 * 60 * 60
+        @access_token_absolute_ttl_choices = [1, 2, 3, 4].map { |hours| hours * 60 * 60 }
+
+        @user_code_character_count = 8
+        @user_code_group_size = 4
+        @user_code_alphabet = DEFAULT_USER_CODE_ALPHABET
+
+        @verification_path = "device_auth"
+        @oauth_path_prefix = "oauth"
+        @path_namespace = :admin
+
+        @scopes = []
+        @default_scopes = []
+        @scope_labels = {}
+
+        @grant_retention_period = 3 * 24 * 60 * 60
+        @token_retention_period = 30 * 24 * 60 * 60
+        @retention_batch_size = 1000
+
+        @token_digest = ->(plaintext) { Digest::SHA256.hexdigest(plaintext.to_s) }
+
+        @on_consent_approved = nil
+        @on_consent_denied = nil
+        @on_token_issued = nil
+        @before_approve = nil
+        @on_approve_step_up = nil
+        @rate_limit_device_authorization = nil
+        @rate_limit_token = nil
+
+        @register_active_admin_page = true
+        @menu_parent = "Admin"
+        @menu_priority = 91
+        @menu_label = nil
+        @verification_base_url = nil
+      end
+
+      def resource_owner_class
+        resource_owner_class_name.constantize
+      end
+
+      def client_class
+        client_class_name.constantize
+      end
+
+      def grant_class
+        grant_class_name.constantize
+      end
+
+      def access_token_class
+        access_token_class_name.constantize
+      end
+
+      def absolute_expiry_enabled?
+        !access_token_absolute_ttl.nil?
+      end
+
+      def idle_expiry_enabled?
+        !access_token_idle_ttl.nil?
+      end
+
+      def digest(plaintext)
+        token_digest.call(plaintext)
+      end
+
+      def label_for_scope(scope)
+        key = scope.to_s
+        return scope_labels[key] if scope_labels.key?(key)
+        return scope_labels[key.to_sym] if scope_labels.key?(key.to_sym)
+
+        key
+      end
+
+      def normalize_scopes(requested)
+        allowed = Array(scopes).map(&:to_s)
+        Array(requested).flatten.compact.map(&:to_s).map(&:strip).uniq.select { |scope| allowed.include?(scope) }
+      end
+
+      def validate_rate_limits!
+        [:rate_limit_device_authorization, :rate_limit_token].each do |setting|
+          raise ArgumentError, "#{setting} must be callable" unless public_send(setting).respond_to?(:call)
+        end
+      end
+
+      # Hard ceiling is access_token_absolute_ttl. Consent max cannot exceed it.
+      def effective_max_absolute_ttl
+        return nil unless absolute_expiry_enabled?
+
+        [access_token_max_absolute_ttl.to_i, access_token_absolute_ttl.to_i].min
+      end
+
+      def clamp_absolute_ttl(seconds)
+        return nil unless absolute_expiry_enabled?
+
+        value = seconds.to_i
+        value = access_token_default_absolute_ttl.to_i if value <= 0
+        min = access_token_min_absolute_ttl.to_i
+        max = effective_max_absolute_ttl
+        value.clamp(min, max)
+      end
+
+      def validate!
+        if challenge_expires_in.to_i <= 0
+          raise ArgumentError, "challenge_expires_in must be a positive number of seconds (RFC 8628 expires_in)"
+        end
+        if poll_interval.to_i <= 0
+          raise ArgumentError, "poll_interval must be a positive number of seconds (RFC 8628 interval)"
+        end
+        if slow_down_increment.to_i <= 0
+          raise ArgumentError, "slow_down_increment must be a positive number of seconds (RFC 8628 slow_down)"
+        end
+        if absolute_expiry_enabled?
+          validate_absolute_ttl_window!
+        end
+        if idle_expiry_enabled? && access_token_idle_ttl.to_i <= 0
+          raise ArgumentError, "access_token_idle_ttl must be positive when set"
+        end
+        true
+      end
+
+      private
+
+      def validate_absolute_ttl_window!
+        abs = access_token_absolute_ttl.to_i
+        min = access_token_min_absolute_ttl.to_i
+        max = access_token_max_absolute_ttl.to_i
+        default = access_token_default_absolute_ttl.to_i
+        raise ArgumentError, "access_token_absolute_ttl must be positive when set" if abs <= 0
+        raise ArgumentError, "access_token_min_absolute_ttl must be positive" if min <= 0
+        raise ArgumentError, "access_token_max_absolute_ttl must be positive" if max <= 0
+        raise ArgumentError, "access_token_default_absolute_ttl must be positive" if default <= 0
+        if max > abs
+          raise ArgumentError,
+            "access_token_max_absolute_ttl (#{max}) cannot exceed access_token_absolute_ttl (#{abs})"
+        end
+        if min > max
+          raise ArgumentError,
+            "access_token_min_absolute_ttl (#{min}) cannot exceed access_token_max_absolute_ttl (#{max})"
+        end
+        if default < min || default > max
+          raise ArgumentError,
+            "access_token_default_absolute_ttl (#{default}) must be within min..max (#{min}..#{max})"
+        end
+        Array(access_token_absolute_ttl_choices).each do |choice|
+          seconds = choice.to_i
+          next if seconds.between?(min, max)
+
+          raise ArgumentError,
+            "access_token_absolute_ttl_choices entry #{seconds} must be within min..max (#{min}..#{max})"
+        end
+      end
+    end
+  end
+end

data/lib/active_admin/device_authorization/consent.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    class Consent
+      class Error < StandardError; end
+
+      def initialize(grant:, resource_owner:, scopes:, absolute_ttl_seconds:, config: ActiveAdmin::DeviceAuthorization.config)
+        @grant = grant
+        @resource_owner = resource_owner
+        @scopes = config.normalize_scopes(scopes)
+        @absolute_ttl_seconds = config.clamp_absolute_ttl(absolute_ttl_seconds)
+        @config = config
+      end
+
+      def approve!
+        @grant.with_lock do
+          raise Error, "not_pending" unless @grant.pending?
+          raise Error, "expired" if @grant.mark_expired_if_needed!
+          raise Error, "invalid_scope" if @scopes.empty?
+          raise Error, "unsupported_scope" unless client.allows_scopes?(@scopes)
+          raise Error, "scope_not_requested" unless (@scopes - @grant.requested_scopes).empty?
+          if @resource_owner.respond_to?(:active_for_authentication?) && !@resource_owner.active_for_authentication?
+            raise Error, "resource_owner_inactive"
+          end
+
+          attrs = {
+            status: "approved",
+            granted_scopes: @scopes
+          }
+          attrs[resource_owner_association] = @resource_owner
+          attrs[:absolute_ttl_seconds] = @absolute_ttl_seconds if @grant.respond_to?(:absolute_ttl_seconds=)
+          @grant.update!(attrs)
+        end
+        Callback.call(@config.on_consent_approved, resource_owner: @resource_owner, grant: @grant)
+        @grant
+      end
+
+      def deny!
+        @grant.with_lock do
+          raise Error, "not_pending" unless @grant.pending?
+          @grant.mark_expired_if_needed!
+          raise Error, "expired" if @grant.status == "expired"
+
+          attrs = {status: "denied"}
+          attrs[resource_owner_association] = @resource_owner
+          @grant.update!(attrs)
+        end
+        Callback.call(@config.on_consent_denied, resource_owner: @resource_owner, grant: @grant)
+        @grant
+      end
+
+      private
+
+      def client
+        association = @config.client_class_name.underscore
+        @grant.public_send(association)
+      end
+
+      def resource_owner_association
+        @config.resource_owner_class_name.underscore.to_sym
+      end
+    end
+  end
+end

data/lib/active_admin/device_authorization/device_authorization_request.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    class DeviceAuthorizationRequest
+      class Error < StandardError; end
+
+      Result = Data.define(
+        :device_code,
+        :user_code,
+        :verification_uri,
+        :verification_uri_complete,
+        :expires_in,
+        :interval
+      )
+
+      def initialize(client_id:, scopes:, verification_base_url:, config: ActiveAdmin::DeviceAuthorization.config)
+        @client_id = client_id
+        @requested_scopes = Array(scopes).flatten.compact.map(&:to_s).map(&:strip).reject(&:empty?).uniq
+        @scopes = config.normalize_scopes(scopes)
+        @verification_base_url = verification_base_url
+        @config = config
+      end
+
+      def call
+        client = @config.client_class.enabled.find_by!(client_id: @client_id)
+        raise Error, "invalid_scope" if @scopes.empty?
+        raise Error, "invalid_scope" unless (@requested_scopes - @scopes).empty?
+        raise Error, "invalid_scope" unless client.allows_scopes?(@scopes)
+
+        device_code = SecureRandom.urlsafe_base64(32)
+        user_code = UserCode.generate(
+          config: @config,
+          exists: ->(code) { @config.grant_class.exists?(user_code: code) }
+        )
+
+        @config.grant_class.create!(
+          client_association_name => client,
+          :device_code_digest => @config.digest(device_code),
+          :user_code => user_code,
+          :requested_scopes => @scopes,
+          :status => "pending",
+          :challenge_expires_at => Time.current + @config.challenge_expires_in.to_i
+        )
+
+        verification_uri = build_verification_uri
+        Result.new(
+          device_code: device_code,
+          user_code: user_code,
+          verification_uri: verification_uri,
+          verification_uri_complete: "#{verification_uri}/#{user_code}",
+          expires_in: @config.challenge_expires_in.to_i,
+          interval: @config.poll_interval.to_i
+        )
+      end
+
+      private
+
+      def client_association_name
+        @config.client_class_name.underscore.to_sym
+      end
+
+      def build_verification_uri
+        base = (@config.verification_base_url.presence || @verification_base_url).to_s.chomp("/")
+        path = [@config.path_namespace, @config.verification_path].compact.join("/")
+        File.join(base, path)
+      end
+    end
+  end
+end

data/lib/active_admin/device_authorization/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    class Engine < ::Rails::Engine
+      initializer "active_admin.device_authorization.locales" do |app|
+        app.config.i18n.load_path += Dir[
+          root.join("config/locales/*.{rb,yml}")
+        ]
+      end
+
+      initializer "active_admin.device_authorization.filter_parameters" do |app|
+        app.config.filter_parameters |= [:device_code, :user_code, :access_token]
+      end
+    end
+  end
+end

data/lib/active_admin/device_authorization/page.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    # Registers the ActiveAdmin consent page. Call after ActiveAdmin.load! setup,
+    # typically from config/initializers/active_admin_device_authorization.rb once
+    # host scopes and model class names are configured.
+    module Page
+      module_function
+
+      def register!
+        config = ActiveAdmin::DeviceAuthorization.config
+        return unless config.register_active_admin_page
+
+        menu_label = config.menu_label || -> { I18n.t("active_admin.device_authorization.menu") }
+        verification = config.verification_path
+
+        ActiveAdmin.register_page "Device Auth" do
+          menu parent: config.menu_parent,
+            priority: config.menu_priority,
+            label: menu_label
+
+          controller do
+            helper_method :device_auth_grant
+
+            define_method(:index) do
+              user_code = ActiveAdmin::DeviceAuthorization::UserCode.normalize(params[:user_code])
+              if user_code.present?
+                redirect_to send(:"#{config.path_namespace}_device_auth_grant_path", user_code)
+                return
+              end
+
+              @page_title = I18n.t("active_admin.device_authorization.enter_code")
+              super()
+            end
+
+            define_method(:show) do
+              load_grant!
+              @grant.mark_expired_if_needed!
+              @page_title = I18n.t("active_admin.device_authorization.title")
+              render "active_admin/page/index"
+            end
+
+            define_method(:approve) do
+              load_grant!
+              if config.before_approve && !config.before_approve.call(self)
+                return
+              end
+
+              ActiveAdmin::DeviceAuthorization::Consent.new(
+                grant: @grant,
+                resource_owner: config.current_resource_owner.call(self),
+                scopes: Array(params[:scopes]),
+                absolute_ttl_seconds: params[:absolute_ttl_seconds]
+              ).approve!
+              redirect_to send(:"#{config.path_namespace}_device_auth_grant_path", @grant.user_code),
+                notice: I18n.t("active_admin.device_authorization.approved")
+            rescue ActiveAdmin::DeviceAuthorization::Consent::Error => error
+              redirect_to send(:"#{config.path_namespace}_device_auth_grant_path", @grant.user_code),
+                alert: I18n.t(
+                  "active_admin.device_authorization.error.#{error.message}",
+                  default: error.message
+                )
+            end
+
+            define_method(:deny) do
+              load_grant!
+              ActiveAdmin::DeviceAuthorization::Consent.new(
+                grant: @grant,
+                resource_owner: config.current_resource_owner.call(self),
+                scopes: @grant.requested_scopes,
+                absolute_ttl_seconds: config.access_token_default_absolute_ttl
+              ).deny!
+              redirect_to send(:"#{config.path_namespace}_device_auth_grant_path", @grant.user_code),
+                notice: I18n.t("active_admin.device_authorization.denied")
+            rescue ActiveAdmin::DeviceAuthorization::Consent::Error => error
+              redirect_to send(:"#{config.path_namespace}_device_auth_grant_path", @grant.user_code),
+                alert: I18n.t(
+                  "active_admin.device_authorization.error.#{error.message}",
+                  default: error.message
+                )
+            end
+
+            define_method(:device_auth_grant) { @grant }
+
+            define_method(:page_presenter) do
+              if action_name == "show"
+                active_admin_config.get_page_presenter(:index)
+              else
+                super()
+              end
+            end
+
+            private
+
+            define_method(:load_grant!) do
+              user_code = ActiveAdmin::DeviceAuthorization::UserCode.normalize(params[:user_code])
+              @grant = config.grant_class.find_by!(user_code: user_code)
+            end
+          end
+
+          page_action :step_up, method: [:get, :post] do
+            handler = ActiveAdmin::DeviceAuthorization.config.on_approve_step_up
+            if handler
+              handler.call(self)
+            else
+              redirect_to send(:"#{ActiveAdmin::DeviceAuthorization.config.path_namespace}_device_auth_path")
+            end
+          end
+
+          content title: proc { I18n.t("active_admin.device_authorization.title") } do
+            if device_auth_grant
+              render partial: "active_admin/device_authorization/consent",
+                locals: {grant: device_auth_grant}
+            else
+              render partial: "active_admin/device_authorization/enter_code"
+            end
+          end
+        end
+
+        # Host must also route show/approve/deny; Page only registers the AA index shell.
+        verification
+      end
+    end
+  end
+end

data/lib/active_admin/device_authorization/retention.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    module Retention
+      module_function
+
+      # Deletes tokens that have been expired or revoked longer than token_retention_period.
+      # Absolute, idle, and revoke axes are all covered so a far-future absolute sentinel
+      # (absolute expiry disabled) cannot retain idle-expired rows for decades.
+      def call(config: ActiveAdmin::DeviceAuthorization.config)
+        token_cutoff = Time.current - config.token_retention_period.to_i
+        predicates = ["absolute_expires_at < ?", "revoked_at < ?"]
+        binds = [token_cutoff, token_cutoff]
+
+        if config.idle_expiry_enabled?
+          idle_cutoff = Time.current -
+            config.access_token_idle_ttl.to_i -
+            config.token_retention_period.to_i
+          predicates << "last_used_at < ?"
+          binds << idle_cutoff
+        end
+
+        config.access_token_class
+          .where(predicates.join(" OR "), *binds)
+          .in_batches(of: config.retention_batch_size)
+          .delete_all
+
+        grant_cutoff = Time.current - config.grant_retention_period.to_i
+        token_assoc = config.access_token_class_name.underscore.to_sym
+        config.grant_class
+          .where(challenge_expires_at: ...grant_cutoff)
+          .where.missing(token_assoc)
+          .in_batches(of: config.retention_batch_size)
+          .delete_all
+      end
+    end
+  end
+end

data/lib/active_admin/device_authorization/routes.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module DeviceAuthorization
+    module Routes
+      # Embed under the host admin namespace, for example:
+      #
+      #   namespace :admin do
+      #     ActiveAdmin::DeviceAuthorization::Routes.draw(self)
+      #   end
+      #
+      # OAuth JSON endpoints always use absolute gem controller paths so nesting
+      # under `namespace :admin` does not invent `Admin::ActiveAdmin::...`.
+      #
+      # consent: :active_admin_page (default) routes show/approve/deny to the
+      # ActiveAdmin "Device Auth" page controller (`device_auth#...`).
+      # consent: :controller routes them to the gem ConsentsController instead.
+      def self.draw(mapper, config: ActiveAdmin::DeviceAuthorization.config, consent: :active_admin_page)
+        config.validate_rate_limits!
+        oauth = config.oauth_path_prefix.to_s
+        verification = config.verification_path.to_s
+
+        mapper.namespace :oauth, path: oauth do
+          mapper.post :device_authorization,
+            to: "/active_admin/device_authorization/device_authorizations#create"
+          mapper.post :token,
+            to: "/active_admin/device_authorization/tokens#create"
+        end
+
+        case consent
+        when :active_admin_page
+          mapper.get "#{verification}/:user_code",
+            to: "device_auth#show",
+            as: :device_auth_grant
+          mapper.post "#{verification}/:user_code/approve",
+            to: "device_auth#approve",
+            as: :approve_device_auth
+          mapper.post "#{verification}/:user_code/deny",
+            to: "device_auth#deny",
+            as: :deny_device_auth
+        when :controller
+          mapper.get verification,
+            to: "/active_admin/device_authorization/consents#index",
+            as: :device_auth
+          mapper.get "#{verification}/:user_code",
+            to: "/active_admin/device_authorization/consents#show",
+            as: :device_auth_grant
+          mapper.post "#{verification}/:user_code/approve",
+            to: "/active_admin/device_authorization/consents#approve",
+            as: :approve_device_auth
+          mapper.post "#{verification}/:user_code/deny",
+            to: "/active_admin/device_authorization/consents#deny",
+            as: :deny_device_auth
+        else
+          raise ArgumentError, "consent must be :active_admin_page or :controller (got #{consent.inspect})"
+        end
+      end
+    end
+  end
+end