nixamp 0.1.0 → 0.2.0

package/src/share.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 type { IncomingMessage } from "node:http";
+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(): string {
+  return randomBytes(16).toString("base64url");
+}
+
+/** Compare without leaking where two keys first differ. */
+export function keysMatch(a: string, b: string): boolean {
+  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: IncomingMessage, url: URL): string | null {
+  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: string): string {
+  // 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: string): "private" | "cgnat" | "public" {
+  const [a, b] = address.split(".").map(Number) as [number, 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: string, port: number): { label: string; url: string }[] {
+  const link = (address: string): string => {
+    // 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" } as const;
+  const found: { label: string; url: string; kind: keyof typeof LABELS }[] = [];
+  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 } as const;
+  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: string, key: string | null): string {
+  return key === null ? base : `${base}/s/${key}`;
+}
+
+/** 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 function firewallInUse(io: Runner): Firewall | null {
+  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: Firewall, port: number): { open: string[]; close: string[] } {
+  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: Runner, command: string[]): string[] | null {
+  const [head, ...rest] = command as [string, ...string[]];
+  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;
+}

package/src/sources.ts

@@ -0,0 +1,136 @@
+/**
+ * Where a playlist comes from.
+ *
+ * A directory, a file, an .m3u, or a URL to any of those. ffmpeg reads a URL as
+ * happily as a path, so a remote track needs no special case once it is in the
+ * list; what needs care is telling the four apart, and telling an .m3u that
+ * lists tracks from an HLS playlist that *is* one track.
+ */
+
+/** http and https only. ffmpeg speaks more, but these are what a link is. */
+export function isRemote(source: string): boolean {
+  return /^https?:\/\//i.test(source);
+}
+
+export function isPlaylistFile(source: string): boolean {
+  const path = isRemote(source) ? new URL(source).pathname : source;
+  return /\.(m3u|m3u8|pls)$/i.test(path);
+}
+
+/**
+ * An HLS playlist describes one stream in segments; an .m3u describes a list of
+ * things to play. Both are "m3u8" on disk, and the tags are the only honest way
+ * to tell them apart. Expanding an HLS playlist into a track per segment would
+ * turn one song into four hundred.
+ */
+export function isHls(text: string): boolean {
+  return /^#EXT-X-(?:STREAM-INF|TARGETDURATION|MEDIA-SEQUENCE|PLAYLIST-TYPE|ENDLIST)/im.test(text);
+}
+
+export interface Entry {
+  /** A path or a URL, whichever the playlist gave us. */
+  source: string;
+  title: string;
+  /** Seconds, from #EXTINF. Zero when it did not say, and for live. */
+  duration: number;
+}
+
+/** Resolve a playlist line against the playlist's own location. */
+export function resolveEntry(base: string, entry: string): string {
+  if (isRemote(entry)) return entry;
+  if (isRemote(base)) return new URL(entry, base).toString();
+  if (entry.startsWith("/")) return entry;
+  const dir = base.slice(0, Math.max(0, base.lastIndexOf("/")));
+  return dir ? `${dir}/${entry}` : entry;
+}
+
+/**
+ * Parse an .m3u or .m3u8. `#EXTINF:<seconds>,<title>` decorates the line after
+ * it; everything else beginning with # is a comment or a tag we do not need.
+ */
+export function parseM3u(text: string, base: string): Entry[] {
+  const out: Entry[] = [];
+  let duration = 0;
+  let title = "";
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "") continue;
+
+    if (line.startsWith("#")) {
+      const info = /^#EXTINF:\s*(-?[\d.]+)\s*(?:,(.*))?$/i.exec(line);
+      if (info) {
+        const seconds = Number(info[1]);
+        // -1 is the conventional "unknown", which is also what live means.
+        duration = Number.isFinite(seconds) && seconds > 0 ? seconds : 0;
+        title = (info[2] ?? "").trim();
+      }
+      continue;
+    }
+
+    const source = resolveEntry(base, line);
+    out.push({ source, duration, title: title || nameOf(source) });
+    duration = 0;
+    title = "";
+  }
+  return out;
+}
+
+/** A .pls, which Shoutcast and Icecast hand out as often as an .m3u. */
+export function parsePls(text: string, base: string): Entry[] {
+  const files = new Map<string, string>();
+  const titles = new Map<string, string>();
+  const lengths = new Map<string, number>();
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    const match = /^(File|Title|Length)(\d+)\s*=\s*(.*)$/i.exec(line);
+    if (!match) continue;
+    const [, kind, index, value] = match as unknown as [string, string, string, string];
+    if (/^file$/i.test(kind)) files.set(index, value);
+    else if (/^title$/i.test(kind)) titles.set(index, value);
+    else lengths.set(index, Number(value));
+  }
+
+  return [...files.entries()]
+    .sort((a, b) => Number(a[0]) - Number(b[0]))
+    .map(([index, file]) => {
+      const source = resolveEntry(base, file);
+      const seconds = lengths.get(index) ?? 0;
+      return {
+        source,
+        title: titles.get(index)?.trim() || nameOf(source),
+        duration: Number.isFinite(seconds) && seconds > 0 ? seconds : 0,
+      };
+    });
+}
+
+/** The last useful part of a path or URL, for when nothing named the track. */
+export function nameOf(source: string): string {
+  const remote = isRemote(source);
+  const path = remote ? new URL(source).pathname : source;
+  const last = path.split("/").filter(Boolean).pop() ?? source;
+  // Percent-decoding is a URL's business. A file on disk called
+  // `Some%20Song.mp3` is called exactly that, and renaming it in the display
+  // would be a lie about what is in the directory.
+  if (!remote) return last || source;
+  try {
+    return decodeURIComponent(last) || source;
+  } catch {
+    return last || source;
+  }
+}
+
+/**
+ * Formats a browser will play as-is. Anything else gets transcoded on the way
+ * out, which is the difference between a library that plays on a phone and one
+ * that plays on the machine it lives on.
+ */
+const WEB_READY = new Set([".mp3", ".m4a", ".aac", ".ogg", ".oga", ".opus", ".webm", ".mp4", ".wav"]);
+
+export function playsInBrowser(source: string): boolean {
+  if (isRemote(source)) return false;
+  const path = source.toLowerCase();
+  const dot = path.lastIndexOf(".");
+  return dot > 0 && WEB_READY.has(path.slice(dot));
+}

package/web/dist/install.ps1

@@ -0,0 +1,214 @@
+<#
+.SYNOPSIS
+  nixamp installer for Windows.
+
+.DESCRIPTION
+  irm https://nixamp.com/install.ps1 | iex
+
+  Installs the app and the CLI under %LOCALAPPDATA%\nixamp. No administrator
+  rights, no registry, nothing outside your profile. The CLI runs on the Node
+  inside the app bundle, so no system Node is needed.
+
+  Updating is `nixamp update` and removing is `nixamp uninstall`, which runs a
+  script this installer leaves behind.
+
+.PARAMETER CliOnly
+  Never install the app. The CLI then needs Node 24 or newer on PATH.
+
+.PARAMETER Version
+  Install a specific release instead of the latest.
+
+.PARAMETER Prefix
+  Install root. Defaults to $env:LOCALAPPDATA\nixamp.
+
+.EXAMPLE
+  & ([scriptblock]::Create((irm https://nixamp.com/install.ps1))) -CliOnly
+#>
+[CmdletBinding()]
+param(
+  [switch]$CliOnly,
+  [string]$Version = $env:NIXAMP_VERSION,
+  [string]$Prefix = $(if ($env:NIXAMP_PREFIX) { $env:NIXAMP_PREFIX } else { Join-Path $env:LOCALAPPDATA 'nixamp' })
+)
+
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+
+$Repo = 'profullstack/nixamp'
+$Site = if ($env:NIXAMP_SITE) { $env:NIXAMP_SITE } else { 'https://nixamp.com' }
+
+function Fail($message) {
+  Write-Error "nixamp: $message"
+  exit 1
+}
+
+# arm64 Windows exists and Electron ships for it, so do not assume x64.
+$Arch = switch ($env:PROCESSOR_ARCHITECTURE) {
+  'AMD64' { 'x64' }
+  'ARM64' { 'arm64' }
+  'x86'   { Fail 'nixamp does not ship a 32-bit build.' }
+  default { 'x64' }
+}
+
+if (-not $Version) {
+  try {
+    $latest = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest"
+    $Version = $latest.tag_name -replace '^v', ''
+  } catch {
+    Fail "could not determine the latest version. Pass -Version, or see $Site"
+  }
+}
+
+$Base = if ($env:NIXAMP_RELEASE_BASE) {
+  $env:NIXAMP_RELEASE_BASE
+} else {
+  "https://github.com/$Repo/releases/download/v$Version"
+}
+
+$Bin = Join-Path $Prefix 'bin'
+$Share = Join-Path $Prefix 'share'
+
+Write-Host "nixamp $Version"
+Write-Host "  platform:  windows-$Arch"
+Write-Host "  desktop:   $(if ($CliOnly) { 'no' } else { 'yes' })"
+Write-Host "  prefix:    $Prefix"
+Write-Host ""
+
+$work = Join-Path ([System.IO.Path]::GetTempPath()) ("nixamp-" + [guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Force -Path $work, $Bin, $Share | Out-Null
+
+$paths = New-Object System.Collections.Generic.List[string]
+$paths.Add((Join-Path $Bin 'nixamp.cmd'))
+$paths.Add($Share)
+$method = 'cli-tarball'
+$appDir = Join-Path $Share 'app'
+$cliDir = $null
+$runtime = $null
+
+# --- the app ------------------------------------------------------------------
+
+if (-not $CliOnly) {
+  $asset = "nixamp-$Version-win-$Arch.zip"
+  Write-Host 'Downloading the app...'
+  try {
+    Invoke-WebRequest "$Base/$asset" -OutFile (Join-Path $work 'app.zip')
+    if (Test-Path $appDir) { Remove-Item -Recurse -Force $appDir }
+    New-Item -ItemType Directory -Force -Path $appDir | Out-Null
+    Expand-Archive -Path (Join-Path $work 'app.zip') -DestinationPath $appDir -Force
+    $method = 'windows-app'
+    $cliDir = Join-Path $appDir 'resources\cli'
+    $runtime = Join-Path $appDir 'nixamp.exe'
+
+    # A Start menu shortcut, which is what the NSIS installer would give you,
+    # done without touching anything outside the profile.
+    $menu = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\nixamp.lnk'
+    $shell = New-Object -ComObject WScript.Shell
+    $link = $shell.CreateShortcut($menu)
+    $link.TargetPath = $runtime
+    $link.WorkingDirectory = $appDir
+    $link.Description = "It really whips the terminal's ass."
+    $link.Save()
+    $paths.Add($menu)
+  } catch {
+    Write-Host "  the app could not be installed ($($_.Exception.Message)); installing the CLI only."
+    $CliOnly = $true
+    $method = 'cli-tarball'
+  }
+}
+
+# --- the CLI ------------------------------------------------------------------
+
+if ($method -eq 'cli-tarball') {
+  # Pure JavaScript, so one bundle runs everywhere a Node does.
+  $asset = "nixamp-cli-$Version.tar.gz"
+  Write-Host 'Downloading the CLI...'
+  $tarball = Join-Path $work 'cli.tar.gz'
+  try {
+    Invoke-WebRequest "$Base/$asset" -OutFile $tarball
+  } catch {
+    Fail "could not download $Base/$asset"
+  }
+
+  $cliDir = Join-Path $Share 'cli'
+  if (Test-Path $cliDir) { Remove-Item -Recurse -Force $cliDir }
+  New-Item -ItemType Directory -Force -Path $cliDir | Out-Null
+  # bsdtar has shipped in Windows since 1809 and reads gzip, so there is no
+  # third-party unpacker to ask for.
+  tar -xzf $tarball -C $cliDir --strip-components=1
+  if ($LASTEXITCODE -ne 0) { Fail 'could not unpack the CLI.' }
+
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Host '  note: no app was installed, so the CLI needs Node 24 or newer. It was not found.'
+  }
+}
+
+# The shim, written here because only the installer knows which of the two
+# runtimes this machine ended up with.
+$entry = Join-Path $cliDir 'bin\nixamp.mjs'
+$shim = Join-Path $Bin 'nixamp.cmd'
+if ($runtime) {
+  @"
+@echo off
+rem nixamp. Runs on the Node inside the app, so no system Node is required.
+rem Written by the installer; ``nixamp uninstall`` removes it.
+set NIXAMP_HOME=$Share
+set ELECTRON_RUN_AS_NODE=1
+"$runtime" "$entry" %*
+"@ | Set-Content -Path $shim -Encoding ASCII
+} else {
+  @"
+@echo off
+rem nixamp. Written by the installer; ``nixamp uninstall`` removes it.
+set NIXAMP_HOME=$Share
+node "$entry" %*
+"@ | Set-Content -Path $shim -Encoding ASCII
+}
+
+# --- what was installed, and how to remove it ---------------------------------
+
+$manifest = [ordered]@{
+  version     = $Version
+  method      = $method
+  installer   = "$Site/install.ps1"
+  installedAt = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+  prefix      = $Prefix
+  desktop     = ($method -eq 'windows-app')
+  paths       = $paths.ToArray()
+}
+$manifest | ConvertTo-Json | Set-Content -Path (Join-Path $Share 'manifest.json') -Encoding UTF8
+
+$removals = ($paths | ForEach-Object { "Remove-Item -Recurse -Force -ErrorAction SilentlyContinue '$_'" }) -join "`n"
+@"
+# Removes nixamp. Written by the installer, which knew exactly what it created.
+# Your music is NOT touched.
+$removals
+Write-Host 'nixamp removed.'
+"@ | Set-Content -Path (Join-Path $Share 'uninstall.ps1') -Encoding UTF8
+
+Remove-Item -Recurse -Force $work -ErrorAction SilentlyContinue
+
+# --- PATH ---------------------------------------------------------------------
+
+$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+if ($userPath -notlike "*$Bin*") {
+  [Environment]::SetEnvironmentVariable('Path', "$userPath;$Bin", 'User')
+  Write-Host ""
+  Write-Host "Added $Bin to your PATH. Open a new terminal for it to take effect."
+}
+
+Write-Host ""
+Write-Host "Installed nixamp $Version"
+Write-Host "  $(if ($method -eq 'windows-app') { 'app and CLI' } else { 'CLI only' })"
+
+# ffmpeg decodes every track. Saying so now beats a confusing failure on first
+# use, when the playlist loads and nothing comes out of the speakers.
+if (-not (Get-Command ffmpeg -ErrorAction SilentlyContinue)) {
+  Write-Host ""
+  Write-Host '  ffmpeg was not found, and nixamp decodes with ffmpeg.'
+  Write-Host '  winget install Gyan.FFmpeg'
+}
+
+Write-Host ""
+Write-Host 'Try:  nixamp %USERPROFILE%\Music'
+Write-Host 'Update with `nixamp update`, remove with `nixamp uninstall`.'
+Write-Host "Docs: $Site"

package/web/dist/sw.js

@@ -1,5 +1,5 @@
 /* nixamp service worker — generated, do not edit */
-const CACHE = "nixamp-1788892198880";
+const CACHE = "nixamp-1788894378334";
 const PRECACHE = [
   "/",
   "/apple-touch-icon.png",