spot-auth 0.1.0

package/dist/react/index.cjs

@@ -0,0 +1,223 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+
+const KEY = "spot_auth_tokens";
+class LocalStorageTokenStore {
+  get() {
+    try {
+      const raw = localStorage.getItem(KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  }
+  set(tokenData) {
+    localStorage.setItem(KEY, JSON.stringify(tokenData));
+  }
+  clear() {
+    localStorage.removeItem(KEY);
+  }
+}
+
+async function generatePKCE() {
+  const array = new Uint8Array(96);
+  crypto.getRandomValues(array);
+  const codeVerifier = btoa(String.fromCharCode(...array)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  return { codeVerifier, codeChallenge };
+}
+
+function buildAuthUrl({ clientId, scope, redirectUri, state, codeChallenge }) {
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: clientId,
+    scope,
+    redirect_uri: redirectUri,
+    state,
+    ...codeChallenge && {
+      code_challenge_method: "S256",
+      code_challenge: codeChallenge
+    }
+  });
+  return `https://accounts.spotify.com/authorize?${params}`;
+}
+async function exchangeCode({ clientId, clientSecret, code, redirectUri, codeVerifier }) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri
+  });
+  const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+  if (codeVerifier) {
+    body.set("code_verifier", codeVerifier);
+    body.set("client_id", clientId);
+  } else {
+    headers["Authorization"] = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+  }
+  const res = await fetch("https://accounts.spotify.com/api/token", {
+    method: "POST",
+    body,
+    headers
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Token exchange failed (${res.status}): ${err}`);
+  }
+  return res.json();
+}
+async function refreshAccessToken({ clientId, clientSecret, refreshToken }) {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: clientId
+  });
+  const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+  if (clientSecret) {
+    headers["Authorization"] = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+  }
+  const res = await fetch("https://accounts.spotify.com/api/token", {
+    method: "POST",
+    body,
+    headers
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Token refresh failed (${res.status}): ${err}`);
+  }
+  return res.json();
+}
+function normalizeTokenData(response, existingRefreshToken = null) {
+  return {
+    access_token: response.access_token,
+    refresh_token: response.refresh_token || existingRefreshToken,
+    expires_at: Date.now() + response.expires_in * 1e3,
+    created_at: Date.now()
+  };
+}
+
+const SpotAuthContext = react.createContext(null);
+const BUFFER_MS = 5 * 60 * 1e3;
+function isExpired(tokenData) {
+  return !tokenData || Date.now() > tokenData.expires_at - BUFFER_MS;
+}
+function SpotAuthProvider({ clientId, scope, redirectUri, children }) {
+  const store = react.useRef(new LocalStorageTokenStore()).current;
+  const [tokenData, setTokenData] = react.useState(() => store.get());
+  const pendingRefresh = react.useRef(null);
+  const doRefresh = async (refreshToken, existingTokenData) => {
+    if (pendingRefresh.current) return pendingRefresh.current;
+    pendingRefresh.current = refreshAccessToken({ clientId, refreshToken }).then((res) => {
+      const td = normalizeTokenData(res, existingTokenData?.refresh_token);
+      store.set(td);
+      setTokenData(td);
+      return td;
+    }).finally(() => {
+      pendingRefresh.current = null;
+    });
+    return pendingRefresh.current;
+  };
+  const getAccessToken = async () => {
+    const cached = store.get();
+    if (cached && !isExpired(cached)) return cached.access_token;
+    if (cached?.refresh_token) {
+      const td = await doRefresh(cached.refresh_token, cached);
+      return td.access_token;
+    }
+    return null;
+  };
+  const triggerAuth = async () => {
+    const { codeVerifier, codeChallenge } = await generatePKCE();
+    const state = Math.random().toString(36).substring(7);
+    sessionStorage.setItem("spot_auth_verifier", codeVerifier);
+    sessionStorage.setItem("spot_auth_state", state);
+    localStorage.setItem("spot_auth_return_url", window.location.href);
+    window.location.href = buildAuthUrl({ clientId, scope, redirectUri, state, codeChallenge });
+  };
+  const logout = () => {
+    store.clear();
+    setTokenData(null);
+  };
+  const isAuthenticated = !!tokenData && !isExpired(tokenData);
+  return /* @__PURE__ */ jsxRuntime.jsx(SpotAuthContext.Provider, { value: {
+    tokenData,
+    isAuthenticated,
+    getAccessToken,
+    triggerAuth,
+    logout,
+    clientId,
+    redirectUri
+  }, children });
+}
+function useSpotAuth() {
+  const ctx = react.useContext(SpotAuthContext);
+  if (!ctx) throw new Error("useSpotAuth must be used within a SpotAuthProvider");
+  return ctx;
+}
+
+function SpotAuthBarrier({ children, fallback = null }) {
+  const { isAuthenticated, triggerAuth } = useSpotAuth();
+  react.useEffect(() => {
+    if (!isAuthenticated) {
+      triggerAuth();
+    }
+  }, [isAuthenticated]);
+  if (!isAuthenticated) return fallback;
+  return children;
+}
+
+function SpotAuthCallbackBase({ onRedirect }) {
+  const { clientId, redirectUri } = useSpotAuth();
+  const [error, setError] = react.useState(null);
+  react.useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+    const errorParam = params.get("error");
+    const storedState = sessionStorage.getItem("spot_auth_state");
+    const codeVerifier = sessionStorage.getItem("spot_auth_verifier");
+    const returnUrl = localStorage.getItem("spot_auth_return_url") || "/";
+    if (errorParam) {
+      setError(`Spotify authorization error: ${errorParam}`);
+      return;
+    }
+    if (!code) {
+      setError("No authorization code received.");
+      return;
+    }
+    if (state !== storedState) {
+      setError("State mismatch \u2014 possible CSRF attack. Please try again.");
+      return;
+    }
+    sessionStorage.removeItem("spot_auth_state");
+    sessionStorage.removeItem("spot_auth_verifier");
+    localStorage.removeItem("spot_auth_return_url");
+    exchangeCode({ clientId, code, redirectUri, codeVerifier }).then((res) => {
+      const tokenData = normalizeTokenData(res);
+      localStorage.setItem("spot_auth_tokens", JSON.stringify(tokenData));
+      if (onRedirect) {
+        onRedirect(returnUrl);
+      } else {
+        window.location.replace(returnUrl);
+      }
+    }).catch((err) => setError(err.message));
+  }, []);
+  if (error) return /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
+    "Authentication error: ",
+    error
+  ] });
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { children: "Authenticating..." });
+}
+function SpotAuthCallback() {
+  return /* @__PURE__ */ jsxRuntime.jsx(SpotAuthCallbackBase, {});
+}
+
+exports.SpotAuthBarrier = SpotAuthBarrier;
+exports.SpotAuthCallback = SpotAuthCallback;
+exports.SpotAuthCallbackBase = SpotAuthCallbackBase;
+exports.SpotAuthProvider = SpotAuthProvider;
+exports.useSpotAuth = useSpotAuth;

package/dist/react-router/index.cjs

@@ -0,0 +1,226 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var reactRouterDom = require('react-router-dom');
+var react = require('react');
+
+const KEY = "spot_auth_tokens";
+class LocalStorageTokenStore {
+  get() {
+    try {
+      const raw = localStorage.getItem(KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  }
+  set(tokenData) {
+    localStorage.setItem(KEY, JSON.stringify(tokenData));
+  }
+  clear() {
+    localStorage.removeItem(KEY);
+  }
+}
+
+async function generatePKCE() {
+  const array = new Uint8Array(96);
+  crypto.getRandomValues(array);
+  const codeVerifier = btoa(String.fromCharCode(...array)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  return { codeVerifier, codeChallenge };
+}
+
+function buildAuthUrl({ clientId, scope, redirectUri, state, codeChallenge }) {
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: clientId,
+    scope,
+    redirect_uri: redirectUri,
+    state,
+    ...codeChallenge && {
+      code_challenge_method: "S256",
+      code_challenge: codeChallenge
+    }
+  });
+  return `https://accounts.spotify.com/authorize?${params}`;
+}
+async function exchangeCode({ clientId, clientSecret, code, redirectUri, codeVerifier }) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri
+  });
+  const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+  if (codeVerifier) {
+    body.set("code_verifier", codeVerifier);
+    body.set("client_id", clientId);
+  } else {
+    headers["Authorization"] = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+  }
+  const res = await fetch("https://accounts.spotify.com/api/token", {
+    method: "POST",
+    body,
+    headers
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Token exchange failed (${res.status}): ${err}`);
+  }
+  return res.json();
+}
+async function refreshAccessToken({ clientId, clientSecret, refreshToken }) {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: clientId
+  });
+  const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+  if (clientSecret) {
+    headers["Authorization"] = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+  }
+  const res = await fetch("https://accounts.spotify.com/api/token", {
+    method: "POST",
+    body,
+    headers
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Token refresh failed (${res.status}): ${err}`);
+  }
+  return res.json();
+}
+function normalizeTokenData(response, existingRefreshToken = null) {
+  return {
+    access_token: response.access_token,
+    refresh_token: response.refresh_token || existingRefreshToken,
+    expires_at: Date.now() + response.expires_in * 1e3,
+    created_at: Date.now()
+  };
+}
+
+const SpotAuthContext = react.createContext(null);
+const BUFFER_MS = 5 * 60 * 1e3;
+function isExpired(tokenData) {
+  return !tokenData || Date.now() > tokenData.expires_at - BUFFER_MS;
+}
+function SpotAuthProvider({ clientId, scope, redirectUri, children }) {
+  const store = react.useRef(new LocalStorageTokenStore()).current;
+  const [tokenData, setTokenData] = react.useState(() => store.get());
+  const pendingRefresh = react.useRef(null);
+  const doRefresh = async (refreshToken, existingTokenData) => {
+    if (pendingRefresh.current) return pendingRefresh.current;
+    pendingRefresh.current = refreshAccessToken({ clientId, refreshToken }).then((res) => {
+      const td = normalizeTokenData(res, existingTokenData?.refresh_token);
+      store.set(td);
+      setTokenData(td);
+      return td;
+    }).finally(() => {
+      pendingRefresh.current = null;
+    });
+    return pendingRefresh.current;
+  };
+  const getAccessToken = async () => {
+    const cached = store.get();
+    if (cached && !isExpired(cached)) return cached.access_token;
+    if (cached?.refresh_token) {
+      const td = await doRefresh(cached.refresh_token, cached);
+      return td.access_token;
+    }
+    return null;
+  };
+  const triggerAuth = async () => {
+    const { codeVerifier, codeChallenge } = await generatePKCE();
+    const state = Math.random().toString(36).substring(7);
+    sessionStorage.setItem("spot_auth_verifier", codeVerifier);
+    sessionStorage.setItem("spot_auth_state", state);
+    localStorage.setItem("spot_auth_return_url", window.location.href);
+    window.location.href = buildAuthUrl({ clientId, scope, redirectUri, state, codeChallenge });
+  };
+  const logout = () => {
+    store.clear();
+    setTokenData(null);
+  };
+  const isAuthenticated = !!tokenData && !isExpired(tokenData);
+  return /* @__PURE__ */ jsxRuntime.jsx(SpotAuthContext.Provider, { value: {
+    tokenData,
+    isAuthenticated,
+    getAccessToken,
+    triggerAuth,
+    logout,
+    clientId,
+    redirectUri
+  }, children });
+}
+function useSpotAuth() {
+  const ctx = react.useContext(SpotAuthContext);
+  if (!ctx) throw new Error("useSpotAuth must be used within a SpotAuthProvider");
+  return ctx;
+}
+
+function SpotAuthCallbackBase({ onRedirect }) {
+  const { clientId, redirectUri } = useSpotAuth();
+  const [error, setError] = react.useState(null);
+  react.useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+    const errorParam = params.get("error");
+    const storedState = sessionStorage.getItem("spot_auth_state");
+    const codeVerifier = sessionStorage.getItem("spot_auth_verifier");
+    const returnUrl = localStorage.getItem("spot_auth_return_url") || "/";
+    if (errorParam) {
+      setError(`Spotify authorization error: ${errorParam}`);
+      return;
+    }
+    if (!code) {
+      setError("No authorization code received.");
+      return;
+    }
+    if (state !== storedState) {
+      setError("State mismatch \u2014 possible CSRF attack. Please try again.");
+      return;
+    }
+    sessionStorage.removeItem("spot_auth_state");
+    sessionStorage.removeItem("spot_auth_verifier");
+    localStorage.removeItem("spot_auth_return_url");
+    exchangeCode({ clientId, code, redirectUri, codeVerifier }).then((res) => {
+      const tokenData = normalizeTokenData(res);
+      localStorage.setItem("spot_auth_tokens", JSON.stringify(tokenData));
+      if (onRedirect) {
+        onRedirect(returnUrl);
+      } else {
+        window.location.replace(returnUrl);
+      }
+    }).catch((err) => setError(err.message));
+  }, []);
+  if (error) return /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
+    "Authentication error: ",
+    error
+  ] });
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { children: "Authenticating..." });
+}
+
+function SpotAuthBarrier({ children, fallback = null }) {
+  const { isAuthenticated, triggerAuth } = useSpotAuth();
+  react.useEffect(() => {
+    if (!isAuthenticated) {
+      triggerAuth();
+    }
+  }, [isAuthenticated]);
+  if (!isAuthenticated) return fallback;
+  return children;
+}
+
+function SpotAuthCallback() {
+  const navigate = reactRouterDom.useNavigate();
+  return /* @__PURE__ */ jsxRuntime.jsx(SpotAuthCallbackBase, { onRedirect: (url) => navigate(url, { replace: true }) });
+}
+
+exports.SpotAuthBarrier = SpotAuthBarrier;
+exports.SpotAuthCallback = SpotAuthCallback;
+exports.SpotAuthCallbackBase = SpotAuthCallbackBase;
+exports.SpotAuthProvider = SpotAuthProvider;
+exports.useSpotAuth = useSpotAuth;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "spot-auth",
+  "version": "0.1.0",
+  "description": "Zero-friction Spotify OAuth for Node.js scripts and web apps",
+  "type": "module",
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Be-Casual-Studios/spot-auth.git"
+  },
+  "homepage": "https://github.com/Be-Casual-Studios/spot-auth#readme",
+  "bugs": {
+    "url": "https://github.com/Be-Casual-Studios/spot-auth/issues"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/core/SpotAuth.js",
+      "require": "./dist/core/SpotAuth.cjs"
+    },
+    "./node": {
+      "import": "./src/node/index.js",
+      "require": "./dist/node/index.cjs"
+    },
+    "./react": {
+      "import": "./src/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./react-router": {
+      "import": "./src/react-router/index.jsx",
+      "require": "./dist/react-router/index.cjs"
+    },
+    "./webcomponent": {
+      "import": "./src/webcomponent/spot-auth-barrier.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup -c"
+  },
+  "dependencies": {
+    "open": "^10.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-dom": ">=17",
+    "react-router-dom": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "spotify",
+    "oauth",
+    "authentication",
+    "pkce",
+    "react"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "rollup": "^4.60.4",
+    "rollup-plugin-esbuild": "^6.2.1"
+  }
+}

package/src/browser/LocalStorageTokenStore.js

@@ -0,0 +1,20 @@
+const KEY = 'spot_auth_tokens';
+
+export class LocalStorageTokenStore {
+  get() {
+    try {
+      const raw = localStorage.getItem(KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  set(tokenData) {
+    localStorage.setItem(KEY, JSON.stringify(tokenData));
+  }
+
+  clear() {
+    localStorage.removeItem(KEY);
+  }
+}

package/src/browser/pkce.js

@@ -0,0 +1,27 @@
+/**
+ * Generates a PKCE code_verifier and code_challenge pair.
+ * Uses the Web Crypto API (available in all modern browsers and Node 19+).
+ *
+ * code_verifier: random 128-char URL-safe base64 string
+ * code_challenge: base64url(SHA-256(code_verifier))
+ */
+export async function generatePKCE() {
+  const array = new Uint8Array(96);
+  crypto.getRandomValues(array);
+
+  const codeVerifier = btoa(String.fromCharCode(...array))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+
+  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+
+  return { codeVerifier, codeChallenge };
+}

package/src/core/SpotAuth.js

@@ -0,0 +1,63 @@
+import { refreshAccessToken } from './oauth.js';
+
+const BUFFER_MS = 5 * 60 * 1000; // refresh 5 min before expiry
+
+export class SpotAuth {
+  constructor(config, tokenStore) {
+    this.config = {
+      redirectUri: 'http://127.0.0.1:3000/callback',
+      ...config,
+    };
+    this.store = tokenStore;
+    this._pendingTokenRequest = null;
+  }
+
+  /**
+   * Returns a valid access token. Handles caching, refresh, and full auth flow.
+   * Safe to call concurrently — duplicate in-flight requests are deduplicated.
+   */
+  async getAccessToken() {
+    const cached = await this.store.get();
+
+    if (cached && !this._isExpired(cached)) {
+      return cached.access_token;
+    }
+
+    if (cached?.refresh_token) {
+      return this._refresh(cached.refresh_token, cached);
+    }
+
+    return this._authenticate();
+  }
+
+  /**
+   * Refreshes the token, deduplicating concurrent calls so only one
+   * request is made even if getAccessToken() is called multiple times simultaneously.
+   */
+  async _refresh(refreshToken, cachedTokenData) {
+    if (this._pendingTokenRequest) return this._pendingTokenRequest;
+
+    this._pendingTokenRequest = this._doRefresh(refreshToken, cachedTokenData)
+      .finally(() => { this._pendingTokenRequest = null; });
+
+    return this._pendingTokenRequest;
+  }
+
+  /**
+   * Override in subclasses to implement environment-specific refresh logic.
+   */
+  async _doRefresh(_refreshToken, _cachedTokenData) {
+    throw new Error('_doRefresh must be implemented by subclass');
+  }
+
+  /**
+   * Override in subclasses to implement environment-specific full auth flow.
+   */
+  async _authenticate() {
+    throw new Error('_authenticate must be implemented by subclass');
+  }
+
+  _isExpired(tokenData) {
+    return Date.now() > (tokenData.expires_at - BUFFER_MS);
+  }
+}