standard_id 0.14.4 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47ce66e4e4b242fd96a90cda7b20a9316e31642551ebe6c94ae660336f8f0b2c
-  data.tar.gz: a1a6d6f746f2ef0590aec0b5d6c4cc51472e04030af53e30d8546495d2556f03
+  metadata.gz: 9e4d6c462fcdc585b2eefb2c5224e92c7b2a9fe276c2a41ccbfd6bf7b1fee162
+  data.tar.gz: 91dde301a0e98b0ec60f704ff5beb03706f5f1dbf36ebdfddfc3e21cf322f5ea
 SHA512:
-  metadata.gz: f323ce02474f8d4fc98a8aa4466616f15e58b9a5f6174336c91c0f9bc02c22e95862909963d0470271b49dc588fb0abcfcd2434c17a7ece79952d7547ed81ddf
-  data.tar.gz: 03a24d819ad4f699be3d97ce26e8dcf04873b373ff55c03e31f0de475a014198053a1927bf6539de40c0398855490be01ea4bc77dbe093d1f381f67eddfb8608
+  metadata.gz: f01caba2626cf9e4c8f4950aeeece214277492d74701f6359268da79cdf4234853f86a5490d33ab250dfe2cdda04e73c9c86a2896dc7ff76e3ab36e529da3cce
+  data.tar.gz: 519d061ab666d5d7a197819545bc9dcd5c304946074b80eaf89dca57898e7c24d6ccbde1b94155095e2ca382340b9179a62c2d2791331345d572ab826b88c8c7

data/README.md

@@ -404,6 +404,56 @@ Event payload includes:
 
 > **Note**: If you're using the deprecated `passwordless_email_sender` or `passwordless_sms_sender` callbacks, see the [Migration Guide](docs/MIGRATION_GUIDE.md) for upgrade instructions.
 
+### Using OTP for non-authentication flows
+
+The same hardened OTP machinery (enumeration defense, atomic attempt tracking, pessimistic locking, bypass_code hook) is exposed as a public primitive via `StandardId::Otp`. Use it when you need one-time codes for purposes *other* than authentication — contact verification widgets, step-up challenges, custom confirmation flows, etc.
+
+```ruby
+# Issue a code — caller handles delivery
+result = StandardId::Otp.issue(
+  realm: "widget_contact_verification",
+  target: "user@example.com",
+  channel: :email,
+  request: request,
+  delivery: :manual
+)
+
+MyMailer.widget_otp(result.challenge.target, result.code).deliver_later
+
+# Verify the code
+result = StandardId::Otp.verify(
+  realm: "widget_contact_verification",
+  target: params[:email],
+  channel: :email,
+  code: params[:otp],
+  request: request
+)
+
+if result.success?
+  # Code is valid — proceed with the action.
+else
+  case result.error_code
+  when :not_found, :invalid_code then render_error("Invalid code")
+  when :expired                  then render_error("Code expired")
+  when :max_attempts             then render_error("Too many attempts")
+  end
+end
+```
+
+**Delivery modes for `Otp.issue`:**
+
+| Mode        | Behavior                                                                 |
+|-------------|--------------------------------------------------------------------------|
+| `:built_in` | Uses the engine's bundled `PasswordlessMailer` (email only).             |
+| `:custom`   | Invokes `passwordless_email_sender` / `passwordless_sms_sender` callback.|
+| `:manual`   | Skips delivery; returns the raw `code` on the result for caller to deliver. |
+
+**Realm isolation.** `realm:` is a free-form string that partitions challenges by purpose. A code issued for realm `"widget_contact_verification"` cannot be used to verify against realm `"authentication"` (or any other realm) — even for the same `target`. Choose a stable string per flow.
+
+**Bypass code (E2E testing).** When `StandardId.config.passwordless.bypass_code` is set (and `Rails.env` is not `"production"`), `Otp.verify` accepts the bypass code for **any realm**. This replaces per-app bypass ENV checks and works consistently across `Otp.verify` and the built-in passwordless login flow. Never set `bypass_code` in production — it will raise if you try.
+
+**Back-compat.** The existing passwordless authentication flow continues to work unchanged. `Otp.issue`/`Otp.verify` are a new addition — you can migrate direct `CodeChallenge.create!` calls at your own pace.
+
 ## Event System
 
 StandardId emits events throughout the authentication lifecycle using `ActiveSupport::Notifications`. This enables decoupled handling of cross-cutting concerns like logging, analytics, audit trails, and webhooks.
@@ -479,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 |
@@ -900,6 +951,60 @@ class Api::UsersController < ApiController
 end
 ```
 
+## Primitives
+
+StandardId also ships a couple of thin, config-free JWT primitives for use cases
+that have nothing to do with OAuth sessions — for example, service-to-service
+tokens between two of your own backends.
+
+### `JwtService.sign` / `JwtService.verify`
+
+These are low-level wrappers around `JWT.encode` / `JWT.decode`. They do **not**
+read `StandardId.config` — you supply the algorithm and key directly, and you
+control the full payload. No `iss`, `aud`, or `iat` is added for you.
+
+```ruby
+# Sign an HS256 service token
+token = StandardId::JwtService.sign(
+  { sub: "harness", aud: "sidekick", gid: "gid://..." },
+  algorithm: "HS256",
+  key: Rails.application.credentials.dig(:service_jwt, :secret),
+  expires_in: 5.minutes
+)
+
+# Verify it on the receiving side
+payload = StandardId::JwtService.verify(
+  token,
+  algorithm: "HS256",
+  key: Rails.application.credentials.dig(:service_jwt, :secret),
+  allowed_audiences: %w[sidekick]
+)
+payload["sub"]  # => "harness"
+```
+
+Supports:
+
+- HS256 / HS384 / HS512, RS256 / RS384 / RS512, ES256 / ES384 / ES512
+- `expires_in:` to auto-set `exp` (caller-supplied `exp` wins)
+- Arbitrary JWT headers via `**extra_headers` (e.g. `kid:`)
+- `allowed_audiences:` to enforce the `aud` claim
+- `key:` as a single value or an `Array` — keys are tried in order, so rotation
+  is a one-liner
+- Failure raises `StandardId::InvalidTokenError` (with subclasses
+  `ExpiredTokenError`, `InvalidSignatureError`, `InvalidAlgorithmError`,
+  `InvalidAudienceTokenError`) — no `nil` returns
+
+### When to use which
+
+| Use case | API |
+|---|---|
+| OAuth 2.0 / OIDC access and ID tokens, browser/device sessions | `JwtService.encode` / `.decode` / `.decode_session` |
+| Anything else (service-to-service, internal signed payloads, webhooks) | `JwtService.sign` / `.verify` |
+
+The OAuth/session methods consult `StandardId.config` (issuer, signing key,
+rotation, claim resolvers, etc.) and add standard claims automatically. The
+primitives deliberately do none of that.
+
 ## Database Schema
 
 StandardId creates the following tables:
@@ -1005,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,34 @@
 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
+  # allowed-audience check, it resolves the current account's profile for the
+  # matched audience and rejects requests whose profile type does not match.
   #
   # Requires StandardId::ApiAuthentication to be included before this concern
   # (provides `verify_access_token!` and `current_session`). An error is raised
@@ -39,6 +64,7 @@ module StandardId
       before_action :verify_audience!
 
       rescue_from StandardId::InvalidAudienceError, with: :handle_invalid_audience
+      rescue_from StandardId::InvalidAudienceProfileError, with: :handle_invalid_audience
 
       # Underscore prefix follows Rails class_attribute convention to avoid
       # collisions with application method names.
@@ -57,10 +83,13 @@ module StandardId
 
     private
 
-    # Verifies the token's `aud` claim contains at least one of the required audiences.
+    # Verifies the token's `aud` claim contains at least one of the required audiences,
+    # then enforces audience → profile-type binding when configured.
     # Supports both string and array `aud` claims.
     #
     # @raise [StandardId::InvalidAudienceError] when no audience matches
+    # @raise [StandardId::InvalidAudienceProfileError] when the account's
+    #   profile type does not match the configured binding for the matched audience
     def verify_audience!
       return if _required_audiences.empty?
 
@@ -69,29 +98,109 @@ module StandardId
       return unless current_session
 
       token_audiences = Array(current_session.aud)
-      return if (token_audiences & _required_audiences).any?
+      matched = (token_audiences & _required_audiences).first
+
+      if matched.nil?
+        raise StandardId::InvalidAudienceError.new(
+          required: _required_audiences,
+          actual: token_audiences
+        )
+      end
+
+      enforce_audience_profile_binding!(matched, token_audiences)
+    end
+
+    # Enforce `audience_profile_types[matched]` against the current account.
+    # No-op when the audience has no binding configured (back-compat).
+    def enforce_audience_profile_binding!(matched_audience, token_audiences)
+      expected_types = StandardId::Oauth::AudienceProfileResolver.profile_types_for(matched_audience)
+      return if expected_types.empty?
+
+      profile = StandardId::Oauth::AudienceProfileResolver.call(
+        account: current_account,
+        audience: matched_audience
+      )
+      actual_type = profile_type_name(profile)
+
+      return if actual_type && expected_types.include?(actual_type)
+
+      # For audit purposes, when there is no matching profile, report the
+      # first profile type the account actually has (if any) so operators can
+      # see what the client was carrying instead.
+      actual_type ||= fallback_actual_profile_type
 
-      raise StandardId::InvalidAudienceError.new(
+      error = StandardId::InvalidAudienceProfileError.new(
+        audience: matched_audience,
+        expected_profile_types: expected_types,
+        actual_profile_type: actual_type,
         required: _required_audiences,
         actual: token_audiences
       )
+      emit_audience_mismatch(error)
+      raise error
+    end
+
+    def profile_type_name(profile)
+      return nil if profile.nil?
+      return profile.profileable_type.to_s if profile.respond_to?(:profileable_type)
+      return profile.type.to_s if profile.respond_to?(:type)
+
+      profile.class.name.to_s
+    end
+
+    # When no matching profile exists for the audience, surface the first
+    # profile type the account carries (if any) to aid debugging/audit. This
+    # never changes the decision — the mismatch is already confirmed when
+    # this is called — it only enriches the error/event payload.
+    def fallback_actual_profile_type
+      account = current_account
+      return nil if account.nil? || !account.respond_to?(:profiles)
+
+      candidates = account.profiles
+      candidates = candidates.to_a unless candidates.is_a?(Array)
+      first = candidates.first
+      profile_type_name(first)
+    end
+
+    def emit_audience_mismatch(error)
+      StandardId::Events.publish(
+        StandardId::Events::OAUTH_AUDIENCE_MISMATCH,
+        audience: error.audience,
+        token_audiences: error.actual,
+        required_audiences: error.required,
+        expected_profile_types: error.expected_profile_types,
+        actual_profile_type: error.actual_profile_type,
+        account: (current_account if respond_to?(:current_account, true))
+      )
+    rescue StandardError => e
+      StandardId.config.logger&.warn(
+        "[StandardId] failed to emit oauth.audience.mismatch event: #{e.class}: #{e.message}"
+      )
     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.
+    # Both the header AND the JSON body use a static description rather
+    # than interpolating error.message, which contains raw aud values
+    # from the JWT and internal profile type names. Exposing those lets
+    # an attacker probe valid tokens across audiences to enumerate the
+    # internal profile-type taxonomy. Details are published as an
+    # OAUTH_AUDIENCE_MISMATCH audit event for server-side inspection.
     #
     # Override in your controller for custom error formatting.
-    def handle_invalid_audience(error)
+    GENERIC_INSUFFICIENT_SCOPE_MESSAGE = "The access token audience is not permitted for this resource".freeze
+
+    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"'
+        %(Bearer error="insufficient_scope", error_description="#{GENERIC_INSUFFICIENT_SCOPE_MESSAGE}")
       )
-      render json: { error: "insufficient_scope", error_description: error.message }, status: :forbidden
+      render json: {
+        error: "insufficient_scope",
+        error_description: GENERIC_INSUFFICIENT_SCOPE_MESSAGE
+      }, status: :forbidden
     end
   end
 end

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

@@ -33,6 +33,10 @@ module StandardId
     # Default profile resolver when StandardId.config.profile_resolver is nil.
     DEFAULT_PROFILE_RESOLVER = ->(acct, pt) { acct.profiles.exists?(profileable_type: pt) }
 
+    # Default scope resolver when StandardId.config.scope_resolver is nil.
+    # Preserves the historical behaviour of reading :scope from route defaults.
+    DEFAULT_SCOPE_RESOLVER = ->(request:, session:) { request.path_parameters[:scope]&.to_sym }
+
     private
 
     # Invoke the before_sign_in hook if configured.
@@ -48,25 +52,23 @@ module StandardId
     #   - :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
+    #   - :profile_type [String, nil] first configured profile type for the scope (back-compat)
+    #   - :profile_types [Array<String>, nil] all configured profile types for the scope
     #   - :after_sign_in_path [String, nil] default redirect path for the scope
     # @return [void]
     # @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
+        context = context.merge(scope_context(scope_config))
+
+        # Built-in profile check and/or authorizer — runs before the app's custom hook.
+        # A scope may configure :authorizer without :profile_types (e.g. policy-only
+        # gates), so we must still run validate_scope_profile! in that case —
+        # otherwise the authorizer would be silently skipped and every sign-in
+        # granted regardless of its decision.
+        if scope_config.requires_profile? || scope_config.authorizer?
+          validate_scope_profile!(account, scope_config)
         end
       end
 
@@ -95,19 +97,14 @@ module StandardId
     #   - :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
+    #   - :profile_type [String, nil] first configured profile type for the scope (back-compat)
+    #   - :profile_types [Array<String>, nil] all configured profile types 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)
       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
+      context = context.merge(scope_context(scope_config)) if scope_config
 
       hook = StandardId.config.after_sign_in
       context = context.merge(
@@ -132,18 +129,13 @@ module StandardId
     #   - :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
+    #   - :profile_type [String, nil] first configured profile type for the scope (back-compat)
+    #   - :profile_types [Array<String>, nil] all configured profile types 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
+      context = context.merge(scope_context(scope_config)) if scope_config
 
       hook = StandardId.config.after_account_created
       return unless hook.respond_to?(:call)
@@ -152,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.
@@ -198,13 +205,87 @@ module StandardId
       end
     end
 
+    # Resolve the active scope name for the current request.
+    # Delegates to the app-configured :scope_resolver callable so apps can source
+    # the scope from subdomains, session state, or custom path params without
+    # overriding this concern.
+    # Memoized per request.
+    def current_scope_name
+      return @current_scope_name if defined?(@current_scope_name)
+      resolver = StandardId.config.scope_resolver
+      resolver = DEFAULT_SCOPE_RESOLVER unless resolver.respond_to?(:call)
+      session = session_manager.respond_to?(:current_session) ? session_manager.current_session : nil
+      @current_scope_name = resolver.call(request: request, session: session)
+    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])
+      @current_scope_config = StandardId.scope_for(current_scope_name)
+    end
+
+    # Validate that the account has a profile matching one of the scope's configured
+    # profile_types, then (when configured) run the scope's custom :authorizer callable.
+    #
+    # Raises StandardId::AuthenticationDenied using the scope's no_profile_message when:
+    #   - no profile of any configured type exists, or
+    #   - the :authorizer returns a falsey value.
+    def validate_scope_profile!(account, scope_config)
+      resolver = StandardId.config.profile_resolver || DEFAULT_PROFILE_RESOLVER
+      matched_type = nil
+
+      if scope_config.requires_profile?
+        matched_type = scope_config.profile_types.find { |type| resolver.call(account, type) }
+
+        unless matched_type
+          raise StandardId::AuthenticationDenied, scope_config.no_profile_message
+        end
+      end
+
+      return unless scope_config.authorizer?
+
+      profile = matched_type ? resolve_profile_for_authorizer(account, matched_type) : nil
+      result = scope_config.authorizer.call(
+        account: account,
+        profile: profile,
+        scope: scope_config
+      )
+
+      unless result
+        raise StandardId::AuthenticationDenied, scope_config.no_profile_message
+      end
+    end
+
+    # Best-effort lookup of the matched profile record to pass into the :authorizer.
+    # Returns nil when the account does not expose a :profiles association of the
+    # expected shape — authorizers that need richer context can re-query from the
+    # account keyword arg.
+    #
+    # Rescue is narrowed to the structural cases we actually want to tolerate
+    # (missing methods / wrong types on a shape-mismatched association). DB-level
+    # errors are intentionally allowed to propagate so a transient outage isn't
+    # silently converted into "no profile found" and a denied sign-in.
+    def resolve_profile_for_authorizer(account, profile_type)
+      return nil unless account.respond_to?(:profiles)
+      relation = account.profiles
+      return nil unless relation.respond_to?(:find_by)
+      relation.find_by(profileable_type: profile_type)
+    rescue NoMethodError, TypeError
+      nil
+    end
+
+    # Build the hash of scope fields merged into lifecycle hook context.
+    # Includes the legacy :profile_type (singular) alongside :profile_types (plural)
+    # so existing hooks keep reading the same key.
+    def scope_context(scope_config)
+      {
+        scope: scope_config.name,
+        profile_type: scope_config.profile_type,
+        profile_types: scope_config.profile_types,
+        after_sign_in_path: scope_config.after_sign_in_path
+      }
     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/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