nixamp 0.4.0 → 0.5.0

package/dist/tokens.js

@@ -0,0 +1,196 @@
+/**
+ * Tokens that are not passwords.
+ *
+ * Two things arrive at the same door and are the same kind of thing on the
+ * way in: the session a browser or a terminal gets after signing in, and the
+ * token a person makes on purpose to paste into a CI job. Both are opaque
+ * strings this server issued, both can be listed and revoked, and neither can
+ * be turned back into a password.
+ *
+ * They are deliberately NOT the JWT the auth module hands out. A JWT cannot be
+ * withdrawn before it expires -- nothing looks it up, that is the point of it
+ * -- and a token somebody pasted into a build server is exactly the one you
+ * want to be able to kill from a laptop. So the secret half is hashed like a
+ * password, the row is what makes the token real, and deleting the row is what
+ * makes it stop working.
+ *
+ * The shape is `nxa_<id>_<secret>`. The id is looked up; the secret is compared
+ * against its hash in constant time. Carrying the id means a token is one index
+ * hit rather than a scan over every hash on the site.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/** Prefixed so a leaked token is greppable, and obvious in a log. */
+export const TOKEN_PREFIX = "nxa_";
+/** How long a sign-in lasts. Long, because signing in on a television is work. */
+export const SESSION_DAYS = 90;
+const TABLE = "nixamp_tokens";
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    id           TEXT PRIMARY KEY,
+    user_id      TEXT NOT NULL,
+    email        TEXT NOT NULL DEFAULT '',
+    kind         TEXT NOT NULL DEFAULT 'session',
+    name         TEXT NOT NULL DEFAULT '',
+    secret_hash  TEXT NOT NULL,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    expires_at   TIMESTAMPTZ,
+    last_used_at TIMESTAMPTZ
+  );
+  CREATE INDEX IF NOT EXISTS ${TABLE}_user ON ${TABLE} (user_id);
+`;
+/** Make a token and the two halves it is made of. */
+export function mintToken() {
+    const id = randomBytes(8).toString("hex");
+    const secret = randomBytes(32).toString("base64url");
+    return { id, secret, token: `${TOKEN_PREFIX}${id}_${secret}` };
+}
+/** Is this one of ours, rather than a JWT from the auth module? */
+export function looksLikeToken(value) {
+    return value.startsWith(TOKEN_PREFIX);
+}
+/** Pull the id and the secret back out. Anything malformed is not a token. */
+export function splitToken(value) {
+    if (!looksLikeToken(value))
+        return null;
+    const rest = value.slice(TOKEN_PREFIX.length);
+    const cut = rest.indexOf("_");
+    if (cut <= 0)
+        return null;
+    const id = rest.slice(0, cut);
+    const secret = rest.slice(cut + 1);
+    if (!/^[0-9a-f]+$/.test(id) || secret.length < 16)
+        return null;
+    return { id, secret };
+}
+export function hashSecret(secret) {
+    // A token secret is 32 random bytes, not a password: there is nothing to
+    // guess by dictionary, so a slow KDF would only slow down every request.
+    return createHash("sha256").update(secret).digest("hex");
+}
+/** Compare without letting the time taken say how much of it matched. */
+function sameHash(left, right) {
+    const a = Buffer.from(left, "utf8");
+    const b = Buffer.from(right, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function asTime(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === "string") {
+        const at = Date.parse(value);
+        return Number.isNaN(at) ? null : at;
+    }
+    if (typeof value === "number")
+        return value;
+    return null;
+}
+function toRecord(row) {
+    return {
+        id: String(row["id"] ?? ""),
+        name: String(row["name"] ?? ""),
+        kind: row["kind"] === "cli" ? "cli" : "session",
+        createdAt: asTime(row["created_at"]) ?? 0,
+        expiresAt: asTime(row["expires_at"]),
+        lastUsedAt: asTime(row["last_used_at"]),
+    };
+}
+export class Tokens {
+    db;
+    now;
+    ready = null;
+    constructor(db, now = Date.now) {
+        this.db = db;
+        this.now = now;
+    }
+    /**
+     * Make the table, once per process, on first use. nixamp carries no
+     * migration runner, and asking anybody to run SQL by hand before they can
+     * sign in is a setup step too many.
+     */
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    async issue(options) {
+        await this.ensure();
+        const { id, secret, token } = mintToken();
+        const ttl = options.ttlMs === undefined ? SESSION_DAYS * 86_400_000 : options.ttlMs;
+        const createdAt = this.now();
+        const expiresAt = ttl === null ? null : createdAt + ttl;
+        await this.db.query(`INSERT INTO ${TABLE} (id, user_id, email, kind, name, secret_hash, created_at, expires_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+            id,
+            options.account.id,
+            options.account.email,
+            options.kind,
+            options.name ?? "",
+            hashSecret(secret),
+            new Date(createdAt).toISOString(),
+            expiresAt === null ? null : new Date(expiresAt).toISOString(),
+        ]);
+        return {
+            id,
+            token,
+            name: options.name ?? "",
+            kind: options.kind,
+            createdAt,
+            expiresAt,
+            lastUsedAt: null,
+        };
+    }
+    /** The account a token belongs to, or null for one this server will not accept. */
+    async verify(value) {
+        const parts = splitToken(value);
+        if (parts === null)
+            return null;
+        await this.ensure();
+        const { rows } = await this.db.query(`SELECT id, user_id, email, secret_hash, expires_at FROM ${TABLE} WHERE id = $1`, [parts.id]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        if (!sameHash(String(row["secret_hash"] ?? ""), hashSecret(parts.secret)))
+            return null;
+        const expiresAt = asTime(row["expires_at"]);
+        if (expiresAt !== null && expiresAt <= this.now()) {
+            // Tidy it away on the way past rather than running a sweeper: an expired
+            // token is only ever noticed when somebody tries to use it.
+            await this.db.query(`DELETE FROM ${TABLE} WHERE id = $1`, [parts.id]).catch(() => { });
+            return null;
+        }
+        // Last used is what makes `nixamp token list` worth reading -- it is how
+        // you tell the token you forgot about from the one CI depends on.
+        await this.db
+            .query(`UPDATE ${TABLE} SET last_used_at = $2 WHERE id = $1`, [
+            parts.id,
+            new Date(this.now()).toISOString(),
+        ])
+            .catch(() => { });
+        return { id: String(row["user_id"] ?? ""), email: String(row["email"] ?? "") };
+    }
+    /** Everything one account holds, newest first. Secrets are not in the table to leak. */
+    async list(userId, kind) {
+        await this.ensure();
+        const { rows } = await this.db.query(`SELECT id, name, kind, created_at, expires_at, last_used_at FROM ${TABLE}
+        WHERE user_id = $1 ${kind ? "AND kind = $2" : ""}
+        ORDER BY created_at DESC`, kind ? [userId, kind] : [userId]);
+        return rows.map(toRecord);
+    }
+    /** Scoped to the owner, so an id from somebody else's list revokes nothing. */
+    async revoke(userId, id) {
+        await this.ensure();
+        const { rows } = await this.db.query(`DELETE FROM ${TABLE} WHERE user_id = $1 AND id = $2 RETURNING id`, [
+            userId,
+            id,
+        ]);
+        return rows.length > 0;
+    }
+    /** Signing out of one place should not sign you out of the build server. */
+    async revokeToken(value) {
+        const parts = splitToken(value);
+        if (parts === null)
+            return false;
+        await this.ensure();
+        const { rows } = await this.db.query(`DELETE FROM ${TABLE} WHERE id = $1 AND kind = 'session' RETURNING id`, [parts.id]);
+        return rows.length > 0;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/accounts.ts

@@ -15,9 +15,14 @@
  *   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, type Identity, type Users } from "./oauth.ts";
+import type { Queryable } from "./follows.ts";
+import { type IssuedToken, looksLikeToken, type TokenKind, type TokenRecord, Tokens } from "./tokens.ts";
 
 export interface Account {
   id: string;
@@ -47,8 +52,17 @@ 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 {
   register(input: { email: string; password: string; autoVerify?: boolean }): Promise<unknown>;
@@ -93,14 +107,27 @@ export function checkCredentials(email: unknown, password: unknown): string {
 
 export class Accounts {
   private readonly system: AuthLike;
+  /** Null only where a test injected an auth system and no storage. */
+  readonly tokens: Tokens | null;
+  private readonly identities: Identities | null;
 
   constructor(options: AccountsOptions) {
+    // 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 }) as unknown as AdapterLike));
     this.system =
       options.system ??
       (createAuthSystem({
-        adapter: new PostgresAdapter({ connectionString: options.connectionString }),
+        adapter,
         jwtSecret: options.secret,
       }) as AuthLike);
+    this.tokens = adapter ? new Tokens(adapter) : null;
+    this.identities = adapter ? new Identities(adapter, adapter) : null;
   }
 
   async signUp(email: unknown, password: unknown): Promise<AuthResult> {
@@ -146,14 +173,88 @@ export class Accounts {
     }
   }
 
+  /**
+   * 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: string): Promise<Account | null> {
     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));
     } catch {
       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: Account, fallback = ""): Promise<string> {
+    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: Identity): Promise<AuthResult> {
+    if (this.identities === null) return { ...NO_ACCOUNT, error: "this nixamp does not keep accounts" };
+    let account: Account | null = 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: Account, name: string, ttlMs: number | null = null): Promise<IssuedToken | null> {
+    return this.tokens === null ? null : this.tokens.issue({ account, kind: "cli", name, ttlMs });
+  }
+
+  async listTokens(userId: string, kind?: TokenKind): Promise<TokenRecord[]> {
+    return this.tokens === null ? [] : this.tokens.list(userId, kind);
+  }
+
+  async revokeToken(userId: string, id: string): Promise<boolean> {
+    return this.tokens === null ? false : this.tokens.revoke(userId, id);
+  }
+
+  /** Signing out ends this session and leaves every other token alone. */
+  async endSession(token: string): Promise<void> {
+    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. */

package/src/attach.ts

@@ -0,0 +1,191 @@
+/**
+ * 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, type KeyEvent } from "@profullstack/hqtui";
+import { resolveTarget } from "./admin.ts";
+import { BAND_COUNT, createState, view, type State } from "./main.ts";
+import type { Command, Snapshot } from "./protocol.ts";
+import { KEY_HEADER } from "./share.ts";
+
+/** 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: State, snapshot: Snapshot): void {
+  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] as number, 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: string,
+  headers: Record<string, string>,
+  onSnapshot: (snapshot: Snapshot) => void,
+  onTrouble: (why: string) => void,
+  signal: AbortSignal,
+  send: typeof fetch = fetch,
+): Promise<void> {
+  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()) as Snapshot);
+            } 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: string): Command | null {
+  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: string[]): Promise<number> {
+  let target: { url: string; key: string | null };
+  try {
+    target = resolveTarget(argv);
+  } catch (error) {
+    console.error((error as Error).message);
+    console.error("  `nixamp daemon start ~/Music` starts one, or press d in the player to hand it one.");
+    return 1;
+  }
+
+  const headers: Record<string, string> = 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: Command): void => {
+    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: KeyEvent) => {
+    // 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;
+}