standard_id 0.14.3 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ef63474df3107460650e529f2c8cf46ec3b0998f81db90ece5cf37d95ec14fc
-  data.tar.gz: 3c0e147ce91c2442d05157507d088aa8f1a6fcb52b7e38c4e15b2d5cb6da9fde
+  metadata.gz: b7231e9470123ff19809e493c1ebea4f84b573b3a39ca1a1f79f1e186a378fa1
+  data.tar.gz: 9dcc82b759903b33a2352e3849ff9044ca576b400e75f728f6c4bf49317011cd
 SHA512:
-  metadata.gz: 0571fe2ae8b0e429f8c9ab8d3f7f73e475e1395297d392460fce1d7db0d75b880baeebbd7e34befbba7e58fc37684255902ea1358b5bbed2be6b6e2a29489c36
-  data.tar.gz: 791d1b6618bd054da2e57b2ee7f626eb60af647070b1d075ceb1f274e92ec4b3912b601ec076af3ad81357f957c1dfa460810d448a628c93c1791b299b127be2
+  metadata.gz: 933f67b55905bd7b6ff421a77ff8b51ea3eab24ce84ed939e710b657b5e3838ead43ce0e0f2e9cdbfb58afb04f1d3f91e69e34ce335e13fdbccfd7161ec63600
+  data.tar.gz: 789d75aa20a6ff0305aa75140abc85d6dd4c7b7ffa42f85f06d3828429c1c763544359dc0519fc4c2ca8debdfa5e568411820b6a4846e86d2990a0b43c272101

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.
@@ -900,6 +950,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:

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

@@ -7,6 +7,11 @@ module StandardId
   # `allowed_audiences` list, this concern provides additional defense-in-depth
   # by restricting which audiences are accepted by each controller.
   #
+  # 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
   # at include time if ApiAuthentication is missing.
@@ -39,6 +44,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 +63,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 +78,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?
 
-      raise StandardId::InvalidAudienceError.new(
+      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
+
+      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)
@@ -198,13 +190,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/jobs/standard_id/cleanup_expired_authorization_codes_job.rb

@@ -0,0 +1,51 @@
+module StandardId
+  class CleanupExpiredAuthorizationCodesJob < ApplicationJob
+    queue_as :default
+
+    # Delete OAuth authorization codes that are either expired or consumed
+    # beyond the respective grace periods.
+    #
+    # Authorization codes are single-use and short-lived (OAuth 2.1 recommends
+    # a lifetime under 10 minutes). Two grace windows apply:
+    #
+    # - `grace_period_seconds` (default 7 days): how long expired-but-unused
+    #   codes are retained after `expires_at`. Matches the sessions/refresh-
+    #   token cleanup windows so operators only have to reason about one
+    #   default.
+    # - `consumed_grace_period_seconds` (default 1 day): how long consumed
+    #   codes are retained after `consumed_at`. Used codes are useless after
+    #   redemption, so they're pruned faster — keeping them briefly only
+    #   helps with replay-attack forensics in the immediate aftermath of a
+    #   redemption.
+    #
+    # Accepts integer seconds for reliable ActiveJob serialization across all
+    # queue adapters.
+    def perform(grace_period_seconds: 7.days.to_i, consumed_grace_period_seconds: 1.day.to_i)
+      expired_cutoff = grace_period_seconds.seconds.ago
+      consumed_cutoff = consumed_grace_period_seconds.seconds.ago
+
+      # The two windows govern disjoint sets of rows:
+      #   - Unconsumed codes: ruled by `expires_at < expired_cutoff`.
+      #   - Consumed codes:   ruled by `consumed_at < consumed_cutoff`.
+      #
+      # A naive `expires_at < :expired_cutoff OR consumed_at < :consumed_cutoff`
+      # would let the expired arm delete a consumed-12-hours-ago row whose
+      # `expires_at` sits 8 days in the past — defeating the consumed grace
+      # window's whole purpose. Scoping the expired clause to `consumed_at IS
+      # NULL` keeps consumed rows under the consumed window exclusively.
+      deleted = StandardId::AuthorizationCode
+        .where(
+          "(expires_at < :expired_cutoff AND consumed_at IS NULL) " \
+            "OR consumed_at < :consumed_cutoff",
+          expired_cutoff: expired_cutoff,
+          consumed_cutoff: consumed_cutoff
+        )
+        .delete_all
+
+      Rails.logger.info(
+        "[StandardId] Cleaned up #{deleted} authorization codes " \
+        "(expired before #{expired_cutoff}, consumed before #{consumed_cutoff})"
+      )
+    end
+  end
+end

data/app/jobs/standard_id/cleanup_expired_code_challenges_job.rb

@@ -0,0 +1,45 @@
+module StandardId
+  class CleanupExpiredCodeChallengesJob < ApplicationJob
+    queue_as :default
+
+    # Delete code challenges (OTP records) that are either expired or used
+    # beyond the respective grace periods.
+    #
+    # Code challenges back passwordless/OTP flows: rows are short-lived and
+    # single-use. Two grace windows apply:
+    #
+    # - `grace_period_seconds` (default 7 days): how long expired-but-unused
+    #   challenges are retained after `expires_at`. Matches the sessions/
+    #   refresh-token cleanup windows for operational consistency.
+    # - `used_grace_period_seconds` (default 1 day): how long used challenges
+    #   are retained after `used_at`. A used OTP is useless after redemption,
+    #   so prune faster — the short tail only helps with replay-attack
+    #   forensics immediately after use.
+    #
+    # Accepts integer seconds for reliable ActiveJob serialization across all
+    # queue adapters.
+    def perform(grace_period_seconds: 7.days.to_i, used_grace_period_seconds: 1.day.to_i)
+      expired_cutoff = grace_period_seconds.seconds.ago
+      used_cutoff = used_grace_period_seconds.seconds.ago
+
+      # See CleanupExpiredAuthorizationCodesJob for the rationale — the two
+      # windows govern disjoint sets of rows and a naive OR lets the expired
+      # arm prune recently-used challenges out from under the used grace
+      # window. Unused challenges follow `expires_at`; used challenges follow
+      # `used_at`.
+      deleted = StandardId::CodeChallenge
+        .where(
+          "(expires_at < :expired_cutoff AND used_at IS NULL) " \
+            "OR used_at < :used_cutoff",
+          expired_cutoff: expired_cutoff,
+          used_cutoff: used_cutoff
+        )
+        .delete_all
+
+      Rails.logger.info(
+        "[StandardId] Cleaned up #{deleted} code challenges " \
+        "(expired before #{expired_cutoff}, used before #{used_cutoff})"
+      )
+    end
+  end
+end

data/app/models/standard_id/code_challenge.rb

@@ -2,10 +2,15 @@ module StandardId
   class CodeChallenge < ApplicationRecord
     self.table_name = "standard_id_code_challenges"
 
+    # Well-known realms used by the engine itself. Host apps may create
+    # challenges in any realm (see StandardId::Otp) — realm is a free-form
+    # string that partitions challenges by purpose (e.g. "authentication",
+    # "verification", "custom_widget"). Only presence is validated so
+    # consumers can define their own realms without the engine knowing.
     REALMS = %w[authentication verification].freeze
     CHANNELS = %w[email sms].freeze
 
-    validates :realm, presence: true, inclusion: { in: REALMS }
+    validates :realm, presence: true
     validates :channel, presence: true, inclusion: { in: CHANNELS }
     validates :target, presence: true
     validates :code, presence: true

data/db/migrate/20260414200000_add_target_created_at_index_to_code_challenges.rb

@@ -0,0 +1,7 @@
+class AddTargetCreatedAtIndexToCodeChallenges < ActiveRecord::Migration[8.0]
+  def change
+    add_index :standard_id_code_challenges,
+      [:realm, :channel, :target, :created_at],
+      name: "index_code_challenges_on_target_created_at"
+  end
+end