standard_id 0.44.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea9ca4b9484333d3ed979bc9479b3ddcbde475a3d4f63e9903a0a4b437d925e7
-  data.tar.gz: 99b5c5993640de8c2634fbdd96fcacb95806a35c130d5b268d7daf51382c5275
+  metadata.gz: 2a825be521399d2fbb91a820cbc0da601d24865a12fc549d1a8697ea1d6c97cb
+  data.tar.gz: da555da47e6a9ae99f1c888e5ef93c2fc4a02d21b11993300c67d02df6ef5d01
 SHA512:
-  metadata.gz: a17095049de6adf0c32413fad6322a58b2f50b77c5db052043a74f082e40e6374518d22dad2518eeb4a01c15921865af993b51bae46447a8ee0135e968e6ec14
-  data.tar.gz: 2262c87410fd09684f885818aca1f31de00fe6f12daad4db0c6706521acf4d852ee2bdc623e15cc83da1aea9a7fbb7001eaab0129331ff93904056055cef4e9d
+  metadata.gz: f54bf303a4cc32095b3117df9636b9f3e04ebe4483de5b79f513a0089b44d45a36a3ff7dbaf54d0858a4c29c657e11452f9e7b4ffe89e7418fbf55598ecf75a7
+  data.tar.gz: 157b2b4ffdca2f4a22eaf78207ba28579ef71c59693d6f8587159be19bd36d9540c008e9ede3bbbcc9f313f10d5ef762b9553e898428ffe4f37f7f513c83c2ef

data/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.46.0] - 2026-10-05
+
+### Added
+
+- **Callback `iss` for providers (RFC 9207).** The web and API social callbacks pass the request's `iss` parameter to `get_user_info` as `callback_iss:` when it is a String, so a provider can refuse an authorization-server mix-up without hooking the callback controller itself. On the API callback, `iss` is no longer forwarded to `SOCIAL_AUTH_COMPLETED` subscribers as `original_request_params`, like the other OAuth-flow params.
+- **Core-managed PKCE: `Providers::Base.supports_pkce?`** (default `false`). For a provider that returns `true`, `/login?connection=<provider>` generates a fresh verifier per sign-in, stores it with the state and nonce in the encrypted pending-requests cookie, and passes `code_challenge:` / `code_challenge_method: "S256"` to `authorization_url`. The web callback passes the stored verifier to `get_user_info` as `code_verifier:`, and refuses a callback whose stored request has none. The API callback never passes a verifier (it has no server-held flow state; a client-supplied `code_verifier` is not forwarded), and the API social login grant refuses a PKCE provider. `build_authorization_url` emits `code_challenge` / `code_challenge_method` when `options` carries them; `Providers::Base.pkce_s256_challenge(verifier)` computes the S256 challenge. Providers that do not opt in see no change: both new kwargs reach them only through `**options`, and nil values are not passed. See the README, "Callback `iss` and core-managed PKCE".
+
+### Fixed
+
+- **Social-link races are classified correctly under MySQL/InnoDB `REPEATABLE READ`.** When a concurrent login committed a rival `(provider, sub)` or `(identifier, provider)` row after this login's lookup, the re-read that decides who won ran inside the link transaction as a plain `SELECT`. Under `REPEATABLE READ` that read the transaction's earlier snapshot, missed the rival, and re-raised the `RecordNotUnique`: a 500 with no `SOCIAL_LINK_BLOCKED` instead of a retryable `invalid_grant` (or adopting a same-account rival). `SocialAuthentication#classify_social_link_race!` now uses locking reads (`SELECT ... FOR UPDATE`), which always see the latest committed row. PostgreSQL (`READ COMMITTED`) already saw the rival and behaves as before; on SQLite the lock is a no-op.
+- **A refused request's new account is reclaimed when the login it was kept for fails too.** Since 0.45.0, `AccountCleanup.destroy_newly_created!` keeps a refused request's new account when a concurrent login (B) has already signed in to it. If B then failed as well, B revoked its own session or refresh token but, not having created the account, removed nothing, so the account and its identifier were left behind with no way in and blocked a later signup for that address. The kept account now remembers the session and refresh-token ids it was kept for (in `StandardId.cache_store`, for one hour), and the social callbacks and `handle_authentication_denied` call the new **`AccountCleanup.reclaim_for_failed_adopter!`** with what the failing login issued. The account is removed, under the same row lock, only when one of those credentials was among the remembered ones and nothing else is signed in to it; if another login still is, the account is kept for that one instead. A login that succeeded, or any other later sign-in, never triggers the removal. This needs a cache store shared by all processes (e.g. Solid Cache or Redis); with a per-process store or `:null_store` nothing is remembered and the account is kept, as in 0.45.0.
+- **`SOCIAL_ACCOUNT_LINKED` is no longer published for a link that was never recorded.** When `SocialAuthentication#record_social_identity!` found a `(provider, sub)` row that was then removed (for example by a concurrent account cleanup) before `classify_social_link_race!` re-read it, it returned without inserting: the provider backfill committed and `SOCIAL_ACCOUNT_LINKED` was published, yet no `(provider, sub)` row existed, so later logins were not matched by subject. The `sub` is free at that point, so the login now goes on to insert the row (any rival that commits meanwhile is classified as before), and the event is published only for a row that was inserted or adopted. Under MySQL/InnoDB `REPEATABLE READ` the uniqueness validations of that insert read the transaction's snapshot, which still holds the removed row, and raised `RecordInvalid`; when the locking re-read finds no rival, the insert is now retried once without validations (every other validation passed, and unique indexes back both uniqueness rules).
+
+## [0.45.0] - 2026-10-04
+
+Two opt-in hooks that the org-IdP provider plugin (`standard_id-void_which_binds`) needs. With neither configured, behaviour is unchanged.
+
+### 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,22 +1526,66 @@ 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+) |
+| `supports_pkce?` | `false` | `true` makes core generate, store and hand back a PKCE (S256) verifier for the web flow; see "Callback `iss` and core-managed PKCE" (0.46+) |
 
 **Protected helpers** for use inside those methods — signatures are stable:
 
 | Helper | Does |
 |--------|------|
 | `build_response(user_info, tokens:)` | The standard `get_user_info` return value |
-| `build_authorization_url(endpoint:, client_id:, redirect_uri:, state:, options: {}, defaults: {}, response_type: "code")` | `client_id`, `redirect_uri`, `response_type`, `state`, then each `supported_authorization_params` entry from `options` or `defaults`; nils dropped |
+| `build_authorization_url(endpoint:, client_id:, redirect_uri:, state:, options: {}, defaults: {}, response_type: "code")` | `client_id`, `redirect_uri`, `response_type`, `state`, then each `supported_authorization_params` entry from `options` or `defaults`, then `code_challenge` / `code_challenge_method` from `options`; nils dropped |
 | `extract_tokens(parsed_token)` | `{ access_token:, refresh_token:, id_token: }` from a token response, nils dropped |
 | `verify_nonce!(expected:, actual:)` | Constant-time nonce check; no-op when `expected` is blank. Raises `InvalidRequestError` without echoing either value |
 | `rescue_to_oauth_error(message_prefix = nil) { ... }` | Lets `StandardId::OAuthError` through; wraps anything else in one, keeping `cause` |
+| `pkce_s256_challenge(code_verifier)` (public) | `BASE64URL(SHA256(verifier))`, unpadded (RFC 7636 S256) |
 
 A plugin using `env:`, `required:` or these helpers should depend on
 `standard_id >= 0.42`. `Providers::Base.setup` is no longer called (removed
 from the base class in 0.42; the call-with-a-warning shim went in 0.43) — do
 one-off initialization in your own Railtie instead.
 
+#### Callback `iss` and core-managed PKCE (0.46+)
+
+Core hands two more values to `get_user_info`, so a provider does not have to
+capture or derive them itself. Both arrive through `**options`; a provider
+that does not name them ignores them, and a nil value is never passed.
+
+- **`callback_iss:`** — the callback's `iss` parameter (RFC 9207), when the
+  redirect carried one as a String. Compare it with the issuer you expect
+  before exchanging the code (authorization-server mix-up defence). It is
+  passed on both the web callback and `/api/oauth/callback/:provider` (where
+  it is whatever the client relayed); refuse a missing one if your IdP always
+  sends it.
+- **`code_verifier:`** — for a provider whose `supports_pkce?` returns `true`.
+  On every `/login?connection=<provider>` core generates a fresh verifier,
+  stores it with the state and nonce in the encrypted pending-requests cookie
+  (it never appears in a URL), and passes `code_challenge:` and
+  `code_challenge_method: "S256"` to `authorization_url`
+  (`build_authorization_url` emits both). At the web callback the stored
+  verifier comes back as `code_verifier:`; send it in the token request. A
+  web callback whose stored request has no verifier (a state issued for
+  another provider, or one started before the provider opted in) is refused
+  before the provider is called.
+
+```ruby
+def self.supports_pkce? = true
+
+def self.get_user_info(code: nil, redirect_uri: nil, nonce: nil, callback_iss: nil, code_verifier: nil, **_options)
+  raise StandardId::InvalidRequestError, "issuer mismatch" unless callback_iss == EXPECTED_ISSUER
+  raise StandardId::InvalidRequestError, "web sign-in only" if code_verifier.blank?
+
+  # POST code, redirect_uri and code_verifier to the token endpoint ...
+end
+```
+
+The API paths keep no server-side flow state, so they never pass a
+`code_verifier:` (a client-supplied `code_verifier` param is not forwarded),
+and the API social login grant (`/authorize?connection=...`) refuses to start
+a sign-in for a provider that `supports_pkce?` rather than send it without a
+challenge. A PKCE provider is therefore web-only unless it handles a native
+flow itself.
+
 **Testing a plugin, or an app that uses one:**
 
 ```ruby

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

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