get/read ownership transfer

app/controllers/api/ownership_transfers_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Api
+  class OwnershipTransfersController < ApiController
+    before_action :authorize_user
+    load_and_authorize_resource :school
+    authorize_resource :ownership_transfer, class: false
+
+    def show
+      @ownership_transfer = most_recent_ownership_transfer
+
+      if @ownership_transfer.blank? || cannot?(:read, @ownership_transfer)
+        head :not_found
+      elsif current_user_is_requester?
+        render json: { status: @ownership_transfer.status, you_are: 'owner', nominee_name: nominee_name }, status: :ok
+      else
+        render json: { status: @ownership_transfer.status, you_are: 'nominee' }, status: :ok
+      end
+    end
+
+    def create
+      result = OwnershipTransfer::Create.call(school: @school, nominated_user_id:, requested_by_user_id: current_user.id)
+
+      if result.success?
+        head :created
+      else
+        render json: { error: result[:error] }, status: :unprocessable_content
+      end
+    end
+
+    private
+
+    def ownership_transfer_params
+      params.expect(ownership_transfer: [:nominated_user_id])
+    end
+
+    def nominated_user_id
+      ownership_transfer_params[:nominated_user_id]
+    end
+
+    def most_recent_ownership_transfer
+      @school.ownership_transfers.order(created_at: :desc).first
+    end
+
+    def current_user_is_requester?
+      @ownership_transfer.requested_by_user_id == current_user.id
+    end
+
+    def nominee_name
+      User.from_userinfo(ids: @ownership_transfer.nominated_user_id).first&.name
+    end
+  end
+end

app/models/ability.rb

@@ -39,6 +39,9 @@ def define_authenticated_abilities(user)
         invitation.email_address.present? &&
         invitation.email_address.casecmp?(user.email)
     end
+    can :read, OwnershipTransfer do |transfer|
+      user.id == transfer.requested_by_user_id || user.id == transfer.nominated_user_id
+    end
   end
 
   def define_authenticated_non_student_abilities(user)
@@ -82,6 +85,7 @@ def define_school_owner_abilities(school:)
     can(%i[read create create_batch destroy], ClassStudent, school_class: { school: { id: school.id } })
     can(%i[read create destroy], :school_owner)
     can(%i[read create destroy], :school_teacher)
+    can(%i[read create], :ownership_transfer)
     can(%i[read create create_batch update destroy destroy_batch], :school_student)
     can(%i[create create_copy], Lesson, school_id: school.id)
     can(%i[read update destroy], Lesson, school_id: school.id, visibility: %w[teachers students public])
@@ -98,6 +102,7 @@ def define_school_teacher_abilities(user:, school:)
     can(%i[read create create_batch destroy], ClassStudent, school_class: { school: { id: school.id }, teachers: { teacher_id: user.id } })
     can(%i[read], :school_owner)
     can(%i[read], :school_teacher)
+    can(:read, :ownership_transfer)
     can(%i[read create create_batch update], :school_student)
     can(%i[create update destroy], Lesson) do |lesson|
       school_teacher_can_manage_lesson?(user:, school:, lesson:)

app/models/ownership_transfer.rb

@@ -4,13 +4,34 @@ class OwnershipTransfer < ApplicationRecord
   delegate :name, to: :school, prefix: true
 
   belongs_to :school
+
+  enum :status, {
+    pending: 'pending', completed: 'completed', rejected: 'rejected', cancelled: 'cancelled'
+  }, default: :pending, validate: true
+
+  validates :nominated_user_id, presence: true
+  validates :requested_by_user_id, presence: true
   validates :email_address,
             format: { with: EmailValidator.regexp, message: I18n.t('validations.invitation.email_address') }
+  validates :school_id,
+            uniqueness: { conditions: -> { where(status: :pending) }, message: I18n.t('validations.ownership_transfer.school_pending') },
+            on: :create
+  validate :nominee_has_the_school_owner_or_school_teacher_role_for_the_school
+
   after_create_commit :send_ownership_transfer_request_email
   encrypts :email_address
 
   private
 
+  def nominee_has_the_school_owner_or_school_teacher_role_for_the_school
+    return unless nominated_user_id_changed? && errors.blank? && school
+
+    return if school.roles.exists?(user_id: nominated_user_id, role: %i[owner teacher])
+
+    msg = "'#{nominated_user_id}' does not have the 'owner' or 'teacher' role for school '#{school.id}'"
+    errors.add(:nominated_user_id, msg)
+  end
+
   def send_ownership_transfer_request_email
     SchoolOwnershipMailer.with(ownership_transfer: self).request_ownership_transfer.deliver_later
   end

app/models/school.rb

@@ -7,6 +7,7 @@ class School < ApplicationRecord
   has_many :roles, dependent: :nullify
   has_many :school_projects, dependent: :nullify
   has_many :school_email_domains, dependent: :destroy
+  has_many :ownership_transfers, dependent: :destroy
 
   VALID_URL_REGEX = %r{\A(?:https?://)?(?:www.)?[a-z0-9]+([-.]{1}[a-z0-9]+)*\.[a-z]{2,63}(\.[a-z]{2,63})*(/.*)?\z}ix
 

config/locales/en.yml

@@ -23,6 +23,8 @@ en:
       school_roll_number_exists: "School roll number already exists"
     invitation:
       email_address: "'%<value>s' is invalid"
+    ownership_transfer:
+      school_pending: "already has a pending ownership transfer"
   activerecord:
     attributes:
       school_class:

config/routes.rb

@@ -87,6 +87,7 @@
 
       resources :owners, only: %i[index], controller: 'school_owners'
       resources :teachers, only: %i[index create], controller: 'school_teachers'
+      resource :ownership_transfer, only: %i[show create], controller: 'ownership_transfers'
       resources :students, only: %i[index create update destroy], controller: 'school_students' do
         post :batch, on: :collection, to: 'school_students#create_batch'
         delete :batch, on: :collection, to: 'school_students#destroy_batch'

db/migrate/20260915093824_add_nominee_and_status_to_ownership_transfers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddNomineeAndStatusToOwnershipTransfers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :ownership_transfers, :nominated_user_id, :uuid, null: false
+    add_column :ownership_transfers, :requested_by_user_id, :uuid, null: false
+    add_column :ownership_transfers, :status, :string, null: false, default: 'pending'
+  end
+end

db/migrate/20260915100000_add_unique_pending_index_to_ownership_transfers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class AddUniquePendingIndexToOwnershipTransfers < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+
+  def change
+    add_index :ownership_transfers, :school_id,
+              unique: true,
+              where: "status = 'pending'",
+              name: 'index_ownership_transfers_on_school_id_when_pending',
+              algorithm: :concurrently
+  end
+end

lib/concepts/ownership_transfer/create.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class OwnershipTransfer
+  class Create
+    class << self
+      def call(school:, nominated_user_id:, requested_by_user_id:)
+        response = OperationResponse.new
+        ownership_transfer = build_ownership_transfer(school:, nominated_user_id:, requested_by_user_id:)
+
+        if ownership_transfer.save
+          response[:ownership_transfer] = ownership_transfer
+        else
+          response[:error] = ownership_transfer.errors
+        end
+
+        response
+      rescue StandardError => e
+        Sentry.capture_exception(e)
+        response[:error] = "Error creating ownership transfer: #{e}"
+        response
+      end
+
+      private
+
+      def build_ownership_transfer(school:, nominated_user_id:, requested_by_user_id:)
+        email_address = nominee_email(school:, nominated_user_id:)
+        OwnershipTransfer.new(school:, nominated_user_id:, requested_by_user_id:, email_address:)
+      end
+
+      def nominee_email(school:, nominated_user_id:)
+        return unless school.roles.exists?(user_id: nominated_user_id, role: %i[owner teacher])
+
+        User.from_userinfo(ids: nominated_user_id).first&.email
+      end
+    end
+  end
+end

spec/factories/ownership_transfer.rb

@@ -2,7 +2,10 @@
 
 FactoryBot.define do
   factory :ownership_transfer do
-    email_address { 'new-owner@example.com' }
-    school factory: :verified_school
+    school
+    email_address { Faker::Internet.email }
+    nominated_user_id { SecureRandom.uuid }
+    requested_by_user_id { SecureRandom.uuid }
+    status { 'pending' }
   end
 end

spec/features/ownership_transfer/creating_an_ownership_transfer_spec.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe 'Creating an ownership transfer', type: :request do
+  include ActionMailer::TestHelper
+
+  include_context 'with a school owner and nominated teacher'
+
+  let(:params) { { ownership_transfer: { nominated_user_id: nominee.id } } }
+
+  before do
+    stub_user_info_api_for(nominee)
+  end
+
+  it 'responds 401 Unauthorized when no token is given' do
+    post("/api/schools/#{school.id}/ownership_transfer", params:)
+    expect(response).to have_http_status(:unauthorized)
+  end
+
+  it 'responds 403 Forbidden when the user is a school-teacher' do
+    authenticated_in_hydra_as(nominee)
+
+    post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+    expect(response).to have_http_status(:forbidden)
+  end
+
+  it 'responds 403 Forbidden when the user is a school-student' do
+    student = create(:student, school:)
+    authenticated_in_hydra_as(student)
+
+    post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+    expect(response).to have_http_status(:forbidden)
+  end
+
+  it 'responds 403 Forbidden when the user is the owner of a different school' do
+    authenticated_in_hydra_as(owner)
+    Role.owner.find_by(user_id: owner.id, school:).delete
+    Role.teacher.find_by(user_id: nominee.id, school:).delete
+    school.update!(id: SecureRandom.uuid)
+
+    post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+    expect(response).to have_http_status(:forbidden)
+  end
+
+  context 'when the current user is the school owner' do
+    before { authenticated_in_hydra_as(owner) }
+
+    context 'when the nominee has the teacher role at the school' do
+      it 'responds 201 Created' do
+        post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        expect(response).to have_http_status(:created)
+      end
+
+      it 'creates an ownership transfer for the nominee' do
+        expect do
+          post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        end.to change(OwnershipTransfer, :count).by(1)
+
+        expect(OwnershipTransfer.last).to have_attributes(
+          school:,
+          nominated_user_id: nominee.id,
+          requested_by_user_id: owner.id,
+          email_address: nominee.email,
+          status: 'pending'
+        )
+      end
+
+      it 'sends the ownership transfer request email' do
+        post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+
+        assert_enqueued_email_with(
+          SchoolOwnershipMailer,
+          :request_ownership_transfer,
+          params: { ownership_transfer: OwnershipTransfer.last }
+        )
+      end
+    end
+
+    context 'when the nominee does not have the owner or teacher role at the school' do
+      let(:params) { { ownership_transfer: { nominated_user_id: SecureRandom.uuid } } }
+
+      it 'responds 422 Unprocessable entity' do
+        post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        expect(response).to have_http_status(:unprocessable_content)
+      end
+
+      it 'does not create an ownership transfer' do
+        expect do
+          post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        end.not_to change(OwnershipTransfer, :count)
+      end
+    end
+
+    context 'when a transfer is already pending for the school' do
+      before { create(:ownership_transfer, school:, nominated_user_id: nominee.id) }
+
+      it 'responds 422 Unprocessable entity' do
+        post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        expect(response).to have_http_status(:unprocessable_content)
+      end
+
+      it 'does not create a second ownership transfer' do
+        expect do
+          post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        end.not_to change(OwnershipTransfer, :count)
+      end
+    end
+
+    context 'when a transfer for the school is no longer pending' do
+      before { create(:ownership_transfer, school:, nominated_user_id: nominee.id, status: :completed) }
+
+      it 'responds 201 Created' do
+        post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        expect(response).to have_http_status(:created)
+      end
+
+      it 'creates a new ownership transfer' do
+        expect do
+          post("/api/schools/#{school.id}/ownership_transfer", params:, headers:)
+        end.to change(OwnershipTransfer, :count).by(1)
+      end
+    end
+  end
+end