nixamp 0.4.0 → 0.5.0

package/dist/session.d.ts

@@ -5,7 +5,15 @@ export interface Session {
     signedInAt: number;
 }
 export declare function sessionPath(): string;
-export declare function readSession(): Session | null;
+/**
+ * The session on disk, or the one in the environment.
+ *
+ * `NIXAMP_TOKEN` wins, and is the whole answer for a build server: there is no
+ * `nixamp login` to run in a container, and a token pasted into a secret store
+ * is the thing a build server can actually hold. It is deliberately not
+ * written to disk -- the environment is where it came from and where it ends.
+ */
+export declare function readSession(env?: NodeJS.ProcessEnv): Session | null;
 export declare function writeSession(session: Session): void;
 export declare function clearSession(): void;
 /**
@@ -18,12 +26,75 @@ export interface LoginOptions {
     email: string;
     /** Create the account rather than signing in to one. */
     signUp: boolean;
+    /** A provider id to sign in with, `""` for none named. */
+    with: string;
+    /** Approve in a browser without naming a provider, whoever it is signed in as. */
+    device: boolean;
+    /** Skip the menu and ask for a password, however the site is configured. */
+    password: boolean;
+    /** A token made with `nixamp token create`, to keep rather than earn. */
+    token: string;
+    /** Do not try to open a browser. */
+    noBrowser: boolean;
     fetcher?: typeof fetch;
 }
 /** Read the flags `nixamp login` accepts. */
 export declare function parseLoginArgs(argv: string[]): LoginOptions;
+export interface SiteWays {
+    password: boolean;
+    device: boolean;
+    providers: {
+        id: string;
+        name: string;
+    }[];
+}
+/**
+ * What this site will accept. An older nixamp has no such endpoint, and the
+ * answer for one is the way in it has always had.
+ */
+export declare function askWays(site: string, send: typeof fetch): Promise<SiteWays>;
+/**
+ * Show a URL in a browser if there is one to show it in.
+ *
+ * Best effort by design: over ssh there is no browser and nothing should
+ * pretend otherwise, which is why the code and the URL are always printed
+ * whether this works or not.
+ */
+export declare function openInBrowser(url: string): void;
+export interface DeviceIo {
+    say: (line: string) => void;
+    wait: (ms: number) => Promise<void>;
+    open: (url: string) => void;
+}
+/**
+ * The device grant, from this side.
+ *
+ * Ask for a code, show it, then poll until somebody approves it in a browser.
+ * `slow_down` is obeyed rather than ignored: a server that says to back off is
+ * the only warning before it stops answering at all.
+ */
+export declare function deviceLogin(site: string, provider: string, send: typeof fetch, io: DeviceIo): Promise<{
+    token: string;
+    email: string;
+} | string>;
 /** `nixamp login` / `nixamp signup`. */
-export declare function login(argv: string[]): Promise<number>;
+export declare function login(argv: string[], fetcher?: typeof fetch): Promise<number>;
+/** The address a token belongs to, or null if the site will not have it. */
+export declare function accountFor(site: string, token: string, send: typeof fetch): Promise<string | null>;
+/**
+ * Which way in to use.
+ *
+ * The menu only appears where it can be answered: a pipe gets the flow it has
+ * always had, so a script that feeds an address and a password still works.
+ * Null means what was asked for is not on offer here.
+ */
+export declare function chooseWay(ways: SiteWays, options: LoginOptions): Promise<string | null>;
+/**
+ * `nixamp token create|list|revoke`, which is how a machine that cannot sign
+ * in gets to be signed in. The token is shown once, at creation, because the
+ * server keeps only its hash and has nothing to show a second time.
+ */
+export declare function tokens(argv: string[], fetcher?: typeof fetch): 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

@@ -1,15 +1,24 @@
 /**
  * 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.
+ * There are three ways in, and they exist because a terminal is a bad place to
+ * be asked for a password and a worse place to click a link:
  *
- * 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.
+ * - **A provider**, through the device grant. The terminal shows a short code,
+ *   you approve it in a browser on whatever device has a keyboard, and the
+ *   terminal ends up holding a session it can use. It never sees the password
+ *   or the provider's token. This is what `nixamp login` offers first.
+ * - **An address and a password**, as before, for anyone who has one.
+ * - **A token**, made once with `nixamp token create` and pasted into a build
+ *   server. `NIXAMP_TOKEN` in the environment is a signed-in nixamp with no
+ *   login at all, which is the only thing that works in CI.
+ *
+ * Whichever way in, what is kept on disk is a token 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.
  */
 import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { dirname, join } from "node:path";
 import { stateDir } from "./daemon.js";
@@ -17,7 +26,24 @@ import { DEFAULT_DIRECTORY } from "./directory.js";
 export function sessionPath() {
     return join(stateDir(), "session.json");
 }
-export function readSession() {
+/**
+ * The session on disk, or the one in the environment.
+ *
+ * `NIXAMP_TOKEN` wins, and is the whole answer for a build server: there is no
+ * `nixamp login` to run in a container, and a token pasted into a secret store
+ * is the thing a build server can actually hold. It is deliberately not
+ * written to disk -- the environment is where it came from and where it ends.
+ */
+export function readSession(env = process.env) {
+    const fromEnv = env["NIXAMP_TOKEN"];
+    if (fromEnv) {
+        return {
+            site: (env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY).replace(/\/+$/, ""),
+            email: "",
+            token: fromEnv,
+            signedInAt: 0,
+        };
+    }
     try {
         return JSON.parse(readFileSync(sessionPath(), "utf8"));
     }
@@ -110,12 +136,165 @@ export function parseLoginArgs(argv) {
         site: (at("--site") ?? DEFAULT_DIRECTORY).replace(/\/+$/, ""),
         email: at("--email") ?? argv.find((a) => !a.startsWith("-") && a.includes("@")) ?? "",
         signUp: argv.includes("--signup") || argv.includes("--sign-up"),
+        // --with github, or the bare --github that people type anyway.
+        with: at("--with") ??
+            at("--provider") ??
+            argv.find((a) => a === "--github" || a === "--google")?.slice(2) ??
+            "",
+        device: argv.includes("--device"),
+        password: argv.includes("--password"),
+        token: at("--token") ?? "",
+        noBrowser: argv.includes("--no-browser"),
     };
 }
+/**
+ * What this site will accept. An older nixamp has no such endpoint, and the
+ * answer for one is the way in it has always had.
+ */
+export async function askWays(site, send) {
+    const fallback = { password: true, device: false, providers: [] };
+    try {
+        const answer = await send(`${site}/api/v1/auth/providers`);
+        if (!answer.ok)
+            return fallback;
+        const body = (await answer.json());
+        return {
+            password: body.password !== false,
+            device: body.device === true,
+            providers: Array.isArray(body.providers) ? body.providers : [],
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Show a URL in a browser if there is one to show it in.
+ *
+ * Best effort by design: over ssh there is no browser and nothing should
+ * pretend otherwise, which is why the code and the URL are always printed
+ * whether this works or not.
+ */
+export function openInBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(opener, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+    }
+    catch {
+        // No browser here. The printed URL is the fallback, and it is enough.
+    }
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/**
+ * The device grant, from this side.
+ *
+ * Ask for a code, show it, then poll until somebody approves it in a browser.
+ * `slow_down` is obeyed rather than ignored: a server that says to back off is
+ * the only warning before it stops answering at all.
+ */
+export async function deviceLogin(site, provider, send, io) {
+    let answer;
+    try {
+        answer = await send(`${site}/api/v1/auth/device/code`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: "{}",
+        });
+    }
+    catch (error) {
+        return `could not reach ${site}: ${error.message}`;
+    }
+    if (!answer.ok)
+        return "this nixamp cannot sign a terminal in";
+    const grant = (await answer.json().catch(() => ({})));
+    if (!grant.device_code || !grant.user_code)
+        return "this nixamp cannot sign a terminal in";
+    // Straight to the provider when one was named, so the only thing to do in
+    // the browser is approve. Otherwise the page asks which.
+    const where = provider && grant.user_code
+        ? `${site}/api/v1/${provider}/oauth/start?device=${encodeURIComponent(grant.user_code)}`
+        : (grant.verification_uri_complete ?? grant.verification_uri ?? `${site}/api/v1/auth/device`);
+    io.say("");
+    io.say(`  Open  ${where}`);
+    io.say(`  Code  ${grant.user_code}`);
+    io.say("");
+    io.say("Waiting for you to approve it...");
+    io.open(where);
+    let interval = Math.max(1, grant.interval ?? 5) * 1000;
+    const until = Date.now() + Math.max(60, grant.expires_in ?? 600) * 1000;
+    while (Date.now() < until) {
+        await io.wait(interval);
+        let poll;
+        try {
+            poll = await send(`${site}/api/v1/auth/device/token`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ device_code: grant.device_code }),
+            });
+        }
+        catch {
+            // A dropped network mid-wait is not a failed sign-in; keep asking.
+            continue;
+        }
+        const body = (await poll.json().catch(() => ({})));
+        if (poll.ok && body.token)
+            return { token: body.token, email: body.email ?? "" };
+        if (body.error === "slow_down") {
+            interval += 5000;
+            continue;
+        }
+        if (body.error === "authorization_pending")
+            continue;
+        if (body.error === "access_denied")
+            return "that sign-in was refused";
+        if (body.error === "expired_token")
+            break;
+    }
+    return "the code expired before it was approved";
+}
 /** `nixamp login` / `nixamp signup`. */
-export async function login(argv) {
+export async function login(argv, fetcher = fetch) {
     const options = parseLoginArgs(argv);
-    const send = options.fetcher ?? fetch;
+    const send = options.fetcher ?? fetcher;
+    // A token is not a sign-in, it is a token somebody already made. It is
+    // checked before it is kept, so a typo fails here rather than at the next
+    // command with a message about something else.
+    if (options.token) {
+        const account = await accountFor(options.site, options.token, send);
+        if (account === null) {
+            console.error(`nixamp: ${options.site} does not accept that token`);
+            return 1;
+        }
+        writeSession({ site: options.site, email: account, token: options.token, signedInAt: Date.now() });
+        console.log(`Signed in to ${options.site} as ${account}.`);
+        return 0;
+    }
+    // Signing up is still an address and a password: a provider account that has
+    // never been here signs up by signing in, which is the point of it.
+    const ways = options.password || options.signUp ? null : await askWays(options.site, send);
+    const chosen = ways ? await chooseWay(ways, options) : "password";
+    if (chosen === null) {
+        const offered = (ways?.providers ?? []).map((provider) => provider.id).join(", ");
+        console.error(offered
+            ? `nixamp: ${options.site} cannot sign you in with ${options.with}. It offers: ${offered}.`
+            : `nixamp: ${options.site} offers no providers to sign in with.`);
+        return 64;
+    }
+    if (chosen !== "password") {
+        const got = await deviceLogin(options.site, chosen === "device" ? "" : chosen, send, {
+            say: (line) => console.log(line),
+            wait: sleep,
+            open: options.noBrowser ? () => { } : openInBrowser,
+        });
+        if (typeof got === "string") {
+            console.error(`nixamp: ${got}`);
+            return 1;
+        }
+        writeSession({ site: options.site, email: got.email, token: got.token, signedInAt: Date.now() });
+        console.log(`Signed in to ${options.site} as ${got.email || "your account"}.`);
+        return 0;
+    }
     const email = options.email || (await ask("Email: "));
     if (!email) {
         console.error("nixamp: no email given");
@@ -148,9 +327,129 @@ export async function login(argv) {
     console.log(`Signed in to ${options.site} as ${email}.`);
     return 0;
 }
+/** The address a token belongs to, or null if the site will not have it. */
+export async function accountFor(site, token, send) {
+    try {
+        const answer = await send(`${site}/api/v1/auth/me`, { headers: { authorization: `Bearer ${token}` } });
+        if (!answer.ok)
+            return null;
+        const body = (await answer.json());
+        return body.account?.email ?? "";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Which way in to use.
+ *
+ * The menu only appears where it can be answered: a pipe gets the flow it has
+ * always had, so a script that feeds an address and a password still works.
+ * Null means what was asked for is not on offer here.
+ */
+export async function chooseWay(ways, options) {
+    if (options.with) {
+        return ways.providers.some((provider) => provider.id === options.with) ? options.with : null;
+    }
+    // Asking for the browser without naming a provider: the page will offer
+    // them, and a browser that is already signed in can approve on the spot.
+    if (options.device)
+        return ways.device ? "device" : null;
+    // Naming an address is asking for the password flow by implication.
+    if (!ways.device || options.email || !process.stdin.isTTY)
+        return "password";
+    if (ways.providers.length === 0)
+        return "password";
+    console.log("How would you like to sign in?");
+    ways.providers.forEach((provider, index) => console.log(`  ${index + 1}) ${provider.name}`));
+    console.log(`  ${ways.providers.length + 1}) Email and password`);
+    const typed = await ask(`Choose [1]: `);
+    const picked = typed === "" ? 1 : Number(typed);
+    if (!Number.isInteger(picked) || picked < 1 || picked > ways.providers.length + 1) {
+        console.log("Not one of those, so: email and password.");
+        return "password";
+    }
+    return picked === ways.providers.length + 1 ? "password" : (ways.providers[picked - 1]?.id ?? "password");
+}
+const day = (at) => (at ? new Date(at).toISOString().slice(0, 10) : "never");
+/**
+ * `nixamp token create|list|revoke`, which is how a machine that cannot sign
+ * in gets to be signed in. The token is shown once, at creation, because the
+ * server keeps only its hash and has nothing to show a second time.
+ */
+export async function tokens(argv, fetcher = fetch) {
+    const session = readSession();
+    if (session === null) {
+        console.error("nixamp: not signed in. Try `nixamp login`.");
+        return 1;
+    }
+    const [command = "list", ...rest] = argv;
+    const where = `${session.site}/api/v1/auth/tokens`;
+    const headers = { authorization: `Bearer ${session.token}`, "content-type": "application/json" };
+    try {
+        if (command === "create" || command === "new" || command === "add") {
+            const nameAt = rest.indexOf("--name");
+            const name = (nameAt === -1 ? rest.find((a) => !a.startsWith("-")) : rest[nameAt + 1]) ?? "";
+            const answer = await fetcher(where, { method: "POST", headers, body: JSON.stringify({ name }) });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok || !body.token) {
+                console.error(`nixamp: ${body.error ?? `could not make a token (${answer.status})`}`);
+                return 1;
+            }
+            console.log(body.token);
+            console.error("");
+            console.error("Keep it somewhere safe: this is the only time it is shown.");
+            console.error("Use it with NIXAMP_TOKEN=... or `nixamp login --token ...`.");
+            return 0;
+        }
+        if (command === "revoke" || command === "rm" || command === "delete") {
+            const id = rest.find((a) => !a.startsWith("-")) ?? "";
+            if (!id) {
+                console.error("nixamp: which token? `nixamp token list` shows their ids.");
+                return 64;
+            }
+            const answer = await fetcher(`${where}/${encodeURIComponent(id)}`, { method: "DELETE", headers });
+            if (!answer.ok) {
+                console.error(`nixamp: ${answer.status === 404 ? "no token with that id" : "could not revoke it"}`);
+                return 1;
+            }
+            console.log(`Revoked ${id}.`);
+            return 0;
+        }
+        if (command === "list" || command === "ls") {
+            const answer = await fetcher(where, { headers });
+            const body = (await answer.json().catch(() => ({})));
+            if (!answer.ok) {
+                console.error(`nixamp: ${body.error ?? `could not list them (${answer.status})`}`);
+                return 1;
+            }
+            const list = body.tokens ?? [];
+            if (list.length === 0) {
+                console.log("No tokens. `nixamp token create --name ci` makes one.");
+                return 0;
+            }
+            for (const token of list) {
+                console.log(`${token.id}  ${day(token.createdAt)}  last used ${day(token.lastUsedAt)}  ${token.name}`);
+            }
+            return 0;
+        }
+        console.error(`nixamp: no such token command: ${command}`);
+        return 64;
+    }
+    catch (error) {
+        console.error(`nixamp: could not reach ${session.site}: ${error.message}`);
+        return 69;
+    }
+}
 export function logout() {
     const session = readSession();
     clearSession();
+    if (process.env["NIXAMP_TOKEN"]) {
+        // Deleting the file would not change anything while this is set, and
+        // saying nothing would leave somebody wondering why they are still in.
+        console.log("nixamp: NIXAMP_TOKEN is set in the environment, so you are still signed in with it.");
+        return 0;
+    }
     console.log(session ? `Signed out of ${session.site}.` : "nixamp: you were not signed in.");
     return 0;
 }

package/dist/tokens.d.ts

@@ -0,0 +1,63 @@
+import type { Account } from "./accounts.ts";
+import type { Queryable } from "./follows.ts";
+/** Prefixed so a leaked token is greppable, and obvious in a log. */
+export declare const TOKEN_PREFIX = "nxa_";
+/** How long a sign-in lasts. Long, because signing in on a television is work. */
+export declare const SESSION_DAYS = 90;
+/** A session ends; a token a person made for a script does not, unless asked. */
+export type TokenKind = "session" | "cli";
+export interface TokenRecord {
+    id: string;
+    name: string;
+    kind: TokenKind;
+    createdAt: number;
+    expiresAt: number | null;
+    lastUsedAt: number | null;
+}
+export interface IssuedToken extends TokenRecord {
+    /** The only time the whole token exists. It is never stored, so never shown twice. */
+    token: string;
+}
+/** Make a token and the two halves it is made of. */
+export declare function mintToken(): {
+    id: string;
+    secret: string;
+    token: string;
+};
+/** Is this one of ours, rather than a JWT from the auth module? */
+export declare function looksLikeToken(value: string): boolean;
+/** Pull the id and the secret back out. Anything malformed is not a token. */
+export declare function splitToken(value: string): {
+    id: string;
+    secret: string;
+} | null;
+export declare function hashSecret(secret: string): string;
+export interface IssueOptions {
+    account: Account;
+    kind: TokenKind;
+    /** What it is for, shown by `nixamp token list`. */
+    name?: string;
+    /** Milliseconds from now. Null never expires, which is the point of a CLI token. */
+    ttlMs?: number | null;
+}
+export declare class Tokens {
+    private readonly db;
+    private readonly now;
+    private ready;
+    constructor(db: Queryable, now?: () => number);
+    /**
+     * 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.
+     */
+    private ensure;
+    issue(options: IssueOptions): Promise<IssuedToken>;
+    /** The account a token belongs to, or null for one this server will not accept. */
+    verify(value: string): Promise<Account | null>;
+    /** Everything one account holds, newest first. Secrets are not in the table to leak. */
+    list(userId: string, kind?: TokenKind): Promise<TokenRecord[]>;
+    /** Scoped to the owner, so an id from somebody else's list revokes nothing. */
+    revoke(userId: string, id: string): Promise<boolean>;
+    /** Signing out of one place should not sign you out of the build server. */
+    revokeToken(value: string): Promise<boolean>;
+}