@3minapi/cli 0.22.1 → 0.24.0

package/README.md

@@ -20,19 +20,22 @@ npm install -g @3minapi/cli
 
 ## Quick start
 
-1. **Create a host token** on the dashboard: [3minapi.com/dashboard/tasks/local](https://3minapi.com/dashboard/tasks/local).
-   It is shown once.
-2. **Log in** — the prompt is masked; the token is saved only on this machine.
+1. **Log in** — prints an approval link and opens it in your browser. Approve it while signed in to 3Min API;
+   the token is sent straight to this machine and saved there. Over SSH or without a display it prints a link and a
+   code to approve on another device (`--device` forces this).
    ```sh
    3minapi login
    ```
-3. **Create the project** (default `~/3minapi`) and a worker:
+   For CI, create a host token on the dashboard
+   ([3minapi.com/dashboard/tasks/local](https://3minapi.com/dashboard/tasks/local)) and pipe it in:
+   `echo "$TOKEN" | 3minapi login --with-token`.
+2. **Create the project** (default `~/3minapi`) and a worker:
    ```sh
    3minapi init
    3minapi worker new hello
    3minapi worker run hello --input '{"message":"hi"}'   # runs locally, no API calls
    ```
-4. **Start the host** — registers the workers and runs tasks until stopped:
+3. **Start the host** — registers the workers and runs tasks until stopped:
    ```sh
    3minapi start            # or: 3minapi start --detach, then 3minapi stop
    ```
@@ -65,7 +68,8 @@ printed by:
 3minapi guide
 ```
 
-Every command takes `--json` for machine-readable output. Log in yourself — never paste the host token into a chat.
+Every command takes `--json` for machine-readable output. An agent may run `3minapi login` and pass the printed
+link (and code) to you to approve — the host token itself never belongs in a chat.
 
 ## Update
 

package/dist/cli.js

@@ -4,6 +4,7 @@ import { commands } from "./commands/index.js";
 import { loadConfig } from "./core/config.js";
 import { describeError, errorDocument } from "./core/error-report.js";
 import { BIN, CliError, ExitCode, UsageError } from "./core/domain/index.js";
+import { openBrowser } from "./core/open-browser.js";
 import { Output } from "./core/output.js";
 import { resolveDirs } from "./core/paths.js";
 import { resolveProject, writeProjectRecord } from "./core/project.js";
@@ -105,6 +106,7 @@ async function dispatch(argv, io, out) {
         now: io.now ?? Date.now,
         signal: io.signal ?? new AbortController().signal,
         claimInterrupt: () => io.claimInterrupt?.(),
+        openBrowser: io.openBrowser ?? ((url) => openBrowser(url, io.platform)),
         chdir: io.chdir ?? ((dir) => process.chdir(dir)),
         loadConfig: () => {
             const config = loadConfig({

package/dist/commands/auth.js

@@ -1,7 +1,12 @@
 import { statSync } from 'node:fs';
+import { hostname } from 'node:os';
 import path from 'node:path';
-import { deleteHostToken, isHostToken, resolveHostToken, saveHostToken } from "../core/credentials.js";
-import { BIN, ENV, ExitCode, HOST_TOKEN_PREFIX, LOCAL_SERVER_TOKEN_FILE, MONTH_MS, StopError, UsageError, builtinResultsName, isReservedWorkerName } from "../core/domain/index.js";
+import { credentialsPath, deleteHostToken, isHostToken, resolveHostToken, saveHostToken } from "../core/credentials.js";
+import { BIN, CODE_CHALLENGE_METHOD, CliError, ConfigError, ENV, ExitCode, HOST_TOKEN_PREFIX, LOGIN_REQUEST_EXPIRES_S, LOCAL_SERVER_TOKEN_FILE, MONTH_MS, StopError, UsageError, builtinResultsName, isOpenableLoginUrl, isReservedWorkerName, loginResultUrl, normalizeUserCode } from "../core/domain/index.js";
+import { chooseFlow, loginClient } from "../core/login/client-info.js";
+import { LOGIN_DENIED_MESSAGE, LOGIN_EXPIRED_MESSAGE, pollDeviceToken } from "../core/login/device.js";
+import { LoopbackUnavailable, startCallbackServer } from "../core/login/loopback.js";
+import { createPkce, createState } from "../core/login/pkce.js";
 import { readAllStdin, readSecret } from "../core/prompt.js";
 import { readRunner, runnerMode } from "../core/host/runner-lock.js";
 import { readDashboard } from "../modules/dashboard/lock.js";
@@ -15,9 +20,9 @@ import { HOST_META, cacheHostIdentity, hostChangedWarning } from "../modules/wor
 import { ResultStore, resultsDbBytes, resultsDbPath } from "../modules/workers/results/store.js";
 import { workerFiles } from "../modules/workers/workers.js";
 import { parseSettings } from "../modules/workers/repeat-scheduler.js";
-import { ApiError } from "../core/api.js";
+import { ApiClient, ApiError, userAgent } from "../core/api.js";
 import { client, noticeUpdate, workersPath } from "./common.js";
-import { readLatest, updateInfo } from "../core/update-notice.js";
+import { readLatest, rememberLatest, updateInfo } from "../core/update-notice.js";
 function nextAfterLogin(ctx, config) {
     const root = config.projectRoot;
     if (!root) {
@@ -33,77 +38,409 @@ function nextAfterLogin(ctx, config) {
 }
 export const login = {
     name: 'login',
-    summary: 'Save the host token issued on the 3Min API dashboard',
-    usage: '[--with-token]',
-    description: 'Prompts for the host token (tm_host_...). Use --with-token to read it from stdin instead,\n' +
-        'e.g. in CI: echo "$TOKEN" | 3minapi login --with-token\n' +
+    summary: 'Log this PC in to 3Min API by approving it in the browser',
+    usage: '[--device | --loopback] [--no-browser] [--force] [--paste | --with-token]',
+    description: 'Prints an approval link and waits. Approve it in a browser where you are signed in to 3Min API;\n' +
+        'the host token is then sent straight to this PC and saved — it never appears on screen.\n' +
+        'On this PC the link opens in the browser (loopback). Over SSH, on Linux without a display, or with\n' +
+        '--device, it prints a link and a code to approve on another device (phone, laptop) instead;\n' +
+        '--loopback keeps the same-PC flow there (e.g. a remote shell that forwards the callback port).\n' +
+        'If this PC is already logged in, nothing changes; --force approves again (the token is rotated).\n' +
+        'A token issued on the dashboard still works: --paste prompts for it, --with-token reads it from\n' +
+        'stdin, e.g. in CI: echo "$TOKEN" | 3minapi login --with-token\n' +
         'The token is checked with the server (one API call) before it is saved.',
     options: {
-        'with-token': { type: 'boolean', description: 'Read the token from stdin' }
+        device: {
+            type: 'boolean',
+            description: 'Approve on another device with a code (no browser on this PC)'
+        },
+        loopback: {
+            type: 'boolean',
+            description: 'Use the same-PC flow even over SSH (the callback port must reach your browser)'
+        },
+        browser: {
+            type: 'boolean',
+            negated: true,
+            description: 'Print the approval link without opening a browser'
+        },
+        force: { type: 'boolean', description: 'Approve again even if this PC is already logged in' },
+        paste: { type: 'boolean', description: 'Paste a dashboard-issued token at a masked prompt' },
+        'with-token': { type: 'boolean', description: 'Read a dashboard-issued token from stdin' }
     },
     args: { min: 0, max: 0 },
     async run(ctx) {
-        const { out, env, values } = ctx;
-        let token;
-        if (values['with-token']) {
-            if (ctx.stdin.isTTY) {
-                throw new UsageError(`--with-token reads the token from stdin. Pipe it in: echo "$TOKEN" | ${BIN} login --with-token`);
-            }
-            token = (await readAllStdin(ctx.stdin)).trim();
+        const { values } = ctx;
+        const manual = [values['with-token'], values.paste].filter(Boolean).length;
+        const browserOnly = values.device || values.loopback || values.browser === false || values.force;
+        if (manual > 1 || (manual === 1 && browserOnly)) {
+            throw new UsageError('--with-token and --paste take a token instead of browser approval — use one of them, without --device, --loopback, --no-browser or --force');
         }
-        else {
-            token = (await readSecret(ctx.stdin, out, `Paste your host token (${HOST_TOKEN_PREFIX}...): `)).trim();
+        if (values.device && values.loopback) {
+            throw new UsageError('--device and --loopback choose opposite flows — use one of them');
         }
-        if (!isHostToken(token)) {
-            throw new UsageError(`that is not a host token (expected ${HOST_TOKEN_PREFIX} followed by 48 hex characters)`);
+        if (values.force && envTokenSet(ctx)) {
+            throw new UsageError(`${ENV.token} is set — approving again would revoke the token it holds. Unset it first.`);
         }
-        const session = openSession(ctx);
-        try {
-            let host;
+        if (values['with-token'] || values.paste) {
+            const token = await readManualToken(ctx);
+            const session = openSession(ctx);
             try {
-                host = await client(ctx, session, token).getHost();
+                return await saveVerifiedToken(ctx, session, token, null);
             }
-            catch (err) {
-                if (err instanceof StopError) {
-                    session.logger.warn('login rejected', { reason: err.reason });
-                    throw new StopError(err.reason, `${err.message}\n${stopHint(err.reason)}`, err.resetAt);
-                }
-                throw err;
+            finally {
+                session.close();
             }
-            const file = saveHostToken(ctx.dirs.config, token, ctx.now());
-            clearStop(session);
-            const previous = cacheHostIdentity(session.db, token, host.host, ctx.now());
-            rememberQuota(session, host.quota, ctx.now());
-            session.logger.info('logged in', { host_id: host.host.id, host_name: host.host.name });
-            if (previous !== null) {
-                out.warn(hostChangedWarning(previous, host.host));
-                session.logger.warn('host changed', { previous_host_id: previous, host_id: host.host.id });
+        }
+        const session = openSession(ctx);
+        try {
+            if (!values.force) {
+                const done = await alreadyLoggedIn(ctx, session);
+                if (done !== null)
+                    return done;
             }
-            if (env[ENV.token]) {
-                out.warn(`${ENV.token} is set and takes precedence over the saved token.`);
+            ctx.claimInterrupt();
+            const { issued, replyBrowser } = await browserLogin(ctx, session);
+            try {
+                return await saveVerifiedToken(ctx, session, issued.token, issued, () => replyBrowser('ok'));
+            }
+            finally {
+                replyBrowser('failed');
             }
-            const projectRoot = session.config.projectRoot;
-            out.result({
-                host: host.host,
-                workers: host.workers,
-                quota: host.quota,
-                credentials: file,
-                previousHostId: previous,
-                projectRoot
-            }, [
-                `${out.out.green('logged in')}  ${stripControl(host.host.name)}`,
-                `token saved to ${file}`,
-                quotaLine(out, host, ctx.now()),
-                '',
-                nextAfterLogin(ctx, session.config)
-            ].join('\n'));
-            return ExitCode.Ok;
         }
         finally {
             session.close();
         }
     }
 };
+async function readManualToken(ctx) {
+    let token;
+    if (ctx.values['with-token']) {
+        if (ctx.stdin.isTTY) {
+            throw new UsageError(`--with-token reads the token from stdin. Pipe it in: echo "$TOKEN" | ${BIN} login --with-token`);
+        }
+        token = (await readAllStdin(ctx.stdin)).trim();
+    }
+    else {
+        token = (await readSecret(ctx.stdin, ctx.out, `Paste your host token (${HOST_TOKEN_PREFIX}...): `)).trim();
+    }
+    if (!isHostToken(token)) {
+        throw new UsageError(`that is not a host token (expected ${HOST_TOKEN_PREFIX} followed by 48 hex characters)`);
+    }
+    return token;
+}
+async function alreadyLoggedIn(ctx, session) {
+    let token;
+    try {
+        token = resolveHostToken(ctx.dirs.config, ctx.env);
+    }
+    catch (err) {
+        if (envTokenSet(ctx) || !(err instanceof ConfigError))
+            throw err;
+        ctx.out.warn(`the saved token in ${credentialsPath(ctx.dirs.config)} cannot be used — approving replaces it.`);
+        return null;
+    }
+    if (!token)
+        return null;
+    let host;
+    try {
+        host = await client(ctx, session, token.token).getHost();
+    }
+    catch (err) {
+        if (err instanceof StopError) {
+            if (err.reason === 'host_token_invalid' && token.source === 'env') {
+                throw new StopError(err.reason, `${err.message}\nThe token comes from ${ENV.token}, which overrides a saved login. Unset it (then run '${BIN} login') or set a valid token.`);
+            }
+            if (err.reason === 'host_token_invalid')
+                return null;
+            recordStop(session, err, ctx.now());
+            throw new StopError(err.reason, `${err.message}\n${stopHint(err.reason)}`, err.resetAt);
+        }
+        throw err;
+    }
+    clearStop(session);
+    const previous = cacheHostIdentity(session.db, token.token, host.host, ctx.now());
+    rememberQuota(session, host.quota, ctx.now());
+    if (previous !== null)
+        ctx.out.warn(hostChangedWarning(previous, host.host));
+    const fromEnv = token.source === 'env';
+    ctx.out.result({
+        alreadyLoggedIn: true,
+        confirmed: true,
+        host: host.host,
+        workers: host.workers,
+        quota: host.quota,
+        credentials: token.source === 'file' ? token.location : null,
+        previousHostId: previous,
+        projectRoot: session.config.projectRoot,
+        tokenSource: token.source
+    }, [
+        `${ctx.out.out.green('already logged in')}  ${stripControl(host.host.name)}${fromEnv ? ctx.out.out.dim(` (token from ${ENV.token})`) : ''}`,
+        quotaLine(ctx.out, host, ctx.now()),
+        ctx.out.out.dim(`To log in again (the token is rotated): ${BIN} login --force`)
+    ].join('\n'));
+    return ExitCode.Ok;
+}
+function envTokenSet(ctx) {
+    return (ctx.env[ENV.token] ?? '') !== '';
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NO_BROWSER_REPLY = () => { };
+async function browserLogin(ctx, session) {
+    const apiUrl = session.config.values.apiUrl;
+    const api = new ApiClient({
+        apiUrl,
+        token: '',
+        userAgent: userAgent(ctx.version, ctx.platform),
+        signal: ctx.signal,
+        onServerCli: (cli) => rememberLatest(session.db, cli, ctx.now(), (m, a) => session.logger.debug(m, a))
+    });
+    const info = loginClient(hostname(), ctx.platform, process.arch, ctx.version);
+    let flow = chooseFlow({ device: ctx.values.device === true, loopback: ctx.values.loopback === true }, ctx.env, ctx.platform);
+    session.logger.info('login started', { flow });
+    try {
+        if (flow === 'loopback') {
+            try {
+                return await loopbackLogin(ctx, session, api, info, apiUrl);
+            }
+            catch (err) {
+                if (!(err instanceof LoopbackUnavailable))
+                    throw err;
+                ctx.out.warn(`${err.message} — approving on another device instead.`);
+                flow = 'device';
+            }
+        }
+        return { issued: await deviceLogin(ctx, api, info, apiUrl), replyBrowser: NO_BROWSER_REPLY };
+    }
+    catch (err) {
+        throw loginError(err, ctx.signal);
+    }
+}
+async function loopbackLogin(ctx, session, api, info, apiUrl) {
+    const pkce = createPkce();
+    const state = createState();
+    const server = await startCallbackServer({
+        state,
+        timeoutMs: LOGIN_REQUEST_EXPIRES_S * 1000,
+        signal: ctx.signal
+    });
+    let resultUrl = null;
+    try {
+        const previous = cachedHostId(session);
+        const started = await api.loginAuthorize({
+            client: info,
+            ...(previous ? { previous_host_id: previous } : {}),
+            redirect_port: server.port,
+            state,
+            code_challenge: pkce.challenge,
+            code_challenge_method: CODE_CHALLENGE_METHOD
+        });
+        const url = openableUrl(started.authorize_url, apiUrl);
+        resultUrl = loginResultUrl(started.result_url, url, apiUrl);
+        if (started.result_url !== undefined && resultUrl === null) {
+            session.logger.debug('login result page not used', {});
+        }
+        ctx.out.event({
+            event: 'login_pending',
+            flow: 'loopback',
+            url,
+            expires_in: started.expires_in
+        });
+        ctx.out.info([
+            'Approve this PC in your browser:',
+            `  ${url}`,
+            waitingLine(ctx, started.expires_in),
+            ctx.out.err.dim(`Browser on another device? Press Ctrl+C and run '${BIN} login --device'.`)
+        ].join('\n'));
+        if (ctx.values.browser !== false && !(await ctx.openBrowser(url))) {
+            ctx.out.warn(`could not open a browser — open the link above yourself. If it never returns here, run '${BIN} login --device'.`);
+        }
+        const callback = await server.result;
+        if (callback.kind === 'denied') {
+            server.reply('denied', resultUrl);
+            throw new CliError(LOGIN_DENIED_MESSAGE);
+        }
+        const issued = issuedToken(await api.loginToken({
+            grant_type: 'authorization_code',
+            code: callback.code,
+            code_verifier: pkce.verifier
+        }));
+        return { issued, replyBrowser: (outcome) => server.reply(outcome, resultUrl) };
+    }
+    catch (err) {
+        server.reply('failed', resultUrl);
+        server.close();
+        throw err;
+    }
+}
+async function deviceLogin(ctx, api, info, apiUrl) {
+    const started = await api.loginDevice({ client: info });
+    const base = openableUrl(started.verification_uri, apiUrl);
+    const complete = started.verification_uri_complete === undefined
+        ? null
+        : openableUrl(started.verification_uri_complete, apiUrl);
+    const userCode = typeof started.user_code === 'string' ? normalizeUserCode(started.user_code) : null;
+    const deviceCode = started.device_code;
+    if (userCode === null || typeof deviceCode !== 'string' || deviceCode === '') {
+        throw new CliError(UNEXPECTED_RESPONSE);
+    }
+    ctx.out.event({
+        event: 'login_pending',
+        flow: 'device',
+        url: complete ?? base,
+        verification_uri: base,
+        user_code: userCode,
+        expires_in: started.expires_in
+    });
+    ctx.out.info([
+        'On a device where you are signed in to 3Min API (phone, laptop), open:',
+        `  ${complete ?? base}`,
+        complete === null ? 'and enter the code:' : `or go to ${base} and enter the code:`,
+        `  ${ctx.out.err.bold(userCode)}`,
+        waitingLine(ctx, started.expires_in)
+    ].join('\n'));
+    return issuedToken(await pollDeviceToken({
+        exchange: () => api.loginToken({ grant_type: 'device_code', device_code: deviceCode }),
+        intervalS: started.interval,
+        expiresInS: started.expires_in,
+        signal: ctx.signal
+    }));
+}
+const UNEXPECTED_RESPONSE = 'the server sent a login response this CLI does not understand. Update the CLI, or log in with --paste.';
+function issuedToken(res) {
+    const host = res?.host;
+    if (typeof res?.token !== 'string' ||
+        typeof host?.id !== 'string' ||
+        typeof host.name !== 'string') {
+        throw new CliError(UNEXPECTED_RESPONSE);
+    }
+    return {
+        token: res.token,
+        created: res.created === true,
+        host: { id: host.id, name: host.name }
+    };
+}
+function waitingLine(ctx, expiresInS) {
+    const seconds = typeof expiresInS === 'number' && Number.isFinite(expiresInS) && expiresInS > 0
+        ? Math.min(expiresInS, LOGIN_REQUEST_EXPIRES_S)
+        : LOGIN_REQUEST_EXPIRES_S;
+    const minutes = Math.max(1, Math.round(seconds / 60));
+    return ctx.out.err.dim(`Waiting for approval (expires in ${minutes} min). Approve only if you ran this command yourself.`);
+}
+function openableUrl(url, apiUrl) {
+    const href = isOpenableLoginUrl(url, apiUrl);
+    if (href === null) {
+        throw new CliError('the server returned an approval link this CLI will not open. Check the API URL, or log in with --paste.');
+    }
+    return href;
+}
+function cachedHostId(session) {
+    try {
+        const id = session.db.getMeta(HOST_META.id);
+        return id !== null && UUID.test(id) ? id.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function loginError(err, signal) {
+    if (signal.aborted && !(err instanceof StopError)) {
+        return new CliError('login cancelled.', ExitCode.Interrupted);
+    }
+    if (!(err instanceof ApiError))
+        return err;
+    switch (err.code) {
+        case 'access_denied':
+            return new CliError(LOGIN_DENIED_MESSAGE);
+        case 'expired_token':
+            return new CliError(LOGIN_EXPIRED_MESSAGE);
+        case 'invalid_grant':
+            return new CliError('the approval was not accepted (expired or already used). Run login again.');
+        case 'device_rate_limited':
+            return new CliError('too many login requests from this network. Try again in a few minutes.');
+        case 'service_unavailable':
+            return new CliError(`${err.message}\nRun login again in a moment.`);
+    }
+    if (err.status === 404 && err.code === null) {
+        return new CliError(`this server does not support browser login. Log in with a token from the dashboard instead: ${BIN} login --paste`);
+    }
+    return err;
+}
+async function saveVerifiedToken(ctx, session, token, issued, onSaved = () => { }) {
+    const { out, env } = ctx;
+    if (!isHostToken(token))
+        throw new CliError('the server returned a token in an unexpected format.');
+    let host = null;
+    let unconfirmed = null;
+    try {
+        host = await client(ctx, session, token).getHost();
+    }
+    catch (err) {
+        const rejected = err instanceof StopError && err.reason === 'host_token_invalid';
+        if (issued === null || rejected) {
+            if (err instanceof StopError) {
+                session.logger.warn('login rejected', { reason: err.reason });
+                throw new StopError(err.reason, `${err.message}\n${stopHint(err.reason)}`, err.resetAt);
+            }
+            throw err;
+        }
+        unconfirmed = err;
+    }
+    const file = saveHostToken(ctx.dirs.config, token, ctx.now());
+    onSaved();
+    const identity = host?.host ?? issued.host;
+    const previous = cacheHostIdentity(session.db, token, identity, ctx.now());
+    if (host) {
+        clearStop(session);
+        rememberQuota(session, host.quota, ctx.now());
+    }
+    const created = issued?.created ?? null;
+    session.logger.info('logged in', {
+        host_id: identity.id,
+        host_name: identity.name,
+        confirmed: host !== null,
+        ...(created === null ? {} : { created })
+    });
+    if (previous !== null) {
+        out.warn(hostChangedWarning(previous, identity));
+        session.logger.warn('host changed', { previous_host_id: previous, host_id: identity.id });
+    }
+    if (env[ENV.token]) {
+        out.warn(`${ENV.token} is set and takes precedence over the saved token.`);
+    }
+    if (unconfirmed !== null) {
+        const saved = `logged in as ${stripControl(identity.name)} — token saved to ${file}`;
+        if (unconfirmed instanceof StopError) {
+            recordStop(session, unconfirmed, ctx.now());
+            throw new StopError(unconfirmed.reason, `${saved}, but ${unconfirmed.message}\n${stopHint(unconfirmed.reason)}`, unconfirmed.resetAt);
+        }
+        if (ctx.signal.aborted) {
+            out.warn(`${saved}; the check was cancelled. Run '${BIN} status' to confirm it.`);
+            return ExitCode.Interrupted;
+        }
+        out.warn(`${saved}, but it could not be checked: ${unconfirmed.message}\nRun '${BIN} status' to confirm it.`);
+    }
+    const projectRoot = session.config.projectRoot;
+    const how = created === null ? '' : out.out.dim(created ? ' (new host)' : ' (token rotated)');
+    out.result({
+        alreadyLoggedIn: false,
+        confirmed: host !== null,
+        tokenSource: 'file',
+        host: identity,
+        workers: host?.workers ?? null,
+        quota: host?.quota ?? null,
+        credentials: file,
+        previousHostId: previous,
+        projectRoot,
+        ...(created === null ? {} : { created })
+    }, [
+        `${out.out.green('logged in')}  ${stripControl(identity.name)}${how}`,
+        `token saved to ${file}`,
+        ...(host ? [quotaLine(out, host, ctx.now())] : []),
+        '',
+        nextAfterLogin(ctx, session.config)
+    ].join('\n'));
+    return ExitCode.Ok;
+}
 export const logout = {
     name: 'logout',
     summary: 'Remove the saved host token from this machine',

package/dist/commands/guide.js

@@ -21,6 +21,14 @@ those workers. Every command below works from any folder and takes \`--json\` fo
 - **\`package.json\`** — only when a worker needs a library. \`npm init -y\` writes \`"type": "commonjs"\`, which
   breaks \`.js\`/\`.ts\` workers that use \`export\`: keep workers as \`.mjs\`/\`.mts\`, or set \`"type": "module"\`.
 
+## Log in
+
+Run \`${BIN} login\` yourself when \`${BIN} status\` says this machine is not logged in. It prints an approval link
+(over SSH or without a display, a link and a code for another device) and waits up to 15 minutes. Pass the link — and
+the code, if there is one — to the user exactly as printed, ask them to approve it in their browser, and keep the
+command running until it exits. If the machine is already logged in it exits at once without changing anything.
+With \`--json\`, the first line (\`"event":"login_pending"\`) carries the link before the result.
+
 ## Run
 
 | Command | Use |
@@ -41,8 +49,8 @@ Handler code and \`${DOTENV_FILE}\` edits apply to the next task with no reload.
 
 ## Do not touch
 
-- **\`${CREDENTIALS_FILE}\`** (the host token) — never read, print or copy it. The user runs \`${BIN} login\` and types
-  the token at its masked prompt; never ask for the token in the chat.
+- **\`${CREDENTIALS_FILE}\`** (the host token) — never read, print or copy it. \`${BIN} login\` saves it after the
+  user approves in the browser; never ask for the token in the chat.
 - **\`${CONTROL_DB_FILE}\`, \`runner.*\`, \`${PROJECT_RECORD_FILE}\`** — internal state. Use \`${BIN} tasks prune\` to clear history.
 - **\`${LOCAL_SERVER_TOKEN_FILE}\`** — only for a local script that calls \`${BIN} start --serve\`.
 - **Tables starting with \`${RESULT_TABLE_PREFIX}\` in \`${USER_DB_FILE}\`** — read them, never write them.

package/dist/core/api.js

@@ -65,17 +65,27 @@ export class ApiClient {
         }
         return this.request('POST', target.href, body);
     }
-    async request(method, url, payload) {
+    loginAuthorize(body) {
+        return this.request('POST', this.opts.apiUrl + '/api/v1/cli/authorize', body, false);
+    }
+    loginDevice(body) {
+        return this.request('POST', this.opts.apiUrl + '/api/v1/cli/device', body, false);
+    }
+    loginToken(body) {
+        return this.request('POST', this.opts.apiUrl + '/api/v1/cli/token', body, false);
+    }
+    async request(method, url, payload, auth = true) {
         if (this.stop)
             throw this.stop;
         const signals = [AbortSignal.timeout(API_TIMEOUT_MS)];
         if (this.opts.signal)
             signals.push(this.opts.signal);
         const headers = {
-            authorization: `Bearer ${this.opts.token}`,
             accept: 'application/json',
             'user-agent': this.opts.userAgent
         };
+        if (auth)
+            headers.authorization = `Bearer ${this.opts.token}`;
         if (payload !== undefined)
             headers['content-type'] = 'application/json';
         let res;

package/dist/core/domain/contract.js

@@ -13,6 +13,14 @@ export const OTHER_CODES = [
     'unsupported_media_type',
     'service_unavailable'
 ];
+export const LOGIN_CODES = [
+    'authorization_pending',
+    'slow_down',
+    'access_denied',
+    'expired_token',
+    'invalid_grant',
+    'device_rate_limited'
+];
 export function isStopCode(code) {
     return typeof code === 'string' && STOP_CODES.includes(code);
 }
@@ -76,6 +84,56 @@ export function isTrustedLiveUrl(liveUrl, apiUrl) {
         live.username === '' &&
         live.password === '');
 }
+export const LOGIN_REQUEST_EXPIRES_S = 900;
+export const DEVICE_POLL_INTERVAL_S = 5;
+export const DEVICE_SLOW_DOWN_STEP_S = 5;
+export const DEVICE_POLL_INTERVAL_MAX_S = 60;
+export const LOOPBACK_REDIRECT_HOST = '127.0.0.1';
+export const LOOPBACK_CALLBACK_PATH = '/callback';
+export const CODE_CHALLENGE_METHOD = 'S256';
+export const USER_CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ';
+export const USER_CODE_PATTERN = /^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/;
+export function normalizeUserCode(input) {
+    const raw = input.toUpperCase().replace(/[\s-]/g, '');
+    if (raw.length !== 8)
+        return null;
+    const code = `${raw.slice(0, 4)}-${raw.slice(4)}`;
+    return USER_CODE_PATTERN.test(code) ? code : null;
+}
+export function isOpenableLoginUrl(url, apiUrl) {
+    if (typeof url !== 'string')
+        return null;
+    let parsed;
+    let api;
+    try {
+        parsed = new URL(url);
+        api = new URL(apiUrl);
+    }
+    catch {
+        return null;
+    }
+    const secure = parsed.protocol === 'https:';
+    const loopback = parsed.protocol === 'http:' &&
+        api.protocol === 'http:' &&
+        LOOPBACK_HOSTNAMES.includes(api.hostname);
+    if (!secure && !loopback)
+        return null;
+    if (parsed.username !== '' || parsed.password !== '')
+        return null;
+    return LOGIN_URL_SAFE_CHARS.test(parsed.href) ? parsed.href : null;
+}
+export function loginResultUrl(resultUrl, authorizeUrl, apiUrl) {
+    const href = isOpenableLoginUrl(resultUrl, apiUrl);
+    if (href === null)
+        return null;
+    const parsed = new URL(href);
+    if (parsed.origin !== new URL(authorizeUrl).origin)
+        return null;
+    if (/[?#]/.test(href))
+        return null;
+    return href;
+}
+export const LOGIN_URL_SAFE_CHARS = /^[A-Za-z0-9\-._~:/?#@&=+,;]+$/;
 export const SYNC_WORKERS_MAX = 200;
 export const WORKER_DESCRIPTION_MAX_CHARS = 500;
 export const PULL_WORKER_NAME = /^[a-z0-9_-]{1,50}$/;

package/dist/core/host/session.js

@@ -73,7 +73,7 @@ export function rememberQuota(session, quota, now) {
 export function stopHint(reason) {
     switch (reason) {
         case 'host_token_invalid':
-            return "The host token was revoked or the host was deleted. Issue a new token on the dashboard and run '3minapi login'.";
+            return "The host token was revoked or the host was deleted. Run '3minapi login' to approve this PC again (if THREEMINAPI_TOKEN is set, unset it or set a valid token).";
         case 'no_subscription':
             return 'There is no active subscription for this account. Subscribe on the dashboard, then run the command again.';
         case 'quota_exhausted':

package/dist/core/login/client-info.js

@@ -0,0 +1,21 @@
+const NAME_MAX = 50;
+const FALLBACK_NAME = '3minapi-host';
+export function loginClient(hostname, platform, arch, version) {
+    const trimmed = [...hostname.trim()].slice(0, NAME_MAX).join('').trim();
+    return {
+        name: trimmed === '' ? FALLBACK_NAME : trimmed,
+        platform: `${platform}-${arch}`,
+        cli_version: version
+    };
+}
+export function chooseFlow(choice, env, platform) {
+    if (choice.device)
+        return 'device';
+    if (choice.loopback)
+        return 'loopback';
+    if (env.SSH_CONNECTION)
+        return 'device';
+    if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return 'device';
+    return 'loopback';
+}

package/dist/core/login/device.js

@@ -0,0 +1,56 @@
+import { setTimeout as sleepFor } from 'node:timers/promises';
+import { ApiError } from "../api.js";
+import { CliError, DEVICE_POLL_INTERVAL_MAX_S, DEVICE_POLL_INTERVAL_S, DEVICE_SLOW_DOWN_STEP_S, ExitCode, LOGIN_REQUEST_EXPIRES_S } from "../domain/index.js";
+export const LOGIN_EXPIRED_MESSAGE = 'the login request expired before it was approved. Run login again.';
+export const LOGIN_DENIED_MESSAGE = 'the login request was denied in the browser. Nothing was changed.';
+export async function pollDeviceToken(opts) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms, signal) => sleepFor(ms, undefined, { signal }));
+    const deadline = now() + clampSeconds(opts.expiresInS, LOGIN_REQUEST_EXPIRES_S, LOGIN_REQUEST_EXPIRES_S) * 1000;
+    let intervalS = clampSeconds(opts.intervalS, DEVICE_POLL_INTERVAL_S, DEVICE_POLL_INTERVAL_MAX_S);
+    let waitS = intervalS;
+    for (;;) {
+        try {
+            await sleep(waitS * 1000, opts.signal);
+        }
+        catch {
+            throw new CliError('login cancelled.', ExitCode.Interrupted);
+        }
+        if (now() >= deadline)
+            throw new CliError(LOGIN_EXPIRED_MESSAGE);
+        try {
+            return await opts.exchange();
+        }
+        catch (err) {
+            if (opts.signal.aborted)
+                throw new CliError('login cancelled.', ExitCode.Interrupted);
+            if (!(err instanceof ApiError))
+                throw err;
+            switch (err.code) {
+                case 'authorization_pending':
+                    waitS = intervalS;
+                    continue;
+                case 'slow_down':
+                    intervalS = Math.min(intervalS + DEVICE_SLOW_DOWN_STEP_S, DEVICE_POLL_INTERVAL_MAX_S);
+                    waitS = intervalS;
+                    continue;
+                case 'access_denied':
+                    throw new CliError(LOGIN_DENIED_MESSAGE);
+                case 'expired_token':
+                    throw new CliError(LOGIN_EXPIRED_MESSAGE);
+            }
+            const transient = err.code === 'service_unavailable' ||
+                (err.code === null && (err.status === null || err.status >= 500));
+            if (transient) {
+                waitS = Math.min(waitS * 2, DEVICE_POLL_INTERVAL_MAX_S);
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+function clampSeconds(value, fallback, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.min(value, max);
+}

package/dist/core/login/loopback.js

@@ -0,0 +1,198 @@
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
+import { CliError, ExitCode, LOOPBACK_CALLBACK_PATH, LOOPBACK_REDIRECT_HOST } from "../domain/index.js";
+import { sameSecret } from "./pkce.js";
+export class LoopbackUnavailable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LoopbackUnavailable';
+    }
+}
+const MIN_PORT = 1024;
+const MAX_CODE_LENGTH = 512;
+export const CALLBACK_HOLD_MS = 10_000;
+export function startCallbackServer(opts) {
+    let settle;
+    let fail;
+    const result = new Promise((resolve, reject) => {
+        settle = resolve;
+        fail = reject;
+    });
+    result.catch(() => { });
+    let port = 0;
+    let done = false;
+    let timer;
+    let held = null;
+    let holdTimer;
+    const server = createServer((req, res) => {
+        const outcome = handle(req, port, opts.state, done);
+        if (!outcome.result) {
+            send(res, 400, PAGES.bad);
+            return;
+        }
+        done = true;
+        settle(outcome.result);
+        clearTimeout(timer);
+        server.close();
+        server.closeIdleConnections();
+        held = res;
+        res.once('close', () => {
+            held = null;
+            finish();
+        });
+        holdTimer = setTimeout(() => reply(null, null), opts.holdMs ?? CALLBACK_HOLD_MS);
+        holdTimer.unref();
+    });
+    server.on('clientError', (_err, socket) => socket.destroy());
+    function reply(outcome, resultUrl) {
+        const res = held;
+        held = null;
+        clearTimeout(holdTimer);
+        if (res === null || res.headersSent)
+            return;
+        if (outcome !== null && resultUrl !== null) {
+            redirect(res, `${resultUrl}?result=${outcome}`);
+        }
+        else {
+            send(res, 200, PAGES[outcome ?? 'unknown']);
+        }
+    }
+    const onAbort = () => {
+        if (done) {
+            reply(null, null);
+            return;
+        }
+        finish();
+        fail(new CliError('login cancelled.', ExitCode.Interrupted));
+    };
+    let finished = false;
+    function finish() {
+        if (finished)
+            return;
+        finished = true;
+        clearTimeout(timer);
+        clearTimeout(holdTimer);
+        opts.signal.removeEventListener('abort', onAbort);
+        server.close();
+        server.closeAllConnections();
+    }
+    return new Promise((resolve, reject) => {
+        const onListenError = (err) => {
+            reject(new LoopbackUnavailable(`cannot listen on ${LOOPBACK_REDIRECT_HOST}: ${err.message}`));
+        };
+        server.once('error', onListenError);
+        server.listen(0, LOOPBACK_REDIRECT_HOST, () => {
+            server.off('error', onListenError);
+            server.on('error', (err) => {
+                finish();
+                fail(new CliError(`the login callback server failed: ${err.message}`));
+            });
+            const address = server.address();
+            port = typeof address === 'object' && address !== null ? address.port : 0;
+            if (port < MIN_PORT) {
+                server.close();
+                reject(new LoopbackUnavailable(`unusable callback port ${port}`));
+                return;
+            }
+            if (opts.signal.aborted) {
+                onAbort();
+            }
+            else {
+                opts.signal.addEventListener('abort', onAbort, { once: true });
+                timer = setTimeout(() => {
+                    finish();
+                    fail(new CliError('the login request expired before it was approved. Run login again.'));
+                }, opts.timeoutMs);
+            }
+            resolve({
+                port,
+                result,
+                reply,
+                close: () => {
+                    if (held !== null) {
+                        reply(null, null);
+                    }
+                    else if (!done) {
+                        done = true;
+                        finish();
+                    }
+                }
+            });
+        });
+    });
+}
+function handle(req, port, state, done) {
+    const bad = {};
+    if ((req.headers.host ?? '').toLowerCase() !== `${LOOPBACK_REDIRECT_HOST}:${port}`)
+        return bad;
+    if (req.method !== 'GET')
+        return bad;
+    const url = new URL(req.url ?? '/', `http://${LOOPBACK_REDIRECT_HOST}:${port}`);
+    if (url.pathname !== LOOPBACK_CALLBACK_PATH)
+        return bad;
+    if (done)
+        return bad;
+    if (!sameSecret(url.searchParams.get('state'), state))
+        return bad;
+    const error = url.searchParams.get('error');
+    if (error !== null) {
+        return error === 'access_denied' ? { result: { kind: 'denied' } } : bad;
+    }
+    const code = url.searchParams.get('code');
+    if (code === null || code === '' || code.length > MAX_CODE_LENGTH)
+        return bad;
+    return { result: { kind: 'code', code } };
+}
+const PAGES = {
+    ok: {
+        title: 'Logged in',
+        body: 'This PC is connected to 3Min API. You can close this tab — the terminal shows the details.'
+    },
+    denied: { title: 'Login denied', body: 'Nothing was changed. You can close this tab.' },
+    failed: {
+        title: 'Login failed',
+        body: 'The approval could not be completed. Check the terminal, then run login again.'
+    },
+    unknown: {
+        title: 'Check the terminal',
+        body: 'The approval reached this PC. The terminal shows whether logging in finished. You can close this tab.'
+    },
+    bad: {
+        title: 'Link not valid',
+        body: 'This login link is not valid here. Return to the terminal.'
+    }
+};
+const STYLE = ':root{color-scheme:light dark}body{margin:0;min-height:100vh;display:grid;place-items:center;' +
+    'font:16px/1.5 system-ui,sans-serif;background:#fafafa;color:#18181b}' +
+    'main{max-width:28rem;margin:1rem;padding:2rem;border:1px solid #e4e4e7;border-radius:12px;background:#fff}' +
+    'h1{margin:0 0 .5rem;font-size:1.25rem}p{margin:0;color:#52525b}' +
+    '@media (prefers-color-scheme:dark){body{background:#09090b;color:#fafafa}' +
+    'main{background:#18181b;border-color:#27272a}p{color:#a1a1aa}}';
+const STYLE_HASH = createHash('sha256').update(STYLE).digest('base64');
+const BASE_HEADERS = {
+    'cache-control': 'no-store',
+    'referrer-policy': 'no-referrer',
+    'x-content-type-options': 'nosniff',
+    connection: 'close'
+};
+function send(res, status, page) {
+    const html = '<!doctype html><html lang="en"><meta charset="utf-8">' +
+        '<meta name="viewport" content="width=device-width,initial-scale=1">' +
+        `<title>3Min API CLI — ${page.title}</title><style>${STYLE}</style>` +
+        `<main><h1>${page.title}</h1><p>${page.body}</p></main>\n`;
+    res.writeHead(status, {
+        ...BASE_HEADERS,
+        'content-type': 'text/html; charset=utf-8',
+        'content-security-policy': `default-src 'none'; style-src 'sha256-${STYLE_HASH}'`
+    });
+    res.end(html);
+}
+function redirect(res, location) {
+    res.writeHead(302, {
+        ...BASE_HEADERS,
+        location,
+        'content-security-policy': "default-src 'none'",
+        'content-length': '0'
+    });
+    res.end();
+}

package/dist/core/login/pkce.js

@@ -0,0 +1,18 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+export function createPkce() {
+    const verifier = randomBytes(32).toString('base64url');
+    return { verifier, challenge: s256(verifier) };
+}
+export function s256(verifier) {
+    return createHash('sha256').update(verifier, 'ascii').digest('base64url');
+}
+export function createState() {
+    return randomBytes(32).toString('base64url');
+}
+export function sameSecret(given, expected) {
+    if (given === null)
+        return false;
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/core/output.js

@@ -42,6 +42,10 @@ export class Output {
             this.writeOut(text.endsWith('\n') ? text : text + '\n');
         }
     }
+    event(data) {
+        if (this.json)
+            this.stdout.write(JSON.stringify(data) + '\n');
+    }
     print(text) {
         this.writeOut(text.endsWith('\n') ? text : text + '\n');
     }

package/dist/core/redact.js

@@ -1,6 +1,6 @@
 import { truncate } from "./text.js";
 export const REDACTED = '<redacted>';
-const SECRET_KEY = /authorization|token|secret|password|passwd|api[-_]?key|signature|cookie|credential/i;
+const SECRET_KEY = /authorization|token|secret|password|passwd|api[-_]?key|signature|cookie|credential|verifier|device_code/i;
 const SECRET_VALUES = [
     /tm_(?:host|live|test|mcp|task)_[0-9a-f]{8,}/gi,
     /whsec_[A-Za-z0-9+/=]{8,}/g,

package/dist/modules/workers/results/missing-paths.js

@@ -62,5 +62,5 @@ export function missingPathsWarning(missing) {
     const shown = missing.slice(0, MISSING_PATHS_MAX);
     const more = missing.length - shown.length;
     return (`No result in the scope has ${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}, so ` +
-        `${missing.length === 1 ? 'it reads' : 'they read'} as NULL — op "describe" lists the paths the results have.`);
+        `${missing.length === 1 ? 'it reads' : 'they read'} as NULL — task_result_describe lists the paths the results have.`);
 }

package/dist/modules/workers/results/reader-input.js

@@ -1,8 +1,7 @@
 import { BUILTIN_TASK_IDS_MAX, READ_LIMIT_MAX } from "../../../core/domain/index.js";
-export const READER_USAGE = 'input is one of: {"op":"describe","task_id":"…","run_no?":1} | {"op":"describe","worker":"…","since?":"ISO date"} | ' +
-    '{"op":"query","sql":"SELECT … FROM results …","worker?":"…","task_id?":"…","task_ids?":["…"],"since?":"ISO date","expect_shape?":"…"} ' +
-    '(at least one of worker, task_id, task_ids, since) | {"op":"read","task_id":"…","run_no?":1,"path?":"$.items","offset?":0,"limit?":100} ' +
-    '(run_no picks a run of a repeating task; the latest run when left out)';
+export const READER_USAGE = 'Use task_result_describe with task_id (and run_no) or worker (and since); task_result_query with sql and at least ' +
+    'one of worker, task_id, task_ids, since (and expect_shape); or task_result_read with task_id (and run_no, path, ' +
+    'offset, limit). run_no picks a run of a repeating task; the latest run when left out';
 const TASK_ID = /^[0-9A-Za-z-]{1,64}$/;
 const SHAPE_HASH = /^[0-9a-f]{16}$/;
 const WORKER_MAX_CHARS = 50;

package/dist/modules/workers/results/reader.js

@@ -79,7 +79,7 @@ function describeOne(db, taskId, hostId, runNo) {
             ? out
             : {
                 ...out,
-                error: { message: 'the saved error is too large to show; read it with op "read"' }
+                error: { message: 'the saved error is too large to show; read it with task_result_read' }
             };
     }
     return {
@@ -382,7 +382,7 @@ function readText(base, text, offset, limit) {
     };
 }
 function missing(path) {
-    return new Failure('read_out_of_range', `${path} does not exist in this result — check the paths with op "describe"`);
+    return new Failure('read_out_of_range', `${path} does not exist in this result — check the paths with task_result_describe`);
 }
 export function parsePath(path) {
     const steps = [];

package/dist/modules/workers/results/substitute.js

@@ -3,9 +3,9 @@ import { formatCount } from "../../../core/text.js";
 import { fitShape } from "./shape.js";
 export const SUBSTITUTE_READ = "The full result is too large to send and is stored on the user's PC. Do not present this summary as the result. " +
     '`shape` summarizes its structure: the paths it has, with types, counts and sample values — an overview; ' +
-    'deeper levels may be left out (`omitted`), and {"op":"describe","task_id":"<task_id>"} returns them. ' +
-    'Compute the answer over those paths by creating a task for the worker in `reader` with input ' +
-    '{"op":"query","task_id":"<task_id>","sql":"SELECT … FROM results"} — help(tasks) explains the view and examples.';
+    'deeper levels may be left out (`omitted`), and task_result_describe with this task_id returns them. ' +
+    'Compute the answer over those paths with task_result_query for this task_id and SQL over the view `results` — ' +
+    'help(tasks) explains the view and examples.';
 export const SUBSTITUTE_READ_LOCAL_ONLY = "The full result is too large to send and is stored on the user's PC. The user can see it with " +
     "'3minapi worker results show <task_id>' or query it with '3minapi worker results query'. " +
     '`shape` summarizes its structure: paths, types, counts and sample values — an overview; deeper ' +

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@3minapi/cli",
-	"version": "0.22.1",
+	"version": "0.24.0",
 	"description": "Run your machine as a 3Min API host — the CLI that fetches tasks from your AI and runs them with your own worker files",
 	"keywords": [
 		"3minapi",