standard_id 0.54.1 → 0.55.0

data/lib/standard_id/email_password/token_flow.rb

@@ -0,0 +1,36 @@
+module StandardId
+  module EmailPassword
+    # Mints the token response for an account that Authentication or
+    # Verification has just proven, through the same pipeline as every other
+    # grant: login-method policy (flow :api_email_password), audience checks,
+    # claims, OAUTH_TOKEN_ISSUING / OAUTH_TOKEN_ISSUED (so AccountStatus and
+    # AccountLocking refuse), refresh token and session persistence.
+    #
+    # client_id, scope and audience come from `c.email_password.token_*`,
+    # never from the request. Not reachable from /oauth/token.
+    class TokenFlow < StandardId::Oauth::TokenGrantFlow
+      def initialize(account:, request:)
+        super({}, request)
+        @account = account
+      end
+
+      def authenticate!
+        raise StandardId::InvalidGrantError, "Account is required" if @account.blank?
+      end
+
+      private
+
+      def login_method_policy_context
+        { auth_method: :password, flow: :api_email_password }
+      end
+
+      def subject_id = @account.id
+      def client_id = EmailPassword.config.token_client_id
+      def token_scope = EmailPassword.config.token_scope
+      def audience = EmailPassword.config.token_audience
+      def grant_type = "password"
+      def supports_refresh_token? = true
+      def token_account = @account
+    end
+  end
+end

data/lib/standard_id/email_password/verification.rb

@@ -0,0 +1,155 @@
+module StandardId
+  module EmailPassword
+    # The sign-up code: issuing it (sign-up and resend) and confirming it.
+    module Verification
+      INVALID_CODE_MESSAGE = "Invalid or expired verification code."
+      TOO_MANY_ATTEMPTS_MESSAGE = "Too many incorrect attempts. Please request a new code."
+      LOCKED_OUT_MESSAGE = "Too many incorrect attempts. Please try again tomorrow."
+
+      class << self
+        # Confirms the code for a pending sign-up, verifies the address and runs
+        # `c.email_password.after_email_verified` when the sign-up was made
+        # through Registration (EmailPassword.api_signup?), as a reset does: an
+        # unverified web sign-up that verifies here is verified without it.
+        #
+        # Requires the sign-up password as well as the code. Code alone would be
+        # a takeover: anyone could start a sign-up for an address and the
+        # owner's code would then confirm an account the stranger controls. The
+        # password is checked FIRST and a mismatch is answered exactly like a
+        # wrong code, so a guessed code is never even compared without it.
+        #
+        # A wrong code sent WITH the right password counts toward
+        # rate_limits.email_password_failed_verifications_per_day; at the cap the
+        # address cannot verify, even with the right code, until the window
+        # passes. A wrong password does not count, so a stranger cannot burn the
+        # registrant's daily allowance, and only the right password is told the
+        # address is locked out (otherwise the lockout would reveal that the
+        # address has a pending sign-up). The controller's short per-email
+        # limit (rate_limits.email_password_verify_per_email) does count every
+        # request, so a stranger CAN hold verification off for that window.
+        #
+        # Given a block, yields the account with the password credential's row
+        # locked, after re-checking that the password has not changed since it
+        # was checked, as Authentication.call does: mint tokens inside it, so a
+        # password reset racing this verification either finishes first (and
+        # this answers :invalid_code) or revokes what it minted.
+        #
+        # @return [Account] ready for EmailPassword::TokenFlow
+        # @raise [StandardId::EmailPasswordError] :invalid_code
+        def verify!(email:, code:, password:, request: nil)
+          email = EmailPassword.normalize_email(email)
+          password_credential = EmailPassword.credential_for_password(email, password)
+          identifier = password_credential&.credential&.identifier
+          raise invalid_code(INVALID_CODE_MESSAGE) if identifier.nil?
+          raise invalid_code(LOCKED_OUT_MESSAGE) if DailyLimit.exceeded?(:failed_verification, email)
+
+          verified_digest = password_credential.password_digest
+
+          otp = StandardId::Otp.verify(
+            realm: EmailPassword.config.verification_realm,
+            target: email,
+            channel: :email,
+            code: code.to_s.strip,
+            request: request
+          )
+          failed!(email, otp.error_code) unless otp.success?
+
+          # The hook runs in the same transaction as the verification: if it
+          # raises, the address stays unverified, so the registrant can ask for
+          # a new code (this one is spent) and the hook runs again. Otherwise a
+          # failed hook would leave a verified account that login lets in
+          # without ever provisioning it.
+          account = ActiveRecord::Base.transaction do
+            password_unchanged!(password_credential, verified_digest)
+            EmailPassword.complete_verification!(
+              identifier,
+              name: otp.challenge&.metadata&.dig("name"),
+              request: request,
+              run_hook: EmailPassword.api_signup?(identifier)
+            )
+            identifier.account
+          end
+          return account unless block_given?
+
+          password_credential.with_lock do
+            password_unchanged!(password_credential, verified_digest)
+            yield account
+          end
+        end
+
+        # Resend: issues a fresh code for a pending sign-up, only when +password+
+        # is its password. Otherwise a silent no-op: the endpoint answers the
+        # same either way, so it cannot probe which addresses have accounts, and
+        # a stranger cannot spend the registrant's daily code allowance.
+        #
+        # @return [Boolean] whether a code was issued
+        def send_code(email:, password:, name: nil, request: nil)
+          email = EmailPassword.normalize_email(email)
+          return false unless EmailPassword.pending_identifier(email, password)
+
+          issue_code(email, name: name, request: request)
+        end
+
+        # Issues and delivers a code for +email+ without checking for a pending
+        # sign-up (Registration has just done so). At most
+        # rate_limits.email_password_codes_per_day per address; past that, and
+        # while passwordless.retry_delay is still running (the code already
+        # sent stays valid), a silent no-op.
+        #
+        # The name given at sign-up rides on the challenge's metadata until the
+        # code is confirmed; a resend carries it forward.
+        #
+        # @return [Boolean] whether a code was issued
+        def issue_code(email, name: nil, request: nil)
+          return false if DailyLimit.exceeded?(:code_issued, email)
+
+          config = EmailPassword.config
+          built_in = config.code_delivery.to_sym == :built_in
+          result = StandardId::Otp.issue(
+            realm: config.verification_realm,
+            target: email,
+            channel: :email,
+            request: request,
+            delivery: built_in ? :manual : :custom,
+            metadata: { "name" => name.presence || EmailPassword.signup_name(email) }.compact
+          )
+          return false unless result.success?
+
+          DailyLimit.record!(:code_issued, email)
+          if built_in
+            StandardId::PasswordlessMailer
+              .with(email: email, otp_code: result.code, realm: config.verification_realm)
+              .verification_email
+              .deliver_later
+          end
+          true
+        end
+
+        private
+
+        # Locks the credential (in the caller's transaction) and refuses the
+        # verification if a reset changed the password after it was checked.
+        def password_unchanged!(password_credential, verified_digest)
+          password_credential.lock!
+          raise invalid_code(INVALID_CODE_MESSAGE) unless password_credential.password_digest == verified_digest
+        end
+
+        def failed!(email, error_code)
+          count = DailyLimit.record!(:failed_verification, email)
+          message = if count >= DailyLimit.limit(:failed_verification)
+            LOCKED_OUT_MESSAGE
+          elsif error_code == :max_attempts
+            TOO_MANY_ATTEMPTS_MESSAGE
+          else
+            INVALID_CODE_MESSAGE
+          end
+          raise invalid_code(message)
+        end
+
+        def invalid_code(message)
+          StandardId::EmailPasswordError.new(:invalid_code, message)
+        end
+      end
+    end
+  end
+end

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.1"
+  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.1
+  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