nixamp 0.8.0 → 0.9.4

package/dist/certs.d.ts

@@ -0,0 +1,112 @@
+import type { DnsZone } from "./dns.ts";
+import type { Queryable } from "./follows.ts";
+export interface Issued {
+    /** PEM, the full chain. */
+    cert: string;
+    /** PEM. */
+    key: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/** Where a DNS-01 challenge gets written, and unwritten. */
+export interface Challenge {
+    set(host: string, value: string): Promise<void>;
+    clear(host: string, value: string): Promise<void>;
+}
+/** Something that turns a list of names into a certificate. ACME, in production. */
+export interface Issuer {
+    issue(names: string[], challenge: Challenge): Promise<Issued>;
+}
+export interface AcmeIssuerOptions {
+    /** acme.directory.letsencrypt.production, or .staging while trying things out. */
+    directoryUrl: string;
+    /** The account contact Let's Encrypt writes to about expiry. */
+    email: string;
+    /** The account's private key, PEM. Kept by the caller; see Certs.accountKey. */
+    accountKey: () => Promise<string>;
+    /**
+     * How long to wait after writing the TXT before letting the CA look for it.
+     * A registrar's API answers at once; the world's resolvers do not.
+     */
+    propagationMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** A minute is what Porkbun's 600-second floor tends to cost in practice. */
+export declare const DEFAULT_PROPAGATION_MS = 60000;
+/** Renew inside the last thirty days, which is what Let's Encrypt recommends. */
+export declare const RENEW_BEFORE_MS: number;
+/** A failed order is worth trying again, but not every time somebody asks. */
+export declare const RETRY_AFTER_MS: number;
+/**
+ * Let's Encrypt, through acme-client, by DNS-01 only: a wildcard cannot be
+ * proved any other way, and the zone is the one thing nixamp.com does hold.
+ */
+export declare class AcmeIssuer implements Issuer {
+    private readonly options;
+    constructor(options: AcmeIssuerOptions);
+    issue(names: string[], challenge: Challenge): Promise<Issued>;
+}
+export type CertState = {
+    status: "ready";
+    cert: string;
+    key: string;
+    expiresAt: number;
+    renewing: boolean;
+} | {
+    status: "issuing";
+    since: number;
+} | {
+    status: "failed";
+    error: string;
+    at: number;
+} | {
+    status: "none";
+};
+export interface CertsOptions {
+    renewBeforeMs?: number;
+    retryAfterMs?: number;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/**
+ * The certificates, one per handle, and the work of getting them.
+ *
+ * The rows are the truth and survive a restart; what is in flight lives in
+ * memory, because nixamp.com is one process and an order interrupted by a
+ * deploy is simply started again when next asked for.
+ */
+export declare class Certs {
+    private readonly db;
+    private readonly zone;
+    private readonly issuer;
+    private ready;
+    private readonly work;
+    private readonly renewBeforeMs;
+    private readonly retryAfterMs;
+    private readonly now;
+    private readonly log;
+    constructor(db: Queryable, zone: DnsZone, issuer: Issuer, options?: CertsOptions);
+    private ensure;
+    /**
+     * The ACME account key, made once and kept. Losing it would not lose any
+     * certificate, but every renewal would register a new account, and Let's
+     * Encrypt rate-limits those too.
+     */
+    accountKey(): Promise<string>;
+    /** The names one handle's certificate covers: every server it has, and the handle itself. */
+    namesFor(handle: string): string[];
+    private stored;
+    /**
+     * A handle's certificate, or what is being done about the lack of one.
+     *
+     * Never blocks on the CA. With nothing stored, or something failed long
+     * enough ago to be worth another go, an order starts in the background and
+     * the answer is "issuing". With one stored that is near its end, the answer
+     * is still the old one -- it is valid -- and a renewal starts alongside.
+     */
+    forHandle(handle: string): Promise<CertState>;
+    /** Order in the background, and remember how it went. */
+    private begin;
+    /** For tests and shutdown: whatever order is in flight for a handle. */
+    settle(handle: string): Promise<void>;
+}

package/dist/certs.js

@@ -0,0 +1,217 @@
+/**
+ * Certificates: one wildcard per handle, issued and renewed by nixamp.com.
+ *
+ * A server that has been given `server2.chovy.nixamp.com` still answers over
+ * plain http until it has a certificate, and getting one by hand is exactly
+ * the manual step this exists to remove. So nixamp.com, which already holds
+ * the zone, does the whole thing: it orders `*.chovy.nixamp.com` and
+ * `chovy.nixamp.com` from Let's Encrypt, answers the DNS-01 challenge by
+ * writing the `_acme-challenge` TXT record itself, keeps the result in the
+ * database, renews it when it gets close to expiry, and hands cert and key
+ * to that account's servers over the authenticated API.
+ *
+ * One wildcard per handle, not one certificate per server. Let's Encrypt
+ * rate-limits per registered domain -- nixamp.com, for all of us -- and every
+ * server an account starts is covered by the wildcard it already has.
+ *
+ * The ACME dance takes minutes, mostly waiting for DNS to propagate, so it is
+ * never done inside a request. `forHandle` starts it in the background and
+ * answers "issuing"; the server asks again in a while.
+ */
+import acme from "acme-client";
+/** A minute is what Porkbun's 600-second floor tends to cost in practice. */
+export const DEFAULT_PROPAGATION_MS = 60_000;
+/** Renew inside the last thirty days, which is what Let's Encrypt recommends. */
+export const RENEW_BEFORE_MS = 30 * 24 * 60 * 60 * 1000;
+/** A failed order is worth trying again, but not every time somebody asks. */
+export const RETRY_AFTER_MS = 60 * 60 * 1000;
+const wait = (ms) => new Promise((done) => setTimeout(done, ms));
+/**
+ * Let's Encrypt, through acme-client, by DNS-01 only: a wildcard cannot be
+ * proved any other way, and the zone is the one thing nixamp.com does hold.
+ */
+export class AcmeIssuer {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async issue(names, challenge) {
+        const [first, ...rest] = names;
+        if (!first)
+            throw new Error("nothing to issue a certificate for");
+        const propagationMs = this.options.propagationMs ?? DEFAULT_PROPAGATION_MS;
+        const sleep = this.options.sleep ?? wait;
+        const client = new acme.Client({
+            directoryUrl: this.options.directoryUrl,
+            accountKey: await this.options.accountKey(),
+        });
+        // A fresh key per certificate. Reusing the account key for the
+        // certificate would make one leak two.
+        const [key, csr] = await acme.crypto.createCsr({ commonName: first, altNames: [first, ...rest] });
+        const cert = await client.auto({
+            csr,
+            email: this.options.email,
+            termsOfServiceAgreed: true,
+            challengePriority: ["dns-01"],
+            // acme-client would otherwise resolve the TXT itself before telling the
+            // CA to, and from wherever nixamp.com runs that lookup can lag the CA's.
+            skipChallengeVerification: true,
+            challengeCreateFn: async (authz, _challenge, keyAuthorization) => {
+                await challenge.set(`_acme-challenge.${authz.identifier.value}`, keyAuthorization);
+                await sleep(propagationMs);
+            },
+            challengeRemoveFn: async (authz, _challenge, keyAuthorization) => {
+                await challenge.clear(`_acme-challenge.${authz.identifier.value}`, keyAuthorization);
+            },
+        });
+        const info = acme.crypto.readCertificateInfo(cert);
+        return { cert, key: key.toString(), expiresAt: info.notAfter.getTime() };
+    }
+}
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS certs (
+    handle      TEXT PRIMARY KEY,
+    cert        TEXT NOT NULL,
+    key         TEXT NOT NULL,
+    expires_at  TIMESTAMPTZ NOT NULL,
+    issued_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+  );
+  CREATE TABLE IF NOT EXISTS acme_account (
+    id       INTEGER PRIMARY KEY,
+    key_pem  TEXT NOT NULL
+  );
+`;
+/**
+ * The certificates, one per handle, and the work of getting them.
+ *
+ * The rows are the truth and survive a restart; what is in flight lives in
+ * memory, because nixamp.com is one process and an order interrupted by a
+ * deploy is simply started again when next asked for.
+ */
+export class Certs {
+    db;
+    zone;
+    issuer;
+    ready = null;
+    work = new Map();
+    renewBeforeMs;
+    retryAfterMs;
+    now;
+    log;
+    constructor(db, zone, issuer, options = {}) {
+        this.db = db;
+        this.zone = zone;
+        this.issuer = issuer;
+        this.renewBeforeMs = options.renewBeforeMs ?? RENEW_BEFORE_MS;
+        this.retryAfterMs = options.retryAfterMs ?? RETRY_AFTER_MS;
+        this.now = options.now ?? Date.now;
+        this.log = options.log ?? (() => undefined);
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    /**
+     * The ACME account key, made once and kept. Losing it would not lose any
+     * certificate, but every renewal would register a new account, and Let's
+     * Encrypt rate-limits those too.
+     */
+    async accountKey() {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT key_pem FROM acme_account WHERE id = 1");
+        const kept = rows[0]?.["key_pem"];
+        if (typeof kept === "string" && kept !== "")
+            return kept;
+        const made = (await acme.crypto.createPrivateKey()).toString();
+        await this.db.query("INSERT INTO acme_account (id, key_pem) VALUES (1, $1) ON CONFLICT (id) DO NOTHING", [made]);
+        // Somebody else may have won the race to insert; theirs is the account now.
+        const again = await this.db.query("SELECT key_pem FROM acme_account WHERE id = 1");
+        const winner = again.rows[0]?.["key_pem"];
+        return typeof winner === "string" && winner !== "" ? winner : made;
+    }
+    /** The names one handle's certificate covers: every server it has, and the handle itself. */
+    namesFor(handle) {
+        return [`*.${handle}.${this.zone.zone}`, `${handle}.${this.zone.zone}`];
+    }
+    async stored(handle) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT cert, key, expires_at FROM certs WHERE handle = $1", [handle]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        const cert = row["cert"];
+        const key = row["key"];
+        const expires = row["expires_at"];
+        if (typeof cert !== "string" || typeof key !== "string")
+            return null;
+        const expiresAt = expires instanceof Date ? expires.getTime() : new Date(String(expires)).getTime();
+        if (!Number.isFinite(expiresAt))
+            return null;
+        return { cert, key, expiresAt };
+    }
+    /**
+     * A handle's certificate, or what is being done about the lack of one.
+     *
+     * Never blocks on the CA. With nothing stored, or something failed long
+     * enough ago to be worth another go, an order starts in the background and
+     * the answer is "issuing". With one stored that is near its end, the answer
+     * is still the old one -- it is valid -- and a renewal starts alongside.
+     */
+    async forHandle(handle) {
+        const kept = await this.stored(handle);
+        const inFlight = this.work.get(handle);
+        if (kept && kept.expiresAt > this.now()) {
+            const renewing = kept.expiresAt - this.now() < this.renewBeforeMs;
+            if (renewing && !(inFlight?.kind === "issuing"))
+                this.begin(handle, "renewal");
+            return {
+                status: "ready",
+                cert: kept.cert,
+                key: kept.key,
+                expiresAt: kept.expiresAt,
+                renewing: renewing || inFlight?.kind === "issuing",
+            };
+        }
+        if (inFlight?.kind === "issuing")
+            return { status: "issuing", since: inFlight.since };
+        if (inFlight?.kind === "failed" && this.now() - inFlight.at < this.retryAfterMs) {
+            return { status: "failed", error: inFlight.error, at: inFlight.at };
+        }
+        const started = this.begin(handle, kept ? "replacement of an expired certificate" : "first certificate");
+        return { status: "issuing", since: started.since };
+    }
+    /** Order in the background, and remember how it went. */
+    begin(handle, why) {
+        const since = this.now();
+        const names = this.namesFor(handle);
+        this.log(`  Ordering a certificate for ${names.join(" and ")} (${why}).`);
+        const done = this.issuer
+            .issue(names, {
+            set: (host, value) => this.zone.add(host, "TXT", value, 600),
+            clear: (host, value) => this.zone.remove(host, "TXT", value),
+        })
+            .then(async (issued) => {
+            await this.ensure();
+            await this.db.query(`INSERT INTO certs (handle, cert, key, expires_at, issued_at) VALUES ($1, $2, $3, $4, now())
+           ON CONFLICT (handle) DO UPDATE SET cert = EXCLUDED.cert, key = EXCLUDED.key,
+             expires_at = EXCLUDED.expires_at, issued_at = now()`, [handle, issued.cert, issued.key, new Date(issued.expiresAt).toISOString()]);
+            const days = Math.max(0, Math.round((issued.expiresAt - this.now()) / (24 * 60 * 60 * 1000)));
+            this.log(`  Certificate for *.${handle}.${this.zone.zone} issued, good for ${days} days.`);
+            this.work.delete(handle);
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            this.log(`  Certificate for *.${handle}.${this.zone.zone} failed: ${message}`);
+            this.work.set(handle, { kind: "failed", error: message, at: this.now() });
+        });
+        const work = { kind: "issuing", since, done };
+        this.work.set(handle, work);
+        return work;
+    }
+    /** For tests and shutdown: whatever order is in flight for a handle. */
+    async settle(handle) {
+        const inFlight = this.work.get(handle);
+        if (inFlight?.kind === "issuing")
+            await inFlight.done;
+    }
+}

package/dist/directory.d.ts

@@ -51,6 +51,14 @@ export interface Listing {
      * an older nixamp that only knows about `url`.
      */
     audio: string;
+    /**
+     * The link that administers the server, as the publisher announced it.
+     *
+     * Kept so the owner can open their own machine as its administrator from
+     * the directory, and handed out to nobody else: the listing route strips it
+     * for anyone but the account that owns the listing.
+     */
+    admin: string;
     tracks: number;
     nowPlaying: string;
     /**
@@ -96,6 +104,8 @@ export interface Announcement {
     url: string;
     /** Where the audio actually is. See `Listing.audio`. */
     audio?: string;
+    /** The admin share link, same origin as `url`. Kept for the owner alone. */
+    admin?: string;
     tracks: number;
     nowPlaying: string;
     /** Absent from an older publisher, which is read as "unknown, say playing". */

package/dist/directory.js

@@ -68,6 +68,10 @@ export function parseAnnouncement(input) {
     const offered = typeof record["audio"] === "string" ? record["audio"] : "";
     const parsed = offered ? publishable(offered) : null;
     const audio = parsed !== null && parsed.origin === listen.origin ? offered : "";
+    // The admin link is held to the same rule: it names this server or nothing.
+    const adminOffered = typeof record["admin"] === "string" ? record["admin"] : "";
+    const adminParsed = adminOffered ? publishable(adminOffered) : null;
+    const admin = adminParsed !== null && adminParsed.origin === listen.origin ? adminOffered : "";
     const name = clean(record["name"], MAX_NAME);
     const tracks = Number(record["tracks"]);
     return {
@@ -75,6 +79,7 @@ export function parseAnnouncement(input) {
         name: name || "a nixamp",
         url,
         ...(audio ? { audio } : {}),
+        ...(admin ? { admin } : {}),
         tracks: Number.isFinite(tracks) && tracks >= 0 ? Math.min(1_000_000, Math.floor(tracks)) : 0,
         nowPlaying: clean(record["nowPlaying"], MAX_TRACK),
         ...(typeof record["playing"] === "boolean" ? { playing: record["playing"] } : {}),
@@ -167,6 +172,7 @@ export class Directory {
             // older publisher renewing an entry should not blank the address the
             // phone line is playing from.
             audio: announcement.audio ?? existing?.audio ?? "",
+            admin: announcement.admin ?? existing?.admin ?? "",
             tracks: announcement.tracks,
             nowPlaying: announcement.nowPlaying,
             // An older publisher says nothing about either; "playing" keeps what a

package/dist/dns.d.ts

@@ -0,0 +1,63 @@
+export type RecordType = "A" | "AAAA" | "TXT";
+export interface DnsRecord {
+    id: string;
+    /** The full hostname, e.g. "server2.chovy.nixamp.com". */
+    host: string;
+    type: RecordType;
+    content: string;
+    ttl: number;
+}
+export interface DnsZone {
+    /** The apex this zone answers for: "nixamp.com". */
+    readonly zone: string;
+    list(host: string, type: RecordType): Promise<DnsRecord[]>;
+    /** Afterwards exactly one record of that host and type exists, with this content. */
+    set(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    /** One more. An ACME order for a wildcard and its apex wants two TXT at once. */
+    add(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    /** All of host and type, or only those whose content matches. */
+    remove(host: string, type: RecordType, content?: string): Promise<void>;
+}
+/** 2026, not 1998: an address is either family, and both are first class. */
+export declare function isIPv4(value: unknown): boolean;
+export declare function isIPv6(value: unknown): boolean;
+/** Porkbun's floor. Anything lower is silently raised, so it is raised here, loudly. */
+export declare const MIN_TTL = 600;
+/**
+ * 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 declare class MemoryZone implements DnsZone {
+    readonly zone: string;
+    readonly records: DnsRecord[];
+    private sequence;
+    constructor(zone: string);
+    list(host: string, type: RecordType): Promise<DnsRecord[]>;
+    set(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    add(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    remove(host: string, type: RecordType, content?: string): Promise<void>;
+}
+/**
+ * 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 declare class Porkbun implements DnsZone {
+    readonly zone: string;
+    private readonly apiKey;
+    private readonly secretApiKey;
+    private readonly send;
+    private readonly base;
+    constructor(zone: string, apiKey: string, secretApiKey: string, send?: typeof fetch, base?: string);
+    /** The part before the zone, or "" for the zone itself. */
+    private sub;
+    private call;
+    list(host: string, type: RecordType): Promise<DnsRecord[]>;
+    add(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    set(host: string, type: RecordType, content: string, ttl?: number): Promise<void>;
+    remove(host: string, type: RecordType, content?: string): Promise<void>;
+}

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>;