standard_id 0.54.0 → 0.55.0

data/lib/standard_id/email_password.rb

@@ -0,0 +1,209 @@
+require "concurrent/delay"
+
+module StandardId
+  # Email + password sign-up and sign-in for JSON clients
+  # (Api::EmailPasswordController), switched on with
+  # `c.email_password.enabled = true`.
+  #
+  # Built on the engine's primitives rather than beside them: PasswordCredential
+  # (has_secure_password, PasswordStrength, the single-use password_reset token),
+  # StandardId::Otp for the 6-digit sign-up code, PasswordResetDeliveryJob for
+  # forgot-password, and a TokenGrantFlow (EmailPassword::TokenFlow) for tokens,
+  # so a sign-in here returns the same TokenResponse as the other grants and
+  # refreshes through /oauth/token.
+  #
+  # The rules:
+  #   * Sign-up creates an UNVERIFIED account and emails a code. Tokens are
+  #     issued only once the code is confirmed, together with the sign-up
+  #     password: the code proves the inbox, the password proves the caller is
+  #     whoever started this sign-up.
+  #   * Login with the right password on an unverified address answers
+  #     :unverified, so the client can send the user to its verify screen.
+  #     Every other login failure is one generic :invalid_credentials.
+  #   * Re-submitting sign-up for a pending address never changes its password.
+  #   * Resend and forgot-password always answer the same, whatever the address.
+  #   * A reset link sets the password, verifies the address (following the
+  #     link proves the inbox) and revokes every session and refresh token.
+  #
+  # Each operation returns its result and raises StandardId::EmailPasswordError
+  # otherwise, so a host can drive them from its own controllers too.
+  module EmailPassword
+    # A digest to compare against when no credential exists, so a miss costs
+    # the same bcrypt work as a hit and timing does not reveal whether the
+    # address is registered.
+    DUMMY_PASSWORD_DIGEST = Concurrent::Delay.new { BCrypt::Password.create("").freeze }
+
+    # Identifier#signup_source of a sign-up made through Registration. A reset
+    # runs `after_email_verified` only for these, and
+    # PurgeUnverifiedEmailSignupsJob only deletes these.
+    SIGNUP_SOURCE = "email_password"
+
+    class << self
+      def config
+        StandardId.config.email_password
+      end
+
+      def enabled?
+        config.enabled == true
+      end
+
+      def normalize_email(email)
+        email.to_s.strip.downcase
+      end
+
+      def valid_email?(email)
+        StandardId::EmailIdentifier::EMAIL_FORMAT.match?(email.to_s)
+      end
+
+      # The password credential whose login is +email+, with the identifier and
+      # account it hangs off preloaded.
+      def find_password_credential(email)
+        StandardId::PasswordCredential
+          .includes(credential: { identifier: :account })
+          .find_by(login: normalize_email(email))
+      end
+
+      # The pending sign-up for +email+ when +password+ is its password: the
+      # identifier of an unverified password credential, else nil. A miss still
+      # pays for a bcrypt comparison.
+      def pending_identifier(email, password)
+        identifier = identifier_for_password(email, password)
+        identifier unless identifier.nil? || identifier.verified?
+      end
+
+      # The identifier of the password credential for +email+, only when
+      # +password+ is that credential's password.
+      def identifier_for_password(email, password)
+        credential_for_password(email, password)&.credential&.identifier
+      end
+
+      # The password credential for +email+, only when +password+ is its
+      # password. A miss still pays for a bcrypt comparison.
+      def credential_for_password(email, password)
+        password = password.to_s
+        password_credential = find_password_credential(email)
+        unless password_credential
+          BCrypt::Password.new(DUMMY_PASSWORD_DIGEST.value).is_password?(password)
+          return nil
+        end
+        return nil if password.empty? || !password_credential.authenticate(password)
+
+        password_credential
+      end
+
+      # The first verification of an address, by code or by reset link: marks
+      # it verified and, for a sign-up made through Registration (+run_hook+),
+      # runs `c.email_password.after_email_verified`. A no-op when the address
+      # is already verified, so the hook runs once.
+      #
+      # Call it inside a transaction. If the hook raises, the address stays
+      # unverified and the next verification retries it; and
+      # IDENTIFIER_VERIFICATION_SUCCEEDED waits for the commit, so subscribers
+      # never see a verification that was rolled back.
+      def complete_verification!(identifier, name: nil, request: nil, run_hook: true)
+        identifier.lock!
+        return if identifier.verified?
+
+        identifier.verify!(defer_event: true)
+        hook = config.after_email_verified
+        return unless run_hook && hook.respond_to?(:call)
+
+        call_hook(hook, account: identifier.account, name: name, request: request)
+      end
+
+      # true when +identifier+ was created by Registration (its signup_source),
+      # as opposed to Web::SignupForm, a social sign-in or the host's own flow.
+      def api_signup?(identifier)
+        identifier.signup_source == SIGNUP_SOURCE
+      end
+
+      # Registration writes Identifier#signup_source, which migration
+      # 20261022000000 adds; without it a sign-up would fail with an unknown
+      # attribute, so say what to run instead.
+      def require_signup_source_column!
+        return if StandardId::Identifier.column_names.include?("signup_source")
+
+        raise StandardId::ConfigurationError,
+          "c.email_password needs migration 20261022000000_add_signup_source_to_standard_id_identifiers: " \
+          "run bin/rails standard_id:install:migrations && bin/rails db:migrate"
+      end
+
+      # The name given at sign-up for +email+, carried on its latest
+      # verification code; nil once CleanupExpiredCodeChallengesJob has removed
+      # that code.
+      def signup_name(email)
+        StandardId::CodeChallenge
+          .where(realm: config.verification_realm, channel: "email", target: normalize_email(email))
+          .order(created_at: :desc)
+          .pick(:metadata)
+          &.dig("name")
+      end
+
+      # Field messages for +password+ (empty when acceptable): PasswordStrength
+      # and has_secure_password's own checks on an unsaved probe, then
+      # `c.email_password.password_validator`, only once those pass.
+      def password_errors(password, email: nil)
+        probe = StandardId::PasswordCredential.new(login: email.presence || "probe@example.invalid", password: password)
+        probe.validate
+        errors = probe.errors.messages_for(:password)
+        return errors if errors.any?
+
+        validator = config.password_validator
+        return [] unless validator.respond_to?(:call)
+
+        Array(call_hook(validator, password: password, email: email)).compact.map(&:to_s)
+      end
+
+      # The key per-IP limits count under (`c.email_password.client_key`).
+      def client_key(request)
+        hook = config.client_key
+        key = hook.respond_to?(:call) ? call_hook(hook, request: request) : nil
+        key.presence || request&.remote_ip.to_s
+      end
+
+      # Pre-account-takeover defence for hosts that link social sign-ins by
+      # email (c.social.link_strategy = :trust_provider). If someone started a
+      # sign-up for an address they do not own and never confirmed it, the
+      # owner signing in with a provider would land in THAT account with the
+      # stranger's password attached. The password was never usable (login
+      # needs the code, which only reaches the owner), but it is one reset away
+      # from becoming so. Drop it: the provider sign-in proved the address, the
+      # pending sign-up proved nothing.
+      #
+      # When anything was discarded, every session and refresh token the
+      # account already held is revoked as well: whatever was issued before
+      # the owner proved the address was issued to someone who had not.
+      # SOCIAL_ACCOUNT_LINKED fires after the social flow has issued its own
+      # session or tokens, so pass +issued_before+ (when that login started) to
+      # spare them. Call it from a SOCIAL_ACCOUNT_LINKED subscriber.
+      #
+      # @return [Integer] the number of pending credentials discarded
+      def discard_pending_credentials!(account, issued_before: nil)
+        return 0 if account.nil?
+
+        discarded = 0
+        StandardId::Credential
+          .joins(:identifier)
+          .where(standard_id_identifiers: { account_id: account.id, verified_at: nil })
+          .where(credentialable_type: StandardId::PasswordCredential.name)
+          .find_each do |credential|
+            ActiveRecord::Base.transaction do
+              password_credential = StandardId::PasswordCredential.find_by(id: credential.credentialable_id)
+              credential.destroy!
+              password_credential&.destroy!
+            end
+            discarded += 1
+          end
+
+        if discarded.positive?
+          StandardId::AccessRevocation.revoke_all!(account, reason: "pending_signup_discarded", issued_before: issued_before)
+        end
+        discarded
+      end
+
+      def call_hook(hook, **context)
+        hook.call(**StandardId::Utils::CallableParameterFilter.filter(hook, context))
+      end
+    end
+  end
+end

data/lib/standard_id/errors.rb

@@ -342,6 +342,45 @@ module StandardId
   class InvalidAlgorithmError < InvalidTokenError; end
   class InvalidAudienceTokenError < InvalidTokenError; end
 
+  # Raised by the API email + password endpoints (StandardId::EmailPassword).
+  # +code+ is one of CODES — stable symbols a client can branch on — and the
+  # status is fixed per code, so `c.email_password.error_renderer` can change
+  # the body without having to know the status. +details+ carries field
+  # messages for :weak_password and :invalid_request.
+  class EmailPasswordError < StandardError
+    CODES = {
+      invalid_credentials: { status: :unauthorized, message: "Invalid email or password" },
+      unverified: { status: :forbidden, message: "The email address has not been verified" },
+      account_exists: { status: :conflict, message: "An account with this email already exists" },
+      social_account: { status: :conflict, message: "This email is registered with a different sign-in method" },
+      invalid_code: { status: :unprocessable_content, message: "Invalid or expired verification code" },
+      invalid_reset_token: { status: :unprocessable_content, message: "The password reset link is invalid or has expired" },
+      weak_password: { status: :unprocessable_content, message: "The password does not meet the requirements" },
+      invalid_request: { status: :unprocessable_content, message: "The request is invalid" },
+      login_method_denied: { status: :forbidden, message: "This sign-in method is not available for this account" },
+      rate_limited: { status: :too_many_requests, message: "Too many requests. Please try again later." }
+    }.freeze
+
+    attr_reader :code, :details, :retry_after
+
+    def initialize(code, message = nil, details: {}, retry_after: nil)
+      @code = code.to_sym
+      raise ArgumentError, "Unknown EmailPasswordError code: #{code.inspect}" unless CODES.key?(@code)
+
+      @details = details.to_h
+      @retry_after = retry_after
+      super(message.presence || CODES.dig(@code, :message))
+    end
+
+    def status
+      CODES.dig(code, :status)
+    end
+
+    def http_status
+      Rack::Utils.status_code(status)
+    end
+  end
+
   # Raised for engine misconfiguration — a required config value is missing,
   # malformed, points at a non-callable with the wrong arity, or references a
   # scope whose claims have no resolver registered. Always indicates a

data/lib/standard_id/login_method_policy.rb

@@ -19,6 +19,7 @@ module StandardId
   # | :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) |
+  # | :api_email_password             | :password      | POST /auth/login and /auth/verify-email (Api::EmailPasswordController) |
   #
   # `refresh_token` is re-checked with the method of the authentication it
   # descends from (see StandardId::AuthLineage): a policy tightened after a
@@ -53,7 +54,7 @@ module StandardId
     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
+      api_device_session api_service_session api_email_password
     ].freeze
 
     module_function

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.54.0"
+  VERSION = "0.55.0"
 end

data/lib/standard_id.rb

@@ -77,6 +77,14 @@ require "standard_id/authorization_bypass"
 require "standard_id/utils/ip_normalizer"
 require "standard_id/rate_limit_store"
 require "standard_id/rate_limiter"
+require "standard_id/access_revocation"
+require "standard_id/email_password"
+require "standard_id/email_password/daily_limit"
+require "standard_id/email_password/verification"
+require "standard_id/email_password/registration"
+require "standard_id/email_password/authentication"
+require "standard_id/email_password/password_reset"
+require "standard_id/email_password/token_flow"
 
 require "concurrent/delay"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.54.0
+  version: 0.55.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -132,6 +132,7 @@ files:
 - app/controllers/concerns/standard_id/web_mechanism_gate.rb
 - app/controllers/standard_id/api/authorization_controller.rb
 - app/controllers/standard_id/api/base_controller.rb
+- app/controllers/standard_id/api/email_password_controller.rb
 - app/controllers/standard_id/api/oauth/base_controller.rb
 - app/controllers/standard_id/api/oauth/callback/providers_controller.rb
 - app/controllers/standard_id/api/oauth/introspections_controller.rb
@@ -175,7 +176,9 @@ files:
 - app/jobs/standard_id/cleanup_expired_sessions_job.rb
 - app/jobs/standard_id/password_reset_delivery_job.rb
 - app/jobs/standard_id/purge_stale_dynamic_clients_job.rb
+- app/jobs/standard_id/purge_unverified_email_signups_job.rb
 - app/jobs/standard_id/secure_mail_delivery_job.rb
+- app/mailers/standard_id/account_notice_mailer.rb
 - app/mailers/standard_id/application_mailer.rb
 - app/mailers/standard_id/password_reset_mailer.rb
 - app/mailers/standard_id/passwordless_mailer.rb
@@ -200,6 +203,8 @@ files:
 - app/models/standard_id/session.rb
 - app/models/standard_id/social_identity.rb
 - app/models/standard_id/username_identifier.rb
+- app/views/standard_id/account_notice_mailer/existing_account.html.erb
+- app/views/standard_id/account_notice_mailer/existing_account.text.erb
 - app/views/standard_id/password_reset_mailer/reset_email.html.erb
 - app/views/standard_id/password_reset_mailer/reset_email.text.erb
 - app/views/standard_id/passwordless_mailer/otp_email.html.erb
@@ -243,10 +248,12 @@ files:
 - db/migrate/20261004000000_add_auth_method_to_standard_id_refresh_tokens.rb
 - db/migrate/20261020000000_add_client_application_id_to_standard_id_refresh_tokens.rb
 - db/migrate/20261020120000_add_registration_access_token_digest_to_standard_id_client_applications.rb
+- db/migrate/20261022000000_add_signup_source_to_standard_id_identifiers.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/generators/standard_id/install/templates/standard_id_reference.rb
 - lib/standard_id.rb
+- lib/standard_id/access_revocation.rb
 - lib/standard_id/account_cleanup.rb
 - lib/standard_id/account_locking.rb
 - lib/standard_id/account_status.rb
@@ -267,6 +274,13 @@ files:
 - lib/standard_id/config_schema.rb
 - lib/standard_id/current_attributes.rb
 - lib/standard_id/deprecator.rb
+- lib/standard_id/email_password.rb
+- lib/standard_id/email_password/authentication.rb
+- lib/standard_id/email_password/daily_limit.rb
+- lib/standard_id/email_password/password_reset.rb
+- lib/standard_id/email_password/registration.rb
+- lib/standard_id/email_password/token_flow.rb
+- lib/standard_id/email_password/verification.rb
 - lib/standard_id/engine.rb
 - lib/standard_id/errors.rb
 - lib/standard_id/events.rb