standard_id 0.29.1 → 0.31.0

data/README.md

@@ -164,6 +164,56 @@ end
 
 `default_token_lifetime` is applied to every OAuth grant unless you override it in `oauth.token_lifetimes`. Keys map to OAuth grant types (for example `:password`, `:client_credentials`, `:refresh_token`) and should return durations in seconds. Non-token endpoint flows such as the implicit flow can be customized with their symbol key (e.g. `:implicit`). Refresh tokens can be tuned separately through `oauth.refresh_token_lifetime`.
 
+### OAuth Hardening Options
+
+Two spec-conformance settings default to the historical (looser) behaviour so
+that upgrading the gem never changes what a live client sees. **New
+deployments should turn both on.**
+
+```ruby
+StandardId.configure do |config|
+  # RFC 6749 §4.1.3 — reject a token exchange that omits redirect_uri when the
+  # authorization request included one. Default: false (accepted, with a
+  # warning logged naming the client_id). Watch your logs for that warning;
+  # once it stops appearing, flip this to true.
+  config.oauth.strict_redirect_uri_matching = true
+
+  # RFC 7009 — how much POST /oauth/revoke revokes.
+  #   :account (default) revokes EVERY active DeviceSession for the token's
+  #     subject, whichever token was presented — one client's logout signs the
+  #     account out everywhere.
+  #   :grant revokes only the authorization grant behind the presented token:
+  #     the refresh-token family its `jti` resolves to, plus that grant's
+  #     Session when one is linked.
+  config.oauth.revocation_scope = :grant
+end
+```
+
+Under `:grant`, revoking a **stateless access token is a no-op** — this engine
+has no per-access-token store, so it cannot invalidate one before its `exp`
+(the response is still `200`, per RFC 7009 §2.2). Clients that need revocation
+to bite must present the **refresh token**. `token_type_hint` is accepted and
+unused under both settings: the lookup is by `jti`, which is type-agnostic, and
+a wrong hint must not change the outcome.
+
+`ServiceSession`s are never touched by `/oauth/revoke` under either setting —
+machine credentials have their own lifecycle.
+
+### Authenticating Opaque Session Tokens
+
+`Session.by_token` is a **lookup**, not authentication: it matches the SHA256
+`lookup_hash` (an index key). The credential is the BCrypt `token_digest`.
+Use `authenticate_by_token`, which does both and compares in constant time:
+
+```ruby
+session = StandardId::Session.api_compatible.active.authenticate_by_token(token)
+raise Unauthorized if session.nil?
+```
+
+It honours the current scope, returns `nil` (never raises) for a blank,
+unknown, mismatched, or malformed-digest token, and has an instance-level
+counterpart, `session.authenticate_token(token)`.
+
 ### Custom Token Claims
 
 You can add additional JWT claims for any token issued through the OAuth token endpoint by mapping scopes to claim names and providing callbacks to resolve each claim. Scopes listed in `oauth.scope_claims` are evaluated against the requested token scopes; when a scope matches, every claim listed for that scope is resolved via the callable defined in `oauth.claim_resolvers`.

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

@@ -2,6 +2,8 @@ module StandardId
   module Api
     module Oauth
       class RevocationsController < BaseController
+        VALID_REVOCATION_SCOPES = %i[account grant].freeze
+
         public_controller
 
         skip_before_action :validate_content_type!
@@ -12,6 +14,12 @@ module StandardId
         # Accepts a token and optional token_type_hint parameter.
         # Always responds with 200 OK regardless of whether the token
         # was valid or revocation was successful (per RFC 7009 Section 2.1).
+        #
+        # How much gets revoked is controlled by
+        # `config.oauth.revocation_scope` (:account — historical, revoke every
+        # active DeviceSession for the subject; :grant — revoke only the
+        # authorization grant the presented token belongs to). See the schema
+        # comment on that field.
         def create
           token = params[:token]
           head :ok and return if token.blank?
@@ -19,77 +27,155 @@ module StandardId
           payload = StandardId::JwtService.decode(token)
           head :ok and return unless payload&.dig(:sub)
 
-          account_id = payload[:sub]
-
-          sessions = StandardId::DeviceSession
-            .where(account_id: account_id)
-            .active
-
-          # token_type_hint is accepted but ignored — we always attempt
-          # 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
-              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
+          if revocation_scope == :grant
+            revoke_presented_grant!(payload)
+          else
+            revoke_account_sessions!(payload[:sub])
+          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
+          head :ok
+        end
+
+        private
+
+        def revocation_scope
+          configured = StandardId.config.oauth.revocation_scope&.to_sym
+          return configured if VALID_REVOCATION_SCOPES.include?(configured)
+
+          StandardId.logger&.warn(
+            "[StandardId::Revocations] Unknown config.oauth.revocation_scope " \
+            "#{configured.inspect}; falling back to :account. Valid values: " \
+            "#{VALID_REVOCATION_SCOPES.inspect}"
+          )
+          :account
+        end
+
+        # :account — the historical blast radius. Every active DeviceSession
+        # for the subject is revoked, whichever token was presented.
+        # ServiceSessions are deliberately excluded: they are machine
+        # credentials with their own lifecycle, not something an interactive
+        # client's logout should silently kill.
+        def revoke_account_sessions!(account_id)
+          sessions = StandardId::DeviceSession.where(account_id: account_id).active.to_a
+          return if sessions.empty?
+
+          refresh_tokens_revoked = revoke_sessions!(sessions)
+          emit_token_revoked(
+            account_id: account_id,
+            sessions_revoked: sessions.size,
+            refresh_tokens_revoked: refresh_tokens_revoked
+          )
+        end
+
+        # :grant — RFC 7009 §2.1: revoke the presented token and the tokens
+        # issued from the same authorization grant, nothing else.
+        #
+        # The lookup is by `jti`, which is type-agnostic: refresh tokens are
+        # persisted as SHA256(jti) in standard_id_refresh_tokens, access tokens
+        # are not persisted at all. That is why token_type_hint stays unused —
+        # it is an optimisation hint for servers keeping separate per-type
+        # stores (RFC 7009 §2.1), and a wrong hint must not change the outcome.
+        # A presented access token therefore resolves to nothing and revokes
+        # nothing: this engine cannot invalidate a stateless JWT before its
+        # exp. Clients that need revocation to bite present the refresh token.
+        def revoke_presented_grant!(payload)
+          jti = payload[:jti]
+          return if jti.blank?
+
+          # Eager-load both associations: host apps run with
+          # `strict_loading_by_default` (jumpdrive-web, luminality-web), where a
+          # lazy `record.session` / `record.account` raises in their test env.
+          record = StandardId::RefreshToken
+            .where(token_digest: StandardId::RefreshToken.digest_for(jti))
+            .includes(:session, :account)
+            .first
+          # A jti that resolves to another subject's grant must never revoke
+          # it — the token was signature-verified, but bind the two identities
+          # anyway rather than trusting a single claim.
+          return if record.nil? || record.account_id.to_s != payload[:sub].to_s
+
+          refresh_tokens_revoked = record.revoke_family!
+
+          # The grant's Session, when the host app materialised one
+          # (RefreshToken#session_id is nil unless the flow sets it).
+          session = record.session
+          sessions = (session && session.active?) ? [session] : []
+          refresh_tokens_revoked += revoke_sessions!(sessions, account: record.account)
 
+          emit_token_revoked(
+            account_id: payload[:sub],
+            sessions_revoked: sessions.size,
+            refresh_tokens_revoked: refresh_tokens_revoked
+          )
+        end
+
+        # 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.
+        #
+        # @return [Integer] number of refresh-token rows revoked by the cascade
+        def revoke_sessions!(sessions, account: nil)
+          return 0 if sessions.empty?
+
+          now = Time.current
+          session_ids = sessions.map(&:id)
+          refresh_tokens_revoked = 0
+
+          ActiveRecord::Base.transaction do
+            StandardId::Session.where(id: session_ids).update_all(revoked_at: now)
+            refresh_tokens_revoked = 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 sessions here belong to the same account (both callers scope by
+          # account), so we load the account once rather than calling
+          # session.account per row, which would issue N extra SELECTs.
+          shared_account = account || sessions.first.account
+          sessions.each do |session|
+            session.revoked_at = now
             begin
               StandardId::Events.publish(
-                StandardId::Events::OAUTH_TOKEN_REVOKED,
-                account_id: account_id,
-                sessions_revoked: revoked_sessions.size
+                StandardId::Events::SESSION_REVOKED,
+                session: session,
+                account: shared_account,
+                reason: "token_revocation"
               )
             rescue StandardError => e
               StandardId.logger.error(
-                "[StandardId::Revocations] Failed to publish OAUTH_TOKEN_REVOKED " \
-                "for account #{account_id}: #{e.class}: #{e.message}"
+                "[StandardId::Revocations] Failed to publish SESSION_REVOKED " \
+                "for session #{session.id}: #{e.class}: #{e.message}"
               )
             end
           end
 
-          head :ok
+          refresh_tokens_revoked
+        end
+
+        def emit_token_revoked(account_id:, sessions_revoked:, refresh_tokens_revoked:)
+          StandardId::Events.publish(
+            StandardId::Events::OAUTH_TOKEN_REVOKED,
+            account_id: account_id,
+            sessions_revoked: sessions_revoked,
+            refresh_tokens_revoked: refresh_tokens_revoked
+          )
+        rescue StandardError => e
+          StandardId.logger.error(
+            "[StandardId::Revocations] Failed to publish OAUTH_TOKEN_REVOKED " \
+            "for account #{account_id}: #{e.class}: #{e.message}"
+          )
         end
       end
     end

data/app/models/standard_id/email_identifier.rb

@@ -1,7 +1,28 @@
 module StandardId
   class EmailIdentifier < Identifier
+    # `URI::MailTo::EMAIL_REGEXP` models the local part as one flat character
+    # class that happens to include `.`, so it accepts dot placements RFC 5322
+    # forbids in an unquoted local part: a leading dot, a trailing dot, and
+    # consecutive dots. `a..b@example.com` passes it.
+    #
+    # ESPs do not. Postmark rejects such an address at send time with
+    # `InvalidEmailRequestError`, so a typo accepted at sign-up surfaces much
+    # later as a failed delivery job that no operator can act on — the address
+    # is already stored and the user is long gone.
+    #
+    # Enforce the dot-atom rule instead: the local part is dot-separated atoms,
+    # each at least one character. The domain pattern is `URI::MailTo`'s,
+    # unchanged.
+    LOCAL_PART = %r{[A-Za-z0-9!\#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!\#$%&'*+/=?^_`{|}~-]+)*}
+    DOMAIN = /[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*/
+    EMAIL_FORMAT = /\A#{LOCAL_PART}@#{DOMAIN}\z/
+
     normalizes :value, with: ->(e) { e.strip.downcase }
 
-    validates :value, format: { with: URI::MailTo::EMAIL_REGEXP }
+    # Scoped to a changed value so tightening the rule cannot strand an account
+    # created under the looser one: an existing row keeps working until someone
+    # actually edits the address. Without this, saving an unrelated attribute on
+    # a grandfathered identifier would start raising.
+    validates :value, format: { with: EMAIL_FORMAT }, if: :value_changed?
   end
 end

data/app/models/standard_id/session.rb

@@ -19,6 +19,48 @@ module StandardId
       where(lookup_hash:)
     }
 
+    # Authenticate an opaque session token.
+    #
+    # `by_token` is NOT authentication on its own: it matches the SHA256
+    # `lookup_hash`, which exists only to find the candidate row from an
+    # indexed column. The credential is the BCrypt `token_digest`, and every
+    # consumer previously had to remember to verify it by hand (and to rescue
+    # BCrypt::Errors::InvalidHash). This is that step, done once, here.
+    #
+    # Honours the current scope, so callers keep their own filters:
+    #
+    #   StandardId::Session.api_compatible.active.authenticate_by_token(token)
+    #
+    # @param token [String, nil] the raw token presented by the client
+    # @return [StandardId::Session, nil] the session, or nil when the token is
+    #   blank, matches no row, or fails the digest verification
+    def self.authenticate_by_token(token)
+      return nil if token.blank?
+
+      session = by_token(token).first
+      return nil if session.nil?
+
+      session.authenticate_token(token) ? session : nil
+    end
+
+    # Timing-safe verification of `token` against this session's stored
+    # BCrypt digest. Re-hashes the presented token with the stored salt and
+    # compares the two digests with a constant-time compare, so the response
+    # time carries no information about how much of the digest matched.
+    #
+    # @return [Boolean] false for a blank or malformed digest — never raises.
+    def authenticate_token(token)
+      return false if token.blank? || token_digest.blank?
+
+      stored = BCrypt::Password.new(token_digest)
+      ActiveSupport::SecurityUtils.secure_compare(
+        stored.to_s,
+        BCrypt::Engine.hash_secret(token, stored.salt)
+      )
+    rescue BCrypt::Errors::InvalidHash, BCrypt::Errors::InvalidSalt
+      false
+    end
+
     attr_reader :token
 
     before_validation :generate_token, :generate_token_digest, :generate_lookup_hash, on: :create

data/lib/standard_id/config/schema.rb

@@ -318,6 +318,45 @@ StandardId::ConfigSchema.define do
     #   "client_secret_basic" — confidential, secret via HTTP Basic
     #   "client_secret_post"  — confidential, secret in the request body
     field :dynamic_registration_default_auth_method, type: :string, default: "none"
+
+    # RFC 6749 §4.1.3 strictness at the token endpoint.
+    #
+    # The spec is unambiguous: if `redirect_uri` was included in the
+    # authorization request, the client MUST send it again at the token
+    # endpoint and the two values MUST be identical. Historically this engine
+    # only compared the values when the client bothered to send one, so a
+    # client could silently skip the check by omitting the parameter.
+    #
+    # When true, redeeming a code that was minted WITH a redirect_uri fails
+    # with invalid_grant unless the token request repeats the identical value.
+    # Codes minted WITHOUT a redirect_uri are unaffected either way.
+    #
+    # Default is false — the historical, lenient behaviour — because flipping
+    # it silently would break any live client that omits the parameter, and
+    # this gem is consumed by several production apps. In lenient mode the
+    # engine logs a warning naming the client_id every time a code with a
+    # stored redirect_uri is redeemed without one, so deployments can confirm
+    # no client relies on the leniency before opting in. Set it to true.
+    field :strict_redirect_uri_matching, type: :boolean, default: false
+
+    # Blast radius of POST /oauth/revoke (RFC 7009).
+    #
+    #   :account (default) — revoke every active DeviceSession belonging to the
+    #     token's `sub`, regardless of which token was presented. Historical
+    #     behaviour. Fail-safe (it over-revokes) but it means a single client's
+    #     logout signs the account out on every device.
+    #
+    #   :grant — revoke only the authorization grant the presented token
+    #     belongs to: the refresh-token family the token's `jti` resolves to,
+    #     plus that refresh token's Session when one is linked. A presented
+    #     ACCESS token resolves to no stored artifact (access tokens are
+    #     stateless JWTs this engine cannot individually invalidate), so in
+    #     :grant mode revoking an access token is a no-op returning 200 per
+    #     RFC 7009 §2.2 — clients that want revocation to bite must present
+    #     the refresh token.
+    #
+    # An unrecognised value logs a warning and falls back to :account.
+    field :revocation_scope, type: :symbol, default: :account
   end
 
   scope :social do

data/lib/standard_id/oauth/authorization_code_flow.rb

@@ -22,9 +22,7 @@ module StandardId
           raise StandardId::InvalidGrantError, "Invalid or expired authorization code"
         end
 
-        if params[:redirect_uri].present? && @authorization_code.redirect_uri != params[:redirect_uri]
-          raise StandardId::InvalidGrantError, "Redirect URI mismatch"
-        end
+        validate_redirect_uri!
 
         # Fail closed: a public client's only authentication factor is PKCE, so a
         # code minted without a code_challenge offers no client authentication at
@@ -44,6 +42,42 @@ module StandardId
 
       private
 
+      # RFC 6749 §4.1.3: when the authorization request carried a redirect_uri,
+      # the token request MUST repeat it and the values MUST be identical.
+      #
+      # A presented value is always compared (that has always been the case).
+      # An OMITTED value is the interesting one: strictly it must be rejected,
+      # but rejecting it unconditionally would break any live client that
+      # relies on the historical leniency, so it is gated on
+      # `config.oauth.strict_redirect_uri_matching` (default false) and logged
+      # loudly in the meantime. See the schema comment for the migration path.
+      def validate_redirect_uri!
+        stored = @authorization_code.redirect_uri
+        presented = params[:redirect_uri]
+
+        if presented.present?
+          raise StandardId::InvalidGrantError, "Redirect URI mismatch" if stored != presented
+          return
+        end
+
+        return if stored.blank?
+
+        unless StandardId.config.oauth.strict_redirect_uri_matching
+          # Rails.logger, not StandardId.logger: the rest of lib/standard_id
+          # logs through Rails directly, and config.logger is host-supplied
+          # (it need not be a Logger at all).
+          Rails.logger.warn(
+            "[StandardId::AuthorizationCodeFlow] client #{params[:client_id]} redeemed an " \
+            "authorization code minted with redirect_uri without sending one at the token " \
+            "endpoint. RFC 6749 §4.1.3 requires it; this is accepted only because " \
+            "config.oauth.strict_redirect_uri_matching is false."
+          )
+          return
+        end
+
+        raise StandardId::InvalidGrantError, "Redirect URI mismatch"
+      end
+
       def emit_code_consumed
         StandardId::Events.publish(
           StandardId::Events::OAUTH_CODE_CONSUMED,

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.29.1"
+  VERSION = "0.31.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.29.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -108,6 +108,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile