nixamp 0.33.0 → 0.34.0

package/dist/server.js

@@ -58,6 +58,8 @@ import { handleStations, isStationListenPath } from "./station-routes.js";
 import { handleLibrary } from "./library-routes.js";
 import { LibraryIndex, probeItem, trackOf } from "./library-index.js";
 import { ListenerStore } from "./library-user.js";
+import { Importer } from "./handoff.js";
+import { handleHandoffs } from "./handoff-routes.js";
 import { STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.js";
 import { StationRunner } from "./station-runner.js";
 import { StationError, StationStore, stationOfChannel } from "./stations.js";
@@ -2227,6 +2229,17 @@ export function createHandler(engine, options) {
             });
             return;
         }
+        if (options.importer && path.startsWith("/api/v1/integrations/bittorrented/")) {
+            const control = await controlOf();
+            await handleHandoffs(request, response, path, {
+                importer: options.importer,
+                canWrite: control.allowed,
+                owner: control.account || "owner",
+                json,
+                readBody,
+            });
+            return;
+        }
         if (options.stations && (path === "/api/v1/stations" || path.startsWith("/api/v1/stations/"))) {
             const control = await controlOf();
             const encrypted = request.socket.encrypted === true;
@@ -2343,12 +2356,17 @@ export function createHandler(engine, options) {
                 return;
             }
             if (path === "/api/v1/auth/me") {
-                const who = await accounts.whoIs(tokenFrom(request.headers));
+                const token = tokenFrom(request.headers);
+                const who = await accounts.whoIs(token);
                 if (who === null) {
                     json(response, 401, { error: "not signed in" });
                     return;
                 }
-                json(response, 200, { account: who });
+                // An app acting for the person says so, with what it was allowed:
+                // a server asking "is this my owner?" must not take a token handed to
+                // some other app as the owner themselves.
+                const grant = options.authServer ? await options.authServer.grantFor(token) : null;
+                json(response, 200, { account: who, ...(grant ? { grant: { clientId: grant.clientId, scope: grant.scope } } : {}) });
                 return;
             }
             /**
@@ -3599,11 +3617,28 @@ export function createHandler(engine, options) {
         // point: a share link in a terminal you closed is a server you have lost.
         if ((path === "/api/v1/servers" || path.startsWith("/api/v1/servers/")) && options.servers && options.accounts) {
             const servers = options.servers;
-            const who = await options.accounts.whoIs(tokenFrom(request.headers));
+            const token = tokenFrom(request.headers);
+            const who = await options.accounts.whoIs(token);
             if (who === null) {
                 json(response, 401, { error: "not signed in" });
                 return;
             }
+            // An app acting for the person sees the list only with a scope that
+            // says so, may not change it, and never gets a control key: those are
+            // the person's, and an app that held one could drive the machine.
+            const grant = options.authServer ? await options.authServer.grantFor(token) : null;
+            if (grant) {
+                if (!(grant.scope.includes("streams") || grant.scope.includes("stations"))) {
+                    json(response, 403, { error: "this app was not given access to your servers", code: "insufficient_scope" });
+                    return;
+                }
+                if (!(path === "/api/v1/servers" && request.method === "GET")) {
+                    json(response, 403, { error: "an app may list your servers, not change them", code: "insufficient_scope" });
+                    return;
+                }
+                json(response, 200, { servers: (await servers.list(who.id)).map(({ key: _key, ...shown }) => shown) });
+                return;
+            }
             if (path === "/api/v1/servers" && request.method === "GET") {
                 json(response, 200, { servers: await servers.list(who.id) });
                 return;
@@ -6147,6 +6182,16 @@ export async function serve(argv, version = "0.1.0") {
         log: (line) => console.log(line),
     });
     const stations = { store: stationStore, runner: stationRunner };
+    // Music handed over from BitTorrented, copied into a folder of our own.
+    const importer = new Importer(join(stateDir(), `handoffs-${options.port}.json`), {
+        index: libraryIndex,
+        stations: stationStore,
+        root: join(stateDir(), "imports", "bittorrented"),
+        probe: probeFile,
+        guard: (url) => refusedDestination(url),
+        log: (line) => console.log(line),
+    });
+    importer.resume();
     // Channels as HLS, on demand, for Safari on a phone: one ffmpeg copying a
     // channel's fragments into short files while somebody is asking for them.
     // What things are, from nichedb.dev, remembered beside the keys so a
@@ -6727,6 +6772,7 @@ export async function serve(argv, version = "0.1.0") {
         channels,
         stations,
         library,
+        importer,
         rememberChannels: remembering,
         catalogs,
         publishUrls: () => publishUrls,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/handoff-routes.ts

@@ -0,0 +1,73 @@
+/**
+ * /api/v1/integrations/bittorrented/handoffs: where BitTorrented hands music
+ * over. Only this server's owner -- the control key, the owner's session, or
+ * an app the owner gave the `stations` scope -- may hand anything over, list
+ * handoffs, retry one or delete its copies.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { publicHandoff, type Importer } from "./handoff.ts";
+import { LibraryError } from "./library-index.ts";
+
+export interface HandoffContext {
+  importer: Importer;
+  canWrite: boolean;
+  /** Whose handoffs: the owner's account, or "owner" for the control key. */
+  owner: string;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<string>;
+}
+
+const BASE = "/api/v1/integrations/bittorrented/handoffs";
+
+export async function handleHandoffs(request: IncomingMessage, response: ServerResponse, path: string, ctx: HandoffContext): Promise<boolean> {
+  if (path !== BASE && !path.startsWith(`${BASE}/`)) return false;
+  const method = request.method ?? "GET";
+  const fail = (status: number, code: string, error: string): true => {
+    ctx.json(response, status, { error, code });
+    return true;
+  };
+  if (!ctx.canWrite) return fail(403, "forbidden", "only this server's owner (or an app they gave the stations scope) hands music over");
+  const body = async (): Promise<Record<string, unknown>> => {
+    const raw = await ctx.readBody(request);
+    if (raw.trim() === "") return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new LibraryError("bad_json", "the body is not a JSON object");
+    return parsed as Record<string, unknown>;
+  };
+  try {
+    if (path === BASE) {
+      if (method === "GET") {
+        ctx.json(response, 200, { handoffs: ctx.importer.list(ctx.owner).map(publicHandoff) });
+        return true;
+      }
+      if (method === "POST") {
+        const { handoff, created } = ctx.importer.create(await body(), ctx.owner);
+        ctx.json(response, created ? 201 : 200, { handoff: publicHandoff(handoff), created });
+        return true;
+      }
+      return fail(405, "method_not_allowed", "GET or POST");
+    }
+    const match = /^\/api\/v1\/integrations\/bittorrented\/handoffs\/([0-9a-f]{16})(?:\/(retry))?$/.exec(path);
+    const handoff = match ? ctx.importer.get(match[1]!) : undefined;
+    if (!match || !handoff || handoff.owner !== ctx.owner) return fail(404, "not_found", "no such handoff");
+    if (match[2] === "retry") {
+      if (method !== "POST") return fail(405, "method_not_allowed", "POST");
+      ctx.json(response, 200, { handoff: publicHandoff(ctx.importer.retry(handoff.id, await body())) });
+      return true;
+    }
+    if (method === "GET") {
+      ctx.json(response, 200, { handoff: publicHandoff(handoff) });
+      return true;
+    }
+    if (method === "DELETE") {
+      const removed = ctx.importer.remove(handoff.id);
+      ctx.json(response, 200, { deleted: handoff.id, copiesRemoved: removed });
+      return true;
+    }
+    return fail(405, "method_not_allowed", "GET or DELETE");
+  } catch (error) {
+    if (error instanceof LibraryError) return fail(error.status, error.code, error.message);
+    if (error instanceof SyntaxError) return fail(400, "bad_json", "the body is not JSON");
+    return fail(500, "internal", error instanceof Error ? error.message : String(error));
+  }
+}

package/src/handoff.ts

@@ -0,0 +1,383 @@
+/**
+ * Music handed over from BitTorrented: copied here, checked, indexed, and
+ * made into a private station draft.
+ *
+ * BitTorrented keeps its own collections and downloads; Nixamp keeps what it
+ * was handed. A handoff names the files a person chose, each with a link that
+ * opens that one file for a short while and nothing else. Nixamp copies each
+ * file into its own imports folder, so a station plays from a copy on this
+ * machine and does not depend on anybody still seeding it. A file is "ready"
+ * only once the copy has the size it was said to have and ffprobe can read
+ * it; until then it is pending, and a station never plays it.
+ *
+ * Asking twice with the same idempotency key is one handoff and one station.
+ * Removing the item in BitTorrented does not touch the copy here; deleting the
+ * handoff here removes the copies it made (and only those), which is the one
+ * place a Nixamp action deletes files, so it is said wherever it is offered.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createWriteStream, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { LibraryError, type LibraryIndex, type Probed } from "./library-index.ts";
+import { playable } from "./playlist.ts";
+import type { StationStore } from "./stations.ts";
+
+export type FileState = "pending" | "downloading" | "ready" | "failed" | "expired" | "unsupported";
+
+export interface HandoffFile {
+  fileId: string;
+  name: string;
+  size: number;
+  mediaType: string;
+  /** Whether BitTorrented said the download was complete when it handed it over. */
+  complete: boolean;
+  state: FileState;
+  error: string;
+  attempts: number;
+  /** Where the copy is (or will be). Shown to the owner only. */
+  path: string;
+  bytes: number;
+  sha256: string;
+  /** The grant; kept until the copy is made, never shown. */
+  url: string;
+  expiresAt: number;
+  tags: { title?: string; artist?: string; album?: string; track?: number };
+}
+
+export interface Handoff {
+  id: string;
+  version: 1;
+  provider: "bittorrented";
+  idempotencyKey: string;
+  owner: string;
+  name: string;
+  source: { torrentId: string; infohash: string; collectionId: string };
+  stationId: string;
+  files: HandoffFile[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export const MAX_FILES = 500;
+export const MAX_FILE_BYTES = 4 * 1024 ** 3;
+const MAX_ATTEMPTS = 3;
+const MAX_REDIRECTS = 3;
+
+export interface ImporterDeps {
+  index: LibraryIndex;
+  stations: StationStore;
+  /** The folder copies go into: a managed library source. */
+  root: string;
+  probe: (path: string) => Promise<Probed>;
+  /** "" when this address may be fetched, else why not (destinations.ts). */
+  guard: (url: string) => Promise<string>;
+  fetcher?: typeof fetch;
+  /** Plain http, for tests on loopback only. */
+  allowHttp?: boolean;
+  now?: () => number;
+  log?: (line: string) => void;
+}
+
+function safeName(name: string, at: number): string {
+  const base = name.split(/[\\/]/).pop() ?? "";
+  const cleaned = base.replace(/[\u0000-\u001f\u007f<>:"|?*]/g, "_").replace(/^\.+/, "").trim().slice(0, 180);
+  return `${String(at + 1).padStart(3, "0")} ${cleaned || "file"}`;
+}
+
+export function publicHandoff(handoff: Handoff): Record<string, unknown> {
+  const counts: Record<string, number> = {};
+  for (const file of handoff.files) counts[file.state] = (counts[file.state] ?? 0) + 1;
+  return {
+    id: handoff.id,
+    version: handoff.version,
+    provider: handoff.provider,
+    idempotencyKey: handoff.idempotencyKey,
+    name: handoff.name,
+    source: handoff.source,
+    stationId: handoff.stationId,
+    status: counts["pending"] || counts["downloading"] ? "importing" : (counts["ready"] ?? 0) === handoff.files.length ? "ready" : counts["ready"] ? "partial" : "failed",
+    counts,
+    files: handoff.files.map(({ url: _url, path: _path, ...file }) => file),
+    createdAt: handoff.createdAt,
+    updatedAt: handoff.updatedAt,
+  };
+}
+
+export class Importer {
+  private handoffs = new Map<string, Handoff>();
+  private running = new Set<string>();
+  private sourceId = "";
+
+  constructor(private readonly file: string, private readonly deps: ImporterDeps) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as { handoffs?: Handoff[] };
+      for (const one of parsed.handoffs ?? []) if (one?.id) this.handoffs.set(one.id, one);
+    } catch {
+      // Nothing yet.
+    }
+  }
+
+  private now(): number {
+    return this.deps.now?.() ?? Date.now();
+  }
+
+  private save(): void {
+    mkdirSync(dirname(this.file), { recursive: true });
+    const temporary = `${this.file}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ version: 1, handoffs: [...this.handoffs.values()] }), { mode: 0o600 });
+    renameSync(temporary, this.file);
+  }
+
+  private source(): string {
+    if (this.sourceId && this.deps.index.source(this.sourceId)) return this.sourceId;
+    mkdirSync(this.deps.root, { recursive: true });
+    this.sourceId = this.deps.index.addManagedSource(this.deps.root).id;
+    return this.sourceId;
+  }
+
+  list(owner: string | null): Handoff[] {
+    return [...this.handoffs.values()].filter((one) => owner === null || one.owner === owner).sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  get(id: string): Handoff | undefined {
+    return this.handoffs.get(id);
+  }
+
+  /** A handoff, or the one this key already made. `created` says which. */
+  create(input: Record<string, unknown>, owner: string): { handoff: Handoff; created: boolean } {
+    if (input["version"] !== 1) throw new LibraryError("unsupported_version", "this server understands handoff version 1");
+    const key = typeof input["idempotencyKey"] === "string" ? input["idempotencyKey"].trim().slice(0, 200) : "";
+    if (!key) throw new LibraryError("idempotency_key_required", "a handoff needs an idempotencyKey, so a retry is not a second one");
+    const again = [...this.handoffs.values()].find((one) => one.idempotencyKey === key && one.owner === owner);
+    if (again) return { handoff: again, created: false };
+    const files = input["files"];
+    if (!Array.isArray(files) || files.length === 0) throw new LibraryError("files_required", "choose at least one file");
+    if (files.length > MAX_FILES) throw new LibraryError("too_many_files", `at most ${MAX_FILES} files in one handoff`);
+    const id = randomBytes(8).toString("hex");
+    const folder = join(this.deps.root, id);
+    const now = this.now();
+    const seen = new Set<string>();
+    const accepted: HandoffFile[] = files.map((raw, at) => {
+      const one = (raw ?? {}) as Record<string, unknown>;
+      const fileId = typeof one["fileId"] === "string" ? one["fileId"].slice(0, 200) : "";
+      const name = typeof one["name"] === "string" ? one["name"] : "";
+      const size = Number(one["size"]);
+      const url = typeof one["url"] === "string" ? one["url"] : "";
+      const mediaType = typeof one["mediaType"] === "string" ? one["mediaType"].slice(0, 100) : "";
+      if (!fileId || seen.has(fileId)) throw new LibraryError("invalid_file", `file ${at + 1} needs a fileId of its own`);
+      seen.add(fileId);
+      if (!name) throw new LibraryError("invalid_file", `file ${at + 1} needs a name`);
+      if (!Number.isInteger(size) || size <= 0 || size > MAX_FILE_BYTES) throw new LibraryError("invalid_file", `file ${at + 1} needs a size in bytes, up to 4 GiB`);
+      if (!(mediaType.startsWith("audio/") || playable(name))) throw new LibraryError("not_audio", `${name} is not a file a station can play`);
+      let parsed: URL;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new LibraryError("invalid_file", `file ${at + 1} needs a url to fetch it from`);
+      }
+      if (parsed.protocol !== "https:" && !(this.deps.allowHttp && parsed.protocol === "http:")) {
+        throw new LibraryError("insecure_url", "files are fetched over https only");
+      }
+      const tags = (one["metadata"] ?? {}) as Record<string, unknown>;
+      return {
+        fileId, name, size, mediaType,
+        complete: one["complete"] === true,
+        state: "pending", error: "", attempts: 0,
+        path: join(folder, safeName(name, at) + (extname(name) ? "" : ".mp3")),
+        bytes: 0, sha256: "",
+        url,
+        expiresAt: Number.isFinite(Number(one["expiresAt"])) ? Number(one["expiresAt"]) : 0,
+        tags: {
+          ...(typeof tags["title"] === "string" ? { title: tags["title"].slice(0, 300) } : {}),
+          ...(typeof tags["artist"] === "string" ? { artist: tags["artist"].slice(0, 300) } : {}),
+          ...(typeof tags["album"] === "string" ? { album: tags["album"].slice(0, 300) } : {}),
+          ...(Number.isInteger(tags["track"]) ? { track: tags["track"] as number } : {}),
+        },
+      };
+    });
+    const sourceInput = (input["source"] ?? {}) as Record<string, unknown>;
+    const name = (typeof input["name"] === "string" && input["name"].trim() ? input["name"].trim() : "From BitTorrented").slice(0, 120);
+    this.source();
+    // The draft, private and stopped, with every file it will have: a file
+    // that is not copied yet is simply not there, and a station plays what is.
+    const station = this.deps.stations.create({ name }, accepted.map((one) => one.path), owner, now, `handoff:${key}`);
+    const handoff: Handoff = {
+      id, version: 1, provider: "bittorrented", idempotencyKey: key, owner, name,
+      source: {
+        torrentId: String(sourceInput["torrentId"] ?? "").slice(0, 200),
+        infohash: String(sourceInput["infohash"] ?? "").slice(0, 80),
+        collectionId: String(sourceInput["collectionId"] ?? "").slice(0, 200),
+      },
+      stationId: station.id,
+      files: accepted,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.handoffs.set(id, handoff);
+    this.save();
+    void this.run(id);
+    return { handoff, created: true };
+  }
+
+  /** New links for files whose links ran out, and another try for the failed ones. */
+  retry(id: string, input: Record<string, unknown>): Handoff {
+    const handoff = this.handoffs.get(id);
+    if (!handoff) throw new LibraryError("not_found", "no such handoff", 404);
+    const fresh = Array.isArray(input["files"]) ? (input["files"] as Array<Record<string, unknown>>) : [];
+    for (const file of handoff.files) {
+      const update = fresh.find((one) => one["fileId"] === file.fileId);
+      if (update && typeof update["url"] === "string") {
+        const parsed = new URL(update["url"]);
+        if (parsed.protocol !== "https:" && !(this.deps.allowHttp && parsed.protocol === "http:")) throw new LibraryError("insecure_url", "files are fetched over https only");
+        file.url = update["url"];
+        file.expiresAt = Number(update["expiresAt"] ?? 0) || 0;
+      }
+      if (file.state === "failed" || file.state === "expired") {
+        file.state = "pending";
+        file.error = "";
+        file.attempts = 0;
+      }
+    }
+    handoff.updatedAt = this.now();
+    this.save();
+    void this.run(id);
+    return handoff;
+  }
+
+  /** The copies this handoff made, removed; the station loses those files. */
+  remove(id: string): number {
+    const handoff = this.handoffs.get(id);
+    if (!handoff) throw new LibraryError("not_found", "no such handoff", 404);
+    const removed = handoff.files.filter((one) => one.state === "ready").length;
+    rmSync(join(this.deps.root, id), { recursive: true, force: true });
+    this.handoffs.delete(id);
+    this.save();
+    void this.deps.index.scan(this.source(), this.deps.probe).done;
+    return removed;
+  }
+
+  /** Every handoff that was part-way when the server stopped, carried on. */
+  resume(): void {
+    for (const handoff of this.handoffs.values()) {
+      let again = false;
+      for (const file of handoff.files) {
+        if (file.state === "downloading") file.state = "pending";
+        if (file.state === "pending") again = true;
+      }
+      if (again) void this.run(handoff.id);
+    }
+  }
+
+  private async run(id: string): Promise<void> {
+    if (this.running.has(id)) return;
+    this.running.add(id);
+    try {
+      const handoff = this.handoffs.get(id);
+      if (!handoff) return;
+      let next = 0;
+      const queue = handoff.files.filter((one) => one.state === "pending");
+      const worker = async (): Promise<void> => {
+        while (next < queue.length) {
+          const file = queue[next++]!;
+          await this.copy(handoff, file);
+          handoff.updatedAt = this.now();
+          this.save();
+        }
+      };
+      await Promise.all([worker(), worker()]);
+      // What was copied, read and indexed; then each file says what it is.
+      await this.deps.index.scan(this.source(), this.deps.probe).done;
+      for (const file of handoff.files) {
+        if (file.state !== "ready") continue;
+        const item = this.deps.index.itemAt(file.path);
+        if (!item || item.state === "failed") {
+          file.state = "failed";
+          file.error = item?.error || "it could not be read after copying";
+        } else if (item.state === "unsupported") {
+          file.state = "unsupported";
+          file.error = "there is nothing in it a station can play";
+        } else if (item.state === "ready") {
+          // What BitTorrented knew, where the file itself says nothing.
+          const patch: Record<string, unknown> = {};
+          if (!item.title && file.tags.title) patch["title"] = file.tags.title;
+          if (!item.artist && file.tags.artist) patch["artist"] = file.tags.artist;
+          if (!item.album && file.tags.album) patch["album"] = file.tags.album;
+          if (Object.keys(patch).length) this.deps.index.correct(item.id, patch);
+        }
+      }
+      handoff.updatedAt = this.now();
+      this.save();
+    } finally {
+      this.running.delete(id);
+    }
+  }
+
+  private async copy(handoff: Handoff, file: HandoffFile): Promise<void> {
+    if (file.expiresAt && file.expiresAt <= this.now()) {
+      file.state = "expired";
+      file.error = "the link to this file ran out before it was copied; ask BitTorrented for a new one";
+      return;
+    }
+    file.state = "downloading";
+    file.attempts += 1;
+    const send = this.deps.fetcher ?? fetch;
+    const part = `${file.path}.part`;
+    try {
+      let at = file.url;
+      let response: Response | null = null;
+      for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const refused = await this.deps.guard(at);
+        if (refused) throw new Error(refused);
+        response = await send(at, { redirect: "manual", headers: { "user-agent": "nixamp-handoff" } });
+        const location = response.headers.get("location");
+        if (response.status >= 300 && response.status < 400 && location) {
+          at = new URL(location, at).toString();
+          continue;
+        }
+        break;
+      }
+      if (!response) throw new Error("no answer");
+      if ([401, 403, 410].includes(response.status)) {
+        file.state = "expired";
+        file.error = `BitTorrented no longer lets this file be fetched (HTTP ${response.status}); ask for a new link`;
+        return;
+      }
+      if (!response.ok || !response.body) throw new Error(`HTTP ${response.status}`);
+      const declared = Number(response.headers.get("content-length") ?? "0");
+      if (declared && declared !== file.size) throw new Error(`the file is ${declared} bytes, not the ${file.size} it was said to be`);
+      mkdirSync(dirname(file.path), { recursive: true });
+      const hash = createHash("sha256");
+      let bytes = 0;
+      const counted = Readable.fromWeb(response.body as import("node:stream/web").ReadableStream).on("data", (chunk: Buffer) => {
+        bytes += chunk.length;
+        if (bytes > file.size) counted.destroy(new Error(`more than the ${file.size} bytes it was said to be`));
+        hash.update(chunk);
+      });
+      await pipeline(counted, createWriteStream(part, { mode: 0o640 }));
+      if (bytes !== file.size) throw new Error(`incomplete: ${bytes} of ${file.size} bytes`);
+      renameSync(part, file.path);
+      file.bytes = bytes;
+      file.sha256 = hash.digest("hex");
+      file.state = "ready";
+      file.error = "";
+      // The grant has done its job.
+      file.url = "";
+    } catch (error) {
+      rmSync(part, { force: true });
+      file.error = error instanceof Error ? error.message : String(error);
+      file.state = file.attempts < MAX_ATTEMPTS ? "pending" : "failed";
+      if (file.state === "pending") await this.copy(handoff, file);
+    }
+  }
+
+  /** The bytes a ready copy takes on disk, for the owner's view. */
+  static sizeOn(path: string): number {
+    try {
+      return statSync(path).size;
+    } catch {
+      return 0;
+    }
+  }
+}

package/src/library-index.ts

@@ -107,6 +107,8 @@ export interface LibrarySource {
   enabled: boolean;
   createdAt: number;
   lastScan: ScanReport | null;
+  /** A folder Nixamp fills itself (imports), allowed where a library may not be. */
+  managed?: boolean;
 }
 
 /** What one probe found. */
@@ -423,6 +425,25 @@ export class LibraryIndex {
     return source;
   }
 
+  /**
+   * A folder Nixamp fills itself -- copies handed over from BitTorrented --
+   * as a source. It lives beside the state, which is hidden and so refused
+   * as a library; it is allowed here because nothing in it was put there by
+   * anybody but Nixamp.
+   */
+  addManagedSource(root: string, host = hostname()): LibrarySource {
+    const full = resolve(root);
+    const existing = this.sources().find((one) => one.root === full);
+    if (existing) return existing;
+    const source: LibrarySource = {
+      id: idOf("source", host, full), kind: "folder", root: full, owner: "", host,
+      enabled: true, createdAt: this.now(), lastScan: null, managed: true,
+    };
+    this.sourceList.set(source.id, source);
+    this.touch();
+    return source;
+  }
+
   /** The folder this server was started on, as a source, made once. */
   ensureSource(root: string, owner: string): LibrarySource | null {
     try {

package/src/oauth-server.ts

@@ -53,6 +53,7 @@ export const SCOPES = {
   email: "the address on your account",
   parties: "host and join watch parties as you",
   streams: "see the servers you run on nixamp, and what is live on them",
+  stations: "manage the library and stations on servers you run, and send them music to play",
   offline_access: "stay connected without asking again",
 } as const;
 

package/src/owner.ts

@@ -69,8 +69,11 @@ export class Owner {
         this.cache.set(token, { id: "", at: now });
         return "";
       }
-      const body = (await answer.json()) as { account?: { id?: string } };
-      const id = typeof body.account?.id === "string" ? body.account.id : "";
+      const body = (await answer.json()) as { account?: { id?: string }; grant?: { scope?: unknown } };
+      // A token some app holds for the person counts here only if they gave
+      // that app the stations scope; otherwise it is not them at this door.
+      const scoped = body.grant === undefined || (Array.isArray(body.grant.scope) && body.grant.scope.includes("stations"));
+      const id = scoped && typeof body.account?.id === "string" ? body.account.id : "";
       this.cache.set(token, { id, at: now });
       return id;
     } catch {