nixamp 0.6.4 → 0.7.1

package/dist/server.js

@@ -12,6 +12,7 @@
 import { createReadStream, statSync } from "node:fs";
 import { createServer as createHttpServer } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
+import { randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
@@ -21,6 +22,8 @@ import { Ingest, normaliseFormat } from "./ingest.js";
 import { Channels, cleanId } from "./channels.js";
 import { RtmpListeners } from "./rtmp-in.js";
 import { Accounts, clearedCookie, sessionCookie, tokenFrom } from "./accounts.js";
+import { anonymousHandle, Handles } from "./handles.js";
+import { OpenDirs } from "./opendirs.js";
 import { Servers } from "./servers.js";
 import { DeviceGrants } from "./device.js";
 import { BAD_KEY_LIMIT, callerOf, Guard, SIGN_IN_LIMIT } from "./guard.js";
@@ -43,7 +46,7 @@ import { extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { detectTools, peaks, RATE, Stream, toMono, } from "./audio.js";
 import { Analyser, bandEdges, bands, decay } from "./fft.js";
-import { loadSource, loadTagged } from "./playlist.js";
+import { loadSource, loadTagged, readRemoteIndex } from "./playlist.js";
 import { emptySnapshot, parseCommand, } from "./protocol.js";
 const FFT_SIZE = 2048;
 export const SERVE_BAND_COUNT = 24;
@@ -555,6 +558,10 @@ export function isSignInPath(path) {
         // rather than by a share key it has nothing to do with.
         path === "/api/v1/servers" ||
         path.startsWith("/api/v1/servers/") ||
+        path === "/api/v1/me/handle" ||
+        // Public to read, so it must not be behind a share key either.
+        path === "/api/v1/opendirs" ||
+        path.startsWith("/api/v1/opendirs/") ||
         OAUTH_ROUTE.test(path));
 }
 function html(response, code, body) {
@@ -994,6 +1001,42 @@ export function createHandler(engine, options) {
                 json(response, 404, { error: "no such endpoint" });
                 return;
             }
+            // --- the name other people see ---------------------------------------
+            //
+            // Separate from the address on purpose. The address is a credential and
+            // a way to reach somebody; publishing it in a directory listing or an
+            // invite would be publishing what they log in with.
+            if (path === "/api/v1/me/handle" && options.handles) {
+                const handles = options.handles;
+                const who = await accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "not signed in" });
+                    return;
+                }
+                if (request.method === "GET") {
+                    json(response, 200, { handle: await handles.of(who.id) });
+                    return;
+                }
+                if (request.method === "PUT" || request.method === "POST") {
+                    let body;
+                    try {
+                        body = JSON.parse(await readBody(request));
+                    }
+                    catch {
+                        json(response, 400, { error: "bad JSON" });
+                        return;
+                    }
+                    const claimed = await handles.claim(who.id, body.handle);
+                    if (claimed.error) {
+                        json(response, 409, { error: claimed.error });
+                        return;
+                    }
+                    json(response, 200, { handle: claimed.handle });
+                    return;
+                }
+                json(response, 405, { error: "GET or PUT" });
+                return;
+            }
             // --- the servers this account runs ----------------------------------
             //
             // Kept against the account rather than the machine, so the list reads the
@@ -1140,6 +1183,17 @@ export function createHandler(engine, options) {
             const result = signingUp
                 ? await accounts.signUp(body.email, body.password)
                 : await accounts.signIn(body.email, body.password);
+            // A handle asked for at sign-up, or one nobody has to think about. Never
+            // derived from the address: turning anthony@… into "anthony" is the leak
+            // this whole idea exists to avoid, and it is one nobody would notice
+            // until it was already in a directory listing.
+            if (signingUp && result.ok && result.account && options.handles) {
+                const asked = body.handle;
+                const claimed = await options.handles.claim(result.account.id, asked);
+                if (claimed.error) {
+                    await options.handles.claim(result.account.id, anonymousHandle((size) => randomBytes(size)));
+                }
+            }
             // Getting it right costs nothing: the counters only exist to stop people
             // who keep getting it wrong.
             if (result.ok)
@@ -1166,6 +1220,74 @@ export function createHandler(engine, options) {
             response.end(JSON.stringify({ account: result.account, token }));
             return;
         }
+        // --- open directories somebody found -----------------------------------
+        //
+        // Its own list, not the stream directory: that one is what is playing now,
+        // with a heartbeat and a room code and somebody at the other end, and this
+        // one is a folder on the web that is always there and belongs to nobody
+        // here. Reading needs no account. Adding does, because a public list with
+        // nobody accountable for its rows is a list of whatever anyone felt like.
+        if ((path === "/api/v1/opendirs" || path.startsWith("/api/v1/opendirs/")) && options.openDirs) {
+            const dirs = options.openDirs;
+            if (path === "/api/v1/opendirs" && request.method === "GET") {
+                const limit = Number(url.searchParams.get("limit") ?? "50");
+                const before = Number(url.searchParams.get("before") ?? "0");
+                const page = await dirs.list(Number.isFinite(limit) ? limit : 50, Number.isFinite(before) ? before : 0);
+                const names = options.handles ? await options.handles.many(page.addedBy) : new Map();
+                json(response, 200, {
+                    opendirs: page.rows.map((row, at) => ({
+                        ...row,
+                        // A handle or nothing. The address that signed up is never here.
+                        by: names.get(page.addedBy[at] ?? "") ?? "",
+                    })),
+                    next: page.next,
+                });
+                return;
+            }
+            if (path === "/api/v1/opendirs" && request.method === "POST" && options.accounts) {
+                const who = await options.accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "sign in to publish one" });
+                    return;
+                }
+                let body;
+                try {
+                    body = JSON.parse(await readBody(request));
+                }
+                catch {
+                    json(response, 400, { error: "bad JSON" });
+                    return;
+                }
+                // Read before publishing. A row nobody can play is worse than no row,
+                // and the count is the one fact a reader wants before clicking.
+                const listed = typeof body.url === "string" ? await readRemoteIndex(body.url) : [];
+                if (listed.length === 0) {
+                    json(response, 422, { error: "nothing playable was linked from that page" });
+                    return;
+                }
+                const made = await dirs.add(who.id, body.url, body.name, listed.length);
+                if (made === null) {
+                    json(response, 422, { error: "that needs an http or https address" });
+                    return;
+                }
+                const handle = options.handles ? await options.handles.of(who.id) : "";
+                json(response, 201, { opendir: { ...made, by: handle } });
+                return;
+            }
+            const dirId = path.slice("/api/v1/opendirs/".length);
+            if (dirId && request.method === "DELETE" && options.accounts) {
+                const who = await options.accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "not signed in" });
+                    return;
+                }
+                const gone = await dirs.remove(who.id, dirId);
+                json(response, gone ? 200 : 404, gone ? { ok: true } : { error: "not yours, or not there" });
+                return;
+            }
+            json(response, 405, { error: "GET, POST or DELETE" });
+            return;
+        }
         // --- coming back from a provider ---------------------------------------
         //
         // /api/v1/<provider>/oauth/start sends a browser away, and .../callback is
@@ -2274,7 +2396,9 @@ export async function serve(argv, version = "0.1.0") {
                 // all: a browser already signed in can approve a terminal.
                 // The same pool the follows and reminders use: three small tables in
                 // one database do not want three sets of connections.
-                ...(pool ? { servers: new Servers(pool) } : {}),
+                ...(pool
+                    ? { servers: new Servers(pool), handles: new Handles(pool), openDirs: new OpenDirs(pool) }
+                    : {}),
                 signIn: new SignIn(providersFrom(process.env), new DeviceGrants(), process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY),
             }
             : {}),

package/dist/session.d.ts

@@ -107,3 +107,11 @@ export declare function whoami(fetcher?: typeof fetch): Promise<number>;
  * the browser and in the desktop app.
  */
 export declare function servers(argv: string[], fetcher?: typeof fetch): Promise<number>;
+/**
+ * `nixamp opendir list|add|remove`, the public list of folders people found.
+ *
+ * Reading needs no account, which is why `list` works signed out. Adding needs
+ * one, because a public list with nobody accountable for its rows is a list of
+ * whatever anybody felt like putting there.
+ */
+export declare function opendirs(argv: string[], fetcher?: typeof fetch): Promise<number>;

package/dist/session.js

@@ -578,3 +578,89 @@ export async function servers(argv, fetcher = fetch) {
         return 69;
     }
 }
+/**
+ * `nixamp opendir list|add|remove`, the public list of folders people found.
+ *
+ * Reading needs no account, which is why `list` works signed out. Adding needs
+ * one, because a public list with nobody accountable for its rows is a list of
+ * whatever anybody felt like putting there.
+ */
+export async function opendirs(argv, fetcher = fetch) {
+    const [command = "list", ...rest] = argv;
+    const session = readSession();
+    const site = session?.site ?? DEFAULT_DIRECTORY;
+    const where = `${site}/api/v1/opendirs`;
+    const headers = {
+        "content-type": "application/json",
+        ...(session ? { authorization: `Bearer ${session.token}` } : {}),
+    };
+    const at = (flag) => {
+        const index = rest.indexOf(flag);
+        return index === -1 ? undefined : rest[index + 1];
+    };
+    try {
+        if (command === "list" || command === "ls") {
+            const answer = await fetcher(where, { headers });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok) {
+                console.error(`nixamp: ${body.error ?? `could not read the list (${answer.status})`}`);
+                return 1;
+            }
+            const rows = body.opendirs ?? [];
+            if (rows.length === 0) {
+                console.log("Nothing published yet. `nixamp opendir add <url>` puts one there.");
+                return 0;
+            }
+            const width = Math.max(...rows.map((row) => row.name.length));
+            for (const row of rows) {
+                const who = row.by ? ` by ${row.by}` : "";
+                console.log(`${row.id}  ${row.name.padEnd(width)}  ${row.tracks} tracks${who}`);
+                console.log(`  ${row.url}`);
+            }
+            return 0;
+        }
+        if (session === null) {
+            console.error("nixamp: sign in to publish or remove one. Try `nixamp login`.");
+            return 1;
+        }
+        if (command === "add" || command === "publish") {
+            const target = rest.find((a) => /^https?:\/\//.test(a)) ?? "";
+            if (!target) {
+                console.error("nixamp: which folder? Give the URL of a directory listing.");
+                return 64;
+            }
+            const answer = await fetcher(where, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ url: target, name: at("--name") ?? "" }),
+            });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok || !body.opendir) {
+                console.error(`nixamp: ${body.error ?? `could not publish it (${answer.status})`}`);
+                return 1;
+            }
+            console.log(`${body.opendir.id}  ${body.opendir.name}  ${body.opendir.tracks} tracks`);
+            return 0;
+        }
+        if (command === "remove" || command === "rm") {
+            const id = rest.find((a) => !a.startsWith("-")) ?? "";
+            if (!id) {
+                console.error("nixamp: which one? `nixamp opendir list` shows their ids.");
+                return 64;
+            }
+            const answer = await fetcher(`${where}/${encodeURIComponent(id)}`, { method: "DELETE", headers });
+            if (!answer.ok) {
+                console.error(`nixamp: ${answer.status === 404 ? "not yours, or not there" : "could not remove it"}`);
+                return 1;
+            }
+            console.log(`Removed ${id}.`);
+            return 0;
+        }
+        console.error(`nixamp: no such opendir command: ${command}`);
+        return 64;
+    }
+    catch (error) {
+        console.error(`nixamp: could not reach ${site}: ${error.message}`);
+        return 69;
+    }
+}

package/package.json

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

package/src/handles.ts

@@ -0,0 +1,141 @@
+/**
+ * The name other people see.
+ *
+ * An account is keyed on an email address, because that is what the auth module
+ * authenticates. An address is a credential and a way to reach somebody, and it
+ * is not a name: putting it in a directory listing, an invite or a subdomain
+ * publishes something the account holder gave us to log in with.
+ *
+ * So there are two names. The address stays private and does the linking, and a
+ * handle is the one that appears in front of strangers. They are never the same
+ * field and never travel in the same response.
+ */
+import type { Queryable } from "./follows.ts";
+
+const TABLE = "nixamp_handles";
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    user_id    TEXT PRIMARY KEY,
+    handle     TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS ${TABLE}_lower ON ${TABLE} (lower(handle));
+`;
+
+/**
+ * What a handle may be.
+ *
+ * It ends up in a URL, a subdomain and a text message, so it is the intersection
+ * of what all three tolerate: lowercase letters, digits and hyphens, not
+ * starting or ending with one. Two to thirty characters, because a subdomain
+ * label cannot exceed sixty-three and nobody types thirty.
+ */
+export function cleanHandle(value: unknown): string {
+  if (typeof value !== "string") return "";
+  const wanted = value.trim().toLowerCase();
+  // Two characters minimum, thirty maximum: the trailing character is required,
+  // which is also what stops a handle ending in a hyphen.
+  if (!/^[a-z0-9][a-z0-9-]{0,28}[a-z0-9]$/.test(wanted)) return "";
+  // Doubled hyphens are how punycode marks an encoded label, so a handle with
+  // one in it can collide with an internationalised domain.
+  return wanted.includes("--") ? "" : wanted;
+}
+
+/**
+ * Names nobody may take, because a subdomain carrying one would impersonate the
+ * service or reach a machine we run.
+ */
+const RESERVED = new Set([
+  "www", "api", "admin", "root", "nixamp", "mail", "smtp", "imap", "ns1", "ns2",
+  "static", "cdn", "assets", "app", "dev", "staging", "test", "support", "help",
+  "status", "blog", "directory", "login", "signup", "account", "settings", "me",
+]);
+
+export function isReserved(handle: string): boolean {
+  return RESERVED.has(handle);
+}
+
+/**
+ * A handle for somebody who has not chosen one.
+ *
+ * Deliberately not derived from the address. "anthony@profullstack.com" turning
+ * into "anthony" is exactly the leak this whole file exists to avoid, and it
+ * would be a leak nobody noticed until it was already in a directory listing.
+ */
+export function anonymousHandle(random: (size: number) => Uint8Array): string {
+  const bytes = random(4);
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return `nixamp-${out}`;
+}
+
+export class Handles {
+  private ready: Promise<void> | null = null;
+
+  constructor(private readonly db: Queryable) {}
+
+  private async ensure(): Promise<void> {
+    this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+    await this.ready;
+  }
+
+  async of(userId: string): Promise<string> {
+    await this.ensure();
+    const { rows } = await this.db.query(`SELECT handle FROM ${TABLE} WHERE user_id = $1`, [userId]);
+    return rows[0] ? String(rows[0]["handle"] ?? "") : "";
+  }
+
+  /**
+   * Handles for a page of rows, in one query.
+   *
+   * A public listing names people, and naming them one query at a time is how a
+   * list of fifty becomes fifty round trips. Anyone without a handle is absent
+   * from the map rather than present as an empty string, so a caller decides
+   * what to show for somebody who never picked one.
+   */
+  async many(userIds: string[]): Promise<Map<string, string>> {
+    const wanted = [...new Set(userIds.filter(Boolean))];
+    if (wanted.length === 0) return new Map();
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `SELECT user_id, handle FROM ${TABLE} WHERE user_id = ANY($1)`,
+      [wanted],
+    );
+    return new Map(rows.map((row) => [String(row["user_id"] ?? ""), String(row["handle"] ?? "")]));
+  }
+
+  /** Who holds this handle, so a listing can name somebody without their address. */
+  async holder(handle: string): Promise<string> {
+    const wanted = cleanHandle(handle);
+    if (!wanted) return "";
+    await this.ensure();
+    const { rows } = await this.db.query(`SELECT user_id FROM ${TABLE} WHERE lower(handle) = $1`, [wanted]);
+    return rows[0] ? String(rows[0]["user_id"] ?? "") : "";
+  }
+
+  /**
+   * Claim one. Answers the reason it could not be taken rather than a boolean,
+   * because "that is already somebody's" and "that is not a name" are different
+   * things to tell a person.
+   */
+  async claim(userId: string, wanted: unknown): Promise<{ handle: string; error: string }> {
+    const handle = cleanHandle(wanted);
+    if (!handle) {
+      return { handle: "", error: "letters, digits and hyphens, 2 to 30 characters" };
+    }
+    if (isReserved(handle)) return { handle: "", error: "that one is reserved" };
+
+    await this.ensure();
+    const taken = await this.holder(handle);
+    if (taken && taken !== userId) return { handle: "", error: "somebody already has that one" };
+
+    await this.db.query(
+      `INSERT INTO ${TABLE} (user_id, handle) VALUES ($1, $2)
+       ON CONFLICT (user_id) DO UPDATE SET handle = EXCLUDED.handle, updated_at = NOW()`,
+      [userId, handle],
+    );
+    return { handle, error: "" };
+  }
+}

package/src/main.ts

@@ -76,6 +76,7 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp logout / whoami        forget it, or check it
   nixamp token create|list|revoke  tokens for a machine that cannot sign in
   nixamp server list|add|remove  the machines you run, kept against your account
+  nixamp opendir list|add|remove  folders found on the web, published for everyone
   nixamp update [version]        re-run the installer, keeping your choices
   nixamp uninstall [--yes]       remove everything the installer created
 
@@ -326,6 +327,11 @@ export async function main(): Promise<void> {
     process.exitCode = await login(first === "signup" ? [...rest, "--signup"] : rest);
     return;
   }
+  if (first === "opendir" || first === "opendirs") {
+    const { opendirs } = await import("./session.ts");
+    process.exitCode = await opendirs(rest);
+    return;
+  }
   if (first === "server" || first === "servers") {
     const { servers } = await import("./session.ts");
     process.exitCode = await servers(rest);

package/src/opendirs.ts

@@ -0,0 +1,158 @@
+/**
+ * Open directories somebody found, kept as a list anyone can read.
+ *
+ * Deliberately not the stream directory. That one lists what is playing right
+ * now: a heartbeat, a TTL, a room code, somebody at the other end. An open
+ * directory is the opposite in every one of those respects. It is always there,
+ * nobody is broadcasting it, and it is not the finder's to broadcast. Mixing
+ * the two would put "chovy is playing this, dial in" next to "here is a link
+ * to a stranger's file server" under one heading.
+ *
+ * Public to read and signed in to add, because a public list with nobody
+ * accountable for its rows is a public list of whatever anybody felt like
+ * putting there. What is shown against a row is the finder's handle, never the
+ * address they signed up with.
+ */
+import { randomBytes } from "node:crypto";
+import type { Queryable } from "./follows.ts";
+import { cleanUrl } from "./servers.ts";
+
+const TABLE = "nixamp_opendirs";
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    id          TEXT PRIMARY KEY,
+    url         TEXT NOT NULL,
+    name        TEXT NOT NULL DEFAULT '',
+    added_by    TEXT NOT NULL,
+    tracks      INTEGER NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS ${TABLE}_url ON ${TABLE} (url);
+  CREATE INDEX IF NOT EXISTS ${TABLE}_added ON ${TABLE} (created_at DESC);
+`;
+
+export interface OpenDir {
+  id: string;
+  url: string;
+  name: string;
+  /** How many playable files were on the page when it was added. */
+  tracks: number;
+  /** The finder's public handle. Never their address. */
+  by: string;
+  createdAt: number;
+}
+
+/**
+ * The name to show for a folder nobody named.
+ *
+ * The last path segment, which for a folder of music is the album, written the
+ * way a person wrote it rather than the way a URL spells it.
+ */
+export function nameOfDir(url: string): string {
+  try {
+    const parts = new URL(url).pathname.split("/").filter(Boolean);
+    const last = parts[parts.length - 1];
+    return last ? decodeURIComponent(last).slice(0, 120) : new URL(url).host;
+  } catch {
+    return "an open directory";
+  }
+}
+
+function asTime(value: unknown): number {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "string") {
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? 0 : at;
+  }
+  return typeof value === "number" ? value : 0;
+}
+
+export class OpenDirs {
+  private ready: Promise<void> | null = null;
+
+  constructor(private readonly db: Queryable) {}
+
+  private async ensure(): Promise<void> {
+    this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+    await this.ready;
+  }
+
+  /**
+   * The list, newest first, in pages.
+   *
+   * Keyset on the row's own creation time rather than an offset, because a list
+   * anybody may add to shifts under a reader who is paging through it, and an
+   * offset in a shifting list repeats and skips rows.
+   */
+  async list(limit = 50, before = 0): Promise<{ rows: Omit<OpenDir, "by">[]; addedBy: string[]; next: number }> {
+    await this.ensure();
+    const size = Math.min(200, Math.max(1, limit));
+    const { rows } = await this.db.query(
+      `SELECT id, url, name, added_by, tracks, created_at FROM ${TABLE}
+        ${before > 0 ? "WHERE created_at < $2" : ""}
+        ORDER BY created_at DESC LIMIT $1`,
+      before > 0 ? [size + 1, new Date(before).toISOString()] : [size + 1],
+    );
+
+    // One more than asked for, so "is there another page" is a fact rather
+    // than a guess from a full one.
+    const page = rows.slice(0, size);
+    return {
+      rows: page.map((row) => ({
+        id: String(row["id"] ?? ""),
+        url: String(row["url"] ?? ""),
+        name: String(row["name"] ?? ""),
+        tracks: Number(row["tracks"] ?? 0),
+        createdAt: asTime(row["created_at"]),
+      })),
+      addedBy: page.map((row) => String(row["added_by"] ?? "")),
+      next: rows.length > size ? asTime(page[page.length - 1]?.["created_at"]) : 0,
+    };
+  }
+
+  /**
+   * Publish one. `tracks` is what the finder's server actually saw on the page,
+   * so a row nobody can play never reaches the list.
+   */
+  async add(userId: string, url: unknown, name: unknown, tracks: number): Promise<Omit<OpenDir, "by"> | null> {
+    const clean = typeof url === "string" ? url.trim() : "";
+    // Not cleanUrl's origin-only treatment: a folder is a path, and the path is
+    // the whole point of the row.
+    if (!/^https?:\/\//i.test(clean) || cleanUrl(clean) === "") return null;
+    if (tracks <= 0) return null;
+
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `INSERT INTO ${TABLE} (id, url, name, added_by, tracks) VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (url) DO UPDATE SET name = EXCLUDED.name, tracks = EXCLUDED.tracks
+       RETURNING id, url, name, tracks, created_at`,
+      [
+        randomBytes(8).toString("hex"),
+        clean,
+        (typeof name === "string" && name.trim() ? name.trim() : nameOfDir(clean)).slice(0, 120),
+        userId,
+        Math.min(100_000, tracks),
+      ],
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      id: String(row["id"] ?? ""),
+      url: String(row["url"] ?? ""),
+      name: String(row["name"] ?? ""),
+      tracks: Number(row["tracks"] ?? 0),
+      createdAt: asTime(row["created_at"]),
+    };
+  }
+
+  /** Only the finder takes their own row down. */
+  async remove(userId: string, id: string): Promise<boolean> {
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `DELETE FROM ${TABLE} WHERE id = $1 AND added_by = $2 RETURNING id`,
+      [id, userId],
+    );
+    return rows.length > 0;
+  }
+}