feat: configure transparent OAuth token refresh via auth.oauth by joshuaellis · Pull Request #1323 · sanity-io/client

joshuaellis · 2026-09-03T12:48:38Z

Description

Apps authenticating with short-lived OAuth access tokens would have to catch 401s, refresh, and re-create clients themselves which is annoying for everyone involved.

This lets the client own that instead: configure auth.oauth with an OAuthTokenSetup and requests, live streams, and uploads stay authenticated across token rotations without the app noticing. When a token genuinely can't be refreshed because the session is over then the app gets a single onAuthError signal to send the user back through login, instead of scattered 401s.

Note

High Risk
Touches authentication across HTTP, uploads, and long-lived SSE connections, including refresh deduplication and 401/reconnect semantics that affect session security.

Overview
Adds auth.oauth (OAuthTokenSetup with getToken, refresh, optional getExpiresAt / onAuthError) as an alternative to a static token, with config validation that the two cannot be combined.

A new oauthRefreshHandler wraps the normal request pipeline: proactive refresh before expiry, single-flight refresh() across concurrent callers, one automatic retry on 401 for fetch-based APIs, and onAuthError when refresh fails. The same setup is wired into paths that skip the default handler—asset uploads (fetch and XHR), listen / live EventSource (Bearer resolved per fetch, including reconnects), plus 401-driven reconnect with token refresh and Last-Event-ID resume so SSE can continue after auth recovery.

Uploads do not auto-retry after 401 (body may be consumed); they still refresh so a caller retry gets a new token.

^{Reviewed by Cursor Bugbot for commit 371fd57. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-09-03T12:48:45Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
tsdocs-client	Ignored		Sep 21, 2026 2:21pm UTC

github-actions · 2026-09-03T12:49:16Z

📚 TypeDoc Generation Result

✅ TypeDoc generated successfully!

File size: 4.1M
Total exports: 254
Artifact: typedoc-78bf7fe61da273b9b0f53124a2fd72bfb61afd18
HTML docs preview: Download artifact

The TypeDoc JSON file has been generated and validated. All documentation scripts completed successfully.

github-actions · 2026-09-03T12:49:37Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	84.16%	1998 / 2374
🔵	Statements	83.81%	2076 / 2477
🔵	Functions	78.92%	543 / 688
🔵	Branches	83.12%	1463 / 1760

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/config.ts	92.1%	91.75%	100%	92%	27, 78-79, 105, 108, 115-117
src/types.ts	100%	100%	100%	100%
src/assets/AssetsClient.ts	63.93%	50.87%	73.33%	66.1%	232-234, 259-283, 292-303, 322-324, 334, 347-353
src/data/dataMethods.ts	86.89%	92.96%	74.76%	87%	290, 353-354, 448-481, 517-578, 667, 708-709, 1268-1292, 1298, 1306, 1324
src/data/listen.ts	100%	100%	100%	100%
src/data/live.ts	95.65%	93.9%	94.73%	98.82%	175, 260, 294
src/data/reconnectOnConnectionFailure.ts	87.5%	100%	75%	92.3%	72
src/data/resolveEventSourceFetch.ts	100%	100%	100%	100%
src/http/oauthRefreshHandler.ts	87.5%	75%	86.66%	97.87%	34, 145, 171, 177, 193

Generated in workflow #5140 for commit 371fd57 by the Vitest Coverage Report Action

cursor

Stale Bugbot comment from a previous run.

bjoerge · 2026-09-04T11:32:52Z


  return connectEventSource(initEventSource, listenFor).pipe(
-    reconnectOnConnectionFailure(),
+    reconnectOnConnectionFailure(tokenSetup && getOAuthRefresher(tokenSetup)),


I think this will break resumability as it will trigger a new listener request, which instantiates a new EventSource rather than reusing the existing one, bypassing the existing EventSource's built-in error/retry mechanism (which sends the Last-Event-ID header on reconnect, telling the server where to resume from).

I've had a look at producing tests which hopefully disproves your concern - let me know if i've missed a case worth having!

cursor

Stale Bugbot comment from a previous run.

cursor

Stale Bugbot comment from a previous run.

bjoerge · 2026-09-18T12:13:38Z

  /** @defaultValue true */
  useCdn?: boolean
-  token?: string
+  token?: string | OAuthTokenSetup


this is potentially breaking, no? a consumer doing e.g. Bearer ${client.config().token}. Should we consider a different field for OauthTokenSetup?

Yeah it would break TS because it could be an object instead of a string. I've updated to a separate field – lmk what you think.

bjoerge · 2026-09-18T12:32:37Z

+          lastAuthRetryAt = Date.now()
+          return concat(
+            of({type: 'reconnect' as const}),
+            from(refreshAuth()).pipe(


not a huge deal I think, but this calls refreshAuth() eagerly. Would be better to use defer(refreshAuth) here to make it call refreshAuth at subscription time.

TIL! Thanks ✅

bjoerge · 2026-09-18T12:39:46Z

-      for (const [key, value] of Object.entries(extraHeaders)) {
-        headers.set(key, value)
+      if (lastEventId && !headers.has('last-event-id')) {
+        headers.set('Last-Event-ID', lastEventId)


EventSource instances also tracks Last-Event-ID internally, how will these interact? We need to be extra careful here so we don't lose events or get duplicated delivery. Find it a bit hard to judge whether that's a real concern though 😅

The wrapper only sets the header when the package hasn't (!headers.has('last-event-id')), and both values come from the same source (#lastEventId, surfaced as message.lastEventId). So on a live instance's own reconnects the package's header wins; the client-tracked value only seeds a fresh instance. Added a test in 0be6f0e for the case that would go wrong: fresh instance seeded with evt-1, receives evt-2, drops, and its own reconnect sends evt-2.

I've (claude) tried to add tests to cover this. Beyond that i'm not sure how else we can test this – open to ideas.

bjoerge · 2026-09-18T12:42:04Z

+    // unhandled-rejection tracker flags a rejected promise in that gap.
+    // Attach a no-op handler synchronously; the rejection still propagates
+    // through the async return to the `eventsource` package's catch.
+    response.catch(() => {})


This feels like a hack to me. Any way we can avoid this?

Agree, reworked.

Co-authored-by: joshuaellis <37798644+joshuaellis@users.noreply.github.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 1e9840c. Configure here.}

pkg-pr-new · 2026-09-22T13:41:37Z

npm i https://pkg.pr.new/@sanity/client@1323

commit: 371fd57

squiggler-app Bot added a commit that referenced this pull request Sep 3, 2026

chore: update auto-generated changeset for PR #1323

63d82b6

joshuaellis mentioned this pull request Sep 3, 2026

feat(core): add OAuth authorization-code + PKCE auth mode sanity-io/sdk#1162

Merged

joshuaellis force-pushed the feat/SDK-2421 branch 3 times, most recently from 8ee8ab0 to d3395f1 Compare September 4, 2026 08:56

joshuaellis marked this pull request as ready for review September 4, 2026 09:15

joshuaellis requested review from bjoerge and ryanbonial September 4, 2026 09:15

cursor Bot reviewed Sep 4, 2026

View reviewed changes

Comment thread src/data/reconnectOnConnectionFailure.ts

bjoerge reviewed Sep 4, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

cursor Bot reviewed Sep 7, 2026

View reviewed changes

Comment thread src/http/oauthRefreshHandler.ts

joshuaellis force-pushed the feat/SDK-2421 branch 2 times, most recently from c2da3af to 07be524 Compare September 7, 2026 15:32

joshuaellis requested a review from bjoerge September 7, 2026 15:34

cursor Bot reviewed Sep 7, 2026

View reviewed changes

Comment thread src/http/requestOptions.ts Outdated

joshuaellis force-pushed the feat/SDK-2421 branch from 07be524 to 5d6b7fb Compare September 10, 2026 13:17

ryanbonial reviewed Sep 10, 2026

View reviewed changes

Comment thread test/resumability.test.ts Outdated

sanity-io deleted a comment from cursor Bot Sep 10, 2026

Copilot started work on behalf of joshuaellis September 10, 2026 17:44 View session

Copilot finished work on behalf of joshuaellis September 10, 2026 17:49

ryanbonial previously approved these changes Sep 10, 2026

View reviewed changes

bjoerge reviewed Sep 18, 2026

View reviewed changes

joshuaellis changed the title ~~feat: accept an OAuth token setup as token for transparent refresh~~ feat: configure transparent OAuth token refresh via auth.oauth Sep 21, 2026

joshuaellis dismissed ryanbonial’s stale review via 0be6f0e September 21, 2026 06:59

squiggler-app Bot added a commit that referenced this pull request Sep 21, 2026

chore: update auto-generated changeset for PR #1323

1064163

feat: accept an OAuth token setup as token for transparent refresh

427134a

joshuaellis and others added 4 commits September 21, 2026 08:06

feat: add proactive refresh

48e9c96

fix: preserve SSE resume position across OAuth reconnects

3d2a612

Co-authored-by: joshuaellis <37798644+joshuaellis@users.noreply.github.com>

chore: pr amends

0de9052

chore: update auto-generated changeset for PR #1323

1e9840c

joshuaellis force-pushed the feat/SDK-2421 branch from 1064163 to 1e9840c Compare September 21, 2026 07:07

joshuaellis requested a review from bjoerge September 21, 2026 07:07

cursor Bot reviewed Sep 21, 2026

View reviewed changes

Comment thread src/data/live.ts Outdated

Copilot started work on behalf of joshuaellis September 21, 2026 12:07 View session

Copilot finished work on behalf of joshuaellis September 21, 2026 12:07

joshuaellis added 2 commits September 21, 2026 15:11

fix: accept auth.oauth as credentials for live drafts

c86cd16

test: satisfy OAuthTokenSetup type in live drafts test

371fd57

bjoerge added the trigger: preview label Sep 22, 2026

Conversation

joshuaellis commented Sep 3, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

vercel Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 TypeDoc Generation Result

Uh oh!

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pkg-pr-new Bot commented Sep 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joshuaellis commented Sep 3, 2026 •

edited by cursor Bot

Loading

vercel Bot commented Sep 3, 2026 •

edited

Loading

github-actions Bot commented Sep 3, 2026 •

edited

Loading

github-actions Bot commented Sep 3, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading