standard_id 0.1.5 → 0.1.7

data/lib/standard_id/events.rb

@@ -0,0 +1,137 @@
+require_relative "events/definitions"
+require_relative "events/event"
+
+module StandardId
+  module Events
+    # Event namespace prefix for all StandardId events
+    NAMESPACE = "standard_id"
+
+    class << self
+      # Publish an event with the given name and payload
+      #
+      # @param event_name [String, Symbol] The event name (use constants from Definitions)
+      # @param payload [Hash] The event payload data
+      # @yield [Hash] Optional block that receives the payload, useful for lazy evaluation
+      # @return [void]
+      #
+      # @example Simple publish
+      #   StandardId::Events.publish(:authentication_succeeded, account: user)
+      #
+      # @example With block for lazy payload
+      #   StandardId::Events.publish(:authentication_succeeded) do
+      #     { account: expensive_lookup, duration_ms: calculate_duration }
+      #   end
+      #
+      def publish(event_name, payload = {}, &block)
+        event_payload = block ? block.call.merge(payload) : payload
+        full_event_name = namespaced_event_name(event_name)
+
+        # Add standard metadata to all events
+        enriched_payload = enrich_payload(event_payload, event_name)
+
+        ActiveSupport::Notifications.instrument(full_event_name, enriched_payload)
+      rescue ActiveSupport::Notifications::InstrumentationSubscriberError => e
+        # Re-raise the first exception only (stop at first failure)
+        # This prevents confusing "multiple exceptions" messages when
+        # multiple guards (e.g., AccountStatus + AccountLocking) both fail
+        raise e.exceptions.first if e.exceptions.any?
+      end
+
+      # Subscribe to an event with a block or callable
+      #
+      # @param event_names [String, Symbol, Array<String, Symbol>] The event name(s) to subscribe to
+      # @yield [StandardId::Events::Event] The event object with name, payload, and timing
+      # @return [ActiveSupport::Notifications::Fanout::Subscribers::Evented, Array] The subscription(s)
+      #
+      # @example Block subscription
+      #   StandardId::Events.subscribe(:authentication_succeeded) do |event|
+      #     puts "Login from #{event.payload[:ip_address]}"
+      #   end
+      #
+      # @example Multiple events subscription
+      #   StandardId::Events.subscribe(:session_creating, :session_validating) do |event|
+      #     check_account_status(event)
+      #   end
+      #
+      # @example Pattern subscription (subscribe to all authentication events)
+      #   StandardId::Events.subscribe(/authentication/) do |event|
+      #     audit_log(event)
+      #   end
+      #
+      def subscribe(*event_names, &block)
+        event_names = event_names.flatten
+
+        if event_names.size == 1
+          subscribe_single(event_names.first, &block)
+        else
+          event_names.map { |event_name| subscribe_single(event_name, &block) }
+        end
+      end
+
+      # Subscribe to an event pattern using a regex
+      #
+      # @param pattern [Regexp] The pattern to match event names
+      # @yield [StandardId::Events::Event] The event object
+      # @return [ActiveSupport::Notifications::Fanout::Subscribers::Evented] The subscription
+      #
+      def subscribe_to_pattern(pattern, &block)
+        subscribe_single(pattern, &block)
+      end
+
+      # Unsubscribe from events
+      #
+      # @param subscribers [Object, Array<Object>] The subscriber(s) returned from subscribe()
+      # @return [void]
+      #
+      def unsubscribe(*subscribers)
+        subscribers.flatten.each do |subscriber|
+          ActiveSupport::Notifications.unsubscribe(subscriber)
+        end
+      end
+
+      # Get the full namespaced event name
+      #
+      # @param event_name [String, Symbol] The short event name
+      # @return [String] The full namespaced event name
+      #
+      def namespaced_event_name(event_name)
+        return event_name.to_s if event_name.to_s.start_with?("#{NAMESPACE}.")
+
+        "#{NAMESPACE}.#{event_name}"
+      end
+
+      private
+
+      def subscribe_single(event_name, &block)
+        pattern = event_name.is_a?(Regexp) ? event_name : namespaced_event_name(event_name)
+
+        ActiveSupport::Notifications.subscribe(pattern) do |name, start, finish, id, payload|
+          event = Event.new(
+            name: name,
+            payload: payload,
+            started_at: start,
+            finished_at: finish,
+            transaction_id: id
+          )
+          block.call(event)
+        end
+      end
+
+      def enrich_payload(payload, event_name)
+        enriched = {
+          event_type: event_name.to_s,
+          event_id: SecureRandom.uuid,
+          timestamp: Time.current.iso8601
+        }
+
+        if defined?(::Current) && ::Current.respond_to?(:request_id)
+          enriched[:request_id] = ::Current.request_id if ::Current.request_id.present?
+          enriched[:ip_address] ||= ::Current.ip_address if ::Current.respond_to?(:ip_address) && ::Current.ip_address.present?
+          enriched[:user_agent] ||= ::Current.user_agent if ::Current.respond_to?(:user_agent) && ::Current.user_agent.present?
+        end
+
+        enriched.merge(payload)
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/authorization_code_flow.rb

@@ -21,10 +21,20 @@ module StandardId
         end
 
         @authorization_code.mark_as_used!
+        emit_code_consumed
       end
 
       private
 
+      def emit_code_consumed
+        StandardId::Events.publish(
+          StandardId::Events::OAUTH_CODE_CONSUMED,
+          authorization_code: @authorization_code,
+          client_id: @credential.client_id,
+          account: @authorization_code.account
+        )
+      end
+
       def subject_id
         @authorization_code.account_id
       end

data/lib/standard_id/oauth/client_credentials_flow.rb

@@ -5,7 +5,12 @@ module StandardId
       permit_params :organization
 
       def authenticate!
+        emit_authentication_started
         @credential = validate_client_secret!(params[:client_id], params[:client_secret])
+        emit_authentication_succeeded
+      rescue StandardId::InvalidClientError => e
+        emit_authentication_failed(e.message)
+        raise
       end
 
       private
@@ -37,6 +42,32 @@ module StandardId
       def token_account
         nil
       end
+
+      def emit_authentication_started
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_ATTEMPT_STARTED,
+          account_lookup: params[:client_id],
+          auth_method: "client_credentials"
+        )
+      end
+
+      def emit_authentication_succeeded
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_SUCCEEDED,
+          client_application: @credential&.client_application,
+          auth_method: "client_credentials"
+        )
+      end
+
+      def emit_authentication_failed(error_message)
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_FAILED,
+          account_lookup: params[:client_id],
+          auth_method: "client_credentials",
+          error_code: "invalid_client",
+          error_message: error_message
+        )
+      end
     end
   end
 end

data/lib/standard_id/oauth/password_flow.rb

@@ -6,15 +6,47 @@ module StandardId
 
       def authenticate!
         validate_client_secret!(params[:client_id], params[:client_secret]) if params[:client_secret].present?
+        emit_authentication_started
 
         @account = authenticate_account(params[:username], params[:password])
-        raise StandardId::InvalidGrantError, "Invalid username or password" if @account.blank?
 
+        if @account.blank?
+          emit_authentication_failed
+          raise StandardId::InvalidGrantError, "Invalid username or password"
+        end
+
+        emit_password_validated
         validate_requested_scope!
       end
 
       private
 
+      def emit_authentication_started
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_ATTEMPT_STARTED,
+          account_lookup: params[:username],
+          auth_method: "password"
+        )
+      end
+
+      def emit_authentication_failed
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_FAILED,
+          account_lookup: params[:username],
+          auth_method: "password",
+          error_code: "invalid_credentials",
+          error_message: "Invalid username or password"
+        )
+      end
+
+      def emit_password_validated
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORD_VALIDATED,
+          account: @account,
+          credential_id: @credential&.id
+        )
+      end
+
       def subject_id
         @account.id
       end
@@ -40,11 +72,11 @@ module StandardId
       end
 
       def authenticate_account(username, password)
-        StandardId::PasswordCredential
+        @credential = StandardId::PasswordCredential
           .includes(credential: :account)
           .find_by(login: username)
-          &.authenticate(password)
-          &.account
+
+        @credential&.authenticate(password)&.account
       end
 
       def validate_requested_scope!

data/lib/standard_id/oauth/passwordless_otp_flow.rb

@@ -7,16 +7,52 @@ module StandardId
       def authenticate!
         validate_client_secret!(params[:client_id], params[:client_secret]) if params[:client_secret].present?
 
-        raise StandardId::InvalidGrantError, "Invalid or expired verification code" if code_challenge.blank?
-        raise StandardId::InvalidGrantError, "Unable to authenticate user" if account.blank?
+        if code_challenge.blank?
+          emit_otp_validation_failed
+          raise StandardId::InvalidGrantError, "Invalid or expired verification code"
+        end
+
+        if account.blank?
+          raise StandardId::InvalidGrantError, "Unable to authenticate user"
+        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

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

@@ -9,29 +9,18 @@ module StandardId
         private
 
         def social_provider_url
-          @social_provider_url ||= case params[:connection]
-          when "google"
-            build_google_oauth_url
-          when "apple"
-            build_apple_oauth_url
-          else
-            raise StandardId::InvalidRequestError, "Unsupported connection: #{params[:connection]}"
-          end
-        end
+          @social_provider_url ||= begin
+            connection = params[:connection]
+            provider = StandardId::ProviderRegistry.get(connection)
 
-        def build_google_oauth_url
-          StandardId::SocialProviders::Google.authorization_url(
-            state: encode_state_with_original_params,
-            redirect_uri: "#{params[:base_url]}/api/oauth/callback/google",
-            scope: "openid email profile"
-          )
-        end
-
-        def build_apple_oauth_url
-          StandardId::SocialProviders::Apple.authorization_url(
-            state: encode_state_with_original_params,
-            redirect_uri: "#{params[:base_url]}/api/oauth/callback/apple"
-          )
+            provider.authorization_url(
+              state: encode_state_with_original_params,
+              redirect_uri: "#{params[:base_url]}/api/oauth/callback/#{connection}",
+              scope: provider.default_scope
+            )
+          rescue StandardId::ProviderRegistry::ProviderNotFoundError => e
+            raise StandardId::InvalidRequestError, e.message
+          end
         end
 
         def encode_state_with_original_params

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -35,6 +35,7 @@ module StandardId
       end
 
       def generate_token_response
+        emit_token_issuing
         expires_in = token_expiry
         payload = build_jwt_payload(expires_in)
         access_token = StandardId::JwtService.encode(payload, expires_in: expires_in)
@@ -47,7 +48,7 @@ module StandardId
 
         response[:scope] = token_scope if token_scope.present?
         response[:refresh_token] = generate_refresh_token if supports_refresh_token?
-
+        emit_token_issued(expires_in)
         response.compact
       end
 
@@ -159,6 +160,26 @@ module StandardId
         filtered_context = StandardId::Utils::CallableParameterFilter.filter(resolver, claim_resolvers_context)
         resolver.call(**filtered_context)
       end
+
+      def emit_token_issuing
+        StandardId::Events.publish(
+          StandardId::Events::OAUTH_TOKEN_ISSUING,
+          grant_type: grant_type,
+          client_id: client_id,
+          account: token_account,
+          scope: token_scope
+        )
+      end
+
+      def emit_token_issued(expires_in)
+        StandardId::Events.publish(
+          StandardId::Events::OAUTH_TOKEN_ISSUED,
+          grant_type: grant_type,
+          client_id: client_id,
+          account: token_account,
+          expires_in: expires_in
+        )
+      end
     end
   end
 end

data/lib/standard_id/passwordless/base_strategy.rb

@@ -16,8 +16,11 @@ module StandardId
       def start!(attrs)
         username = attrs[:username]
         validate_username!(username)
+        emit_code_requested(username)
         challenge = create_challenge!(username)
+        emit_code_generated(challenge, username)
         sender_callback&.call(username, challenge.code)
+        emit_code_sent(username)
         challenge
       end
 
@@ -66,6 +69,35 @@ module StandardId
         # Implement in subclasses
         nil
       end
+
+      private
+
+      def emit_code_requested(username)
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_REQUESTED,
+          identifier: username,
+          channel: connection_type
+        )
+      end
+
+      def emit_code_generated(challenge, username)
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_GENERATED,
+          code_challenge: challenge,
+          identifier: username,
+          channel: connection_type,
+          expires_at: challenge.expires_at
+        )
+      end
+
+      def emit_code_sent(username)
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_SENT,
+          identifier: username,
+          channel: connection_type,
+          delivery_status: "sent"
+        )
+      end
     end
   end
 end

data/lib/standard_id/provider_registry.rb

@@ -0,0 +1,73 @@
+module StandardId
+  class ProviderRegistry
+    class ProviderNotFoundError < StandardError; end
+    class InvalidProviderError < StandardError; end
+
+    @providers = {}
+
+    class << self
+      # Register a provider
+      # @param name [Symbol, String] Provider identifier
+      # @param provider_class [Class] Provider implementation class
+      def register(name, provider_class)
+        validate_provider!(provider_class)
+        @providers[name.to_s] = provider_class
+        register_config_schema(provider_class)
+        provider_class.setup if provider_class.respond_to?(:setup)
+        provider_class
+      end
+
+      # Get provider by name
+      # @param name [Symbol, String] Provider identifier
+      # @return [Class] Provider class
+      # @raise [ProviderNotFoundError] if provider not found
+      def get(name)
+        @providers[name.to_s] || raise(
+          ProviderNotFoundError,
+          "Unknown provider: #{name}. Available providers: #{@providers.keys.join(', ')}"
+        )
+      end
+
+
+      # Get all registered providers
+      # @return [Hash] Provider name => class mapping
+      def all
+        @providers.dup
+      end
+
+      # Check if provider is registered
+      # @param name [Symbol, String] Provider identifier
+      # @return [Boolean]
+      def registered?(name)
+        @providers.key?(name.to_s)
+      end
+
+      private
+
+      # Register provider's config schema fields with StandardConfig
+      # @param provider_class [Class] Provider implementation class
+      def register_config_schema(provider_class)
+        schema = provider_class.config_schema
+        return if schema.nil? || schema.empty?
+
+        StandardConfig.schema.scope(:social) do
+          schema.each do |field_name, options|
+            field field_name, **options
+          end
+        end
+      end
+
+      def validate_provider!(provider_class)
+        unless provider_class.is_a?(Class)
+          raise InvalidProviderError,
+                "Provider must be a class, got #{provider_class.class.name}"
+        end
+
+        unless provider_class < StandardId::Providers::Base
+          raise InvalidProviderError,
+                "Provider #{provider_class.name} must inherit from StandardId::Providers::Base"
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/{social_providers → providers}/apple.rb

@@ -2,13 +2,11 @@ require "uri"
 require "net/http"
 require "json"
 require "jwt"
-require_relative "response_builder"
+require_relative "base"
 
 module StandardId
-  module SocialProviders
-    class Apple
-      include ResponseBuilder
-
+  module Providers
+    class Apple < Base
       ISSUER = "https://appleid.apple.com".freeze
       AUTH_ENDPOINT = "#{ISSUER}/auth/authorize".freeze
       TOKEN_ENDPOINT = "#{ISSUER}/auth/token".freeze
@@ -17,7 +15,14 @@ module StandardId
       DEFAULT_RESPONSE_MODE = "form_post".freeze
 
       class << self
-        def authorization_url(state:, redirect_uri:, scope: DEFAULT_SCOPE, response_mode: DEFAULT_RESPONSE_MODE)
+        def provider_name
+          "apple"
+        end
+
+        def authorization_url(state:, redirect_uri:, **options)
+          scope = options[:scope] || DEFAULT_SCOPE
+          response_mode = options[:response_mode] || DEFAULT_RESPONSE_MODE
+
           ensure_basic_credentials!
 
           query = {
@@ -32,7 +37,9 @@ module StandardId
           "#{AUTH_ENDPOINT}?#{URI.encode_www_form(query)}"
         end
 
-        def get_user_info(code: nil, id_token: nil, redirect_uri: nil, client_id: StandardId.config.apple_client_id)
+        def get_user_info(code: nil, id_token: nil, access_token: nil, redirect_uri: nil, **options)
+          client_id = options[:client_id] || StandardId.config.apple_client_id
+
           if id_token.present?
             build_response(
               verify_id_token(id_token: id_token, client_id: client_id),
@@ -45,6 +52,35 @@ module StandardId
           end
         end
 
+        def config_schema
+          {
+            apple_client_id: { type: :string, default: nil },
+            apple_mobile_client_id: { type: :string, default: nil },
+            apple_private_key: { type: :string, default: nil },
+            apple_key_id: { type: :string, default: nil },
+            apple_team_id: { type: :string, default: nil }
+          }
+        end
+
+        def default_scope
+          DEFAULT_SCOPE
+        end
+
+        def skip_csrf?
+          true
+        end
+
+        def supports_mobile_callback?
+          true
+        end
+
+        def resolve_params(params, context: {})
+          flow = context[:flow] || :web
+          client_id = flow == :mobile ? StandardId.config.apple_mobile_client_id : StandardId.config.apple_client_id
+
+          params.merge(client_id: client_id)
+        end
+
         def exchange_code_for_user_info(code:, redirect_uri:, client_id: StandardId.config.apple_client_id)
           ensure_full_credentials!(client_id: client_id)
           raise StandardId::InvalidRequestError, "Missing authorization code" if code.blank?
@@ -182,3 +218,6 @@ module StandardId
     end
   end
 end
+
+# Auto-register with the provider registry
+StandardId::ProviderRegistry.register(:apple, StandardId::Providers::Apple)