create and read ownership transfer

[DNR500]

Summary WIP

• Backend for #1766 / #1767 / #1770.
• Tracked on https://github.com/RaspberryPiFoundation/digital-editor-issues/issues/1813

This PR adds the two endpoints editor-standalone needs for the owner-initiates / nominee-reviews flow: starting a transfer, and checking its status.

What's changed?

• POST /api/schools/:school_id/ownership_transfer — the school owner nominates another owner or teacher at the school to take over. Sends the nomination email on success; rejects the nominee if they don't hold an owner/teacher role at the school, or if the school already has a pending transfer
• GET /api/schools/:school_id/ownership_transfer — returns the school's most recent transfer, whatever its status, and who the current user is relative to it (owner/nominee); anyone not involved gets a 404, same as if no transfer had ever existed
• A partial unique index on ownership_transfers.school_id (scoped to status = 'pending') plus a matching model validation, so two concurrent create requests can't both succeed — closes a race condition Update ownership transfer and mailer #1019 flagged as not yet covered

Adds the endpoint editor-standalone needs to show ownership transfer status to both the owner and the nominee.

Examples

Creating a transfer

POST /api/schools/9d9c1e3e-1e4b-4b0a-9a2e-6a2b7e6f1a10/ownership_transfer
Authorization: Bearer <owner's token>
Content-Type: application/json

{ "ownership_transfer": { "nominated_user_id": "3f2b1c4a-...-a1b2c3d4e5f6" } }

As the school owner, nominating a teacher or another owner at the school:

201 Created

(empty body — the nominee gets an email; the requester and nominee then use the GET endpoint below to see it)

If the nominated user doesn't hold an owner/teacher role at the school:

// 422 Unprocessable Content
{
  "error": {
    "nominated_user_id": ["'3f2b1c4a-...' does not have the 'owner' or 'teacher' role for school '9d9c1e3e-...'"]
  }
}

If the school already has a pending transfer (whether from this request racing another, or a genuinely separate attempt):

// 422 Unprocessable Content
{
  "error": {
    "school_id": ["already has a pending ownership transfer"]
  }
}

Other responses: 401 (no token), 403 (caller isn't an owner of that school — teachers and students can view a transfer but not start one).

Checking transfer status

GET /api/schools/9d9c1e3e-1e4b-4b0a-9a2e-6a2b7e6f1a10/ownership_transfer
Authorization: Bearer <token>

As the owner who requested it, while it's pending:

// 200 OK
{
  "status": "pending",
  "you_are": "owner",
  "nominee_name": "Priya Shah"
}

As the nominee, while it's pending:

// 200 OK
{
  "status": "pending",
  "you_are": "nominee"
}

The transfer stays visible to the requester and nominee after it's resolved — status reflects whatever actually happened, rather than the response disappearing once it's no longer pending:

// 200 OK — the requester, after the nominee accepted
{
  "status": "completed",
  "you_are": "owner",
  "nominee_name": "Priya Shah"
}

// 200 OK — the nominee, after declining it themselves
{
  "status": "rejected",
  "you_are": "nominee"
}

As another teacher or owner at the school who wasn't involved (or if no transfer has ever existed for the school) — deliberately indistinguishable, so the response doesn't leak whether one exists or what happened to it:

404 Not Found

(empty body)

Other responses: 401 (no token), 403 (caller is a school-student — a category that's never eligible to view or act on an ownership transfer at all, so it's rejected outright rather than folded into the 404 case above).

[github-actions]

Test coverage

93.67% line coverage reported by SimpleCov.
Run: https://github.com/RaspberryPiFoundation/editor-api/actions/runs/35360175400

[Copilot]

🟡 Changes recommended

The current model/controller behavior can surface incorrect validation errors for invalid nominees and the authorization behavior for students appears inconsistent with the PR description.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds REST support for school ownership transfers so editor-standalone can (1) start a transfer (owner nominates) and (2) read the latest transfer’s status (requester/nominee visibility with 404 for non-involved users).

Changes:

• Introduces POST /api/schools/:school_id/ownership_transfer and GET /api/schools/:school_id/ownership_transfer with Cancancan authorization.
• Adds DB + model protection against concurrent pending transfers (partial unique index + validation), plus a domain operation for creation.
• Adds request/unit/model specs and shared RSpec helpers for the new flow.

File summaries

File	Description
spec/support/shared_examples/ownership_transfer_examples.rb	Shared example for asserting “hidden transfer” 404 behavior.
spec/support/shared_contexts/ownership_transfer_context.rb	Shared context for owner/nominee setup and auth headers.
spec/models/school_spec.rb	Adds specs for School#owner_or_teacher? and updates ownership transfer association spec for new status constraints.
spec/models/ownership_transfer_spec.rb	Adds specs for “only one pending transfer per school” (including DB constraint behavior).
spec/features/ownership_transfer/viewing_ownership_transfer_status_spec.rb	Request specs for GET status endpoint across roles and transfer statuses.
spec/features/ownership_transfer/creating_an_ownership_transfer_spec.rb	Request specs for POST create endpoint, validation errors, and mail enqueue.
spec/concepts/ownership_transfer/create_spec.rb	Unit specs for creation operation, including concurrency handling and error reporting.
lib/concepts/ownership_transfer/create.rb	New operation object for creating a transfer and mapping race conditions to friendly errors.
db/schema.rb	Captures new partial unique index in schema dump.
db/migrate/20260915100000_add_unique_pending_index_to_ownership_transfers.rb	Adds partial unique index enforcing one pending transfer per school.
config/routes.rb	Adds nested singular ownership_transfer resource routes under schools.
config/locales/en.yml	Adds i18n message for “school already has pending transfer”.
app/models/school.rb	Adds owner_or_teacher?(user_id) helper.
app/models/ownership_transfer.rb	Adds pending uniqueness validation and uses School#owner_or_teacher? in nominee-role validation.
app/models/ability.rb	Adds ownership transfer read permissions (object-level) and controller-level abilities (symbol).
app/controllers/api/ownership_transfers_controller.rb	New API controller implementing show/create behavior and “hide from non-involved users” logic.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[DNR500]

Addressed