standard_id 0.41.0 → 0.42.0

data/lib/standard_id/checks/migrations.rb

@@ -0,0 +1,61 @@
+module StandardId
+  module Checks
+    # A StandardHealth-compatible readiness check reporting StandardId
+    # migrations the host never installed or never ran (see
+    # StandardId::MigrationCheck).
+    #
+    # Duck-typed like StandardAudit::Checks::Retention — no dependency on
+    # standard_health; it exposes the `#initialize(name:, critical:)` + `#run`
+    # contract the aggregator calls. Register it NON-critical, so a missing
+    # index degrades /health/ready (HTTP 200) instead of failing the probe:
+    #
+    #   c.register_check :standard_id_migrations,
+    #                    StandardId::Checks::Migrations,
+    #                    critical: false
+    #
+    # Cheap: one directory scan plus one `schema_migrations` read, and once
+    # everything is present the :ok result is memoized for the life of the
+    # process (migration files cannot change without a deploy).
+    class Migrations
+      attr_reader :name
+
+      def initialize(name: :standard_id_migrations, critical: false)
+        @name = name
+        @critical = critical
+      end
+
+      def critical? = !!@critical
+
+      def run
+        return { status: :ok } if self.class.all_present?
+
+        all_missing = StandardId::MigrationCheck.pending(check_database: true)
+        if all_missing.empty?
+          self.class.all_present = true
+          return { status: :ok }
+        end
+
+        # Deferred upgrade steps (MigrationCheck::DEFERRED_UPGRADE_STEPS) are
+        # reported but never degrade readiness.
+        deferred, missing = all_missing.partition(&:info?)
+        if missing.empty?
+          return { status: :ok, pending_upgrade_steps: deferred.map(&:to_s) }
+        end
+
+        {
+          status: :warn,
+          message: "#{missing.size} StandardId migration(s) missing: #{missing.map(&:to_s).join(', ')}",
+          missing: missing.map { |m| { name: m.name, version: m.version, state: m.state } }
+        }
+      rescue StandardError => e
+        { status: :fail, error: e.message, error_class: e.class.name }
+      end
+
+      class << self
+        attr_writer :all_present
+
+        def all_present? = !!@all_present
+      end
+    end
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -9,8 +9,11 @@ StandardId::ConfigSchema.define do
     field :cache_store, type: :any, default: nil
     field :logger, type: :any, default: nil
     field :web_layout, type: :string, default: nil
-    field :passwordless_email_sender, type: :any, default: nil
-    field :passwordless_sms_sender, type: :any, default: nil
+    # Deprecated since 0.1.7 (see docs/MIGRATION_GUIDE.md), still honoured.
+    field :passwordless_email_sender, type: :any, default: nil,
+      deprecated: "deliver the code from a StandardId::Events::PASSWORDLESS_CODE_GENERATED subscriber instead (it runs synchronously in the request, so I18n.locale is still available; skip it when event[:skip_sender] is true) and call Otp.issue with its default delivery: :built_in. Removal in v2.0; see docs/MIGRATION_GUIDE.md."
+    field :passwordless_sms_sender, type: :any, default: nil,
+      deprecated: "deliver the code from a StandardId::Events::PASSWORDLESS_CODE_GENERATED subscriber instead (it runs synchronously in the request, so I18n.locale is still available; skip it when event[:skip_sender] is true) and call Otp.issue with its default delivery: :built_in. Removal in v2.0; see docs/MIGRATION_GUIDE.md."
     field :issuer, type: :string, default: nil
 
     # Whether `JwtService.decode` REQUIRES a matching `iss` claim.
@@ -55,6 +58,17 @@ StandardId::ConfigSchema.define do
     # loading for every app that never asked for it.
     field :association_strict_loading, type: :any, default: nil
 
+    # Boot-time check for StandardId migrations the host never copied in
+    # (StandardId::MigrationCheck). :warn, :raise or :ignore. nil (default)
+    # means :warn in development/test and :ignore elsewhere — it never raises
+    # in production unless you ask it to.
+    field :missing_migrations, type: :symbol, default: nil
+
+    # Gem migration names (e.g. "add_target_created_at_index_to_code_challenges")
+    # or original versions the check should skip — for a migration the host
+    # deliberately superseded or deferred.
+    field :ignored_migrations, type: :array, default: -> { [] }
+
     # Scope-aware authentication: maps scope names to profile-based access config.
     # Each scope is a hash with keys: :profile_types (Array<String>), :after_sign_in_path,
     # :no_profile_message, :label, :allow_registration, :authorizer.
@@ -139,9 +153,11 @@ StandardId::ConfigSchema.define do
   end
 
   scope :passwordless do
-    # Deprecated: use web.passwordless_login to control WebEngine passwordless login.
-    # Retained for backwards compatibility with consuming apps that set this field.
-    field :enabled, type: :boolean, default: false
+    # Deprecated since 0.8: use web.passwordless_login to control WebEngine
+    # passwordless login. Never read; retained so host initializers that set it
+    # still boot.
+    field :enabled, type: :boolean, default: false,
+      deprecated: "it has had no effect since 0.8. Use web.passwordless_login (WebEngine) instead, and remove this line. Removal in v2.0."
     field :connection, type: :string, default: "email"
     field :code_ttl, type: :integer, default: 600 # 10 minutes in seconds
 
@@ -162,7 +178,10 @@ StandardId::ConfigSchema.define do
     # rate limit (config.rate_limits.otp_verify_per_ip) — the per-IP limit
     # prevents brute-forcing from a single source, while this ceiling defends
     # against distributed brute-force attempts against the same challenge.
-    # When nil, falls back to :max_attempts for backwards compatibility.
+    # When nil, falls back to :max_attempts for backwards compatibility, so the
+    # effective default is 3 (:max_attempts' default), not 5. 5 is only the
+    # last resort when both are unset or non-positive
+    # (StandardId::Passwordless::FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE).
     field :max_attempts_per_challenge, type: :integer, default: nil
 
     field :retry_delay, type: :integer, default: 30 # 30 seconds
@@ -293,8 +312,12 @@ StandardId::ConfigSchema.define do
     # RefreshTokenFlow::MAX_REUSE_LEEWAY_SECONDS.
     field :refresh_token_reuse_leeway, type: :integer, default: 0
     field :token_lifetimes, type: :hash, default: -> { {} }
-    field :client_id, type: :string, default: nil
-    field :client_secret, type: :string, default: nil
+    # Never read by the gem. OAuth clients are StandardId::ClientApplication
+    # rows with ClientSecretCredential secrets.
+    field :client_id, type: :string, default: nil,
+      deprecated: "it is not read anywhere — OAuth clients are StandardId::ClientApplication records. Remove this line. Removal in v2.0."
+    field :client_secret, type: :string, default: nil,
+      deprecated: "it is not read anywhere — client secrets are StandardId::ClientSecretCredential records. Remove this line. Removal in v2.0."
     field :scope_claims, type: :hash, default: -> { {} }
     field :claim_resolvers, type: :hash, default: -> { {} }
     # List of audience values that tokens issued and accepted by this app may
@@ -548,6 +571,11 @@ StandardId::ConfigSchema.define do
     field :allowed_redirect_url_prefixes, type: :array, default: []
     field :available_scopes, type: :array, default: -> { [] }
     field :link_strategy, type: :symbol, default: :strict
+    # What to do at boot when an enabled social provider is missing required
+    # config (e.g. apple_client_id set without apple_private_key). :warn logs
+    # in every environment; :raise raises StandardId::ConfigurationError in
+    # production and logs elsewhere. See ProviderRegistry.validate_configuration!
+    field :provider_misconfiguration, type: :symbol, default: :warn
   end
 
   scope :web do
@@ -580,8 +608,10 @@ StandardId::ConfigSchema.define do
     # these values (see StandardId::RateLimitHandling.login_per_ip). New name
     # wins when explicitly set. Mirrors the max_attempts ->
     # max_attempts_per_challenge deprecation-alias precedent.
-    field :password_login_per_ip, type: :integer, default: 20        # per 15 minutes; deprecated alias of login_per_ip
-    field :password_login_per_email, type: :integer, default: 5      # per 15 minutes; deprecated alias of login_per_email
+    field :password_login_per_ip, type: :integer, default: 20, # per 15 minutes; deprecated alias of login_per_ip
+      deprecated: "use rate_limits.login_per_ip (same meaning; it also governs passwordless OTP sends). Removal in v2.0."
+    field :password_login_per_email, type: :integer, default: 5, # per 15 minutes; deprecated alias of login_per_email
+      deprecated: "use rate_limits.login_per_email (same meaning; it also governs passwordless OTP sends). Removal in v2.0."
 
     # RAR-60: OTP verification
     field :otp_verify_per_ip, type: :integer, default: 20            # per 15 minutes

data/lib/standard_id/config_schema.rb

@@ -1,5 +1,6 @@
 require "active_support/ordered_options"
 require "concurrent/map"
+require "standard_id/deprecator"
 
 module StandardId
   # Lightweight configuration schema backed by ActiveSupport::OrderedOptions.
@@ -9,7 +10,10 @@ module StandardId
   # to the owning scope (so host apps can read base-scope fields like
   # `config.account_class_name` without the `base.` prefix).
   class ConfigSchema
-    Field = Struct.new(:name, :type, :default) do
+    # +deprecation+ is a message (String) for a field kept only so existing
+    # host initializers still boot. Assigning a non-nil value warns through
+    # StandardId.deprecator; reads and schema defaults never warn.
+    Field = Struct.new(:name, :type, :default, :deprecation) do
       def default_value
         return default.call if default.respond_to?(:call)
         return default.dup if default.is_a?(Array) || default.is_a?(Hash)
@@ -35,9 +39,9 @@ module StandardId
       self
     end
 
-    def add_field(scope:, name:, type: :string, default: nil)
+    def add_field(scope:, name:, type: :string, default: nil, deprecated: nil)
       fields = ensure_scope(scope)
-      fields.compute_if_absent(name.to_sym) { Field.new(name.to_sym, type, default) }
+      fields.compute_if_absent(name.to_sym) { Field.new(name.to_sym, type, default, deprecated) }
     end
 
     # Register a scope without adding a field. Allows `define { scope :foo }` so
@@ -100,8 +104,8 @@ module StandardId
         DSL.new(@schema, name.to_sym).instance_eval(&block) if block
       end
 
-      def field(name, type: :string, default: nil, **)
-        @schema.add_field(scope: @scope_name, name: name, type: type, default: default)
+      def field(name, type: :string, default: nil, deprecated: nil, **)
+        @schema.add_field(scope: @scope_name, name: name, type: type, default: default, deprecated: deprecated)
       end
     end
 
@@ -122,6 +126,7 @@ module StandardId
 
       def []=(key, value)
         validate!(key)
+        warn_if_deprecated(key, value)
         super(key.to_sym, value)
       end
 
@@ -154,6 +159,24 @@ module StandardId
           "Unknown field '#{key}' for scope '#{@scope_name}'. Valid fields: #{@schema.scopes[@scope_name]&.keys}"
       end
 
+      def warn_if_deprecated(key, value)
+        return if value.nil?
+
+        message = @schema.field_for(@scope_name, key)&.deprecation
+        return if message.nil?
+
+        # Point the warning at the host's assignment, not at this file.
+        # (OrderedOptions' method_missing forwards `c.foo = x` to #[]=.)
+        callstack = caller_locations(1).reject do |location|
+          location.path == __FILE__ || location.path.end_with?("active_support/ordered_options.rb")
+        end
+        StandardId.deprecator.warn("StandardId.config.#{config_path(key)} is deprecated: #{message}", callstack)
+      end
+
+      def config_path(key)
+        @scope_name == :base ? key.to_s : "#{@scope_name}.#{key}"
+      end
+
       def cast_read(key, value)
         field = @schema.field_for(@scope_name, key)
         return value unless field

data/lib/standard_id/deprecator.rb

@@ -0,0 +1,17 @@
+require "active_support/deprecation"
+
+module StandardId
+  # The gem's single ActiveSupport::Deprecation instance.
+  #
+  # The engine registers it in `Rails.application.deprecators[:standard_id]`,
+  # so the host's `config.active_support.deprecation` behaviour (:raise in
+  # test, :log / :notify in production, ...) and
+  # `Rails.application.deprecators.silence` apply to StandardId warnings exactly
+  # as they do to Rails' own. An unregistered deprecator only ever printed to
+  # stderr, whatever the host configured.
+  #
+  # @return [ActiveSupport::Deprecation]
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("2.0", "StandardId")
+  end
+end

data/lib/standard_id/engine.rb

@@ -37,6 +37,26 @@ module StandardId
       StandardId::ProviderRegistry.declare_config_schemas!
     end
 
+    # Route StandardId deprecation warnings through the host's deprecation
+    # behaviour (`config.active_support.deprecation`, `report_deprecations`,
+    # `Rails.application.deprecators.silence`).
+    initializer "standard_id.deprecator" do |app|
+      app.deprecators[:standard_id] = StandardId.deprecator if app.respond_to?(:deprecators)
+    end
+
+    # Check every enabled social provider is fully configured, once all of
+    # them have registered.
+    #
+    # Provider plugins register from `config.after_initialize` hooks added
+    # when their gem is required — before any initializer runs. A hook added
+    # from inside an initializer is appended after all of those, so it sees
+    # the complete registry.
+    initializer "standard_id.validate_social_providers" do |app|
+      app.config.after_initialize do
+        StandardId::ProviderRegistry.validate_configuration!
+      end
+    end
+
     initializer "standard_id.filter_parameters" do |app|
       app.config.filter_parameters += %i[
         code_verifier
@@ -79,6 +99,7 @@ module StandardId
       StandardId::Config::ScopeClaimsValidator.validate!
 
       StandardId::Engine.verify_host_cookie_encryption!(app)
+      StandardId::MigrationCheck.verify_at_boot!
       StandardId::Engine.warn_if_allowed_audiences_empty_in_production!
     end
 

data/lib/standard_id/instrumentation.rb

@@ -0,0 +1,49 @@
+require "active_support/notifications"
+
+module StandardId
+  # ActiveSupport::Notifications hooks around the expensive, opaque steps of
+  # the OAuth token endpoint, so hosts can attach tracing spans (Sentry,
+  # OpenTelemetry, Datadog) or timing metrics without prepending onto private
+  # gem methods.
+  #
+  # Names follow the Rails `<event>.<library>` convention (like
+  # `process_action.action_controller`), deliberately distinct from the
+  # `standard_id.<domain>.<event>` names StandardId::Events publishes: these
+  # are timing hooks, not audit events, and must not reach audit subscribers
+  # listening on `standard_id.*`.
+  #
+  # Every event is a block instrument, so subscribers get start/finish (and
+  # `:exception` / `:exception_object` in the payload when the step raised).
+  # Events nest: AUDIENCE_PROFILE_RESOLVE fires inside AUDIENCE_PROFILE_BINDING.
+  #
+  # Subscribe to all of them with:
+  #
+  #   ActiveSupport::Notifications.subscribe(StandardId::Instrumentation::PATTERN) { |event| ... }
+  module Instrumentation
+    # TokenGrantFlow#authenticate! — client authentication plus grant
+    # validation (for refresh_token: JWT decode + token row lookup + reuse
+    # detection). Payload: :flow (class name), :grant_type.
+    AUTHENTICATE = "authenticate.standard_id".freeze
+
+    # TokenGrantFlow#enforce_audience_profile_binding! — the account load and
+    # profile resolution for audience→profile binding. Fires on every token
+    # grant, including when no binding is configured (then it is a no-op).
+    # Payload: :flow, :grant_type, :audience (Array<String>).
+    AUDIENCE_PROFILE_BINDING = "audience_profile_binding.standard_id".freeze
+
+    # Oauth::AudienceProfileResolver.resolve! — just the resolver call (the
+    # host's `oauth.audience_profile_resolver` or the built-in strict lookup).
+    # Payload: :audience (String).
+    AUDIENCE_PROFILE_RESOLVE = "audience_profile_resolve.standard_id".freeze
+
+    EVENTS = [AUTHENTICATE, AUDIENCE_PROFILE_BINDING, AUDIENCE_PROFILE_RESOLVE].freeze
+
+    # Matches every instrumentation event above and nothing StandardId::Events
+    # publishes.
+    PATTERN = /\.standard_id\z/
+
+    def self.instrument(name, payload = {}, &)
+      ActiveSupport::Notifications.instrument(name, payload, &)
+    end
+  end
+end

data/lib/standard_id/migration_check.rb

@@ -0,0 +1,183 @@
+module StandardId
+  # Detects StandardId migrations a host never installed (or installed but
+  # never ran).
+  #
+  # WHY
+  #
+  # `bin/rails standard_id:install:migrations` copies the engine's migrations
+  # into the host with NEW timestamps. Rails' pending-migration check only
+  # sees files that are in the host's db/migrate, so a gem migration that was
+  # never copied is invisible to it — fundbright-web, luminality-web and
+  # nutripod-web each ran for months without 20260416180511's indexes, and
+  # two still lack 20260414200000. This compares by migration NAME (the part
+  # after the timestamp, with or without the `.standard_id` suffix Rails adds),
+  # which survives the re-timestamping.
+  #
+  # COST
+  #
+  # A Dir.glob over the host's migration paths; the database is only consulted
+  # (one `schema_migrations` read) when `check_database: true`, which the boot
+  # check never passes.
+  module MigrationCheck
+    GEM_MIGRATIONS_PATH = File.expand_path("../../db/migrate", __dir__)
+    FILENAME = /\A(\d+)_(\w+?)(?:\.[a-z_]+)?\.rb\z/
+
+    # A gem migration whose job is fully done by a LATER gem migration, so a
+    # host that installed the later one may skip it. name => superseding name.
+    #
+    # 20260414200000 adds a plain, non-concurrent 4-column index on
+    # standard_id_code_challenges; 20260416180511 adds the partial
+    # `index_code_challenges_on_active_target_created_at` (same columns,
+    # WHERE used_at IS NULL, built CONCURRENTLY) that serves the same lookups.
+    # Hosts on busy tables (fundbright-web, luminality-web) skipped the former
+    # on purpose rather than take the write lock.
+    SUPERSEDED_BY = {
+      "add_target_created_at_index_to_code_challenges" =>
+        "add_partial_indexes_for_active_session_and_challenge_lookups"
+    }.freeze
+
+    # Gem migrations hosts are EXPECTED to hold back for a while — reported as
+    # a pending upgrade step (severity :info), never as an error, so they do
+    # not warn at boot, fail boot in :raise mode, or degrade the health check.
+    #
+    # 20260915000000 drops a column 0.41.1 ignores; per the 0.41.1 upgrade
+    # notes it must only run once 0.41.1+ is deployed everywhere.
+    DEFERRED_UPGRADE_STEPS = {
+      "remove_refresh_token_lifetime_from_standard_id_client_applications" =>
+        "run once StandardId >= 0.41.1 is deployed to every process (it drops a column 0.41.1 ignores)"
+    }.freeze
+
+    # state:    :not_installed — no host migration file with this name
+    #           :not_run       — the host file exists but its version is not in schema_migrations
+    # severity: :error — a migration the host should have
+    #           :info  — a DEFERRED_UPGRADE_STEPS entry: pending, but intentionally
+    Missing = Data.define(:name, :version, :state, :severity) do
+      def initialize(name:, version:, state:, severity: :error) = super
+
+      def info? = severity == :info
+
+      def to_s
+        label = state.to_s.tr("_", " ")
+        info? ? "#{version}_#{name} (#{label}; pending upgrade step: #{DEFERRED_UPGRADE_STEPS[name]})" : "#{version}_#{name} (#{label})"
+      end
+    end
+
+    MODES = %i[warn raise ignore].freeze
+
+    module_function
+
+    # @return [Array<Array(String, String)>] [[original_version, name], ...] for every gem migration
+    def gem_migrations
+      @gem_migrations ||= parse_dir(GEM_MIGRATIONS_PATH).sort.freeze
+    end
+
+    # @param paths [Array<String>] host migration directories
+    # @param check_database [Boolean] also report installed-but-unrun migrations
+    # @param ignore [Array<String>] migration names (or original versions) to skip
+    # @return [Array<Missing>]
+    def pending(paths: host_migration_paths, check_database: false, ignore: StandardId.config.ignored_migrations)
+      ignore = Array(ignore).map(&:to_s)
+      host = host_versions_by_name(paths)
+      applied = check_database ? applied_versions : nil
+
+      present = ->(migration_name) { present_in_host?(host[migration_name], applied) }
+
+      gem_migrations.filter_map do |version, name|
+        next if ignore.include?(name) || ignore.include?(version)
+
+        host_versions = host[name]
+        state = if host_versions.blank?
+                  :not_installed
+        elsif applied && (host_versions & applied).empty?
+                  :not_run
+        end
+        next if state.nil?
+        next if (successor = SUPERSEDED_BY[name]) && present.call(successor)
+
+        severity = DEFERRED_UPGRADE_STEPS.key?(name) ? :info : :error
+        Missing.new(name: name, version: version, state: state, severity: severity)
+      end
+    end
+
+    # Installed (and, when +applied+ is given, run).
+    def present_in_host?(host_versions, applied)
+      return false if host_versions.blank?
+
+      applied.nil? || (host_versions & applied).any?
+    end
+
+    # The mode in effect: config.missing_migrations, else :warn in
+    # development/test and :ignore everywhere else (never raise in production
+    # by default).
+    def mode
+      configured = StandardId.config.missing_migrations
+      return configured.to_sym if configured.present?
+
+      Rails.env.local? ? :warn : :ignore
+    end
+
+    # Called from the engine's after_initialize. File-system only — boot must
+    # not need a database (assets:precompile, db:create).
+    #
+    # @raise [StandardId::ConfigurationError] in :raise mode when migrations are missing
+    def verify_at_boot!
+      current = mode
+      unless MODES.include?(current)
+        raise StandardId::ConfigurationError,
+          "StandardId.config.missing_migrations must be one of #{MODES.inspect} (got #{current.inspect})"
+      end
+      return if current == :ignore
+
+      all_missing = pending
+      deferred, missing = all_missing.partition(&:info?)
+      Rails.logger.info(deferred_message(deferred)) if deferred.any?
+      return if missing.empty?
+
+      message = boot_message(missing)
+      raise StandardId::ConfigurationError, message if current == :raise
+
+      Rails.logger.warn(message)
+      warn(message) if Rails.env.local?
+    end
+
+    def boot_message(missing)
+      <<~MESSAGE.strip
+        [StandardId] #{missing.size} StandardId migration(s) are not installed in this app:
+          #{missing.map(&:to_s).join("\n  ")}
+        Run `bin/rails standard_id:install:migrations && bin/rails db:migrate`.
+        If one is deliberately skipped (e.g. superseded by a host migration), list its name in
+        `StandardId.config.ignored_migrations`. Set `config.missing_migrations = :raise` to fail
+        boot instead, or `:ignore` to silence this check.
+      MESSAGE
+    end
+
+    def deferred_message(deferred)
+      "[StandardId] Pending upgrade step(s), held back intentionally: #{deferred.map(&:to_s).join('; ')}"
+    end
+
+    def host_migration_paths
+      paths = Rails.application.paths["db/migrate"].existent
+      paths += Array(ActiveRecord::Migrator.migrations_paths).map { |p| File.expand_path(p, Rails.root) }
+      paths.uniq.select { |p| File.directory?(p) }
+    end
+
+    def host_versions_by_name(paths)
+      Array(paths).flat_map { |dir| parse_dir(dir) }.each_with_object({}) do |(version, name), acc|
+        (acc[name] ||= []) << version
+      end
+    end
+
+    def parse_dir(dir)
+      Dir.children(dir).filter_map do |file|
+        match = FILENAME.match(file)
+        [match[1], match[2]] if match
+      end
+    rescue Errno::ENOENT
+      []
+    end
+
+    def applied_versions
+      ActiveRecord::Base.connection_pool.schema_migration.versions
+    end
+  end
+end

data/lib/standard_id/migration_helpers.rb

@@ -0,0 +1,65 @@
+require "active_support/concern"
+
+module StandardId
+  # `primary_key_type` / `foreign_key_type` for StandardId's own migrations:
+  # the host's generator `primary_key_type` (e.g. :uuid), else :bigint.
+  #
+  # These used to be monkey-patched onto ActiveRecord::Migration itself, so
+  # every migration in every host app gained three methods it never asked for.
+  # They are now scoped to StandardId migrations:
+  #
+  # * the gem's migrations `include StandardId::MigrationHelpers` explicitly
+  #   (so newly installed copies carry the include with them), and
+  # * copies installed BEFORE that line existed — which call the helpers with
+  #   no include — are recognised by file name (a StandardId migration name,
+  #   with or without the `.standard_id` suffix) when their class is defined,
+  #   and get the module then. No other migration is touched.
+  module MigrationHelpers
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def primary_and_foreign_key_types
+        config = Rails.configuration.generators
+        config.options[config.orm][:primary_key_type] || :bigint
+      end
+
+      def primary_key_type = primary_and_foreign_key_types
+      def foreign_key_type = primary_and_foreign_key_types
+    end
+
+    def primary_and_foreign_key_types = self.class.primary_and_foreign_key_types
+    def primary_key_type = self.class.primary_key_type
+    def foreign_key_type = self.class.foreign_key_type
+
+    # Is +path+ a (possibly host-copied) StandardId migration file?
+    def self.standard_id_migration_file?(path)
+      return false if path.nil?
+
+      match = StandardId::MigrationCheck::FILENAME.match(File.basename(path))
+      return false unless match
+
+      gem_migration_names.include?(match[2])
+    end
+
+    def self.gem_migration_names
+      @gem_migration_names ||= StandardId::MigrationCheck.gem_migrations.to_set(&:last).freeze
+    end
+
+    # Prepended onto ActiveRecord::Migration's singleton class. `inherited`
+    # fires while the migration's `class ... < ActiveRecord::Migration[x]`
+    # line runs, so the caller location is the migration file itself.
+    module LegacyCopySupport
+      def inherited(subclass)
+        super
+        path = caller_locations(1, 1).first&.path
+        return unless StandardId::MigrationHelpers.standard_id_migration_file?(path)
+
+        subclass.include(StandardId::MigrationHelpers)
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Migration.singleton_class.prepend(StandardId::MigrationHelpers::LegacyCopySupport)
+end

data/lib/standard_id/oauth/audience_profile_resolver.rb

@@ -78,6 +78,14 @@ module StandardId
         # @raise [StandardId::NoBoundProfileError]
         # @raise [StandardId::AmbiguousProfileError]
         def resolve!(account:, audience:)
+          StandardId::Instrumentation.instrument(
+            StandardId::Instrumentation::AUDIENCE_PROFILE_RESOLVE, audience: audience
+          ) { resolve_bound_profile!(account, audience) }
+        end
+
+        private
+
+        def resolve_bound_profile!(account, audience)
           types = profile_types_for(audience)
           raise ArgumentError, "audience #{audience.inspect} has no profile binding" if types.empty?
 
@@ -101,8 +109,6 @@ module StandardId
           strict_default_lookup(account, audience, types)
         end
 
-        private
-
         def default_lookup(account, types)
           return nil unless account.respond_to?(:profiles)