@wirecat/max-cli 0.0.0 → 0.43.0

package/dist/session/browser.js

@@ -0,0 +1,321 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "@wirecat/cli-core";
+import qrcode from "qrcode-generator";
+export const realBrowser = {
+    open: (url) => openUrl(url),
+    chromiumToken: (options) => tokenFromChromium(options),
+};
+const WEB_MAX = "https://web.max.ru/";
+const AUTH_KEY = "__oneme_auth";
+/**
+ * The QR page, served from `127.0.0.1` rather than written to a file: a browser installed as a
+ * snap cannot read our temporary directory, and a file would leave the link on disk. The path is
+ * random, so another local user guessing the port finds nothing.
+ */
+export const serveQrPage = async (link) => {
+    const path = `/${randomBytes(16).toString("hex")}`;
+    const code = qrcode(0, "M");
+    code.addData(link);
+    code.make();
+    const page = qrHtml(code.createSvgTag({ cellSize: 8, margin: 4, scalable: true }));
+    const server = createServer((request, response) => {
+        if (request.url !== path) {
+            response.writeHead(404).end();
+            return;
+        }
+        response
+            .writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+        })
+            .end(page);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const { port } = server.address();
+    return {
+        url: `http://127.0.0.1:${port}${path}`,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+};
+const qrHtml = (svg) => `<!doctype html>
+<html lang="ru"><head><meta charset="utf-8"><title>MAX — вход</title>
+<style>body{font-family:system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;margin:0;background:#fff;color:#111}
+main{text-align:center;max-width:22rem}svg{width:18rem;height:18rem}</style></head>
+<body><main>${svg}<p>Отсканируйте код приложением MAX на телефоне. Код действует около двух минут.</p>
+<p>После входа эту вкладку можно закрыть.</p></main></body></html>`;
+export const openUrl = async (url) => {
+    refuseInTests();
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: "ignore", detached: true, windowsHide: true });
+        child.once("error", () => reject(new CliError("configuration_error", "no browser could be opened here — use `session start token`")));
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+};
+/**
+ * Chrome, Chromium, Edge or Brave — any browser that speaks the DevTools protocol. `MAX_BROWSER`
+ * names another. A snap build is skipped: it keeps its own `/tmp`, so the profile we hand it would
+ * land where we cannot delete it.
+ */
+export const findChromium = () => {
+    const named = process.env.MAX_BROWSER;
+    if (named)
+        return named;
+    if (process.platform === "darwin") {
+        return [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+            "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+        ].find((path) => existsSync(path));
+    }
+    if (process.platform === "win32") {
+        const roots = [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA];
+        const apps = [
+            "Google\\Chrome\\Application\\chrome.exe",
+            "Microsoft\\Edge\\Application\\msedge.exe",
+            "BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+        ];
+        return apps
+            .flatMap((app) => roots.filter((root) => root !== undefined).map((root) => join(root, app)))
+            .find(existsSync);
+    }
+    const names = [
+        "google-chrome",
+        "google-chrome-stable",
+        "chromium",
+        "chromium-browser",
+        "microsoft-edge",
+        "microsoft-edge-stable",
+        "brave-browser",
+    ];
+    const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    for (const name of names) {
+        for (const dir of dirs) {
+            const path = join(dir, name);
+            if (existsSync(path) && !realpathSync(path).startsWith("/snap/"))
+                return path;
+        }
+    }
+    return undefined;
+};
+/**
+ * web.max.ru logs itself in — it asks MAX for the QR code, or sends the SMS — in a real browser with
+ * a profile of its own, and we read the token it stores once it has one. MAX sees its own web
+ * client do the login, not our socket.
+ *
+ * ⚠ The profile holds a live session, so it is deleted on every way out: success, a closed window,
+ * `--timeout`, Ctrl-C.
+ */
+export const tokenFromChromium = async ({ track, waitMs, }) => {
+    refuseInTests();
+    const binary = findChromium();
+    if (!binary) {
+        throw new CliError("configuration_error", "no Chrome, Chromium, Edge or Brave found — set MAX_BROWSER to one, or use `session start qr`");
+    }
+    const profile = mkdtempSync(join(tmpdir(), "max-login-"));
+    // A pipe, not `--remote-debugging-port`: a port on 127.0.0.1 lets any local user read the token
+    // while the window is open. Chrome reads commands on fd 3 and answers on fd 4.
+    const child = spawn(binary, [`--user-data-dir=${profile}`, "--remote-debugging-pipe", "--no-first-run", "--no-default-browser-check", WEB_MAX], { stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"] });
+    const browser = new ChromiumSession(child, profile);
+    track(browser);
+    const stopSignals = closeOnSignal(browser);
+    try {
+        return await browser.waitForToken(waitMs);
+    }
+    finally {
+        stopSignals();
+        await browser.close();
+    }
+};
+export class ChromiumSession {
+    #child;
+    #profile;
+    #devtools;
+    #exited;
+    #graceMs;
+    #pollMs;
+    #page;
+    #closing;
+    constructor(child, profile, graceMs = 5_000, pollMs = 1_000) {
+        this.#child = child;
+        this.#profile = profile;
+        this.#graceMs = graceMs;
+        this.#pollMs = pollMs;
+        this.#devtools = new DevToolsPipe(child);
+        this.#exited = new Promise((resolve) => {
+            child.once("exit", () => resolve());
+            child.once("error", () => resolve());
+        });
+    }
+    async waitForToken(waitMs) {
+        const deadline = Date.now() + waitMs;
+        let running = true;
+        void this.#exited.then(() => {
+            running = false;
+        });
+        while (Date.now() < deadline) {
+            if (!running)
+                throw new CliError("cancelled", "the browser was closed before the login finished");
+            const token = await this.#storedToken().catch(() => undefined);
+            if (token)
+                return token;
+            await delay(this.#pollMs);
+        }
+        throw new CliError("timeout", `nobody logged in within ${Math.round(waitMs / 60_000)} minutes`);
+    }
+    close() {
+        this.#closing ??= this.#shutdown();
+        return this.#closing;
+    }
+    async #shutdown() {
+        // Chrome writes to the profile while it shuts down; removing it first leaves half of it behind.
+        await this.#devtools.send("Browser.close").catch(() => undefined);
+        const exited = await Promise.race([this.#exited.then(() => true), delay(this.#graceMs).then(() => false)]);
+        if (!exited && this.#child.pid !== undefined) {
+            this.#child.kill();
+            await Promise.race([this.#exited, delay(2_000)]);
+        }
+        rmSync(this.#profile, { recursive: true, force: true, maxRetries: 3 });
+    }
+    async #storedToken() {
+        const { targetInfos } = await this.#devtools.send("Target.getTargets");
+        const page = (Array.isArray(targetInfos) ? targetInfos : []).find((target) => target?.type === "page" && typeof target.url === "string" && target.url.startsWith(WEB_MAX));
+        if (typeof page?.targetId !== "string")
+            return undefined;
+        if (this.#page?.targetId !== page.targetId) {
+            const { sessionId } = await this.#devtools.send("Target.attachToTarget", {
+                targetId: page.targetId,
+                flatten: true,
+            });
+            this.#page = { targetId: page.targetId, sessionId };
+        }
+        const sessionId = this.#page?.sessionId;
+        if (typeof sessionId !== "string")
+            return undefined;
+        const result = await this.#devtools.send("Runtime.evaluate", { expression: `localStorage.getItem(${JSON.stringify(AUTH_KEY)})`, returnByValue: true }, sessionId);
+        const stored = result?.result?.value;
+        return typeof stored === "string" ? tokenIn(stored) : undefined;
+    }
+}
+/** The DevTools protocol over Chrome's pipe: JSON messages, each ended by a NUL byte. */
+class DevToolsPipe {
+    #input;
+    #waiting = new Map();
+    #next = 0;
+    #buffer = "";
+    constructor(child) {
+        this.#input = child.stdio[3];
+        const output = child.stdio[4];
+        // A pipe that breaks with no listener kills the process (HANDOFF bite 16).
+        this.#input?.on("error", () => { });
+        output?.on("error", () => { });
+        output?.setEncoding("utf8");
+        output?.on("data", (chunk) => {
+            this.#buffer += chunk;
+            for (let end = this.#buffer.indexOf("\0"); end >= 0; end = this.#buffer.indexOf("\0")) {
+                this.#receive(this.#buffer.slice(0, end));
+                this.#buffer = this.#buffer.slice(end + 1);
+            }
+        });
+        child.once("exit", () => this.#failAll(new Error("the browser exited")));
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: see above.
+    send(method, params = {}, sessionId) {
+        const input = this.#input;
+        if (!input || input.destroyed)
+            return Promise.reject(new Error("the browser has no DevTools pipe"));
+        const id = ++this.#next;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#waiting.delete(id);
+                reject(new Error("the browser did not answer"));
+            }, 5_000);
+            this.#waiting.set(id, { resolve, reject, timer });
+            input.write(`${JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })}\0`);
+        });
+    }
+    #receive(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const waiting = typeof message.id === "number" ? this.#waiting.get(message.id) : undefined;
+        if (!waiting)
+            return;
+        clearTimeout(waiting.timer);
+        this.#waiting.delete(message.id);
+        if (message.error)
+            waiting.reject(new Error(String(message.error.message ?? "DevTools refused")));
+        else
+            waiting.resolve(message.result ?? {});
+    }
+    #failAll(error) {
+        for (const { reject, timer } of this.#waiting.values()) {
+            clearTimeout(timer);
+            reject(error);
+        }
+        this.#waiting.clear();
+    }
+}
+/**
+ * The stored value is JSON holding the token, or the token itself — which one is not measured yet.
+ * Either way nothing here prints it.
+ */
+export const tokenIn = (stored) => {
+    try {
+        const parsed = JSON.parse(stored);
+        if (typeof parsed === "object" && parsed !== null && "token" in parsed) {
+            const token = parsed.token;
+            return typeof token === "string" && token !== "" ? token : undefined;
+        }
+        return typeof parsed === "string" && parsed !== "" ? parsed : undefined;
+    }
+    catch {
+        return stored === "" ? undefined : stored;
+    }
+};
+/**
+ * Node's default Ctrl-C exits without running a `finally`, which would leave the browser open and
+ * its logged-in profile on disk. Returns the function that removes the handlers again.
+ */
+const closeOnSignal = (closeable) => {
+    const onSignal = () => {
+        void closeable.close().finally(() => process.exit(130));
+    };
+    // `on`, not `once`: a second Ctrl-C during the shutdown would otherwise exit before the profile goes.
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    return () => {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    };
+};
+const refuseInTests = () => {
+    if (process.env.MAX_TEST_SANDBOX)
+        throw new Error("a test reached the real browser — inject BrowserDoors");
+};
+//# sourceMappingURL=browser.js.map

package/dist/session/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/session/browser.ts"],"names":[],"mappings":"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"}

package/dist/session/handshake.d.ts

@@ -0,0 +1,57 @@
+import type { Invoke } from "../generated/client.generated.js";
+import type { Payload } from "../protocol/frame.js";
+export interface SessionOptions {
+    token: string;
+    deviceId: string;
+    /** How many chats LOGIN should return with the profile. The specification caps it at 100. */
+    chatsCount?: number;
+    /**
+     * The `time` the previous login answered with, or `0` for "send me everything".
+     *
+     * **The four markers are moments, not flags** — measured 2026-09-20. MAX returns only what
+     * changed in each collection since the one given, so a stored marker is the difference between
+     * re-fetching every chat and every contact on every invocation and receiving the handful that
+     * moved. Where it is kept, and why the merge and the marker share a transaction, is
+     * `docs/dev/architecture/session.md`.
+     *
+     * **Only `contactsSync` carries it** — correction 2026-09-25: this said all four carry the same
+     * value, measured harmless over JSON (`NEED-103`). Over the binary protocol MAX refused a login
+     * with the time in all four (`proto.payload`, `FIND-162`), and web.max.ru sends a 64-bit time in
+     * `contactsSync` alone, small numbers in the other three. We send 0 there.
+     */
+    sync?: number;
+    /**
+     * What a web tab sends when the same page logs in again (`MAX-51`, recorded 2026-09-25): the
+     * previous login's `time`, its `config.hash`, and in `chatsSync` the newest chat event it has
+     * seen. MAX then answers only the chats that changed. `max serve` alone logs in again.
+     */
+    resume?: Resume;
+}
+export interface Resume {
+    lastLogin: number;
+    chatsSync: number;
+    configHash: string;
+}
+/**
+ * How many chats LOGIN is asked for — the web tab's 15, with the rest read by one `CHATS_LIST`
+ * right after (`MAX-53`, captured 2026-09-25). MAX answers the newest that many, newest first (`FIND-80`).
+ */
+export declare const LOGIN_CHATS = 15;
+/**
+ * INIT then LOGIN, in that order, before anything else will be answered
+ * (`max-api-docs/protocol/auth.md`).
+ *
+ * **Handwritten, and staying that way** (`REQUIREMENTS.md` §9): a socket problem has to be
+ * debuggable without reading a generator. What the specification supplies is the two payloads, so
+ * the field names have one home rather than two.
+ *
+ * It lives here rather than under `protocol/` because it is not transport: the transport moves
+ * frames and does not care who is asking. Establishing a session is this layer's job.
+ *
+ * **It is handed the client's own `invoke` rather than the socket**, so INIT and LOGIN are built,
+ * checked and reported exactly like every other request. They were not, until 2026-09-20: a
+ * diagnostic hook in `MaxClient` saw nothing of the two requests every single invocation makes,
+ * and `max chats list` answers from the LOGIN response without sending anything else.
+ */
+export declare const startSession: (invoke: Invoke, { token, deviceId, chatsCount, sync, resume }: SessionOptions) => Promise<Payload>;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/session/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/session/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAA;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAInD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,KAAK,CAAA;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,WACf,MAAM,iDACmD,cAAc,KAC9E,OAAO,CAAC,OAAO,CAgBjB,CAAA"}

package/dist/session/handshake.js

@@ -0,0 +1,40 @@
+import { WEB_USER_AGENT } from "../spec/identity.js";
+import { sessionInit, sessionLogin } from "../spec/operations/session.js";
+/**
+ * How many chats LOGIN is asked for — the web tab's 15, with the rest read by one `CHATS_LIST`
+ * right after (`MAX-53`, captured 2026-09-25). MAX answers the newest that many, newest first (`FIND-80`).
+ */
+export const LOGIN_CHATS = 15;
+/**
+ * INIT then LOGIN, in that order, before anything else will be answered
+ * (`max-api-docs/protocol/auth.md`).
+ *
+ * **Handwritten, and staying that way** (`REQUIREMENTS.md` §9): a socket problem has to be
+ * debuggable without reading a generator. What the specification supplies is the two payloads, so
+ * the field names have one home rather than two.
+ *
+ * It lives here rather than under `protocol/` because it is not transport: the transport moves
+ * frames and does not care who is asking. Establishing a session is this layer's job.
+ *
+ * **It is handed the client's own `invoke` rather than the socket**, so INIT and LOGIN are built,
+ * checked and reported exactly like every other request. They were not, until 2026-09-20: a
+ * diagnostic hook in `MaxClient` saw nothing of the two requests every single invocation makes,
+ * and `max chats list` answers from the LOGIN response without sending anything else.
+ */
+export const startSession = async (invoke, { token, deviceId, chatsCount = LOGIN_CHATS, sync = 0, resume }) => {
+    await invoke(sessionInit, { userAgent: WEB_USER_AGENT, deviceId });
+    return await invoke(sessionLogin, {
+        token,
+        // A script reading is not a person looking; see the specification for why this is never true.
+        interactive: false,
+        chatsCount,
+        ...(resume ? { lastLogin: resume.lastLogin } : {}),
+        chatsSync: resume?.chatsSync ?? 0,
+        contactsSync: sync,
+        // -1 as the tab sends it; presence pushes (132) follow, and nothing here answers them, as the tab does not.
+        presenceSync: -1,
+        draftsSync: 0,
+        ...(resume ? { configHash: resume.configHash } : {}),
+    });
+};
+//# sourceMappingURL=handshake.js.map

package/dist/session/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/session/handshake.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAoCzE;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAA;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,MAAc,EACd,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,GAAG,WAAW,EAAE,IAAI,GAAG,CAAC,EAAE,MAAM,EAAkB,EAC7D,EAAE;IACpB,MAAM,MAAM,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAA;IAElE,OAAO,MAAM,MAAM,CAAC,YAAY,EAAE;QAChC,KAAK;QACL,8FAA8F;QAC9F,WAAW,EAAE,KAAK;QAClB,UAAU;QACV,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,CAAC;QACjC,YAAY,EAAE,IAAI;QAClB,4GAA4G;QAC5G,YAAY,EAAE,CAAC,CAAC;QAChB,UAAU,EAAE,CAAC;QACb,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrD,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/session/login.d.ts

@@ -0,0 +1,20 @@
+import type { WireClient } from "../generated/client.generated.js";
+export interface SecondFactor {
+    /** Asked only when the account has a cloud password; `again` after a wrong one. */
+    askPassword: (hint: string | undefined, again: boolean) => Promise<string>;
+}
+export interface QrLogin extends SecondFactor {
+    /** Put the code where a phone can scan it. Resolves once it is shown, not once it is scanned. */
+    show: (link: string) => Promise<void>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The login MAX's web client does itself when it shows a QR code: ask for a code, wait until a phone
+ * approves it, then exchange it for a token. Shapes from PyMax 2.4.1 (`auth/qr.py`), not measured.
+ *
+ * One code per run: an expired one is an error rather than a fresh code, so a person who walked
+ * away does not come back to a loop that has been asking MAX for codes all along.
+ */
+export declare const tokenByQr: (wire: WireClient, { show, askPassword, now, sleep }: QrLogin) => Promise<string>;
+//# sourceMappingURL=login.d.ts.map

package/dist/session/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/session/login.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AAGlE,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC3E;AAED,MAAM,WAAW,OAAQ,SAAQ,YAAY;IAC3C,iGAAiG;IACjG,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,SACd,UAAU,qCACsC,OAAO,KAC5D,OAAO,CAAC,MAAM,CAiBhB,CAAA"}

package/dist/session/login.js

@@ -0,0 +1,66 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "@wirecat/cli-core";
+/**
+ * The login MAX's web client does itself when it shows a QR code: ask for a code, wait until a phone
+ * approves it, then exchange it for a token. Shapes from PyMax 2.4.1 (`auth/qr.py`), not measured.
+ *
+ * One code per run: an expired one is an error rather than a fresh code, so a person who walked
+ * away does not come back to a loop that has been asking MAX for codes all along.
+ */
+export const tokenByQr = async (wire, { show, askPassword, now = Date.now, sleep = delay }) => {
+    const code = await wire.login.qrRequest({});
+    const trackId = text(code.trackId, "trackId");
+    const expiresAt = typeof code.expiresAt === "number" ? code.expiresAt : now() + 120_000;
+    const interval = typeof code.pollingInterval === "number" ? code.pollingInterval : 5_000;
+    await show(text(code.qrLink, "qrLink"));
+    while (now() < expiresAt) {
+        const answer = await wire.login.qrStatus({ trackId });
+        if (record(answer.status)?.loginAvailable === true) {
+            return await tokenFrom(wire, await wire.login.byQr({ trackId }), askPassword);
+        }
+        await sleep(interval);
+    }
+    throw new CliError("timeout", "the QR code expired before it was scanned — run the command again");
+};
+/**
+ * A few attempts, not PyMax's endless loop, and not one: a mistyped password would otherwise cost a
+ * fresh QR code. Only a person at a terminal gets here, so asking again cannot hang a script.
+ */
+const tokenFrom = async (wire, answer, askPassword) => {
+    const issued = loginToken(answer);
+    if (issued)
+        return issued;
+    const challenge = record(answer.passwordChallenge);
+    if (!challenge)
+        throw new CliError("authentication_error", "MAX confirmed the login but sent no token");
+    const trackId = text(challenge.trackId, "trackId");
+    const hint = typeof challenge.hint === "string" && challenge.hint !== "" ? challenge.hint : undefined;
+    for (let attempt = 1; attempt <= PASSWORD_ATTEMPTS; attempt++) {
+        const password = await askPassword(hint, attempt > 1);
+        if (!password)
+            throw new CliError("validation_error", "no password given");
+        const checked = await wire.login.password({ trackId, password }).catch((error) => {
+            if (wrongPassword(error))
+                return undefined;
+            throw error;
+        });
+        const token = checked && loginToken(checked);
+        if (token)
+            return token;
+    }
+    throw new CliError("authentication_error", `the password was wrong ${PASSWORD_ATTEMPTS} times — run the command again`);
+};
+const PASSWORD_ATTEMPTS = 3;
+// Measured 2026-09-24: a wrong cloud password is refused as `password2fa.wrong`.
+const wrongPassword = (error) => error instanceof CliError && /password2fa\.wrong/.test(error.message);
+const loginToken = (answer) => {
+    const token = record(record(answer.tokenAttrs)?.LOGIN)?.token;
+    return typeof token === "string" && token !== "" ? token : undefined;
+};
+const text = (value, field) => {
+    if (typeof value === "string" && value !== "")
+        return value;
+    throw new CliError("provider_error", `MAX's answer had no ${field}`);
+};
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+//# sourceMappingURL=login.js.map

package/dist/session/login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/session/login.ts"],"names":[],"mappings":"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"}

package/dist/session/prompt.d.ts

@@ -0,0 +1,2 @@
+export { readSecret, type SecretInput } from "@wirecat/cli-messaging";
+//# sourceMappingURL=prompt.d.ts.map

package/dist/session/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/session/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/session/prompt.js

@@ -0,0 +1,2 @@
+export { readSecret } from "@wirecat/cli-messaging";
+//# sourceMappingURL=prompt.js.map

package/dist/session/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/session/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,wBAAwB,CAAA"}

package/dist/session/qr-terminal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A QR code as text, two modules per character cell with half blocks, so it fits a terminal
+ * without being twice as tall as it is wide. `width` is in columns, for deciding whether it fits.
+ */
+export declare const terminalQr: (link: string) => {
+    text: string;
+    width: number;
+};
+//# sourceMappingURL=qr-terminal.d.ts.map

package/dist/session/qr-terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-terminal.d.ts","sourceRoot":"","sources":["../../src/session/qr-terminal.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAwBtE,CAAA"}

package/dist/session/qr-terminal.js

@@ -0,0 +1,34 @@
+import qrcode from "qrcode-generator";
+const QUIET_ZONE = 4;
+// Dark modules on a light ground whatever the terminal's theme: a phone camera reads an inverted
+// code unreliably, so the colours are forced even under NO_COLOR.
+const BLACK_ON_WHITE = "\x1b[30;107m";
+const RESET = "\x1b[0m";
+/**
+ * A QR code as text, two modules per character cell with half blocks, so it fits a terminal
+ * without being twice as tall as it is wide. `width` is in columns, for deciding whether it fits.
+ */
+export const terminalQr = (link) => {
+    const code = qrcode(0, "M");
+    code.addData(link);
+    code.make();
+    const count = code.getModuleCount();
+    const size = count + QUIET_ZONE * 2;
+    const dark = (row, col) => {
+        const r = row - QUIET_ZONE;
+        const c = col - QUIET_ZONE;
+        return r >= 0 && c >= 0 && r < count && c < count && code.isDark(r, c);
+    };
+    const lines = [];
+    for (let row = 0; row < size; row += 2) {
+        let line = "";
+        for (let col = 0; col < size; col++) {
+            const top = dark(row, col);
+            const bottom = row + 1 < size && dark(row + 1, col);
+            line += top && bottom ? "█" : top ? "▀" : bottom ? "▄" : " ";
+        }
+        lines.push(`${BLACK_ON_WHITE}${line}${RESET}`);
+    }
+    return { text: lines.join("\n"), width: size };
+};
+//# sourceMappingURL=qr-terminal.js.map

package/dist/session/qr-terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-terminal.js","sourceRoot":"","sources":["../../src/session/qr-terminal.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,kBAAkB,CAAA;AAErC,MAAM,UAAU,GAAG,CAAC,CAAA;AACpB,iGAAiG;AACjG,kEAAkE;AAClE,MAAM,cAAc,GAAG,cAAc,CAAA;AACrC,MAAM,KAAK,GAAG,SAAS,CAAA;AAEvB;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAmC,EAAE;IAC1E,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,IAAI,CAAC,IAAI,EAAE,CAAA;IAEX,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;IACnC,MAAM,IAAI,GAAG,KAAK,GAAG,UAAU,GAAG,CAAC,CAAA;IACnC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,GAAW,EAAE,EAAE;QACxC,MAAM,CAAC,GAAG,GAAG,GAAG,UAAU,CAAA;QAC1B,MAAM,CAAC,GAAG,GAAG,GAAG,UAAU,CAAA;QAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACxE,CAAC,CAAA;IAED,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACvC,IAAI,IAAI,GAAG,EAAE,CAAA;QACb,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;YACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;YAC1B,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;YACnD,IAAI,IAAI,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;QAC9D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,cAAc,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAA;IAChD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AAChD,CAAC,CAAA"}