@vigilbase/cli 0.2.3 → 0.2.4

package/dist/cli.js

@@ -6,79 +6,81 @@ import { renderBanner, shouldShowBanner } from './lib/banner.js';
 import { createWriter, formatError } from './lib/format.js';
 import { HELP_TAGLINE, HELP_TEXT, HELP_USAGE, helpForCommand, isCatalogTool } from './lib/help.js';
 import { wasRendered } from './lib/tui.js';
-import { getCommandHandler } from './commands/index.js';
-import { LocalCheckupError } from './local/cloudflare-checkup/errors.js';
+import { isOneAuthRequiredTool } from './lib/one-client.js';
+import { COMMAND_HANDLERS, getCommandHandler } from './commands/index.js';
+import { CheckupCancelledError, LocalCheckupError } from './local/cloudflare-checkup/errors.js';
 import { EXIT } from './types.js';
 import { CLI_VERSION } from './version.js';
 export { CLI_VERSION };
+const OPTIONS = {
+    json: { type: 'boolean', short: 'j', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'V', default: false },
+    'base-url': { type: 'string' },
+    'one-url': { type: 'string' },
+    'auth-url': { type: 'string' },
+    'client-id': { type: 'string' },
+    timeout: { type: 'string' },
+    style: { type: 'string' },
+    'no-skill': { type: 'boolean', default: false },
+    via: { type: 'string' },
+    public: { type: 'boolean', default: false },
+    token: { type: 'string' },
+    'token-stdin': { type: 'boolean', default: false },
+    'no-open': { type: 'boolean', default: false },
+    email: { type: 'string' },
+    role: { type: 'string' },
+    confirm: { type: 'boolean', default: false },
+    'account-id': { type: 'string' },
+    tool: { type: 'string' },
+    limit: { type: 'string' },
+    'target-id': { type: 'string' },
+    'customer-id': { type: 'string' },
+    'zone-id': { type: 'string' },
+    'days': { type: 'string' },
+    'offset': { type: 'string' },
+    'status': { type: 'string' },
+    'severity': { type: 'string' },
+    'attack-category': { type: 'string' },
+    'order-by': { type: 'string' },
+    'order-direction': { type: 'string' },
+    'asset-id': { type: 'string' },
+    'provider': { type: 'string' },
+    'dataset': { type: 'string' },
+    'search': { type: 'string' },
+    'start': { type: 'string' },
+    'end': { type: 'string' },
+    'sort': { type: 'string' },
+    'frs-min': { type: 'string' },
+    'before': { type: 'string' },
+    'note': { type: 'string' },
+    'cursor': { type: 'string' },
+    'action-prefix': { type: 'string' },
+    'outcome': { type: 'string' },
+    'hours': { type: 'string' },
+    'metrics': { type: 'string' },
+    'min-weight': { type: 'string' },
+    'range': { type: 'string' },
+    'region': { type: 'string' },
+    'issue-id': { type: 'string' },
+    'revision': { type: 'string' },
+    all: { type: 'boolean', default: false },
+    light: { type: 'boolean', default: false },
+    profile: { type: 'string' },
+    'cf-auth': { type: 'string' },
+    'cf-bin': { type: 'string' },
+    out: { type: 'string' },
+    overwrite: { type: 'boolean', default: false },
+    'dry-run': { type: 'boolean', default: false },
+    'max-requests-per-5min': { type: 'string' },
+    yes: { type: 'boolean', default: false },
+};
 function parseCli(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
         strict: true,
-        options: {
-            json: { type: 'boolean', short: 'j', default: false },
-            help: { type: 'boolean', short: 'h', default: false },
-            version: { type: 'boolean', short: 'V', default: false },
-            'base-url': { type: 'string' },
-            'one-url': { type: 'string' },
-            'auth-url': { type: 'string' },
-            'client-id': { type: 'string' },
-            timeout: { type: 'string' },
-            style: { type: 'string' },
-            'no-skill': { type: 'boolean', default: false },
-            via: { type: 'string' },
-            public: { type: 'boolean', default: false },
-            token: { type: 'string' },
-            'token-stdin': { type: 'boolean', default: false },
-            'no-open': { type: 'boolean', default: false },
-            email: { type: 'string' },
-            role: { type: 'string' },
-            confirm: { type: 'boolean', default: false },
-            'account-id': { type: 'string' },
-            tool: { type: 'string' },
-            limit: { type: 'string' },
-            'target-id': { type: 'string' },
-            'customer-id': { type: 'string' },
-            'zone-id': { type: 'string' },
-            'days': { type: 'string' },
-            'offset': { type: 'string' },
-            'status': { type: 'string' },
-            'severity': { type: 'string' },
-            'attack-category': { type: 'string' },
-            'order-by': { type: 'string' },
-            'order-direction': { type: 'string' },
-            'asset-id': { type: 'string' },
-            'provider': { type: 'string' },
-            'dataset': { type: 'string' },
-            'search': { type: 'string' },
-            'start': { type: 'string' },
-            'end': { type: 'string' },
-            'sort': { type: 'string' },
-            'frs-min': { type: 'string' },
-            'before': { type: 'string' },
-            'note': { type: 'string' },
-            'cursor': { type: 'string' },
-            'action-prefix': { type: 'string' },
-            'outcome': { type: 'string' },
-            'hours': { type: 'string' },
-            'metrics': { type: 'string' },
-            'min-weight': { type: 'string' },
-            'range': { type: 'string' },
-            'region': { type: 'string' },
-            'issue-id': { type: 'string' },
-            'revision': { type: 'string' },
-            all: { type: 'boolean', default: false },
-            light: { type: 'boolean', default: false },
-            profile: { type: 'string' },
-            'cf-auth': { type: 'string' },
-            'cf-bin': { type: 'string' },
-            out: { type: 'string' },
-            overwrite: { type: 'boolean', default: false },
-            'dry-run': { type: 'boolean', default: false },
-            'max-requests-per-5min': { type: 'string' },
-            yes: { type: 'boolean', default: false },
-        },
+        options: OPTIONS,
     });
     return {
         positionals,
@@ -161,6 +163,111 @@ function parseTimeout(raw) {
 function resolveMode(jsonFlag) {
     return jsonFlag ? 'json' : 'text';
 }
+/** Arguments before `--`: everything after it is a positional. */
+function optionArguments(argv) {
+    const end = argv.indexOf('--');
+    return end === -1 ? argv : argv.slice(0, end);
+}
+/** JSON mode for an error from parsing itself: --json, --json=… or a short-flag cluster with j. */
+function requestsJson(argv) {
+    return optionArguments(argv).some((arg) => /^--json(=|$)/.test(arg) || /^-[A-Za-z]*j[A-Za-z]*$/.test(arg));
+}
+/** Edit distance counting a swap of two neighbouring letters as one edit. */
+function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i ? (j ? 0 : i) : j)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+/** The nearest candidate when it is close enough to be a typo: one edit for short words, two from six letters. */
+function didYouMean(input, candidates) {
+    let best;
+    let bestDistance = Math.min(2, Math.max(1, Math.floor(input.length / 3))) + 1;
+    for (const candidate of candidates) {
+        const distance = editDistance(input, candidate);
+        if (distance < bestDistance)
+            [best, bestDistance] = [candidate, distance];
+    }
+    return best;
+}
+/** Commands with subcommands, whose help covers them all. */
+const COMMAND_GROUPS = new Set(['account', 'billing', 'runs', 'runhistory', 'cf', 'cloudflare', 'watchdog', 'security',
+    'customers', 'orgs', 'monitoring', 'support', 'local', 'cloudflare-checkup']);
+const USAGE_POINTER = 'Run `vigilbase help` for usage.';
+function cliError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function unknownCommand(typed) {
+    const name = typed.toLowerCase();
+    const command = didYouMean(name, [...Object.keys(COMMAND_HANDLERS), 'help']);
+    const suggestion = command ?? (name === 'version' || name === 'json' ? `--${name}` : undefined);
+    return new Error(`Unknown command "${typed}".${suggestion ? ` Did you mean ${suggestion}?` : ''} ${USAGE_POINTER}`);
+}
+function unknownOption(argv, reported) {
+    const longNames = Object.keys(OPTIONS);
+    let name = reported;
+    let suggestion;
+    // parseArgs reads -help as -h -e -l -p: name the whole word and suggest the long option.
+    const word = optionArguments(argv).find((arg) => /^-[^-]{2,}$/.test(arg) && arg.includes(reported.slice(1)) &&
+        didYouMean(arg.slice(1), longNames));
+    if (word) {
+        name = word;
+        suggestion = `--${didYouMean(word.slice(1), longNames)}`;
+    }
+    else if (reported.startsWith('--')) {
+        const option = didYouMean(reported.slice(2).split('=')[0], longNames);
+        if (option)
+            suggestion = `--${option}`;
+    }
+    else {
+        const letter = reported.slice(1);
+        const short = Object.values(OPTIONS).find((option) => 'short' in option && option.short.toLowerCase() === letter.toLowerCase());
+        if (short && 'short' in short)
+            suggestion = `-${short.short}`;
+    }
+    return cliError(`Unknown option ${name}.${suggestion ? ` Did you mean ${suggestion}?` : ''} ${USAGE_POINTER}`, 'UNKNOWN_OPTION');
+}
+/** node:util parseArgs errors in the CLI's words, with the CLI's own codes. */
+function argumentError(error, argv) {
+    const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+    if (typeof code !== 'string' || !code.startsWith('ERR_PARSE_ARGS_'))
+        return error;
+    const message = error instanceof Error ? error.message : '';
+    if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION')
+        return unknownOption(argv, /'([^']+)'/.exec(message)?.[1] ?? '');
+    const flag = /--[a-z0-9-]+/.exec(message)?.[0];
+    if (!flag)
+        return cliError(`Invalid arguments. ${USAGE_POINTER}`, 'INVALID_ARGUMENT');
+    if (message.includes('does not take an argument'))
+        return cliError(`${flag} does not take a value.`, 'INVALID_ARGUMENT');
+    if (message.includes('argument missing'))
+        return cliError(`${flag} needs a value.`, 'INVALID_ARGUMENT');
+    if (message.includes('ambiguous')) {
+        return cliError(`${flag} needs a value. To pass one that starts with a dash, use ${flag}=<value>.`, 'INVALID_ARGUMENT');
+    }
+    return cliError(`Invalid value for ${flag}. ${USAGE_POINTER}`, 'INVALID_ARGUMENT');
+}
+/** Public tool commands: they contact One only to run a tool through it. */
+const PUBLIC_TOOL_COMMANDS = new Set(['list', 'tools', 'run', 'headers', 'email', 'describe', 'skill', 'badge']);
+/**
+ * The origins a command contacts, so settings for the others can't fail it. Doctor checks both. `list` reads a
+ * saved sign-in offline and only warns about one it can't use.
+ */
+function originsUsed(command, rest, values) {
+    if (!PUBLIC_TOOL_COMMANDS.has(command))
+        return { public: command === 'doctor', one: true };
+    if (command !== 'run' && command !== 'headers' && command !== 'email')
+        return { public: true, one: false };
+    const toolName = command === 'headers' ? 'security-headers' : command === 'email' ? 'email-security' : rest[0] ?? '';
+    const isForcedPublic = values.isPublic || values.via === 'public';
+    const isViaOne = !isForcedPublic && (values.via === 'one' || isOneAuthRequiredTool(toolName));
+    return { public: !isViaOne, one: isViaOne };
+}
 export async function runCli(options = {}) {
     const argv = options.argv ?? process.argv.slice(2);
     const stdoutStream = options.stdout ?? process.stdout;
@@ -169,10 +276,20 @@ export async function runCli(options = {}) {
     if (options.env) {
         process.env = options.env;
     }
+    let mode;
     try {
-        const parsed = parseCli(argv);
-        const mode = resolveMode(parsed.values.isJson);
-        if (parsed.values.isVersion || parsed.values.isHelp || !parsed.positionals.length || parsed.positionals[0] === 'help') {
+        let parsed;
+        try {
+            parsed = parseCli(argv);
+        }
+        catch (error) {
+            throw argumentError(error, argv);
+        }
+        mode = resolveMode(parsed.values.isJson);
+        // Commands are matched in any case, as subcommands are.
+        const [typed, ...rest] = parsed.positionals;
+        const command = typed?.toLowerCase();
+        if (parsed.values.isVersion || parsed.values.isHelp || !command || command === 'help') {
             const informational = new Set(['isJson', 'isHelp', 'isVersion', 'base-url', 'one-url', 'auth-url', 'client-id', 'timeout']);
             for (const [key, value] of Object.entries(parsed.values)) {
                 if (value === undefined || value === false || informational.has(key))
@@ -182,7 +299,8 @@ export async function runCli(options = {}) {
             }
             if (parsed.values.isVersion && parsed.positionals.length)
                 throw new Error('Usage: vigilbase --version');
-            if (parsed.positionals[0] === 'help' && parsed.positionals.length > 2)
+            // `help <group> <subcommand>` shows the group's help, as `<group> <subcommand> --help` does.
+            if (command === 'help' && rest.length > 1 && !COMMAND_GROUPS.has(rest[0].toLowerCase()))
                 throw new Error(HELP_USAGE);
         }
         if (parsed.values.isVersion) {
@@ -201,15 +319,16 @@ export async function runCli(options = {}) {
             }
             return EXIT.OK;
         }
-        const [command, ...rest] = parsed.positionals;
-        const helpCommand = command === 'help' ? rest[0] : parsed.values.isHelp ? command : undefined;
+        // `help --help` is help's own help, like `help help`.
+        const helpTyped = command === 'help' ? rest[0] ?? (parsed.values.isHelp ? 'help' : undefined) : parsed.values.isHelp ? typed : undefined;
+        const helpCommand = helpTyped?.toLowerCase();
         if (parsed.values.isHelp ||
             !command ||
             command === 'help' ||
             command === '--help') {
             const specific = helpCommand ? helpForCommand(helpCommand) : null;
             if (helpCommand && !specific) {
-                throw new Error(`Unknown command "${helpCommand}". Run \`vigilbase help\` for usage.`);
+                throw unknownCommand(helpTyped);
             }
             if (mode === 'json') {
                 writer.stdout(JSON.stringify({
@@ -223,13 +342,21 @@ export async function runCli(options = {}) {
                 writer.stdout(specific);
             }
             else {
-                const prefix = shouldShowBanner(mode)
+                // Like --version, pipes and files get no banner.
+                const prefix = shouldShowBanner(mode) && stdoutStream.isTTY
                     ? `${renderBanner({ version: CLI_VERSION, tagline: HELP_TAGLINE })}\n\n`
                     : '';
                 writer.stdout(`${prefix}${HELP_TEXT}`);
             }
             return EXIT.OK;
         }
+        const handler = getCommandHandler(command);
+        if (!handler) {
+            // Tools are not commands of their own (no aliases): point to how they run.
+            throw isCatalogTool(command)
+                ? new Error(`Unknown command "${typed}". Run the tool with \`vigilbase run ${command} <target>\`.`)
+                : unknownCommand(typed);
+        }
         // Local checkups validate --base-url themselves (resolveSubmitOrigin) and ignore VIGILBASE_* URLs.
         const config = command === 'local' || command === 'cloudflare-checkup'
             ? createLocalCommandConfig(parseTimeout(parsed.values.timeout))
@@ -239,15 +366,9 @@ export async function runCli(options = {}) {
                 identityBaseUrl: parsed.values['auth-url'],
                 clientId: parsed.values['client-id'],
                 timeoutMs: parseTimeout(parsed.values.timeout),
+                checkOrigins: originsUsed(command, rest, parsed.values),
             });
         const publicClient = new VigilbaseClient(config);
-        const handler = getCommandHandler(command);
-        if (!handler) {
-            // Tools are not commands of their own (no aliases): point to how they run.
-            throw new Error(isCatalogTool(command)
-                ? `Unknown command "${command}". Run the tool with \`vigilbase run ${command} <target>\`.`
-                : `Unknown command "${command}". Run \`vigilbase help\` for usage.`);
-        }
         return await handler({
             command,
             rest,
@@ -264,7 +385,7 @@ export async function runCli(options = {}) {
         });
     }
     catch (error) {
-        const mode = argv.includes('--json') || argv.includes('-j') ? 'json' : 'text';
+        mode ??= requestsJson(argv) ? 'json' : 'text';
         // The terminal UI already showed it (■ and the hint) in its timeline.
         if (mode === 'json' || !wasRendered(error))
             formatError(error, mode, writer);
@@ -274,6 +395,9 @@ export async function runCli(options = {}) {
         if (error instanceof LocalCheckupError && error.isRateLimited) {
             return EXIT.RATE_LIMITED;
         }
+        // A cf run or install stopped by a signal: 128 + the signal number.
+        if (error instanceof CheckupCancelledError)
+            return error.exitCode;
         return EXIT.ERROR;
     }
     finally {

package/dist/commands/account.js

@@ -1,4 +1,4 @@
-import { invitationSchema, validateArguments } from './legacy-validation.js';
+import { InvalidArgumentError, invitationValue, unknownSubcommand, validateArguments } from './legacy-validation.js';
 import { asArray, asRecord, ok, outputJson, outputLines, requireOneClient, withSpinner, } from './helpers.js';
 import { handleBilling } from './billing.js';
 export const handleAccount = async (ctx) => {
@@ -16,19 +16,23 @@ export const handleAccount = async (ctx) => {
         if (action === 'list' || action === 'ls')
             validateArguments(ctx, ctx.rest[1] === undefined ? 1 : 2);
         else if (action === 'create' || action === 'add') {
+            // The email may be positional or --email; help and both errors show the same usage.
+            const usage = 'Usage: vigilbase account invites create <email>|--email <email> [--role <role>] --confirm';
             if (ctx.values.email !== undefined && ctx.rest[2] !== undefined)
-                throw new Error('Specify the invite email either positionally or with --email, not both.');
-            validateArguments(ctx, ctx.values.email === undefined ? 3 : 2, ['email', 'role', 'isConfirm'], 'vigilbase account invites create <email> --confirm');
-            invitation = invitationSchema.parse({ email: ctx.values.email ?? ctx.rest[2], role: ctx.values.role });
+                throw new InvalidArgumentError(`Give the email once, as <email> or --email <email>. ${usage}`);
+            if (!(ctx.values.email ?? ctx.rest[2] ?? '').trim())
+                throw new Error(`Missing <email>. ${usage}`);
+            validateArguments(ctx, ctx.values.email === undefined ? 3 : 2, ['email', 'role', 'isConfirm']);
+            invitation = invitationValue(ctx.values.email ?? ctx.rest[2], ctx.values.role);
             if (!ctx.values.isConfirm)
                 throw new Error('Sending an organization invitation requires --confirm.');
         }
         else
-            throw new Error('Usage: vigilbase account invites [list|create]');
+            throw unknownSubcommand(`account ${subcommand}`, ctx.rest[1] ?? '');
     }
     else {
         if (!['show', 'me', 'overview', 'services', 'service', 'org', 'organization', 'members', 'endpoints', 'endpoint', 'sessions', 'session'].includes(subcommand)) {
-            throw new Error('Usage: vigilbase account [services|org|endpoints|sessions|invites|billing]');
+            throw unknownSubcommand('account', ctx.rest[0] ?? '');
         }
         validateArguments(ctx, ctx.rest[0] === undefined ? 0 : 1);
     }
@@ -143,7 +147,7 @@ export const handleAccount = async (ctx) => {
             const session = asRecord(raw);
             if (!session)
                 continue;
-            ctx.writer.stdout(`${String(session.id).slice(0, 12)}…  ${String(session.ipAddress || '-')}  ${String(session.createdAt || '')}`);
+            ctx.writer.stdout(`${String(session.id)}  ${String(session.ipAddress || '-')}  ${String(session.createdAt || '')}`);
         }
         return ok();
     }

package/dist/commands/auth.d.ts

@@ -1,4 +1,10 @@
 import { type CommandHandler } from './helpers.js';
+/**
+ * A bearer token from --token, VIGILBASE_ONE_TOKEN or --token-stdin, checked before any request: fetch refuses
+ * header values with other characters, which would read as a connection failure.
+ */
+export declare function validateBearerToken(token: string): string;
+/** A piped token fails with the same messages as --token. Reading stops past 16 KiB, with room for a line ending. */
 export declare function readTokenFromStdin(input?: NodeJS.ReadableStream): Promise<string>;
 export declare const handleLogin: CommandHandler;
 export declare const handleLogout: CommandHandler;

package/dist/commands/auth.js

@@ -1,13 +1,28 @@
 import { readIdentityTokenMetadata } from '../auth/token-metadata.js';
 import { discoverAuthProvider } from '../auth/provider.js';
-import { revokeIdentityCredentials, revokeIdentityGrant, revokeSavedCredentials, withCredentialsLock } from '../auth/refresh.js';
-import { checkCredentialsLocation, clearIdentityCredentials, clearOneCredentials, hasIgnoredIdentityCredentials, readReplacedIdentityGrant, readStoredCredentials } from '../auth/store.js';
+import { boundIdentityCredentials, revokeIdentityCredentials, revokeIdentityGrant, revokeSavedCredentials, withCredentialsLock } from '../auth/refresh.js';
+import { checkCredentialsLocation, clearIdentityCredentials, clearOneCredentials, hasCredentialsDirectory, hasIgnoredIdentityCredentials, readReplacedIdentityGrant, readStoredCredentials, savedForAnotherConfiguration, SignInEndedError } from '../auth/store.js';
 import { getOneAccessToken, readCredentials, requestDeviceCode, waitForDeviceAuthorization, writeOneCredentials, } from '../auth/index.js';
 import { VigilbaseOneClient, ONE_AUTH_REQUIRED_TOOLS } from '../lib/one-client.js';
 import { VigilbaseApiError } from '../lib/client.js';
 import { formatUserCode, isHeadlessEnvironment, openUrlInBrowser, resolveDeviceVerificationUrl, } from '../lib/open-url.js';
 import { shouldShowProgress, startProgress } from '../lib/progress.js';
 import { assertCommandFlags, ok, outputJson, outputLines, withSpinner, } from './helpers.js';
+import { InvalidArgumentError, validateArguments } from './legacy-validation.js';
+/**
+ * A bearer token from --token, VIGILBASE_ONE_TOKEN or --token-stdin, checked before any request: fetch refuses
+ * header values with other characters, which would read as a connection failure.
+ */
+export function validateBearerToken(token) {
+    if (!token)
+        throw new InvalidArgumentError('The token must not be empty.');
+    if (token.length > 16384)
+        throw new InvalidArgumentError('The token exceeds 16 KiB.');
+    if (!/^[\x21-\x7E]+$/.test(token))
+        throw new InvalidArgumentError('The token must be a single value of printable ASCII characters.');
+    return token;
+}
+/** A piped token fails with the same messages as --token. Reading stops past 16 KiB, with room for a line ending. */
 export async function readTokenFromStdin(input = process.stdin) {
     if ('isTTY' in input && input.isTTY) {
         throw new Error('--token-stdin requires piped input. Pipe the token from your secret manager to vigilbase login --token-stdin.');
@@ -15,13 +30,21 @@ export async function readTokenFromStdin(input = process.stdin) {
     let token = '';
     for await (const chunk of input) {
         token += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
-        if (Buffer.byteLength(token, 'utf8') > 16384)
-            throw new Error('Token input exceeds 16 KiB.');
+        if (Buffer.byteLength(token, 'utf8') > 16386)
+            throw new InvalidArgumentError('The token exceeds 16 KiB.');
     }
-    token = token.trim();
-    if (!token || /\s/.test(token))
-        throw new Error('Token input must contain exactly one nonempty token.');
-    return token;
+    return validateBearerToken(token.trim());
+}
+/**
+ * Token and legacy logins revoke saved Identity grants before saving their session, and a grant bound to another
+ * One, issuer or client can't be revoked with this configuration. Stop before the token or device code is used.
+ */
+async function assertSavedGrantsReplaceable(ctx) {
+    const { identity, shared } = await readStoredCredentials(ctx.config, () => { });
+    const other = [identity, shared].find((saved) => saved?.version === 2 && saved.one && !boundIdentityCredentials(ctx.config, saved.one))?.one;
+    if (!other)
+        return;
+    throw new Error(`A saved Identity sign-in belongs to ${other.issuer} for ${other.oneBaseUrl ?? other.resource} (client ID ${other.clientId}). Pass the matching --auth-url, --one-url and --client-id, or log out with them first.`);
 }
 /**
  * Revoke the Identity grant a new login replaces, before the new grant exists. Identity treats a revoked refresh
@@ -57,16 +80,16 @@ export const handleLogin = async (ctx) => {
     // Fail on Windows or an unsafe credentials directory or file before validating a token or starting device
     // authorization: once a device grant is approved, a failed save would leave it unsaved and unrevoked.
     await checkCredentialsLocation(ctx.config);
-    if (ctx.values.isTokenStdin && (ctx.values.token !== undefined || ctx.env.VIGILBASE_ONE_TOKEN !== undefined)) {
+    if (ctx.values.isTokenStdin && (ctx.values.token !== undefined || ctx.env.VIGILBASE_ONE_TOKEN?.trim())) {
         throw new Error('Use --token-stdin without --token or VIGILBASE_ONE_TOKEN.');
     }
+    // An empty --token fails like any other invalid token; an empty VIGILBASE_ONE_TOKEN is unset.
     const explicitToken = ctx.values.isTokenStdin
         ? await readTokenFromStdin(ctx.stdin)
-        : ctx.values.token?.trim() || ctx.env.VIGILBASE_ONE_TOKEN?.trim() || '';
-    if (ctx.values.token !== undefined && !ctx.values.token.trim()) {
-        throw new Error('The --token value must not be empty.');
-    }
+        : ctx.values.token !== undefined ? validateBearerToken(ctx.values.token.trim()) : ctx.env.VIGILBASE_ONE_TOKEN?.trim() || '';
     if (explicitToken) {
+        validateBearerToken(explicitToken);
+        await assertSavedGrantsReplaceable(ctx);
         const oneClient = new VigilbaseOneClient(ctx.config, explicitToken);
         let user;
         const session = await withSpinner(ctx, 'Validating token', () => oneClient.getSession());
@@ -110,6 +133,8 @@ export const handleLogin = async (ctx) => {
     ctx.config.authProvider = await discoverAuthProvider(ctx.config);
     if (ctx.config.authProvider)
         await retirePreviousIdentityGrant(ctx);
+    else
+        await assertSavedGrantsReplaceable(ctx);
     const device = await withSpinner(ctx, 'Requesting device code', () => requestDeviceCode(ctx.config));
     const verifyUrl = resolveDeviceVerificationUrl(ctx.config.authProvider?.issuer ?? ctx.config.oneBaseUrl, device);
     const prettyCode = formatUserCode(device.user_code);
@@ -199,12 +224,14 @@ export const handleLogout = async (ctx) => {
     if (ctx.rest.length)
         throw new Error('Usage: vigilbase logout');
     assertCommandFlags(ctx, []);
+    const warnings = [];
     const cleared = await revokeSavedCredentials(ctx.config, (warning) => {
+        warnings.push(warning);
         if (ctx.mode !== 'json')
             ctx.writer.stderr(`Warning: ${warning}`);
     });
     if (ctx.mode === 'json') {
-        outputJson(ctx, { success: true, cleared });
+        outputJson(ctx, { success: true, cleared, warnings });
     }
     else if (cleared) {
         ctx.writer.stdout('Signed out. Local One credentials removed.');
@@ -214,12 +241,28 @@ export const handleLogout = async (ctx) => {
     }
     return ok();
 };
+/** "One <origin>, Identity <issuer>, client ID <id>" for a sign-in saved for another configuration. */
+function describeSavedFor(savedFor) {
+    return [`One ${savedFor.oneBaseUrl}`, ...(savedFor.issuer ? [`Identity ${savedFor.issuer}`] : []), ...(savedFor.clientId ? [`client ID ${savedFor.clientId}`] : [])].join(', ');
+}
 export const handleWhoami = async (ctx) => {
-    if (ctx.rest.length)
-        throw new Error('Usage: vigilbase whoami');
-    assertCommandFlags(ctx, []);
-    const legacyIdentityFileIgnored = await hasIgnoredIdentityCredentials(ctx.config);
-    const accessToken = await getOneAccessToken(ctx.config);
+    validateArguments(ctx, 0);
+    // Like list and doctor, a directory that fails the checks with no credentials in it is signed out.
+    const hasDirectory = await hasCredentialsDirectory(ctx.config);
+    const legacyIdentityFileIgnored = hasDirectory && await hasIgnoredIdentityCredentials(ctx.config);
+    const savedFor = hasDirectory ? await savedForAnotherConfiguration(ctx.config, await readCredentials(ctx.config)) : null;
+    let accessToken = null;
+    let signInEnded = false;
+    try {
+        if (hasDirectory)
+            accessToken = await getOneAccessToken(ctx.config);
+    }
+    catch (error) {
+        // Identity ended the grant and its file was removed: signed out, which whoami reports as success.
+        if (!(error instanceof SignInEndedError))
+            throw error;
+        signInEnded = true;
+    }
     let liveUser = null;
     if (accessToken) {
         try {
@@ -233,16 +276,18 @@ export const handleWhoami = async (ctx) => {
             }
         }
         catch (error) {
-            // A rejected session is signed out. Connectivity and server failures
-            // must remain errors rather than claiming the cached session is valid.
-            if (!(error instanceof VigilbaseApiError) || ![401, 403].includes(error.status)) {
+            // A rejected session is signed out, and so is a grant Identity ended when the 401 retry refreshed it.
+            // Connectivity and server failures must remain errors rather than claiming the cached session is valid.
+            if (error instanceof SignInEndedError)
+                signInEnded = true;
+            else if (!(error instanceof VigilbaseApiError) || ![401, 403].includes(error.status)) {
                 throw error;
             }
         }
     }
     const signedIn = Boolean(liveUser);
     // Read after the token and session calls: either may have refreshed the sign-in, which saves a new expiry and scope.
-    const credentials = await readCredentials(ctx.config);
+    const credentials = signedIn ? await readCredentials(ctx.config) : { one: null };
     const payload = {
         authenticated: signedIn,
         oneBaseUrl: ctx.config.oneBaseUrl,
@@ -250,6 +295,8 @@ export const handleWhoami = async (ctx) => {
         clientId: credentials.one?.clientId ?? null,
         resource: credentials.one?.resource ?? null,
         organizationId: credentials.one?.orgId ?? null,
+        savedFor,
+        signInEnded,
         user: liveUser,
         expiresAt: signedIn ? credentials.one?.expiresAt ?? null : null,
         scope: signedIn ? credentials.one?.scope ?? null : null,
@@ -263,9 +310,13 @@ export const handleWhoami = async (ctx) => {
         outputJson(ctx, payload);
     }
     else if (!signedIn) {
+        if (signInEnded)
+            ctx.writer.stderr('Your saved sign-in was ended by Vigilbase Identity and has been removed.');
         outputLines(ctx, [
             'Not signed in. Public tools still work.',
-            'Run `vigilbase login` to unlock auth-required tools (website-security, react2shell, fortibleed-check).',
+            savedFor
+                ? `A saved sign-in exists for ${describeSavedFor(savedFor)}; pass the matching options or run \`vigilbase login\`.`
+                : 'Run `vigilbase login` to unlock auth-required tools (website-security, react2shell, fortibleed-check).',
             ...(legacyIdentityFileIgnored ? [legacyNote] : []),
         ]);
     }

package/dist/commands/billing.js

@@ -1,10 +1,10 @@
-import { validateArguments } from './legacy-validation.js';
+import { unknownSubcommand, validateArguments } from './legacy-validation.js';
 import { openUrlInBrowser } from '../lib/open-url.js';
 import { asRecord, ok, outputJson, requireOneClient, withSpinner, } from './helpers.js';
 export const handleBilling = async (ctx) => {
     const subcommand = (ctx.rest[0] ?? 'summary').toLowerCase();
     if (!['summary', 'show', 'status', 'portal', 'open'].includes(subcommand))
-        throw new Error('Usage: vigilbase billing [summary|portal]');
+        throw unknownSubcommand('billing', ctx.rest[0] ?? '');
     validateArguments(ctx, ctx.rest[0] === undefined ? 0 : 1, ['portal', 'open'].includes(subcommand) ? ['isNoOpen'] : []);
     const one = await requireOneClient(ctx);
     if (subcommand === 'summary' ||

package/dist/commands/cloudflare.d.ts

@@ -1,3 +1,3 @@
 import { type CommandHandler } from './helpers.js';
-export declare const CLOUDFLARE_HELP = "Usage: vigilbase cf <command> [options]\nAlias: vigilbase cloudflare\n\nInventory and workspace:\n  zones                         List zones (default); --customer-id, --account-id, --zone-id\n  zone <zone-id>                Zone detail; --customer-id selects live details, optional --account-id\n  accounts                      List accessible accounts; --customer-id, --account-id\n  account <account-id>          Stored account detail; --customer-id\n  workspace [section]           Workspace bootstrap or section; --customer-id, --account-id, --zone-id\n    Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings\n\nZone reads (--customer-id <uuid> required; IDs can use --zone-id):\n  dns <zone-id>                 DNS records, TTL and proxy state\n  waf <zone-id>                 WAF rules, expressions, analytics and suggestions\n  speed-settings <zone-id>      Performance settings (internal users only)\n\nAccount reads (optional --customer-id; IDs can use --account-id):\n  audit-logs <account-id>       Latest provider audit events (up to 100; service-read permission)\n  zero-trust <account-id>       Users, Access applications, tunnels and authentication analytics\n  developer-platform <account-id>\n                                Workers, Workers analytics and Pages\n  magic-transit <account-id>    Prefixes, routes and traffic analytics\n    Zero Trust, Developer Platform and Magic Transit require deployment-read permission.\n\nAnalytics and checkups:\n  analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>] [--days 1..30]\n    Default 7 days; live zone analytics uses the most recent 23 hours.\n  checkup [status]              Latest completed checkup; --customer-id, --account-id\n  checkup start                 Start and persist a scan; --customer-id, --account-id\n  checkup progress <run-uuid>   Read saved progress once\n  checkup result <run-uuid>     Read the stored Cloudflare checkup result\n    checkups aliases checkup; list/show alias status; run aliases start.\n\nCommon options: --json, --one-url <origin>, --timeout <milliseconds>, --help\nCustomer IDs are UUIDs; account and zone IDs are 32 hexadecimal characters.\nOne login, tenant bindings and permissions apply to every command.\nCheckup start creates a scan run. These commands do not edit provider configuration.\nSee CLOUDFLARE.md for full grammar, API mapping, data limits and examples.";
+export declare const CLOUDFLARE_HELP = "Usage: vigilbase cf <command> [options]\nAlias: vigilbase cloudflare\n\nInventory and workspace:\n  zones                         List zones (default)\n                                --customer-id --account-id --zone-id\n  zone <zone-id>                Zone detail; --customer-id for live details,\n                                optional --account-id\n  accounts                      List accessible accounts\n                                --customer-id --account-id\n  account <account-id>          Stored account detail; --customer-id\n  workspace [section]           Workspace bootstrap or one section\n                                --customer-id --account-id --zone-id\n    Sections: overview, reports, zones, rule-analyzer,\n    accounts, checkups, settings\n\nZone reads (--customer-id <uuid> required; IDs can use --zone-id):\n  dns <zone-id>                 DNS records, TTL and proxy state\n  waf <zone-id>                 WAF rules, expressions, analytics and\n                                suggestions\n  speed-settings <zone-id>      Performance settings (internal users only)\n\nAccount reads (optional --customer-id; IDs can use --account-id):\n  audit-logs <account-id>       Latest provider audit events (up to 100)\n                                Needs service-read permission.\n  zero-trust <account-id>       Users, Access applications, tunnels and\n                                authentication analytics\n  developer-platform <account-id>\n                                Workers, Workers analytics and Pages\n  magic-transit <account-id>    Prefixes, routes and traffic analytics\n    Zero Trust, Developer Platform and Magic Transit require deployment-read permission.\n\nAnalytics and checkups:\n  analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>]\n    [--days 1..30]\n    Default 7 days; live zone analytics uses the most recent 23 hours.\n  checkup [status]              Latest completed checkup\n                                --customer-id --account-id\n  checkup start                 Start and persist a scan\n                                --customer-id --account-id\n  checkup progress <run-uuid>   Read saved progress once\n  checkup result <run-uuid>     Read the stored Cloudflare checkup result\n    checkups aliases checkup; list/show alias status; run aliases start.\n\nCommon options: --json, --one-url <origin>, --timeout <milliseconds>, --help\nCustomer IDs are UUIDs; account and zone IDs are 32 hexadecimal characters.\nOne login, tenant bindings and permissions apply to every command.\nCheckup start creates a scan run. These commands do not edit provider configuration.\nSee CLOUDFLARE.md for full grammar, API mapping, data limits and examples.";
 export declare const handleCloudflare: CommandHandler;