standard_id 0.54.0 → 0.55.0

data/app/jobs/standard_id/purge_unverified_email_signups_job.rb

@@ -0,0 +1,141 @@
+module StandardId
+  # Deletes email + password sign-ups (StandardId::EmailPassword) that were
+  # never verified. A no-op unless `c.email_password.enabled`; not part of
+  # CleanupAllJob, so schedule it yourself (daily is plenty).
+  #
+  # A sign-up that sits unverified is dead weight at best and, at worst, a
+  # stranger squatting someone else's address (see
+  # EmailPassword::Registration). After `c.email_password.unverified_purge_after`
+  # seconds (3 days by default, far beyond the code TTL and the daily code cap)
+  # the pending password credential and its email identifier are removed, and
+  # the account too when nothing else is left on it.
+  #
+  # Only an email identifier that is unverified, has no provider, carries a
+  # password credential, is older than the cutoff AND was created by
+  # EmailPassword::Registration (`signup_source`, EmailPassword.api_signup?)
+  # is considered. That last condition keeps the job away from other
+  # unverified password sign-ups, such as Web::SignupForm's.
+  # Even then the whole account is skipped, unchanged, at any sign of real use:
+  #   * any verified identifier, or any with a provider (a social sign-in
+  #     linked to it does not verify the identifier, so the provider is
+  #     checked separately);
+  #   * any session or refresh token;
+  #   * `c.email_password.account_in_use` returning true (e.g. the host's
+  #     profile rows);
+  #   * any other row still referencing the account: the delete is guarded by
+  #     restrict / foreign keys, and a guard failure rolls the unit back.
+  # A sign-up whose owner asked for a code within
+  # `c.email_password.purge_recent_code_window` seconds is kept, so someone
+  # who comes back on day 4 is not deleted minutes before typing the code in.
+  # So is one whose address asked for a password reset in the last 24 hours
+  # (EmailPassword::DailyLimit's counter; a reset leaves no row), so the
+  # link in flight still works. That check is only as good as the rate-limit
+  # store: with a null store it never fires.
+  # Each sign-up is re-checked under a row lock in its own transaction, so a
+  # verification that lands mid-run wins. The locks are taken in the order
+  # verify and reset take them (password credential, then identifier); a
+  # deadlock or lock wait timeout anyway leaves the sign-up for the next run.
+  class PurgeUnverifiedEmailSignupsJob < ApplicationJob
+    queue_as :default
+
+    # @param older_than_seconds [Integer, nil] defaults to
+    #   c.email_password.unverified_purge_after
+    # @return [Hash] `{ purged_count:, skipped_count: }`
+    def perform(older_than_seconds: nil)
+      return { purged_count: 0, skipped_count: 0 } unless StandardId::EmailPassword.enabled?
+
+      cutoff = (older_than_seconds || config.unverified_purge_after).to_i.seconds.ago
+      purged = 0
+      skipped = 0
+
+      candidates(cutoff).find_each do |identifier|
+        if purge(identifier, cutoff)
+          purged += 1
+        else
+          skipped += 1
+        end
+      end
+
+      Rails.logger.info("[StandardId] Purged #{purged} unverified email sign-ups older than #{cutoff} (skipped #{skipped})")
+      { purged_count: purged, skipped_count: skipped }
+    end
+
+    private
+
+    def config
+      StandardId::EmailPassword.config
+    end
+
+    def candidates(cutoff)
+      StandardId::EmailIdentifier
+        .where(verified_at: nil, provider: nil, signup_source: StandardId::EmailPassword::SIGNUP_SOURCE)
+        .where(created_at: ...cutoff)
+        .where(id: StandardId::Credential.where(credentialable_type: StandardId::PasswordCredential.name).select(:identifier_id))
+    end
+
+    # true when the sign-up was removed, false when it was left alone.
+    def purge(identifier, cutoff)
+      ActiveRecord::Base.transaction do
+        lock_password_credentials(identifier)
+        identifier.lock!
+        return false unless identifier.verified_at.nil? && identifier.provider.nil? && identifier.created_at < cutoff &&
+          StandardId::EmailPassword.api_signup?(identifier)
+
+        account = StandardId.account_class.find_by(id: identifier.account_id)
+        return false if account.nil? || account_in_use?(account)
+        return false if recent_code_requested?(identifier.value) || reset_requested?(identifier.value)
+
+        credentials = StandardId::Credential.where(identifier_id: identifier.id).to_a
+        return false unless credentials.all? { |c| c.credentialable_type == StandardId::PasswordCredential.name }
+
+        password_credentials = StandardId::PasswordCredential.where(id: credentials.map(&:credentialable_id)).to_a
+        credentials.each(&:destroy!)
+        password_credentials.each(&:destroy!)
+        identifier.destroy!
+
+        unless StandardId::Identifier.exists?(account_id: account.id)
+          # The dependent-destroy cascade lazy-loads associations, which a host
+          # running strict_loading_by_default would refuse.
+          account.strict_loading!(false)
+          account.destroy!
+        end
+        true
+      end
+    rescue ActiveRecord::DeleteRestrictionError, ActiveRecord::InvalidForeignKey, ActiveRecord::RecordNotDestroyed,
+      ActiveRecord::Deadlocked, ActiveRecord::LockWaitTimeout => e
+      Rails.logger.warn("[StandardId] Left unverified email sign-up #{identifier.id} alone: #{e.class}")
+      false
+    end
+
+    def lock_password_credentials(identifier)
+      StandardId::PasswordCredential
+        .where(id: StandardId::Credential
+          .where(identifier_id: identifier.id, credentialable_type: StandardId::PasswordCredential.name)
+          .select(:credentialable_id))
+        .order(:id)
+        .lock
+        .to_a
+    end
+
+    def account_in_use?(account)
+      return true if StandardId::Identifier.where(account_id: account.id).where("verified_at IS NOT NULL OR provider IS NOT NULL").exists?
+      return true if StandardId::Session.where(account_id: account.id).exists?
+      return true if StandardId::RefreshToken.where(account_id: account.id).exists?
+
+      hook = config.account_in_use
+      # Any truthy answer keeps the account: when in doubt, keep.
+      hook.respond_to?(:call) && StandardId::EmailPassword.call_hook(hook, account: account) ? true : false
+    end
+
+    def reset_requested?(email)
+      StandardId::EmailPassword::DailyLimit.count(:reset_requested, email).positive?
+    end
+
+    def recent_code_requested?(email)
+      StandardId::CodeChallenge
+        .where(realm: config.verification_realm, target: StandardId::EmailPassword.normalize_email(email))
+        .where(created_at: config.purge_recent_code_window.to_i.seconds.ago..)
+        .exists?
+    end
+  end
+end

data/app/mailers/standard_id/account_notice_mailer.rb

@@ -0,0 +1,33 @@
+module StandardId
+  # Notices about an account, sent to its address rather than to whoever made
+  # the request.
+  #
+  # * #existing_account: sign-up was attempted for an address that already has
+  #   an account, while `c.email_password.reveal_existing_accounts` is false
+  #   (the API then answers as if the sign-up went ahead). The owner learns
+  #   about it and how to get in; the requester learns nothing.
+  #
+  # Copy lives under `standard_id.account_notice_mailer.<action>.*` in
+  # config/locales/en.yml; override any key in the host's locale files, or the
+  # templates in app/views/standard_id/account_notice_mailer/.
+  class AccountNoticeMailer < ApplicationMailer
+    layout false
+
+    helper_method :notice_copy
+
+    # @param email [String]
+    def existing_account
+      @email = params[:email]
+
+      mail(to: @email, from: StandardId.config.passwordless.mailer_from, subject: notice_copy(:subject))
+    end
+
+    # Copy for the current action, falling back to the gem's English (see
+    # PasswordlessMailer#otp_copy).
+    def notice_copy(key, default: nil, **options)
+      scope = "standard_id.account_notice_mailer.#{action_name}"
+      english = I18n.t(key, scope: scope, locale: :en, default: default, **options)
+      I18n.t(key, scope: scope, default: english, **options)
+    end
+  end
+end

data/app/models/standard_id/identifier.rb

@@ -20,9 +20,17 @@ module StandardId
       verified_at.present?
     end
 
-    def verify!
+    # +defer_event+ holds IDENTIFIER_VERIFICATION_SUCCEEDED until the
+    # enclosing transaction commits, and drops it if that rolls back. The
+    # verification has committed by the time it fires, so a failing
+    # subscriber is logged rather than raised.
+    def verify!(defer_event: false)
       update!(verified_at: Time.current)
-      emit_verification_succeeded
+      if defer_event
+        ActiveRecord.after_all_transactions_commit { emit_verification_succeeded_after_commit }
+      else
+        emit_verification_succeeded
+      end
     end
 
     def unverify!
@@ -63,6 +71,18 @@ module StandardId
       )
     end
 
+    def emit_verification_succeeded_after_commit
+      emit_verification_succeeded
+    rescue StandardError => e
+      logger = StandardId.logger
+      return unless logger.respond_to?(:error)
+
+      logger.error(
+        "[StandardId::Identifier] Failed to publish IDENTIFIER_VERIFICATION_SUCCEEDED " \
+        "for identifier #{id}: #{e.class}: #{e.message}"
+      )
+    end
+
     def emit_account_verified
       StandardId::Events.publish(
         StandardId::Events::ACCOUNT_VERIFIED,

data/app/models/standard_id/session.rb

@@ -176,8 +176,10 @@ module StandardId
       )
     end
 
-    # DB state is already committed by the time this runs; event publishing is
-    # best-effort audit emission. A failing subscriber must not short-circuit the
+    # DB state is already committed by the time this runs, unless the caller
+    # wraps revoke_all_for! in its own transaction, as StandardId::AccessRevocation
+    # does for the password-reset paths (Web::ResetPasswordConfirmForm and
+    # EmailPassword::PasswordReset). Event publishing is best-effort audit emission. A failing subscriber must not short-circuit the
     # loop and leave later sessions without their SESSION_REVOKED event, which
     # would permanently desync audit-trail consumers from the DB.
     def self.publish_session_revocations(sessions, account:, reason:, now:)

data/app/views/standard_id/account_notice_mailer/existing_account.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; background-color: #f5f5f5; margin: 0; padding: 0; }
+    .container { max-width: 480px; margin: 40px auto; background-color: #ffffff; border-radius: 8px; padding: 40px; }
+    .footer { margin-top: 32px; font-size: 13px; color: #888888; text-align: center; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <p><%= notice_copy(:greeting) %></p>
+    <p><%= notice_copy(:intro) %></p>
+    <p><%= notice_copy(:action) %></p>
+    <p><%= notice_copy(:ignore) %></p>
+    <div class="footer">
+      <p><%= notice_copy(:footer) %></p>
+    </div>
+  </div>
+</body>
+</html>

data/app/views/standard_id/account_notice_mailer/existing_account.text.erb

@@ -0,0 +1,10 @@
+<%= notice_copy(:greeting) %>
+
+<%= notice_copy(:intro) %>
+
+<%= notice_copy(:action) %>
+
+<%= notice_copy(:ignore) %>
+
+--
+<%= notice_copy(:footer) %>

data/config/locales/en.yml

@@ -20,3 +20,11 @@ en:
           other: "This code will expire in %{count} minutes."
         ignore: "If you did not request this code, you can safely ignore this email."
         footer: "This is an automated message. Please do not reply."
+    account_notice_mailer:
+      existing_account:
+        subject: "Someone tried to sign up with your email"
+        greeting: "Hi,"
+        intro: "Someone just tried to create an account with this email address, but you already have one."
+        action: "If that was you, sign in the way you did before, or reset your password if you have forgotten it."
+        ignore: "If it wasn't you, you can safely ignore this email. Your account has not changed."
+        footer: "This is an automated message. Please do not reply."

data/config/routes/api.rb

@@ -10,6 +10,20 @@ StandardId::ApiEngine.routes.draw do
       post :start
     end
 
+    # Email + password for JSON clients (StandardId::EmailPassword). Drawn
+    # always but matched only while c.email_password.enabled is true, so the
+    # endpoints 404 otherwise.
+    constraints(->(_request) { StandardId::EmailPassword.enabled? }) do
+      scope "auth", controller: :email_password, as: :email_password do
+        post "register", action: :register, as: :register
+        post "login", action: :login, as: :login
+        post "verify-email", action: :verify, as: :verify
+        post "verify-email/resend", action: :resend, as: :resend
+        post "password/forgot", action: :forgot_password, as: :forgot_password
+        post "password/reset", action: :reset_password, as: :reset_password
+      end
+    end
+
     namespace :oidc do
       resource :logout, only: [:show], controller: :logout
     end

data/db/migrate/20261022000000_add_signup_source_to_standard_id_identifiers.rb

@@ -0,0 +1,13 @@
+# Records which flow created an identifier's sign-up. EmailPassword::Registration
+# writes "email_password"; nothing else writes it, so NULL means any other
+# sign-up (Web::SignupForm, social, passwordless, the host's own). The email +
+# password API reads it to tell its own pending sign-ups apart: a password
+# reset runs `after_email_verified` only for them, and
+# PurgeUnverifiedEmailSignupsJob only ever deletes them. One nullable string
+# column, no default, no index: metadata-only on PostgreSQL. Required before
+# enabling `c.email_password`.
+class AddSignupSourceToStandardIdIdentifiers < ActiveRecord::Migration[8.0]
+  def change
+    add_column :standard_id_identifiers, :signup_source, :string
+  end
+end

data/lib/standard_id/access_revocation.rb

@@ -0,0 +1,40 @@
+module StandardId
+  # Ends everything an account is signed in with: every session (cascading to
+  # the refresh tokens under it), then every refresh token with no session, such
+  # as one minted by a grant flow. Sessions alone would leave those alive.
+  # Revoking rather than destroying keeps the audit trail and fires one
+  # SESSION_REVOKED per session.
+  #
+  # Runs in one transaction, so a caller that wraps it in its own (a password
+  # change, say) commits the change and the revocation together. The
+  # SESSION_REVOKED events then publish before that commit; each is rescued
+  # (see Session.publish_session_revocations), so a subscriber cannot roll the
+  # change back, but one that reads the rows must do so after commit.
+  #
+  # Access tokens already issued are stateless JWTs and stay valid until they
+  # expire.
+  module AccessRevocation
+    module_function
+
+    # @param account [ActiveRecord::Base]
+    # @param reason [String] carried on each SESSION_REVOKED event
+    # @param issued_before [Time, nil] only revoke sessions and refresh tokens
+    #   CREATED before this. Activity (updated_at) never spares one.
+    def revoke_all!(account, reason:, issued_before: nil)
+      ActiveRecord::Base.transaction do
+        if issued_before
+          sessions = StandardId::Session
+            .where(account_id: account.id, revoked_at: nil)
+            .where(created_at: ...issued_before)
+          StandardId::Session.revoke_sessions!(sessions, account: account, reason: reason)
+        else
+          StandardId::Session.revoke_all_for!(account, reason: reason)
+        end
+
+        refresh_tokens = StandardId::RefreshToken.where(account_id: account.id, revoked_at: nil)
+        refresh_tokens = refresh_tokens.where(created_at: ...issued_before) if issued_before
+        refresh_tokens.update_all(revoked_at: Time.current)
+      end
+    end
+  end
+end

data/lib/standard_id/config/callable_validator.rb

@@ -70,6 +70,41 @@ module StandardId
           signature: "(audience:, client:, configured_scopes:)",
           kind: :keyword,
           keywords: %i[audience client configured_scopes]
+        },
+        "email_password.reset_url" => {
+          signature: "(request:)",
+          kind: :keyword,
+          keywords: %i[request]
+        },
+        "email_password.client_key" => {
+          signature: "(request:)",
+          kind: :keyword,
+          keywords: %i[request]
+        },
+        "email_password.account_creator" => {
+          signature: "(email:, name:, request:)",
+          kind: :keyword,
+          keywords: %i[email name request]
+        },
+        "email_password.password_validator" => {
+          signature: "(password:, email:)",
+          kind: :keyword,
+          keywords: %i[password email]
+        },
+        "email_password.after_email_verified" => {
+          signature: "(account:, name:, request:)",
+          kind: :keyword,
+          keywords: %i[account name request]
+        },
+        "email_password.account_in_use" => {
+          signature: "(account:)",
+          kind: :keyword,
+          keywords: %i[account]
+        },
+        "email_password.error_renderer" => {
+          signature: "(error:, request:)",
+          kind: :keyword,
+          keywords: %i[error request]
         }
       }.freeze
 
@@ -154,6 +189,7 @@ module StandardId
         def validate_keyword!(path, callable, allowed_keywords, signature)
           params = extract_parameters(callable)
           return if params.nil?
+          validate_no_required_positional!(path, callable, params, signature)
           # If the callable takes a double-splat, it accepts anything — fine.
           return if params.any? { |type, _| type == :keyrest }
 
@@ -167,6 +203,19 @@ module StandardId
             "(allowed keywords: #{allowed_keywords.inspect})."
         end
 
+        # EmailPassword.call_hook passes only the keywords a hook declares, so a
+        # lambda with a required positional argument (`->(request) { }`) would
+        # raise on its first call. Limited to the email_password hooks, which
+        # are new: older keyword hooks keep accepting what they always did.
+        def validate_no_required_positional!(path, callable, params, signature)
+          return unless path.start_with?("email_password.") && lambda_callable?(callable)
+          return unless params.any? { |type, _| type == :req }
+
+          raise StandardId::ConfigurationError,
+            "StandardId config: `#{path}` takes a positional argument, but it is called " \
+            "with keyword arguments. Expected signature #{signature}."
+        end
+
         def validate_claim_resolvers!(config)
           resolvers = config.oauth.claim_resolvers
           return if resolvers.nil? || resolvers.empty?

data/lib/standard_id/config/schema.rb

@@ -277,6 +277,93 @@ StandardId::ConfigSchema.define do
     field :mailer_subject, type: :string, default: "Reset your password"
   end
 
+  # Email + password sign-up and sign-in over JSON (Api::EmailPasswordController,
+  # StandardId::EmailPassword), for native and SPA clients that cannot use the
+  # WebEngine's cookie forms. Off by default: until `enabled` is true the
+  # routes are not drawn at all (a routing constraint, so a host's own routes
+  # behind the mount point still match). See README "Email + password API".
+  #
+  # Sign-up creates an UNVERIFIED account and emails a 6-digit code; tokens are
+  # issued only when the code is confirmed, together with the sign-up password.
+  scope :email_password do
+    field :enabled, type: :boolean, default: false
+
+    # Stamped on the tokens this flow mints. It plays the role a provider name
+    # plays for social tokens: the client presents it on the refresh_token
+    # grant, which must match the token's client_id claim.
+    field :token_client_id, type: :string, default: "email"
+    field :token_scope, type: :string, default: "profile"
+    field :token_audience, type: :string, default: nil
+
+    # OTP realm for the sign-up code. Deliberately not "authentication": that
+    # realm resolves (and can create) an account on verify.
+    field :verification_realm, type: :string, default: "email_verification"
+
+    # What sign-up answers for an address that already has a verified password
+    # account, or belongs to a social-only account:
+    #   true  — (default) 409 :account_exists / :social_account
+    #   false — the same 202 as a new address, and the owner is emailed
+    #           (AccountNoticeMailer#existing_account), so sign-up cannot be
+    #           used to learn which addresses are registered.
+    field :reveal_existing_accounts, type: :boolean, default: true
+
+    field :require_name, type: :boolean, default: false
+    field :name_max_length, type: :integer, default: 100
+
+    # Who emails the sign-up code:
+    #   :built_in — the engine, with PasswordlessMailer#verification_email
+    #   :custom   — a host PASSWORDLESS_CODE_GENERATED subscriber (the event
+    #               carries delivery: :custom and realm verification_realm)
+    # Independent of passwordless.delivery, so turning this on does not start
+    # delivering codes for the passwordless-login endpoint.
+    field :code_delivery, type: :symbol, default: :built_in
+
+    # Link emailed by forgot-password. A String containing "{token}", or a
+    # callable `(request:)` returning one. Required once enabled: the reset
+    # page lives on the host, not the API engine. Delivery follows
+    # reset_password.delivery.
+    field :reset_url, type: :any, default: nil
+
+    # Callable `(request:)` returning the key the per-IP limits and the daily
+    # per-network reset cap count under. Default: request.remote_ip. Return a
+    # masked network (an IPv4 /24, IPv6 /64) to stop address rotation inside
+    # one allocation from resetting the count.
+    field :client_key, type: :any, default: nil
+
+    # Callable `(email:, name:, request:)` returning a new, persisted account.
+    # Default: account_class.create! with email and name (the local part when
+    # name is blank), each only when the account has that attribute.
+    field :account_creator, type: :any, default: nil
+
+    # Callable `(password:, email:)` returning an Array of messages (empty when
+    # acceptable), run after PasswordStrength on sign-up and reset. For checks
+    # that must not be a model validation, e.g. a breached-password lookup.
+    field :password_validator, type: :any, default: nil
+
+    # Callable `(account:, name:, request:)` run when a sign-up's address is
+    # first verified, by its code or by a reset link, before tokens are
+    # minted, e.g. to provision a profile. +name+ is the one given at sign-up.
+    # Only sign-ups made through this API run it (a reset of a web sign-up
+    # does not). It runs in the verification's transaction, with the password
+    # credential and identifier rows locked: a raise undoes it, and a slow
+    # hook holds those locks for as long as it takes.
+    field :after_email_verified, type: :any, default: nil
+
+    # Callable `(account:)`; truthy keeps an account from
+    # PurgeUnverifiedEmailSignupsJob on top of the built-in checks.
+    field :account_in_use, type: :any, default: nil
+
+    # Callable `(error:, request:)` returning the JSON body for a
+    # StandardId::EmailPasswordError; the status stays error.http_status.
+    # Default: { error:, error_description:, details? }.
+    field :error_renderer, type: :any, default: nil
+
+    # PurgeUnverifiedEmailSignupsJob: unverified sign-ups older than this are
+    # removed, unless a code was requested within purge_recent_code_window.
+    field :unverified_purge_after, type: :integer, default: 259200 # 3 days in seconds
+    field :purge_recent_code_window, type: :integer, default: 86400 # 24 hours in seconds
+  end
+
   scope :session do
     field :browser_session_lifetime, type: :integer, default: 86400 # 24 hours in seconds
     field :browser_session_remember_me_lifetime, type: :integer, default: 2592000 # 30 days in seconds
@@ -875,5 +962,26 @@ StandardId::ConfigSchema.define do
     # "throttled" from "token invalid" and turn the limiter into a token-validity
     # oracle.
     field :introspection_per_ip, type: :integer, default: 30              # per 15 minutes
+
+    # Email + password API (Api::EmailPasswordController). The other actions
+    # reuse the limits above: register signup_per_ip + verification_start_per_target,
+    # login login_per_*, resend verification_start_*, forgot password_reset_start_*.
+    field :email_password_verify_per_email, type: :integer, default: 10  # per 15 minutes
+    field :email_password_reset_per_ip, type: :integer, default: 20      # per 15 minutes
+
+    # Daily (24h) per-address caps (StandardId::EmailPassword::DailyLimit), on
+    # top of the short windows. Counted whether or not the address has an
+    # account, so reaching one reveals nothing.
+    #   failed_verifications — a wrong code sent WITH the right password; at the
+    #     cap the address cannot verify until the window passes. Wrong-password
+    #     attempts never count, so a stranger cannot lock the registrant out.
+    #   codes — sign-up codes (and existing-account notices) emailed.
+    #   reset_requests_per_network — forgot-password emails per address per
+    #     client_key, so one attacker cannot spend the owner's allowance.
+    #   reset_requests — the same across all networks.
+    field :email_password_failed_verifications_per_day, type: :integer, default: 10
+    field :email_password_codes_per_day, type: :integer, default: 10
+    field :email_password_reset_requests_per_network_per_day, type: :integer, default: 5
+    field :email_password_reset_requests_per_day, type: :integer, default: 20
   end
 end

data/lib/standard_id/email_password/authentication.rb

@@ -0,0 +1,71 @@
+module StandardId
+  module EmailPassword
+    # The email + password check for login. Token minting is TokenFlow.
+    #
+    # An unknown address, a wrong password and an account that signs in only
+    # another way all raise one generic :invalid_credentials, so login cannot
+    # enumerate accounts. :unverified is only reachable WITH the right
+    # password, so it reveals nothing the caller did not already know.
+    # Publishes the events Oauth::PasswordFlow does.
+    #
+    # 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
+    # verified. Mint tokens inside it: PasswordReset.complete! takes the same
+    # lock to change the password and revoke access, so a login racing a reset
+    # either finishes first (and its tokens are revoked) or fails.
+    module Authentication
+      class << self
+        # @return [Account]
+        # @raise [StandardId::EmailPasswordError] :invalid_credentials, :unverified
+        def call(email:, password:)
+          email = EmailPassword.normalize_email(email)
+          password = password.to_s
+
+          StandardId::Events.publish(
+            StandardId::Events::AUTHENTICATION_ATTEMPT_STARTED,
+            account_lookup: email,
+            auth_method: "password"
+          )
+
+          password_credential = EmailPassword.find_password_credential(email)
+          unless password_credential
+            BCrypt::Password.new(DUMMY_PASSWORD_DIGEST.value).is_password?(password)
+            failed!(email)
+          end
+
+          identifier = password_credential.credential&.identifier
+          verified_digest = password_credential.password_digest
+          failed!(email) unless identifier && password_credential.authenticate(password)
+
+          account = identifier.account
+          StandardId::Events.publish(
+            StandardId::Events::PASSWORD_VALIDATED,
+            account: account,
+            credential_id: password_credential.id
+          )
+
+          raise StandardId::EmailPasswordError.new(:unverified) unless identifier.verified?
+          return account unless block_given?
+
+          password_credential.with_lock do
+            failed!(email) unless password_credential.password_digest == verified_digest
+            yield account
+          end
+        end
+
+        private
+
+        def failed!(email)
+          StandardId::Events.publish(
+            StandardId::Events::AUTHENTICATION_FAILED,
+            account_lookup: email,
+            auth_method: "password",
+            error_code: "invalid_credentials",
+            error_message: "Invalid email or password"
+          )
+          raise StandardId::EmailPasswordError.new(:invalid_credentials)
+        end
+      end
+    end
+  end
+end