standard_id 0.43.2 → 0.45.0

data/app/models/standard_id/social_identity.rb

@@ -0,0 +1,30 @@
+module StandardId
+  # A social provider's stable subject id (`sub`) linked to an account.
+  #
+  # Written by StandardId::SocialAuthentication when a social login creates an
+  # account, or links to an existing email identifier on a provider-verified
+  # email. Later logins with the same (provider, subject) resolve to the same
+  # account, whatever email the provider then reports.
+  #
+  # `identifier` is the email identifier the link was made through. A different
+  # subject from the same provider for that identifier is refused.
+  class SocialIdentity < ApplicationRecord
+    self.table_name = "standard_id_social_identities"
+
+    belongs_to :account, class_name: StandardId.config.account_class_name
+    belongs_to :identifier, class_name: "StandardId::Identifier"
+
+    validates :provider, presence: true
+    validates :subject, presence: true, uniqueness: { scope: :provider }
+    validates :identifier_id, uniqueness: { scope: :provider }
+
+    # Hosts that upgraded the gem but have not run
+    # 20261002000000_create_standard_id_social_identities yet. Cached by the
+    # schema cache, so this is one lookup per process.
+    def self.available?
+      table_exists?
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+  end
+end

data/db/migrate/20261002000000_create_standard_id_social_identities.rb

@@ -0,0 +1,44 @@
+# Stores the social provider's stable subject id (`sub`) per account, so a
+# returning social login is matched on (provider, sub) instead of on the email
+# address alone.
+#
+# Before this table, `find_or_create_account_from_social` linked a provider
+# login to whichever account held an email identifier with the same address,
+# without looking at `sub` or `email_verified`. Under `link_strategy:
+# :trust_provider`, or for an identifier with a NULL provider, any token that
+# claimed an address could sign in as that address's account.
+#
+# New, empty table: nothing existing is rewritten, and no row is backfilled.
+# Each existing social user gets a row on their next successful login (when the
+# provider reports the email as verified). Until the migration has run, the
+# gem skips subject matching and logs a warning, but still refuses to link an
+# existing account to an unverified provider email.
+#
+# Both foreign keys cascade so the host's account- and identifier-deletion
+# paths keep working unchanged: deleting the email identifier a link was made
+# through removes the link, and the next login has to re-link on a verified
+# email.
+class CreateStandardIdSocialIdentities < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
+  def change
+    create_table :standard_id_social_identities, id: primary_key_type do |t|
+      t.references :account, type: foreign_key_type, null: false, index: true,
+        foreign_key: { to_table: StandardId.account_class.table_name, on_delete: :cascade }
+      t.references :identifier, type: foreign_key_type, null: false, index: false,
+        foreign_key: { to_table: :standard_id_identifiers, on_delete: :cascade }
+
+      t.string :provider, null: false
+      t.string :subject, null: false
+
+      t.timestamps
+    end
+
+    # One account per provider subject.
+    add_index :standard_id_social_identities, [:provider, :subject], unique: true
+    # One subject per provider for a given email identifier: a second subject
+    # claiming the same address is refused as a possible takeover.
+    add_index :standard_id_social_identities, [:identifier_id, :provider], unique: true,
+      name: "index_standard_id_social_identities_on_identifier_and_provider"
+  end
+end

data/db/migrate/20261004000000_add_auth_method_to_standard_id_refresh_tokens.rb

@@ -0,0 +1,17 @@
+# Records how the authentication behind a refresh token was established
+# (`auth_method`: "password", "passwordless", "social", ...; `auth_provider`:
+# the social provider's name, or NULL), so `config.login_method_policy` can be
+# consulted again on the `refresh_token` grant with the ORIGINAL method. Each
+# rotated token copies the values from its predecessor. See
+# StandardId::AuthLineage.
+#
+# Two nullable columns, no default, no index, no backfill: metadata-only on
+# PostgreSQL, so safe on a large table and under StrongMigrations. Rows minted
+# before this ran keep NULL and reach the policy as `:unspecified`. Until the
+# migration has run the gem simply does not write the columns.
+class AddAuthMethodToStandardIdRefreshTokens < ActiveRecord::Migration[8.0]
+  def change
+    add_column :standard_id_refresh_tokens, :auth_method, :string
+    add_column :standard_id_refresh_tokens, :auth_provider, :string
+  end
+end

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -403,6 +403,19 @@ StandardId.configure do |c|
   #   context[:first_sign_in] ? "/onboarding" : nil
   # }
 
+  # Decides which authentication methods may sign an account in. Consulted in
+  # EVERY web and API flow that establishes a new authentication, after the
+  # credential is proven and before any session or token is created.
+  # Receives any subset of: account:, auth_method: (:password, :passwordless,
+  # :social, :remember_me, :unspecified), provider:, request:, flow:
+  # Return truthy to allow, false/nil to refuse, or raise
+  # StandardId::LoginMethodDenied.new("message") to refuse with a message.
+  # Default: nil (every method allowed)
+  # c.login_method_policy = ->(account:, auth_method:, provider:) {
+  #   next true unless account.staff?
+  #   auth_method == :social && provider == "void_which_binds"
+  # }
+
   # Called after a new account is created via any mechanism.
   # Receives: (account, request, context)
   #   context = { mechanism:, provider: }
@@ -478,10 +491,14 @@ StandardId.configure do |c|
   # Default: []
   # c.social.available_scopes = %w[profile email offline_access]
 
-  # Account linking strategy:
-  #   :strict          — refuse to link a social identity unless the email
-  #                      already matches a verified identifier (default)
-  #   :trust_provider  — accept the social provider's claim and create or link
+  # Account linking strategy, for a social login whose (provider, sub) is not
+  # linked yet but whose email belongs to an existing account:
+  #   :strict          — link only if that email identifier came from the same
+  #                      provider, predates provider tracking, or the account
+  #                      already has an identifier from this provider (default)
+  #   :trust_provider  — link to the account that holds the email
+  # Under both, the provider must report the email as verified, and an email
+  # already linked to a different sub from the same provider is refused.
   # Default: :strict
   # c.social.link_strategy = :trust_provider
 

data/lib/standard_id/account_cleanup.rb

@@ -0,0 +1,62 @@
+module StandardId
+  # Removes an account that was created during the current request and then
+  # refused sign-in (by a lifecycle hook or the login-method policy), so the
+  # refusal does not leave an orphaned account behind.
+  #
+  # Every association read goes through `.strict_loading(false)`: the account
+  # was built in this request, so none of its associations are loaded, and a
+  # host running `strict_loading_by_default = true` (most consumers) would
+  # otherwise raise StrictLoadingViolationError on `account.sessions` — turning
+  # a clean rejection of a new signup into a 500 and leaving the orphaned
+  # account behind. Relation-level `strict_loading(false)` also covers the
+  # records it loads, so `identifier.credentials` below is safe too.
+  #
+  # The account is visible to other requests from the moment it is created,
+  # so a concurrent sign-in can find it (by email) and sign in to it before
+  # this request is refused. The removal therefore takes a row lock on the
+  # account and skips it when the account has been adopted — it has an
+  # active session or an unrevoked refresh token, which this request's own
+  # rejection paths revoke before calling here. The social callbacks take
+  # the same lock before they write a link (SocialAuthentication#commit_social_link!)
+  # and fail when the account is gone, so either the other login completes
+  # first and the account stays, or the removal goes first and the other
+  # login fails and can be retried (creating a fresh account). Nothing waits
+  # on a doomed account, and nothing signs in to one.
+  module AccountCleanup
+    module_function
+
+    # @return [Boolean] true when the account was removed, false when it was
+    #   already gone or another login has adopted it.
+    def destroy_newly_created!(account)
+      return false unless account&.persisted?
+
+      ActiveRecord::Base.transaction do
+        next false if account.class.lock.where(id: account.id).pick(:id).nil?
+
+        if adopted?(account)
+          Rails.logger&.info("[StandardId] Kept refused new account #{account.id}: a concurrent sign-in is using it")
+          next false
+        end
+
+        # Tokens first: refresh_tokens.account_id has no ON DELETE action, and
+        # a refused API grant may already have issued one for this account.
+        StandardId::RefreshToken.where(account_id: account.id).delete_all
+        account.sessions.strict_loading(false).destroy_all
+        identifiers = account.identifiers.strict_loading(false).to_a
+        identifiers.each { |i| i.credentials.strict_loading(false).destroy_all }
+        # Deliberately destroy! (unlike the destroy_all calls above): a failed identifier destroy raises and rolls back the whole cleanup, failing loud instead of leaving a half-cleaned orphan.
+        identifiers.each(&:destroy!)
+        account.destroy
+        true
+      end
+    end
+
+    # Another request signed in to the account. The refusing request has
+    # already revoked whatever session / refresh token it issued itself.
+    def adopted?(account)
+      return true if account.sessions.strict_loading(false).active.exists?
+
+      StandardId::RefreshToken.active.where(account_id: account.id).exists?
+    end
+  end
+end

data/lib/standard_id/api/token_manager.rb

@@ -7,7 +7,18 @@ module StandardId
         @request = request
       end
 
-      def create_device_session(account, device_id: nil, device_agent: nil)
+      # Host-facing primitives: the engine itself never calls these two, so
+      # whoever does has authenticated `account` on its own. They still go
+      # through `config.login_method_policy` (flows :api_device_session /
+      # :api_service_session) so no session-creating entry point bypasses it;
+      # pass `auth_method:` (and `provider:`) so a policy can tell the method
+      # apart — without it the policy sees `:unspecified`.
+      def create_device_session(account, device_id: nil, device_agent: nil, auth_method: nil, provider: nil)
+        StandardId::LoginMethodPolicy.enforce!(
+          account: account, auth_method: auth_method, provider: provider,
+          request: @request, flow: :api_device_session
+        )
+
         session_class = StandardId::SessionTypeResolver.resolve!(
           request: @request,
           account: account,
@@ -22,7 +33,12 @@ module StandardId
         )
       end
 
-      def create_service_session(account, service_name:, service_version:, owner:, metadata: {})
+      def create_service_session(account, service_name:, service_version:, owner:, metadata: {}, auth_method: nil, provider: nil)
+        StandardId::LoginMethodPolicy.enforce!(
+          account: account, auth_method: auth_method, provider: provider,
+          request: @request, flow: :api_service_session
+        )
+
         session_class = StandardId::SessionTypeResolver.resolve!(
           request: @request,
           account: account,

data/lib/standard_id/auth_lineage.rb

@@ -0,0 +1,75 @@
+module StandardId
+  # Carries the method an authentication was established with (password,
+  # passwordless, social + provider, ...) along everything derived from it, so
+  # `config.login_method_policy` can be consulted again on the `refresh_token`
+  # grant with the ORIGINAL method:
+  #
+  #   web sign-in ──▶ BrowserSession#metadata ──▶ AuthorizationCode#metadata
+  #   (/authorize, consent)                         │
+  #   password / passwordless_otp / social grants ──┴─▶ RefreshToken#auth_method,
+  #                                                     #auth_provider
+  #   refresh_token grant: copied from the presented token to its successor.
+  #
+  # Sessions and authorization codes already have a JSON `metadata` column, so
+  # the lineage lives there under "auth_method" / "auth_provider". Refresh tokens
+  # get two columns (migration 20261004000000). Anything minted before 0.45, or
+  # before that migration ran, has no recorded method and reaches the policy as
+  # `:unspecified` — a restrictive policy refuses it (fails closed).
+  module AuthLineage
+    METHOD_KEY = "auth_method".freeze
+    PROVIDER_KEY = "auth_provider".freeze
+
+    module_function
+
+    # @return [Hash] `{ auth_method: String|nil, auth_provider: String|nil }`
+    def build(auth_method, provider = nil)
+      { auth_method: auth_method&.to_s.presence, auth_provider: provider&.to_s.presence }
+    end
+
+    def empty
+      build(nil, nil)
+    end
+
+    # Lineage stored on a session or authorization code `metadata` hash.
+    def from_metadata(metadata)
+      metadata = metadata.is_a?(Hash) ? metadata.stringify_keys : {}
+      build(metadata[METHOD_KEY], metadata[PROVIDER_KEY])
+    end
+
+    def from_session(session)
+      return empty unless session.respond_to?(:metadata)
+
+      from_metadata(session.metadata)
+    end
+
+    def from_refresh_token(record)
+      return empty unless record && refresh_token_columns?
+
+      build(record.auth_method, record.auth_provider)
+    end
+
+    # Merge into a `metadata` hash. Nothing is added for an empty lineage.
+    def to_metadata(lineage)
+      { METHOD_KEY => lineage[:auth_method], PROVIDER_KEY => lineage[:auth_provider] }.compact
+    end
+
+    # Attributes for a new RefreshToken row; empty until the host has run the
+    # migration, so a rolling deploy never writes to a column that is not there.
+    def refresh_token_attributes(lineage)
+      return {} unless refresh_token_columns?
+
+      { auth_method: lineage[:auth_method], auth_provider: lineage[:auth_provider] }
+    end
+
+    # The policy's view: missing method → :unspecified.
+    def policy_arguments(lineage)
+      { auth_method: (lineage[:auth_method].presence || :unspecified).to_sym, provider: lineage[:auth_provider] }
+    end
+
+    def refresh_token_columns?
+      StandardId::RefreshToken.column_names.include?("auth_method")
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+  end
+end

data/lib/standard_id/config/callable_validator.rb

@@ -36,6 +36,11 @@ module StandardId
           kind: :keyword,
           keywords: %i[identifier params request]
         },
+        "login_method_policy" => {
+          signature: "(account:, auth_method:, provider:, request:, flow:)",
+          kind: :keyword,
+          keywords: %i[account auth_method provider request flow]
+        },
         "oauth.custom_claims" => {
           signature: "(account:, client:, request:, audience:)",
           kind: :keyword,

data/lib/standard_id/config/schema.rb

@@ -118,6 +118,20 @@ StandardId::ConfigSchema.define do
     #   Return: nil (default redirect) or a path string (override redirect)
     #   Raise StandardId::AuthenticationDenied.new("message") to reject sign-in.
     field :after_sign_in, type: :any, default: nil
+
+    # login_method_policy: decides whether an account may authenticate with a
+    # given method. Consulted in EVERY flow that establishes a new
+    # authentication (web and API), after the credential is proven and BEFORE
+    # any session or token is created. See StandardId::LoginMethodPolicy for
+    # the list of flows.
+    #   Receives (keywords, take any subset):
+    #     account:, auth_method: (:password / :passwordless / :social /
+    #     :remember_me / :unspecified), provider: ("google", ... or nil),
+    #     request:, flow: (e.g. :web_password, :oauth_social_callback)
+    #   Return: truthy to allow; false/nil to refuse with a generic message.
+    #   Raise StandardId::LoginMethodDenied.new("message") to refuse with your own.
+    # nil (the default) allows every method, i.e. no behaviour change.
+    field :login_method_policy, type: :any, default: nil
   end
 
   scope :events do
@@ -565,6 +579,10 @@ StandardId::ConfigSchema.define do
     field :social_account_attributes, type: :any, default: nil
     field :allowed_redirect_url_prefixes, type: :array, default: []
     field :available_scopes, type: :array, default: -> { [] }
+    # How a social login whose (provider, sub) is not linked yet may link to
+    # an existing account that holds its email: :strict or :trust_provider.
+    # Either way the provider must report the email as verified. See
+    # StandardId::SocialAuthentication#find_or_create_account_from_social.
     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

data/lib/standard_id/errors.rb

@@ -150,16 +150,64 @@ module StandardId
   # Lifecycle hook errors
   class AuthenticationDenied < StandardError; end
 
+  # Raised when `config.login_method_policy` refuses an authentication method
+  # for an account (e.g. "staff must sign in with the org IdP"). See
+  # StandardId::LoginMethodPolicy.
+  #
+  # A subclass of AuthenticationDenied so every WebEngine flow that already
+  # rescues AuthenticationDenied (redirect to /login with the message as the
+  # flash alert, new-account cleanup) handles it unchanged. The API engine
+  # renders it as `403 access_denied` (see Api::BaseController), the same
+  # shape as SocialLinkError.
+  #
+  # The policy is only ever consulted AFTER the credential has been proven
+  # (password checked, OTP verified, provider token verified), so the message
+  # reaches only someone who already controls the credential. Policies may
+  # raise this themselves to supply their own message:
+  #
+  #   raise StandardId::LoginMethodDenied, "Staff must sign in with Void Which Binds"
+  #
+  # `auth_method`, `provider` and `flow` are filled in by the engine for
+  # logging and audit; do not surface them to end users.
+  class LoginMethodDenied < AuthenticationDenied
+    DEFAULT_MESSAGE = "This sign-in method is not available for your account".freeze
+
+    attr_reader :auth_method, :provider, :flow
+
+    def initialize(message = nil, auth_method: nil, provider: nil, flow: nil)
+      @auth_method = auth_method
+      @provider = provider
+      @flow = flow
+      super(message.presence || DEFAULT_MESSAGE)
+    end
+
+    def oauth_error_code = :access_denied
+    def http_status = :forbidden
+  end
+
   # Social login errors
   # NOTE: email and provider_name are exposed as reader attributes for host
   # apps to build custom error responses. If you report exceptions to an
   # error tracker (Sentry, etc.), be aware these attributes contain PII.
+  #
+  # `reason` says why the link was refused:
+  #   :link_required    — the email belongs to an account the strict
+  #                       link_strategy will not link this provider to
+  #   :email_unverified — the provider did not report the email as verified,
+  #                       so it cannot prove ownership of the existing account
+  #   :subject_mismatch — the account's email identifier is already linked to a
+  #                       different subject (`sub`) from this provider
+  # (SOCIAL_LINK_BLOCKED also uses :subject_conflict, for the race raised as
+  # SocialLinkConflictError rather than this error.)
   class SocialLinkError < OAuthError
-    attr_reader :email, :provider_name
+    REASONS = %i[link_required email_unverified subject_mismatch].freeze
+
+    attr_reader :email, :provider_name, :reason
 
-    def initialize(email:, provider_name:)
+    def initialize(email:, provider_name:, reason: :link_required)
       @email = email
       @provider_name = provider_name
+      @reason = reason
       super("This email is already associated with an account. Please sign in first to link this provider.")
     end
 
@@ -168,6 +216,24 @@ module StandardId
     def http_status = :forbidden
   end
 
+  # Raised while a social login writes its (provider, sub) link and loses a
+  # race to a concurrent login. The client sees a retryable `invalid_grant`;
+  # SOCIAL_LINK_BLOCKED is published with `reason` (not SOCIAL_AUTH_FAILED,
+  # which is for infrastructure failures):
+  #   :subject_conflict — the same (provider, sub) was committed for a
+  #     DIFFERENT account;
+  #   :subject_mismatch — this identifier was linked to this provider under a
+  #     DIFFERENT sub (the (identifier, provider) unique index won).
+  class SocialLinkConflictError < InvalidGrantError
+    attr_reader :identifier, :reason
+
+    def initialize(message = nil, identifier: nil, reason: :subject_conflict)
+      @identifier = identifier
+      @reason = reason
+      super(message)
+    end
+  end
+
   # Audience verification errors
   class InvalidAudienceError < StandardError
     attr_reader :required, :actual

data/lib/standard_id/events/definitions.rb

@@ -8,6 +8,9 @@ module StandardId
       PASSWORD_VALIDATION_FAILED = "authentication.password.failed"
       OTP_VALIDATED = "authentication.otp.validated"
       OTP_VALIDATION_FAILED = "authentication.otp.failed"
+      # config.login_method_policy refused the method for the account, after
+      # the credential was proven and before any session was created.
+      AUTHENTICATION_METHOD_DENIED = "authentication.method.denied"
 
       SESSION_CREATING = "session.creating"
       SESSION_CREATED = "session.created"
@@ -75,7 +78,8 @@ module StandardId
         PASSWORD_VALIDATED,
         PASSWORD_VALIDATION_FAILED,
         OTP_VALIDATED,
-        OTP_VALIDATION_FAILED
+        OTP_VALIDATION_FAILED,
+        AUTHENTICATION_METHOD_DENIED
       ].freeze
 
       SESSION_EVENTS = [
@@ -157,6 +161,7 @@ module StandardId
         AUTHENTICATION_FAILED,
         PASSWORD_VALIDATION_FAILED,
         OTP_VALIDATION_FAILED,
+        AUTHENTICATION_METHOD_DENIED,
         # Session
         SESSION_CREATED,
         SESSION_REVOKED,

data/lib/standard_id/events/subscribers/logging_subscriber.rb

@@ -12,6 +12,7 @@ module StandardId
           "authentication.password.failed" => :warn,
           "authentication.otp.validated" => :debug,
           "authentication.otp.failed" => :warn,
+          "authentication.method.denied" => :warn,
           "session.creating" => :debug,
           "session.created" => :info,
           "session.validating" => :debug,

data/lib/standard_id/login_method_policy.rb

@@ -0,0 +1,108 @@
+module StandardId
+  # Enforces `config.login_method_policy`: one decision point, consulted by
+  # every engine flow that establishes a NEW authentication, after the
+  # credential has been proven and before any session or token exists.
+  #
+  # ## Flows (the `flow:` the policy receives)
+  #
+  # | flow                            | auth_method    | where                                                    |
+  # |---------------------------------|----------------|----------------------------------------------------------|
+  # | :web_password                   | :password      | Web LoginController (WebAuthentication#sign_in_account)  |
+  # | :web_signup                     | :password      | Web SignupController                                     |
+  # | :web_passwordless               | :passwordless  | Web LoginVerifyController (email/SMS OTP)                |
+  # | :web_social                     | :social        | Web Auth::Callback::ProvidersController                  |
+  # | :web_remember_me                | :remember_me   | Web::SessionManager (remember-me cookie re-auth)         |
+  # | :web_session                    | caller's, else :unspecified | Web::SessionManager#sign_in_account called by host code |
+  # | :oauth_password_grant           | :password      | POST /oauth/token grant_type=password                    |
+  # | :oauth_passwordless_otp_grant   | :passwordless  | POST /oauth/token grant_type=passwordless_otp            |
+  # | :oauth_social_callback          | :social        | /oauth/callback/:provider (Oauth::SocialFlow)            |
+  # | :oauth_refresh_token            | the ORIGINAL sign-in's, else :unspecified | POST /oauth/token grant_type=refresh_token |
+  # | :api_device_session             | caller's, else :unspecified | Api::TokenManager#create_device_session (host code) |
+  # | :api_service_session            | caller's, else :unspecified | Api::TokenManager#create_service_session (host code) |
+  #
+  # `refresh_token` is re-checked with the method of the authentication it
+  # descends from (see StandardId::AuthLineage): a policy tightened after a
+  # client signed in takes effect at that client's next refresh, and a refused
+  # refresh revokes the token family (answered as `invalid_grant`). Tokens with
+  # no recorded method (minted before 0.45) are checked as `:unspecified`.
+  #
+  # Not gated: `authorization_code` and the implicit flow (minted within
+  # minutes from a browser session that passed the policy when it was created;
+  # the code records that session's method for the refresh tokens it yields)
+  # and `client_credentials` (no account). Live browser sessions that predate a
+  # policy change are not re-checked; revoke them if they must end.
+  #
+  # ## Contract
+  #
+  # The policy is any object responding to `call`. It receives keywords and
+  # may declare any subset of them (see Utils::CallableParameterFilter):
+  # `account:`, `auth_method:`, `provider:`, `request:`, `flow:`.
+  #
+  # - truthy → allowed;
+  # - `false` / `nil` → refused with LoginMethodDenied::DEFAULT_MESSAGE;
+  # - `raise StandardId::LoginMethodDenied, "message"` → refused with that
+  #   message.
+  #
+  # Any other exception propagates: a broken policy fails closed (the request
+  # errors) rather than open.
+  #
+  # Every refusal publishes AUTHENTICATION_METHOD_DENIED before raising.
+  module LoginMethodPolicy
+    AUTH_METHODS = %i[password passwordless social remember_me unspecified].freeze
+
+    FLOWS = %i[
+      web_password web_signup web_passwordless web_social web_remember_me web_session
+      oauth_password_grant oauth_passwordless_otp_grant oauth_social_callback oauth_refresh_token
+      api_device_session api_service_session
+    ].freeze
+
+    module_function
+
+    # Whether a policy is configured at all.
+    def configured?
+      !StandardId.config.login_method_policy.nil?
+    end
+
+    # @return [true] when allowed
+    # @raise [StandardId::LoginMethodDenied] when refused
+    # @raise [StandardId::ConfigurationError] when the policy is not callable
+    def enforce!(account:, auth_method:, flow:, provider: nil, request: nil)
+      policy = StandardId.config.login_method_policy
+      return true if policy.nil?
+
+      unless policy.respond_to?(:call)
+        raise StandardId::ConfigurationError,
+          "StandardId config: `login_method_policy` must respond to #call (got #{policy.class})"
+      end
+
+      auth_method = (auth_method || :unspecified).to_sym
+      provider = provider&.to_s
+      context = { account:, auth_method:, provider:, request:, flow: }
+
+      message = nil
+      allowed =
+        begin
+          policy.call(**StandardId::Utils::CallableParameterFilter.filter(policy, context))
+        rescue StandardId::LoginMethodDenied => e
+          message = e.message unless e.message == e.class.name
+          false
+        end
+      return true if allowed
+
+      denial = StandardId::LoginMethodDenied.new(message, auth_method:, provider:, flow:)
+      publish_denied(account:, auth_method:, provider:, flow:, message: denial.message)
+      raise denial
+    end
+
+    def publish_denied(account:, auth_method:, provider:, flow:, message:)
+      StandardId::Events.publish(
+        StandardId::Events::AUTHENTICATION_METHOD_DENIED,
+        account: account,
+        auth_method: auth_method.to_s,
+        provider: provider,
+        flow: flow.to_s,
+        error_message: message
+      )
+    end
+  end
+end

data/lib/standard_id/oauth/authorization_code_authorization_flow.rb

@@ -37,7 +37,8 @@ module StandardId
           traditional: -> do
             Subflows::TraditionalCodeGrant.new(
               **common_subflow_params(flow_params),
-              current_account: current_account
+              current_account: current_account,
+              auth_lineage: auth_lineage
             )
           end
         }

data/lib/standard_id/oauth/authorization_code_flow.rb

@@ -107,6 +107,12 @@ module StandardId
         true
       end
 
+      # The browser session the code was minted from recorded its sign-in
+      # method; carry it onto the refresh token.
+      def refresh_token_auth_lineage
+        StandardId::AuthLineage.from_metadata(@authorization_code&.metadata)
+      end
+
       def find_authorization_code(code)
         StandardId::AuthorizationCode.lookup(code)
       end

data/lib/standard_id/oauth/authorization_flow.rb

@@ -1,12 +1,16 @@
 module StandardId
   module Oauth
     class AuthorizationFlow < BaseRequestFlow
-      attr_reader :params, :request, :current_account
+      attr_reader :params, :request, :current_account, :auth_lineage
 
-      def initialize(params, request, current_account: nil)
+      # `auth_lineage` (StandardId::AuthLineage) is how the browser session
+      # behind `current_account` was established; an authorization code carries
+      # it on to the tokens it is exchanged for.
+      def initialize(params, request, current_account: nil, auth_lineage: nil)
         @params = params
         @request = request
         @current_account = current_account
+        @auth_lineage = auth_lineage
       end
 
       class << self