katalyst-koi 5.4.0 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 559fd46fee1b7874a6593314f73ca7c2f205b31650457f35b171ba4165ff3e91
-  data.tar.gz: 7a8ad3000aa8d852adf95943574b0a56aa1eafd72446a9f9cd0abe107d968072
+  metadata.gz: 9a64f8ea56e122d169ec52b8c304c79a1b81289bba216d89d2b97c9f0aaf9e24
+  data.tar.gz: e07ac3a269c0cf2958f33fb9e3da25dec86a84d27f25f3d0314ecc4d4fed5f4f
 SHA512:
-  metadata.gz: 4f039daf2363cf733d2d271f6a544b843d0ab1b1746db24f2be2177065a8bd4d9495bb7570def596ee86b674558f7dd8632d846522fe6a00b678019752858a17
-  data.tar.gz: d1c3be39ebf0fdfceb631a9fd86ffbf86e655f18b6b489b92243b261d4b52deb9165a99ea40b1c3ed62bb7c8fae5457fb5033fd2abd42c474320b3da04c2fdce
+  metadata.gz: c337a6f84e5ce47739dc9242207b9eafd2a0fbf6c9bf3f5b89338910175b3598dc575037849fb1a844e1a1608b54cb9e08e891286047b1548bbe127484ae446a
+  data.tar.gz: 84b32b36bd70147f24f0b975df0b722ba37f860185c1df483c1947c55ec17c74d1332e16b29d30b95f1f0f59021dced986db12ae005f7962349f3cd30df74246

data/README.md

@@ -1,25 +1,19 @@
-# Koi
+# Katalyst Koi
 
 Koi is a framework for building Rails admin functionality.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+In most cases, Koi is installed using `https://github.com/katalyst/koi-template`.
 
-```ruby
-gem "katalyst-koi"
-```
+## API Access
 
-And then execute:
-
-```sh
-bundle install
-```
+See [docs/api-access.md](docs/api-access.md).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/katalyst/katalyst-tables.
+Bug reports and pull requests are welcome on GitHub at https://github.com/katalyst/koi.
 
 ## License
 
-Katalyst Tables is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Koi is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/admin/admin_users_controller.rb

@@ -2,6 +2,7 @@
 
 module Admin
   class AdminUsersController < ApplicationController
+    before_action :requires_session_authentication!
     before_action :set_admin_user, only: %i[show edit update destroy]
 
     attr_reader :admin_user

data/app/controllers/admin/credentials_controller.rb

@@ -4,6 +4,7 @@ module Admin
   class CredentialsController < ApplicationController
     include Koi::Controller::HasWebauthn
 
+    before_action :requires_session_authentication!
     before_action :set_admin_user, only: %i[new create]
     before_action :set_credential, only: %i[show update destroy]
 

data/app/controllers/admin/device_authorizations_controller.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Admin
+  class DeviceAuthorizationsController < ApplicationController
+    EXPIRES_IN = 10.minutes
+    INTERVAL = 5
+
+    rate_limit to: 3, within: 1.minute, only: :create
+    skip_before_action :verify_authenticity_token, only: :create
+
+    before_action :set_device_authorization, only: %i[show update]
+
+    attr_reader :device_authorization
+
+    delegate :admin_user, to: ::Koi::Current
+
+    def show
+      render locals: { device_authorization: }
+    end
+
+    def create
+      device_authorization, device_code = Admin::DeviceAuthorization.issue!(
+        requested_ip: request.remote_ip,
+        user_agent:   request.user_agent,
+      )
+
+      render json: {
+        device_code:,
+        user_code:                 device_authorization.user_code,
+        verification_uri:          admin_device_authorization_url(device_authorization.user_code),
+        verification_uri_complete: admin_device_authorization_url(device_authorization.user_code),
+        expires_in:                EXPIRES_IN.to_i,
+        interval:                  INTERVAL,
+      }
+    end
+
+    def update
+      if device_authorization.actionable?
+        case params[:decision]
+        when "approve"
+          device_authorization.approve!(admin_user:)
+        else
+          device_authorization.deny!(admin_user:)
+        end
+
+        redirect_to(admin_device_authorization_path(device_authorization.user_code), status: :see_other)
+      else
+        render(:show, status: :unprocessable_content, locals: { device_authorization: })
+      end
+    end
+
+    private
+
+    def set_device_authorization
+      @device_authorization = Admin::DeviceAuthorization.find_by!(user_code: params[:user_code])
+    end
+  end
+end

data/app/controllers/admin/device_tokens_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Admin
+  class DeviceTokensController < ApplicationController
+    GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+    rate_limit to: 20, within: 1.minute, only: :create
+    skip_before_action :verify_authenticity_token, only: :create
+
+    def create
+      return render(json: { error: "invalid_request" }, status: :bad_request) unless params[:grant_type] == GRANT_TYPE
+
+      render json: Admin::DeviceAuthorization.issue_access_token!(device_code: params[:device_code])
+    rescue Admin::DeviceAuthorization::TokenError => e
+      render json: { error: e.code }, status: :bad_request
+    end
+  end
+end

data/app/controllers/admin/otps_controller.rb

@@ -4,6 +4,8 @@ module Admin
   class OtpsController < ApplicationController
     alias_method :admin_user, :current_admin
 
+    before_action :requires_session_authentication!
+
     def new
       admin_user.otp_secret = ROTP::Base32.random
 

data/app/controllers/admin/profiles_controller.rb

@@ -4,6 +4,8 @@ module Admin
   class ProfilesController < ApplicationController
     include Koi::Controller::HasWebauthn
 
+    before_action :requires_session_authentication!
+
     alias_method :admin_user, :current_admin
 
     def show

data/app/controllers/admin/sessions_controller.rb

@@ -41,7 +41,7 @@ module Admin
     end
 
     def destroy
-      record_sign_out!(current_admin_user)
+      record_sign_out!(Koi::Current.admin_user)
 
       session[:admin_user_id] = nil
 
@@ -103,11 +103,11 @@ module Admin
     def authenticate_local_admin
       return if admin_signed_in? || !Rails.env.development?
 
-      @current_admin_user = Admin::User.find_by(email: "#{ENV.fetch('USER', nil)}@katalyst.com.au")
+      Koi::Current.admin_user = Admin::User.find_by(email: "#{ENV.fetch('USER', nil)}@katalyst.com.au")
 
       return unless admin_signed_in?
 
-      session[:admin_user_id] = current_admin_user.id
+      session[:admin_user_id] = Koi::Current.admin_user.id
 
       flash.delete(:redirect) if (redirect = flash[:redirect])
 

data/app/controllers/concerns/koi/controller/has_admin_users.rb

@@ -14,23 +14,20 @@ module Koi
       end
 
       def admin_signed_in?
-        current_admin_user.present?
-      rescue ActiveRecord::RecordNotFound
-        false
+        Koi::Current.admin_user.present?
       end
 
       def current_admin_user
-        return @current_admin_user if instance_variable_defined?(:@current_admin_user)
-        return @current_admin_user = nil unless session.has_key?(:admin_user_id)
-
-        @current_admin_user = Admin::User.find(session[:admin_user_id])
-      ensure
-        session.delete(:admin_user_id) unless @current_admin_user
+        Koi::Current.admin_user
       end
 
       # @deprecated Use current_admin_user instead
       alias_method :current_admin, :current_admin_user
 
+      def requires_session_authentication!
+        head(:forbidden) if session[:admin_user_id].blank?
+      end
+
       module Test
         # Include in view specs to stub out the current admin user
         module ViewHelper
@@ -40,11 +37,11 @@ module Koi
             before do
               view.singleton_class.module_eval do
                 def admin_signed_in?
-                  current_admin_user.present?
+                  Koi::Current.admin_user.present?
                 end
 
                 def current_admin_user
-                  respond_to?(:admin_user) ? admin_user : nil
+                  Koi::Current.admin_user = (respond_to?(:admin_user) ? admin_user : nil)
                 end
 
                 alias_method :current_admin, :current_admin_user

data/app/controllers/concerns/koi/controller/has_webauthn.rb

@@ -27,7 +27,7 @@ module Koi
         end
 
         def webauthn_registration_options_value
-          user = current_admin_user.tap do |u|
+          user = Koi::Current.admin_user.tap do |u|
             u.update!(webauthn_id: WebAuthn.generate_user_id) unless u.webauthn_id
           end
 
@@ -74,7 +74,8 @@ module Koi
           session.delete(:registration_challenge),
         )
 
-        current_admin_user
+        Koi::Current
+          .admin_user
           .credentials
           .create_with(nickname:   webauthn_nickname,
                        public_key: webauthn_credential.public_key,

data/app/controllers/concerns/koi/controller.rb

@@ -38,6 +38,13 @@ module Koi
       layout -> { turbo_frame_request? ? "koi/frame" : "koi/application" }
 
       protect_from_forgery with: :exception
+      skip_forgery_protection if: :bearer_token_request?
+    end
+
+    private
+
+    def bearer_token_request?
+      request.authorization.to_s.match?(/\ABearer .+\z/)
     end
   end
 end

data/app/jobs/admin/device_authorizations_cleanup_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Admin
+  class DeviceAuthorizationsCleanupJob < Koi::ApplicationJob
+    def perform
+      Admin::DeviceAuthorization.where(created_at: ...7.days.ago).delete_all
+    end
+  end
+end

data/app/models/admin/device_authorization.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Admin
+  class DeviceAuthorization < ApplicationRecord
+    EXPIRES_IN = 10.minutes
+
+    class TokenError < StandardError
+      attr_reader :code
+
+      def initialize(code)
+        @code = code
+        super
+      end
+    end
+
+    self.table_name = :admin_device_authorizations
+
+    belongs_to :admin_user, class_name: "Admin::User", optional: true
+
+    enum :status, %w[pending approved denied consumed].index_with(&:to_s)
+
+    validates :device_code_digest, presence: true, uniqueness: true
+    validates :request_expires_at, presence: true
+    validates :status, presence: true, inclusion: { in: statuses.values }
+    validates :user_code, presence: true, uniqueness: true
+
+    def self.issue!(requested_ip:, user_agent:)
+      device_code = SecureRandom.urlsafe_base64(32)
+
+      device_authorization = create!(
+        device_code_digest: digest(device_code),
+        user_code:          generate_user_code,
+        request_expires_at: EXPIRES_IN.from_now,
+        requested_ip:,
+        user_agent:,
+      )
+
+      [device_authorization, device_code]
+    end
+
+    def self.digest(device_code)
+      Digest::SHA256.hexdigest(device_code)
+    end
+
+    def self.generate_user_code
+      "#{SecureRandom.alphanumeric(4).upcase}-#{SecureRandom.alphanumeric(4).upcase}"
+    end
+
+    def self.issue_access_token!(device_code:, token_expires_in: 12.hours)
+      device_authorization = find_by(device_code_digest: digest(device_code.to_s))
+      raise TokenError.new("invalid_grant") unless device_authorization
+
+      device_authorization.with_lock do
+        device_authorization.reload
+
+        if (error = device_authorization.token_error)
+          raise TokenError.new(error)
+        end
+
+        access_token = device_authorization.admin_user.generate_token_for(:api_access)
+        device_authorization.consume!(token_expires_in:)
+
+        {
+          access_token:,
+          token_type:   "Bearer",
+          expires_in:   token_expires_in.to_i,
+        }
+      end
+    end
+
+    def expired?
+      request_expires_at <= Time.current
+    end
+
+    def issuable?
+      approved? && !expired?
+    end
+
+    def token_error
+      return "authorization_pending" if pending?
+      return "access_denied" if denied?
+
+      "invalid_grant" if consumed? || expired?
+    end
+
+    def consume!(token_expires_in:)
+      update!(
+        status:           "consumed",
+        consumed_at:      Time.current,
+        token_expires_at: token_expires_in.from_now,
+      )
+    end
+
+    def approve!(admin_user:)
+      update!(
+        status:      "approved",
+        approved_at: Time.current,
+        admin_user:,
+      )
+    end
+
+    def deny!(admin_user:)
+      update!(
+        status:     "denied",
+        admin_user:,
+      )
+    end
+
+    def actionable?
+      pending? && !expired?
+    end
+  end
+end

data/app/models/admin/user.rb

@@ -14,6 +14,7 @@ module Admin
     # disable validations for password_digest
     has_secure_password validations: false
 
+    generates_token_for(:api_access, expires_in: 12.hours) { current_sign_in_at }
     generates_token_for(:password_reset, expires_in: 30.minutes) { current_sign_in_at }
 
     has_many :credentials, inverse_of: :admin, class_name: "Admin::Credential", dependent: :destroy

data/app/models/koi/current.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Koi
+  class Current < ActiveSupport::CurrentAttributes
+    # @return [Admin::User]
+    attribute :admin_user
+  end
+end

data/app/views/admin/device_authorizations/show.html.erb

@@ -0,0 +1,38 @@
+<%# locals: (device_authorization:) %>
+
+<%= content_for(:roadblock) do %>
+  <header>
+    <icon aria-hidden="true" class="icon" data-icon="koi">&nbsp;</icon>
+    <h1>API access request</h1>
+  </header>
+
+  <% if device_authorization.pending? && !device_authorization.expired? %>
+    <p>
+      A device is requesting a short-lived API token.
+    </p>
+    <dl>
+      <dt>Code</dt><dd><%= device_authorization.user_code %></dd>
+    </dl>
+
+    <div class="actions">
+      <%= button_to("Approve",
+                    admin_device_authorization_path(device_authorization.user_code),
+                    method: :patch,
+                    params: { decision: "approve" },
+                    class:  "button") %>
+      <%= button_to("Deny",
+                    admin_device_authorization_path(device_authorization.user_code),
+                    method: :patch,
+                    params: { decision: "deny" },
+                    class:  "button button--secondary") %>
+    </div>
+  <% end %>
+
+  <%= summary_table_with(model: device_authorization) do |row| %>
+    <% row.enum(:status) %>
+    <% row.text(:requested_ip) %>
+    <% row.text(:user_agent) %>
+    <% row.datetime(:request_expires_at) %>
+    <% row.datetime(:token_expires_at) %>
+  <% end %>
+<% end %>

data/app/views/layouts/koi/_application_navigation.html.erb

@@ -14,10 +14,10 @@
                         keydown.enter->navigation#go keydown.esc->navigation#clear">
     </div>
 
-    <% if current_admin_user %>
+    <% if Koi::Current.admin_user %>
       <ul class="navigation-group | flow" role="list">
         <li>
-          <span><%= current_admin_user.name %></span>
+          <span><%= Koi::Current.admin_user.name %></span>
           <ul class="navigation-list | flow" role="list">
             <li><%= link_to("Profile", main_app.admin_profile_path) %></li>
             <li><%= link_to("Log out", main_app.admin_session_path, data: { turbo_method: :delete }) %></li>

data/config/routes.rb

@@ -13,6 +13,9 @@ Rails.application.routes.draw do
     resource :cache, only: %i[destroy]
     resource :dashboard, only: %i[show]
 
+    resources :device_authorizations, param: :user_code, only: %i[create show update]
+    resources :device_tokens, only: %i[create]
+
     resource :profile, only: %i[show edit update], shallow: true do
       resources :credentials, only: %i[show new create update destroy]
       resource :otp, only: %i[new create destroy]

data/db/migrate/20260413014834_create_admin_device_authorizations.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateAdminDeviceAuthorizations < ActiveRecord::Migration[8.0]
+  def change
+    create_table :admin_device_authorizations do |t|
+      t.string :device_code_digest, null: false, index: { unique: true }
+      t.string :user_code, null: false, index: { unique: true }
+      t.string :status, null: false, default: "pending"
+      t.datetime :request_expires_at, null: false
+      t.datetime :approved_at
+      t.datetime :consumed_at
+      t.datetime :token_expires_at
+      t.references :admin_user, null: true, foreign_key: { to_table: :admins }
+      t.string :requested_ip
+      t.string :user_agent
+
+      t.timestamps
+    end
+  end
+end

data/lib/koi/middleware/admin_authentication.rb

@@ -19,27 +19,71 @@ module Koi
         request = ActionDispatch::Request.new(env)
         session = ActionDispatch::Request::Session.find(request)
 
-        if requires_authentication?(request) && !authenticated?(session)
-          # Set the redirection path for returning the user to their requested path after login
-          if request.get?
-            request.flash[:redirect] = request.fullpath
-            request.commit_flash
-          end
+        # Always retrieve user to ensure we are not vulnerable to timing attacks
+        Koi::Current.admin_user = if bearer_token(request).present?
+                                    bearer_admin_user(request)
+                                  else
+                                    session_admin_user(session)
+                                  end
 
-          [303, { "Location" => "/admin/session/new" }, []]
+        # Remove from session if not found
+        session.delete(:admin_user_id) if session.has_key?(:admin_user_id) && !authenticated?
+
+        if requires_authentication?(request) && !authenticated?
+          unauthorized_response(request)
         else
           @app.call(env)
         end
+      ensure
+        Koi::Current.admin_user = nil
       end
 
       private
 
       def requires_authentication?(request)
-        !request.path.starts_with?("/admin/session")
+        !request.path.starts_with?("/admin/session") && !device_flow_request?(request)
+      end
+
+      def authenticated?
+        Koi::Current.admin_user.present?
+      end
+
+      def bearer_admin_user(request)
+        token = bearer_token(request)
+        return if token.blank?
+
+        request.session_options[:skip] = true
+
+        Admin::User.find_by_token_for(:api_access, token)
+      end
+
+      def session_admin_user(session)
+        Admin::User.find_by(id: session[:admin_user_id])
+      end
+
+      def bearer_token(request)
+        return nil if request.authorization.blank?
+
+        request.authorization.match(/^Bearer (?<token>.+)$/)&.named_captures&.fetch("token", nil)
+      end
+
+      def unauthorized_response(request)
+        if bearer_token(request).present?
+          # If the user provided a token, it was not valid, and the request requires authentication
+          [401, {}, []]
+        else
+          if request.get?
+            # Set the redirection path for returning the user to their requested path after login
+            request.flash[:redirect] = request.fullpath
+            request.commit_flash
+          end
+
+          [303, { "Location" => "/admin/session/new" }, []]
+        end
       end
 
-      def authenticated?(session)
-        session[:admin_user_id].present?
+      def device_flow_request?(request)
+        request.post? && %w[/admin/device_authorizations /admin/device_tokens].include?(request.path)
       end
     end
   end

data/spec/factories/admin_device_authorizations.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :admin_device_authorization, class: "Admin::DeviceAuthorization" do
+    sequence(:device_code_digest) { |n| "digest-#{n}" }
+    sequence(:user_code) { |n| "CODE-#{n.to_s.rjust(4, '0')}" }
+    status { :pending }
+    request_expires_at { 10.minutes.from_now }
+    requested_ip { "127.0.0.1" }
+    user_agent { "RSpec" }
+
+    trait :approved do
+      status { :approved }
+      approved_at { Time.current }
+      admin_user
+    end
+
+    trait :denied do
+      status { :denied }
+      admin_user
+    end
+
+    trait :consumed do
+      status { :consumed }
+      consumed_at { Time.current }
+      admin_user
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-koi
 version: !ruby/object:Gem::Version
-  version: 5.4.0
+  version: 5.5.0
 platform: ruby
 authors:
 - Katalyst Interactive
@@ -356,6 +356,8 @@ files:
 - app/controllers/admin/caches_controller.rb
 - app/controllers/admin/credentials_controller.rb
 - app/controllers/admin/dashboards_controller.rb
+- app/controllers/admin/device_authorizations_controller.rb
+- app/controllers/admin/device_tokens_controller.rb
 - app/controllers/admin/otps_controller.rb
 - app/controllers/admin/profiles_controller.rb
 - app/controllers/admin/sessions_controller.rb
@@ -389,13 +391,16 @@ files:
 - app/javascript/koi/elements/index.js
 - app/javascript/koi/elements/toolbar.js
 - app/javascript/koi/utils/transition.js
+- app/jobs/admin/device_authorizations_cleanup_job.rb
 - app/jobs/koi/application_job.rb
 - app/models/admin/collection.rb
 - app/models/admin/credential.rb
+- app/models/admin/device_authorization.rb
 - app/models/admin/user.rb
 - app/models/application_record.rb
 - app/models/concerns/koi/model/archivable.rb
 - app/models/concerns/koi/model/otp.rb
+- app/models/koi/current.rb
 - app/models/url_rewrite.rb
 - app/models/well_known.rb
 - app/views/admin/admin_users/_form.html.erb
@@ -408,6 +413,7 @@ files:
 - app/views/admin/credentials/new.html.erb
 - app/views/admin/credentials/show.html.erb
 - app/views/admin/dashboards/show.html.erb
+- app/views/admin/device_authorizations/show.html.erb
 - app/views/admin/otps/_form.html.erb
 - app/views/admin/otps/create.turbo_stream.erb
 - app/views/admin/otps/new.html.erb
@@ -463,6 +469,7 @@ files:
 - db/migrate/20231211005214_add_status_code_to_url_rewrites.rb
 - db/migrate/20241214060913_add_otp_secret_to_admin_users.rb
 - db/migrate/20250204060748_create_well_knowns.rb
+- db/migrate/20260413014834_create_admin_device_authorizations.rb
 - db/seeds.rb
 - lib/generators/koi/admin/USAGE
 - lib/generators/koi/admin/admin_generator.rb
@@ -499,6 +506,7 @@ files:
 - lib/koi/middleware/admin_authentication.rb
 - lib/koi/middleware/url_redirect.rb
 - lib/koi/release.rb
+- spec/factories/admin_device_authorizations.rb
 - spec/factories/admins.rb
 - spec/factories/url_rewrites.rb
 - spec/factories/well_knowns.rb
@@ -521,7 +529,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Koi CMS admin framework
 test_files: []