spot-auth 0.1.0

package/src/core/oauth.js

@@ -0,0 +1,101 @@
+/**
+ * Builds the Spotify authorization URL.
+ * Used by both node (Authorization Code) and browser (PKCE) flows.
+ */
+export 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}`;
+}
+
+/**
+ * Exchanges an authorization code for tokens.
+ * - Node flow: pass clientSecret → uses Basic auth header
+ * - PKCE flow: pass codeVerifier → uses client_id + verifier, no secret
+ */
+export 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) {
+    // PKCE — no secret, verifier proves identity
+    body.set('code_verifier', codeVerifier);
+    body.set('client_id', clientId);
+  } else {
+    // Authorization Code — use Basic auth with client_secret
+    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();
+}
+
+/**
+ * Refreshes an access token.
+ * - Node flow: pass clientSecret → uses Basic auth
+ * - PKCE flow: pass only clientId → Spotify accepts without secret for PKCE tokens
+ */
+export 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();
+}
+
+/**
+ * Normalizes a Spotify token response into the shape used by token stores.
+ * Accepts an optional existing refresh_token as fallback for PKCE rotating tokens
+ * in case the response omits it (defensive).
+ */
+export function normalizeTokenData(response, existingRefreshToken = null) {
+  return {
+    access_token: response.access_token,
+    refresh_token: response.refresh_token || existingRefreshToken,
+    expires_at: Date.now() + (response.expires_in * 1000),
+    created_at: Date.now(),
+  };
+}

package/src/node/FileTokenStore.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import path from 'path';
+
+export class FileTokenStore {
+  constructor(tokenCachePath) {
+    this.path = tokenCachePath || path.join(process.cwd(), '.spotify-tokens.json');
+  }
+
+  get() {
+    try {
+      if (!fs.existsSync(this.path)) return null;
+      return JSON.parse(fs.readFileSync(this.path, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  set(tokenData) {
+    fs.writeFileSync(this.path, JSON.stringify(tokenData, null, 2));
+  }
+
+  clear() {
+    try {
+      if (fs.existsSync(this.path)) fs.unlinkSync(this.path);
+    } catch { /* non-fatal */ }
+  }
+}

package/src/node/LocalAuthServer.js

@@ -0,0 +1,48 @@
+import http from 'http';
+import { URL } from 'url';
+
+/**
+ * Starts a temporary local HTTP server that waits for Spotify's OAuth callback.
+ * Resolves with { code, state } when the callback is received, then shuts down.
+ */
+export function waitForCallback(port = 3000) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${port}`);
+
+      if (url.pathname !== '/callback') {
+        res.writeHead(404).end();
+        return;
+      }
+
+      const code = url.searchParams.get('code');
+      const error = url.searchParams.get('error');
+      const state = url.searchParams.get('state');
+
+      if (error) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<h1>Authorization failed</h1><p>You can close this window.</p>');
+        server.close();
+        reject(new Error(`Spotify authorization error: ${error}`));
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end('<h1>Authorization successful!</h1><p>You can close this window and return to the terminal.</p>');
+      server.close();
+      resolve({ code, state });
+    });
+
+    server.listen(port, '127.0.0.1', () => {
+      // Ready — caller opens the browser and awaits this promise
+    });
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        reject(new Error(`spot-auth: port ${port} is already in use. Set a different redirectUri port in your config.`));
+      } else {
+        reject(err);
+      }
+    });
+  });
+}

package/src/node/gitignore.js

@@ -0,0 +1,22 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Appends the token cache filename to the project's .gitignore if not already present.
+ * Non-fatal — logs a warning on failure but does not throw.
+ */
+export function ensureGitignored(filename = '.spotify-tokens.json') {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  try {
+    const existing = fs.existsSync(gitignorePath)
+      ? fs.readFileSync(gitignorePath, 'utf8')
+      : '';
+
+    const lines = existing.split('\n').map(l => l.trim());
+    if (!lines.includes(filename)) {
+      fs.appendFileSync(gitignorePath, `\n# spot-auth token cache\n${filename}\n`);
+    }
+  } catch (err) {
+    console.warn(`spot-auth: could not update .gitignore (${err.message}). Add "${filename}" manually.`);
+  }
+}

package/src/node/index.js

@@ -0,0 +1,71 @@
+import open from 'open';
+import { SpotAuth } from '../core/SpotAuth.js';
+import { FileTokenStore } from './FileTokenStore.js';
+import { waitForCallback } from './LocalAuthServer.js';
+import { ensureGitignored } from './gitignore.js';
+import { buildAuthUrl, exchangeCode, refreshAccessToken, normalizeTokenData } from '../core/oauth.js';
+
+class NodeSpotAuth extends SpotAuth {
+  constructor(config) {
+    super(config, new FileTokenStore(config.tokenCachePath));
+  }
+
+  async _authenticate() {
+    const state = Math.random().toString(36).substring(7);
+    const authUrl = buildAuthUrl({
+      clientId: this.config.clientId,
+      scope: this.config.scope,
+      redirectUri: this.config.redirectUri,
+      state,
+      // No codeChallenge — node flow uses Authorization Code with client_secret
+    });
+
+    console.log('\n🔑 Spotify authentication required.');
+
+    try {
+      await open(authUrl);
+      console.log('Browser opened. Waiting for authorization...\n');
+    } catch {
+      console.log('Could not open browser automatically. Please open this URL:\n');
+      console.log(`  ${authUrl}\n`);
+    }
+
+    const { code } = await waitForCallback(this._getCallbackPort());
+
+    const tokenResponse = await exchangeCode({
+      clientId: this.config.clientId,
+      clientSecret: this.config.clientSecret,
+      code,
+      redirectUri: this.config.redirectUri,
+    });
+
+    const tokenData = normalizeTokenData(tokenResponse);
+    this.store.set(tokenData);
+    ensureGitignored();
+
+    console.log('✅ Spotify authentication successful.\n');
+    return tokenData.access_token;
+  }
+
+  async _doRefresh(refreshToken, cachedTokenData) {
+    const tokenResponse = await refreshAccessToken({
+      clientId: this.config.clientId,
+      clientSecret: this.config.clientSecret,
+      refreshToken,
+    });
+
+    const tokenData = normalizeTokenData(tokenResponse, cachedTokenData?.refresh_token);
+    this.store.set(tokenData);
+    return tokenData.access_token;
+  }
+
+  _getCallbackPort() {
+    try {
+      return parseInt(new URL(this.config.redirectUri).port) || 3000;
+    } catch {
+      return 3000;
+    }
+  }
+}
+
+export { NodeSpotAuth as SpotAuth };

package/src/react/SpotAuthBarrier.jsx

@@ -0,0 +1,22 @@
+import { useEffect } from 'react';
+import { useSpotAuth } from './SpotAuthContext.jsx';
+
+/**
+ * Auth gate component. Renders children only when authenticated.
+ * Automatically triggers the Spotify auth flow if no valid token exists.
+ *
+ * @param {React.ReactNode} children - Content to render when authenticated
+ * @param {React.ReactNode} fallback - Content to render while unauthenticated (default: null)
+ */
+export function SpotAuthBarrier({ children, fallback = null }) {
+  const { isAuthenticated, triggerAuth } = useSpotAuth();
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      triggerAuth();
+    }
+  }, [isAuthenticated]);
+
+  if (!isAuthenticated) return fallback;
+  return children;
+}

package/src/react/SpotAuthCallback.jsx

@@ -0,0 +1,71 @@
+import { useEffect, useState } from 'react';
+import { useSpotAuth } from './SpotAuthContext.jsx';
+import { exchangeCode, normalizeTokenData } from '../core/oauth.js';
+
+/**
+ * Base callback handler. Reads ?code= from the URL, exchanges it for tokens
+ * via PKCE, saves to localStorage, then redirects to the original URL.
+ *
+ * @param {(url: string) => void} [onRedirect] - Override navigation (e.g. React Router's navigate()).
+ *   Defaults to window.location.replace().
+ */
+export function SpotAuthCallbackBase({ onRedirect }) {
+  const { clientId, redirectUri } = useSpotAuth();
+  const [error, setError] = useState(null);
+
+  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 — possible CSRF attack. Please try again.');
+      return;
+    }
+
+    // Clean up PKCE session state
+    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 <div>Authentication error: {error}</div>;
+  return <div>Authenticating...</div>;
+}
+
+/**
+ * Router-agnostic callback component. Mount this on your /auth/callback route.
+ * Uses window.location.replace() to navigate back after auth.
+ *
+ * For React Router apps, import from 'spot-auth/react-router' instead.
+ */
+export function SpotAuthCallback() {
+  return <SpotAuthCallbackBase />;
+}

package/src/react/SpotAuthContext.jsx

@@ -0,0 +1,87 @@
+import { createContext, useContext, useState, useRef } from 'react';
+import { LocalStorageTokenStore } from '../browser/LocalStorageTokenStore.js';
+import { generatePKCE } from '../browser/pkce.js';
+import { buildAuthUrl, refreshAccessToken, normalizeTokenData } from '../core/oauth.js';
+
+const SpotAuthContext = createContext(null);
+const BUFFER_MS = 5 * 60 * 1000;
+
+function isExpired(tokenData) {
+  return !tokenData || Date.now() > (tokenData.expires_at - BUFFER_MS);
+}
+
+export function SpotAuthProvider({ clientId, scope, redirectUri, children }) {
+  const store = useRef(new LocalStorageTokenStore()).current;
+  const [tokenData, setTokenData] = useState(() => store.get());
+  const pendingRefresh = 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;
+  };
+
+  /**
+   * Returns a valid access token. Refreshes silently if expired.
+   * Returns null if no token exists (SpotAuthBarrier handles triggering full auth).
+   */
+  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;
+  };
+
+  /**
+   * Saves current URL, generates PKCE params, redirects to Spotify auth.
+   */
+  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 (
+    <SpotAuthContext.Provider value={{
+      tokenData,
+      isAuthenticated,
+      getAccessToken,
+      triggerAuth,
+      logout,
+      clientId,
+      redirectUri,
+    }}>
+      {children}
+    </SpotAuthContext.Provider>
+  );
+}
+
+export function useSpotAuth() {
+  const ctx = useContext(SpotAuthContext);
+  if (!ctx) throw new Error('useSpotAuth must be used within a SpotAuthProvider');
+  return ctx;
+}

package/src/react/index.js

@@ -0,0 +1,3 @@
+export { SpotAuthProvider, useSpotAuth } from './SpotAuthContext.jsx';
+export { SpotAuthBarrier } from './SpotAuthBarrier.jsx';
+export { SpotAuthCallback, SpotAuthCallbackBase } from './SpotAuthCallback.jsx';

package/src/react-router/index.jsx

@@ -0,0 +1,19 @@
+import { useNavigate } from 'react-router-dom';
+import { SpotAuthCallbackBase } from '../react/SpotAuthCallback.jsx';
+
+/**
+ * React Router-aware callback component.
+ * Uses useNavigate() to redirect back after auth (preserves browser history).
+ * Mount this on your /auth/callback route.
+ *
+ * Import from 'spot-auth/react-router' instead of 'spot-auth/react' to use this.
+ */
+export function SpotAuthCallback() {
+  const navigate = useNavigate();
+  return <SpotAuthCallbackBase onRedirect={(url) => navigate(url, { replace: true })} />;
+}
+
+// Re-export everything else from spot-auth/react unchanged
+export { SpotAuthProvider, useSpotAuth } from '../react/SpotAuthContext.jsx';
+export { SpotAuthBarrier } from '../react/SpotAuthBarrier.jsx';
+export { SpotAuthCallbackBase } from '../react/SpotAuthCallback.jsx';

package/src/webcomponent/spot-auth-barrier.js

@@ -0,0 +1,190 @@
+import { generatePKCE } from '../browser/pkce.js';
+import { buildAuthUrl, exchangeCode, refreshAccessToken, normalizeTokenData } from '../core/oauth.js';
+import { LocalStorageTokenStore } from '../browser/LocalStorageTokenStore.js';
+
+const BUFFER_MS = 5 * 60 * 1000;
+const store = new LocalStorageTokenStore();
+
+// Holds a reference to the active <spot-auth-barrier> instance so getSpotToken()
+// can refresh or trigger auth without the caller needing to pass config.
+let _activeInstance = null;
+
+/**
+ * Returns a valid Spotify access token.
+ * - If the cached token is still valid, returns it immediately.
+ * - If expired but a refresh token exists, silently refreshes and returns the new token.
+ * - If no token exists at all, triggers the full PKCE auth redirect (page navigates away).
+ *
+ * Requires a <spot-auth-barrier> element to be present in the DOM.
+ *
+ * @returns {Promise<string>}
+ *
+ * @example
+ * const token = await getSpotToken();
+ * const res = await fetch('https://api.spotify.com/v1/me', {
+ *   headers: { Authorization: `Bearer ${token}` }
+ * });
+ */
+export async function getSpotToken() {
+  const tokenData = store.get();
+
+  if (tokenData && Date.now() < tokenData.expires_at - BUFFER_MS) {
+    return tokenData.access_token;
+  }
+
+  if (!_activeInstance) {
+    throw new Error('spot-auth: getSpotToken() requires a <spot-auth-barrier> element in the DOM.');
+  }
+
+  if (tokenData?.refresh_token) {
+    return _activeInstance._refreshAndReturn(tokenData);
+  }
+
+  // No token at all — trigger full auth (page redirects away, promise never resolves)
+  await _activeInstance._triggerAuth();
+}
+
+/**
+ * <spot-auth-barrier> web component.
+ *
+ * Hides its children until a valid Spotify token exists.
+ * Handles the full PKCE auth flow, including detecting the callback URL.
+ *
+ * Dispatches a 'spot-auth-ready' CustomEvent on the element when auth is
+ * confirmed, with `event.detail.accessToken` available.
+ *
+ * Attributes:
+ *   client-id     (required) Spotify app client ID
+ *   scope         (required) Space-separated Spotify scopes
+ *   redirect-uri  (required) Must match a URI registered in your Spotify app
+ *
+ * Usage:
+ *   <spot-auth-barrier
+ *     client-id="..."
+ *     scope="playlist-read-private user-library-read"
+ *     redirect-uri="https://yourapp.com/auth/callback"
+ *   >
+ *     <div>Protected content</div>
+ *   </spot-auth-barrier>
+ */
+class SpotAuthBarrier extends HTMLElement {
+  connectedCallback() {
+    _activeInstance = this;
+    this.style.display = 'none';
+    this._pendingRefresh = null;
+    this._init();
+  }
+
+  disconnectedCallback() {
+    if (_activeInstance === this) _activeInstance = null;
+  }
+
+  get _config() {
+    return {
+      clientId: this.getAttribute('client-id'),
+      scope: this.getAttribute('scope'),
+      redirectUri: this.getAttribute('redirect-uri'),
+    };
+  }
+
+  _ready(accessToken) {
+    this.style.display = '';
+    this.dispatchEvent(new CustomEvent('spot-auth-ready', {
+      bubbles: true,
+      detail: { accessToken },
+    }));
+  }
+
+  async _refreshAndReturn(cachedTokenData) {
+    if (this._pendingRefresh) return this._pendingRefresh;
+
+    this._pendingRefresh = refreshAccessToken({
+      clientId: this._config.clientId,
+      refreshToken: cachedTokenData.refresh_token,
+    })
+      .then(res => {
+        const tokenData = normalizeTokenData(res, cachedTokenData.refresh_token);
+        store.set(tokenData);
+        return tokenData.access_token;
+      })
+      .catch(err => {
+        store.clear();
+        throw err;
+      })
+      .finally(() => { this._pendingRefresh = null; });
+
+    return this._pendingRefresh;
+  }
+
+  async _init() {
+    const params = new URLSearchParams(window.location.search);
+    if (params.has('code') || params.has('error')) {
+      await this._handleCallback(params);
+      return;
+    }
+
+    const cached = store.get();
+
+    if (cached && Date.now() < cached.expires_at - BUFFER_MS) {
+      this._ready(cached.access_token);
+      return;
+    }
+
+    if (cached?.refresh_token) {
+      try {
+        const accessToken = await this._refreshAndReturn(cached);
+        this._ready(accessToken);
+        return;
+      } catch {
+        // Fall through to full auth
+      }
+    }
+
+    await this._triggerAuth();
+  }
+
+  async _triggerAuth() {
+    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({ ...this._config, state, codeChallenge });
+  }
+
+  async _handleCallback(params) {
+    const code = params.get('code');
+    const state = params.get('state');
+    const error = params.get('error');
+
+    if (error) {
+      console.error(`spot-auth: Spotify authorization error: ${error}`);
+      return;
+    }
+
+    const storedState = sessionStorage.getItem('spot_auth_state');
+    const codeVerifier = sessionStorage.getItem('spot_auth_verifier');
+    const returnUrl = localStorage.getItem('spot_auth_return_url') || '/';
+
+    if (state !== storedState) {
+      console.error('spot-auth: state mismatch — possible CSRF. Aborting.');
+      return;
+    }
+
+    sessionStorage.removeItem('spot_auth_state');
+    sessionStorage.removeItem('spot_auth_verifier');
+    localStorage.removeItem('spot_auth_return_url');
+
+    try {
+      const res = await exchangeCode({ ...this._config, code, codeVerifier });
+      store.set(normalizeTokenData(res));
+      window.location.replace(returnUrl);
+    } catch (err) {
+      console.error(`spot-auth: token exchange failed: ${err.message}`);
+    }
+  }
+}
+
+customElements.define('spot-auth-barrier', SpotAuthBarrier);