@vigilbase/cli 0.1.4 → 0.2.1

package/dist/lib/format.d.ts

@@ -5,6 +5,8 @@ export type Writer = {
 };
 /** Untrusted API data must never become terminal control sequences or bidi overrides. */
 export declare function sanitizeTerminal(value: string): string;
+/** One sanitised line, cut to `maxLength` characters with an ellipsis. */
+export declare function singleLine(value: string, maxLength?: number): string;
 export declare function createWriter(stdout?: NodeJS.WritableStream, stderr?: NodeJS.WritableStream): Writer;
 export declare function printJson(writer: Writer, value: unknown): void;
 export declare function formatToolsList(catalog: AgentToolsCatalogResponse, mode: CliOutputMode, writer: Writer, options?: {
@@ -16,4 +18,3 @@ export declare function formatToolsList(catalog: AgentToolsCatalogResponse, mode
 export declare function formatToolDescription(tool: AgentToolDefinition, mode: CliOutputMode, writer: Writer, skillMarkdown?: string): void;
 export declare function formatExecuteResult(result: AgentToolExecuteResponse, mode: CliOutputMode, writer: Writer): void;
 export declare function formatError(error: unknown, mode: CliOutputMode, writer: Writer): void;
-//# sourceMappingURL=format.d.ts.map

package/dist/lib/format.js

@@ -3,6 +3,11 @@ import { stripVTControlCharacters } from 'node:util';
 export function sanitizeTerminal(value) {
     return stripVTControlCharacters(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '');
 }
+/** One sanitised line, cut to `maxLength` characters with an ellipsis. */
+export function singleLine(value, maxLength = 300) {
+    const line = sanitizeTerminal(value).replace(/\s+/g, ' ').trim();
+    return line.length > maxLength ? `${line.slice(0, maxLength - 1).trimEnd()}…` : line;
+}
 export function createWriter(stdout = process.stdout, stderr = process.stderr) {
     return {
         stdout: (line = '') => {
@@ -257,8 +262,9 @@ export function formatExecuteResult(result, mode, writer) {
         writer.stdout(head);
     else
         writer.stderr(head);
-    if (result.error) {
-        writer.stderr(`  ${result.error}`);
+    const error = typeof result.error === 'string' ? result.error : result.error?.message;
+    if (error) {
+        writer.stderr(`  ${error}`);
     }
     for (const line of summarizeResultCompact(result.result)) {
         writer.stdout(`  ${line}`);
@@ -266,11 +272,17 @@ export function formatExecuteResult(result, mode, writer) {
 }
 export function formatError(error, mode, writer) {
     let message = error instanceof Error ? error.message : String(error);
+    let reason = '';
     // Server bodies can contain credentials, customer data, or arbitrary error text.
     if (error && typeof error === 'object' && 'body' in error && error.body != null && 'status' in error && typeof error.status === 'number') {
-        message = 'code' in error && error.code === 'FLAREHAWK_VIEW_AS_REQUIRED'
-            ? 'Select a customer with --customer-id <customer UUID> for security commands.'
-            : `Request failed (HTTP ${error.status}).`;
+        if ('code' in error && error.code === 'FLAREHAWK_VIEW_AS_REQUIRED') {
+            message = 'Select a customer with --customer-id <customer UUID> for security commands.';
+        }
+        else {
+            // Only the reason the public client accepted from a known problem+json error is shown.
+            reason = 'reason' in error && typeof error.reason === 'string' ? singleLine(error.reason) : '';
+            message = reason || `Request failed (HTTP ${error.status}).`;
+        }
     }
     const payload = {
         success: false,
@@ -292,14 +304,22 @@ export function formatError(error, mode, writer) {
             error.retryAfterSec >= 0) {
             payload.retryAfterSec = error.retryAfterSec;
         }
+        // CLI-authored remediation (never server text); bounded and sanitised like any output.
+        if ('hint' in error && typeof error.hint === 'string') {
+            const hint = singleLine(error.hint);
+            if (hint)
+                payload.hint = hint;
+        }
     }
     if (mode === 'json') {
         printJson(writer, payload);
         return;
     }
-    writer.stderr(`Error: ${message}`);
+    writer.stderr(`Error: ${message}${reason && typeof payload.code === 'string' ? ` (${payload.code})` : ''}`);
     if (typeof payload.retryAfterSec === 'number') {
         writer.stderr(`Retry after ${payload.retryAfterSec}s`);
     }
+    if (typeof payload.hint === 'string') {
+        writer.stderr(`Hint: ${payload.hint}`);
+    }
 }
-//# sourceMappingURL=format.js.map

package/dist/lib/help.d.ts

@@ -1,4 +1,3 @@
 export declare const HELP_TAGLINE = "one \u00B7 security \u00B7 tools";
-export declare const HELP_TEXT = "Usage: vigilbase <command>\n\nPublic tools (no login)\n  list                         List available tools\n  run <tool> <target>          Run a scan\n  headers <url>                Check security headers\n  email <domain>               Check email security\n  describe <tool> \u00B7 skill      Tool details / skill markdown\n  badge <domain> \u00B7 doctor      Badge URL \u00B7 connectivity\n\nAuth-required tools (after login)\n  website-security \u00B7 react2shell \u00B7 fortibleed-check\n\nAccount (login required)\n  login \u00B7 logout \u00B7 whoami      Session\n  account [services|org|\u2026]     Account overview\n  account endpoints            Endpoint inventory\n  account sessions             Active sessions\n  account invites [list|create]\n  billing [summary|portal]     Billing summary / Stripe portal\n  runs [list|get <id>]         Tool run history\n  cf <command>                Cloudflare accounts, zones, DNS, WAF, analytics\n  security <command>          Incidents, logs, assets, detections, intel, reports\n  watchdog [list|scans]        Watchdog targets / scans\n  customers <command>         Customer records, billing, reports, investigations\n  orgs <command>              Organizations, members, permission roles\n  monitoring <command>        Health, probes, metrics, customer targets\n  support tickets             Support ticket history\n\nOptions\n  -j, --json                   JSON output\n  -h, --help                   Help for the current command\n  -V, --version                Installed version\n  --timeout <milliseconds>     Request timeout (default: 60000)\n  --base-url <origin>           Public API origin\n  --one-url <origin>            Vigilbase One origin\n  --client-id <id>              Device authorization client ID\n\nUse vigilbase <command> --help for command options.\n\nExamples\n  vigilbase headers https://vigilbase.com\n  vigilbase email vigilbase.com --json\n  vigilbase login\n  vigilbase account --json\n  vigilbase runs list --json\n  vigilbase cf zones\n  vigilbase security incidents --severity high\n";
+export declare const HELP_TEXT: string;
 export declare function helpForCommand(command: string): string | null;
-//# sourceMappingURL=help.d.ts.map

package/dist/lib/help.js

@@ -1,7 +1,26 @@
 import { CLOUDFLARE_HELP } from '../commands/cloudflare.js';
+import { LOCAL_HELP } from '../commands/local.js';
 import { ONE_HELP } from '../commands/one.js';
 import { SECURITY_HELP } from '../commands/security.js';
 export const HELP_TAGLINE = 'one · security · tools';
+/** Column where descriptions start in the main help: two-space indent, term, at least two spaces. */
+const DESCRIPTION_COLUMN = 31;
+/** Two-column help rows whose descriptions all start at DESCRIPTION_COLUMN. */
+function helpRows(rows) {
+    return rows
+        .map(([term, description]) => `  ${term.padEnd(DESCRIPTION_COLUMN - 4)}  ${description}`)
+        .join('\n');
+}
+const GLOBAL_OPTIONS = helpRows([
+    ['-j, --json', 'JSON output'],
+    ['-h, --help', 'Help for the current command'],
+    ['-V, --version', 'Installed version'],
+    ['--timeout <milliseconds>', 'Request timeout (default: 60000)'],
+    ['--base-url <origin>', 'Public API origin'],
+    ['--one-url <origin>', 'Vigilbase One origin'],
+    ['--auth-url <origin>', 'Identity issuer (default: auth.vigilbase.com)'],
+    ['--client-id <id>', 'Device authorization client ID'],
+]);
 export const HELP_TEXT = `Usage: vigilbase <command>
 
 Public tools (no login)
@@ -15,6 +34,10 @@ Public tools (no login)
 Auth-required tools (after login)
   website-security · react2shell · fortibleed-check
 
+On this machine (no login)
+  cloudflare-checkup           Run the Cloudflare Checkup on this machine in one
+                               command (alias: local cloudflare-checkup)
+
 Account (login required)
   login · logout · whoami      Session
   account [services|org|…]     Account overview
@@ -23,22 +46,16 @@ Account (login required)
   account invites [list|create]
   billing [summary|portal]     Billing summary / Stripe portal
   runs [list|get <id>]         Tool run history
-  cf <command>                Cloudflare accounts, zones, DNS, WAF, analytics
-  security <command>          Incidents, logs, assets, detections, intel, reports
+  cf <command>                 Cloudflare accounts, zones, DNS, WAF, analytics
+  security <command>           Incidents, logs, assets, detections, intel, reports
   watchdog [list|scans]        Watchdog targets / scans
-  customers <command>         Customer records, billing, reports, investigations
-  orgs <command>              Organizations, members, permission roles
-  monitoring <command>        Health, probes, metrics, customer targets
-  support tickets             Support ticket history
+  customers <command>          Customer records, billing, reports, investigations
+  orgs <command>               Organizations, members, permission roles
+  monitoring <command>         Health, probes, metrics, customer targets
+  support tickets              Support ticket history
 
 Options
-  -j, --json                   JSON output
-  -h, --help                   Help for the current command
-  -V, --version                Installed version
-  --timeout <milliseconds>     Request timeout (default: 60000)
-  --base-url <origin>           Public API origin
-  --one-url <origin>            Vigilbase One origin
-  --client-id <id>              Device authorization client ID
+${GLOBAL_OPTIONS}
 
 Use vigilbase <command> --help for command options.
 
@@ -70,9 +87,10 @@ Login:  website-security, react2shell, fortibleed-check`;
         case 'doctor':
             return `Usage: vigilbase doctor [--json]
 
-Checks the public tools API and Vigilbase One session endpoint independently.
-Login is optional. Exits with status 1 if either check fails.
-Use --base-url, --one-url, and --timeout to check alternate environments.`;
+Checks the public tools API, your session (Identity's userinfo endpoint when
+signed in through Identity, otherwise One's session endpoint) and any saved
+sign-in independently. Login is optional. Exits with status 1 if any check fails.
+Use --base-url, --one-url, --auth-url and --timeout to check other environments.`;
         case 'account':
             return `Usage: vigilbase account [services|org|endpoints|sessions|invites|billing] [--json]
 
@@ -95,6 +113,9 @@ List only: --tool <name>, --limit <1..200> (default 50).`;
         case 'watchdog':
             return `Usage: vigilbase watchdog [list|scans] [--json]
 Scans only: --target-id <UUID>, --limit <1..100> (default 20).`;
+        case 'local':
+        case 'cloudflare-checkup':
+            return LOCAL_HELP;
         case 'billing':
             return `Usage: vigilbase billing [summary|portal] [--json]
 Portal only: --no-open. URLs must use HTTPS on billing.stripe.com.`;
@@ -113,4 +134,3 @@ Prefer --token-stdin with piped input to keep tokens out of command arguments.`;
             return null;
     }
 }
-//# sourceMappingURL=help.js.map

package/dist/lib/network.d.ts

@@ -8,10 +8,19 @@ export declare function networkError(error: unknown, url: string, timeoutMs: num
 export declare const MAX_RESPONSE_BYTES: number;
 /** Bound decoded bytes even when Content-Length is absent, compressed, or dishonest. */
 export declare function readBoundedBody(response: Response, signal: AbortSignal, maxBytes?: number): Promise<string>;
+/**
+ * A signal that aborts with the reason of the first of `signals` to abort.
+ * Uses `AbortSignal.any` (Node 20.3+) and combines them by hand on older
+ * Node 20; `dispose` then removes the listeners so a long-lived signal does
+ * not collect one per request.
+ */
+export declare function anySignal(signals: AbortSignal[]): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
 /** Keep the timeout active until the complete response body has been read. */
 export declare function requestText(config: CliConfig, url: string, init?: RequestInit): Promise<{
     response: Response;
     text: string;
 }>;
 export declare function parseJsonResponse(response: Response, text: string): unknown;
-//# sourceMappingURL=network.d.ts.map

package/dist/lib/network.js

@@ -70,16 +70,44 @@ export async function readBoundedBody(response, signal, maxBytes = MAX_RESPONSE_
         reader.releaseLock();
     }
 }
+/**
+ * A signal that aborts with the reason of the first of `signals` to abort.
+ * Uses `AbortSignal.any` (Node 20.3+) and combines them by hand on older
+ * Node 20; `dispose` then removes the listeners so a long-lived signal does
+ * not collect one per request.
+ */
+export function anySignal(signals) {
+    if (typeof AbortSignal.any === 'function')
+        return { signal: AbortSignal.any(signals), dispose: () => undefined };
+    const controller = new AbortController();
+    const dispose = () => {
+        for (const signal of signals)
+            signal.removeEventListener('abort', onAbort);
+    };
+    function onAbort(event) {
+        dispose();
+        controller.abort(event.target.reason);
+    }
+    const aborted = signals.find((signal) => signal.aborted);
+    if (aborted) {
+        controller.abort(aborted.reason);
+        return { signal: controller.signal, dispose: () => undefined };
+    }
+    for (const signal of signals)
+        signal.addEventListener('abort', onAbort, { once: true });
+    return { signal: controller.signal, dispose };
+}
 /** Keep the timeout active until the complete response body has been read. */
 export async function requestText(config, url, init = {}) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), config.timeoutMs);
-    const signal = init.signal
-        ? AbortSignal.any([init.signal, controller.signal])
-        : controller.signal;
+    const { signal, dispose } = init.signal
+        ? anySignal([init.signal, controller.signal])
+        : { signal: controller.signal, dispose: () => undefined };
     try {
         // Never forward token-bearing POST bodies (or credentials) through redirects.
-        const response = await fetch(url, { ...init, signal, redirect: 'error' });
+        // 'manual' is honoured because it surfaces the 3xx without following it.
+        const response = await fetch(url, { ...init, signal, redirect: init.redirect === 'manual' ? 'manual' : 'error' });
         return { response, text: await readBoundedBody(response, signal) };
     }
     catch (error) {
@@ -92,6 +120,7 @@ export async function requestText(config, url, init = {}) {
     }
     finally {
         clearTimeout(timer);
+        dispose();
     }
 }
 export function parseJsonResponse(response, text) {
@@ -105,4 +134,3 @@ export function parseJsonResponse(response, text) {
         throw new NetworkError(`Expected JSON but received a non-JSON response (HTTP ${response.status}). Check the configured API URL and any proxy or sign-in page.`, 'INVALID_RESPONSE');
     }
 }
-//# sourceMappingURL=network.js.map

package/dist/lib/one-client.d.ts

@@ -45,8 +45,11 @@ export declare const ONE_EXECUTABLE_TOOLS: readonly ["security-headers", "email-
 export declare function isOneExecutableTool(toolName: string): boolean;
 export declare class VigilbaseOneClient {
     private readonly config;
-    private readonly accessToken;
-    constructor(config: CliConfig, accessToken: string);
+    private accessToken;
+    private readonly managed;
+    /** The userinfo endpoint Identity discovery named for the last getSession, if it used Identity. */
+    userinfoEndpoint?: string;
+    constructor(config: CliConfig, accessToken: string, managed?: boolean);
     private request;
     /** Authenticated JSON transport shared by the One command clients. */
     requestJson<T extends ApiErrorBody = Record<string, unknown>>(path: string, init?: RequestInit, options?: {
@@ -88,4 +91,3 @@ export declare class VigilbaseOneClient {
     executeTool(toolName: string, target: string): Promise<OneToolExecuteResponse>;
 }
 export {};
-//# sourceMappingURL=one-client.d.ts.map

package/dist/lib/one-client.js

@@ -1,3 +1,6 @@
+import { managedAccessToken } from '../auth/refresh.js';
+import { readCredentials } from '../auth/store.js';
+import { identityProvider } from '../auth/provider.js';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { validateOneOrigin } from './config.js';
@@ -80,13 +83,22 @@ export function isOneExecutableTool(toolName) {
 export class VigilbaseOneClient {
     config;
     accessToken;
-    constructor(config, accessToken) {
+    managed;
+    /** The userinfo endpoint Identity discovery named for the last getSession, if it used Identity. */
+    userinfoEndpoint;
+    constructor(config, accessToken, managed = false) {
         this.config = config;
         this.accessToken = accessToken;
+        this.managed = managed;
     }
     async request(path, init) {
         const url = `${validateOneOrigin(this.config.oneBaseUrl)}${path.startsWith('/') ? path : `/${path}`}`;
-        const { response, text } = await requestText(this.config, url, {
+        if (this.managed) {
+            const token = await managedAccessToken(this.config);
+            if (token)
+                this.accessToken = token;
+        }
+        const send = () => requestText(this.config, url, {
             ...init,
             headers: {
                 Accept: 'application/json',
@@ -95,6 +107,14 @@ export class VigilbaseOneClient {
                 ...(init?.headers ?? {}),
             },
         });
+        let { response, text } = await send();
+        if (response.status === 401 && this.managed) {
+            const token = await managedAccessToken(this.config, this.accessToken);
+            if (token) {
+                this.accessToken = token;
+                ({ response, text } = await send());
+            }
+        }
         return { response, body: parseJsonResponse(response, text) };
     }
     /** Authenticated JSON transport shared by the One command clients. */
@@ -135,6 +155,33 @@ export class VigilbaseOneClient {
         return parsed;
     }
     async getSession() {
+        const saved = this.managed ? await readCredentials(this.config) : null;
+        const issuer = this.config.authProvider?.issuer ?? (saved?.version === 2 ? saved.one?.issuer : undefined);
+        if (issuer) {
+            const provider = await identityProvider(this.config, issuer);
+            this.userinfoEndpoint = provider.userinfoEndpoint;
+            if (this.managed) {
+                const token = await managedAccessToken(this.config);
+                if (!token)
+                    throw new VigilbaseApiError('Authentication required.', { status: 401 });
+                this.accessToken = token;
+            }
+            const load = () => requestText(this.config, provider.userinfoEndpoint, { headers: { Authorization: `Bearer ${this.accessToken}`, Accept: 'application/json', 'User-Agent': this.config.userAgent } });
+            let { response, text } = await load();
+            if (response.status === 401 && this.managed) {
+                const token = await managedAccessToken(this.config, this.accessToken);
+                if (token) {
+                    this.accessToken = token;
+                    ({ response, text } = await load());
+                }
+            }
+            if (!response.ok)
+                throw new VigilbaseApiError('Failed to load Identity profile.', { status: response.status });
+            const user = z.object({ sub: z.string(), email: z.string().optional(), name: z.string().optional() }).safeParse(parseJsonResponse(response, text));
+            if (!user.success)
+                throw new VigilbaseApiError('Invalid Identity profile.', { status: response.status });
+            return { user: { id: user.data.sub, email: user.data.email, name: user.data.name } };
+        }
         const { response, body } = await this.request('/api/auth/get-session');
         if (!response.ok) {
             throw new VigilbaseApiError(`Failed to load One session (HTTP ${response.status})`, { status: response.status, body });
@@ -239,4 +286,3 @@ export class VigilbaseOneClient {
         }, { allowStatuses: [422] });
     }
 }
-//# sourceMappingURL=one-client.js.map

package/dist/lib/one-operations.d.ts

@@ -8,4 +8,3 @@ export interface OneOperation {
 export declare function executeOneOperation(client: VigilbaseOneClient, operation: OneOperation): Promise<Record<string, unknown>>;
 /** Render all fields, including pagination and degraded-health metadata. */
 export declare function formatOnePayload(value: unknown, indent?: string): string[];
-//# sourceMappingURL=one-operations.d.ts.map

package/dist/lib/one-operations.js

@@ -64,4 +64,3 @@ export function formatOnePayload(value, indent = '') {
         return [`${indent}${safeText(key)}: ${safeText(item)}`];
     });
 }
-//# sourceMappingURL=one-operations.js.map

package/dist/lib/open-url.d.ts

@@ -24,4 +24,3 @@ export declare function resolveDeviceVerificationUrl(oneBaseUrl: string, device:
     verification_uri?: string;
     verification_uri_complete?: string;
 }): string;
-//# sourceMappingURL=open-url.d.ts.map

package/dist/lib/open-url.js

@@ -110,4 +110,3 @@ export function resolveDeviceVerificationUrl(oneBaseUrl, device) {
     // redirect parameters, fragments, or paths, even when they share One's origin.
     return fallback;
 }
-//# sourceMappingURL=open-url.js.map

package/dist/lib/platform.d.ts

@@ -0,0 +1,2 @@
+/** The host platform. A function rather than a constant so tests can simulate Windows. */
+export declare function platform(): NodeJS.Platform;

package/dist/lib/platform.js

@@ -0,0 +1,4 @@
+/** The host platform. A function rather than a constant so tests can simulate Windows. */
+export function platform() {
+    return process.platform;
+}

package/dist/lib/progress.d.ts

@@ -17,4 +17,3 @@ export declare function shouldShowProgress(mode: 'text' | 'json', env?: NodeJS.P
 }): boolean;
 /** Tiny helper so call sites stay readable. */
 export declare function withProgress<T>(label: string, mode: 'text' | 'json', work: () => Promise<T>, writer?: Writer): Promise<T>;
-//# sourceMappingURL=progress.d.ts.map

package/dist/lib/progress.js

@@ -77,4 +77,3 @@ export async function withProgress(label, mode, work, writer) {
         throw error;
     }
 }
-//# sourceMappingURL=progress.js.map

package/dist/lib/security-client.d.ts

@@ -237,8 +237,8 @@ export declare const securityResponses: {
     intel: z.ZodObject<{
         query: z.ZodString;
         query_type: z.ZodEnum<{
-            ip: "ip";
             asn: "asn";
+            ip: "ip";
             cidr: "cidr";
             ja3: "ja3";
             ja4: "ja4";
@@ -276,4 +276,3 @@ export declare class SecurityClient {
     constructor(one: VigilbaseOneClient);
     request(input: SecurityRequest): Promise<SecurityPayload>;
 }
-//# sourceMappingURL=security-client.d.ts.map

package/dist/lib/security-client.js

@@ -108,4 +108,3 @@ export class SecurityClient {
         return payload;
     }
 }
-//# sourceMappingURL=security-client.js.map

package/dist/lib/skill-fetch.d.ts

@@ -4,4 +4,3 @@ export declare function isPublicSkillAddress(address: string): boolean;
 export declare function validateSkillUrl(raw: string): URL;
 /** Resolve once, reject mixed private/public DNS, and pin the validated address to TLS. */
 export declare function fetchSkillText(config: CliConfig, raw: string): Promise<string>;
-//# sourceMappingURL=skill-fetch.d.ts.map

package/dist/lib/skill-fetch.js

@@ -99,4 +99,3 @@ export async function fetchSkillText(config, raw) {
         clearTimeout(timer);
     }
 }
-//# sourceMappingURL=skill-fetch.js.map

package/dist/lib/system-trust.d.ts

@@ -5,4 +5,3 @@ type SystemTrustApi = {
 /** CLI startup only: preserve bundled/extra CAs and add OS-managed trust. */
 export declare function configureSystemTrust(api?: SystemTrustApi): boolean;
 export {};
-//# sourceMappingURL=system-trust.d.ts.map

package/dist/lib/system-trust.js

@@ -8,4 +8,3 @@ export function configureSystemTrust(api = tls) {
     ]);
     return true;
 }
-//# sourceMappingURL=system-trust.js.map