@zocomputer/cli 0.1.1 → 0.2.1

package/dist/http.d.ts

@@ -3,7 +3,11 @@ import { CliError } from "./errors.ts";
 export declare function systemApiFailure(response: Response, raw: string | Uint8Array, operation: string): SystemAPIError;
 export declare class RequestFailure extends CliError {
     readonly ambiguous: boolean;
-    constructor(ambiguous: boolean, code?: string, exitCode?: number);
+    /** The HTTP status when the server answered; absent for transport failures. */
+    readonly status?: number | undefined;
+    constructor(ambiguous: boolean, code?: string, exitCode?: number, 
+    /** The HTTP status when the server answered; absent for transport failures. */
+    status?: number | undefined);
 }
 export declare function requestJson(url: string, init?: RequestInit, fetcher?: typeof fetch, options?: {
     timeoutMs?: number;

package/dist/http.js

@@ -46,11 +46,15 @@ export function systemApiFailure(response, raw, operation) {
 }
 export class RequestFailure extends CliError {
     ambiguous;
-    constructor(ambiguous, code = "transport_error", exitCode = 5) {
+    status;
+    constructor(ambiguous, code = "transport_error", exitCode = 5, 
+    /** The HTTP status when the server answered; absent for transport failures. */
+    status) {
         super(code === "invalid_grant"
             ? "Your sign-in ended. Run zo login."
             : "The authentication request failed. Try again or run zo login.", exitCode, code);
         this.ambiguous = ambiguous;
+        this.status = status;
     }
 }
 export async function requestJson(url, init = {}, fetcher = fetch, options = {}) {
@@ -106,6 +110,10 @@ export async function requestJson(url, init = {}, fetcher = fetch, options = {})
         body = JSON.parse(raw);
     }
     catch {
+        // Cloudflare's edge rate limits answer 429 with a non-JSON page before the
+        // worker runs; the status alone says the request was not processed.
+        if (response.status === 429)
+            throw new RequestFailure(true, "temporarily_unavailable", 5, 429);
         throw new RequestFailure(false, "invalid_response");
     }
     if (!response.ok) {
@@ -118,7 +126,7 @@ export async function requestJson(url, init = {}, fetcher = fetch, options = {})
             ? 3
             : response.status === 403
                 ? 4
-                : 5);
+                : 5, response.status);
     }
     return body;
 }

package/dist/login.d.ts

@@ -1,14 +1,30 @@
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface LoginPrompt {
+    url: string;
+    userCode: string;
+    /** False when the CLI won't open a browser: --no-browser, SSH or no display. */
+    browser: boolean;
+}
 export interface LoginOptions {
     noBrowser?: boolean;
-    timeoutMs?: number;
     signal?: AbortSignal;
-    announce?: (url: string) => void;
+    platform?: NodeJS.Platform;
+    announce?: (prompt: LoginPrompt) => void;
     openBrowser?: (url: string) => Promise<void>;
 }
-export interface LoginCode {
-    code: string;
-    verifier: string;
-    redirectUri: string;
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    url: string;
+    expiresInMs: number;
+    intervalMs: number;
 }
 export declare function openBrowser(url: string): Promise<void>;
-export declare function loginCode(issuer: string, audience: string, clientId: string, options?: LoginOptions): Promise<LoginCode>;
+/**
+ * A browser opened over SSH, or with no display, lands on the wrong machine or
+ * nowhere. xdg-open needs a display on every system other than macOS.
+ */
+export declare function browserAvailable(env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+export declare function pause(ms: number, signal?: AbortSignal | null): Promise<void>;
+export declare function parseDeviceAuthorization(raw: unknown, issuer: string): DeviceAuthorization;
+export declare function deviceAuthorization(issuer: string, audience: string, clientId: string, fetcher: typeof fetch, signal?: AbortSignal): Promise<DeviceAuthorization>;

package/dist/login.js

@@ -1,102 +1,93 @@
-import { createHash, randomBytes } from "node:crypto";
-import { createServer } from "node:http";
 import { spawn } from "node:child_process";
-import { CliError } from "./errors.js";
+import { CliError, record, throwIfInterrupted } from "./errors.js";
+import { requestJson, RequestFailure } from "./http.js";
+export const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 export async function openBrowser(url) {
     await new Promise((resolve, reject) => {
         const child = spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore", detached: true });
         child.unref();
-        child.once("error", () => reject(new CliError("Could not open a browser. Retry with --no-browser.")));
-        child.once("exit", (status) => status === 0
-            ? resolve()
-            : reject(new CliError("Could not open a browser. Retry with --no-browser.")));
+        child.once("error", reject);
+        child.once("exit", (status) => status === 0 ? resolve() : reject(new Error("Browser opener failed.")));
     });
 }
-export async function loginCode(issuer, audience, clientId, options = {}) {
-    const state = randomBytes(32).toString("base64url");
-    const verifier = randomBytes(32).toString("base64url");
-    let complete = () => { };
-    let fail = () => { };
-    const received = new Promise((resolve, reject) => {
-        complete = resolve;
-        fail = reject;
-    });
-    // The callback may arrive while the browser opener is still running.
-    void received.catch(() => { });
-    let accepted = false;
-    const server = createServer((request, response) => {
-        let url;
-        try {
-            url = new URL(request.url ?? "/", "http://127.0.0.1");
-        }
-        catch {
-            response.writeHead(400).end("Invalid callback.");
-            return;
-        }
-        const params = url.searchParams;
-        const keys = [...params.keys()];
-        const valid = !accepted &&
-            request.method === "GET" &&
-            url.pathname === "/callback" &&
-            keys.length === new Set(keys).size &&
-            params.get("state") === state &&
-            params.get("iss") === issuer &&
-            params.has("code") !== params.has("error");
-        response.setHeader("Content-Type", "text/plain; charset=utf-8");
-        response.setHeader("Cache-Control", "no-store");
-        if (!valid) {
-            response.writeHead(400).end("Invalid callback.");
-            return;
-        }
-        accepted = true;
-        response.end("You may close this window and return to Zo.");
-        if (params.has("error"))
-            fail(new CliError("Authorization was denied. Run zo login to try again.", 4, "access_denied"));
-        else {
-            const code = params.get("code");
-            if (code)
-                complete(code);
-            else
-                fail(new CliError("Authorization returned an empty code.", 3, "invalid_response"));
-        }
-    });
-    server.requestTimeout = 5_000;
-    server.headersTimeout = 5_000;
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", resolve);
+/**
+ * A browser opened over SSH, or with no display, lands on the wrong machine or
+ * nowhere. xdg-open needs a display on every system other than macOS.
+ */
+export function browserAvailable(env, platform = process.platform) {
+    if (env.SSH_CONNECTION || env.SSH_TTY)
+        return false;
+    return platform === "darwin" || !!env.DISPLAY || !!env.WAYLAND_DISPLAY;
+}
+export function pause(ms, signal) {
+    throwIfInterrupted(signal);
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(new CliError("Interrupted.", 130, "interrupted"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", abort, { once: true });
     });
-    const address = server.address();
-    if (!address || typeof address === "string")
-        throw new CliError("Could not bind the login callback.");
-    const redirectUri = `http://127.0.0.1:${address.port}/callback`;
-    const authorize = new URL("/zo-system-api/oauth/authorize", issuer);
-    authorize.search = new URLSearchParams({
-        response_type: "code",
-        client_id: clientId,
-        redirect_uri: redirectUri,
-        resource: audience,
-        code_challenge: createHash("sha256").update(verifier).digest("base64url"),
-        code_challenge_method: "S256",
-        state,
-    }).toString();
-    const timer = setTimeout(() => fail(new CliError("Login timed out. Run zo login to try again.", 3, "login_timeout")), options.timeoutMs ?? 300_000);
-    const abort = () => fail(new CliError("Login interrupted.", 130, "interrupted"));
-    options.signal?.addEventListener("abort", abort, { once: true });
+}
+function seconds(value, maximum) {
+    return typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value > 0 &&
+        value <= maximum
+        ? value
+        : undefined;
+}
+export function parseDeviceAuthorization(raw, issuer) {
+    const invalid = () => new CliError("The sign-in service returned an invalid response.", 5, "invalid_response");
+    if (!record(raw) ||
+        typeof raw.device_code !== "string" ||
+        !/^[A-Za-z0-9._~-]{1,512}$/.test(raw.device_code) ||
+        typeof raw.user_code !== "string" ||
+        !/^[A-Z0-9]{1,8}(?:-[A-Z0-9]{1,8}){0,3}$/.test(raw.user_code) ||
+        typeof raw.verification_uri_complete !== "string")
+        throw invalid();
+    const expiresIn = seconds(raw.expires_in, 3_600);
+    const interval = raw.interval === undefined ? 2 : seconds(raw.interval, 60);
+    if (expiresIn === undefined || interval === undefined)
+        throw invalid();
+    let url;
+    try {
+        url = new URL(raw.verification_uri_complete);
+    }
+    catch {
+        throw invalid();
+    }
+    // The URL goes to the system opener; only the issuer's own scheme is safe.
+    // Production is https; the local test issuer is http.
+    if (url.protocol !== new URL(issuer).protocol || url.username || url.password)
+        throw invalid();
+    return {
+        deviceCode: raw.device_code,
+        userCode: raw.user_code,
+        url: url.href,
+        expiresInMs: expiresIn * 1000,
+        intervalMs: interval * 1000,
+    };
+}
+export async function deviceAuthorization(issuer, audience, clientId, fetcher, signal) {
+    let raw;
     try {
-        if (options.signal?.aborted)
-            abort();
-        else {
-            options.announce?.(authorize.href);
-            if (!options.noBrowser)
-                void (options.openBrowser ?? openBrowser)(authorize.href).catch(fail);
-        }
-        return { code: await received, verifier, redirectUri };
+        raw = await requestJson(`${issuer}/zo-system-api/oauth/device_authorization`, {
+            method: "POST",
+            signal,
+            body: new URLSearchParams({ client_id: clientId, resource: audience }),
+        }, fetcher);
     }
-    finally {
-        clearTimeout(timer);
-        options.signal?.removeEventListener("abort", abort);
-        server.closeAllConnections();
-        await new Promise((resolve) => server.close(() => resolve()));
+    catch (error) {
+        if (error instanceof RequestFailure && error.status === 429)
+            throw new CliError("Too many sign-in attempts from this network. Wait a minute, then run zo login again.", 5, "rate_limited");
+        if (error instanceof RequestFailure && error.code === "unauthorized_client")
+            throw new CliError("This environment does not allow Zo CLI sign-in yet.", 5, "unauthorized_client");
+        throw error;
     }
+    return parseDeviceAuthorization(raw, issuer);
 }

package/dist/main.js

@@ -26,7 +26,7 @@ Use --profile to keep separate sign-ins. New profiles use production.
 ZO_SYSTEM_API_ACCESS_TOKEN overrides saved credentials; ZO_WORKSPACE_ID selects a workspace.
 `;
 const localHelp = {
-    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint the sign-in URL, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser skips opening the browser and still waits for the localhost callback.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
+    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint a sign-in URL and code, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser prints the URL without opening a browser; approve it on any device.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
     logout: "Usage: zo logout [--profile <name>] [--local-only]\nRevoke the saved sign-in and pending replaced sign-ins. --local-only removes local credentials without revoking server access.\n",
     auth: "Usage: zo auth status | token [--headers]\nStatus shows the current identity; token explicitly prints an access token.\n",
     "auth status": "Usage: zo auth status [--profile <name>] [--workspace <id>] [--json]\nShow the approving person, sign-in expiry and effective identity in the selected workspace.\n",
@@ -41,6 +41,16 @@ const localHelp = {
     rpc: "Usage: zo rpc <action> [--input <json> | --input-file <path|->] [--version <integer>]\n  --query <json>            Declared list-query options; one page per call\n  --idempotency-key <key>   Envelope key where the action supports it\n  --preview                Print the request without invoking\n  --envelope               Print the complete success envelope\n  --json                   Print exact result JSON\n  --profile <name> --workspace <id>\nThe live catalog supplies the default version. RPC preserves supplied inputs. Invocations are never retried.\n",
     completion: "Usage: zo completion bash|zsh|fish\nPrint completion from installed metadata without credentials or network requests.\n",
 };
+function identity(session, workspace) {
+    const { type, id } = workspace.subject;
+    if (type === "user" &&
+        session.approving_subject?.type === "user" &&
+        session.approving_subject.id === id)
+        return "as you";
+    if (type === "service_account")
+        return `as service account ${safeText(id)}`;
+    return `as ${type} ${safeText(id)}`;
+}
 async function showHelp(args, stdout) {
     if (!args.length) {
         stdout.write(help);
@@ -121,19 +131,17 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             const login = await auth.login({
                 noBrowser: parsed.flags.has("no-browser"),
                 signal,
-                announce: (url) => {
-                    const message = `Open this URL to sign in:\n${url}\n`;
-                    const dim = stderr.isTTY &&
-                        !options.json &&
-                        env.NO_COLOR === undefined &&
-                        env.TERM !== "dumb";
-                    stderr.write(dim ? `\u001b[2m${message}\u001b[22m` : message);
-                },
+                announce: ({ url, userCode, browser }) => stderr.write(`${browser
+                    ? "Opening your browser to sign in. If it doesn't open, visit:"
+                    : "To sign in, visit this URL on any device:"}\n\n  ${url}\n\nCode: ${userCode}. Approve only if your browser shows the same code.\nWaiting for approval… (Ctrl-C to cancel)\n`),
             });
-            stderr.write(`Sign-in saved for profile ${profile.name}.\n`);
+            stderr.write(`\nApproved in the browser. Sign-in saved for profile ${profile.name}.\n`);
             if (login.cleanupPending)
                 stderr.write("A previous sign-in could not be revoked. Cleanup remains saved for the next login; the current sign-in is active. You can revoke the previous sign-in in Authorized apps.\n");
             const session = await auth.session();
+            // Always list the approved workspaces, so a sign-in someone else
+            // approved shows up as workspaces or identities you don't recognize.
+            session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id}), ${identity(session, workspace)}\n`));
             const desired = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
             let chosen;
             if (options.workspace !== undefined)
@@ -152,7 +160,6 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
                 process.stdin.isTTY &&
                 stderr.isTTY &&
                 session.workspaces.length > 0) {
-                session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id})\n`));
                 const input = createInterface({
                     input: process.stdin,
                     output: process.stderr,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "description": "Public Zo command line client",
   "bin": {
@@ -14,7 +14,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.13.0"
   },
   "dependencies": {
-    "@zocomputer/system-api": "0.1.1"
+    "@zocomputer/system-api": "0.1.3"
   },
   "publishConfig": {
     "access": "public",