standard_id 0.15.0 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7231e9470123ff19809e493c1ebea4f84b573b3a39ca1a1f79f1e186a378fa1
-  data.tar.gz: 9dcc82b759903b33a2352e3849ff9044ca576b400e75f728f6c4bf49317011cd
+  metadata.gz: 1cc415579c94e298230fc9d647869d7c2ea2b422b1130eac38bd05bba262956a
+  data.tar.gz: 653d1cd02170d5ba6933973635cb50d62729be158b0037812da8b2f832fb0c0e
 SHA512:
-  metadata.gz: 933f67b55905bd7b6ff421a77ff8b51ea3eab24ce84ed939e710b657b5e3838ead43ce0e0f2e9cdbfb58afb04f1d3f91e69e34ce335e13fdbccfd7161ec63600
-  data.tar.gz: 789d75aa20a6ff0305aa75140abc85d6dd4c7b7ffa42f85f06d3828429c1c763544359dc0519fc4c2ca8debdfa5e568411820b6a4846e86d2990a0b43c272101
+  metadata.gz: 16fa94e1dde5fa46e92999ef2fb24b5bb683ff5f5ab3e6549e91f8c738e4cdd42d8e872ab0d13705659ec6ab2bb4c4e184f4947c1d95bf5e00afbc3b9dfe0328
+  data.tar.gz: b730ef767275f8d71aa9b93a8c8fca55a1935c84e1e4e6eaf022ec935d2d152d7b72e99576b5075e3dffba8269b07be66abf43f4fd96e1f7728858d64244f7e2

data/README.md

@@ -529,6 +529,7 @@ Every StandardId event automatically carries tracing metadata (`event_id`, `time
 |  | `social.account.created` | `account`, `provider`, `social_info` | When a social login creates a new account |
 |  | `social.account.linked` | `account`, `provider`, `identifier` | When a social identity links to an existing account |
 |  | `social.auth.completed` | `account`, `provider`, `tokens` | After social login completes |
+|  | `social.auth.failed` | `provider`, `error`, `error_class`, `account` | When social login fails due to an infrastructure error (HTTP/DNS/SSL/timeout) |
 | Credential | `credential.password.created` | `credential`, `account` | After a password credential is created |
 |  | `credential.password.reset_initiated` | `credential`, `account`, `reset_token_expires_at` | After a password reset is initiated |
 |  | `credential.password.reset_completed` | `credential`, `account` | After a password reset is confirmed |
@@ -1109,9 +1110,17 @@ bundle exec rspec spec/controllers/
 - CSRF protection enabled for web requests
 - Secure session management with proper expiry
 - Client secrets are rotatable with audit trail
-- PKCE support for public clients
+- PKCE is enforced whenever `ClientApplication#require_pkce?` is true (the
+  default). Public clients cannot disable it — a model-level validation
+  rejects any public client saved with `require_pkce: false`. Authorize
+  requests that omit `code_challenge` for a PKCE-required client are
+  rejected with `invalid_request`.
 - Rate limiting on authentication endpoints
 
+## Scheduled Maintenance
+
+StandardId ships cleanup jobs (`StandardId::CleanupExpiredSessionsJob`, `StandardId::CleanupExpiredRefreshTokensJob`) and rake wrappers (`standard_id:cleanup:all`, `:sessions`, `:refresh_tokens`) to prune expired rows. See [docs/OPERATIONS.md](docs/OPERATIONS.md) for SolidQueue, sidekiq-cron, whenever, and system-cron scheduling examples.
+
 ## Contributing
 
 1. Fork the repository

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

@@ -3,9 +3,29 @@
 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.
+  # StandardId enforces audience in three layers:
+  #
+  #   1. At encode time (`Oauth::TokenGrantFlow#validate_audience!`):
+  #      rejects issuance of tokens with an audience outside the global
+  #      `StandardId.config.oauth.allowed_audiences` list.
+  #   2. At decode time (`JwtService.decode(..., allowed_audiences:)`):
+  #      rejects tokens whose `aud` claim does not match the caller-supplied
+  #      list, raising `StandardId::InvalidAudienceError`. The engine's
+  #      `Api::TokenManager#verify_jwt_token` wires this automatically when
+  #      `StandardId.config.oauth.allowed_audiences` is non-empty — a
+  #      mismatch there is normalised to the same 401 "invalid token"
+  #      response as a bad signature. Call sites that pass no arguments
+  #      to `decode` directly still skip aud checks by design.
+  #   3. At the controller, via this concern: layers on top as
+  #      per-endpoint defense-in-depth. Required when a controller serves
+  #      a strict subset of the global allowed audiences (e.g., the global
+  #      list is `%w[web api admin]` but `AdminController` must only
+  #      accept `admin`).
+  #
+  # With the global decode-time check now automatic, this concern is
+  # primarily useful for tightening the allowed audience per controller,
+  # not for plugging the "controller forgot to verify aud" gap (which
+  # is closed globally when `config.oauth.allowed_audiences` is set).
   #
   # In addition, when `StandardId.config.oauth.audience_profile_types` is set,
   # this concern enforces the audience → profile-type binding: after the

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

@@ -144,12 +144,27 @@ module StandardId
     end
 
     # Determine if this is the account's first browser session.
-    # When called before session creation (before_sign_in), count == 0 means first.
-    # When called after session creation (after_sign_in), count <= 1 means first
-    # (the just-created session is the only one).
+    # Uses `exists?` (which compiles to `SELECT 1 ... LIMIT 1`) instead of
+    # `count` — we only care whether *any other* active browser session is
+    # present, not the exact number. This short-circuits as soon as a row is
+    # found, so it's dramatically cheaper on accounts with many sessions.
+    #
+    # When called before session creation (before_sign_in), "first" means no
+    # active browser session exists at all.
+    # When called after session creation (after_sign_in), the just-created
+    # session counts as one, so "first" means no OTHER active browser session
+    # exists — i.e. exclude the current session before checking existence.
+    #
+    # Invariant: when `session_created: true`, `session_manager.current_session`
+    # is always set — invoke_after_sign_in runs immediately after
+    # session_manager.sign_in_account, which populates current_session. The
+    # nil guard below is defensive only; it would behave differently from the
+    # old `count <= 1` path (new: false, old: true) if that invariant were
+    # ever violated, but today no call site can reach it.
     def first_sign_in?(account, session_created: true)
-      active_count = account.sessions.where(type: "StandardId::BrowserSession").active.count
-      session_created ? active_count <= 1 : active_count == 0
+      scope = account.sessions.where(type: "StandardId::BrowserSession").active
+      scope = scope.where.not(id: session_manager.current_session.id) if session_created && session_manager.current_session
+      !scope.exists?
     end
 
     # Handle AuthenticationDenied by revoking the session and redirecting to login.

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

@@ -4,6 +4,7 @@ module StandardId
 
     included do
       before_action :set_current_request_details
+      after_action  :clear_rails_event_context
     end
 
     private
@@ -14,6 +15,38 @@ module StandardId
       ::Current.request_id = request.request_id if ::Current.respond_to?(:request_id=)
       ::Current.ip_address = StandardId::Utils::IpNormalizer.normalize(request.remote_ip) if ::Current.respond_to?(:ip_address=)
       ::Current.user_agent = request.user_agent if ::Current.respond_to?(:user_agent=)
+
+      set_rails_event_context
+    end
+
+    # Mirror request details into the Rails 8.1+ structured event reporter so
+    # that `Rails.event.notify` calls made during this request automatically
+    # carry request_id / ip_address / user_agent. Feature-detected: on older
+    # Rails versions this is a no-op. Reads straight from `::Current` — setters
+    # and getters on `ActiveSupport::CurrentAttributes` are paired, so the
+    # `respond_to?(:foo=)` checks above also guarantee the getter exists.
+    def set_rails_event_context
+      return unless defined?(::Current) && rails_event_available?
+
+      Rails.event.set_context(
+        request_id: (::Current.request_id if ::Current.respond_to?(:request_id)),
+        ip_address: (::Current.ip_address if ::Current.respond_to?(:ip_address)),
+        user_agent: (::Current.user_agent if ::Current.respond_to?(:user_agent))
+      )
+    end
+
+    # Rails 8.1 clears fiber-local state between requests via middleware, but
+    # thread-pooled servers (Puma, Falcon) can reuse the same fiber across
+    # requests. An explicit clear ensures a denied-upstream value cannot leak
+    # into the next request handled by the same worker.
+    def clear_rails_event_context
+      return unless rails_event_available?
+
+      Rails.event.clear_context
+    end
+
+    def rails_event_available?
+      Rails.respond_to?(:event) && Rails.event.respond_to?(:set_context)
     end
   end
 end

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

@@ -200,5 +200,24 @@ module StandardId
         source: "social"
       )
     end
+
+    # Emit SOCIAL_AUTH_FAILED for infrastructure-level failures during the
+    # social authentication flow (HTTP errors, DNS/SSL/timeouts surfaced as
+    # OAuthError by provider implementations).
+    #
+    # Host apps can subscribe to this event to forward failures to Sentry or
+    # similar observability tools without monkey-patching the controller.
+    #
+    # @param error [StandardId::OAuthError] the captured failure
+    # @param account [Object, nil] the account if one was resolved before the failure
+    def emit_social_auth_failed(error, account: nil)
+      StandardId::Events.publish(
+        StandardId::Events::SOCIAL_AUTH_FAILED,
+        provider: provider&.provider_name,
+        error: error.message,
+        error_class: error.class.name,
+        account: account
+      )
+    end
   end
 end

data/app/controllers/standard_id/api/oauth/revocations_controller.rb

@@ -29,15 +29,64 @@ module StandardId
           # revocation via sub claim regardless of token type (RFC 7009 §2.1)
           revoked_sessions = sessions.to_a
           if revoked_sessions.any?
+            now = Time.current
+            session_ids = revoked_sessions.map(&:id)
+
+            # Bulk-revoke in two queries (one UPDATE per table) instead of
+            # issuing session.revoke! per row, which would be O(N) UPDATEs plus
+            # another O(N) cascades to refresh_tokens.
+            #
+            # Tradeoff: update_all skips ActiveRecord callbacks, so the per-row
+            # SESSION_REVOKED event emitted by Session#revoke! is not fired
+            # automatically. We re-emit it explicitly below so audit-trail
+            # subscribers (account status/locking, etc.) still see one event
+            # per revoked session — the semantics are preserved, only the SQL
+            # shape has changed.
             ActiveRecord::Base.transaction do
-              revoked_sessions.each { |session| session.revoke!(reason: "token_revocation") }
+              StandardId::Session.where(id: session_ids).update_all(revoked_at: now)
+              StandardId::RefreshToken
+                .where(session_id: session_ids, revoked_at: nil)
+                .update_all(revoked_at: now)
+            end
+
+            # DB state is already committed above; event publishing is best-effort
+            # audit emission. A failing subscriber must not short-circuit the loop
+            # and leave later sessions without their SESSION_REVOKED event, which
+            # would permanently desync audit-trail consumers from the DB.
+            #
+            # All revoked_sessions share the same account_id (we filtered by it
+            # at line 25), so we load the account once rather than calling
+            # session.account per row, which would issue N extra SELECTs.
+            shared_account = revoked_sessions.first.account
+            revoked_sessions.each do |session|
+              session.revoked_at = now
+              begin
+                StandardId::Events.publish(
+                  StandardId::Events::SESSION_REVOKED,
+                  session: session,
+                  account: shared_account,
+                  reason: "token_revocation"
+                )
+              rescue StandardError => e
+                StandardId.logger.error(
+                  "[StandardId::Revocations] Failed to publish SESSION_REVOKED " \
+                  "for session #{session.id}: #{e.class}: #{e.message}"
+                )
+              end
             end
 
-            StandardId::Events.publish(
-              StandardId::Events::OAUTH_TOKEN_REVOKED,
-              account_id: account_id,
-              sessions_revoked: revoked_sessions.size
-            )
+            begin
+              StandardId::Events.publish(
+                StandardId::Events::OAUTH_TOKEN_REVOKED,
+                account_id: account_id,
+                sessions_revoked: revoked_sessions.size
+              )
+            rescue StandardError => e
+              StandardId.logger.error(
+                "[StandardId::Revocations] Failed to publish OAUTH_TOKEN_REVOKED " \
+                "for account #{account_id}: #{e.class}: #{e.message}"
+              )
+            end
           end
 
           head :ok

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

@@ -26,15 +26,19 @@ module StandardId
 
       private
 
+      # All Session subclasses live on the same STI table and therefore
+      # always respond to these columns — the prior `respond_to?` guards
+      # were defensive overhead that allocated per record. Direct access
+      # is both cheaper and clearer.
       def serialize_session(session)
         {
           id: session.id,
           type: session.type&.demodulize,
           created_at: session.created_at.iso8601,
-          last_refreshed_at: session.respond_to?(:last_refreshed_at) ? session.last_refreshed_at&.iso8601 : nil,
-          ip_address: session.respond_to?(:ip_address) ? session.ip_address : nil,
+          last_refreshed_at: session.last_refreshed_at&.iso8601,
+          ip_address: session.ip_address,
           # user_agent is the API-facing name for the device_agent model attribute
-          user_agent: session.respond_to?(:device_agent) ? session.device_agent : nil
+          user_agent: session.device_agent
         }.compact
       end
     end

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

@@ -61,7 +61,13 @@ module StandardId
               redirect_to destination, redirect_options
             rescue StandardId::AuthenticationDenied => e
               handle_authentication_denied(e, account: account, newly_created: newly_created)
+            rescue StandardId::SocialLinkError => e
+              # Policy/link error — SOCIAL_LINK_BLOCKED has already been emitted
+              # by validate_social_link!, so do not also emit SOCIAL_AUTH_FAILED
+              # (which is reserved for infrastructure-level failures).
+              redirect_to StandardId::WebEngine.routes.url_helpers.login_path(redirect_uri: state_data&.dig("redirect_uri")), alert: "Authentication failed: #{e.message}"
             rescue StandardId::OAuthError => e
+              emit_social_auth_failed(e, account: account)
               redirect_to StandardId::WebEngine.routes.url_helpers.login_path(redirect_uri: state_data&.dig("redirect_uri")), alert: "Authentication failed: #{e.message}"
             end
           end

data/app/controllers/standard_id/web/reset_password/start_controller.rb

@@ -14,7 +14,10 @@ module StandardId
         end
 
         def create
-          form = StandardId::Web::ResetPasswordStartForm.new(email: params[:email])
+          form = StandardId::Web::ResetPasswordStartForm.new(
+            email: params[:email],
+            reset_url_template: build_reset_url_template
+          )
 
           if form.submit
             flash[:notice] = "If an account with that email exists, we've sent password reset instructions."
@@ -24,6 +27,29 @@ module StandardId
             render :show, status: :unprocessable_content
           end
         end
+
+        private
+
+        # Build a password-reset URL template containing a literal "{token}"
+        # placeholder. The async delivery job substitutes the placeholder with
+        # the generated token once the account lookup completes. We build this
+        # here (rather than in the job) so the URL reflects the request's
+        # scheme/host/port — the job has no access to the HTTP request.
+        #
+        # The route helper may be absent if the host app mounts the engine
+        # without the `:password_reset` mechanism, or raise UrlGenerationError
+        # if required params are missing; fall back to a request-derived URL
+        # in those cases. Any other exception should surface normally.
+        def build_reset_url_template
+          base = begin
+            reset_password_confirm_url
+          rescue NameError, NoMethodError, ActionController::UrlGenerationError
+            nil
+          end
+          base ||= "#{request.base_url}/reset_password/confirm"
+          separator = base.include?("?") ? "&" : "?"
+          "#{base}#{separator}token={token}"
+        end
       end
     end
   end

data/app/controllers/standard_id/web/verify_email/start_controller.rb

@@ -32,7 +32,7 @@ module StandardId
             realm: "verification",
             channel: "email",
             target: email,
-            code: generate_otp_code,
+            code: StandardId::Passwordless.generate_otp_code,
             expires_at: 10.minutes.from_now,
             ip_address: StandardId::Utils::IpNormalizer.normalize(request.remote_ip),
             user_agent: request.user_agent
@@ -42,12 +42,6 @@ module StandardId
 
           redirect_to standard_id_web.login_path, notice: "Verification code sent to your email", status: :see_other
         end
-
-        private
-
-        def generate_otp_code
-          (SecureRandom.random_number(900_000) + 100_000).to_s
-        end
       end
     end
   end

data/app/controllers/standard_id/web/verify_phone/start_controller.rb

@@ -32,7 +32,7 @@ module StandardId
             realm: "verification",
             channel: "sms",
             target: phone,
-            code: generate_otp_code,
+            code: StandardId::Passwordless.generate_otp_code,
             expires_at: 10.minutes.from_now,
             ip_address: StandardId::Utils::IpNormalizer.normalize(request.remote_ip),
             user_agent: request.user_agent
@@ -42,12 +42,6 @@ module StandardId
 
           redirect_to standard_id_web.login_path, notice: "Verification code sent via SMS", status: :see_other
         end
-
-        private
-
-        def generate_otp_code
-          (SecureRandom.random_number(900_000) + 100_000).to_s
-        end
       end
     end
   end

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

@@ -6,32 +6,33 @@ module StandardId
 
       attribute :email, :string
 
-      attr_reader :password_credential, :token
-
       validates :email, presence: { message: "Please enter your email address" }, format: { with: URI::MailTo::EMAIL_REGEXP }
 
-      def submit
-        return false unless valid?
-
-        if token.present?
-          # TODO: send reset link via email
-        end
-
-        true
+      # Constructor accepts the reset URL template so the form is decoupled
+      # from routing. The controller builds a URL from `reset_password_confirm_url`
+      # (or a request-derived fallback) and appends a literal `?token={token}` (or
+      # `&token={token}`) marker via string concatenation. The delivery job
+      # substitutes that placeholder with the actual token after account lookup.
+      def initialize(attributes = {})
+        @reset_url_template = attributes.delete(:reset_url_template) if attributes.is_a?(Hash)
+        super
       end
 
-      def password_credential
-        @password_credential ||= identifier&.account&.credentials&.where(credentialable_type: "StandardId::PasswordCredential")&.sole&.credentialable
-      end
+      attr_reader :reset_url_template
 
-      def token
-        @token ||= password_credential&.generate_token_for(:password_reset)
-      end
+      def submit
+        return false unless valid?
 
-      private
+        # Enqueue the full lookup + token generation + mailer delivery pipeline
+        # so the controller response time does not depend on whether an account
+        # exists for the submitted email. This closes the user-enumeration
+        # timing side channel.
+        StandardId::PasswordResetDeliveryJob.perform_later(
+          email: email.to_s,
+          reset_url_template: reset_url_template.to_s
+        )
 
-      def identifier
-        @identifier ||= StandardId::EmailIdentifier.find_by(value: email.to_s.strip.downcase)
+        true
       end
     end
   end

data/app/jobs/standard_id/password_reset_delivery_job.rb

@@ -0,0 +1,42 @@
+module StandardId
+  # Handles the full password-reset email delivery pipeline asynchronously.
+  #
+  # Running this work in a job (rather than inline in the request) eliminates
+  # the timing side-channel that would otherwise leak whether an account
+  # exists for a given email: every request enqueues the same job, so the
+  # synchronous request path is constant-time regardless of account state.
+  class PasswordResetDeliveryJob < ApplicationJob
+    queue_as :default
+
+    # @param email [String] the raw email submitted by the user
+    # @param reset_url_template [String] URL with a literal "{token}" placeholder
+    #   that the job will substitute with the generated reset token
+    def perform(email:, reset_url_template:)
+      normalized = email.to_s.strip.downcase
+      return if normalized.blank?
+
+      identifier = StandardId::EmailIdentifier.find_by(value: normalized)
+      return if identifier.nil?
+
+      password_credential = identifier.account
+        &.credentials
+        &.where(credentialable_type: "StandardId::PasswordCredential")
+        &.first
+        &.credentialable
+      return if password_credential.nil?
+
+      token = password_credential.generate_token_for(:password_reset)
+      return if token.blank?
+
+      reset_url = reset_url_template.to_s.sub("{token}", token)
+
+      StandardId::Events.publish(
+        StandardId::Events::CREDENTIAL_PASSWORD_RESET_INITIATED,
+        account: identifier.account,
+        identifier: normalized,
+        token: token,
+        reset_url: reset_url
+      )
+    end
+  end
+end

data/app/mailers/standard_id/password_reset_mailer.rb

@@ -0,0 +1,16 @@
+module StandardId
+  class PasswordResetMailer < ApplicationMailer
+    layout false
+
+    def reset_email
+      @reset_url = params[:reset_url]
+      @email = params[:email]
+
+      mail(
+        to: @email,
+        from: StandardId.config.reset_password.mailer_from,
+        subject: StandardId.config.reset_password.mailer_subject
+      )
+    end
+  end
+end

data/app/models/concerns/standard_id/account_associations.rb

@@ -12,6 +12,31 @@ module StandardId
       accepts_nested_attributes_for :identifiers
     end
 
+    # Returns the account's StandardId::EmailIdentifier, if any.
+    #
+    # Uses the in-memory collection when identifiers is already loaded to
+    # avoid issuing an extra query (N+1 safety). Falls back to a scoped
+    # query otherwise.
+    #
+    # @return [StandardId::EmailIdentifier, nil]
+    def email_identifier
+      typed_identifier(StandardId::EmailIdentifier)
+    end
+
+    # Returns the account's StandardId::PhoneNumberIdentifier, if any.
+    #
+    # @return [StandardId::PhoneNumberIdentifier, nil]
+    def phone_number_identifier
+      typed_identifier(StandardId::PhoneNumberIdentifier)
+    end
+
+    # Returns the account's StandardId::UsernameIdentifier, if any.
+    #
+    # @return [StandardId::UsernameIdentifier, nil]
+    def username_identifier
+      typed_identifier(StandardId::UsernameIdentifier)
+    end
+
     class_methods do
       def find_or_create_by_verified_email!(email, **account_attributes)
         raise ArgumentError, "email is required" if email.blank?
@@ -54,5 +79,23 @@ module StandardId
         identifier.account
       end
     end
+
+    private
+
+    # Fetch the first identifier of the given STI subclass.
+    #
+    # When the identifiers association is already loaded, filters in memory
+    # to avoid triggering an additional query. Otherwise issues a scoped
+    # query that returns at most one row.
+    #
+    # @param klass [Class] subclass of StandardId::Identifier
+    # @return [StandardId::Identifier, nil]
+    def typed_identifier(klass)
+      if association(:identifiers).loaded?
+        identifiers.detect { |i| i.is_a?(klass) }
+      else
+        identifiers.where(type: klass.sti_name).first
+      end
+    end
   end
 end

data/app/models/standard_id/authorization_code.rb

@@ -18,9 +18,22 @@ module StandardId
 
     def self.issue!(plaintext_code:, client_id:, redirect_uri:, scope: nil, audience: nil, account: nil, code_challenge: nil, code_challenge_method: nil, nonce: nil, metadata: {})
       # Fail fast: reject unsupported PKCE methods at issuance rather than
-      # storing a code that will always fail at redemption time.
+      # storing a code that will always fail at redemption time. When the
+      # client record has PKCE required, defer to the client's configured
+      # `code_challenge_methods`. In all other cases (client lookup missing,
+      # or client opted out of PKCE but still sent a challenge) fall back
+      # to an S256-only belt-and-suspenders check so we never silently
+      # accept a weaker method.
       if code_challenge.present?
-        unless code_challenge_method.to_s.downcase == "s256"
+        client = StandardId::ClientApplication.find_by(client_id: client_id)
+        method_supported =
+          if client&.require_pkce?
+            client.supports_pkce_method?(code_challenge_method)
+          else
+            code_challenge_method.to_s.downcase == "s256"
+          end
+
+        unless method_supported
           raise StandardId::InvalidRequestError, "Unsupported code_challenge_method: only S256 is allowed"
         end
       end