standard_id 0.43.1 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8003e8ad18d3a88d9684bb3877d88bbc1d9d207a897776e6ef3a6cd01b0f1191
-  data.tar.gz: 3fb388482c096695f36d79ee02e122e1cbede9fc1d11b14c6236a4d423a82a0b
+  metadata.gz: ea9ca4b9484333d3ed979bc9479b3ddcbde475a3d4f63e9903a0a4b437d925e7
+  data.tar.gz: 99b5c5993640de8c2634fbdd96fcacb95806a35c130d5b268d7daf51382c5275
 SHA512:
-  metadata.gz: 2aade7f1bba3cb85827120d4ac19e55b0a2a039955097cd43af6ef75a84f1516080c4e6c0fc36a87d15731bb332603eab987c93130e69e2e2f5701a5ac929053
-  data.tar.gz: c0a8bc153ac8db1de5f5186fb014e4ed89e0b5db06ef7e295ee276f032fc59ec39a591eb6e54e440263a22d43faf8b426f6e1acf4ab09fed72870e96c4e17f85
+  metadata.gz: a17095049de6adf0c32413fad6322a58b2f50b77c5db052043a74f082e40e6374518d22dad2518eeb4a01c15921865af993b51bae46447a8ee0135e968e6ec14
+  data.tar.gz: 2262c87410fd09684f885818aca1f31de00fe6f12daad4db0c6706521acf4d852ee2bdc623e15cc83da1aea9a7fbb7001eaab0129331ff93904056055cef4e9d

data/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.44.0] - 2026-10-02
+
+**Security fix (L1-01): social login could take over an existing account by email.** Behaviour change and a new migration; see **Upgrade notes**.
+
+### Security
+
+- **Social logins are now matched on the provider's stable subject id (`sub`), and linking to an existing account requires a provider-verified email.** `SocialAuthentication#find_or_create_account_from_social` used to look up `EmailIdentifier.find_by(value: email)` and sign the login in to that account. It never looked at `sub`, and `email_verified` only decided whether a *new* identifier was marked verified. Under `link_strategy: :trust_provider`, or under the default `:strict` for any email identifier with a `NULL` provider (every identifier created before migration `20260311000000` added the column, and every identifier the gem creates outside social login: password signup, passwordless, `find_or_create_by_verified_email!`), a provider token that merely *claimed* an address, verified or not, signed in as that address's account. Both the web callback (`Web::Auth::Callback::ProvidersController`) and the API callback (`Api::Oauth::Callback::ProvidersController` → `Oauth::SocialFlow`) went through this method; `SocialFlow` and `SocialLoginGrant` themselves do no account lookup. Resolution is now:
+  1. `(provider, sub)` matches a `StandardId::SocialIdentity` → that account, whatever email the provider now reports.
+  2. The email matches an existing identifier → link only if the `link_strategy` allows it, the identifier is not already linked to a **different** `sub` from the same provider, and the provider reports `email_verified` as `true` or `"true"` (Apple and Google's tokeninfo send the string). This holds under `:trust_provider` too. A successful link stores the `sub`.
+  3. Otherwise a new account is created exactly as before (an unverified provider email still creates an unverified identifier), and the `sub` is stored.
+
+  Each refusal emits `SOCIAL_LINK_BLOCKED` and raises `StandardId::SocialLinkError` instead of creating a duplicate account. The web callback already turns that error into a redirect to `/login` with an alert; the API callback returns `403 access_denied`.
+
+### Added
+
+- **`standard_id_social_identities`** (migration `20261002000000_create_standard_id_social_identities`) and the `StandardId::SocialIdentity` model: `account_id`, `identifier_id` (the email identifier the link was made through), `provider`, `subject`, unique on `(provider, subject)` and on `(identifier_id, provider)`. Both foreign keys are `ON DELETE CASCADE`, so deleting an identifier or account needs no new step.
+- `StandardId::SocialLinkError#reason`: `:link_required` (the strict strategy refused, as before), `:email_unverified` or `:subject_mismatch`. `SOCIAL_LINK_BLOCKED` carries the same `reason`. The constructor's new `reason:` keyword is optional and defaults to `:link_required`, so code that builds the error itself is unaffected.
+
+### Changed
+
+- `email_verified` is read strictly: only `true` or `"true"` (any case) count. Google's OAuth2 v2 userinfo key `verified_email` is accepted when `email_verified` is absent, because standard_id-google ≤ 0.5.0 returns that endpoint's JSON unchanged on its code and access-token paths.
+
+### Upgrade notes
+
+1. **Install and run the migration**: `bin/rails standard_id:install:migrations && bin/rails db:migrate`. It creates one new, empty table; nothing existing is rewritten and nothing is backfilled. Existing social users get their row on their next login (on a verified email). Until it has run, the gem logs a warning once per process, skips subject matching, and still enforces the verified-email requirement; the boot-time missing-migration check and `StandardId::Checks::Migrations` also report it.
+2. **Upgrade standard_id-google to 0.6.0** alongside this release if you use it. Its code-exchange and access-token paths read Google's v2 userinfo endpoint, which returns `id` / `verified_email` rather than `sub` / `email_verified`, so on ≤ 0.5.0 those logins carry no `sub` (they still work, matched by verified email every time). 0.6.0 adds `sub` and `email_verified`. standard_id-apple already returns both from the verified ID token.
+3. **Expect refusals where a link used to go through silently.** A social login whose provider reports the email as unverified can no longer attach to an existing account (it previously did under `:trust_provider`, or for a `NULL`-provider identifier). Google and Apple report `email_verified: true` for the address on almost every account, so this should be rare; subscribe to `SOCIAL_LINK_BLOCKED` and read `reason` to see it. A host that builds custom copy from `SocialLinkError` may want per-`reason` messages.
+4. `link_strategy` keeps its meaning (`:strict` default, `:trust_provider`); no config change is needed.
+
+
+## [0.43.2] - 2026-09-25
+
+### Fixed
+
+- **`CleanupExpiredSessionsJob` failed on every run once an expired session had a refresh token** (sidekick-web SIDEKICK-WEB-3K / cron monitor SIDEKICK-WEB-3M: `PG::ForeignKeyViolation … violates foreign key constraint "fk_rails_db44ba6f6e" on table "standard_id_refresh_tokens"`). `standard_id_refresh_tokens.session_id` references `standard_id_sessions` with no `ON DELETE` action, and `Session.where(...).delete_all` skipped the model's `dependent: :nullify`. This affected every host that schedules the job, directly or through `CleanupAllJob`, and nothing was ever cleaned up. Now, per batch of 1,000 (`batch_size:`), in one transaction, with the candidate rows re-checked under `FOR UPDATE SKIP LOCKED`:
+  - **An expired session that still has a live refresh token (unrevoked, unexpired) is kept.** Refresh tokens deliberately outlive their session's expiry: `RefreshTokenFlow#validate_parent_session!` checks revocation, not expiry, since 0.35.x, so `refresh_token_lifetime` alone decides how long a client stays signed in (jumpdrive-web runs 1-day browser sessions against 30-day refresh tokens). Deleting such a session would detach its token and lose "revoking this session ends its access". Revoking the token, as `Session#destroy` does, would sign the client out early. The session is collected on a later run, once its tokens are dead, so at most `refresh_token_lifetime` after it would otherwise have gone.
+  - **Dead refresh tokens (revoked or expired) of the sessions being deleted are detached** (`session_id` → `NULL`, as `dependent: :nullify` does) rather than deleted. `CleanupExpiredRefreshTokensJob` removes them on its own window, and until then a replayed revoked token still triggers reuse detection.
+  - A host whose copy of the migration added `on_delete: :nullify` to that FK (sidekick-web's `db/schema.rb` shows one, although its production constraint evidently has none) no longer has live tokens silently detached from their sessions either.
+- The other cleanup jobs had no such hazard. Nothing references `standard_id_authorization_codes` or `standard_id_code_challenges`, and the only foreign key into `standard_id_refresh_tokens` is its own `previous_token_id`, which is `ON DELETE SET NULL`. `standard_id_refresh_tokens.session_id` is the only foreign key into `standard_id_sessions`, in the gem, standard_id-provider and all five apps.
+
+### Changed
+
+- **Requires Rails 8.1** (`rails >= 8.1`, was `>= 8.0`; #344, merged since 0.43.1). All five consumer apps already run Rails 8.1.3.1, and 8.0 was never tested in CI.
+
+### Upgrade notes
+
+Bump only. The first run after upgrading deletes, in batches, the backlog of expired sessions the job never managed to remove.
+
 ## [0.43.1] - 2026-09-24
 
 Fixes found while shipping 0.43.0. **Take this instead of 0.43.0** — hosts on `c.passwordless.delivery = :built_in` with the WebEngine mounted (jumpdrive-web, nutripod-web) would otherwise email email-verification codes as "your sign-in code".

data/README.md

@@ -1165,6 +1165,30 @@ redirect_to "/api/authorize?" + {
 }.to_query
 ```
 
+#### How a social login finds its account (0.44+)
+
+1. **Provider + subject.** A login whose `(provider, sub)` is stored in
+   `standard_id_social_identities` signs in to that account. The email the
+   provider reports is not consulted.
+2. **Existing email identifier.** Otherwise, if the email belongs to an
+   existing account, the login links to it only when all of these hold, and
+   raises `StandardId::SocialLinkError` (after emitting `SOCIAL_LINK_BLOCKED`)
+   when one does not. The error's `reason` says which:
+   - `link_strategy` allows it (`:link_required` under `:strict`);
+   - the identifier is not already linked to a **different** `sub` from the
+     same provider (`:subject_mismatch`);
+   - the provider reports the email as verified: `email_verified` is `true`
+     or the string `"true"` (`:email_unverified`). This applies under
+     `:trust_provider` too.
+
+   A successful link stores the `sub`, so the next login matches on step 1.
+3. **New account.** Otherwise a new account is created, as before, and the
+   `sub` is stored.
+
+Providers must return the OIDC `sub` and `email_verified` claims in
+`user_info`. A provider that returns no `sub` still works, but is matched on
+email (with the verified-email requirement) every time.
+
 ### Passwordless Authentication
 
 ```ruby
@@ -1503,12 +1527,12 @@ StandardId never deletes expired rows on its own. Four cleanup jobs do, and **al
 
 | Job | Deletes | Grace windows (`perform` kwargs) | Recommended cadence |
 |---|---|---|---|
-| `StandardId::CleanupExpiredSessionsJob` | browser/device/service sessions expired > grace | `grace_period_seconds:` 7 days | hourly (minute 6) |
+| `StandardId::CleanupExpiredSessionsJob` | browser/device/service sessions expired > grace and holding no live refresh token (dead tokens are detached, not deleted) | `grace_period_seconds:` 7 days; `batch_size:` 1,000 | hourly (minute 6) |
 | `StandardId::CleanupExpiredRefreshTokensJob` | refresh tokens expired or revoked > grace | `grace_period_seconds:` 7 days | hourly (minute 3) |
 | `StandardId::CleanupExpiredAuthorizationCodesJob` | OAuth authorization codes expired > 7 days or consumed > 1 day | `grace_period_seconds:`, `consumed_grace_period_seconds:` | hourly (minute 9) |
 | `StandardId::CleanupExpiredCodeChallengesJob` | OTP code challenges expired > 7 days or used > 1 day | `grace_period_seconds:`, `used_grace_period_seconds:` | hourly (minute 13) |
 
-Retention is bounded by the grace windows, not the cadence; each job is a single `DELETE`, so running hourly keeps that statement small on busy tables (daily is fine for small apps). Stagger them off minute 0.
+Retention is bounded by the grace windows, not the cadence. Three of the jobs are a single `DELETE`, so running hourly keeps that statement small on busy tables (daily is fine for small apps). `CleanupExpiredSessionsJob` instead works in batches of `batch_size:` sessions: one transaction per batch, holding a `SELECT … FOR UPDATE SKIP LOCKED` on the candidates, an `UPDATE` detaching their dead refresh tokens and the `DELETE`. It never deletes a session whose refresh token is still live, because refresh tokens outlive session expiry by design; such a session goes on a later run, once its tokens are dead. Stagger the jobs off minute 0.
 
 `rails g standard_id:install` adds all four to `config/recurring.yml` (Solid Queue) under `production:` when that file exists (`--skip-recurring` to opt out; re-running is a no-op). An engine cannot register Solid Queue recurring tasks itself — Solid Queue reads one schedule file — so existing apps should paste this under their `production:` key:
 

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

@@ -31,6 +31,25 @@ module StandardId
       provider.get_user_info(**resolved_params.compact)
     end
 
+    # Resolves the account for a social login, in this order:
+    #
+    # 1. (provider, sub) matches a StandardId::SocialIdentity → that account.
+    #    The provider's stable subject id is authoritative; the email it
+    #    reports is not consulted.
+    # 2. The email matches an existing EmailIdentifier → link to that account,
+    #    but only when
+    #      - the link_strategy allows it (validate_social_link!),
+    #      - the identifier is not already linked to a DIFFERENT sub from this
+    #        provider (possible takeover), and
+    #      - the provider reports the email as verified. Without that, the
+    #        token proves nothing about who owns the address — under
+    #        :trust_provider, or for a pre-provider-tracking identifier, any
+    #        provider token for the address would otherwise take the account.
+    #    A successful link stores the sub, so step 1 matches next time.
+    # 3. Otherwise create a new account (unchanged) and store the sub.
+    #
+    # Each refusal raises StandardId::SocialLinkError (with a `reason`) after
+    # emitting SOCIAL_LINK_BLOCKED; a duplicate account is never created.
     def find_or_create_account_from_social(raw_social_info)
       social_info = raw_social_info.to_h.with_indifferent_access
       email = social_info[:email]
@@ -38,11 +57,21 @@ module StandardId
 
       emit_social_user_info_fetched(provider, social_info, email)
 
+      subject = social_subject(social_info)
+      social_identity = find_social_identity(subject)
+      if social_identity
+        emit_social_account_linked(social_identity.account, provider, social_identity.identifier)
+        return social_identity.account
+      end
+
       identifier = StandardId::EmailIdentifier.includes(:account).find_by(value: email)
 
       if identifier.present?
         validate_social_link!(identifier, provider)
+        validate_social_subject!(identifier, provider, subject)
+        validate_social_email_verified!(identifier, provider, social_info)
         identifier.update!(provider: provider.provider_name) if identifier.provider.nil?
+        record_social_identity!(identifier, subject)
         emit_social_account_linked(identifier.account, provider, identifier)
         identifier.account
       else
@@ -52,7 +81,8 @@ module StandardId
           value: email,
           provider: provider.provider_name
         )
-        identifier.verify! if identifier.respond_to?(:verify!) && [true, "true"].include?(social_info[:email_verified])
+        identifier.verify! if identifier.respond_to?(:verify!) && social_email_verified?(social_info)
+        record_social_identity!(identifier, subject)
         emit_social_account_created(account, provider, social_info)
         account
       end
@@ -68,15 +98,95 @@ module StandardId
 
       return if strategy == :trust_provider
       # nil provider means the identifier predates provider tracking — allow
-      # through since we can't retroactively determine its origin.
+      # through since we can't retroactively determine its origin. The
+      # email_verified check (validate_social_email_verified!) still applies.
       return if identifier.provider.nil?
       return if identifier.provider == provider.provider_name
       return if account_has_social_identifier_from?(identifier.account, provider)
 
-      emit_social_link_blocked(identifier, provider)
+      refuse_social_link!(identifier, provider, :link_required)
+    end
+
+    # The identifier is already linked to another subject from this provider:
+    # a second provider account is claiming the same address.
+    def validate_social_subject!(identifier, provider, subject)
+      return if subject.nil?
+      return unless StandardId::SocialIdentity.available?
+
+      linked = StandardId::SocialIdentity.where(identifier_id: identifier.id, provider: provider.provider_name)
+      return unless linked.where.not(subject: subject).exists?
+
+      refuse_social_link!(identifier, provider, :subject_mismatch)
+    end
+
+    # Linking a login to an EXISTING account by email needs the provider to
+    # vouch for the address, under either link_strategy.
+    def validate_social_email_verified!(identifier, provider, social_info)
+      return if social_email_verified?(social_info)
+
+      refuse_social_link!(identifier, provider, :email_unverified)
+    end
+
+    def refuse_social_link!(identifier, provider, reason)
+      emit_social_link_blocked(identifier, provider, reason)
       raise StandardId::SocialLinkError.new(
         email: identifier.value,
-        provider_name: provider.provider_name
+        provider_name: provider.provider_name,
+        reason: reason
+      )
+    end
+
+    # The provider's stable subject id (OIDC `sub`), or nil when the provider
+    # reports none.
+    def social_subject(social_info)
+      social_info[:sub].presence&.to_s
+    end
+
+    # Strict: only boolean true or the string "true" (any case) count. Apple
+    # sends `email_verified` as the string "true"; Google's tokeninfo endpoint
+    # does too. Google's OAuth2 v2 userinfo endpoint names the claim
+    # `verified_email` (standard_id-google <= 0.5.0 passes it through as-is),
+    # so it is accepted as a fallback.
+    def social_email_verified?(social_info)
+      value = social_info.key?(:email_verified) ? social_info[:email_verified] : social_info[:verified_email]
+      value.to_s.strip.casecmp?("true")
+    end
+
+    def find_social_identity(subject)
+      return nil if subject.nil?
+      return nil unless social_identities_available?
+
+      StandardId::SocialIdentity.includes(:account, :identifier).find_by(provider: provider.provider_name, subject: subject)
+    end
+
+    def record_social_identity!(identifier, subject)
+      return if subject.nil?
+      return unless social_identities_available?
+
+      StandardId::SocialIdentity.find_or_create_by!(
+        provider: provider.provider_name,
+        subject: subject
+      ) do |social_identity|
+        social_identity.account = identifier.account
+        social_identity.identifier = identifier
+      end
+    end
+
+    def social_identities_available?
+      return true if StandardId::SocialIdentity.available?
+
+      StandardId::SocialAuthentication.warn_social_identities_missing!
+      false
+    end
+
+    # Logged once per process when the host has not run the migration yet.
+    def self.warn_social_identities_missing!
+      return if @social_identities_missing_warned
+
+      @social_identities_missing_warned = true
+      Rails.logger&.warn(
+        "[StandardId] standard_id_social_identities is missing, so social logins are not matched on the " \
+        "provider's subject id. Run `bin/rails standard_id:install:migrations && bin/rails db:migrate`."
       )
     end
 
@@ -154,13 +264,14 @@ module StandardId
       )
     end
 
-    def emit_social_link_blocked(identifier, provider)
+    def emit_social_link_blocked(identifier, provider, reason = :link_required)
       StandardId::Events.publish(
         StandardId::Events::SOCIAL_LINK_BLOCKED,
         email: identifier.value,
         provider: provider,
         identifier: identifier,
-        account: identifier.account
+        account: identifier.account,
+        reason: reason
       )
     end
 

data/app/jobs/standard_id/cleanup_expired_sessions_job.rb

@@ -2,14 +2,70 @@ module StandardId
   class CleanupExpiredSessionsJob < ApplicationJob
     queue_as :default
 
+    DEFAULT_BATCH_SIZE = 1_000
+
     # Delete sessions that expired more than `grace_period_seconds` ago.
     # A grace period avoids deleting sessions that just expired and might
     # still be referenced in in-flight requests.
     # Accepts integer seconds for reliable ActiveJob serialization across all queue adapters.
-    def perform(grace_period_seconds: 7.days.to_i)
+    #
+    # Refresh tokens reference their session (standard_id_refresh_tokens.session_id,
+    # a foreign key with no ON DELETE action in the gem's migration), and
+    # `delete_all` skips the model's `dependent: :nullify`, so a bare delete
+    # failed the whole run once any expired session had a refresh token
+    # (sidekick-web SIDEKICK-WEB-3K). Per batch, in one transaction:
+    #
+    # * An expired session that still has a LIVE refresh token (unrevoked,
+    #   unexpired) is kept. Refresh tokens deliberately outlive their session's
+    #   expiry — RefreshTokenFlow#validate_parent_session! checks revocation,
+    #   not expiry, so refresh_token_lifetime alone governs how long a client
+    #   stays signed in. Deleting the session would detach the token from it and
+    #   lose "revoking this session ends its access"; revoking the token (what
+    #   Session#destroy does) would sign the client out early. The session is
+    #   collected on a later run, once its tokens are dead — at most
+    #   refresh_token_lifetime later.
+    # * Dead refresh tokens (revoked or expired) of the sessions being deleted
+    #   are detached (`session_id` → NULL, the model's `dependent: :nullify`),
+    #   not deleted: CleanupExpiredRefreshTokensJob removes them on its own
+    #   window, and until then a replayed revoked token still triggers reuse
+    #   detection.
+    #
+    # Batches (`in_batches`) keep each transaction and its locks small.
+    def perform(grace_period_seconds: 7.days.to_i, batch_size: DEFAULT_BATCH_SIZE)
       cutoff = grace_period_seconds.seconds.ago
-      deleted = StandardId::Session.where("expires_at < ?", cutoff).delete_all
+      deleted = 0
+
+      StandardId::Session.where("expires_at < ?", cutoff).in_batches(of: batch_size) do |batch|
+        deleted += delete_batch(batch.pluck(:id), cutoff)
+      end
+
       Rails.logger.info("[StandardId] Cleaned up #{deleted} expired sessions older than #{cutoff}")
     end
+
+    private
+
+    def delete_batch(candidate_ids, cutoff)
+      StandardId::Session.transaction do
+        # Re-check under a row lock: a sign-in may have revived one of these
+        # rows (OauthSessionPersistence reuses an expired, unrevoked device
+        # session and bumps expires_at) or issued it a refresh token since the
+        # batch was read. SKIP LOCKED leaves a row another transaction holds for
+        # the next run. (SQLite ignores the lock clause; it serialises writers.)
+        ids = StandardId::Session
+          .where(id: candidate_ids)
+          .where("expires_at < ?", cutoff)
+          .where.not(id: live_refresh_tokens.select(:session_id))
+          .lock("FOR UPDATE SKIP LOCKED")
+          .pluck(:id)
+        next 0 if ids.empty?
+
+        StandardId::RefreshToken.where(session_id: ids).update_all(session_id: nil)
+        StandardId::Session.where(id: ids).delete_all
+      end
+    end
+
+    def live_refresh_tokens
+      StandardId::RefreshToken.active.where.not(session_id: nil)
+    end
   end
 end

data/app/models/standard_id/social_identity.rb

@@ -0,0 +1,30 @@
+module StandardId
+  # A social provider's stable subject id (`sub`) linked to an account.
+  #
+  # Written by StandardId::SocialAuthentication when a social login creates an
+  # account, or links to an existing email identifier on a provider-verified
+  # email. Later logins with the same (provider, subject) resolve to the same
+  # account, whatever email the provider then reports.
+  #
+  # `identifier` is the email identifier the link was made through. A different
+  # subject from the same provider for that identifier is refused.
+  class SocialIdentity < ApplicationRecord
+    self.table_name = "standard_id_social_identities"
+
+    belongs_to :account, class_name: StandardId.config.account_class_name
+    belongs_to :identifier, class_name: "StandardId::Identifier"
+
+    validates :provider, presence: true
+    validates :subject, presence: true, uniqueness: { scope: :provider }
+    validates :identifier_id, uniqueness: { scope: :provider }
+
+    # Hosts that upgraded the gem but have not run
+    # 20261002000000_create_standard_id_social_identities yet. Cached by the
+    # schema cache, so this is one lookup per process.
+    def self.available?
+      table_exists?
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+  end
+end

data/db/migrate/20261002000000_create_standard_id_social_identities.rb

@@ -0,0 +1,44 @@
+# Stores the social provider's stable subject id (`sub`) per account, so a
+# returning social login is matched on (provider, sub) instead of on the email
+# address alone.
+#
+# Before this table, `find_or_create_account_from_social` linked a provider
+# login to whichever account held an email identifier with the same address,
+# without looking at `sub` or `email_verified`. Under `link_strategy:
+# :trust_provider`, or for an identifier with a NULL provider, any token that
+# claimed an address could sign in as that address's account.
+#
+# New, empty table: nothing existing is rewritten, and no row is backfilled.
+# Each existing social user gets a row on their next successful login (when the
+# provider reports the email as verified). Until the migration has run, the
+# gem skips subject matching and logs a warning, but still refuses to link an
+# existing account to an unverified provider email.
+#
+# Both foreign keys cascade so the host's account- and identifier-deletion
+# paths keep working unchanged: deleting the email identifier a link was made
+# through removes the link, and the next login has to re-link on a verified
+# email.
+class CreateStandardIdSocialIdentities < ActiveRecord::Migration[8.0]
+  include StandardId::MigrationHelpers
+
+  def change
+    create_table :standard_id_social_identities, id: primary_key_type do |t|
+      t.references :account, type: foreign_key_type, null: false, index: true,
+        foreign_key: { to_table: StandardId.account_class.table_name, on_delete: :cascade }
+      t.references :identifier, type: foreign_key_type, null: false, index: false,
+        foreign_key: { to_table: :standard_id_identifiers, on_delete: :cascade }
+
+      t.string :provider, null: false
+      t.string :subject, null: false
+
+      t.timestamps
+    end
+
+    # One account per provider subject.
+    add_index :standard_id_social_identities, [:provider, :subject], unique: true
+    # One subject per provider for a given email identifier: a second subject
+    # claiming the same address is refused as a possible takeover.
+    add_index :standard_id_social_identities, [:identifier_id, :provider], unique: true,
+      name: "index_standard_id_social_identities_on_identifier_and_provider"
+  end
+end

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -478,10 +478,14 @@ StandardId.configure do |c|
   # Default: []
   # c.social.available_scopes = %w[profile email offline_access]
 
-  # Account linking strategy:
-  #   :strict          — refuse to link a social identity unless the email
-  #                      already matches a verified identifier (default)
-  #   :trust_provider  — accept the social provider's claim and create or link
+  # Account linking strategy, for a social login whose (provider, sub) is not
+  # linked yet but whose email belongs to an existing account:
+  #   :strict          — link only if that email identifier came from the same
+  #                      provider, predates provider tracking, or the account
+  #                      already has an identifier from this provider (default)
+  #   :trust_provider  — link to the account that holds the email
+  # Under both, the provider must report the email as verified, and an email
+  # already linked to a different sub from the same provider is refused.
   # Default: :strict
   # c.social.link_strategy = :trust_provider
 

data/lib/standard_id/config/schema.rb

@@ -565,6 +565,10 @@ StandardId::ConfigSchema.define do
     field :social_account_attributes, type: :any, default: nil
     field :allowed_redirect_url_prefixes, type: :array, default: []
     field :available_scopes, type: :array, default: -> { [] }
+    # How a social login whose (provider, sub) is not linked yet may link to
+    # an existing account that holds its email: :strict or :trust_provider.
+    # Either way the provider must report the email as verified. See
+    # StandardId::SocialAuthentication#find_or_create_account_from_social.
     field :link_strategy, type: :symbol, default: :strict
     # What to do at boot when an enabled social provider is missing required
     # config (e.g. apple_client_id set without apple_private_key). :warn logs

data/lib/standard_id/errors.rb

@@ -154,12 +154,23 @@ module StandardId
   # NOTE: email and provider_name are exposed as reader attributes for host
   # apps to build custom error responses. If you report exceptions to an
   # error tracker (Sentry, etc.), be aware these attributes contain PII.
+  #
+  # `reason` says why the link was refused:
+  #   :link_required    — the email belongs to an account the strict
+  #                       link_strategy will not link this provider to
+  #   :email_unverified — the provider did not report the email as verified,
+  #                       so it cannot prove ownership of the existing account
+  #   :subject_mismatch — the account's email identifier is already linked to a
+  #                       different subject (`sub`) from this provider
   class SocialLinkError < OAuthError
-    attr_reader :email, :provider_name
+    REASONS = %i[link_required email_unverified subject_mismatch].freeze
+
+    attr_reader :email, :provider_name, :reason
 
-    def initialize(email:, provider_name:)
+    def initialize(email:, provider_name:, reason: :link_required)
       @email = email
       @provider_name = provider_name
+      @reason = reason
       super("This email is already associated with an account. Please sign in first to link this provider.")
     end
 

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.43.1"
+  VERSION = "0.44.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.43.1
+  version: 0.44.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: bcrypt
   requirement: !ruby/object:Gem::Requirement
@@ -195,6 +195,7 @@ files:
 - app/models/standard_id/refresh_token.rb
 - app/models/standard_id/service_session.rb
 - app/models/standard_id/session.rb
+- app/models/standard_id/social_identity.rb
 - app/models/standard_id/username_identifier.rb
 - app/views/standard_id/password_reset_mailer/reset_email.html.erb
 - app/views/standard_id/password_reset_mailer/reset_email.text.erb
@@ -235,6 +236,7 @@ files:
 - db/migrate/20260611000000_create_standard_id_client_grants.rb
 - db/migrate/20260915000000_remove_refresh_token_lifetime_from_standard_id_client_applications.rb
 - db/migrate/20260924000000_add_unique_active_device_index_to_standard_id_sessions.rb
+- db/migrate/20261002000000_create_standard_id_social_identities.rb
 - lib/generators/standard_id/install/install_generator.rb
 - lib/generators/standard_id/install/templates/standard_id.rb
 - lib/standard_id.rb
@@ -345,7 +347,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A comprehensive authentication engine for Rails, built on the security primitives
   introduced in Rails 8.