standard_id 0.45.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7acc907df7682568d732664fb09873ab023b696e4057095b261a318aab7543b1
-  data.tar.gz: f20929b44d2669f600e304345dbc34992fe9df54b9ff7e40fd64b45731a117e1
+  metadata.gz: 2a825be521399d2fbb91a820cbc0da601d24865a12fc549d1a8697ea1d6c97cb
+  data.tar.gz: da555da47e6a9ae99f1c888e5ef93c2fc4a02d21b11993300c67d02df6ef5d01
 SHA512:
-  metadata.gz: ac1c4b0e6148140f310456a71fa9e88e162750aa35707b945c2b7c0061a19b1cae54a0cc2fb33b8b418d151c6bfd60190f49669c9cb14dedb159c6bb3b448602
-  data.tar.gz: 99ddde4158e6354df56d377ed3508cb4111207492b62f12ffcb9c6276a862c0bd0e7cbbcc22e41a026b3073db3252325d6a354be903e3413bf5431ac8ea9f45d
+  metadata.gz: f54bf303a4cc32095b3117df9636b9f3e04ebe4483de5b79f513a0089b44d45a36a3ff7dbaf54d0858a4c29c657e11452f9e7b4ffe89e7418fbf55598ecf75a7
+  data.tar.gz: 157b2b4ffdca2f4a22eaf78207ba28579ef71c59693d6f8587159be19bd36d9540c008e9ede3bbbcc9f313f10d5ef762b9553e898428ffe4f37f7f513c83c2ef

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.46.0] - 2026-10-05
+
+### Added
+
+- **Callback `iss` for providers (RFC 9207).** The web and API social callbacks pass the request's `iss` parameter to `get_user_info` as `callback_iss:` when it is a String, so a provider can refuse an authorization-server mix-up without hooking the callback controller itself. On the API callback, `iss` is no longer forwarded to `SOCIAL_AUTH_COMPLETED` subscribers as `original_request_params`, like the other OAuth-flow params.
+- **Core-managed PKCE: `Providers::Base.supports_pkce?`** (default `false`). For a provider that returns `true`, `/login?connection=<provider>` generates a fresh verifier per sign-in, stores it with the state and nonce in the encrypted pending-requests cookie, and passes `code_challenge:` / `code_challenge_method: "S256"` to `authorization_url`. The web callback passes the stored verifier to `get_user_info` as `code_verifier:`, and refuses a callback whose stored request has none. The API callback never passes a verifier (it has no server-held flow state; a client-supplied `code_verifier` is not forwarded), and the API social login grant refuses a PKCE provider. `build_authorization_url` emits `code_challenge` / `code_challenge_method` when `options` carries them; `Providers::Base.pkce_s256_challenge(verifier)` computes the S256 challenge. Providers that do not opt in see no change: both new kwargs reach them only through `**options`, and nil values are not passed. See the README, "Callback `iss` and core-managed PKCE".
+
+### Fixed
+
+- **Social-link races are classified correctly under MySQL/InnoDB `REPEATABLE READ`.** When a concurrent login committed a rival `(provider, sub)` or `(identifier, provider)` row after this login's lookup, the re-read that decides who won ran inside the link transaction as a plain `SELECT`. Under `REPEATABLE READ` that read the transaction's earlier snapshot, missed the rival, and re-raised the `RecordNotUnique`: a 500 with no `SOCIAL_LINK_BLOCKED` instead of a retryable `invalid_grant` (or adopting a same-account rival). `SocialAuthentication#classify_social_link_race!` now uses locking reads (`SELECT ... FOR UPDATE`), which always see the latest committed row. PostgreSQL (`READ COMMITTED`) already saw the rival and behaves as before; on SQLite the lock is a no-op.
+- **A refused request's new account is reclaimed when the login it was kept for fails too.** Since 0.45.0, `AccountCleanup.destroy_newly_created!` keeps a refused request's new account when a concurrent login (B) has already signed in to it. If B then failed as well, B revoked its own session or refresh token but, not having created the account, removed nothing, so the account and its identifier were left behind with no way in and blocked a later signup for that address. The kept account now remembers the session and refresh-token ids it was kept for (in `StandardId.cache_store`, for one hour), and the social callbacks and `handle_authentication_denied` call the new **`AccountCleanup.reclaim_for_failed_adopter!`** with what the failing login issued. The account is removed, under the same row lock, only when one of those credentials was among the remembered ones and nothing else is signed in to it; if another login still is, the account is kept for that one instead. A login that succeeded, or any other later sign-in, never triggers the removal. This needs a cache store shared by all processes (e.g. Solid Cache or Redis); with a per-process store or `:null_store` nothing is remembered and the account is kept, as in 0.45.0.
+- **`SOCIAL_ACCOUNT_LINKED` is no longer published for a link that was never recorded.** When `SocialAuthentication#record_social_identity!` found a `(provider, sub)` row that was then removed (for example by a concurrent account cleanup) before `classify_social_link_race!` re-read it, it returned without inserting: the provider backfill committed and `SOCIAL_ACCOUNT_LINKED` was published, yet no `(provider, sub)` row existed, so later logins were not matched by subject. The `sub` is free at that point, so the login now goes on to insert the row (any rival that commits meanwhile is classified as before), and the event is published only for a row that was inserted or adopted. Under MySQL/InnoDB `REPEATABLE READ` the uniqueness validations of that insert read the transaction's snapshot, which still holds the removed row, and raised `RecordInvalid`; when the locking re-read finds no rival, the insert is now retried once without validations (every other validation passed, and unique indexes back both uniqueness rules).
+
 ## [0.45.0] - 2026-10-04
 
 Two opt-in hooks that the org-IdP provider plugin (`standard_id-void_which_binds`) needs. With neither configured, behaviour is unchanged.

data/README.md

@@ -1527,22 +1527,65 @@ end
 | `skip_csrf?` | `false` | `true` for POST (form_post) callbacks |
 | `supports_mobile_callback?` | `false` | Enables the server-side redirect back to a native app |
 | `trusted_for_linking?` | `false` | `true` lets `:strict` link to an account created via another provider (verified emails only). Org-owned IdPs only; see "Trusted linking" (0.45+) |
+| `supports_pkce?` | `false` | `true` makes core generate, store and hand back a PKCE (S256) verifier for the web flow; see "Callback `iss` and core-managed PKCE" (0.46+) |
 
 **Protected helpers** for use inside those methods — signatures are stable:
 
 | Helper | Does |
 |--------|------|
 | `build_response(user_info, tokens:)` | The standard `get_user_info` return value |
-| `build_authorization_url(endpoint:, client_id:, redirect_uri:, state:, options: {}, defaults: {}, response_type: "code")` | `client_id`, `redirect_uri`, `response_type`, `state`, then each `supported_authorization_params` entry from `options` or `defaults`; nils dropped |
+| `build_authorization_url(endpoint:, client_id:, redirect_uri:, state:, options: {}, defaults: {}, response_type: "code")` | `client_id`, `redirect_uri`, `response_type`, `state`, then each `supported_authorization_params` entry from `options` or `defaults`, then `code_challenge` / `code_challenge_method` from `options`; nils dropped |
 | `extract_tokens(parsed_token)` | `{ access_token:, refresh_token:, id_token: }` from a token response, nils dropped |
 | `verify_nonce!(expected:, actual:)` | Constant-time nonce check; no-op when `expected` is blank. Raises `InvalidRequestError` without echoing either value |
 | `rescue_to_oauth_error(message_prefix = nil) { ... }` | Lets `StandardId::OAuthError` through; wraps anything else in one, keeping `cause` |
+| `pkce_s256_challenge(code_verifier)` (public) | `BASE64URL(SHA256(verifier))`, unpadded (RFC 7636 S256) |
 
 A plugin using `env:`, `required:` or these helpers should depend on
 `standard_id >= 0.42`. `Providers::Base.setup` is no longer called (removed
 from the base class in 0.42; the call-with-a-warning shim went in 0.43) — do
 one-off initialization in your own Railtie instead.
 
+#### Callback `iss` and core-managed PKCE (0.46+)
+
+Core hands two more values to `get_user_info`, so a provider does not have to
+capture or derive them itself. Both arrive through `**options`; a provider
+that does not name them ignores them, and a nil value is never passed.
+
+- **`callback_iss:`** — the callback's `iss` parameter (RFC 9207), when the
+  redirect carried one as a String. Compare it with the issuer you expect
+  before exchanging the code (authorization-server mix-up defence). It is
+  passed on both the web callback and `/api/oauth/callback/:provider` (where
+  it is whatever the client relayed); refuse a missing one if your IdP always
+  sends it.
+- **`code_verifier:`** — for a provider whose `supports_pkce?` returns `true`.
+  On every `/login?connection=<provider>` core generates a fresh verifier,
+  stores it with the state and nonce in the encrypted pending-requests cookie
+  (it never appears in a URL), and passes `code_challenge:` and
+  `code_challenge_method: "S256"` to `authorization_url`
+  (`build_authorization_url` emits both). At the web callback the stored
+  verifier comes back as `code_verifier:`; send it in the token request. A
+  web callback whose stored request has no verifier (a state issued for
+  another provider, or one started before the provider opted in) is refused
+  before the provider is called.
+
+```ruby
+def self.supports_pkce? = true
+
+def self.get_user_info(code: nil, redirect_uri: nil, nonce: nil, callback_iss: nil, code_verifier: nil, **_options)
+  raise StandardId::InvalidRequestError, "issuer mismatch" unless callback_iss == EXPECTED_ISSUER
+  raise StandardId::InvalidRequestError, "web sign-in only" if code_verifier.blank?
+
+  # POST code, redirect_uri and code_verifier to the token endpoint ...
+end
+```
+
+The API paths keep no server-side flow state, so they never pass a
+`code_verifier:` (a client-supplied `code_verifier` param is not forwarded),
+and the API social login grant (`/authorize?connection=...`) refuses to start
+a sign-in for a provider that `supports_pkce?` rather than send it without a
+challenge. A PKCE provider is therefore web-only unless it handles a native
+flow itself.
+
 **Testing a plugin, or an app that uses one:**
 
 ```ruby

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

@@ -191,8 +191,16 @@ module StandardId
     # @param account [Object, nil] the account to clean up if newly created
     # @param newly_created [Boolean] whether the account was created during this request
     def handle_authentication_denied(error, account: nil, newly_created: false)
+      # Only a session THIS request created can have kept a refused new
+      # account alive (see AccountCleanup.reclaim_for_failed_adopter!), never
+      # one the browser already had.
+      created_session = session_manager.created_session if session_manager.respond_to?(:created_session)
       session_manager.revoke_current_session! if session_manager.current_session.present?
-      destroy_newly_created_account(account) if newly_created
+      if newly_created
+        destroy_newly_created_account(account)
+      elsif account && created_session
+        StandardId::AccountCleanup.reclaim_for_failed_adopter!(account, sessions: [created_session])
+      end
       message = error.message
       # When raised without arguments, StandardError#message returns the class name
       message = "Sign-in was denied" if message.blank? || message == error.class.name

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

@@ -18,19 +18,32 @@ module StandardId
       raise StandardId::InvalidRequestError, e.message
     end
 
-    def get_user_info_from_provider(redirect_uri: nil, nonce: nil, flow: :web)
+    # `callback_iss` is the callback's RFC 9207 `iss` parameter (a String
+    # only; anything else is dropped), for providers that defend against
+    # authorization-server mix-up. `code_verifier` is passed only by the web
+    # callback, from the server-held flow state, for providers that opt in to
+    # core-managed PKCE (Providers::Base.supports_pkce?). Nil values are not
+    # passed, so a provider that ignores both sees no change.
+    def get_user_info_from_provider(redirect_uri: nil, nonce: nil, code_verifier: nil, flow: :web)
       provider_params = {
         code: params[:code],
         id_token: params[:id_token],
         access_token: params[:access_token],
         redirect_uri:,
-        nonce:
+        nonce:,
+        callback_iss: callback_iss_param,
+        code_verifier:
       }
 
       resolved_params = provider.resolve_params(provider_params, context: { flow: flow })
       provider.get_user_info(**resolved_params.compact)
     end
 
+    def callback_iss_param
+      iss = params[:iss]
+      iss.is_a?(String) && iss.present? ? iss : nil
+    end
+
     # Resolves the account for a social login, in this order:
     #
     # 1. (provider, sub) matches a StandardId::SocialIdentity → that account.
@@ -193,13 +206,21 @@ module StandardId
     # (identifier, provider) collision into RecordNotFound, and return a
     # (provider, sub) winner for ANY account). Every one of them is classified
     # by classify_social_link_race!.
+    #
+    # A row found by the first lookup can be removed again (e.g. by a
+    # concurrent account cleanup) before classify_social_link_race! re-reads
+    # it. The (provider, sub) is then free, so the insert goes ahead: returning
+    # instead would let commit_social_link! backfill the provider and publish
+    # SOCIAL_ACCOUNT_LINKED for a link no row records.
     def record_social_identity!(identifier, subject)
       return if subject.nil?
       return unless social_identities_available?
 
       attributes = { provider: provider.provider_name, subject: subject }
-      existing = StandardId::SocialIdentity.find_by(attributes)
-      return classify_social_link_race!(identifier, subject) if existing
+      if StandardId::SocialIdentity.find_by(attributes)
+        winner = classify_social_link_race!(identifier, subject)
+        return winner if winner
+      end
 
       StandardId::SocialIdentity.transaction(requires_new: true) do
         StandardId::SocialIdentity.create!(attributes.merge(account: identifier.account, identifier: identifier))
@@ -209,6 +230,22 @@ module StandardId
     rescue ActiveRecord::RecordInvalid => e
       raise unless social_link_race_invalid?(e.record)
 
+      classify_social_link_race!(identifier, subject) || insert_past_stale_uniqueness!(e.record, identifier, subject)
+    end
+
+    # The uniqueness validations said `taken`, but the locking re-read in
+    # classify_social_link_race! finds no rival: the validations read a stale
+    # snapshot. Under MySQL/InnoDB REPEATABLE READ they read the transaction's
+    # snapshot, which still holds a row a concurrent cleanup has since removed
+    # (the vanished-row case above), and every later validation would say
+    # `taken` again. Every other validation passed (social_link_race_invalid?),
+    # and both uniqueness rules are backed by unique indexes, so insert once
+    # without validating and let the indexes decide; a rival that commits in
+    # the meantime surfaces as RecordNotUnique and is classified as usual.
+    def insert_past_stale_uniqueness!(record, identifier, subject)
+      StandardId::SocialIdentity.transaction(requires_new: true) { record.save!(validate: false) }
+      record
+    rescue ActiveRecord::RecordNotUnique
       classify_social_link_race!(identifier, subject) || raise
     end
 
@@ -229,8 +266,19 @@ module StandardId
     # (:subject_conflict) or this identifier to this provider under ANOTHER
     # sub (:subject_mismatch); returns nil when no rival is found (it was
     # removed again), so the caller re-raises the original error.
+    #
+    # Both lookups are locking reads (SELECT ... FOR UPDATE). They run inside
+    # commit_social_link!'s transaction, and under MySQL/InnoDB's default
+    # REPEATABLE READ a plain SELECT there reads the snapshot taken by the
+    # transaction's first plain read (record_social_identity!'s own lookup),
+    # which predates the rival that just made the INSERT fail: the rival
+    # would be invisible, the race unclassified, and the login a 500 with no
+    # SOCIAL_LINK_BLOCKED. A locking read always reads the latest committed
+    # row. Under PostgreSQL's READ COMMITTED (and on SQLite, where `lock` is
+    # a no-op) a plain read already saw it; the lock only holds the rival row
+    # until this transaction ends.
     def classify_social_link_race!(identifier, subject)
-      winner = StandardId::SocialIdentity.find_by(provider: provider.provider_name, subject: subject)
+      winner = StandardId::SocialIdentity.lock.find_by(provider: provider.provider_name, subject: subject)
       if winner
         return winner if winner.account_id == identifier.account_id
 
@@ -238,7 +286,7 @@ module StandardId
       end
 
       other_sub = StandardId::SocialIdentity.where(identifier_id: identifier.id, provider: provider.provider_name).where.not(subject: subject)
-      return nil unless other_sub.exists?
+      return nil unless other_sub.lock.exists?
 
       raise StandardId::SocialLinkConflictError.new(SOCIAL_RETRY_MESSAGE, identifier: identifier, reason: :subject_mismatch)
     end
@@ -343,9 +391,18 @@ module StandardId
     # binding, an unexpected error — must leave nothing behind: drop the link
     # and remove an account this request created. Safe to call when nothing
     # was recorded, and when the account is already gone.
-    def discard_social_attempt!(account, newly_created:)
+    #
+    # When the login matched an EXISTING account, `sessions` / `refresh_tokens`
+    # are what this request issued (and has revoked): if a concurrent, refused
+    # request kept that account only because this login had signed in to it,
+    # the account is removed after all (AccountCleanup.reclaim_for_failed_adopter!).
+    def discard_social_attempt!(account, newly_created:, sessions: [], refresh_tokens: [])
       rollback_social_link!
-      StandardId::AccountCleanup.destroy_newly_created!(account) if newly_created
+      if newly_created
+        StandardId::AccountCleanup.destroy_newly_created!(account)
+      else
+        StandardId::AccountCleanup.reclaim_for_failed_adopter!(account, sessions:, refresh_tokens:)
+      end
     end
 
     # The login matched an account by email that a concurrent, refused

data/app/controllers/concerns/standard_id/web/social_login_params.rb

@@ -8,7 +8,10 @@ module StandardId
 
       private
 
-      def store_oauth_request(state:, nonce: nil, params:)
+      # `code_verifier` is the PKCE verifier for providers that opt in with
+      # `supports_pkce?`; like the nonce it stays server-held (the cookie is
+      # encrypted) and is handed back to the provider at the callback.
+      def store_oauth_request(state:, params:, nonce: nil, code_verifier: nil)
         pending_requests = load_pending_requests || {}
 
         cleanup_expired_requests!(pending_requests)
@@ -16,6 +19,7 @@ module StandardId
         pending_requests[state] = {
           "params" => params,
           "nonce" => nonce,
+          "code_verifier" => code_verifier,
           "expires_at" => REQUEST_EXPIRY.from_now.to_i
         }
 
@@ -43,7 +47,7 @@ module StandardId
           save_pending_requests(pending_requests)
         end
 
-        request_data.slice("params", "nonce")
+        request_data.slice("params", "nonce", "code_verifier")
       rescue JSON::ParserError => e
         StandardId.logger.error({
           subject: "standard_id.consume_oauth_request.error",

data/app/controllers/standard_id/api/oauth/callback/providers_controller.rb

@@ -14,7 +14,7 @@ module StandardId
         # (UTM, campaign IDs, deep-link slugs) to the signing-in account.
         RESERVED_CALLBACK_PARAMS = %w[
           id_token code scope scopes audience redirect_uri flow
-          state nonce provider controller action format
+          state nonce iss provider controller action format
           authenticity_token utf8 _method
         ].freeze
 
@@ -52,8 +52,8 @@ module StandardId
             commit_social_link!
           rescue StandardError
             removed = social_account_removed_concurrently?(account, newly_created:)
-            revoke_issued_tokens!(flow)
-            discard_social_attempt!(account, newly_created: newly_created)
+            issued = revoke_issued_tokens!(flow)
+            discard_social_attempt!(account, newly_created: newly_created, **issued)
             raise unless removed
 
             # The matched account was removed under this login by a
@@ -79,9 +79,12 @@ module StandardId
         # AccountCleanup does not mistake them for a concurrent login using a
         # new account. A token whose transaction rolled back is not persisted
         # and is skipped (its session write was rolled back with it).
+        #
+        # Returns what was revoked, as discard_social_attempt!'s `sessions:` /
+        # `refresh_tokens:`.
         def revoke_issued_tokens!(flow)
           record = flow&.issued_refresh_token
-          return unless record&.persisted?
+          return { sessions: [], refresh_tokens: [] } unless record&.persisted?
 
           # Loaded by id, not through the association: the record was built
           # with only session_id, and a host with strict_loading_by_default
@@ -89,6 +92,7 @@ module StandardId
           session = record.session_id && StandardId::Session.find_by(id: record.session_id)
           session.revoke!(reason: "social_sign_in_rejected") unless session.nil? || session.revoked?
           record.revoke!
+          { sessions: [session].compact, refresh_tokens: [record] }
         end
 
         # Mirror of the web callback's OAuthError handling: emit
@@ -100,6 +104,12 @@ module StandardId
         # ...) are policy/client errors, not infrastructure failures, and
         # must not emit. The error re-raises into the standard
         # handle_oauth_error JSON response.
+        #
+        # The provider receives the request's `iss` as `callback_iss:` (as on
+        # the web callback) but never a `code_verifier:`: this endpoint has no
+        # server-held flow state, and a client-supplied `code_verifier` param
+        # is not forwarded. A provider that opts in to core-managed PKCE
+        # (supports_pkce?) gets no verifier here and should refuse.
         def fetch_provider_user_info
           get_user_info_from_provider(flow: provider.flow_for(params))
         rescue StandardId::OAuthError => e

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

@@ -25,10 +25,11 @@ module StandardId
             state_data = nil
 
             begin
-              extract_state_and_nonce => { state_data:, nonce: }
+              extract_state_and_nonce => { state_data:, nonce:, code_verifier: }
+              code_verifier = pkce_verifier_for_provider!(code_verifier)
               caller_redirect_uri = state_data&.dig("redirect_uri").presence
               redirect_uri = callback_url_for
-              provider_response = get_user_info_from_provider(redirect_uri:, nonce:)
+              provider_response = get_user_info_from_provider(redirect_uri:, nonce:, code_verifier:)
               social_info = provider_response[:user_info]
               provider_tokens = provider_response[:tokens]
               begin
@@ -143,7 +144,7 @@ module StandardId
               created.revoke!(reason: "social_sign_in_rejected") unless created.revoked?
               session_manager.clear_session!
             end
-            discard_social_attempt!(account, newly_created: newly_created)
+            discard_social_attempt!(account, newly_created: newly_created, sessions: [created])
           end
 
           # Write the (provider, sub) link only once the login is accepted.
@@ -168,10 +169,24 @@ module StandardId
 
             {
               state_data: oauth_state["params"],
-              nonce: oauth_state["nonce"]
+              nonce: oauth_state["nonce"],
+              code_verifier: oauth_state["code_verifier"].presence
             }
           end
 
+          # Core-managed PKCE (Providers::Base.supports_pkce?): the provider
+          # receives the verifier stored with this flow's state, and only
+          # then. A PKCE provider's flow must have been started with one (by
+          # /login for this provider), so a missing verifier — a state issued
+          # for another provider, or stored before the provider opted in — is
+          # refused rather than the code exchanged without it.
+          def pkce_verifier_for_provider!(code_verifier)
+            return nil unless provider.supports_pkce?
+            raise StandardId::InvalidRequestError, "Missing PKCE verifier for this sign-in" if code_verifier.nil?
+
+            code_verifier
+          end
+
           def handle_callback_error
             error_message = case params[:error]
             when "access_denied"

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

@@ -133,10 +133,12 @@ module StandardId
 
         state = generate_oauth_token
         nonce = provider_supports_nonce?(provider) ? generate_oauth_token : nil
+        code_verifier = provider.supports_pkce? ? generate_oauth_token : nil
 
         store_oauth_request(
           state:,
           nonce:,
+          code_verifier:,
           params: extract_social_login_params
         )
 
@@ -146,6 +148,12 @@ module StandardId
         # Add nonce to OAuth params if provider supports it
         extra_params[:nonce] = nonce if nonce.present?
 
+        # Core-managed PKCE: only the S256 challenge leaves the server.
+        if code_verifier
+          extra_params[:code_challenge] = provider.pkce_s256_challenge(code_verifier)
+          extra_params[:code_challenge_method] = "S256"
+        end
+
         url = provider.authorization_url(
           state:,
           redirect_uri: callback_url,

data/lib/standard_id/account_cleanup.rb

@@ -22,9 +22,25 @@ module StandardId
   # first and the account stays, or the removal goes first and the other
   # login fails and can be retried (creating a fresh account). Nothing waits
   # on a doomed account, and nothing signs in to one.
+  #
+  # An account kept that way is kept FOR the adopters it found: the session
+  # and refresh token ids that were active, remembered in
+  # StandardId.cache_store. When such an adopter's own request then fails
+  # too, it revokes what it issued and calls reclaim_for_failed_adopter!,
+  # which removes the account after all unless it is still adopted (by
+  # someone else, who is then remembered in turn). Only a failing request
+  # that issued one of the remembered credentials can trigger the removal,
+  # so an adopter that went on to succeed is never undone by a later,
+  # unrelated failure. With a cache store that does not share entries
+  # across processes (or the null store) nothing is remembered and the kept
+  # account stays, as before.
   module AccountCleanup
     module_function
 
+    # How long a kept account remembers its adopters: comfortably longer than
+    # the adopting request can take to finish.
+    KEPT_FOR_ADOPTERS_TTL = 1.hour
+
     # @return [Boolean] true when the account was removed, false when it was
     #   already gone or another login has adopted it.
     def destroy_newly_created!(account)
@@ -34,20 +50,41 @@ module StandardId
         next false if account.class.lock.where(id: account.id).pick(:id).nil?
 
         if adopted?(account)
+          remember_adopters!(account)
           Rails.logger&.info("[StandardId] Kept refused new account #{account.id}: a concurrent sign-in is using it")
           next false
         end
 
-        # Tokens first: refresh_tokens.account_id has no ON DELETE action, and
-        # a refused API grant may already have issued one for this account.
-        StandardId::RefreshToken.where(account_id: account.id).delete_all
-        account.sessions.strict_loading(false).destroy_all
-        identifiers = account.identifiers.strict_loading(false).to_a
-        identifiers.each { |i| i.credentials.strict_loading(false).destroy_all }
-        # Deliberately destroy! (unlike the destroy_all calls above): a failed identifier destroy raises and rolls back the whole cleanup, failing loud instead of leaving a half-cleaned orphan.
-        identifiers.each(&:destroy!)
-        account.destroy
-        true
+        remove!(account)
+      end
+    end
+
+    # Called by a sign-in that matched an EXISTING account and then failed,
+    # with the sessions / refresh tokens it issued (already revoked). When a
+    # refused request kept that account only because of this sign-in (see
+    # destroy_newly_created!), the account is removed after all, unless
+    # something else has adopted it since. Anything else is left alone.
+    #
+    # @return [Boolean] true when the account was removed.
+    def reclaim_for_failed_adopter!(account, sessions: [], refresh_tokens: [])
+      return false unless account&.persisted?
+
+      issued = credential_keys(Array(sessions).compact.map(&:id), Array(refresh_tokens).compact.map(&:id))
+      return false if issued.empty?
+
+      ActiveRecord::Base.transaction do
+        next false if account.class.lock.where(id: account.id).pick(:id).nil?
+
+        kept_for = Array(read_kept_for(account))
+        next false if (kept_for & issued).empty?
+
+        if adopted?(account)
+          remember_adopters!(account)
+          next false
+        end
+
+        Rails.logger&.info("[StandardId] Removing refused new account #{account.id}: the sign-in it was kept for failed")
+        remove!(account)
       end
     end
 
@@ -58,5 +95,53 @@ module StandardId
 
       StandardId::RefreshToken.active.where(account_id: account.id).exists?
     end
+
+    def remove!(account)
+      # Tokens first: refresh_tokens.account_id has no ON DELETE action, and
+      # a refused API grant may already have issued one for this account.
+      StandardId::RefreshToken.where(account_id: account.id).delete_all
+      account.sessions.strict_loading(false).destroy_all
+      identifiers = account.identifiers.strict_loading(false).to_a
+      identifiers.each { |i| i.credentials.strict_loading(false).destroy_all }
+      # Deliberately destroy! (unlike the destroy_all calls above): a failed identifier destroy raises and rolls back the whole cleanup, failing loud instead of leaving a half-cleaned orphan.
+      identifiers.each(&:destroy!)
+      account.destroy
+      forget_kept_for(account)
+      true
+    end
+
+    # Remembers the adopters the account is being kept for. Best effort: the
+    # cache is not part of the transaction, and a cache failure only means
+    # the kept account is not reclaimed later.
+    def remember_adopters!(account)
+      session_ids = account.sessions.strict_loading(false).active.pluck(:id)
+      token_ids = StandardId::RefreshToken.active.where(account_id: account.id).pluck(:id)
+      StandardId.cache_store&.write(kept_for_key(account), credential_keys(session_ids, token_ids), expires_in: KEPT_FOR_ADOPTERS_TTL)
+    rescue StandardError => e
+      Rails.logger&.warn("[StandardId] Could not remember the adopters of kept account #{account.id}: #{e.class}: #{e.message}")
+    end
+
+    def read_kept_for(account)
+      StandardId.cache_store&.read(kept_for_key(account))
+    rescue StandardError => e
+      Rails.logger&.warn("[StandardId] Could not read the adopters of kept account #{account.id}: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def forget_kept_for(account)
+      StandardId.cache_store&.delete(kept_for_key(account))
+    rescue StandardError
+      nil
+    end
+
+    def kept_for_key(account)
+      "standard_id:account_cleanup:kept_for:#{account.class.name}:#{account.id}"
+    end
+
+    def credential_keys(session_ids, refresh_token_ids)
+      session_ids.map { |id| "session:#{id}" } + refresh_token_ids.map { |id| "refresh_token:#{id}" }
+    end
+
+    private_class_method :remove!, :remember_adopters!, :read_kept_for, :forget_kept_for, :kept_for_key, :credential_keys
   end
 end

data/lib/standard_id/oauth/subflows/social_login_grant.rb

@@ -12,6 +12,12 @@ module StandardId
           @social_provider_url ||= begin
             connection = params[:connection]
             provider = StandardId::ProviderRegistry.get(connection)
+            # This flow's state is a stateless encoding, so there is nowhere
+            # server-held to keep a PKCE verifier. Refuse a provider that
+            # requires core-managed PKCE rather than start it without one.
+            if provider.supports_pkce?
+              raise StandardId::InvalidRequestError, "#{connection} sign-in requires the web login flow (PKCE)"
+            end
 
             provider.authorization_url(
               state: encode_state_with_original_params,

data/lib/standard_id/providers/base.rb

@@ -1,4 +1,6 @@
 require "uri"
+require "base64"
+require "digest"
 require "active_support/security_utils"
 
 module StandardId
@@ -81,7 +83,14 @@ module StandardId
         # @param id_token [String, nil] JWT ID token (mobile/implicit flow)
         # @param access_token [String, nil] Access token (implicit flow)
         # @param redirect_uri [String, nil] Original redirect_uri for code exchange validation
-        # @param options [Hash] Provider-specific options (client_id for Apple mobile, etc.)
+        # @param options [Hash] Provider-specific options (client_id for Apple mobile, etc.).
+        #   Core may also pass, and a provider that does not need them ignores:
+        #   - `nonce:` the nonce the server issued for this flow (only for
+        #     providers listing :nonce in {supported_authorization_params});
+        #   - `callback_iss:` the callback's RFC 9207 `iss` parameter, when the
+        #     redirect carried one as a String (absent otherwise);
+        #   - `code_verifier:` the PKCE verifier core generated and stored with
+        #     the flow's state (web callback only, and only when {supports_pkce?}).
         # @return [HashWithIndifferentAccess] Standardized response with user_info and tokens
         # @raise [NotImplementedError] if not overridden by subclass
         # @raise [StandardId::InvalidRequestError] if credentials are missing or invalid
@@ -246,6 +255,42 @@ module StandardId
           false
         end
 
+        # Whether core manages PKCE (RFC 7636, S256) for this provider's web
+        # sign-in.
+        #
+        # Default: false — core neither sends a challenge nor passes a verifier.
+        #
+        # When true, the web login flow generates a fresh `code_verifier` for
+        # every sign-in, stores it server-held alongside the state and nonce
+        # (the encrypted pending-requests cookie; it is never sent to the
+        # provider or put in a URL), and:
+        #   - passes `code_challenge:` (the S256 challenge) and
+        #     `code_challenge_method: "S256"` to {authorization_url}
+        #     ({build_authorization_url} emits both when present);
+        #   - passes the stored `code_verifier:` to {get_user_info} at the web
+        #     callback, which the provider sends in its token request. A web
+        #     callback whose stored request has no verifier is refused before
+        #     the provider is called.
+        #
+        # The API callback (`/api/oauth/callback/:provider`) has no server-held
+        # flow state, so it never passes a `code_verifier:`; the API social
+        # login grant refuses to start a sign-in for a provider that returns
+        # true here rather than send it without a challenge.
+        #
+        # @return [Boolean]
+        def supports_pkce?
+          false
+        end
+
+        # The RFC 7636 S256 code challenge for a verifier:
+        # BASE64URL(SHA256(verifier)) without padding.
+        #
+        # @param code_verifier [String]
+        # @return [String]
+        def pkce_s256_challenge(code_verifier)
+          Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier.to_s), padding: false)
+        end
+
         # Returns list of supported authorization parameters for this provider.
         #
         # Include :nonce in this list for OIDC providers to enable nonce validation.
@@ -453,7 +498,10 @@ module StandardId
         #
         # Emits `client_id`, `redirect_uri`, `response_type`, `state`, then one
         # entry per {supported_authorization_params}, taking the caller's value
-        # from `options` or falling back to `defaults`. Nil values are dropped.
+        # from `options` or falling back to `defaults`, then `code_challenge` and
+        # `code_challenge_method` when `options` carries them (core passes them
+        # only to providers that opt in with {supports_pkce?}). Nil values are
+        # dropped.
         #
         # @param endpoint [String] Provider authorization endpoint
         # @param client_id [String]
@@ -486,6 +534,9 @@ module StandardId
             query[param] = options[param] || defaults[param]
           end
 
+          query[:code_challenge] = options[:code_challenge]
+          query[:code_challenge_method] = options[:code_challenge_method]
+
           "#{endpoint}?#{URI.encode_www_form(query.compact)}"
         end
 

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.45.0"
+  VERSION = "0.46.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.45.0
+  version: 0.46.0
 platform: ruby
 authors:
 - Jaryl Sim