standard_id 0.44.0 → 0.45.0

data/app/controllers/standard_id/api/oauth/callback/providers_controller.rb

@@ -23,28 +23,74 @@ module StandardId
           social_info = provider_response[:user_info]
           provider_tokens = provider_response[:tokens]
           account = find_or_create_account_from_social(social_info)
+          newly_created = account.previously_new_record?
 
-          flow = StandardId::Oauth::SocialFlow.new(
-            params,
-            request,
-            account:,
-            connection: provider.provider_name,
-            scopes: params[:scope]
-          )
+          # Everything after find_or_create_account_from_social can still
+          # reject the login: SocialFlow.new (InvalidScopeError), the grant's
+          # audience/profile binding (InvalidGrantError), the login-method
+          # policy, a SOCIAL_AUTH_COMPLETED subscriber, or anything unexpected.
+          # Any of them leaves no link (it is only written on acceptance), no
+          # new account, and no usable token or session from this request.
+          token_response = nil
+          flow = nil
+          begin
+            flow = StandardId::Oauth::SocialFlow.new(
+              params,
+              request,
+              account:,
+              connection: provider.provider_name,
+              scopes: params[:scope]
+            )
+            token_response = flow.execute
+            run_social_callback(
+              provider: provider.provider_name,
+              social_info:,
+              provider_tokens:,
+              account:,
+              original_request_params: forwarded_request_params
+            )
+            commit_social_link!
+          rescue StandardError
+            removed = social_account_removed_concurrently?(account, newly_created:)
+            revoke_issued_tokens!(flow)
+            discard_social_attempt!(account, newly_created: newly_created)
+            raise unless removed
+
+            # The matched account was removed under this login by a
+            # concurrent, refused request: retryable, not a 500.
+            raise StandardId::InvalidGrantError, SOCIAL_RETRY_MESSAGE
+          end
 
-          token_response = flow.execute
-          run_social_callback(
-            provider: provider.provider_name,
-            social_info:,
-            provider_tokens:,
-            account:,
-            original_request_params: forwarded_request_params
-          )
           render json: token_response, status: :ok
         end
 
         private
 
+        # Write the (provider, sub) link only once the login is accepted.
+        def defer_social_link?
+          true
+        end
+
+        # The response was never sent, but the grant may already have
+        # persisted a refresh token and a session — also when the grant itself
+        # raised after writing them (e.g. an OAUTH_TOKEN_ISSUED subscriber), so
+        # they are read from the flow, not from a token response. Revoke them
+        # so nothing from the rejected request stays usable, and so that
+        # AccountCleanup does not mistake them for a concurrent login using a
+        # new account. A token whose transaction rolled back is not persisted
+        # and is skipped (its session write was rolled back with it).
+        def revoke_issued_tokens!(flow)
+          record = flow&.issued_refresh_token
+          return unless record&.persisted?
+
+          # Loaded by id, not through the association: the record was built
+          # with only session_id, and a host with strict_loading_by_default
+          # would raise here and mask the original error.
+          session = record.session_id && StandardId::Session.find_by(id: record.session_id)
+          session.revoke!(reason: "social_sign_in_rejected") unless session.nil? || session.revoked?
+          record.revoke!
+        end
+
         # Mirror of the web callback's OAuthError handling: emit
         # SOCIAL_AUTH_FAILED for infrastructure-level provider failures
         # (HTTP/DNS/SSL/timeouts surfaced as OAuthError by provider

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

@@ -40,7 +40,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 +74,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 +89,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 +130,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)
+          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

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_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,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

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,