standard_id 0.54.0 → 0.55.0

data/lib/standard_id/email_password/daily_limit.rb

@@ -0,0 +1,67 @@
+require "digest"
+
+module StandardId
+  module EmailPassword
+    # Per-address caps over a 24-hour window, on top of the controller's short
+    # per-IP / per-email limits. Those bound bursts; these bound what one
+    # address can be put through in a day, however patiently it is spread out.
+    # The limits are `c.rate_limits.email_password_*_per_day` (see the schema).
+    #
+    # Counted per normalised address whether or not an account exists, so a cap
+    # being reached reveals nothing. Counters live in the engine's rate-limit
+    # store. The window is fixed from the first event: `increment(expires_in:)`
+    # only sets the expiry when it creates the entry.
+    #
+    # Check-then-record is not atomic, so concurrent requests can overshoot a
+    # cap by a few. That is fine for an abuse bound; do not use these as quotas.
+    module DailyLimit
+      WINDOW = 24.hours
+
+      LIMIT_FIELDS = {
+        failed_verification: :email_password_failed_verifications_per_day,
+        code_issued: :email_password_codes_per_day,
+        reset_requested_network: :email_password_reset_requests_per_network_per_day,
+        reset_requested: :email_password_reset_requests_per_day
+      }.freeze
+
+      class << self
+        def limit(kind)
+          StandardId.config.rate_limits.public_send(LIMIT_FIELDS.fetch(kind)).to_i
+        end
+
+        # +scope+ further partitions the counter (the client key for
+        # :reset_requested_network).
+        def exceeded?(kind, email, scope: nil)
+          count(kind, email, scope: scope) >= limit(kind)
+        end
+
+        def count(kind, email, scope: nil)
+          store.read(key(kind, email, scope: scope)).to_i
+        end
+
+        # Records one event; returns the new count.
+        def record!(kind, email, scope: nil)
+          store.increment(key(kind, email, scope: scope), 1, expires_in: WINDOW).to_i
+        end
+
+        # Records one event unless the cap is already reached. Returns true when
+        # the event may proceed.
+        def consume!(kind, email, scope: nil)
+          return false if exceeded?(kind, email, scope: scope)
+
+          record!(kind, email, scope: scope) <= limit(kind)
+        end
+
+        def key(kind, email, scope: nil)
+          LIMIT_FIELDS.fetch(kind) # unknown kinds raise
+          subject = [EmailPassword.normalize_email(email), scope].compact.join("|")
+          "standard_id:email-password-daily:#{kind}:#{Digest::SHA256.hexdigest(subject)}"
+        end
+
+        def store
+          StandardId::RateLimiter::STORE
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/email_password/password_reset.rb

@@ -0,0 +1,148 @@
+module StandardId
+  module EmailPassword
+    # Forgot-password and the reset it leads to.
+    module PasswordReset
+      class TokenAlreadyUsed < StandardError; end
+
+      class << self
+        # Queues the reset email for +email+. The lookup, the token and the
+        # CREDENTIAL_PASSWORD_RESET_INITIATED event all happen in
+        # PasswordResetDeliveryJob, so the request path is identical whether or
+        # not the address has an account. Delivery follows
+        # reset_password.delivery.
+        #
+        # Daily caps, counted whether or not the address has an account:
+        # rate_limits.email_password_reset_requests_per_network_per_day per
+        # address per client key, so an attacker who burns their own allowance
+        # does not stop the owner, elsewhere, from getting a link; and
+        # email_password_reset_requests_per_day per address overall. The
+        # network cap is checked first, so requests it refuses never spend the
+        # shared ceiling.
+        #
+        # @return [void]
+        def request(email:, request: nil)
+          email = EmailPassword.normalize_email(email)
+          return if email.blank?
+
+          url_template = reset_url_template(request)
+          client_key = EmailPassword.client_key(request)
+          return if DailyLimit.exceeded?(:reset_requested_network, email, scope: client_key)
+          return unless DailyLimit.consume!(:reset_requested, email)
+
+          DailyLimit.record!(:reset_requested_network, email, scope: client_key)
+          StandardId::PasswordResetDeliveryJob.perform_later(email: email, reset_url_template: url_template)
+        end
+
+        # Whether +token+ still resolves (not expired, used or tampered with).
+        def valid_token?(token)
+          find_credential(token).present?
+        end
+
+        # Sets a new password from a reset token, verifies the address and
+        # revokes every session and refresh token (AccessRevocation).
+        #
+        # A reset that verifies a pending sign-up is its first verification, so
+        # it runs `c.email_password.after_email_verified` too, in the same
+        # transaction (EmailPassword.complete_verification!): if the hook
+        # raises, nothing changes and the token still works. An unverified
+        # account that did not sign up through Registration (no signup_source,
+        # EmailPassword.api_signup?) is verified without the hook.
+        #
+        # The token is PasswordCredential's `generates_token_for
+        # :password_reset`: it embeds the current digest, so the change below is
+        # what makes it single-use. That holds under concurrency too: the row is
+        # locked and the token re-resolved inside the transaction, so of two
+        # requests racing with one token, the second sees the new digest.
+        #
+        # @param password_confirmation [String, nil] compared when given
+        # @return [Account]
+        # @raise [StandardId::EmailPasswordError] :invalid_reset_token,
+        #   :weak_password
+        def complete!(token:, password:, password_confirmation: nil, request: nil)
+          password = password.to_s
+          password_credential = find_credential(token)
+          identifier = password_credential&.credential&.identifier
+          raise StandardId::EmailPasswordError.new(:invalid_reset_token) if identifier.nil?
+
+          validate!(password, password_confirmation, password_credential.login)
+
+          account = identifier.account
+          issued_for_digest = password_credential.password_digest
+
+          ActiveRecord::Base.transaction do
+            password_credential.lock!
+            unless password_credential.password_digest == issued_for_digest &&
+                find_credential(token)&.id == password_credential.id
+              raise TokenAlreadyUsed
+            end
+
+            password_credential.update!(password: password)
+            api_signup = !identifier.verified? && EmailPassword.api_signup?(identifier)
+            EmailPassword.complete_verification!(
+              identifier,
+              name: (EmailPassword.signup_name(password_credential.login) if api_signup),
+              request: request,
+              run_hook: api_signup
+            )
+            StandardId::AccessRevocation.revoke_all!(account, reason: "password_reset")
+          end
+
+          publish_reset_completed(account, password_credential)
+          account
+        rescue TokenAlreadyUsed
+          raise StandardId::EmailPasswordError.new(:invalid_reset_token)
+        end
+
+        private
+
+        def find_credential(token)
+          return nil if token.blank?
+
+          StandardId::PasswordCredential
+            .includes(credential: { identifier: :account })
+            .find_by_token_for(:password_reset, token.to_s)
+        end
+
+        def validate!(password, password_confirmation, login)
+          # has_secure_password ignores an empty assignment on an existing
+          # record, which would "succeed" without changing anything.
+          errors = password.empty? ? ["can't be blank"] : EmailPassword.password_errors(password, email: login)
+          details = {}
+          details[:password] = errors if errors.any?
+          if !password_confirmation.nil? && password_confirmation.to_s != password
+            details[:password_confirmation] = ["doesn't match Password"]
+          end
+          raise StandardId::EmailPasswordError.new(:weak_password, details: details) if details.any?
+        end
+
+        def reset_url_template(request)
+          setting = EmailPassword.config.reset_url
+          template = setting.respond_to?(:call) ? EmailPassword.call_hook(setting, request: request) : setting
+          return template.to_s if template.to_s.include?("{token}")
+
+          raise StandardId::ConfigurationError,
+            "c.email_password.reset_url must be a URL containing \"{token}\" (or a callable (request:) returning one), " \
+            "e.g. \"https://app.example.com/password-reset?token={token}\"."
+        end
+
+        # The reset has already happened, so a failing subscriber must not turn
+        # it into an error; log and carry on, as Web::ResetPasswordConfirmForm does.
+        def publish_reset_completed(account, password_credential)
+          StandardId::Events.publish(
+            StandardId::Events::CREDENTIAL_PASSWORD_RESET_COMPLETED,
+            credential: password_credential,
+            account: account
+          )
+        rescue StandardError => e
+          logger = StandardId.logger
+          return unless logger.respond_to?(:error)
+
+          logger.error(
+            "[StandardId::EmailPassword::PasswordReset] Failed to publish " \
+            "CREDENTIAL_PASSWORD_RESET_COMPLETED for account #{account.id}: #{e.class}: #{e.message}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/email_password/registration.rb

@@ -0,0 +1,141 @@
+module StandardId
+  module EmailPassword
+    # Sign-up: creates an unverified account with a password credential and
+    # emails it a code. No tokens here; those come from Verification.verify!.
+    #
+    # Re-submitting sign-up for an address whose sign-up was never verified
+    # NEVER changes the pending password: overwriting it would let anyone
+    # re-register a stranger's pending address with their own password and
+    # then ride the owner's code into the account. It is treated like a resend:
+    #   * same password as the pending one -> a fresh code is sent;
+    #   * different password               -> nothing changes, nothing is sent.
+    # Both get the same answer as a brand-new address, so sign-up cannot be used
+    # to learn that someone started a sign-up. The owner of a squatted address
+    # recovers through forgot-password (the link verifies the address and
+    # replaces the password), a social sign-in (see
+    # EmailPassword.discard_pending_credentials!), or
+    # PurgeUnverifiedEmailSignupsJob.
+    #
+    # An address that already has a verified password account, or belongs to
+    # an account that signs in another way, raises :account_exists /
+    # :social_account, unless `c.email_password.reveal_existing_accounts` is
+    # false: then it returns normally and the address is emailed
+    # (AccountNoticeMailer#existing_account) instead.
+    #
+    # ACCOUNT_CREATED and CREDENTIAL_PASSWORD_CREATED fire here, inside the
+    # sign-up transaction, for an account whose address is NOT yet verified
+    # (as they do for Web::SignupForm). Provision anything that should wait for
+    # a proven address from `c.email_password.after_email_verified` instead.
+    module Registration
+      class << self
+        # @return [String] the normalised email
+        # @raise [StandardId::EmailPasswordError] :invalid_request,
+        #   :weak_password, :account_exists, :social_account
+        def call(email:, password:, name: nil, request: nil)
+          email = EmailPassword.normalize_email(email)
+          name = name.to_s.strip
+          password = password.to_s
+          validate!(email, name, password)
+
+          existing = EmailPassword.find_password_credential(email)
+          if existing
+            identifier = existing.credential&.identifier
+            return existing_account!(email, :account_exists, password) if identifier.nil? || identifier.verified?
+
+            Verification.issue_code(email, name: name, request: request) if existing.authenticate(password)
+            return email
+          end
+
+          return existing_account!(email, :social_account, password) if StandardId::EmailIdentifier.exists?(value: email)
+
+          create_account!(email, name, password, request)
+          Verification.issue_code(email, name: name, request: request)
+          email
+        rescue ActiveRecord::RecordNotUnique
+          # Lost a race with a concurrent sign-up for the same address.
+          existing_account!(email, :account_exists)
+        rescue ActiveRecord::RecordInvalid => e
+          # The same race, caught by the uniqueness validation instead.
+          return existing_account!(email, :account_exists) if e.record.errors.of_kind?(:login, :taken)
+
+          # A host Account validation (or account_creator) refused the record.
+          raise StandardId::EmailPasswordError.new(:invalid_request, details: e.record.errors.to_hash)
+        end
+
+        private
+
+        def validate!(email, name, password)
+          config = EmailPassword.config
+          details = {}
+          details[:name] = ["can't be blank"] if config.require_name && name.blank?
+          if name.length > config.name_max_length.to_i
+            details[:name] = ["is too long (maximum is #{config.name_max_length} characters)"]
+          end
+          details[:email] = ["is invalid"] unless EmailPassword.valid_email?(email)
+          raise StandardId::EmailPasswordError.new(:invalid_request, details: details) if details.any?
+
+          errors = EmailPassword.password_errors(password, email: email)
+          raise StandardId::EmailPasswordError.new(:weak_password, details: { password: errors }) if errors.any?
+        end
+
+        # +password+ is hashed and thrown away when concealing: a new address
+        # pays one bcrypt to store its password, so an existing one must too,
+        # or the response time would tell them apart.
+        def existing_account!(email, code, password = nil)
+          raise StandardId::EmailPasswordError.new(code) if EmailPassword.config.reveal_existing_accounts
+
+          StandardId::PasswordCredential.new(password: password) unless password.nil?
+          if DailyLimit.consume!(:code_issued, email)
+            StandardId::AccountNoticeMailer.with(email: email).existing_account.deliver_later
+          end
+          email
+        end
+
+        def create_account!(email, name, password, request)
+          EmailPassword.require_signup_source_column!
+          ActiveRecord::Base.transaction do
+            StandardId::Events.publish(
+              StandardId::Events::ACCOUNT_CREATING,
+              account_params: { email: email, name: name.presence }.compact,
+              auth_method: "password"
+            )
+
+            account = build_account(email, name, request)
+            identifier = StandardId::EmailIdentifier.create!(
+              account: account, value: email, signup_source: EmailPassword::SIGNUP_SOURCE
+            )
+            password_credential = StandardId::PasswordCredential.create!(login: email, password: password)
+            StandardId::Credential.create!(identifier: identifier, credentialable: password_credential)
+
+            StandardId::Events.publish(
+              StandardId::Events::ACCOUNT_CREATED,
+              account: account,
+              auth_method: "password",
+              source: "email_password_signup"
+            )
+            StandardId::Events.publish(
+              StandardId::Events::CREDENTIAL_PASSWORD_CREATED,
+              credential: password_credential,
+              account: account
+            )
+            account
+          end
+        end
+
+        def build_account(email, name, request)
+          creator = EmailPassword.config.account_creator
+          if creator.respond_to?(:call)
+            account = EmailPassword.call_hook(creator, email: email, name: name.presence, request: request)
+            raise StandardId::ConfigurationError, "c.email_password.account_creator must return a persisted account" unless account&.persisted?
+
+            return account
+          end
+
+          account_class = StandardId.account_class
+          attributes = { email: email, name: name.presence || email.split("@").first }
+          account_class.create!(attributes.slice(*account_class.attribute_names.map(&:to_sym)))
+        end
+      end
+    end
+  end
+end

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