administrate-mcp 0.1.0

data/docs/configuration.md

@@ -0,0 +1,220 @@
+# Configuration
+
+[Back to README](../README.md)
+
+Configure the engine in an initializer, `config/initializers/administrate_mcp.rb`. It must run
+before the engine's models load, because the `admin` association reads `admin_class_name`.
+
+```ruby
+Administrate::MCP.configure do |c|
+  c.server_name = 'acme_admin'
+  c.server_version = '1.0.0'
+
+  c.admin_class_name = 'Administrator'
+  c.current_admin = ->(controller) { controller.send(:warden)&.authenticate(scope: :administrator) }
+  c.admin_active = ->(admin) { admin.admin? && admin.anonymized_at.nil? }
+  c.sign_in = lambda do |controller|
+    controller.send(:store_location_for, :administrator, controller.request.fullpath)
+    controller.redirect_to(controller.main_app.new_administrator_session_path)
+  end
+
+  # These procs are also called without a request, when the engine builds a record URL outside a
+  # request cycle, so guard the dereference.
+  c.issuer = ->(request) { request&.subdomain == 'admin-mcp' ? request.base_url : 'https://admin-mcp.acme.com' }
+  c.admin_origin = ->(request) { request&.subdomain == 'admin' ? request.base_url : 'https://admin.acme.com' }
+  c.admin_url_options = { subdomain: 'admin' }
+
+  c.authorization = Administrate::MCP::Authorization::Pundit.new
+  c.default_required_roles = [:full_access]
+
+  c.tool_paths = [Rails.root.join('app/mcp_tools')]
+
+  c.instrument = lambda do |tool_name:, admin:, &block|
+    Datadog::Tracing.trace('call', resource: tool_name, service: 'mcp_tool') { block.call }
+  end
+  c.on_tool_call = lambda do |tool_name:, admin:, arguments:, scopes:|
+    Admin::AuditOperation.call!(administrator_id: admin.id, request_method: 'POST',
+                                request_url: "mcp://tools/#{tool_name}", params: arguments)
+  end
+  c.on_feedback = ->(feedback) { SlackNotifier.notify(notification_type: :mcp_feedback, blocks: blocks_for(feedback)) }
+end
+```
+
+## The full configuration object
+
+```ruby
+class Configuration
+  SKIPPED_FIELD_CLASSES = ['Administrate::Field::Password'].freeze
+
+  HAS_MANY_FIELD_CLASSES = ['Administrate::Field::HasMany'].freeze
+
+  FIELD_SERIALIZERS = {
+    'Administrate::Field::HasMany' => :has_many,
+    'Administrate::Field::Polymorphic' => :polymorphic,
+    'Administrate::Field::BelongsTo' => :belongs_to,
+    'Administrate::Field::HasOne' => :belongs_to,
+    'Administrate::Field::DateTime' => :datetime,
+    'Administrate::Field::Date' => :datetime,
+    'Administrate::Field::Time' => :datetime,
+    'Administrate::Field::Enum' => :enum,
+    'Administrate::Field::Select' => :enum,
+    'Administrate::Field::Shrine' => :attachment,
+    'Administrate::Field::String' => :scalar,
+    'Administrate::Field::Text' => :scalar,
+    'Administrate::Field::Email' => :scalar,
+    'Administrate::Field::Url' => :scalar,
+    'Administrate::Field::Number' => :scalar,
+    'Administrate::Field::Boolean' => :scalar
+  }.freeze
+
+  attr_accessor :server_name,
+                :server_version,
+                :issuer,
+                :admin_origin,
+                :current_admin,
+                :admin_active,
+                :identity_fallback,
+                :oauth,
+                :sign_in,
+                :admin_class_name,
+                :authorization,
+                :default_required_roles,
+                :tool_paths,
+                :dashboard_paths,
+                :instrument,
+                :on_tool_call,
+                :on_feedback,
+                :on_error,
+                :allow_localhost_redirects,
+                :default_client_name,
+                :sidekiq_stats_provider,
+                :admin_route_namespace,
+                :admin_url_options,
+                :skipped_field_classes,
+                :has_many_field_classes,
+                :field_serializers
+
+  attr_reader :api_key_token_prefix
+
+  def assign_identity
+    @server_name = 'administrate_mcp'
+    @server_version = VERSION
+    @issuer = nil
+    @admin_origin = nil
+    @current_admin = ->(_controller) {}
+    @admin_active = ->(_admin) { true }
+    @identity_fallback = ->(_request) {}
+    @oauth = true
+    @sign_in = nil
+    @admin_class_name = 'Administrator'
+    @authorization = default_authorization
+    @default_required_roles = []
+    @tool_paths = []
+    @dashboard_paths = nil
+  end
+
+  def assign_hooks
+    @instrument = ->(tool_name:, admin:, &block) { block.call }
+    @on_tool_call = ->(tool_name:, admin:, arguments:, scopes:) {}
+    @on_feedback = ->(feedback) {}
+    @on_error = ->(exception) {}
+    @allow_localhost_redirects = true
+    @api_key_token_prefix = 'amcp_'
+    @default_client_name = 'MCP Client'
+    @sidekiq_stats_provider = nil
+  end
+
+  def assign_fields
+    @admin_route_namespace = :admin
+    @admin_url_options = {}
+    @skipped_field_classes = SKIPPED_FIELD_CLASSES.dup
+    @has_many_field_classes = HAS_MANY_FIELD_CLASSES.dup
+    @field_serializers = FIELD_SERIALIZERS.dup
+  end
+
+  def api_key_token_prefix=(prefix); end          # raises ArgumentError on a blank prefix
+
+  def register_field(class_name, as: nil, &serializer); end
+  def skip_field(*class_names); end
+  def register_has_many_field(*class_names); end
+
+  def issuer_for(request = nil); end
+  def admin_origin_for(request = nil); end
+  def dashboard_directories; end
+end
+```
+
+| Entry                       | Default                            | What it does                                                                                                                                                                     |
+| --------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server_name`               | `'administrate_mcp'`               | Name reported in the MCP handshake                                                                                                                                               |
+| `server_version`            | the gem version                    | Version reported in the handshake                                                                                                                                                |
+| `issuer`                    | `nil`                              | MCP origin. String or a proc taking the request                                                                                                                                  |
+| `admin_origin`              | `nil`                              | Admin origin, where the consent screen lives. String or proc                                                                                                                     |
+| `current_admin`             | returns `nil`                      | Proc taking the OAuth controller, returning the signed-in admin                                                                                                                  |
+| `admin_active`              | `true`                             | Proc taking the authenticated admin. Return false and the call is refused with 401 `inactive_admin`, so a credential does not outlive the person's admin status                  |
+| `identity_fallback`         | returns `nil`                      | Proc taking the request, returning an `Authentication::Identity` or nil, consulted when no credential the engine issued matched                                                  |
+| `oauth`                     | `true`                             | Whether the engine serves its own OAuth 2.1 server. False draws no OAuth routes and never looks an access token up                                                               |
+| `sign_in`                   | `nil` (renders 401)                | Proc taking the OAuth controller, sending an anonymous visitor to sign in                                                                                                        |
+| `admin_class_name`          | `'Administrator'`                  | Class the `admin_id` column points at                                                                                                                                            |
+| `authorization`             | Pundit if defined, else Permissive | Adapter: `authorize!`, `authorized?`, `authorize_roles!`                                                                                                                         |
+| `default_required_roles`    | `[]`                               | Roles a tool requires unless it declares its own                                                                                                                                 |
+| `tool_paths`                | `[]`                               | Directories scanned for extra `BaseTool` subclasses                                                                                                                              |
+| `dashboard_paths`           | `app/dashboards`                   | Where dashboards are found                                                                                                                                                       |
+| `instrument`                | yields                             | Around hook `(tool_name:, admin:, &block)`                                                                                                                                       |
+| `on_tool_call`              | no-op                              | Audit hook `(tool_name:, admin:, arguments:, scopes:)`, after the permission checks                                                                                              |
+| `on_feedback`               | no-op                              | Called with each new `Feedback` record                                                                                                                                           |
+| `on_error`                  | no-op                              | Called with an exception the engine swallowed, so you can report it                                                                                                              |
+| `allow_localhost_redirects` | `true`                             | Whether loopback OAuth redirect URIs are accepted. Inert when `oauth` is false                                                                                                   |
+| `api_key_token_prefix`      | `'amcp_'`                          | Prefix that marks a bearer token as an API key. Cannot be blank                                                                                                                  |
+| `default_client_name`       | `'MCP Client'`                     | Name given to a dynamically registered client that sends no `client_name`. Inert when `oauth` is false                                                                           |
+| `sidekiq_stats_provider`    | `nil`                              | Object answering `counts`, `total_counts`, `queues`, `stats_cleared_at`; a class name String or a Proc is resolved lazily so autoloaded providers can be named in an initializer |
+| `admin_route_namespace`     | `:admin`                           | Namespace record URLs are built from                                                                                                                                             |
+| `admin_url_options`         | `{}`                               | Options passed to `polymorphic_url`; when no `:host` is given, host, protocol and port are taken from `admin_origin`                                                             |
+| `skipped_field_classes`     | Password                           | Field class names never serialized                                                                                                                                               |
+| `has_many_field_classes`    | HasMany                            | Field class names treated as expandable collections                                                                                                                              |
+| `field_serializers`         | see above                          | Field class name to serializer                                                                                                                                                   |
+
+## Authorization adapters
+
+`Authorization::Permissive` grants every action to every authenticated admin. `Authorization::Pundit`
+runs the policy for the resource exactly as the Administrate UI does: `index?` to list, `show?` to
+read, and the action's own predicate for a write action.
+
+Both inherit `authorize_roles!` from `Authorization::Base`: a tool's `requires_roles` (or
+`default_required_roles`) is checked with `admin.can_access?(*roles)`. An admin class that does not
+answer `can_access?` raises `Administrate::MCP::ConfigurationError` rather than letting the call
+through. Clear `default_required_roles`, give the class the method, or override `authorize_roles!`.
+
+`report_mcp_improvement` requires no role: reporting that a tool description or result is wrong is
+not a privileged action, so it stays open to any authenticated admin regardless of
+`default_required_roles`.
+
+Write your own by answering three methods:
+
+```ruby
+class MyAuthorization < Administrate::MCP::Authorization::Base
+  def authorize!(admin, record_or_class, action); end     # raise Administrate::MCP::UnauthorizedError
+  def authorized?(admin, record_or_class, action); end    # true / false
+  def authorize_roles!(admin, roles); end                 # optional, inherited
+end
+```
+
+## Serializing your own field classes
+
+The engine matches field classes by name, walking the field's ancestors, so it never references a
+class you own:
+
+```ruby
+Administrate::MCP.configure do |c|
+  c.register_field('MonetaryAmountsField') { |source| source.value&.serialize }
+  c.register_field('AnyAttachmentField', as: :attachment)
+  c.register_has_many_field('HasManyNonAssociationField')
+  c.skip_field('GridField', 'HasOneNonAssociationField')
+end
+```
+
+A field class that answers `mcp_value(record, attr_name)` and is not registered is asked for its own
+value. An unregistered field class with no `mcp_value` falls back to its raw value.
+
+`Field::Text` and `Field::Url`, along with every other field class registered as `:scalar`,
+serialize a nil value as `null` rather than an empty string.

data/docs/dashboards.md

@@ -0,0 +1,50 @@
+# Dashboard declarations
+
+[Back to README](../README.md)
+
+```ruby
+class OrderDashboard < Administrate::BaseDashboard
+  MCP_DESCRIPTION = 'Customer orders, including the cancelled ones the UI hides by default.'
+  MCP_BASE_SCOPE = -> { Order.unscope(where: :state) }
+
+  COLLECTION_FILTERS = {
+    unpaid: ->(scope) { scope.where(paid_at: nil) },
+    for_country: ->(scope, code) { scope.where(country: code) }
+  }.freeze
+
+  mcp_action :refund,
+             description: 'Refund an order.',
+             params: { reason: { type: 'string', description: 'Why the order is being refunded.' } } do |record:, admin:, params:|
+    Orders::Refund.call!(order: record, admin:, reason: params[:reason])
+  end
+end
+```
+
+Every `MCP_` constant and `COLLECTION_FILTERS` is read off the dashboard itself, never inherited, so
+a constant of the same name defined at the top level of your application, or on a shared dashboard
+base class, is not applied to every resource. A subclass that wants one declares it.
+
+- `MCP_DESCRIPTION` tells the client what the resource is.
+- `MCP_SKIPPED_ATTRIBUTES = %i[email]` keeps attributes visible in the admin UI but out of MCP
+  reads, listings and field selection.
+- `MCP_EXPOSED = false` leaves the dashboard out of the MCP registry entirely.
+- Namespaced models work through the dashboard's own `self.model`, as in Administrate.
+- `MCP_BASE_SCOPE` replaces the model's default scope for MCP reads, mirroring an admin controller's
+  `scoped_resource`.
+- `COLLECTION_FILTERS` are published as filters; a one-argument lambda is a boolean filter, a
+  two-argument one takes a value. Foreign key columns are filterable without being declared.
+- `mcp_action` publishes one tool per declaration. It requires the OAuth `write` scope, and the
+  authorization predicate (`refund?` by default, or `predicate:`) on the loaded record. The block
+  receives `record:`, `admin:` and `params:`; a result answering `success? == false` is reported as
+  an error.
+
+## Search
+
+The `admin_resource_list` tool's `query` argument matches exactly by default, so searching for an id
+or a slug does not also match every row that merely contains it. `*` is the only wildcard. Every
+comparison casts the column to text first, so a search term matched against a uuid `id` column
+returns no rows instead of raising an error.
+
+Search is implemented by `FastSearch`, a subclass of `Administrate::Search` that calls methods that
+class treats as internal (`search_attributes`, `searchable_fields`, `query_table_name`,
+`column_to_query`). That is why the gemspec pins `administrate` below 2.0.

data/docs/development.md

@@ -0,0 +1,19 @@
+# Development
+
+[Back to README](../README.md)
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+You need a reachable PostgreSQL server; the test suite creates its own database on first run (the
+spec helper catches `ActiveRecord::NoDatabaseError` and calls `ActiveRecord::Tasks::DatabaseTasks.create`),
+so no separate `createdb` step is needed. Point the specs at another Postgres with
+`ADMINISTRATE_MCP_DB_HOST`, `_PORT`, `_USER`, `_PASSWORD` and `_NAME`.
+
+The dummy application under `spec/dummy` has an `Admin`, a `Widget` (with `MCP_BASE_SCOPE` and
+collection filters) and a `Gadget` (with a `belongs_to` and an `mcp_action`).
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to propose a change.

data/docs/oauth.md

@@ -0,0 +1,54 @@
+# OAuth
+
+[Back to README](../README.md)
+
+The engine ships a complete OAuth 2.1 authorization server: Dynamic Client Registration, a consent
+screen, PKCE, refresh tokens, and the two discovery documents clients read to find all of it. That is
+the default, and for most hosts it is the whole story.
+
+It does not fit a deployment where something in front of the application already does this. Cloudflare
+Access managed OAuth, for instance, serves both discovery documents at its own edge and points
+clients at `<team>.cloudflareaccess.com` for authorization, token, registration and revocation. The
+engine's endpoints are then unreachable, and advertising them only gives clients a second, broken
+answer. Turn the server off:
+
+```ruby
+Administrate::MCP.configure do |c|
+  c.oauth = false
+end
+```
+
+`Routes.draw_mcp_origin` then draws the JSON-RPC endpoint and nothing else: no `/.well-known/*`, no
+`/oauth/register`, no `/oauth/token`, and `Routes.draw_admin_origin` becomes a no-op, so you can
+leave both calls where they are. API keys keep working. An OAuth token presented while the server is
+off is a bearer token the engine does not recognise, and goes to `identity_fallback` like any other.
+
+The models and migrations still ship, and the tables are never queried while `oauth` is false, so a
+host that never ran that migration boots and serves normally. `default_client_name` and
+`allow_localhost_redirects` have nothing to act on and are inert.
+
+A verifier for Cloudflare Access managed OAuth ships with the gem, for hosts that run authentication
+at the edge instead of through this server: see
+[Identity fallback](authentication.md#identity-fallback) in the authentication guide.
+
+## Dynamic Client Registration
+
+Registration accepts `localhost`, `127.0.0.1`, `::1` and any `*.localhost` subdomain as loopback
+hosts, and issues authorization codes to them over plain http rather than requiring https.
+`*.localhost` covers parallel development checkouts running on different subdomains. The match is
+made on the parsed hostname, so a redirect URI on a host such as `localhost.attacker.com` is
+rejected. Set `allow_localhost_redirects = false` to require https for every redirect URI, including
+loopback ones.
+
+## Rate limiting
+
+The gem does not depend on rack-attack. If you use it, these are the throttles to add, or call
+`Administrate::MCP::RackAttack.throttles(host: 'admin-mcp')` from your own initializer, which
+registers exactly these:
+
+| Name                        | Request                                | Limit                |
+| --------------------------- | -------------------------------------- | -------------------- |
+| `mcp_oauth/register/ip`     | `POST /oauth/register` on the MCP host | 5 per minute per IP  |
+| `mcp_oauth/register/ip-day` | `POST /oauth/register` on the MCP host | 50 per day per IP    |
+| `mcp_oauth/token/ip`        | `POST /oauth/token` on the MCP host    | 10 per minute per IP |
+| `mcp_oauth/authorize/ip`    | `GET /mcp/oauth/authorize`             | 20 per minute per IP |

data/docs/routes.md

@@ -0,0 +1,30 @@
+# Routes
+
+[Back to README](../README.md)
+
+The consent screen must be served on the admin origin, where the admin's session lives, while the
+JSON-RPC and metadata endpoints live on a dedicated MCP origin. Draw each set inside your own
+constraints:
+
+```ruby
+Rails.application.routes.draw do
+  constraints ->(request) { request.subdomain == 'admin-mcp' } do
+    Administrate::MCP::Routes.draw_mcp_origin(self)
+  end
+
+  constraints subdomain: 'admin' do
+    Administrate::MCP::Routes.draw_admin_origin(self)
+  end
+end
+```
+
+`draw_mcp_origin` adds `/.well-known/oauth-protected-resource`,
+`/.well-known/oauth-authorization-server`, `POST /oauth/register`, `POST /oauth/token` and the
+JSON-RPC endpoint at `/`. `draw_admin_origin` adds `GET` and `POST /mcp/oauth/authorize`; pass
+`path:` to move it. With `config.oauth` false the OAuth routes are left out of both. See
+[OAuth](oauth.md) for what that means.
+
+Both sets have to sit at the root of their origin. The metadata documents the engine publishes name
+the token, registration and JSON-RPC endpoints as absolute paths, `/oauth/token`, `/oauth/register`,
+`/`, so mounting the engine under a prefix would advertise paths that do not answer. If you serve
+everything on a single origin, call both helpers on that origin rather than mounting the engine.

data/lib/administrate/mcp/authorization/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'administrate/mcp/errors'
+
+module Administrate
+  module MCP
+    module Authorization
+      # Shared role gating. Roles are a host concept: an admin class that does not answer
+      # `can_access?` cannot be gated on them, and saying so beats letting the call through.
+      class Base
+        def authorize!(admin, record_or_class, action)
+          return if authorized?(admin, record_or_class, action)
+
+          raise UnauthorizedError, "Not authorized to #{action} #{model_name(record_or_class)}"
+        end
+
+        def authorized?(_admin, _record_or_class, _action)
+          true
+        end
+
+        def authorize_roles!(admin, roles)
+          return if roles.blank?
+
+          unless admin.respond_to?(:can_access?)
+            raise ConfigurationError,
+                  "#{admin.class.name} does not respond to can_access?, so the required roles " \
+                  "#{roles.join(', ')} cannot be checked. Give the admin class a can_access?(*roles) " \
+                  'method, clear default_required_roles, or override authorize_roles! on the ' \
+                  'authorization adapter.'
+          end
+
+          return if admin.can_access?(*roles)
+
+          raise UnauthorizedError, "Insufficient permissions. Required roles: #{roles.join(', ')}"
+        end
+
+        private
+
+        def model_name(record_or_class)
+          record_or_class.is_a?(Class) ? record_or_class.name : record_or_class.class.name
+        end
+      end
+    end
+  end
+end

data/lib/administrate/mcp/authorization/permissive.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'administrate/mcp/authorization/base'
+
+module Administrate
+  module MCP
+    module Authorization
+      # Grants every action to every authenticated admin. The default when the host has no policies.
+      class Permissive < Base
+      end
+    end
+  end
+end

data/lib/administrate/mcp/authorization/pundit.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'administrate/mcp/authorization/base'
+
+module Administrate
+  module MCP
+    module Authorization
+      # Runs the host's Pundit policy for the resource, exactly as the Administrate UI does.
+      class Pundit < Base
+        def authorize!(admin, record_or_class, action)
+          policy = policy_for(admin, record_or_class)
+          return if policy.public_send(action)
+
+          raise UnauthorizedError, "Not authorized to #{action} #{model_name(record_or_class)}"
+        end
+
+        def authorized?(admin, record_or_class, action)
+          authorize!(admin, record_or_class, action)
+          true
+        rescue UnauthorizedError, ::Pundit::NotDefinedError
+          false
+        end
+
+        private
+
+        def policy_for(admin, record_or_class)
+          ::Pundit::PolicyFinder.new(record_or_class).policy!.new(admin, record_or_class)
+        end
+      end
+    end
+  end
+end

data/lib/administrate/mcp/cloudflare_access.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/object/blank'
+require 'jwt'
+require 'net/http'
+
+module Administrate
+  module MCP
+    # Verifies the signed assertion Cloudflare Access attaches to every request it lets through.
+    #
+    # Clients using Access managed OAuth never reach an MCP server's own OAuth flow: Access resolves
+    # their token at its own edge and forwards the caller's identity in this header instead. Build
+    # one of these and hand it to `config.identity_fallback` — it answers `call(request)`.
+    #
+    # This ships in `lib` rather than `app` so a host initializer can name the constant: autoloading
+    # is not available while initializers run. Nothing outside a method body names a constant the
+    # engine autoloads, so `Authentication` still resolves at call time.
+    class CloudflareAccess
+      ASSERTION_HEADER = 'Cf-Access-Jwt-Assertion'
+      ALGORITHM = 'RS256'
+      CERTS_PATH = '/cdn-cgi/access/certs'
+      KEYS_CACHE_EXPIRY = 1.hour
+      AUTH_ERROR_TYPE = 'cloudflare_access'
+
+      NETWORK_ERRORS = [
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        Errno::EHOSTUNREACH,
+        Errno::ENETUNREACH,
+        IOError,
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        OpenSSL::SSL::SSLError,
+        SocketError,
+        Timeout::Error
+      ].freeze
+
+      # `team_domain` and `audience` each take a value or something that answers `call`. Hosts build
+      # this in an initializer, before the environment that carries those settings is necessarily
+      # readable, so a callable is re-read on every request rather than captured at boot.
+      def initialize(team_domain:, audience:, find_admin:, scopes_for: ->(_admin) { [] })
+        @team_domain = team_domain
+        @audience = audience
+        @find_admin = find_admin
+        @scopes_for = scopes_for
+      end
+
+      def team_domain
+        resolve(@team_domain)
+      end
+
+      def audience
+        resolve(@audience)
+      end
+
+      def call(request)
+        return nil unless configured?
+
+        assertion = request.headers[ASSERTION_HEADER]
+        return nil if assertion.blank?
+
+        payload = verify(assertion)
+        return nil if payload.nil?
+
+        admin = find_admin!(payload['email'])
+        Authentication::Identity.new(admin:, scopes: @scopes_for.call(admin))
+      end
+
+      def configured?
+        team_domain.present? && audience.present?
+      end
+
+      def verify(assertion)
+        kid = key_id(assertion)
+        return nil if kid.blank?
+
+        key = find_key(kid) || find_key(kid, refresh: true)
+        return nil if key.nil?
+
+        decode(assertion, key)
+      end
+
+      def decode(assertion, key)
+        JWT.decode(
+          assertion,
+          JWT::JWK.import(key).public_key,
+          true,
+          algorithms: [ALGORITHM],
+          iss: team_domain,
+          verify_iss: true,
+          aud: audience,
+          verify_aud: true
+        ).first
+      rescue JWT::DecodeError, JWT::JWKError
+        nil
+      end
+
+      def key_id(assertion)
+        JSON.parse(Base64.urlsafe_decode64(assertion.split('.').first))['kid']
+      rescue ArgumentError, JSON::ParserError
+        nil
+      end
+
+      def find_key(kid, refresh: false)
+        Rails.cache.delete(certs_url) if refresh
+        keys = Rails.cache.fetch(certs_url, expires_in: KEYS_CACHE_EXPIRY, skip_nil: true) { fetch_keys }
+        keys&.find { |key| key['kid'] == kid }
+      end
+
+      def fetch_keys
+        JSON.parse(Net::HTTP.get(URI.parse(certs_url)))['keys']
+      rescue JSON::ParserError, *NETWORK_ERRORS
+        nil
+      end
+
+      def certs_url
+        "#{team_domain}#{CERTS_PATH}"
+      end
+
+      private
+
+      def resolve(setting)
+        value = setting.respond_to?(:call) ? setting.call : setting
+        value.presence
+      end
+
+      # The identity provider decides how it capitalises an address; the lookup should not care.
+      def find_admin!(email)
+        admin = @find_admin.call(email.to_s.downcase)
+        return admin if admin
+
+        raise Authentication::ExternalIdentityError.new(
+          "No admin account for #{email}",
+          auth_error_type: AUTH_ERROR_TYPE
+        )
+      end
+    end
+  end
+end