standard_id 0.1.5 → 0.1.7

data/lib/standard_id/providers/base.rb

@@ -0,0 +1,242 @@
+module StandardId
+  module Providers
+    # Base class for social login providers.
+    #
+    # All provider implementations (Google, Apple, GitHub, etc.) must inherit from this class
+    # and implement the required interface methods. This enables a plugin architecture where
+    # provider gems can be developed independently and registered with StandardId.
+    #
+    # @example Creating a custom provider
+    #   module StandardId
+    #     module Providers
+    #       class GitHub < Base
+    #         def self.provider_name
+    #           "github"
+    #         end
+    #
+    #         def self.authorization_url(state:, redirect_uri:, **options)
+    #           # Build and return GitHub OAuth authorization URL
+    #         end
+    #
+    #         def self.get_user_info(code: nil, id_token: nil, access_token: nil, redirect_uri: nil, **options)
+    #           # Exchange credentials for user info and return standardized response
+    #         end
+    #
+    #         def self.config_schema
+    #           {
+    #             github_client_id: { type: :string, default: nil },
+    #             github_client_secret: { type: :string, default: nil }
+    #           }
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    #   # Register the provider
+    #   StandardId::ProviderRegistry.register(:github, StandardId::Providers::GitHub)
+    #
+    class Base
+      class << self
+        # Provider identifier used for routing and configuration.
+        #
+        # @return [String] Unique provider name (e.g., "google", "apple", "github")
+        # @raise [NotImplementedError] if not overridden by subclass
+        #
+        # @example
+        #   StandardId::Providers::Google.provider_name #=> "google"
+        #
+        def provider_name
+          raise NotImplementedError, "#{name} must implement .provider_name"
+        end
+
+        # Generate OAuth authorization URL for redirecting users to the provider.
+        #
+        # @param state [String] OAuth state parameter (typically encoded with redirect + session info)
+        # @param redirect_uri [String] Callback URL where provider will redirect after authentication
+        # @param options [Hash] Provider-specific options (scope, prompt, response_mode, etc.)
+        # @return [String] Full authorization URL to redirect user to
+        # @raise [NotImplementedError] if not overridden by subclass
+        #
+        # @example
+        #   url = StandardId::Providers::Google.authorization_url(
+        #     state: "encoded_state_data",
+        #     redirect_uri: "https://app.example.com/auth/callback/google",
+        #     scope: "openid email profile"
+        #   )
+        #
+        def authorization_url(state:, redirect_uri:, **options)
+          raise NotImplementedError, "#{name} must implement .authorization_url"
+        end
+
+        # Exchange OAuth credentials for user information.
+        #
+        # Providers must support at least one of: authorization code, ID token, or access token.
+        # The method should validate the credentials with the provider and return standardized
+        # user information.
+        #
+        # @param code [String, nil] OAuth authorization code (web flow)
+        # @param id_token [String, nil] JWT ID token (mobile/implicit flow)
+        # @param access_token [String, nil] Access token (implicit flow)
+        # @param redirect_uri [String, nil] Original redirect_uri for code exchange validation
+        # @param options [Hash] Provider-specific options (client_id for Apple mobile, etc.)
+        # @return [HashWithIndifferentAccess] Standardized response with user_info and tokens
+        # @raise [NotImplementedError] if not overridden by subclass
+        # @raise [StandardId::InvalidRequestError] if credentials are missing or invalid
+        # @raise [StandardId::OAuthError] if provider returns an error
+        #
+        # @example Response format
+        #   {
+        #     user_info: {
+        #       "sub" => "unique_provider_user_id",
+        #       "email" => "user@example.com",
+        #       "email_verified" => true,
+        #       "name" => "Full Name",
+        #       # ... other provider-specific fields
+        #     },
+        #     tokens: {
+        #       id_token: "...",
+        #       access_token: "...",
+        #       refresh_token: "..."
+        #     }
+        #   }
+        #
+        def get_user_info(code: nil, id_token: nil, access_token: nil, redirect_uri: nil, **options)
+          raise NotImplementedError, "#{name} must implement .get_user_info"
+        end
+
+        # Define configuration schema fields for this provider.
+        #
+        # Returns a hash of field definitions compatible with StandardConfig schema DSL.
+        # These fields will be registered under the :social configuration scope.
+        #
+        # @return [Hash] Field definitions with types and defaults
+        #
+        # @example
+        #   def self.config_schema
+        #     {
+        #       github_client_id: { type: :string, default: nil },
+        #       github_client_secret: { type: :string, default: nil }
+        #     }
+        #   end
+        #
+        def config_schema
+          {}
+        end
+
+        # Resolve provider-specific parameters based on context.
+        #
+        # Override this method to customize parameters based on flow type,
+        # platform, or other contextual information. This allows providers
+        # to handle platform-specific requirements (e.g., Apple's different
+        # client IDs for web vs mobile).
+        #
+        # @param params [Hash] Base parameters from the controller
+        # @param context [Hash] Contextual information
+        # @option context [Symbol] :flow The authentication flow (:web or :mobile)
+        # @return [Hash] Modified parameters with provider-specific adjustments
+        #
+        # @example Apple provider overriding for mobile flow
+        #   def self.resolve_params(params, context: {})
+        #     if context[:flow] == :mobile
+        #       params.merge(client_id: StandardId.config.apple_mobile_client_id)
+        #     else
+        #       params
+        #     end
+        #   end
+        #
+        def resolve_params(params, context: {})
+          params
+        end
+
+        # Returns the callback path for this provider.
+        #
+        # Used to build the OAuth redirect URI. Uses the engine's route helpers
+        # to respect the mount path.
+        #
+        # @return [String] The callback path (respects engine mount path)
+        #
+        # @example Engine mounted at "/"
+        #   StandardId::Providers::Google.callback_path #=> "/auth/callback/google"
+        #
+        # @example Engine mounted at "/identity"
+        #   StandardId::Providers::Google.callback_path #=> "/identity/auth/callback/google"
+        #
+        def callback_path
+          StandardId::WebEngine.routes.url_helpers.auth_callback_provider_path(provider: provider_name)
+        end
+
+        # Returns the default OAuth scope for this provider.
+        #
+        # Can be overridden by passing :scope in authorization_url options.
+        # Returns nil by default, letting the provider use its own default.
+        #
+        # @return [String, nil] Default scope string
+        #
+        # @example
+        #   StandardId::Providers::Google.default_scope #=> "openid email profile"
+        #
+        def default_scope
+          nil
+        end
+
+        # Whether to skip CSRF verification for web callbacks.
+        #
+        # Some providers (like Apple) use POST callbacks which require
+        # CSRF verification to be skipped. Override this method to return
+        # true if your provider uses POST callbacks.
+        #
+        # @return [Boolean] true to skip CSRF verification
+        #
+        # @example Apple provider (POST callback)
+        #   def self.skip_csrf?
+        #     true
+        #   end
+        #
+        def skip_csrf?
+          false
+        end
+
+        # Whether this provider supports mobile callback flow.
+        #
+        # Mobile callbacks are used when native apps (especially Android)
+        # need a server-side redirect back to the app after OAuth.
+        # For example, Apple Sign In on Android uses a web-based flow
+        # that requires the server to redirect back to the app.
+        #
+        # @return [Boolean] true if provider supports mobile callback
+        #
+        def supports_mobile_callback?
+          false
+        end
+
+        # Optional setup hook called when provider is registered.
+        #
+        # Override this method to perform initialization tasks like:
+        # - Registering additional routes
+        # - Adding custom validations
+        # - Setting up caching for JWKS
+        #
+        # @return [void]
+        #
+        def setup
+          # Override in subclasses if needed
+        end
+
+        protected
+
+        # Helper to build standardized response format.
+        #
+        # @param user_info [Hash] User information from provider
+        # @param tokens [Hash] OAuth tokens (id_token, access_token, refresh_token)
+        # @return [HashWithIndifferentAccess] Standardized response
+        #
+        def build_response(user_info, tokens: {})
+          {
+            user_info: user_info,
+            tokens: tokens.compact
+          }.with_indifferent_access
+        end
+      end
+    end
+  end
+end

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

@@ -1,10 +1,8 @@
-require_relative "response_builder"
+require_relative "base"
 
 module StandardId
-  module SocialProviders
-    class Google
-      include ResponseBuilder
-
+  module Providers
+    class Google < Base
       AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth".freeze
       TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token".freeze
       USERINFO_ENDPOINT = "https://www.googleapis.com/oauth2/v2/userinfo".freeze
@@ -12,7 +10,14 @@ module StandardId
       DEFAULT_SCOPE = "openid email profile".freeze
 
       class << self
-        def authorization_url(state:, redirect_uri:, scope: DEFAULT_SCOPE, prompt: nil)
+        def provider_name
+          "google"
+        end
+
+        def authorization_url(state:, redirect_uri:, **options)
+          scope = options[:scope] || DEFAULT_SCOPE
+          prompt = options[:prompt]
+
           query = {
             client_id: credentials[:client_id],
             redirect_uri: redirect_uri,
@@ -26,7 +31,7 @@ module StandardId
           "#{AUTH_ENDPOINT}?#{URI.encode_www_form(query)}"
         end
 
-        def get_user_info(code: nil, id_token: nil, access_token: nil, redirect_uri: nil)
+        def get_user_info(code: nil, id_token: nil, access_token: nil, redirect_uri: nil, **options)
           if id_token.present?
             build_response(
               verify_id_token(id_token: id_token),
@@ -44,6 +49,17 @@ module StandardId
           end
         end
 
+        def config_schema
+          {
+            google_client_id: { type: :string, default: nil },
+            google_client_secret: { type: :string, default: nil }
+          }
+        end
+
+        def default_scope
+          DEFAULT_SCOPE
+        end
+
         def exchange_code_for_user_info(code:, redirect_uri:)
           raise StandardId::InvalidRequestError, "Missing authorization code" if code.blank?
 
@@ -166,3 +182,6 @@ module StandardId
     end
   end
 end
+
+# Auto-register with the provider registry
+StandardId::ProviderRegistry.register(:google, StandardId::Providers::Google)

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/standard_id/web/authentication_guard.rb

@@ -5,10 +5,12 @@ module StandardId
         session[:return_to_after_authenticating] = request.url
 
         browser_session = session_manager.current_session
+        emit_session_validating(browser_session, request)
 
         if browser_session.blank?
           raise StandardId::NotAuthenticatedError
         elsif browser_session.expired?
+          emit_session_expired(browser_session)
           session_manager.clear_session!
           raise StandardId::ExpiredSessionError
         elsif browser_session.revoked?
@@ -16,8 +18,35 @@ module StandardId
           raise StandardId::RevokedSessionError
         end
 
+        emit_session_validated(browser_session)
         browser_session
       end
+
+      private
+
+      def emit_session_validating(browser_session, request)
+        StandardId::Events.publish(
+          StandardId::Events::SESSION_VALIDATING,
+          session: browser_session
+        )
+      end
+
+      def emit_session_validated(browser_session)
+        StandardId::Events.publish(
+          StandardId::Events::SESSION_VALIDATED,
+          session: browser_session,
+          account: browser_session.account
+        )
+      end
+
+      def emit_session_expired(browser_session)
+        StandardId::Events.publish(
+          StandardId::Events::SESSION_EXPIRED,
+          session: browser_session,
+          account: browser_session.account,
+          expired_at: browser_session.expires_at
+        )
+      end
     end
   end
 end

data/lib/standard_id/web/session_manager.rb

@@ -19,9 +19,11 @@ module StandardId
       end
 
       def sign_in_account(account)
+        emit_session_creating(account, "browser")
         token_manager.create_browser_session(account).tap do |browser_session|
           session[:session_token] = browser_session.token
           Current.session = browser_session
+          emit_session_created(browser_session, account, "browser")
         end
       end
 
@@ -48,7 +50,16 @@ module StandardId
         Current.session ||= load_session_from_session_token
         Current.session ||= load_session_from_remember_token
 
-        clear_session! if Current.session.blank? || Current.session.expired? || Current.session.revoked?
+        if Current.session.present?
+          if Current.session.expired?
+            emit_session_expired(Current.session)
+            clear_session!
+          elsif Current.session.revoked?
+            clear_session!
+          end
+        else
+          clear_session!
+        end
 
         Current.session
       end
@@ -66,6 +77,33 @@ module StandardId
           cookies[:remember_token] = token_manager.create_remember_token(password_credential)
         end
       end
+
+      def emit_session_creating(account, session_type)
+        StandardId::Events.publish(
+          StandardId::Events::SESSION_CREATING,
+          account: account,
+          session_type: session_type
+        )
+      end
+
+      def emit_session_created(browser_session, account, session_type)
+        StandardId::Events.publish(
+          StandardId::Events::SESSION_CREATED,
+          session: browser_session,
+          account: account,
+          session_type: session_type,
+          token_issued: true
+        )
+      end
+
+      def emit_session_expired(browser_session)
+        StandardId::Events.publish(
+          StandardId::Events::SESSION_EXPIRED,
+          session: browser_session,
+          account: browser_session.account,
+          expired_at: browser_session.expires_at
+        )
+      end
     end
   end
 end

data/lib/standard_id/web/token_manager.rb

@@ -12,14 +12,14 @@ module StandardId
           account: account,
           ip_address: request.remote_ip,
           user_agent: request.user_agent,
-          expires_at: 24.hours.from_now # TODO: make configurable
+          expires_at: StandardId::BrowserSession.expiry
         )
       end
 
       def create_remember_token(password_credential)
         {
           value: password_credential.generate_token_for(:remember_me),
-          expires: 30.days.from_now, # TODO: make configurable
+          expires: StandardId::BrowserSession.remember_me_expiry,
           httponly: true,
           secure: request.ssl?,
           same_site: :lax

data/lib/standard_id.rb

@@ -1,9 +1,17 @@
 require "standard_id/version"
+require "standard_id/current_attributes"
 require "standard_id/engine"
 require "standard_id/web_engine"
 require "standard_id/api_engine"
 require "standard_id/config/schema"
 require "standard_id/errors"
+require "standard_id/events"
+require "standard_id/events/subscribers/base"
+require "standard_id/events/subscribers/logging_subscriber"
+require "standard_id/events/subscribers/account_status_subscriber"
+require "standard_id/events/subscribers/account_locking_subscriber"
+require "standard_id/account_status"
+require "standard_id/account_locking"
 require "standard_id/http_client"
 require "standard_id/jwt_service"
 require "standard_id/web/session_manager"
@@ -31,8 +39,11 @@ require "standard_id/passwordless/base_strategy"
 require "standard_id/passwordless/email_strategy"
 require "standard_id/passwordless/sms_strategy"
 require "standard_id/utils/callable_parameter_filter"
-require "standard_id/social_providers/google"
-require "standard_id/social_providers/apple"
+
+require "standard_id/providers/base"
+require "standard_id/provider_registry"
+require "standard_id/providers/google"
+require "standard_id/providers/apple"
 
 module StandardId
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Jaryl Sim
@@ -65,6 +65,9 @@ files:
 - Rakefile
 - app/assets/stylesheets/standard_id/application.css
 - app/controllers/concerns/standard_id/api_authentication.rb
+- app/controllers/concerns/standard_id/inertia_rendering.rb
+- app/controllers/concerns/standard_id/inertia_support.rb
+- app/controllers/concerns/standard_id/set_current_request_details.rb
 - app/controllers/concerns/standard_id/social_authentication.rb
 - app/controllers/concerns/standard_id/web_authentication.rb
 - app/controllers/standard_id/api/authorization_controller.rb
@@ -115,7 +118,7 @@ files:
 - app/models/standard_id/username_identifier.rb
 - app/views/standard_id/web/account/edit.html.erb
 - app/views/standard_id/web/account/show.html.erb
-- app/views/standard_id/web/auth/callback/providers/apple_mobile.html.erb
+- app/views/standard_id/web/auth/callback/providers/mobile_callback.html.erb
 - app/views/standard_id/web/login/show.html.erb
 - app/views/standard_id/web/reset_password/confirm/show.html.erb
 - app/views/standard_id/web/reset_password/start/show.html.erb
@@ -141,13 +144,23 @@ files:
 - lib/standard_config/manager.rb
 - lib/standard_config/schema.rb
 - lib/standard_id.rb
+- lib/standard_id/account_locking.rb
+- lib/standard_id/account_status.rb
 - lib/standard_id/api/authentication_guard.rb
 - lib/standard_id/api/session_manager.rb
 - lib/standard_id/api/token_manager.rb
 - lib/standard_id/api_engine.rb
 - lib/standard_id/config/schema.rb
+- lib/standard_id/current_attributes.rb
 - lib/standard_id/engine.rb
 - lib/standard_id/errors.rb
+- lib/standard_id/events.rb
+- lib/standard_id/events/definitions.rb
+- lib/standard_id/events/event.rb
+- lib/standard_id/events/subscribers/account_locking_subscriber.rb
+- lib/standard_id/events/subscribers/account_status_subscriber.rb
+- lib/standard_id/events/subscribers/base.rb
+- lib/standard_id/events/subscribers/logging_subscriber.rb
 - lib/standard_id/http_client.rb
 - lib/standard_id/jwt_service.rb
 - lib/standard_id/oauth/authorization_code_authorization_flow.rb
@@ -168,9 +181,10 @@ files:
 - lib/standard_id/passwordless/base_strategy.rb
 - lib/standard_id/passwordless/email_strategy.rb
 - lib/standard_id/passwordless/sms_strategy.rb
-- lib/standard_id/social_providers/apple.rb
-- lib/standard_id/social_providers/google.rb
-- lib/standard_id/social_providers/response_builder.rb
+- lib/standard_id/provider_registry.rb
+- lib/standard_id/providers/apple.rb
+- lib/standard_id/providers/base.rb
+- lib/standard_id/providers/google.rb
 - lib/standard_id/utils/callable_parameter_filter.rb
 - lib/standard_id/version.rb
 - lib/standard_id/web/authentication_guard.rb
@@ -192,7 +206,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/standard_id/social_providers/response_builder.rb

@@ -1,18 +0,0 @@
-require "active_support/concern"
-
-module StandardId
-  module SocialProviders
-    module ResponseBuilder
-      extend ActiveSupport::Concern
-
-      class_methods do
-        def build_response(user_info, tokens: {})
-          {
-            user_info: user_info,
-            tokens: tokens.compact
-          }.with_indifferent_access
-        end
-      end
-    end
-  end
-end