standard_id 0.3.2 → 0.5.0

data/lib/standard_id/jwt_service.rb

@@ -1,5 +1,6 @@
 require "jwt"
 require "concurrent/delay"
+require "concurrent/atomic/atomic_reference"
 require "openssl"
 require "digest"
 
@@ -34,6 +35,11 @@ module StandardId
       end
     end
 
+    @signing_key_ref = Concurrent::AtomicReference.new
+    @key_id_ref = Concurrent::AtomicReference.new
+    @previous_keys_ref = Concurrent::AtomicReference.new
+    @jwks_ref = Concurrent::AtomicReference.new
+
     def self.session_class
       SESSION_CLASS.value
     end
@@ -52,7 +58,11 @@ module StandardId
 
     def self.signing_key
       if asymmetric?
-        @signing_key_cache ||= parse_private_key(StandardId.config.oauth.signing_key)
+        @signing_key_ref.get || begin
+          computed = parse_private_key(StandardId.config.oauth.signing_key)
+          @signing_key_ref.compare_and_set(nil, computed)
+          @signing_key_ref.get
+        end
       else
         Rails.application.secret_key_base
       end
@@ -74,16 +84,24 @@ module StandardId
 
       # Generate stable key ID from public key fingerprint
       # Use public_to_pem which works for both RSA and EC keys
-      @key_id ||= Digest::SHA256.hexdigest(signing_key.public_to_pem)[0..7]
+      @key_id_ref.get || begin
+        computed = Digest::SHA256.hexdigest(signing_key.public_to_pem)[0..7]
+        @key_id_ref.compare_and_set(nil, computed)
+        @key_id_ref.get
+      end
     end
 
     def self.previous_keys
       return [] unless asymmetric?
 
-      @previous_keys_cache ||= Array(StandardId.config.oauth.previous_signing_keys).filter_map do |entry|
-        parse_previous_key_entry(entry)
-      rescue StandardError
-        nil
+      @previous_keys_ref.get || begin
+        computed = Array(StandardId.config.oauth.previous_signing_keys).filter_map do |entry|
+          parse_previous_key_entry(entry)
+        rescue StandardError
+          nil
+        end
+        @previous_keys_ref.compare_and_set(nil, computed)
+        @previous_keys_ref.get
       end
     end
 
@@ -93,11 +111,15 @@ module StandardId
       [{ kid: key_id, key: verification_key, algorithm: algorithm }] + previous_keys
     end
 
+    # NOTE: Individual resets are atomic but the group is not — a concurrent
+    # reader between two .set(nil) calls may see a mix of old and new values.
+    # This is acceptable: key rotation is an infrequent operator action and
+    # the worst case is one request using a stale (but still valid) key.
     def self.reset_cached_key!
-      @key_id = nil
-      @signing_key_cache = nil
-      @previous_keys_cache = nil
-      @jwks = nil
+      @key_id_ref.set(nil)
+      @signing_key_ref.set(nil)
+      @previous_keys_ref.set(nil)
+      @jwks_ref.set(nil)
     end
 
     def self.encode(payload, expires_in: 1.hour)
@@ -168,12 +190,16 @@ module StandardId
     def self.jwks
       return nil unless asymmetric?
 
-      @jwks ||= begin
-        exported_keys = all_verification_keys.map do |entry|
-          jwk = JWT::JWK.new(entry[:key], kid: entry[:kid]).export
-          jwk.merge(alg: entry[:algorithm], use: "sig")
+      @jwks_ref.get || begin
+        computed = begin
+          exported_keys = all_verification_keys.map do |entry|
+            jwk = JWT::JWK.new(entry[:key], kid: entry[:kid]).export
+            jwk.merge(alg: entry[:algorithm], use: "sig")
+          end
+          { keys: exported_keys }
         end
-        { keys: exported_keys }
+        @jwks_ref.compare_and_set(nil, computed)
+        @jwks_ref.get
       end
     end
 

data/lib/standard_id/oauth/authorization_code_authorization_flow.rb

@@ -2,7 +2,7 @@ module StandardId
   module Oauth
     class AuthorizationCodeAuthorizationFlow < AuthorizationFlow
       expect_params :client_id, :audience
-      permit_params :scope, :redirect_uri, :state, :connection, :prompt, :organization, :invitation, :code_challenge, :code_challenge_method
+      permit_params :scope, :redirect_uri, :state, :connection, :prompt, :organization, :invitation, :code_challenge, :code_challenge_method, :nonce
 
       private
 
@@ -39,7 +39,8 @@ module StandardId
           audience: audience,
           state: state,
           code_challenge: flow_params[:code_challenge],
-          code_challenge_method: flow_params[:code_challenge_method]
+          code_challenge_method: flow_params[:code_challenge_method],
+          nonce: flow_params[:nonce]
         }
       end
     end

data/lib/standard_id/oauth/authorization_code_flow.rb

@@ -70,6 +70,10 @@ module StandardId
       def audience
         @authorization_code&.audience
       end
+
+      def nonce
+        @authorization_code&.nonce
+      end
     end
   end
 end

data/lib/standard_id/oauth/password_flow.rb

@@ -1,9 +1,13 @@
+require "concurrent/delay"
+
 module StandardId
   module Oauth
     class PasswordFlow < TokenGrantFlow
       expect_params :username, :password, :client_id
       permit_params :client_secret, :audience, :scope, :realm
 
+      DUMMY_PASSWORD_DIGEST = Concurrent::Delay.new { BCrypt::Password.create("").freeze }
+
       def authenticate!
         validate_client_secret!(params[:client_id], params[:client_secret]) if params[:client_secret].present?
         emit_authentication_started
@@ -95,7 +99,7 @@ module StandardId
       end
 
       def dummy_password_digest
-        @dummy_password_digest ||= BCrypt::Password.create("").freeze
+        DUMMY_PASSWORD_DIGEST.value
       end
 
       def default_scope

data/lib/standard_id/oauth/passwordless_otp_flow.rb

@@ -6,53 +6,22 @@ module StandardId
 
       def authenticate!
         validate_client_secret!(params[:client_id], params[:client_secret]) if params[:client_secret].present?
+        validate_requested_scope!
 
-        if code_challenge.blank?
-          emit_otp_validation_failed
-          raise StandardId::InvalidGrantError, "Invalid or expired verification code"
-        end
+        @verification_result = StandardId::Passwordless::VerificationService.verify(
+          connection: params[:connection],
+          username: params[:username],
+          code: params[:otp],
+          request: request
+        )
 
-        if account.blank?
-          raise StandardId::InvalidGrantError, "Unable to authenticate user"
+        unless @verification_result.success?
+          raise StandardId::InvalidGrantError, @verification_result.error
         end
-
-        validate_requested_scope!
-
-        code_challenge.use!
-        emit_otp_validated
       end
 
       private
 
-      def emit_otp_validated
-        StandardId::Events.publish(
-          StandardId::Events::OTP_VALIDATED,
-          account: account,
-          channel: params[:connection]
-        )
-        StandardId::Events.publish(
-          StandardId::Events::PASSWORDLESS_CODE_VERIFIED,
-          code_challenge: code_challenge,
-          account: account,
-          channel: params[:connection]
-        )
-      end
-
-      def emit_otp_validation_failed
-        StandardId::Events.publish(
-          StandardId::Events::OTP_VALIDATION_FAILED,
-          identifier: params[:username],
-          channel: params[:connection],
-          attempts: nil
-        )
-        StandardId::Events.publish(
-          StandardId::Events::PASSWORDLESS_CODE_FAILED,
-          identifier: params[:username],
-          channel: params[:connection],
-          attempts: nil
-        )
-      end
-
       def subject_id
         account.id
       end
@@ -77,28 +46,8 @@ module StandardId
         true
       end
 
-      def code_challenge
-        @code_challenge ||= StandardId::CodeChallenge.active.find_by(
-          realm: "authentication",
-          channel: params[:connection],
-          target: params[:username],
-          code: params[:otp]
-        )
-      end
-
       def account
-        @account ||= strategy_for(params[:connection]).find_or_create_account(params[:username])
-      end
-
-      def strategy_for(connection)
-        case connection
-        when "email"
-          StandardId::Passwordless::EmailStrategy.new(request)
-        when "sms"
-          StandardId::Passwordless::SmsStrategy.new(request)
-        else
-          raise StandardId::InvalidRequestError, "Unsupported connection type: #{connection}"
-        end
+        @verification_result&.account
       end
 
       def validate_requested_scope!

data/lib/standard_id/oauth/subflows/social_login_grant.rb

@@ -31,7 +31,8 @@ module StandardId
             audience: params[:audience],
             state: params[:state],
             code_challenge: params[:code_challenge],
-            code_challenge_method: params[:code_challenge_method]
+            code_challenge_method: params[:code_challenge_method],
+            nonce: params[:nonce]
           }.compact
 
           # Remove code_challenge_method if code_challenge is not present

data/lib/standard_id/oauth/subflows/traditional_code_grant.rb

@@ -31,6 +31,7 @@ module StandardId
             account: params[:current_account],
             code_challenge: params[:code_challenge],
             code_challenge_method: params[:code_challenge_method],
+            nonce: params[:nonce],
             metadata: { state: params[:state] }.compact
           )
         end

data/lib/standard_id/passwordless/verification_service.rb

@@ -0,0 +1,227 @@
+module StandardId
+  module Passwordless
+    class VerificationService
+      # Result object returned by .verify.
+      # - success?: true/false
+      # - account: the resolved account (nil on failure)
+      # - challenge: the consumed CodeChallenge (nil on failure)
+      # - error: error message string (nil on success)
+      # - attempts: nil on success, 0 when no challenge was found (fabricated
+      #   target), or 1+ for wrong-code failures against an active challenge
+      Result = Data.define(:success?, :account, :challenge, :error, :attempts)
+
+      STRATEGY_MAP = {
+        "email" => StandardId::Passwordless::EmailStrategy,
+        "sms"   => StandardId::Passwordless::SmsStrategy
+      }.freeze
+
+      class << self
+        # Verify a passwordless OTP code and resolve the account.
+        #
+        # @param email [String, nil] The email address (mutually exclusive with phone)
+        # @param phone [String, nil] The phone number (mutually exclusive with email)
+        # @param connection [String, nil] Channel type ("email" or "sms") — convenience
+        #   alternative to email:/phone: (use with username:)
+        # @param username [String, nil] The identifier value — used with connection:
+        # @param code [String] The OTP code to verify
+        # @param request [ActionDispatch::Request] The current request (needed for strategy)
+        # @return [Result] A result object with success?, account, challenge, error, and attempts
+        #
+        # OTP_VALIDATION_FAILED / PASSWORDLESS_CODE_FAILED events are only emitted
+        # when an active challenge exists but the code is wrong. Requests with no
+        # matching challenge (e.g. fabricated usernames) do not emit failure events
+        # — this avoids noise from speculative probes that never triggered a code.
+        # NOTE: This is a behavioral change from the pre-extraction API flow
+        # (PasswordlessOtpFlow), which emitted failure events unconditionally.
+        #
+        # @example Using connection/username (preferred for callers with channel info)
+        #   result = StandardId::Passwordless::VerificationService.verify(
+        #     connection: "email",
+        #     username: "user@example.com",
+        #     code: "123456",
+        #     request: request
+        #   )
+        #
+        # @example Using email/phone directly
+        #   result = StandardId::Passwordless::VerificationService.verify(
+        #     email: "user@example.com",
+        #     code: "123456",
+        #     request: request
+        #   )
+        #   if result.success?
+        #     sign_in(result.account)
+        #   else
+        #     render_error(result.error)
+        #   end
+        #
+        def verify(email: nil, phone: nil, code:, request:, connection: nil, username: nil)
+          # Allow callers to use connection:/username: instead of email:/phone:
+          if connection.present?
+            if username.blank?
+              raise StandardId::InvalidRequestError, "username: is required when connection: is provided"
+            end
+
+            case connection.to_s
+            when "email" then email = username
+            when "sms"   then phone = username
+            else raise StandardId::InvalidRequestError, "Unsupported connection type: #{connection}"
+            end
+          end
+
+          new(email: email, phone: phone, code: code, request: request).verify
+        end
+      end
+
+      def initialize(email: nil, phone: nil, code:, request:)
+        @code = code.to_s.strip
+        @request = request
+        resolve_target_and_channel!(email, phone)
+      end
+
+      def verify
+        if @code.blank?
+          return failure("Code is required")
+        end
+
+        challenge = find_active_challenge
+        code_matches = challenge.present? && secure_compare(challenge.code, @code)
+        attempts = record_failed_attempt(challenge, code_matches)
+
+        unless code_matches
+          emit_otp_validation_failed(attempts) if challenge.present?
+          return failure("Invalid or expired verification code", attempts: attempts)
+        end
+
+        # Re-fetch with lock inside a transaction to prevent concurrent use.
+        result = nil
+        ActiveRecord::Base.transaction do
+          locked_challenge = StandardId::CodeChallenge.lock.find(challenge.id)
+          unless locked_challenge.active?
+            # No OTP_VALIDATION_FAILED event here: the code was correct but the
+            # challenge was consumed by a concurrent request — not an attacker
+            # guessing codes. Emitting a failure event would be misleading.
+            result = failure("Invalid or expired verification code", attempts: attempts)
+            raise ActiveRecord::Rollback
+          end
+
+          strategy = strategy_for(@channel)
+          account = strategy.find_or_create_account(@target)
+
+          locked_challenge.use!
+
+          result = success(account: account, challenge: locked_challenge)
+        end
+
+        raise "BUG: transaction block failed to set result" if result.nil?
+
+        # Emit events after the transaction commits so subscribers never see
+        # events for rolled-back state.
+        emit_otp_validated(result.account, result.challenge) if result.success?
+
+        result
+      rescue ActiveRecord::RecordNotFound
+        failure("Invalid or expired verification code")
+      rescue ActiveRecord::RecordInvalid => e
+        failure("Unable to complete verification: #{e.record.errors.full_messages.to_sentence}")
+      end
+
+      private
+
+      def resolve_target_and_channel!(email, phone)
+        if email.present?
+          @target = email.to_s.strip
+          @channel = "email"
+        elsif phone.present?
+          @target = phone.to_s.strip
+          @channel = "sms"
+        else
+          raise StandardId::InvalidRequestError, "Either email: or phone: must be provided"
+        end
+      end
+
+      def find_active_challenge
+        StandardId::CodeChallenge.active.find_by(
+          realm: "authentication",
+          channel: @channel,
+          target: @target
+        )
+      end
+
+      # NOTE: The update! here can raise ActiveRecord::RecordInvalid, which is
+      # rescued alongside account-creation errors. This is intentional — both
+      # represent unexpected persistence failures and warrant the same response.
+      def record_failed_attempt(challenge, code_matches)
+        return 0 if challenge.blank?
+        return 0 if code_matches
+
+        attempts = (challenge.metadata["attempts"] || 0) + 1
+        challenge.update!(metadata: challenge.metadata.merge("attempts" => attempts))
+
+        max_attempts = StandardId.config.passwordless.max_attempts
+        challenge.use! if attempts >= max_attempts
+
+        attempts
+      end
+
+      def secure_compare(a, b)
+        ActiveSupport::SecurityUtils.secure_compare(a.to_s, b.to_s)
+      end
+
+      def strategy_for(channel)
+        klass = STRATEGY_MAP[channel]
+        raise StandardId::InvalidRequestError, "Unsupported connection type: #{channel}" unless klass
+        klass.new(@request)
+      end
+
+      def emit_otp_validated(account, challenge)
+        StandardId::Events.publish(
+          StandardId::Events::OTP_VALIDATED,
+          account: account,
+          channel: @channel
+        )
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_VERIFIED,
+          code_challenge: challenge,
+          account: account,
+          channel: @channel
+        )
+      end
+
+      def emit_otp_validation_failed(attempts)
+        StandardId::Events.publish(
+          StandardId::Events::OTP_VALIDATION_FAILED,
+          identifier: @target,
+          channel: @channel,
+          attempts: attempts
+        )
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_FAILED,
+          identifier: @target,
+          channel: @channel,
+          attempts: attempts
+        )
+      end
+
+      def success(account:, challenge:)
+        Result.new(
+          "success?": true,
+          account: account,
+          challenge: challenge,
+          error: nil,
+          attempts: nil
+        )
+      end
+
+      # attempts is nil on success (not meaningful) and 0 when no challenge was found.
+      def failure(error, attempts: nil)
+        Result.new(
+          "success?": false,
+          account: nil,
+          challenge: nil,
+          error: error,
+          attempts: attempts
+        )
+      end
+    end
+  end
+end

data/lib/standard_id/testing/authentication_helpers.rb

@@ -0,0 +1,75 @@
+module StandardId
+  module Testing
+    # Helpers for stubbing StandardId authentication in controller and request specs.
+    #
+    # Usage in rails_helper.rb:
+    #
+    #   require "standard_id/testing"
+    #
+    #   RSpec.configure do |config|
+    #     config.include StandardId::Testing::AuthenticationHelpers, type: :request
+    #     config.include StandardId::Testing::AuthenticationHelpers, type: :controller
+    #   end
+    #
+    module AuthenticationHelpers
+      # Stub web (cookie-based) authentication for controllers that include
+      # StandardId::WebAuthentication.
+      #
+      # Stubs the following methods on the given controller class:
+      # - current_account → returns the given account
+      # - authenticated? → true when account is present
+      # - authenticate_account! → no-op (returns true)
+      # - require_browser_session! → no-op (returns true)
+      #
+      # @param account [Object] the account to return from current_account
+      # @param controller_class [Class] the controller class to stub (default: ApplicationController)
+      #
+      # Example:
+      #   stub_web_authentication(account: my_account)
+      #   stub_web_authentication(account: my_account, controller_class: BackendController)
+      #
+      def stub_web_authentication(account:, controller_class: ApplicationController)
+        allow_any_instance_of(controller_class).to receive(:current_account).and_return(account)
+        allow_any_instance_of(controller_class).to receive(:authenticated?).and_return(account.present?)
+        allow_any_instance_of(controller_class).to receive(:authenticate_account!).and_return(true)
+        allow_any_instance_of(controller_class).to receive(:require_browser_session!).and_return(true)
+      end
+
+      # Stub API (JWT-based) authentication for controllers that include
+      # StandardId::ApiAuthentication.
+      #
+      # @param account [Object] the account to return from current_account
+      # @param session [Object, nil] optional session object for current_session
+      # @param controller_class [Class] the controller class to stub (default: inferred)
+      #
+      # Example:
+      #   stub_api_authentication(account: my_account)
+      #   stub_api_authentication(account: my_account, session: mock_session)
+      #
+      # When controller_class is not provided, defaults to Api::BaseController — the
+      # conventional base class generated by StandardId's install generator.
+      #
+      # Note: Uses allow_any_instance_of which RSpec discourages. For more targeted
+      # stubbing, pass the exact controller class your spec exercises:
+      #
+      #   stub_api_authentication(account: my_account, controller_class: Api::V1::WidgetsController)
+      #
+      def stub_api_authentication(account:, session: nil, controller_class: nil)
+        if controller_class.nil?
+          unless defined?(Api::BaseController)
+            raise ArgumentError,
+              "Could not infer API controller class. Api::BaseController is not defined. " \
+              "Pass controller_class: explicitly (e.g. controller_class: YourApi::BaseController)."
+          end
+
+          controller_class = Api::BaseController
+        end
+
+        allow_any_instance_of(controller_class).to receive(:current_account).and_return(account)
+        allow_any_instance_of(controller_class).to receive(:authenticated?).and_return(account.present?)
+        allow_any_instance_of(controller_class).to receive(:verify_access_token!).and_return(true)
+        allow_any_instance_of(controller_class).to receive(:current_session).and_return(session)
+      end
+    end
+  end
+end

data/lib/standard_id/testing/factories/credentials.rb

@@ -0,0 +1,24 @@
+FactoryBot.define do
+  factory :standard_id_password_credential, class: "StandardId::PasswordCredential" do
+    sequence(:login) { |n| "user#{n}@example.com" }
+    password { "password123" }
+    password_confirmation { "password123" }
+  end
+
+  factory :standard_id_credential, class: "StandardId::Credential" do
+    association :identifier, factory: [:standard_id_email_identifier, :verified]
+    association :credentialable, factory: :standard_id_password_credential
+
+    # Sync login to identifier value so authentication works out of the box.
+    # If you override credentialable after build, set login manually.
+    after(:build) do |credential|
+      credential.credentialable.login = credential.identifier.value
+    end
+  end
+
+  factory :standard_id_client_secret_credential, class: "StandardId::ClientSecretCredential" do
+    association :client_application, factory: :standard_id_client_application
+    name { "Default Secret" }
+    active { true }
+  end
+end

data/lib/standard_id/testing/factories/identifiers.rb

@@ -0,0 +1,37 @@
+FactoryBot.define do
+  factory :standard_id_email_identifier, class: "StandardId::EmailIdentifier" do
+    sequence(:value) { |n| "user#{n}@example.com" }
+
+    trait :verified do
+      verified_at { Time.current }
+    end
+
+    trait :unverified do
+      verified_at { nil }
+    end
+  end
+
+  factory :standard_id_phone_number_identifier, class: "StandardId::PhoneNumberIdentifier" do
+    sequence(:value) { |n| "+1555#{(n % 10_000_000).to_s.rjust(7, '0')}" }
+
+    trait :verified do
+      verified_at { Time.current }
+    end
+
+    trait :unverified do
+      verified_at { nil }
+    end
+  end
+
+  factory :standard_id_username_identifier, class: "StandardId::UsernameIdentifier" do
+    sequence(:value) { |n| "user_#{n}" }
+
+    trait :verified do
+      verified_at { Time.current }
+    end
+
+    trait :unverified do
+      verified_at { nil }
+    end
+  end
+end