standard_id 0.54.1 → 0.55.1

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

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,160 @@
+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
+
+        CREDENTIAL_ASSOCIATIONS = { credential: { identifier: :account } }.freeze
+        private_constant :CREDENTIAL_ASSOCIATIONS
+
+        def find_credential(token)
+          return nil if token.blank?
+
+          StandardId::PasswordCredential
+            .includes(CREDENTIAL_ASSOCIATIONS)
+            .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; report and carry on, as Web::ResetPasswordConfirmForm
+        # does.
+        #
+        # lock! reloaded the credential, dropping what find_credential
+        # preloaded, so load it again: under strict loading a subscriber that
+        # walks credential.identifier would otherwise raise.
+        def publish_reset_completed(account, password_credential)
+          ActiveRecord::Associations::Preloader.new(
+            records: [password_credential], associations: CREDENTIAL_ASSOCIATIONS
+          ).call
+          StandardId::Events.publish(
+            StandardId::Events::CREDENTIAL_PASSWORD_RESET_COMPLETED,
+            credential: password_credential,
+            account: account
+          )
+        rescue StandardError => e
+          Rails.error.report(e, handled: true, source: "standard_id")
+          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