@vigilbase/cli 0.2.0 → 0.2.1

package/dist/commands/security.js

@@ -387,5 +387,4 @@ export const handleSecurity = async (ctx) => {
         display(ctx, request, payload);
     return ok();
 };
-export const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                       --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>                --limit --before\n  incidents fabric <id>                  --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>         --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>                --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections                            --asset-id\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";
-//# sourceMappingURL=security.js.map
+export const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections                            --asset-id\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";

package/dist/commands/watchdog.d.ts

@@ -1,3 +1,2 @@
 import { type CommandHandler } from './helpers.js';
 export declare const handleWatchdog: CommandHandler;
-//# sourceMappingURL=watchdog.d.ts.map

package/dist/commands/watchdog.js

@@ -59,4 +59,3 @@ export const handleWatchdog = async (ctx) => {
     }
     throw new Error('Usage: vigilbase watchdog [list|scans] [--target-id …] [--limit …] [--json]');
 };
-//# sourceMappingURL=watchdog.js.map

package/dist/index.d.ts

@@ -1,14 +1,13 @@
 export { runCli, CLI_VERSION } from './cli.js';
 export { VigilbaseClient, VigilbaseApiError } from './lib/client.js';
 export { createConfig, resolveBaseUrl, resolvePublicBaseUrl, resolveOneBaseUrl, } from './lib/config.js';
-export { discoverAuthProvider, identityProvider, managedAccessToken, revokeSavedCredentials, clearOneCredentials, credentialsPath, DeviceAuthError, getOneAccessToken, readCredentials, requestDeviceCode, waitForDeviceAuthorization, writeOneCredentials, } from './auth/index.js';
+export { discoverAuthProvider, identityProvider, managedAccessToken, revokeSavedCredentials, clearOneCredentials, credentialsPath, DeviceAuthError, getOneAccessToken, identityCredentialsPath, readCredentials, requestDeviceCode, waitForDeviceAuthorization, writeOneCredentials, } from './auth/index.js';
 export { isOneAuthRequiredTool, isOneExecutableTool, ONE_AUTH_REQUIRED_TOOLS, ONE_AUTH_REQUIRED_TOOL_DEFINITIONS, ONE_EXECUTABLE_TOOLS, VigilbaseOneClient, } from './lib/one-client.js';
 export { EXIT } from './types.js';
-export type { AgentToolDefinition, AgentToolExecuteResponse, AgentToolsCatalogResponse, CliOutputMode, ExitCode, } from './types.js';
+export type { AgentApiError, AgentApiErrorCode, AgentApiErrorResponse, AgentToolDefinition, AgentToolExecuteResponse, AgentToolsCatalogResponse, CliOutputMode, ExitCode, } from './types.js';
 export type { AuthProvider } from './auth/provider.js';
 export type { CredentialsFile, OneCredentials } from './auth/types.js';
 export { CloudflareClient } from './lib/cloudflare-client.js';
 export type { CloudflareScope, WorkspaceSection } from './lib/cloudflare-client.js';
 export { SecurityClient } from './lib/security-client.js';
 export type { SecurityPayload, SecurityQuery, SecurityRequest } from './lib/security-client.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,9 +1,8 @@
 export { runCli, CLI_VERSION } from './cli.js';
 export { VigilbaseClient, VigilbaseApiError } from './lib/client.js';
 export { createConfig, resolveBaseUrl, resolvePublicBaseUrl, resolveOneBaseUrl, } from './lib/config.js';
-export { discoverAuthProvider, identityProvider, managedAccessToken, revokeSavedCredentials, clearOneCredentials, credentialsPath, DeviceAuthError, getOneAccessToken, readCredentials, requestDeviceCode, waitForDeviceAuthorization, writeOneCredentials, } from './auth/index.js';
+export { discoverAuthProvider, identityProvider, managedAccessToken, revokeSavedCredentials, clearOneCredentials, credentialsPath, DeviceAuthError, getOneAccessToken, identityCredentialsPath, readCredentials, requestDeviceCode, waitForDeviceAuthorization, writeOneCredentials, } from './auth/index.js';
 export { isOneAuthRequiredTool, isOneExecutableTool, ONE_AUTH_REQUIRED_TOOLS, ONE_AUTH_REQUIRED_TOOL_DEFINITIONS, ONE_EXECUTABLE_TOOLS, VigilbaseOneClient, } from './lib/one-client.js';
 export { EXIT } from './types.js';
 export { CloudflareClient } from './lib/cloudflare-client.js';
 export { SecurityClient } from './lib/security-client.js';
-//# sourceMappingURL=index.js.map

package/dist/lib/banner.d.ts

@@ -26,4 +26,3 @@ export declare function shouldShowBanner(mode?: 'text' | 'json', env?: NodeJS.Pr
 export declare function renderBanner(options?: BannerOptions, stream?: {
     isTTY?: boolean;
 } | undefined, env?: NodeJS.ProcessEnv): string;
-//# sourceMappingURL=banner.d.ts.map

package/dist/lib/banner.js

@@ -65,4 +65,3 @@ export function renderBanner(options = {}, stream = process.stdout, env = proces
     });
     return lines.join('\n');
 }
-//# sourceMappingURL=banner.js.map

package/dist/lib/client.d.ts

@@ -1,15 +1,18 @@
-import type { AgentToolExecuteResponse, AgentToolsCatalogResponse } from '../types.js';
+import { type AgentToolExecuteResponse, type AgentToolsCatalogResponse } from '../types.js';
 import type { CliConfig } from './config.js';
 export declare class VigilbaseApiError extends Error {
     readonly status: number;
     readonly body: unknown;
     readonly retryAfterSec?: number;
     readonly code?: string;
+    /** The server's sanitised explanation, set only for known vigilbase.com problem errors. */
+    readonly reason?: string;
     constructor(message: string, options: {
         status: number;
         body?: unknown;
         retryAfterSec?: number;
         code?: string;
+        reason?: string;
     });
 }
 export declare function retryAfterSeconds(response: Response, body: unknown): number | undefined;
@@ -27,4 +30,3 @@ export declare class VigilbaseClient {
     fetchSkillMarkdown(skillUrl: string): Promise<string>;
     badgeUrl(domain: string, style?: 'default' | 'compact' | 'mini'): string;
 }
-//# sourceMappingURL=client.d.ts.map

package/dist/lib/client.js

@@ -1,11 +1,15 @@
 import { z } from 'zod';
+import { singleLine } from './format.js';
 import { parseJsonResponse, requestText } from './network.js';
 import { fetchSkillText } from './skill-fetch.js';
+import { AGENT_API_ERROR_CODES, } from '../types.js';
 export class VigilbaseApiError extends Error {
     status;
     body;
     retryAfterSec;
     code;
+    /** The server's sanitised explanation, set only for known vigilbase.com problem errors. */
+    reason;
     constructor(message, options) {
         super(message);
         this.name = 'VigilbaseApiError';
@@ -13,6 +17,7 @@ export class VigilbaseApiError extends Error {
         this.body = options.body;
         this.retryAfterSec = options.retryAfterSec;
         this.code = options.code;
+        this.reason = options.reason;
     }
 }
 export function retryAfterSeconds(response, body) {
@@ -30,6 +35,39 @@ export function retryAfterSeconds(response, body) {
     }
     return undefined;
 }
+/** Longer messages are withheld rather than cut. */
+const MAX_REASON_SOURCE_LENGTH = 1000;
+const problemSchema = z.object({
+    error: z.object({ code: z.unknown(), message: z.string().max(MAX_REASON_SOURCE_LENGTH) }),
+    code: z.unknown(),
+});
+/**
+ * The reason a vigilbase.com problem+json error gives, when its code is one com sends.
+ * Anything else stays redacted: other media types, unknown codes, odd messages.
+ */
+function problemReason(response, body) {
+    const mediaType = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+    if (mediaType !== 'application/problem+json')
+        return undefined;
+    const problem = problemSchema.safeParse(body);
+    if (!problem.success)
+        return undefined;
+    const code = z.enum(AGENT_API_ERROR_CODES).safeParse(problem.data.error.code ?? problem.data.code);
+    if (!code.success)
+        return undefined;
+    const message = singleLine(problem.data.error.message);
+    return message ? { code: code.data, message } : undefined;
+}
+function publicApiError(fallback, response, body) {
+    const reason = problemReason(response, body);
+    return new VigilbaseApiError(reason?.message ?? fallback, {
+        status: response.status,
+        body,
+        retryAfterSec: retryAfterSeconds(response, body),
+        code: reason?.code,
+        reason: reason?.message,
+    });
+}
 /**
  * Public (unauthenticated) vigilbase.com tools client.
  * Vigilbase One authenticated calls will use a separate client + device-auth tokens.
@@ -57,12 +95,7 @@ export class VigilbaseClient {
     async listTools() {
         const { response, body } = await this.request('/api/agent/tools');
         if (!response.ok) {
-            const message = `Failed to list tools (HTTP ${response.status})`;
-            throw new VigilbaseApiError(message, {
-                status: response.status,
-                body,
-                retryAfterSec: retryAfterSeconds(response, body),
-            });
+            throw publicApiError(`Failed to list tools (HTTP ${response.status})`, response, body);
         }
         const schema = z.object({
             success: z.literal(true),
@@ -84,24 +117,16 @@ export class VigilbaseClient {
         });
         const parsed = (body ?? {});
         if (response.status === 429) {
-            throw new VigilbaseApiError('Rate limit exceeded. Retry after the indicated delay.', {
-                status: 429,
-                body: parsed,
-                retryAfterSec: retryAfterSeconds(response, body),
-            });
+            throw publicApiError('Rate limit exceeded. Retry after the indicated delay.', response, parsed);
         }
         if (!response.ok && response.status !== 422) {
-            throw new VigilbaseApiError(`Tool execution failed (HTTP ${response.status})`, {
-                status: response.status,
-                body: parsed,
-                retryAfterSec: retryAfterSeconds(response, body),
-            });
+            throw publicApiError(`Tool execution failed (HTTP ${response.status})`, response, parsed);
         }
         if (!z.object({ success: z.boolean() }).passthrough().safeParse(body).success) {
             throw new VigilbaseApiError('Invalid tool execution response. Check the API URL or retry later.', { status: response.status });
         }
         if (!parsed.success) {
-            throw new VigilbaseApiError('Tool execution was unsuccessful.', { status: response.status, body, retryAfterSec: retryAfterSeconds(response, body) });
+            throw publicApiError('Tool execution was unsuccessful.', response, body);
         }
         return parsed;
     }
@@ -116,4 +141,3 @@ export class VigilbaseClient {
         return `${this.origin}/api/badge/${encodeURIComponent(domain)}${query ? `?${query}` : ''}`;
     }
 }
-//# sourceMappingURL=client.js.map

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

@@ -37,4 +37,3 @@ export declare class CloudflareClient {
     checkupProgress(toolRunId: string): Promise<Record<string, unknown>>;
     private path;
 }
-//# sourceMappingURL=cloudflare-client.d.ts.map

package/dist/lib/cloudflare-client.js

@@ -78,4 +78,3 @@ export class CloudflareClient {
         return `${path}${query ? `?${query}` : ''}`;
     }
 }
-//# sourceMappingURL=cloudflare-client.js.map

package/dist/lib/config.d.ts

@@ -5,10 +5,13 @@ export type CliConfig = {
     oneBaseUrl: string;
     /** OAuth client_id for Better Auth device authorization. */
     clientId: string;
-    /** Explicit development issuer; production issuer is chosen through One discovery. */
+    /** Explicit Identity issuer (--auth-url / VIGILBASE_AUTH_URL). One's discovery must name it; unset, only production Identity is trusted. */
     identityBaseUrl?: string;
     authProvider?: import('../auth/provider.js').AuthProvider;
-    /** Directory for credentials and local config (~/.config/vigilbase). */
+    /**
+     * Directory for credentials and local config (~/.config/vigilbase). Not validated when the config is built:
+     * the credential store rejects a relative path itself, so commands that never use it work whatever it holds.
+     */
     configDir: string;
     userAgent: string;
     timeoutMs: number;
@@ -17,14 +20,25 @@ export type CliConfig = {
 export type CliConfigLegacy = CliConfig & {
     baseUrl: string;
 };
+export declare function parseOrigin(raw: string, option: string): string;
 /** Default request timeout; also used when library callers omit `timeoutMs`. */
 export declare const DEFAULT_TIMEOUT_MS = 60000;
 export declare function resolvePublicBaseUrl(explicit?: string | null): string;
 export declare function resolveOneBaseUrl(explicit?: string | null): string;
 /** Validate at transport boundaries too: library callers may construct config objects. */
 export declare function validateOneOrigin(raw: string): string;
+/** Production Identity: the only issuer trusted unless --auth-url / VIGILBASE_AUTH_URL names another. */
+export declare const DEFAULT_IDENTITY_ISSUER = "https://auth.vigilbase.com";
+export declare const STAGING_IDENTITY_ISSUER = "https://identity-staging.vigilbase.com";
 export declare function resolveIdentityBaseUrl(raw: string): string;
+/**
+ * The one Identity issuer this configuration trusts: --auth-url / VIGILBASE_AUTH_URL
+ * when set, otherwise production. Staging is trusted only when configured explicitly.
+ * Validated here too because library callers may construct config objects.
+ */
+export declare function trustedIdentityIssuer(config: Pick<CliConfig, 'oneBaseUrl' | 'identityBaseUrl'>): string;
 export declare function resolveClientId(explicit?: string | null): string;
+/** The config directory, which must be absolute. */
 export declare function resolveConfigDir(explicit?: string | null, env?: NodeJS.ProcessEnv): string;
 export declare function createConfig(options?: {
     baseUrl?: string | null;
@@ -45,4 +59,3 @@ export declare function createConfig(options?: {
 export declare function createLocalCommandConfig(timeoutMs?: number): CliConfigLegacy;
 /** Back-compat helper used by older call sites / tests. */
 export declare function resolveBaseUrl(explicit?: string | null): string;
-//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.js

@@ -9,7 +9,7 @@ const DEFAULT_CLIENT_ID = 'vigilbase-cli';
 const originSchema = z.string().url().transform((raw) => new URL(raw)).refine((url) => (url.protocol === 'https:' || url.protocol === 'http:') &&
     !url.username && !url.password &&
     /^\/+$/.test(url.pathname) && !url.search && !url.hash, 'Expected an HTTP(S) origin without credentials, a path, query, or fragment.').transform((url) => url.origin);
-function parseOrigin(raw, option) {
+export function parseOrigin(raw, option) {
     const result = originSchema.safeParse(raw);
     if (!result.success) {
         // Do not echo the input: malformed URLs can contain credentials.
@@ -44,10 +44,32 @@ export function validateOneOrigin(raw) {
     }
     return origin;
 }
+/** Production Identity: the only issuer trusted unless --auth-url / VIGILBASE_AUTH_URL names another. */
+export const DEFAULT_IDENTITY_ISSUER = 'https://auth.vigilbase.com';
+export const STAGING_IDENTITY_ISSUER = 'https://identity-staging.vigilbase.com';
+const IDENTITY_OPTION = '--auth-url / VIGILBASE_AUTH_URL';
+function isIdentityLoopback(origin) {
+    return ['localhost', '127.0.0.1', '[::1]'].includes(new URL(origin).hostname);
+}
 export function resolveIdentityBaseUrl(raw) {
-    const origin = validateOneOrigin(raw);
-    if (!['https://auth.vigilbase.com', 'https://identity-staging.vigilbase.com'].includes(origin) && !['localhost', '127.0.0.1', '[::1]'].includes(new URL(origin).hostname))
-        throw new Error('--auth-url / VIGILBASE_AUTH_URL must identify a registered issuer or explicit loopback development origin.');
+    const origin = parseOrigin(raw, IDENTITY_OPTION);
+    if (origin !== DEFAULT_IDENTITY_ISSUER && origin !== STAGING_IDENTITY_ISSUER && !isIdentityLoopback(origin)) {
+        throw new Error(`${IDENTITY_OPTION} must be ${DEFAULT_IDENTITY_ISSUER}, ${STAGING_IDENTITY_ISSUER} or a loopback development origin.`);
+    }
+    return origin;
+}
+/**
+ * The one Identity issuer this configuration trusts: --auth-url / VIGILBASE_AUTH_URL
+ * when set, otherwise production. Staging is trusted only when configured explicitly.
+ * Validated here too because library callers may construct config objects.
+ */
+export function trustedIdentityIssuer(config) {
+    if (!config.identityBaseUrl)
+        return DEFAULT_IDENTITY_ISSUER;
+    const origin = resolveIdentityBaseUrl(config.identityBaseUrl);
+    if (isIdentityLoopback(origin) && !isIdentityLoopback(validateOneOrigin(config.oneBaseUrl))) {
+        throw new Error(`${IDENTITY_OPTION} can be a loopback origin only when --one-url / VIGILBASE_ONE_URL is loopback too.`);
+    }
     return origin;
 }
 export function resolveClientId(explicit) {
@@ -55,17 +77,23 @@ export function resolveClientId(explicit) {
         process.env.VIGILBASE_CLIENT_ID?.trim() ||
         DEFAULT_CLIENT_ID);
 }
-export function resolveConfigDir(explicit, env = process.env) {
+/**
+ * VIGILBASE_CONFIG_DIR (or `explicit`), else $XDG_CONFIG_HOME/vigilbase, else ~/.config/vigilbase. A relative
+ * XDG_CONFIG_HOME is ignored, as the XDG Base Directory spec says; a relative custom directory is returned as is.
+ */
+function configDirFromEnvironment(explicit, env) {
     const custom = explicit?.trim() || env.VIGILBASE_CONFIG_DIR?.trim();
-    const xdg = env.XDG_CONFIG_HOME?.trim();
-    if ((custom && !isAbsolute(custom)) || (xdg && !isAbsolute(xdg))) {
-        throw new Error('Custom config directories and XDG_CONFIG_HOME must be absolute paths.');
-    }
     if (custom)
         return custom;
-    if (xdg)
-        return join(xdg, 'vigilbase');
-    return join(homedir(), '.config', 'vigilbase');
+    const xdg = env.XDG_CONFIG_HOME?.trim();
+    return xdg && isAbsolute(xdg) ? join(xdg, 'vigilbase') : join(homedir(), '.config', 'vigilbase');
+}
+/** The config directory, which must be absolute. */
+export function resolveConfigDir(explicit, env = process.env) {
+    const configDir = configDirFromEnvironment(explicit, env);
+    if (!isAbsolute(configDir))
+        throw new Error('VIGILBASE_CONFIG_DIR must be an absolute path.');
+    return configDir;
 }
 export function createConfig(options) {
     const publicBaseUrl = resolvePublicBaseUrl(options?.publicBaseUrl ?? options?.baseUrl);
@@ -80,7 +108,7 @@ export function createConfig(options) {
         oneBaseUrl: resolveOneBaseUrl(options?.oneBaseUrl),
         ...(options?.identityBaseUrl || process.env.VIGILBASE_AUTH_URL ? { identityBaseUrl: resolveIdentityBaseUrl(options?.identityBaseUrl || process.env.VIGILBASE_AUTH_URL) } : {}),
         clientId: resolveClientId(options?.clientId),
-        configDir: resolveConfigDir(options?.configDir),
+        configDir: configDirFromEnvironment(options?.configDir, process.env),
         userAgent: `@vigilbase/cli/${CLI_VERSION} (+https://vigilbase.com; node/${process.version})`,
         timeoutMs,
     };
@@ -112,4 +140,3 @@ export function createLocalCommandConfig(timeoutMs) {
 export function resolveBaseUrl(explicit) {
     return resolvePublicBaseUrl(explicit);
 }
-//# sourceMappingURL=config.js.map

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,
@@ -294,7 +306,7 @@ export function formatError(error, mode, writer) {
         }
         // CLI-authored remediation (never server text); bounded and sanitised like any output.
         if ('hint' in error && typeof error.hint === 'string') {
-            const hint = sanitizeTerminal(error.hint).replace(/\s+/g, ' ').trim().slice(0, 300);
+            const hint = singleLine(error.hint);
             if (hint)
                 payload.hint = hint;
         }
@@ -303,7 +315,7 @@ export function formatError(error, mode, writer) {
         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`);
     }
@@ -311,4 +323,3 @@ export function formatError(error, mode, writer) {
         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\nOn this machine (no login)\n  cloudflare-checkup           Run the Cloudflare Checkup on this machine in one\n                               command (alias: local cloudflare-checkup)\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  --auth-url <origin>  Explicit registered Identity or loopback development issuer\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

@@ -3,6 +3,24 @@ 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)
@@ -28,23 +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
-  --auth-url <origin>  Explicit registered Identity or loopback development issuer
-  --client-id <id>              Device authorization client ID
+${GLOBAL_OPTIONS}
 
 Use vigilbase <command> --help for command options.
 
@@ -76,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]
 
@@ -122,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,13 +70,40 @@ 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.
         // 'manual' is honoured because it surfaces the 3xx without following it.
@@ -93,6 +120,7 @@ export async function requestText(config, url, init = {}) {
     }
     finally {
         clearTimeout(timer);
+        dispose();
     }
 }
 export function parseJsonResponse(response, text) {
@@ -106,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

@@ -47,6 +47,8 @@ export declare class VigilbaseOneClient {
     private readonly config;
     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. */
@@ -89,4 +91,3 @@ export declare class VigilbaseOneClient {
     executeTool(toolName: string, target: string): Promise<OneToolExecuteResponse>;
 }
 export {};
-//# sourceMappingURL=one-client.d.ts.map