standard_id 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74492c7c108bb4188cb94b9bd1d35437b6957e92ae8a7066b182bcbda9a697d8
-  data.tar.gz: 504fab0ff0fbc628c6369743a10729541fb737c8d33c1eabd4fb992453b3e173
+  metadata.gz: 90019539f1e0cc2c3fee8e641ff0b18a337bd1b263aa78441b3c886bde6b72d4
+  data.tar.gz: a98746c6be195bf842304c07bcb6276f8f95031be8c83b349ce902185874e248
 SHA512:
-  metadata.gz: 00ba9d5328bc4811d6b30c2801779a44ded02010f30932854d85aac312f3e7cf78149169a6fab1e1e78d433e3b90e2d0b5ae701d3d2cd6c9f83bd68527a95065
-  data.tar.gz: 3f5eade22b06b4f8eef090602af59d61ef0e3a7b3ca7dfb5f942b4e65bedd54992569bab0b8ceb181a9319fae76e011721e71d7fe8186be2822cbdeb6e593d1b
+  metadata.gz: 85558657315f76bfbdb3d05638cb7280805e2f329dca42dc99f0c0a2e2fd99bcd0ce6d0ffa4289138d13ac89207276fd9c0d75dd52336e8538c12dcfcbcd8164
+  data.tar.gz: 707fb170fee01dae20abd78a62ba67c9f9d6a2135ed6ddad02610f1194b89c41e9cef62f12a8c2358931b66c21aa66952cfaaccb2b0d36bd60f7269fbf6b7493

data/app/controllers/concerns/standard_id/lifecycle_hooks.rb

@@ -1,24 +1,80 @@
 module StandardId
+  # Public concern providing authentication lifecycle hook invocations.
+  #
+  # Include this in host app controllers that implement custom authentication
+  # flows but want to participate in StandardId's hook system. The hooks are
+  # configured via `StandardId.config.before_sign_in`, `after_sign_in`, and
+  # `after_account_created` callbacks.
+  #
+  # This is the same concern used internally by the WebEngine's built-in
+  # controllers -- there is no separate "internal" version.
+  #
+  # Requires the including controller to include `StandardId::WebAuthentication`
+  # (for `session_manager` and `request` access).
+  #
+  # @example Usage in a host app controller
+  #   class Auth::SessionsController < ApplicationController
+  #     include StandardId::WebAuthentication
+  #     include StandardId::LifecycleHooks
+  #
+  #     def create
+  #       account = authenticate_somehow(params)
+  #       invoke_before_sign_in(account, { mechanism: "custom", provider: nil })
+  #       session_manager.sign_in_account(account)
+  #       redirect_override = invoke_after_sign_in(account, { mechanism: "custom", provider: nil })
+  #       redirect_to redirect_override || root_path
+  #     rescue StandardId::AuthenticationDenied => e
+  #       handle_authentication_denied(e)
+  #     end
+  #   end
   module LifecycleHooks
     extend ActiveSupport::Concern
 
+    # Default profile resolver when StandardId.config.profile_resolver is nil.
+    DEFAULT_PROFILE_RESOLVER = ->(acct, pt) { acct.profiles.exists?(profileable_type: pt) }
+
     private
 
     # Invoke the before_sign_in hook if configured.
     # Called after credential verification, BEFORE session creation.
     #
+    # When a scope is active (via route defaults), the built-in profile
+    # validation runs BEFORE the app's custom hook. If the account lacks
+    # the required profile, AuthenticationDenied is raised immediately.
+    #
     # @param account [Object] the authenticated account
     # @param context [Hash] context about the sign-in
     #   - :mechanism [String] "password", "passwordless", or "social"
     #   - :provider [String, nil] e.g. "google", "apple", or nil
     #   - :first_sign_in [Boolean] whether this is the account's first browser session
+    #   - :scope [Symbol, nil] scope name when scoped authentication is active
+    #   - :profile_type [String, nil] required profile type for the scope
+    #   - :after_sign_in_path [String, nil] default redirect path for the scope
     # @return [void]
-    # @raise [StandardId::AuthenticationDenied] when hook returns { error: "..." }
+    # @raise [StandardId::AuthenticationDenied] when profile check fails or hook returns { error: "..." }
     def invoke_before_sign_in(account, context)
+      scope_config = current_scope_config
+      if scope_config
+        context = context.merge(
+          scope: scope_config.name,
+          profile_type: scope_config.profile_type,
+          after_sign_in_path: scope_config.after_sign_in_path
+        )
+
+        # Built-in profile check — runs before the app's custom hook
+        if scope_config.requires_profile?
+          resolver = StandardId.config.profile_resolver || DEFAULT_PROFILE_RESOLVER
+          unless resolver.call(account, scope_config.profile_type)
+            raise StandardId::AuthenticationDenied, scope_config.no_profile_message
+          end
+        end
+      end
+
+      context = context.merge(first_sign_in: first_sign_in?(account, session_created: false))
+
       hook = StandardId.config.before_sign_in
       return unless hook.respond_to?(:call)
 
-      context = context.merge(first_sign_in: first_sign_in?(account, session_created: false))
       result = hook.call(account, request, context)
 
       if result.is_a?(Hash) && result[:error].present?
@@ -28,23 +84,45 @@ module StandardId
 
     # Invoke the after_sign_in hook if configured.
     #
+    # When a scope is active, scope context is merged into the context hash.
+    # If the hook does not return a custom redirect path, the scope's
+    # after_sign_in_path is used as the default redirect.
+    #
     # @param account [Object] the authenticated account
     # @param context [Hash] context about the sign-in
     #   - :mechanism [String] "password", "passwordless", or "social"
     #   - :provider [String, nil] e.g. "google", "apple", or nil
     #   - :first_sign_in [Boolean] whether this is the account's first browser session
     #   - :session [StandardId::Session] the session that was just created
+    #   - :scope [Symbol, nil] scope name when scoped authentication is active
+    #   - :profile_type [String, nil] required profile type for the scope
+    #   - :after_sign_in_path [String, nil] default redirect path for the scope
     # @return [String, nil] redirect path override, or nil for default
     # @raise [StandardId::AuthenticationDenied] to reject the sign-in
     def invoke_after_sign_in(account, context)
-      hook = StandardId.config.after_sign_in
-      return nil unless hook.respond_to?(:call)
+      scope_config = current_scope_config
+      if scope_config
+        context = context.merge(
+          scope: scope_config.name,
+          profile_type: scope_config.profile_type,
+          after_sign_in_path: scope_config.after_sign_in_path
+        )
+      end
 
+      hook = StandardId.config.after_sign_in
       context = context.merge(
         first_sign_in: first_sign_in?(account, session_created: true),
         session: session_manager.current_session
       )
-      hook.call(account, request, context)
+
+      if hook.respond_to?(:call)
+        result = hook.call(account, request, context)
+        # If hook returned a redirect path, use it; otherwise fall back to scope path
+        return result if result.present?
+      end
+
+      # When no hook override, use the scope's after_sign_in_path if present
+      scope_config&.after_sign_in_path
     end
 
     # Invoke the after_account_created hook if configured.
@@ -53,8 +131,20 @@ module StandardId
     # @param context [Hash] context about the creation
     #   - :mechanism [String] "passwordless", "social", or "signup"
     #   - :provider [String, nil] e.g. "google", "apple", or nil
+    #   - :scope [Symbol, nil] scope name when scoped authentication is active
+    #   - :profile_type [String, nil] required profile type for the scope
+    #   - :after_sign_in_path [String, nil] default redirect path for the scope
     # @return [void]
     def invoke_after_account_created(account, context)
+      scope_config = current_scope_config
+      if scope_config
+        context = context.merge(
+          scope: scope_config.name,
+          profile_type: scope_config.profile_type,
+          after_sign_in_path: scope_config.after_sign_in_path
+        )
+      end
+
       hook = StandardId.config.after_account_created
       return unless hook.respond_to?(:call)
 
@@ -73,6 +163,11 @@ module StandardId
     # Handle AuthenticationDenied by revoking the session and redirecting to login.
     # If the account was just created, clean it up to avoid orphaned records.
     #
+    # @note By default this redirects to the WebEngine's login_path. Host app
+    #   controllers that include LifecycleHooks without mounting the WebEngine
+    #   should override this method to redirect to their own login page. When the
+    #   WebEngine route is unavailable, falls back to `StandardId.config.login_url`
+    #   or `"/"`.
     # @param error [StandardId::AuthenticationDenied] the denial error
     # @param account [Object, nil] the account to clean up if newly created
     # @param newly_created [Boolean] whether the account was created during this request
@@ -82,7 +177,12 @@ module StandardId
       message = error.message
       # When raised without arguments, StandardError#message returns the class name
       message = "Sign-in was denied" if message.blank? || message == error.class.name
-      redirect_to StandardId::WebEngine.routes.url_helpers.login_path, alert: message
+      login_path = begin
+        StandardId::WebEngine.routes.url_helpers.login_path
+      rescue NameError, NoMethodError, ActionController::UrlGenerationError
+        StandardId.config.login_url || "/"
+      end
+      redirect_to login_path, alert: message
     end
 
     # Destroy a newly created account and all its dependents.
@@ -97,5 +197,14 @@ module StandardId
         account.destroy
       end
     end
+
+    # Look up the scope config for the current request.
+    # Reads :scope from route defaults (set by scoped route constraints).
+    # Returns nil when no scope is active, preserving backward compatibility.
+    # Memoized per request to avoid redundant ScopeConfig allocations.
+    def current_scope_config
+      return @current_scope_config if defined?(@current_scope_config)
+      @current_scope_config = StandardId.scope_for(request.path_parameters[:scope])
+    end
   end
 end

data/app/controllers/concerns/standard_id/passwordless_flow.rb

@@ -0,0 +1,84 @@
+module StandardId
+  # Public concern for host app controllers that need passwordless OTP capabilities.
+  #
+  # Include this in your custom controllers to generate and verify OTP codes
+  # without mounting the WebEngine's built-in login controllers.
+  #
+  # Requires the including controller to have access to `request` (standard in
+  # all Rails controllers). No other dependencies are needed -- both
+  # `generate_passwordless_otp` and `verify_passwordless_otp` only use `request`.
+  #
+  # @example Usage in a host app controller
+  #   class Auth::LoginController < ApplicationController
+  #     include StandardId::PasswordlessFlow
+  #     include StandardId::WebAuthentication # needed for session_manager
+  #     include StandardId::LifecycleHooks
+  #
+  #     def create
+  #       generate_passwordless_otp(username: params[:email])
+  #       redirect_to verify_path
+  #     end
+  #
+  #     def verify
+  #       result = verify_passwordless_otp(username: params[:email], code: params[:code])
+  #       if result.success?
+  #         session_manager.sign_in_account(result.account)
+  #         redirect_to root_path
+  #       else
+  #         render :verify, status: :unprocessable_content
+  #       end
+  #     end
+  #   end
+  module PasswordlessFlow
+    extend ActiveSupport::Concern
+
+    include StandardId::PasswordlessStrategy
+
+    private
+
+    # Generate a passwordless OTP code and send it to the user.
+    #
+    # Delegates to the appropriate strategy (EmailStrategy or SmsStrategy)
+    # based on the connection type. The strategy validates the username,
+    # creates a CodeChallenge, and triggers the configured sender callback.
+    #
+    # @param username [String] the recipient's email address or phone number
+    # @param connection [String] the delivery channel ("email" or "sms"), defaults to "email"
+    # @return [StandardId::CodeChallenge] the created code challenge
+    # @raise [StandardId::InvalidRequestError] when the username format is invalid
+    #   or the connection type is unsupported
+    def generate_passwordless_otp(username:, connection: "email")
+      strategy = strategy_for(connection)
+      strategy.start!(username: username, connection: connection)
+    end
+
+    # Verify a passwordless OTP code and resolve the account.
+    #
+    # Delegates to `StandardId::Passwordless.verify`, which handles code
+    # validation, constant-time comparison, attempt tracking, and account
+    # resolution (find or create).
+    #
+    # @param username [String] the identifier value (email or phone number)
+    # @param code [String] the OTP code to verify
+    # @param connection [String] the delivery channel ("email" or "sms"), defaults to "email"
+    # @param allow_registration [Boolean] whether to create a new account if none exists (default: true)
+    # @return [StandardId::Passwordless::VerificationService::Result] a result with:
+    #   - success? -- true when verification succeeded
+    #   - account  -- the authenticated/created account (nil on failure)
+    #   - challenge -- the consumed CodeChallenge (nil on failure)
+    #   - error -- human-readable message (nil on success)
+    #   - error_code -- machine-readable symbol (nil on success):
+    #       :invalid_code, :expired, :max_attempts, :not_found, :blank_code,
+    #       :account_not_found, :server_error
+    #   - attempts -- failed attempt count (nil on success)
+    def verify_passwordless_otp(username:, code:, connection: "email", allow_registration: true)
+      StandardId::Passwordless.verify(
+        username: username,
+        code: code,
+        connection: connection,
+        request: request,
+        allow_registration: allow_registration
+      )
+    end
+  end
+end

data/app/controllers/concerns/standard_id/web_authentication.rb

@@ -1,10 +1,44 @@
 module StandardId
+  # Public concern providing cookie-based session management for web controllers.
+  #
+  # Include this in host app controllers to access StandardId's session
+  # management capabilities. This is the same concern used internally by
+  # the WebEngine's built-in controllers.
+  #
+  # ## Public helpers (available in controllers and views)
+  #
+  # - `current_account` -- Returns the currently authenticated account, or nil.
+  #   Loads from session token or remember-me cookie. Delegated to SessionManager.
+  #
+  # - `authenticated?` -- Returns true if a user is currently signed in.
+  #
+  # - `current_session` -- Returns the current StandardId::BrowserSession, or nil.
+  #   Delegated to SessionManager.
+  #
+  # - `revoke_current_session!` -- Revokes the current browser session and clears
+  #   all session/cookie tokens. Use for sign-out flows. Delegated to SessionManager.
+  #
+  # - `sign_in_account(login_params, &before_session)` -- Authenticates via password
+  #   credentials. Accepts a block called after credential verification but before
+  #   session creation (for lifecycle hooks). Returns the PasswordCredential on
+  #   success, nil on failure.
+  #
+  # - `session_manager` -- Returns the StandardId::Web::SessionManager instance
+  #   for the current request. Useful for direct session operations like
+  #   `session_manager.sign_in_account(account)` in passwordless flows.
+  #
+  # @example Usage in a host app controller
+  #   class ApplicationController < ActionController::Base
+  #     include StandardId::WebAuthentication
+  #
+  #     before_action :authenticate_account!
+  #   end
   module WebAuthentication
     extend ActiveSupport::Concern
 
     included do
       include StandardId::InertiaSupport
-      helper_method :current_account, :authenticated?
+      helper_method :current_account, :authenticated?, :current_scope_names
 
       if StandardId.config.alias_current_user
         define_method(:current_user) { current_account }
@@ -12,10 +46,22 @@ module StandardId
       end
     end
 
-    delegate :current_session, :current_account, :revoke_current_session!, to: :session_manager
+    # @!method current_session
+    #   Returns the current StandardId::BrowserSession, or nil.
+    # @!method current_account
+    #   Returns the currently authenticated account, or nil.
+    #   Loads from session token or remember-me cookie.
+    # @!method current_scope_names
+    #   Returns an array of scope names the user has authenticated into.
+    # @!method revoke_current_session!
+    #   Revokes the current browser session and clears all session/cookie tokens.
+    delegate :current_session, :current_account, :current_scope_names, :revoke_current_session!, to: :session_manager
 
     private
 
+    # Returns true if a user is currently signed in.
+    #
+    # @return [Boolean]
     def authenticated?
       current_account.present?
     end
@@ -59,6 +105,16 @@ module StandardId
       session.delete(:return_to_after_authenticating) || "/"
     end
 
+    # Authenticate a user via password credentials and create a browser session.
+    #
+    # Accepts a block called after credential verification but before session
+    # creation, allowing lifecycle hooks (e.g. invoke_before_sign_in) to reject
+    # the sign-in by raising StandardId::AuthenticationDenied.
+    #
+    # @param login_params [Hash] must include :email (or :login) and :password;
+    #   optionally :remember_me
+    # @yield [account] called after password verification, before session creation
+    # @return [StandardId::PasswordCredential, nil] the credential on success, nil on failure
     def sign_in_account(login_params, &before_session)
       login = login_params[:email] || login_params[:login] # support both :email and :login keys
       password = login_params[:password]
@@ -98,7 +154,7 @@ module StandardId
         # but before session creation. The block may raise AuthenticationDenied.
         before_session&.call(password_credential.account)
 
-        session_manager.sign_in_account(password_credential.account)
+        session_manager.sign_in_account(password_credential.account, scope_name: request.path_parameters[:scope])
         session_manager.set_remember_cookie(password_credential) if remember_me
 
         StandardId::Events.publish(
@@ -110,6 +166,12 @@ module StandardId
       end
     end
 
+    # Returns the StandardId::Web::SessionManager for the current request.
+    #
+    # Use this for direct session operations in custom flows, e.g.:
+    #   session_manager.sign_in_account(account)
+    #
+    # @return [StandardId::Web::SessionManager]
     def session_manager
       @session_manager ||= StandardId::Web::SessionManager.new(
         token_manager,

data/app/controllers/standard_id/api/passwordless_controller.rb

@@ -3,7 +3,7 @@ module StandardId
     class PasswordlessController < BaseController
       public_controller
 
-      include StandardId::PasswordlessStrategy
+      include StandardId::PasswordlessFlow
 
       # RAR-60: Rate limit OTP initiation by IP (10 per hour)
       rate_limit to: StandardId.config.rate_limits.api_passwordless_start_per_ip,
@@ -23,7 +23,7 @@ module StandardId
       def start
         raise StandardId::InvalidRequestError, "username, email, or phone_number parameter is required" if start_params[:username].blank?
 
-        strategy_for(start_params[:connection]).start!(start_params)
+        generate_passwordless_otp(username: start_params[:username], connection: start_params[:connection])
 
         render json: { message: "Code sent successfully" }, status: :ok
       end

data/app/controllers/standard_id/web/auth/callback/providers_controller.rb

@@ -39,7 +39,7 @@ module StandardId
               newly_created = account.previously_new_record?
 
               invoke_before_sign_in(account, { mechanism: "social", provider: provider.provider_name })
-              session_manager.sign_in_account(account)
+              session_manager.sign_in_account(account, scope_name: state_data&.dig("scope"))
 
               provider_name = provider.provider_name
               invoke_after_account_created(account, { mechanism: "social", provider: provider_name }) if newly_created

data/app/controllers/standard_id/web/login_controller.rb

@@ -5,7 +5,7 @@ module StandardId
 
       include StandardId::InertiaRendering
       include StandardId::Web::SocialLoginParams
-      include StandardId::PasswordlessStrategy
+      include StandardId::PasswordlessFlow
       include StandardId::LifecycleHooks
 
       layout "public"
@@ -72,19 +72,17 @@ module StandardId
       end
 
       def handle_passwordless_login
-        email = login_params[:email].to_s.strip.downcase
+        username = login_params[:email].to_s.strip.downcase
         connection = StandardId.config.passwordless.connection
 
-        if email.blank?
+        if username.blank?
           flash.now[:alert] = "Please enter your email address"
           render_with_inertia action: :show, props: auth_page_props(passwordless_enabled: passwordless_enabled?), status: :unprocessable_content
           return
         end
 
-        strategy = strategy_for(connection)
-
         begin
-          strategy.start!(username: email, connection: connection)
+          generate_passwordless_otp(username: username, connection: connection)
         rescue StandardId::InvalidRequestError => e
           flash.now[:alert] = e.message
           render_with_inertia action: :show, props: auth_page_props(passwordless_enabled: passwordless_enabled?), status: :unprocessable_content
@@ -93,7 +91,7 @@ module StandardId
 
         code_ttl = StandardId.config.passwordless.code_ttl
         signed_payload = Rails.application.message_verifier(:otp).generate(
-          { username: email, connection: connection },
+          { username: username, connection: connection },
           expires_in: code_ttl.seconds
         )
         session[:standard_id_otp_payload] = signed_payload
@@ -138,7 +136,11 @@ module StandardId
       end
 
       def extract_social_login_params
-        request.parameters.except("controller", "action", "format", "authenticity_token", "commit", "login").to_h.deep_dup
+        social_params = request.parameters.except("controller", "action", "format", "authenticity_token", "commit", "login").to_h.deep_dup
+        # Include scope from route defaults so it survives the OAuth redirect/callback round trip
+        scope = request.path_parameters[:scope]
+        social_params["scope"] = scope.to_s if scope.present?
+        social_params
       end
 
       def extract_oauth_params(provider)

data/app/controllers/standard_id/web/login_verify_controller.rb

@@ -5,6 +5,7 @@ module StandardId
       requires_web_mechanism :passwordless_login
 
       include StandardId::InertiaRendering
+      include StandardId::PasswordlessFlow
       include StandardId::LifecycleHooks
 
       layout "public"
@@ -33,11 +34,10 @@ module StandardId
           return
         end
 
-        result = StandardId::Passwordless.verify(
+        result = verify_passwordless_otp(
           username: @otp_data[:username],
           code: code,
           connection: @otp_data[:connection],
-          request: request,
           allow_registration: passwordless_registration_enabled?
         )
 
@@ -52,7 +52,7 @@ module StandardId
 
         invoke_before_sign_in(account, { mechanism: "passwordless", provider: nil })
 
-        session_manager.sign_in_account(account)
+        session_manager.sign_in_account(account, scope_name: request.path_parameters[:scope])
         emit_authentication_succeeded(account)
 
         if newly_created

data/app/controllers/standard_id/web/signup_controller.rb

@@ -40,7 +40,7 @@ module StandardId
 
         if form.submit
           invoke_before_sign_in(form.account, { mechanism: "password", provider: nil })
-          session_manager.sign_in_account(form.account)
+          session_manager.sign_in_account(form.account, scope_name: request.path_parameters[:scope])
           invoke_after_account_created(form.account, { mechanism: "signup", provider: nil })
 
           context = { mechanism: "password", provider: nil }

data/lib/standard_id/config/schema.rb

@@ -18,6 +18,17 @@ StandardConfig.schema.draw do
     field :use_inertia, type: :boolean, default: false
     field :inertia_component_namespace, type: :string, default: "standard_id"
     field :alias_current_user, type: :boolean, default: false
+
+    # Scope-aware authentication: maps scope names to profile-based access config.
+    # Each scope is a hash with keys: :profile_type, :after_sign_in_path,
+    # :no_profile_message, :label, :allow_registration.
+    field :scopes, type: :any, default: {}
+
+    # Callable that resolves whether an account has a profile for a given scope.
+    # Receives (account, profile_type) and returns true/false.
+    # Override to customise profile lookup logic.
+    # Default (nil) uses: account.profiles.exists?(profileable_type: profile_type)
+    field :profile_resolver, type: :any, default: nil
     # Callable (lambda/proc) that returns a Hash of extra Sentry user context fields.
     # Receives (account, session) where session may be nil. Non-callable values are ignored.
     field :sentry_context, type: :any, default: nil

data/lib/standard_id/scope_config.rb

@@ -0,0 +1,20 @@
+module StandardId
+  class ScopeConfig
+    # @!attribute [r] allow_registration
+    #   Reserved for future use — controls whether new accounts can register under this scope.
+    attr_reader :name, :profile_type, :after_sign_in_path, :no_profile_message, :label, :allow_registration
+
+    def initialize(name, config = {})
+      @name = name.to_sym
+      @profile_type = config[:profile_type]
+      @after_sign_in_path = config[:after_sign_in_path]
+      @no_profile_message = config[:no_profile_message] || "Access denied. No matching profile found."
+      @label = config[:label] || name.to_s.humanize
+      @allow_registration = config.fetch(:allow_registration, true)
+    end
+
+    def requires_profile?
+      profile_type.present?
+    end
+  end
+end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/standard_id/web/session_manager.rb

@@ -19,26 +19,37 @@ module StandardId
         Current.account ||= load_current_account
       end
 
-      def sign_in_account(account)
+      def sign_in_account(account, scope_name: nil)
         emit_session_creating(account, "browser")
 
         # Prevent session fixation by resetting the Rails session before
         # creating an authenticated session (Rails Security Guide §2.5).
         # Preserve return_to URL across the reset so post-login redirect works.
         return_to = session[:return_to_after_authenticating]
+        existing_scopes = session[:standard_id_scopes]
         @reset_session&.call
         session[:return_to_after_authenticating] = return_to if return_to
+        session[:standard_id_scopes] = existing_scopes if existing_scopes
 
         token_manager.create_browser_session(account).tap do |browser_session|
           # Store in both session and encrypted cookie for backward compatibility
           # Action Cable will use the encrypted cookie
           session[:session_token] = browser_session.token
           cookies.encrypted[:session_token] = browser_session.token
+          if scope_name
+            scopes = Array(session[:standard_id_scopes])
+            scopes << scope_name.to_s unless scopes.include?(scope_name.to_s)
+            session[:standard_id_scopes] = scopes
+          end
           Current.session = browser_session
           emit_session_created(browser_session, account, "browser")
         end
       end
 
+      def current_scope_names
+        Array(session[:standard_id_scopes])
+      end
+
       def revoke_current_session!
         current_session&.revoke!
         clear_session!
@@ -51,6 +62,7 @@ module StandardId
       def clear_session!
         # TODO: make token key names configurable
         session.delete(:session_token)
+        session.delete(:standard_id_scopes)
         cookies.encrypted[:session_token] = nil
         cookies.delete(:remember_token)
 
@@ -100,7 +112,10 @@ module StandardId
         password_credential = StandardId::PasswordCredential.find_by_token_for(:remember_me, cookies[:remember_token])
         return if password_credential.blank?
 
-        # Prevent session fixation on returning-user remember-me flow
+        # Prevent session fixation on returning-user remember-me flow.
+        # Note: standard_id_scopes are intentionally NOT preserved here —
+        # remember-me re-auth is a fresh session context where scopes
+        # must be re-acquired through explicit scoped sign-in.
         @reset_session&.call
 
         token_manager.create_browser_session(password_credential.account, remember_me: true).tap do |browser_session|

data/lib/standard_id.rb

@@ -4,6 +4,7 @@ require "standard_id/engine"
 require "standard_id/web_engine"
 require "standard_id/api_engine"
 require "standard_id/config/schema"
+require "standard_id/scope_config"
 require "standard_id/errors"
 require "standard_id/events"
 require "standard_id/events/subscribers/base"
@@ -81,6 +82,13 @@ module StandardId
       config.account_class_name.constantize
     end
 
+    def scope_for(name)
+      return nil if config.scopes.blank? || name.blank?
+      scope_hash = config.scopes[name.to_sym]
+      return nil unless scope_hash
+      ScopeConfig.new(name, scope_hash)
+    end
+
     def skip_host_authorization(framework: nil, callback: nil)
       AuthorizationBypass.apply(framework: framework, callback: callback)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -113,6 +113,7 @@ files:
 - app/controllers/concerns/standard_id/inertia_rendering.rb
 - app/controllers/concerns/standard_id/inertia_support.rb
 - app/controllers/concerns/standard_id/lifecycle_hooks.rb
+- app/controllers/concerns/standard_id/passwordless_flow.rb
 - app/controllers/concerns/standard_id/passwordless_strategy.rb
 - app/controllers/concerns/standard_id/rate_limit_handling.rb
 - app/controllers/concerns/standard_id/sentry_context.rb
@@ -257,6 +258,7 @@ files:
 - lib/standard_id/provider_registry.rb
 - lib/standard_id/providers/base.rb
 - lib/standard_id/rate_limit_store.rb
+- lib/standard_id/scope_config.rb
 - lib/standard_id/testing.rb
 - lib/standard_id/testing/authentication_helpers.rb
 - lib/standard_id/testing/factories/credentials.rb