standard_id 0.43.2 → 0.45.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb59a29db3ed35482b44a1a0755a3827d7e02a6ad3a78bad5e5bd22e309d048
-  data.tar.gz: 93491ec90c91e2fdc6cf900bc62f9475ee786c723f4591dc40446964fbac1492
+  metadata.gz: 7acc907df7682568d732664fb09873ab023b696e4057095b261a318aab7543b1
+  data.tar.gz: f20929b44d2669f600e304345dbc34992fe9df54b9ff7e40fd64b45731a117e1
 SHA512:
-  metadata.gz: 0daceb3e839301ec3b294b8aa36af72441ec5b52ea82bcdcb7066fbc1bfef97cb5efaa11d62f729995c4a7ad22b22afd946e3ed1ff4999fa694a3dc2446b8a50
-  data.tar.gz: ab971a917f3ea552ca3c54d6928a88086bfef17066131cb727a12df721d6bfd2988fb348a33ded3fd529d09102ea053b904ff5146129e9b5008e10e64d7b2f15
+  metadata.gz: ac1c4b0e6148140f310456a71fa9e88e162750aa35707b945c2b7c0061a19b1cae54a0cc2fb33b8b418d151c6bfd60190f49669c9cb14dedb159c6bb3b448602
+  data.tar.gz: 99ddde4158e6354df56d377ed3508cb4111207492b62f12ffcb9c6276a862c0bd0e7cbbcc22e41a026b3073db3252325d6a354be903e3413bf5431ac8ea9f45d

data/CHANGELOG.md

@@ -7,6 +7,78 @@ 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**.
+
+### 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

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 |
@@ -1165,6 +1166,149 @@ 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`). 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`
+     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.
+   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.
+
+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
@@ -1382,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:
 
@@ -1503,12 +1648,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/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.