Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

11.4 KB
Raw Blame
/**
 * Spotify OAuth (#2152) — authorization-code flow with refresh tokens for the
 * machine-local Spotify listening-history ingestion (see spotifySync.js).
 *
 * Design constraints (docs/plans/2026-07-04-human-activity-tracking.md):
 *
 * - **Zero new dependencies.** Spotify has no first-party Node SDK we need — the
 *   token exchange is two `fetch` POSTs to `accounts.spotify.com`, so we own the
 *   ~40 lines rather than pull a library (per the dependency policy). Node ≥18
 *   `fetch` is built in.
 * - **Confidential client.** The user creates their own Spotify developer app and
 *   pastes the client id/secret (stored under `data/spotify/`, mirroring
 *   `data/calendar/google-auth/`). We authenticate the token endpoint with HTTP
 *   Basic (`client_secret_basic`) — no PKCE needed for a server-side secret.
 * - **Machine-local.** Credentials + tokens live in `data/spotify/` JSON files,
 *   never federated. Derived `media.listen` events land in the machine-local
 *   `human_activity_events` table.
 * - **No cold-bootstrap side effects.** Nothing here runs at module load; the
 *   first token exchange only happens when the user completes the OAuth flow.
 *
 * The pure helpers (`isTokenExpired`, `withExpiry`, `getRedirectUri`) are exported
 * and unit-tested without any network or filesystem access.
 */
import { dataPath, ensureDir, atomicWrite, tryReadFile } from '../lib/fileUtils.js';
import { ServerError } from '../lib/errorHandler.js';
import { fetchWithTimeout } from '../lib/fetchWithTimeout.js';
import { getSelfHost } from '../lib/peerSelfHost.js';
import { getHttpsEnabledAtBoot } from '../lib/httpsState.js';
import { PORTS } from '../lib/ports.js';

// Cap on each token-endpoint round-trip so a hung accounts.spotify.com can't
// stall an OAuth callback or a history-sync refresh indefinitely.
const TOKEN_TIMEOUT_MS = 15000;

const AUTH_DIR = dataPath('spotify');
const CREDENTIALS_FILE = dataPath('spotify', 'credentials.json');
const TOKENS_FILE = dataPath('spotify', 'tokens.json');

// These are the minimal read-only scopes for history ingestion plus the
// playlist reference library. (`user-read-playback-state` would enable a
// future live "now playing" feature, so it remains out of scope.)
export const SPOTIFY_SCOPES = [
  'user-read-recently-played',
  'playlist-read-private',
  'playlist-read-collaborative',
];

const ACCOUNTS_BASE = 'https://accounts.spotify.com';

// ---------------------------------------------------------------------------
// Pure helpers (exported for unit tests — no network, no filesystem).
// ---------------------------------------------------------------------------

/**
 * The redirect URI registered in the user's Spotify developer app. Mirrors
 * googleAuth's env-driven constant so it stays stable across the auth-url and
 * callback round-trip. Surfaced in the auth status so the user can copy the
 * exact string into the Spotify dashboard (it must match byte-for-byte).
 * An explicit request origin takes precedence over machine metadata so remote
 * Tailscale HTTPS users see the same callback URI the browser will use.
 */
export function getRedirectUri({ origin } = {}) {
  if (process.env.SPOTIFY_REDIRECT_URI) return process.env.SPOTIFY_REDIRECT_URI;
  const port = process.env.PORT || PORTS.API;
  if (origin) return `${origin.replace(/\/$/, '')}/api/spotify/oauth/callback`;
  if (process.env.PUBLIC_HOST) {
    return `http://${process.env.PUBLIC_HOST}:${port}/api/spotify/oauth/callback`;
  }
  const detectedHost = getSelfHost();
  const host = detectedHost && !/^(undefined|null)\b/i.test(detectedHost) ? detectedHost : null;
  if (!host) return `http://localhost:${port}/api/spotify/oauth/callback`;
  const scheme = getHttpsEnabledAtBoot().value ? 'https' : 'http';
  return `${scheme}://${host}:${port}/api/spotify/oauth/callback`;
}

/**
 * Stamp an absolute `expires_at` (epoch ms) onto a raw Spotify token response so
 * `isTokenExpired` can decide when to refresh. `expires_in` is seconds-from-now.
 */
export function withExpiry(tokens, now = Date.now()) {
  const expiresIn = Number(tokens?.expires_in);
  return {
    ...tokens,
    expires_at: Number.isFinite(expiresIn) ? now + expiresIn * 1000 : null,
  };
}

/**
 * True when the access token is missing or within `skewMs` of its expiry (so a
 * caller refreshes proactively). An unknown `expires_at` counts as expired — we
 * refresh rather than gamble on a stale token. `null`/absent token ⇒ expired.
 */
export function isTokenExpired(tokens, now = Date.now(), skewMs = 60000) {
  if (!tokens?.access_token) return true;
  if (!Number.isFinite(tokens?.expires_at)) return true;
  return now >= tokens.expires_at - skewMs;
}

// ---------------------------------------------------------------------------
// Credentials + tokens (machine-local files under data/spotify/).
// ---------------------------------------------------------------------------

async function ensureAuthDir() {
  await ensureDir(AUTH_DIR);
}

export async function getCredentials() {
  await ensureAuthDir();
  const raw = await tryReadFile(CREDENTIALS_FILE);
  if (!raw) return null;
  return JSON.parse(raw);
}

export async function saveCredentials({ clientId, clientSecret }, options = {}) {
  await ensureAuthDir();
  const credentials = { clientId, clientSecret, redirectUri: getRedirectUri(options) };
  await atomicWrite(CREDENTIALS_FILE, credentials);
  console.log('🎧 Spotify OAuth credentials saved');
  return { hasCredentials: true, redirectUri: credentials.redirectUri };
}

export async function getTokens() {
  await ensureAuthDir();
  const raw = await tryReadFile(TOKENS_FILE);
  if (!raw) return null;
  return JSON.parse(raw);
}

async function saveTokens(tokens) {
  await ensureAuthDir();
  await atomicWrite(TOKENS_FILE, tokens);
}

export async function clearAuth() {
  await ensureAuthDir();
  await atomicWrite(TOKENS_FILE, {});
  console.log('🎧 Spotify OAuth tokens cleared');
  return { cleared: true };
}

// ---------------------------------------------------------------------------
// OAuth flow (side-effecting — network via fetch).
// ---------------------------------------------------------------------------

// Exchange with the Spotify token endpoint. `.json()` failures are caught inline
// (a non-JSON error body must not mask the real HTTP status).
async function requestToken(params) {
  const credentials = await getCredentials();
  if (!credentials?.clientId) {
    throw new ServerError('No Spotify OAuth credentials configured', { status: 400 });
  }
  const basic = Buffer.from(`${credentials.clientId}:${credentials.clientSecret}`).toString('base64');
  const res = await fetchWithTimeout(`${ACCOUNTS_BASE}/api/token`, {
    method: 'POST',
    headers: {
      Authorization: `Basic ${basic}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams(params).toString(),
  }, TOKEN_TIMEOUT_MS);
  const json = await res.json().catch(() => ({}));
  if (!res.ok) {
    throw new ServerError(
      `Spotify token request failed: ${json.error_description || json.error || res.status}`,
      { status: 400 },
    );
  }
  return json;
}

export async function getAuthUrl(options = {}) {
  const credentials = await getCredentials();
  if (!credentials?.clientId) {
    throw new ServerError('No Spotify OAuth credentials configured', { status: 400 });
  }
  const params = new URLSearchParams({
    client_id: credentials.clientId,
    response_type: 'code',
    redirect_uri: getRedirectUri(options),
    scope: SPOTIFY_SCOPES.join(' '),
    show_dialog: 'false',
  });
  return { url: `${ACCOUNTS_BASE}/authorize?${params.toString()}` };
}

async function processCallback(code, options = {}) {
  const tokens = await requestToken({
    grant_type: 'authorization_code',
    code,
    redirect_uri: getRedirectUri(options),
  });
  await saveTokens(withExpiry(tokens));
  console.log('🎧 Spotify OAuth callback processed, tokens stored');
  return { success: true };
}

// Spotify authorization codes are single-use. Browsers and reverse proxies can
// replay a redirect while the first callback is still settling, and Spotify
// then reports the second request as "Invalid authorization code" even though
// the first request successfully stored the tokens. Remember successful codes
// briefly so an immediate replay is a harmless success.
const completedCallbacks = new Map();
const callbackInFlight = new Map();
const CALLBACK_REPLAY_WINDOW_MS = 120000;

export async function handleCallback(code, options = {}) {
  const key = `${code}\u0000${getRedirectUri(options)}`;
  const prior = completedCallbacks.get(key);
  if (prior && Date.now() - prior.completedAt < CALLBACK_REPLAY_WINDOW_MS) {
    return { ...prior.result, duplicate: true };
  }
  const active = callbackInFlight.get(key);
  if (active) return active.then((result) => ({ ...result, duplicate: true }));
  const promise = processCallback(code, options).then((result) => {
    completedCallbacks.set(key, { completedAt: Date.now(), result });
    for (const [cachedKey, cached] of completedCallbacks) {
      if (Date.now() - cached.completedAt >= CALLBACK_REPLAY_WINDOW_MS) completedCallbacks.delete(cachedKey);
    }
    return result;
  }).finally(() => callbackInFlight.delete(key));
  callbackInFlight.set(key, promise);
  return promise;
}

// Single-flight guard: while one refresh is in flight, concurrent callers await
// the same promise instead of each POSTing their own refresh (Spotify rotates
// the grant, so a double-refresh means the loser writes a stale token — classic
// last-write-wins). Cleared in `finally` so a failed refresh can be retried.
let refreshPromise = null;

async function refreshAccessToken(tokens) {
  const refreshed = await requestToken({
    grant_type: 'refresh_token',
    refresh_token: tokens.refresh_token,
  });
  const merged = withExpiry({ ...tokens, ...refreshed });
  if (!refreshed.refresh_token) merged.refresh_token = tokens.refresh_token;
  await saveTokens(merged);
  console.log('🎧 Spotify OAuth access token refreshed');
  return merged.access_token;
}

/**
 * Return a valid access token, refreshing via the stored refresh token when the
 * current one is expired/near-expiry. Returns `null` when the user hasn't
 * connected (no tokens) or the grant is unrecoverable (no refresh token) — the
 * caller surfaces a "connect in Settings" prompt rather than throwing.
 *
 * Spotify may OMIT `refresh_token` from a refresh response (it stays valid), so
 * the existing refresh token is preserved when the response doesn't carry one.
 *
 * Concurrent callers that all find the token expired share ONE refresh via the
 * module-level `refreshPromise` (single-flight), so the grant is rotated once.
 */
export async function getAccessToken() {
  const tokens = await getTokens();
  if (!tokens?.access_token && !tokens?.refresh_token) return null;
  if (!isTokenExpired(tokens)) return tokens.access_token;
  if (!tokens?.refresh_token) return null;

  if (!refreshPromise) {
    refreshPromise = refreshAccessToken(tokens).finally(() => {
      refreshPromise = null;
    });
  }
  return refreshPromise;
}

export async function getAuthStatus(options = {}) {
  const credentials = await getCredentials();
  const tokens = await getTokens();
  return {
    hasCredentials: !!credentials?.clientId,
    hasTokens: !!(tokens?.access_token || tokens?.refresh_token),
    expiresAt: Number.isFinite(tokens?.expires_at) ? new Date(tokens.expires_at).toISOString() : null,
    scope: tokens?.scope || null,
    redirectUri: getRedirectUri(options),
  };
}