nixamp 0.29.1 → 0.30.3

package/src/station-mcp.ts

@@ -0,0 +1,183 @@
+/**
+ * Stations as MCP tools: what `nixamp station` does, for an agent.
+ *
+ * The same API and the same rules as the CLI and the page. On this machine
+ * the tools use the daemon's control key, which is what being on the machine
+ * means; for another server they send this machine's nixamp.com session,
+ * which the server accepts only if that account owns it. Publishing is its
+ * own tool and asks for the basis, exactly as for a person.
+ */
+import { daemonUrl, readState } from "./daemon.ts";
+import { readSession } from "./session.ts";
+import { KEY_HEADER } from "./share.ts";
+
+const STRING = { type: "string" } as const;
+const ID = { ...STRING, description: "The station's id (10 characters), from station_list." };
+const SERVER = { ...STRING, description: "A nixamp server's address; this machine's daemon when omitted." };
+
+export const STATION_TOOLS = [
+  {
+    name: "station_list",
+    description: "List this server's stations: id, name, state (live, stopped, offline...), visibility and listening link.",
+    inputSchema: { type: "object", properties: { server: SERVER } },
+  },
+  {
+    name: "station_get",
+    description: "One station in full: files, rotation, state, any problem, and its links.",
+    inputSchema: { type: "object", properties: { server: SERVER, id: ID }, required: ["id"] },
+  },
+  {
+    name: "station_create",
+    description: "Make a station from a folder in the library (path relative to it, \"\" for all of it) or from track indexes. It starts private and stopped; nothing is published.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        server: SERVER,
+        name: STRING,
+        folder: { ...STRING, description: "A folder under the library, e.g. \"Albums/Late Night\"." },
+        items: { type: "array", items: { type: "integer" }, description: "Track indexes, as /api/state lists them." },
+        description: STRING,
+        shuffle: { type: "boolean" },
+        repeat: { type: "boolean", description: "Round and round (default) or once." },
+        bitrate: { type: "integer", description: "kbps: 64, 96, 128 (default), 160, 192, 256 or 320." },
+        idempotencyKey: { ...STRING, description: "Asking again with the same key returns the same station." },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "station_update",
+    description: "Rename, describe, change files or rotation. Edits to the files land on the next track.",
+    inputSchema: {
+      type: "object",
+      properties: { server: SERVER, id: ID, name: STRING, description: STRING, folder: STRING, items: { type: "array", items: { type: "integer" } }, shuffle: { type: "boolean" }, repeat: { type: "boolean" }, bitrate: { type: "integer" } },
+      required: ["id"],
+    },
+  },
+  {
+    name: "station_control",
+    description: "start, stop or skip a station, or retry the files it left out. Starting does not publish.",
+    inputSchema: {
+      type: "object",
+      properties: { server: SERVER, id: ID, action: { type: "string", enum: ["start", "stop", "skip", "retry"] } },
+      required: ["id", "action"],
+    },
+  },
+  {
+    name: "station_publish",
+    description: "Make a station unlisted (a link) or public (and listed in the nixamp.com directory). Public needs the basis on which it may be broadcast: owned, permission, licensed or public-domain. A declaration, not legal clearance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        server: SERVER,
+        id: ID,
+        visibility: { type: "string", enum: ["unlisted", "public"] },
+        listed: { type: "boolean", description: "In the directory (public only). Default true for public." },
+        basis: { type: "string", enum: ["owned", "permission", "licensed", "public-domain"] },
+        note: STRING,
+      },
+      required: ["id", "visibility"],
+    },
+  },
+  {
+    name: "station_unpublish",
+    description: "Take a station out of the directory, or make it private: its links stop working and listeners are disconnected.",
+    inputSchema: { type: "object", properties: { server: SERVER, id: ID, private: { type: "boolean" } }, required: ["id"] },
+  },
+];
+
+interface Result {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+}
+
+const say = (value: string, isError = false): Result => ({ content: [{ type: "text", text: value }], ...(isError ? { isError: true } : {}) });
+
+export interface StationToolOptions {
+  fetcher?: typeof fetch;
+  /** Where the local daemon is and its key; the tests hand these in. */
+  local?: { url: string; key: string | null } | null;
+  session?: { site: string; token: string } | null;
+}
+
+export function isStationTool(name: string): boolean {
+  return STATION_TOOLS.some((tool) => tool.name === name);
+}
+
+function line(station: Record<string, unknown>): string {
+  const links = (station["links"] ?? {}) as Record<string, string>;
+  const problem = station["error"] ? `; problem: ${String(station["error"])}` : "";
+  const link = station["visibility"] !== "private" && links["page"] ? `\n  listen: ${links["page"]}` : "";
+  return `${String(station["name"])} [${String(station["id"])}] ${String(station["state"])}, ${String(station["visibility"])}${station["listed"] ? " and listed" : ""}${problem}${link}`;
+}
+
+export async function callStationTool(name: string, args: Record<string, unknown>, options: StationToolOptions = {}): Promise<Result> {
+  const send = options.fetcher ?? fetch;
+  const server = typeof args["server"] === "string" ? args["server"].replace(/\/+$/, "") : "";
+  let base = server;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (server === "") {
+    const local = options.local === undefined ? (() => { const state = readState(); return state ? { url: daemonUrl(state), key: state.key } : null; })() : options.local;
+    if (!local) return say("No nixamp daemon runs on this machine. Start one (nixamp daemon start ~/Music) or pass `server`.", true);
+    base = local.url;
+    if (local.key) headers[KEY_HEADER] = local.key;
+  } else {
+    const session = options.session === undefined ? readSession() : options.session;
+    if (!session) return say("Another server's stations need this machine signed in as its owner: nixamp login.", true);
+    headers["authorization"] = `Bearer ${session.token}`;
+  }
+  const id = typeof args["id"] === "string" ? args["id"] : "";
+  const call = async (method: string, path: string, body?: unknown): Promise<{ ok: boolean; body: Record<string, unknown> }> => {
+    const response = await send(`${base}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    const parsed = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+    return { ok: response.ok, body: parsed };
+  };
+  const refused = (body: Record<string, unknown>): Result => say(`${String(body["error"] ?? "refused")} (${String(body["code"] ?? "error")})`, true);
+  const pick = (keys: string[]): Record<string, unknown> => Object.fromEntries(keys.filter((key) => args[key] !== undefined).map((key) => [key, args[key]]));
+
+  try {
+    if (name === "station_list") {
+      const answer = await call("GET", "/api/v1/stations?limit=200");
+      if (!answer.ok) return refused(answer.body);
+      const all = (answer.body["stations"] as Record<string, unknown>[] | undefined) ?? [];
+      return say(all.length === 0 ? "No stations on this server yet." : all.map(line).join("\n"));
+    }
+    if (!/^[a-z0-9]{10}$/.test(id) && name !== "station_create") return say("Which station? Pass its id from station_list.", true);
+    if (name === "station_get") {
+      const answer = await call("GET", `/api/v1/stations/${id}`);
+      return answer.ok ? say(JSON.stringify(answer.body["station"], null, 2)) : refused(answer.body);
+    }
+    if (name === "station_create") {
+      const answer = await call("POST", "/api/v1/stations", pick(["name", "folder", "items", "description", "shuffle", "repeat", "bitrate", "idempotencyKey"]));
+      return answer.ok ? say(`Made, private and stopped: ${line(answer.body["station"] as Record<string, unknown>)}`) : refused(answer.body);
+    }
+    if (name === "station_update") {
+      const answer = await call("PATCH", `/api/v1/stations/${id}`, pick(["name", "description", "folder", "items", "shuffle", "repeat", "bitrate"]));
+      return answer.ok ? say(line(answer.body["station"] as Record<string, unknown>)) : refused(answer.body);
+    }
+    if (name === "station_control") {
+      const action = String(args["action"] ?? "");
+      if (!["start", "stop", "skip", "retry"].includes(action)) return say("action is start, stop, skip or retry", true);
+      const answer = await call("POST", `/api/v1/stations/${id}/${action}`, {});
+      return answer.ok ? say(line(answer.body["station"] as Record<string, unknown>)) : refused(answer.body);
+    }
+    if (name === "station_publish") {
+      const visibility = args["visibility"] === "public" ? "public" : "unlisted";
+      const answer = await call("POST", `/api/v1/stations/${id}/access`, {
+        visibility,
+        listed: visibility === "public" && args["listed"] !== false,
+        ...(typeof args["basis"] === "string" ? { rights: { basis: args["basis"], note: typeof args["note"] === "string" ? args["note"] : "" } } : {}),
+      });
+      return answer.ok ? say(line(answer.body["station"] as Record<string, unknown>)) : refused(answer.body);
+    }
+    if (name === "station_unpublish") {
+      const answer = await call("POST", `/api/v1/stations/${id}/access`, args["private"] === true ? { visibility: "private" } : { listed: false });
+      if (!answer.ok) return refused(answer.body);
+      const dropped = Number(answer.body["dropped"] ?? 0);
+      return say(`${line(answer.body["station"] as Record<string, unknown>)}${dropped ? `\n${dropped} listener(s) disconnected.` : ""}`);
+    }
+  } catch (error) {
+    return say(`Could not reach ${base}: ${(error as Error).message}`, true);
+  }
+  return say(`No such tool: ${name}`, true);
+}

package/src/station-page.ts

@@ -0,0 +1,145 @@
+/**
+ * The page a station's link opens: its name, what is on, and Play.
+ *
+ * Served by the station's own server, without the server's key, because the
+ * link is the key: the page reads `t` from its own address and asks the
+ * station's state and stream with it. Nothing about the station is written
+ * into the HTML, so the page is the same bytes for every station and can be
+ * locked down with a content security policy naming its script and style by
+ * hash. A private station, or a wrong link, shows "not available" -- the
+ * same answer, so the page cannot be used to find out which stations exist.
+ */
+import { createHash } from "node:crypto";
+
+const STYLE = `
+:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}
+@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}
+*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:560px;margin:0 auto;padding:48px 16px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}
+h1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}
+.about{color:var(--muted);margin:0 0 20px}
+.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}
+.chip::before{content:"";width:8px;height:8px;border-radius:50%;background:currentColor}
+.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}
+.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}
+.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}
+button{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}
+button:disabled{opacity:.5;cursor:not-allowed}
+button:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}
+label{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}
+input[type=range]{width:120px;accent-color:var(--accent)}
+.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}
+.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}
+@keyframes pulse{50%{opacity:.35}}
+`;
+
+const SCRIPT = `
+(() => {
+  const id = location.pathname.split("/").filter(Boolean)[1] || "";
+  const token = new URLSearchParams(location.search).get("t") || "";
+  const q = "?t=" + encodeURIComponent(token);
+  const api = "/api/v1/stations/" + encodeURIComponent(id);
+  const $ = (s) => document.querySelector(s);
+  const audio = new Audio();
+  audio.preload = "none";
+  let wanted = false, retry = 0, timer = 0, last = null;
+  const chip = (state, text) => { const c = $("#state"); c.className = "chip " + state; c.textContent = text; };
+  const say = (text) => { $("#announce").textContent = text; };
+  const draw = (s) => {
+    last = s;
+    document.title = s.name + " · nixamp";
+    $("#name").textContent = s.name;
+    $("#about").textContent = s.description || "";
+    $("#about").hidden = !s.description;
+    const playing = s.nowPlaying;
+    $("#title").textContent = playing ? (playing.title || "Untitled") : (s.state === "live" ? "On the air" : "");
+    $("#by").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(" · ") : "";
+    if (wanted && retry > 0) chip("reconnecting", "Reconnecting");
+    else if (s.state === "live") chip("live", "Live");
+    else if (s.state === "starting" || s.state === "recovering") chip("reconnecting", "Coming back");
+    else if (s.state === "stopped") chip("stopped", "Off the air");
+    else chip("unavailable", "Unavailable");
+    $("#play").disabled = !(s.state === "live" || s.state === "recovering" || s.state === "starting");
+    $("#m3u").href = api + "/listen.m3u" + q;
+  };
+  const poll = async () => {
+    try {
+      const r = await fetch(api + "/state" + q, { cache: "no-store" });
+      if (r.status === 404) { $("#name").textContent = "This station is not available"; chip("unavailable", "Unavailable"); $("#play").disabled = true; stop(); return; }
+      if (r.ok) draw(await r.json());
+    } catch {}
+  };
+  // Always the live edge: a fresh request, never a cached or paused one.
+  const join = () => { audio.src = api + "/stream" + q + "&n=" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };
+  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute("src"); audio.load(); button(); };
+  const button = () => { const b = $("#play"); b.textContent = wanted ? "Stop" : "Play"; b.setAttribute("aria-pressed", String(wanted)); };
+  const again = () => {
+    if (!wanted) return;
+    retry += 1;
+    if (last) draw(last);
+    clearTimeout(timer);
+    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));
+  };
+  audio.addEventListener("playing", () => { if (retry) say("Back on"); retry = 0; if (last) draw(last); });
+  audio.addEventListener("error", again);
+  audio.addEventListener("ended", again);
+  audio.addEventListener("stalled", () => { if (wanted && audio.readyState < 3) again(); });
+  $("#play").addEventListener("click", () => { if (wanted) { stop(); say("Stopped"); } else { wanted = true; retry = 0; button(); join(); say("Playing"); } });
+  $("#volume").addEventListener("input", (e) => { audio.volume = Number(e.target.value); });
+  poll();
+  setInterval(poll, 5000);
+})();
+`;
+
+const hash = (text: string): string => `'sha256-${createHash("sha256").update(text).digest("base64")}'`;
+
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<link rel="icon" href="data:,">
+<title>Station · nixamp</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+  <div class="card">
+    <span id="state" class="chip unavailable" role="status">Loading</span>
+    <h1 id="name">&nbsp;</h1>
+    <p id="about" class="about" hidden></p>
+    <div class="now" aria-live="polite"><div id="title" class="title"></div><div id="by" class="by"></div></div>
+    <div class="controls">
+      <button id="play" type="button" aria-pressed="false" disabled>Play</button>
+      <label>Volume <input id="volume" type="range" min="0" max="1" step="0.05" value="1"></label>
+    </div>
+    <p class="small"><a id="m3u" href="#">Open in another player (.m3u)</a> · Pausing here does not pause the station.</p>
+  </div>
+  <p class="small">Played by <a href="https://nixamp.com">nixamp</a>.</p>
+  <div id="announce" class="sr" aria-live="assertive"></div>
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+
+/** A station page's path: /station/<id>. */
+export const STATION_PAGE = /^\/station\/([a-z0-9]{10})\/?$/;
+
+export const STATION_PAGE_HTML = PAGE;
+
+/** Only its own script and style, only its own server, never framed. */
+export const STATION_PAGE_CSP = [
+  "default-src 'none'",
+  `script-src ${hash(SCRIPT)}`,
+  `style-src ${hash(STYLE)}`,
+  "connect-src 'self'",
+  "media-src 'self'",
+  "img-src 'self' data:",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'none'",
+].join("; ");

package/src/station-routes.ts

@@ -0,0 +1,302 @@
+/**
+ * /api/v1/stations: making, running and sharing stations.
+ *
+ * Two kinds of caller, kept apart. The owner -- the control key, or the
+ * nixamp.com account that owns this server -- manages: create, edit, start,
+ * stop, skip, share. A listener holds one station's link and may do three
+ * things with it: hear the stream, ask what is on, and fetch an .m3u for
+ * another player. A listener's link never opens the library, another station,
+ * or anything that changes what is playing.
+ *
+ * Errors carry a stable `code` beside the sentence, so the page, the CLI and
+ * an agent over MCP can each tell "rights_required" from "not_found" without
+ * reading English.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Channels } from "./channels.ts";
+import type { StationRunner } from "./station-runner.ts";
+import {
+  StationError, channelOf, tokensMatch, type OwnerStation, type PublicStation, type Station, type StationStore,
+} from "./stations.ts";
+
+/** The three things a station's link opens. */
+const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u)$/;
+
+/** Whether this path is one a station's own link may open, without the server's key. */
+export function isStationListenPath(path: string): boolean {
+  return LISTEN.test(path);
+}
+
+export interface StationContext {
+  store: StationStore;
+  runner: StationRunner;
+  channels: Channels;
+  /** Holds the control key, or is signed in as this server's owner. */
+  canControl: boolean;
+  /** The nixamp.com account asking, "" when it is the control key. */
+  account: string;
+  /** Files chosen by track index or by folder; null when neither was given. */
+  select: (body: { items?: unknown; folder?: unknown }) => string[] | null;
+  /** What the library knows about a file, for now playing. */
+  trackFor: (file: string) => { title: string; artist: string; album: string } | null;
+  /** This server's address as the asker reached it, for links. */
+  base: string;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<string>;
+  /** Headers every answer carries (CORS). */
+  headers: Record<string, string>;
+}
+
+function fail(ctx: StationContext, response: ServerResponse, error: unknown): void {
+  if (error instanceof StationError) {
+    ctx.json(response, error.status, { error: error.message, code: error.code });
+    return;
+  }
+  ctx.json(response, 500, { error: error instanceof Error ? error.message : String(error), code: "internal" });
+}
+
+function links(ctx: StationContext, station: Station): { page: string; stream: string; m3u: string; state: string } {
+  const query = `t=${encodeURIComponent(station.listenToken)}`;
+  const at = `${ctx.base}/api/v1/stations/${station.id}`;
+  return {
+    page: `${ctx.base}/station/${station.id}?${query}`,
+    stream: `${at}/stream?${query}`,
+    m3u: `${at}/listen.m3u?${query}`,
+    state: `${at}/state?${query}`,
+  };
+}
+
+/** The file on the air now, as the channel's own encoder last reported it. */
+function nowPlayingFile(ctx: StationContext, station: Station): string {
+  const info = ctx.channels.info(channelOf(station.id));
+  if (!info?.playlist?.length) return "";
+  return info.playlist[info.playlistAt ?? 0] ?? "";
+}
+
+export function publicView(ctx: StationContext, station: Station): PublicStation {
+  const state = ctx.runner.observed(station.id);
+  const file = state === "live" || state === "recovering" ? nowPlayingFile(ctx, station) : "";
+  // The tags the player read when it put this file on, else the library's.
+  const track = file ? (ctx.channels.tagsOf(channelOf(station.id), file) ?? ctx.trackFor(file)) : null;
+  return {
+    id: station.id,
+    name: station.name,
+    description: station.description,
+    visibility: station.visibility,
+    state,
+    // Tags, or nothing: a bare file name is the owner's, not the public's.
+    nowPlaying: track && (track.title || track.artist) ? track : null,
+    format: state === "stopped" || state === "offline" ? null : { codec: "mp3", bitrateKbps: station.bitrate, sampleRate: 48_000, channels: 2 },
+    listeners: ctx.runner.listeners(station.id),
+  };
+}
+
+export function ownerView(ctx: StationContext, station: Station): OwnerStation & { links: ReturnType<typeof links>; nowPlaying: string } {
+  const { failures, idempotencyKey: _key, ...rest } = station;
+  return {
+    ...rest,
+    state: ctx.runner.observed(station.id),
+    excluded: Object.entries(failures).filter(([, count]) => count >= 3).map(([file]) => file),
+    listeners: ctx.runner.listeners(station.id),
+    error: ctx.runner.error(station.id),
+    links: links(ctx, station),
+    nowPlaying: nowPlayingFile(ctx, station),
+  };
+}
+
+/** Answers anything under /api/v1/stations; false when the path is not one. */
+export async function handleStations(
+  request: IncomingMessage,
+  response: ServerResponse,
+  path: string,
+  url: URL,
+  ctx: StationContext,
+): Promise<boolean> {
+  if (path !== "/api/v1/stations" && !path.startsWith("/api/v1/stations/")) return false;
+  const method = request.method ?? "GET";
+
+  const listen = LISTEN.exec(path);
+  if (listen) {
+    const station = ctx.store.get(listen[1]!);
+    const token = url.searchParams.get("t") ?? "";
+    // The same answer for "no such station" and "not with that link", so a
+    // link cannot be used to find out which stations exist.
+    const allowed = station !== undefined &&
+      (ctx.canControl || (station.visibility !== "private" && token !== "" && tokensMatch(token, station.listenToken)));
+    if (!station || !allowed) {
+      ctx.json(response, 404, { error: "no such station, or not with that link", code: "not_found" });
+      return true;
+    }
+    if (method !== "GET" && method !== "HEAD") {
+      ctx.json(response, 405, { error: "a station's link can listen, not drive", code: "method_not_allowed" });
+      return true;
+    }
+    const what = listen[2];
+    if (what === "state") {
+      ctx.json(response, 200, publicView(ctx, station));
+      return true;
+    }
+    if (what === "listen.m3u") {
+      const stream = links(ctx, station).stream;
+      response.writeHead(200, {
+        ...ctx.headers,
+        "content-type": "audio/x-mpegurl; charset=utf-8",
+        "content-disposition": `inline; filename="${station.id}.m3u"`,
+        "cache-control": "no-store",
+      });
+      response.end(`#EXTM3U\n#EXTINF:-1,${station.name.replace(/[\r\n]/g, " ")}\n${stream}\n`);
+      return true;
+    }
+    const channelId = channelOf(station.id);
+    if (!ctx.channels.has(channelId)) {
+      ctx.json(response, 503, { error: "the station is not on the air", code: "not_live", state: ctx.runner.observed(station.id) });
+      return true;
+    }
+    response.writeHead(200, { ...ctx.headers, "content-type": ctx.channels.contentType(channelId), "cache-control": "no-store" });
+    if (method === "HEAD") {
+      response.end();
+      return true;
+    }
+    const detach = ctx.channels.listen(channelId, response);
+    if (detach === null) {
+      response.end();
+      return true;
+    }
+    const untrack = ctx.runner.track(station.id, { end: () => response.destroy() });
+    const leave = (): void => {
+      detach();
+      untrack();
+    };
+    request.on("close", leave);
+    response.on("close", leave);
+    return true;
+  }
+
+  // Everything else is the owner's.
+  if (!ctx.canControl) {
+    ctx.json(response, 403, { error: "only this server's owner manages its stations", code: "forbidden" });
+    return true;
+  }
+
+  const body = async (): Promise<Record<string, unknown>> => {
+    if (method === "GET" || method === "DELETE") return {};
+    const raw = await ctx.readBody(request);
+    if (raw.trim() === "") return {};
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new StationError("bad_json", "the body is not JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new StationError("bad_json", "the body is not a JSON object");
+    return parsed as Record<string, unknown>;
+  };
+
+  try {
+    if (path === "/api/v1/stations") {
+      if (method === "GET") {
+        const all = ctx.store.list();
+        const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit")) || 50));
+        const offset = Math.max(0, Number(url.searchParams.get("offset")) || 0);
+        ctx.json(response, 200, { stations: all.slice(offset, offset + limit).map((one) => ownerView(ctx, one)), total: all.length, limit, offset });
+        return true;
+      }
+      if (method === "POST") {
+        const input = await body();
+        const key = String(request.headers["idempotency-key"] ?? input["idempotencyKey"] ?? "").trim();
+        const again = ctx.store.byIdempotencyKey(key);
+        if (again) {
+          ctx.json(response, 200, { station: ownerView(ctx, again), created: false });
+          return true;
+        }
+        const items = ctx.select(input);
+        if (items === null) throw new StationError("items_required", "choose files by track index (items) or a folder");
+        const station = ctx.store.create(input, items, ctx.account, Date.now(), key);
+        ctx.json(response, 201, { station: ownerView(ctx, station), created: true });
+        return true;
+      }
+      ctx.json(response, 405, { error: "GET or POST", code: "method_not_allowed" });
+      return true;
+    }
+
+    const match = /^\/api\/v1\/stations\/([a-z0-9]{10})(?:\/([a-z-]+))?$/.exec(path);
+    if (!match) {
+      ctx.json(response, 404, { error: "no such station", code: "not_found" });
+      return true;
+    }
+    const id = match[1]!;
+    const action = match[2];
+    const station = ctx.store.get(id);
+    if (!station) {
+      ctx.json(response, 404, { error: "no such station", code: "not_found" });
+      return true;
+    }
+
+    if (action === undefined) {
+      if (method === "GET") {
+        ctx.json(response, 200, { station: ownerView(ctx, station) });
+        return true;
+      }
+      if (method === "PATCH") {
+        const input = await body();
+        const items = ctx.select(input);
+        const updated = ctx.store.update(id, input, items);
+        ctx.json(response, 200, { station: ownerView(ctx, updated) });
+        return true;
+      }
+      if (method === "DELETE") {
+        ctx.runner.remove(id);
+        ctx.json(response, 200, { deleted: id });
+        return true;
+      }
+      ctx.json(response, 405, { error: "GET, PATCH or DELETE", code: "method_not_allowed" });
+      return true;
+    }
+
+    if (method !== "POST") {
+      ctx.json(response, 405, { error: "POST", code: "method_not_allowed" });
+      return true;
+    }
+    if (action === "start") {
+      const started = await ctx.runner.start(id);
+      ctx.json(response, 200, { station: ownerView(ctx, started) });
+      return true;
+    }
+    if (action === "stop") {
+      ctx.json(response, 200, { station: ownerView(ctx, ctx.runner.stop(id)) });
+      return true;
+    }
+    if (action === "skip") {
+      ctx.runner.skip(id);
+      ctx.json(response, 200, { station: ownerView(ctx, station) });
+      return true;
+    }
+    if (action === "retry") {
+      ctx.json(response, 200, { station: ownerView(ctx, ctx.store.clearFailures(id)) });
+      return true;
+    }
+    if (action === "rotate-link") {
+      const rotated = ctx.store.rotateToken(id);
+      const dropped = ctx.runner.revoke(id);
+      ctx.json(response, 200, { station: ownerView(ctx, rotated), dropped });
+      return true;
+    }
+    if (action === "access") {
+      const input = await body();
+      const rights = input["rights"];
+      const { station: changed, revoked } = ctx.store.setAccess(id, {
+        visibility: input["visibility"],
+        listed: input["listed"],
+        rights: typeof rights === "object" && rights !== null ? rights as { basis?: unknown; note?: unknown } : null,
+      }, ctx.account || "control-key");
+      const dropped = revoked ? ctx.runner.revoke(id) : 0;
+      ctx.json(response, 200, { station: ownerView(ctx, changed), dropped });
+      return true;
+    }
+    ctx.json(response, 404, { error: "no such action", code: "not_found" });
+    return true;
+  } catch (error) {
+    fail(ctx, response, error);
+    return true;
+  }
+}