@vigilbase/cli 0.2.2 → 0.2.4

package/ONE.md

@@ -95,4 +95,4 @@ vigilbase support tickets [--all] [--limit 1..100] [--customer-id <uuid>] [--jso
 
 ## Related commands and validation
 
-See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.
+See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.

package/README.md

@@ -28,14 +28,17 @@ supported on Windows yet; public tools and `cloudflare-checkup` still work there
 
 | Reference | Covers |
 | --- | --- |
-| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
-| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
-| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
-| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
-| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |
+| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
+| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
+| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
+| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
+| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |
 
 These files ship with the package. Built-in help: `vigilbase <command> --help`
-or `vigilbase help <command>`; `vigilbase help <tool>` shows how to run a tool.
+or `vigilbase help <command>`; `vigilbase help <command> <subcommand>` (for
+example `vigilbase help cf zones`) shows the same help as
+`vigilbase cf zones --help`, and `vigilbase help <tool>` shows how to run a
+tool. The library is ESM-only: use `import()`, not `require()`.
 
 ## Examples
 
@@ -143,7 +146,7 @@ read-only Cloudflare API token instead. When you are done:
 npx @vigilbase/cli cloudflare-checkup logout   # removes the read-only cf login and the cf it installed
 ```
 
-See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) for
+See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/LOCAL.md) for
 every step, what is uploaded and the error codes.
 
 ## Public tools and sign-in
@@ -152,48 +155,106 @@ every step, what is uploaded and the error codes.
   `run security-headers|email-security` call the public API anonymously and
   never read your saved sign-in, so an expired, broken or unreachable sign-in
   cannot make them fail. `--public` and `--via public` force the public API for
-  any tool.
+  the public tools (`security-headers`, `email-security`).
 - **One-only scans need a sign-in.** `website-security`, `react2shell`,
   `fortibleed-check` and any run with `--via one` go through Vigilbase One.
   Without a usable sign-in they stop with
-  ``This tool needs a Vigilbase One sign-in: run `vigilbase login`.``
+  ``This command needs a Vigilbase One sign-in: run `vigilbase login`.``
+  (code `NOT_SIGNED_IN`), as every One command does. With `--public` or
+  `--via public` a One-only tool stops before any request:
+  ``website-security runs only through Vigilbase One: drop --public and run `vigilbase login`.``
+  `run` with a tool name it doesn't know fails locally with
+  ``Unknown tool "<name>". Run `vigilbase list` for the allowlist.``
+  (code `INVALID_ARGUMENT`).
+- **Scan quota.** Public scans share an hourly quota of 20 scans per client IP
+  address and 20 per target (1,000 an hour overall). When it is used up,
+  vigilbase.com answers HTTP 429 (`rate_limit_exceeded`) and the CLI exits 2
+  with the delay until the quota resets (up to an hour; `retryAfterSec` in
+  JSON). The CLI never retries on its own.
 - **`list`** reads your saved sign-in from disk only (no refresh, no network,
   no waiting for another command) to show which tools you can run. If it can't
   use it, it lists the tools as signed out and prints one line on stderr:
   ``Couldn't use your saved sign-in (<reason>); running anonymously. Run `vigilbase login` to fix.``
   When the reason is an unsafe config path or credentials file, the line ends
   with its fix instead (see [Directory checks](#directory-checks)).
-- **`doctor`** reports a sign-in problem as its own failed `signIn` check.
+- **`doctor`** reports a sign-in problem as its own failed `signIn` check,
+  including a sign-in saved for another One origin, Identity issuer or client
+  ID: ``Saved for a different One origin, Identity issuer or client ID. Pass the matching --one-url, --auth-url and --client-id, or run `vigilbase login`.``
 
 ## Automation and output
 
 Every command supports `-j` / `--json`. JSON goes to stdout; progress and
-browser instructions go to stderr. Progress animations are off for JSON, CI and
-output that isn't a terminal. List commands never fetch every page on their
-own: keep the JSON pagination fields to fetch the next page. Text output shows
-complete identifiers. Human-readable output removes terminal control sequences
-and bidirectional overrides from everything it prints, including names, tool
-results, skills and errors. JSON keeps successful response data, with control
-characters escaped.
-
-`vigilbase --version` prints the banner in a terminal and only the version
-number when stdout is a pipe or a file, so `v=$(vigilbase --version)` works in
-scripts. With `--json` it prints `{"name":"@vigilbase/cli","version":"…"}`.
+browser instructions go to stderr. Errors are JSON on stdout whenever `--json`
+or `-j` is given, also inside a cluster of short flags (`-hj`) and as
+`--json=…`; a `--json` after `--` is an argument, not the flag. Commands are
+matched in any case (`vigilbase LIST` is `vigilbase list`).
+
+Progress animations are off for `--json`, for output that isn't a terminal, in
+CI (`CI` set to anything but `0` or `false`, in any case), with `TERM=dumb` and
+with `VIGILBASE_CLI_NO_PROGRESS=1`. `NO_COLOR` doesn't turn them off, because
+the spinner has no colour. The spinner fits the terminal width, and Ctrl-C
+during a scan clears its line and exits 130. The same CI rule decides the
+checkup's terminal UI and its colours and opening a browser (login, billing),
+so `CI=yes` neither animates nor opens a browser.
+
+List commands never fetch every page on their own: keep the JSON pagination
+fields to fetch the next page. Text output shows complete identifiers: the
+first column of `runs list` works with `runs get`, and `watchdog list` starts
+with the target ID that `watchdog scans --target-id` takes.
+
+Human-readable output removes terminal control sequences, bidirectional
+overrides and invisible characters (zero-width characters, word joiners, the
+byte order mark, U+2028/U+2029 line separators and Unicode tag characters) from
+everything it prints, including names, tool results, skills and errors. Server
+text in scan results never starts a line of its own: every line of a message is
+indented. JSON keeps successful response data, with the same characters escaped
+as `\uXXXX`, so values stay lossless.
+
+`vigilbase --version` and `vigilbase help` print the banner only in a terminal.
+When stdout is a pipe or a file, `--version` prints only the version number and
+help starts at `Usage:`, so `v=$(vigilbase --version)` works in scripts. With
+`--json`, `--version` prints `{"name":"@vigilbase/cli","version":"…"}`. The
+banner is plain text.
 
 | Exit code | Meaning |
 | --- | --- |
-| `0` | Success (including a signed-out `whoami`) |
-| `1` | Validation, API, network or sign-in error, or an unsuccessful scan result |
+| `0` | Success (including a signed-out `whoami`, and a graded scan whatever its grade) |
+| `1` | Validation, API, network or sign-in error, or a scan that failed or couldn't be assessed |
 | `2` | Rate limited (`HTTP 429`) |
+| `130`, `143`, `129` | `cloudflare-checkup` cancelled by Ctrl-C (SIGINT), SIGTERM or SIGHUP (128 + the signal number) |
 
-Errors keep a safe status, error code and retry delay. When a public scan
-fails and vigilbase.com explains why, the CLI shows that reason:
-`Error: <message> (<code>)` in text, and `error` plus `code` in JSON. The
-reason is shown only when vigilbase.com sends it as a known error code, and it
-is cleaned to one line of at most 300 characters. Anything else, and every
-Vigilbase One error, prints only `Request failed (HTTP <status>).` without the
-server's text. Hints (`Hint: …`, `hint` in JSON) are always written by the CLI;
-COMMANDS.md lists the One errors that get one.
+A graded scan exits 0 even with an F. Its first line starts with `✓` only when
+the result's `status` is `secure` and the grade isn't F; otherwise it starts
+with `•`. Scripts should gate on `.grade` or `.result.status` in the JSON.
+
+Errors keep a safe status, error code and retry delay. These codes come from
+the CLI itself:
+
+| Code | Meaning |
+| --- | --- |
+| `NOT_SIGNED_IN` | A command that needs Vigilbase One has no usable sign-in |
+| `SIGN_IN_ENDED` | Vigilbase Identity ended the saved sign-in, and `identity-credentials.json` was removed |
+| `SIGN_IN_UNSUPPORTED` | Signing in isn't supported on Windows yet |
+| `UNKNOWN_OPTION` | An option the CLI doesn't know, with `Did you mean --x?` when one is close |
+| `INVALID_ARGUMENT` | A missing or unexpected option value (`--timeout needs a value.`, `--json does not take a value.`), an invalid value, an unknown subcommand or a token that isn't valid |
+| `UNEXPECTED_REDIRECT` | An origin answered with a redirect, which the CLI never follows |
+| `BLOCKED_PORT` | Node's fetch refuses the port (see [Troubleshooting](#troubleshooting)) |
+| `TIMEOUT` | A request took longer than `--timeout` |
+
+Network failures otherwise carry Node's code (for example `ENOTFOUND` or
+`ECONNREFUSED`), and `cloudflare-checkup` has codes of its own (LOCAL.md).
+
+When a public scan fails and vigilbase.com explains why, the CLI shows that
+reason: `Error: <message> (<code>)` in text, and `error` plus `code` in JSON.
+The reason is shown only when vigilbase.com sends it as a known error code, and
+it is cleaned to one line of at most 300 characters. Anything else, and every
+Vigilbase One error, prints a message the CLI wrote (for example
+`You don't have access to this.` or `Request failed (HTTP <status>).`), never
+the server's text. The exception is a scan the scanner couldn't assess (for
+example a bot verification challenge), on the public API or through One: the
+CLI prints `✗ <tool> · <target> · n/a` and the scanner's reason, cleaned the
+same way (code `scan_unassessed`). Hints (`Hint: …`, `hint` in JSON) are always
+written by the CLI; COMMANDS.md lists the One errors that get one.
 
 Commands use named One APIs and One's own authorization. They never take
 Cloudflare or other provider secrets, delegated identity claims or an arbitrary
@@ -226,12 +287,26 @@ command arguments can show up in process listings and shell history; neither
 combines with `--token-stdin`. Login checks the token with One before saving
 it.
 
+A token must be one value of printable ASCII (no spaces or control
+characters), at most 16 KiB, whether it comes from `--token-stdin`, `--token`
+or `VIGILBASE_ONE_TOKEN`. Otherwise login stops before any request with
+`The token must be a single value of printable ASCII characters.`,
+`The token exceeds 16 KiB.` or `The token must not be empty.` (code
+`INVALID_ARGUMENT`); an empty `VIGILBASE_ONE_TOKEN` counts as unset. If an Identity
+sign-in saved with other `--auth-url`, `--one-url` or `--client-id` values
+exists, a token login or a legacy device login stops before it sends the token
+or asks for a device code:
+`A saved Identity sign-in belongs to <issuer> for <One origin> (client ID <id>). Pass the matching --auth-url, --one-url and --client-id, or log out with them first.`
+
 ### Where credentials are stored
 
 Credentials live in the config directory: `VIGILBASE_CONFIG_DIR` if set,
 otherwise `$XDG_CONFIG_HOME/vigilbase`, otherwise `~/.config/vigilbase`.
 `VIGILBASE_CONFIG_DIR` must be an absolute path; a relative `XDG_CONFIG_HOME`
-is ignored.
+is ignored. A set but empty `VIGILBASE_CONFIG_DIR` doesn't fall back: when the
+credentials are needed it is an error
+(`VIGILBASE_CONFIG_DIR is empty. Set it to an absolute path or unset it.`). If
+`HOME` is relative and nothing else is set, the error names `HOME`.
 
 | File | Holds |
 | --- | --- |
@@ -286,6 +361,11 @@ that passes the [directory checks](#directory-checks) but can't be parsed.
    warning, without being revoked; an unsafe file stops logout and stays in
    place.
 
+With nothing saved, logout creates no directories. `logout --json` prints
+`{success, cleared, warnings}`: `warnings` lists the warnings text mode prints
+on stderr (an unparseable file removed without revoking, a failed legacy
+sign-out) and is `[]` when there are none.
+
 Saved Identity credentials belong to one issuer, client and One. If you signed
 in with `--auth-url`, `--one-url` or `--client-id`, log out with the same
 options; otherwise logout stops, before revoking anything, with
@@ -295,35 +375,60 @@ options; otherwise logout stops, before revoking anything, with
 
 Identity access tokens last five minutes. The CLI refreshes within 60 seconds
 of expiry, or once after a 401. The lock coordinates CLI processes, and each
-holder rereads the file before rotating the refresh token. If a refresh may
-have been used but its answer was lost, the CLI marks it and asks you to run
-`vigilbase login` again rather than retrying it. A command waits up to 15
-seconds (or `--timeout`, if shorter) for the lock, then stops with
-`Credentials are locked by another command. …`. `login` and `logout` may
-remove a lock left by a process that has exited, but never one held by a
-running process. If a damaged lock can't be recovered, stop every `vigilbase`
-process, delete `credentials.json.lock` and log in again. Never reuse a refresh
-token by hand.
+holder rereads the file before rotating the refresh token.
+
+- A command waits up to 15 seconds (or `--timeout`, if shorter) for a lock
+  held by a running command, then stops with
+  ``Credentials are locked by another vigilbase command (process <pid>). If none is running, delete <path> and run `vigilbase login`.``
+- If the command holding the lock has exited (an interrupted refresh, for
+  example after Ctrl-C), other commands stop at once with
+  ``A previous vigilbase command was interrupted while it held <path>. Run `vigilbase login` to recover.``
+  `login` and `logout` replace such a lock, but never one held by a running
+  command.
+- An empty or unreadable lock stops with
+  ``<path> is damaged. Stop every vigilbase command, delete it, and run `vigilbase login`.``
+  `login` and `logout` replace one older than 30 seconds.
+- If a refresh request gets no answer (a timeout or a dropped connection),
+  Identity may have rotated the token already, so the first error says so:
+  ``The Identity refresh may not have completed (…). Run `vigilbase login` again; its token cannot be retried safely.``
+  A definite refusal (a 4xx other than `invalid_grant`) leaves the refresh
+  retryable; a 5xx counts as uncertain.
+- An `invalid_grant` answer (for example after a browser sign-out ended the
+  session) removes `identity-credentials.json`. The command then fails with
+  ``Your saved sign-in was ended by Vigilbase Identity and has been removed. Run `vigilbase login` again.``
+  (code `SIGN_IN_ENDED`), while `whoami` reports you as signed out (exit 0).
+
+Never reuse a refresh token by hand.
 
 ### Directory checks
 
-Commands that read or write credentials (`login`, `logout`, `whoami`, every One
-command, `--via one` and the One-only scans) check the whole config path first:
+Commands that read or write credentials (`login`, `logout`, every One command,
+`--via one` and the One-only scans, and `whoami` when credentials may be there)
+check the whole config path first:
 
 - no component of the path may be a symbolic link;
 - every parent directory must be owned by you or root, and not writable by its
   group or by others unless it has the sticky bit;
 - the config directory must be owned by you with mode `0700`;
 - credential files must be regular files owned by you, with one hard link and
-  mode `0600`.
+  mode `0600`;
+- on macOS, the config directory and credential files must have no access
+  control list (the CLI removes inherited entries from what it creates), and no
+  parent may have an ACL entry that lets another user add, remove or replace
+  its entries.
 
 Each error names the path that failed and how to fix it, for example:
 
 ```
 Error: /tmp is a symbolic link. Set VIGILBASE_CONFIG_DIR to a private directory without symbolic links in its path.
 Error: /Users/jane/.config/vigilbase must have mode 0700. Run chmod 700 /Users/jane/.config/vigilbase, or set VIGILBASE_CONFIG_DIR to another directory.
+Error: /Users/jane/.config/vigilbase has an access control list. Run chmod -N /Users/jane/.config/vigilbase, or set VIGILBASE_CONFIG_DIR to another directory.
+Error: /Users/jane/Shared is writable by other users through its access control list. Set VIGILBASE_CONFIG_DIR to a private directory without symbolic links in its path.
 ```
 
+Paths with spaces, quotes or other special characters are shell-quoted in the
+suggested commands.
+
 On macOS `/tmp` and `/var` are symbolic links, and dotfiles managers often make
 `~/.config` one. Fix the mode with the `chmod` the error names, or point
 `VIGILBASE_CONFIG_DIR` at a private directory of its own, for example:
@@ -338,11 +443,12 @@ files hold your refresh token.
 
 Public commands don't need these checks: public scans, `describe`, `skill` and
 `badge` never open the config directory, and work even when
-`VIGILBASE_CONFIG_DIR` isn't absolute. `list` and `doctor` never create or open
-anything in a directory that fails them, and only treat it as a problem when a
-credentials file may be there: `list` then shows you as signed out with one
-warning, and `doctor` reports it in its `signIn` check. With no saved sign-in,
-both carry on as usual.
+`VIGILBASE_CONFIG_DIR` isn't absolute. `list`, `doctor` and `whoami` never
+create or open anything in a directory that fails them, and only treat it as a
+problem when a credentials file may be there: `list` then shows you as signed
+out with one warning, `doctor` reports it in its `signIn` check, and `whoami`
+fails with the error. With no saved sign-in, `list` and `doctor` carry on as
+usual and `whoami` reports you as signed out (exit 0).
 
 ### Windows
 
@@ -364,21 +470,32 @@ work and ignore any saved credentials.
 | `--client-id <id>` | `VIGILBASE_CLIENT_ID` | `vigilbase-cli` |
 | `--timeout <ms>` | — | `60000` per request |
 
-Origins are HTTP(S) URLs without credentials, paths, queries or fragments. One
-needs HTTPS; HTTP is allowed only for loopback development (`localhost`,
-`127.0.0.0/8` or `[::1]`). This applies to device sign-in, tokens and saved
-sessions. `VIGILBASE_API_URL` and `VIGILBASE_PUBLIC_URL` are older names for
-the public origin, used after `VIGILBASE_BASE_URL` when no flag is given.
-`VIGILBASE_CLI_NO_OPEN=1` stops the CLI from opening a browser, and
-`VIGILBASE_CLI_NO_BANNER=1` hides the banner.
+Origins are HTTP(S) URLs without credentials, paths, queries or fragments, and
+need HTTPS; HTTP is allowed only for loopback development (`localhost`,
+`127.0.0.0/8` or `[::1]`). This applies to `--base-url`, `--one-url` and
+`--auth-url`. An empty flag value (`--base-url ""`) is an error; an empty
+environment variable counts as unset. `VIGILBASE_API_URL` and
+`VIGILBASE_PUBLIC_URL` are older names for the public origin, used after
+`VIGILBASE_BASE_URL` when no flag is given; errors about the public origin name
+the variable that held the bad value.
+
+Commands check only the origins they use. Public scans, `list`, `describe`,
+`skill` and `badge` ignore `--one-url`, `--auth-url` and their variables, and
+One-only commands such as `whoami` ignore the public origin. `doctor` checks
+both.
+
+| Environment variable | Effect |
+| --- | --- |
+| `VIGILBASE_CLI_NO_OPEN=1` | Never open a browser |
+| `VIGILBASE_CLI_NO_BANNER=1` | Hide the banner |
+| `VIGILBASE_CLI_NO_PROGRESS=1` | Turn off progress animations |
 
 **Identity issuer.** The CLI trusts one Identity issuer: `--auth-url` /
 `VIGILBASE_AUTH_URL` when set, otherwise `https://auth.vigilbase.com`. The
 issuer One names must be exactly that origin, or sign-in stops before any
-request to it. `--auth-url` accepts `https://auth.vigilbase.com`,
-`https://identity-staging.vigilbase.com`, or a loopback origin when `--one-url`
-is loopback too; staging is trusted only when you pass it. Saved Identity
-credentials from another issuer count as signed out.
+request to it. `--auth-url` accepts `https://auth.vigilbase.com`, or a loopback
+origin (`localhost`, `127.0.0.0/8` or `[::1]`) when `--one-url` is loopback
+too. Saved Identity credentials from another issuer count as signed out.
 
 Billing portal URLs must use HTTPS on `billing.stripe.com`. Skill downloads are
 limited to HTTPS `vigilbase.com/agent-skills/<name>.md` (or
@@ -401,9 +518,25 @@ three checks on their own and exits 1 if any fails:
 - `signIn`: whether your saved sign-in works, including a refresh if one is
   due.
 
-DNS, TLS, connection and timeout failures name the endpoint and the cause.
-Use `--base-url`, `--one-url`, `--auth-url` and `--timeout` to check other
-environments.
+DNS, TLS, connection and timeout failures name the endpoint and the cause. A
+connection failure ends with the hint ``Run `vigilbase doctor` for connectivity checks.``,
+which `doctor` itself doesn't print. Doctor's `--json` top level includes the
+first failing check's `code`. Use `--base-url`, `--one-url`, `--auth-url` and
+`--timeout` to check other environments.
+
+**Redirects and blocked ports.** The CLI never follows redirects. An origin
+that redirects fails with code `UNEXPECTED_REDIRECT`, naming the origin it
+redirects to and the option to set (for example
+`… redirected (HTTP 301) to https://www.example.com. Set --base-url to that origin.`).
+Node's fetch refuses some ports (the Fetch standard's blocked ports, such as
+6000 and 10080); they fail with code `BLOCKED_PORT`. Use another port.
+
+**Proxies.** The CLI uses Node's built-in fetch, which ignores `HTTP_PROXY` and
+`HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is set (Node 22.21+ or 24.5+; Node
+prints an experimental warning). Skill documents (`skill`, `describe`) are
+fetched directly, with DNS pinned to a checked public address, and never go
+through a proxy: on a network that allows only proxied connections, `skill`
+fails and `describe` shows no docs.
 
 **`Unknown command "cloudflare-checkup"`.** An older global install (0.1.x)
 takes priority over a bare `npx @vigilbase/cli`. Update it with
@@ -416,7 +549,11 @@ pnpm 11 and later skip releases published in the last 24 hours by default
 (Yarn's `npmMinimalAgeGate`, pnpm's `minimumReleaseAge`). For a day after a
 release, `yarn dlx @vigilbase/cli` and `pnpm dlx @vigilbase/cli` run an
 older release, and Yarn refuses the new version by number
-(`All versions satisfying "…" are quarantined`). Use `npx @vigilbase/cli`, or
+(`All versions satisfying "…" are quarantined`). pnpm 11 runs a pinned
+version (`pnpm dlx @vigilbase/cli@<version>`). pnpm 10.16 and later apply
+`minimumReleaseAge` only when you set it, and then refuse a pinned version
+released within that time with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`. Use
+`npx @vigilbase/cli`, add `--config.minimum-release-age=0` to `pnpm dlx`, or
 wait a day.
 
 **`Device sign-in isn't available at <origin> right now.`** Login got a 404
@@ -429,6 +566,14 @@ in.
 
 **`A previous refresh has an uncertain result.`** Run `vigilbase login` again.
 
+**`A previous vigilbase command was interrupted while it held …` or
+`… credentials.json.lock is damaged.`** Run `vigilbase login`, or delete the
+file as the message says (see
+[Refresh and the credentials lock](#refresh-and-the-credentials-lock)).
+
+**`Your saved sign-in was ended by Vigilbase Identity and has been removed.`**
+You signed out in the browser, or the session ended. Run `vigilbase login`.
+
 **Certificates.** On Node 22.19+ and 24.5+ the CLI adds your operating
 system's trusted certificates, keeping Node's bundled roots and
 `NODE_EXTRA_CA_CERTS`. This covers private CAs trusted in the macOS Keychain or
@@ -442,8 +587,14 @@ NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--use-system-ca" vigilbase login
 ```
 
 For a private CA outside the system store, set
-`NODE_EXTRA_CA_CERTS=/path/to/trusted-ca.pem` before starting the CLI.
-Certificate checks always stay on.
+`NODE_EXTRA_CA_CERTS=/path/to/trusted-ca.pem` before starting the CLI. The
+advice to use Node 22.19+ or 24.5+ appears in TLS errors only when the running
+Node couldn't add the operating system's certificates.
+
+The CLI never turns certificate checks off. `NODE_TLS_REJECT_UNAUTHORIZED=0`
+does, for every request of the process, including those that carry your One
+sign-in; Node then prints a warning. It is not supported: use
+`NODE_EXTRA_CA_CERTS` instead.
 
 **Timeouts.** Use `--timeout` for slower queries; some security analytics APIs
 take longer than the default.

package/SECURITY.md

@@ -99,7 +99,7 @@ Provider events map `--provider` to `provider_id`, `--dataset` to `dataset_id`,
 | `settings broadcast-emails` | None | `/settings/broadcast-emails` |
 | `settings applications` | None | `/integrations/grants` |
 
-Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Personal settings and `notifications preferences` belong to each user: with `--customer-id` (View-as), a refusal prints `Request failed (HTTP 403).` with the hint `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` Reports are fetched on demand; this CLI does not persist report or billing records.
+Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Personal settings and `notifications preferences` belong to each user: with `--customer-id` (View-as), a refusal prints `You don't have access to this.` with the hint `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` Reports are fetched on demand; this CLI does not persist report or billing records.
 
 ## Limits and pagination
 

package/dist/auth/acl.d.ts

@@ -0,0 +1,6 @@
+/** Remove every entry from a path the CLI just created, so it doesn't keep one inherited from its parent. */
+export declare function stripAcl(path: string): Promise<void>;
+/** The ACL entries of each path, in order, like ` 0: group:everyone allow read`. Empty off darwin. */
+export declare function aclEntries(paths: string[]): Promise<string[][]>;
+/** Whether an entry lets someone other than the current user change the directory's entries. */
+export declare function letsOthersChangeEntries(entry: string): boolean;

package/dist/auth/acl.js

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { promisify } from 'node:util';
+import { platform } from '../lib/platform.js';
+/**
+ * macOS access control lists. An allow entry grants access whatever the mode bits say, and Node's stat can't see
+ * entries, so on darwin the credentials paths are checked with /bin/ls and cleaned with /bin/chmod. Other platforms
+ * have nothing to do: Linux's chmod 0600 masks a default POSIX ACL.
+ */
+const run = promisify(execFile);
+/**
+ * Directory rights that let another user add, remove or replace an entry, remove the directory, or take over its ACL
+ * or ownership (and then grant themselves the rest). The boundaries keep writeattr and writeextattr from matching.
+ */
+const CHANGES_ENTRIES = /\b(?:add_file|add_subdirectory|delete_child|delete|write|append|writesecurity|chown)\b/;
+/** Remove every entry from a path the CLI just created, so it doesn't keep one inherited from its parent. */
+export async function stripAcl(path) {
+    if (platform() !== 'darwin')
+        return;
+    await run('/bin/chmod', ['-N', path]);
+}
+/** The ACL entries of each path, in order, like ` 0: group:everyone allow read`. Empty off darwin. */
+export async function aclEntries(paths) {
+    if (platform() !== 'darwin' || !paths.length)
+        return paths.map(() => []);
+    // -q prints a newline in a name as ?, -f keeps the operands' order.
+    const { stdout } = await run('/bin/ls', ['-ledqf', '--', ...paths]);
+    const entries = [];
+    for (const line of stdout.split('\n')) {
+        if (/^\s*\d+: /.test(line))
+            entries.at(-1)?.push(line.trim());
+        else if (line)
+            entries.push([]);
+    }
+    if (entries.length !== paths.length)
+        throw new Error('Unexpected /bin/ls output.');
+    return entries;
+}
+/** Whether an entry lets someone other than the current user change the directory's entries. */
+export function letsOthersChangeEntries(entry) {
+    const match = /^\d+: (.+?) (?:inherited )?(allow|deny) (\S+)/.exec(entry);
+    if (!match || match[2] !== 'allow' || !CHANGES_ENTRIES.test(match[3]))
+        return false;
+    return match[1] !== `user:${userInfo().username}`;
+}

package/dist/auth/device-auth.d.ts

@@ -14,10 +14,13 @@ export declare class DeviceAuthError extends Error {
     readonly code?: string;
     readonly status: number;
     readonly body: unknown;
+    /** The message is the CLI's own text, never the server's (see VigilbaseApiError). */
+    readonly isCliAuthored: boolean;
     constructor(message: string, options: {
         status: number;
         code?: string;
         body?: unknown;
+        isCliAuthored?: boolean;
     });
 }
 export declare function requestDeviceCode(config: CliConfig, options?: {

package/dist/auth/device-auth.js

@@ -8,12 +8,15 @@ export class DeviceAuthError extends Error {
     code;
     status;
     body;
+    /** The message is the CLI's own text, never the server's (see VigilbaseApiError). */
+    isCliAuthored;
     constructor(message, options) {
         super(message);
         this.name = 'DeviceAuthError';
         this.status = options.status;
         this.code = options.code;
         this.body = options.body;
+        this.isCliAuthored = options.isCliAuthored ?? false;
     }
 }
 function authBase(config) {
@@ -31,6 +34,7 @@ async function postJson(config, path, body) {
     const url = provider ? (path === '/device/code' ? provider.deviceEndpoint : provider.tokenEndpoint) : `${authBase(config)}${path}`;
     const form = provider && path === '/device/token';
     const { response, text } = await requestText(config, url, {
+        option: provider ? '--auth-url' : '--one-url',
         method: 'POST',
         headers: {
             Accept: 'application/json',
@@ -139,7 +143,7 @@ export async function pollDeviceToken(config, deviceCode) {
             },
         };
     }
-    throw new DeviceAuthError(`Device token request failed (HTTP ${status})`, { status, code, body: errorBody });
+    throw new DeviceAuthError(`Device token request failed (HTTP ${status})`, { status, code, body: errorBody, isCliAuthored: true });
 }
 export async function sleep(ms, signal) {
     await new Promise((resolve, reject) => {
@@ -198,14 +202,19 @@ export async function waitForDeviceAuthorization(config, device, options) {
                 consecutiveTransient += 1;
                 lastTransientStatus = result.httpStatus;
                 if (consecutiveTransient >= maxTransient) {
+                    // After an HTTP error the description is the server's, so only a network failure's
+                    // own (CLI-authored) description joins the message.
+                    const detail = (!lastTransientStatus && result.error.error_description) ||
+                        'Retry `vigilbase login` once One is healthy.';
                     throw new DeviceAuthError(`Lost contact with device authorization on ${config.oneBaseUrl} while waiting for approval` +
                         (lastTransientStatus
                             ? ` (HTTP ${lastTransientStatus})`
                             : '') +
-                        `. ${result.error.error_description ?? 'Retry `vigilbase login` once One is healthy.'}`, {
+                        `. ${detail}`, {
                         status: lastTransientStatus,
                         code: 'unreachable',
                         body: result.error,
+                        isCliAuthored: true,
                     });
                 }
                 break;
@@ -214,9 +223,10 @@ export async function waitForDeviceAuthorization(config, device, options) {
                     status: 403,
                     code: 'access_denied',
                     body: result.error,
+                    isCliAuthored: true,
                 });
             case 'expired':
-                throw new DeviceAuthError('The device code expired. Run `vigilbase login` again.', { status: 400, code: 'expired_token', body: result.error });
+                throw new DeviceAuthError('The device code expired. Run `vigilbase login` again.', { status: 400, code: 'expired_token', body: result.error, isCliAuthored: true });
             default: {
                 const _exhaustive = result;
                 throw new DeviceAuthError(`Unexpected poll result: ${JSON.stringify(_exhaustive)}`, {

package/dist/auth/provider.js

@@ -1,6 +1,6 @@
 import { DeviceAuthError } from './device-auth.js';
 import { z } from 'zod';
-import { DEFAULT_IDENTITY_ISSUER, parseOrigin, STAGING_IDENTITY_ISSUER, trustedIdentityIssuer, validateOneOrigin } from '../lib/config.js';
+import { DEFAULT_IDENTITY_ISSUER, parseOrigin, trustedIdentityIssuer, validateOneOrigin } from '../lib/config.js';
 import { requestText, parseJsonResponse } from '../lib/network.js';
 /** An issuer (discovered from One, or saved with credentials) is trusted only when its origin is exactly trustedIdentityIssuer(config). */
 export function validateIdentityIssuer(raw, config) {
@@ -17,9 +17,9 @@ export function validateIdentityIssuer(raw, config) {
         return origin;
     throw new Error(config.identityBaseUrl
         ? `Untrusted Identity issuer ${origin}: --auth-url / VIGILBASE_AUTH_URL is ${trusted}. Set it to the issuer for this One, or unset it to use ${DEFAULT_IDENTITY_ISSUER}.`
-        : `Untrusted Identity issuer ${origin}: only ${DEFAULT_IDENTITY_ISSUER} is trusted by default. For staging, pass --auth-url ${STAGING_IDENTITY_ISSUER} or set VIGILBASE_AUTH_URL.`);
+        : `Untrusted Identity issuer ${origin}: only ${DEFAULT_IDENTITY_ISSUER} is trusted by default. To use another issuer, pass --auth-url <issuer> or set VIGILBASE_AUTH_URL.`);
 }
-async function json(config, url) { const { response, text } = await requestText(config, url, { headers: { Accept: 'application/json', 'User-Agent': config.userAgent } }); return { response, body: parseJsonResponse(response, text) }; }
+async function json(config, url) { const { response, text } = await requestText(config, url, { option: '--auth-url', headers: { Accept: 'application/json', 'User-Agent': config.userAgent } }); return { response, body: parseJsonResponse(response, text) }; }
 export async function identityProvider(config, issuer) {
     issuer = validateIdentityIssuer(issuer, config);
     const { response, body } = await json(config, `${issuer}/.well-known/openid-configuration`);
@@ -42,7 +42,7 @@ export async function identityProvider(config, issuer) {
  */
 export async function discoverAuthProvider(config) {
     const one = validateOneOrigin(config.oneBaseUrl);
-    const { response, text } = await requestText(config, `${one}/.well-known/oauth-protected-resource`, { headers: { Accept: 'application/json', 'User-Agent': config.userAgent }, redirect: 'manual' });
+    const { response, text } = await requestText(config, `${one}/.well-known/oauth-protected-resource`, { option: '--one-url', headers: { Accept: 'application/json', 'User-Agent': config.userAgent }, redirect: 'manual' });
     if (response.type === 'opaqueredirect' || response.status === 0 || (response.status >= 300 && response.status < 400))
         return undefined;
     if (response.status === 404)

package/dist/auth/refresh.d.ts

@@ -3,14 +3,15 @@ import type { OneCredentials } from './types.js';
 export declare function boundIdentityCredentials(config: CliConfig, one: OneCredentials): boolean;
 /** Library callers may omit or mistype timeoutMs; NaN would make the wait unbounded. */
 export declare function credentialsLockWaitMs(timeoutMs: unknown): number;
-/** Another command holds credentials.json.lock. */
+/** credentials.json.lock is held: by a running command, by one that was interrupted, or it is damaged. */
 export declare class CredentialsLockedError extends Error {
-    constructor();
+    constructor(message: string);
 }
 /**
  * credentials.json.lock guards both credentials files; CLI 0.2.0 takes the same lock.
- * Never steal a stale lock: a crashed refresh may have consumed the rotating token.
- * With `wait` false, a held lock fails at once instead of after the lock wait.
+ * Only login and logout (`replaceDeadLock`) replace a lock whose owner has exited, or an old damaged one: a crashed
+ * refresh may have consumed the rotating token, and both start over without it. Other commands fail at once on a
+ * dead owner. With `wait` false, a held lock fails at once instead of after the lock wait.
  */
 export declare function withCredentialsLock<T>(config: Pick<CliConfig, 'configDir'> & Partial<Pick<CliConfig, 'timeoutMs'>>, callback: () => Promise<T>, replaceDeadLock?: boolean, wait?: boolean): Promise<T>;
 export declare function managedAccessToken(config: CliConfig, failedToken?: string): Promise<string | null>;