standard_id 0.1.5 → 0.1.7

data/lib/standard_id/events/definitions.rb

@@ -0,0 +1,157 @@
+module StandardId
+  module Events
+    module Definitions
+      AUTHENTICATION_ATTEMPT_STARTED = "authentication.attempt.started"
+      AUTHENTICATION_SUCCEEDED = "authentication.attempt.succeeded"
+      AUTHENTICATION_FAILED = "authentication.attempt.failed"
+      PASSWORD_VALIDATED = "authentication.password.validated"
+      PASSWORD_VALIDATION_FAILED = "authentication.password.failed"
+      OTP_VALIDATED = "authentication.otp.validated"
+      OTP_VALIDATION_FAILED = "authentication.otp.failed"
+
+      SESSION_CREATING = "session.creating"
+      SESSION_CREATED = "session.created"
+      SESSION_VALIDATING = "session.validating"
+      SESSION_VALIDATED = "session.validated"
+      SESSION_EXPIRED = "session.expired"
+      SESSION_REVOKED = "session.revoked"
+      SESSION_REFRESHED = "session.refreshed"
+
+      ACCOUNT_CREATING = "account.creating"
+      ACCOUNT_CREATED = "account.created"
+      ACCOUNT_VERIFIED = "account.verified"
+      ACCOUNT_STATUS_CHANGED = "account.status_changed"
+      ACCOUNT_ACTIVATED = "account.activated"
+      ACCOUNT_DEACTIVATED = "account.deactivated"
+      ACCOUNT_LOCKED = "account.locked"
+      ACCOUNT_UNLOCKED = "account.unlocked"
+
+      IDENTIFIER_CREATED = "identifier.created"
+      IDENTIFIER_VERIFICATION_STARTED = "identifier.verification.started"
+      IDENTIFIER_VERIFICATION_SUCCEEDED = "identifier.verification.succeeded"
+      IDENTIFIER_VERIFICATION_FAILED = "identifier.verification.failed"
+      IDENTIFIER_LINKED = "identifier.linked"
+
+      OAUTH_AUTHORIZATION_REQUESTED = "oauth.authorization.requested"
+      OAUTH_AUTHORIZATION_GRANTED = "oauth.authorization.granted"
+      OAUTH_AUTHORIZATION_DENIED = "oauth.authorization.denied"
+      OAUTH_TOKEN_ISSUING = "oauth.token.issuing"
+      OAUTH_TOKEN_ISSUED = "oauth.token.issued"
+      OAUTH_TOKEN_REFRESHED = "oauth.token.refreshed"
+      OAUTH_CODE_CONSUMED = "oauth.code.consumed"
+
+      PASSWORDLESS_CODE_REQUESTED = "passwordless.code.requested"
+      PASSWORDLESS_CODE_GENERATED = "passwordless.code.generated"
+      PASSWORDLESS_CODE_SENT = "passwordless.code.sent"
+      PASSWORDLESS_CODE_VERIFIED = "passwordless.code.verified"
+      PASSWORDLESS_CODE_FAILED = "passwordless.code.failed"
+      PASSWORDLESS_ACCOUNT_CREATED = "passwordless.account.created"
+
+      SOCIAL_AUTH_STARTED = "social.auth.started"
+      SOCIAL_CALLBACK_RECEIVED = "social.auth.callback_received"
+      SOCIAL_USER_INFO_FETCHED = "social.user_info.fetched"
+      SOCIAL_ACCOUNT_CREATED = "social.account.created"
+      SOCIAL_ACCOUNT_LINKED = "social.account.linked"
+      SOCIAL_AUTH_COMPLETED = "social.auth.completed"
+
+      CREDENTIAL_PASSWORD_CREATED = "credential.password.created"
+      CREDENTIAL_PASSWORD_RESET_INITIATED = "credential.password.reset_initiated"
+      CREDENTIAL_PASSWORD_RESET_COMPLETED = "credential.password.reset_completed"
+      CREDENTIAL_PASSWORD_CHANGED = "credential.password.changed"
+      CREDENTIAL_CLIENT_SECRET_CREATED = "credential.client_secret.created"
+      CREDENTIAL_CLIENT_SECRET_ROTATED = "credential.client_secret.rotated"
+      CREDENTIAL_CLIENT_SECRET_REVOKED = "credential.client_secret.revoked"
+
+      AUTHENTICATION_EVENTS = [
+        AUTHENTICATION_ATTEMPT_STARTED,
+        AUTHENTICATION_SUCCEEDED,
+        AUTHENTICATION_FAILED,
+        PASSWORD_VALIDATED,
+        PASSWORD_VALIDATION_FAILED,
+        OTP_VALIDATED,
+        OTP_VALIDATION_FAILED
+      ].freeze
+
+      SESSION_EVENTS = [
+        SESSION_CREATING,
+        SESSION_CREATED,
+        SESSION_VALIDATING,
+        SESSION_VALIDATED,
+        SESSION_EXPIRED,
+        SESSION_REVOKED,
+        SESSION_REFRESHED
+      ].freeze
+
+      ACCOUNT_EVENTS = [
+        ACCOUNT_CREATING,
+        ACCOUNT_CREATED,
+        ACCOUNT_VERIFIED,
+        ACCOUNT_STATUS_CHANGED,
+        ACCOUNT_ACTIVATED,
+        ACCOUNT_DEACTIVATED,
+        ACCOUNT_LOCKED,
+        ACCOUNT_UNLOCKED
+      ].freeze
+
+      IDENTIFIER_EVENTS = [
+        IDENTIFIER_CREATED,
+        IDENTIFIER_VERIFICATION_STARTED,
+        IDENTIFIER_VERIFICATION_SUCCEEDED,
+        IDENTIFIER_VERIFICATION_FAILED,
+        IDENTIFIER_LINKED
+      ].freeze
+
+      OAUTH_EVENTS = [
+        OAUTH_AUTHORIZATION_REQUESTED,
+        OAUTH_AUTHORIZATION_GRANTED,
+        OAUTH_AUTHORIZATION_DENIED,
+        OAUTH_TOKEN_ISSUING,
+        OAUTH_TOKEN_ISSUED,
+        OAUTH_TOKEN_REFRESHED,
+        OAUTH_CODE_CONSUMED
+      ].freeze
+
+      PASSWORDLESS_EVENTS = [
+        PASSWORDLESS_CODE_REQUESTED,
+        PASSWORDLESS_CODE_GENERATED,
+        PASSWORDLESS_CODE_SENT,
+        PASSWORDLESS_CODE_VERIFIED,
+        PASSWORDLESS_CODE_FAILED,
+        PASSWORDLESS_ACCOUNT_CREATED
+      ].freeze
+
+      SOCIAL_EVENTS = [
+        SOCIAL_AUTH_STARTED,
+        SOCIAL_CALLBACK_RECEIVED,
+        SOCIAL_USER_INFO_FETCHED,
+        SOCIAL_ACCOUNT_CREATED,
+        SOCIAL_ACCOUNT_LINKED,
+        SOCIAL_AUTH_COMPLETED
+      ].freeze
+
+      CREDENTIAL_EVENTS = [
+        CREDENTIAL_PASSWORD_CREATED,
+        CREDENTIAL_PASSWORD_RESET_INITIATED,
+        CREDENTIAL_PASSWORD_RESET_COMPLETED,
+        CREDENTIAL_PASSWORD_CHANGED,
+        CREDENTIAL_CLIENT_SECRET_CREATED,
+        CREDENTIAL_CLIENT_SECRET_ROTATED,
+        CREDENTIAL_CLIENT_SECRET_REVOKED
+      ].freeze
+
+      ALL_EVENTS = (
+        AUTHENTICATION_EVENTS +
+        SESSION_EVENTS +
+        ACCOUNT_EVENTS +
+        IDENTIFIER_EVENTS +
+        OAUTH_EVENTS +
+        PASSWORDLESS_EVENTS +
+        SOCIAL_EVENTS +
+        CREDENTIAL_EVENTS
+      ).freeze
+    end
+
+    # Include definitions at module level for convenience
+    include Definitions
+  end
+end

data/lib/standard_id/events/event.rb

@@ -0,0 +1,123 @@
+module StandardId
+  module Events
+    # Event object that wraps ActiveSupport::Notifications event data
+    #
+    # Provides a clean interface for accessing event information in subscribers.
+    #
+    # @attr_reader [String] name The full namespaced event name
+    # @attr_reader [Hash] payload The event payload data
+    # @attr_reader [Time] started_at When the event started
+    # @attr_reader [Time] finished_at When the event finished
+    # @attr_reader [String] transaction_id Unique identifier for this event instance
+    #
+    class Event
+      attr_reader :name, :payload, :started_at, :finished_at, :transaction_id
+
+      # @param name [String] The full namespaced event name
+      # @param payload [Hash] The event payload
+      # @param started_at [Time] When the event started
+      # @param finished_at [Time] When the event finished
+      # @param transaction_id [String] Unique identifier for the event
+      def initialize(name:, payload:, started_at: nil, finished_at: nil, transaction_id: nil)
+        @name = name
+        @payload = payload.with_indifferent_access
+        @started_at = started_at
+        @finished_at = finished_at
+        @transaction_id = transaction_id
+      end
+
+      # Get the event name without the namespace prefix
+      #
+      # @return [String] The short event name
+      # @example
+      #   event.short_name # => "authentication.attempt.succeeded"
+      #
+      def short_name
+        name.to_s.delete_prefix("#{Events::NAMESPACE}.")
+      end
+
+      # Get the event type from the payload
+      #
+      # @return [String, nil] The event type
+      #
+      def event_type
+        payload[:event_type]
+      end
+
+      # Get the unique event ID
+      #
+      # @return [String, nil] The event UUID
+      #
+      def event_id
+        payload[:event_id]
+      end
+
+      # Get the event timestamp
+      #
+      # @return [String, nil] ISO8601 formatted timestamp
+      #
+      def timestamp
+        payload[:timestamp]
+      end
+
+      # Calculate the duration of the event in milliseconds
+      #
+      # @return [Float, nil] Duration in milliseconds, or nil if timing not available
+      #
+      def duration_ms
+        return nil unless started_at && finished_at
+        (finished_at - started_at) * 1000
+      end
+
+      # Convenience method to access payload values
+      #
+      # @param key [Symbol, String] The payload key
+      # @return [Object] The value from the payload
+      #
+      def [](key)
+        payload[key]
+      end
+
+      # Check if the payload contains a key
+      #
+      # @param key [Symbol, String] The payload key
+      # @return [Boolean]
+      #
+      def key?(key)
+        payload.key?(key)
+      end
+
+      # Convert event to a hash representation
+      #
+      # @return [Hash] The event as a hash
+      #
+      def to_h
+        {
+          name: name,
+          short_name: short_name,
+          transaction_id: transaction_id,
+          started_at: started_at&.iso8601,
+          finished_at: finished_at&.iso8601,
+          duration_ms: duration_ms,
+          payload: payload.to_h
+        }
+      end
+
+      # Convert event to JSON
+      #
+      # @return [String] JSON representation
+      #
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # String representation for debugging
+      #
+      # @return [String]
+      #
+      def inspect
+        "#<#{self.class.name} name=#{name} event_id=#{event_id} duration_ms=#{duration_ms}>"
+      end
+    end
+  end
+end

data/lib/standard_id/events/subscribers/account_locking_subscriber.rb

@@ -0,0 +1,17 @@
+module StandardId
+  module Events
+    module Subscribers
+      class AccountLockingSubscriber < Base
+        subscribe_to StandardId::Events::ACCOUNT_LOCKED
+
+        def call(event)
+          account = event[:account]
+          active_sessions = account.sessions.active
+          active_sessions.find_each do |session|
+            session.revoke!(reason: "account_locked")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/events/subscribers/account_status_subscriber.rb

@@ -0,0 +1,17 @@
+module StandardId
+  module Events
+    module Subscribers
+      class AccountStatusSubscriber < Base
+        subscribe_to StandardId::Events::ACCOUNT_DEACTIVATED
+
+        def call(event)
+          account = event[:account]
+          active_sessions = account.sessions.active
+          active_sessions.find_each do |session|
+            session.revoke!(reason: "account_deactivated")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/events/subscribers/base.rb

@@ -0,0 +1,165 @@
+module StandardId
+  module Events
+    module Subscribers
+      # Base class for event subscribers
+      #
+      # @example Single event subscription
+      #   class AuditSubscriber < StandardId::Events::Subscribers::Base
+      #     subscribe_to StandardId::Events::AUTHENTICATION_SUCCEEDED
+      #
+      #     def call(event)
+      #       AuditLog.create!(
+      #         event_type: event.short_name,
+      #         account_id: event[:account]&.id,
+      #         ip_address: event[:ip_address],
+      #         metadata: event.payload
+      #       )
+      #     end
+      #   end
+      #
+      # @example Multiple event subscription
+      #   class SecurityAlertSubscriber < StandardId::Events::Subscribers::Base
+      #     subscribe_to StandardId::Events::AUTHENTICATION_FAILED,
+      #                  StandardId::Events::SESSION_REVOKED,
+      #                  StandardId::Events::ACCOUNT_LOCKED
+      #
+      #     def call(event)
+      #       SecurityMailer.alert(event.to_h).deliver_later
+      #     end
+      #   end
+      #
+      # @example Pattern subscription
+      #   class MetricsSubscriber < StandardId::Events::Subscribers::Base
+      #     subscribe_to_pattern(/authentication/)
+      #
+      #     def call(event)
+      #       StatsD.increment("standard_id.#{event.short_name}")
+      #     end
+      #   end
+      #
+      class Base
+        class << self
+          # Subscribe to specific event(s)
+          #
+          # @param event_names [Array<String>] Event name constants
+          # @return [void]
+          #
+          def subscribe_to(*event_names)
+            @subscribed_events = event_names.flatten
+          end
+
+          # Subscribe to events matching a pattern
+          #
+          # @param pattern [Regexp] Pattern to match event names
+          # @return [void]
+          #
+          def subscribe_to_pattern(pattern)
+            @subscription_pattern = pattern
+          end
+
+          # Get the subscribed events
+          #
+          # @return [Array<String>]
+          #
+          def subscribed_events
+            @subscribed_events || []
+          end
+
+          # Get the subscription pattern
+          #
+          # @return [Regexp, nil]
+          #
+          def subscription_pattern
+            @subscription_pattern
+          end
+
+          # Register this subscriber with the event system
+          #
+          # @return [Array<Object>] The subscription handles
+          #
+          def attach
+            instance = new
+            @subscriptions ||= []
+
+            if subscription_pattern
+              @subscriptions << Events.subscribe(subscription_pattern) do |event|
+                instance.handle(event)
+              end
+            end
+
+            subscribed_events.each do |event_name|
+              @subscriptions << Events.subscribe(event_name) do |event|
+                instance.handle(event)
+              end
+            end
+
+            @subscriptions
+          end
+
+          # Unregister this subscriber from the event system
+          #
+          # @return [void]
+          #
+          def detach
+            return unless @subscriptions
+
+            @subscriptions.each do |subscription|
+              Events.unsubscribe(subscription)
+            end
+            @subscriptions = []
+          end
+
+          # Check if the subscriber is currently attached
+          #
+          # @return [Boolean]
+          #
+          def attached?
+            @subscriptions&.any?
+          end
+        end
+
+        # Handle an event
+        #
+        # Override this method to add custom handling logic like
+        # async processing or error handling. By default, it calls
+        # the `call` method.
+        #
+        # @param event [StandardId::Events::Event] The event to handle
+        # @return [void]
+        #
+        def handle(event)
+          call(event)
+        rescue StandardError => e
+          handle_error(e, event)
+        end
+
+        # Process the event
+        #
+        # Subclasses must implement this method.
+        #
+        # @param event [StandardId::Events::Event] The event to process
+        # @raise [NotImplementedError] If not implemented by subclass
+        #
+        def call(event)
+          raise NotImplementedError, "#{self.class.name} must implement #call"
+        end
+
+        # Handle errors during event processing
+        #
+        # Override this method to customize error handling.
+        # By default, it logs the error and re-raises.
+        #
+        # @param error [StandardError] The error that occurred
+        # @param event [StandardId::Events::Event] The event being processed
+        # @raise [StandardError] Re-raises the error by default
+        #
+        def handle_error(error, event)
+          StandardId.logger.error(
+            "[StandardId::Events] Error in #{self.class.name} handling #{event.short_name}: #{error.message}"
+          )
+          raise error
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/events/subscribers/logging_subscriber.rb

@@ -0,0 +1,122 @@
+module StandardId
+  module Events
+    module Subscribers
+      class LoggingSubscriber < Base
+        subscribe_to_pattern(/\Astandard_id\./)
+
+        LOG_LEVELS = {
+          "authentication.attempt.started" => :debug,
+          "authentication.attempt.succeeded" => :info,
+          "authentication.attempt.failed" => :warn,
+          "authentication.password.validated" => :debug,
+          "authentication.password.failed" => :warn,
+          "authentication.otp.validated" => :debug,
+          "authentication.otp.failed" => :warn,
+          "session.creating" => :debug,
+          "session.created" => :info,
+          "session.validating" => :debug,
+          "session.validated" => :debug,
+          "session.expired" => :info,
+          "session.revoked" => :info,
+          "session.refreshed" => :debug,
+          "account.creating" => :debug,
+          "account.created" => :info,
+          "account.verified" => :info,
+          "account.status_changed" => :warn,
+          "account.activated" => :info,
+          "account.deactivated" => :warn,
+          "account.locked" => :warn,
+          "account.unlocked" => :info,
+          "identifier.created" => :debug,
+          "identifier.verification.started" => :debug,
+          "identifier.verification.succeeded" => :info,
+          "identifier.verification.failed" => :warn,
+          "identifier.linked" => :info,
+          "oauth.authorization.requested" => :debug,
+          "oauth.authorization.granted" => :info,
+          "oauth.authorization.denied" => :info,
+          "oauth.token.issuing" => :debug,
+          "oauth.token.issued" => :info,
+          "oauth.token.refreshed" => :debug,
+          "oauth.code.consumed" => :debug,
+          "passwordless.code.requested" => :debug,
+          "passwordless.code.generated" => :debug,
+          "passwordless.code.sent" => :info,
+          "passwordless.code.verified" => :info,
+          "passwordless.code.failed" => :warn,
+          "passwordless.account.created" => :info,
+          "social.auth.started" => :debug,
+          "social.auth.callback_received" => :debug,
+          "social.user_info.fetched" => :debug,
+          "social.account.created" => :info,
+          "social.account.linked" => :info,
+          "social.auth.completed" => :info,
+          "credential.password.created" => :info,
+          "credential.password.reset_initiated" => :info,
+          "credential.password.reset_completed" => :info,
+          "credential.password.changed" => :info,
+          "credential.client_secret.created" => :info,
+          "credential.client_secret.rotated" => :warn
+        }.freeze
+
+        DEFAULT_LOG_LEVEL = :debug
+
+        def call(event)
+          return unless logging_enabled?
+
+          log_level = LOG_LEVELS.fetch(event.short_name, DEFAULT_LOG_LEVEL)
+          payload = build_payload(event, log_level)
+
+          case log_level
+          when :debug then StandardId.logger.debug(payload)
+          when :info  then StandardId.logger.info(payload)
+          when :warn  then StandardId.logger.warn(payload)
+          when :error then StandardId.logger.error(payload)
+          end
+        end
+
+        def handle_error(error, event)
+          StandardId.logger.error({
+            subject: "standard_id.logging_subscriber.error",
+            event_type: event.short_name,
+            error: error.message
+          })
+        end
+
+        private
+
+        def logging_enabled?
+          config = StandardId.config
+          return true unless config.respond_to?(:events)
+
+          config.events.enable_logging
+        end
+
+        def build_payload(event, log_level)
+          payload = {
+            subject: "standard_id.#{event.short_name}",
+            severity: log_level.to_s
+          }
+
+          payload[:duration] = event.duration_ms.round(2) if event.duration_ms
+
+          if (account = event[:account])
+            payload[:account_id] = account.respond_to?(:id) ? account.id : account
+          elsif event[:account_id]
+            payload[:account_id] = event[:account_id]
+          end
+
+          payload[:login] = event[:account_lookup] || event[:login] || event[:username] if event[:account_lookup] || event[:login] || event[:username]
+          payload[:auth_method] = event[:auth_method] if event[:auth_method]
+          payload[:grant_type] = event[:grant_type] if event[:grant_type]
+          payload[:provider] = event[:provider] if event[:provider]
+          payload[:session_type] = event[:session_type] if event[:session_type]
+          payload[:ip_address] = event[:ip_address] if event[:ip_address]
+          payload[:error_code] = event[:error_code] if event[:error_code]
+
+          payload
+        end
+      end
+    end
+  end
+end