nixamp 0.2.0 → 0.3.0

package/dist/session.d.ts

@@ -0,0 +1,29 @@
+export interface Session {
+    site: string;
+    email: string;
+    token: string;
+    signedInAt: number;
+}
+export declare function sessionPath(): string;
+export declare function readSession(): Session | null;
+export declare function writeSession(session: Session): void;
+export declare function clearSession(): void;
+/**
+ * Ask without echoing. Node has no "read a password" call, so the terminal is
+ * put in raw mode and the keystrokes are collected by hand.
+ */
+export declare function askSecret(prompt: string): Promise<string>;
+export interface LoginOptions {
+    site: string;
+    email: string;
+    /** Create the account rather than signing in to one. */
+    signUp: boolean;
+    fetcher?: typeof fetch;
+}
+/** Read the flags `nixamp login` accepts. */
+export declare function parseLoginArgs(argv: string[]): LoginOptions;
+/** `nixamp login` / `nixamp signup`. */
+export declare function login(argv: string[]): Promise<number>;
+export declare function logout(): number;
+/** `nixamp whoami`, which asks the server rather than trusting the file. */
+export declare function whoami(fetcher?: typeof fetch): Promise<number>;

package/dist/session.js

@@ -0,0 +1,184 @@
+/**
+ * Being signed in, from a terminal.
+ *
+ * `nixamp login` asks for an address and a password, and keeps the token it
+ * gets back beside the daemon's state. The desktop app bundles this same CLI,
+ * so signing in there and signing in here are the same thing on disk.
+ *
+ * The password is read with the echo turned off and is never written down: the
+ * token is what is kept, and it can be revoked without changing anything the
+ * person has to remember.
+ */
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { dirname, join } from "node:path";
+import { stateDir } from "./daemon.js";
+import { DEFAULT_DIRECTORY } from "./directory.js";
+export function sessionPath() {
+    return join(stateDir(), "session.json");
+}
+export function readSession() {
+    try {
+        return JSON.parse(readFileSync(sessionPath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSession(session) {
+    const path = sessionPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(session, null, 2)}\n`);
+    // A bearer token is as good as the password for as long as it lives, so it
+    // is not left readable by everyone with an account on the machine.
+    chmodSync(path, 0o600);
+}
+export function clearSession() {
+    rmSync(sessionPath(), { force: true });
+}
+/**
+ * Ask without echoing. Node has no "read a password" call, so the terminal is
+ * put in raw mode and the keystrokes are collected by hand.
+ */
+export async function askSecret(prompt) {
+    const input = process.stdin;
+    if (!input.isTTY) {
+        // A pipe has no echo to turn off, and reading a line is what a script
+        // wants anyway.
+        const rl = createInterface({ input, output: process.stdout });
+        try {
+            return await rl.question("");
+        }
+        finally {
+            rl.close();
+        }
+    }
+    process.stdout.write(prompt);
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf8");
+    return new Promise((done) => {
+        let typed = "";
+        const onData = (key) => {
+            switch (key) {
+                case "\u0003": // ctrl-c
+                    input.setRawMode(false);
+                    input.pause();
+                    process.stdout.write("\n");
+                    process.exit(130);
+                    return;
+                case "\r":
+                case "\n":
+                case "\u0004": // ctrl-d
+                    input.setRawMode(false);
+                    input.pause();
+                    input.off("data", onData);
+                    process.stdout.write("\n");
+                    done(typed);
+                    return;
+                case "\u007f": // backspace
+                case "\b":
+                    typed = typed.slice(0, -1);
+                    return;
+                default:
+                    // One printable character. An arrow key arrives as a whole escape
+                    // sequence, which would otherwise be appended as several characters
+                    // of password nobody typed.
+                    if (key.length === 1 && key >= " " && key !== "\u007f")
+                        typed += key;
+            }
+        };
+        input.on("data", onData);
+    });
+}
+async function ask(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(prompt)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Read the flags `nixamp login` accepts. */
+export function parseLoginArgs(argv) {
+    const at = (flag) => {
+        const index = argv.indexOf(flag);
+        return index === -1 ? undefined : argv[index + 1];
+    };
+    return {
+        site: (at("--site") ?? DEFAULT_DIRECTORY).replace(/\/+$/, ""),
+        email: at("--email") ?? argv.find((a) => !a.startsWith("-") && a.includes("@")) ?? "",
+        signUp: argv.includes("--signup") || argv.includes("--sign-up"),
+    };
+}
+/** `nixamp login` / `nixamp signup`. */
+export async function login(argv) {
+    const options = parseLoginArgs(argv);
+    const send = options.fetcher ?? fetch;
+    const email = options.email || (await ask("Email: "));
+    if (!email) {
+        console.error("nixamp: no email given");
+        return 64;
+    }
+    const password = await askSecret("Password: ");
+    if (!password) {
+        console.error("nixamp: no password given");
+        return 64;
+    }
+    const where = `${options.site}/api/v1/auth/${options.signUp ? "signup" : "login"}`;
+    let answer;
+    try {
+        answer = await send(where, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ email, password }),
+        });
+    }
+    catch (error) {
+        console.error(`nixamp: could not reach ${options.site}: ${error.message}`);
+        return 69;
+    }
+    const body = (await answer.json().catch(() => ({})));
+    if (!answer.ok || !body.token) {
+        console.error(`nixamp: ${body.error ?? `signing in failed (${answer.status})`}`);
+        return 1;
+    }
+    writeSession({ site: options.site, email, token: body.token, signedInAt: Date.now() });
+    console.log(`Signed in to ${options.site} as ${email}.`);
+    return 0;
+}
+export function logout() {
+    const session = readSession();
+    clearSession();
+    console.log(session ? `Signed out of ${session.site}.` : "nixamp: you were not signed in.");
+    return 0;
+}
+/** `nixamp whoami`, which asks the server rather than trusting the file. */
+export async function whoami(fetcher = fetch) {
+    const session = readSession();
+    if (session === null) {
+        console.log("nixamp: not signed in. Try `nixamp login`.");
+        return 1;
+    }
+    try {
+        const answer = await fetcher(`${session.site}/api/v1/auth/me`, {
+            headers: { authorization: `Bearer ${session.token}` },
+        });
+        if (!answer.ok) {
+            // The token outlived its welcome, which is worth saying plainly rather
+            // than leaving a stale file to confuse the next command.
+            console.log(`nixamp: signed in as ${session.email}, but ${session.site} no longer accepts it.`);
+            console.log("  Run `nixamp login` again.");
+            return 1;
+        }
+        const body = (await answer.json());
+        console.log(`${body.account?.email ?? session.email} at ${session.site}`);
+        return 0;
+    }
+    catch {
+        // Offline is not signed out: the token is still good, we just cannot ask.
+        console.log(`${session.email} at ${session.site} (could not reach it to check)`);
+        return 0;
+    }
+}

package/dist/share.d.ts

@@ -1,4 +1,13 @@
 import type { IncomingMessage } from "node:http";
+/**
+ * Two keys, two scopes.
+ *
+ * The full key drives the player: it can skip, stop, and point the server at a
+ * different source. The listen key can only hear it. A stream published to the
+ * public directory hands out the listen key, because a link that lets a
+ * stranger pause your music is not a link you can publish.
+ */
+export type Scope = "control" | "listen";
 /** The cookie, and the query parameter that sets it. */
 export declare const KEY_COOKIE = "nixamp_key";
 export declare const KEY_QUERY = "k";
@@ -28,6 +37,13 @@ export declare function reachableAddresses(host: string, port: number): {
 }[];
 /** The full link, key and all. */
 export declare function shareLink(base: string, key: string | null): string;
+/**
+ * What a key is allowed to do. An unknown key is allowed nothing, which is the
+ * same answer as no key at all.
+ */
+export declare function scopeOf(offered: string | null, control: string | null, listen: string | null): Scope | null;
+/** Paths a listen key may have. Everything else needs the control key. */
+export declare function allowedForListening(path: string): boolean;
 /** How to run a command, so the tests never touch a real firewall. */
 export interface Runner {
     read(path: string): string | null;

package/dist/share.js

@@ -112,6 +112,25 @@ export function reachableAddresses(host, port) {
 export function shareLink(base, key) {
     return key === null ? base : `${base}/s/${key}`;
 }
+/**
+ * What a key is allowed to do. An unknown key is allowed nothing, which is the
+ * same answer as no key at all.
+ */
+export function scopeOf(offered, control, listen) {
+    if (offered === null)
+        return null;
+    if (control !== null && keysMatch(offered, control))
+        return "control";
+    if (listen !== null && keysMatch(offered, listen))
+        return "listen";
+    return null;
+}
+/** Paths a listen key may have. Everything else needs the control key. */
+export function allowedForListening(path) {
+    if (path === "/api/command" || path === "/api/source")
+        return false;
+    return true;
+}
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",
@@ -39,7 +39,10 @@
     "pack:cli": "bun scripts/pack-cli.ts"
   },
   "dependencies": {
-    "@profullstack/hqtui": "^0.3.0"
+    "@profullstack/auth-system": "^0.6.0",
+    "@profullstack/hqtui": "^0.3.0",
+    "@profullstack/x402-gateway": "^0.4.0",
+    "pg": "^8.23.0"
   },
   "devDependencies": {
     "@types/node": "^26",

package/src/accounts.ts

@@ -0,0 +1,193 @@
+/**
+ * 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";
+
+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;
+}
+
+const NO_ACCOUNT: AuthResult = { 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";
+
+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 function readResult(value: unknown): AuthResult {
+  const record = (value ?? {}) as Record<string, unknown>;
+  const user = (record["user"] ?? {}) as Record<string, unknown>;
+  const tokens = (record["tokens"] ?? {}) as Record<string, unknown>;
+  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: unknown): Account | null {
+  const claims = (value ?? {}) as Record<string, unknown>;
+  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: unknown, password: unknown): string {
+  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 {
+  private readonly system: AuthLike;
+
+  constructor(options: AccountsOptions) {
+    this.system =
+      options.system ??
+      (createAuthSystem({
+        adapter: new PostgresAdapter({ connectionString: options.connectionString }),
+        jwtSecret: options.secret,
+      }) as AuthLike);
+  }
+
+  async signUp(email: unknown, password: unknown): Promise<AuthResult> {
+    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 as string,
+          password: password as string,
+          autoVerify: true,
+        }),
+      );
+    } catch (error) {
+      const message = (error as 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: unknown, password: unknown): Promise<AuthResult> {
+    if (checkCredentials(email, password)) return { ...NO_ACCOUNT, error: REFUSED };
+    try {
+      return readResult(await this.system.login({ email: email as string, password: password as string }));
+    } catch {
+      // login() throws on bad credentials, so this is the ordinary path.
+      return { ...NO_ACCOUNT, error: REFUSED };
+    }
+  }
+
+  async whoIs(token: string): Promise<Account | null> {
+    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: Record<string, string | string[] | undefined>): string {
+  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: string, secure: boolean): string {
+  const parts = [
+    `nixamp_session=${encodeURIComponent(token)}`,
+    "Path=/",
+    "Max-Age=2592000",
+    "SameSite=Lax",
+    "HttpOnly",
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+export function clearedCookie(): string {
+  return "nixamp_session=; Path=/; Max-Age=0; SameSite=Lax; HttpOnly";
+}