nixamp 0.7.41 → 0.9.3

package/dist/dns.js

@@ -0,0 +1,171 @@
+/**
+ * The zone: where a server's name is written down.
+ *
+ * nixamp.com hands every signed-in account's servers a name under
+ * `<label>.<handle>.nixamp.com`, and a name is only a name once it resolves.
+ * The records live at Porkbun, behind an API key that stays on nixamp.com:
+ * a server asks nixamp.com for its name, and nixamp.com is the only thing
+ * that ever talks to the registrar. The certificate module needs the same
+ * zone for its `_acme-challenge` TXT records, which is why TXT is here too.
+ *
+ * Behind an interface, because a test wants a zone it can read back without
+ * a network, and a nixamp started without keys still wants the rest of the
+ * code to run.
+ */
+import { isIP } from "node:net";
+/** 2026, not 1998: an address is either family, and both are first class. */
+export function isIPv4(value) {
+    return typeof value === "string" && isIP(value) === 4;
+}
+export function isIPv6(value) {
+    return typeof value === "string" && isIP(value) === 6;
+}
+/** Porkbun's floor. Anything lower is silently raised, so it is raised here, loudly. */
+export const MIN_TTL = 600;
+function ttlOf(ttl) {
+    return Math.max(MIN_TTL, Math.floor(ttl ?? MIN_TTL));
+}
+/**
+ * A zone kept in memory. For tests, and for a nixamp started without registrar
+ * keys, where a name can be handed out and simply will not resolve -- which the
+ * operator is told about elsewhere, rather than crashing here.
+ */
+export class MemoryZone {
+    zone;
+    records = [];
+    sequence = 0;
+    constructor(zone) {
+        this.zone = zone;
+    }
+    async list(host, type) {
+        return this.records.filter((record) => record.host === host && record.type === type);
+    }
+    async set(host, type, content, ttl) {
+        await this.remove(host, type);
+        await this.add(host, type, content, ttl);
+    }
+    async add(host, type, content, ttl) {
+        this.records.push({ id: String(++this.sequence), host, type, content, ttl: ttlOf(ttl) });
+    }
+    async remove(host, type, content) {
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const record = this.records[i];
+            if (record.host !== host || record.type !== type)
+                continue;
+            if (content !== undefined && record.content !== content)
+                continue;
+            this.records.splice(i, 1);
+        }
+    }
+}
+/** How long to wait on the registrar before deciding it is not answering. */
+const PORKBUN_TIMEOUT_MS = 20_000;
+/**
+ * Porkbun's v3 DNS API.
+ *
+ * Every call is a POST carrying both halves of the key in the body -- the
+ * field is `secretapikey`, which the API itself names as the usual mistake --
+ * and the subdomain is the host with the zone taken off: "server2.chovy" for
+ * "server2.chovy.nixamp.com", and nothing at all for the apex.
+ */
+export class Porkbun {
+    zone;
+    apiKey;
+    secretApiKey;
+    send;
+    base;
+    constructor(zone, apiKey, secretApiKey, send = fetch, base = "https://api.porkbun.com/api/json/v3") {
+        this.zone = zone;
+        this.apiKey = apiKey;
+        this.secretApiKey = secretApiKey;
+        this.send = send;
+        this.base = base;
+    }
+    /** The part before the zone, or "" for the zone itself. */
+    sub(host) {
+        const suffix = `.${this.zone}`;
+        if (host === this.zone)
+            return "";
+        if (!host.endsWith(suffix))
+            throw new Error(`${host} is not in ${this.zone}`);
+        return host.slice(0, -suffix.length);
+    }
+    async call(path, fields = {}) {
+        let answer;
+        try {
+            answer = await this.send(`${this.base}${path}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ apikey: this.apiKey, secretapikey: this.secretApiKey, ...fields }),
+                signal: AbortSignal.timeout(PORKBUN_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new Error(`Porkbun did not answer: ${error.message}`);
+        }
+        let body;
+        try {
+            body = (await answer.json());
+        }
+        catch {
+            throw new Error(`Porkbun answered ${answer.status} with something that is not JSON`);
+        }
+        if (!answer.ok || body.status !== "SUCCESS") {
+            throw new Error(`Porkbun refused: ${body.message ?? `HTTP ${answer.status}`}`);
+        }
+        return body;
+    }
+    async list(host, type) {
+        // A trailing slash with nothing after it is how the apex is asked for.
+        const body = await this.call(`/dns/retrieveByNameType/${this.zone}/${type}/${this.sub(host)}`);
+        return (body.records ?? [])
+            .filter((record) => (record.type ?? type) === type)
+            .map((record) => ({
+            id: String(record.id ?? ""),
+            host: record.name ?? host,
+            type,
+            content: record.content ?? "",
+            ttl: Number(record.ttl ?? MIN_TTL) || MIN_TTL,
+        }));
+    }
+    async add(host, type, content, ttl) {
+        await this.call(`/dns/create/${this.zone}`, {
+            name: this.sub(host),
+            type,
+            content,
+            ttl: String(ttlOf(ttl)),
+        });
+    }
+    async set(host, type, content, ttl) {
+        const existing = await this.list(host, type);
+        const [first, ...extras] = existing;
+        if (first === undefined) {
+            await this.add(host, type, content, ttl);
+            return;
+        }
+        // Edit rather than delete-and-create: the name never has a moment with no
+        // record at all, which for an A record is a moment nobody can connect.
+        // Unless nothing would change: Porkbun refuses an edit that edits nothing
+        // ("We were unable to edit the DNS record"), and a server announcing the
+        // address it already has is the ordinary case, not an error.
+        if (first.content !== content || first.ttl !== ttlOf(ttl)) {
+            await this.call(`/dns/edit/${this.zone}/${first.id}`, {
+                name: this.sub(host),
+                type,
+                content,
+                ttl: String(ttlOf(ttl)),
+            });
+        }
+        for (const extra of extras) {
+            await this.call(`/dns/delete/${this.zone}/${extra.id}`);
+        }
+    }
+    async remove(host, type, content) {
+        const existing = await this.list(host, type);
+        for (const record of existing) {
+            if (content !== undefined && record.content !== content)
+                continue;
+            await this.call(`/dns/delete/${this.zone}/${record.id}`);
+        }
+    }
+}

package/dist/library.d.ts

@@ -0,0 +1,36 @@
+export interface Config {
+    /** The folder the daemon serves when it is not told which. */
+    library?: string;
+}
+export declare function configPath(): string;
+export declare function readConfig(): Config;
+export declare function writeConfig(patch: Partial<Config>): void;
+/** The saved library, or "" when nobody has said yet. */
+export declare function readLibrary(): string;
+export declare function writeLibrary(path: string): void;
+/**
+ * Why a folder must not be served, or "" when it may be.
+ *
+ * Judged on the resolved path, so `~/..` and `/home/me/./` do not slip past.
+ * A hidden folder inside home is refused because that is where `.ssh`,
+ * `.config` and nixamp's own keys are; a hidden folder elsewhere is somebody's
+ * deliberate choice.
+ */
+export declare function forbiddenLibrary(path: string, home?: string): string;
+/** Folders a person is likely to mean, in the order they are likely to mean them. */
+export declare function suggestedLibraries(home?: string): string[];
+/** One line from the terminal. Split out so the question can be tested. */
+export declare function askLine(question: string): Promise<string>;
+/**
+ * Ask where the media is, refusing the answers that must be refused, and
+ * keep the answer. Empty when the person gave up or gave nothing usable
+ * three times.
+ */
+export declare function askLibrary(ask?: (question: string) => Promise<string>, home?: string, say?: (line: string) => void): Promise<string>;
+/**
+ * The library to use: the saved one, or -- when there is somebody to ask --
+ * the one they name now. "" when there is neither.
+ */
+export declare function chooseLibrary(interactive: boolean, ask?: (question: string) => Promise<string>): Promise<string>;
+/** `nixamp library [folder]`: say where the media is, or set it. */
+export declare function libraryCommand(argv: string[]): Promise<number>;

package/dist/library.js

@@ -0,0 +1,167 @@
+/**
+ * Where the media is.
+ *
+ * A server that is not told serves the directory it was started in, and a
+ * daemon restarted from a home directory served the home directory: every
+ * key, session and download on the machine, listed in a public directory
+ * under a link anybody could be handed. That is not a default anyone chose,
+ * so it is not a default any more.
+ *
+ * The library is a setting. It is asked for once -- at sign-in, or the first
+ * time the daemon is started without being told -- and kept beside the keys,
+ * so `nixamp daemon start` on its own means the same folder every time. And
+ * some folders are refused however they are asked for: the whole filesystem,
+ * the home directory, anything above it, and the hidden folders where keys
+ * and sessions live.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stateDir } from "./daemon.js";
+export function configPath() {
+    return join(stateDir(), "config.json");
+}
+export function readConfig() {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return {};
+        const record = parsed;
+        return { ...(typeof record["library"] === "string" ? { library: record["library"] } : {}) };
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(patch) {
+    const next = { ...readConfig(), ...patch };
+    mkdirSync(stateDir(), { recursive: true });
+    writeFileSync(configPath(), `${JSON.stringify(next, null, 2)}\n`);
+}
+/** The saved library, or "" when nobody has said yet. */
+export function readLibrary() {
+    return readConfig().library ?? "";
+}
+export function writeLibrary(path) {
+    writeConfig({ library: resolve(path) });
+}
+/**
+ * Why a folder must not be served, or "" when it may be.
+ *
+ * Judged on the resolved path, so `~/..` and `/home/me/./` do not slip past.
+ * A hidden folder inside home is refused because that is where `.ssh`,
+ * `.config` and nixamp's own keys are; a hidden folder elsewhere is somebody's
+ * deliberate choice.
+ */
+export function forbiddenLibrary(path, home = homedir()) {
+    const full = resolve(path);
+    const house = resolve(home);
+    if (full === "/" || /^[A-Za-z]:\\?$/.test(full))
+        return "the whole filesystem";
+    if (full === house)
+        return "your whole home directory";
+    if (house.startsWith(`${full}/`))
+        return "a folder above your home directory";
+    if (full.startsWith(`${house}/`)) {
+        // Any dotted segment on the way, not only the last: ~/.local/state is
+        // where nixamp's own keys are, and its basename says nothing.
+        const hidden = full.slice(house.length + 1).split("/").find((segment) => segment.startsWith("."));
+        if (hidden)
+            return `a hidden folder (${hidden}), which is where keys and sessions live`;
+    }
+    return "";
+}
+/** Folders a person is likely to mean, in the order they are likely to mean them. */
+export function suggestedLibraries(home = homedir()) {
+    return ["Music", "Videos", "Movies", "Downloads"]
+        .map((name) => join(home, name))
+        .filter((path) => {
+        try {
+            return statSync(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** One line from the terminal. Split out so the question can be tested. */
+export async function askLine(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Ask where the media is, refusing the answers that must be refused, and
+ * keep the answer. Empty when the person gave up or gave nothing usable
+ * three times.
+ */
+export async function askLibrary(ask = askLine, home = homedir(), say = (line) => console.log(line)) {
+    const suggestions = suggestedLibraries(home);
+    say("Where is your media? nixamp serves one folder and nothing outside it.");
+    for (const path of suggestions)
+        say(`  ${path}`);
+    const fallback = suggestions[0] ?? "";
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const typed = await ask(fallback ? `Folder [${fallback}]: ` : "Folder: ");
+        const chosen = (typed || fallback).replace(/^~(?=$|\/)/, home);
+        if (!chosen)
+            continue;
+        const full = resolve(chosen);
+        const why = forbiddenLibrary(full, home);
+        if (why) {
+            say(`  nixamp will not serve ${why}. Pick a folder with your media in it.`);
+            continue;
+        }
+        if (!existsSync(full) || !statSync(full).isDirectory()) {
+            say(`  ${full} is not a folder here.`);
+            continue;
+        }
+        writeLibrary(full);
+        say(`  Serving ${full}. Change it any time with \`nixamp library <folder>\`.`);
+        return full;
+    }
+    return "";
+}
+/**
+ * The library to use: the saved one, or -- when there is somebody to ask --
+ * the one they name now. "" when there is neither.
+ */
+export async function chooseLibrary(interactive, ask) {
+    const saved = readLibrary();
+    if (saved)
+        return saved;
+    if (!interactive)
+        return "";
+    return askLibrary(ask);
+}
+/** `nixamp library [folder]`: say where the media is, or set it. */
+export async function libraryCommand(argv) {
+    const [given] = argv;
+    if (!given) {
+        const saved = readLibrary();
+        if (!saved) {
+            console.log("nixamp: no library set. `nixamp library ~/Music` sets it, and `nixamp daemon start` serves it.");
+            return 1;
+        }
+        console.log(saved);
+        return 0;
+    }
+    const full = resolve(given.replace(/^~(?=$|\/)/, homedir()));
+    const why = forbiddenLibrary(full);
+    if (why) {
+        console.error(`nixamp: will not serve ${why}. Pick a folder with your media in it.`);
+        return 64;
+    }
+    if (!existsSync(full) || !statSync(full).isDirectory()) {
+        console.error(`nixamp: ${full} is not a folder here.`);
+        return 66;
+    }
+    writeLibrary(full);
+    console.log(`nixamp will serve ${full}. Start it with \`nixamp daemon start\`.`);
+    return 0;
+}

package/dist/main.js

@@ -53,6 +53,8 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp login [--with github]  sign in to nixamp.com, in a browser or here
   nixamp logout / whoami        forget it, or check it
   nixamp token create|list|revoke  tokens for a machine that cannot sign in
+  nixamp dns [set|rm]           names under your handle, for your servers
+  nixamp library [folder]       where the media is; the daemon serves this and nothing outside it
   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
@@ -164,6 +166,18 @@ NIXAMP_TOKEN in the environment is a signed-in nixamp with no login at all.
 A token is shown once because the server keeps only its hash. Put it in the
 environment as NIXAMP_TOKEN, or keep it here with \`nixamp login --token\`.
 Signing out does not touch it: that is what it is for.
+`,
+    dns: `nixamp dns — names under your handle, for your servers.
+
+  nixamp dns                     every name on your account, and where it points
+  nixamp dns set NAME            NAME.<handle>.nixamp.com, pointed at this machine
+  nixamp dns set NAME --a IP --aaaa IP   pointed somewhere you name; "off" clears one
+  nixamp dns set NAME --ttl N    how long resolvers may keep it (seconds)
+  nixamp dns rm NAME             take the name away
+
+The DNS keys stay on nixamp.com. A signed-in \`nixamp serve\` names itself
+this way on start and picks up the handle's certificate, so a server is
+https://NAME.<handle>.nixamp.com with nothing typed here.
 `,
     daemon: `nixamp daemon — a nixamp that outlives the terminal that started it.
 
@@ -221,9 +235,45 @@ async function runDaemon(argv) {
     const d = await import("./daemon.js");
     const [action = "status", ...rest] = argv;
     const entry = fileURLToPath(new URL("./main.js", import.meta.url));
+    // The daemon has to know where the media is. Told a folder, that folder is
+    // kept as the library so the next start needs no telling; told nothing, the
+    // saved library is used, or asked for when there is somebody to ask.
+    const withLibrary = async (args) => {
+        const { forbiddenLibrary, chooseLibrary, writeLibrary } = await import("./library.js");
+        const { parseServeArgs } = await import("./server.js");
+        const { isRemote } = await import("./sources.js");
+        let given = "";
+        try {
+            given = parseServeArgs(args).root;
+        }
+        catch {
+            // A bad flag is the daemon's to report, in its own words.
+            return args;
+        }
+        if (given) {
+            if (!isRemote(given)) {
+                const why = forbiddenLibrary(given);
+                if (why) {
+                    console.error(`nixamp: will not serve ${why}. Pick a folder with your media in it.`);
+                    return null;
+                }
+                writeLibrary(given);
+            }
+            return args;
+        }
+        const library = await chooseLibrary(process.stdin.isTTY === true);
+        if (!library) {
+            console.error("nixamp: which folder? `nixamp library ~/Music` once, then `nixamp daemon start`.");
+            return null;
+        }
+        return [library, ...args];
+    };
     if (action === "start") {
+        const args = await withLibrary(rest);
+        if (args === null)
+            return 64;
         try {
-            const state = await d.start(rest, entry);
+            const state = await d.start(args, entry);
             for (const line of d.daemonLines(state))
                 console.log(line);
             return 0;
@@ -239,8 +289,13 @@ async function runDaemon(argv) {
         return 0;
     }
     if (action === "restart") {
+        // With no arguments the flags it was started with are replayed, library
+        // included; with arguments, the library rule applies as for start.
+        const args = rest.length === 0 ? rest : await withLibrary(rest);
+        if (args === null)
+            return 64;
         try {
-            const state = await d.restart(rest, entry);
+            const state = await d.restart(args, entry);
             for (const line of d.daemonLines(state))
                 console.log(line);
             return 0;
@@ -298,7 +353,14 @@ export async function main() {
     }
     if (first === "serve") {
         const { serve } = await import("./server.js");
-        await serve(rest, version());
+        try {
+            await serve(rest, version());
+        }
+        catch (error) {
+            // A refusal is a sentence, not a stack trace.
+            console.error(error.message);
+            process.exitCode = 64;
+        }
         return;
     }
     if (first === "daemon") {
@@ -313,6 +375,14 @@ export async function main() {
     if (first === "login" || first === "signup") {
         const { login } = await import("./session.js");
         process.exitCode = await login(first === "signup" ? [...rest, "--signup"] : rest);
+        // Signed in is the moment a machine is about to be a server, so it is
+        // the moment to ask where the media is -- once, kept beside the keys.
+        if (process.exitCode === 0 && process.stdin.isTTY) {
+            const { chooseLibrary } = await import("./library.js");
+            const library = await chooseLibrary(true);
+            if (library)
+                console.log("  Start serving it with `nixamp daemon start`.");
+        }
         return;
     }
     if (first === "opendir" || first === "opendirs") {
@@ -330,6 +400,16 @@ export async function main() {
         process.exitCode = await tokens(rest);
         return;
     }
+    if (first === "dns") {
+        const { dns } = await import("./session.js");
+        process.exitCode = await dns(rest);
+        return;
+    }
+    if (first === "library") {
+        const { libraryCommand } = await import("./library.js");
+        process.exitCode = await libraryCommand(rest);
+        return;
+    }
     if (first === "logout" || first === "whoami") {
         const session = await import("./session.js");
         process.exitCode = first === "logout" ? session.logout() : await session.whoami();
@@ -346,8 +426,16 @@ export async function main() {
     }
     // resolve() would turn https://host/x into /cwd/https:/host/x, so a URL is
     // left exactly as it was typed.
-    const asked = first ?? ".";
+    // The saved library before the current directory, and never a folder the
+    // server would refuse: `d` hands this same folder to a daemon.
+    const { forbiddenLibrary, readLibrary } = await import("./library.js");
+    const asked = first ?? (readLibrary() || ".");
     const target = isRemote(asked) ? asked : resolve(asked);
+    const why = isRemote(target) ? "" : forbiddenLibrary(target);
+    if (why) {
+        console.error(`nixamp: will not play ${why}. Pick a folder with your media in it, or set one: nixamp library ~/Music`);
+        process.exit(64);
+    }
     const tools = detectTools();
     // The noise it makes when it wakes up. Started before the library is walked
     // so it plays over the wait rather than after it, and never awaited: a

package/dist/names.d.ts

@@ -0,0 +1,66 @@
+/**
+ * An account's names: the servers it runs, each with a hostname under its handle.
+ *
+ * `server2.chovy.nixamp.com` used to be a record somebody typed into the
+ * registrar by hand, which is why the second machine came up as a bare IP
+ * over http. A name is now a row against the account, mirrored into the zone
+ * as an A and an AAAA record, and the account may make, change and drop as
+ * many as it reasonably needs without anybody holding a registrar key.
+ *
+ * The database row is the truth and the zone follows it: the zone is written
+ * first, so a registrar that refuses is an error to the caller and nothing is
+ * stored, rather than a row that claims a name the world cannot resolve.
+ */
+import type { Queryable } from "./follows.ts";
+import { type DnsZone } from "./dns.ts";
+export interface NameRecord {
+    label: string;
+    host: string;
+    a: string;
+    aaaa: string;
+    ttl: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** An error with the HTTP status it deserves, so a route can pass it straight on. */
+export declare class NameError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * The label a server may have: two to thirty of [a-z0-9-], not starting or
+ * ending with a hyphen, lowercased for the caller who typed it in capitals.
+ * "" when it is not one, so a route can say so in one sentence.
+ */
+export declare function validLabel(value: unknown): string;
+export declare const MIN_TTL = 600;
+export declare const MAX_TTL = 86400;
+/** Enough for a rack, not enough for a squatter. */
+export declare const DEFAULT_PER_ACCOUNT = 20;
+export declare class Names {
+    private readonly db;
+    private readonly dns;
+    private readonly limits;
+    private ready;
+    constructor(db: Queryable, dns: DnsZone, limits?: {
+        perAccount?: number;
+    });
+    private ensure;
+    private host;
+    private record;
+    list(accountId: string, handle: string): Promise<NameRecord[]>;
+    /** The row for one name, whoever owns it. */
+    private find;
+    /**
+     * Make or change a name. `null` for a family takes that record away,
+     * `undefined` leaves it as it was, so a server that has only ever had an
+     * IPv4 address can be given an IPv6 one without restating the first.
+     */
+    set(accountId: string, handle: string, wanted: unknown, want: {
+        a?: string | null;
+        aaaa?: string | null;
+        ttl?: number;
+    }): Promise<NameRecord>;
+    /** Take a name away. False when it is not this account's to take. */
+    remove(accountId: string, handle: string, wanted: unknown): Promise<boolean>;
+}