nixamp 0.1.0 → 0.3.0

package/README.md

@@ -48,6 +48,18 @@ curl -fsSL https://nixamp.com/install.sh | sh -s -- --version 0.1.0
 curl -fsSL https://nixamp.com/install.sh | sh -s -- --prefix ~/opt
 ```
 
+On Windows, in PowerShell:
+
+```
+irm https://nixamp.com/install.ps1 | iex
+```
+
+That lands under `%LOCALAPPDATA%\nixamp`, adds itself to your user PATH, and
+needs no administrator rights. Nothing is code signed, so SmartScreen will warn
+the first time.
+
+Builds are published for Linux, macOS and Windows, on both x64 and arm64.
+
 Then:
 
 ```
@@ -63,6 +75,219 @@ network. Your music is never touched.
 If you would rather not pipe a script into a shell, `npm i -g nixamp` and
 `bunx nixamp ~/Music` both work; that route needs Node 24 or newer.
 
+## Signing in
+
+An account on nixamp.com is what lets you publish, be paid, and administer a
+server you own. Email and password, on every surface:
+
+```
+nixamp login              # or: nixamp signup
+nixamp whoami
+nixamp logout
+```
+
+The PWA and the desktop app share one form, since the desktop is that page in a
+window. The CLI keeps its token beside the daemon's state, mode 600, so signing
+in there and in the desktop app are the same thing on disk. The password is read
+with the echo off and is never written down.
+
+No magic link. A link in an inbox is no use on a television, or on a phone that
+is not the one you read mail on.
+
+Running the account side of nixamp.com needs Postgres:
+
+```
+DATABASE_URL=postgres://user:pass@host/nixamp NIXAMP_JWT_SECRET=… nixamp serve --directory
+```
+
+Accounts live where the directory lives and nowhere else: a nixamp on a laptop
+has nobody to be an account of.
+
+## The directory
+
+[nixamp.com/directory](https://nixamp.com/directory) lists nixamps that agreed
+to be listed. In the PWA, **Browse the directory** next to the address field
+picks one without typing anything.
+
+`nixamp serve` asks before listing you, and shows the exact link it would
+publish:
+
+```
+  List this stream at https://nixamp.com/directory so anyone can find it?
+  It publishes http://198.51.100.7:4321/s/Lk1EM_mP977e1VT — listen only,
+  not the controls. [Y/n]
+```
+
+Yes is the default; `--publish` and `--no-publish` skip the question, `--name`
+sets what it is called. A terminal that cannot ask never publishes, because
+nobody being there to answer is not consent.
+
+What gets published is a **listen-only** link. Every server mints two keys: the
+one in your own share link drives the player, and the listen key can hear it
+and nothing else. `/api/command` and `/api/source` answer 403 to a listen key,
+so a stranger in the directory cannot pause your music or point your machine at
+something else.
+
+Entries expire a few minutes after a stream stops renewing, so the list is
+always what is actually live.
+
+## Several streams at once
+
+A channel is one publisher and everybody listening to them. Two or three devices
+can be live at the same time -- a phone, a desktop, a second window -- each with
+its own audience.
+
+```
+GET  /api/channels              what is live now
+POST /api/channels/<id>         publish to one
+GET  /api/channels/<id>         listen to one
+```
+
+One ffmpeg decodes each publisher once and the result is written to every
+listener on that channel. A decode per listener would cost a core each and, for
+a live stream, would not even agree with itself about what "now" is.
+
+A listener who joins halfway through gets the stream from that moment, which is
+what live means. Two publishers on **one** channel is refused; on two channels it
+is the whole point.
+
+Publishing is administering the server, so it needs the control link or the
+owner's account. Listening only needs the share link, like any other audio.
+
+## Streaming into it
+
+A nixamp can be the thing you broadcast *to*, not just from.
+
+```
+nixamp serve ~/Music --rtmp-in 1935
+```
+
+Then point OBS, Larix, or another ffmpeg at the URL it prints. RTMP is what
+every native broadcaster already speaks, so there is no nixamp-shaped client to
+install. ffmpeg does the listening, so this costs no extra dependency.
+
+A browser cannot speak RTMP at all, so the web app uses HTTP instead: one long
+`POST /api/ingest` where the platform allows a streaming request body, and
+`POST /api/ingest/chunk` where it does not. All three end up in the same place.
+
+One publisher at a time. A second is refused rather than mixed.
+
+## Broadcasting out
+
+Out to as many places as you like, at once:
+
+```
+nixamp serve ~/Music --rtmp youtube=<key> --rtmp x=<key> --rtmp tiktok=<key>
+```
+
+`youtube`, `x`, `facebook`, `tiktok`, `twitch` and `kick` are known by name and
+need only a key; anything else takes a full `rtmp://host/app/key`.
+
+One ffmpeg, one encode, many outputs, through the `tee` muxer. An ffmpeg per
+destination is the obvious shape and it encodes the same frames four times.
+Every output carries `onfail=ignore`, so one destination with an expired key
+cannot take the others down with it.
+
+The encoder settings come from PairUX, which learned them against the real
+platforms: a one-second keyframe interval because YouTube stalls on ffmpeg's
+default, a forced constant frame rate because a variable-rate source makes
+YouTube report a stream falling behind, and `yuv420p` because that is what RTMP
+platforms accept. Music has no picture, so a flat colour is generated: RTMP
+wants a video track either way.
+
+Stream keys are read from the command line or the environment and never from a
+request. `/api/broadcast/destinations` shows names and URLs with the keys
+redacted.
+
+## Paying to listen
+
+A stream serving a handful of friends costs nothing and asks nothing. Past five
+people listening at once it is bandwidth somebody is paying for, so the gate
+opens: the sixth listener gets a 402 with an
+[x402](https://github.com/profullstack/x402-gateway) offer, and a dollar buys a
+day.
+
+```
+NIXAMP_PAY_TO=0xYourAddress COINPAY_X402_KEY=cp_live_… nixamp serve ~/Music --x402
+```
+
+Three things are deliberate. The count is of *live* listeners, so a stream
+quietens back to free on its own. Only the audio is gated: a 402 on `/api/state`
+would break the page that has to render the offer. And nobody is cut off
+mid-track, because the gate is asked once, when a request arrives.
+
+`NIXAMP_PRICE_CENTS` and `NIXAMP_PASS_MINUTES` change the terms; the defaults are
+100 and 1440, which is the dollar and the day. A server that has agreed to be in
+the directory can also be switched on and off from nixamp.com: the configuration
+rides back on the heartbeat it is already sending.
+
+## Leaving it running
+
+`nixamp serve` holds a terminal. `nixamp daemon` does not.
+
+```
+nixamp daemon start ~/Music --open-port
+nixamp daemon status
+nixamp daemon stop
+```
+
+Start writes down where it went and the key it minted, waits until the server
+is actually answering before saying it started, and prints the share link. It is
+one daemon per user, and the state lives in `$XDG_STATE_HOME/nixamp`.
+
+## Who may administer a server
+
+Two ways to be allowed, and they answer different questions.
+
+**You hold its control link.** That is possession: you are at the machine, or
+somebody at it sent you the link. It works with no account and no network.
+
+**You own it.** `nixamp login` and then `nixamp serve` claims the server for the
+account signed in on that machine, and from then on that account can administer
+it from a phone anywhere, by signing in to nixamp.com in the browser.
+
+The server cannot check a nixamp.com token itself, and should not: it holds no
+part of that secret. It asks nixamp.com who the token belongs to and compares
+the answer to the owner it recorded at startup. Delegating identity while
+keeping authorisation local is what lets a nixamp on a laptop trust an account
+it has never seen.
+
+Answers are remembered for a minute, so admin requests do not each cost a round
+trip, and a revoked session stops working in about a minute rather than at the
+next restart. If nixamp.com cannot be reached, nobody becomes the owner — the
+control link is the way in until it can.
+
+Listening is never affected: `/api/state`, `/api/stream` and the page itself
+stay open to whoever has the share link.
+
+## Watching it
+
+```
+nixamp admin
+```
+
+Who is connected, from where, to what, for how long and how much has gone out.
+It reads the daemon's own state file, so it needs no arguments; point it
+anywhere else with `--url` and `--key`.
+
+```
+╭─ Server ─────────────────────────╮ ╭─ Now playing ────────────────────╮
+│ http://127.0.0.1:4321            │ │ long.flac                        │
+│ /home/anthony/Music              │ │ —                                │
+│ Uptime                        3s │ │ State                    stopped │
+│ Tracks                         1 │ │ Position                      0s │
+│ Listeners                      2 │ │                                  │
+╰──────────────────────────────────╯ ╰──────────────────────────────────╯
+╭─ Connections (2 live) ────────────────────────────────────────────────╮
+│ Where        Network   Kind    Client    Track          For      Sent │
+│ 10.0.0.42    private   media   VLC 3     long.flac       3s   2.6 MiB │
+│ 100.65.1.7   tailscale stream  Safari 17 long.flac      41s    18 MiB │
+╰───────────────────────────────────────────────────────────────────────╯
+```
+
+Press `r` to re-stream: hand the running server a different URL or path and the
+listeners stay connected while what they are hearing changes under them.
+
 ## How it works
 
 One decode feeds both your speakers and the display. `ffmpeg` writes raw 32-bit float samples to a pipe; nixamp reads every sample on its way past, runs an FFT over it, and hands the same bytes to `ffplay`.

package/bin/nixamp.mjs

@@ -2,6 +2,9 @@
 import { main } from "../dist/main.js";
 
 main().catch((error) => {
-  console.error(error);
+  // A message we wrote is a message the user can act on; anything else is a
+  // bug and deserves its stack.
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message.startsWith("nixamp:") ? message : error);
   process.exit(1);
 });

package/dist/accounts.d.ts

@@ -0,0 +1,54 @@
+export interface Account {
+    id: string;
+    email: string;
+}
+export interface AuthResult {
+    ok: boolean;
+    account: Account | null;
+    token: string;
+    /** Safe to show a stranger: it never says whether an address is registered. */
+    error: string;
+}
+export interface AccountsOptions {
+    /** postgres://user:pass@host/db */
+    connectionString: string;
+    /** Signing secret. Without one, every session dies on restart. */
+    secret: string;
+    /** Injected by the tests, which have no database. */
+    system?: AuthLike;
+}
+/** The slice of the auth system nixamp uses. */
+export interface AuthLike {
+    register(input: {
+        email: string;
+        password: string;
+        autoVerify?: boolean;
+    }): Promise<unknown>;
+    login(input: {
+        email: string;
+        password: string;
+    }): Promise<unknown>;
+    validateToken(token: string): Promise<unknown>;
+}
+/** Pull an account and a token out of whatever shape the module returned. */
+export declare function readResult(value: unknown): AuthResult;
+/** `validateToken` answers claims directly, unlike login and register. */
+export declare function readClaims(value: unknown): Account | null;
+/** An address that could exist, and a password long enough to be worth having. */
+export declare function checkCredentials(email: unknown, password: unknown): string;
+export declare class Accounts {
+    private readonly system;
+    constructor(options: AccountsOptions);
+    signUp(email: unknown, password: unknown): Promise<AuthResult>;
+    signIn(email: unknown, password: unknown): Promise<AuthResult>;
+    whoIs(token: string): Promise<Account | null>;
+}
+/** The bearer token on a request, from the header or the session cookie. */
+export declare function tokenFrom(headers: Record<string, string | string[] | undefined>): string;
+/**
+ * The session cookie. HttpOnly because nothing in the page reads it -- the
+ * browser attaches it by itself -- and Secure only where the page was served
+ * over https, since a nixamp on your own network is plain http.
+ */
+export declare function sessionCookie(token: string, secure: boolean): string;
+export declare function clearedCookie(): string;

package/dist/accounts.js

@@ -0,0 +1,160 @@
+/**
+ * Accounts on nixamp.com.
+ *
+ * The house auth module does the work: password and JWT, over the Postgres
+ * adapter. This is the shape nixamp needs around it, and the two things the
+ * module gets wrong from a caller's point of view:
+ *
+ * - `login()` and `register()` THROW on a bad password or a taken address
+ *   rather than resolving `{ success: false }`, so a bare `if (!result.success)`
+ *   never runs. Everything here answers a result instead.
+ * - `validateToken()` resolves to the claims directly, not to a wrapper like
+ *   the other two, so the shapes differ between calls.
+ * - `register()` without `autoVerify` creates an account that `login()` will
+ *   refuse for ever, and returns no tokens. nixamp sends no email, so there
+ *   would be nothing to click.
+ *
+ * No magic link: a link in an inbox is no use on a television or a phone that
+ * is not the one you read mail on.
+ */
+import { createAuthSystem, PostgresAdapter } from "@profullstack/auth-system";
+const NO_ACCOUNT = { ok: false, account: null, token: "", error: "" };
+/**
+ * The same sentence for a wrong password and an address with no account.
+ * Saying which is how an endpoint tells a stranger who has registered.
+ */
+const REFUSED = "that email and password do not match an account";
+/** Pull an account and a token out of whatever shape the module returned. */
+export function readResult(value) {
+    const record = (value ?? {});
+    const user = (record["user"] ?? {});
+    const tokens = (record["tokens"] ?? {});
+    const id = typeof user["id"] === "string" ? user["id"] : "";
+    const email = typeof user["email"] === "string" ? user["email"] : "";
+    const token = typeof tokens["accessToken"] === "string" ? tokens["accessToken"] : "";
+    if (!id || !token)
+        return { ...NO_ACCOUNT, error: REFUSED };
+    return { ok: true, account: { id, email }, token, error: "" };
+}
+/** `validateToken` answers claims directly, unlike login and register. */
+export function readClaims(value) {
+    const claims = (value ?? {});
+    const id = typeof claims["userId"] === "string" ? claims["userId"] : "";
+    const email = typeof claims["email"] === "string" ? claims["email"] : "";
+    return id ? { id, email } : null;
+}
+/** An address that could exist, and a password long enough to be worth having. */
+export function checkCredentials(email, password) {
+    if (typeof email !== "string" || !/^[^@\s]+@[^@\s.]+\.[^@\s]+$/.test(email)) {
+        return "that does not look like an email address";
+    }
+    if (typeof password !== "string" || password.length < 10) {
+        // Length is checked here so a hopeless password never reaches the
+        // database. The auth module then applies its own composition rules on top,
+        // and its refusals are passed through rather than swallowed.
+        return "a password needs at least 10 characters";
+    }
+    if (password.length > 200)
+        return "that password is too long";
+    return "";
+}
+export class Accounts {
+    system;
+    constructor(options) {
+        this.system =
+            options.system ??
+                createAuthSystem({
+                    adapter: new PostgresAdapter({ connectionString: options.connectionString }),
+                    jwtSecret: options.secret,
+                });
+    }
+    async signUp(email, password) {
+        const wrong = checkCredentials(email, password);
+        if (wrong)
+            return { ...NO_ACCOUNT, error: wrong };
+        try {
+            // autoVerify does two things, and both are necessary here: without it
+            // the account is created unverified and login() refuses it forever --
+            // nixamp sends no email, so there is nothing to click -- and register()
+            // returns no tokens, so signing up would not sign you in.
+            return readResult(await this.system.register({
+                email: email,
+                password: password,
+                autoVerify: true,
+            }));
+        }
+        catch (error) {
+            const message = error.message ?? "";
+            // "already exists" is the one case worth naming: a sign-up form that
+            // will not say why is a sign-up form people give up on. It reveals
+            // nothing that trying to sign up does not reveal anyway.
+            if (/exist|taken|duplicate/i.test(message)) {
+                return { ...NO_ACCOUNT, error: "there is already an account with that email" };
+            }
+            // The module has its own password rules -- an uppercase letter, and so
+            // on -- and refuses with a sentence saying which. Hiding that behind
+            // "could not create that account" leaves someone retyping a password
+            // that will never be accepted.
+            const complaint = /^Invalid (?:password|email)[:\s]+(.*)$/i.exec(message);
+            if (complaint?.[1])
+                return { ...NO_ACCOUNT, error: complaint[1].trim().toLowerCase() };
+            return { ...NO_ACCOUNT, error: "could not create that account" };
+        }
+    }
+    async signIn(email, password) {
+        if (checkCredentials(email, password))
+            return { ...NO_ACCOUNT, error: REFUSED };
+        try {
+            return readResult(await this.system.login({ email: email, password: password }));
+        }
+        catch {
+            // login() throws on bad credentials, so this is the ordinary path.
+            return { ...NO_ACCOUNT, error: REFUSED };
+        }
+    }
+    async whoIs(token) {
+        if (!token)
+            return null;
+        try {
+            return readClaims(await this.system.validateToken(token));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** The bearer token on a request, from the header or the session cookie. */
+export function tokenFrom(headers) {
+    const authorization = headers["authorization"];
+    const header = Array.isArray(authorization) ? authorization[0] : authorization;
+    const bearer = /^Bearer\s+(.+)$/i.exec(header ?? "")?.[1];
+    if (bearer)
+        return bearer.trim();
+    const cookie = Array.isArray(headers["cookie"]) ? headers["cookie"][0] : headers["cookie"];
+    for (const part of (cookie ?? "").split(";")) {
+        const [name, ...rest] = part.trim().split("=");
+        if (name === "nixamp_session" && rest.length > 0)
+            return decodeURIComponent(rest.join("="));
+    }
+    return "";
+}
+/**
+ * The session cookie. HttpOnly because nothing in the page reads it -- the
+ * browser attaches it by itself -- and Secure only where the page was served
+ * over https, since a nixamp on your own network is plain http.
+ */
+export function sessionCookie(token, secure) {
+    const parts = [
+        `nixamp_session=${encodeURIComponent(token)}`,
+        "Path=/",
+        "Max-Age=2592000",
+        "SameSite=Lax",
+        "HttpOnly",
+    ];
+    if (secure)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+export function clearedCookie() {
+    return "nixamp_session=; Path=/; Max-Age=0; SameSite=Lax; HttpOnly";
+}

package/dist/admin.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `nixamp admin` — what the daemon is doing, and who is listening to it.
+ *
+ * It talks to a running server over the same HTTP API a browser uses, so it
+ * works against the local daemon, against `nixamp serve` in another terminal,
+ * or against a nixamp on a different machine entirely.
+ */
+import { type Container, type Theme } from "@profullstack/hqtui";
+import type { Connection } from "./connections.ts";
+interface Report {
+    connections: Connection[];
+    active: number;
+    startedAt: number;
+    now: number;
+}
+interface Snapshot {
+    tracks: {
+        title: string;
+        artist: string;
+        duration: number;
+    }[];
+    index: number;
+    playing: boolean;
+    position: number;
+    root: string;
+    note: string;
+}
+export interface AdminOptions {
+    url: string;
+    key: string | null;
+}
+/** Where to point, from the flags or from the daemon that is running. */
+export declare function resolveTarget(argv: string[]): AdminOptions;
+/** Seconds as something a person reads at a glance. */
+export declare function since(ms: number): string;
+export declare function bytes(value: number): string;
+export declare function admin(argv: string[]): Promise<void>;
+export interface View {
+    url: string;
+    report: Report | null;
+    snapshot: Snapshot | null;
+    error: string;
+    typing: boolean;
+    restreaming: string;
+}
+export declare function draw(ui: Container, theme: Theme, view: View): void;
+export {};