nixamp 0.7.41 → 0.9.3

package/dist/session.js

@@ -453,6 +453,109 @@ export async function tokens(argv, fetcher = fetch) {
         return 69;
     }
 }
+/**
+ * `nixamp dns list|set|rm`: names under your handle, for your servers.
+ *
+ * The DNS keys stay on nixamp.com; this only says which label should point
+ * where. "auto" is the address the request arrives from, which is what a
+ * server naming itself wants and what nobody behind a router can type.
+ */
+export async function dns(argv, fetcher = fetch) {
+    const session = readSession();
+    if (session === null) {
+        console.error("nixamp: not signed in. Try `nixamp login`.");
+        return 1;
+    }
+    const [command = "list", ...rest] = argv;
+    const where = `${session.site}/api/v1/dns`;
+    const headers = { authorization: `Bearer ${session.token}`, "content-type": "application/json" };
+    const flag = (name) => {
+        const at = rest.indexOf(name);
+        return at === -1 ? undefined : rest[at + 1];
+    };
+    // "off" is a word a person types; null is what the API takes it to mean.
+    const family = (value) => value === undefined ? undefined : value === "off" || value === "none" ? null : value;
+    try {
+        if (command === "set" || command === "add" || command === "claim") {
+            const label = rest.find((a) => !a.startsWith("-")) ?? "";
+            if (!label) {
+                console.error("nixamp: which name? `nixamp dns set server2` names this machine server2.");
+                return 64;
+            }
+            let a = family(flag("--a"));
+            let aaaa = family(flag("--aaaa"));
+            // Neither named: a server naming itself, both families from where it is.
+            if (a === undefined && aaaa === undefined) {
+                a = "auto";
+                aaaa = "auto";
+            }
+            const ttlText = flag("--ttl");
+            const ttl = ttlText === undefined ? undefined : Number(ttlText);
+            if (ttl !== undefined && (!Number.isInteger(ttl) || ttl < 60)) {
+                console.error("nixamp: --ttl is seconds, 60 or more.");
+                return 64;
+            }
+            const answer = await fetcher(`${where}/${encodeURIComponent(label)}`, {
+                method: "PUT",
+                headers,
+                body: JSON.stringify({
+                    ...(a !== undefined ? { a } : {}),
+                    ...(aaaa !== undefined ? { aaaa } : {}),
+                    ...(ttl !== undefined ? { ttl } : {}),
+                }),
+            });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok || !body.name) {
+                console.error(`nixamp: ${body.error ?? `could not set it (${answer.status})`}`);
+                return 1;
+            }
+            console.log(`${body.name.host}`);
+            console.log(`  A     ${body.name.a || "—"}`);
+            console.log(`  AAAA  ${body.name.aaaa || "—"}`);
+            console.log(`  ttl   ${body.name.ttl}`);
+            return 0;
+        }
+        if (command === "rm" || command === "remove" || command === "delete") {
+            const label = rest.find((a) => !a.startsWith("-")) ?? "";
+            if (!label) {
+                console.error("nixamp: which name? `nixamp dns list` shows them.");
+                return 64;
+            }
+            const answer = await fetcher(`${where}/${encodeURIComponent(label)}`, { method: "DELETE", headers });
+            if (!answer.ok) {
+                const body = (await answer.json().catch(() => ({})));
+                console.error(`nixamp: ${answer.status === 404 ? "no name like that under your handle" : (body.error ?? "could not remove it")}`);
+                return 1;
+            }
+            console.log(`Removed ${label}.`);
+            return 0;
+        }
+        if (command === "list" || command === "ls") {
+            const answer = await fetcher(where, { headers });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok) {
+                console.error(`nixamp: ${body.error ?? `could not list them (${answer.status})`}`);
+                return 1;
+            }
+            const names = body.names ?? [];
+            if (names.length === 0) {
+                console.log("No names yet. `nixamp dns set <name>` gives this machine one.");
+                return 0;
+            }
+            const width = Math.max(...names.map((n) => n.host.length));
+            for (const name of names) {
+                console.log(`${name.host.padEnd(width)}  A ${(name.a || "—").padEnd(15)}  AAAA ${(name.aaaa || "—").padEnd(39)}  ttl ${String(name.ttl).padStart(5)}  ${day(name.updatedAt)}`);
+            }
+            return 0;
+        }
+        console.error(`nixamp: no such dns command: ${command}`);
+        return 64;
+    }
+    catch (error) {
+        console.error(`nixamp: could not reach ${session.site}: ${error.message}`);
+        return 69;
+    }
+}
 export function logout() {
     const session = readSession();
     clearSession();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.7.41",
+  "version": "0.9.3",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,9 @@
   "dependencies": {
     "@profullstack/auth-system": "^0.6.0",
     "@profullstack/hqtui": "^0.3.0",
-    "@profullstack/x402-gateway": "^0.4.0",
+    "@profullstack/throttle": "0.2.2",
+    "@profullstack/x402-gateway": "0.6.0",
+    "acme-client": "5.4.0",
     "pg": "^8.23.0",
     "web-push": "^3.6.7"
   },
@@ -67,5 +69,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/profullstack/nixamp.git"
+  },
+  "overrides": {
+    "https-proxy-agent": "7.0.6",
+    "tslib": "2.8.1"
   }
 }

package/src/certs.ts

@@ -0,0 +1,294 @@
+/**
+ * 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";
+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 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: number): Promise<void> => 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 implements Issuer {
+  constructor(private readonly options: AcmeIssuerOptions) {}
+
+  async issue(names: string[], challenge: Challenge): Promise<Issued> {
+    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() };
+  }
+}
+
+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;
+}
+
+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
+  );
+`;
+
+interface Stored {
+  cert: string;
+  key: string;
+  expiresAt: number;
+}
+
+/** What is happening to a handle's certificate right now, in this process. */
+type Work =
+  | { kind: "issuing"; since: number; done: Promise<void> }
+  | { kind: "failed"; error: string; at: number };
+
+/**
+ * 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 {
+  private ready: Promise<void> | null = null;
+  private readonly work = new Map<string, Work>();
+  private readonly renewBeforeMs: number;
+  private readonly retryAfterMs: number;
+  private readonly now: () => number;
+  private readonly log: (line: string) => void;
+
+  constructor(
+    private readonly db: Queryable,
+    private readonly zone: DnsZone,
+    private readonly issuer: Issuer,
+    options: CertsOptions = {},
+  ) {
+    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);
+  }
+
+  private async ensure(): Promise<void> {
+    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(): Promise<string> {
+    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: string): string[] {
+    return [`*.${handle}.${this.zone.zone}`, `${handle}.${this.zone.zone}`];
+  }
+
+  private async stored(handle: string): Promise<Stored | null> {
+    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: string): Promise<CertState> {
+    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. */
+  private begin(handle: string, why: string): { since: number } {
+    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: unknown) => {
+        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: 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: string): Promise<void> {
+    const inFlight = this.work.get(handle);
+    if (inFlight?.kind === "issuing") await inFlight.done;
+  }
+}

package/src/channels.ts

@@ -64,6 +64,8 @@ export const GIVE_UP = 5;
  * channel that is quiet for half a minute is not being quiet, it is dead.
  */
 export const STALL = 30_000;
+/** How long an on-demand channel stays up with nobody watching. */
+export const IDLE = 60_000;
 /** How much of what ffmpeg said to keep, for the last line when it dies. */
 const TAIL = 2000;
 /**
@@ -116,6 +118,8 @@ export interface ChannelOptions {
   ffmpeg: string[];
   onStart?: (info: ChannelInfo) => void;
   onEnd?: (info: ChannelInfo) => void;
+  /** How long an on-demand channel outlives its last viewer. Tests shorten it. */
+  idleMs?: number;
 }
 
 /**
@@ -151,6 +155,13 @@ export class Channel {
    */
   private recent: Buffer[] = [];
   private recentBytes = 0;
+  /**
+   * Started for whoever asked and stopped when nobody is left. A catalog
+   * channel is one of thousands; keeping every one that was ever clicked
+   * running would be a decoder per click, for ever.
+   */
+  ephemeral = false;
+  private idle: ReturnType<typeof setTimeout> | null = null;
 
   constructor(
     readonly info: ChannelInfo,
@@ -466,12 +477,25 @@ export class Channel {
     }
     this.listeners.add(listener);
     this.info.listeners = this.listeners.size;
+    if (this.idle) clearTimeout(this.idle);
+    this.idle = null;
     return () => {
       this.listeners.delete(listener);
       this.info.listeners = this.listeners.size;
+      if (this.ephemeral && this.listeners.size === 0) this.idleOut();
     };
   }
 
+  /** Nobody is watching an on-demand channel: give it a minute, then stop. */
+  private idleOut(): void {
+    if (this.idle) clearTimeout(this.idle);
+    this.idle = setTimeout(() => {
+      this.idle = null;
+      if (this.ephemeral && this.listeners.size === 0) this.close();
+    }, this.options.idleMs ?? IDLE);
+    this.idle.unref?.();
+  }
+
   close(): void {
     if (this.closing) return;
     this.closing = true;
@@ -480,6 +504,8 @@ export class Channel {
     this.timer = null;
     if (this.watchdog) clearTimeout(this.watchdog);
     this.watchdog = null;
+    if (this.idle) clearTimeout(this.idle);
+    this.idle = null;
     const said = lastLine(this.stderr);
     if (said && !this.info.error) this.info.error = said;
     const child = this.child;
@@ -615,6 +641,21 @@ export class Channels {
     return this.open.get(id)?.info.via === "pull";
   }
 
+  /** Mark a channel as on demand: it stops itself a minute after its last viewer leaves. */
+  ephemeral(id: string): void {
+    const channel = this.open.get(id);
+    if (!channel) return;
+    channel.ephemeral = true;
+    if (channel.listeners.size === 0) channel.listen({ write: () => true, end: () => undefined })();
+  }
+
+  /** How many on-demand channels are up, for a ceiling on decoders. */
+  get ephemeralCount(): number {
+    let total = 0;
+    for (const channel of this.open.values()) if (channel.ephemeral) total += 1;
+    return total;
+  }
+
   /** What a listener should be told this channel is. */
   contentType(id: string): string {
     return this.open.get(id)?.info.kind === "video" ? "video/mp4" : "audio/mpeg";

package/src/directory.ts

@@ -55,6 +55,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;
   /**
@@ -103,6 +111,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". */
@@ -160,6 +170,10 @@ export function parseAnnouncement(input: unknown): Announcement | null {
   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"]);
@@ -168,6 +182,7 @@ export function parseAnnouncement(input: unknown): Announcement | null {
     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"] } : {}),
@@ -261,6 +276,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