standard_id 0.2.9 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2452ed8123165d861c0336f59c980b08aad25936f3a1aaee39a2b13f370148b8
-  data.tar.gz: a1390102deff80b924ac9d6ce5f53e260a0daaf0001524486f909c9d64c422d9
+  metadata.gz: a164420e3b36d754be94711721ead8cb4d29efed42fd6e75b0060e1c8c7c3bce
+  data.tar.gz: cded0bf7e847cc77ed0f6aa7c69647435c847d62ae02c2af1466778a507f88f4
 SHA512:
-  metadata.gz: 598e2740f693cc6e1f58c77f02897fe2f39c6bd2c2748c7f40bd729bafe1f15bc80fccc6755daeabe0a1ca2a08c0bb547b5f308f0596a233dc6e7ca81939c68f
-  data.tar.gz: eae44ac9c2cb4d0226547519b8d67ff042b4e3395efd0ffb91cb41ba7b9d8789c2f1a6afbfc4e2f75dcb32aad27ec9414ccbe30906b28d83f5bac842c42fa482
+  metadata.gz: 0b9b506d8014bd8d8cd380b1f5300a87d2d6825e073e8b959c67cbfeac3eb577abe671c9dac330833c8d27ee010b87786f533ac4e247459d691dd956d5053faf
+  data.tar.gz: ec1a9973e61d08fff4579099dbcac25ad8355d140994c51c2621559d4aed39486d2fdd891b451ade775799f792c3db19916d555d3a50f3bc84d07ed77c1f0a52

data/README.md

@@ -516,27 +516,71 @@ StandardId::Events.subscribe(/social/) do |event|
 end
 ```
 
-#### Class-based (complex logic)
+### Audit Logging
+
+For production audit trails, use the [standard_audit](https://github.com/rarebit-one/standard_audit) gem. StandardId and StandardAudit have zero direct references to each other — the host application wires them together.
+
+#### Setup
+
+Add both gems to your Gemfile:
 
 ```ruby
-# app/subscribers/audit_subscriber.rb
-class AuditSubscriber < StandardId::Events::Subscribers::Base
-  subscribe_to StandardId::Events::SECURITY_EVENTS
+gem "standard_id"
+gem "standard_audit"
+```
 
-  def call(event)
-    AuditLog.create!(
-      event_type: event.short_name,
-      account_id: event[:account]&.id,
-      ip_address: event[:ip_address],
-      metadata: event.payload
-    )
-  end
+Run the StandardAudit install generator:
+
+```bash
+rails generate standard_audit:install
+rails db:migrate
+```
+
+#### Wiring StandardId events to StandardAudit
+
+Configure StandardAudit to subscribe to StandardId's event namespace and map its payload conventions:
+
+```ruby
+# config/initializers/standard_audit.rb
+StandardAudit.configure do |config|
+  config.subscribe_to /\Astandard_id\./
+
+  # StandardId uses :account and :current_account rather than :actor/:target.
+  # Map them so StandardAudit extracts the right records.
+  config.actor_extractor = ->(payload) {
+    payload[:current_account] || payload[:account]
+  }
+
+  config.target_extractor = ->(payload) {
+    # Only set a target when the actor (current_account) differs from the
+    # account being acted upon — e.g. an admin locking another user.
+    if payload[:current_account]
+      target = payload[:account] || payload[:client_application]
+      target unless target == payload[:current_account]
+    end
+  }
 end
+```
 
-# config/initializers/standard_id_events.rb
-AuditSubscriber.attach
+That's it. Every StandardId authentication event will now be persisted as an audit log entry. No changes are needed inside StandardId itself.
+
+#### Querying audit logs
+
+```ruby
+# All auth events for a user
+StandardAudit::AuditLog.for_actor(user).reverse_chronological
+
+# Failed logins this week
+StandardAudit::AuditLog
+  .by_event_type("standard_id.authentication.attempt.failed")
+  .this_week
+
+# All activity from an IP address
+StandardAudit::AuditLog.from_ip("192.168.1.1")
 ```
 
+See the [StandardAudit README](https://github.com/rarebit-one/standard_audit) for the full query interface, async processing, GDPR compliance, and multi-tenancy support.
+
 ## Account Status (Activation/Deactivation)
 
 StandardId provides an optional `AccountStatus` concern for managing account activation and deactivation. This uses Rails enum with the event system to enforce status checks and handle side effects without modifying core authentication logic.
@@ -743,8 +787,7 @@ class ApplicationController < ActionController::Base
   private
 
   def handle_account_locked(error)
-    # error.account     - The locked account
-    # error.lock_reason - Why the account was locked
+    # error.lock_reason - Why the account was locked (avoid exposing to end users)
     # error.locked_at   - When the account was locked
     redirect_to login_path, alert: "Your account has been locked. Please contact support."
   end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module StandardId
+  # Per-controller audience verification for API endpoints.
+  #
+  # While StandardId validates that the JWT `aud` claim is in the global
+  # `allowed_audiences` list, this concern provides additional defense-in-depth
+  # by restricting which audiences are accepted by each controller.
+  #
+  # Requires StandardId::ApiAuthentication to be included before this concern
+  # (provides `verify_access_token!` and `current_session`). An error is raised
+  # at include time if ApiAuthentication is missing.
+  #
+  # The caller is responsible for registering `before_action :verify_access_token!`
+  # (typically via ApiAuthentication or a base controller). This concern only adds
+  # the `verify_audience!` callback, which must run after token verification so
+  # that `current_session` is populated. This is consistent with how
+  # `require_scopes!` works in ApiAuthentication.
+  #
+  # @example Single audience
+  #   class AdminController < Api::BaseController
+  #     include StandardId::AudienceVerification
+  #     verify_audience "admin"
+  #   end
+  #
+  # @example Multiple audiences
+  #   class SharedController < Api::BaseController
+  #     include StandardId::AudienceVerification
+  #     verify_audience "admin", "mobile"
+  #   end
+  module AudienceVerification
+    extend ActiveSupport::Concern
+
+    included do
+      unless ancestors.include?(StandardId::ApiAuthentication)
+        raise "#{name || 'Controller'} must include StandardId::ApiAuthentication before StandardId::AudienceVerification"
+      end
+
+      before_action :verify_audience!
+
+      rescue_from StandardId::InvalidAudienceError, with: :handle_invalid_audience
+
+      # Underscore prefix follows Rails class_attribute convention to avoid
+      # collisions with application method names.
+      class_attribute :_required_audiences, instance_writer: false, default: []
+    end
+
+    class_methods do
+      # Declare the allowed audiences for this controller.
+      # The token's `aud` claim must include at least one of these values.
+      #
+      # @param audiences [Array<String>] allowed JWT `aud` claim values
+      def verify_audience(*audiences)
+        self._required_audiences = audiences.flatten.map(&:to_s)
+      end
+    end
+
+    private
+
+    # Verifies the token's `aud` claim contains at least one of the required audiences.
+    # Supports both string and array `aud` claims.
+    #
+    # @raise [StandardId::InvalidAudienceError] when no audience matches
+    def verify_audience!
+      return if _required_audiences.empty?
+
+      # If authentication hasn't run (or token is invalid), let the auth
+      # layer handle 401 — don't mask it with a 403.
+      return unless current_session
+
+      token_audiences = Array(current_session.aud)
+      return if (token_audiences & _required_audiences).any?
+
+      raise StandardId::InvalidAudienceError.new(
+        required: _required_audiences,
+        actual: token_audiences
+      )
+    end
+
+    # Returns 403 Forbidden per RFC 6750 §3.1 (insufficient_scope).
+    # Includes WWW-Authenticate header per spec, consistent with the gem's
+    # 401 handling in Api::BaseController#render_bearer_unauthorized!.
+    #
+    # The header uses a static description rather than interpolating
+    # error.message (which contains raw aud values from the JWT) to
+    # avoid header injection via crafted audience strings.
+    #
+    # Override in your controller for custom error formatting.
+    def handle_invalid_audience(error)
+      response.set_header(
+        "WWW-Authenticate",
+        'Bearer error="insufficient_scope", error_description="The access token audience is not permitted for this resource"'
+      )
+      render json: { error: "insufficient_scope", error_description: error.message }, status: :forbidden
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module StandardId
+  module PasswordlessStrategy
+    extend ActiveSupport::Concern
+
+    STRATEGY_MAP = {
+      "email" => StandardId::Passwordless::EmailStrategy,
+      "sms"   => StandardId::Passwordless::SmsStrategy
+    }.freeze
+
+    private
+
+    def strategy_for(connection)
+      klass = STRATEGY_MAP[connection]
+      raise StandardId::InvalidRequestError, "Unsupported connection type: #{connection}" unless klass
+      klass.new(request)
+    end
+  end
+end

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

@@ -47,7 +47,7 @@ module StandardId
           account: account,
           value: email
         )
-        identifier.verify! if identifier.respond_to?(:verify!)
+        identifier.verify! if identifier.respond_to?(:verify!) && [true, "true"].include?(social_info[:email_verified])
         emit_social_account_created(account, provider, social_info)
         account
       end

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

@@ -66,7 +66,13 @@ module StandardId
       )
 
       StandardId::PasswordCredential.find_by(login:).tap do |password_credential|
-        unless password_credential&.authenticate(password)
+        authenticated = password_credential&.authenticate(password)
+
+        # Perform a dummy bcrypt comparison when the credential doesn't exist
+        # to prevent user enumeration via response timing differences.
+        BCrypt::Password.new(dummy_password_digest).is_password?(password) unless password_credential
+
+        unless authenticated
           StandardId::Events.publish(
             StandardId::Events::AUTHENTICATION_FAILED,
             account_lookup: login,
@@ -103,6 +109,10 @@ module StandardId
       @token_manager ||= StandardId::Web::TokenManager.new(request)
     end
 
+    def dummy_password_digest
+      @dummy_password_digest ||= BCrypt::Password.create("").freeze
+    end
+
     def authentication_guard
       @authentication_guard ||= StandardId::Web::AuthenticationGuard.new
     end

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

@@ -1,10 +1,7 @@
 module StandardId
   module Api
     class PasswordlessController < BaseController
-      STRATEGY_MAP = {
-        "email" => StandardId::Passwordless::EmailStrategy,
-        "sms"   => StandardId::Passwordless::SmsStrategy
-      }.freeze
+      include StandardId::PasswordlessStrategy
 
       def start
         raise StandardId::InvalidRequestError, "username, email, or phone_number parameter is required" if start_params[:username].blank?
@@ -16,12 +13,6 @@ module StandardId
 
       private
 
-      def strategy_for(connection)
-        klass = STRATEGY_MAP[connection]
-        raise StandardId::InvalidRequestError, "Unsupported connection type: #{connection}" unless klass
-        klass.new(request)
-      end
-
       def start_params
         return @start_params if @start_params.present?
 

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

@@ -3,7 +3,7 @@ module StandardId
     class LoginController < BaseController
       include StandardId::InertiaRendering
       include StandardId::Web::SocialLoginParams
-
+      include StandardId::PasswordlessStrategy
 
       layout "public"
 
@@ -16,19 +16,62 @@ module StandardId
         @redirect_uri = params[:redirect_uri] || after_authentication_url
         @connection = params[:connection]
 
-        render_with_inertia props: auth_page_props
+        render_with_inertia props: auth_page_props(passwordless_enabled: passwordless_enabled?)
       end
 
       def create
+        if passwordless_enabled?
+          handle_passwordless_login
+        else
+          handle_password_login
+        end
+      end
+
+      private
+
+      def passwordless_enabled?
+        StandardId.config.passwordless.enabled
+      end
+
+      def handle_password_login
         if sign_in_account(login_params)
           redirect_to params[:redirect_uri] || after_authentication_url, status: :see_other, notice: "Successfully signed in"
         else
           flash.now[:alert] = "Invalid email or password"
-          render_with_inertia action: :show, props: auth_page_props, status: :unprocessable_content
+          render_with_inertia action: :show, props: auth_page_props(passwordless_enabled: passwordless_enabled?), status: :unprocessable_content
         end
       end
 
-      private
+      def handle_passwordless_login
+        email = login_params[:email].to_s.strip.downcase
+        connection = StandardId.config.passwordless.connection
+
+        if email.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)
+        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
+          return
+        end
+
+        code_ttl = StandardId.config.passwordless.code_ttl
+        signed_payload = Rails.application.message_verifier(:otp).generate(
+          { username: email, connection: connection },
+          expires_in: code_ttl.seconds
+        )
+        session[:standard_id_otp_payload] = signed_payload
+        session[:return_to_after_authenticating] = params[:redirect_uri] if params[:redirect_uri].present?
+
+        redirect_to login_verify_path, status: :see_other
+      end
 
       def redirect_if_authenticated
         redirect_to after_authentication_url, status: :see_other, notice: "You are already signed in" if authenticated?

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

@@ -0,0 +1,170 @@
+module StandardId
+  module Web
+    class LoginVerifyController < BaseController
+      include StandardId::InertiaRendering
+      include StandardId::PasswordlessStrategy
+
+      class OtpVerificationFailed < StandardError; end
+
+      layout "public"
+
+      skip_before_action :require_browser_session!, only: [:show, :update]
+
+      before_action :ensure_passwordless_enabled!
+      before_action :redirect_if_authenticated, only: [:show]
+      before_action :require_otp_payload!
+
+      def show
+        render_with_inertia props: verify_page_props
+      end
+
+      def update
+        code = params[:code].to_s.strip
+
+        if code.blank?
+          flash.now[:alert] = "Please enter the verification code"
+          render_with_inertia action: :show, props: verify_page_props, status: :unprocessable_content
+          return
+        end
+
+        # Record failed attempts outside the main transaction so they persist
+        challenge = find_active_challenge
+        attempts = record_attempt(challenge, code)
+
+        if challenge.blank? || !ActiveSupport::SecurityUtils.secure_compare(challenge.code, code)
+          emit_otp_validation_failed(attempts) if challenge.present?
+
+          flash.now[:alert] = "Invalid or expired verification code"
+          render_with_inertia action: :show, props: verify_page_props, status: :unprocessable_content
+          return
+        end
+
+        strategy = strategy_for(@otp_data[:connection])
+
+        begin
+          ActiveRecord::Base.transaction do
+            # Re-fetch with lock inside transaction to prevent concurrent use
+            locked_challenge = StandardId::CodeChallenge.lock.find(challenge.id)
+            raise OtpVerificationFailed unless locked_challenge.active?
+
+            account = strategy.find_or_create_account(@otp_data[:username])
+            locked_challenge.use!
+
+            emit_otp_validated(account, locked_challenge)
+            session_manager.sign_in_account(account)
+            emit_authentication_succeeded(account)
+          end
+        rescue OtpVerificationFailed
+          flash.now[:alert] = "Invalid or expired verification code"
+          render_with_inertia action: :show, props: verify_page_props, status: :unprocessable_content
+          return
+        rescue ActiveRecord::RecordInvalid => e
+          flash.now[:alert] = "Unable to complete sign in: #{e.record.errors.full_messages.to_sentence}"
+          render_with_inertia action: :show, props: verify_page_props, status: :unprocessable_content
+          return
+        end
+
+        session.delete(:standard_id_otp_payload)
+
+        redirect_to after_authentication_url, status: :see_other, notice: "Successfully signed in"
+      end
+
+      private
+
+      def ensure_passwordless_enabled!
+        return if StandardId.config.passwordless.enabled
+
+        session.delete(:standard_id_otp_payload)
+        redirect_to login_path, alert: "Passwordless login is not available"
+      end
+
+      def redirect_if_authenticated
+        redirect_to after_authentication_url, status: :see_other if authenticated?
+      end
+
+      def require_otp_payload!
+        signed_payload = session[:standard_id_otp_payload]
+
+        if signed_payload.blank?
+          redirect_to login_path, alert: "Please start the login process"
+          return
+        end
+
+        begin
+          @otp_data = Rails.application.message_verifier(:otp).verify(signed_payload).symbolize_keys
+        rescue ActiveSupport::MessageVerifier::InvalidSignature
+          session.delete(:standard_id_otp_payload)
+          redirect_to login_path, alert: "Your verification session has expired. Please try again."
+        end
+      end
+
+      def find_active_challenge
+        StandardId::CodeChallenge.active.find_by(
+          realm: "authentication",
+          channel: @otp_data[:connection],
+          target: @otp_data[:username]
+        )
+      end
+
+      def record_attempt(challenge, code)
+        return 0 if challenge.blank?
+        return 0 if ActiveSupport::SecurityUtils.secure_compare(challenge.code, code)
+
+        attempts = (challenge.metadata["attempts"] || 0) + 1
+        challenge.update!(metadata: challenge.metadata.merge("attempts" => attempts))
+
+        max_attempts = StandardId.config.passwordless.max_attempts
+        challenge.use! if attempts >= max_attempts
+
+        attempts
+      end
+
+      def emit_otp_validated(account, challenge)
+        StandardId::Events.publish(
+          StandardId::Events::OTP_VALIDATED,
+          account: account,
+          channel: @otp_data[:connection]
+        )
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_VERIFIED,
+          code_challenge: challenge,
+          account: account,
+          channel: @otp_data[:connection]
+        )
+      end
+
+      def emit_otp_validation_failed(attempts)
+        StandardId::Events.publish(
+          StandardId::Events::OTP_VALIDATION_FAILED,
+          identifier: @otp_data[:username],
+          channel: @otp_data[:connection],
+          attempts: attempts
+        )
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORDLESS_CODE_FAILED,
+          identifier: @otp_data[:username],
+          channel: @otp_data[:connection],
+          attempts: attempts
+        )
+      end
+
+      def emit_authentication_succeeded(account)
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_SUCCEEDED,
+          account: account,
+          auth_method: "passwordless_otp",
+          session_type: "browser"
+        )
+      end
+
+      def verify_page_props
+        {
+          flash: {
+            notice: flash[:notice],
+            alert: flash[:alert]
+          }.compact
+        }
+      end
+    end
+  end
+end

data/app/forms/standard_id/web/signup_form.rb

@@ -37,8 +37,8 @@ module StandardId
       rescue ActiveRecord::RecordInvalid => e
         errors.add(:base, e.record.errors.full_messages.join(", "))
         false
-      rescue ActiveRecord::RecordNotUnique => e
-        errors.add(:base, e.message)
+      rescue ActiveRecord::RecordNotUnique
+        errors.add(:base, "Unable to complete registration. If you already have an account, please sign in.")
         false
       end
 

data/app/jobs/standard_id/cleanup_expired_sessions_job.rb

@@ -0,0 +1,15 @@
+module StandardId
+  class CleanupExpiredSessionsJob < ApplicationJob
+    queue_as :default
+
+    # Delete sessions that expired more than `grace_period_seconds` ago.
+    # A grace period avoids deleting sessions that just expired and might
+    # still be referenced in in-flight requests.
+    # Accepts integer seconds for reliable ActiveJob serialization across all queue adapters.
+    def perform(grace_period_seconds: 7.days.to_i)
+      cutoff = grace_period_seconds.seconds.ago
+      deleted = StandardId::Session.where("expires_at < ?", cutoff).delete_all
+      Rails.logger.info("[StandardId] Cleaned up #{deleted} expired sessions older than #{cutoff}")
+    end
+  end
+end

data/app/views/standard_id/web/login_verify/show.html.erb

@@ -0,0 +1,35 @@
+<%# ERB fallback for non-Inertia rendering. Flash is read directly here;
+    Inertia clients receive structured flash via verify_page_props instead. %>
+<% content_for :title, "Verify Code" %>
+
+<div class="flex min-h-full flex-col justify-center py-12 sm:px-6 lg:px-8">
+  <div class="sm:mx-auto sm:w-full sm:max-w-md">
+    <h2 class="mt-6 text-center text-2xl/9 font-bold tracking-tight text-gray-900 dark:text-white">Enter verification code</h2>
+    <p class="mt-2 text-center text-sm text-gray-500 dark:text-gray-400">We sent you a verification code.</p>
+  </div>
+
+  <div class="mt-10 sm:mx-auto sm:w-full sm:max-w-[480px]">
+    <div class="bg-white px-6 py-12 shadow sm:rounded-lg sm:px-12 dark:bg-gray-800/50 dark:shadow-none dark:outline dark:outline-1 dark:-outline-offset-1 dark:outline-white/10">
+
+      <% if flash[:alert].present? %>
+        <div class="mb-4 rounded-md bg-red-50 p-4 text-sm text-red-700 dark:bg-red-900/20 dark:text-red-300"><%= flash[:alert] %></div>
+      <% end %>
+      <% if flash[:notice].present? %>
+        <div class="mb-4 rounded-md bg-green-50 p-4 text-sm text-green-700 dark:bg-green-900/20 dark:text-green-300"><%= flash[:notice] %></div>
+      <% end %>
+
+      <%= form_with url: login_verify_path, method: :patch, local: true, html: { class: "space-y-6" } do |form| %>
+        <div>
+          <%= form.label :code, "Verification code", class: "block text-sm/6 font-medium text-gray-900 dark:text-white" %>
+          <div class="mt-2">
+            <%= form.text_field :code, required: true, autofocus: true, autocomplete: "one-time-code", inputmode: "numeric", maxlength: 6, class: "block w-full rounded-md bg-white px-3 py-1.5 text-base text-gray-900 outline outline-1 -outline-offset-1 outline-gray-300 placeholder:text-gray-400 focus:outline focus:outline-2 focus:-outline-offset-2 focus:outline-indigo-600 sm:text-sm/6 dark:bg-white/5 dark:text-white dark:outline-white/10 dark:placeholder:text-gray-500 dark:focus:outline-indigo-500" %>
+          </div>
+        </div>
+
+        <div>
+          <%= form.submit "Verify", class: "flex w-full justify-center rounded-md bg-indigo-600 px-3 py-1.5 text-sm/6 font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600 dark:bg-indigo-500 dark:shadow-none dark:hover:bg-indigo-400 dark:focus-visible:outline-indigo-500" %>
+        </div>
+      <% end %>
+    </div>
+  </div>
+</div>

data/config/brakeman.ignore

@@ -0,0 +1,30 @@
+{
+  "ignored_warnings": [
+    {
+      "fingerprint": "24fc02735a2ad863d6bf1171a4a329b208e9e7c41841fa0149d8e6878d4ce299",
+      "note": "Auth engine intentionally redirects to params[:redirect_uri] after signup for OAuth/post-auth flow"
+    },
+    {
+      "fingerprint": "6b35e9906d62a9b9cd0dff9cf53924d40e74bc4f96cfccf27e67e93551113243",
+      "note": "Auth engine intentionally redirects to params[:redirect_uri] after logout for OAuth/post-auth flow"
+    },
+    {
+      "fingerprint": "8fddb7968577ac46fdda8e799f476c3eced60cc585da9c30fa61117f91e04ab9",
+      "note": "HEAD vs GET distinction is inconsequential here; redirect_to_login adding redirect_uri param on GET-only is safe"
+    },
+    {
+      "fingerprint": "bdbc72619da2ba771b1185ccf16acce801066689bf51adf116eab8c8714b39af",
+      "note": "HEAD vs GET distinction is inconsequential here; storing return URL on GET-only is safe"
+    },
+    {
+      "fingerprint": "16bd6ec7c3fa130eb80c15fc90c87f9859d89b37258807bfaffe4101366611a6",
+      "note": "Auth engine intentionally redirects to params[:redirect_uri] after login for OAuth/post-auth flow"
+    },
+    {
+      "fingerprint": "e4f96cb212c73c3165c3db6eaa6368c29d362b61264f034e80c9fa6705d72e5b",
+      "note": "Auth engine intentionally redirects to params[:redirect_uri] when user is not authenticated"
+    }
+  ],
+  "updated": "2026-02-27",
+  "brakeman_version": "8.0.2"
+}

data/config/routes/web.rb

@@ -2,6 +2,7 @@ StandardId::WebEngine.routes.draw do
   scope module: :web do
     # Authentication flows
     resource :login, only: [:show, :create], controller: :login
+    resource :login_verify, only: [:show, :update], controller: :login_verify
     resource :logout, only: [:create], controller: :logout
     resource :signup, only: [:show, :create], controller: :signup
 

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -101,6 +101,8 @@ StandardId.configure do |c|
   # Events
   # Enable or disable logging emitted via the internal event system
   # c.events.enable_logging = false
+  #
+  # For audit logging, use the standard_audit gem. See the README for wiring instructions.
 
   # Social login credentials (if enabled in your app)
   # c.social.google_client_id     = ENV["GOOGLE_CLIENT_ID"]

data/lib/standard_id/api/session_manager.rb

@@ -12,7 +12,9 @@ module StandardId
 
       def current_account
         return unless current_session
-        @current_account ||= StandardId.account_class.find_by(id: current_session.account_id)
+        @current_account ||= StandardId.account_class
+          .find_by(id: current_session.account_id)
+          &.tap { |a| a.strict_loading!(false) }
       end
 
       def revoke_current_session!

data/lib/standard_id/api/token_manager.rb

@@ -30,12 +30,9 @@ module StandardId
       end
 
       def bearer_token
-        return @bearer_token if @bearer_token.present?
+        return @bearer_token if defined?(@bearer_token)
 
-        auth_header = @request.headers["Authorization"]
-        return unless auth_header&.start_with?("Bearer ")
-
-        @bearer_token = auth_header.split(" ", 2).last
+        @bearer_token = StandardId::BearerTokenExtraction.extract(@request.headers["Authorization"])
       end
 
       def verify_jwt_token(token: bearer_token)

data/lib/standard_id/bearer_token_extraction.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module StandardId
+  # Bearer token extraction utility.
+  #
+  # This module serves two roles:
+  #
+  # 1. **Class method** (`BearerTokenExtraction.extract`) — pure extraction
+  #    logic used by TokenManager in lib/. Lives in lib/ so there is no
+  #    cross-layer dependency on app/ autoloading.
+  #
+  # 2. **Controller mixin** (`include StandardId::BearerTokenExtraction`) —
+  #    provides `extract_bearer_token` as a private instance method.
+  #    Conventionally, controller concerns live under app/controllers/concerns/,
+  #    but this module is co-located with the utility to keep the extraction
+  #    logic in a single file and avoid the same-constant-name conflict
+  #    between lib/ and app/ autoloading.
+  #
+  # Does not use ActiveSupport::Concern because it has no `included` or
+  # `class_methods` blocks — it is a plain Ruby module.
+  #
+  # Controllers that include StandardId::ApiAuthentication do NOT need this —
+  # token extraction is handled internally by the TokenManager.
+  #
+  # @example As a controller concern
+  #   class McpController < ActionController::API
+  #     include StandardId::BearerTokenExtraction
+  #
+  #     def authenticate!
+  #       token = extract_bearer_token
+  #       # validate token...
+  #     end
+  #   end
+  #
+  # @example Direct class method (used by TokenManager)
+  #   StandardId::BearerTokenExtraction.extract(auth_header)
+  module BearerTokenExtraction
+    # Extracts the Bearer token from a raw Authorization header value.
+    #
+    # Note: prior to the introduction of this module, TokenManager#bearer_token
+    # returned "" for a bare "Bearer " header. This now returns nil via .presence,
+    # which is the correct behavior — downstream JWT parsing receives nil instead
+    # of attempting to decode an empty string.
+    #
+    # @param auth_header [String, nil] the raw Authorization header value
+    # @return [String, nil] the bearer token, or nil if not present/empty
+    def self.extract(auth_header)
+      return unless auth_header&.start_with?("Bearer ")
+
+      auth_header.split(" ", 2).last.presence
+    end
+
+    private
+
+    # Extracts the token from an "Authorization: Bearer <token>" header.
+    # Result is memoized for the lifetime of the controller instance.
+    #
+    # @return [String, nil] the bearer token, or nil if not present
+    def extract_bearer_token
+      return @_bearer_token if defined?(@_bearer_token)
+
+      @_bearer_token = StandardId::BearerTokenExtraction.extract(request.headers["Authorization"])
+    end
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -23,6 +23,8 @@ StandardConfig.schema.draw do
   end
 
   scope :passwordless do
+    field :enabled, type: :boolean, default: false
+    field :connection, type: :string, default: "email"
     field :code_ttl, type: :integer, default: 600 # 10 minutes in seconds
     field :max_attempts, type: :integer, default: 3
     field :retry_delay, type: :integer, default: 30 # 30 seconds

data/lib/standard_id/engine.rb

@@ -9,6 +9,11 @@ module StandardId
 
       StandardId::Events::Subscribers::AccountStatusSubscriber.attach
       StandardId::Events::Subscribers::AccountLockingSubscriber.attach
+
+      if StandardId.config.issuer.blank?
+        Rails.logger.warn("[StandardId] No issuer configured. JWT tokens will not include or verify the 'iss' claim. " \
+                          "Set StandardId.config.issuer in your initializer for production use.")
+      end
     end
   end
 end

data/lib/standard_id/errors.rb

@@ -1,22 +1,27 @@
 module StandardId
+  # Session errors
   class NotAuthenticatedError < StandardError; end
 
   class InvalidSessionError < StandardError; end
   class ExpiredSessionError < InvalidSessionError; end
   class RevokedSessionError < InvalidSessionError; end
+
+  # Account errors
   class AccountDeactivatedError < StandardError; end
 
   class AccountLockedError < StandardError
-    attr_reader :account, :lock_reason, :locked_at
+    # lock_reason and locked_at are available for logging and admin use.
+    # Avoid surfacing lock_reason in user-facing responses.
+    attr_reader :lock_reason, :locked_at
 
     def initialize(account)
-      @account = account
       @lock_reason = account.lock_reason
       @locked_at = account.locked_at
-      super("Account has been locked#{lock_reason ? ": #{lock_reason}" : ""}")
+      super("Account has been locked")
     end
   end
 
+  # OAuth errors
   class OAuthError < StandardError
     def oauth_error_code
       :invalid_request
@@ -64,4 +69,15 @@ module StandardId
   class UnsupportedResponseTypeError < OAuthError
     def oauth_error_code = :unsupported_response_type
   end
+
+  # Audience verification errors
+  class InvalidAudienceError < StandardError
+    attr_reader :required, :actual
+
+    def initialize(required:, actual:)
+      @required = required
+      @actual = actual
+      super("Token audience [#{actual.join(', ')}] does not match required audiences: #{required.join(', ')}")
+    end
+  end
 end

data/lib/standard_id/http_client.rb

@@ -3,19 +3,30 @@ require "uri"
 
 module StandardId
   class HttpClient
+    OPEN_TIMEOUT = 5
+    READ_TIMEOUT = 10
+
     class << self
       def post_form(endpoint, params)
         uri = URI(endpoint)
-        Net::HTTP.post_form(uri, params)
+        request = Net::HTTP::Post.new(uri)
+        request.set_form_data(params)
+        start_connection(uri) { |http| http.request(request) }
       end
 
       def get_with_bearer(endpoint, access_token)
         uri = URI(endpoint)
         request = Net::HTTP::Get.new(uri)
         request["Authorization"] = "Bearer #{access_token}"
-        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
-          http.request(request)
-        end
+        start_connection(uri) { |http| http.request(request) }
+      end
+
+      private
+
+      def start_connection(uri, &block)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                             open_timeout: OPEN_TIMEOUT,
+                                             read_timeout: READ_TIMEOUT, &block)
       end
     end
   end

data/lib/standard_id/oauth/password_flow.rb

@@ -76,6 +76,10 @@ module StandardId
           .includes(credential: :account)
           .find_by(login: username)
 
+        # Perform a dummy bcrypt comparison when the credential doesn't exist
+        # to prevent user enumeration via response timing differences.
+        BCrypt::Password.new(dummy_password_digest).is_password?(password) unless @credential
+
         @credential&.authenticate(password)&.account
       end
 
@@ -90,6 +94,10 @@ module StandardId
         end
       end
 
+      def dummy_password_digest
+        @dummy_password_digest ||= BCrypt::Password.create("").freeze
+      end
+
       def default_scope
         "read"
       end

data/lib/standard_id/oauth/token_lifetime_resolver.rb

@@ -1,17 +1,21 @@
 module StandardId
   module Oauth
     class TokenLifetimeResolver
-      class << self
-        DEFAULT_ACCESS_TOKEN_LIFETIME = 1.hour.to_i
-        DEFAULT_REFRESH_TOKEN_LIFETIME = 30.days.to_i
+      DEFAULT_ACCESS_TOKEN_LIFETIME = 1.hour.to_i
+      DEFAULT_REFRESH_TOKEN_LIFETIME = 30.days.to_i
+      MAX_ACCESS_TOKEN_LIFETIME = 24.hours.to_i
+      MAX_REFRESH_TOKEN_LIFETIME = 90.days.to_i
 
+      class << self
         def access_token_for(flow_key)
           configured = lookup_token_lifetime(flow_key)
-          positive_seconds(configured, default_access_token_lifetime)
+          lifetime = positive_seconds(configured, default_access_token_lifetime)
+          clamp_seconds(lifetime, MAX_ACCESS_TOKEN_LIFETIME)
         end
 
         def refresh_token_lifetime
-          positive_seconds(oauth_config.refresh_token_lifetime, DEFAULT_REFRESH_TOKEN_LIFETIME)
+          lifetime = positive_seconds(oauth_config.refresh_token_lifetime, DEFAULT_REFRESH_TOKEN_LIFETIME)
+          clamp_seconds(lifetime, MAX_REFRESH_TOKEN_LIFETIME)
         end
 
         private
@@ -41,6 +45,16 @@ module StandardId
           (normalized_value.positive? ? normalized_value : fallback_value).seconds
         end
 
+        def clamp_seconds(duration, max)
+          seconds = duration.to_i
+          if seconds > max
+            Rails.logger.warn { "[StandardId] Token lifetime #{seconds}s exceeds maximum #{max}s, clamping to #{max}s" }
+            max.seconds
+          else
+            duration
+          end
+        end
+
         def oauth_config
           StandardId.config.oauth
         end

data/lib/standard_id/passwordless/base_strategy.rb

@@ -34,7 +34,7 @@ module StandardId
           channel: connection_type,
           target: username,
           code: code,
-          expires_at: 10.minutes.from_now,
+          expires_at: StandardId.config.passwordless.code_ttl.seconds.from_now,
           ip_address: request.remote_ip,
           user_agent: request.user_agent
         )

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.2.9"
+  VERSION = "0.3.1"
 end

data/lib/standard_id/web/session_manager.rb

@@ -15,7 +15,7 @@ module StandardId
       end
 
       def current_account
-        Current.account ||= current_session&.account
+        Current.account ||= current_session&.account&.tap { |a| a.strict_loading!(false) }
       end
 
       def sign_in_account(account)

data/lib/standard_id.rb

@@ -13,6 +13,7 @@ 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/bearer_token_extraction"
 require "standard_id/jwt_service"
 require "standard_id/web/session_manager"
 require "standard_id/web/token_manager"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: StandardId is an authentication engine that provides a complete, secure-by-default
   solution for identity management, reducing boilerplate and eliminating common security
   pitfalls.
@@ -66,8 +80,10 @@ files:
 - app/assets/stylesheets/standard_id/application.css
 - app/channels/concerns/standard_id/cable_authentication.rb
 - app/controllers/concerns/standard_id/api_authentication.rb
+- app/controllers/concerns/standard_id/audience_verification.rb
 - app/controllers/concerns/standard_id/inertia_rendering.rb
 - app/controllers/concerns/standard_id/inertia_support.rb
+- app/controllers/concerns/standard_id/passwordless_strategy.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/social_login_params.rb
@@ -85,6 +101,7 @@ files:
 - app/controllers/standard_id/web/auth/callback/providers_controller.rb
 - app/controllers/standard_id/web/base_controller.rb
 - app/controllers/standard_id/web/login_controller.rb
+- app/controllers/standard_id/web/login_verify_controller.rb
 - app/controllers/standard_id/web/logout_controller.rb
 - app/controllers/standard_id/web/reset_password/confirm_controller.rb
 - app/controllers/standard_id/web/reset_password/start_controller.rb
@@ -101,6 +118,7 @@ files:
 - app/forms/standard_id/web/signup_form.rb
 - app/helpers/standard_id/application_helper.rb
 - app/jobs/standard_id/application_job.rb
+- app/jobs/standard_id/cleanup_expired_sessions_job.rb
 - app/mailers/standard_id/application_mailer.rb
 - app/models/concerns/standard_id/account_associations.rb
 - app/models/concerns/standard_id/credentiable.rb
@@ -123,10 +141,12 @@ files:
 - app/views/standard_id/web/account/show.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/login_verify/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
 - app/views/standard_id/web/sessions/index.html.erb
 - app/views/standard_id/web/signup/show.html.erb
+- config/brakeman.ignore
 - config/initializers/generators.rb
 - config/initializers/migration_helpers.rb
 - config/routes/api.rb
@@ -153,6 +173,7 @@ files:
 - lib/standard_id/api/session_manager.rb
 - lib/standard_id/api/token_manager.rb
 - lib/standard_id/api_engine.rb
+- lib/standard_id/bearer_token_extraction.rb
 - lib/standard_id/config/schema.rb
 - lib/standard_id/current_attributes.rb
 - lib/standard_id/engine.rb
@@ -214,7 +235,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A comprehensive authentication engine for Rails, built on the security primitives
   introduced in Rails 7/8.