fix(spotify): let a person hand over the credentials Spotify still accepts

Since 2026-08-10 Spotify refuses any login built from an OAuth access token whose
client id is not the desktop one. That is every credential this server can produce
on its own: `loginWithAccessToken` mints from a token, `startConnectDeviceWithToken`
exchanges one internally, and both come out INVALID_CREDENTIALS. Browsing runs on the
Web API and is untouched, so an account looks healthy while no zone can authenticate —
which is exactly how #333 reads. The same week broke librespot and go-librespot too.

Nothing on that path can be repaired, so the recovery written for #333 could not land:
every route out of a refusal — re-mint, then fall back to the access token — goes
through the closed door. What still authenticates is a blob handed over by the Spotify
app during a real handshake, and node-librespot has exposed `startZeroconfLogin` all
along without anything here calling it.

So: advertise a plain Connect device, wait for someone to pick it, keep what comes back
as the account's credentials. Pairing runs as a job rather than on the request, because
it finishes when a person taps something and a browser will not hold a POST that long;
the screen polls and can say what to go and tap. One handshake per account at a time.

A refusal is now a verdict with an expiry rather than a life sentence. That was
survivable while minting could replace a retired blob, but it cannot, so a single
refusal — including a wrong one against a blob that works — retired that device for the
life of the process. And a new account blob clears every verdict recorded against the
old one: `credentialsForDevice` consults the refusal flag before falling back to the
account payload, so without that a paired account would keep logging in with nothing at
all, and pairing would report success while changing nothing until a restart.

Refs #333. Zeroconf primitive and endpoint shape from tobsch's #337.

Co-authored-by: Tobias Schlottke <tobias@saas.group>

Author: rudyberends

src/adapters/content/providers/spotify/serviceAuth.ts

@@ -9,6 +9,7 @@ import { consumePkceVerifier } from '@/adapters/content/providers/spotify/pkce';
 import { resolveSpotifyClientId } from '@/adapters/content/providers/spotify/utils';
 import {
   generateLibrespotCredentialsFromOAuth,
+  pairLibrespotCredentialsViaZeroconf,
 } from '@/adapters/inputs/spotify/spotifyStreamingService';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
@@ -212,14 +213,7 @@ export async function handleSpotifyLibrespotOAuth(
     return;
   }
 
-  const cfg = configPort.getConfig();
-  const account = cfg.content?.spotify?.accounts?.find(
-    (acc) =>
-      acc.id === accountId ||
-      acc.user === accountId ||
-      acc.email === accountId ||
-      acc.spotifyId === accountId,
-  );
+  const account = findSpotifyAccount(configPort, accountId);
   if (!account) {
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: 'account_not_found' }));
@@ -262,6 +256,180 @@ export async function handleSpotifyLibrespotOAuth(
   }
 }
 
+/**
+ * A pairing handshake in flight, per account.
+ *
+ * Pairing finishes when a person picks the device in the Spotify app, so it is held here rather than
+ * on the request: a browser will not sit on a POST for two minutes, and the admin screen needs
+ * something to poll while it tells the user what to go and tap.
+ */
+type PairingState = {
+  state: 'pairing' | 'paired' | 'failed';
+  deviceName: string;
+  startedAt: number;
+  expiresAt: number;
+  username?: string;
+  error?: string;
+};
+
+const pairingByAccount = new Map<string, PairingState>();
+const PAIRING_RESULT_TTL_MS = 5 * 60 * 1000;
+
+function pairingSnapshot(accountId: string): PairingState | null {
+  const entry = pairingByAccount.get(accountId);
+  if (!entry) {
+    return null;
+  }
+  // A settled result is worth keeping only long enough for the screen that asked to read it.
+  if (entry.state !== 'pairing' && Date.now() - entry.expiresAt > PAIRING_RESULT_TTL_MS) {
+    pairingByAccount.delete(accountId);
+    return null;
+  }
+  if (entry.state === 'pairing' && Date.now() > entry.expiresAt) {
+    entry.state = 'failed';
+    entry.error = 'timed_out';
+  }
+  return entry;
+}
+
+function findSpotifyAccount(
+  configPort: ConfigPort,
+  accountId: string,
+): SpotifyAccountConfig | undefined {
+  return configPort
+    .getConfig()
+    .content?.spotify?.accounts?.find(
+      (acc) =>
+        acc.id === accountId ||
+        acc.user === accountId ||
+        acc.email === accountId ||
+        acc.spotifyId === accountId,
+    );
+}
+
+/**
+ * Pair an account by handshake, the only login Spotify still accepts (#333).
+ *
+ * POST /admin/api/spotify/librespot/zeroconf { accountId, deviceName?, timeoutMs? }
+ *   Starts advertising and returns immediately with the device name to show the user.
+ * GET  /admin/api/spotify/librespot/zeroconf?accountId=<id>
+ *   Reports how it is going: pairing | paired | failed.
+ *
+ * One handshake per account at a time — a second advertisement for the same account would just
+ * compete with the first for the same pick.
+ */
+export async function handleSpotifyLibrespotZeroconf(
+  req: IncomingMessage,
+  res: ServerResponse,
+  configPort: ConfigPort,
+  spotifyInputService: SpotifyInputService,
+): Promise<void> {
+  const json = (status: number, body: unknown): void => {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+  };
+
+  if (req.method === 'GET') {
+    const { searchParams } = new URL(req.url ?? '', 'http://localhost');
+    const accountId = (searchParams.get('accountId') || '').trim();
+    if (!accountId) {
+      return json(400, { error: 'missing_account' });
+    }
+    const entry = pairingSnapshot(accountId);
+    if (!entry) {
+      return json(200, { ok: true, state: 'idle' });
+    }
+    return json(200, {
+      ok: true,
+      state: entry.state,
+      deviceName: entry.deviceName,
+      expiresAt: entry.expiresAt,
+      username: entry.username,
+      error: entry.error,
+    });
+  }
+
+  if (req.method !== 'POST') {
+    return json(405, { error: 'method_not_allowed' });
+  }
+
+  const body = (await readJsonBody(req)) as
+    | { accountId?: string; deviceName?: string; timeoutMs?: number }
+    | null;
+  const accountId = (body?.accountId || '').trim();
+  if (!accountId) {
+    return json(400, { error: 'missing_account' });
+  }
+
+  const account = findSpotifyAccount(configPort, accountId);
+  if (!account) {
+    return json(404, { error: 'account_not_found' });
+  }
+
+  const existing = pairingSnapshot(accountId);
+  if (existing?.state === 'pairing') {
+    return json(200, {
+      ok: true,
+      state: 'pairing',
+      deviceName: existing.deviceName,
+      expiresAt: existing.expiresAt,
+      alreadyRunning: true,
+    });
+  }
+
+  const deviceName = (body?.deviceName || '').trim() || 'Sonn (pairing)';
+  const timeoutMs =
+    typeof body?.timeoutMs === 'number' && Number.isFinite(body.timeoutMs)
+      ? Math.max(30_000, Math.min(300_000, body.timeoutMs))
+      : 120_000;
+  // librespot device ids are 40-hex; derive one from the account so repeat pairings reuse it
+  // instead of leaving a trail of one-off devices in the user's Spotify app.
+  const deviceId = crypto.createHash('sha1').update(`pair:${accountId}`).digest('hex');
+
+  const entry: PairingState = {
+    state: 'pairing',
+    deviceName,
+    startedAt: Date.now(),
+    expiresAt: Date.now() + timeoutMs,
+  };
+  pairingByAccount.set(accountId, entry);
+  log.info('spotify zeroconf pairing started', { accountId, deviceName, timeoutMs });
+
+  void (async () => {
+    try {
+      const result = await pairLibrespotCredentialsViaZeroconf({
+        deviceId,
+        name: deviceName,
+        timeoutMs,
+      });
+      if (!result) {
+        entry.state = 'failed';
+        entry.error = 'no_credentials';
+        log.warn('spotify zeroconf pairing produced no credentials', { accountId });
+        return;
+      }
+      let parsed: string | Record<string, unknown> = result.credentials;
+      try {
+        parsed = JSON.parse(result.credentials);
+      } catch {
+        /* keep string */
+      }
+      await pushLibrespotCredentials(spotifyInputService, accountId, parsed);
+      entry.state = 'paired';
+      entry.username = result.username;
+      log.info('spotify zeroconf pairing stored', { accountId, username: result.username });
+      reinitializeSpotifyInputs(configPort, spotifyInputService, 'zeroconf_paired', accountId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      entry.state = 'failed';
+      entry.error = message;
+      log.warn('spotify zeroconf pairing failed', { accountId, message });
+    }
+  })();
+
+  return json(202, { ok: true, state: 'pairing', deviceName, expiresAt: entry.expiresAt });
+}
+
 /**
  * Export existing librespot credentials for an account.
  * Request (GET): /admin/api/spotify/librespot/credentials?accountId=<id>
@@ -284,14 +452,7 @@ export async function handleSpotifyLibrespotExport(
     res.end(JSON.stringify({ error: 'missing_account' }));
     return;
   }
-  const cfg = configPort.getConfig();
-  const account = cfg.content?.spotify?.accounts?.find(
-    (acc) =>
-      acc.id === accountId ||
-      acc.user === accountId ||
-      acc.email === accountId ||
-      acc.spotifyId === accountId,
-  );
+  const account = findSpotifyAccount(configPort, accountId);
   if (!account) {
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: 'account_not_found' }));

src/adapters/http/adminApi/spotify/spotifyHandlers.ts

@@ -13,6 +13,7 @@ import {
   deleteSpotifyAccount,
   handleSpotifyLibrespotExport,
   handleSpotifyLibrespotOAuth,
+  handleSpotifyLibrespotZeroconf,
   handleSpotifyOAuthCallback,
 } from '@/adapters/content/providers/spotify/serviceAuth';
 import type { Route } from '@/adapters/http/adminApi/routeTypes';
@@ -64,6 +65,20 @@ export function buildSpotifyRoutes(deps: SpotifyHandlerDeps): Route[] {
           deps.spotifyManagerProvider,
         ),
     },
+    {
+      // Start a pairing handshake — the only login Spotify still accepts (#333). Returns at once;
+      // the GET below reports whether the user has picked the device yet.
+      method: 'POST',
+      pattern: /^\/spotify\/librespot\/zeroconf$/,
+      handler: async (req, res) =>
+        handleSpotifyLibrespotZeroconf(req, res, deps.configPort, deps.spotifyInputService),
+    },
+    {
+      method: 'GET',
+      pattern: /^\/spotify\/librespot\/zeroconf$/,
+      handler: async (req, res) =>
+        handleSpotifyLibrespotZeroconf(req, res, deps.configPort, deps.spotifyInputService),
+    },
     {
       // Anchored and GET-only: the pattern used to be an unanchored prefix with no
       // method, so it also claimed anything beginning with this path.

src/adapters/inputs/spotify/spotifyInputService.ts

@@ -118,8 +118,17 @@ class SpotifyConnectInstance {
    * survives a rejection is per device, which is what this holds. Keyed `<accountId>::<deviceId>`.
    */
   static deviceCredentials = new Map<string, string>();
-  /** Devices whose account-level blob Spotify has already refused; never replayed again. */
-  static rejectedCredentials = new Set<string>();
+  /**
+   * When Spotify last refused this device's blob, keyed the same way.
+   *
+   * A verdict, not a life sentence. It used to be a Set cleared only by a successful re-mint, which
+   * was survivable while minting could succeed. Since Spotify closed the access-token login path it
+   * cannot, so a single refusal — including a spurious one on a blob that is actually good — retired
+   * that device's credentials for the rest of the process. It expires now, so the worst a wrong
+   * verdict costs is one retry per {@link rejectionTtlMs}.
+   */
+  static rejectedCredentials = new Map<string, number>();
+  static readonly rejectionTtlMs = 30 * 60 * 1000;
   /** Last mint attempt per device, so a refusal that survives minting cannot spin. */
   static lastRemintAt = new Map<string, number>();
   static readonly remintCooldownMs = 10 * 60 * 1000;
@@ -232,7 +241,7 @@ class SpotifyConnectInstance {
       this.log.warn('spotify connect host start failed', { zoneId: this.zoneId, message });
       return null;
     });
-    if (!native && SpotifyConnectInstance.rejectedCredentials.has(this.deviceCredentialKey(deviceId))) {
+    if (!native && SpotifyConnectInstance.isRejected(this.deviceCredentialKey(deviceId))) {
       // Login was refused rather than unreachable: mint a blob for this device and try once more,
       // instead of handing the same refused one back on every scheduled restart.
       const minted = await this.mintCredentialsForDevice(deviceId, 'connect_login_refused');
@@ -405,7 +414,47 @@ class SpotifyConnectInstance {
   private markCredentialsRejected(deviceId: string): void {
     const key = this.deviceCredentialKey(deviceId);
     SpotifyConnectInstance.deviceCredentials.delete(key);
-    SpotifyConnectInstance.rejectedCredentials.add(key);
+    SpotifyConnectInstance.rejectedCredentials.set(key, Date.now());
+  }
+
+  /** Whether this device's blob is currently under a refusal verdict that has not yet expired. */
+  static isRejected(key: string): boolean {
+    const at = SpotifyConnectInstance.rejectedCredentials.get(key);
+    if (at === undefined) {
+      return false;
+    }
+    if (Date.now() - at < SpotifyConnectInstance.rejectionTtlMs) {
+      return true;
+    }
+    SpotifyConnectInstance.rejectedCredentials.delete(key);
+    return false;
+  }
+
+  /**
+   * Drop every per-device verdict held for an account.
+   *
+   * Called when a new account-level blob arrives. Without this a fresh blob is unreachable:
+   * `credentialsForDevice` consults the refusal flag before falling back to the account payload, so
+   * a zone that had already been refused would keep logging in with nothing at all — pairing would
+   * report success and change nothing until a restart.
+   */
+  static clearVerdictsForAccount(accountId: string): void {
+    const prefix = `${accountId}::`;
+    for (const key of [...SpotifyConnectInstance.rejectedCredentials.keys()]) {
+      if (key.startsWith(prefix)) {
+        SpotifyConnectInstance.rejectedCredentials.delete(key);
+      }
+    }
+    for (const key of [...SpotifyConnectInstance.deviceCredentials.keys()]) {
+      if (key.startsWith(prefix)) {
+        SpotifyConnectInstance.deviceCredentials.delete(key);
+      }
+    }
+    for (const key of [...SpotifyConnectInstance.lastRemintAt.keys()]) {
+      if (key.startsWith(prefix)) {
+        SpotifyConnectInstance.lastRemintAt.delete(key);
+      }
+    }
   }
 
   /**
@@ -418,7 +467,7 @@ class SpotifyConnectInstance {
     if (proven) {
       return proven;
     }
-    if (SpotifyConnectInstance.rejectedCredentials.has(key)) {
+    if (SpotifyConnectInstance.isRejected(key)) {
       return null;
     }
     return this.credentialsPayload;
@@ -440,7 +489,7 @@ class SpotifyConnectInstance {
     }
     SpotifyConnectInstance.lastRemintAt.set(key, Date.now());
     // Mark refused up front: if the mint fails, the seed must not be replayed on the next attempt.
-    SpotifyConnectInstance.rejectedCredentials.add(key);
+    SpotifyConnectInstance.rejectedCredentials.set(key, Date.now());
     SpotifyConnectInstance.deviceCredentials.delete(key);
 
     let accessToken: string | null | undefined;
@@ -1764,6 +1813,9 @@ export class SpotifyInputService {
     const serialized =
       typeof credentials === 'string' ? credentials : JSON.stringify(credentials, null, 2);
     SpotifyConnectInstance.accountCredentials.set(accountId, serialized);
+    // A new blob overrules every verdict recorded against the old one. Without this the zones that
+    // had already been refused would ignore the one credential that now works.
+    SpotifyConnectInstance.clearVerdictsForAccount(accountId);
     await bestEffort(
       () =>
         this.configPort.updateConfig((cfg) => {