spot-auth 0.1.0

package/README.md

@@ -0,0 +1,228 @@
+# spot-auth
+
+Zero-friction Spotify OAuth for Node.js scripts and web apps.
+
+- **Scripts** — one call to `getAccessToken()`, browser opens automatically, token cached to disk
+- **React** — wrap your app in `<SpotAuthProvider>`, gate content with `<SpotAuthBarrier>`
+- **Web Component** — `<spot-auth-barrier>` works in any framework or plain HTML
+- **No backend required** — web flows use PKCE, no `client_secret` in the browser
+- **Auto-refresh** — expired tokens are silently refreshed; concurrent calls are deduplicated
+
+---
+
+## Installation
+
+```bash
+npm install spot-auth
+```
+
+---
+
+## Spotify Developer Setup
+
+1. Go to [https://developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) and create an app
+2. Add your redirect URIs under **Edit Settings**:
+   - Scripts: `http://127.0.0.1:3000/callback`
+   - Web apps: `https://yourdomain.com/auth/callback` (and `http://localhost:5173/auth/callback` for local dev)
+3. Note your **Client ID** (and **Client Secret** for scripts only)
+
+---
+
+## Script / Node.js
+
+```js
+import { SpotAuth } from 'spot-auth/node';
+
+const auth = new SpotAuth({
+  clientId: process.env.CLIENT_ID,
+  clientSecret: process.env.CLIENT_SECRET,
+  scope: 'playlist-read-private user-library-read',
+});
+
+const token = await auth.getAccessToken();
+// First run: browser opens automatically, you log in once
+// Subsequent runs: token loaded from .spotify-tokens.json instantly
+```
+
+### Config options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `clientId` | string | required | Spotify app Client ID |
+| `clientSecret` | string | required | Spotify app Client Secret |
+| `scope` | string | required | Space-separated Spotify scopes |
+| `redirectUri` | string | `http://127.0.0.1:3000/callback` | Must match Spotify dashboard |
+| `tokenCachePath` | string | `process.cwd()/.spotify-tokens.json` | Override token cache location |
+
+### How it works
+
+1. On first call, opens your browser to Spotify login and starts a temporary local server to capture the callback
+2. Exchanges the code for tokens and caches them to `.spotify-tokens.json` (auto-added to `.gitignore`)
+3. On subsequent calls, loads the cached token — if expired, silently refreshes using the stored refresh token
+4. Multiple concurrent calls to `getAccessToken()` share a single in-flight request
+
+---
+
+## React
+
+### 1. Wrap your app with `SpotAuthProvider`
+
+```jsx
+// main.jsx
+import { SpotAuthProvider } from 'spot-auth/react';
+
+createRoot(document.getElementById('root')).render(
+  <SpotAuthProvider
+    clientId={import.meta.env.VITE_SPOTIFY_CLIENT_ID}
+    scope="playlist-read-private user-library-read"
+    redirectUri={`${window.location.origin}/auth/callback`}
+  >
+    <App />
+  </SpotAuthProvider>
+);
+```
+
+### 2. Mount `SpotAuthCallback` on your callback route
+
+```jsx
+// Router-agnostic — renders on the /auth/callback page
+import { SpotAuthCallback } from 'spot-auth/react';
+<SpotAuthCallback />
+```
+
+```jsx
+// React Router
+import { SpotAuthCallback } from 'spot-auth/react-router';
+<Route path="/auth/callback" element={<SpotAuthCallback />} />
+```
+
+### 3. Gate content with `SpotAuthBarrier`
+
+```jsx
+import { SpotAuthBarrier } from 'spot-auth/react';
+
+<SpotAuthBarrier fallback={<div>Loading...</div>}>
+  <MySpotifyPage />
+</SpotAuthBarrier>
+```
+
+Users who aren't authenticated are redirected to Spotify login automatically. After login they're returned to the page they were on.
+
+### 4. Access the token anywhere
+
+```jsx
+import { useSpotAuth } from 'spot-auth/react';
+
+function MyComponent() {
+  const { accessToken, isAuthenticated, logout } = useSpotAuth();
+
+  const fetchProfile = async () => {
+    const res = await fetch('https://api.spotify.com/v1/me', {
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+    return res.json();
+  };
+
+  return (
+    <div>
+      {isAuthenticated && <button onClick={logout}>Log out</button>}
+    </div>
+  );
+}
+```
+
+### `SpotAuthProvider` props
+
+| Prop | Type | Description |
+|---|---|---|
+| `clientId` | string | Spotify app Client ID |
+| `scope` | string | Space-separated Spotify scopes |
+| `redirectUri` | string | Must match Spotify dashboard and your callback route |
+
+### `SpotAuthBarrier` props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | ReactNode | required | Content to render when authenticated |
+| `fallback` | ReactNode | `null` | Content to render while unauthenticated |
+
+---
+
+## Web Component
+
+Works in any framework or plain HTML. No build step required.
+
+```html
+<script type="module" src="/node_modules/spot-auth/webcomponent/spot-auth-barrier.js"></script>
+
+<spot-auth-barrier
+  client-id="your_client_id"
+  scope="playlist-read-private user-library-read"
+  redirect-uri="https://yourapp.com/auth/callback"
+>
+  <div>This content is hidden until the user is authenticated.</div>
+</spot-auth-barrier>
+```
+
+The component handles both the initial auth redirect and the callback detection automatically — no separate callback page needed.
+
+### Accessing the token
+
+**Option 1 — `getSpotToken()` helper** (use anywhere after the barrier is in the DOM):
+
+```js
+import { getSpotToken } from '/node_modules/spot-auth/webcomponent/spot-auth-barrier.js';
+
+// Always returns a valid token — silently refreshes if expired,
+// triggers full auth redirect if no token exists at all.
+const token = await getSpotToken();
+
+const res = await fetch('https://api.spotify.com/v1/me', {
+  headers: { Authorization: `Bearer ${token}` }
+});
+```
+
+**Option 2 — `spot-auth-ready` event** (fired by the component when auth is confirmed):
+
+```js
+document.querySelector('spot-auth-barrier')
+  .addEventListener('spot-auth-ready', (event) => {
+    const { accessToken } = event.detail;
+    // safe to make Spotify API calls now
+  });
+```
+
+The event fires on every page load where a valid token exists (including after a silent refresh), not just the first time.
+
+### Attributes
+
+| Attribute | Description |
+|---|---|
+| `client-id` | Spotify app Client ID |
+| `scope` | Space-separated Spotify scopes |
+| `redirect-uri` | Must match Spotify dashboard |
+
+---
+
+## How PKCE Works (Web / Browser)
+
+The browser and web component flows use PKCE (Proof Key for Code Exchange), which lets you authenticate without a `client_secret`:
+
+1. A random `code_verifier` is generated in the browser
+2. Its SHA-256 hash (`code_challenge`) is sent to Spotify during the auth redirect
+3. After login, Spotify sends back an auth code
+4. The browser exchanges the code + original verifier directly with Spotify — no backend needed
+5. Spotify validates that the verifier matches the challenge it stored
+
+Refresh tokens are **rotating** with PKCE — each refresh returns a new refresh token, which is saved automatically.
+
+---
+
+## localStorage / sessionStorage Keys
+
+| Key | Storage | Contents |
+|---|---|---|
+| `spot_auth_tokens` | localStorage | `{ access_token, refresh_token, expires_at, created_at }` |
+| `spot_auth_return_url` | localStorage | URL to redirect to after auth (cleared after use) |
+| `spot_auth_verifier` | sessionStorage | PKCE code_verifier (cleared after use) |
+| `spot_auth_state` | sessionStorage | OAuth state for CSRF protection (cleared after use) |

package/dist/core/SpotAuth.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+const BUFFER_MS = 5 * 60 * 1e3;
+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;
+  }
+}
+
+exports.SpotAuth = SpotAuth;

package/dist/node/index.cjs

@@ -0,0 +1,257 @@
+'use strict';
+
+var open = require('open');
+var fs = require('fs');
+var path = require('path');
+var http = require('http');
+var url = require('url');
+
+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 BUFFER_MS = 5 * 60 * 1e3;
+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;
+  }
+}
+
+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 {
+    }
+  }
+}
+
+function waitForCallback(port = 3e3) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url$1 = new url.URL(req.url, `http://127.0.0.1:${port}`);
+      if (url$1.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const code = url$1.searchParams.get("code");
+      const error = url$1.searchParams.get("error");
+      const state = url$1.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", () => {
+    });
+    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);
+      }
+    });
+  });
+}
+
+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, `
+# spot-auth token cache
+${filename}
+`);
+    }
+  } catch (err) {
+    console.warn(`spot-auth: could not update .gitignore (${err.message}). Add "${filename}" manually.`);
+  }
+}
+
+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\u{1F511} 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}
+`);
+    }
+    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("\u2705 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) || 3e3;
+    } catch {
+      return 3e3;
+    }
+  }
+}
+
+exports.SpotAuth = NodeSpotAuth;