@zocomputer/cli 0.2.2 → 0.4.0

package/README.md

@@ -11,15 +11,14 @@ 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
-export PATH="$HOME/.local/bin:$PATH"
-zo --version
 ```
 
-It includes Node, verifies the archive, and keeps versions under
+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. 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)
+symlink, and adds `~/.local/bin` to your shell's PATH configuration unless it's
+already on PATH. Run `zo update` to upgrade, or re-run the installer; `--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:
@@ -30,9 +29,9 @@ zo --version
 zo login
 ```
 
-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.
+Run the same install command again to upgrade; `zo update` refuses an npm
+installation and names this command. The CLI installs its matching public SDK
+dependency. It performs no update check when you run a command.
 
 To try the CLI without installing it globally:
 
@@ -97,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
@@ -126,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 };
         });
     }
 }

package/dist/commands.js

@@ -97,6 +97,7 @@ export function completionScript(shell) {
             "actions",
             "rpc",
             "completion",
+            "update",
             "status",
             "token",
             "list",

package/dist/generated/commands.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate-commands.mjs. Do not edit.
 export const commandManifest = {
-    schemaDigest: "sha256:3ea715bdec97fa1eee17b34583dc048bd5576ca2679b41cbc8f515f56a89e4ee",
+    schemaDigest: "sha256:f3723f93d9d519ebe2517e16cb3db50c99b38e60b9705187006ada3eaeb4e391",
     commands: [
         {
             action: "zo.activity.list",
@@ -507,7 +507,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Validate a payload against an active event definition and publish the occurrence durably under a caller-scoped idempotency key.",
-                    inputJson: '{"additionalProperties":false,"description":"The payload and its caller-scoped idempotency key (1 to 255 printable ASCII\\ncharacters). Every envelope attribute (``id``, ``source``, ``type``, ``time``,\\nthe workspace, the definition and the causal fields) is derived by the server\\nand rejected as input.","properties":{"event_id":{"title":"Event Id","type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","title":"Idempotency Key","type":"string"},"data":{"additionalProperties":{"x-zo-json-value":true},"title":"Data","type":"object"},"subject":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Subject"}},"required":["event_id","idempotency_key","data"],"title":"EventDispatchInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"description":"The payload and an optional caller-scoped idempotency key (1 to 255 printable ASCII\\ncharacters). Every envelope attribute (``id``, ``source``, ``type``, ``time``,\\nthe workspace, the definition and the causal fields) is derived by the server\\nand rejected as input.","properties":{"event_id":{"title":"Event Id","type":"string"},"idempotency_key":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^[!-~]{1,255}$","type":"string"},{"type":"null"}],"default":null,"title":"Idempotency Key"},"data":{"additionalProperties":{"x-zo-json-value":true},"title":"Data","type":"object"},"subject":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Subject"}},"required":["event_id","data"],"title":"EventDispatchInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -968,6 +968,19 @@ export const commandManifest = {
                 },
             ],
         },
+        {
+            action: "zo.model.list",
+            path: ["model", "list"],
+            versions: [
+                {
+                    version: 1,
+                    description: "List the models this workspace can call, each with its ID, capabilities, accepted file types, reasoning levels, limits and current prices.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"ModelListInput","type":"object"}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc"],"default":"id.asc"},"filter":{"additionalProperties":false,"properties":{"capability":{"anyOf":[{"enum":["text","structured_output","embedding","rerank","image","speech","transcription","video"],"type":"string"},{"type":"null"}],"default":null,"description":"Only models with this capability.","title":"Capability"}},"type":"object","required":[],"default":{}}},"required":[]}',
+                    resultKind: "inline",
+                },
+            ],
+        },
         {
             action: "zo.oauth_app.create",
             path: ["oauth-app", "create"],
@@ -1457,79 +1470,6 @@ export const commandManifest = {
                 },
             ],
         },
-        {
-            action: "zo.vault.create",
-            path: ["vault", "create"],
-            versions: [
-                {
-                    version: 1,
-                    description: "Store a pasted credential, such as an API key, with the hosts it may be sent to. The value is never returned.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"display_name":{"maxLength":256,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","maxLength":2000,"title":"Description","type":"string"},"value":{"description":"Secret: the credential. Stored sealed and never returned.","maxLength":16384,"minLength":1,"title":"Value","type":"string"},"environment_variable":{"anyOf":[{"pattern":"^[A-Z_][A-Z0-9_]{0,127}$","type":"string"},{"type":"null"}],"default":null,"description":"The environment variable name a machine gets the value under, such as `OPENAI_API_KEY`.","title":"Environment Variable"},"injections":{"default":[],"items":{"$ref":"#/$defs/VaultInjection"},"maxItems":10,"title":"Injections","type":"array"},"visibility":{"default":"workspace","description":"`workspace` (default): every member can use it. `protected`: only you, and whoever you share it with; workspace-wide grants don\'t reach it. Fixed at creation.","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","display_name","value"],"title":"VaultCreateInput","type":"object","$defs":{"BasicFormat":{"additionalProperties":false,"properties":{"type":{"const":"basic","description":"`Basic` with base64 of `<username>:<value>`.","title":"Type","type":"string"},"username":{"pattern":"^[^:]{1,256}$","title":"Username","type":"string"}},"required":["type","username"],"title":"BasicFormat","type":"object"},"BearerFormat":{"additionalProperties":false,"properties":{"type":{"const":"bearer","description":"`Bearer <value>`.","title":"Type","type":"string"}},"required":["type"],"title":"BearerFormat","type":"object"},"HeaderLocation":{"additionalProperties":false,"properties":{"type":{"const":"header","title":"Type","type":"string"},"name":{"description":"The header to set, such as `Authorization` or `X-API-Key`.","pattern":"^[A-Za-z0-9!#$%&\'*+.^_`|~-]{1,128}$","title":"Name","type":"string"}},"required":["type","name"],"title":"HeaderLocation","type":"object"},"RawFormat":{"additionalProperties":false,"properties":{"type":{"const":"raw","description":"The value as it is.","title":"Type","type":"string"}},"required":["type"],"title":"RawFormat","type":"object"},"VaultInjection":{"additionalProperties":false,"description":"Where and how the value is sent on requests to ``hosts``. A host appears\\nin at most one entry of a vault\'s list.","properties":{"hosts":{"items":{"description":"An exact lowercase DNS name, such as `api.openai.com`: no wildcard, port or path.","maxLength":253,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$","type":"string"},"maxItems":20,"minItems":1,"title":"Hosts","type":"array"},"location":{"$ref":"#/$defs/HeaderLocation"},"format":{"discriminator":{"mapping":{"basic":"#/$defs/BasicFormat","bearer":"#/$defs/BearerFormat","raw":"#/$defs/RawFormat"},"propertyName":"type"},"oneOf":[{"$ref":"#/$defs/BearerFormat"},{"$ref":"#/$defs/BasicFormat"},{"$ref":"#/$defs/RawFormat"}],"title":"Format"}},"required":["hosts","location","format"],"title":"VaultInjection","type":"object"}}}',
-                    resultKind: "inline",
-                },
-            ],
-        },
-        {
-            action: "zo.vault.delete",
-            path: ["vault", "delete"],
-            versions: [
-                {
-                    version: 1,
-                    description: "Delete a vault: its value is destroyed and every grant on it is revoked.",
-                    inputJson: '{"additionalProperties":false,"properties":{"vault_id":{"maxLength":200,"minLength":1,"title":"Vault Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"}},"required":["vault_id","expected_revision"],"title":"VaultTargetInput","type":"object"}',
-                    resultKind: "inline",
-                },
-            ],
-        },
-        {
-            action: "zo.vault.get",
-            path: ["vault", "get"],
-            versions: [
-                {
-                    version: 1,
-                    description: "Read a vault's settings. The value is never returned.",
-                    inputJson: '{"additionalProperties":false,"properties":{"vault_id":{"maxLength":200,"minLength":1,"title":"Vault Id","type":"string"}},"required":["vault_id"],"title":"VaultGetInput","type":"object"}',
-                    resultKind: "inline",
-                },
-            ],
-        },
-        {
-            action: "zo.vault.list",
-            path: ["vault", "list"],
-            versions: [
-                {
-                    version: 1,
-                    description: "List the vaults the caller can read in a workspace.",
-                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"VaultListInput","type":"object"}',
-                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":50,"description":"Rows per page, at most 100; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc","created_at.desc","created_at.asc","display_name.asc"],"default":"id.asc"}},"required":[]}',
-                    resultKind: "inline",
-                },
-            ],
-        },
-        {
-            action: "zo.vault.rotate",
-            path: ["vault", "rotate"],
-            versions: [
-                {
-                    version: 1,
-                    description: "Replace a vault's value. The previous value is destroyed.",
-                    inputJson: '{"additionalProperties":false,"properties":{"vault_id":{"maxLength":200,"minLength":1,"title":"Vault Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"value":{"description":"Secret: the credential. Stored sealed and never returned.","maxLength":16384,"minLength":1,"title":"Value","type":"string"}},"required":["vault_id","expected_revision","value"],"title":"VaultRotateInput","type":"object"}',
-                    resultKind: "inline",
-                },
-            ],
-        },
-        {
-            action: "zo.vault.update",
-            path: ["vault", "update"],
-            versions: [
-                {
-                    version: 1,
-                    description: "Change a vault's name, description, environment variable or injections against its current revision.",
-                    inputJson: '{"additionalProperties":false,"description":"Omitted fields keep their value; ``injections`` replaces the whole list.","properties":{"vault_id":{"maxLength":200,"minLength":1,"title":"Vault Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":256,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"`\\"\\"` clears the description.","title":"Description"},"environment_variable":{"anyOf":[{"pattern":"^([A-Z_][A-Z0-9_]{0,127})?$","type":"string"},{"type":"null"}],"default":null,"description":"`\\"\\"` clears the variable.","title":"Environment Variable"},"injections":{"anyOf":[{"items":{"$ref":"#/$defs/VaultInjection"},"maxItems":10,"type":"array"},{"type":"null"}],"default":null,"title":"Injections"}},"required":["vault_id","expected_revision"],"title":"VaultUpdateInput","type":"object","$defs":{"BasicFormat":{"additionalProperties":false,"properties":{"type":{"const":"basic","description":"`Basic` with base64 of `<username>:<value>`.","title":"Type","type":"string"},"username":{"pattern":"^[^:]{1,256}$","title":"Username","type":"string"}},"required":["type","username"],"title":"BasicFormat","type":"object"},"BearerFormat":{"additionalProperties":false,"properties":{"type":{"const":"bearer","description":"`Bearer <value>`.","title":"Type","type":"string"}},"required":["type"],"title":"BearerFormat","type":"object"},"HeaderLocation":{"additionalProperties":false,"properties":{"type":{"const":"header","title":"Type","type":"string"},"name":{"description":"The header to set, such as `Authorization` or `X-API-Key`.","pattern":"^[A-Za-z0-9!#$%&\'*+.^_`|~-]{1,128}$","title":"Name","type":"string"}},"required":["type","name"],"title":"HeaderLocation","type":"object"},"RawFormat":{"additionalProperties":false,"properties":{"type":{"const":"raw","description":"The value as it is.","title":"Type","type":"string"}},"required":["type"],"title":"RawFormat","type":"object"},"VaultInjection":{"additionalProperties":false,"description":"Where and how the value is sent on requests to ``hosts``. A host appears\\nin at most one entry of a vault\'s list.","properties":{"hosts":{"items":{"description":"An exact lowercase DNS name, such as `api.openai.com`: no wildcard, port or path.","maxLength":253,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$","type":"string"},"maxItems":20,"minItems":1,"title":"Hosts","type":"array"},"location":{"$ref":"#/$defs/HeaderLocation"},"format":{"discriminator":{"mapping":{"basic":"#/$defs/BasicFormat","bearer":"#/$defs/BearerFormat","raw":"#/$defs/RawFormat"},"propertyName":"type"},"oneOf":[{"$ref":"#/$defs/BearerFormat"},{"$ref":"#/$defs/BasicFormat"},{"$ref":"#/$defs/RawFormat"}],"title":"Format"}},"required":["hosts","location","format"],"title":"VaultInjection","type":"object"}}}',
-                    resultKind: "inline",
-                },
-            ],
-        },
         {
             action: "zo.web.fetch",
             path: ["web", "fetch"],
@@ -1561,7 +1501,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Create a Website address in a workspace. Describe what this Website is for in the user's terms.",
-                    inputJson: '{"additionalProperties":false,"properties":{"tags":{"default":[],"items":{"description":"A tag ID or name; unknown names are created, unknown IDs are refused.","maxLength":256,"minLength":1,"type":"string"},"maxItems":100,"title":"Tags","type":"array"},"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"slug":{"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$","title":"Slug","type":"string"},"display_name":{"maxLength":200,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this Website is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"}},"required":["workspace_id","slug","display_name"],"title":"WebsiteCreateInput","type":"object"}',
+                    inputJson: '{"additionalProperties":false,"properties":{"tags":{"default":[],"items":{"description":"A tag ID or name; unknown names are created, unknown IDs are refused.","maxLength":256,"minLength":1,"type":"string"},"maxItems":100,"title":"Tags","type":"array"},"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"},"slug":{"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$","title":"Slug","type":"string"},"display_name":{"maxLength":200,"minLength":1,"title":"Display Name","type":"string"},"description":{"default":"","description":"Describe what this Website is for in the user\'s terms.","maxLength":2000,"title":"Description","type":"string"},"visibility":{"default":"workspace","enum":["workspace","protected"],"title":"Visibility","type":"string"},"access":{"default":"public","enum":["public","authenticated"],"title":"Access","type":"string"}},"required":["workspace_id","slug","display_name"],"title":"WebsiteCreateInput","type":"object"}',
                     resultKind: "inline",
                 },
             ],
@@ -1610,7 +1550,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Update a Website display name or custom hostname.",
-                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this Website is for in the user\'s terms.","title":"Description"},"custom_hostname":{"anyOf":[{"$ref":"#/$defs/CustomHostnameChange"},{"type":"null"}],"default":null}},"required":["website_id","expected_revision"],"title":"WebsiteUpdateInput","type":"object","$defs":{"CustomHostnameChange":{"additionalProperties":false,"properties":{"hostname":{"anyOf":[{"maxLength":253,"minLength":4,"type":"string"},{"type":"null"}],"title":"Hostname"}},"required":["hostname"],"title":"CustomHostnameChange","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"display_name":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Describe what this Website is for in the user\'s terms.","title":"Description"},"custom_hostname":{"anyOf":[{"$ref":"#/$defs/CustomHostnameChange"},{"type":"null"}],"default":null},"access":{"anyOf":[{"enum":["public","authenticated"],"type":"string"},{"type":"null"}],"default":null,"title":"Access"}},"required":["website_id","expected_revision"],"title":"WebsiteUpdateInput","type":"object","$defs":{"CustomHostnameChange":{"additionalProperties":false,"properties":{"hostname":{"anyOf":[{"maxLength":253,"minLength":4,"type":"string"},{"type":"null"}],"title":"Hostname"}},"required":["hostname"],"title":"CustomHostnameChange","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1622,7 +1562,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Create an unpublished Website route.",
-                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"path":{"maxLength":1024,"minLength":1,"title":"Path","type":"string"},"target":{"discriminator":{"mapping":{"function":"#/$defs/FunctionRouteConfigInput","kb":"#/$defs/KbRouteConfigInput","machine":"#/$defs/MachineRouteConfigInput"},"propertyName":"kind"},"oneOf":[{"$ref":"#/$defs/FunctionRouteConfigInput"},{"$ref":"#/$defs/MachineRouteConfigInput"},{"$ref":"#/$defs/KbRouteConfigInput"}],"title":"Target"},"acknowledge_bound_accounts":{"default":[],"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":8,"title":"Acknowledge Bound Accounts","type":"array"}},"required":["website_id","expected_revision","path","target"],"title":"RouteCreateInput","type":"object","$defs":{"FunctionInputMapping":{"additionalProperties":false,"properties":{"handler":{"default":"http","maxLength":200,"minLength":1,"title":"Handler","type":"string"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"title":"FunctionInputMapping","type":"object","required":[]},"FunctionRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"function","title":"Kind","type":"string"},"function_id":{"maxLength":200,"minLength":1,"title":"Function Id","type":"string"},"deployment_id":{"maxLength":200,"minLength":1,"title":"Deployment Id","type":"string"},"input_mapping":{"$ref":"#/$defs/FunctionInputMapping"}},"required":["kind","function_id","deployment_id"],"title":"FunctionRouteConfigInput","type":"object"},"KbRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"kb","title":"Kind","type":"string"},"kb_path":{"maxLength":4096,"minLength":1,"title":"Kb Path","type":"string"},"spa_fallback":{"default":false,"title":"Spa Fallback","type":"boolean"},"published_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published As Of"}},"required":["kind","kb_path"],"title":"KbRouteConfigInput","type":"object"},"MachineRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"machine","title":"Kind","type":"string"},"machine_id":{"maxLength":200,"minLength":1,"title":"Machine Id","type":"string"},"port":{"maximum":65535,"minimum":1,"title":"Port","type":"integer"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"required":["kind","machine_id","port"],"title":"MachineRouteConfigInput","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"path":{"maxLength":1024,"minLength":1,"title":"Path","type":"string"},"target":{"discriminator":{"mapping":{"function":"#/$defs/FunctionRouteConfigInput","kb":"#/$defs/KbRouteConfigInput","machine":"#/$defs/MachineRouteConfigInput"},"propertyName":"kind"},"oneOf":[{"$ref":"#/$defs/FunctionRouteConfigInput"},{"$ref":"#/$defs/MachineRouteConfigInput"},{"$ref":"#/$defs/KbRouteConfigInput"}],"title":"Target"},"acknowledge_bound_accounts":{"default":[],"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":8,"title":"Acknowledge Bound Accounts","type":"array"},"access":{"default":"authenticated","enum":["public","authenticated"],"title":"Access","type":"string"}},"required":["website_id","expected_revision","path","target"],"title":"RouteCreateInput","type":"object","$defs":{"FunctionInputMapping":{"additionalProperties":false,"properties":{"handler":{"default":"http","maxLength":200,"minLength":1,"title":"Handler","type":"string"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"title":"FunctionInputMapping","type":"object","required":[]},"FunctionRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"function","title":"Kind","type":"string"},"function_id":{"maxLength":200,"minLength":1,"title":"Function Id","type":"string"},"deployment_id":{"maxLength":200,"minLength":1,"title":"Deployment Id","type":"string"},"input_mapping":{"$ref":"#/$defs/FunctionInputMapping"}},"required":["kind","function_id","deployment_id"],"title":"FunctionRouteConfigInput","type":"object"},"KbRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"kb","title":"Kind","type":"string"},"kb_path":{"maxLength":4096,"minLength":1,"title":"Kb Path","type":"string"},"spa_fallback":{"default":false,"title":"Spa Fallback","type":"boolean"},"published_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published As Of"}},"required":["kind","kb_path"],"title":"KbRouteConfigInput","type":"object"},"MachineRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"machine","title":"Kind","type":"string"},"machine_id":{"maxLength":200,"minLength":1,"title":"Machine Id","type":"string"},"port":{"maximum":65535,"minimum":1,"title":"Port","type":"integer"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"required":["kind","machine_id","port"],"title":"MachineRouteConfigInput","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],
@@ -1695,7 +1635,7 @@ export const commandManifest = {
                 {
                     version: 1,
                     description: "Update a Website route and recheck its published source.",
-                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"route_id":{"maxLength":200,"minLength":1,"title":"Route Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"path":{"anyOf":[{"maxLength":1024,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Path"},"target":{"anyOf":[{"discriminator":{"mapping":{"function":"#/$defs/FunctionRouteConfigInput","kb":"#/$defs/KbRouteConfigInput","machine":"#/$defs/MachineRouteConfigInput"},"propertyName":"kind"},"oneOf":[{"$ref":"#/$defs/FunctionRouteConfigInput"},{"$ref":"#/$defs/MachineRouteConfigInput"},{"$ref":"#/$defs/KbRouteConfigInput"}]},{"type":"null"}],"default":null,"title":"Target"},"acknowledge_bound_accounts":{"default":[],"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":8,"title":"Acknowledge Bound Accounts","type":"array"}},"required":["website_id","route_id","expected_revision"],"title":"RouteUpdateInput","type":"object","$defs":{"FunctionInputMapping":{"additionalProperties":false,"properties":{"handler":{"default":"http","maxLength":200,"minLength":1,"title":"Handler","type":"string"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"title":"FunctionInputMapping","type":"object","required":[]},"FunctionRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"function","title":"Kind","type":"string"},"function_id":{"maxLength":200,"minLength":1,"title":"Function Id","type":"string"},"deployment_id":{"maxLength":200,"minLength":1,"title":"Deployment Id","type":"string"},"input_mapping":{"$ref":"#/$defs/FunctionInputMapping"}},"required":["kind","function_id","deployment_id"],"title":"FunctionRouteConfigInput","type":"object"},"KbRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"kb","title":"Kind","type":"string"},"kb_path":{"maxLength":4096,"minLength":1,"title":"Kb Path","type":"string"},"spa_fallback":{"default":false,"title":"Spa Fallback","type":"boolean"},"published_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published As Of"}},"required":["kind","kb_path"],"title":"KbRouteConfigInput","type":"object"},"MachineRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"machine","title":"Kind","type":"string"},"machine_id":{"maxLength":200,"minLength":1,"title":"Machine Id","type":"string"},"port":{"maximum":65535,"minimum":1,"title":"Port","type":"integer"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"required":["kind","machine_id","port"],"title":"MachineRouteConfigInput","type":"object"}}}',
+                    inputJson: '{"additionalProperties":false,"properties":{"website_id":{"maxLength":200,"minLength":1,"title":"Website Id","type":"string"},"route_id":{"maxLength":200,"minLength":1,"title":"Route Id","type":"string"},"expected_revision":{"exclusiveMinimum":0,"maximum":9007199254740991,"title":"Expected Revision","type":"integer"},"path":{"anyOf":[{"maxLength":1024,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Path"},"target":{"anyOf":[{"discriminator":{"mapping":{"function":"#/$defs/FunctionRouteConfigInput","kb":"#/$defs/KbRouteConfigInput","machine":"#/$defs/MachineRouteConfigInput"},"propertyName":"kind"},"oneOf":[{"$ref":"#/$defs/FunctionRouteConfigInput"},{"$ref":"#/$defs/MachineRouteConfigInput"},{"$ref":"#/$defs/KbRouteConfigInput"}]},{"type":"null"}],"default":null,"title":"Target"},"acknowledge_bound_accounts":{"default":[],"items":{"maxLength":200,"minLength":1,"type":"string"},"maxItems":8,"title":"Acknowledge Bound Accounts","type":"array"},"access":{"anyOf":[{"enum":["public","authenticated"],"type":"string"},{"type":"null"}],"default":null,"title":"Access"}},"required":["website_id","route_id","expected_revision"],"title":"RouteUpdateInput","type":"object","$defs":{"FunctionInputMapping":{"additionalProperties":false,"properties":{"handler":{"default":"http","maxLength":200,"minLength":1,"title":"Handler","type":"string"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"title":"FunctionInputMapping","type":"object","required":[]},"FunctionRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"function","title":"Kind","type":"string"},"function_id":{"maxLength":200,"minLength":1,"title":"Function Id","type":"string"},"deployment_id":{"maxLength":200,"minLength":1,"title":"Deployment Id","type":"string"},"input_mapping":{"$ref":"#/$defs/FunctionInputMapping"}},"required":["kind","function_id","deployment_id"],"title":"FunctionRouteConfigInput","type":"object"},"KbRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"kb","title":"Kind","type":"string"},"kb_path":{"maxLength":4096,"minLength":1,"title":"Kb Path","type":"string"},"spa_fallback":{"default":false,"title":"Spa Fallback","type":"boolean"},"published_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published As Of"}},"required":["kind","kb_path"],"title":"KbRouteConfigInput","type":"object"},"MachineRouteConfigInput":{"additionalProperties":false,"properties":{"kind":{"const":"machine","title":"Kind","type":"string"},"machine_id":{"maxLength":200,"minLength":1,"title":"Machine Id","type":"string"},"port":{"maximum":65535,"minimum":1,"title":"Port","type":"integer"},"strip_prefix":{"default":false,"title":"Strip Prefix","type":"boolean"}},"required":["kind","machine_id","port"],"title":"MachineRouteConfigInput","type":"object"}}}',
                     resultKind: "inline",
                 },
             ],

package/dist/login.d.ts

@@ -1,16 +1,22 @@
 export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
-export interface LoginPrompt {
+/** The browser opened at `url` on this machine, or a device flow to approve anywhere. */
+export type LoginPrompt = {
+    flow: "browser";
+    url: string;
+} | {
+    flow: "device";
     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;
+    /** Use the device flow even when this machine can open a browser. */
+    device?: boolean;
     signal?: AbortSignal;
     platform?: NodeJS.Platform;
     announce?: (prompt: LoginPrompt) => void;
     openBrowser?: (url: string) => Promise<void>;
+    /** How long the loopback listener waits for the browser's callback. */
+    callbackTimeoutMs?: number;
 }
 export interface DeviceAuthorization {
     deviceCode: string;
@@ -25,6 +31,25 @@ export declare function openBrowser(url: string): Promise<void>;
  * 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 const CALLBACK_TIMEOUT_MS = 600000;
+export interface LoopbackAuthorization {
+    /** The authorization URL to open in the browser. */
+    url: string;
+    redirectUri: string;
+    codeVerifier: string;
+    /** Resolves with the authorization code from the one callback whose state matches. */
+    code: Promise<string>;
+    close: () => Promise<void>;
+}
+/**
+ * RFC 8252 loopback redirect with PKCE (RFC 7636): listen on 127.0.0.1 at an
+ * OS-assigned port until one callback carries the matching state, the timeout
+ * passes, or the signal aborts. The listener closes in every case.
+ */
+export declare function loopbackAuthorization(issuer: string, audience: string, clientId: string, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<LoopbackAuthorization>;
 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,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
 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";
@@ -19,6 +21,85 @@ export function browserAvailable(env, platform = process.platform) {
         return false;
     return platform === "darwin" || !!env.DISPLAY || !!env.WAYLAND_DISPLAY;
 }
+export const CALLBACK_TIMEOUT_MS = 600_000;
+const base64url = (bytes) => bytes.toString("base64url");
+const page = (heading, detail) => `<!doctype html><meta charset="utf-8"><title>Zo CLI</title><body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem"><h1 style="font-size:1.25rem">${heading}</h1><p>${detail}</p></body>`;
+/**
+ * Sends the page, then runs `then` once it is flushed: settling the login
+ * closes every connection, which would otherwise cut the page off.
+ */
+function answer(response, status, html, then) {
+    response.writeHead(status, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+        connection: "close",
+    });
+    response.end(html, then);
+}
+/**
+ * RFC 8252 loopback redirect with PKCE (RFC 7636): listen on 127.0.0.1 at an
+ * OS-assigned port until one callback carries the matching state, the timeout
+ * passes, or the signal aborts. The listener closes in every case.
+ */
+export async function loopbackAuthorization(issuer, audience, clientId, options = {}) {
+    throwIfInterrupted(options.signal);
+    const codeVerifier = base64url(randomBytes(32));
+    const state = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(codeVerifier).digest());
+    const result = Promise.withResolvers();
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (request.method !== "GET" || url.pathname !== "/callback")
+            return answer(response, 404);
+        const params = url.searchParams;
+        if (params.get("state") !== state)
+            return answer(response, 400, page("This sign-in link doesn't match", "Return to your terminal and run zo login again if it is still waiting."));
+        // RFC 9207: a response from another issuer is a mix-up, never a code to redeem.
+        if (params.get("iss") !== issuer) {
+            return answer(response, 400, page("Sign-in failed", "Return to your terminal and try again."), () => result.reject(new CliError("The sign-in service returned an invalid response.", 5, "invalid_response")));
+        }
+        const code = params.get("code");
+        if (params.get("error") === "access_denied") {
+            return answer(response, 200, page("Sign-in denied", "You can close this tab."), () => result.reject(new CliError("Authorization was denied. Run zo login to try again.", 4, "access_denied")));
+        }
+        if (params.has("error") || !code)
+            return answer(response, 400, page("Sign-in failed", "Return to your terminal and try again."), () => result.reject(new CliError("The sign-in service returned an invalid response.", 5, "invalid_response")));
+        answer(response, 200, page("Signed in to the Zo CLI", "You can close this tab and return to your terminal."), () => result.resolve(code));
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const { port } = server.address();
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const timer = setTimeout(() => result.reject(new CliError("Login timed out. Run zo login to try again.", 3, "login_timeout")), options.timeoutMs ?? CALLBACK_TIMEOUT_MS);
+    const abort = () => result.reject(new CliError("Interrupted.", 130, "interrupted"));
+    options.signal?.addEventListener("abort", abort, { once: true });
+    let closed;
+    const close = () => (closed ??= new Promise((resolve) => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", abort);
+        server.close(() => resolve());
+        server.closeAllConnections();
+    }));
+    // Stop listening after the one accepted callback, a failure or the timeout.
+    const code = result.promise.finally(close);
+    code.catch(() => { });
+    const url = new URL(`${issuer}/zo-system-api/oauth/authorize`);
+    url.search = new URLSearchParams({
+        response_type: "code",
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        code_challenge_method: "S256",
+        code_challenge: challenge,
+        state,
+        resource: audience,
+    }).toString();
+    return { url: url.href, redirectUri, codeVerifier, code, close };
+}
 export function pause(ms, signal) {
     throwIfInterrupted(signal);
     return new Promise((resolve, reject) => {

package/dist/output.js

@@ -55,7 +55,7 @@ export function writeRpcResult(result, options = {}) {
 }
 const detailFields = {
     invalid_envelope: ["reason"],
-    conflict: ["reason", "pointer"],
+    conflict: ["reason", "pointer", "route_ids", "total"],
     quota_exceeded: ["reason"],
     invalid_input: ["violations"],
     invalid_query: ["violations"],
@@ -120,7 +120,9 @@ export function safeDetails(code, details) {
                     return integer === undefined ? [] : [integer];
                 });
             }
-            else if (field === "function_ids" || field === "subscription_ids")
+            else if (field === "function_ids" ||
+                field === "subscription_ids" ||
+                field === "route_ids")
                 projected[field] = value.filter((item) => boundedString(item));
         }
     }

package/dist/profiles.d.ts

@@ -1,15 +1,20 @@
+/**
+ * The Zo CLI's OAuth client metadata document, served from www as its own
+ * client ID for both environments; its redirects are the loopback callbacks.
+ */
+export declare const CLIENT_ID = "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
 export declare const environments: {
     readonly production: {
         readonly issuer: "https://auth.zo.computer";
         readonly api: "https://api.zo.computer";
         readonly audience: "https://api.zo.computer/zo-system-api";
-        readonly clientId: "zo-public-cli";
+        readonly clientId: "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
     };
     readonly staging: {
         readonly issuer: "https://auth.zostaging.computer";
         readonly api: "https://api.zostaging.computer";
         readonly audience: "https://api.zostaging.computer/zo-system-api";
-        readonly clientId: "zo-public-cli";
+        readonly clientId: "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
     };
 };
 export type Environment = keyof typeof environments;

package/dist/profiles.js

@@ -1,18 +1,23 @@
 import { join } from "node:path";
 import { CliError, record, throwIfInterrupted } from "./errors.js";
 import { configDirectory, privateDirectory, readPrivate, withLock, writePrivate, } from "./storage.js";
+/**
+ * The Zo CLI's OAuth client metadata document, served from www as its own
+ * client ID for both environments; its redirects are the loopback callbacks.
+ */
+export const CLIENT_ID = "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
 export const environments = {
     production: {
         issuer: "https://auth.zo.computer",
         api: "https://api.zo.computer",
         audience: "https://api.zo.computer/zo-system-api",
-        clientId: "zo-public-cli",
+        clientId: CLIENT_ID,
     },
     staging: {
         issuer: "https://auth.zostaging.computer",
         api: "https://api.zostaging.computer",
         audience: "https://api.zostaging.computer/zo-system-api",
-        clientId: "zo-public-cli",
+        clientId: CLIENT_ID,
     },
 };
 export function profileName(name) {

package/dist/rpc.js

@@ -154,7 +154,7 @@ export async function runRpc(context, options, loadedCatalog) {
         });
     if (options.preview)
         return { kind: "preview", workspaceId: context.workspaceId, requestJson };
-    // Snapshot calls may run for 210 seconds; leave time to receive that result.
+    // A call may run for 210 seconds; leave time to receive its result.
     const timeout = AbortSignal.timeout(240_000);
     const signal = context.signal
         ? AbortSignal.any([context.signal, timeout])

package/dist/runner.js

@@ -18,6 +18,7 @@ Usage: zo <command> [--profile <name>] [--workspace <id>] [--json]
   rpc <action>         Invoke any callable action from JSON
   <resource> <action>  Invoke an installed built-in command
   completion <shell>  Print bash, zsh or fish completion (offline)
+  update               Install the latest standalone release
   --version            Show the installed CLI version
 
 Run zo <command> --help for options; for example, zo machine list --help.
@@ -25,8 +26,8 @@ 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 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",
+    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--device]\nOpen your browser to sign in and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--device prints a URL and code to approve on any device; login does the same when this machine can't open a browser.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
+    logout: "Usage: zo logout [--profile <name>]\nRevoke the saved sign-in and pending replaced sign-ins, then remove them from this computer. If revocation fails, logout says why and removes them anyway.\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",
     "auth token": "Usage: zo auth token [--profile <name>] [--headers]\nExplicitly print a short-lived access token; --headers prints Authorization JSON.\n",
@@ -39,6 +40,7 @@ const localHelp = {
     "actions describe": "Usage: zo actions describe <action> [--version <integer>] [--catalog scoped|all] [--json]\nShow live input, output and query schemas. Omit --version to inspect every published version.\n",
     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",
+    update: "Usage: zo update [--json]\nDownload the latest standalone release, verify it and switch the zo command to it. Sign-ins are kept.\nDoes nothing when this version is already the latest. An npm installation upgrades with npm install --global @zocomputer/cli@latest.\n",
 };
 // Printed after login so a first-time caller, person or agent, knows the next
 // command and that one sign-in serves the CLI, HTTP and MCP alike.
@@ -106,7 +108,7 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
         stdout.write((await import("./commands.js")).completionScript(args[1]));
         return;
     }
-    const local = ["login", "logout", "auth", "context"].includes(args[0] ?? "");
+    const local = ["login", "logout", "auth", "context", "update"].includes(args[0] ?? "");
     if (options.envelope && local)
         throw new CliError("--envelope is only supported for action invocation.");
     const controller = new AbortController();
@@ -123,8 +125,20 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             throwIfInterrupted(signal);
             writeJson(value, output);
         };
+        if (args[0] === "update") {
+            commandOptions(args.slice(1), []);
+            const { update } = await import("./update.js");
+            writeLocalJson(await update({
+                version: runtime.version,
+                env,
+                fetch: runtime.fetch,
+                signal,
+                stderr,
+            }));
+            return;
+        }
         if (args[0] === "login") {
-            const parsed = commandOptions(args.slice(1), ["environment"], ["no-browser"]);
+            const parsed = commandOptions(args.slice(1), ["environment"], ["device"]);
             const requested = parsed.values.get("environment");
             if (requested !== undefined &&
                 requested !== "production" &&
@@ -137,11 +151,11 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
                 signal,
             });
             const login = await auth.login({
-                noBrowser: parsed.flags.has("no-browser"),
+                device: parsed.flags.has("device"),
                 signal,
-                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`),
+                announce: (prompt) => stderr.write(prompt.flow === "browser"
+                    ? `Opening your browser to sign in. If it doesn't open, visit this URL on this computer:\n\n  ${prompt.url}\n\nWaiting for approval… (Ctrl-C to cancel)\n`
+                    : `To sign in, visit this URL on any device:\n\n  ${prompt.url}\n\nCode: ${prompt.userCode}. Approve only if your browser shows the same code.\nWaiting for approval… (Ctrl-C to cancel)\n`),
             });
             stderr.write(`\nApproved in the browser. Sign-in saved for profile ${profile.name}.\n`);
             if (login.cleanupPending)
@@ -207,13 +221,12 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             signal,
         });
         if (args[0] === "logout") {
-            const parsed = commandOptions(args.slice(1), [], ["local-only"]);
-            const localOnly = parsed.flags.has("local-only");
-            await auth.logout(localOnly);
+            commandOptions(args.slice(1), [], []);
+            const { warning } = await auth.logout();
             throwIfInterrupted(signal);
-            stderr.write(localOnly
-                ? "Local credentials removed. Server access was not revoked.\n"
-                : "Signed out; saved sign-ins revoked.\n");
+            stderr.write(warning === undefined
+                ? "Signed out; saved sign-ins revoked.\n"
+                : `Warning: ${warning}\nSigned out of this computer.\n`);
             return;
         }
         if (args[0] === "auth" && args[1] === "token") {

package/dist/update.d.ts

@@ -0,0 +1,21 @@
+import type { FetchLike } from "@zocomputer/system-api";
+export interface UpdateOptions {
+    /** The standalone executable's version. npm installations have none. */
+    version?: string;
+    execPath?: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+    stderr?: {
+        write(text: string): unknown;
+    };
+    /** Runs the release installer and resolves with its exit status. */
+    runInstaller?: (script: Buffer, args: string[]) => Promise<number>;
+}
+export interface UpdateResult {
+    /** The version the zo command runs after this update. */
+    version: string;
+    latest_version: string;
+    updated: boolean;
+}
+export declare function update(options?: UpdateOptions): Promise<UpdateResult>;

package/dist/update.js

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, readlink, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { CliError, record, safeText, throwIfInterrupted } from "./errors.js";
+const releases = "https://github.com/zocomputer/zo-cli/releases";
+const installCommand = "curl -fsSL https://zo.computer/install.sh | sh";
+const versionPattern = /^(\d+)\.(\d+)\.(\d+)(-[A-Za-z0-9][A-Za-z0-9.-]*)?$/;
+// The installer links <data home>/zo/cli/releases/<version>/<target>/zo.
+const managedPath = /^(\/.*\/zo\/cli)\/releases\/[^/]+\/[^/]+\/zo$/;
+function unreachable() {
+    return new CliError("Could not download the latest Zo CLI release. Check your connection and try again.", 5, "transport_error");
+}
+/** Follows redirects by hand so a release can never be fetched over plain HTTP. */
+async function download(url, fetcher, signal) {
+    const timeout = AbortSignal.timeout(60_000);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    try {
+        let target = url;
+        for (let hop = 0; hop < 5; hop++) {
+            const response = await fetcher(target, {
+                redirect: "manual",
+                signal: combined,
+            });
+            const location = response.headers.get("location");
+            if (response.status >= 300 && response.status < 400 && location) {
+                await response.body?.cancel();
+                target = new URL(location, target).href;
+                if (!target.startsWith("https://"))
+                    break;
+                continue;
+            }
+            if (!response.ok || !response.body)
+                break;
+            // The manifest and installer are a few kilobytes; refuse anything else.
+            const reader = response.body.getReader();
+            const chunks = [];
+            for (let size = 0;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return Buffer.concat(chunks);
+                size += value.length;
+                if (size > 1_048_576) {
+                    await reader.cancel().catch(() => { });
+                    break;
+                }
+                chunks.push(value);
+            }
+            break;
+        }
+    }
+    catch {
+        throwIfInterrupted(signal);
+    }
+    throw unreachable();
+}
+function isNewer(candidate, current) {
+    const next = versionPattern.exec(candidate);
+    const now = versionPattern.exec(current);
+    if (!next || !now)
+        return false;
+    for (const index of [1, 2, 3]) {
+        const difference = Number(next[index]) - Number(now[index]);
+        if (difference !== 0)
+            return difference > 0;
+    }
+    // 0.4.0 follows 0.4.0-rc.1; the latest release is never a prerelease.
+    return now[4] !== undefined && next[4] === undefined;
+}
+/** Finds the installer's link on PATH, else in the installer's default directory. */
+async function managedCommand(executable, env) {
+    const directories = (env.PATH ?? "").split(delimiter);
+    directories.push(join(env.HOME ?? homedir(), ".local/bin"));
+    let shadowedBy;
+    for (const directory of directories) {
+        if (!isAbsolute(directory))
+            continue;
+        const command = join(directory, "zo");
+        const resolved = await realpath(command).catch(() => undefined);
+        if (resolved === undefined)
+            continue;
+        if (resolved !== executable) {
+            shadowedBy ??= command;
+            continue;
+        }
+        // The installer replaces only a link it wrote, so an alias that points at
+        // that link is passed over for the link itself.
+        const root = managedPath.exec(await readlink(command).catch(() => ""))?.[1];
+        if (root)
+            return { directory, root, shadowedBy };
+    }
+    return undefined;
+}
+function shell(env, signal, stderr) {
+    return (script, args) => new Promise((resolve, reject) => {
+        // The installer reads itself from stdin, as it does under `curl | sh`.
+        // It gets its own process group so an interrupt also stops its download;
+        // a shell alone would wait for curl before running its trap.
+        const child = spawn("/bin/sh", ["-s", "--", ...args], {
+            env,
+            detached: true,
+            stdio: ["pipe", "ignore", "pipe"],
+        });
+        const stop = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGTERM");
+            }
+            catch {
+                /* The installer already exited. */
+            }
+        };
+        signal?.addEventListener("abort", stop, { once: true });
+        if (signal?.aborted)
+            stop();
+        child.on("error", reject);
+        child.on("close", (code) => {
+            signal?.removeEventListener("abort", stop);
+            resolve(code ?? 1);
+        });
+        child.stderr.on("data", (chunk) => stderr.write(String(chunk)));
+        // A shell that exits early closes the pipe; its status reports why.
+        child.stdin.on("error", () => { });
+        child.stdin.end(script);
+    });
+}
+export async function update(options = {}) {
+    const env = options.env ?? process.env;
+    const stderr = options.stderr ?? process.stderr;
+    const current = options.version;
+    if (current === undefined)
+        throw new CliError("zo update replaces the standalone executable. This zo was installed with npm; run npm install --global @zocomputer/cli@latest instead.", 2, "unsupported_installation");
+    const unmanaged = (reason) => new CliError(`${reason} Install the latest release with: ${installCommand}`, 2, "unsupported_installation");
+    const executable = await realpath(options.execPath ?? process.execPath);
+    const command = await managedCommand(executable, env);
+    if (managedPath.test(executable) && !command)
+        throw unmanaged("No zo command on your PATH links to this executable.");
+    const marker = command
+        ? await readFile(join(command.root, ".installer-v1"), "utf8").catch(() => "")
+        : "";
+    if (!command || marker.trim() !== "zo-cli-installer-v1")
+        throw unmanaged("This zo was not installed by the standalone installer, so it cannot update itself.");
+    const fetcher = options.fetch ?? fetch;
+    let manifest;
+    try {
+        manifest = JSON.parse((await download(`${releases}/latest/download/release.json`, fetcher, options.signal)).toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+    }
+    const invalid = new CliError("The latest Zo CLI release could not be verified. Nothing was changed.", 5, "invalid_response");
+    if (!record(manifest) ||
+        manifest.schema_version !== 1 ||
+        typeof manifest.cli_version !== "string" ||
+        !versionPattern.test(manifest.cli_version) ||
+        typeof manifest.installer_sha256 !== "string")
+        throw invalid;
+    const latest = manifest.cli_version;
+    if (!isNewer(latest, current)) {
+        stderr.write(latest === current
+            ? `zo ${current} is the latest version.\n`
+            : `zo ${current} is newer than the latest release, ${latest}. Nothing to update; to install ${latest}, run: ${installCommand}\n`);
+        return { version: current, latest_version: latest, updated: false };
+    }
+    // Each release publishes the installer pinned to its own version.
+    const installer = await download(`${releases}/download/v${latest}/install.sh`, fetcher, options.signal);
+    if (createHash("sha256").update(installer).digest("hex") !==
+        manifest.installer_sha256)
+        throw invalid;
+    stderr.write(`Updating zo ${current} to ${latest}…\n`);
+    // The installer derives its root from XDG_DATA_HOME, which may have changed
+    // since installation; the link records the root it must keep using.
+    const run = options.runInstaller ??
+        shell({ ...env, XDG_DATA_HOME: dirname(dirname(command.root)) }, options.signal, stderr);
+    let status;
+    try {
+        status = await run(installer, [
+            "--bin-dir",
+            command.directory,
+            "--no-modify-path",
+        ]);
+    }
+    catch {
+        status = 1;
+    }
+    throwIfInterrupted(options.signal);
+    if (status !== 0)
+        throw new CliError(`The update did not finish. zo ${current} is still installed.`, 5, "update_failed");
+    stderr.write(`Updated zo to ${latest}. Sign-ins are unchanged.\n`);
+    if (command.shadowedBy)
+        stderr.write(`Another zo at ${safeText(command.shadowedBy)} comes first on your PATH and was not updated.\n`);
+    return { version: latest, latest_version: latest, updated: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "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.4"
+    "@zocomputer/system-api": "0.3.0"
   },
   "publishConfig": {
     "access": "public",