nixamp 0.7.7 → 0.7.9

package/dist/owner.js

@@ -85,7 +85,17 @@ export const ADMIN_PATHS = [
     "/api/ingest",
     "/api/admin",
 ];
+/**
+ * Going live and coming back off, which is administering a server.
+ *
+ * Listed separately from ADMIN_PATHS on purpose: those match by prefix, and
+ * `/api/live` itself is the public listen address -- the one the phone line is
+ * handed. Gating it by prefix would shut the front door to lock the office.
+ */
+const LIVE_CONTROL = ["/api/live/state", "/api/live/start", "/api/live/stop"];
 export function needsAdmin(path, method = "GET") {
+    if (LIVE_CONTROL.includes(path))
+        return true;
     if (ADMIN_PATHS.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)))
         return true;
     // Publishing to a channel, or ending one, is administering the server.

package/dist/server.d.ts

@@ -29,6 +29,8 @@ export interface ServeOptions {
      * port, which is what the public deployment wants and no private one does.
      */
     key: boolean;
+    /** Mint a new share key rather than reusing the one this port had. */
+    newKey: boolean;
     /**
      * Ask the local firewall to let the port through, and put it back on the way
      * out. Off by default because it changes the machine, not just this process.
@@ -357,6 +359,31 @@ export interface HandlerOptions {
         destinations: Destination[];
         settings: EncoderSettings;
     };
+    /**
+     * Going live: whether this server is listed, and how to change that.
+     *
+     * Listing used to be a question asked once at startup and never again, so a
+     * server started with --no-publish had no listing, no phone code, and no
+     * link to hand anybody -- and no way to change its mind short of stopping
+     * and starting it. It is an action now, because that is what it is.
+     */
+    live?: {
+        status: () => {
+            live: boolean;
+            code: string;
+            name: string;
+            url: string;
+            possible: boolean;
+        };
+        start: () => Promise<{
+            live: boolean;
+            code: string;
+            name: string;
+            url: string;
+            error?: string;
+        }>;
+        stop: () => Promise<void>;
+    };
     /**
      * Where OBS should point, one entry per stream this server will accept.
      *

package/dist/server.js

@@ -29,6 +29,7 @@ import { DeviceGrants } from "./device.js";
 import { BAD_KEY_LIMIT, callerOf, Guard, SIGN_IN_LIMIT } from "./guard.js";
 import { deviceDonePage, devicePage, exchangeCode, providersFrom, signInFailedPage, SignIn, } from "./oauth.js";
 import { needsAdmin, Owner } from "./owner.js";
+import { stateDir } from "./daemon.js";
 import { readSession } from "./session.js";
 import { Directory, ENDED_TTL_MS, parseAnnouncement } from "./directory.js";
 import { PartyLine, telnyxSms } from "./partyline.js";
@@ -41,7 +42,7 @@ import { confirm, DEFAULT_DIRECTORY, Publisher } from "./publish.js";
 import { applyRemoteConfig, createPaywall, FREE_LISTENERS, paywallFromEnv, } from "./paywall.js";
 import { isRemote, playsInBrowser, sourceLabel } from "./sources.js";
 import { codecsOf, videoArgs } from "./audio.js";
-import { allowedForListening, elevate, firewallInUse, keyCookie, keyFrom, lookupPublicIp, newKey, portCommands, reachableAddresses, scopeOf, shareLink, audioLink, } from "./share.js";
+import { allowedForListening, elevate, firewallInUse, certifiable, keyCookie, rememberedKeys, keyFrom, lookupPublicIp, portCommands, reachableAddresses, scopeOf, shareLink, audioLink, } from "./share.js";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { detectTools, peaks, RATE, Stream, toMono, } from "./audio.js";
@@ -68,6 +69,7 @@ export function parseServeArgs(argv) {
         web: null,
         media: true,
         key: true,
+        newKey: false,
         openPort: false,
         announce: false,
         directory: false,
@@ -157,6 +159,9 @@ export function parseServeArgs(argv) {
         else if (arg === "--owner") {
             options.owner = value();
         }
+        else if (arg === "--new-key") {
+            options.newKey = true;
+        }
         else if (arg === "--ingest") {
             options.ingest = true;
         }
@@ -1814,6 +1819,35 @@ export function createHandler(engine, options) {
         }
         // Everything the admin view draws, in one request: who is connected, and
         // what this server is.
+        // Going live, and coming back off. Admin-gated by ADMIN_PATHS, because
+        // listing somebody's machine in a public directory is not a thing a
+        // listener gets to do.
+        if (path === "/api/live/state") {
+            if (!options.live) {
+                json(response, 200, { live: false, possible: false, code: "", name: "", url: "" });
+                return;
+            }
+            json(response, 200, options.live.status());
+            return;
+        }
+        if (path === "/api/live/start" || path === "/api/live/stop") {
+            if (request.method !== "POST") {
+                json(response, 405, { error: "POST only" });
+                return;
+            }
+            if (!options.live) {
+                json(response, 409, { error: "this nixamp cannot be listed; it has no address the world can reach" });
+                return;
+            }
+            if (path === "/api/live/stop") {
+                await options.live.stop();
+                json(response, 200, options.live.status());
+                return;
+            }
+            const started = await options.live.start();
+            json(response, started.error ? 502 : 200, started);
+            return;
+        }
         if (path === "/api/connections") {
             json(response, 200, {
                 connections: tracker.list(),
@@ -2373,10 +2407,15 @@ export async function serve(argv, version = "0.1.0") {
     // the slowest part of starting and nothing about it needs to happen first.
     const engine = new PlayerEngine([], root, tools);
     const web = options.web !== null ? resolve(options.web) : defaultWebDir();
-    const key = options.key ? newKey() : null;
-    // Minted whether or not it is published, so `nixamp admin` and the operator
+    // The same keys this port used last time, so a link somebody was given
+    // still works after a restart -- and a server is restarted to pick up a new
+    // version, which is to say often. `--new-key` mints a fresh pair and forgets
+    // the old one, which is the way to revoke a link that got out.
+    const remembered = options.key ? rememberedKeys(stateDir(), options.port, options.newKey) : null;
+    const key = remembered?.key ?? null;
+    // Kept whether or not it is published, so `nixamp admin` and the operator
     // both have a link they can hand out without handing over the controls.
-    const listenKey = key === null ? null : newKey();
+    const listenKey = remembered?.listenKey ?? null;
     // Configuration can arrive from the directory later, so it is a box the
     // paywall reads rather than a value it was handed once.
     let paywallConfig = { ...paywallFromEnv(), enabled: options.x402 || paywallFromEnv().enabled };
@@ -2574,12 +2613,55 @@ export async function serve(argv, version = "0.1.0") {
     // function so the handler sees the list rather than the empty array it was
     // built with.
     let publishUrls = [];
+    // Declared up here, not beside the publishing below: the port opens before
+    // that code runs, so an admin asking to go live in the first moments would
+    // otherwise reach a binding that has not been initialised.
+    let publisher = null;
+    let listing = null;
+    let publishable_;
     const server = createServer(engine, {
         web,
         media: options.media,
         owner,
         channels,
         publishUrls: () => publishUrls,
+        live: {
+            status: () => ({
+                live: publisher !== null,
+                code: listing?.code ?? "",
+                name: listing?.name ?? (options.name || hostname()),
+                url: listing?.url ?? (publishable_ ? shareLink(publishable_.url, listenKey) : ""),
+                // Whether going live is even possible here. A laptop behind a router
+                // with no address the world can reach cannot be listed, and a button
+                // that could only fail is worse than one that is not offered.
+                possible: publishable_ !== undefined,
+            }),
+            start: async () => {
+                if (publisher === null)
+                    publisher = makePublisher();
+                if (publisher === null) {
+                    return { live: false, code: "", name: "", url: "", error: "this machine has no address the world can reach" };
+                }
+                const first = await publisher.start();
+                if (first === null) {
+                    // Nothing was listed, so nothing should claim to be: a publisher
+                    // left running here would heartbeat at a directory that refused it.
+                    await publisher.stop();
+                    publisher = null;
+                    return {
+                        live: false, code: "", name: "", url: "",
+                        error: `${DEFAULT_DIRECTORY} would not list this stream. Run \`nixamp login\` on that machine.`,
+                    };
+                }
+                listing = first;
+                return { live: true, code: first.code, name: first.name, url: first.url };
+            },
+            stop: async () => {
+                await publisher?.stop();
+                publisher = null;
+                listing = null;
+            },
+        },
         ...(ingest ? { ingest } : {}),
         broadcaster,
         broadcast: () => ({ destinations, settings: DEFAULT_ENCODER }),
@@ -2811,51 +2893,67 @@ export async function serve(argv, version = "0.1.0") {
     }
     // The listing carries the listen link, and only ever a public address: an
     // entry pointing at 192.168.1.5 is one nobody outside that house can open.
-    const publishable_ = addresses.find((a) => a.label === "on the internet")
+    // Never a bare IP over https: a certificate is issued for a name, so a
+    // listing pointing at one is a listing nobody can open.
+    publishable_ = addresses.find((a) => a.label === "on the internet" && certifiable(a.url))
+        ?? addresses.find((a) => a.label === "on tailscale" && certifiable(a.url))
+        ?? addresses.find((a) => a.label === "on the internet")
         ?? addresses.find((a) => a.label === "on tailscale");
-    let publisher = null;
-    if (options.publish !== "no" && publishable_) {
+    /**
+     * Make a publisher for this server. Called at startup when the operator says
+     * yes, and again whenever somebody goes live from the admin panel.
+     *
+     * A declaration rather than an assignment, so it exists from the moment the
+     * function is entered -- the port is open well before this line is reached.
+     */
+    function makePublisher() {
+        if (!publishable_)
+            return null;
         const listen = shareLink(publishable_.url, listenKey);
         // Announced next to the listen link, not instead of it: one is for a person
         // with a browser, the other for the phone line and anything else that is
         // handed one address and expected to play it.
         const audio = audioLink(publishable_.url, listenKey);
+        return new Publisher({
+            directory: DEFAULT_DIRECTORY,
+            name: options.name || hostname(),
+            url: listen,
+            audio,
+            // Asked of the engine rather than a variable, because the library is
+            // now read after the port opens and may still be arriving.
+            tracks: engine.snapshot(false).trackCount,
+            // From `nixamp login`. The directory will not list a stream it cannot
+            // attribute to somebody, because a listing is now a phone code that
+            // costs money to answer.
+            ...(session?.token ? { token: session.token } : {}),
+            onRefused: () => {
+                console.log("");
+                console.log("  nixamp.com would not list this stream: it needs an account.");
+                console.log("  Run `nixamp login` (or `nixamp signup`) and start again.");
+            },
+            nowPlaying: () => {
+                const snapshot = engine.snapshot();
+                return snapshot.tracks?.[snapshot.index]?.title ?? "";
+            },
+            onConfig: (remote) => {
+                const next = applyRemoteConfig(paywallConfig, remote?.x402);
+                if (JSON.stringify(next) === JSON.stringify(paywallConfig))
+                    return;
+                paywallConfig = next;
+                console.log(next.enabled
+                    ? `  nixamp.com turned paid listening on: $${(next.priceCents / 100).toFixed(2)} for ${next.passMinutes} minutes, over ${FREE_LISTENERS} listeners.`
+                    : "  nixamp.com turned paid listening off.");
+            },
+        });
+    }
+    if (options.publish !== "no" && publishable_) {
+        const listen = shareLink(publishable_.url, listenKey);
         const wanted = options.publish === "yes"
             ? true
             : await confirm(`\n  List this stream at ${DEFAULT_DIRECTORY}/directory so anyone can find it?\n  It publishes ${listen} — listen only, not the controls.`);
         if (wanted) {
-            publisher = new Publisher({
-                directory: DEFAULT_DIRECTORY,
-                name: options.name || hostname(),
-                url: listen,
-                audio,
-                // Asked of the engine rather than a variable, because the library is
-                // now read after the port opens and may still be arriving.
-                tracks: engine.snapshot(false).trackCount,
-                // From `nixamp login`. The directory will not list a stream it cannot
-                // attribute to somebody, because a listing is now a phone code that
-                // costs money to answer.
-                ...(session?.token ? { token: session.token } : {}),
-                onRefused: () => {
-                    console.log("");
-                    console.log("  nixamp.com would not list this stream: it needs an account.");
-                    console.log("  Run `nixamp login` (or `nixamp signup`) and start again.");
-                },
-                nowPlaying: () => {
-                    const snapshot = engine.snapshot();
-                    return snapshot.tracks?.[snapshot.index]?.title ?? "";
-                },
-                onConfig: (remote) => {
-                    const next = applyRemoteConfig(paywallConfig, remote?.x402);
-                    if (JSON.stringify(next) === JSON.stringify(paywallConfig))
-                        return;
-                    paywallConfig = next;
-                    console.log(next.enabled
-                        ? `  nixamp.com turned paid listening on: $${(next.priceCents / 100).toFixed(2)} for ${next.passMinutes} minutes, over ${FREE_LISTENERS} listeners.`
-                        : "  nixamp.com turned paid listening off.");
-                },
-            });
-            const listing = await publisher.start();
+            publisher = makePublisher();
+            listing = (await publisher?.start()) ?? null;
             console.log("");
             console.log(listing
                 ? `  Listed at ${DEFAULT_DIRECTORY}/directory as "${listing.name}". It leaves the list when this stops.`

package/dist/share.d.ts

@@ -17,6 +17,31 @@ export declare const KEY_HEADER = "x-nixamp-key";
  * enough to read down a phone screen when someone types it by hand.
  */
 export declare function newKey(): string;
+/** The pair of keys a server hands out: one that drives, one that only hears. */
+export interface KeyPair {
+    key: string;
+    listenKey: string;
+}
+/**
+ * The keys this port used last time, or a new pair remembered for next time.
+ *
+ * Keys used to be minted on every start, so every link anybody had been given
+ * died the moment the server was restarted -- and a server gets restarted to
+ * pick up a new version, which is to say often. A link you cannot rely on is
+ * not a link you can share, which was most of why sharing did not feel like it
+ * worked.
+ *
+ * Kept per port, because two servers on one machine are two different
+ * audiences, and a single remembered key would hand each of them the other's.
+ *
+ * The trade is that a key which never changes is a key that stays valid if it
+ * leaks, so `fresh` mints a new pair and forgets the old one -- which is what
+ * `--new-key` is for.
+ */
+export declare function rememberedKeys(dir: string, port: number, fresh?: boolean, io?: {
+    read: (path: string) => string | null;
+    write: (path: string, body: string) => void;
+}): KeyPair;
 /** Compare without leaking where two keys first differ. */
 export declare function keysMatch(a: string, b: string): boolean;
 /** Every place a key is accepted from, in the order they are looked for. */

package/dist/share.js

@@ -11,6 +11,8 @@
  * every EventSource and every `<audio src>` on its own.
  */
 import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { networkInterfaces } from "node:os";
 /** The cookie, and the query parameter that sets it. */
 export const KEY_COOKIE = "nixamp_key";
@@ -23,6 +25,66 @@ export const KEY_HEADER = "x-nixamp-key";
 export function newKey() {
     return randomBytes(16).toString("base64url");
 }
+/**
+ * The keys this port used last time, or a new pair remembered for next time.
+ *
+ * Keys used to be minted on every start, so every link anybody had been given
+ * died the moment the server was restarted -- and a server gets restarted to
+ * pick up a new version, which is to say often. A link you cannot rely on is
+ * not a link you can share, which was most of why sharing did not feel like it
+ * worked.
+ *
+ * Kept per port, because two servers on one machine are two different
+ * audiences, and a single remembered key would hand each of them the other's.
+ *
+ * The trade is that a key which never changes is a key that stays valid if it
+ * leaks, so `fresh` mints a new pair and forgets the old one -- which is what
+ * `--new-key` is for.
+ */
+export function rememberedKeys(dir, port, fresh = false, io = defaultKeyStore) {
+    const path = `${dir}/keys.json`;
+    let all = {};
+    const existing = io.read(path);
+    if (existing !== null) {
+        try {
+            const parsed = JSON.parse(existing);
+            if (parsed && typeof parsed === "object")
+                all = parsed;
+        }
+        catch {
+            // A file we cannot read is a file we replace. Losing a key costs a link;
+            // refusing to start costs the whole server.
+        }
+    }
+    const held = all[String(port)];
+    if (!fresh && held && typeof held.key === "string" && typeof held.listenKey === "string")
+        return held;
+    const minted = { key: newKey(), listenKey: newKey() };
+    all[String(port)] = minted;
+    try {
+        io.write(path, JSON.stringify(all, null, 2));
+    }
+    catch {
+        // Unwritable state is a key that will not survive a restart, which is how
+        // it behaved before this existed. Not a reason to refuse to serve.
+    }
+    return minted;
+}
+const defaultKeyStore = {
+    read: (path) => {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return null;
+        }
+    },
+    write: (path, body) => {
+        mkdirSync(dirname(path), { recursive: true });
+        // Readable only by its owner: it is the password to this server.
+        writeFileSync(path, body, { mode: 0o600 });
+    },
+};
 /** Compare without leaking where two keys first differ. */
 export function keysMatch(a, b) {
     const left = Buffer.from(a);
@@ -217,6 +279,11 @@ export function allowedForListening(path) {
     // album out of somebody else's playlist.
     if (path === "/api/source" || path.startsWith("/api/source/"))
         return false;
+    // Listing this machine in a public directory is not listening to it. The
+    // listen address itself, /api/live, stays open: that is the thing a listen
+    // key is for.
+    if (path === "/api/live/state" || path === "/api/live/start" || path === "/api/live/stop")
+        return false;
     return true;
 }
 /**

package/package.json

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

package/src/owner.ts

@@ -104,7 +104,17 @@ export const ADMIN_PATHS = [
   "/api/admin",
 ];
 
+/**
+ * Going live and coming back off, which is administering a server.
+ *
+ * Listed separately from ADMIN_PATHS on purpose: those match by prefix, and
+ * `/api/live` itself is the public listen address -- the one the phone line is
+ * handed. Gating it by prefix would shut the front door to lock the office.
+ */
+const LIVE_CONTROL = ["/api/live/state", "/api/live/start", "/api/live/stop"];
+
 export function needsAdmin(path: string, method = "GET"): boolean {
+  if (LIVE_CONTROL.includes(path)) return true;
   if (ADMIN_PATHS.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))) return true;
   // Publishing to a channel, or ending one, is administering the server.
   // Listening to a channel is not: that is what the share link is for.