@zocomputer/cli 0.1.1 → 0.2.1

package/README.md

@@ -6,25 +6,26 @@ see [runtime requirements](../README.md#set-up).
 
 ## Install or upgrade
 
-After publication, install the versioned package:
+Install the latest published version from npm:
 
 ```sh
-npm install --global @zocomputer/cli@0.1.1
+npm install --global @zocomputer/cli@latest
 zo --version
 zo login
 ```
 
-Use the same install command with the desired version to upgrade. The CLI
+Run the same install command again to upgrade. The CLI
 installs its matching public SDK dependency. It performs no update check when
 you run a command.
 
-To test unpublished artifacts, install both tarballs together:
+To try the CLI without installing it globally:
 
 ```sh
-npm install --global ./zocomputer-system-api-0.1.1.tgz ./zocomputer-cli-0.1.1.tgz
-zo --version
+npx -y @zocomputer/cli@latest --help
 ```
 
+Replace `--help` with a command such as `login` or `--version`.
+
 ## Develop locally
 
 Install the independent client workspace, then build the CLI:
@@ -50,8 +51,10 @@ node dist/main.js auth status
 ```
 
 Use `node dist/main.js` while working in this repository. The repository's
-internal operator CLI is `./zocli/zo` from the repository root. Run `type -a zo`
-to diagnose a PATH collision; the two clients store separate sign-ins.
+internal operator CLI is `zd` (`./zocli/zd` from the repository root).
+If an old internal `zo` symlink is still on PATH, run `./zocli/zd setup` from
+your main checkout and refresh your shell's command cache. Run `type -a zd zo`
+to check both commands; the two clients store separate sign-ins.
 
 ## Accounts and workspaces
 
@@ -78,13 +81,26 @@ 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` prints the authorization URL on its own line on stderr, opens your
-browser, and waits for sign-in to finish. You can copy the URL into another
-browser window. The message is dim on interactive terminals and plain when
-redirected, with `--json`, or when `NO_COLOR` is set.
+`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.
+
+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
+one. A workspace you don't recognize means someone else approved your sign-in
+link; run `logout` to revoke it.
 
-`login --no-browser` prints the same URL and waits without opening a browser.
-It is not a device-code login. The browser must reach the CLI's localhost callback.
+Each poll waits up to 20 seconds. After a timeout or network error the CLI
+retries once at once, inside the issuer's 30-second redemption window, then
+resumes polling every `interval` seconds; `slow_down` and a 429 add 5 seconds.
 
 ## Tokens and logout
 
@@ -131,7 +147,9 @@ Before sending, the CLI durably marks the outcome uncertain. If syncing that
 marker fails after replacement, it attempts to restore the original ready
 credential and reports the storage error; no exchange was sent. A lost response
 may be retried once under the lock within the server's 30-second recovery
-window. Saving the received successor clears the marker. A crash, failure to
+window. A 429 comes only from the rate limiter, before any exchange, so the
+CLI restores the ready state, does not retry, and asks you to try again
+shortly; a 429 on that retry leaves the marker in place. Saving the received successor clears the marker. A crash, failure to
 replace the credential file, or unresolved second request leaves the marker
 in place and requires login;
 later processes cannot unknowingly replay that refresh token.

package/dist/auth.d.ts

@@ -12,6 +12,7 @@ export interface AuthOptions {
     environment?: Binding;
     env?: NodeJS.ProcessEnv;
     now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     signal?: AbortSignal;
 }
 export declare class AuthClient {
@@ -22,6 +23,7 @@ export declare class AuthClient {
     private readonly fetcher;
     private readonly env;
     private readonly now;
+    private readonly sleep;
     private readonly signal?;
     constructor(profile: Profile, directory: string, options?: AuthOptions);
     private locked;
@@ -31,6 +33,8 @@ export declare class AuthClient {
     session(): Promise<Session>;
     private revoke;
     private cleanup;
+    /** RFC 8628 section 3.4 polling until approval, denial or expiry. */
+    private poll;
     login(options?: LoginOptions): Promise<{
         cleanupPending: boolean;
     }>;

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 { loginCode } from "./login.js";
+import { browserAvailable, DEVICE_CODE_GRANT, deviceAuthorization, 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";
+// 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;
 function tokens(raw, now) {
     if (!record(raw) ||
         raw.error !== undefined ||
@@ -36,6 +39,7 @@ export class AuthClient {
     fetcher;
     env;
     now;
+    sleep;
     signal;
     constructor(profile, directory, options = {}) {
         this.profile = profile;
@@ -45,6 +49,7 @@ export class AuthClient {
         this.fetcher = options.fetch ?? fetch;
         this.env = options.env ?? process.env;
         this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? pause;
         this.signal = options.signal;
     }
     async locked(work, signal = this.signal) {
@@ -97,7 +102,7 @@ export class AuthClient {
             refreshState: raw.refreshState,
         };
     }
-    async tokenRequest(form, signal = this.signal) {
+    async tokenRequest(form, signal = this.signal, timeoutMs) {
         const issuedAt = this.now();
         return tokens(await requestJson(`${this.binding.issuer}/zo-system-api/oauth/token`, {
             method: "POST",
@@ -107,7 +112,7 @@ export class AuthClient {
                 client_id: this.binding.clientId,
                 resource: this.binding.audience,
             }),
-        }, this.fetcher), issuedAt);
+        }, this.fetcher, timeoutMs === undefined ? {} : { timeoutMs }), issuedAt);
     }
     async accessToken() {
         throwIfInterrupted(this.signal);
@@ -150,6 +155,13 @@ export class AuthClient {
             }
             catch (error) {
                 throwIfInterrupted(this.signal);
+                if (error instanceof RequestFailure && error.status === 429) {
+                    // Only the rate limiter answers 429, before any exchange, so the
+                    // refresh token is unused. Retrying now would hit the same limit.
+                    credential.refreshState = "ready";
+                    await writePrivate(this.path, credential);
+                    throw new CliError("Too many sign-in requests right now. Try again shortly.", 5, "rate_limited");
+                }
                 // Two eight-second requests fit the issuer's thirty-second recovery
                 // window. Wall time also catches suspension of the monotonic clock.
                 const elapsed = this.now() - startedAt;
@@ -208,6 +220,61 @@ export class AuthClient {
             throwIfInterrupted(signal);
         }
     }
+    /** RFC 8628 section 3.4 polling until approval, denial or expiry. */
+    async poll(device, signal) {
+        const deadline = this.now() + device.expiresInMs;
+        const form = {
+            grant_type: DEVICE_CODE_GRANT,
+            device_code: device.deviceCode,
+        };
+        const expired = () => new CliError("Login timed out. Run zo login to try again.", 3, "login_timeout");
+        let interval = device.intervalMs;
+        let retryNow = false;
+        for (;;) {
+            if (!retryNow)
+                await this.sleep(interval, signal);
+            throwIfInterrupted(signal);
+            if (this.now() >= deadline)
+                throw expired();
+            const retry = retryNow;
+            retryNow = false;
+            try {
+                return await this.tokenRequest(form, signal, DEVICE_POLL_TIMEOUT_MS);
+            }
+            catch (error) {
+                throwIfInterrupted(signal);
+                if (!(error instanceof RequestFailure))
+                    throw error;
+                if (error.status === 400) {
+                    if (error.code === "authorization_pending")
+                        continue;
+                    if (error.code === "slow_down") {
+                        interval += 5_000;
+                        continue;
+                    }
+                    if (error.code === "access_denied")
+                        throw new CliError("Authorization was denied. Run zo login to try again.", 4, "access_denied");
+                    if (error.code === "expired_token")
+                        throw expired();
+                    if (error.code === "invalid_grant")
+                        throw new CliError("This sign-in request can no longer be completed. Run zo login again.", 3, "invalid_grant");
+                    throw error;
+                }
+                // The rate limiter answered before the issuer saw the poll.
+                if (error.status === 429) {
+                    interval += 5_000;
+                    continue;
+                }
+                // A timeout, network error or 5xx may have lost an approval the issuer
+                // already redeemed. One immediate retry gets the same refresh token.
+                if (error.ambiguous) {
+                    retryNow = !retry;
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
     async login(options = {}) {
         const signal = this.signal && options.signal
             ? AbortSignal.any([this.signal, options.signal])
@@ -218,13 +285,18 @@ export class AuthClient {
         return this.locked(async () => {
             const previous = await this.read();
             throwIfInterrupted(signal);
-            const code = await loginCode(this.binding.issuer, this.binding.audience, this.binding.clientId, { ...options, signal });
-            const active = await this.tokenRequest({
-                grant_type: "authorization_code",
-                code: code.code,
-                code_verifier: code.verifier,
-                redirect_uri: code.redirectUri,
-            }, 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 credential = {
                 version: 1,
                 binding: this.binding,