nixamp 0.4.0 → 0.5.0

package/dist/device.js

@@ -0,0 +1,157 @@
+/**
+ * Signing in on one screen for a session on another.
+ *
+ * This is the device authorization grant (RFC 8628), which is the flow a
+ * television has been using to sign you in for years: the terminal shows a
+ * short code, you open a page on whatever device has a keyboard and a browser,
+ * you type the code, and the terminal -- which was polling all along -- is
+ * signed in.
+ *
+ * It is the right shape for nixamp for the same reason a magic link is the
+ * wrong one: the thing being signed in has no browser to hand off to, and may
+ * not be the device where you read your mail. It also means the CLI never sees
+ * a password or a provider token, only the session it ends up with.
+ *
+ * Grants are held in memory. They live ten minutes, they are worth nothing
+ * after they are redeemed, and a restart costing somebody a retyped code is a
+ * better trade than a table to migrate.
+ */
+import { randomBytes } from "node:crypto";
+/** Long enough to walk to another room, short enough that a stolen code is stale. */
+export const GRANT_TTL_MS = 600_000;
+/** What the CLI is told to wait between polls, in seconds. */
+export const POLL_INTERVAL_SECONDS = 5;
+/**
+ * Not a timestamp, so the first poll is never mistaken for a fast one. Zero
+ * would be, and a clock that starts at zero is exactly what a test has.
+ */
+const NEVER_POLLED = -1;
+/**
+ * No vowels, so the generator cannot produce a word; no 0/O or 1/I, so nobody
+ * mistypes one for the other. This is the alphabet RFC 8628 suggests.
+ */
+const ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+function randomFrom(alphabet, length, bytes) {
+    let out = "";
+    for (let index = 0; index < length; index += 1) {
+        out += alphabet[bytes[index] % alphabet.length];
+    }
+    return out;
+}
+/** `WXYZ-4RTB`. Hyphenated because it is read aloud and typed by hand. */
+export function makeUserCode(random) {
+    const bytes = random(8);
+    return `${randomFrom(ALPHABET, 4, bytes.subarray(0, 4))}-${randomFrom(ALPHABET, 4, bytes.subarray(4, 8))}`;
+}
+/** Accept what a person typed however they typed it: lower case, no hyphen. */
+export function normalizeUserCode(value) {
+    if (typeof value !== "string")
+        return "";
+    const bare = value.toUpperCase().replace(/[^A-Z0-9]/g, "");
+    if (bare.length !== 8)
+        return "";
+    return `${bare.slice(0, 4)}-${bare.slice(4)}`;
+}
+export class DeviceGrants {
+    byDevice = new Map();
+    byUser = new Map();
+    now;
+    random;
+    /** Told to the terminal, and enforced here: the two must be the same number. */
+    interval;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.random = options.random ?? ((size) => randomBytes(size));
+        this.interval = Math.max(1, options.intervalSeconds ?? POLL_INTERVAL_SECONDS);
+    }
+    start() {
+        this.sweep();
+        const at = this.now();
+        // A user code can collide -- there are only 20^8 of them and they are
+        // short-lived -- so it is retried rather than handed out twice.
+        let userCode = makeUserCode(this.random);
+        for (let tries = 0; this.byUser.has(userCode) && tries < 10; tries += 1) {
+            userCode = makeUserCode(this.random);
+        }
+        const grant = {
+            deviceCode: Buffer.from(this.random(32)).toString("base64url"),
+            userCode,
+            createdAt: at,
+            expiresAt: at + GRANT_TTL_MS,
+            lastPolledAt: NEVER_POLLED,
+            session: null,
+            denied: false,
+        };
+        this.byDevice.set(grant.deviceCode, grant);
+        this.byUser.set(grant.userCode, grant);
+        return grant;
+    }
+    /** The grant behind a code somebody typed, if it is still worth anything. */
+    find(userCode) {
+        const grant = this.byUser.get(normalizeUserCode(userCode));
+        if (!grant || grant.expiresAt <= this.now() || grant.session !== null || grant.denied)
+            return null;
+        return grant;
+    }
+    approve(userCode, session) {
+        const grant = this.find(userCode);
+        if (grant === null)
+            return false;
+        grant.session = session;
+        return true;
+    }
+    deny(userCode) {
+        const grant = this.find(userCode);
+        if (grant === null)
+            return false;
+        grant.denied = true;
+        return true;
+    }
+    /**
+     * What the waiting terminal is told. A grant is forgotten the moment it
+     * answers with a session, so the same device code cannot be redeemed twice.
+     */
+    poll(deviceCode) {
+        const at = this.now();
+        const grant = this.byDevice.get(deviceCode);
+        if (!grant || grant.expiresAt <= at) {
+            this.forget(grant);
+            return { status: "expired" };
+        }
+        // Polling faster than it was told to is answered with slow_down rather
+        // than an answer, which is what RFC 8628 asks of a server.
+        if (grant.lastPolledAt !== NEVER_POLLED && at - grant.lastPolledAt < this.interval * 1000 - 250) {
+            return { status: "slow_down" };
+        }
+        grant.lastPolledAt = at;
+        if (grant.denied) {
+            this.forget(grant);
+            return { status: "denied" };
+        }
+        if (grant.session === null)
+            return { status: "pending" };
+        this.forget(grant);
+        return { status: "ok", token: grant.session.token, email: grant.session.email };
+    }
+    forget(grant) {
+        if (!grant)
+            return;
+        this.byDevice.delete(grant.deviceCode);
+        this.byUser.delete(grant.userCode);
+    }
+    sweep() {
+        const at = this.now();
+        for (const grant of this.byDevice.values()) {
+            if (grant.expiresAt <= at)
+                this.forget(grant);
+        }
+    }
+    get size() {
+        return this.byDevice.size;
+    }
+    /** The grants nobody has answered yet, newest last. */
+    pending() {
+        const at = this.now();
+        return [...this.byDevice.values()].filter((grant) => grant.expiresAt > at && grant.session === null && !grant.denied);
+    }
+}

package/dist/main.d.ts

@@ -25,6 +25,18 @@ export interface State {
 export declare function createState(tracks: Track[], root: string, silent: boolean): State;
 export declare function current(state: State): Track | undefined;
 export declare function barGlyph(value: number): string;
+/** `-h`, `--help`, or the word, which is what people type when they forget. */
+export declare function isHelp(arg: string | undefined): boolean;
+/**
+ * Was help asked for, given what the command already means by its flags?
+ *
+ * `serve` has had `-h HOST` since the beginning, and `daemon start` passes its
+ * flags straight through, so for those two `-h` is a bind address and only the
+ * spelled-out forms ask for help. Everywhere else `-h` is help, because that
+ * is what it is everywhere else.
+ */
+export declare function wantsHelp(first: string | undefined, rest: string[]): boolean;
+export declare function helpFor(topic: string | undefined): string;
 /**
  * The whole CLI, as a function. `bin/nixamp.mjs` imports and calls it: relying
  * on `import.meta.main` there would leave the installed binary doing nothing,

package/dist/main.js

@@ -46,9 +46,11 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp [source]                play it in the terminal
   nixamp serve [source] [options]  play here, and hand out a browser remote
   nixamp daemon start|stop|status  serve in the background, and let go of it
+  nixamp attach                  put the player back in front of the daemon
   nixamp admin [--url U] [--key K] who is connected, and re-stream to them
-  nixamp login [--signup]        sign in to nixamp.com
+  nixamp login [--with github]  sign in to nixamp.com, in a browser or here
   nixamp logout / whoami        forget it, or check it
+  nixamp token create|list|revoke  tokens for a machine that cannot sign in
   nixamp update [version]        re-run the installer, keeping your choices
   nixamp uninstall [--yes]       remove everything the installer created
 
@@ -72,9 +74,110 @@ Options for serve:
       --x402       charge for listening once more than 5 people are listening
       --no-x402    never charge
 
+Options for login:
+      --with NAME  sign in with a provider (github, google) in a browser
+      --device     approve in a browser, whichever way it is signed in
+      --password   ask for an address and a password here instead
+      --token T    keep a token made with \`nixamp token create\`
+      --signup     make an account with an address and a password
+      --no-browser print the URL rather than trying to open one
+      --site URL   somewhere other than https://nixamp.com
+
+NIXAMP_TOKEN in the environment is a signed-in nixamp with no login at all,
+which is what a build server wants.
+
+Keys in the player:
+  space play/pause   enter play   s stop   n/p next/previous   up/down choose
+  d     detach: hand the music to a daemon and get the terminal back
+  q     quit
+
   -v, --version    print the version
-      --help       print this
+  -h, --help       print this. \`nixamp help <command>\` says more about one
 `;
+/** `-h`, `--help`, or the word, which is what people type when they forget. */
+export function isHelp(arg) {
+    return arg === "-h" || arg === "--help" || arg === "help";
+}
+/**
+ * Was help asked for, given what the command already means by its flags?
+ *
+ * `serve` has had `-h HOST` since the beginning, and `daemon start` passes its
+ * flags straight through, so for those two `-h` is a bind address and only the
+ * spelled-out forms ask for help. Everywhere else `-h` is help, because that
+ * is what it is everywhere else.
+ */
+export function wantsHelp(first, rest) {
+    if (isHelp(first))
+        return true;
+    const shortIsHost = first === "serve" || first === "daemon";
+    return rest.some((arg) => (shortIsHost ? arg !== "-h" && isHelp(arg) : isHelp(arg)));
+}
+/**
+ * Longer help, one command at a time.
+ *
+ * The summary in HELP is a list of what exists; these say how each is used,
+ * which is the thing you want at the moment you ask, and the thing that makes
+ * the summary unreadable if it is folded in.
+ */
+const TOPICS = {
+    login: `nixamp login — sign in to nixamp.com.
+
+  nixamp login                 choose how: a provider in a browser, or a password
+  nixamp login --with github   go straight to a provider (github, google)
+  nixamp login --device        approve in a browser you are already signed in to
+  nixamp login --password      an address and a password, here in the terminal
+  nixamp login --token TOKEN   keep a token made with \`nixamp token create\`
+  nixamp signup                make an account with an address and a password
+
+A provider sign-in never asks this terminal for anything secret. It shows a
+short code, you approve it in a browser on whatever device has a keyboard, and
+this terminal ends up holding the session. That works over ssh, and it works on
+a television, which is why it is the default.
+
+  --no-browser  print the URL rather than trying to open one
+  --site URL    somewhere other than https://nixamp.com
+
+NIXAMP_TOKEN in the environment is a signed-in nixamp with no login at all.
+`,
+    token: `nixamp token — tokens for a machine that cannot sign in.
+
+  nixamp token create --name ci   make one, and print it once
+  nixamp token list               id, when it was made, when it was last used
+  nixamp token revoke ID          stop it working, everywhere, now
+
+A token is shown once because the server keeps only its hash. Put it in the
+environment as NIXAMP_TOKEN, or keep it here with \`nixamp login --token\`.
+Signing out does not touch it: that is what it is for.
+`,
+    daemon: `nixamp daemon — a nixamp that outlives the terminal that started it.
+
+  nixamp daemon start [source] [serve options]   start it, detached
+  nixamp daemon status                           where it is, and how long
+  nixamp daemon stop                             stop it
+
+It is \`nixamp serve\` with nobody holding its terminal, so it keeps playing and
+keeps serving its browser remote. One per user.
+
+  nixamp attach   put the player back in front of it
+  nixamp admin    who is connected, and re-stream to them
+
+From inside the player, d hands the music to a daemon without stopping it.
+`,
+    attach: `nixamp attach — the player, in front of the running daemon.
+
+The same view and the same keys as the local player, except that the music is
+the daemon's: keys are sent to it, and what you see is what it is doing. Any
+number of terminals may attach at once.
+
+  nixamp attach                    the daemon on this machine
+  nixamp attach --url URL [--key K]  a nixamp somewhere else
+
+q or d leaves; neither stops anything. \`nixamp daemon stop\` is what stops it.
+`,
+};
+export function helpFor(topic) {
+    return (topic ? TOPICS[topic] : undefined) ?? HELP;
+}
 /**
  * `nixamp daemon <start|stop|status>`.
  *
@@ -127,7 +230,13 @@ async function runDaemon(argv) {
         console.log(`  up ${Math.round((Date.now() - state.startedAt) / 1000)}s`);
         return 0;
     }
-    console.error(`nixamp daemon: unknown action ${action}. Try start, stop or status.`);
+    // `nixamp daemon attach` is what people try before `nixamp attach`, so it is
+    // the same thing rather than an error about a word that means what it says.
+    if (action === "attach") {
+        const { attach } = await import("./attach.js");
+        return attach(rest);
+    }
+    console.error(`nixamp daemon: unknown action ${action}. Try start, stop, status or attach.`);
     return 64;
 }
 /**
@@ -137,6 +246,17 @@ async function runDaemon(argv) {
  */
 export async function main() {
     const [first, ...rest] = process.argv.slice(2);
+    // Asked for however anybody asks for it. `nixamp help serve` and
+    // `nixamp serve --help` are the same question, so they get the same answer.
+    if (wantsHelp(first, rest)) {
+        console.log(helpFor(isHelp(first) ? rest[0] : first));
+        return;
+    }
+    if (first === "attach") {
+        const { attach } = await import("./attach.js");
+        process.exitCode = await attach(rest);
+        return;
+    }
     if (first === "serve") {
         const { serve } = await import("./server.js");
         await serve(rest, version());
@@ -156,6 +276,11 @@ export async function main() {
         process.exitCode = await login(first === "signup" ? [...rest, "--signup"] : rest);
         return;
     }
+    if (first === "token" || first === "tokens") {
+        const { tokens } = await import("./session.js");
+        process.exitCode = await tokens(rest);
+        return;
+    }
     if (first === "logout" || first === "whoami") {
         const session = await import("./session.js");
         process.exitCode = first === "logout" ? session.logout() : await session.whoami();
@@ -170,10 +295,6 @@ export async function main() {
         console.log(version());
         return;
     }
-    if (first === "--help") {
-        console.log(HELP);
-        return;
-    }
     // resolve() would turn https://host/x into /cwd/https:/host/x, so a URL is
     // left exactly as it was typed.
     const asked = first ?? ".";
@@ -186,6 +307,10 @@ export async function main() {
     }
     const state = createState(tracks, target, tools.play === null);
     const app = await createApp({ theme: themes.matrix, title: "nixamp", quitKeys: ["ctrl+c"] });
+    // Set when d handed the music to a daemon, and printed after the TUI is
+    // gone. A field rather than a local, because a local assigned only inside a
+    // closure stays narrowed to null for the checker.
+    const handoff = { to: null };
     const analyser = new Analyser(FFT_SIZE, RATE);
     const edges = bandEdges(BAND_COUNT, RATE, FFT_SIZE);
     // Samples accumulate until there are enough for one transform.
@@ -249,12 +374,41 @@ export async function main() {
         state.position = 0;
         app.invalidate();
     };
+    /**
+     * Hand the music to a daemon and give the terminal back.
+     *
+     * The local stream is stopped first, because two processes fighting over the
+     * audio device is a worse experience than a second of silence. What comes
+     * back is where it went, so `nixamp attach` is a suggestion rather than a
+     * thing to remember.
+     */
+    const detach = async () => {
+        state.note = "Handing over to a daemon...";
+        app.invalidate();
+        stream.stop();
+        state.playing = false;
+        try {
+            const d = await import("./daemon.js");
+            const daemon = await d.start([target], fileURLToPath(new URL("./main.js", import.meta.url)));
+            handoff.to = { daemon, url: d.daemonUrl(daemon) };
+            app.quit();
+        }
+        catch (error) {
+            // Most often: a daemon is already running, which is worth saying rather
+            // than leaving somebody looking at a player that stopped for no reason.
+            state.note = error.message;
+            app.invalidate();
+        }
+    };
     app.on("key", (event) => {
         switch (event.key) {
             case "q":
                 stream.stop();
                 app.quit();
                 return;
+            case "d":
+                void detach();
+                return;
             case "space":
                 state.playing ? stopAll() : play();
                 return;
@@ -291,6 +445,13 @@ export async function main() {
     app.on("exit", () => stream.stop());
     app.render((args) => view(args, state));
     await app.start();
+    const handed = handoff.to;
+    if (handed !== null) {
+        console.log(`Detached. Still playing as pid ${handed.daemon.pid}.`);
+        console.log(`  ${handed.daemon.key ? `${handed.url}/s/${handed.daemon.key}` : handed.url}`);
+        console.log("  nixamp attach       come back to it");
+        console.log("  nixamp daemon stop  when you are done");
+    }
 }
 /**
  * The bars, on a braille canvas: four vertical pixels per cell, so a bar moves

package/dist/oauth.d.ts

@@ -0,0 +1,108 @@
+import type { Account } from "./accounts.ts";
+import type { DeviceGrants } from "./device.ts";
+import type { Queryable } from "./follows.ts";
+export interface Provider {
+    /** As it appears in a URL and in `nixamp login --with <id>`. */
+    id: string;
+    /** As it appears to a person. */
+    name: string;
+    clientId: string;
+    clientSecret: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    scope: string;
+    /** Turn the provider's access token into an address it stands behind. */
+    identify(accessToken: string, send: typeof fetch): Promise<Identity | null>;
+}
+/** Who the provider says this is. `subject` is stable when an address is not. */
+export interface Identity {
+    provider: string;
+    subject: string;
+    email: string;
+}
+export declare function githubProvider(clientId: string, clientSecret: string): Provider;
+export declare function googleProvider(clientId: string, clientSecret: string): Provider;
+/** Whichever providers this deployment has been given both halves of. */
+export declare function providersFrom(env: Record<string, string | undefined>): Provider[];
+export declare function redirectUri(site: string, provider: Provider): string;
+/** Where to send the browser. `state` is the only thing standing between this and CSRF. */
+export declare function authorizeUrl(provider: Provider, site: string, state: string): string;
+/** Swap the code for an access token. Empty string means the provider refused. */
+export declare function exchangeCode(provider: Provider, code: string, site: string, send?: typeof fetch): Promise<string>;
+/** The slice of the auth module's storage adapter that identities need. */
+export interface Users {
+    getUserByEmail(email: string): Promise<{
+        id?: string;
+        email?: string;
+    } | null | undefined>;
+    createUser(user: {
+        email: string;
+        password: string | null;
+        emailVerified: boolean;
+        profile?: Record<string, unknown>;
+    }): Promise<{
+        id?: string;
+        email?: string;
+    }>;
+}
+/**
+ * The account behind a provider identity, creating one the first time.
+ *
+ * The account row is made with no password at all rather than a random one
+ * nobody knows. A null password is a fact -- this account signs in with GitHub
+ * -- where a random password is a credential sitting in a database waiting to
+ * be found.
+ */
+export declare class Identities {
+    private readonly db;
+    private readonly users;
+    private ready;
+    constructor(db: Queryable, users: Users);
+    private ensure;
+    resolve(identity: Identity): Promise<Account | null>;
+}
+/**
+ * What a round trip to a provider is for.
+ *
+ * A browser sent to GitHub comes back with a code and a state, and nothing
+ * else: whatever the request knew has to be remembered here in the meantime.
+ * The state is unguessable and single-use, which is what makes a callback
+ * somebody else caused useless.
+ */
+export interface Pending {
+    provider: string;
+    /** Set when this round trip is approving a terminal rather than a browser. */
+    userCode: string;
+    createdAt: number;
+}
+/** A state is only ever open for the length of one sign-in. */
+export declare const STATE_TTL_MS = 600000;
+export declare class SignIn {
+    readonly providers: Provider[];
+    readonly device: DeviceGrants;
+    readonly site: string;
+    private readonly now;
+    private readonly states;
+    constructor(providers: Provider[], device: DeviceGrants, site: string, now?: () => number);
+    /** What /api/v1/auth/providers says, and what the CLI menu is built from. */
+    get offered(): {
+        id: string;
+        name: string;
+    }[];
+    provider(id: unknown): Provider | null;
+    /** Start a round trip, and answer the URL the browser should go to. */
+    begin(provider: Provider, userCode?: string): string;
+    /** Redeem a state exactly once, so a replayed callback finds nothing. */
+    claim(state: unknown): Pending | null;
+    private sweep;
+}
+/**
+ * The page the terminal sends somebody to.
+ *
+ * It is served by the API rather than the app because it has to work before
+ * there is a session and without the web build being present -- a nixamp
+ * deployed with no web assets can still sign a terminal in.
+ */
+export declare function devicePage(signIn: SignIn, code: string, signedInAs: string): string;
+export declare function deviceDonePage(email: string): string;
+export declare function signInFailedPage(why: string): string;