standard_id 0.44.0 → 0.45.0

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

data/lib/standard_id/oauth/password_flow.rb

@@ -55,6 +55,10 @@ module StandardId
         @account.id
       end
 
+      def login_method_policy_context
+        { auth_method: :password, flow: :oauth_password_grant }
+      end
+
       def client_id
         params[:client_id]
       end
@@ -76,15 +80,22 @@ module StandardId
       end
 
       def authenticate_account(username, password)
+        # Credential reaches the account through its identifier (`delegate
+        # :account, to: :identifier`); there is no `account` association to
+        # preload, and asking for one raised AssociationNotFoundError for every
+        # login that found a credential.
         @credential = StandardId::PasswordCredential
-          .includes(credential: :account)
+          .includes(credential: { identifier: :account })
           .find_by(login: username)
 
         # Perform a dummy bcrypt comparison when the credential doesn't exist
         # to prevent user enumeration via response timing differences.
         BCrypt::Password.new(dummy_password_digest).is_password?(password) unless @credential
 
-        @credential&.authenticate(password)&.account
+        # has_secure_password's authenticate returns false (not nil) on a wrong
+        # password, so `&.account` would call false.account → NoMethodError (500).
+        authenticated = @credential&.authenticate(password)
+        authenticated ? authenticated.account : nil
       end
 
       def validate_requested_scope!

data/lib/standard_id/oauth/passwordless_otp_flow.rb

@@ -26,6 +26,10 @@ module StandardId
         account.id
       end
 
+      def login_method_policy_context
+        { auth_method: :passwordless, flow: :oauth_passwordless_otp_grant }
+      end
+
       def client_id
         params[:client_id]
       end

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -15,6 +15,7 @@ module StandardId
       # in a transaction for atomicity.
       def execute
         instrumented_authenticate!
+        enforce_refresh_login_method_policy!
         response = nil
         StandardId::RefreshToken.transaction do
           rotate_current_refresh_token!
@@ -45,6 +46,37 @@ module StandardId
 
       private
 
+      # The refresh_token grant re-checks config.login_method_policy with the
+      # method the ORIGINAL authentication used (recorded on the token, copied
+      # down each rotation). A token minted before 0.45 / before migration
+      # 20261004000000 has none and is checked as :unspecified, so a
+      # restrictive policy refuses it and the client must sign in again.
+      def login_method_policy_context
+        StandardId::AuthLineage.policy_arguments(refresh_token_auth_lineage).merge(flow: :oauth_refresh_token)
+      end
+
+      # Successor tokens inherit the presented token's lineage.
+      def refresh_token_auth_lineage
+        StandardId::AuthLineage.from_refresh_token(@current_refresh_token_record)
+      end
+
+      # Runs after authenticate! proved the token, before rotation. Outside the
+      # rotation transaction so the family revocation persists. The answer is
+      # the same `invalid_grant` as any other dead refresh token: whoever
+      # presents a refresh token may not be its legitimate holder, so the
+      # response must not reveal why (RFC 6749 §5.2; see
+      # Api::Oauth::BaseController#handle_account_unusable). The reason is in
+      # the AUTHENTICATION_METHOD_DENIED event, server-side.
+      def enforce_refresh_login_method_policy!
+        account = token_account
+        return if account.nil?
+
+        StandardId::LoginMethodPolicy.enforce!(account: account, request: request, **login_method_policy_context)
+      rescue StandardId::LoginMethodDenied
+        @current_refresh_token_record&.revoke_family!
+        raise StandardId::InvalidGrantError, "Refresh token is no longer valid"
+      end
+
       def validate_refresh_token_record!
         jti = @refresh_payload[:jti]
         # Legacy tokens minted before jti tracking was added cannot be looked

data/lib/standard_id/oauth/social_flow.rb

@@ -20,6 +20,10 @@ module StandardId
         @account.id
       end
 
+      def login_method_policy_context
+        { auth_method: :social, provider: @connection, flow: :oauth_social_callback }
+      end
+
       def client_id
         @connection
       end

data/lib/standard_id/oauth/subflows/traditional_code_grant.rb

@@ -21,6 +21,11 @@ module StandardId
           @authorization_code ||= SecureRandom.urlsafe_base64(32)
         end
 
+        def lineage_metadata
+          lineage = params[:auth_lineage]
+          lineage ? StandardId::AuthLineage.to_metadata(lineage) : {}
+        end
+
         def store_authorization_code
           StandardId::AuthorizationCode.issue!(
             plaintext_code: authorization_code,
@@ -32,7 +37,7 @@ module StandardId
             code_challenge: params[:code_challenge],
             code_challenge_method: params[:code_challenge_method],
             nonce: params[:nonce],
-            metadata: { state: params[:state] }.compact
+            metadata: { state: params[:state] }.compact.merge(lineage_metadata)
           )
         end
 

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -3,6 +3,13 @@ module StandardId
     class TokenGrantFlow < BaseRequestFlow
       attr_reader :params, :request
 
+      # The refresh token row this grant persisted, once it got that far (nil
+      # before). A caller that rejects the grant after it ran (the API social
+      # callback) revokes it, and its session, from here: when the grant
+      # itself raised after the write, no token response came back to read
+      # it from.
+      attr_reader :issued_refresh_token
+
       def initialize(params, request, current_account: nil)
         @params = params
         @request = request
@@ -17,11 +24,42 @@ module StandardId
 
       def execute
         instrumented_authenticate!
+        enforce_login_method_policy!
         generate_token_response
       end
 
       private
 
+      # The login-method policy context for this grant, or nil when the grant
+      # does not establish a new authentication (authorization_code,
+      # refresh_token, client_credentials derive from one that already
+      # happened, or have no account). Grants that authenticate an account
+      # themselves override this. See StandardId::LoginMethodPolicy.
+      #
+      # @return [Hash, nil] `{ auth_method:, flow:, provider: }`
+      def login_method_policy_context
+        nil
+      end
+
+      # Runs after authenticate! has proven the credential and before any
+      # token, refresh token or session row is created. On refusal an account
+      # created by this very request (passwordless or social registration) is
+      # removed again, mirroring the WebEngine's handle_authentication_denied.
+      def enforce_login_method_policy!
+        policy_context = login_method_policy_context
+        return if policy_context.nil?
+
+        account = token_account
+        return if account.nil?
+
+        StandardId::LoginMethodPolicy.enforce!(account: account, request: request, **policy_context)
+      rescue StandardId::LoginMethodDenied
+        if account.respond_to?(:previously_new_record?) && account.previously_new_record?
+          StandardId::AccountCleanup.destroy_newly_created!(account)
+        end
+        raise
+      end
+
       # authenticate!, wrapped in the Instrumentation::AUTHENTICATE event.
       def instrumented_authenticate!
         StandardId::Instrumentation.instrument(StandardId::Instrumentation::AUTHENTICATE, instrumentation_payload) do
@@ -186,15 +224,29 @@ module StandardId
       end
 
       def persist_refresh_token!(jti:, expires_at:)
-        StandardId::RefreshToken.create!(
+        @issued_refresh_token = StandardId::RefreshToken.create!(
           account_id: subject_id,
           session_id: refresh_token_session_id,
           token_digest: StandardId::RefreshToken.digest_for(jti),
           expires_at: expires_at,
-          previous_token: previous_refresh_token_record
+          previous_token: previous_refresh_token_record,
+          **StandardId::AuthLineage.refresh_token_attributes(refresh_token_auth_lineage)
         )
       end
 
+      # How the authentication behind this grant was established, recorded on
+      # the refresh token so the refresh_token grant can re-check the
+      # login-method policy against it. Grants that authenticate an account
+      # themselves derive it from their policy context; the authorization_code
+      # and refresh_token grants override it (from the code / the presented
+      # token). See StandardId::AuthLineage.
+      def refresh_token_auth_lineage
+        context = login_method_policy_context
+        return StandardId::AuthLineage.empty if context.nil?
+
+        StandardId::AuthLineage.build(context[:auth_method], context[:provider])
+      end
+
       # The parent session for the refresh token issued by THIS grant, when the
       # host materialised one via `config.session.session_type_resolver`.
       #

data/lib/standard_id/providers/base.rb

@@ -212,6 +212,40 @@ module StandardId
           false
         end
 
+        # Whether the `:strict` link_strategy may link this provider's login to
+        # an existing account that was created through ANOTHER provider (for
+        # example, a Google-created account) when the email addresses match.
+        #
+        # Default: false. Every provider, including Google and Apple, keeps
+        # the 0.44 behaviour: `:strict` refuses that link with
+        # SocialLinkError (reason `:link_required`).
+        #
+        # Return true ONLY for the organisation's own identity provider whose
+        # email claims the organisation itself verifies — e.g. a broker-local
+        # directory such as moneta (standard_id-void_which_binds), where an
+        # address is provisioned by the org and cannot be self-asserted. A
+        # public IdP that lets anyone register an address (Google, Apple,
+        # GitHub, ...) must never return true: trusting it would let whoever
+        # controls an address *at that IdP* take over the account holding the
+        # same address here.
+        #
+        # Returning true relaxes ONLY the `:strict` cross-provider check. All
+        # of these still apply, unchanged:
+        #   - the provider must report `email_verified` as true (or "true"),
+        #     otherwise the link is refused with reason `:email_unverified`;
+        #   - the existing email identifier must itself be verified (an
+        #     unverified address on the existing account proves nothing about
+        #     who created it — see the pre-account-hijacking note in the
+        #     README);
+        #   - the identifier must not already be linked to a different `sub`
+        #     from this provider (`:subject_mismatch`);
+        #   - a stored (provider, sub) match still wins over any email match.
+        #
+        # @return [Boolean]
+        def trusted_for_linking?
+          false
+        end
+
         # Returns list of supported authorization parameters for this provider.
         #
         # Include :nonce in this list for OIDC providers to enable nonce validation.

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.44.0"
+  VERSION = "0.45.0"
 end

data/lib/standard_id/web/session_manager.rb

@@ -3,6 +3,11 @@ module StandardId
     class SessionManager
       attr_reader :token_manager, :request, :session, :cookies
 
+      # The session sign_in_account created in this request, set as soon as the
+      # row exists — so a caller can revoke it even when sign_in_account then
+      # raises (e.g. a SESSION_CREATED subscriber fails).
+      attr_reader :created_session
+
       def initialize(token_manager, request:, session:, cookies:, reset_session: nil)
         @token_manager = token_manager
         @request = request
@@ -32,7 +37,26 @@ module StandardId
         Current.account = load_current_account
       end
 
-      def sign_in_account(account, scope_name: nil)
+      # Creates a browser session for an account whose credential the caller
+      # has already verified.
+      #
+      # `config.login_method_policy` is consulted first, before anything is
+      # written; a refusal raises StandardId::LoginMethodDenied (an
+      # AuthenticationDenied) and no session, cookie or Rails-session change
+      # happens. The engine's own controllers pass `auth_method:` /
+      # `provider:` / `flow:`. Host code that signs accounts in itself should
+      # pass at least `auth_method:` (e.g. `:password`, `:social`); without it
+      # the policy sees `:unspecified` under flow `:web_session`, which a
+      # restrictive policy will (correctly) refuse.
+      def sign_in_account(account, scope_name: nil, auth_method: nil, provider: nil, flow: :web_session)
+        StandardId::LoginMethodPolicy.enforce!(
+          account: account,
+          auth_method: auth_method,
+          provider: provider,
+          request: request,
+          flow: flow
+        )
+
         emit_session_creating(account, "browser")
 
         # Prevent session fixation by resetting the Rails session before
@@ -44,7 +68,9 @@ module StandardId
         session[:return_to_after_authenticating] = return_to if return_to
         session[:standard_id_scopes] = existing_scopes if existing_scopes
 
-        token_manager.create_browser_session(account).tap do |browser_session|
+        lineage = StandardId::AuthLineage.build(auth_method || :unspecified, provider)
+        token_manager.create_browser_session(account, auth_lineage: lineage).tap do |browser_session|
+          @created_session = browser_session
           # Store in both session and encrypted cookie for backward compatibility
           # Action Cable will use the encrypted cookie
           session[:session_token] = browser_session.token
@@ -202,13 +228,34 @@ module StandardId
         password_credential = StandardId::PasswordCredential.find_by_token_for(:remember_me, cookies[:remember_token])
         return if password_credential.blank?
 
+        # Remember-me is a re-authentication (it mints a new session), so the
+        # login-method policy applies. A refusal must not raise here — this
+        # runs on any request that asks for current_session — so it signs the
+        # visitor out instead (clearing the remember cookie, so the refused
+        # cookie is not replayed on every request). The refusal itself is
+        # published as AUTHENTICATION_METHOD_DENIED by the policy.
+        begin
+          StandardId::LoginMethodPolicy.enforce!(
+            account: password_credential.account,
+            auth_method: :remember_me,
+            request: request,
+            flow: :web_remember_me
+          )
+        rescue StandardId::LoginMethodDenied
+          clear_session!
+          return
+        end
+
         # Prevent session fixation on returning-user remember-me flow.
         # Note: standard_id_scopes are intentionally NOT preserved here —
         # remember-me re-auth is a fresh session context where scopes
         # must be re-acquired through explicit scoped sign-in.
         @reset_session&.call
 
-        token_manager.create_browser_session(password_credential.account, remember_me: true).tap do |browser_session|
+        # Recorded as :remember_me, the method the policy approved above, so
+        # tokens later derived from this session are re-checked as such.
+        lineage = StandardId::AuthLineage.build(:remember_me)
+        token_manager.create_browser_session(password_credential.account, auth_lineage: lineage).tap do |browser_session|
           # Store in both session and encrypted cookie for backward compatibility
           session[:session_token] = browser_session.token
           write_session_cookie(browser_session)

data/lib/standard_id/web/token_manager.rb

@@ -7,14 +7,17 @@ module StandardId
         @request = request
       end
 
-      def create_browser_session(account)
+      # `auth_lineage` (StandardId::AuthLineage) records how the sign-in was
+      # made in the session's metadata, so codes and tokens derived from this
+      # session can be re-checked against config.login_method_policy.
+      def create_browser_session(account, auth_lineage: nil)
         session_class = StandardId::SessionTypeResolver.resolve!(
           request: request,
           account: account,
           flow: :web_sign_in
         )
 
-        create_session_for(session_class, account: account)
+        create_session_for(session_class, account: account, auth_lineage: auth_lineage)
       end
 
       def create_remember_token(password_credential)
@@ -29,10 +32,12 @@ module StandardId
 
       private
 
-      def create_session_for(session_class, account:)
+      def create_session_for(session_class, account:, auth_lineage: nil)
         attrs = base_attributes(account: account).merge(
           session_specific_attributes(session_class)
         )
+        lineage_metadata = auth_lineage ? StandardId::AuthLineage.to_metadata(auth_lineage) : {}
+        attrs[:metadata] = lineage_metadata if lineage_metadata.present?
         session_class.create!(**attrs)
       end
 

data/lib/standard_id.rb

@@ -33,6 +33,9 @@ require "standard_id/api/session_manager"
 require "standard_id/api/token_manager"
 require "standard_id/api/authentication_guard"
 require "standard_id/utils/callable_parameter_filter"
+require "standard_id/login_method_policy"
+require "standard_id/auth_lineage"
+require "standard_id/account_cleanup"
 require "standard_id/oauth/audience_profile_resolver"
 require "standard_id/oauth/audience_scope_resolver"
 require "standard_id/oauth/base_request_flow"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.44.0
+  version: 0.45.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -237,9 +237,11 @@ files:
 - db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb
 - db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb
 - db/migrate/20261002000000_create_standard_id_social_identities.rb
+- db/migrate/20261004000000_add_auth_method_to_standard_id_refresh_tokens.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/standard_id.rb
+- lib/standard_id/account_cleanup.rb
 - lib/standard_id/account_locking.rb
 - lib/standard_id/account_status.rb
 - lib/standard_id/api/authentication_guard.rb
@@ -247,6 +249,7 @@ files:
 - lib/standard_id/api/token_manager.rb
 - lib/standard_id/api_engine.rb
 - lib/standard_id/association_strict_loading.rb
+- lib/standard_id/auth_lineage.rb
 - lib/standard_id/authorization_bypass.rb
 - lib/standard_id/bearer_token_extraction.rb
 - lib/standard_id/checks/migrations.rb
@@ -270,6 +273,7 @@ files:
 - lib/standard_id/http_client.rb
 - lib/standard_id/instrumentation.rb
 - lib/standard_id/jwt_service.rb
+- lib/standard_id/login_method_policy.rb
 - lib/standard_id/migration_check.rb
 - lib/standard_id/migration_helpers.rb
 - lib/standard_id/oauth/audience_profile_resolver.rb