nixamp 0.1.0 → 0.2.0

package/dist/server.js

@@ -11,11 +11,15 @@
  */
 import { createReadStream, statSync } from "node:fs";
 import { createServer as createHttpServer } from "node:http";
-import { networkInterfaces } from "node:os";
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { Connections } from "./connections.js";
+import { isRemote } from "./sources.js";
+import { elevate, firewallInUse, keyCookie, keyFrom, keysMatch, newKey, portCommands, reachableAddresses, shareLink, } from "./share.js";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { detectTools, peaks, RATE, Stream, toMono, } from "./audio.js";
 import { Analyser, bandEdges, bands, decay } from "./fft.js";
-import { loadPlaylist } from "./playlist.js";
+import { loadSource } from "./playlist.js";
 import { emptySnapshot, parseCommand, } from "./protocol.js";
 const FFT_SIZE = 2048;
 export const SERVE_BAND_COUNT = 24;
@@ -30,9 +34,15 @@ export function parseServeArgs(argv) {
     const options = {
         root: ".",
         port: Number.isInteger(fromEnv) && fromEnv > 0 && fromEnv <= 65535 ? fromEnv : DEFAULT_PORT,
-        host: "127.0.0.1",
+        // Every interface, because a player nobody else can reach is not much of a
+        // remote. The key in the link is what makes that safe; --no-key gives up
+        // both at once, and --host pins it back to one address.
+        host: "0.0.0.0",
         web: null,
         media: true,
+        key: true,
+        openPort: false,
+        announce: false,
     };
     let sawRoot = false;
     for (let i = 0; i < argv.length; i++) {
@@ -60,6 +70,15 @@ export function parseServeArgs(argv) {
         else if (arg === "--no-media") {
             options.media = false;
         }
+        else if (arg === "--no-key") {
+            options.key = false;
+        }
+        else if (arg === "--open-port") {
+            options.openPort = true;
+        }
+        else if (arg === "--announce") {
+            options.announce = true;
+        }
         else if (arg.startsWith("-")) {
             throw new Error(`nixamp serve: unknown option ${arg}`);
         }
@@ -80,6 +99,7 @@ const TYPES = {
     // The installer, so `curl https://nixamp.com/install.sh` is readable rather
     // than a download prompt.
     ".sh": "text/x-shellscript; charset=utf-8",
+    ".ps1": "text/plain; charset=utf-8",
     ".svg": "image/svg+xml",
     ".png": "image/png",
     ".ico": "image/x-icon",
@@ -343,6 +363,15 @@ export class PlayerEngine {
         }
         this.listeners.clear();
     }
+    replace(tracks, root) {
+        this.stop();
+        this.tracks = tracks;
+        this.root = root;
+        this.state.index = 0;
+        this.state.position = 0;
+        this.state.note = "";
+        this.push();
+    }
 }
 /** An engine with no library behind it, for the hosted PWA. */
 export class EmptyEngine {
@@ -361,6 +390,7 @@ export class EmptyEngine {
     trackPath() {
         return undefined;
     }
+    replace() { }
     stop() { }
 }
 const CORS = {
@@ -399,14 +429,54 @@ async function readBody(request, limit = 64 * 1024) {
  * drive it with a real socket and no ffmpeg in sight.
  */
 export function createHandler(engine, options) {
+    const tracker = options.connections ?? new Connections();
+    const started = Date.now();
+    /** Count a request in, count its bytes, and close it out exactly once. */
+    const watch = (request, response, kind, track) => {
+        const { id } = tracker.open(request, kind, track);
+        const write = response.write.bind(response);
+        response.write = ((chunk, ...rest) => {
+            if (typeof chunk === "string" || chunk instanceof Uint8Array) {
+                tracker.add(id, typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.byteLength);
+            }
+            return write(chunk, ...rest);
+        });
+        // 'close' fires for a finished response and for a listener that walked
+        // away, which are the same thing as far as "is it still going" goes.
+        response.once("close", () => tracker.close(id));
+    };
     return async function handle(request, response) {
         const url = new URL(request.url ?? "/", "http://localhost");
         const path = url.pathname;
+        const key = options.key ?? null;
         if (request.method === "OPTIONS") {
             response.writeHead(204, CORS);
             response.end();
             return;
         }
+        // Opening the share link is what hands a browser its key. It comes back as
+        // a cookie, so every later fetch, EventSource and <audio src> carries it
+        // without the page knowing anything about keys.
+        if (key !== null && path.startsWith("/s/")) {
+            const offered = decodeURIComponent(path.slice("/s/".length));
+            if (!keysMatch(offered, key)) {
+                json(response, 404, { error: "not found" });
+                return;
+            }
+            response.writeHead(302, { ...CORS, "set-cookie": keyCookie(key), location: "/" });
+            response.end();
+            return;
+        }
+        // /api/health answers unauthenticated on purpose: it is how you check the
+        // port is open from another device before wondering whether the link is
+        // wrong, and it says nothing about the library.
+        if (key !== null && path !== "/api/health") {
+            const offered = keyFrom(request, url);
+            if (offered === null || !keysMatch(offered, key)) {
+                json(response, 401, { error: "this nixamp needs the key from its share link" });
+                return;
+            }
+        }
         if (path === "/api/health") {
             json(response, 200, { name: "nixamp", version: options.version, media: options.media });
             return;
@@ -415,7 +485,19 @@ export function createHandler(engine, options) {
             json(response, 200, engine.snapshot());
             return;
         }
+        // Everything the admin view draws, in one request: who is connected, and
+        // what this server is.
+        if (path === "/api/connections") {
+            json(response, 200, {
+                connections: tracker.list(),
+                active: tracker.active,
+                startedAt: started,
+                now: Date.now(),
+            });
+            return;
+        }
         if (path === "/api/events") {
+            watch(request, response, "events", "");
             response.writeHead(200, {
                 ...CORS,
                 "content-type": "text/event-stream; charset=utf-8",
@@ -461,6 +543,39 @@ export function createHandler(engine, options) {
             json(response, 200, engine.snapshot());
             return;
         }
+        // Re-stream: hand the running server a different source. The listeners
+        // stay connected; what they are listening to changes under them.
+        if (path === "/api/source") {
+            if (request.method !== "POST") {
+                json(response, 405, { error: "POST only" });
+                return;
+            }
+            let source = "";
+            try {
+                source = String(JSON.parse(await readBody(request)).source ?? "");
+            }
+            catch {
+                json(response, 400, { error: "bad JSON" });
+                return;
+            }
+            if (!source) {
+                json(response, 400, { error: "no source given" });
+                return;
+            }
+            try {
+                const tracks = await options.load(source);
+                if (tracks.length === 0) {
+                    json(response, 422, { error: `nothing to play at ${source}` });
+                    return;
+                }
+                engine.replace(tracks, source);
+                json(response, 200, engine.snapshot());
+            }
+            catch (error) {
+                json(response, 422, { error: error.message.replace(/^nixamp: /, "") });
+            }
+            return;
+        }
         if (path.startsWith("/api/media/")) {
             if (!options.media) {
                 json(response, 403, { error: "media streaming is off" });
@@ -472,9 +587,29 @@ export function createHandler(engine, options) {
                 json(response, 404, { error: "no such track" });
                 return;
             }
+            watch(request, response, "media", engine.snapshot().tracks[index]?.title ?? file);
             sendFile(request, response, file);
             return;
         }
+        // Whatever the source is, this comes back as MP3 a browser will play:
+        // a flac, a wma, a URL, an HLS stream. ffmpeg reads them all and we hand
+        // the bytes on as they arrive, so a live stream starts immediately rather
+        // than after it ends, which for a live stream is never.
+        if (path.startsWith("/api/stream/")) {
+            const index = Number(path.slice("/api/stream/".length));
+            const source = Number.isInteger(index) ? engine.trackPath(index) : undefined;
+            if (source === undefined) {
+                json(response, 404, { error: "no such track" });
+                return;
+            }
+            if (!options.media) {
+                json(response, 403, { error: "media streaming is off" });
+                return;
+            }
+            watch(request, response, "stream", engine.snapshot().tracks[index]?.title ?? source);
+            transcode(request, response, source, options.ffmpeg ?? ["ffmpeg"]);
+            return;
+        }
         if (path.startsWith("/api/")) {
             json(response, 404, { error: "no such endpoint" });
             return;
@@ -501,6 +636,91 @@ export function createHandler(engine, options) {
         json(response, 404, { error: "not found" });
     };
 }
+/** Read a file, or null. The firewall probe asks about files it may not have. */
+function readIfPossible(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode anything and hand back MP3, as it is produced.
+ *
+ * No seeking: this is a pipe, and the length is not known until it ends. The
+ * player falls back to /api/media for a local file it can seek, and uses this
+ * for everything else.
+ */
+function transcode(request, response, source, ffmpeg) {
+    const [command, ...prefix] = ffmpeg;
+    const child = spawn(command, [
+        ...prefix,
+        "-hide_banner",
+        "-loglevel", "error",
+        // Reconnect through the sort of hiccup a long stream runs into. These
+        // belong to the http protocol, and ffmpeg rejects the whole command
+        // when they are handed to it for a file on disk.
+        ...(isRemote(source) ? ["-reconnect", "1", "-reconnect_streamed", "1", "-reconnect_delay_max", "5"] : []),
+        "-i", source,
+        "-vn",
+        "-f", "mp3",
+        "-b:a", "192k",
+        "-",
+    ], { stdio: ["ignore", "pipe", "pipe"] });
+    let failed = "";
+    child.stderr.on("data", (chunk) => {
+        // Keep the tail: ffmpeg says what went wrong on its last line.
+        failed = (failed + chunk.toString()).slice(-2000);
+    });
+    let started = false;
+    const begin = () => {
+        if (started)
+            return;
+        started = true;
+        response.writeHead(200, {
+            ...CORS,
+            "content-type": "audio/mpeg",
+            "cache-control": "no-store",
+            // Length is unknowable up front, and a browser is happy without it.
+            "transfer-encoding": "chunked",
+        });
+    };
+    // Wait for a first byte before promising success. ffmpeg rejects a bad option
+    // or a missing input immediately, and answering 200 with nothing looks the
+    // same from a player as a track that is simply silent.
+    child.stdout.once("data", begin);
+    // Both ends can fail: a listener closing the tab breaks the socket under the
+    // pipe, and an EPIPE nobody is listening for takes the process down.
+    child.stdout.on("error", () => child.kill("SIGKILL"));
+    response.on("error", () => child.kill("SIGKILL"));
+    child.stdout.pipe(response);
+    child.on("error", (error) => {
+        console.error(`nixamp: ffmpeg could not start: ${error.message}`);
+        if (!response.headersSent)
+            json(response, 500, { error: "ffmpeg could not start" });
+        else
+            response.end();
+    });
+    child.on("close", (code) => {
+        const message = failed.trim();
+        if (code !== 0 && code !== null)
+            console.error(`nixamp: ffmpeg exited ${code}: ${message}`);
+        if (!started) {
+            // Nothing was ever produced, so the status can still tell the truth.
+            json(response, 502, { error: "could not decode that source", detail: message.split("\n").pop() ?? "" });
+            return;
+        }
+        response.end();
+    });
+    // A listener that closes the tab should not leave an ffmpeg decoding into
+    // nothing for the rest of the album.
+    const stop = () => {
+        child.kill("SIGKILL");
+    };
+    request.on("close", stop);
+    response.on("close", stop);
+}
 function isFile(path) {
     try {
         return statSync(path).isFile();
@@ -559,38 +779,118 @@ export function createServer(engine, options) {
         });
     });
 }
-/** Where a remote on another device should point its browser. */
-export function addressesFor(host, port) {
-    if (host !== "0.0.0.0" && host !== "::")
-        return [`http://${host}:${port}`];
-    const out = [`http://localhost:${port}`];
-    for (const entries of Object.values(networkInterfaces())) {
-        for (const entry of entries ?? []) {
-            if (entry.family === "IPv4" && !entry.internal)
-                out.push(`http://${entry.address}:${port}`);
-        }
-    }
-    return out;
-}
 export async function serve(argv, version = "0.1.0") {
     const options = parseServeArgs(argv);
-    const root = resolve(options.root);
+    const root = isRemote(options.root) ? options.root : resolve(options.root);
     const tools = detectTools();
-    const tracks = loadPlaylist(tools, root);
+    const tracks = await loadSource(tools, root);
     const engine = tracks.length > 0
         ? new PlayerEngine(tracks, root, tools)
         : new EmptyEngine(`No audio files under ${root}.`);
     const web = options.web !== null ? resolve(options.web) : defaultWebDir();
-    const server = createServer(engine, { web, media: options.media, version });
-    await new Promise((done) => server.listen(options.port, options.host, done));
+    const key = options.key ? newKey() : null;
+    const server = createServer(engine, {
+        web,
+        media: options.media,
+        version,
+        key,
+        ffmpeg: tools.ffmpeg,
+        load: (next) => loadSource(tools, next),
+    });
+    // A port already in use is the most ordinary failure there is, and it
+    // arrives as an unhandled 'error' event that takes the process down with a
+    // stack trace nobody reads.
+    await new Promise((done, fail) => {
+        server.once("error", (error) => {
+            fail(new Error(error.code === "EADDRINUSE"
+                ? `nixamp: port ${options.port} is already in use. Pass --port to pick another.`
+                : error.code === "EACCES"
+                    ? `nixamp: not allowed to listen on port ${options.port}. Ports below 1024 need root.`
+                    : `nixamp: could not listen on ${options.host}:${options.port}: ${error.message}`));
+        });
+        server.listen(options.port, options.host, done);
+    });
     const bound = server.address();
     const port = typeof bound === "object" && bound !== null ? bound.port : options.port;
+    const io = {
+        read: readIfPossible,
+        run: (command, args) => {
+            const done = spawnSync(command, args, { encoding: "utf8" });
+            return { status: done.status, stdout: done.stdout ?? "" };
+        },
+    };
+    if (options.announce) {
+        console.log(JSON.stringify({ nixamp: "listening", host: options.host, port, key, source: root }));
+    }
     console.log(`nixamp serve — ${tracks.length} tracks under ${root}`);
-    for (const address of addressesFor(options.host, port))
-        console.log(`  ${address}`);
+    console.log("");
+    // The link, not the address. Without the key the address is a 401, so
+    // printing a bare host:port would be printing something that does not work.
+    const addresses = reachableAddresses(options.host, port);
+    const width = Math.max(...addresses.map((a) => a.label.length));
+    for (const { label, url } of addresses) {
+        console.log(`  ${label.padEnd(width)}  ${shareLink(url, key)}`);
+    }
+    console.log("");
+    if (key === null) {
+        console.log("  No key: anyone who can reach this port can drive it and hear it.");
+    }
+    else {
+        console.log("  Open that link once on a phone or a laptop and it stays signed in.");
+        console.log(`  Anything without the key gets a 401. Key: ${key}`);
+    }
+    if (addresses.some((a) => a.label === "on the internet")) {
+        console.log("");
+        console.log(key === null
+            ? "  The public address is open to anyone: --no-key means no key. --host 127.0.0.1 keeps it here."
+            : "  The public address works from anywhere, for anyone with the key. --host 127.0.0.1 keeps it here.");
+    }
+    if (!options.media)
+        console.log("  Audio stays on this machine: --no-media is set.");
     if (web === null)
-        console.log("  (no built PWA found — run `bun run web:build` to serve one)");
+        console.log("  No built PWA found, so / has nothing to serve: run `bun run web:build`.");
+    // Listening on every interface proves the socket is open here and nothing
+    // about the path between here and the phone.
+    const listening = options.host === "0.0.0.0" || options.host === "::";
+    const firewall = listening ? firewallInUse(io) : null;
+    let closePort = null;
+    if (firewall !== null) {
+        const { open, close } = portCommands(firewall, port);
+        if (!options.openPort) {
+            console.log("");
+            console.log(`  ${firewall} is running, so other devices cannot reach this port yet:`);
+            console.log(`    sudo ${open.join(" ")}`);
+            console.log("  or start with --open-port and nixamp will do it, and undo it on exit.");
+        }
+        else {
+            const elevated = elevate(io, open);
+            if (elevated === null) {
+                console.log("");
+                console.log(`  --open-port needs root or passwordless sudo. Run this yourself:`);
+                console.log(`    sudo ${open.join(" ")}`);
+            }
+            else {
+                const done = spawnSync(elevated[0], elevated.slice(1), { encoding: "utf8" });
+                if (done.status === 0) {
+                    console.log("");
+                    console.log(`  Opened ${port}/tcp in ${firewall}. It closes again when this exits.`);
+                    // Leave the machine as it was found. A player should not be the
+                    // reason a port is still open next week.
+                    closePort = () => {
+                        const undo = elevate(io, close);
+                        if (undo)
+                            spawnSync(undo[0], undo.slice(1), { stdio: "ignore" });
+                    };
+                }
+                else {
+                    console.log("");
+                    console.log(`  Could not open the port: ${(done.stderr || done.stdout || "").trim() || "unknown error"}`);
+                }
+            }
+        }
+    }
     const shutdown = () => {
+        closePort?.();
         engine.stop();
         server.close(() => process.exit(0));
         // A hung keep-alive should not outlive a ctrl-c.

package/dist/share.d.ts

@@ -0,0 +1,58 @@
+import type { IncomingMessage } from "node:http";
+/** The cookie, and the query parameter that sets it. */
+export declare const KEY_COOKIE = "nixamp_key";
+export declare const KEY_QUERY = "k";
+export declare const KEY_HEADER = "x-nixamp-key";
+/**
+ * 128 bits, base64url. Long enough that guessing is not a strategy, short
+ * enough to read down a phone screen when someone types it by hand.
+ */
+export declare function newKey(): string;
+/** 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. */
+export declare function keyFrom(request: IncomingMessage, url: URL): string | null;
+/** The Set-Cookie for a browser that just opened the link. */
+export declare function keyCookie(key: string): string;
+/** Where an address actually goes, which is not always where you would like. */
+export declare function classify(address: string): "private" | "cgnat" | "public";
+/**
+ * The addresses another device could actually reach this machine on, nearest
+ * first. On a server the public one is the point: it is the address a phone
+ * somewhere else can open. It is labelled for what it is, because the key in
+ * the link is then the only thing between a stranger and the library.
+ */
+export declare function reachableAddresses(host: string, port: number): {
+    label: string;
+    url: string;
+}[];
+/** The full link, key and all. */
+export declare function shareLink(base: string, key: string | null): string;
+/** How to run a command, so the tests never touch a real firewall. */
+export interface Runner {
+    read(path: string): string | null;
+    run(command: string, args: string[]): {
+        status: number | null;
+        stdout: string;
+    };
+}
+/** Which firewall is in the way, if any. */
+export type Firewall = "ufw" | "firewalld";
+/**
+ * Whether a firewall is running that would keep the port closed to other
+ * devices. Listening on 0.0.0.0 proves the socket is open on this machine and
+ * nothing more, so this is the difference between "it works" and "it works
+ * here".
+ */
+export declare function firewallInUse(io: Runner): Firewall | null;
+/** The commands that open and close a port, for each firewall we know. */
+export declare function portCommands(firewall: Firewall, port: number): {
+    open: string[];
+    close: string[];
+};
+/**
+ * Root runs it directly; anyone else goes through sudo, and only when sudo
+ * will not stop to ask. A server that hangs on an invisible password prompt is
+ * worse than one that tells you the command to run yourself.
+ */
+export declare function elevate(io: Runner, command: string[]): string[] | null;

package/dist/share.js

@@ -0,0 +1,153 @@
+/**
+ * The share link.
+ *
+ * `nixamp serve` listens on every interface so the phone in your pocket can
+ * reach it, and that is only reasonable because the address is not enough on
+ * its own: every request has to carry a key that is printed once, in the link.
+ * Someone else on the coffee shop wifi can find the port and gets nothing.
+ *
+ * The key travels in a cookie, set by opening the link. Nothing in the PWA had
+ * to change for that: a browser sends a same-origin cookie with every fetch,
+ * every EventSource and every `<audio src>` on its own.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { networkInterfaces } from "node:os";
+/** The cookie, and the query parameter that sets it. */
+export const KEY_COOKIE = "nixamp_key";
+export const KEY_QUERY = "k";
+export const KEY_HEADER = "x-nixamp-key";
+/**
+ * 128 bits, base64url. Long enough that guessing is not a strategy, short
+ * enough to read down a phone screen when someone types it by hand.
+ */
+export function newKey() {
+    return randomBytes(16).toString("base64url");
+}
+/** Compare without leaking where two keys first differ. */
+export function keysMatch(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    // timingSafeEqual throws on a length mismatch, which is itself the answer.
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** Every place a key is accepted from, in the order they are looked for. */
+export function keyFrom(request, url) {
+    const query = url.searchParams.get(KEY_QUERY);
+    if (query)
+        return query;
+    const header = request.headers[KEY_HEADER];
+    if (typeof header === "string" && header)
+        return header;
+    for (const part of (request.headers.cookie ?? "").split(";")) {
+        const [name, ...rest] = part.trim().split("=");
+        if (name === KEY_COOKIE && rest.length > 0)
+            return decodeURIComponent(rest.join("="));
+    }
+    return null;
+}
+/** The Set-Cookie for a browser that just opened the link. */
+export function keyCookie(key) {
+    // HttpOnly because nothing in the page reads it: the browser attaches it to
+    // every same-origin request by itself. No Secure, because the whole point is
+    // a plain-http address on your own network.
+    return `${KEY_COOKIE}=${encodeURIComponent(key)}; Path=/; Max-Age=31536000; SameSite=Lax; HttpOnly`;
+}
+/**
+ * Interfaces that exist for containers and virtual machines. An address on one
+ * of these reaches a bridge, not the phone on the sofa, and listing six of them
+ * buries the one line someone actually needed.
+ */
+const VIRTUAL = /^(docker|br-|veth|virbr|vmnet|vboxnet|lo)/;
+/** Where an address actually goes, which is not always where you would like. */
+export function classify(address) {
+    const [a, b] = address.split(".").map(Number);
+    if (a === 10)
+        return "private";
+    if (a === 192 && b === 168)
+        return "private";
+    if (a === 172 && b >= 16 && b <= 31)
+        return "private";
+    if (a === 169 && b === 254)
+        return "private";
+    // 100.64/10 is carrier-grade NAT, which in practice means Tailscale here.
+    if (a === 100 && b >= 64 && b <= 127)
+        return "cgnat";
+    return "public";
+}
+/**
+ * The addresses another device could actually reach this machine on, nearest
+ * first. On a server the public one is the point: it is the address a phone
+ * somewhere else can open. It is labelled for what it is, because the key in
+ * the link is then the only thing between a stranger and the library.
+ */
+export function reachableAddresses(host, port) {
+    const link = (address) => {
+        // A bare IPv6 address needs brackets before it is a URL.
+        const authority = address.includes(":") ? `[${address}]` : address;
+        return `http://${authority}:${port}`;
+    };
+    if (host !== "0.0.0.0" && host !== "::")
+        return [{ label: "here", url: link(host) }];
+    const LABELS = { private: "on your network", cgnat: "on tailscale", public: "on the internet" };
+    const found = [];
+    for (const [name, entries] of Object.entries(networkInterfaces())) {
+        if (VIRTUAL.test(name))
+            continue;
+        for (const entry of entries ?? []) {
+            // Link-local v6 needs a scope id to be usable, and nobody types those in.
+            if (entry.internal || entry.family !== "IPv4")
+                continue;
+            const kind = classify(entry.address);
+            found.push({ label: LABELS[kind], url: link(entry.address), kind });
+        }
+    }
+    const order = { private: 0, cgnat: 1, public: 2 };
+    found.sort((x, y) => order[x.kind] - order[y.kind]);
+    return [
+        { label: "here", url: `http://localhost:${port}` },
+        ...found.map(({ label, url }) => ({ label, url })),
+    ];
+}
+/** The full link, key and all. */
+export function shareLink(base, key) {
+    return key === null ? base : `${base}/s/${key}`;
+}
+/**
+ * Whether a firewall is running that would keep the port closed to other
+ * devices. Listening on 0.0.0.0 proves the socket is open on this machine and
+ * nothing more, so this is the difference between "it works" and "it works
+ * here".
+ */
+export function firewallInUse(io) {
+    if (process.platform !== "linux")
+        return null;
+    // ufw keeps its state in a file, so asking needs no privileges.
+    const ufw = io.read("/etc/ufw/ufw.conf");
+    if (ufw && /^ENABLED=yes/im.test(ufw))
+        return "ufw";
+    const firewalld = io.run("systemctl", ["is-active", "firewalld"]);
+    if (firewalld.status === 0 && firewalld.stdout.trim() === "active")
+        return "firewalld";
+    return null;
+}
+/** The commands that open and close a port, for each firewall we know. */
+export function portCommands(firewall, port) {
+    return firewall === "ufw"
+        ? { open: ["ufw", "allow", `${port}/tcp`], close: ["ufw", "delete", "allow", `${port}/tcp`] }
+        : {
+            open: ["firewall-cmd", `--add-port=${port}/tcp`],
+            close: ["firewall-cmd", `--remove-port=${port}/tcp`],
+        };
+}
+/**
+ * Root runs it directly; anyone else goes through sudo, and only when sudo
+ * will not stop to ask. A server that hangs on an invisible password prompt is
+ * worse than one that tells you the command to run yourself.
+ */
+export function elevate(io, command) {
+    const [head, ...rest] = command;
+    if (typeof process.getuid === "function" && process.getuid() === 0)
+        return [head, ...rest];
+    const canSudo = io.run("sudo", ["-n", "true"]);
+    return canSudo.status === 0 ? ["sudo", "-n", head, ...rest] : null;
+}