Keep Spotify sessions alive with the refresh token

Login now keeps Spotify's refresh token and when the access token
expires. Each request refreshes the token in the minute before it
expires, and a 401 gets one retry with a renewed token, reusing one
another request or tab already fetched. Overlapping refreshes share a
single request, use the client ID that logged in, and store a rotated
refresh token. Only when Spotify refuses the refresh, or no refresh
token was stored, does the user go back to login; the refusal is
reported without the token. A long Export All now outlives the one-hour
token (#225).

apiCall reads the stored token for each request rather than having it
threaded through every component and data class, so a refreshed token
reaches exports already in progress.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: watsonbox

src/App.test.tsx

@@ -151,12 +151,13 @@ describe("logging in", () => {
     expect(window.location.search).toBe("")
   })
 
-  test("renders the playlist table when an access token is already stored", () => {
+  test("renders the playlist table when an access token is already stored", async () => {
     localStorage.setItem("access_token", "TEST_ACCESS_TOKEN")
 
     render(<App />)
 
     expect(screen.getByTestId("playlistTableSpinner")).toBeInTheDocument()
+    expect(await screen.findByText(/Export All/)).toBeInTheDocument()
   })
 })
 

src/App.tsx

@@ -93,7 +93,7 @@ function App() {
   }, [])
 
   if (accessToken) {
-    view = <PlaylistTable accessToken={accessToken!} onSetSubtitle={onSetSubtitle} />
+    view = <PlaylistTable onSetSubtitle={onSetSubtitle} />
   } else {
     view = <>
       {loginError && (

src/auth.test.ts

@@ -1,20 +1,54 @@
 import { http, HttpResponse } from "msw"
 import { server } from "./mocks/server"
 import { redirectTo } from "./navigation"
-import { exchangeCodeForToken, logout } from "./auth"
+import { captureBugsnagReports } from "./test/bugsnag"
+import { currentAccessToken, exchangeCodeForToken, logout, refreshAccessToken, SessionExpiredError } from "./auth"
+import grantedToken from "./test/fixtures/spotify/documented/token.json"
+import refreshedToken from "./test/fixtures/spotify/documented/token-refresh.json"
+import revokedRefreshToken from "./test/fixtures/spotify/documented/token-refresh-revoked.json"
+
+const tokenUrl = "https://accounts.spotify.com/api/token"
+const HOUR = 60 * 60 * 1000
+
+// Records each token request body and answers with respond
+function mockTokenEndpoint(respond: () => Response | Promise<Response>) {
+  const requests: URLSearchParams[] = []
+  server.use(http.post(tokenUrl, async ({ request }) => {
+    requests.push(new URLSearchParams(await request.text()))
+    return respond()
+  }))
+  return requests
+}
+
+const refresh = (body: object = refreshedToken.body) => () => HttpResponse.json(body)
+const revoke = () => HttpResponse.json(revokedRefreshToken.body, { status: revokedRefreshToken.status })
+
+function logIn({ expiresAt = Date.now() + HOUR, clientId }: { expiresAt?: number, clientId?: string } = {}) {
+  localStorage.setItem("access_token", "TEST_ACCESS_TOKEN")
+  localStorage.setItem("refresh_token", "TEST_REFRESH_TOKEN")
+  localStorage.setItem("token_expires_at", String(expiresAt))
+  if (clientId) { localStorage.setItem("client_id", clientId) }
+}
 
 beforeEach(() => {
+  vi.useFakeTimers({ toFake: ["Date"] })
   window.history.replaceState(null, "", "/exportify")
 })
 
+afterEach(() => {
+  vi.useRealTimers()
+})
+
 describe("exchangeCodeForToken", () => {
-  test("stores the token and discards the single-use code verifier", async () => {
-    server.use(http.post("https://accounts.spotify.com/api/token", () =>
-      HttpResponse.json({ access_token: "TEST_ACCESS_TOKEN", token_type: "Bearer", expires_in: 3600 })))
+  test("stores the tokens and their expiry, and discards the single-use code verifier", async () => {
+    server.use(http.post(tokenUrl, () => HttpResponse.json(grantedToken.body)))
     localStorage.setItem("code_verifier", "TEST_CODE_VERIFIER")
+    const now = Date.now()
 
     await expect(exchangeCodeForToken("TEST_AUTH_CODE")).resolves.toBe("TEST_ACCESS_TOKEN")
     expect(localStorage.getItem("access_token")).toBe("TEST_ACCESS_TOKEN")
+    expect(localStorage.getItem("refresh_token")).toBe("TEST_REFRESH_TOKEN")
+    expect(localStorage.getItem("token_expires_at")).toBe(String(now + HOUR))
     expect(localStorage.getItem("code_verifier")).toBeNull()
   })
 
@@ -33,11 +67,124 @@ describe("exchangeCodeForToken", () => {
   })
 })
 
+describe("refreshAccessToken", () => {
+  test("exchanges the refresh token using the client ID that logged in", async () => {
+    const requests = mockTokenEndpoint(refresh())
+    logIn({ clientId: "CUSTOM_CLIENT_ID" })
+
+    await expect(refreshAccessToken()).resolves.toBe("REFRESHED_ACCESS_TOKEN")
+    expect(Object.fromEntries(requests[0])).toEqual({
+      grant_type: "refresh_token",
+      refresh_token: "TEST_REFRESH_TOKEN",
+      client_id: "CUSTOM_CLIENT_ID",
+    })
+  })
+
+  test("stores the new access token, its expiry and the rotated refresh token", async () => {
+    mockTokenEndpoint(refresh())
+    logIn({ expiresAt: Date.now() })
+    const now = Date.now()
+
+    await refreshAccessToken()
+
+    expect(localStorage.getItem("access_token")).toBe("REFRESHED_ACCESS_TOKEN")
+    expect(localStorage.getItem("token_expires_at")).toBe(String(now + HOUR))
+    expect(localStorage.getItem("refresh_token")).toBe("ROTATED_REFRESH_TOKEN")
+  })
+
+  test("keeps the refresh token when Spotify doesn't rotate it", async () => {
+    const { refresh_token: _, ...withoutRefreshToken } = refreshedToken.body
+    mockTokenEndpoint(refresh(withoutRefreshToken))
+    logIn()
+
+    await refreshAccessToken()
+
+    expect(localStorage.getItem("refresh_token")).toBe("TEST_REFRESH_TOKEN")
+  })
+
+  test("shares one request between overlapping refreshes", async () => {
+    const requests = mockTokenEndpoint(refresh())
+    logIn()
+
+    const tokens = await Promise.all([refreshAccessToken(), refreshAccessToken(), refreshAccessToken()])
+
+    expect(tokens).toEqual(["REFRESHED_ACCESS_TOKEN", "REFRESHED_ACCESS_TOKEN", "REFRESHED_ACCESS_TOKEN"])
+    expect(requests).toHaveLength(1)
+  })
+
+  test("refreshes again once the previous refresh has finished", async () => {
+    const requests = mockTokenEndpoint(refresh())
+    logIn()
+
+    await refreshAccessToken()
+    await refreshAccessToken()
+
+    expect(requests).toHaveLength(2)
+    expect(requests[1].get("refresh_token")).toBe("ROTATED_REFRESH_TOKEN")
+  })
+
+  test("ends the session when Spotify refuses the refresh token, reporting why but not the token", async () => {
+    const reports = captureBugsnagReports()
+    mockTokenEndpoint(revoke)
+    logIn()
+
+    await expect(refreshAccessToken()).rejects.toBeInstanceOf(SessionExpiredError)
+    expect(reports).toHaveLength(1)
+    expect(reports[0].groupingHash).toBe("Token refresh: Spotify: invalid_grant (Refresh token revoked)")
+    expect(reports[0].metadata).toEqual({ oauth: { status: 400, error: "invalid_grant", error_description: "Refresh token revoked" } })
+    expect(JSON.stringify(reports)).not.toContain("TEST_REFRESH_TOKEN")
+  })
+
+  test("ends the session without calling Spotify when no refresh token was stored", async () => {
+    const reports = captureBugsnagReports()
+    const requests = mockTokenEndpoint(refresh())
+    localStorage.setItem("access_token", "TEST_ACCESS_TOKEN")
+
+    await expect(refreshAccessToken()).rejects.toBeInstanceOf(SessionExpiredError)
+    expect(requests).toHaveLength(0)
+    expect(reports).toEqual([])
+  })
+
+  test("passes on a network failure so the request can be retried", async () => {
+    mockTokenEndpoint(() => HttpResponse.error())
+    logIn()
+
+    await expect(refreshAccessToken()).rejects.toMatchObject({ code: "ERR_NETWORK" })
+    expect(localStorage.getItem("refresh_token")).toBe("TEST_REFRESH_TOKEN")
+  })
+})
+
+describe("currentAccessToken", () => {
+  test("is the stored token while it has time left", async () => {
+    const requests = mockTokenEndpoint(refresh())
+    logIn()
+    vi.setSystemTime(Date.now() + HOUR - 2 * 60 * 1000)
+
+    await expect(currentAccessToken()).resolves.toBe("TEST_ACCESS_TOKEN")
+    expect(requests).toHaveLength(0)
+  })
+
+  test("is refreshed in the last minute before expiry", async () => {
+    mockTokenEndpoint(refresh())
+    logIn()
+    vi.setSystemTime(Date.now() + HOUR - 30 * 1000)
+
+    await expect(currentAccessToken()).resolves.toBe("REFRESHED_ACCESS_TOKEN")
+  })
+
+  test("is the stored token for a login from before refresh tokens were kept", async () => {
+    const requests = mockTokenEndpoint(refresh())
+    localStorage.setItem("access_token", "TEST_ACCESS_TOKEN")
+
+    await expect(currentAccessToken()).resolves.toBe("TEST_ACCESS_TOKEN")
+    expect(requests).toHaveLength(0)
+  })
+})
+
 describe("logout", () => {
   test("clears stored credentials and returns to the current page", () => {
-    localStorage.setItem("access_token", "TEST_ACCESS_TOKEN")
+    logIn({ clientId: "CUSTOM_CLIENT_ID" })
     localStorage.setItem("code_verifier", "TEST_CODE_VERIFIER")
-    localStorage.setItem("client_id", "CUSTOM_CLIENT_ID")
 
     logout()
 

src/auth.ts

@@ -2,29 +2,98 @@
 // - https://developer.spotify.com/documentation/web-api/tutorials/migration-implicit-auth-code
 // - https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow
 
+import Bugsnag from "@bugsnag/js"
 import axios from "axios"
 import { redirectTo } from "./navigation"
 
 const SPOTIFY_CLIENT_ID = "9950ac751e34487dbbe027c4fd7f8e99"
 const SPOTIFY_AUTH_URL = "https://accounts.spotify.com/authorize"
 const SPOTIFY_TOKEN_URL = "https://accounts.spotify.com/api/token"
 const SPOTIFY_SCOPES = "playlist-read-private playlist-read-collaborative user-library-read"
+const EXPIRY_MARGIN = 60 * 1000
+
+type TokenResponse = { access_token: string, expires_in: number, refresh_token?: string }
 
 // Access token management
 export function loadAccessToken(): string | null {
   return localStorage.getItem('access_token')
 }
 
-export function saveAccessToken(token: string): void {
-  localStorage.setItem('access_token', token)
+// Spotify may rotate the refresh token, so a response without one keeps the old
+function saveTokens({ access_token, expires_in, refresh_token }: TokenResponse): void {
+  localStorage.setItem('access_token', access_token)
+  localStorage.setItem('token_expires_at', String(Date.now() + expires_in * 1000))
+  if (refresh_token) { localStorage.setItem('refresh_token', refresh_token) }
 }
 
 export function clearAccessToken(): void {
   localStorage.removeItem('access_token')
+  localStorage.removeItem('refresh_token')
+  localStorage.removeItem('token_expires_at')
   localStorage.removeItem('code_verifier')
   localStorage.removeItem('client_id')
 }
 
+// Thrown when the session can't be renewed and the user has to log in again
+export class SessionExpiredError extends Error {
+  constructor() {
+    super('Spotify session expired')
+    this.name = 'SessionExpiredError'
+  }
+}
+
+let refreshing: Promise<string> | null = null
+
+// Overlapping callers share one refresh, since each would otherwise spend the same single-use refresh token
+export function refreshAccessToken(): Promise<string> {
+  refreshing ??= requestRefresh().finally(() => { refreshing = null })
+  return refreshing
+}
+
+async function requestRefresh(): Promise<string> {
+  const refreshToken = localStorage.getItem('refresh_token')
+  if (!refreshToken) { throw new SessionExpiredError() }
+
+  try {
+    const response = await axios.post(
+      SPOTIFY_TOKEN_URL,
+      new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: localStorage.getItem('client_id') || SPOTIFY_CLIENT_ID,
+      }),
+      { headers: { "Content-Type": "application/x-www-form-urlencoded" } }
+    )
+    saveTokens(response.data)
+    return response.data.access_token
+  } catch (error: any) {
+    // With no response it's the connection, which the request's own retries can ride out
+    if (!error.response) { throw error }
+
+    reportRefreshFailure(error)
+    throw new SessionExpiredError()
+  }
+}
+
+// Sends Spotify's reason but never the request, whose body holds the refresh token
+function reportRefreshFailure(error: any) {
+  const { status, data } = error.response
+  const reason = data?.error_description ? `${data.error} (${data.error_description})` : data?.error ?? status
+
+  Bugsnag.notify(new Error(`Token refresh failed: ${reason}`), (event) => {
+    event.groupingHash = `Token refresh: Spotify: ${reason}`
+    event.addMetadata("oauth", { status, error: data?.error, error_description: data?.error_description })
+  })
+}
+
+// The stored access token, refreshed first if it's about to expire
+export async function currentAccessToken(): Promise<string | null> {
+  const expiresAt = Number(localStorage.getItem('token_expires_at'))
+  if (expiresAt && Date.now() >= expiresAt - EXPIRY_MARGIN) { return refreshAccessToken() }
+
+  return loadAccessToken()
+}
+
 // Generate code verifier for PKCE flow
 function generateCodeVerifier(): string {
   const possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
@@ -120,13 +189,11 @@ export async function exchangeCodeForToken(code: string): Promise<string> {
     }
   )
 
-  const accessToken = response.data.access_token
-
   // The verifier is single-use, like the code it was paired with
-  saveAccessToken(accessToken)
+  saveTokens(response.data)
   localStorage.removeItem('code_verifier')
 
-  return accessToken
+  return response.data.access_token
 }
 
 // Logout and optionally redirect to change user

src/components/PlaylistExporter.test.ts

@@ -16,11 +16,15 @@ const playlist = buildPlaylist({ id: 'p1', name: 'Mixtape', tracks: { total: 1 }
 const serveTracks = (...tracks: object[]) =>
   server.use(pagedGet(`${API}/playlists/p1/tracks`, tracks.map(track => buildPlaylistItem({ track, added_by: buildUser({ id: 'dj' }), added_at: '2024-01-02T03:04:05Z' }))))
 
+beforeEach(() => {
+  localStorage.setItem("access_token", "TEST_ACCESS_TOKEN")
+})
+
 describe("PlaylistExporter", () => {
   test("puts base track columns before the item columns", async () => {
     serveTracks(buildTrack())
 
-    const csv = await new PlaylistExporter('TEST_ACCESS_TOKEN', playlist, {}).csvData()
+    const csv = await new PlaylistExporter(playlist, {}).csvData()
 
     expect(csvHeaders(csv)).toEqual(baseHeaders)
   })
@@ -34,7 +38,7 @@ describe("PlaylistExporter", () => {
     )
     const config = { includeArtistsData: true, includeAudioFeaturesData: true, includeAlbumData: true }
 
-    const csv = await new PlaylistExporter('TEST_ACCESS_TOKEN', playlist, config).csvData()
+    const csv = await new PlaylistExporter(playlist, config).csvData()
 
     expect(csvHeaders(csv).slice(baseHeaders.length)).toEqual([
       "Artist Genres",
@@ -47,7 +51,7 @@ describe("PlaylistExporter", () => {
   test("quotes every field so commas, quotes and newlines survive", async () => {
     serveTracks(buildTrack({ id: 't1', name: 'Say "Hi",\nthen leave', artists: [buildArtist({ name: 'A, B' })] }))
 
-    const csv = await new PlaylistExporter('TEST_ACCESS_TOKEN', playlist, {}).csvData()
+    const csv = await new PlaylistExporter(playlist, {}).csvData()
 
     expect(csvRecords(csv)).toEqual([expect.objectContaining({
       "Track URI": "spotify:track:t1",
@@ -64,7 +68,7 @@ describe("PlaylistExporter", () => {
     ['tabs\tand "quotes"', 'tabs_and_quotes_'],
     ['Déjà Vu', 'déjà_vu'],
   ])("names the file for %j as %j", (name, fileName) => {
-    const exporter = new PlaylistExporter('TEST_ACCESS_TOKEN', { ...playlist, name }, {})
+    const exporter = new PlaylistExporter({ ...playlist, name }, {})
 
     expect(exporter.fileName(false)).toBe(fileName)
     expect(exporter.fileName()).toBe(`${fileName}.csv`)