nixamp 0.4.0 → 0.5.0

package/README.md

@@ -78,22 +78,55 @@ If you would rather not pipe a script into a shell, `npm i -g nixamp` and
 ## 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:
+server you own. Three ways in, because a terminal is a bad place to be asked
+for a password:
 
 ```
-nixamp login              # or: nixamp signup
+nixamp login                 # choose: a provider in a browser, or a password
+nixamp login --with github   # straight to GitHub (or google)
+nixamp login --password      # an address and a password, here
 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.
+`--with github` is OAuth 2.0 through the device grant (RFC 8628), which is how
+a television has signed you in for years: the terminal shows a short code, you
+approve it in a browser on whatever device has a keyboard, and the terminal ends
+up holding the session. It never sees your password or the provider's token, and
+it works over ssh.
+
+The PWA and the desktop app offer the same providers, since an account made by
+signing in with GitHub has no password to type anywhere. 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. A password, where one is used, 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.
 
+### Tokens, for a machine that cannot sign in
+
+```
+nixamp token create --name ci   # printed once, and only once
+nixamp token list
+nixamp token revoke <id>
+```
+
+`NIXAMP_TOKEN` in the environment is a signed-in nixamp with no login at all,
+which is the only thing that works in CI. Tokens are stored as hashes and can be
+withdrawn from anywhere; signing out does not touch them, which is the point of
+them. Sessions are the same kind of thing with an expiry, so `nixamp logout`
+really does end one.
+
+Providers are configured per deployment, and only a provider with both halves is
+offered:
+
+```
+GITHUB_CLIENT_ID=… GITHUB_CLIENT_SECRET=… nixamp serve --directory
+```
+
+The callback to register is `https://your-site/api/v1/<provider>/oauth/callback`.
+
 Running the account side of nixamp.com needs Postgres:
 
 ```
@@ -235,6 +268,21 @@ 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`.
 
+### Detaching, and coming back
+
+`d` in the player hands the music to a daemon and gives you your terminal back.
+Nothing stops. `nixamp attach` puts the player back in front of it:
+
+```
+nixamp attach                      # the daemon on this machine
+nixamp attach --url URL --key KEY  # a nixamp somewhere else
+```
+
+An attached player is the same view and the same keys; the difference is that
+the keys are sent to the daemon and what you see is what the daemon is doing.
+Any number of terminals may attach at once. `q` or `d` leaves without stopping
+anything, which is what `nixamp daemon stop` is for.
+
 ## Who may administer a server
 
 Two ways to be allowed, and they answer different questions.
@@ -382,6 +430,7 @@ A bare `ffmpeg` on `PATH` is used when there is one; `mise` shims are detected a
 | `↑` `↓` | Move through the playlist |
 | `n` `p` (or `→` `←`) | Next and previous track |
 | `s` | Stop |
+| `d` | Detach: hand the music to a daemon and keep the terminal |
 | `q` | Quit |
 
 ## Formats

package/dist/accounts.d.ts

@@ -1,3 +1,6 @@
+import { type Identity, type Users } from "./oauth.ts";
+import type { Queryable } from "./follows.ts";
+import { type IssuedToken, type TokenKind, type TokenRecord, Tokens } from "./tokens.ts";
 export interface Account {
     id: string;
     email: string;
@@ -16,6 +19,15 @@ export interface AccountsOptions {
     secret: string;
     /** Injected by the tests, which have no database. */
     system?: AuthLike;
+    /** Also injected by the tests: the storage tokens and identities sit in. */
+    adapter?: AdapterLike;
+}
+/**
+ * The slice of the auth module's storage adapter the rest of this file needs.
+ * It is the same Postgres pool the users table lives in, which is why nixamp's
+ * two tables need no connection of their own.
+ */
+export interface AdapterLike extends Queryable, Users {
 }
 /** The slice of the auth system nixamp uses. */
 export interface AuthLike {
@@ -38,10 +50,38 @@ export declare function readClaims(value: unknown): Account | null;
 export declare function checkCredentials(email: unknown, password: unknown): string;
 export declare class Accounts {
     private readonly system;
+    /** Null only where a test injected an auth system and no storage. */
+    readonly tokens: Tokens | null;
+    private readonly identities;
     constructor(options: AccountsOptions);
     signUp(email: unknown, password: unknown): Promise<AuthResult>;
     signIn(email: unknown, password: unknown): Promise<AuthResult>;
+    /**
+     * Who a token belongs to, whichever kind of token it is.
+     *
+     * A `nxa_` token is one this server issued and can withdraw, so it is looked
+     * up. Anything else is a JWT from the auth module, which is self-describing
+     * and cannot be. Both answer the same shape, so nothing downstream has to
+     * know which door the caller came in by.
+     */
     whoIs(token: string): Promise<Account | null>;
+    /**
+     * The token a signed-in caller carries away.
+     *
+     * A revocable token is preferred to the module's JWT wherever there is
+     * storage to keep one in, because signing out of a laptop you no longer have
+     * should mean something. The JWT is the fallback, and the only difference to
+     * a caller is that one of the two can be taken away.
+     */
+    sessionFor(account: Account, fallback?: string): Promise<string>;
+    /** Sign in as whoever a provider says this is, making the account if it is new. */
+    signInWith(identity: Identity): Promise<AuthResult>;
+    /** A token a person made on purpose, for a script that cannot sign in. */
+    mintCliToken(account: Account, name: string, ttlMs?: number | null): Promise<IssuedToken | null>;
+    listTokens(userId: string, kind?: TokenKind): Promise<TokenRecord[]>;
+    revokeToken(userId: string, id: string): Promise<boolean>;
+    /** Signing out ends this session and leaves every other token alone. */
+    endSession(token: string): Promise<void>;
 }
 /** The bearer token on a request, from the header or the session cookie. */
 export declare function tokenFrom(headers: Record<string, string | string[] | undefined>): string;

package/dist/accounts.js

@@ -15,9 +15,13 @@
  *   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.
+ * is not the one you read mail on. There is now a third way in that suits a
+ * terminal better than either -- OAuth 2.0 reached through the device grant in
+ * device.ts -- and what it ends with is a token from tokens.ts.
  */
 import { createAuthSystem, PostgresAdapter } from "@profullstack/auth-system";
+import { Identities } from "./oauth.js";
+import { looksLikeToken, Tokens } from "./tokens.js";
 const NO_ACCOUNT = { ok: false, account: null, token: "", error: "" };
 /**
  * The same sentence for a wrong password and an address with no account.
@@ -60,13 +64,25 @@ export function checkCredentials(email, password) {
 }
 export class Accounts {
     system;
+    /** Null only where a test injected an auth system and no storage. */
+    tokens;
+    identities;
     constructor(options) {
+        // The adapter is kept rather than only handed over: tokens and provider
+        // identities are nixamp's own tables in the same database, and a second
+        // pool for two small tables would be a second thing to configure.
+        const adapter = options.adapter ??
+            (options.system
+                ? null
+                : new PostgresAdapter({ connectionString: options.connectionString }));
         this.system =
             options.system ??
                 createAuthSystem({
-                    adapter: new PostgresAdapter({ connectionString: options.connectionString }),
+                    adapter,
                     jwtSecret: options.secret,
                 });
+        this.tokens = adapter ? new Tokens(adapter) : null;
+        this.identities = adapter ? new Identities(adapter, adapter) : null;
     }
     async signUp(email, password) {
         const wrong = checkCredentials(email, password);
@@ -112,9 +128,27 @@ export class Accounts {
             return { ...NO_ACCOUNT, error: REFUSED };
         }
     }
+    /**
+     * Who a token belongs to, whichever kind of token it is.
+     *
+     * A `nxa_` token is one this server issued and can withdraw, so it is looked
+     * up. Anything else is a JWT from the auth module, which is self-describing
+     * and cannot be. Both answer the same shape, so nothing downstream has to
+     * know which door the caller came in by.
+     */
     async whoIs(token) {
         if (!token)
             return null;
+        if (looksLikeToken(token)) {
+            if (this.tokens === null)
+                return null;
+            try {
+                return await this.tokens.verify(token);
+            }
+            catch {
+                return null;
+            }
+        }
         try {
             return readClaims(await this.system.validateToken(token));
         }
@@ -122,6 +156,65 @@ export class Accounts {
             return null;
         }
     }
+    /**
+     * The token a signed-in caller carries away.
+     *
+     * A revocable token is preferred to the module's JWT wherever there is
+     * storage to keep one in, because signing out of a laptop you no longer have
+     * should mean something. The JWT is the fallback, and the only difference to
+     * a caller is that one of the two can be taken away.
+     */
+    async sessionFor(account, fallback = "") {
+        if (this.tokens === null)
+            return fallback;
+        try {
+            return (await this.tokens.issue({ account, kind: "session" })).token;
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /** Sign in as whoever a provider says this is, making the account if it is new. */
+    async signInWith(identity) {
+        if (this.identities === null)
+            return { ...NO_ACCOUNT, error: "this nixamp does not keep accounts" };
+        let account = null;
+        try {
+            account = await this.identities.resolve(identity);
+        }
+        catch {
+            account = null;
+        }
+        if (account === null) {
+            return { ...NO_ACCOUNT, error: `${identity.provider} did not give a verified email address` };
+        }
+        const token = await this.sessionFor(account);
+        if (!token)
+            return { ...NO_ACCOUNT, error: "could not start a session" };
+        return { ok: true, account, token, error: "" };
+    }
+    /** A token a person made on purpose, for a script that cannot sign in. */
+    async mintCliToken(account, name, ttlMs = null) {
+        return this.tokens === null ? null : this.tokens.issue({ account, kind: "cli", name, ttlMs });
+    }
+    async listTokens(userId, kind) {
+        return this.tokens === null ? [] : this.tokens.list(userId, kind);
+    }
+    async revokeToken(userId, id) {
+        return this.tokens === null ? false : this.tokens.revoke(userId, id);
+    }
+    /** Signing out ends this session and leaves every other token alone. */
+    async endSession(token) {
+        if (this.tokens === null || !looksLikeToken(token))
+            return;
+        try {
+            await this.tokens.revokeToken(token);
+        }
+        catch {
+            // A session that cannot be deleted still expires, and refusing to sign
+            // somebody out because the database blinked would be worse.
+        }
+    }
 }
 /** The bearer token on a request, from the header or the session cookie. */
 export function tokenFrom(headers) {

package/dist/attach.d.ts

@@ -0,0 +1,15 @@
+import { type State } from "./main.ts";
+import type { Command, Snapshot } from "./protocol.ts";
+/** A remote track has no path, because no filesystem path leaves the machine. */
+export declare function applySnapshot(state: State, snapshot: Snapshot): void;
+/**
+ * Read the server's event stream, calling back with every snapshot.
+ *
+ * Reconnects for as long as it is wanted: a daemon restarting under an
+ * attached player should look like a pause, not a crash.
+ */
+export declare function follow(url: string, headers: Record<string, string>, onSnapshot: (snapshot: Snapshot) => void, onTrouble: (why: string) => void, signal: AbortSignal, send?: typeof fetch): Promise<void>;
+/** Drive the daemon with the same keys that drive the local player. */
+export declare function commandFor(key: string): Command | null;
+/** `nixamp attach` — the player, in front of whatever the daemon is doing. */
+export declare function attach(argv: string[]): Promise<number>;

package/dist/attach.js

@@ -0,0 +1,174 @@
+/**
+ * Walking away from the player, and coming back to it.
+ *
+ * The daemon has always been able to outlive the terminal that started it.
+ * What was missing was the pair of moves that makes that worth having: `d` in
+ * the player hands the music to a daemon and gives you your terminal back, and
+ * `nixamp attach` puts the same player back in front of the same music.
+ *
+ * Attaching is not a second player. It is the same view, drawn from the
+ * daemon's snapshot instead of a local stream, with the keys sent as commands
+ * over the API a browser remote already uses. So the analyser moves, the track
+ * list is the daemon's, and nothing has to agree twice about what a player
+ * looks like.
+ *
+ * Quitting an attached player stops nothing. That is the whole point: it is
+ * tmux's detach, not a stop button.
+ */
+import { createApp, themes } from "@profullstack/hqtui";
+import { resolveTarget } from "./admin.js";
+import { BAND_COUNT, createState, view } from "./main.js";
+import { KEY_HEADER } from "./share.js";
+/** How long to wait before trying the event stream again. */
+const RECONNECT_MS = 1000;
+/** A remote track has no path, because no filesystem path leaves the machine. */
+export function applySnapshot(state, snapshot) {
+    state.tracks = snapshot.tracks.map((track) => ({ path: "", ...track }));
+    state.index = snapshot.index;
+    state.playing = snapshot.playing;
+    state.position = snapshot.position;
+    state.levels = snapshot.levels;
+    state.silent = snapshot.silent;
+    state.root = snapshot.root;
+    state.note = snapshot.note;
+    // The bars come down the wire; the peaks that hang above them do not, and
+    // are a local decoration either way. Falling at the same rate the local
+    // player uses keeps the two looking like one program.
+    const bars = new Array(BAND_COUNT).fill(0).map((_, index) => snapshot.bars[index] ?? 0);
+    state.bars = bars;
+    state.peakHold = state.peakHold.map((peak, index) => Math.max(bars[index], peak - 0.02));
+}
+/**
+ * Read the server's event stream, calling back with every snapshot.
+ *
+ * Reconnects for as long as it is wanted: a daemon restarting under an
+ * attached player should look like a pause, not a crash.
+ */
+export async function follow(url, headers, onSnapshot, onTrouble, signal, send = fetch) {
+    while (!signal.aborted) {
+        try {
+            const answer = await send(`${url}/api/events`, { headers, signal });
+            if (!answer.ok || answer.body === null)
+                throw new Error(`${answer.status}`);
+            onTrouble("");
+            // SSE frames are separated by a blank line, and arrive split across
+            // chunks in whatever way the network felt like.
+            let buffered = "";
+            const reader = answer.body.getReader();
+            const decoder = new TextDecoder();
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffered += decoder.decode(value, { stream: true });
+                let cut = buffered.indexOf("\n\n");
+                while (cut !== -1) {
+                    const frame = buffered.slice(0, cut);
+                    buffered = buffered.slice(cut + 2);
+                    for (const line of frame.split("\n")) {
+                        if (!line.startsWith("data:"))
+                            continue;
+                        try {
+                            onSnapshot(JSON.parse(line.slice(5).trim()));
+                        }
+                        catch {
+                            // A frame we cannot read is one frame, not a reason to hang up.
+                        }
+                    }
+                    cut = buffered.indexOf("\n\n");
+                }
+            }
+        }
+        catch {
+            if (signal.aborted)
+                return;
+            onTrouble(`cannot reach ${url}`);
+        }
+        if (signal.aborted)
+            return;
+        await new Promise((done) => setTimeout(done, RECONNECT_MS));
+    }
+}
+/** Drive the daemon with the same keys that drive the local player. */
+export function commandFor(key) {
+    switch (key) {
+        case "space":
+            return { type: "toggle" };
+        case "enter":
+            return { type: "play" };
+        case "s":
+            return { type: "stop" };
+        case "n":
+        case "right":
+            return { type: "next" };
+        case "p":
+        case "left":
+            return { type: "prev" };
+        default:
+            return null;
+    }
+}
+/** `nixamp attach` — the player, in front of whatever the daemon is doing. */
+export async function attach(argv) {
+    let target;
+    try {
+        target = resolveTarget(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        console.error("  `nixamp daemon start ~/Music` starts one, or press d in the player to hand it one.");
+        return 1;
+    }
+    const headers = target.key ? { [KEY_HEADER]: target.key } : {};
+    const state = createState([], target.url, false);
+    state.note = `attaching to ${target.url}...`;
+    const app = await createApp({ theme: themes.matrix, title: "nixamp", quitKeys: ["ctrl+c"] });
+    const stop = new AbortController();
+    const tell = (command) => {
+        void fetch(`${target.url}/api/command`, {
+            method: "POST",
+            headers: { ...headers, "content-type": "application/json" },
+            body: JSON.stringify(command),
+        }).catch(() => {
+            // The next snapshot says whether it landed; a failed keypress is not
+            // worth a dialog in a player.
+        });
+    };
+    app.on("key", (event) => {
+        // q and d both leave, because both mean "I am done with this terminal".
+        // Neither stops the music, and the line printed on the way out says so.
+        if (event.key === "q" || event.key === "d") {
+            app.quit();
+            return;
+        }
+        if (event.key === "up" || event.key === "down") {
+            const at = state.index + (event.key === "down" ? 1 : -1);
+            if (at < 0 || at >= state.tracks.length)
+                return;
+            // Moved here as well as asked for, so the highlight does not wait for a
+            // round trip before it moves.
+            state.index = at;
+            app.invalidate();
+            tell({ type: "select", index: at });
+            return;
+        }
+        const command = commandFor(event.key);
+        if (command)
+            tell(command);
+    });
+    app.on("exit", () => stop.abort());
+    app.render((args) => view(args, state));
+    void follow(target.url, headers, (snapshot) => {
+        applySnapshot(state, snapshot);
+        app.invalidate();
+    }, (why) => {
+        state.note = why;
+        app.invalidate();
+    }, stop.signal);
+    await app.start();
+    stop.abort();
+    console.log(`Detached. ${target.url} is still playing.`);
+    console.log("  nixamp attach       come back");
+    console.log("  nixamp daemon stop  when you are done");
+    return 0;
+}

package/dist/device.d.ts

@@ -0,0 +1,67 @@
+/** Long enough to walk to another room, short enough that a stolen code is stale. */
+export declare const GRANT_TTL_MS = 600000;
+/** What the CLI is told to wait between polls, in seconds. */
+export declare const POLL_INTERVAL_SECONDS = 5;
+export interface Grant {
+    deviceCode: string;
+    userCode: string;
+    createdAt: number;
+    expiresAt: number;
+    lastPolledAt: number;
+    /** Set once somebody approved it in a browser. */
+    session: {
+        token: string;
+        email: string;
+    } | null;
+    denied: boolean;
+}
+export type PollStatus = {
+    status: "pending";
+} | {
+    status: "slow_down";
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+} | {
+    status: "ok";
+    token: string;
+    email: string;
+};
+/** `WXYZ-4RTB`. Hyphenated because it is read aloud and typed by hand. */
+export declare function makeUserCode(random: (size: number) => Uint8Array): string;
+/** Accept what a person typed however they typed it: lower case, no hyphen. */
+export declare function normalizeUserCode(value: unknown): string;
+export interface DeviceOptions {
+    now?: () => number;
+    random?: (size: number) => Uint8Array;
+    /** How often a waiting terminal is told to ask. Five seconds is RFC 8628's. */
+    intervalSeconds?: number;
+}
+export declare class DeviceGrants {
+    private readonly byDevice;
+    private readonly byUser;
+    private readonly now;
+    private readonly random;
+    /** Told to the terminal, and enforced here: the two must be the same number. */
+    readonly interval: number;
+    constructor(options?: DeviceOptions);
+    start(): Grant;
+    /** The grant behind a code somebody typed, if it is still worth anything. */
+    find(userCode: string): Grant | null;
+    approve(userCode: string, session: {
+        token: string;
+        email: string;
+    }): boolean;
+    deny(userCode: string): boolean;
+    /**
+     * 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: string): PollStatus;
+    private forget;
+    sweep(): void;
+    get size(): number;
+    /** The grants nobody has answered yet, newest last. */
+    pending(): Grant[];
+}