standard_id 0.44.0 → 0.46.0

data/app/controllers/standard_id/web/auth/callback/providers_controller.rb

@@ -25,10 +25,11 @@ module StandardId
             state_data = nil
 
             begin
-              extract_state_and_nonce => { state_data:, nonce: }
+              extract_state_and_nonce => { state_data:, nonce:, code_verifier: }
+              code_verifier = pkce_verifier_for_provider!(code_verifier)
               caller_redirect_uri = state_data&.dig("redirect_uri").presence
               redirect_uri = callback_url_for
-              provider_response = get_user_info_from_provider(redirect_uri:, nonce:)
+              provider_response = get_user_info_from_provider(redirect_uri:, nonce:, code_verifier:)
               social_info = provider_response[:user_info]
               provider_tokens = provider_response[:tokens]
               begin
@@ -40,7 +41,13 @@ module StandardId
               newly_created = account.previously_new_record?
 
               invoke_before_sign_in(account, { mechanism: "social", provider: provider.provider_name })
-              session_manager.sign_in_account(account, scope_name: state_data&.dig("scope"))
+              session_manager.sign_in_account(
+                account,
+                scope_name: state_data&.dig("scope"),
+                auth_method: :social,
+                provider: provider.provider_name,
+                flow: :web_social
+              )
 
               provider_name = provider.provider_name
               invoke_after_account_created(account, { mechanism: "social", provider: provider_name }) if newly_created
@@ -68,8 +75,14 @@ module StandardId
               destination = redirect_override || (safe_destination?(caller_redirect_uri) ? caller_redirect_uri : safe_post_signin_default)
               redirect_options = { notice: "Successfully signed in with #{provider_name.humanize}" }
               redirect_options[:allow_other_host] = true if allow_other_host_redirect?(destination)
-              redirect_to destination, redirect_options
+
+              # Accepted: only now write the (provider, sub) link, in the same
+              # transaction as the redirect, which can still raise (e.g. an
+              # after_sign_in URL on a host that is not allowed). If it does,
+              # the link is rolled back with it.
+              commit_social_link! { redirect_to destination, redirect_options }
             rescue StandardId::AuthenticationDenied => e
+              rollback_social_link!
               handle_authentication_denied(e, account: account, newly_created: newly_created)
             rescue StandardId::SocialLinkError => e
               # Policy/link error — SOCIAL_LINK_BLOCKED has already been emitted
@@ -77,8 +90,23 @@ module StandardId
               # (which is reserved for infrastructure-level failures).
               redirect_to StandardId::WebEngine.routes.url_helpers.login_path(redirect_uri: state_data&.dig("redirect_uri")), alert: "Authentication failed: #{e.message}"
             rescue StandardId::OAuthError => e
-              emit_social_auth_failed(e, account: account)
+              discard_rejected_social_sign_in!(account, newly_created:)
+              # A (provider, sub) conflict with a concurrent login is a link
+              # refusal (SOCIAL_LINK_BLOCKED, already published), not an
+              # infrastructure failure.
+              emit_social_auth_failed(e, account: account) unless e.is_a?(StandardId::SocialLinkConflictError)
               redirect_to StandardId::WebEngine.routes.url_helpers.login_path(redirect_uri: state_data&.dig("redirect_uri")), alert: "Authentication failed: #{e.message}"
+            rescue StandardError => e
+              # Unexpected failure after the link/account may have been
+              # written: undo them, then let the error surface as before —
+              # unless the matched account was removed under this login by a
+              # concurrent, refused request, which is retryable.
+              removed = social_account_removed_concurrently?(account, newly_created:)
+              discard_rejected_social_sign_in!(account, newly_created:)
+              raise unless removed
+
+              emit_social_auth_failed(e, account: account)
+              redirect_to StandardId::WebEngine.routes.url_helpers.login_path(redirect_uri: state_data&.dig("redirect_uri")), alert: "Authentication failed: #{SOCIAL_RETRY_MESSAGE}"
             end
           end
 
@@ -103,6 +131,27 @@ module StandardId
 
           private
 
+          # A rejection after find_or_create_account_from_social leaves no
+          # link, no new account and no session — including one that
+          # sign_in_account created before raising (a failing SESSION_CREATED
+          # subscriber), which is why this reads session_manager.created_session
+          # rather than relying on sign_in_account having returned.
+          # AuthenticationDenied has its own path (handle_authentication_denied);
+          # SocialLinkError is raised before anything is written.
+          def discard_rejected_social_sign_in!(account, newly_created:)
+            created = session_manager.created_session
+            if created
+              created.revoke!(reason: "social_sign_in_rejected") unless created.revoked?
+              session_manager.clear_session!
+            end
+            discard_social_attempt!(account, newly_created: newly_created, sessions: [created])
+          end
+
+          # Write the (provider, sub) link only once the login is accepted.
+          def defer_social_link?
+            true
+          end
+
           def callback_url_for
             "#{request.base_url}#{provider.callback_path}"
           end
@@ -120,10 +169,24 @@ module StandardId
 
             {
               state_data: oauth_state["params"],
-              nonce: oauth_state["nonce"]
+              nonce: oauth_state["nonce"],
+              code_verifier: oauth_state["code_verifier"].presence
             }
           end
 
+          # Core-managed PKCE (Providers::Base.supports_pkce?): the provider
+          # receives the verifier stored with this flow's state, and only
+          # then. A PKCE provider's flow must have been started with one (by
+          # /login for this provider), so a missing verifier — a state issued
+          # for another provider, or stored before the provider opted in — is
+          # refused rather than the code exchanged without it.
+          def pkce_verifier_for_provider!(code_verifier)
+            return nil unless provider.supports_pkce?
+            raise StandardId::InvalidRequestError, "Missing PKCE verifier for this sign-in" if code_verifier.nil?
+
+            code_verifier
+          end
+
           def handle_callback_error
             error_message = case params[:error]
             when "access_denied"

data/app/controllers/standard_id/web/consent_controller.rb

@@ -81,7 +81,11 @@ module StandardId
         )
 
         result = StandardId::Oauth::AuthorizationCodeAuthorizationFlow
-          .new(@consent_request, request, current_account: current_account)
+          .new(
+            @consent_request, request,
+            current_account: current_account,
+            auth_lineage: StandardId::AuthLineage.from_session(current_session)
+          )
           .execute
 
         redirect_out(result[:redirect_to], status: result[:status] || :found)

data/app/controllers/standard_id/web/login_controller.rb

@@ -133,10 +133,12 @@ module StandardId
 
         state = generate_oauth_token
         nonce = provider_supports_nonce?(provider) ? generate_oauth_token : nil
+        code_verifier = provider.supports_pkce? ? generate_oauth_token : nil
 
         store_oauth_request(
           state:,
           nonce:,
+          code_verifier:,
           params: extract_social_login_params
         )
 
@@ -146,6 +148,12 @@ module StandardId
         # Add nonce to OAuth params if provider supports it
         extra_params[:nonce] = nonce if nonce.present?
 
+        # Core-managed PKCE: only the S256 challenge leaves the server.
+        if code_verifier
+          extra_params[:code_challenge] = provider.pkce_s256_challenge(code_verifier)
+          extra_params[:code_challenge_method] = "S256"
+        end
+
         url = provider.authorization_url(
           state:,
           redirect_uri: callback_url,

data/app/controllers/standard_id/web/login_verify_controller.rb

@@ -52,7 +52,12 @@ module StandardId
 
         invoke_before_sign_in(account, { mechanism: "passwordless", provider: nil })
 
-        session_manager.sign_in_account(account, scope_name: request.path_parameters[:scope])
+        session_manager.sign_in_account(
+          account,
+          scope_name: request.path_parameters[:scope],
+          auth_method: :passwordless,
+          flow: :web_passwordless
+        )
         emit_authentication_succeeded(account)
 
         if newly_created

data/app/controllers/standard_id/web/signup_controller.rb

@@ -47,7 +47,12 @@ module StandardId
 
         if form.submit
           invoke_before_sign_in(form.account, { mechanism: "password", provider: nil })
-          session_manager.sign_in_account(form.account, scope_name: request.path_parameters[:scope])
+          session_manager.sign_in_account(
+            form.account,
+            scope_name: request.path_parameters[:scope],
+            auth_method: :password,
+            flow: :web_signup
+          )
           invoke_after_account_created(form.account, { mechanism: "signup", provider: nil })
 
           redirect_uri = string_param(:redirect_uri)

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: }

data/lib/standard_id/account_cleanup.rb

@@ -0,0 +1,147 @@
+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.
+  #
+  # An account kept that way is kept FOR the adopters it found: the session
+  # and refresh token ids that were active, remembered in
+  # StandardId.cache_store. When such an adopter's own request then fails
+  # too, it revokes what it issued and calls reclaim_for_failed_adopter!,
+  # which removes the account after all unless it is still adopted (by
+  # someone else, who is then remembered in turn). Only a failing request
+  # that issued one of the remembered credentials can trigger the removal,
+  # so an adopter that went on to succeed is never undone by a later,
+  # unrelated failure. With a cache store that does not share entries
+  # across processes (or the null store) nothing is remembered and the kept
+  # account stays, as before.
+  module AccountCleanup
+    module_function
+
+    # How long a kept account remembers its adopters: comfortably longer than
+    # the adopting request can take to finish.
+    KEPT_FOR_ADOPTERS_TTL = 1.hour
+
+    # @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)
+          remember_adopters!(account)
+          Rails.logger&.info("[StandardId] Kept refused new account #{account.id}: a concurrent sign-in is using it")
+          next false
+        end
+
+        remove!(account)
+      end
+    end
+
+    # Called by a sign-in that matched an EXISTING account and then failed,
+    # with the sessions / refresh tokens it issued (already revoked). When a
+    # refused request kept that account only because of this sign-in (see
+    # destroy_newly_created!), the account is removed after all, unless
+    # something else has adopted it since. Anything else is left alone.
+    #
+    # @return [Boolean] true when the account was removed.
+    def reclaim_for_failed_adopter!(account, sessions: [], refresh_tokens: [])
+      return false unless account&.persisted?
+
+      issued = credential_keys(Array(sessions).compact.map(&:id), Array(refresh_tokens).compact.map(&:id))
+      return false if issued.empty?
+
+      ActiveRecord::Base.transaction do
+        next false if account.class.lock.where(id: account.id).pick(:id).nil?
+
+        kept_for = Array(read_kept_for(account))
+        next false if (kept_for & issued).empty?
+
+        if adopted?(account)
+          remember_adopters!(account)
+          next false
+        end
+
+        Rails.logger&.info("[StandardId] Removing refused new account #{account.id}: the sign-in it was kept for failed")
+        remove!(account)
+      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
+
+    def remove!(account)
+      # 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
+      forget_kept_for(account)
+      true
+    end
+
+    # Remembers the adopters the account is being kept for. Best effort: the
+    # cache is not part of the transaction, and a cache failure only means
+    # the kept account is not reclaimed later.
+    def remember_adopters!(account)
+      session_ids = account.sessions.strict_loading(false).active.pluck(:id)
+      token_ids = StandardId::RefreshToken.active.where(account_id: account.id).pluck(:id)
+      StandardId.cache_store&.write(kept_for_key(account), credential_keys(session_ids, token_ids), expires_in: KEPT_FOR_ADOPTERS_TTL)
+    rescue StandardError => e
+      Rails.logger&.warn("[StandardId] Could not remember the adopters of kept account #{account.id}: #{e.class}: #{e.message}")
+    end
+
+    def read_kept_for(account)
+      StandardId.cache_store&.read(kept_for_key(account))
+    rescue StandardError => e
+      Rails.logger&.warn("[StandardId] Could not read the adopters of kept account #{account.id}: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def forget_kept_for(account)
+      StandardId.cache_store&.delete(kept_for_key(account))
+    rescue StandardError
+      nil
+    end
+
+    def kept_for_key(account)
+      "standard_id:account_cleanup:kept_for:#{account.class.name}:#{account.id}"
+    end
+
+    def credential_keys(session_ids, refresh_token_ids)
+      session_ids.map { |id| "session:#{id}" } + refresh_token_ids.map { |id| "refresh_token:#{id}" }
+    end
+
+    private_class_method :remove!, :remember_adopters!, :read_kept_for, :forget_kept_for, :kept_for_key, :credential_keys
+  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

data/lib/standard_id/errors.rb

@@ -150,6 +150,41 @@ 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
@@ -162,6 +197,8 @@ module StandardId
   #                       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
     REASONS = %i[link_required email_unverified subject_mismatch].freeze
 
@@ -179,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,