From 0d19c815c6f152b1b052db054e05ff2b07907ab9 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 17:44:20 +0000
Subject: [PATCH 1/8] docs: plan Saloon OAuth token management

Define cached token acquisition and optional encrypted OAuth account storage using the existing authentication and cache APIs. Specify expiry, credential identity, scope metadata, shared renewal claims, conditional persistence, and bounded recovery from transient provider failures.

Document partition hooks, model customization, transaction and cancellation behavior, database-load expectations, and focused verification. Keep provider-side replay limits explicit and retain application control of credentials and business-request retries.
---
 ...0-24-1738-saloon-oauth-token-management.md | 250 ++++++++++++++++++
 1 file changed, 250 insertions(+)
 create mode 100644 docs/plans/2026-10-24-1738-saloon-oauth-token-management.md

diff --git a/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md b/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
new file mode 100644
index 000000000..d3b9e605d
--- /dev/null
+++ b/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
@@ -0,0 +1,250 @@
+# Saloon token management
+
+## Outcome
+
+Add two opt-in capabilities to `hypervel/saloon`:
+
+- Cache independently reacquirable tokens, such as client-credentials grants, without an application repeating expiry and concurrency handling.
+- Persist connected OAuth accounts, cache their credentials, and renew rotating refresh tokens without holding database connections through provider calls.
+
+Keep manual grant methods, immutable connectors, existing authenticators, request modifiers and application-owned provider credentials. Applications choose their cache stores and publish the account migration only when using durable accounts. No new package, store-driver abstraction, provider registry, scheduler or UI is needed.
+
+Status: ready for implementation; implementation has not started. Implement in the `components-saloon` worktree. The only approved existing API departure is scope metadata on `OAuthAuthenticator`, `AccessTokenAuthenticator` and the corresponding grant factories. No Socialite API change is required.
+
+## Existing boundaries and evidence
+
+Read the current implementations when changing their callers:
+
+| Existing source | Consequence for this design |
+|---|---|
+| `Contracts/OAuthAuthenticator.php`, `Http/Auth/AccessTokenAuthenticator.php` | Token values already own expiry and authentication; extend them instead of adding a parallel token DTO. |
+| `Traits/OAuth2/{ClientCredentialsGrant,ClientCredentialsBasicAuthGrant,AuthorizationCodeGrant,ParsesOAuthTokenResponses}.php` | Keep existing grant construction, configuration and per-call modifiers. Both response factories must carry scopes. |
+| `SaloonManager::send()`, `Http/PendingRequest.php` | Authentication runs when each pending request is built. A normal business-request retry creates a new pending request; never send a business request from token-management code. |
+| `Cache/CacheKey.php` | Default response-cache identity includes authorization headers. Token renewal naturally creates a new response-cache identity. |
+| `Cache/ModelCacheCoordinator.php`, `ModelCacheStoreValidator.php` | Reuse committed model caching, fill/invalidation coordination and supported-store validation. Do not build another coherence protocol. |
+| `Database/Eloquent/Model.php` | Ordinary saves do not compare a version. Use fresh credential revisions and conditional renewal writes. Models are transient; serialization clears cast caches. |
+| `Coroutine/Locker.php`, `Database/ConnectionResolver.php` | Keyed owner/waiter coordination already exists. Release idle connections before provider calls and backoff; do not hold transactions across them. |
+| `Socialite/Two/{Token,AbstractProvider}.php` | A refresh callback can adapt the existing token. An empty approved-scopes array does not distinguish an omitted field. |
+
+Saloon paths are relative to `src/saloon/src`; other package anchors refer to `src/{package}/src`. Existing tests under `tests/Saloon/Feature/Oauth2`, authentication tests and cache integration tests establish the surrounding behavior.
+
+Relevant external evidence:
+
+- [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html), §§3.3, 5.1, 5.2 and 6: scope metadata, token errors and refresh behavior.
+- [RFC 9700 §4.14.2](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.14.2): replay of a rotated refresh token can revoke the active grant.
+- [OAuth2 Proxy renewal](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/pkg/middleware/stored_session.go): lock, reread, persist, release; transient and rejected-credential failures differ.
+- [Supabase session recovery](https://supabase.com/docs/guides/auth/sessions#what-is-refresh-token-reuse-detection-and-what-does-it-protect-from): retries can be supported by provider reuse grace and parent-token recovery. Do not assume those guarantees for arbitrary providers.
+- [Saloon OAuth addon](https://github.com/SimpleSquid/saloonphp-oauth), available in `references/saloonphp-oauth`: useful comparison, not a port. Do not copy class-name-only token keys, mandatory persistence, or best-effort saving of rotated tokens.
+
+## 1. Token metadata
+
+Append `?array $scopes = null` to `AccessTokenAuthenticator` and add `getScopes(): ?array` to `OAuthAuthenticator`, documented as `null|list<string>`. Preserve current parameter names/order. Append the same optional metadata to both protected `createOAuthAuthenticator()` signatures and update overrides and fixtures together.
+
+- `null`: provider did not report scopes; a renewal retains stored scopes.
+- `[]`: explicitly supplied empty set; do not replace it with a fallback.
+- Parse supplied space-delimited scope strings at the shared OAuth response boundary. Treat absent/null/empty-string metadata as unknown, and reject other wire types. An empty wire string is not a valid reported OAuth scope; it must not erase stored scopes. Custom callbacks can supply normalized lists, including an intentional `[]`, directly. Do not infer effective permissions from the requested scopes when the response omits them.
+- Preserve omitted refresh tokens through the existing fallback path. Scope handling must work for client credentials, Basic-auth client credentials and authorization-code refreshes.
+- Mark credential parameters sensitive. Do not log token response bodies, credentials, or serialized authenticators.
+
+## 2. Cached acquisition
+
+Public usage:
+
+```php
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Http\Auth\CachedTokenAuthenticator;
+
+$authenticator = new CachedTokenAuthenticator(
+    key: $grantIdentity,
+    resolver: fn (): OAuthAuthenticator => $oauth->getAccessToken(),
+    store: 'redis',
+);
+
+$authenticator = $oauth->cachedAccessToken(
+    scopes: ['read'],
+    store: 'redis',
+    requestModifier: fn ($request) => $request->timeout(20),
+);
+
+$authenticator->forget();
+```
+
+`CachedTokenAuthenticator` implements `Authenticator`. Its constructor configuration is immutable; it holds one completed entry for its fixed identity. The entry contains the actual `OAuthAuthenticator` and one computed renewal time, preserving custom token authentication behavior. Never serialize resolver closures or pending requests.
+
+Add `cachedAccessToken()` to the existing client-credentials trait, inherited by the Basic-auth variant. Keep scopes, scope separator, optional store, per-call request modifier, and an optional extra `key` contribution. This convenience returns an authenticator; it does not fetch during connector construction.
+
+### Identity and lifetime
+
+- Hash an unambiguous encoding with SHA-256. The convenience identity includes connector class, resolved token endpoint, client ID, client secret, effective requested scopes and explicit key contribution. The generic constructor requires the caller to identify its complete grant. Never put raw credentials in a key.
+- A modifier, overridden request factory or custom audience can change the grant. Document the extra key contribution for those cases; do not hash closures or prepare a whole pending request on each cache hit.
+- Resolve stores as explicit store → `saloon.cache.store` → framework default. `worker-array` shares entries within a worker; the ordinary `array` driver does not share across request coroutines. Redis supports sharing between workers.
+- Calculate renewal time once: expiry minus a small early allowance, capped at half the token's remaining lifetime. Store that absolute time; rereading an entry does not restart its life. Use a 30-second maximum allowance.
+- Cache only through renewal time. A token without expiry follows the existing non-expiring contract; the caller must provide expiry when the provider documents one. Reject an already-expired newly acquired token without an internal fetch loop.
+- `forget()` clears this object's entry and its shared cache entry. It is not provider revocation and does not erase entries retained by other live authenticator instances.
+
+### Coordination
+
+Add one internal `Http/Auth/TokenAcquisition.php` service, used by both cached acquisition and account renewal, reusing `Locker` for owner/waiter coordination. Keep **active acquisitions only** in an instance property, keyed by operation kind, full identity and store. A `Data/TokenAcquisitionResult.php` holder carries the completed token or provider failure for existing waiters. Remove the service entry in `finally`, including owner cancellation; waiters retain their captured holder until they resume. This avoids serial retry chains after a shared failure. No completed-token registry or exception history remains in worker memory. The service is safe to auto-singleton; container teardown resets it, so it needs no static `flushState()` hook.
+
+Keep cancellation local to the canceled coroutine; a canceled waiter must not release another caller's lock. An owner cancellation cleans up and wakes waiters without sharing its `CanceledException` as their cancellation. With no completed result, waiters use Locker's next-owner rule: one becomes the new owner, rereads the cache/account and starts a fresh attempt; others wait. Durable claim cleanup/recovery still applies. No detached work is spawned. A genuinely later call may also try again. Separate workers may acquire independent client-credentials tokens; do not add a distributed acquisition lock for grants where this is harmless.
+
+Use the existing cache serialization allowlist for built-in token/entry classes. Custom authenticators use its normal application registration mechanism. Capture the selected token locally while applying it; resource headers and merchant context stay on the connector/request, never in shared token state.
+
+## 3. Durable accounts and public API
+
+Add these files relative to `src/saloon/src`:
+
+- `OAuthAccount.php` and `OAuthAccounts.php` for the model and account service, following Sanctum's root model placement.
+- `Traits/HasOAuthAccounts.php` for the owner relation.
+- `Http/Auth/CachedTokenAuthenticator.php` and `Http/Auth/OAuthAccountAuthenticator.php` beside existing authenticators, plus the shared acquisition files specified above.
+- `Console/Commands/OAuthAccountsTableCommand.php` and `Console/Commands/stubs/oauth-accounts.stub`, following Saloon's existing command directory and `MigrationGeneratorCommand`'s stub loading.
+
+`OAuthAccounts` owns model selection, partition configuration and account operations; it is a worker-safe service with no current-account or current-partition field. Use dependency injection and existing auto-singleton semantics, not a new facade or redundant bindings.
+
+```php
+use Hypervel\Saloon\OAuthAccounts;
+
+// Application provider; optional model customization.
+OAuthAccounts::useAccountModel(App\Models\OAuthAccount::class);
+
+$account = $user->oauthAccounts()->create([
+    'provider' => 'gitlab',
+    'provider_account_id' => $providerUserId,
+    'access_token' => $token->getAccessToken(),
+    'refresh_token' => $token->getRefreshToken(),
+    'expires_at' => $token->getExpiresAt(),
+    'scopes' => $token->getScopes(),
+]);
+
+$authenticator = $oauth->accountAuthenticator($account);
+
+// Other OAuth clients can supply the same token contract.
+$authenticator = $account->authenticator(
+    refreshUsing: fn ($current) => $provider->refresh($current),
+);
+```
+
+`AuthorizationCodeGrant::accountAuthenticator()` adapts its existing `refreshAccessToken()` method; retain a per-call request modifier. The generic callback receives `OAuthAuthenticator` and returns `OAuthAuthenticator`. The account authenticator captures model class, resolved connection/table, primary key and persisted partition, not a mutable account model or a permanent token copy.
+
+`OAuthAccount::newOAuthAuthenticator()` constructs the current token from persisted fields and is the model extension point for custom authentication behavior; `authenticator()` constructs the renewing account authenticator. The default token represents OAuth bearer credentials. Persist defined credential fields, not arbitrary serialized provider objects. Provide `clearCredentialCache()` for application-controlled bulk/quiet mutations, following the existing token-model cache conventions. Credential writes through these escape hatches must also replace the revision, calculate the renewal time and clear obsolete claims; cache invalidation alone does not fence an in-flight renewal.
+
+### Migration and casts
+
+Add `make:oauth-accounts-table`, alias `oauth-accounts:table`, using `MigrationGeneratorCommand`. Generate `oauth_accounts`; do not load or run a migration automatically. Applications may adjust the published migration and model table/connection.
+
+| Column | Contract |
+|---|---|
+| `id` | UUID primary key; framework UUID model concern |
+| `owner_type`, `owner_id` | Morph owner, using framework morph-key conventions |
+| `provider`, nullable `provider_account_id` | Provider reference and optional external account identifier |
+| `access_token`, nullable `refresh_token` | Text columns, encrypted casts and hidden serialization |
+| nullable `expires_at` | UTC `dateTime`, immutable cast |
+| nullable `refresh_at` | UTC `dateTime`, immutable cast; fixed early-renewal time calculated when credentials are installed |
+| nullable `scopes` | `text()`, array cast; opaque list read back whole, preserving omission versus empty set |
+| `credential_revision` | Fresh UUID whenever credentials change |
+| nullable `refresh_claim`, `refresh_started_at` | UUID ownership of one renewal attempt and UTC `timestamp()` recording its start |
+| timestamps | Ordinary created/updated timestamps |
+
+Index owner lookup and provider/external-account lookup. Do not impose uniqueness on owner + provider + external account: distinct client registrations or permission grants may legitimately share those values. Reconnect replaces a selected account row's credentials; it is not inferred from that tuple.
+
+Keep client secrets in application configuration. Encrypt stored access/refresh tokens, including cached model attributes; never hash tokens that must later be sent to a provider. Use existing encryption casts and key management. These protections complement normal cache/database access controls; cached standalone token values still contain usable credentials.
+
+### Ordinary mutations and cache configuration
+
+Use model events for normal saves/deletes and committed invalidation. The credential `saving` hook assigns a fresh UUID revision and clears an obsolete claim when credential attributes change. On creation or a changed access token/expiry, that same hook computes `refresh_at` from save time using the capped allowance in §4, or sets it to null when expiry is absent. Thus relation `create()` and ordinary reconnect `save()` need no manually supplied deadline. Unrelated metadata saves must neither move the deadline nor clear a live claim.
+
+All account reads, claims, conditional writes and cleanup start from the account model's `newQuery()`, preserving global scopes and custom Eloquent builders. Do not use base/raw queries to bypass them. Conditional builder updates need explicitly cast/encrypted attributes, revision/deadline calculation and invalidation because they do not run model events. Raw, quiet and bulk application mutations retain normal Eloquent responsibilities: callers invalidate affected account keys; do not build a second Eloquent mutation system.
+
+Add `saloon.oauth_accounts.cache` with `enabled` (false), `store` (null = framework default), `ttl` (300 seconds), and `prefix` (`saloon:oauth-accounts:`). Add `saloon.oauth_accounts.lock_store` (null = selected account-cache store). Validate selected stores lazily when durable accounts are used; unused installations need no account table or lock connection.
+
+- Cache enabled: use `ModelCacheCoordinator` and `ModelCacheStoreValidator`; cache a relations-unset model, using normal encrypted casts and model serialization. Register the configured model with the cache serialization policy.
+- Warm cache hits require no database query and no per-request write. No `last_used_at` update or worker-lifetime private token slot for durable accounts.
+- Cache disabled: read the authoritative row; renewal still uses the shared lock store.
+- Key identity encodes model class, captured resolved connection **name**, table name, account ID and partition, hashed with SHA-256. Capture the selected connection name even when the model normally follows the default. Do not inspect physical database configuration; connection names separate ordinary multiple-connection/table uses, while the partition separates scoped databases behind one connection. Reuse the identity for reads, writes, invalidation and locks; cache-fill and renewal locks are distinct.
+- Stores must span the deployment using those accounts. Redis/database suit multiple hosts; file/Swoole scope must match the deployment. Reject worker-local/stack/failover stores for durable credential caching; never hide a cache outage by serving stale credentials.
+- Use writer reads for renewal and recovery. Never publish uncommitted credentials. Cache writes and invalidations follow `afterCommitOrNow`; normal application transactions bypass shared fills through the existing coordinator.
+
+## 4. Renewal and recovery
+
+Renewal uses a short cache lock for waiting and a committed row claim for coordination that survives a cache restart. Neither provides exactly-once provider execution. The recovery policy intentionally permits another attempt after transient failures or an abandoned claim; delayed provider requests can still overlap and trigger reuse detection.
+
+### When to renew
+
+When installing credentials, compute `refresh_at` once using the same expiry calculation as cached acquisition: `expires_at - min(30 seconds, remaining lifetime / 2)`. Recompute on successful renewal or a replacement access token/expiry, never on cache reads or unrelated metadata saves. Persisting this deadline avoids both resetting it on reads and immediately re-renewing short-lived tokens.
+
+- Before `refresh_at`, apply usable credentials without renewal. A current claim still takes precedence over the old token.
+- At/after `refresh_at`, renew if a refresh token exists. Without one, use the access token until its actual expiry, then fail explicitly as needing reconnection before taking a claim.
+- No expiry means no automatic renewal and a null renewal time.
+
+### One attempt
+
+1. Resolve/check the current partition, then enter worker-local acquisition coordination. Existing same-worker waiters share the entire bounded attempt chain and its final result/error.
+2. Acquire the account's cache lock, then reread the writer. If another attempt installed usable credentials, use them. Missing/deleted accounts fail; never recreate them. A present claim blocks use of the old token because some providers invalidate it immediately on refresh.
+3. Reject renewal while the account connection has an applicable caller transaction. This avoids remote rotation followed by rollback, uncommitted account reads, and caller/child row-lock deadlocks. Do not escape the caller into a detached coroutine.
+4. Validate locally before claiming. Atomically set a fresh `refresh_claim` UUID and `refresh_started_at`, conditioned on account, partition, credential revision and a null or abandoned claim. A claim is abandoned after 300 seconds. This is a recovery interval, not proof that the old provider operation has ended.
+5. Commit the claim and invalidate its cache before provider I/O. Proceed only when one row changed; an uncertain claim write does not authorize a provider request. Release idle database connections.
+6. Invoke one provider refresh attempt. The Saloon convenience applies the caller's modifier, then disables transport retries for this request. Custom callbacks must also perform one provider attempt.
+7. On success, reject an already-expired result, prepare encrypted credentials through the model's casts, retain omitted refresh token/scopes, calculate `refresh_at`, and conditionally store credentials + a fresh revision + cleared claim. Match account, partition, read credential revision **and claim UUID**. Commit and invalidate before exposing the result through the model's token factory. On a lost comparison, reread the account; never return the losing result or overwrite a reconnect. Do not repeat provider refresh merely because persistence or cache invalidation failed.
+8. On failure/cancellation, conditionally clear only this attempt's claim and invalidate. Do not clear a successor's claim. A process crash or failed cleanup leaves a reclaimable claim. Propagate cancellation unchanged; never start its next retry. Preserve the primary failure if cleanup also fails, reporting the cleanup failure without credentials.
+9. Release the cache lock in `finally`. No transaction or pooled connection is held while waiting or during HTTP.
+
+Use a 120-second cache-lock lease and a 120-second acquisition wait. Default single-attempt HTTP timeouts are currently 10 seconds connecting and 30 seconds total; these leave headroom for ordinary processing but do not enforce a whole-operation deadline. Custom timeouts/callbacks must respect the documented budget. The durable claim still blocks a second attempt if the cache lease expires before the abandonment interval. A late owner loses local write authority after its claim is replaced. Do not wait for the full abandonment interval on a request that finds a still-owned row after the cache lease expired; fail explicitly and let a later operation recover.
+
+### Retry ownership
+
+- Built in, fixed small budget: three provider attempts total; exponential full-jitter delays capped at 250 ms then 500 ms. No policy selector or collection of retry configuration keys.
+- Release the distributed lock and row claim before sleeping; retain worker-local result sharing for callers already waiting on this operation. Reacquire and reread before every attempt. Another operation may have succeeded during the delay.
+- Retry provider connection failures, HTTP 408/429/500/502/503/504 and OAuth `server_error`/`temporarily_unavailable`. Read structured OAuth error codes from the actual response, never substring-match exception messages. `invalid_grant`, `invalid_client`, invalid scope and malformed configuration take precedence over a generic server status and are not retried. Restrict this classification to the provider invocation, not local database/cache failures.
+- Respect `Retry-After`; if it requires a delay outside the small retry budget, surface the provider response for the caller to schedule later rather than retry early. Reuse existing parsing logic at its owning boundary if needed, without building a general retry subsystem.
+- Handle Saloon/HTTP client exceptions and the corresponding Guzzle exceptions from Socialite callbacks. Unknown callback exceptions are not assumed transient. Do not wrap provider errors in a new parallel exception hierarchy.
+- On `invalid_grant`, reread first. If the credentials changed, use/reassess the replacement instead of rejecting it. Otherwise clear only this claim and surface the original rejection without another attempt. The application handles reconnecting/disabling use of the account; do not silently delete credentials or introduce a persisted account-status system.
+- `invalid_client` requires correcting client configuration, not reconnecting every account. Preserve stored grants and surface it without automatic retries. Transient exhaustion likewise retains credentials for a later operation.
+- Same-worker waiters share errors through the active holder, rather than each starting its own chain. Across workers, authoritative claims serialize provider attempts; do not serialize exception objects into the cache or promise distributed error broadcasting.
+
+Tests must exercise late completion after claim replacement and cancellation, not just a mocked lock call. Keep clocks, delays and operation budgets explicit; do not add a timer heartbeat, detached completion, durable retry queue or periodic cleanup job.
+
+## 5. Partitioning and state lifetime
+
+Expose boot-only `OAuthAccounts::resolvePartitionUsing(string $column, Closure $resolver)`, beside `useAccountModel()` and its `accountModel()` getter. Follow Permission's SQL-column validation and registration-before-use guard. Seal configuration on first account operation, not a harmless model-class getter, so application boot can override a default model before use. A configured resolver returns the current nonempty string or integer partition; missing context fails explicitly. An unconfigured ordinary application has no partition column requirement.
+
+- Creating an account fills the partition column from the resolver and rejects a conflicting supplied value.
+- Capture the **persisted** partition when constructing its authenticator. Validate it against the current resolver on every apply, including cache hits, and after yielding before using credentials or publishing changes.
+- Saloon's account reads, claims, conditional writes and invalidations always include that partition. A UUID alone is not authorization.
+- Do not add an application-wide Eloquent global scope in Saloon. Applications/integrations own query policy and schema columns. A model scope alone cannot protect warmed cache entries or retained authenticators.
+- Platform-owned accounts use an explicit platform partition. There is no special global-credential bypass flag.
+- Reacquirable-token keys follow credential/grant identity, not the current partition automatically. Identical platform credentials may share their token; distinct grants supply distinct identity. Resource/merchant headers remain request-owned.
+- Boot callbacks capture only worker-safe services and resolve current context when called. Never change global config per request or retain a tenant/account object in a singleton. Mark configuration mutators boot-only and register static cleanup in the existing testing subscriber.
+
+## 6. Documentation and integration
+
+Update `src/docs/saloon.md` in its existing Laravel-docs style:
+
+- Replace the boot-fetch example with cached authentication; explain worker-array versus shared storage, identity, expiry, invalidation and custom token classes.
+- Show account migration, owner relation, custom model, OAuth callback persistence, reconnect/delete, encryption and optional cache setup. Do not imply installing Saloon creates a table.
+- Show a Socialite callback mapping `token`, `refreshToken`, `expiresIn` to an absolute immutable expiry, and `approvedScopes ?: null`. Initial Socialite user data already exposes the raw response when exact scope presence matters. Custom provider adapters can explicitly supply an empty scopes list.
+- Explain transaction rejection, transient recovery, `invalid_grant` versus client configuration failures, custom callback single-attempt bounds, cancellation and the remaining provider-side overlap risk.
+- Document generic partition registration and request-owned credentials/headers. No private integration names or dependencies.
+- Explain that default response-cache entries stop matching after bearer renewal. Apps choosing stable custom keys/scopes must retain account/permission isolation; no automatic cache-key rewrite.
+- Keep the package README's lasting API differences accurate, including the approved scope contract/factory additions. Purely additive helpers belong in the guide. Update porting guidance only for an actual affected upstream contract.
+
+## 7. Implementation and verification
+
+Implement metadata and cached acquisition, then account persistence/cache/partitioning, then renewal/recovery and documentation as coherent slices. One final code-review boundary covers the complete feature. No source implementation is authorized by this planning task itself.
+
+Before adding tests, inspect existing coverage and extend it where practical. The focused matrix is:
+
+| Area | Meaningful coverage |
+|---|---|
+| Token metadata | Omitted/empty/nonempty scopes, both grant factories and custom override signatures; existing refresh-token fallback |
+| Acquisition | Memory/shared reuse; fixed short/no-expiry lifetime; identities across credentials/environments/custom audience; separate instances coalesce; owner failure reaches waiters; canceled waiter leaves owner intact; explicit forget and normal request retry |
+| Persistence | Generated migration and morph-key conventions; encrypted DB/cache representation; hidden secrets; custom model/connection; save/delete/reconnect invalidation and rollback |
+| Database load | Warm shared-cache authentication performs no SQL; cache disabled works; no repeated account writes on ordinary API calls |
+| Renewal | Fixed early deadline including short/no-expiry tokens; non-refreshable token remains usable until actual expiry; two competing callers invoke once; success saved before use; rejected/expired returned token; omitted metadata retained; failed save surfaces; cache lease expiry alone does not bypass a fresh claim |
+| Recovery | Transient backoff/jitter is bounded; no nested HTTP retries; fresh writer read before retry; rejected grant versus invalid client; abandoned claim takeover; old success/cleanup cannot overwrite new claim/reconnect/delete |
+| Transactions/cancellation | Caller transaction rejected before provider call; cancellation propagates and releases owned coordination; cleanup failure does not hide cancellation; no detached child or held DB connection |
+| Partitioning | Cold/warm cross-partition denial, captured authenticator after context switch, concurrent partitions, missing context, create mismatch, post-yield checks |
+| HTTP integration | New pending request receives renewed auth; provider response/errors remain available. Run existing response-cache and OAuth suites for unchanged behavior, without duplicating their tests. |
+
+Use real supported shared-store/database integration for competing claims and invalidation; mock-only tests cannot prove cross-worker behavior. Use testbench SQLite for portable model behavior, with focused Redis and database integration where the shared-state claim needs it. Reuse existing service traits and CI discovery conventions; avoid a full driver/HTTP/provider cross-product. Never contact real provider accounts in tests.
+
+Run each changed test file immediately during implementation. At completion run `composer lint:fix`, `composer analyse`, then affected Saloon tests and touched integration suites sequentially, from the worktree root, with execution timeouts. Use the full suite only for framework-wide changes. Self-review callers/callees, retry multiplication, cache keys, context changes, secret exposure and API signatures before requesting review. Do not add benchmark claims; obtain owner idle-machine confirmation before benchmarking.

From a3dcea2319e90bafc31e86ce8679824c447277f9 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 19:19:20 +0000
Subject: [PATCH 2/8] Pin PHPStan to 2.3.1 while loop narrowing is corrected

PHPStan 2.3.2 rejects a correctly narrowed generic value in the existing Data collection cast. The unchanged cast and an isolated reproducer pass on 2.3.1 and fail on 2.3.2.

Pin the development requirement so fresh installs and CI use the verified analyzer. Keep the Data implementation and its type contracts intact, and track removal of the pin once a fixed release passes the source and type-fixture analyses.

Validation: the full source analysis and type fixtures pass with PHPStan 2.3.1.
---
 composer.json | 2 +-
 docs/todo.md  | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/composer.json b/composer.json
index f63ca001a..f728758c4 100644
--- a/composer.json
+++ b/composer.json
@@ -131,7 +131,7 @@
         "mockery/mockery": "^1.6.15",
         "opis/json-schema": "^2.6.0",
         "pda/pheanstalk": "^8.0.2",
-        "phpstan/phpstan": "^2.3",
+        "phpstan/phpstan": "2.3.1",
         "phpunit/phpunit": "~13.4.3",
         "pusher/pusher-php-server": "^7.2",
         "resend/resend-php": "^1.0",
diff --git a/docs/todo.md b/docs/todo.md
index 2a734bac7..fbc187221 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -34,6 +34,7 @@
 
 ## Testing
 
+- Remove the root PHPStan `2.3.1` pin once a release fixes the 2.3.2 loop-narrowing regression: `DataCollectionEloquentCast::set()` rejects a value narrowed by `instanceof` against `class-string<TData>`. Verify the full source and type-fixture analyses before restoring the version range.
 - Adopt a Swoole release fixing the intermittent AIO shutdown hang in [swoole-src#6297](https://github.com/swoole/swoole-src/issues/6297). On 6.3.0RC1, ordinary coroutine scheduler teardown can wait forever for an idle native thread that missed its shutdown notification, including between tests. Verify the released fix with the standalone reproduction and affected suites; do not add a Hypervel workaround or a timing-dependent regression test.
 - Add the required title docblocks to the untitled non-test methods in `tests/`: about 7,600 methods in 1,500 files, mostly helpers, fixtures, and methods of anonymous classes in older tests. `AGENTS.md` requires a title on every method except test methods, but most existing tests omit them, and agents follow the surrounding code over the written rule, so new tests keep reproducing the gap until review catches it. Make the change as one approved sweep (short imperative titles only), then add an automated check, such as a PHPStan rule, so the code and the rule cannot drift apart again. Decide whether the check also covers `src/`.
 - Add native return types to the `test*` methods that lack them: about 5,600 methods in 490 files. `AGENTS.md` requires `: void` on test methods; a test that returns a value for `#[Depends]` takes its actual return type instead. As with method titles, untyped methods in existing files lead new tests to copy them, so make the change as one approved sweep and enforce it with the same automated check.

From 71caf01ebcc2c9c4fa0f63d74e73799959e0fb46 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 19:19:27 +0000
Subject: [PATCH 3/8] Share Saloon Retry-After parsing across rate limits and
 OAuth

Move the existing Retry-After parser into the HTTP namespace so account renewal can honor provider delays without duplicating the rate-limit implementation.

Preserve numeric delays, strict HTTP-date parsing, obsolete date formats and leap-second handling. Keep the rate limiter limit and its missing-or-invalid default in the rate-limit caller; the shared parser returns the provider delay without applying that policy.

Validation: formatting, full static analysis and the Saloon suite, including the existing rate-limit cases, pass.
---
 src/saloon/src/Http/RetryAfter.php            | 121 +++++++++++++++++
 .../src/RateLimit/Traits/HasRateLimits.php    | 125 +-----------------
 2 files changed, 124 insertions(+), 122 deletions(-)
 create mode 100644 src/saloon/src/Http/RetryAfter.php

diff --git a/src/saloon/src/Http/RetryAfter.php b/src/saloon/src/Http/RetryAfter.php
new file mode 100644
index 000000000..9259a60d1
--- /dev/null
+++ b/src/saloon/src/Http/RetryAfter.php
@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Http;
+
+use Carbon\Exceptions\InvalidFormatException;
+use Hypervel\Support\CarbonImmutable;
+
+class RetryAfter
+{
+    /**
+     * Parse a Retry-After value into seconds.
+     *
+     * Return null when the value is missing or malformed.
+     */
+    public static function seconds(string $retryAfter): ?int
+    {
+        $retryAfter = trim($retryAfter);
+        if ($retryAfter === '') {
+            return null;
+        }
+
+        if (ctype_digit($retryAfter)) {
+            return (int) $retryAfter;
+        }
+
+        $now = CarbonImmutable::now('GMT');
+        $format = null;
+        $rfc850Year = null;
+        $timestamp = null;
+
+        if (preg_match(
+            '/\A(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?<timestamp>\d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT)\z/',
+            $retryAfter,
+            $matches,
+        ) === 1) {
+            $format = 'd M Y H:i:s \G\M\T';
+            $timestamp = $matches['timestamp'];
+        } elseif (preg_match(
+            '/\A(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (?<day>\d{2})-(?<month>[A-Z][a-z]{2})-(?<year>\d{2}) (?<time>\d{2}:\d{2}:\d{2}) GMT\z/',
+            $retryAfter,
+            $matches,
+        ) === 1) {
+            $year = intdiv($now->year, 100) * 100 + (int) $matches['year'];
+            $format = 'd-M-Y H:i:s \G\M\T';
+            $rfc850Year = $year;
+            $timestamp = sprintf(
+                '%s-%s-%04d %s GMT',
+                $matches['day'],
+                $matches['month'],
+                $year,
+                $matches['time'],
+            );
+        } elseif (preg_match(
+            '/\A(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?<timestamp>[A-Z][a-z]{2} (?:\d{2}| \d) \d{2}:\d{2}:\d{2} \d{4})\z/',
+            $retryAfter,
+            $matches,
+        ) === 1) {
+            $format = 'M j H:i:s Y';
+            $timestamp = $matches['timestamp'];
+        }
+
+        if ($format === null || $timestamp === null) {
+            return null;
+        }
+
+        $availableAt = self::parseHttpDate($format, $timestamp);
+
+        if ($availableAt === null) {
+            return null;
+        }
+
+        if ($rfc850Year !== null && $availableAt->greaterThan($now->addYears(50))) {
+            $timestamp = sprintf(
+                '%s-%s-%04d %s GMT',
+                $matches['day'],
+                $matches['month'],
+                $rfc850Year - 100,
+                $matches['time'],
+            );
+            $availableAt = self::parseHttpDate($format, $timestamp);
+        }
+
+        if ($availableAt === null) {
+            return null;
+        }
+
+        return $availableAt->getTimestamp() - $now->getTimestamp();
+    }
+
+    /**
+     * Parse a validated HTTP-date shape without accepting normalized fields.
+     */
+    private static function parseHttpDate(string $format, string $timestamp): ?CarbonImmutable
+    {
+        $timestamp = preg_replace(
+            '/(\d{2}:\d{2}):60(?=\D|$)/',
+            '$1:59',
+            $timestamp,
+            1,
+            $leapSecond,
+        );
+
+        try {
+            $availableAt = CarbonImmutable::createFromFormat($format, $timestamp, 'GMT');
+        } catch (InvalidFormatException) {
+            return null;
+        }
+
+        // Carbon stores errors from only its latest parse, so keep this read
+        // adjacent to createFromFormat() before any other Carbon call.
+        $errors = CarbonImmutable::getLastErrors();
+
+        if ($errors !== false && ($errors['warning_count'] > 0 || $errors['error_count'] > 0)) {
+            return null;
+        }
+
+        return $availableAt->addSeconds($leapSecond);
+    }
+}
diff --git a/src/saloon/src/RateLimit/Traits/HasRateLimits.php b/src/saloon/src/RateLimit/Traits/HasRateLimits.php
index f2c5d3268..a3a3a8b30 100644
--- a/src/saloon/src/RateLimit/Traits/HasRateLimits.php
+++ b/src/saloon/src/RateLimit/Traits/HasRateLimits.php
@@ -4,13 +4,12 @@
 
 namespace Hypervel\Saloon\RateLimit\Traits;
 
-use Carbon\Exceptions\InvalidFormatException;
 use Hypervel\RateLimiter\AdmissionPolicy;
 use Hypervel\RateLimiter\Contracts\Decision;
 use Hypervel\RateLimiter\Cooldown;
 use Hypervel\Saloon\Http\PendingRequest;
 use Hypervel\Saloon\Http\Response;
-use Hypervel\Support\CarbonImmutable;
+use Hypervel\Saloon\Http\RetryAfter;
 use UnitEnum;
 
 trait HasRateLimits
@@ -150,127 +149,9 @@ protected function resolveRateLimitCooldown(Response $response): ?int
 
         // A 429 without a usable delay still blocks for upstream's 60-second default. A valid delay that has
         // already passed blocks nothing.
-        $seconds = $this->parseRateLimitRetryAfter(trim($response->header('Retry-After'))) ?? 60;
+        $seconds = RetryAfter::seconds($response->header('Retry-After'));
+        $seconds = $seconds === null || $seconds > intdiv(AdmissionPolicy::MAX_INTEGER, 1_000_000) ? 60 : $seconds;
 
         return $seconds > 0 ? $seconds : null;
     }
-
-    /**
-     * Parse a Retry-After value into seconds.
-     *
-     * Return null when the value is missing, malformed or too long for the rate limiter.
-     */
-    private function parseRateLimitRetryAfter(string $retryAfter): ?int
-    {
-        if ($retryAfter === '') {
-            return null;
-        }
-
-        if (ctype_digit($retryAfter)) {
-            return $this->checkedRateLimitCooldownSeconds((int) $retryAfter);
-        }
-
-        $now = CarbonImmutable::now('GMT');
-        $format = null;
-        $rfc850Year = null;
-        $timestamp = null;
-
-        if (preg_match(
-            '/\A(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?<timestamp>\d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT)\z/',
-            $retryAfter,
-            $matches,
-        ) === 1) {
-            $format = 'd M Y H:i:s \G\M\T';
-            $timestamp = $matches['timestamp'];
-        } elseif (preg_match(
-            '/\A(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (?<day>\d{2})-(?<month>[A-Z][a-z]{2})-(?<year>\d{2}) (?<time>\d{2}:\d{2}:\d{2}) GMT\z/',
-            $retryAfter,
-            $matches,
-        ) === 1) {
-            $year = intdiv($now->year, 100) * 100 + (int) $matches['year'];
-            $format = 'd-M-Y H:i:s \G\M\T';
-            $rfc850Year = $year;
-            $timestamp = sprintf(
-                '%s-%s-%04d %s GMT',
-                $matches['day'],
-                $matches['month'],
-                $year,
-                $matches['time'],
-            );
-        } elseif (preg_match(
-            '/\A(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?<timestamp>[A-Z][a-z]{2} (?:\d{2}| \d) \d{2}:\d{2}:\d{2} \d{4})\z/',
-            $retryAfter,
-            $matches,
-        ) === 1) {
-            $format = 'M j H:i:s Y';
-            $timestamp = $matches['timestamp'];
-        }
-
-        if ($format === null || $timestamp === null) {
-            return null;
-        }
-
-        $availableAt = $this->parseRateLimitRetryAfterHttpDate($format, $timestamp);
-
-        if ($availableAt === null) {
-            return null;
-        }
-
-        if ($rfc850Year !== null && $availableAt->greaterThan($now->addYears(50))) {
-            $timestamp = sprintf(
-                '%s-%s-%04d %s GMT',
-                $matches['day'],
-                $matches['month'],
-                $rfc850Year - 100,
-                $matches['time'],
-            );
-            $availableAt = $this->parseRateLimitRetryAfterHttpDate($format, $timestamp);
-        }
-
-        if ($availableAt === null) {
-            return null;
-        }
-
-        $seconds = $availableAt->getTimestamp() - $now->getTimestamp();
-
-        return $this->checkedRateLimitCooldownSeconds($seconds);
-    }
-
-    /**
-     * Parse a validated HTTP-date shape without accepting normalized fields.
-     */
-    private function parseRateLimitRetryAfterHttpDate(string $format, string $timestamp): ?CarbonImmutable
-    {
-        $timestamp = preg_replace(
-            '/(\d{2}:\d{2}):60(?=\D|$)/',
-            '$1:59',
-            $timestamp,
-            1,
-            $leapSecond,
-        );
-
-        try {
-            $availableAt = CarbonImmutable::createFromFormat($format, $timestamp, 'GMT');
-        } catch (InvalidFormatException) {
-            return null;
-        }
-
-        // Carbon stores errors from only its latest parse, so keep this read
-        // adjacent to createFromFormat() before any other Carbon call.
-        $errors = CarbonImmutable::getLastErrors();
-
-        if ($errors !== false && ($errors['warning_count'] > 0 || $errors['error_count'] > 0)) {
-            return null;
-        }
-
-        return $availableAt->addSeconds($leapSecond);
-    }
-
-    /**
-     * Return a delay the rate limiter can represent, or null when it is too long.
-     */
-    private function checkedRateLimitCooldownSeconds(int $seconds): ?int
-    {
-        return $seconds <= intdiv(AdmissionPolicy::MAX_INTEGER, 1_000_000) ? $seconds : null;
-    }
 }

From d695849002a7c41eda69c943d4b9e210943d62a0 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 19:19:50 +0000
Subject: [PATCH 4/8] Add cached access tokens and durable OAuth account
 renewal

Provide cached authentication for independently reacquirable grants and
durable account authentication for rotating user grants. Keep provider
credentials, request context and OAuth client selection application-owned.

CachedTokenAuthenticator retains the actual authenticator and a fixed early
renewal deadline. ClientCredentialsGrant builds a hashed identity from the
connector, resolved endpoint, credentials, scopes and caller contribution.
Concurrent callers share active acquisitions and failures within a worker;
completed tokens use the selected cache without a worker-wide token registry.

Add an opt-in OAuth accounts migration, encrypted model, owner relation and
authenticator. Shared credential caching uses committed invalidation and
preserves custom models, query builders and connection identities. A boot-time
partition resolver isolates storage and cache identity without retaining the
current account or partition in worker state. Deferred invalidation uses the
captured key even when application context is restored before commit.

Coordinate renewal with existing locks and conditional database claims.
Revision and claim checks prevent late responses from overwriting reconnects
or successor attempts. Store replacements before use, preserve omitted scopes
and refresh tokens, and surface an explicit reconnect-required exception for
expired credentials that cannot renew. Retry only classified provider failures
within a small bounded budget; local persistence failures never repeat the
provider request. Release idle database connections before provider calls and
waits, reject renewal inside caller transactions, and preserve cancellation
when cleanup or reporting also fails.

Extend OAuth metadata and grant factories with nullable reported scopes. Fix
request modifiers to accept all declared callable forms. Register cache
serialization classes, migration command discovery and testing-state cleanup.

Cover serialized token reuse, grant identity, concurrent acquisition and
partition isolation, committed cache invalidation, encryption, bounded retries,
cancellation, database-pool release and late-result ownership. Exercise lost
Redis leases and abandoned database claims with real stores, and include these
tests in the existing Redis, Redis Cluster and Valkey jobs.

Validation: formatting, full PHPStan source and type-fixture analysis, the
complete Saloon suite and the real Redis integration tests pass.
---
 .github/workflows/redis.yml                   |   3 +
 src/saloon/config/saloon.php                  |  22 +
 .../Commands/OAuthAccountsTableCommand.php    |  45 +
 .../Commands/stubs/oauth-accounts.stub        |  41 +
 .../src/Contracts/OAuthAuthenticator.php      |   7 +
 src/saloon/src/Data/CachedToken.php           |  36 +
 src/saloon/src/Data/OAuthAccountIdentity.php  |  53 ++
 .../src/Data/TokenAcquisitionResult.php       |  20 +
 ...OAuthAccountReconnectRequiredException.php |  18 +
 .../Http/Auth/AccessTokenAuthenticator.php    |  13 +
 .../Http/Auth/CachedTokenAuthenticator.php    |  97 ++
 .../Http/Auth/OAuthAccountAuthenticator.php   |  41 +
 src/saloon/src/Http/Auth/TokenAcquisition.php |  65 ++
 src/saloon/src/Http/Auth/TokenExpiry.php      |  26 +
 src/saloon/src/OAuthAccount.php               | 119 +++
 src/saloon/src/OAuthAccounts.php              | 577 +++++++++++
 src/saloon/src/SaloonServiceProvider.php      |  18 +-
 src/saloon/src/Traits/HasOAuthAccounts.php    |  26 +
 .../Traits/OAuth2/AuthorizationCodeGrant.php  |  39 +-
 .../Traits/OAuth2/ClientCredentialsGrant.php  |  44 +-
 .../OAuth2/ParsesOAuthTokenResponses.php      |  20 +
 .../src/PHPUnit/AfterEachTestSubscriber.php   |   1 +
 .../Saloon/Redis/OAuthAccountRenewalTest.php  | 163 ++++
 .../Oauth2/AuthCodeFlowConnectorTest.php      |  16 +
 .../ClientCredentialsFlowConnectorTest.php    |  44 +-
 .../CustomOAuthAuthenticator.php              |   1 +
 .../CustomResponseOAuth2Connector.php         |   4 +-
 tests/Saloon/OAuthAccountTest.php             | 899 ++++++++++++++++++
 tests/Saloon/SaloonServiceProviderTest.php    |   3 +
 tests/Saloon/SensitiveParameterTest.php       |   2 +
 .../Oauth2/CachedTokenAuthenticatorTest.php   | 260 +++++
 .../Unit/Oauth2/TokenAcquisitionTest.php      |  90 ++
 32 files changed, 2796 insertions(+), 17 deletions(-)
 create mode 100644 src/saloon/src/Console/Commands/OAuthAccountsTableCommand.php
 create mode 100644 src/saloon/src/Console/Commands/stubs/oauth-accounts.stub
 create mode 100644 src/saloon/src/Data/CachedToken.php
 create mode 100644 src/saloon/src/Data/OAuthAccountIdentity.php
 create mode 100644 src/saloon/src/Data/TokenAcquisitionResult.php
 create mode 100644 src/saloon/src/Exceptions/OAuthAccountReconnectRequiredException.php
 create mode 100644 src/saloon/src/Http/Auth/CachedTokenAuthenticator.php
 create mode 100644 src/saloon/src/Http/Auth/OAuthAccountAuthenticator.php
 create mode 100644 src/saloon/src/Http/Auth/TokenAcquisition.php
 create mode 100644 src/saloon/src/Http/Auth/TokenExpiry.php
 create mode 100644 src/saloon/src/OAuthAccount.php
 create mode 100644 src/saloon/src/OAuthAccounts.php
 create mode 100644 src/saloon/src/Traits/HasOAuthAccounts.php
 create mode 100644 tests/Integration/Saloon/Redis/OAuthAccountRenewalTest.php
 create mode 100644 tests/Saloon/OAuthAccountTest.php
 create mode 100644 tests/Saloon/Unit/Oauth2/CachedTokenAuthenticatorTest.php
 create mode 100644 tests/Saloon/Unit/Oauth2/TokenAcquisitionTest.php

diff --git a/.github/workflows/redis.yml b/.github/workflows/redis.yml
index 1d532ac77..78e64a745 100644
--- a/.github/workflows/redis.yml
+++ b/.github/workflows/redis.yml
@@ -66,6 +66,7 @@ jobs:
           QUEUE_CONNECTION=redis vendor/bin/paratest --max-processes=15 tests/Integration/Queue
           vendor/bin/paratest --max-processes=15 tests/Integration/RateLimiter/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Redis
+          vendor/bin/paratest --max-processes=15 tests/Integration/Saloon/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Session/Redis
 
   redis_cluster:
@@ -213,6 +214,7 @@ jobs:
           vendor/bin/phpunit --no-progress tests/Integration/Pennant/Redis
           QUEUE_CONNECTION=redis vendor/bin/phpunit --no-progress tests/Integration/Queue
           vendor/bin/phpunit --no-progress tests/Integration/RateLimiter/Redis
+          vendor/bin/phpunit --no-progress tests/Integration/Saloon/Redis
           vendor/bin/phpunit --no-progress tests/Integration/Session/Redis
           # This explicit list contains the topology-neutral Redis tests; the remaining files require standalone-only behavior.
           vendor/bin/phpunit --no-progress \
@@ -286,4 +288,5 @@ jobs:
           vendor/bin/paratest --max-processes=15 tests/Integration/RateLimiter/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Redis
           vendor/bin/phpunit --no-progress tests/Integration/Reverb/ClearStateCommandTest.php
+          vendor/bin/paratest --max-processes=15 tests/Integration/Saloon/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Session/Redis
diff --git a/src/saloon/config/saloon.php b/src/saloon/config/saloon.php
index 2cf479d5f..82ac7e9e4 100644
--- a/src/saloon/config/saloon.php
+++ b/src/saloon/config/saloon.php
@@ -43,6 +43,28 @@
         'store' => null,
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Connected OAuth Accounts
+    |--------------------------------------------------------------------------
+    |
+    | Credential caching avoids database reads for ordinary authenticated calls.
+    | Use a shared store that spans the workers using these accounts. A null
+    | lock store uses the account cache store, or the framework default.
+    | Omitted settings use the defaults below.
+    |
+    */
+
+    'oauth_accounts' => [
+        'cache' => [
+            'enabled' => false,
+            'store' => null,
+            'ttl' => 300,
+            'prefix' => 'saloon:oauth-accounts:',
+        ],
+        'lock_store' => null,
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Fixtures
diff --git a/src/saloon/src/Console/Commands/OAuthAccountsTableCommand.php b/src/saloon/src/Console/Commands/OAuthAccountsTableCommand.php
new file mode 100644
index 000000000..ed706e3f4
--- /dev/null
+++ b/src/saloon/src/Console/Commands/OAuthAccountsTableCommand.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Console\Commands;
+
+use Hypervel\Console\MigrationGeneratorCommand;
+use Symfony\Component\Console\Attribute\AsCommand;
+
+#[AsCommand(name: 'make:oauth-accounts-table', aliases: ['oauth-accounts:table'])]
+class OAuthAccountsTableCommand extends MigrationGeneratorCommand
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected ?string $signature = 'make:oauth-accounts-table';
+
+    /**
+     * The console command name aliases.
+     *
+     * @var string[]
+     */
+    protected array $aliases = ['oauth-accounts:table'];
+
+    /**
+     * The console command description.
+     */
+    protected string $description = 'Create a migration for the OAuth accounts table';
+
+    /**
+     * Get the migration table name.
+     */
+    protected function migrationTableName(): string
+    {
+        return 'oauth_accounts';
+    }
+
+    /**
+     * Get the path to the migration stub file.
+     */
+    protected function migrationStubFile(): string
+    {
+        return __DIR__ . '/stubs/oauth-accounts.stub';
+    }
+}
diff --git a/src/saloon/src/Console/Commands/stubs/oauth-accounts.stub b/src/saloon/src/Console/Commands/stubs/oauth-accounts.stub
new file mode 100644
index 000000000..8eba7729a
--- /dev/null
+++ b/src/saloon/src/Console/Commands/stubs/oauth-accounts.stub
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+use Hypervel\Database\Migrations\Migration;
+use Hypervel\Database\Schema\Blueprint;
+use Hypervel\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('{{table}}', function (Blueprint $table): void {
+            $table->uuid('id')->primary();
+            $table->morphs('owner');
+            $table->string('provider');
+            $table->string('provider_account_id')->nullable();
+            $table->text('access_token');
+            $table->text('refresh_token')->nullable();
+            $table->dateTime('expires_at')->nullable();
+            $table->dateTime('refresh_at')->nullable();
+            $table->text('scopes')->nullable();
+            $table->uuid('credential_revision');
+            $table->uuid('refresh_claim')->nullable();
+            $table->timestamp('refresh_started_at')->nullable();
+            $table->timestamps();
+            $table->index(['provider', 'provider_account_id']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('{{table}}');
+    }
+};
diff --git a/src/saloon/src/Contracts/OAuthAuthenticator.php b/src/saloon/src/Contracts/OAuthAuthenticator.php
index 7c732e53f..e8a7affc2 100644
--- a/src/saloon/src/Contracts/OAuthAuthenticator.php
+++ b/src/saloon/src/Contracts/OAuthAuthenticator.php
@@ -23,6 +23,13 @@ public function getRefreshToken(): ?string;
      */
     public function getExpiresAt(): ?DateTimeImmutable;
 
+    /**
+     * Get the reported scopes, or null when the provider did not report them.
+     *
+     * @return null|list<string>
+     */
+    public function getScopes(): ?array;
+
     /**
      * Determine if the authenticator has expired.
      */
diff --git a/src/saloon/src/Data/CachedToken.php b/src/saloon/src/Data/CachedToken.php
new file mode 100644
index 000000000..0b104b877
--- /dev/null
+++ b/src/saloon/src/Data/CachedToken.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Data;
+
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Http\Auth\TokenExpiry;
+use Hypervel\Support\Facades\Date;
+use SensitiveParameter;
+use UnexpectedValueException;
+
+final readonly class CachedToken
+{
+    public ?int $refreshAt;
+
+    /**
+     * Create a cache entry with a fixed renewal deadline.
+     */
+    public function __construct(#[SensitiveParameter] public OAuthAuthenticator $authenticator)
+    {
+        if ($authenticator->hasExpired()) {
+            throw new UnexpectedValueException('The acquired OAuth token has already expired.');
+        }
+
+        $this->refreshAt = TokenExpiry::refreshAt($authenticator->getExpiresAt());
+    }
+
+    /**
+     * Determine whether this entry can still be used.
+     */
+    public function isUsable(): bool
+    {
+        return $this->refreshAt === null || $this->refreshAt > Date::now()->getTimestamp();
+    }
+}
diff --git a/src/saloon/src/Data/OAuthAccountIdentity.php b/src/saloon/src/Data/OAuthAccountIdentity.php
new file mode 100644
index 000000000..415b50fd6
--- /dev/null
+++ b/src/saloon/src/Data/OAuthAccountIdentity.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Data;
+
+use Hypervel\Database\Eloquent\Builder;
+use Hypervel\Saloon\OAuthAccount;
+
+final readonly class OAuthAccountIdentity
+{
+    public string $key;
+
+    /**
+     * Capture the storage identity without retaining a mutable account.
+     *
+     * @param class-string<OAuthAccount> $model
+     */
+    public function __construct(
+        public string $model,
+        public string $connection,
+        public string $table,
+        public int|string $id,
+        public ?string $partitionColumn,
+        public ?string $partition,
+    ) {
+        $this->key = hash('sha256', serialize([$model, $connection, $table, (string) $id, $partitionColumn, $partition]));
+    }
+
+    /**
+     * Create a source model on the captured connection and table.
+     */
+    public function newModel(): OAuthAccount
+    {
+        return (new $this->model)->setConnection($this->connection)->setTable($this->table);
+    }
+
+    /**
+     * Start an account query with its model scopes and partition intact.
+     *
+     * @return Builder<OAuthAccount>
+     */
+    public function query(): Builder
+    {
+        $query = $this->newModel()->newQuery()->whereKey($this->id);
+
+        if ($this->partitionColumn !== null) {
+            $query->where($this->partitionColumn, $this->partition);
+        }
+
+        return $query;
+    }
+}
diff --git a/src/saloon/src/Data/TokenAcquisitionResult.php b/src/saloon/src/Data/TokenAcquisitionResult.php
new file mode 100644
index 000000000..f83e31de1
--- /dev/null
+++ b/src/saloon/src/Data/TokenAcquisitionResult.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Data;
+
+use Throwable;
+
+/**
+ * @template TResult
+ */
+class TokenAcquisitionResult
+{
+    public bool $completed = false;
+
+    /** @var null|TResult */
+    public mixed $value = null;
+
+    public ?Throwable $error = null;
+}
diff --git a/src/saloon/src/Exceptions/OAuthAccountReconnectRequiredException.php b/src/saloon/src/Exceptions/OAuthAccountReconnectRequiredException.php
new file mode 100644
index 000000000..35d5797fb
--- /dev/null
+++ b/src/saloon/src/Exceptions/OAuthAccountReconnectRequiredException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Exceptions;
+
+use Throwable;
+
+class OAuthAccountReconnectRequiredException extends SaloonException
+{
+    /**
+     * Create an exception for expired credentials that cannot be refreshed.
+     */
+    public function __construct(?string $message = null, int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct($message ?? 'The OAuth account token has expired and cannot be refreshed. Reconnect the account.', $code, $previous);
+    }
+}
diff --git a/src/saloon/src/Http/Auth/AccessTokenAuthenticator.php b/src/saloon/src/Http/Auth/AccessTokenAuthenticator.php
index a06bb96a3..273f9456b 100644
--- a/src/saloon/src/Http/Auth/AccessTokenAuthenticator.php
+++ b/src/saloon/src/Http/Auth/AccessTokenAuthenticator.php
@@ -14,6 +14,8 @@ class AccessTokenAuthenticator implements OAuthAuthenticator
 {
     /**
      * Create an access token authenticator.
+     *
+     * @param null|list<string> $scopes
      */
     public function __construct(
         #[SensitiveParameter]
@@ -21,6 +23,7 @@ public function __construct(
         #[SensitiveParameter]
         public readonly ?string $refreshToken = null,
         public readonly ?DateTimeImmutable $expiresAt = null,
+        public readonly ?array $scopes = null,
     ) {
     }
 
@@ -72,6 +75,16 @@ public function getExpiresAt(): ?DateTimeImmutable
         return $this->expiresAt;
     }
 
+    /**
+     * Get the reported scopes.
+     *
+     * @return null|list<string>
+     */
+    public function getScopes(): ?array
+    {
+        return $this->scopes;
+    }
+
     /**
      * Determine if the authenticator is refreshable.
      */
diff --git a/src/saloon/src/Http/Auth/CachedTokenAuthenticator.php b/src/saloon/src/Http/Auth/CachedTokenAuthenticator.php
new file mode 100644
index 000000000..fb87832ea
--- /dev/null
+++ b/src/saloon/src/Http/Auth/CachedTokenAuthenticator.php
@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Http\Auth;
+
+use Closure;
+use DateTimeImmutable;
+use Hypervel\Container\Container;
+use Hypervel\Contracts\Cache\Factory as CacheFactory;
+use Hypervel\Contracts\Cache\Repository as CacheRepository;
+use Hypervel\Contracts\Config\Repository as ConfigRepository;
+use Hypervel\Database\ConnectionResolver;
+use Hypervel\Saloon\Contracts\Authenticator;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Data\CachedToken;
+use Hypervel\Saloon\Http\PendingRequest;
+use SensitiveParameter;
+
+class CachedTokenAuthenticator implements Authenticator
+{
+    protected readonly string $cacheKey;
+
+    protected readonly string $store;
+
+    /** @var Closure(): OAuthAuthenticator */
+    protected readonly Closure $resolver;
+
+    protected ?CachedToken $token = null;
+
+    /**
+     * Create an authenticator for an independently reacquirable grant.
+     *
+     * @param callable(): OAuthAuthenticator $resolver
+     */
+    public function __construct(#[SensitiveParameter] string $key, callable $resolver, ?string $store = null)
+    {
+        $container = Container::getInstance();
+        $config = $container->make(ConfigRepository::class);
+        $this->store = $store ?? $config->get('saloon.cache.store') ?? $config->string('cache.default');
+        $this->cacheKey = 'saloon:oauth-token:' . hash('sha256', $key);
+        $this->resolver = $resolver(...);
+    }
+
+    /**
+     * Apply a cached token, acquiring one when needed.
+     */
+    public function set(PendingRequest $pendingRequest): void
+    {
+        $token = $this->token;
+
+        if ($token === null || ! $token->isUsable()) {
+            $token = Container::getInstance()->make(TokenAcquisition::class)->run(
+                $this->store . ':' . $this->cacheKey,
+                function (): CachedToken {
+                    $cache = $this->cache();
+                    $token = $cache->get($this->cacheKey);
+
+                    if ($token instanceof CachedToken && $token->isUsable()) {
+                        return $token;
+                    }
+
+                    ConnectionResolver::releaseIdleConnections();
+                    $token = new CachedToken(($this->resolver)());
+                    $cache->put(
+                        $this->cacheKey,
+                        $token,
+                        $token->refreshAt === null ? null : new DateTimeImmutable('@' . $token->refreshAt),
+                    );
+
+                    return $token;
+                },
+            );
+
+            $this->token = $token;
+        }
+
+        $token->authenticator->set($pendingRequest);
+    }
+
+    /**
+     * Forget this instance's token and the shared cache entry.
+     */
+    public function forget(): void
+    {
+        $this->token = null;
+        $this->cache()->forget($this->cacheKey);
+    }
+
+    /**
+     * Resolve the selected token cache.
+     */
+    protected function cache(): CacheRepository
+    {
+        return Container::getInstance()->make(CacheFactory::class)->store($this->store);
+    }
+}
diff --git a/src/saloon/src/Http/Auth/OAuthAccountAuthenticator.php b/src/saloon/src/Http/Auth/OAuthAccountAuthenticator.php
new file mode 100644
index 000000000..a0c770ac6
--- /dev/null
+++ b/src/saloon/src/Http/Auth/OAuthAccountAuthenticator.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Http\Auth;
+
+use Closure;
+use Hypervel\Container\Container;
+use Hypervel\Saloon\Contracts\Authenticator;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Data\OAuthAccountIdentity;
+use Hypervel\Saloon\Http\PendingRequest;
+use Hypervel\Saloon\OAuthAccount;
+use Hypervel\Saloon\OAuthAccounts;
+use SensitiveParameter;
+
+class OAuthAccountAuthenticator implements Authenticator
+{
+    protected readonly OAuthAccountIdentity $identity;
+
+    /**
+     * Capture the persisted account identity and its renewal callback.
+     *
+     * @param Closure(OAuthAuthenticator): OAuthAuthenticator $refreshUsing
+     */
+    public function __construct(#[SensitiveParameter] OAuthAccount $account, protected readonly Closure $refreshUsing)
+    {
+        $this->identity = Container::getInstance()->make(OAuthAccounts::class)->identity($account);
+    }
+
+    /**
+     * Apply current credentials without retaining a private token copy.
+     */
+    public function set(PendingRequest $pendingRequest): void
+    {
+        $accounts = Container::getInstance()->make(OAuthAccounts::class);
+        $token = $accounts->token($this->identity, $this->refreshUsing);
+        $accounts->ensurePartition($this->identity);
+        $token->set($pendingRequest);
+    }
+}
diff --git a/src/saloon/src/Http/Auth/TokenAcquisition.php b/src/saloon/src/Http/Auth/TokenAcquisition.php
new file mode 100644
index 000000000..2c6606018
--- /dev/null
+++ b/src/saloon/src/Http/Auth/TokenAcquisition.php
@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Http\Auth;
+
+use Closure;
+use Hypervel\Coroutine\Locker;
+use Hypervel\Database\ConnectionResolver;
+use Hypervel\Saloon\Data\TokenAcquisitionResult;
+use Swoole\Coroutine\CanceledException;
+use Throwable;
+
+class TokenAcquisition
+{
+    /** @var array<string, TokenAcquisitionResult<mixed>> */
+    protected array $active = [];
+
+    /**
+     * Share an active acquisition with callers already waiting for it.
+     *
+     * @template TResult
+     * @param Closure(): TResult $acquire
+     * @return TResult
+     */
+    public function run(string $key, Closure $acquire): mixed
+    {
+        ConnectionResolver::releaseIdleConnections();
+        $lockKey = '__saloon.token_acquisition.' . $key;
+
+        while (true) {
+            /** @var TokenAcquisitionResult<TResult> $result */
+            $result = $this->active[$key] ??= new TokenAcquisitionResult;
+
+            if (! Locker::lock($lockKey, 120)) {
+                if ($result->error !== null) {
+                    throw $result->error;
+                }
+
+                if ($result->completed) {
+                    return $result->value;
+                }
+
+                // Owner cancellation is not cancellation of its waiters.
+                continue;
+            }
+
+            try {
+                $result->value = $acquire();
+                $result->completed = true;
+
+                return $result->value;
+            } catch (CanceledException $exception) {
+                throw $exception;
+            } catch (Throwable $exception) {
+                $result->error = $exception;
+
+                throw $exception;
+            } finally {
+                unset($this->active[$key]);
+                Locker::unlock($lockKey);
+            }
+        }
+    }
+}
diff --git a/src/saloon/src/Http/Auth/TokenExpiry.php b/src/saloon/src/Http/Auth/TokenExpiry.php
new file mode 100644
index 000000000..9e4b8696f
--- /dev/null
+++ b/src/saloon/src/Http/Auth/TokenExpiry.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Http\Auth;
+
+use DateTimeImmutable;
+use Hypervel\Support\Facades\Date;
+
+class TokenExpiry
+{
+    /**
+     * Calculate a fixed renewal deadline when installing credentials.
+     */
+    public static function refreshAt(?DateTimeImmutable $expiresAt): ?int
+    {
+        if ($expiresAt === null) {
+            return null;
+        }
+
+        $expiry = $expiresAt->getTimestamp();
+        $remaining = max(0, $expiry - Date::now()->getTimestamp());
+
+        return $expiry - min(30, intdiv($remaining, 2));
+    }
+}
diff --git a/src/saloon/src/OAuthAccount.php b/src/saloon/src/OAuthAccount.php
new file mode 100644
index 000000000..b1158a8d7
--- /dev/null
+++ b/src/saloon/src/OAuthAccount.php
@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon;
+
+use Closure;
+use Hypervel\Container\Container;
+use Hypervel\Database\Eloquent\Concerns\HasUuids;
+use Hypervel\Database\Eloquent\Model;
+use Hypervel\Database\Eloquent\Relations\MorphTo;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\OAuthAccountAuthenticator;
+use Hypervel\Saloon\Http\Auth\TokenExpiry;
+use Hypervel\Support\CarbonImmutable;
+use Hypervel\Support\Str;
+
+/**
+ * @property string $access_token
+ * @property ?string $refresh_token
+ * @property ?CarbonImmutable $expires_at
+ * @property ?CarbonImmutable $refresh_at
+ * @property null|list<string> $scopes
+ * @property string $credential_revision
+ * @property ?string $refresh_claim
+ * @property ?CarbonImmutable $refresh_started_at
+ */
+class OAuthAccount extends Model
+{
+    use HasUuids;
+
+    protected ?string $table = 'oauth_accounts';
+
+    protected array $fillable = [
+        'provider',
+        'provider_account_id',
+        'access_token',
+        'refresh_token',
+        'expires_at',
+        'scopes',
+    ];
+
+    protected array $hidden = ['access_token', 'refresh_token'];
+
+    protected array $casts = [
+        'access_token' => 'encrypted',
+        'refresh_token' => 'encrypted',
+        'expires_at' => 'immutable_datetime',
+        'refresh_at' => 'immutable_datetime',
+        'refresh_started_at' => 'immutable_datetime',
+        'scopes' => 'array',
+    ];
+
+    /**
+     * Register credential revisions and committed cache invalidation.
+     */
+    protected static function booted(): void
+    {
+        static::saving(function (self $account): void {
+            $accounts = Container::getInstance()->make(OAuthAccounts::class);
+
+            if (! $account->exists) {
+                $accounts->prepareAccount($account);
+            } else {
+                $accounts->identity($account);
+            }
+
+            if (! $account->exists || $account->isDirty(['access_token', 'refresh_token', 'expires_at', 'scopes'])) {
+                $account->credential_revision = (string) Str::uuid();
+                $account->refresh_claim = null;
+                $account->refresh_started_at = null;
+            }
+
+            if (! $account->exists || $account->isDirty(['access_token', 'expires_at'])) {
+                $refreshAt = TokenExpiry::refreshAt($account->expires_at);
+                $account->refresh_at = $refreshAt === null ? null : CarbonImmutable::createFromTimestampUTC($refreshAt);
+            }
+        });
+
+        static::saved(static fn (self $account) => $account->clearCredentialCache());
+        static::deleted(static fn (self $account) => $account->clearCredentialCache());
+    }
+
+    /**
+     * Get the account owner.
+     */
+    public function owner(): MorphTo
+    {
+        return $this->morphTo('owner');
+    }
+
+    /**
+     * Create an authenticator from these credential values.
+     */
+    public function newOAuthAuthenticator(): OAuthAuthenticator
+    {
+        return new AccessTokenAuthenticator($this->access_token, $this->refresh_token, $this->expires_at, $this->scopes);
+    }
+
+    /**
+     * Authenticate using the latest persisted credentials and renew them when needed.
+     *
+     * @param Closure(OAuthAuthenticator): OAuthAuthenticator $refreshUsing
+     */
+    public function authenticator(Closure $refreshUsing): OAuthAccountAuthenticator
+    {
+        return new OAuthAccountAuthenticator($this, $refreshUsing);
+    }
+
+    /**
+     * Clear this account's cached credentials after the current transaction commits.
+     */
+    public function clearCredentialCache(): void
+    {
+        $accounts = Container::getInstance()->make(OAuthAccounts::class);
+        $accounts->invalidate($accounts->identity($this));
+    }
+}
diff --git a/src/saloon/src/OAuthAccounts.php b/src/saloon/src/OAuthAccounts.php
new file mode 100644
index 000000000..80b9cd695
--- /dev/null
+++ b/src/saloon/src/OAuthAccounts.php
@@ -0,0 +1,577 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon;
+
+use Closure;
+use GuzzleHttp\Exception\NetworkException;
+use GuzzleHttp\Exception\ResponseException as GuzzleResponseException;
+use GuzzleHttp\Exception\ResponseTransferException;
+use Hypervel\Cache\ModelCacheCoordinator;
+use Hypervel\Cache\ModelCacheStoreValidator;
+use Hypervel\Contracts\Cache\Factory as CacheFactory;
+use Hypervel\Contracts\Cache\LockProvider;
+use Hypervel\Contracts\Cache\Repository as CacheRepository;
+use Hypervel\Contracts\Cache\Store;
+use Hypervel\Contracts\Config\Repository as ConfigRepository;
+use Hypervel\Contracts\Debug\ExceptionHandler;
+use Hypervel\Database\ConnectionResolver;
+use Hypervel\Http\Client\ConnectionException;
+use Hypervel\Http\Client\RequestException;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Data\OAuthAccountIdentity;
+use Hypervel\Saloon\Exceptions\OAuthAccountReconnectRequiredException;
+use Hypervel\Saloon\Exceptions\Request\FatalRequestException;
+use Hypervel\Saloon\Http\Auth\TokenAcquisition;
+use Hypervel\Saloon\Http\Auth\TokenExpiry;
+use Hypervel\Saloon\Http\RetryAfter;
+use Hypervel\Support\CarbonImmutable;
+use Hypervel\Support\Facades\Date;
+use Hypervel\Support\Sleep;
+use Hypervel\Support\Str;
+use InvalidArgumentException;
+use LogicException;
+use Psr\Http\Message\ResponseInterface;
+use RuntimeException;
+use SensitiveParameter;
+use Swoole\Coroutine\CanceledException;
+use Throwable;
+use UnexpectedValueException;
+
+class OAuthAccounts
+{
+    public const int DEFAULT_CACHE_TTL = 300;
+
+    public const string DEFAULT_CACHE_PREFIX = 'saloon:oauth-accounts:';
+
+    protected const string DEFAULT_ACCOUNT_MODEL = OAuthAccount::class;
+
+    /** @var class-string<OAuthAccount> */
+    protected static string $accountModel = self::DEFAULT_ACCOUNT_MODEL;
+
+    protected static bool $initialized = false;
+
+    protected static ?string $partitionColumn = null;
+
+    /** @var null|Closure(): (null|int|string) */
+    protected static ?Closure $partitionResolver = null;
+
+    protected ?CacheRepository $cache = null;
+
+    protected int $cacheTtl;
+
+    protected ?CacheRepository $renewalCache = null;
+
+    protected string $renewalStore;
+
+    /**
+     * Create the account service.
+     */
+    public function __construct(
+        protected readonly ConfigRepository $config,
+        protected readonly CacheFactory $cacheFactory,
+        protected readonly ModelCacheCoordinator $cacheCoordinator,
+        protected readonly ModelCacheStoreValidator $cacheValidator,
+        protected readonly TokenAcquisition $acquisition,
+        protected readonly ExceptionHandler $exceptions,
+    ) {
+    }
+
+    /**
+     * Select the account model.
+     *
+     * Boot-only. The model persists for the worker lifetime and affects every account operation.
+     *
+     * @param class-string<OAuthAccount> $model
+     */
+    public static function useAccountModel(string $model): void
+    {
+        if (static::$initialized) {
+            throw new LogicException('Configure the OAuth account model before using accounts.');
+        }
+
+        if (! is_a($model, OAuthAccount::class, true)) {
+            throw new InvalidArgumentException('The OAuth account model must extend ' . OAuthAccount::class . '.');
+        }
+
+        static::$accountModel = $model;
+    }
+
+    /**
+     * Get the configured account model.
+     *
+     * @return class-string<OAuthAccount>
+     */
+    public static function accountModel(): string
+    {
+        return static::$accountModel;
+    }
+
+    /**
+     * Configure the account partition resolver.
+     *
+     * Boot-only. The column and callback persist for the worker lifetime and affect every account operation.
+     *
+     * @param Closure(): (null|int|string) $resolver
+     */
+    public static function resolvePartitionUsing(string $column, Closure $resolver): void
+    {
+        if (static::$initialized || static::$partitionResolver !== null) {
+            throw new LogicException('Configure the OAuth account partition once, before using accounts.');
+        }
+
+        if (preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/D', $column) !== 1) {
+            throw new InvalidArgumentException('The OAuth account partition column must be a simple SQL identifier.');
+        }
+
+        static::$partitionColumn = $column;
+        static::$partitionResolver = $resolver;
+    }
+
+    /**
+     * Resolve the current partition, rejecting missing configured context.
+     */
+    public function partition(): ?string
+    {
+        static::$initialized = true;
+
+        if (static::$partitionResolver === null) {
+            return null;
+        }
+
+        $partition = (static::$partitionResolver)();
+
+        if ((! is_string($partition) && ! is_int($partition)) || $partition === '') {
+            throw new LogicException('The current OAuth account partition is not available.');
+        }
+
+        return (string) $partition;
+    }
+
+    /**
+     * Fill the partition of a new account without accepting another context's value.
+     */
+    public function prepareAccount(OAuthAccount $account): void
+    {
+        $partition = $this->partition();
+
+        if (static::$partitionColumn === null) {
+            return;
+        }
+
+        $supplied = $account->getAttribute(static::$partitionColumn);
+
+        if ($supplied !== null && (string) $supplied !== $partition) {
+            throw new LogicException('The OAuth account belongs to another partition.');
+        }
+
+        $account->setAttribute(static::$partitionColumn, $partition);
+    }
+
+    /**
+     * Capture an account's persisted storage identity.
+     */
+    public function identity(OAuthAccount $account): OAuthAccountIdentity
+    {
+        $current = $this->partition();
+
+        if (! $account->exists && $account->getRawOriginal($account->getKeyName()) === null) {
+            throw new LogicException('Save the OAuth account before using its credentials.');
+        }
+
+        $partition = null;
+
+        if (static::$partitionColumn !== null) {
+            $original = $account->getRawOriginal();
+            $value = $original[static::$partitionColumn]
+                ?? ($account->wasRecentlyCreated ? $account->getAttribute(static::$partitionColumn) : null);
+
+            if ((! is_int($value) && ! is_string($value)) || $value === '' || (string) $value !== $current) {
+                throw new LogicException('The OAuth account belongs to another partition.');
+            }
+
+            $partition = (string) $value;
+        }
+
+        return new OAuthAccountIdentity(
+            $account::class,
+            $account->getConnectionName() ?? $account::getConnectionResolver()->getDefaultConnection(),
+            $account->getTable(),
+            $account->getKey(),
+            static::$partitionColumn,
+            $partition,
+        );
+    }
+
+    /**
+     * Check that an account reference still belongs to the active context.
+     */
+    public function ensurePartition(OAuthAccountIdentity $identity): void
+    {
+        if ($this->partition() !== $identity->partition) {
+            throw new LogicException('The OAuth account belongs to another partition.');
+        }
+    }
+
+    /**
+     * Read committed credentials, using the shared cache when enabled.
+     */
+    public function find(OAuthAccountIdentity $identity): OAuthAccount
+    {
+        $this->ensurePartition($identity);
+        $read = fn (): OAuthAccount => $identity->query()->useWritePdo()->firstOrFail()->unsetRelations();
+
+        $account = $this->cacheEnabled()
+            ? $this->cacheCoordinator->fill(
+                $this->cache(),
+                $identity->newModel(...),
+                $this->cacheKey($identity),
+                $this->cacheTtl,
+                $read,
+            )
+            : $read();
+
+        $this->ensurePartition($identity);
+
+        return $account;
+    }
+
+    /**
+     * Invalidate the account after its transaction commits.
+     */
+    public function invalidate(OAuthAccountIdentity $identity): void
+    {
+        if (! $this->cacheEnabled()) {
+            return;
+        }
+
+        $cache = $this->cache();
+        $key = $this->cacheKey($identity);
+
+        // The captured key remains safe to invalidate after the caller restores its outer context.
+        $identity->newModel()->getConnection()->afterCommitOrNow(function () use ($cache, $key): void {
+            $this->cacheCoordinator->invalidate($cache, $key);
+        });
+    }
+
+    /**
+     * Get current credentials, sharing one bounded renewal with waiting callers.
+     *
+     * @param Closure(OAuthAuthenticator): OAuthAuthenticator $refreshUsing
+     */
+    public function token(OAuthAccountIdentity $identity, Closure $refreshUsing): OAuthAuthenticator
+    {
+        if (($token = $this->usableToken($this->find($identity))) !== null) {
+            return $token;
+        }
+
+        $cache = $this->renewalCache();
+        /** @var LockProvider&Store $locks */
+        $locks = $cache->getStore();
+
+        return $this->acquisition->run('account:' . $this->renewalStore . ':' . $identity->key, function () use ($identity, $refreshUsing, $locks): OAuthAuthenticator {
+            for ($attempt = 1;; ++$attempt) {
+                $retryDelay = null;
+
+                try {
+                    return $locks->lock('saloon:oauth-renewal:' . $identity->key, 120)->block(
+                        120,
+                        function () use ($identity, $refreshUsing, $attempt, &$retryDelay): OAuthAuthenticator {
+                            return $this->renew($identity, $refreshUsing, $attempt, $retryDelay);
+                        },
+                    );
+                } catch (CanceledException $exception) {
+                    throw $exception;
+                } catch (Throwable $exception) {
+                    if ($retryDelay === null) {
+                        throw $exception;
+                    }
+
+                    ConnectionResolver::releaseIdleConnections();
+                    Sleep::usleep($retryDelay * 1000);
+                }
+            }
+        });
+    }
+
+    /**
+     * Return a usable token, or null when renewal must run first.
+     */
+    protected function usableToken(#[SensitiveParameter] OAuthAccount $account): ?OAuthAuthenticator
+    {
+        if ($account->refresh_claim !== null) {
+            return null;
+        }
+
+        $token = $account->newOAuthAuthenticator();
+
+        if ($token->isNotRefreshable()) {
+            if ($token->hasExpired()) {
+                throw new OAuthAccountReconnectRequiredException;
+            }
+
+            return $token;
+        }
+
+        return $account->expires_at === null
+            || ($account->refresh_at ?? $account->expires_at)->getTimestamp() > Date::now()->getTimestamp()
+                ? $token : null;
+    }
+
+    /**
+     * Claim, perform and persist one provider attempt while holding the renewal lock.
+     *
+     * @param Closure(OAuthAuthenticator): OAuthAuthenticator $refreshUsing
+     */
+    protected function renew(OAuthAccountIdentity $identity, Closure $refreshUsing, int $attempt, ?int &$retryDelay): OAuthAuthenticator
+    {
+        $this->ensurePartition($identity);
+        $account = $identity->query()->useWritePdo()->firstOrFail();
+        $this->ensurePartition($identity);
+
+        if (($token = $this->usableToken($account)) !== null) {
+            return $token;
+        }
+
+        if ($account->hasApplicableTransaction()) {
+            throw new LogicException('OAuth account renewal cannot run inside a database transaction.');
+        }
+
+        $abandonedBefore = Date::now()->subSeconds(300);
+
+        if ($account->refresh_claim !== null && ($account->refresh_started_at === null || $account->refresh_started_at > $abandonedBefore)) {
+            throw new RuntimeException('The OAuth account is already being refreshed. Try again later.');
+        }
+
+        $current = $account->newOAuthAuthenticator();
+
+        $revision = $account->credential_revision;
+        $claim = (string) Str::uuid();
+        $claimed = $identity->query()->where('credential_revision', $revision)
+            ->where(fn ($query) => $query->whereNull('refresh_claim')->orWhere('refresh_started_at', '<=', $abandonedBefore))
+            ->update(['refresh_claim' => $claim, 'refresh_started_at' => Date::now()]);
+
+        if ($claimed !== 1) {
+            return $this->replacementToken($identity);
+        }
+
+        $oauthError = null;
+
+        try {
+            $this->invalidate($identity);
+            ConnectionResolver::releaseIdleConnections();
+            $this->ensurePartition($identity);
+
+            try {
+                $renewed = $refreshUsing($current);
+            } catch (Throwable $exception) {
+                $oauthError = $this->oauthError($exception);
+                $retryDelay = $attempt < 3 ? $this->retryDelay($exception, $oauthError, $attempt) : null;
+                throw $exception;
+            }
+
+            $this->ensurePartition($identity);
+
+            if ($renewed->hasExpired()) {
+                throw new UnexpectedValueException('The refreshed OAuth token has already expired.');
+            }
+
+            $refreshAt = TokenExpiry::refreshAt($renewed->getExpiresAt());
+            $replacement = clone $account;
+            $replacement->forceFill([
+                'access_token' => $renewed->getAccessToken(),
+                'refresh_token' => $renewed->getRefreshToken() ?? $account->refresh_token,
+                'expires_at' => $renewed->getExpiresAt(),
+                'refresh_at' => $refreshAt === null ? null : CarbonImmutable::createFromTimestampUTC($refreshAt),
+                'scopes' => $renewed->getScopes() ?? $account->scopes,
+                'credential_revision' => (string) Str::uuid(),
+                'refresh_claim' => null,
+                'refresh_started_at' => null,
+            ]);
+            // The snapshot predates the claim, so include the cleared fields even when they are not dirty.
+            $written = $identity->query()->where('credential_revision', $revision)->where('refresh_claim', $claim)
+                ->update([...$replacement->getDirty(), 'refresh_claim' => null, 'refresh_started_at' => null]);
+            $this->invalidate($identity);
+            $this->ensurePartition($identity);
+
+            return $written === 1 ? $replacement->newOAuthAuthenticator() : $this->replacementToken($identity);
+        } catch (Throwable $exception) {
+            try {
+                // Release only this captured claim, even if the callback changed the current partition.
+                $identity->query()->where('credential_revision', $revision)->where('refresh_claim', $claim)
+                    ->update(['refresh_claim' => null, 'refresh_started_at' => null]);
+                $this->invalidate($identity);
+            } catch (Throwable $cleanupFailure) {
+                $retryDelay = null;
+                $oauthError = null;
+                try {
+                    $this->exceptions->report($cleanupFailure);
+                } catch (Throwable) {
+                    // Reporting must not replace the provider failure or cancellation.
+                }
+            }
+
+            if ($oauthError === 'invalid_grant') {
+                $this->ensurePartition($identity);
+                $latest = $identity->query()->useWritePdo()->firstOrFail();
+                $this->ensurePartition($identity);
+
+                if ($latest->credential_revision !== $revision) {
+                    return $this->usableToken($latest)
+                        ?? throw new RuntimeException('The replacement OAuth credentials are awaiting renewal. Try again later.');
+                }
+            }
+
+            throw $exception;
+        }
+    }
+
+    /**
+     * Use the authoritative replacement after losing a conditional write.
+     */
+    protected function replacementToken(OAuthAccountIdentity $identity): OAuthAuthenticator
+    {
+        $this->ensurePartition($identity);
+        $account = $identity->query()->useWritePdo()->firstOrFail();
+        $this->ensurePartition($identity);
+
+        return $this->usableToken($account)
+            ?? throw new RuntimeException('The OAuth account changed during renewal. Try again with the current credentials.');
+    }
+
+    /**
+     * Calculate a bounded provider retry delay in milliseconds.
+     */
+    protected function retryDelay(Throwable $exception, ?string $error, int $attempt): ?int
+    {
+        $response = $this->failureResponse($exception);
+
+        if (in_array($error, ['invalid_grant', 'invalid_client', 'invalid_scope', 'invalid_request', 'unauthorized_client', 'unsupported_grant_type', 'access_denied'], true)) {
+            return null;
+        }
+
+        $transient = in_array($error, ['server_error', 'temporarily_unavailable'], true)
+            || $exception instanceof ConnectionException || $exception instanceof NetworkException
+            || $exception instanceof FatalRequestException
+            || $exception instanceof ResponseTransferException
+            || ($response !== null && in_array($response->getStatusCode(), [408, 429, 500, 502, 503, 504], true));
+
+        if (! $transient) {
+            return null;
+        }
+
+        $maximum = $attempt === 1 ? 250 : 500;
+        $retryAfter = $response === null ? null : RetryAfter::seconds($response->getHeaderLine('Retry-After'));
+
+        if ($retryAfter !== null && $retryAfter > 0) {
+            // Retry-After is in whole seconds, beyond this operation's subsecond retry budget.
+            return null;
+        }
+
+        return random_int(0, $maximum);
+    }
+
+    /**
+     * Read a structured OAuth error without inspecting exception messages.
+     */
+    protected function oauthError(Throwable $exception): ?string
+    {
+        if ($exception instanceof ResponseTransferException) {
+            return null;
+        }
+
+        $response = $this->failureResponse($exception);
+
+        if ($response === null) {
+            return null;
+        }
+
+        $body = $exception instanceof RequestException
+            ? $exception->response->body()
+            : (string) $response->getBody();
+        $data = json_decode($body, true);
+
+        return is_array($data) && is_string($data['error'] ?? null) ? $data['error'] : null;
+    }
+
+    /**
+     * Get the response retained by the supported OAuth clients.
+     */
+    protected function failureResponse(Throwable $exception): ?ResponseInterface
+    {
+        return match (true) {
+            $exception instanceof RequestException => $exception->response->toPsrResponse(),
+            $exception instanceof GuzzleResponseException => $exception->getResponse(),
+            default => null,
+        };
+    }
+
+    /**
+     * Determine whether shared credential caching is enabled.
+     */
+    protected function cacheEnabled(): bool
+    {
+        return $this->config->boolean('saloon.oauth_accounts.cache.enabled', false);
+    }
+
+    /**
+     * Resolve and validate the credential cache only when it is used.
+     */
+    protected function cache(): CacheRepository
+    {
+        if ($this->cache !== null) {
+            return $this->cache;
+        }
+
+        $cache = $this->cacheFactory->store($this->config->get('saloon.oauth_accounts.cache.store'));
+        $this->cacheValidator->validate($cache, 'Saloon OAuth account cache');
+        $ttl = $this->config->integer('saloon.oauth_accounts.cache.ttl', self::DEFAULT_CACHE_TTL);
+
+        if ($ttl <= 0) {
+            throw new InvalidArgumentException('The OAuth account cache TTL must be a positive integer.');
+        }
+
+        $this->cacheTtl = $ttl;
+
+        return $this->cache = $cache;
+    }
+
+    /**
+     * Resolve and validate the renewal lock store only when it is used.
+     */
+    protected function renewalCache(): CacheRepository
+    {
+        if ($this->renewalCache !== null) {
+            return $this->renewalCache;
+        }
+
+        $store = $this->config->get('saloon.oauth_accounts.lock_store')
+            ?? $this->config->get('saloon.oauth_accounts.cache.store')
+            ?? $this->config->string('cache.default');
+        $cache = $this->cacheFactory->store($store);
+        $this->cacheValidator->validate($cache, 'Saloon OAuth account renewal');
+        $this->renewalStore = $store;
+
+        return $this->renewalCache = $cache;
+    }
+
+    /**
+     * Build the shared credential key.
+     */
+    protected function cacheKey(OAuthAccountIdentity $identity): string
+    {
+        return $this->config->string('saloon.oauth_accounts.cache.prefix', self::DEFAULT_CACHE_PREFIX) . $identity->key;
+    }
+
+    /**
+     * Flush all static state.
+     */
+    public static function flushState(): void
+    {
+        static::$accountModel = self::DEFAULT_ACCOUNT_MODEL;
+        static::$initialized = false;
+        static::$partitionColumn = null;
+        static::$partitionResolver = null;
+    }
+}
diff --git a/src/saloon/src/SaloonServiceProvider.php b/src/saloon/src/SaloonServiceProvider.php
index 76660901d..9525cda3a 100644
--- a/src/saloon/src/SaloonServiceProvider.php
+++ b/src/saloon/src/SaloonServiceProvider.php
@@ -4,6 +4,8 @@
 
 namespace Hypervel\Saloon;
 
+use Carbon\CarbonImmutable as BaseCarbonImmutable;
+use DateTimeImmutable;
 use Hypervel\Cache\CacheManager;
 use Hypervel\Contracts\Cache\Factory as CacheFactory;
 use Hypervel\Contracts\Config\Repository as ConfigRepository;
@@ -18,8 +20,12 @@
 use Hypervel\Saloon\Console\Commands\MakePlugin;
 use Hypervel\Saloon\Console\Commands\MakeRequest;
 use Hypervel\Saloon\Console\Commands\MakeResponse;
+use Hypervel\Saloon\Console\Commands\OAuthAccountsTableCommand;
+use Hypervel\Saloon\Data\CachedToken;
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
 use Hypervel\Saloon\Http\RequestOptionValidator;
 use Hypervel\Saloon\Http\Sender;
+use Hypervel\Support\CarbonImmutable;
 use Hypervel\Support\ServiceProvider;
 
 class SaloonServiceProvider extends ServiceProvider
@@ -54,8 +60,15 @@ public function register(): void
      */
     public function boot(HttpFactory $httpFactory, ConfigRepository $config, CacheManager $cache): void
     {
-        // Cached responses are stored as CachedResponse objects, which serializing stores must be allowed to restore.
-        $cache->allowSerializableClassesUsing(static fn (): array => [CachedResponse::class]);
+        $cache->allowSerializableClassesUsing(static fn (): array => [
+            CachedResponse::class,
+            CachedToken::class,
+            AccessTokenAuthenticator::class,
+            DateTimeImmutable::class,
+            BaseCarbonImmutable::class,
+            CarbonImmutable::class,
+            OAuthAccounts::accountModel(),
+        ]);
 
         $connection = $config->string('saloon.connection.name');
         $options = $config->array('saloon.connection.options');
@@ -89,6 +102,7 @@ protected function registerConsoleResources(): void
             MakePlugin::class,
             MakeRequest::class,
             MakeResponse::class,
+            OAuthAccountsTableCommand::class,
         ]);
 
         $this->publishes([
diff --git a/src/saloon/src/Traits/HasOAuthAccounts.php b/src/saloon/src/Traits/HasOAuthAccounts.php
new file mode 100644
index 000000000..13a4fb713
--- /dev/null
+++ b/src/saloon/src/Traits/HasOAuthAccounts.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Saloon\Traits;
+
+use Hypervel\Database\Eloquent\Model;
+use Hypervel\Database\Eloquent\Relations\MorphMany;
+use Hypervel\Saloon\OAuthAccount;
+use Hypervel\Saloon\OAuthAccounts;
+
+/**
+ * @phpstan-require-extends Model
+ */
+trait HasOAuthAccounts
+{
+    /**
+     * Get the owner's connected OAuth accounts.
+     *
+     * @return MorphMany<OAuthAccount, $this>
+     */
+    public function oauthAccounts(): MorphMany
+    {
+        return $this->morphMany(OAuthAccounts::accountModel(), 'owner');
+    }
+}
diff --git a/src/saloon/src/Traits/OAuth2/AuthorizationCodeGrant.php b/src/saloon/src/Traits/OAuth2/AuthorizationCodeGrant.php
index b80239e87..890cd7649 100644
--- a/src/saloon/src/Traits/OAuth2/AuthorizationCodeGrant.php
+++ b/src/saloon/src/Traits/OAuth2/AuthorizationCodeGrant.php
@@ -10,6 +10,7 @@
 use Hypervel\Saloon\Data\OAuthConfig;
 use Hypervel\Saloon\Exceptions\InvalidStateException;
 use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\OAuthAccountAuthenticator;
 use Hypervel\Saloon\Http\Connector;
 use Hypervel\Saloon\Http\OAuth2\GetAccessTokenRequest;
 use Hypervel\Saloon\Http\OAuth2\GetRefreshTokenRequest;
@@ -17,6 +18,7 @@
 use Hypervel\Saloon\Http\Request;
 use Hypervel\Saloon\Http\Response;
 use Hypervel\Saloon\Http\UrlResolver;
+use Hypervel\Saloon\OAuthAccount;
 use Hypervel\Support\Str;
 use InvalidArgumentException;
 use SensitiveParameter;
@@ -31,6 +33,24 @@ trait AuthorizationCodeGrant
     use HasOAuthConfig;
     use ParsesOAuthTokenResponses;
 
+    /**
+     * Authenticate a connected account and renew its stored credentials when needed.
+     *
+     * @param null|callable(Request): void $requestModifier
+     */
+    public function accountAuthenticator(OAuthAccount $account, ?callable $requestModifier = null): OAuthAccountAuthenticator
+    {
+        return $account->authenticator(fn (OAuthAuthenticator $current): OAuthAuthenticator => $this->refreshAccessToken(
+            $current,
+            requestModifier: static function (Request $request) use ($requestModifier): void {
+                if ($requestModifier !== null) {
+                    $requestModifier($request);
+                }
+                $request->retry(1);
+            },
+        ));
+    }
+
     /**
      * Create an authorization URL and its paired state.
      *
@@ -116,7 +136,9 @@ public function getAccessToken(
         }
 
         $request = $config->modify($request);
-        $requestModifier?->__invoke($request);
+        if ($requestModifier !== null) {
+            $requestModifier($request);
+        }
         $response = $this->send($request);
 
         if ($returnResponse) {
@@ -154,7 +176,9 @@ public function refreshAccessToken(
         }
 
         $request = $config->modify($this->resolveRefreshTokenRequest($config, $refreshToken));
-        $requestModifier?->__invoke($request);
+        if ($requestModifier !== null) {
+            $requestModifier($request);
+        }
         $response = $this->send($request);
 
         if ($returnResponse) {
@@ -182,11 +206,13 @@ protected function createOAuthAuthenticatorFromResponse(
             throw new UnexpectedValueException('The OAuth token response contains an invalid refresh token.');
         }
 
-        return $this->createOAuthAuthenticator($accessToken, $refreshToken, $expiresAt);
+        return $this->createOAuthAuthenticator($accessToken, $refreshToken, $expiresAt, $this->resolveOAuthScopes($data['scope'] ?? null));
     }
 
     /**
      * Create an OAuth authenticator.
+     *
+     * @param null|list<string> $scopes
      */
     protected function createOAuthAuthenticator(
         #[SensitiveParameter]
@@ -194,8 +220,9 @@ protected function createOAuthAuthenticator(
         #[SensitiveParameter]
         ?string $refreshToken = null,
         ?DateTimeImmutable $expiresAt = null,
+        ?array $scopes = null,
     ): OAuthAuthenticator {
-        return new AccessTokenAuthenticator($accessToken, $refreshToken, $expiresAt);
+        return new AccessTokenAuthenticator($accessToken, $refreshToken, $expiresAt, $scopes);
     }
 
     /**
@@ -208,7 +235,9 @@ public function getUser(OAuthAuthenticator $oauthAuthenticator, ?callable $reque
     {
         $config = $this->oauthConfig();
         $request = $config->modify($this->resolveUserRequest($config))->authenticate($oauthAuthenticator);
-        $requestModifier?->__invoke($request);
+        if ($requestModifier !== null) {
+            $requestModifier($request);
+        }
 
         return $this->send($request);
     }
diff --git a/src/saloon/src/Traits/OAuth2/ClientCredentialsGrant.php b/src/saloon/src/Traits/OAuth2/ClientCredentialsGrant.php
index d877a6d5a..32ac4692b 100644
--- a/src/saloon/src/Traits/OAuth2/ClientCredentialsGrant.php
+++ b/src/saloon/src/Traits/OAuth2/ClientCredentialsGrant.php
@@ -8,10 +8,12 @@
 use Hypervel\Saloon\Contracts\OAuthAuthenticator;
 use Hypervel\Saloon\Data\OAuthConfig;
 use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\CachedTokenAuthenticator;
 use Hypervel\Saloon\Http\Connector;
 use Hypervel\Saloon\Http\OAuth2\GetClientCredentialsTokenRequest;
 use Hypervel\Saloon\Http\Request;
 use Hypervel\Saloon\Http\Response;
+use Hypervel\Saloon\Http\UrlResolver;
 use SensitiveParameter;
 
 /**
@@ -23,6 +25,35 @@ trait ClientCredentialsGrant
     use HasOAuthConfig;
     use ParsesOAuthTokenResponses;
 
+    /**
+     * Cache client-credentials tokens for this grant.
+     *
+     * @param list<?string> $scopes
+     * @param null|callable(Request): void $requestModifier
+     */
+    public function cachedAccessToken(
+        array $scopes = [],
+        string $scopeSeparator = ' ',
+        ?string $store = null,
+        ?callable $requestModifier = null,
+        string $key = '',
+    ): CachedTokenAuthenticator {
+        $config = $this->oauthConfig();
+        $config->validate(withRedirectUrl: false);
+        $endpoint = UrlResolver::resolve(
+            $this->resolveBaseUrl(),
+            $config->tokenEndpoint,
+            $config->allowBaseUrlOverride || $this->allowsBaseUrlOverride(),
+        );
+
+        return new CachedTokenAuthenticator(
+            serialize([static::class, (string) $endpoint, $config->clientId, $config->clientSecret,
+                implode($scopeSeparator, $config->scopes($scopes)), $key]),
+            fn (): OAuthAuthenticator => $this->getAccessToken($scopes, $scopeSeparator, requestModifier: $requestModifier),
+            $store,
+        );
+    }
+
     /**
      * Request a client-credentials access token.
      *
@@ -40,7 +71,9 @@ public function getAccessToken(
         $config = $this->oauthConfig();
         $config->validate(withRedirectUrl: false);
         $request = $config->modify($this->resolveAccessTokenRequest($config, $scopes, $scopeSeparator));
-        $requestModifier?->__invoke($request);
+        if ($requestModifier !== null) {
+            $requestModifier($request);
+        }
         $response = $this->send($request);
 
         if ($returnResponse) {
@@ -57,20 +90,23 @@ public function getAccessToken(
      */
     protected function createOAuthAuthenticatorFromResponse(#[SensitiveParameter] Response $response): OAuthAuthenticator
     {
-        [$accessToken, $expiresAt] = $this->parseOAuthTokenResponse($response);
+        [$accessToken, $expiresAt, $data] = $this->parseOAuthTokenResponse($response);
 
-        return $this->createOAuthAuthenticator($accessToken, $expiresAt);
+        return $this->createOAuthAuthenticator($accessToken, $expiresAt, $this->resolveOAuthScopes($data['scope'] ?? null));
     }
 
     /**
      * Create an OAuth authenticator.
+     *
+     * @param null|list<string> $scopes
      */
     protected function createOAuthAuthenticator(
         #[SensitiveParameter]
         string $accessToken,
         ?DateTimeImmutable $expiresAt = null,
+        ?array $scopes = null,
     ): OAuthAuthenticator {
-        return new AccessTokenAuthenticator($accessToken, null, $expiresAt);
+        return new AccessTokenAuthenticator($accessToken, null, $expiresAt, $scopes);
     }
 
     /**
diff --git a/src/saloon/src/Traits/OAuth2/ParsesOAuthTokenResponses.php b/src/saloon/src/Traits/OAuth2/ParsesOAuthTokenResponses.php
index 299818298..de7ff68be 100644
--- a/src/saloon/src/Traits/OAuth2/ParsesOAuthTokenResponses.php
+++ b/src/saloon/src/Traits/OAuth2/ParsesOAuthTokenResponses.php
@@ -34,6 +34,26 @@ protected function parseOAuthTokenResponse(#[SensitiveParameter] Response $respo
         return [$accessToken, $this->resolveOAuthExpiry($data['expires_in'] ?? null), $data];
     }
 
+    /**
+     * Resolve the scopes reported by the provider.
+     *
+     * @return null|list<string>
+     */
+    protected function resolveOAuthScopes(mixed $scopes): ?array
+    {
+        if ($scopes === null || $scopes === '') {
+            return null;
+        }
+
+        if (! is_string($scopes)) {
+            throw new UnexpectedValueException('The OAuth token response contains invalid scopes.');
+        }
+
+        $resolved = array_values(array_filter(explode(' ', $scopes), static fn (string $scope): bool => $scope !== ''));
+
+        return $resolved === [] ? null : $resolved;
+    }
+
     /**
      * Resolve an OAuth token expiry.
      */
diff --git a/src/testing/src/PHPUnit/AfterEachTestSubscriber.php b/src/testing/src/PHPUnit/AfterEachTestSubscriber.php
index d060f12e8..fe30576bb 100644
--- a/src/testing/src/PHPUnit/AfterEachTestSubscriber.php
+++ b/src/testing/src/PHPUnit/AfterEachTestSubscriber.php
@@ -520,6 +520,7 @@ protected function flushReverbState(): void
      */
     protected function flushSaloonState(): void
     {
+        $this->callIfExists(\Hypervel\Saloon\OAuthAccounts::class, 'flushState');
         $this->callIfExists(\Hypervel\Saloon\Http\Connector::class, 'flushState');
         $this->callIfExists(\Hypervel\Saloon\Http\PendingRequest::class, 'flushState');
         $this->callIfExists(\Hypervel\Saloon\Http\PendingRequest\BootPlugins::class, 'flushState');
diff --git a/tests/Integration/Saloon/Redis/OAuthAccountRenewalTest.php b/tests/Integration/Saloon/Redis/OAuthAccountRenewalTest.php
new file mode 100644
index 000000000..7886355bb
--- /dev/null
+++ b/tests/Integration/Saloon/Redis/OAuthAccountRenewalTest.php
@@ -0,0 +1,163 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Integration\Saloon\Redis;
+
+use Closure;
+use Hypervel\Contracts\Foundation\Application as ApplicationContract;
+use Hypervel\Engine\Channel;
+use Hypervel\Engine\Coroutine as EngineCoroutine;
+use Hypervel\Foundation\Testing\Concerns\InteractsWithRedis;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\TokenAcquisition;
+use Hypervel\Saloon\OAuthAccount;
+use Hypervel\Saloon\OAuthAccounts;
+use Hypervel\Saloon\SaloonServiceProvider;
+use Hypervel\Support\Facades\Date;
+use Hypervel\Support\Facades\DB;
+use Hypervel\Testbench\TestCase;
+use PHPUnit\Framework\Attributes\TestWith;
+use RuntimeException;
+use Throwable;
+
+use function Hypervel\Coroutine\go;
+
+class OAuthAccountRenewalTest extends TestCase
+{
+    use InteractsWithRedis;
+
+    protected ?string $migration = null;
+
+    /**
+     * Register Saloon for shared-store renewal tests.
+     */
+    protected function getPackageProviders(ApplicationContract $app): array
+    {
+        return [SaloonServiceProvider::class];
+    }
+
+    /**
+     * Use the isolated Redis connection for credentials and renewal locks.
+     */
+    protected function defineEnvironment(ApplicationContract $app): void
+    {
+        $app->make('config')->set('saloon.oauth_accounts.cache', ['enabled' => true, 'store' => 'redis']);
+    }
+
+    /**
+     * Create the account schema through its migration command.
+     */
+    protected function setUpInCoroutine(): void
+    {
+        Date::setTestNow('2026-01-01 00:00:00');
+        $this->artisan('make:oauth-accounts-table')->assertSuccessful();
+        $files = $this->app->make('files')->glob($this->app->databasePath('migrations/*_create_oauth_accounts_table.php'));
+        $this->migration = $files[0];
+        (require $this->migration)->up();
+    }
+
+    /**
+     * Remove the generated migration.
+     */
+    protected function tearDown(): void
+    {
+        try {
+            if ($this->migration !== null) {
+                $this->app->make('files')->delete($this->migration);
+            }
+        } finally {
+            parent::tearDown();
+        }
+    }
+
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testDatabaseClaimSurvivesLostRedisLockAndFencesLateCompletion(bool $abandoned): void
+    {
+        $account = new OAuthAccount;
+        $account->forceFill([
+            'owner_type' => 'test', 'owner_id' => 1,
+            'provider' => 'example', 'access_token' => 'old', 'refresh_token' => 'refresh',
+            'expires_at' => Date::now()->subMinute(),
+        ])->save();
+        $first = $this->worker('first');
+        $second = $this->worker('second');
+        $identity = $first->identity($account);
+        $entered = new Channel(1);
+        $release = new Channel(1);
+        $result = new Channel(1);
+        DB::releaseIdleConnections();
+        $owner = go(function () use ($first, $identity, $entered, $release, $result): void {
+            try {
+                $result->push($first->token($identity, function () use ($entered, $release): OAuthAuthenticator {
+                    $entered->push(true);
+                    if ($release->pop(5) !== true) {
+                        throw new RuntimeException('Provider release was not received.');
+                    }
+
+                    return new AccessTokenAuthenticator('first-result');
+                })->getAccessToken());
+            } catch (Throwable $exception) {
+                $result->push($exception);
+            }
+        });
+
+        try {
+            $this->assertTrue($entered->pop(5));
+            $this->app->make('cache')->store('redis')->lock('saloon:oauth-renewal:' . $identity->key)->forceRelease();
+
+            if ($abandoned) {
+                Date::setTestNow('2026-01-01 00:05:00');
+                $replacement = $second->token($identity, fn (): OAuthAuthenticator => new AccessTokenAuthenticator('replacement'));
+                $this->assertSame('replacement', $replacement->getAccessToken());
+            } else {
+                try {
+                    $second->token($identity, fn (): never => $this->fail('A fresh row claim must prevent a second provider call.'));
+                    $this->fail('The lost Redis lease must not bypass a fresh row claim.');
+                } catch (RuntimeException $exception) {
+                    $this->assertSame('The OAuth account is already being refreshed. Try again later.', $exception->getMessage());
+                }
+            }
+
+            DB::releaseIdleConnections();
+            $release->push(true);
+            $expected = $abandoned ? 'replacement' : 'first-result';
+            $this->assertSame($expected, $result->pop(5));
+            $this->assertSame($expected, $account->fresh()->access_token);
+            $this->assertNull($account->fresh()->refresh_claim);
+        } finally {
+            $release->close();
+            EngineCoroutine::join([$owner], 5);
+            $entered->close();
+            $result->close();
+        }
+    }
+
+    /**
+     * Isolate worker-local coordination while exercising the real Redis and database protocol.
+     */
+    protected function worker(string $name): OAuthAccounts
+    {
+        return $this->app->make(OAuthAccounts::class, ['acquisition' => new WorkerTokenAcquisition($name)]);
+    }
+}
+
+class WorkerTokenAcquisition extends TokenAcquisition
+{
+    /**
+     * Select an independent worker-local coordination namespace.
+     */
+    public function __construct(private readonly string $worker)
+    {
+    }
+
+    /**
+     * Coordinate only callers belonging to this simulated worker.
+     */
+    public function run(string $key, Closure $acquire): mixed
+    {
+        return parent::run($this->worker . ':' . $key, $acquire);
+    }
+}
diff --git a/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php b/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php
index 7da2cfb3a..a5c99bc1a 100644
--- a/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php
+++ b/tests/Saloon/Feature/Oauth2/AuthCodeFlowConnectorTest.php
@@ -406,6 +406,22 @@ public function testYouCanRefreshATokenFromAConnector(): void
         $this->assertInstanceOf(DateTimeImmutable::class, $newAuthenticator->getExpiresAt());
     }
 
+    public function testScopesReachCustomFactoriesOnExchangeAndRefresh(): void
+    {
+        $connector = new CustomResponseOAuth2Connector('hello');
+        Saloon::fake([
+            MockResponse::make(['access_token' => 'access', 'refresh_token' => 'refresh', 'scope' => 'read write']),
+            MockResponse::make(['access_token' => 'renewed', 'scope' => 'read']),
+        ]);
+
+        $original = $connector->getAccessToken('code');
+        $renewed = $connector->refreshAccessToken($original);
+
+        $this->assertSame(['read', 'write'], $original->getScopes());
+        $this->assertSame(['read'], $renewed->getScopes());
+        $this->assertSame('refresh', $renewed->getRefreshToken());
+    }
+
     public function testYouCanTapIntoTheRefreshTokenRequest(): void
     {
         $mockClient = new MockClient([
diff --git a/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php b/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
index c2982f962..a1cca9205 100644
--- a/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
+++ b/tests/Saloon/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
@@ -125,6 +125,24 @@ public function testYouCanTapIntoTheTokenRequest(): void
         $this->assertSame(['yee' => 'haw'], $mockClient->lastPendingRequest()->queryParameters());
     }
 
+    public function testAnArrayCallableCanModifyTheTokenRequest(): void
+    {
+        $mockClient = Saloon::fake([MockResponse::make(['access_token' => 'access'])]);
+        $modifier = new class {
+            /**
+             * Add an application header to the token request.
+             */
+            public function modify(Request $request): void
+            {
+                $request->withHeader('X-OAuth-Client', 'application');
+            }
+        };
+
+        (new ClientCredentialsConnector)->getAccessToken(requestModifier: [$modifier, 'modify']);
+
+        $this->assertSame('application', $mockClient->lastPendingRequest()->headers()['X-OAuth-Client']);
+    }
+
     public function testYouCanSendScopesWithTheTokenRequest(): void
     {
         $mockClient = new MockClient([
@@ -302,14 +320,31 @@ public function testAReturnedRefreshTokenIsIgnored(): void
         $this->assertNull($authenticator->getRefreshToken());
     }
 
+    #[DataProvider('scopeConnectors')]
+    public function testReportedScopesArePreservedWithoutInferringRequestedPermissions(ClientCredentialsBasicAuthConnector|ClientCredentialsConnector $connector): void
+    {
+        foreach ([null, '', '   ', 'read write', '0'] as $scope) {
+            Saloon::fake([MockResponse::make(['access_token' => 'access', 'scope' => $scope])]);
+
+            $authenticator = $connector->getAccessToken(['requested']);
+
+            $this->assertSame(match ($scope) {
+                null, '', '   ' => null,
+                '0' => ['0'],
+                default => ['read', 'write'],
+            }, $authenticator->getScopes());
+        }
+    }
+
     public function testACustomAuthenticatorReceivesTheExpiry(): void
     {
         Date::setTestNow('2026-01-01T00:00:00+00:00');
-        Saloon::fake([MockResponse::make(['access_token' => 'access', 'expires_in' => 3600])]);
+        Saloon::fake([MockResponse::make(['access_token' => 'access', 'expires_in' => 3600, 'scope' => 'read'])]);
 
         $authenticator = (new CustomAuthenticatorClientCredentialsConnector)->getAccessToken();
 
         $this->assertInstanceOf(CustomOAuthAuthenticator::class, $authenticator);
+        $this->assertSame(['read'], $authenticator->getScopes());
         $this->assertEquals(new DateTimeImmutable('2026-01-01T01:00:00+00:00'), $authenticator->getExpiresAt());
     }
 
@@ -325,6 +360,7 @@ public function testTokenResponseValidationRejectsInvalidValues(): void
             ['access_token' => 'token', 'expires_in' => '1.5'],
             ['access_token' => 'token', 'expires_in' => 1.0E+30],
             ['access_token' => 'token', 'expires_in' => PHP_INT_MAX],
+            ['access_token' => 'token', 'scope' => ['read']],
         ] as $body) {
             Saloon::fake([MockResponse::make($body)]);
 
@@ -371,10 +407,10 @@ public static function validExpiries(): array
 class CustomAuthenticatorClientCredentialsConnector extends ClientCredentialsConnector
 {
     /**
-     * Create the OAuth authenticator with upstream's client-credentials signature.
+     * Create the custom OAuth authenticator.
      */
-    protected function createOAuthAuthenticator(string $accessToken, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator
+    protected function createOAuthAuthenticator(string $accessToken, ?DateTimeImmutable $expiresAt = null, ?array $scopes = null): OAuthAuthenticator
     {
-        return new CustomOAuthAuthenticator($accessToken, 'Howdy!', null, $expiresAt);
+        return new CustomOAuthAuthenticator($accessToken, 'Howdy!', null, $expiresAt, $scopes);
     }
 }
diff --git a/tests/Saloon/Fixtures/Authenticators/CustomOAuthAuthenticator.php b/tests/Saloon/Fixtures/Authenticators/CustomOAuthAuthenticator.php
index fc3ef671c..29b7f6286 100644
--- a/tests/Saloon/Fixtures/Authenticators/CustomOAuthAuthenticator.php
+++ b/tests/Saloon/Fixtures/Authenticators/CustomOAuthAuthenticator.php
@@ -17,6 +17,7 @@ public function __construct(
         public readonly string $greeting,
         public readonly ?string $refreshToken = null,
         public readonly ?DateTimeImmutable $expiresAt = null,
+        public readonly ?array $scopes = null,
     ) {
     }
 
diff --git a/tests/Saloon/Fixtures/Connectors/CustomResponseOAuth2Connector.php b/tests/Saloon/Fixtures/Connectors/CustomResponseOAuth2Connector.php
index 46158e808..f7bd55257 100644
--- a/tests/Saloon/Fixtures/Connectors/CustomResponseOAuth2Connector.php
+++ b/tests/Saloon/Fixtures/Connectors/CustomResponseOAuth2Connector.php
@@ -45,8 +45,8 @@ protected function defaultOauthConfig(): OAuthConfig
     /**
      * Create the OAuth authenticator.
      */
-    protected function createOAuthAuthenticator(string $accessToken, ?string $refreshToken = null, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator
+    protected function createOAuthAuthenticator(string $accessToken, ?string $refreshToken = null, ?DateTimeImmutable $expiresAt = null, ?array $scopes = null): OAuthAuthenticator
     {
-        return new CustomOAuthAuthenticator($accessToken, $this->greeting, $refreshToken, $expiresAt);
+        return new CustomOAuthAuthenticator($accessToken, $this->greeting, $refreshToken, $expiresAt, $scopes);
     }
 }
diff --git a/tests/Saloon/OAuthAccountTest.php b/tests/Saloon/OAuthAccountTest.php
new file mode 100644
index 000000000..f8f2c999d
--- /dev/null
+++ b/tests/Saloon/OAuthAccountTest.php
@@ -0,0 +1,899 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Saloon\OAuthAccountTest;
+
+use GuzzleHttp\Exception\ResponseTransferException;
+use GuzzleHttp\Psr7\PumpStream;
+use GuzzleHttp\Psr7\Request as PsrRequest;
+use GuzzleHttp\Psr7\Response as PsrResponse;
+use Hypervel\Contracts\Debug\ExceptionHandler;
+use Hypervel\Contracts\Foundation\Application as ApplicationContract;
+use Hypervel\Database\Eloquent\Builder;
+use Hypervel\Database\Eloquent\Model;
+use Hypervel\Database\Eloquent\ModelNotFoundException;
+use Hypervel\Database\Pool\PoolManager;
+use Hypervel\Database\Query\Builder as QueryBuilder;
+use Hypervel\Database\Schema\Blueprint;
+use Hypervel\Engine\Channel;
+use Hypervel\Engine\Coroutine as EngineCoroutine;
+use Hypervel\Http\Client\RequestException;
+use Hypervel\Http\Client\Response;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Exceptions\OAuthAccountReconnectRequiredException;
+use Hypervel\Saloon\Facades\Saloon;
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\OAuthAccountAuthenticator;
+use Hypervel\Saloon\Http\Faking\MockResponse;
+use Hypervel\Saloon\Http\Request;
+use Hypervel\Saloon\OAuthAccount;
+use Hypervel\Saloon\OAuthAccounts;
+use Hypervel\Saloon\SaloonServiceProvider;
+use Hypervel\Saloon\Traits\HasOAuthAccounts;
+use Hypervel\Support\Facades\Context;
+use Hypervel\Support\Facades\Date;
+use Hypervel\Support\Facades\DB;
+use Hypervel\Support\Facades\Schema;
+use Hypervel\Support\Sleep;
+use Hypervel\Testbench\Attributes\DefineEnvironment;
+use Hypervel\Testbench\TestCase;
+use Hypervel\Tests\Saloon\Fixtures\Connectors\OAuth2Connector;
+use Hypervel\Tests\Saloon\Fixtures\Connectors\TestConnector;
+use Hypervel\Tests\Saloon\Fixtures\Mocking\UnseekableBodyMockResponse;
+use Hypervel\Tests\Saloon\Fixtures\Requests\UserRequest;
+use LogicException;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\TestWith;
+use RuntimeException;
+use Swoole\Coroutine\CanceledException;
+use Throwable;
+use UnexpectedValueException;
+
+use function Hypervel\Coroutine\go;
+use function Hypervel\Coroutine\parallel;
+
+class OAuthAccountTest extends TestCase
+{
+    protected ?string $migration = null;
+
+    protected bool $credentialCacheEnabled = true;
+
+    /**
+     * Register Saloon for the account tests.
+     */
+    protected function getPackageProviders(ApplicationContract $app): array
+    {
+        return [SaloonServiceProvider::class];
+    }
+
+    /**
+     * Configure isolated databases and a shared credential cache.
+     */
+    protected function defineEnvironment(ApplicationContract $app): void
+    {
+        $app->make('config')->set([
+            'database.default' => 'oauth',
+            'database.connections.oauth' => [
+                'driver' => 'sqlite',
+                'database' => ':memory:',
+                'pool' => ['testing_enabled' => true, 'max_connections' => 1, 'wait_timeout' => 1.0],
+            ],
+            'database.connections.oauth-secondary' => ['driver' => 'sqlite', 'database' => ':memory:'],
+            'cache.stores.oauth-accounts' => [
+                'driver' => 'file',
+                'path' => $app->storagePath('framework/cache/oauth-accounts'),
+            ],
+            'saloon.oauth_accounts.cache' => [
+                'enabled' => $this->credentialCacheEnabled,
+                'store' => 'oauth-accounts',
+            ],
+        ]);
+    }
+
+    /**
+     * Exercise uncached account reads.
+     */
+    protected function disableCredentialCache(ApplicationContract $app): void
+    {
+        $this->credentialCacheEnabled = false;
+    }
+
+    /**
+     * Select a custom model after reading the current default.
+     */
+    protected function configureCustomAccountModel(): void
+    {
+        OAuthAccounts::accountModel();
+        OAuthAccounts::useAccountModel(CustomAccount::class);
+    }
+
+    /**
+     * Select a model with guarded credential writes.
+     */
+    protected function configureGuardedAccountModel(): void
+    {
+        OAuthAccounts::useAccountModel(GuardedAccount::class);
+    }
+
+    /**
+     * Select a model whose claim cleanup fails.
+     */
+    protected function configureCleanupFailingAccountModel(): void
+    {
+        OAuthAccounts::useAccountModel(CleanupFailingAccount::class);
+    }
+
+    /**
+     * Create the schema through the public migration command.
+     */
+    protected function setUpInCoroutine(): void
+    {
+        Date::setTestNow('2026-01-01 00:00:00');
+        $this->artisan('make:oauth-accounts-table')->assertSuccessful();
+        $files = $this->app->make('files')->glob($this->app->databasePath('migrations/*_create_oauth_accounts_table.php'));
+        $this->migration = $files[0];
+        (require $this->migration)->up();
+        Schema::create('owners', function (Blueprint $table): void {
+            $table->id();
+        });
+    }
+
+    /**
+     * Remove the generated migration and cached credentials.
+     */
+    protected function tearDown(): void
+    {
+        try {
+            if ($this->migration !== null) {
+                $this->app->make('files')->delete($this->migration);
+            }
+
+            $this->app->make('cache')->store('oauth-accounts')->flush();
+        } finally {
+            parent::tearDown();
+        }
+    }
+
+    public function testRelationPersistsEncryptedCredentialsAndCreatesFixedRenewalDeadline(): void
+    {
+        $owner = Owner::create();
+        $account = $owner->oauthAccounts()->create([
+            'provider' => 'example',
+            'provider_account_id' => 'external-id',
+            'access_token' => 'secret-access',
+            'refresh_token' => 'secret-refresh',
+            'expires_at' => Date::now()->addSeconds(10),
+            'scopes' => [],
+        ]);
+
+        $stored = DB::table('oauth_accounts')->first();
+        $this->assertNotSame('secret-access', $stored->access_token);
+        $this->assertNotSame('secret-refresh', $stored->refresh_token);
+        $this->assertStringNotContainsString('secret-', json_encode($account));
+        $this->assertSame('secret-access', $account->fresh()->newOAuthAuthenticator()->getAccessToken());
+        $this->assertSame([], $account->fresh()->scopes);
+        $accounts = $this->app->make(OAuthAccounts::class);
+        $serialized = serialize($accounts->find($accounts->identity($account)));
+        $this->assertStringNotContainsString('secret-access', $serialized);
+        $this->assertStringNotContainsString('secret-refresh', $serialized);
+        $this->assertSame('2026-01-01 00:00:05', $account->refresh_at->format('Y-m-d H:i:s'));
+        $this->assertTrue($account->owner->is($owner));
+
+        $revision = $account->credential_revision;
+        Date::setTestNow('2026-01-01 00:00:04');
+        $account->update(['provider_account_id' => 'renamed']);
+        $this->assertSame($revision, $account->credential_revision);
+        $this->assertSame('2026-01-01 00:00:05', $account->refresh_at->format('Y-m-d H:i:s'));
+
+        $account->update(['access_token' => 'replacement', 'expires_at' => Date::now()->addHour()]);
+        $this->assertNotSame($revision, $account->credential_revision);
+        $this->assertSame('2026-01-01 00:59:34', $account->refresh_at->format('Y-m-d H:i:s'));
+        $account->update(['expires_at' => null]);
+        $this->assertNull($account->refresh_at);
+    }
+
+    public function testWarmCredentialsRequireNoQueriesAndSaveAndDeleteInvalidateThem(): void
+    {
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'first']);
+        $accounts = $this->app->make(OAuthAccounts::class);
+        $identity = $accounts->identity($account);
+        $accounts->find($identity);
+        DB::enableQueryLog();
+        DB::flushQueryLog();
+
+        $this->assertSame('first', $accounts->find($identity)->newOAuthAuthenticator()->getAccessToken());
+        $this->assertSame([], DB::getQueryLog());
+
+        $account->update(['access_token' => 'second']);
+        $this->assertSame('second', $accounts->find($identity)->access_token);
+        $account->delete();
+        $this->expectException(ModelNotFoundException::class);
+        $accounts->find($identity);
+    }
+
+    #[DefineEnvironment('disableCredentialCache')]
+    public function testCachingCanBeDisabledWithoutChangingAuthentication(): void
+    {
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'uncached']);
+        $authenticator = $account->authenticator(fn (): never => $this->fail('Non-expiring credentials must not refresh.'));
+        DB::enableQueryLog();
+        DB::flushQueryLog();
+
+        $this->assertSame('Bearer uncached', $this->authorization($authenticator));
+        $this->assertSame('Bearer uncached', $this->authorization($authenticator));
+        $this->assertCount(2, DB::getQueryLog());
+    }
+
+    #[DefineEnvironment('configureCustomAccountModel')]
+    public function testCustomModelTableAndTokenFactorySurviveSharedCaching(): void
+    {
+        Schema::rename('oauth_accounts', 'custom_oauth_accounts');
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'stored']);
+        $this->assertInstanceOf(CustomAccount::class, $account);
+        $authenticator = $account->authenticator(fn (): never => $this->fail('Non-expiring credentials must not refresh.'));
+
+        $this->assertSame('Bearer custom:stored', $this->authorization($authenticator));
+        $this->assertSame('Bearer custom:stored', $this->authorization($authenticator));
+    }
+
+    public function testCapturedConnectionsKeepIdenticalAccountIdsSeparate(): void
+    {
+        DB::usingConnection('oauth-secondary', fn () => (require $this->migration)->up());
+        $first = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'first']);
+        $second = new OAuthAccount;
+        $second->setConnection('oauth-secondary')->forceFill([
+            'id' => $first->getKey(), 'owner_type' => Owner::class, 'owner_id' => 1,
+            'provider' => 'example', 'access_token' => 'second',
+        ])->save();
+        $refresh = fn (): never => $this->fail('Non-expiring tokens must not refresh.');
+        $firstAuthenticator = $first->authenticator($refresh);
+        $secondAuthenticator = $second->authenticator($refresh);
+
+        $this->assertSame('Bearer first', $this->authorization($firstAuthenticator));
+        $this->assertSame('Bearer second', $this->authorization($secondAuthenticator));
+        $this->assertSame('Bearer first', DB::usingConnection('oauth-secondary', fn (): string => $this->authorization($firstAuthenticator)));
+    }
+
+    #[DefineEnvironment('configureGuardedAccountModel')]
+    public function testPersistenceFailureRespectsTheCustomBuilderAndDoesNotRepeatTheProviderCall(): void
+    {
+        $account = $this->refreshableAccount();
+        $calls = 0;
+        $authenticator = $account->authenticator(function () use (&$calls): OAuthAuthenticator {
+            ++$calls;
+
+            return new AccessTokenAuthenticator('renewed');
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('The model builder must control conditional credential writes.');
+        } catch (RuntimeException $exception) {
+            $this->assertSame('Credential writes are denied.', $exception->getMessage());
+        }
+
+        $this->assertSame(1, $calls);
+        $this->assertSame('old', $account->fresh()->access_token);
+        $this->assertNull($account->fresh()->refresh_claim);
+    }
+
+    public function testAnExplicitEmptyScopeSetReplacesStoredScopes(): void
+    {
+        $account = $this->refreshableAccount();
+        $authenticator = $account->authenticator(fn (): OAuthAuthenticator => new AccessTokenAuthenticator('renewed', scopes: []));
+
+        $this->assertSame('Bearer renewed', $this->authorization($authenticator));
+        $this->assertSame([], $account->fresh()->scopes);
+    }
+
+    public function testRollbackDoesNotPublishOrInvalidateUncommittedCredentials(): void
+    {
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'committed']);
+        $accounts = $this->app->make(OAuthAccounts::class);
+        $identity = $accounts->identity($account);
+        $accounts->find($identity);
+
+        DB::beginTransaction();
+        try {
+            $account->update(['access_token' => 'uncommitted']);
+            $this->assertSame('uncommitted', $accounts->find($identity)->access_token);
+        } finally {
+            DB::rollBack();
+        }
+
+        DB::enableQueryLog();
+        DB::flushQueryLog();
+        $this->assertSame('committed', $accounts->find($identity)->access_token);
+        $this->assertSame([], DB::getQueryLog());
+    }
+
+    public function testCommittedSaveInvalidatesItsCapturedKeyAfterTheOuterContextIsRestored(): void
+    {
+        Schema::table('oauth_accounts', fn (Blueprint $table) => $table->string('partition_id')->nullable());
+        $current = 'first';
+        OAuthAccounts::resolvePartitionUsing('partition_id', static function () use (&$current): ?string {
+            return $current;
+        });
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'old']);
+        $accounts = $this->app->make(OAuthAccounts::class);
+        $identity = $accounts->identity($account);
+        $this->assertSame('old', $accounts->find($identity)->access_token);
+
+        DB::transaction(function () use ($account, &$current): void {
+            try {
+                $account->update(['access_token' => 'new']);
+            } finally {
+                $current = null;
+            }
+        });
+
+        $current = 'first';
+        $this->assertSame('new', $accounts->find($identity)->access_token);
+    }
+
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testPartitionMustMatchPersistedAccountBeforeReadingCredentials(bool $warm): void
+    {
+        Schema::table('oauth_accounts', fn (Blueprint $table) => $table->string('partition_id')->nullable());
+        $current = 'first';
+        OAuthAccounts::resolvePartitionUsing('partition_id', static function () use (&$current): ?string {
+            return $current;
+        });
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'secret']);
+        $this->assertSame('first', $account->partition_id);
+        $accounts = $this->app->make(OAuthAccounts::class);
+        $identity = $accounts->identity($account);
+        if ($warm) {
+            $accounts->find($identity);
+        }
+        $current = 'second';
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('another partition');
+        $accounts->find($identity);
+    }
+
+    public function testConcurrentPartitionsRenewAndReuseTheirOwnCredentials(): void
+    {
+        Schema::table('oauth_accounts', fn (Blueprint $table) => $table->string('partition_id')->nullable());
+        OAuthAccounts::resolvePartitionUsing('partition_id', static fn (): ?string => Context::get('oauth_partition'));
+        $authenticators = [];
+
+        foreach (['first', 'second'] as $partition) {
+            Context::add('oauth_partition', $partition);
+            $account = Owner::create()->oauthAccounts()->create([
+                'provider' => 'example',
+                'access_token' => 'old-' . $partition,
+                'refresh_token' => 'refresh-' . $partition,
+                'expires_at' => Date::now()->subSecond(),
+            ]);
+            $authenticators[$partition] = $account->authenticator(function (OAuthAuthenticator $current) use ($partition): OAuthAuthenticator {
+                $this->assertSame('refresh-' . $partition, $current->getRefreshToken());
+                usleep(5000);
+                $this->assertSame($partition, Context::get('oauth_partition'));
+
+                return new AccessTokenAuthenticator('renewed-' . $partition);
+            });
+        }
+
+        DB::releaseIdleConnections();
+        $calls = [];
+        foreach ($authenticators as $partition => $authenticator) {
+            $calls[] = function () use ($partition, $authenticator): array {
+                Context::add('oauth_partition', $partition);
+
+                return [$this->authorization($authenticator), $this->authorization($authenticator)];
+            };
+        }
+
+        $this->assertSame([
+            ['Bearer renewed-first', 'Bearer renewed-first'],
+            ['Bearer renewed-second', 'Bearer renewed-second'],
+        ], parallel($calls));
+        $this->assertSame('second', Context::get('oauth_partition'));
+    }
+
+    public function testCreationRejectsAConflictingPartition(): void
+    {
+        OAuthAccounts::resolvePartitionUsing('partition_id', static fn (): string => 'first');
+        $account = new OAuthAccount;
+        $account->forceFill(['provider' => 'example', 'access_token' => 'secret', 'partition_id' => 'second']);
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('another partition');
+        $account->save();
+    }
+
+    public function testMissingPartitionContextRejectsCreation(): void
+    {
+        OAuthAccounts::resolvePartitionUsing('partition_id', static fn (): null => null);
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('partition is not available');
+        Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'secret']);
+    }
+
+    public function testConcurrentRenewalPersistsBeforeUseAndReleasesTheOnlyDatabaseSlot(): void
+    {
+        $account = $this->refreshableAccount();
+        $calls = 0;
+        $pool = $this->app->make(PoolManager::class)->pool('oauth');
+        $refresh = function (OAuthAuthenticator $current) use (&$calls, $pool): OAuthAuthenticator {
+            ++$calls;
+            $this->assertSame(1, $pool->getIdleCount());
+            $this->assertSame('refresh', $current->getRefreshToken());
+            usleep(5000);
+
+            return new AccessTokenAuthenticator('renewed', expiresAt: Date::now()->addHour()->toDateTimeImmutable());
+        };
+        $first = $account->authenticator($refresh);
+        $second = $account->authenticator($refresh);
+        DB::releaseIdleConnections();
+
+        $this->assertSame(['Bearer renewed', 'Bearer renewed'], parallel([
+            fn (): string => $this->authorization($first),
+            fn (): string => $this->authorization($second),
+        ]));
+        $this->assertSame(1, $calls);
+        $persisted = $account->fresh();
+        $this->assertSame('renewed', $persisted->access_token);
+        $this->assertSame('refresh', $persisted->refresh_token);
+        $this->assertSame(['read'], $persisted->scopes);
+        $this->assertNull($persisted->refresh_claim);
+        $this->assertNotSame($account->credential_revision, $persisted->credential_revision);
+    }
+
+    public function testRenewalRejectsCallerTransactionsWithoutReleasingThem(): void
+    {
+        $account = $this->refreshableAccount();
+        $authenticator = $account->authenticator(fn (): never => $this->fail('A caller transaction must prevent provider I/O.'));
+        DB::beginTransaction();
+
+        try {
+            $this->expectException(LogicException::class);
+            $this->expectExceptionMessage('inside a database transaction');
+            $this->authorization($authenticator);
+        } finally {
+            $this->assertSame(1, DB::transactionLevel());
+            $this->assertSame(0, $this->app->make(PoolManager::class)->pool('oauth')->getIdleCount());
+            DB::rollBack();
+        }
+    }
+
+    #[DataProvider('providerFailures')]
+    public function testOnlyTransientProviderFailuresRetry(int $status, string $error, ?string $retryAfter, int $attempts): void
+    {
+        Sleep::fake();
+        $account = $this->refreshableAccount();
+        $failure = new RequestException(new Response(new PsrResponse(
+            $status,
+            $retryAfter === null ? [] : ['Retry-After' => $retryAfter],
+            json_encode(['error' => $error]),
+        )));
+        $calls = 0;
+        $pool = $this->app->make(PoolManager::class)->pool('oauth');
+        $idleWhileWaiting = [];
+        Sleep::whenFakingSleep(static function () use ($pool, &$idleWhileWaiting): void {
+            $idleWhileWaiting[] = $pool->getIdleCount();
+        });
+        $authenticator = $account->authenticator(function () use ($failure, &$calls): never {
+            ++$calls;
+            throw $failure;
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('The provider failure must remain available to the caller.');
+        } catch (RequestException $exception) {
+            $this->assertSame($failure, $exception);
+        }
+
+        $this->assertSame($attempts, $calls);
+        $this->assertSame(array_fill(0, $attempts - 1, 1), $idleWhileWaiting);
+        $this->assertNull($account->fresh()->refresh_claim);
+        $this->assertSame('refresh', $account->fresh()->refresh_token);
+    }
+
+    /**
+     * Provide transient and terminal provider failures.
+     */
+    public static function providerFailures(): array
+    {
+        return [
+            'temporary OAuth failure' => [400, 'temporarily_unavailable', null, 3],
+            'server failure' => [503, '', null, 3],
+            'revoked grant wins over server status' => [503, 'invalid_grant', null, 1],
+            'bad client' => [401, 'invalid_client', null, 1],
+            'provider asks for longer delay' => [429, 'temporarily_unavailable', '30', 1],
+        ];
+    }
+
+    public function testLateProviderSuccessCannotOverwriteAReconnect(): void
+    {
+        $account = $this->refreshableAccount();
+        $authenticator = $account->authenticator(function () use ($account): OAuthAuthenticator {
+            $account->fresh()->update(['access_token' => 'reconnected', 'refresh_token' => 'new-grant', 'expires_at' => null]);
+
+            return new AccessTokenAuthenticator('loser', 'loser-refresh', Date::now()->addHour()->toDateTimeImmutable());
+        });
+
+        $this->assertSame('Bearer reconnected', $this->authorization($authenticator));
+        $this->assertSame('new-grant', $account->fresh()->refresh_token);
+    }
+
+    public function testFreshClaimPreventsUseUntilAbandonedEvenWhenAccessTokenIsValid(): void
+    {
+        $account = $this->refreshableAccount();
+        $account->forceFill(['refresh_claim' => '0198f162-15b5-7000-8000-000000000001', 'refresh_started_at' => Date::now()])->save();
+        $calls = 0;
+        $authenticator = $account->authenticator(function () use (&$calls): OAuthAuthenticator {
+            ++$calls;
+
+            return new AccessTokenAuthenticator('recovered');
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('A fresh durable claim must block renewal and use of the old token.');
+        } catch (RuntimeException $exception) {
+            $this->assertSame('The OAuth account is already being refreshed. Try again later.', $exception->getMessage());
+        }
+
+        $this->assertSame(0, $calls);
+        Date::setTestNow('2026-01-01 00:05:05');
+        $this->assertSame('Bearer recovered', $this->authorization($authenticator));
+        $this->assertSame(1, $calls);
+    }
+
+    public function testInvalidGrantFromAnOldAttemptDoesNotRejectReconnectedCredentials(): void
+    {
+        $account = $this->refreshableAccount();
+        $failure = new RequestException(new Response(new PsrResponse(400, [], '{"error":"invalid_grant"}')));
+        $authenticator = $account->authenticator(function () use ($account, $failure): never {
+            $account->fresh()->update(['access_token' => 'reconnected', 'refresh_token' => 'replacement', 'expires_at' => null]);
+            throw $failure;
+        });
+
+        $this->assertSame('Bearer reconnected', $this->authorization($authenticator));
+        $this->assertSame('replacement', $account->fresh()->refresh_token);
+    }
+
+    public function testLateSuccessCannotOverwriteAReplacedClaimWithTheSameRevision(): void
+    {
+        $account = $this->refreshableAccount();
+        $successor = '0198f162-15b5-7000-8000-000000000002';
+        $authenticator = $account->authenticator(function () use ($account, $successor): OAuthAuthenticator {
+            // Another worker reclaimed the same credential revision after the old lease expired.
+            $account->newQuery()->whereKey($account->getKey())->update([
+                'refresh_claim' => $successor,
+                'refresh_started_at' => Date::now(),
+            ]);
+
+            return new AccessTokenAuthenticator('late-token');
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('A replaced claim must prevent the late provider result from being used.');
+        } catch (RuntimeException $exception) {
+            $this->assertSame('The OAuth account changed during renewal. Try again with the current credentials.', $exception->getMessage());
+        }
+
+        $this->assertSame('old', $account->fresh()->access_token);
+        $this->assertSame($successor, $account->fresh()->refresh_claim);
+    }
+
+    public function testExpiredProviderResultIsNotStoredOrRetried(): void
+    {
+        $account = $this->refreshableAccount();
+        $calls = 0;
+        $authenticator = $account->authenticator(function () use (&$calls): OAuthAuthenticator {
+            ++$calls;
+
+            return new AccessTokenAuthenticator('expired', expiresAt: Date::now()->toDateTimeImmutable());
+        });
+        $this->expectException(UnexpectedValueException::class);
+
+        try {
+            $this->authorization($authenticator);
+        } finally {
+            $this->assertSame(1, $calls);
+            $this->assertSame('old', $account->fresh()->access_token);
+            $this->assertNull($account->fresh()->refresh_claim);
+        }
+    }
+
+    public function testUnrefreshableTokenWorksUntilItsActualExpiry(): void
+    {
+        $account = $this->refreshableAccount();
+        $account->update(['refresh_token' => null]);
+        $authenticator = $account->authenticator(fn (): never => $this->fail('A missing refresh token must not call the provider.'));
+
+        $this->assertSame('Bearer old', $this->authorization($authenticator));
+        Date::setTestNow('2026-01-01 00:00:10');
+        $this->expectException(OAuthAccountReconnectRequiredException::class);
+        $this->expectExceptionMessage('Reconnect the account');
+        $this->authorization($authenticator);
+    }
+
+    public function testCanceledOwnerCleansItsClaimAndWaiterCanRenew(): void
+    {
+        $account = $this->refreshableAccount();
+        $entered = new Channel(1);
+        $release = new Channel(1);
+        $results = new Channel(2);
+        $calls = 0;
+        $authenticator = $account->authenticator(function () use ($entered, $release, &$calls): OAuthAuthenticator {
+            if (++$calls === 1) {
+                $entered->push(true);
+                $release->pop(2);
+                if ($release->isCanceled()) {
+                    throw new CanceledException('Provider canceled.');
+                }
+            }
+
+            return new AccessTokenAuthenticator('renewed');
+        });
+        $call = function () use ($results, $authenticator): void {
+            try {
+                $results->push($this->authorization($authenticator));
+            } catch (Throwable $exception) {
+                $results->push($exception);
+            }
+        };
+        DB::releaseIdleConnections();
+        $owner = go($call);
+
+        try {
+            $this->assertTrue($entered->pop(2));
+            $waiter = go($call);
+            usleep(1000);
+            $this->assertTrue(EngineCoroutine::cancelById($owner));
+            $this->assertInstanceOf(CanceledException::class, $results->pop(2));
+            $this->assertSame('Bearer renewed', $results->pop(2));
+            $this->assertSame(2, $calls);
+            $this->assertNull($account->fresh()->refresh_claim);
+        } finally {
+            $release->close();
+            EngineCoroutine::join([$owner, ...isset($waiter) ? [$waiter] : []], 2);
+            $entered->close();
+            $results->close();
+        }
+    }
+
+    #[DefineEnvironment('configureCleanupFailingAccountModel')]
+    public function testCleanupAndReportingFailuresDoNotReplaceCancellation(): void
+    {
+        $account = $this->refreshableAccount();
+        $reported = null;
+        $this->app->make(ExceptionHandler::class)->reportable(static function (RuntimeException $failure) use (&$reported): never {
+            $reported = $failure;
+            throw new RuntimeException('Logging unavailable.');
+        });
+        $cancellation = new CanceledException('Provider canceled.');
+        $authenticator = $account->authenticator(static fn (): never => throw $cancellation);
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('The original cancellation must reach the caller.');
+        } catch (CanceledException $exception) {
+            $this->assertSame($cancellation, $exception);
+        }
+
+        $this->assertSame('Claim cleanup failed.', $reported?->getMessage());
+        $this->assertNotNull($account->fresh()->refresh_claim);
+    }
+
+    public function testConnectorConvenienceDisablesNestedRetriesAfterTheCallerModifier(): void
+    {
+        Sleep::fake();
+        $account = $this->refreshableAccount();
+        $mock = Saloon::fake([
+            MockResponse::make(['error' => 'temporarily_unavailable'], 503),
+            MockResponse::make(['error' => 'temporarily_unavailable'], 503),
+            MockResponse::make(['access_token' => 'renewed', 'scope' => 'write']),
+        ]);
+        $modifier = new class {
+            /**
+             * Customize a refresh request through an array callable.
+             */
+            public function modify(Request $request): void
+            {
+                $request->retry(10)->withHeader('X-Refresh', 'custom');
+            }
+        };
+        $authenticator = (new OAuth2Connector)->accountAuthenticator(
+            $account,
+            [$modifier, 'modify'],
+        );
+
+        $this->assertSame('Bearer renewed', $this->authorization($authenticator));
+        $mock->assertSentCount(3);
+        $this->assertSame('custom', $mock->lastPendingRequest()->headers()['X-Refresh']);
+        $this->assertSame(1, $mock->lastPendingRequest()->request()->retryPolicy()->times);
+        $this->assertSame(['write'], $account->fresh()->scopes);
+    }
+
+    public function testStreamedInvalidGrantOverridesServerStatusAndRetainsItsResponse(): void
+    {
+        Sleep::fake();
+        $account = $this->refreshableAccount();
+        $mock = Saloon::fake([new UnseekableBodyMockResponse(['error' => 'invalid_grant'], 503)]);
+
+        try {
+            $this->authorization((new OAuth2Connector)->accountAuthenticator($account));
+            $this->fail('A rejected grant must be returned to the caller.');
+        } catch (RequestException $exception) {
+            $this->assertSame(['error' => 'invalid_grant'], $exception->response->json());
+            $this->assertSame('{"error":"invalid_grant"}', $exception->response->body());
+            $this->assertSame('{"error":"invalid_grant"}', (string) $exception->response->toPsrResponse()->getBody());
+        }
+
+        $mock->assertSentCount(1);
+        Sleep::assertNeverSlept();
+        $this->assertNull($account->fresh()->refresh_claim);
+    }
+
+    public function testGuzzleResponseTransferFailuresRetryWithoutReadingTheIncompleteBody(): void
+    {
+        Sleep::fake();
+        $account = $this->refreshableAccount();
+        $reads = 0;
+        $calls = 0;
+        $body = new PumpStream(static function () use (&$reads): false {
+            ++$reads;
+
+            return false;
+        });
+        $failure = new ResponseTransferException('Transfer failed.', new PsrRequest('POST', 'https://example.test/token'), new PsrResponse(200, [], $body));
+        $authenticator = $account->authenticator(function () use ($failure, &$calls): never {
+            ++$calls;
+            throw $failure;
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('The transfer failure must be returned to the caller.');
+        } catch (ResponseTransferException $exception) {
+            $this->assertSame($failure, $exception);
+        }
+
+        $this->assertSame(3, $calls);
+        $this->assertSame(0, $reads);
+        $this->assertNull($account->fresh()->refresh_claim);
+    }
+
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testPartitionIsRecheckedAfterProviderYieldBeforeWritingOrUsingCredentials(bool $cancel): void
+    {
+        Schema::table('oauth_accounts', fn (Blueprint $table) => $table->string('partition_id')->nullable());
+        $current = 'first';
+        OAuthAccounts::resolvePartitionUsing('partition_id', static function () use (&$current): string {
+            return $current;
+        });
+        $account = $this->refreshableAccount();
+        $authenticator = $account->authenticator(function () use (&$current, $cancel): OAuthAuthenticator {
+            usleep(1000);
+            $current = 'second';
+
+            if ($cancel) {
+                throw new CanceledException('Provider canceled.');
+            }
+
+            return new AccessTokenAuthenticator('wrong-context');
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('Context changes must prevent credential writes and use.');
+        } catch (LogicException|CanceledException $exception) {
+            $this->assertSame($cancel ? 'Provider canceled.' : 'The OAuth account belongs to another partition.', $exception->getMessage());
+        } finally {
+            $current = 'first';
+        }
+
+        $this->assertSame('old', $account->fresh()->access_token);
+        $this->assertNull($account->fresh()->refresh_claim);
+    }
+
+    /**
+     * Create an account due for renewal but whose old token has not yet expired.
+     */
+    protected function refreshableAccount(): OAuthAccount
+    {
+        $account = Owner::create()->oauthAccounts()->create([
+            'provider' => 'example',
+            'access_token' => 'old',
+            'refresh_token' => 'refresh',
+            'expires_at' => Date::now()->addSeconds(10),
+            'scopes' => ['read'],
+        ]);
+        Date::setTestNow('2026-01-01 00:00:05');
+
+        return $account;
+    }
+
+    /**
+     * Apply account authentication to a real pending request.
+     */
+    protected function authorization(OAuthAccountAuthenticator $authenticator): string
+    {
+        return (new TestConnector)->createPendingRequest(UserRequest::make()->authenticate($authenticator))->headers()['Authorization'];
+    }
+}
+
+class Owner extends Model
+{
+    use HasOAuthAccounts;
+
+    public bool $timestamps = false;
+
+    protected array $guarded = [];
+}
+
+class CustomAccount extends OAuthAccount
+{
+    protected ?string $table = 'custom_oauth_accounts';
+
+    /**
+     * Apply custom authentication to the stored credentials.
+     */
+    public function newOAuthAuthenticator(): OAuthAuthenticator
+    {
+        return new AccessTokenAuthenticator('custom:' . $this->access_token, $this->refresh_token, $this->expires_at, $this->scopes);
+    }
+}
+
+class GuardedAccount extends OAuthAccount
+{
+    /**
+     * Create the account's guarded query builder.
+     */
+    public function newEloquentBuilder(QueryBuilder $query): Builder
+    {
+        return new GuardedAccountBuilder($query);
+    }
+}
+
+class GuardedAccountBuilder extends Builder
+{
+    /**
+     * Reject credential writes while allowing claim coordination.
+     */
+    public function update(array $values): int
+    {
+        if (array_key_exists('access_token', $values)) {
+            throw new RuntimeException('Credential writes are denied.');
+        }
+
+        return parent::update($values);
+    }
+}
+
+class CleanupFailingAccount extends OAuthAccount
+{
+    /**
+     * Create a builder that rejects claim cleanup.
+     */
+    public function newEloquentBuilder(QueryBuilder $query): Builder
+    {
+        return new CleanupFailingAccountBuilder($query);
+    }
+}
+
+class CleanupFailingAccountBuilder extends Builder
+{
+    /**
+     * Allow claiming, then fail the cleanup write.
+     */
+    public function update(array $values): int
+    {
+        if (array_key_exists('refresh_claim', $values) && $values['refresh_claim'] === null) {
+            throw new RuntimeException('Claim cleanup failed.');
+        }
+
+        return parent::update($values);
+    }
+}
diff --git a/tests/Saloon/SaloonServiceProviderTest.php b/tests/Saloon/SaloonServiceProviderTest.php
index c942175f2..0cb425e06 100644
--- a/tests/Saloon/SaloonServiceProviderTest.php
+++ b/tests/Saloon/SaloonServiceProviderTest.php
@@ -8,6 +8,7 @@
 use Hypervel\Contracts\Foundation\Application as ApplicationContract;
 use Hypervel\Http\Client\Factory;
 use Hypervel\Saloon\Facades\Saloon;
+use Hypervel\Saloon\OAuthAccounts;
 use Hypervel\Saloon\SaloonManager;
 use Hypervel\Saloon\SaloonServiceProvider;
 use Hypervel\Support\ServiceProvider;
@@ -38,6 +39,8 @@ public function testProviderMergesConfigurationAndRegistersTheNamedConnection():
             'timeout' => 30,
             'transport_sharing' => TransportSharing::HANDLER_PREFER,
         ], $this->app->make(Factory::class)->getConnectionConfig('saloon'));
+        $this->assertSame(OAuthAccounts::DEFAULT_CACHE_TTL, config('saloon.oauth_accounts.cache.ttl'));
+        $this->assertSame(OAuthAccounts::DEFAULT_CACHE_PREFIX, config('saloon.oauth_accounts.cache.prefix'));
     }
 
     public function testOmittedFixtureSettingsUsePackageDefaults(): void
diff --git a/tests/Saloon/SensitiveParameterTest.php b/tests/Saloon/SensitiveParameterTest.php
index 4b45f9c42..83c3316e0 100644
--- a/tests/Saloon/SensitiveParameterTest.php
+++ b/tests/Saloon/SensitiveParameterTest.php
@@ -4,6 +4,7 @@
 
 namespace Hypervel\Tests\Saloon;
 
+use Hypervel\Saloon\Http\Auth\CachedTokenAuthenticator;
 use Hypervel\Saloon\Http\Auth\CookieAuthenticator;
 use Hypervel\Saloon\Traits\OAuth2\AuthorizationCodeGrant;
 use Hypervel\Saloon\Traits\OAuth2\ClientCredentialsGrant;
@@ -42,6 +43,7 @@ public function testSecretParametersAreSensitive(
     public static function sensitiveParameters(): array
     {
         return [
+            [CachedTokenAuthenticator::class, '__construct', 'key'],
             [CookieAuthenticator::class, '__construct', 'value'],
             [ParsesOAuthTokenResponses::class, 'parseOAuthTokenResponse', 'response'],
             [AuthorizationCodeGrant::class, 'createOAuthAuthenticatorFromResponse', 'response'],
diff --git a/tests/Saloon/Unit/Oauth2/CachedTokenAuthenticatorTest.php b/tests/Saloon/Unit/Oauth2/CachedTokenAuthenticatorTest.php
new file mode 100644
index 000000000..85f78b0a9
--- /dev/null
+++ b/tests/Saloon/Unit/Oauth2/CachedTokenAuthenticatorTest.php
@@ -0,0 +1,260 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Saloon\Unit\Oauth2;
+
+use Hypervel\Contracts\Foundation\Application as ApplicationContract;
+use Hypervel\Database\Pool\PoolManager;
+use Hypervel\Engine\Channel;
+use Hypervel\Engine\Coroutine as EngineCoroutine;
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Facades\Saloon;
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\CachedTokenAuthenticator;
+use Hypervel\Saloon\Http\Faking\MockResponse;
+use Hypervel\Saloon\Http\Request;
+use Hypervel\Saloon\SaloonServiceProvider;
+use Hypervel\Support\Facades\Date;
+use Hypervel\Support\Facades\DB;
+use Hypervel\Testbench\TestCase;
+use Hypervel\Tests\Saloon\Fixtures\Connectors\ClientCredentialsConnector;
+use Hypervel\Tests\Saloon\Fixtures\Connectors\TestConnector;
+use Hypervel\Tests\Saloon\Fixtures\Requests\UserRequest;
+use RuntimeException;
+use Throwable;
+use UnexpectedValueException;
+
+use function Hypervel\Coroutine\go;
+use function Hypervel\Coroutine\parallel;
+
+class CachedTokenAuthenticatorTest extends TestCase
+{
+    /**
+     * Register Saloon for the acquisition tests.
+     */
+    protected function getPackageProviders(ApplicationContract $app): array
+    {
+        return [SaloonServiceProvider::class];
+    }
+
+    /**
+     * Configure serialized token caching and a single-slot database pool.
+     */
+    protected function defineEnvironment(ApplicationContract $app): void
+    {
+        $app->make('config')->set('cache.serializable_classes', [CacheableCustomToken::class]);
+        $app->make('config')->set('cache.stores.oauth-file', [
+            'driver' => 'file',
+            'path' => $app->storagePath('framework/cache/oauth-tokens'),
+        ]);
+        $app->make('config')->set('database.connections.oauth-pool', [
+            'driver' => 'sqlite',
+            'database' => ':memory:',
+            'pool' => ['testing_enabled' => true, 'max_connections' => 1, 'wait_timeout' => 1.0],
+        ]);
+    }
+
+    /**
+     * Clear cached test credentials.
+     */
+    protected function tearDown(): void
+    {
+        try {
+            $this->app->make('cache')->store('oauth-file')->flush();
+        } finally {
+            parent::tearDown();
+        }
+    }
+
+    public function testSerializedTokensRetainExpiryAndCustomAuthentication(): void
+    {
+        Date::setTestNow('2026-01-01 00:00:00');
+        $first = new CachedTokenAuthenticator('serialized', fn (): OAuthAuthenticator => new CacheableCustomToken(
+            'access',
+            expiresAt: Date::now()->addHour()->toDateTimeImmutable(),
+        ), 'oauth-file');
+        $this->assertSame('Bearer custom:access', $this->authorization($first));
+
+        $second = new CachedTokenAuthenticator('serialized', fn (): never => $this->fail('The stored token must be reused.'), 'oauth-file');
+        $this->assertSame('Bearer custom:access', $this->authorization($second));
+    }
+
+    public function testSeparateInstancesShareAnAcquisitionAndCompletedToken(): void
+    {
+        $calls = 0;
+        $resolve = function () use (&$calls): OAuthAuthenticator {
+            ++$calls;
+            usleep(5000);
+
+            return new AccessTokenAuthenticator('shared');
+        };
+        $first = new CachedTokenAuthenticator('grant', $resolve, 'worker-array');
+        $second = new CachedTokenAuthenticator('grant', $resolve, 'worker-array');
+
+        $results = parallel([
+            fn (): string => $this->authorization($first),
+            fn (): string => $this->authorization($second),
+        ]);
+
+        $this->assertSame(['Bearer shared', 'Bearer shared'], $results);
+        $this->assertSame('Bearer shared', $this->authorization(new CachedTokenAuthenticator('grant', $resolve, 'worker-array')));
+        $this->assertSame(1, $calls);
+    }
+
+    public function testFailureIsSharedWithWaitersButNotRetainedForLaterCalls(): void
+    {
+        $calls = 0;
+        $failure = new RuntimeException('Provider unavailable.');
+        $resolve = function () use (&$calls, $failure): OAuthAuthenticator {
+            ++$calls;
+            usleep(5000);
+            throw $failure;
+        };
+        $attempt = function () use ($resolve): RuntimeException {
+            try {
+                $this->authorization(new CachedTokenAuthenticator('failed', $resolve, 'worker-array'));
+            } catch (RuntimeException $exception) {
+                return $exception;
+            }
+
+            $this->fail('The provider failure was not propagated.');
+        };
+
+        $this->assertSame([$failure, $failure], parallel([$attempt, $attempt]));
+        $this->assertSame(1, $calls);
+        $this->assertSame($failure, $attempt());
+        $this->assertSame(2, $calls);
+    }
+
+    public function testAcquisitionAndItsWaitersReleaseIdleDatabaseConnections(): void
+    {
+        $pool = $this->app->make(PoolManager::class)->pool('oauth-pool');
+        $release = new Channel(1);
+        $results = new Channel(2);
+        $enteredProvider = new Channel(1);
+        $enteredWaiter = new Channel(1);
+        $idleAtProvider = null;
+        $resolve = function () use ($pool, $release, $enteredProvider, &$idleAtProvider): OAuthAuthenticator {
+            $idleAtProvider = $pool->getIdleCount();
+            $enteredProvider->push(true);
+            $release->pop(2);
+
+            return new AccessTokenAuthenticator('shared');
+        };
+        $call = function (bool $waiter = false) use ($resolve, $results, $enteredWaiter): void {
+            try {
+                DB::connection('oauth-pool')->selectOne('select 1');
+                if ($waiter) {
+                    $enteredWaiter->push(true);
+                }
+                $results->push($this->authorization(new CachedTokenAuthenticator('pool-test', $resolve, 'worker-array')));
+            } catch (Throwable $exception) {
+                $results->push($exception);
+            }
+        };
+        $owner = go($call);
+
+        try {
+            $this->assertTrue($enteredProvider->pop(2));
+            $waiter = go(fn () => $call(true));
+            $this->assertTrue($enteredWaiter->pop(2));
+            $this->assertSame(1, $idleAtProvider);
+            $this->assertTrue($results->isEmpty());
+            $this->assertSame(7, DB::connection('oauth-pool')->selectOne('select 7 as value')->value);
+            $release->push(true);
+            $this->assertSame('Bearer shared', $results->pop(2));
+            $this->assertSame('Bearer shared', $results->pop(2));
+        } finally {
+            $release->close();
+            EngineCoroutine::join([$owner, ...isset($waiter) ? [$waiter] : []], 2);
+            $results->close();
+            $enteredProvider->close();
+            $enteredWaiter->close();
+        }
+    }
+
+    public function testShortTokenLifetimeUsesOneFixedDeadlineAndForgetClearsBothLevels(): void
+    {
+        Date::setTestNow('2026-01-01 00:00:00');
+        $calls = 0;
+        $resolve = function () use (&$calls): OAuthAuthenticator {
+            return new AccessTokenAuthenticator('token-' . ++$calls, expiresAt: Date::now()->addSeconds(10)->toDateTimeImmutable());
+        };
+        $first = new CachedTokenAuthenticator('short', $resolve, 'worker-array');
+        $this->assertSame('Bearer token-1', $this->authorization($first));
+
+        Date::setTestNow('2026-01-01 00:00:04');
+        $second = new CachedTokenAuthenticator('short', $resolve, 'worker-array');
+        $this->assertSame('Bearer token-1', $this->authorization($second));
+
+        Date::setTestNow('2026-01-01 00:00:05');
+        $this->assertSame('Bearer token-2', $this->authorization($second));
+        $this->assertSame('Bearer token-2', $this->authorization($first));
+        $first->forget();
+        $this->assertSame('Bearer token-3', $this->authorization($first));
+        $this->assertSame('Bearer token-2', $this->authorization($second));
+    }
+
+    public function testAnExpiredAcquisitionIsRejectedWithoutRefetching(): void
+    {
+        Date::setTestNow('2026-01-01 00:00:00');
+        $calls = 0;
+        $authenticator = new CachedTokenAuthenticator('expired', function () use (&$calls): OAuthAuthenticator {
+            ++$calls;
+
+            return new AccessTokenAuthenticator('expired', expiresAt: Date::now()->toDateTimeImmutable());
+        });
+
+        $this->expectException(UnexpectedValueException::class);
+
+        try {
+            $this->authorization($authenticator);
+        } finally {
+            $this->assertSame(1, $calls);
+        }
+    }
+
+    public function testConvenienceSeparatesGrantsAndKeepsRequestModifiers(): void
+    {
+        $mock = Saloon::fake([
+            MockResponse::make(['access_token' => 'first', 'expires_in' => 3600]),
+            MockResponse::make(['access_token' => 'secret']),
+            MockResponse::make(['access_token' => 'scope']),
+            MockResponse::make(['access_token' => 'endpoint']),
+            MockResponse::make(['access_token' => 'audience']),
+        ]);
+        $connector = new ClientCredentialsConnector;
+        $this->assertSame('Bearer first', $this->authorization($connector->cachedAccessToken(store: 'oauth-file')));
+        $this->assertSame('Bearer first', $this->authorization($connector->cachedAccessToken(store: 'oauth-file')));
+        $this->assertSame('Bearer secret', $this->authorization((new ClientCredentialsConnector(['clientSecret' => 'other']))->cachedAccessToken(store: 'oauth-file')));
+        $this->assertSame('Bearer scope', $this->authorization($connector->cachedAccessToken(scopes: ['read'], store: 'oauth-file')));
+        $this->assertSame('Bearer endpoint', $this->authorization((new ClientCredentialsConnector(['tokenEndpoint' => '/other']))->cachedAccessToken(store: 'oauth-file')));
+        $this->assertSame('Bearer audience', $this->authorization($connector->cachedAccessToken(
+            store: 'oauth-file',
+            requestModifier: fn (Request $request) => $request->withData(['audience' => 'billing']),
+            key: 'billing',
+        )));
+        $this->assertSame('billing', $mock->lastPendingRequest()->body()['audience']);
+        $mock->assertSentCount(5);
+    }
+
+    /**
+     * Read the authentication applied to a real pending request.
+     */
+    protected function authorization(CachedTokenAuthenticator $authenticator): string
+    {
+        return (new TestConnector)->createPendingRequest(UserRequest::make()->authenticate($authenticator))->headers()['Authorization'];
+    }
+}
+
+class CacheableCustomToken extends AccessTokenAuthenticator
+{
+    /**
+     * Apply the custom token spelling through the inherited authentication method.
+     */
+    public function getAccessToken(): string
+    {
+        return 'custom:' . $this->accessToken;
+    }
+}
diff --git a/tests/Saloon/Unit/Oauth2/TokenAcquisitionTest.php b/tests/Saloon/Unit/Oauth2/TokenAcquisitionTest.php
new file mode 100644
index 000000000..004e763c8
--- /dev/null
+++ b/tests/Saloon/Unit/Oauth2/TokenAcquisitionTest.php
@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Saloon\Unit\Oauth2;
+
+use Hypervel\Engine\Channel;
+use Hypervel\Engine\Coroutine as EngineCoroutine;
+use Hypervel\Saloon\Http\Auth\TokenAcquisition;
+use Hypervel\Tests\TestCase;
+use Swoole\Coroutine\CanceledException;
+
+use function Hypervel\Coroutine\go;
+
+class TokenAcquisitionTest extends TestCase
+{
+    public function testCancelingAWaiterDoesNotReleaseTheOwnersAcquisition(): void
+    {
+        $acquisition = new TokenAcquisition;
+        $release = new Channel(1);
+        $results = new Channel(3);
+        $owner = go(fn () => $results->push($acquisition->run('grant', function () use ($release): string {
+            $release->pop(1);
+
+            return 'owner';
+        })));
+        $waiter = go(function () use ($acquisition, $results): void {
+            try {
+                $results->push($acquisition->run('grant', fn (): string => 'wrong waiter'));
+            } catch (CanceledException $exception) {
+                $results->push($exception);
+            }
+        });
+
+        try {
+            $this->assertTrue(EngineCoroutine::cancelById($waiter));
+            $this->assertInstanceOf(CanceledException::class, $results->pop(1));
+            $other = go(fn () => $results->push($acquisition->run('grant', fn (): string => 'wrong successor')));
+            $this->assertTrue($results->isEmpty());
+            $release->push(true);
+            $this->assertSame('owner', $results->pop(1));
+            $this->assertSame('owner', $results->pop(1));
+        } finally {
+            $release->close();
+            EngineCoroutine::join([$owner, $waiter, ...isset($other) ? [$other] : []], 1);
+            $results->close();
+        }
+    }
+
+    public function testCanceledOwnerLeavesOneSuccessorAndDoesNotCancelWaiters(): void
+    {
+        $acquisition = new TokenAcquisition;
+        $release = new Channel(1);
+        $results = new Channel(3);
+        $owner = go(function () use ($acquisition, $release, $results): void {
+            try {
+                $acquisition->run('grant', function () use ($release): void {
+                    $release->pop(1);
+
+                    if ($release->isCanceled()) {
+                        throw new CanceledException('Owner canceled.');
+                    }
+                });
+            } catch (CanceledException $exception) {
+                $results->push($exception);
+            }
+        });
+        $calls = 0;
+        $resolve = function () use (&$calls): string {
+            ++$calls;
+            usleep(5000);
+
+            return 'replacement';
+        };
+        $first = go(fn () => $results->push($acquisition->run('grant', $resolve)));
+        $second = go(fn () => $results->push($acquisition->run('grant', $resolve)));
+
+        try {
+            $this->assertTrue(EngineCoroutine::cancelById($owner));
+            $this->assertInstanceOf(CanceledException::class, $results->pop(1));
+            $this->assertSame('replacement', $results->pop(1));
+            $this->assertSame('replacement', $results->pop(1));
+            $this->assertSame(1, $calls);
+        } finally {
+            $release->close();
+            EngineCoroutine::join([$owner, $first, $second], 1);
+            $results->close();
+        }
+    }
+}

From 3b9773a9b2f9a58c62ffe364bf2249b4a6fe5362 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 19:20:00 +0000
Subject: [PATCH 5/8] Document Saloon token caching and connected OAuth
 accounts

Replace token acquisition on every request with examples for cached client credentials and custom username/password token endpoints. Explain grant identity, store selection, fixed renewal deadlines, custom authenticator serialization and the limits of explicit invalidation.

Document opt-in account persistence, encrypted credentials, custom models, Socialite adapters, cache invalidation, partition context and coordinated renewal. Describe reconnect-required errors, bounded retries, transaction restrictions, cancellation and ambiguous remote refresh outcomes.

Record the scope metadata contract and factory signature change in the porting guide and package README. Mark the implementation plan verified and ready for a framework PR, retaining the separate integration boundary.
---
 ...0-24-1738-saloon-oauth-token-management.md |   6 +-
 src/docs/porting-from-laravel.md              |   2 +
 src/docs/saloon.md                            | 220 ++++++++++++++++--
 src/saloon/README.md                          |   2 +-
 4 files changed, 204 insertions(+), 26 deletions(-)

diff --git a/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md b/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
index d3b9e605d..5f2982079 100644
--- a/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
+++ b/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
@@ -9,7 +9,7 @@ Add two opt-in capabilities to `hypervel/saloon`:
 
 Keep manual grant methods, immutable connectors, existing authenticators, request modifiers and application-owned provider credentials. Applications choose their cache stores and publish the account migration only when using durable accounts. No new package, store-driver abstraction, provider registry, scheduler or UI is needed.
 
-Status: ready for implementation; implementation has not started. Implement in the `components-saloon` worktree. The only approved existing API departure is scope metadata on `OAuthAuthenticator`, `AccessTokenAuthenticator` and the corresponding grant factories. No Socialite API change is required.
+Status: implemented, verified and reviewed; ready for a framework PR. The only approved existing API departure is scope metadata on `OAuthAuthenticator`, `AccessTokenAuthenticator` and the corresponding grant factories. No Socialite API change is required.
 
 ## Existing boundaries and evidence
 
@@ -173,7 +173,7 @@ Renewal uses a short cache lock for waiting and a committed row claim for coordi
 When installing credentials, compute `refresh_at` once using the same expiry calculation as cached acquisition: `expires_at - min(30 seconds, remaining lifetime / 2)`. Recompute on successful renewal or a replacement access token/expiry, never on cache reads or unrelated metadata saves. Persisting this deadline avoids both resetting it on reads and immediately re-renewing short-lived tokens.
 
 - Before `refresh_at`, apply usable credentials without renewal. A current claim still takes precedence over the old token.
-- At/after `refresh_at`, renew if a refresh token exists. Without one, use the access token until its actual expiry, then fail explicitly as needing reconnection before taking a claim.
+- At/after `refresh_at`, renew if a refresh token exists. Without one, use the access token until its actual expiry, then throw `OAuthAccountReconnectRequiredException` before taking a claim.
 - No expiry means no automatic renewal and a null renewal time.
 
 ### One attempt
@@ -229,7 +229,7 @@ Update `src/docs/saloon.md` in its existing Laravel-docs style:
 
 ## 7. Implementation and verification
 
-Implement metadata and cached acquisition, then account persistence/cache/partitioning, then renewal/recovery and documentation as coherent slices. One final code-review boundary covers the complete feature. No source implementation is authorized by this planning task itself.
+Implement metadata and cached acquisition, then account persistence/cache/partitioning, then renewal/recovery and documentation as coherent slices. One final code-review boundary covers the complete feature.
 
 Before adding tests, inspect existing coverage and extend it where practical. The focused matrix is:
 
diff --git a/src/docs/porting-from-laravel.md b/src/docs/porting-from-laravel.md
index 090b7077b..6dade8895 100644
--- a/src/docs/porting-from-laravel.md
+++ b/src/docs/porting-from-laravel.md
@@ -586,6 +586,8 @@ Integrations built with `saloonphp/saloon`, its Laravel plugin, and its cache, p
 
 Connectors may be shared by concurrent requests, so they are read-only. Move code that changes a connector's headers, query parameters, options, authenticator, delay, middleware, or mock client at runtime to the request, the `send` call, or the connector's `boot` method. Requests use fluent methods such as `withHeaders` and `withQueryParameters` instead of `headers()->add()` and `query()->add()`. Replace `sendAsync` and promises with pools, retry properties with `retry` or `defaultRetryPolicy`, custom senders with HTTP connections, and the rate limit plugin's limits and stores with rate limiter policies. Request exceptions extend the HTTP client's `RequestException`, so `catch (SaloonException $e)` no longer catches failed responses. See [Differences From Saloon](/docs/{{version}}/saloon#differences-from-saloon).
 
+Custom OAuth authenticators must implement `getScopes(): ?array`. Overrides of either grant's `createOAuthAuthenticator()` factory append `?array $scopes = null` and pass it to the authenticator. Return `null` for unreported scopes and `[]` for an explicitly empty set. See [customizing OAuth requests](/docs/{{version}}/saloon#customizing-oauth-requests).
+
 <a name="broadcasting"></a>
 ### Broadcasting
 
diff --git a/src/docs/saloon.md b/src/docs/saloon.md
index 3e15a6441..088db2979 100644
--- a/src/docs/saloon.md
+++ b/src/docs/saloon.md
@@ -42,7 +42,12 @@
 - [OAuth 2](#oauth2)
     - [Authorization Code Grant](#authorization-code-grant)
     - [Client Credentials Grant](#client-credentials-grant)
+    - [Cached Access Tokens](#cached-access-tokens)
     - [Refreshing Access Tokens](#refreshing-access-tokens)
+    - [Connected OAuth Accounts](#connected-oauth-accounts)
+    - [Account Caching](#oauth-account-caching)
+    - [Account Renewal](#oauth-account-renewal)
+    - [Partitioning Accounts](#partitioning-oauth-accounts)
     - [Customizing OAuth Requests](#customizing-oauth-requests)
 - [Concurrent Requests](#concurrent-requests)
     - [Collecting Responses](#collecting-responses)
@@ -731,27 +736,13 @@ class GetPrivateReport extends Request
 
 You may also add the trait to a connector to require authentication for every request in that integration. Saloon throws `MissingAuthenticatorException` before sending an unauthenticated request. You may override `getRequiresAuthMessage(PendingRequest $pendingRequest): string` when the integration needs a more specific message.
 
-Some APIs require you to request a token before calling other endpoints. A connector's `boot` method may send that request and authenticate the pending request with the result:
+For APIs that issue reusable access tokens, use [cached authentication](#cached-access-tokens) instead of requesting a token for every API call. Here, `$oauth` is a client-credentials connector:
 
 ```php
-use Hypervel\Saloon\Http\Auth\TokenAuthenticator;
-use Hypervel\Saloon\Http\PendingRequest;
-
-public function boot(PendingRequest $pendingRequest): void
-{
-    if ($pendingRequest->request() instanceof GetAccessToken) {
-        return;
-    }
-
-    $token = $this->send(new GetAccessToken($this->username, $this->password))
-        ->throw()
-        ->json('token');
-
-    $pendingRequest->authenticate(new TokenAuthenticator($token));
-}
+$request->authenticate($oauth->cachedAccessToken(store: 'redis'));
 ```
 
-The early return stops the token request from requesting a token itself. Don't combine this with `RequiresAuth`, which checks for an authenticator before `boot` runs. When the API's tokens last longer than one request, you may store the token in your application's [cache](/docs/{{version}}/cache) until it expires.
+For user-authorized connections with refresh tokens, use [connected OAuth accounts](#connected-oauth-accounts). Token endpoint requests must not use the authenticator that fetches their own token; use a separate OAuth connector when your API connector supplies authentication by default.
 
 <a name="request-bodies"></a>
 ### Request Bodies
@@ -1633,10 +1624,65 @@ $response = $connector->getAccessToken(
 );
 ```
 
+<a name="cached-access-tokens"></a>
+### Cached Access Tokens
+
+Client credentials connectors provide a `cachedAccessToken` method. It returns an authenticator that fetches a token on first use and reuses it until renewal is due:
+
+```php
+$authenticator = $oauth->cachedAccessToken(
+    scopes: ['reports:read'],
+    store: 'redis',
+);
+
+$response = $api->send((new GetReports)->authenticate($authenticator));
+```
+
+The cache key includes the connector class, token URL, client credentials and requested scopes. Credentials are hashed, never included directly in cache keys. Fresh connector and authenticator instances with the same grant reuse the shared entry. Account and merchant headers stay on each request or connector.
+
+If a request modifier or custom request factory changes the grant, include that difference in the optional `key` argument:
+
+```php
+$authenticator = $oauth->cachedAccessToken(
+    store: 'redis',
+    requestModifier: fn ($request) => $request->withData(['audience' => 'billing']),
+    key: 'billing',
+);
+```
+
+The store defaults to `saloon.cache.store`, then the framework's default cache store. Use Redis to share tokens across workers. The `worker-array` store shares within one worker; the ordinary `array` store is local to a coroutine. Concurrent callers in one worker share the active fetch and its result or failure. Different workers may safely acquire their own client-credentials tokens on a simultaneous cache miss.
+
+Tokens renew up to 30 seconds before expiry, capped at half their remaining lifetime when acquired. This deadline does not move when an entry is read. Tokens without expiry do not renew automatically; supply an expiry when the provider documents one. An already-expired result is rejected.
+
+For APIs with a username/password token endpoint, supply a resolver returning `OAuthAuthenticator`. In this example, `$auth` is a connector for the authentication API, and `LoginRequest` exchanges the credentials for a token and its lifetime:
+
+```php
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Saloon\Http\Auth\CachedTokenAuthenticator;
+use Hypervel\Support\Facades\Date;
+
+$authenticator = new CachedTokenAuthenticator(
+    key: serialize([LoginRequest::class, $auth->resolveBaseUrl(), $username, $password]),
+    resolver: function () use ($auth, $username, $password): AccessTokenAuthenticator {
+        $response = $auth->send(new LoginRequest($username, $password))->throw();
+
+        return new AccessTokenAuthenticator(
+            accessToken: $response->json('token'),
+            expiresAt: Date::now()->addSeconds($response->json('expires_in'))->toDateTimeImmutable(),
+        );
+    },
+    store: 'redis',
+);
+```
+
+Your grant identity must distinguish credentials, environments and any audience or other grant inputs. Saloon hashes it before storage. The cache retains the actual authenticator, including custom authentication behavior. Register custom classes through the cache's `allowSerializableClassesUsing` method during provider boot, and use a serializer that preserves PHP objects. Cached standalone tokens contain usable credentials, so protect access to the cache.
+
+Call `$authenticator->forget()` to clear that instance's token and its shared entry. This does not revoke the provider token or clear copies held by other live instances. Use connected accounts for rotating refresh tokens, which require durable storage and coordinated updates.
+
 <a name="refreshing-access-tokens"></a>
 ### Refreshing Access Tokens
 
-An `AccessTokenAuthenticator` exposes its access token, optional refresh token, expiry, and expiration helpers:
+An `AccessTokenAuthenticator` exposes its access token, optional refresh token, expiry, reported scopes, and expiration helpers:
 
 ```php
 if ($authenticator->hasExpired() && $authenticator->isRefreshable()) {
@@ -1644,7 +1690,7 @@ if ($authenticator->hasExpired() && $authenticator->isRefreshable()) {
 }
 ```
 
-To keep tokens between requests, store the authenticator's `accessToken`, `refreshToken`, and `expiresAt` properties and create a new authenticator from them when you need it. For example, you may store the tokens in [encrypted](/docs/{{version}}/eloquent-mutators#encrypted-casting) model attributes and [cast](/docs/{{version}}/eloquent-mutators#date-casting) the expiry attribute to `immutable_datetime`:
+For automatic persistence and renewal, use [connected OAuth accounts](#connected-oauth-accounts). You may also manage tokens yourself using [encrypted](/docs/{{version}}/eloquent-mutators#encrypted-casting) model attributes and an `immutable_datetime` [cast](/docs/{{version}}/eloquent-mutators#date-casting) for expiry:
 
 ```php
 use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
@@ -1658,6 +1704,8 @@ $authenticator = new AccessTokenAuthenticator(
 
 OAuth token expiry values use immutable dates. Saloon rejects negative or unrepresentable expiry durations instead of creating an already-expired token.
 
+`getScopes()` returns the scopes reported by the provider, or `null` when none were reported. Saloon does not infer granted permissions from the requested scopes. A custom authenticator may supply `[]` to represent an explicitly empty set.
+
 Refresh requests use the configured `tokenEndpoint` by default. If your provider uses a separate endpoint, set `refreshEndpoint` on your `OAuthConfig`:
 
 ```php
@@ -1672,6 +1720,134 @@ return new OAuthConfig(
 
 For an absolute refresh URL, also set `allowBaseUrlOverride: true`.
 
+<a name="connected-oauth-accounts"></a>
+### Connected OAuth Accounts
+
+Connected accounts store user-authorized credentials and renew them when needed. Generate and run the migration only if your application uses this feature:
+
+```shell
+php artisan make:oauth-accounts-table
+php artisan migrate
+```
+
+The `oauth-accounts:table` alias is also available. The migration creates `oauth_accounts` with a UUID key and a polymorphic owner. Add `HasOAuthAccounts` to the owning model:
+
+```php
+use Hypervel\Saloon\Traits\HasOAuthAccounts;
+
+class User extends Authenticatable
+{
+    use HasOAuthAccounts;
+}
+```
+
+After exchanging an authorization code, save the returned credentials:
+
+```php
+$account = $user->oauthAccounts()->create([
+    'provider' => 'gitlab',
+    'provider_account_id' => $providerUserId,
+    'access_token' => $token->getAccessToken(),
+    'refresh_token' => $token->getRefreshToken(),
+    'expires_at' => $token->getExpiresAt(),
+    'scopes' => $token->getScopes(),
+]);
+
+$request->authenticate($oauth->accountAuthenticator($account));
+```
+
+Access and refresh tokens use encrypted casts and are hidden from model serialization. Client secrets remain in your application configuration. Reconnect by updating the selected account's credential fields, and disconnect locally by deleting the account. Deletion does not revoke the provider grant. The same owner may have several grants for one provider account, so Saloon does not infer which row a reconnect should replace.
+
+To customize the table, connection or token behavior, extend `Hypervel\Saloon\OAuthAccount` and select the model during provider boot, before using accounts:
+
+```php
+use Hypervel\Saloon\OAuthAccounts;
+
+OAuthAccounts::useAccountModel(App\Models\OAuthAccount::class);
+```
+
+Override `newOAuthAuthenticator()` when persisted credentials need custom authentication behavior. The default creates a bearer authenticator. An account authenticator retains the account's storage identity, not a permanent copy of its token.
+
+You may use another OAuth client by supplying a refresh callback. For example, a Socialite provider's refresh result can be adapted without changing Socialite:
+
+```php
+use Hypervel\Saloon\Contracts\OAuthAuthenticator;
+use Hypervel\Saloon\Http\Auth\AccessTokenAuthenticator;
+use Hypervel\Support\Facades\Date;
+
+$authenticator = $account->authenticator(
+    refreshUsing: function (OAuthAuthenticator $current) use ($provider): OAuthAuthenticator {
+        $token = $provider->refreshToken($current->getRefreshToken());
+
+        return new AccessTokenAuthenticator(
+            accessToken: $token->token,
+            refreshToken: $token->refreshToken,
+            expiresAt: $token->expiresIn === null
+                ? null
+                : Date::now()->addSeconds($token->expiresIn)->toDateTimeImmutable(),
+            scopes: $token->approvedScopes ?: null,
+        );
+    },
+);
+```
+
+Socialite's empty approved-scopes list does not distinguish an omitted field. Mapping it to `null` retains the account's stored scopes; adapters that know the provider explicitly cleared them may return `[]`. Initial Socialite user results expose the raw token response when exact field presence matters.
+
+<a name="oauth-account-caching"></a>
+### Account Caching
+
+Credential caching is disabled by default. Enable it in `config/saloon.php` to avoid database reads on ordinary authenticated calls:
+
+```php
+'oauth_accounts' => [
+    'cache' => [
+        'enabled' => true,
+        'store' => 'redis',
+        'ttl' => 300,
+        'prefix' => 'saloon:oauth-accounts:',
+    ],
+    'lock_store' => null,
+],
+```
+
+The cache stores encrypted model attributes. Normal saves and deletes invalidate the entry after commit; reads inside an application transaction bypass shared caching. Custom account models retain their global scopes and query builders.
+
+The renewal lock store defaults to the account cache store, then the framework default. It is required even when credential caching is disabled. Use Redis or a database store for deployments spanning hosts. File and Swoole stores are supported when their sharing scope covers every worker using the accounts. Worker-local, stack and failover stores are not supported for durable account credentials or renewal locks.
+
+Quiet saves, bulk updates and raw queries have the usual Eloquent responsibilities. After such changes, call `$account->clearCredentialCache()`. Credential changes must also replace `credential_revision`, recompute `refresh_at` and clear obsolete refresh claims. Prefer normal model updates so these steps happen automatically.
+
+The default response-cache key includes the bearer token, so renewed tokens no longer match old response entries. If you choose stable response-cache keys or scopes, preserve account and permission isolation yourself.
+
+<a name="oauth-account-renewal"></a>
+### Account Renewal
+
+Saloon records a fixed early-renewal deadline when credentials are saved. A token without a refresh token remains usable until its actual expiry, then throws `Hypervel\Saloon\Exceptions\OAuthAccountReconnectRequiredException`. Catch this exception to prompt the user to reconnect. Tokens without expiry do not renew automatically.
+
+Renewal rereads the account, records ownership of the attempt, then calls the provider without holding an idle database connection. The replacement is stored before it is applied to a request. A concurrent reconnect, deletion or replacement attempt cannot be overwritten by a late result. Renewal is rejected inside a transaction on the account connection, before contacting the provider.
+
+Transient connection failures, selected HTTP errors and temporary OAuth errors receive up to three attempts, with jittered delays capped at 250 and 500 milliseconds. Each attempt rereads current credentials. Longer `Retry-After` delays are returned to the caller for later scheduling. The connector convenience disables nested HTTP retries; custom refresh callbacks must also make one provider attempt per invocation.
+
+An `invalid_grant` response is not retried. Saloon first checks for replacement credentials, then preserves the provider exception if the grant is still rejected. Your application decides how to reconnect or disable the account. `invalid_client` indicates client configuration needs attention; it does not require every user to reconnect. Transient exhaustion preserves the stored grant for a later attempt. Provider responses remain available through their normal exceptions.
+
+The renewal lock lasts 120 seconds, with up to 120 seconds waiting to acquire it. A recorded attempt becomes recoverable after 300 seconds. Keep custom refresh callbacks and timeouts within those bounds; the default HTTP timeouts are 10 seconds connecting and 30 seconds total. Cancellation stops that caller and clears its owned claim where possible. Waiting callers may continue independently.
+
+These measures cannot guarantee exactly one provider request after a crash or ambiguous network failure. A delayed request may overlap recovery, and providers that detect reuse of rotated refresh tokens may revoke the grant. Such accounts need reconnection. Saloon does not run detached refresh tasks or silently retry failed local persistence.
+
+<a name="partitioning-oauth-accounts"></a>
+### Partitioning Accounts
+
+Applications that divide accounts by tenant or another ownership boundary may register a partition resolver during provider boot:
+
+```php
+use Hypervel\Saloon\OAuthAccounts;
+
+OAuthAccounts::resolvePartitionUsing('tenant_id', fn () => $tenancy->currentKey());
+```
+
+Add the partition column and suitable indexes to your published migration. The callback should capture a worker-safe context service and resolve the current key when called. Missing context fails explicitly. New accounts receive that partition, and retained authenticators are checked against it on every use, including warm cache reads and after provider calls.
+
+Your model or integration still owns application-wide query scoping; Saloon does not install a global Eloquent scope. Platform-owned accounts use an explicit platform partition. Cached client-credentials tokens use grant identity instead, allowing identical platform credentials to share a token. Keep merchant-specific headers on the request or connector.
+
 <a name="customizing-oauth-requests"></a>
 ### Customizing OAuth Requests
 
@@ -1704,15 +1880,15 @@ $authenticator = $connector->getAccessToken(
 
 For providers that require a different request body or token response format, override the protected `resolveAccessTokenRequest`, `resolveRefreshTokenRequest`, `resolveUserRequest`, `createOAuthAuthenticatorFromResponse`, or `createOAuthAuthenticator` method on the connector. These methods let you adapt the provider protocol without replacing the OAuth flow. A PKCE verifier is added to the request your `resolveAccessTokenRequest` method returns.
 
-For example, you may return your own authenticator class. Authorization code connectors receive the access token, refresh token, and expiry, while client credentials connectors receive the access token and expiry:
+For example, you may return your own authenticator class. Authorization code connectors receive the access token, refresh token, expiry and scopes; client credentials connectors receive the access token, expiry and scopes:
 
 ```php
 use DateTimeImmutable;
 use Hypervel\Saloon\Contracts\OAuthAuthenticator;
 
-protected function createOAuthAuthenticator(string $accessToken, ?string $refreshToken = null, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator
+protected function createOAuthAuthenticator(string $accessToken, ?string $refreshToken = null, ?DateTimeImmutable $expiresAt = null, ?array $scopes = null): OAuthAuthenticator
 {
-    return new SpotifyAuthenticator($accessToken, $refreshToken, $expiresAt);
+    return new SpotifyAuthenticator($accessToken, $refreshToken, $expiresAt, $scopes);
 }
 ```
 
diff --git a/src/saloon/README.md b/src/saloon/README.md
index 678328265..2e5cfb6f5 100644
--- a/src/saloon/README.md
+++ b/src/saloon/README.md
@@ -42,7 +42,7 @@ Authentication helpers use the HTTP client's names: `withToken()`, `withBasicAut
 
 The upstream NTLM authenticator is omitted. Integrations requiring NTLM must supply their own authenticator and transport middleware.
 
-OAuth 2 configuration is an immutable `Data\OAuthConfig` built from constructor arguments and read through public properties, replacing upstream's `Helpers\OAuth2\OAuthConfig` setters and getters, so connectors define `defaultOAuthConfig()` and per-call changes use the grant methods' `requestModifier`. `invokeRequestModifier()` is `modify()`. `authorizationUrl()` returns an `AuthorizationUrl` holding the URL and its state, instead of `getAuthorizationUrl()` storing the state on the shared connector for `getState()`. Additional authorization parameters cannot replace that state, and if `getAccessToken()` receives either state, both must be non-empty and equal. `getUser()` applies the configuration's request modifier before the per-call one, as the token methods do, and its request sends no form `Content-Type`. See [OAuth 2](https://hypervel.org/docs/saloon#oauth2).
+OAuth 2 configuration is an immutable `Data\OAuthConfig` built from constructor arguments and read through public properties, replacing upstream's `Helpers\OAuth2\OAuthConfig` setters and getters, so connectors define `defaultOAuthConfig()` and per-call changes use the grant methods' `requestModifier`. `invokeRequestModifier()` is `modify()`. `authorizationUrl()` returns an `AuthorizationUrl` holding the URL and its state, instead of `getAuthorizationUrl()` storing the state on the shared connector for `getState()`. Additional authorization parameters cannot replace that state, and if `getAccessToken()` receives either state, both must be non-empty and equal. `getUser()` applies the configuration's request modifier before the per-call one, as the token methods do, and its request sends no form `Content-Type`. `OAuthAuthenticator` also requires `getScopes(): ?array`; `AccessTokenAuthenticator` and both grants' `createOAuthAuthenticator()` factories append an optional `?array $scopes = null` argument. This preserves reported permissions during account renewal: `null` means unreported, while `[]` is explicitly empty. See [OAuth 2](https://hypervel.org/docs/saloon#oauth2).
 
 Ported from:
 

From c15da87566abd52ef493ff18bc20546ccbae20d3 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 20:24:30 +0000
Subject: [PATCH 6/8] Align split-package PHPStan constraints with the root pin

Pin the Database and Foundation development requirements to PHPStan 2.3.1, matching the root manifest while the 2.3.2 generic loop-narrowing regression remains unresolved.

Record all three manifests in the removal task so the ranges are restored together. Keep the package manifest consistency check intact; its failure exposed the incomplete pin.

Validation: Composer manifest checks and full source and type-fixture analysis pass.
---
 docs/todo.md                 | 2 +-
 src/database/composer.json   | 2 +-
 src/foundation/composer.json | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/todo.md b/docs/todo.md
index fbc187221..355d9ad90 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -34,7 +34,7 @@
 
 ## Testing
 
-- Remove the root PHPStan `2.3.1` pin once a release fixes the 2.3.2 loop-narrowing regression: `DataCollectionEloquentCast::set()` rejects a value narrowed by `instanceof` against `class-string<TData>`. Verify the full source and type-fixture analyses before restoring the version range.
+- Remove the PHPStan `2.3.1` pins in the root, Database and Foundation manifests once a release fixes the 2.3.2 loop-narrowing regression: `DataCollectionEloquentCast::set()` rejects a value narrowed by `instanceof` against `class-string<TData>`. Verify the full source and type-fixture analyses before restoring the version ranges.
 - Adopt a Swoole release fixing the intermittent AIO shutdown hang in [swoole-src#6297](https://github.com/swoole/swoole-src/issues/6297). On 6.3.0RC1, ordinary coroutine scheduler teardown can wait forever for an idle native thread that missed its shutdown notification, including between tests. Verify the released fix with the standalone reproduction and affected suites; do not add a Hypervel workaround or a timing-dependent regression test.
 - Add the required title docblocks to the untitled non-test methods in `tests/`: about 7,600 methods in 1,500 files, mostly helpers, fixtures, and methods of anonymous classes in older tests. `AGENTS.md` requires a title on every method except test methods, but most existing tests omit them, and agents follow the surrounding code over the written rule, so new tests keep reproducing the gap until review catches it. Make the change as one approved sweep (short imperative titles only), then add an automated check, such as a PHPStan rule, so the code and the rule cannot drift apart again. Decide whether the check also covers `src/`.
 - Add native return types to the `test*` methods that lack them: about 5,600 methods in 490 files. `AGENTS.md` requires `: void` on test methods; a test that returns a value for `#[Depends]` takes its actual return type instead. As with method titles, untyped methods in existing files lead new tests to copy them, so make the change as one approved sweep and enforce it with the same automated check.
diff --git a/src/database/composer.json b/src/database/composer.json
index d21b8be16..b8e0f7917 100644
--- a/src/database/composer.json
+++ b/src/database/composer.json
@@ -59,7 +59,7 @@
     },
     "require-dev": {
         "fakerphp/faker": "^1.24",
-        "phpstan/phpstan": "^2.3"
+        "phpstan/phpstan": "2.3.1"
     },
     "suggest": {
         "fakerphp/faker": "Required to use Eloquent model factories (^1.24)."
diff --git a/src/foundation/composer.json b/src/foundation/composer.json
index f39d851f7..5824c6420 100644
--- a/src/foundation/composer.json
+++ b/src/foundation/composer.json
@@ -84,7 +84,7 @@
         "hypervel/websocket-server": "^0.4"
     },
     "require-dev": {
-        "phpstan/phpstan": "^2.3"
+        "phpstan/phpstan": "2.3.1"
     },
     "suggest": {
         "algolia/algoliasearch-client-php": "Required to use the InteractsWithAlgolia trait (^4.49.0).",

From 3433b112a02fac36c0b9bb3667184fd687231e7b Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 20:24:39 +0000
Subject: [PATCH 7/8] Preserve OAuth account isolation and credentials across
 renewal races

Validate the current partition before normal saves and deletes, and reject partition changes on existing accounts. Keep application deleting observers active. Normalize write aliases only in cache and renewal identity while preserving the requested connection for transaction ownership.

Store computed renewal deadlines and callback expiry instants through the normal numeric date casts so non-UTC applications do not shift them. Check caller transactions before joining a renewal; allow unclaimed, unexpired tokens to remain usable during the early-renewal window without contacting the provider.

Preserve the original provider rejection when an account is concurrently deleted. Conditionally persist rotated credentials even when the returned access token has already expired, then reject its use without an immediate retry. Late results still cannot overwrite a reconnect or a replacement claim.

Add regressions for partition mutations, model observers, write-alias invalidation, non-UTC dates, transactional waiters, deferred early renewal, concurrent deletion and expired rotated results. Formatting, full source and type analysis, the Saloon suite and shared Redis renewal integration pass.
---
 src/saloon/src/Data/OAuthAccountIdentity.php |   3 +-
 src/saloon/src/OAuthAccount.php              |  12 +-
 src/saloon/src/OAuthAccounts.php             |  52 +++--
 tests/Saloon/OAuthAccountTest.php            | 215 +++++++++++++++++--
 4 files changed, 239 insertions(+), 43 deletions(-)

diff --git a/src/saloon/src/Data/OAuthAccountIdentity.php b/src/saloon/src/Data/OAuthAccountIdentity.php
index 415b50fd6..e5f5993bb 100644
--- a/src/saloon/src/Data/OAuthAccountIdentity.php
+++ b/src/saloon/src/Data/OAuthAccountIdentity.php
@@ -4,6 +4,7 @@
 
 namespace Hypervel\Saloon\Data;
 
+use Hypervel\Database\ConnectionName;
 use Hypervel\Database\Eloquent\Builder;
 use Hypervel\Saloon\OAuthAccount;
 
@@ -24,7 +25,7 @@ public function __construct(
         public ?string $partitionColumn,
         public ?string $partition,
     ) {
-        $this->key = hash('sha256', serialize([$model, $connection, $table, (string) $id, $partitionColumn, $partition]));
+        $this->key = hash('sha256', serialize([$model, ConnectionName::withoutWriteType($connection), $table, (string) $id, $partitionColumn, $partition]));
     }
 
     /**
diff --git a/src/saloon/src/OAuthAccount.php b/src/saloon/src/OAuthAccount.php
index b1158a8d7..a079de50b 100644
--- a/src/saloon/src/OAuthAccount.php
+++ b/src/saloon/src/OAuthAccount.php
@@ -60,11 +60,7 @@ protected static function booted(): void
         static::saving(function (self $account): void {
             $accounts = Container::getInstance()->make(OAuthAccounts::class);
 
-            if (! $account->exists) {
-                $accounts->prepareAccount($account);
-            } else {
-                $accounts->identity($account);
-            }
+            $accounts->prepareAccount($account);
 
             if (! $account->exists || $account->isDirty(['access_token', 'refresh_token', 'expires_at', 'scopes'])) {
                 $account->credential_revision = (string) Str::uuid();
@@ -73,12 +69,14 @@ protected static function booted(): void
             }
 
             if (! $account->exists || $account->isDirty(['access_token', 'expires_at'])) {
-                $refreshAt = TokenExpiry::refreshAt($account->expires_at);
-                $account->refresh_at = $refreshAt === null ? null : CarbonImmutable::createFromTimestampUTC($refreshAt);
+                $account->setAttribute('refresh_at', TokenExpiry::refreshAt($account->expires_at));
             }
         });
 
         static::saved(static fn (self $account) => $account->clearCredentialCache());
+        static::deleting(static function (self $account): void {
+            Container::getInstance()->make(OAuthAccounts::class)->identity($account);
+        });
         static::deleted(static fn (self $account) => $account->clearCredentialCache());
     }
 
diff --git a/src/saloon/src/OAuthAccounts.php b/src/saloon/src/OAuthAccounts.php
index 80b9cd695..670c3a2c5 100644
--- a/src/saloon/src/OAuthAccounts.php
+++ b/src/saloon/src/OAuthAccounts.php
@@ -26,7 +26,6 @@
 use Hypervel\Saloon\Http\Auth\TokenAcquisition;
 use Hypervel\Saloon\Http\Auth\TokenExpiry;
 use Hypervel\Saloon\Http\RetryAfter;
-use Hypervel\Support\CarbonImmutable;
 use Hypervel\Support\Facades\Date;
 use Hypervel\Support\Sleep;
 use Hypervel\Support\Str;
@@ -150,10 +149,20 @@ public function partition(): ?string
     }
 
     /**
-     * Fill the partition of a new account without accepting another context's value.
+     * Validate an existing account's partition or fill it for a new account.
      */
     public function prepareAccount(OAuthAccount $account): void
     {
+        if ($account->exists) {
+            $this->identity($account);
+
+            if (static::$partitionColumn !== null && $account->isDirty(static::$partitionColumn)) {
+                throw new LogicException('An OAuth account cannot move to another partition.');
+            }
+
+            return;
+        }
+
         $partition = $this->partition();
 
         if (static::$partitionColumn === null) {
@@ -262,10 +271,20 @@ public function invalidate(OAuthAccountIdentity $identity): void
      */
     public function token(OAuthAccountIdentity $identity, Closure $refreshUsing): OAuthAuthenticator
     {
-        if (($token = $this->usableToken($this->find($identity))) !== null) {
+        $account = $this->find($identity);
+
+        if (($token = $this->usableToken($account)) !== null) {
             return $token;
         }
 
+        if ($identity->newModel()->hasApplicableTransaction()) {
+            if ($account->refresh_claim === null && ($token = $account->newOAuthAuthenticator())->hasNotExpired()) {
+                return $token;
+            }
+
+            throw new LogicException('OAuth account renewal cannot run inside a database transaction.');
+        }
+
         $cache = $this->renewalCache();
         /** @var LockProvider&Store $locks */
         $locks = $cache->getStore();
@@ -334,10 +353,6 @@ protected function renew(OAuthAccountIdentity $identity, Closure $refreshUsing,
             return $token;
         }
 
-        if ($account->hasApplicableTransaction()) {
-            throw new LogicException('OAuth account renewal cannot run inside a database transaction.');
-        }
-
         $abandonedBefore = Date::now()->subSeconds(300);
 
         if ($account->refresh_claim !== null && ($account->refresh_started_at === null || $account->refresh_started_at > $abandonedBefore)) {
@@ -373,17 +388,13 @@ protected function renew(OAuthAccountIdentity $identity, Closure $refreshUsing,
 
             $this->ensurePartition($identity);
 
-            if ($renewed->hasExpired()) {
-                throw new UnexpectedValueException('The refreshed OAuth token has already expired.');
-            }
-
             $refreshAt = TokenExpiry::refreshAt($renewed->getExpiresAt());
             $replacement = clone $account;
             $replacement->forceFill([
                 'access_token' => $renewed->getAccessToken(),
                 'refresh_token' => $renewed->getRefreshToken() ?? $account->refresh_token,
-                'expires_at' => $renewed->getExpiresAt(),
-                'refresh_at' => $refreshAt === null ? null : CarbonImmutable::createFromTimestampUTC($refreshAt),
+                'expires_at' => $renewed->getExpiresAt()?->getTimestamp(),
+                'refresh_at' => $refreshAt,
                 'scopes' => $renewed->getScopes() ?? $account->scopes,
                 'credential_revision' => (string) Str::uuid(),
                 'refresh_claim' => null,
@@ -395,7 +406,16 @@ protected function renew(OAuthAccountIdentity $identity, Closure $refreshUsing,
             $this->invalidate($identity);
             $this->ensurePartition($identity);
 
-            return $written === 1 ? $replacement->newOAuthAuthenticator() : $this->replacementToken($identity);
+            if ($written !== 1) {
+                return $this->replacementToken($identity);
+            }
+
+            // Persist rotated refresh credentials even if the returned access token is no longer usable.
+            if ($renewed->hasExpired()) {
+                throw new UnexpectedValueException('The refreshed OAuth token has already expired.');
+            }
+
+            return $replacement->newOAuthAuthenticator();
         } catch (Throwable $exception) {
             try {
                 // Release only this captured claim, even if the callback changed the current partition.
@@ -414,10 +434,10 @@ protected function renew(OAuthAccountIdentity $identity, Closure $refreshUsing,
 
             if ($oauthError === 'invalid_grant') {
                 $this->ensurePartition($identity);
-                $latest = $identity->query()->useWritePdo()->firstOrFail();
+                $latest = $identity->query()->useWritePdo()->first();
                 $this->ensurePartition($identity);
 
-                if ($latest->credential_revision !== $revision) {
+                if ($latest !== null && $latest->credential_revision !== $revision) {
                     return $this->usableToken($latest)
                         ?? throw new RuntimeException('The replacement OAuth credentials are awaiting renewal. Try again later.');
                 }
diff --git a/tests/Saloon/OAuthAccountTest.php b/tests/Saloon/OAuthAccountTest.php
index f8f2c999d..a0f58722e 100644
--- a/tests/Saloon/OAuthAccountTest.php
+++ b/tests/Saloon/OAuthAccountTest.php
@@ -4,6 +4,7 @@
 
 namespace Hypervel\Tests\Saloon\OAuthAccountTest;
 
+use DateTimeImmutable;
 use GuzzleHttp\Exception\ResponseTransferException;
 use GuzzleHttp\Psr7\PumpStream;
 use GuzzleHttp\Psr7\Request as PsrRequest;
@@ -207,11 +208,61 @@ public function testWarmCredentialsRequireNoQueriesAndSaveAndDeleteInvalidateThe
 
         $account->update(['access_token' => 'second']);
         $this->assertSame('second', $accounts->find($identity)->access_token);
+        $deleting = false;
+        OAuthAccount::deleting(static function () use (&$deleting): void {
+            $deleting = true;
+        });
         $account->delete();
+        $this->assertTrue($deleting);
         $this->expectException(ModelNotFoundException::class);
         $accounts->find($identity);
     }
 
+    public function testWriteAliasesShareCredentialInvalidation(): void
+    {
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'old']);
+        $accounts = $this->app->make(OAuthAccounts::class);
+        $identity = $accounts->identity($account);
+        $authenticator = $account->authenticator(fn (): never => $this->fail('Non-expiring credentials must not refresh.'));
+        $this->assertSame('Bearer old', $this->authorization($authenticator));
+
+        $write = $account->fresh()->setConnection('oauth::write');
+        $writeIdentity = $accounts->identity($write);
+        $this->assertSame($identity->key, $writeIdentity->key);
+        $this->assertSame('oauth::write', $writeIdentity->connection);
+        $write->update(['access_token' => 'new']);
+        $this->assertSame('Bearer new', $this->authorization($authenticator));
+
+        $write->delete();
+        $this->expectException(ModelNotFoundException::class);
+        $this->authorization($authenticator);
+    }
+
+    public function testNonUtcDatesPreserveExpiryAndRenewalInstants(): void
+    {
+        $timezone = date_default_timezone_get();
+        date_default_timezone_set('America/New_York');
+
+        try {
+            Date::setTestNow('2026-01-01 00:00:00');
+            $account = Owner::create()->oauthAccounts()->create([
+                'provider' => 'example', 'access_token' => 'old', 'refresh_token' => 'refresh',
+                'expires_at' => Date::now()->addHour(),
+            ]);
+            $this->assertSame(Date::now()->addHour()->getTimestamp() - 30, $account->fresh()->refresh_at->getTimestamp());
+            Date::setTestNow('2026-01-01 00:59:30');
+            $expiry = new DateTimeImmutable('2026-01-01 07:00:00 UTC');
+            $authenticator = $account->authenticator(fn (): OAuthAuthenticator => new AccessTokenAuthenticator('renewed', expiresAt: $expiry));
+
+            $this->assertSame('Bearer renewed', $this->authorization($authenticator));
+            $persisted = $account->fresh();
+            $this->assertSame($expiry->getTimestamp(), $persisted->expires_at->getTimestamp());
+            $this->assertSame($expiry->getTimestamp() - 30, $persisted->refresh_at->getTimestamp());
+        } finally {
+            date_default_timezone_set($timezone);
+        }
+    }
+
     #[DefineEnvironment('disableCredentialCache')]
     public function testCachingCanBeDisabledWithoutChangingAuthentication(): void
     {
@@ -406,6 +457,51 @@ public function testCreationRejectsAConflictingPartition(): void
         $account->save();
     }
 
+    public function testSavingCannotMoveAnAccountToAnotherPartition(): void
+    {
+        Schema::table('oauth_accounts', fn (Blueprint $table) => $table->string('partition_id')->nullable());
+        OAuthAccounts::resolvePartitionUsing('partition_id', static fn (): string => 'first');
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'secret']);
+        $account->partition_id = 'second';
+
+        try {
+            $account->save();
+            $this->fail('An existing account must retain its partition.');
+        } catch (LogicException $exception) {
+            $this->assertSame('An OAuth account cannot move to another partition.', $exception->getMessage());
+        }
+
+        $this->assertSame('first', $account->fresh()->partition_id);
+    }
+
+    #[TestWith(['save'])]
+    #[TestWith(['delete'])]
+    public function testMutationsRejectAnotherPartitionBeforeChangingTheRow(string $operation): void
+    {
+        Schema::table('oauth_accounts', fn (Blueprint $table) => $table->string('partition_id')->nullable());
+        $partition = 'first';
+        OAuthAccounts::resolvePartitionUsing('partition_id', static function () use (&$partition): string {
+            return $partition;
+        });
+        $account = Owner::create()->oauthAccounts()->create(['provider' => 'example', 'access_token' => 'secret']);
+        $authenticator = $account->authenticator(fn (): never => $this->fail('Non-expiring credentials must not refresh.'));
+        $this->assertSame('Bearer secret', $this->authorization($authenticator));
+        $account->access_token = 'changed';
+        $partition = 'second';
+
+        try {
+            $account->{$operation}();
+            $this->fail('An account mutation must reject another partition.');
+        } catch (LogicException $exception) {
+            $this->assertSame('The OAuth account belongs to another partition.', $exception->getMessage());
+        } finally {
+            $partition = 'first';
+        }
+
+        $this->assertSame('secret', $account->fresh()->access_token);
+        $this->assertSame('Bearer secret', $this->authorization($authenticator));
+    }
+
     public function testMissingPartitionContextRejectsCreation(): void
     {
         OAuthAccounts::resolvePartitionUsing('partition_id', static fn (): null => null);
@@ -444,20 +540,69 @@ public function testConcurrentRenewalPersistsBeforeUseAndReleasesTheOnlyDatabase
         $this->assertNotSame($account->credential_revision, $persisted->credential_revision);
     }
 
-    public function testRenewalRejectsCallerTransactionsWithoutReleasingThem(): void
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testTransactionsDeferEarlyRenewalUntilActualExpiry(bool $expired): void
     {
         $account = $this->refreshableAccount();
-        $authenticator = $account->authenticator(fn (): never => $this->fail('A caller transaction must prevent provider I/O.'));
-        DB::beginTransaction();
+        $authenticator = $account->authenticator(fn (): never => $this->fail('A caller transaction must not invoke the provider.'));
 
-        try {
+        if ($expired) {
+            Date::setTestNow('2026-01-01 00:00:10');
             $this->expectException(LogicException::class);
             $this->expectExceptionMessage('inside a database transaction');
-            $this->authorization($authenticator);
+        }
+
+        DB::transaction(function () use ($authenticator): void {
+            $this->assertSame('Bearer old', $this->authorization($authenticator));
+        });
+    }
+
+    public function testRenewalRejectsCallerTransactionsWithoutReleasingThem(): void
+    {
+        $account = $this->refreshableAccount();
+        $entered = new Channel(1);
+        $release = new Channel(1);
+        $result = new Channel(1);
+        $authenticator = $account->authenticator(function () use ($entered, $release): OAuthAuthenticator {
+            $entered->push(true);
+            $release->pop(5);
+
+            return new AccessTokenAuthenticator('renewed');
+        });
+        DB::releaseIdleConnections();
+        $owner = go(function () use ($authenticator, $result): void {
+            try {
+                $result->push($this->authorization($authenticator));
+            } catch (Throwable $exception) {
+                $result->push($exception);
+            }
+        });
+
+        try {
+            $this->assertTrue($entered->pop(2));
+            DB::beginTransaction();
+            try {
+                $this->authorization($authenticator);
+                $this->fail('A transactional caller must not wait for another renewal.');
+            } catch (LogicException $exception) {
+                $this->assertStringContainsString('inside a database transaction', $exception->getMessage());
+                $this->assertSame(1, DB::transactionLevel());
+                $this->assertSame(0, $this->app->make(PoolManager::class)->pool('oauth')->getIdleCount());
+            } finally {
+                DB::rollBack();
+                DB::releaseIdleConnections();
+                $release->push(true);
+            }
+            $this->assertSame('Bearer renewed', $result->pop(2));
+            DB::transaction(function () use ($authenticator): void {
+                $this->assertSame('Bearer renewed', $this->authorization($authenticator));
+            });
         } finally {
-            $this->assertSame(1, DB::transactionLevel());
-            $this->assertSame(0, $this->app->make(PoolManager::class)->pool('oauth')->getIdleCount());
-            DB::rollBack();
+            $release->close();
+            EngineCoroutine::join([$owner], 2);
+            $entered->close();
+            $result->close();
         }
     }
 
@@ -509,13 +654,15 @@ public static function providerFailures(): array
         ];
     }
 
-    public function testLateProviderSuccessCannotOverwriteAReconnect(): void
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testLateProviderSuccessCannotOverwriteAReconnect(bool $expired): void
     {
         $account = $this->refreshableAccount();
-        $authenticator = $account->authenticator(function () use ($account): OAuthAuthenticator {
+        $authenticator = $account->authenticator(function () use ($account, $expired): OAuthAuthenticator {
             $account->fresh()->update(['access_token' => 'reconnected', 'refresh_token' => 'new-grant', 'expires_at' => null]);
 
-            return new AccessTokenAuthenticator('loser', 'loser-refresh', Date::now()->addHour()->toDateTimeImmutable());
+            return new AccessTokenAuthenticator('loser', 'loser-refresh', Date::now()->addSeconds($expired ? 0 : 3600)->toDateTimeImmutable());
         });
 
         $this->assertSame('Bearer reconnected', $this->authorization($authenticator));
@@ -559,6 +706,25 @@ public function testInvalidGrantFromAnOldAttemptDoesNotRejectReconnectedCredenti
         $this->assertSame('replacement', $account->fresh()->refresh_token);
     }
 
+    public function testConcurrentDeletionPreservesTheProviderRejection(): void
+    {
+        $account = $this->refreshableAccount();
+        $failure = new RequestException(new Response(new PsrResponse(400, [], '{"error":"invalid_grant"}')));
+        $authenticator = $account->authenticator(function () use ($account, $failure): never {
+            $account->fresh()->delete();
+            throw $failure;
+        });
+
+        try {
+            $this->authorization($authenticator);
+            $this->fail('The provider rejection must reach the caller.');
+        } catch (RequestException $exception) {
+            $this->assertSame($failure, $exception);
+        }
+
+        $this->assertNull($account->fresh());
+    }
+
     public function testLateSuccessCannotOverwriteAReplacedClaimWithTheSameRevision(): void
     {
         $account = $this->refreshableAccount();
@@ -584,24 +750,35 @@ public function testLateSuccessCannotOverwriteAReplacedClaimWithTheSameRevision(
         $this->assertSame($successor, $account->fresh()->refresh_claim);
     }
 
-    public function testExpiredProviderResultIsNotStoredOrRetried(): void
+    public function testExpiredProviderResultRetainsRotatedCredentialsForALaterAttempt(): void
     {
         $account = $this->refreshableAccount();
         $calls = 0;
-        $authenticator = $account->authenticator(function () use (&$calls): OAuthAuthenticator {
+        $authenticator = $account->authenticator(function (OAuthAuthenticator $current) use (&$calls): OAuthAuthenticator {
             ++$calls;
 
-            return new AccessTokenAuthenticator('expired', expiresAt: Date::now()->toDateTimeImmutable());
+            if ($calls === 1) {
+                return new AccessTokenAuthenticator('expired', 'rotated', Date::now()->toDateTimeImmutable());
+            }
+
+            $this->assertSame('rotated', $current->getRefreshToken());
+
+            return new AccessTokenAuthenticator('usable');
         });
-        $this->expectException(UnexpectedValueException::class);
 
         try {
             $this->authorization($authenticator);
-        } finally {
-            $this->assertSame(1, $calls);
-            $this->assertSame('old', $account->fresh()->access_token);
-            $this->assertNull($account->fresh()->refresh_claim);
+            $this->fail('An expired token must not be used.');
+        } catch (UnexpectedValueException $exception) {
+            $this->assertSame('The refreshed OAuth token has already expired.', $exception->getMessage());
         }
+
+        $this->assertSame(1, $calls);
+        $this->assertSame('expired', $account->fresh()->access_token);
+        $this->assertSame('rotated', $account->fresh()->refresh_token);
+        $this->assertNull($account->fresh()->refresh_claim);
+        $this->assertSame('Bearer usable', $this->authorization($authenticator));
+        $this->assertSame(2, $calls);
     }
 
     public function testUnrefreshableTokenWorksUntilItsActualExpiry(): void

From f4b8272105ecfe0484458f717ef460beb7dbf5e7 Mon Sep 17 00:00:00 2001
From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com>
Date: Sat, 24 Oct 2026 20:24:47 +0000
Subject: [PATCH 8/8] Clarify OAuth account transaction and renewal guarantees

Document use of unexpired, unclaimed credentials inside caller transactions and rejection before waiting when renewal is required. Explain why an expired access result is not used even though its rotated refresh credentials are retained, including the exception applications receive.

Describe partition checks on normal saves and deletes and the prohibition on moving an existing account between partitions. Align the implementation plan with date-cast conventions, write-alias identity, conditional credential persistence and the current PR review state.
---
 ...0-24-1738-saloon-oauth-token-management.md | 22 +++++++++----------
 src/docs/saloon.md                            |  6 +++--
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md b/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
index 5f2982079..2e018f88c 100644
--- a/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
+++ b/docs/plans/2026-10-24-1738-saloon-oauth-token-management.md
@@ -9,7 +9,7 @@ Add two opt-in capabilities to `hypervel/saloon`:
 
 Keep manual grant methods, immutable connectors, existing authenticators, request modifiers and application-owned provider credentials. Applications choose their cache stores and publish the account migration only when using durable accounts. No new package, store-driver abstraction, provider registry, scheduler or UI is needed.
 
-Status: implemented, verified and reviewed; ready for a framework PR. The only approved existing API departure is scope metadata on `OAuthAuthenticator`, `AccessTokenAuthenticator` and the corresponding grant factories. No Socialite API change is required.
+Status: in PR review; complete the remaining CI/bot review cycle before merge. The only approved existing API departure is scope metadata on `OAuthAuthenticator`, `AccessTokenAuthenticator` and the corresponding grant factories. No Socialite API change is required.
 
 ## Existing boundaries and evidence
 
@@ -138,11 +138,11 @@ Add `make:oauth-accounts-table`, alias `oauth-accounts:table`, using `MigrationG
 | `owner_type`, `owner_id` | Morph owner, using framework morph-key conventions |
 | `provider`, nullable `provider_account_id` | Provider reference and optional external account identifier |
 | `access_token`, nullable `refresh_token` | Text columns, encrypted casts and hidden serialization |
-| nullable `expires_at` | UTC `dateTime`, immutable cast |
-| nullable `refresh_at` | UTC `dateTime`, immutable cast; fixed early-renewal time calculated when credentials are installed |
+| nullable `expires_at` | `dateTime`, immutable cast using the application's date conventions |
+| nullable `refresh_at` | `dateTime`, immutable cast; fixed early-renewal time calculated when credentials are installed |
 | nullable `scopes` | `text()`, array cast; opaque list read back whole, preserving omission versus empty set |
 | `credential_revision` | Fresh UUID whenever credentials change |
-| nullable `refresh_claim`, `refresh_started_at` | UUID ownership of one renewal attempt and UTC `timestamp()` recording its start |
+| nullable `refresh_claim`, `refresh_started_at` | UUID ownership of one renewal attempt and `timestamp()` recording its start |
 | timestamps | Ordinary created/updated timestamps |
 
 Index owner lookup and provider/external-account lookup. Do not impose uniqueness on owner + provider + external account: distinct client registrations or permission grants may legitimately share those values. Reconnect replaces a selected account row's credentials; it is not inferred from that tuple.
@@ -160,7 +160,7 @@ Add `saloon.oauth_accounts.cache` with `enabled` (false), `store` (null = framew
 - Cache enabled: use `ModelCacheCoordinator` and `ModelCacheStoreValidator`; cache a relations-unset model, using normal encrypted casts and model serialization. Register the configured model with the cache serialization policy.
 - Warm cache hits require no database query and no per-request write. No `last_used_at` update or worker-lifetime private token slot for durable accounts.
 - Cache disabled: read the authoritative row; renewal still uses the shared lock store.
-- Key identity encodes model class, captured resolved connection **name**, table name, account ID and partition, hashed with SHA-256. Capture the selected connection name even when the model normally follows the default. Do not inspect physical database configuration; connection names separate ordinary multiple-connection/table uses, while the partition separates scoped databases behind one connection. Reuse the identity for reads, writes, invalidation and locks; cache-fill and renewal locks are distinct.
+- Key identity encodes model class, captured resolved connection **name**, table name, account ID and partition, hashed with SHA-256. Capture the selected connection even when the model follows the default. Write aliases retain their requested connection for transactions but normalize to the base name in the hash. Do not inspect physical database configuration. Reuse the identity for reads, writes, invalidation and locks; cache-fill and renewal locks are distinct.
 - Stores must span the deployment using those accounts. Redis/database suit multiple hosts; file/Swoole scope must match the deployment. Reject worker-local/stack/failover stores for durable credential caching; never hide a cache outage by serving stale credentials.
 - Use writer reads for renewal and recovery. Never publish uncommitted credentials. Cache writes and invalidations follow `afterCommitOrNow`; normal application transactions bypass shared fills through the existing coordinator.
 
@@ -173,18 +173,18 @@ Renewal uses a short cache lock for waiting and a committed row claim for coordi
 When installing credentials, compute `refresh_at` once using the same expiry calculation as cached acquisition: `expires_at - min(30 seconds, remaining lifetime / 2)`. Recompute on successful renewal or a replacement access token/expiry, never on cache reads or unrelated metadata saves. Persisting this deadline avoids both resetting it on reads and immediately re-renewing short-lived tokens.
 
 - Before `refresh_at`, apply usable credentials without renewal. A current claim still takes precedence over the old token.
-- At/after `refresh_at`, renew if a refresh token exists. Without one, use the access token until its actual expiry, then throw `OAuthAccountReconnectRequiredException` before taking a claim.
+- At/after `refresh_at`, renew if a refresh token exists. Inside a caller transaction, defer early renewal while the token remains unexpired and has no claim. Without a refresh token, use the access token until its actual expiry, then throw `OAuthAccountReconnectRequiredException` before taking a claim.
 - No expiry means no automatic renewal and a null renewal time.
 
 ### One attempt
 
-1. Resolve/check the current partition, then enter worker-local acquisition coordination. Existing same-worker waiters share the entire bounded attempt chain and its final result/error.
-2. Acquire the account's cache lock, then reread the writer. If another attempt installed usable credentials, use them. Missing/deleted accounts fail; never recreate them. A present claim blocks use of the old token because some providers invalidate it immediately on refresh.
-3. Reject renewal while the account connection has an applicable caller transaction. This avoids remote rotation followed by rollback, uncommitted account reads, and caller/child row-lock deadlocks. Do not escape the caller into a detached coroutine.
+1. Resolve/check the current partition and read credentials. Inside an applicable caller transaction, an unexpired token without a claim remains usable, including during the early-renewal window. Otherwise reject renewal before waiting or contacting the provider. Do not escape the caller into a detached coroutine.
+2. Enter worker-local acquisition coordination. Existing same-worker waiters share the entire bounded attempt chain and its final result/error.
+3. Acquire the account's cache lock, then reread the writer. If another attempt installed usable credentials, use them. Missing/deleted accounts fail; never recreate them. A present claim blocks use of the old token because some providers invalidate it immediately on refresh.
 4. Validate locally before claiming. Atomically set a fresh `refresh_claim` UUID and `refresh_started_at`, conditioned on account, partition, credential revision and a null or abandoned claim. A claim is abandoned after 300 seconds. This is a recovery interval, not proof that the old provider operation has ended.
 5. Commit the claim and invalidate its cache before provider I/O. Proceed only when one row changed; an uncertain claim write does not authorize a provider request. Release idle database connections.
 6. Invoke one provider refresh attempt. The Saloon convenience applies the caller's modifier, then disables transport retries for this request. Custom callbacks must also perform one provider attempt.
-7. On success, reject an already-expired result, prepare encrypted credentials through the model's casts, retain omitted refresh token/scopes, calculate `refresh_at`, and conditionally store credentials + a fresh revision + cleared claim. Match account, partition, read credential revision **and claim UUID**. Commit and invalidate before exposing the result through the model's token factory. On a lost comparison, reread the account; never return the losing result or overwrite a reconnect. Do not repeat provider refresh merely because persistence or cache invalidation failed.
+7. On success, prepare encrypted credentials through the model's casts, retain omitted refresh token/scopes, calculate `refresh_at`, and conditionally store credentials + a fresh revision + cleared claim. Match account, partition, read credential revision **and claim UUID**. Commit and invalidate before exposing the result through the model's token factory. Reject an expired access token after persistence so its rotated refresh token remains available for a later attempt; do not retry immediately. On a lost comparison, reread the account; never return the losing result or overwrite a reconnect. Do not repeat provider refresh merely because persistence or cache invalidation failed.
 8. On failure/cancellation, conditionally clear only this attempt's claim and invalidate. Do not clear a successor's claim. A process crash or failed cleanup leaves a reclaimable claim. Propagate cancellation unchanged; never start its next retry. Preserve the primary failure if cleanup also fails, reporting the cleanup failure without credentials.
 9. Release the cache lock in `finally`. No transaction or pooled connection is held while waiting or during HTTP.
 
@@ -207,7 +207,7 @@ Tests must exercise late completion after claim replacement and cancellation, no
 
 Expose boot-only `OAuthAccounts::resolvePartitionUsing(string $column, Closure $resolver)`, beside `useAccountModel()` and its `accountModel()` getter. Follow Permission's SQL-column validation and registration-before-use guard. Seal configuration on first account operation, not a harmless model-class getter, so application boot can override a default model before use. A configured resolver returns the current nonempty string or integer partition; missing context fails explicitly. An unconfigured ordinary application has no partition column requirement.
 
-- Creating an account fills the partition column from the resolver and rejects a conflicting supplied value.
+- Creating an account fills the partition column from the resolver and rejects a conflicting supplied value. Existing accounts cannot change partition; normal saves and deletes validate the current partition before writing.
 - Capture the **persisted** partition when constructing its authenticator. Validate it against the current resolver on every apply, including cache hits, and after yielding before using credentials or publishing changes.
 - Saloon's account reads, claims, conditional writes and invalidations always include that partition. A UUID alone is not authorization.
 - Do not add an application-wide Eloquent global scope in Saloon. Applications/integrations own query policy and schema columns. A model scope alone cannot protect warmed cache entries or retained authenticators.
diff --git a/src/docs/saloon.md b/src/docs/saloon.md
index 088db2979..cc6018d40 100644
--- a/src/docs/saloon.md
+++ b/src/docs/saloon.md
@@ -1823,7 +1823,9 @@ The default response-cache key includes the bearer token, so renewed tokens no l
 
 Saloon records a fixed early-renewal deadline when credentials are saved. A token without a refresh token remains usable until its actual expiry, then throws `Hypervel\Saloon\Exceptions\OAuthAccountReconnectRequiredException`. Catch this exception to prompt the user to reconnect. Tokens without expiry do not renew automatically.
 
-Renewal rereads the account, records ownership of the attempt, then calls the provider without holding an idle database connection. The replacement is stored before it is applied to a request. A concurrent reconnect, deletion or replacement attempt cannot be overwritten by a late result. Renewal is rejected inside a transaction on the account connection, before contacting the provider.
+Renewal rereads the account, records ownership of the attempt, then calls the provider without holding an idle database connection. The replacement is stored before it is applied to a request. A concurrent reconnect, deletion or replacement attempt cannot be overwritten by a late result. Inside a transaction on the account connection, Saloon uses an unexpired token when no attempt holds a refresh claim, deferring early renewal. Otherwise, it rejects renewal before waiting or contacting the provider.
+
+If the returned access token has already expired, Saloon stores the replacement credentials and throws an `UnexpectedValueException` instead of using it. This preserves a rotated refresh token for a later attempt without immediately calling the provider again.
 
 Transient connection failures, selected HTTP errors and temporary OAuth errors receive up to three attempts, with jittered delays capped at 250 and 500 milliseconds. Each attempt rereads current credentials. Longer `Retry-After` delays are returned to the caller for later scheduling. The connector convenience disables nested HTTP retries; custom refresh callbacks must also make one provider attempt per invocation.
 
@@ -1844,7 +1846,7 @@ use Hypervel\Saloon\OAuthAccounts;
 OAuthAccounts::resolvePartitionUsing('tenant_id', fn () => $tenancy->currentKey());
 ```
 
-Add the partition column and suitable indexes to your published migration. The callback should capture a worker-safe context service and resolve the current key when called. Missing context fails explicitly. New accounts receive that partition, and retained authenticators are checked against it on every use, including warm cache reads and after provider calls.
+Add the partition column and suitable indexes to your published migration. The callback should capture a worker-safe context service and resolve the current key when called. Missing context fails explicitly. New accounts receive that partition and cannot move to another partition. Normal saves and deletes are rejected outside the account's partition. Retained authenticators are checked against it on every use, including warm cache reads and after provider calls.
 
 Your model or integration still owns application-wide query scoping; Saloon does not install a global Eloquent scope. Platform-owned accounts use an explicit platform partition. Cached client-credentials tokens use grant identity instead, allowing identical platform credentials to share a token. Keep merchant-specific headers on the request or connector.