musix-box 0.1.0

package/src/providers/spotify/spotify_oauth.ts

@@ -0,0 +1,197 @@
+/**
+ * Spotify's Authorization Code with PKCE flow.
+ *
+ * PKCE, not the plain Authorization Code flow, because this runs in a
+ * Cloudflare Worker with no place to keep a client secret safe from a
+ * request handler that also serves public endpoints. PKCE proves the token
+ * request came from whoever started the authorization request without
+ * needing a secret at all — that is the whole point of the extension.
+ */
+
+const SPOTIFY_AUTHORIZE_URL = "https://accounts.spotify.com/authorize";
+const SPOTIFY_TOKEN_URL = "https://accounts.spotify.com/api/token";
+
+/** Scopes this package's tools need, named for what each unlocks. */
+export const SPOTIFY_SCOPES = [
+  "user-library-read", // liked tracks, saved albums
+  "user-follow-read", // followed artists
+  "playlist-read-private", // the user's own and followed playlists
+  "playlist-read-collaborative",
+] as const;
+
+/** A code_verifier: 43-128 characters from Spotify's allowed alphabet. */
+const VERIFIER_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+const VERIFIER_LENGTH = 64;
+
+/**
+ * Generate a PKCE code verifier.
+ *
+ * @returns A random string in Spotify's allowed alphabet, long enough to
+ *   satisfy the 43-character minimum with margin.
+ */
+export function generateCodeVerifier(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(VERIFIER_LENGTH));
+  return Array.from(bytes, (byte) => VERIFIER_ALPHABET[byte % VERIFIER_ALPHABET.length]).join(
+    "",
+  );
+}
+
+/**
+ * Derive the S256 code challenge from a verifier, base64url-encoded per the
+ * PKCE spec (RFC 7636): standard base64, then `+`→`-`, `/`→`_`, padding
+ * stripped.
+ *
+ * @param verifier - The code verifier generated for this authorization.
+ * @returns The code challenge to send with the authorization request.
+ */
+export async function deriveCodeChallenge(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  const bytes = new Uint8Array(digest);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Build the URL to send the user to for Spotify's consent screen.
+ *
+ * @param options.clientId - This app's Spotify client ID.
+ * @param options.redirectUri - Must match one registered in the Spotify
+ *   dashboard exactly.
+ * @param options.codeChallenge - From {@link deriveCodeChallenge}.
+ * @param options.state - Opaque value round-tripped to the redirect, for
+ *   CSRF protection — the caller generates and verifies it.
+ * @returns The full authorize URL to redirect the user to.
+ */
+export function buildAuthorizeUrl(options: {
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+  state: string;
+}): string {
+  const url = new URL(SPOTIFY_AUTHORIZE_URL);
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("code_challenge", options.codeChallenge);
+  url.searchParams.set("scope", SPOTIFY_SCOPES.join(" "));
+  url.searchParams.set("state", options.state);
+  return url.toString();
+}
+
+export type SpotifyTokens = {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch milliseconds. Derived from `expires_in` at the moment of the call. */
+  expiresAt: number;
+};
+
+/**
+ * Exchange an authorization code for tokens.
+ *
+ * @param options.clientId - This app's Spotify client ID.
+ * @param options.redirectUri - Must match the one used in the authorize step.
+ * @param options.code - The `code` query parameter Spotify redirected back with.
+ * @param options.codeVerifier - The verifier generated for this authorization.
+ * @param options.now - Clock, injected so `expiresAt` is testable.
+ */
+export async function exchangeCodeForTokens(options: {
+  clientId: string;
+  redirectUri: string;
+  code: string;
+  codeVerifier: string;
+  now: () => number;
+}): Promise<SpotifyTokens> {
+  const response = await fetch(SPOTIFY_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      client_id: options.clientId,
+      code_verifier: options.codeVerifier,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Spotify token exchange failed: ${response.status} ${await response.text()}`);
+  }
+
+  const body = (await response.json()) as {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+  };
+
+  return {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: options.now() + body.expires_in * 1000,
+  };
+}
+
+/**
+ * Refresh an access token.
+ *
+ * Spotify's PKCE refresh may or may not return a new `refresh_token` — when
+ * it does not, the caller keeps using the one it already has. This function
+ * reflects that directly: `refreshToken` in the result is the one to store
+ * going forward, whether or not Spotify issued a new one.
+ *
+ * @param options.clientId - This app's Spotify client ID.
+ * @param options.refreshToken - The refresh token to use.
+ * @param options.now - Clock, injected so `expiresAt` is testable.
+ */
+export async function refreshAccessToken(options: {
+  clientId: string;
+  refreshToken: string;
+  now: () => number;
+}): Promise<SpotifyTokens> {
+  const response = await fetch(SPOTIFY_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: options.refreshToken,
+      client_id: options.clientId,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Spotify token refresh failed: ${response.status} ${await response.text()}`);
+  }
+
+  const body = (await response.json()) as {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+  };
+
+  return {
+    accessToken: body.access_token,
+    // Spotify's own documented behaviour: a refresh token is not guaranteed
+    // in every response, and when absent the existing one is still valid.
+    refreshToken: body.refresh_token ?? options.refreshToken,
+    expiresAt: options.now() + body.expires_in * 1000,
+  };
+}
+
+/**
+ * Whether a token is due for refresh.
+ *
+ * @param tokens - The stored tokens.
+ * @param options.now - Clock.
+ * @param options.marginMs - How long before actual expiry to refresh early,
+ *   so a request in flight does not race the token's own expiry.
+ */
+export function needsRefresh(
+  tokens: SpotifyTokens,
+  options: { now: () => number; marginMs: number },
+): boolean {
+  return options.now() >= tokens.expiresAt - options.marginMs;
+}

package/src/providers/spotify/spotify_provider.ts

@@ -0,0 +1,159 @@
+/**
+ * `MediaProvider` implemented against the real Spotify Web API.
+ *
+ * Maps Spotify's own response shapes onto the shared interface. Two of
+ * Spotify's list endpoints paginate by numeric offset (saved tracks, saved
+ * albums, playlists, playlist tracks) and one paginates by cursor (followed
+ * artists) — `Page.nextCursor` is opaque on purpose so this difference never
+ * has to leak past this file.
+ */
+
+import {
+  LIBRARY_MAX_LIMIT,
+  SEARCH_MAX_LIMIT,
+  SpotifyApiClient,
+  type SpotifyAlbum,
+  type SpotifyArtist,
+  type SpotifyPagingObject,
+  type SpotifyPlaylist,
+  type SpotifyTrack,
+} from "./spotify_api_client";
+import type {
+  Album,
+  Artist,
+  MediaProvider,
+  Page,
+  Playlist,
+  SearchType,
+  Track,
+} from "../media_provider";
+
+function toTrack(track: SpotifyTrack): Track {
+  return {
+    id: track.id,
+    name: track.name,
+    artistNames: track.artists.map((artist) => artist.name),
+    albumName: track.album.name,
+    durationMs: track.duration_ms,
+    uri: track.uri,
+  };
+}
+
+function toArtist(artist: SpotifyArtist): Artist {
+  return { id: artist.id, name: artist.name, genres: artist.genres, uri: artist.uri };
+}
+
+function toAlbum(album: SpotifyAlbum): Album {
+  return {
+    id: album.id,
+    name: album.name,
+    artistNames: album.artists.map((artist) => artist.name),
+    releaseDate: album.release_date,
+    uri: album.uri,
+  };
+}
+
+function toPlaylist(playlist: SpotifyPlaylist): Playlist {
+  return {
+    id: playlist.id,
+    name: playlist.name,
+    ownerName: playlist.owner.display_name ?? playlist.owner.id,
+    trackCount: playlist.tracks.total,
+    uri: playlist.uri,
+  };
+}
+
+/** Offset-paginated Spotify endpoints all share this cursor shape: the next offset, as a string. */
+function offsetPage<SpotifyItem, Item>(
+  paging: SpotifyPagingObject<SpotifyItem>,
+  map: (item: SpotifyItem) => Item,
+): Page<Item> {
+  return {
+    items: paging.items.map(map),
+    nextCursor: paging.next === null ? null : String(paging.offset + paging.items.length),
+    total: paging.total,
+  };
+}
+
+const emptyPage = <Item>(): Page<Item> => ({ items: [], nextCursor: null, total: 0 });
+
+export class SpotifyProvider implements MediaProvider {
+  readonly name = "spotify";
+  private readonly client: SpotifyApiClient;
+
+  constructor(accessToken: string) {
+    this.client = new SpotifyApiClient(accessToken);
+  }
+
+  async search(
+    query: string,
+    options: { types?: SearchType[]; limit?: number; cursor?: string } = {},
+  ): Promise<{
+    tracks: Page<Track>;
+    artists: Page<Artist>;
+    albums: Page<Album>;
+    playlists: Page<Playlist>;
+  }> {
+    const types = options.types ?? (["track", "artist", "album", "playlist"] as const);
+    const limit = Math.min(options.limit ?? SEARCH_MAX_LIMIT, SEARCH_MAX_LIMIT);
+    const offset = options.cursor ? Number(options.cursor) : 0;
+
+    const result = await this.client.search(query, [...types], { limit, offset });
+
+    return {
+      tracks: result.tracks ? offsetPage(result.tracks, toTrack) : emptyPage(),
+      artists: result.artists ? offsetPage(result.artists, toArtist) : emptyPage(),
+      albums: result.albums ? offsetPage(result.albums, toAlbum) : emptyPage(),
+      playlists: result.playlists ? offsetPage(result.playlists, toPlaylist) : emptyPage(),
+    };
+  }
+
+  async getLikedTracks(options: { limit?: number; cursor?: string } = {}): Promise<Page<Track>> {
+    const paging = await this.client.getSavedTracks({
+      limit: Math.min(options.limit ?? LIBRARY_MAX_LIMIT, LIBRARY_MAX_LIMIT),
+      offset: options.cursor ? Number(options.cursor) : 0,
+    });
+    return offsetPage(paging, (saved) => toTrack(saved.track));
+  }
+
+  async getSavedAlbums(options: { limit?: number; cursor?: string } = {}): Promise<Page<Album>> {
+    const paging = await this.client.getSavedAlbums({
+      limit: Math.min(options.limit ?? LIBRARY_MAX_LIMIT, LIBRARY_MAX_LIMIT),
+      offset: options.cursor ? Number(options.cursor) : 0,
+    });
+    return offsetPage(paging, (saved) => toAlbum(saved.album));
+  }
+
+  async getFollowedArtists(
+    options: { limit?: number; cursor?: string } = {},
+  ): Promise<Page<Artist>> {
+    const result = await this.client.getFollowedArtists({
+      limit: Math.min(options.limit ?? LIBRARY_MAX_LIMIT, LIBRARY_MAX_LIMIT),
+      after: options.cursor,
+    });
+    return {
+      items: result.artists.items.map(toArtist),
+      nextCursor: result.artists.cursors.after,
+      total: result.artists.total,
+    };
+  }
+
+  async getPlaylists(options: { limit?: number; cursor?: string } = {}): Promise<Page<Playlist>> {
+    const paging = await this.client.getPlaylists({
+      limit: Math.min(options.limit ?? LIBRARY_MAX_LIMIT, LIBRARY_MAX_LIMIT),
+      offset: options.cursor ? Number(options.cursor) : 0,
+    });
+    return offsetPage(paging, toPlaylist);
+  }
+
+  async getPlaylistTracks(
+    playlistId: string,
+    options: { limit?: number; cursor?: string } = {},
+  ): Promise<Page<Track>> {
+    const paging = await this.client.getPlaylistTracks(playlistId, {
+      limit: Math.min(options.limit ?? LIBRARY_MAX_LIMIT, LIBRARY_MAX_LIMIT),
+      offset: options.cursor ? Number(options.cursor) : 0,
+    });
+    return offsetPage(paging, (entry) => toTrack(entry.item));
+  }
+}

package/src/providers/spotify/spotify_session.ts

@@ -0,0 +1,95 @@
+/**
+ * Keeping one user's Spotify access token usable across many tool calls.
+ *
+ * An access token lasts an hour; an MCP session, and the KV entry storing
+ * the refresh token, both outlive that easily. So every tool call must be
+ * able to discover "is the stored token still good, and if not, refresh it
+ * and store the result" — not just read a token once at session start.
+ *
+ * The refresh token itself is the thing worth keeping durable: it is what
+ * KV stores, keyed by Spotify user id. The access token is not stored at
+ * all — it is fetched fresh from `refreshAccessToken` whenever a call needs
+ * one and doesn't have a still-valid one cached in the (fresh, per-call)
+ * closure this module doesn't keep.
+ */
+
+import { refreshAccessToken, type SpotifyTokens } from "./spotify_oauth";
+
+const REFRESH_MARGIN_MS = 60_000;
+
+/** What is actually persisted in KV, and its own record of freshness. */
+type StoredSession = {
+  refreshToken: string;
+  accessToken: string;
+  expiresAt: number;
+};
+
+function kvKey(spotifyUserId: string): string {
+  return `spotify-session:${spotifyUserId}`;
+}
+
+/**
+ * Store the tokens from a fresh authorization or refresh.
+ *
+ * @param kv - The `SPOTIFY_TOKENS` namespace.
+ * @param spotifyUserId - Whose session this is.
+ * @param tokens - The tokens to store.
+ */
+export async function storeSession(
+  kv: KVNamespace,
+  spotifyUserId: string,
+  tokens: SpotifyTokens,
+): Promise<void> {
+  const stored: StoredSession = {
+    refreshToken: tokens.refreshToken,
+    accessToken: tokens.accessToken,
+    expiresAt: tokens.expiresAt,
+  };
+  await kv.put(kvKey(spotifyUserId), JSON.stringify(stored));
+}
+
+/** Thrown when a caller has no stored session — they need to authorize first. */
+export class NoSpotifySessionError extends Error {
+  constructor(spotifyUserId: string) {
+    super(
+      `No stored Spotify session for ${spotifyUserId}. Authorize this server `
+        + "with Spotify first.",
+    );
+    this.name = "NoSpotifySessionError";
+  }
+}
+
+/**
+ * Get a usable access token for a user, refreshing and re-storing it first
+ * if the stored one is expired or close to it.
+ *
+ * @param kv - The `SPOTIFY_TOKENS` namespace.
+ * @param spotifyUserId - Whose session to use.
+ * @param options.clientId - This app's Spotify client ID, needed to refresh.
+ * @param options.now - Clock, injected for testability.
+ * @returns A valid access token.
+ * @throws NoSpotifySessionError - When the user has never authorized.
+ */
+export async function getAccessToken(
+  kv: KVNamespace,
+  spotifyUserId: string,
+  options: { clientId: string; now: () => number },
+): Promise<string> {
+  const raw = await kv.get(kvKey(spotifyUserId));
+  if (!raw) {
+    throw new NoSpotifySessionError(spotifyUserId);
+  }
+  const stored = JSON.parse(raw) as StoredSession;
+
+  if (options.now() < stored.expiresAt - REFRESH_MARGIN_MS) {
+    return stored.accessToken;
+  }
+
+  const refreshed = await refreshAccessToken({
+    clientId: options.clientId,
+    refreshToken: stored.refreshToken,
+    now: options.now,
+  });
+  await storeSession(kv, spotifyUserId, refreshed);
+  return refreshed.accessToken;
+}

package/src/spotify_handler.ts

@@ -0,0 +1,128 @@
+/**
+ * Spotify as the identity and data-access provider for this MCP server's
+ * own OAuth layer.
+ *
+ * Shaped after `other-memory`'s `github_handler.ts`, with one structural
+ * difference: GitHub there is only ever used to answer "who is this,"
+ * against a token this server never stores or reuses. Spotify here is also
+ * the source the tools actually call — the tokens from this exchange are
+ * what `spotify_session.ts` persists and refreshes for every later tool
+ * call, not a one-time identity check.
+ */
+
+import type { AuthRequest, OAuthHelpers } from "@cloudflare/workers-oauth-provider";
+import { Hono } from "hono";
+
+import {
+  buildAuthorizeUrl,
+  deriveCodeChallenge,
+  exchangeCodeForTokens,
+  generateCodeVerifier,
+} from "./providers/spotify/spotify_oauth";
+import { storeSession } from "./providers/spotify/spotify_session";
+import type { Env, UserProps } from "./types";
+
+/**
+ * Only this Spotify account may complete the flow. Single-user by design —
+ * an authenticated stranger is still a stranger.
+ */
+function assertAllowedUser(spotifyUserId: string, env: Env): void {
+  if (spotifyUserId !== env.ALLOWED_SPOTIFY_USER_ID) {
+    throw new Error(`Spotify user ${spotifyUserId} is not permitted to use this server.`);
+  }
+}
+
+const app = new Hono<{ Bindings: Env & { OAUTH_PROVIDER: OAuthHelpers } }>();
+
+app.get("/authorize", async (context) => {
+  const oauthRequest = await context.env.OAUTH_PROVIDER.parseAuthRequest(context.req.raw);
+  if (!oauthRequest.clientId) {
+    return context.text("Invalid authorization request.", 400);
+  }
+
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = await deriveCodeChallenge(codeVerifier);
+
+  // The verifier has to survive the round trip to Spotify and back, and
+  // this server keeps no server-side session between the two requests — so
+  // it travels inside `state`, alongside the original MCP AuthRequest, the
+  // same way `oauthRequest` itself does in the GitHub handler.
+  const state = btoa(JSON.stringify({ oauthRequest, codeVerifier }));
+
+  const redirectUri = new URL("/callback", context.req.url).href;
+  const authorizeUrl = buildAuthorizeUrl({
+    clientId: context.env.SPOTIFY_CLIENT_ID,
+    redirectUri,
+    codeChallenge,
+    state,
+  });
+
+  return Response.redirect(authorizeUrl, 302);
+});
+
+app.get("/callback", async (context) => {
+  const code = context.req.query("code");
+  const stateParam = context.req.query("state");
+  if (!code || !stateParam) {
+    return context.text("Missing code or state.", 400);
+  }
+
+  let oauthRequest: AuthRequest;
+  let codeVerifier: string;
+  try {
+    ({ oauthRequest, codeVerifier } = JSON.parse(atob(stateParam)) as {
+      oauthRequest: AuthRequest;
+      codeVerifier: string;
+    });
+  } catch {
+    return context.text("Invalid state.", 400);
+  }
+
+  const redirectUri = new URL("/callback", context.req.url).href;
+  const tokens = await exchangeCodeForTokens({
+    clientId: context.env.SPOTIFY_CLIENT_ID,
+    redirectUri,
+    code,
+    codeVerifier,
+    now: () => Date.now(),
+  });
+
+  const profile = await fetchSpotifyProfile(tokens.accessToken);
+
+  try {
+    assertAllowedUser(profile.id, context.env);
+  } catch (error) {
+    return context.text((error as Error).message, 403);
+  }
+
+  await storeSession(context.env.SPOTIFY_TOKENS, profile.id, tokens);
+
+  const props: UserProps = {
+    spotifyUserId: profile.id,
+    displayName: profile.display_name ?? profile.id,
+  };
+
+  const { redirectTo } = await context.env.OAUTH_PROVIDER.completeAuthorization({
+    request: oauthRequest,
+    userId: profile.id,
+    metadata: { label: props.displayName },
+    scope: oauthRequest.scope,
+    props,
+  });
+
+  return Response.redirect(redirectTo, 302);
+});
+
+async function fetchSpotifyProfile(
+  accessToken: string,
+): Promise<{ id: string; display_name: string | null }> {
+  const response = await fetch("https://api.spotify.com/v1/me", {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+  if (!response.ok) {
+    throw new Error(`Fetching the Spotify profile failed: ${response.status}`);
+  }
+  return response.json();
+}
+
+export { app as SpotifyHandler };