@zocomputer/cli 0.2.1 → 0.3.0

package/README.md

@@ -6,6 +6,21 @@ see [runtime requirements](../README.md#set-up).
 
 ## Install or upgrade
 
+The standalone installer is implemented but awaits its first public release.
+Once published, macOS 15+ and Linux glibc 2.35+ users on arm64 or x64 can run:
+
+```sh
+curl -fsSL https://zo.computer/install.sh | sh
+```
+
+Then open a new terminal and run `zo --version`. It includes Node, verifies the archive, and keeps versions under
+`${XDG_DATA_HOME:-$HOME/.local/share}/zo/cli/` with a managed `~/.local/bin/zo`
+symlink, and adds `~/.local/bin` to your shell's PATH configuration unless it's
+already on PATH. Re-run it to upgrade; `--version`, `--bin-dir`, and `--no-modify-path`
+control pinned installs, command placement and shell setup. Existing sign-ins
+are preserved. The [CLI guide](../../src/hostagent/system_api/docs/guides/cli.md)
+covers supported systems, PATH collisions, rollback and removal.
+
 Install the latest published version from npm:
 
 ```sh
@@ -81,17 +96,27 @@ workspaces, a terminal prompts for a selection; scripts must supply
 person separately from the effective subject in the selected workspace.
 `context list`, `context use` and status refresh that view from the server.
 
-`login` uses the OAuth device authorization grant (RFC 8628). It prints a
-sign-in URL and a code on stderr, opens your browser, and polls the token
-endpoint until you approve or deny. Approve only if the page shows the same
-code. Nothing connects back to the CLI's machine, so the URL works from any
-browser or device. The request expires after 10 minutes; Ctrl-C cancels it
-(exit 130). Denial exits 4 with `access_denied`; expiry exits 3 with
-`login_timeout`.
-
-Over SSH (`SSH_CONNECTION` or `SSH_TTY` set), or with no `DISPLAY` or
-`WAYLAND_DISPLAY` outside macOS, login doesn't open a browser and asks you to
-visit the URL on any device. `login --no-browser` does the same anywhere.
+`login` signs in as the client ID
+`https://www.zo.computer/oauth/zo-cli-client-metadata.json`, the CLI's OAuth
+client metadata document, so the consent page names it "Zo CLI". By default it
+uses an authorization code with PKCE (S256) and a loopback callback (RFC 8252):
+it listens on `127.0.0.1` at a port the OS assigns, opens your browser at the
+authorization URL, and prints that URL on stderr in case the browser doesn't
+open. The browser returns to `http://127.0.0.1:<port>/callback`; the CLI accepts
+the one callback whose `state` and `iss` match, redeems the code with its
+verifier, and stops listening. It waits 10 minutes; Ctrl-C cancels (exit 130).
+Denial exits 4 with `access_denied`; a timeout exits 3 with `login_timeout`.
+
+`login --device` uses the device authorization grant (RFC 8628) instead: it
+prints a URL and a code and polls the token endpoint until you approve on any
+device. Approve only if the page shows the same code. Login does the same
+without `--device` over SSH (`SSH_CONNECTION` or `SSH_TTY` set), with no
+`DISPLAY` or `WAYLAND_DISPLAY` outside macOS, or when the browser fails to open.
+The device request expires after at most 10 minutes, with the same exit codes.
+
+A credential saved by an earlier release, which signed in as `zo-public-cli`,
+is refused as `invalid_credential` after an upgrade, `login` included. Run
+`zo logout` for that profile, then `zo login`.
 
 After approval, login lists every approved workspace with the identity the CLI
 acts as there (`as you` or `as service account <id>`), even when there is only
@@ -110,15 +135,16 @@ token. `ZO_SYSTEM_API_ACCESS_TOKEN` supplies an explicit automation token for
 the selected profile's fixed origins; the CLI never saves or refreshes it,
 including when the server refuses it.
 
-`logout` revokes the saved sign-in and pending replaced sign-ins. If revocation
-fails, local credentials remain so you can retry. `logout --local-only`
-removes local credentials without revoking server access. Unset a bearer
-override before logging in or out of a saved profile.
+`logout` revokes the saved sign-in and pending replaced sign-ins, then removes
+them from this computer. If a revocation fails, for a network error, an HTTP
+error or a credential it can't read (such as one saved by an earlier release),
+logout prints a one-line warning with the reason, removes the local credential
+anyway and exits 0; revoke the sign-in in **Authorized apps** if it may still be
+in use. Ctrl-C during logout keeps what is left so a later logout can finish.
+Unset a bearer override before logging in or out of a saved profile.
 
-If a credential file is malformed, revoke its login in **Authorized apps**,
-then run `logout --local-only` for that profile before signing in again.
-Ordinary login and logout preserve the unreadable file so they do not silently
-discard pending revocations.
+Login refuses a malformed credential file, so it never silently discards pending
+revocations; run `logout` for that profile first.
 
 ## Local storage
 

package/dist/argv.js

@@ -18,8 +18,7 @@ export function parseGlobals(argv) {
         const name = arg.slice(2, equal === -1 ? undefined : equal);
         if (!/^[a-z][a-z0-9-]*$/.test(name))
             throw new CliError("Invalid option syntax.");
-        const localSwitch = (name === "no-browser" && args[0] === "login") ||
-            (name === "local-only" && args[0] === "logout") ||
+        const localSwitch = (name === "device" && args[0] === "login") ||
             (name === "headers" && args[0] === "auth" && args[1] === "token");
         const flag = switches.has(name) || localSwitch || (name === "version" && !command);
         if (flag && equal !== -1)

package/dist/auth.d.ts

@@ -35,9 +35,22 @@ export declare class AuthClient {
     private cleanup;
     /** RFC 8628 section 3.4 polling until approval, denial or expiry. */
     private poll;
+    /**
+     * Authorization code with PKCE over a loopback callback when this machine
+     * can open a browser; the device flow with --device, without a local
+     * browser, or when opening the browser fails.
+     */
+    private authorize;
     login(options?: LoginOptions): Promise<{
         cleanupPending: boolean;
     }>;
-    logout(localOnly?: boolean): Promise<void>;
+    /**
+     * Revoke the saved sign-in and pending replaced sign-ins on the server, then remove them from
+     * this computer. A revocation that fails, or a credential that can't be read, still removes the
+     * local file and returns the reason as a warning; only an interruption keeps it.
+     */
+    logout(): Promise<{
+        warning?: string;
+    }>;
 }
 export {};

package/dist/auth.js

@@ -1,10 +1,13 @@
 import { join } from "node:path";
 import { CliError, record, throwIfInterrupted } from "./errors.js";
 import { requestJson, RequestFailure } from "./http.js";
-import { browserAvailable, DEVICE_CODE_GRANT, deviceAuthorization, openBrowser, pause, } from "./login.js";
+import { browserAvailable, DEVICE_CODE_GRANT, deviceAuthorization, loopbackAuthorization, openBrowser, pause, } from "./login.js";
 import { environments, profileName } from "./profiles.js";
 import { parseSession } from "./session.js";
 import { privateDirectory, PrivateWriteDurabilityError, readPrivate, removePrivate, withLock, writePrivate, } from "./storage.js";
+// How long login waits for the browser opener to fail before printing the
+// browser URL and waiting on the callback alone.
+const OPENER_GRACE_MS = 1_000;
 // Longer than requestJson's 8-second default, and short enough that a retry
 // after a lost approval lands inside the issuer's 30-second redemption window.
 const DEVICE_POLL_TIMEOUT_MS = 20_000;
@@ -28,8 +31,24 @@ function tokens(raw, now) {
         expiresAt: now + raw.expires_in * 1000,
     };
 }
+/** A revocation the issuer did not confirm, with why: a network error or the HTTP status. */
+class RevocationError extends CliError {
+    detail;
+    constructor(detail) {
+        super(`Revocation failed (${detail}). Local credentials were retained; retry zo logout.`, 5, "revocation_failed");
+        this.detail = detail;
+    }
+}
+/** Why logout could not revoke, in one line. */
+function revocationProblem(error) {
+    if (error instanceof RevocationError)
+        return `the server did not confirm it (${error.detail})`;
+    if (error instanceof CliError && error.code === "invalid_credential")
+        return "the saved credential can't be read, for example one saved by an earlier zo version";
+    return error instanceof CliError ? error.code : "unexpected error";
+}
 function invalidCredential() {
-    return new CliError("The saved credential cannot be read safely. Revoke Zo CLI in Authorized apps, then run zo logout --local-only for this profile before signing in again. Local-only logout does not revoke server access.", 3, "invalid_credential");
+    return new CliError("The saved credential cannot be read safely. Run zo logout for this profile, then zo login. If logout can't revoke it, revoke Zo CLI in Authorized apps.", 3, "invalid_credential");
 }
 export class AuthClient {
     profile;
@@ -202,12 +221,12 @@ export class AuthClient {
         }
         catch {
             throwIfInterrupted(signal);
-            throw new CliError("Revocation failed. Local credentials were retained; retry zo logout.", 5, "revocation_failed");
+            throw new RevocationError("network error");
         }
         await response.body?.cancel();
         throwIfInterrupted(signal);
         if (!response.ok)
-            throw new CliError("Revocation failed. Local credentials were retained; retry zo logout.", 5, "revocation_failed");
+            throw new RevocationError(`HTTP ${response.status}`);
     }
     async cleanup(credential, signal = this.signal) {
         while (credential.pendingRevocations.length) {
@@ -275,6 +294,50 @@ export class AuthClient {
             }
         }
     }
+    /**
+     * Authorization code with PKCE over a loopback callback when this machine
+     * can open a browser; the device flow with --device, without a local
+     * browser, or when opening the browser fails.
+     */
+    async authorize(options, signal) {
+        if (!options.device &&
+            browserAvailable(this.env, options.platform ?? process.platform)) {
+            const loopback = await loopbackAuthorization(this.binding.issuer, this.binding.audience, this.binding.clientId, { signal, timeoutMs: options.callbackTimeoutMs });
+            // The opener can outlive the sign-in (xdg-open may become the browser
+            // itself), so it is never awaited past a short grace: a failure inside
+            // it falls back to the device flow; after it, the printed URL stands.
+            // The callback, the timeout and Ctrl-C end the wait on their own.
+            let grace;
+            const outcome = await Promise.race([
+                (options.openBrowser ?? openBrowser)(loopback.url).then(() => "opened", () => "failed"),
+                new Promise((resolve) => {
+                    grace = setTimeout(() => resolve("pending"), OPENER_GRACE_MS);
+                }),
+                loopback.code.then(() => "pending", () => "pending"),
+            ]);
+            clearTimeout(grace);
+            if (outcome !== "failed") {
+                options.announce?.({ flow: "browser", url: loopback.url });
+                const code = await loopback.code;
+                throwIfInterrupted(signal);
+                return this.tokenRequest({
+                    grant_type: "authorization_code",
+                    code,
+                    redirect_uri: loopback.redirectUri,
+                    code_verifier: loopback.codeVerifier,
+                }, signal);
+            }
+            await loopback.close();
+            throwIfInterrupted(signal);
+        }
+        const device = await deviceAuthorization(this.binding.issuer, this.binding.audience, this.binding.clientId, this.fetcher, signal);
+        options.announce?.({
+            flow: "device",
+            url: device.url,
+            userCode: device.userCode,
+        });
+        return this.poll(device, signal);
+    }
     async login(options = {}) {
         const signal = this.signal && options.signal
             ? AbortSignal.any([this.signal, options.signal])
@@ -285,18 +348,7 @@ export class AuthClient {
         return this.locked(async () => {
             const previous = await this.read();
             throwIfInterrupted(signal);
-            const device = await deviceAuthorization(this.binding.issuer, this.binding.audience, this.binding.clientId, this.fetcher, signal);
-            const browser = !options.noBrowser &&
-                browserAvailable(this.env, options.platform ?? process.platform);
-            options.announce?.({
-                url: device.url,
-                userCode: device.userCode,
-                browser,
-            });
-            // The printed URL is the fallback when the opener fails.
-            if (browser)
-                void (options.openBrowser ?? openBrowser)(device.url).catch(() => { });
-            const active = await this.poll(device, signal);
+            const active = await this.authorize(options, signal);
             const credential = {
                 version: 1,
                 binding: this.binding,
@@ -335,28 +387,35 @@ export class AuthClient {
             return { cleanupPending: false };
         }, signal);
     }
-    async logout(localOnly = false) {
+    /**
+     * Revoke the saved sign-in and pending replaced sign-ins on the server, then remove them from
+     * this computer. A revocation that fails, or a credential that can't be read, still removes the
+     * local file and returns the reason as a warning; only an interruption keeps it.
+     */
+    async logout() {
         throwIfInterrupted(this.signal);
         if (this.env.ZO_SYSTEM_API_ACCESS_TOKEN !== undefined)
             throw new CliError("Unset ZO_SYSTEM_API_ACCESS_TOKEN before logging out a saved profile.");
-        await this.locked(async () => {
-            if (localOnly) {
-                await removePrivate(this.path);
+        return this.locked(async () => {
+            let warning;
+            try {
+                const credential = await this.read();
                 throwIfInterrupted(this.signal);
-                return;
+                if (credential?.active) {
+                    await this.revoke(credential.active.refreshToken);
+                    delete credential.active;
+                    await writePrivate(this.path, credential);
+                }
+                if (credential)
+                    await this.cleanup(credential);
             }
-            const credential = await this.read();
-            throwIfInterrupted(this.signal);
-            if (!credential)
-                return;
-            if (credential.active) {
-                await this.revoke(credential.active.refreshToken);
-                delete credential.active;
-                await writePrivate(this.path, credential);
+            catch (error) {
+                throwIfInterrupted(this.signal);
+                warning = `Could not revoke the saved sign-in on the server: ${revocationProblem(error)}. It was removed from this computer; revoke Zo CLI in Authorized apps if it may still be in use.`;
             }
-            await this.cleanup(credential);
             await removePrivate(this.path);
             throwIfInterrupted(this.signal);
+            return warning === undefined ? {} : { warning };
         });
     }
 }