standard_id 0.44.0 → 0.45.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea9ca4b9484333d3ed979bc9479b3ddcbde475a3d4f63e9903a0a4b437d925e7
-  data.tar.gz: 99b5c5993640de8c2634fbdd96fcacb95806a35c130d5b268d7daf51382c5275
+  metadata.gz: 7acc907df7682568d732664fb09873ab023b696e4057095b261a318aab7543b1
+  data.tar.gz: f20929b44d2669f600e304345dbc34992fe9df54b9ff7e40fd64b45731a117e1
 SHA512:
-  metadata.gz: a17095049de6adf0c32413fad6322a58b2f50b77c5db052043a74f082e40e6374518d22dad2518eeb4a01c15921865af993b51bae46447a8ee0135e968e6ec14
-  data.tar.gz: 2262c87410fd09684f885818aca1f31de00fe6f12daad4db0c6706521acf4d852ee2bdc623e15cc83da1aea9a7fbb7001eaab0129331ff93904056055cef4e9d
+  metadata.gz: ac1c4b0e6148140f310456a71fa9e88e162750aa35707b945c2b7c0061a19b1cae54a0cc2fb33b8b418d151c6bfd60190f49669c9cb14dedb159c6bb3b448602
+  data.tar.gz: 99ddde4158e6354df56d377ed3508cb4111207492b62f12ffcb9c6276a862c0bd0e7cbbcc22e41a026b3073db3252325d6a354be903e3413bf5431ac8ea9f45d

data/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+
+- **`Providers::Base.trusted_for_linking?`** (default `false` for every provider, including Google and Apple). When a provider returns exactly `true`, the `:strict` link_strategy may link its login to an existing account that was created through **another** provider, when the emails match. Every 0.44 (L1-01) guard still applies, and one more is added for this path:
+  - the provider must report `email_verified` as `true` / `"true"` (`:email_unverified` otherwise);
+  - the existing email identifier must itself be verified, closing pre-account hijacking (`:link_required` otherwise);
+  - the identifier must not be linked to a different `sub` from that provider (`:subject_mismatch`);
+  - a stored `(provider, sub)` match still wins over any email match.
+
+  Only an organisation's own IdP, whose email claims the organisation provisions and verifies (e.g. moneta's broker-local directory), should return `true`. A public IdP must not: anyone who controls an address there could take over the matching account here. See the README, "Trusted linking for the organisation's own IdP".
+- **`c.login_method_policy`**: a callable consulted in every flow that establishes a new authentication, after the credential is proven and before any session, token or cookie is created. It receives any subset of `account:`, `auth_method:` (`:password`, `:passwordless`, `:social`, `:remember_me`, `:unspecified`), `provider:`, `request:` and `flow:`. Return truthy to allow, `false`/`nil` to refuse, or raise `StandardId::LoginMethodDenied` with a message. Default `nil` (allow all). Covered flows:
+  - web: `/login` password, `/signup`, `/login_verify` passwordless, the social callback, remember-me re-authentication, and host calls to `session_manager.sign_in_account`;
+  - API: the `password`, `passwordless_otp` and `refresh_token` token grants, the `/api/oauth/callback/:provider` social callback, and host calls to `Api::TokenManager#create_device_session` / `#create_service_session`.
+
+  The `refresh_token` grant is checked with the method of the **original** sign-in (flow `:oauth_refresh_token`; see below). `authorization_code`, the implicit flow and `client_credentials` derive from an earlier authentication (or have no account) and are not gated. A refusal redirects to `/login` with the message as the alert on the web, returns `403 access_denied` on the API, signs out silently for remember-me, and removes an account that the same request had just created. A refused `refresh_token` grant answers `400 invalid_grant` ("Refresh token is no longer valid", the same as any dead refresh token, so the presenter learns nothing) and revokes the token family. The table and the full contract are in the README under "Restricting sign-in methods".
+- **Authentication lineage** (`StandardId::AuthLineage`). The sign-in method and provider are recorded and carried along: web sign-in → `BrowserSession#metadata` (`auth_method`, `auth_provider`) → the authorization code minted from it (`metadata`) → the refresh token → every rotated successor. Migration **`20261004000000_add_auth_method_to_standard_id_refresh_tokens`** adds the two nullable `auth_method` / `auth_provider` string columns to `standard_id_refresh_tokens`. There is no default, index or backfill, so on PostgreSQL the change is metadata-only and safe under StrongMigrations. Until the migration has run the gem does not write the columns. `Web::TokenManager#create_browser_session` and `Oauth::AuthorizationFlow.new` take an optional `auth_lineage:`.
+- **`StandardId::LoginMethodDenied`** (subclass of `AuthenticationDenied`, so existing web handling covers it; `oauth_error_code` `:access_denied`, `http_status` `:forbidden`) and the event **`authentication.method.denied`** (`AUTHENTICATION_METHOD_DENIED`; payload `account`, `auth_method`, `provider`, `flow`, `error_message`). The event is in `SECURITY_EVENTS`, so audit trails that record `standard_id.authentication.*` pick it up.
+- `Web::SessionManager#sign_in_account` takes optional `auth_method:`, `provider:` and `flow:`. `Api::TokenManager#create_device_session` and `#create_service_session` take optional `auth_method:` and `provider:`. Host code that signs accounts in itself should pass `auth_method:`; without it a configured policy sees `:unspecified`.
+- `StandardId::AccountCleanup.destroy_newly_created!`, extracted from `LifecycleHooks#destroy_newly_created_account` so the API grants can share it.
+
+### Changed
+
+- **A refused social login no longer leaves its provider link behind.** On the web and API callbacks, the `(provider, sub)` row and any provider backfilled onto a `NULL`-provider email identifier are written only once the login is accepted, in one transaction. When the login-method policy, `before_sign_in`, a scope/profile check or anything later refuses the sign-in, nothing is written. On the web the write shares a transaction with the final redirect, so a redirect that raises (e.g. an `after_sign_in` URL on a host that is not allowed) rolls the link back too. Links that existed beforehand are kept.
+- **`social.account.linked` is published only after the link is written.** It was published as soon as an email match was found, so a refused login left an audit record of a link that never existed. A login that matches an existing link by `sub` still publishes it at match time. Because the link has already committed when it is published, a subscriber that raises no longer fails the login: the error is logged and reported to `Rails.error` (`handled: true`). Put guards on events that fire before anything is written.
+- **A refused request's new account is removed only if nothing else is using it.** `AccountCleanup.destroy_newly_created!` now locks the account row and keeps the account when it has an active session or refresh token (the refusing request revokes its own first); it returns `true` when it removed the account. The social callbacks take the same lock before writing a link and fail when the account is gone. So a concurrent login for the same email either signs in first and the account is kept, or fails with a retryable error (web: `/login` with an alert; API: `400 invalid_grant`) and a retry creates a fresh account. It never signs in to, or links to, an account that is being removed. The API callback now revokes the refresh token (and its session) the grant persisted even when the grant raised after writing them (`TokenGrantFlow#issued_refresh_token`).
+- When two logins race to create the same `(provider, sub)` row and the winner belongs to a different account, the loser now fails with `invalid_grant` instead of signing in to one account while the subject is linked to another. The link is now written with an explicit find-then-insert (no longer `find_or_create_by!`), and every way the race surfaces is classified: a rival row found by the SELECT, a uniqueness-validation `RecordInvalid` (rival committed after the SELECT), or a unique-index `RecordNotUnique` (rival committed after validation). A rival for the same account is adopted. Any other `RecordInvalid` still propagates. The refusal raises `StandardId::SocialLinkConflictError` (a subclass of `InvalidGrantError`, so clients still see a retryable `invalid_grant`) and publishes `SOCIAL_LINK_BLOCKED` with the new reason **`:subject_conflict`**, after the link transaction has rolled back. The web callback no longer reports it as `SOCIAL_AUTH_FAILED`, which is for infrastructure failures. When instead the `(identifier, provider)` index wins (a concurrent login linked the same identifier to the provider under another sub), the reason is `:subject_mismatch`.
+
+### Upgrade notes
+
+1. Run `bin/rails standard_id:install:migrations && bin/rails db:migrate` (one new migration: two nullable columns on `standard_id_refresh_tokens`).
+2. Nothing changes until you set `c.login_method_policy` or a provider plugin returns `trusted_for_linking? == true`.
+3. **Before enabling a restrictive policy (e.g. `standard_id-void_which_binds`' `require_for_staff`), update host code that signs accounts in itself.** Calls to `session_manager.sign_in_account(account)` and `Api::TokenManager#create_device_session` / `#create_service_session` without `auth_method:` reach the policy as `:unspecified`. A staff policy treats that as "not via the org IdP" and refuses: the call raises `StandardId::LoginMethodDenied`, which is an `AuthenticationDenied`. Pass the real method (e.g. `auth_method: :password`, or `:social` with `provider:`) and rescue `StandardId::AuthenticationDenied`. Known call sites without it: nutripod-web (`ApplicationController`, `Inertia::ApplicationController`, `InviteAcceptancesController`, `Auth::SessionActions`) and fundbright-web (`OrganisationInvitationsController`, `PlatformInvitationsController`, `Widget::OffersController`, `Auth::SessionActions`).
+4. **Expect existing OAuth clients to re-authenticate once a restrictive policy is on.** Refresh tokens minted before 0.45 (or before the migration) carry no method and are checked as `:unspecified`, so such a policy refuses them (`invalid_grant`) and revokes their family. This fails closed by design. Existing browser sessions are not re-checked; revoke them if they must end.
+
+### Fixed
+
+- **Remember-me restore raised `ArgumentError` (500).** `SessionManager#load_session_from_remember_token` passed `remember_me: true` to `Web::TokenManager#create_browser_session`, which has no such keyword, so every request carrying a valid remember-me cookie and no live session failed. The restored session now records its lineage as `auth_method: "remember_me"`, the method the login-method policy checked, so refresh tokens derived from it are re-checked as `:remember_me`.
+- **The OAuth `password` grant failed for every existing user.** `PasswordFlow` preloaded `credential: :account`, but `Credential` reaches the account through its identifier and has no such association. Any request that found a credential raised `ActiveRecord::AssociationNotFoundError` (500). A wrong password for an existing login also returned 500 (`false.account`) instead of `400 invalid_grant`. Both have existed since the grant was added. The grant had no request-level coverage; `spec/requests/standard_id/api/oauth/password_grant_spec.rb` now covers it.
+
 ## [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**.

data/README.md

@@ -673,6 +673,7 @@ Every StandardId event automatically carries tracing metadata (`event_id`, `time
 |  | `authentication.attempt.failed` | `account_lookup`, `auth_method`, `error_code`, `error_message` | After authentication fails |
 |  | `authentication.password.failed` | `account_lookup`, `error_code`, `error_message` | After password verification fails |
 |  | `authentication.otp.failed` | `identifier`, `channel`, `error_code`, `error_message` | After OTP verification fails |
+|  | `authentication.method.denied` | `account`, `auth_method`, `provider`, `flow`, `error_message` | `config.login_method_policy` refused the method, after the credential was proven and before any session or token was created (0.45+) |
 | Session | `session.creating` | `account`, `session_type`, `ip_address`, `user_agent` | Before a session record is created |
 |  | `session.created` | `session`, `account`, `session_type`, `token_issued`, `ip_address`, `user_agent` | After session persistence completes |
 |  | `session.validating` | `session` | Before validating an existing session |
@@ -708,7 +709,7 @@ Every StandardId event automatically carries tracing metadata (`event_id`, `time
 |  | `social.auth.callback_received` | `provider`, `code`, `state` | After the provider redirects back |
 |  | `social.user_info.fetched` | `provider`, `social_info`, `email` | After fetching user info from the provider |
 |  | `social.account.created` | `account`, `provider`, `social_info` | When a social login creates a new account |
-|  | `social.account.linked` | `account`, `provider`, `identifier` | When a social identity links to an existing account |
+|  | `social.account.linked` | `account`, `provider`, `identifier` | When a social login links to an existing account by email (published once the link is written, never for a refused login), or matches an existing link by `sub` |
 |  | `social.auth.completed` | `account`, `provider`, `tokens` | After social login completes |
 |  | `social.auth.failed` | `provider`, `error`, `error_class`, `account` | When social login fails due to an infrastructure error (HTTP/DNS/SSL/timeout) |
 | Credential | `credential.password.created` | `credential`, `account` | After a password credential is created |
@@ -1174,7 +1175,10 @@ redirect_to "/api/authorize?" + {
    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`);
+   - `link_strategy` allows it (`:link_required` under `:strict`). Under
+     `:strict`, a provider whose `trusted_for_linking?` returns `true` may
+     link to an account created through another provider, but only when the
+     existing email identifier is itself verified (see below);
    - 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`
@@ -1182,6 +1186,10 @@ redirect_to "/api/authorize?" + {
      `:trust_provider` too.
 
    A successful link stores the `sub`, so the next login matches on step 1.
+   If a concurrent login commits the same `sub` for a **different** account
+   while this one writes its link, the login fails with a retryable
+   `invalid_grant` (`StandardId::SocialLinkConflictError`) and
+   `SOCIAL_LINK_BLOCKED` is published with reason `:subject_conflict`.
 3. **New account.** Otherwise a new account is created, as before, and the
    `sub` is stored.
 
@@ -1189,6 +1197,118 @@ 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.
 
+#### Trusted linking for the organisation's own IdP (0.45+)
+
+`:strict` refuses to link, say, an org-SSO login to an existing account that
+was first created by a Google login, even when the addresses match. A provider
+plugin can lift that one refusal by returning `true` from
+`Providers::Base.trusted_for_linking?` (default `false` for every provider,
+including Google and Apple, so nothing changes unless a plugin opts in).
+
+**Only the organisation's own identity provider should ever return `true`**:
+one whose email claims the organisation itself provisions and verifies, such as
+a broker-local directory (moneta, via `standard_id-void_which_binds`). A public
+IdP lets anyone register an address there; trusting it would let whoever holds
+an address *at that IdP* take over the account holding the same address here.
+
+Trust relaxes only the `:strict` cross-provider check. The link is still
+refused unless all of these hold:
+
+- the provider reports `email_verified` as `true` / `"true"`
+  (`:email_unverified` otherwise);
+- the existing email identifier is verified (`verified_at` set). This closes
+  pre-account hijacking: someone who registered an account for an address they
+  never proved must not have it handed to the address's real owner (they would
+  keep their own way in). Refused as `:link_required`;
+- the identifier is not linked to a different `sub` from the same provider
+  (`:subject_mismatch`);
+- `trusted_for_linking?` returns exactly `true` (a truthy string does not count).
+
+A stored `(provider, sub)` match still wins over any email match.
+
+### Restricting sign-in methods (`login_method_policy`, 0.45+)
+
+`c.login_method_policy` decides, per account, which authentication methods may
+sign it in, for example "staff must sign in with the org IdP". The default
+(`nil`) allows everything.
+
+```ruby
+StandardId.configure do |c|
+  # Any subset of: account:, auth_method:, provider:, request:, flow:
+  c.login_method_policy = ->(account:, auth_method:, provider:) {
+    next true unless account.staff?
+    next true if auth_method == :social && provider == "void_which_binds"
+
+    raise StandardId::LoginMethodDenied, "Staff must sign in with Void Which Binds"
+  }
+end
+```
+
+Return a truthy value to allow, `false`/`nil` to refuse with a generic
+message, or raise `StandardId::LoginMethodDenied` with your own message. Any
+other exception propagates, so a broken policy fails closed.
+
+The policy is consulted in every flow that establishes a new authentication,
+**after** the credential is proven (password checked, code verified, provider
+token verified) and **before** any session, token or cookie is created. Because
+it runs only after the credential is proven, its message reaches only someone
+who already controls the credential; a wrong password still gets the flow's
+usual "invalid" answer and never reaches the policy.
+
+| `flow` | `auth_method` | Refusal |
+|--------|---------------|---------|
+| `:web_password` (`/login`) | `:password` | redirect to `/login`, message as flash alert |
+| `:web_signup` (`/signup`) | `:password` | same; the just-created account is removed |
+| `:web_passwordless` (`/login_verify`) | `:passwordless` | same; a just-registered account is removed |
+| `:web_social` (`/auth/callback/:provider`) | `:social` + `provider` | same; a just-created account is removed |
+| `:web_remember_me` (remember-me cookie) | `:remember_me` | signed out silently, remember cookie cleared |
+| `:web_session` (`session_manager.sign_in_account` from host code) | what you pass, else `:unspecified` | raises `LoginMethodDenied` (an `AuthenticationDenied`) |
+| `:oauth_password_grant` | `:password` | `403 {"error":"access_denied"}` |
+| `:oauth_passwordless_otp_grant` | `:passwordless` | `403 access_denied`; a just-registered account is removed |
+| `:oauth_social_callback` (`/api/oauth/callback/:provider`) | `:social` + `provider` | `403 access_denied`; a just-created account is removed |
+| `:oauth_refresh_token` | the **original** sign-in's method (and provider), else `:unspecified` | `400 invalid_grant` ("Refresh token is no longer valid"), and the token family is revoked |
+| `:api_device_session` / `:api_service_session` (`Api::TokenManager#create_*_session` from host code) | what you pass, else `:unspecified` | raises `LoginMethodDenied` |
+
+**Refresh tokens remember how their authentication was made.** The method
+(and provider) is recorded at sign-in and carried along: web sign-in → the
+browser session's `metadata` → the authorization code minted from it at
+`/api/authorize` → the refresh token (`auth_method` / `auth_provider` columns,
+migration `20261004000000`) → every rotated successor. The `refresh_token`
+grant re-checks the policy with that original method, so tightening the policy
+takes effect at each OAuth client's next refresh. A refused refresh is answered
+like any dead refresh token (`invalid_grant`, nothing about why, since whoever
+presents a refresh token may not be its holder) and revokes the family; the
+reason is in the `authentication.method.denied` event. Refresh tokens minted
+before 0.45 (or before the migration ran) have no recorded method and are
+checked as **`:unspecified`**: a policy that requires a particular method will
+refuse them, failing closed, and those clients must sign in again.
+
+Not gated: the `authorization_code` grant and the implicit flow (minted within
+minutes from a browser session that passed the policy when it was created) and
+`client_credentials` (no account). Browser sessions that already exist are not
+re-checked when the policy changes; revoke them if they must end.
+
+A refused social login also leaves no trace of the link: the `(provider, sub)`
+row and any provider backfilled onto the email identifier are written only once
+the login is accepted (on the web, together with the final redirect), so a
+refusal by the policy, `before_sign_in`, a scope check or a failing redirect
+writes nothing and publishes no `social.account.linked`.
+
+A just-created account is removed only if no other sign-in is using it. When a
+concurrent login for the same email has already signed in to it, it is kept;
+when the removal goes first, that login fails with a retryable error (web:
+redirect to `/login`; API: `400 invalid_grant`), never signs in to the removed
+account, and a retry creates a fresh one.
+
+Every refusal publishes `authentication.method.denied`.
+
+**Host code that signs accounts in itself** (`session_manager.sign_in_account`,
+`Api::TokenManager#create_device_session`) should pass the method, e.g.
+`session_manager.sign_in_account(account, auth_method: :password)`, and rescue
+`StandardId::AuthenticationDenied` (which `LoginMethodDenied` subclasses) as the
+engine's controllers do. Without `auth_method:` the policy sees
+`:unspecified`, which a restrictive policy will refuse.
+
 ### Passwordless Authentication
 
 ```ruby
@@ -1406,6 +1526,7 @@ end
 | `flow_for(params)` | `:web` only for `flow=web` on providers that `supports_mobile_callback?`, else `:mobile` | Flow for the API callback |
 | `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+) |
 
 **Protected helpers** for use inside those methods — signatures are stable:
 

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

@@ -208,25 +208,10 @@ module StandardId
 
     # Destroy a newly created account and all its dependents.
     # Used when after_sign_in rejects a just-created account to avoid orphans.
-    #
-    # Every association read goes through `.strict_loading(false)`: the account
-    # was built in this request, so none of its associations are loaded, and a
-    # host running `strict_loading_by_default = true` (most consumers) would
-    # otherwise raise StrictLoadingViolationError on `account.sessions` — turning
-    # a hook's clean rejection of a new signup into a 500 and leaving the
-    # orphaned account behind. Relation-level `strict_loading(false)` also covers
-    # the records it loads, so `identifier.credentials` below is safe too.
+    # See StandardId::AccountCleanup (shared with the API token grants, which
+    # do the same when the login-method policy refuses a new account).
     def destroy_newly_created_account(account)
-      return unless account&.persisted?
-
-      ActiveRecord::Base.transaction do
-        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
-      end
+      StandardId::AccountCleanup.destroy_newly_created!(account)
     end
 
     # Resolve the active scope name for the current request.

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

@@ -38,7 +38,9 @@ module StandardId
     #    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 link_strategy allows it (validate_social_link!; under :strict a
+    #        provider that is trusted_for_linking? may link across providers
+    #        to a verified identifier),
     #      - 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
@@ -70,9 +72,9 @@ module StandardId
         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)
+        # SOCIAL_ACCOUNT_LINKED is published by commit_social_link!, once the
+        # link has been written — never for a staged link that is dropped.
+        stage_social_link!(identifier, subject, backfill_provider: identifier.provider.nil?, emit_linked: true)
         identifier.account
       else
         account = build_account_from_social(social_info)
@@ -82,7 +84,7 @@ module StandardId
           provider: provider.provider_name
         )
         identifier.verify! if identifier.respond_to?(:verify!) && social_email_verified?(social_info)
-        record_social_identity!(identifier, subject)
+        stage_social_link!(identifier, subject, backfill_provider: false)
         emit_social_account_created(account, provider, social_info)
         account
       end
@@ -103,10 +105,29 @@ module StandardId
       return if identifier.provider.nil?
       return if identifier.provider == provider.provider_name
       return if account_has_social_identifier_from?(identifier.account, provider)
+      return if trusted_cross_provider_link?(identifier, provider)
 
       refuse_social_link!(identifier, provider, :link_required)
     end
 
+    # The provider opted in via Providers::Base.trusted_for_linking? (only the
+    # org's own IdP, whose email claims the org verifies, should) AND the
+    # existing identifier's address is itself verified. This only lifts the
+    # :strict cross-provider refusal: validate_social_subject! and
+    # validate_social_email_verified! still run after it, so an unverified
+    # provider email or a different sub is refused exactly as before.
+    #
+    # The verified-identifier requirement closes pre-account hijacking: an
+    # account someone registered for an address they never proved must not
+    # be handed to the address's real owner arriving via the trusted IdP
+    # (the registrant would keep their own way in).
+    def trusted_cross_provider_link?(identifier, provider)
+      return false unless provider.respond_to?(:trusted_for_linking?)
+      return false unless provider.trusted_for_linking? == true
+
+      identifier.respond_to?(:verified?) && identifier.verified?
+    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)
@@ -159,17 +180,193 @@ module StandardId
       StandardId::SocialIdentity.includes(:account, :identifier).find_by(provider: provider.provider_name, subject: subject)
     end
 
+    # Writes the (provider, sub) row inside its own savepoint (it runs inside
+    # commit_social_link!'s transaction; on PostgreSQL a failed INSERT would
+    # otherwise abort it).
+    #
+    # Find-then-insert is spelled out rather than left to find_or_create_by!,
+    # because a concurrent login can commit a rival row at any point in it and
+    # each point surfaces differently: before the SELECT (the row is found),
+    # between the SELECT and validation (the uniqueness validations raise
+    # RecordInvalid), or between validation and the INSERT (the unique index
+    # raises RecordNotUnique; find_or_create_by! would turn an
+    # (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!.
     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
+      attributes = { provider: provider.provider_name, subject: subject }
+      existing = StandardId::SocialIdentity.find_by(attributes)
+      return classify_social_link_race!(identifier, subject) if existing
+
+      StandardId::SocialIdentity.transaction(requires_new: true) do
+        StandardId::SocialIdentity.create!(attributes.merge(account: identifier.account, identifier: identifier))
+      end
+    rescue ActiveRecord::RecordNotUnique
+      classify_social_link_race!(identifier, subject) || raise
+    rescue ActiveRecord::RecordInvalid => e
+      raise unless social_link_race_invalid?(e.record)
+
+      classify_social_link_race!(identifier, subject) || raise
+    end
+
+    # A RecordInvalid that is only the uniqueness validations losing a race.
+    # Anything else (a missing account, a host validation) is a real error.
+    def social_link_race_invalid?(record)
+      details = record&.errors&.details
+      return false if details.blank?
+
+      details.all? do |attribute, errors|
+        %i[subject identifier_id].include?(attribute) && errors.all? { |error| error[:error] == :taken }
+      end
+    end
+
+    # Another login has linked first. Returns the winning row when it links
+    # this (provider, sub) to the same account (adopt it); raises
+    # SocialLinkConflictError when it links this sub to ANOTHER account
+    # (: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.
+    def classify_social_link_race!(identifier, subject)
+      winner = StandardId::SocialIdentity.find_by(provider: provider.provider_name, subject: subject)
+      if winner
+        return winner if winner.account_id == identifier.account_id
+
+        raise StandardId::SocialLinkConflictError.new(SOCIAL_RETRY_MESSAGE, identifier: identifier, reason: :subject_conflict)
+      end
+
+      other_sub = StandardId::SocialIdentity.where(identifier_id: identifier.id, provider: provider.provider_name).where.not(subject: subject)
+      return nil unless other_sub.exists?
+
+      raise StandardId::SocialLinkConflictError.new(SOCIAL_RETRY_MESSAGE, identifier: identifier, reason: :subject_mismatch)
+    end
+
+    # The (provider, sub) link and the provider backfill are STAGED, not
+    # written, by find_or_create_account_from_social when the caller defers
+    # them (the web and API callbacks do), and written by commit_social_link!
+    # only once the login has been accepted. A rejected login therefore never
+    # writes a link, so rejecting it never has to delete one — and cannot
+    # delete a row a concurrent, successful callback for the same
+    # (provider, sub) has created or adopted in the meantime.
+    #
+    # Callers that do not defer (the default, e.g. host code calling
+    # find_or_create_account_from_social directly) get the link written
+    # immediately, as before.
+    def stage_social_link!(identifier, subject, backfill_provider:, emit_linked: false)
+      @pending_social_link = {
+        identifier: identifier,
+        subject: subject,
+        backfill_provider: backfill_provider,
+        emit_linked: emit_linked
+      }
+      commit_social_link! unless defer_social_link?
+    end
+
+    def defer_social_link?
+      false
+    end
+
+    # Writes the staged link in one transaction: the provider backfill and
+    # the (provider, sub) row land together or not at all, and the staged
+    # state is kept until they have, so a failure part-way leaves nothing to
+    # reverse. A block, when given, runs inside that transaction after the
+    # writes: work the login still has to get through for the link to stand
+    # (the web callback's redirect_to, which can raise). It runs even when
+    # nothing is staged. SOCIAL_ACCOUNT_LINKED is published only after the
+    # transaction has committed.
+    #
+    # The account row is locked first and must still exist. That serialises
+    # this commit with AccountCleanup.destroy_newly_created!, which takes the
+    # same lock: an account another, rejected request created and is now
+    # removing is never linked to (this login fails and can simply be
+    # retried, creating a fresh account), and an account this login has
+    # already signed in to is never removed under it (see AccountCleanup).
+    def commit_social_link!
+      pending = @pending_social_link
+      if pending.nil?
+        yield if block_given?
+        return
+      end
+
+      identifier = pending[:identifier]
+      begin
+        write_social_link!(pending, identifier) { yield if block_given? }
+      rescue StandardId::SocialLinkConflictError => e
+        # A concurrent login won the link (see the error's reasons).
+        # Published here, once the transaction has rolled back, so a
+        # subscriber that writes an audit row is not rolled back with the
+        # link; and only on this path, so never for a link that commits.
+        emit_social_link_blocked(identifier, provider, e.reason)
+        raise
       end
+
+      @pending_social_link = nil
+      if pending[:backfill_provider]
+        identifier.provider = provider.provider_name
+        identifier.clear_attribute_changes([:provider]) if identifier.respond_to?(:clear_attribute_changes)
+      end
+      emit_committed_social_link(identifier, provider) if pending[:emit_linked]
+    end
+
+    # The transaction behind commit_social_link!.
+    def write_social_link!(pending, identifier)
+      ActiveRecord::Base.transaction do
+        if StandardId.account_class.lock.where(id: identifier.account_id).pick(:id).nil?
+          raise StandardId::InvalidGrantError, SOCIAL_RETRY_MESSAGE
+        end
+
+        if pending[:backfill_provider]
+          # Conditional, so a provider set concurrently is never overwritten.
+          StandardId::Identifier.where(id: identifier.id, provider: nil).update_all(provider: provider.provider_name)
+        end
+        record_social_identity!(identifier, pending[:subject])
+        yield if block_given?
+      end
+    end
+
+    # SOCIAL_ACCOUNT_LINKED reports a link that has already committed, so it
+    # cannot refuse the login: a subscriber that raises here would fail the
+    # callback while the link stays. Its error is logged and reported to
+    # Rails.error instead of propagating. (Guards belong on the events that
+    # run before anything is written.)
+    def emit_committed_social_link(identifier, provider)
+      emit_social_account_linked(identifier.account, provider, identifier)
+    rescue StandardError => e
+      Rails.logger&.error("[StandardId] SOCIAL_ACCOUNT_LINKED subscriber raised after the link committed: #{e.class}: #{e.message}")
+      Rails.error.report(e, handled: true, source: "standard_id")
+    end
+
+    # A social login that recorded a link (and maybe created an account) and
+    # was then rejected for ANY reason — policy, hook, invalid scope, audience
+    # 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:)
+      rollback_social_link!
+      StandardId::AccountCleanup.destroy_newly_created!(account) if newly_created
+    end
+
+    # The login matched an account by email that a concurrent, refused
+    # request had created and has since removed (AccountCleanup). The login
+    # then fails part-way (its session insert hits the foreign key, or
+    # commit_social_link! finds the account gone); the callbacks report that
+    # as a retryable invalid_grant rather than a 500. A retry finds no
+    # account and creates a fresh one. Check before discard_social_attempt!,
+    # which removes an account THIS request created.
+    def social_account_removed_concurrently?(account, newly_created:)
+      return false if newly_created || account.nil? || account.id.nil?
+
+      !StandardId.account_class.where(id: account.id).exists?
+    end
+
+    SOCIAL_RETRY_MESSAGE = "The sign-in could not be completed. Please try again.".freeze
+
+    # Nothing was written for a deferred link, so dropping the staged one is
+    # the whole rollback. (A non-deferring caller has already committed it.)
+    def rollback_social_link!
+      @pending_social_link = nil
     end
 
     def social_identities_available?

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

@@ -154,7 +154,12 @@ module StandardId
         # but before session creation. The block may raise AuthenticationDenied.
         before_session&.call(password_credential.account)
 
-        session_manager.sign_in_account(password_credential.account, scope_name: request.path_parameters[:scope])
+        session_manager.sign_in_account(
+          password_credential.account,
+          scope_name: request.path_parameters[:scope],
+          auth_method: :password,
+          flow: :web_password
+        )
         session_manager.set_remember_cookie(password_credential) if remember_me
 
         StandardId::Events.publish(

data/app/controllers/standard_id/api/authorization_controller.rb

@@ -19,7 +19,11 @@ module StandardId
         reject_invalid_redirect_uri!
         return redirect_to_consent if consent_required?
 
-        response_data = flow_strategy_class.new(flow_strategy_params, request, current_account: current_account).execute
+        response_data = flow_strategy_class.new(
+          flow_strategy_params, request,
+          current_account: current_account,
+          auth_lineage: StandardId::AuthLineage.from_session(authorization_session_manager.current_session)
+        ).execute
 
         if response_data[:redirect_to]
           redirect_to response_data[:redirect_to], status: response_data[:status] || :found, allow_other_host: true
@@ -150,10 +154,13 @@ module StandardId
       end
 
       def current_account
-        @current_account ||= begin
+        @current_account ||= authorization_session_manager.current_account
+      end
+
+      def authorization_session_manager
+        @authorization_session_manager ||= begin
           token_manager = StandardId::Web::TokenManager.new(request)
-          session_manager = StandardId::Web::SessionManager.new(token_manager, request: request, session: session, cookies: cookies)
-          session_manager.current_account
+          StandardId::Web::SessionManager.new(token_manager, request: request, session: session, cookies: cookies)
         end
       end
     end

data/app/controllers/standard_id/api/base_controller.rb

@@ -26,6 +26,11 @@ module StandardId
       rescue_from StandardId::AccountDeactivatedError, with: :handle_account_deactivated
       rescue_from StandardId::AccountLockedError, with: :handle_account_locked
 
+      # config.login_method_policy refused the method (token grants, social
+      # callback). Not an OAuthError — it is an AuthenticationDenied so the
+      # WebEngine's existing handling covers it — so it is mapped here.
+      rescue_from StandardId::LoginMethodDenied, with: :handle_login_method_denied
+
       protected
 
       def validate_content_type!
@@ -74,6 +79,17 @@ module StandardId
         render_bearer_unauthorized!(error_description: "The account is locked")
       end
 
+      # `403 access_denied`, the shape SocialLinkError already uses on the API
+      # callback. The policy only runs after the credential was proven, so the
+      # caller already controls it and the policy's message (e.g. "Staff must
+      # sign in with ...") tells them nothing they could not learn otherwise.
+      def handle_login_method_denied(error)
+        render json: {
+          error: error.oauth_error_code.to_s,
+          error_description: error.message
+        }, status: error.http_status
+      end
+
       def handle_oauth_error(error)
         render json: {
           error: error.oauth_error_code,