@vigilbase/cli 0.2.2 → 0.2.4

package/dist/lib/format.js

@@ -1,7 +1,18 @@
 import { stripVTControlCharacters } from 'node:util';
-/** Untrusted API data must never become terminal control sequences or bidi overrides. */
+import { LOCAL_ERROR_CODES } from '../local/cloudflare-checkup/errors.js';
+/** A scan that ended without a result: com's copy (apps/com/lib/tools/execute-internal-scan.ts). */
+export const SCAN_FAILED_MESSAGE = "The scan couldn't be completed. Try again later.";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Terminal controls, bidi overrides, and invisible characters an agent reads but a person can't
+ * see: zero-width characters, word joiners, the BOM, line separators and tag characters.
+ */
+const TERMINAL_UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu;
+/** The same, less the C0 controls JSON.stringify already escapes. */
+const JSON_UNSAFE = /[\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu;
+/** Untrusted API data must never become terminal control sequences, bidi overrides or invisible text. */
 export function sanitizeTerminal(value) {
-    return stripVTControlCharacters(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '');
+    return stripVTControlCharacters(value).replace(TERMINAL_UNSAFE, '');
 }
 /** One sanitised line, cut to `maxLength` characters with an ellipsis. */
 export function singleLine(value, maxLength = 300) {
@@ -22,7 +33,7 @@ export function createWriter(stdout = process.stdout, stderr = process.stderr) {
 }
 export function printJson(writer, value) {
     // Keep JSON lossless while preventing literal terminal/bidi controls in rendered output.
-    writer.stdout(JSON.stringify(value, null, 2).replace(/[\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`));
+    writer.stdout(JSON.stringify(value, null, 2).replace(JSON_UNSAFE, (char) => [...Array(char.length).keys()].map((index) => `\\u${char.charCodeAt(index).toString(16).padStart(4, '0')}`).join('')));
 }
 function asRecord(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -153,6 +164,9 @@ function collectFindings(result) {
                 if (!header)
                     continue;
                 const status = typeof header.status === 'string' ? header.status : '';
+                // An absent header the scanner graded good (X-XSS-Protection) is not a finding.
+                if (status === 'good')
+                    continue;
                 if (status !== 'missing' && status !== 'misconfigured' && header.present !== false) {
                     continue;
                 }
@@ -188,30 +202,49 @@ function collectFindings(result) {
     return findings;
 }
 const MAX_FINDING_LINES = 12;
+/** The shareable report link, only when it is a plain https://vigilbase.com URL. */
+function reportUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' || url.hostname !== 'vigilbase.com' || url.port || url.username || url.password)
+        return null;
+    return url.href;
+}
 /** Compact human lines for a scan result (no UI/skill links, no summary dump). */
 function summarizeResultCompact(result) {
     if (!result)
         return [];
+    // Server text never starts a line of its own: each message line is indented like the rest.
     const lines = [];
     const message = typeof result.message === 'string' ? result.message : null;
     if (message)
-        lines.push(message);
+        lines.push(...sanitizeTerminal(message).split('\n').map((line) => line.trim()).filter(Boolean));
     const counts = summarizeCounts(result);
     if (counts)
         lines.push(counts);
     const findings = collectFindings(result);
     for (const finding of findings.slice(0, MAX_FINDING_LINES)) {
-        const sev = finding.severity ? ` ${finding.severity}` : '';
+        const sev = finding.severity ? ` ${singleLine(finding.severity, 20)}` : '';
         if (finding.recommendation) {
-            lines.push(`✗${sev}  ${finding.title} — ${finding.recommendation}`);
+            lines.push(`✗${sev}  ${singleLine(finding.title)} — ${singleLine(finding.recommendation)}`);
         }
         else {
-            lines.push(`✗${sev}  ${finding.title}`);
+            lines.push(`✗${sev}  ${singleLine(finding.title)}`);
         }
     }
     if (findings.length > MAX_FINDING_LINES) {
         lines.push(`… +${findings.length - MAX_FINDING_LINES} more (use --json)`);
     }
+    const report = reportUrl(result.shareableUrl);
+    if (report)
+        lines.push(`Report: ${report}`);
     return lines;
 }
 export function formatToolsList(catalog, mode, writer, options) {
@@ -219,11 +252,12 @@ export function formatToolsList(catalog, mode, writer, options) {
         printJson(writer, catalog);
         return;
     }
-    const publicNames = catalog.tools.map((tool) => tool.toolName).join('  ');
+    // Catalog names are the server's: a newline in one must not start a line of its own.
+    const publicNames = catalog.tools.map((tool) => singleLine(tool.toolName, 100)).join('  ');
     writer.stdout(`public     ${publicNames || '(none)'}`);
     const authRequired = options?.authRequiredTools ?? options?.sensitiveTools ?? [];
     if (authRequired.length) {
-        writer.stdout(`auth-req   ${authRequired.join('  ')}`);
+        writer.stdout(`auth-req   ${authRequired.map((name) => singleLine(name, 100)).join('  ')}`);
     }
     if (typeof options?.isAuthenticated === 'boolean') {
         writer.stdout(options.isAuthenticated ? 'auth       signed in' : 'auth       signed out');
@@ -231,49 +265,79 @@ export function formatToolsList(catalog, mode, writer, options) {
 }
 export function formatToolDescription(tool, mode, writer, skillMarkdown) {
     if (mode === 'json') {
-        printJson(writer, { ...tool, skillMarkdown: skillMarkdown ?? null });
+        printJson(writer, { success: true, ...tool, skillMarkdown: skillMarkdown ?? null });
         return;
     }
-    writer.stdout(`${tool.toolName}  ${tool.name}`);
-    const blurb = tool.description.length > 100
-        ? `${tool.description.slice(0, 97).trimEnd()}…`
-        : tool.description;
-    writer.stdout(blurb);
-    writer.stdout(`vigilbase run ${tool.toolName} <target>`);
+    // Catalog text is the server's: each field stays on its own line.
+    writer.stdout(`${singleLine(tool.toolName, 100)}  ${singleLine(tool.name)}`);
+    writer.stdout(singleLine(tool.description, 2000));
+    if (tool.targetDescription)
+        writer.stdout(`Target: ${singleLine(tool.targetDescription)}`);
+    writer.stdout(`vigilbase run ${singleLine(tool.toolName, 100)} <target>`);
     if (skillMarkdown) {
         writer.stdout();
         writer.stdout(skillMarkdown.trimEnd());
     }
 }
+/**
+ * Why a scan failed, or null when it has a result. A scan the scanner could not grade has
+ * `status: "error"` with a message and no grade: One and vigilbase.com both send it as a 422,
+ * which the clients turn into a `scan_unassessed` result.
+ */
+function scanFailure(result) {
+    if (result.success && result.result?.status !== 'error')
+        return null;
+    const message = result.result?.status === 'error'
+        ? result.result.message
+        : result.success ? undefined : typeof result.error === 'string' ? result.error : result.error?.message;
+    // Vigilbase's scanner wrote it, but it is bounded like any server reason.
+    return (typeof message === 'string' && singleLine(message)) || SCAN_FAILED_MESSAGE;
+}
+/** Whether a scan produced a result; the exit code follows it. */
+export function isSuccessfulScan(result) {
+    return scanFailure(result) === null;
+}
 export function formatExecuteResult(result, mode, writer) {
+    const failure = scanFailure(result);
     if (mode === 'json') {
-        printJson(writer, result);
+        // A scan without a result fails in JSON as in the exit code.
+        // A failed scan has no grade, whatever placeholder the scanner used.
+        printJson(writer, failure === null ? result : { ...result, success: false, error: failure, grade: null, gradeScore: null });
         return;
     }
-    const tool = result.toolName ?? 'tool';
-    const target = result.target ?? '';
-    const grade = result.grade != null
-        ? `${result.grade}${result.gradeScore != null ? ` ${result.gradeScore}` : ''}`
+    const tool = singleLine(result.toolName ?? 'tool', 100);
+    const target = singleLine(result.target ?? '', 2100);
+    const gradeLetter = result.grade != null ? singleLine(String(result.grade), 10) : '';
+    const grade = failure === null && result.grade != null
+        ? `${gradeLetter}${result.gradeScore != null ? ` ${singleLine(String(result.gradeScore), 10)}` : ''}`
         : 'n/a';
-    const head = result.success
-        ? `✓ ${tool} · ${target} · ${grade}`
-        : `✗ ${tool} · ${target} · ${grade}`;
-    if (result.success)
-        writer.stdout(head);
-    else
-        writer.stderr(head);
-    const error = typeof result.error === 'string' ? result.error : result.error?.message;
-    if (error) {
-        writer.stderr(`  ${error}`);
+    if (failure !== null) {
+        writer.stderr(`✗ ${tool} · ${target} · ${grade}`);
+        writer.stderr(`  ${failure}`);
+        return;
     }
+    // A graded scan exits 0 whatever the grade; only a secure one without an F gets the ✓.
+    const isClean = result.result?.status === 'secure' && gradeLetter.toUpperCase() !== 'F';
+    writer.stdout(`${isClean ? '✓' : '•'} ${tool} · ${target} · ${grade}`);
     for (const line of summarizeResultCompact(result.result)) {
         writer.stdout(`  ${line}`);
     }
 }
+/** Issues of a ZodError, also one from another copy of zod. */
+function zodErrorIssues(error) {
+    if (!(error instanceof Error) || error.name !== 'ZodError' || !('issues' in error) || !Array.isArray(error.issues))
+        return null;
+    return error.issues;
+}
 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.
+    const zodIssues = zodErrorIssues(error);
+    // A ZodError's message is its serialised issue list; show the issue messages instead.
+    if (zodIssues)
+        message = zodIssues.map((issue) => `${issue.path?.length ? `${issue.path.map(String).join('.')}: ` : ''}${singleLine(String(issue.message))}`).join(' ') || 'Invalid argument.';
+    // Server bodies can contain credentials, customer data, or arbitrary error text, so an error that
+    // carries one shows only text the CLI wrote, or the reason the public client accepted.
     if (error && typeof error === 'object' && 'body' in error && error.body != null && 'status' in error && typeof error.status === 'number') {
         if ('code' in error && error.code === 'FLAREHAWK_VIEW_AS_REQUIRED') {
             message = 'Select a customer with --customer-id <customer UUID> for security commands.';
@@ -281,13 +345,16 @@ export function formatError(error, mode, writer) {
         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 isCliAuthored = 'isCliAuthored' in error && error.isCliAuthored === true;
+            message = reason || (isCliAuthored ? message : `Request failed (HTTP ${error.status}).`);
         }
     }
     const payload = {
         success: false,
         error: message,
     };
+    if (zodIssues)
+        payload.code = 'INVALID_ARGUMENT';
     if (error && typeof error === 'object') {
         if ('status' in error && typeof error.status === 'number' &&
             Number.isInteger(error.status) && error.status >= 0 && error.status <= 599) {
@@ -310,14 +377,22 @@ export function formatError(error, mode, writer) {
             if (hint)
                 payload.hint = hint;
         }
+        // The One tool run a failed scan recorded, for `vigilbase runs get`.
+        if ('toolRunId' in error && typeof error.toolRunId === 'string' && UUID.test(error.toolRunId)) {
+            payload.toolRunId = error.toolRunId;
+        }
     }
     if (mode === 'json') {
         printJson(writer, payload);
         return;
     }
-    writer.stderr(`Error: ${message}${reason && typeof payload.code === 'string' ? ` (${payload.code})` : ''}`);
+    // Local checkup codes show as in the terminal UI; invalid-argument messages already name the flag.
+    const isLocalCode = LOCAL_ERROR_CODES.includes(payload.code);
+    writer.stderr(`Error: ${message}${(reason || isLocalCode) && typeof payload.code === 'string' ? ` (${payload.code})` : ''}`);
     if (typeof payload.retryAfterSec === 'number') {
-        writer.stderr(`Retry after ${payload.retryAfterSec}s`);
+        // Quotas reset after up to an hour: minutes read better than thousands of seconds.
+        const seconds = payload.retryAfterSec;
+        writer.stderr(seconds < 120 ? `Retry after ${seconds}s` : `Retry after about ${Math.round(seconds / 60)} minutes`);
     }
     if (typeof payload.hint === 'string') {
         writer.stderr(`Hint: ${payload.hint}`);

package/dist/lib/help.js

@@ -19,6 +19,52 @@ export function isCatalogTool(name) {
 }
 /** Column where descriptions start in the main help: two-space indent, term, at least two spaces. */
 const DESCRIPTION_COLUMN = 31;
+/** Help lines fit an 80-column terminal. */
+const HELP_WIDTH = 80;
+/**
+ * Where a wrapped line continues: under the description of a row, under the text of a usage
+ * line, at the indent of a note, or at the margin for prose.
+ */
+function continuationIndent(line) {
+    const described = /^ {2}\S.*? {2,}(?=\S)/.exec(line);
+    if (described)
+        return described[0].length;
+    if (line.startsWith('Usage: '))
+        return 'Usage: '.length;
+    const indent = /^ */.exec(line)[0].length;
+    return indent === 0 ? 0 : Math.max(indent, 4);
+}
+/** Where to cut a line at most `width` long: before an option group, else at a space, else after a |. */
+function breakPoint(line, from, width) {
+    const head = line.slice(0, width + 1);
+    const bracket = head.lastIndexOf(' [');
+    if (bracket > from + (width - from) / 2)
+        return { cut: bracket, skip: 1 };
+    const space = head.lastIndexOf(' ');
+    if (space > from)
+        return { cut: space, skip: 1 };
+    const bar = line.slice(0, width).lastIndexOf('|');
+    return bar > from ? { cut: bar + 1, skip: 0 } : null;
+}
+/** Wraps help lines longer than HELP_WIDTH, keeping descriptions aligned. */
+function wrapHelp(text) {
+    return text.split('\n').flatMap((line) => {
+        const lines = [];
+        const pad = ' '.repeat(continuationIndent(line));
+        let rest = line;
+        // Past the first cut, only cut after the indent, so every line is shorter than the last.
+        let from = /^ */.exec(line)[0].length;
+        while (rest.length > HELP_WIDTH) {
+            const at = breakPoint(rest, from, HELP_WIDTH);
+            if (!at)
+                break;
+            lines.push(rest.slice(0, at.cut).trimEnd());
+            rest = `${pad}${rest.slice(at.cut + at.skip).trimStart()}`;
+            from = pad.length;
+        }
+        return [...lines, rest];
+    }).join('\n');
+}
 /** Two-column help rows whose descriptions all start at DESCRIPTION_COLUMN. */
 function helpRows(rows) {
     return rows
@@ -35,7 +81,7 @@ const GLOBAL_OPTIONS = helpRows([
     ['--auth-url <origin>', 'Identity issuer (default: auth.vigilbase.com)'],
     ['--client-id <id>', 'Device authorization client ID'],
 ]);
-export const HELP_TEXT = `Usage: vigilbase <command>
+export const HELP_TEXT = wrapHelp(`Usage: vigilbase <command>
 
 Public tools (no login)
   list                         List available tools
@@ -63,7 +109,7 @@ Account (login required)
   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
+  customers <command>          Customers, billing, reports, investigations
   orgs <command>               Organizations, members, permission roles
   monitoring <command>         Health, probes, metrics, customer targets
   support tickets              Support ticket history
@@ -81,7 +127,7 @@ Examples
   vigilbase runs list --json
   vigilbase cf zones
   vigilbase security incidents --severity high
-`;
+`);
 /** How to run a catalog tool: `help <tool>` and `<tool> --help`, since tools run as `run <tool> <target>`. */
 function helpForTool(tool) {
     if (isPublicTool(tool)) {
@@ -100,6 +146,10 @@ Details: vigilbase describe ${tool}`;
 }
 export const HELP_USAGE = 'Usage: vigilbase help [<command> | <tool>]';
 export function helpForCommand(command) {
+    const help = commandHelp(command);
+    return help === null ? null : wrapHelp(help);
+}
+function commandHelp(command) {
     switch (command) {
         case 'help':
             return `${HELP_USAGE}
@@ -127,13 +177,14 @@ Run vigilbase help <tool> for a tool's usage.`;
 
 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.`;
+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]
 
 Requires \`vigilbase login\`.
-  account invites create --email user@example.com [--role member] --confirm`;
+  account invites create <email>|--email <email> [--role <role>] --confirm`;
         case 'runhistory':
         case 'runs':
             return `Usage: vigilbase runs [list|get <UUID>] [--json]

package/dist/lib/network.d.ts

@@ -1,10 +1,14 @@
 import type { CliConfig } from './config.js';
 export declare class NetworkError extends Error {
     readonly code: string;
+    readonly hint?: string | undefined;
     readonly status = 0;
-    constructor(message: string, code: string, cause?: unknown);
+    /** `hint` is printed after the error; doctor, which is the connectivity check, leaves it out. */
+    constructor(message: string, code: string, cause?: unknown, hint?: string | undefined);
 }
 export declare function networkError(error: unknown, url: string, timeoutMs: number, timedOut: boolean): NetworkError;
+/** The option that sets each service's origin, which a caller names for the redirect message. */
+export type OriginOption = '--base-url' | '--one-url' | '--auth-url';
 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>;
@@ -18,8 +22,13 @@ 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<{
+/**
+ * Keep the timeout active until the complete response body has been read. `option` names the option that sets the
+ * service's origin, for the message when it redirects.
+ */
+export declare function requestText(config: CliConfig, url: string, { option, ...init }?: RequestInit & {
+    option?: OriginOption;
+}): Promise<{
     response: Response;
     text: string;
 }>;

package/dist/lib/network.js

@@ -1,9 +1,13 @@
+import { isSystemTrustConfigured } from './system-trust.js';
 export class NetworkError extends Error {
     code;
+    hint;
     status = 0;
-    constructor(message, code, cause) {
+    /** `hint` is printed after the error; doctor, which is the connectivity check, leaves it out. */
+    constructor(message, code, cause, hint) {
         super(message, { cause });
         this.code = code;
+        this.hint = hint;
         this.name = 'NetworkError';
     }
 }
@@ -18,21 +22,70 @@ function errorCodes(error, seen = new Set()) {
         ...(Array.isArray(item.errors) ? item.errors.flatMap((e) => errorCodes(e, seen)) : []),
     ];
 }
+/** Messages along the cause chain: undici reports a blocked port or a refused redirect only by message. */
+function causeMessages(error, seen = new Set()) {
+    if (!error || typeof error !== 'object' || seen.has(error))
+        return [];
+    seen.add(error);
+    const item = error;
+    return [...(typeof item.message === 'string' ? [item.message] : []), ...causeMessages(item.cause, seen)];
+}
 export function networkError(error, url, timeoutMs, timedOut) {
     // Never echo query strings, URL credentials, request bodies, or raw causes.
-    const endpoint = new URL(url).origin;
+    const { origin: endpoint, port } = new URL(url);
     const codes = errorCodes(error);
     const code = codes[0] ?? 'NETWORK_ERROR';
+    const messages = causeMessages(error);
     if (timedOut || codes.some((c) => /TIMEOUT|ETIMEDOUT/.test(c))) {
         return new NetworkError(`Request to ${endpoint} timed out after ${timeoutMs}ms. Check your connection or increase --timeout.`, 'TIMEOUT', error);
     }
+    if (messages.includes('bad port')) {
+        return new NetworkError(`Node's fetch refuses port ${port} of ${endpoint} (a port the Fetch standard blocks). Use another port.`, 'BLOCKED_PORT', error);
+    }
+    if (messages.includes('unexpected redirect')) {
+        return new NetworkError(`${endpoint} answered with a redirect, which the CLI does not follow.`, 'UNEXPECTED_REDIRECT', error);
+    }
     if (codes.some((c) => /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/.test(c))) {
-        return new NetworkError(`TLS certificate verification failed for ${endpoint} (${code}). Use Node 22.19+ or Node 24.5+ for automatic system certificate trust. If your organization uses a private CA, configure NODE_EXTRA_CA_CERTS with its trusted PEM certificate.`, code, error);
+        // Without system trust (older Node), the OS certificate store isn't used at all.
+        const upgrade = isSystemTrustConfigured() ? '' : ' Use Node 22.19+ or Node 24.5+ for automatic system certificate trust.';
+        return new NetworkError(`TLS certificate verification failed for ${endpoint} (${code}).${upgrade} If your organization uses a private CA, configure NODE_EXTRA_CA_CERTS with its trusted PEM certificate.`, code, error);
     }
     if (codes.some((c) => c === 'ENOTFOUND' || c === 'EAI_AGAIN')) {
         return new NetworkError(`Cannot resolve ${endpoint} (${code}). Check DNS, your VPN, and the configured API URL.`, code, error);
     }
-    return new NetworkError(`Cannot connect to ${endpoint} (${code}). Check your connection, VPN, proxy settings, and API URL. Run \`vigilbase doctor\` for connectivity checks.`, code, error);
+    return new NetworkError(`Cannot connect to ${endpoint} (${code}). Check your connection, VPN, proxy settings, and API URL.`, code, error, 'Run `vigilbase doctor` for connectivity checks.');
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** The option that sets this origin, when the caller didn't name it. */
+function optionFor(config, origin) {
+    if (origin === config.publicBaseUrl)
+        return '--base-url';
+    if (origin === config.oneBaseUrl)
+        return '--one-url';
+    if (origin === config.identityBaseUrl)
+        return '--auth-url';
+    return undefined;
+}
+/** A redirect the CLI refuses, naming only the target's origin: its path and query may carry tokens. */
+function redirectError(config, url, response, named) {
+    const { origin } = new URL(url);
+    let target;
+    try {
+        const location = new URL(response.headers.get('location') ?? '', url);
+        if ((location.protocol === 'https:' || location.protocol === 'http:') && location.origin !== origin)
+            target = location.origin;
+    }
+    catch {
+        // An unparsable Location: say only that it redirected.
+    }
+    // Public, One and Identity may share an origin, so the caller's service decides the option.
+    const option = named ?? optionFor(config, origin);
+    const message = !target
+        ? `${origin} answered with a redirect (HTTP ${response.status}), which the CLI does not follow.`
+        : option
+            ? `${origin} redirected (HTTP ${response.status}) to ${target}. Set ${option} to that origin.`
+            : `${origin} redirected (HTTP ${response.status}) to ${target}, which the CLI does not follow.`;
+    return new NetworkError(message, 'UNEXPECTED_REDIRECT');
 }
 export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 /** Bound decoded bytes even when Content-Length is absent, compressed, or dishonest. */
@@ -97,22 +150,33 @@ export function anySignal(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 = {}) {
+/**
+ * Keep the timeout active until the complete response body has been read. `option` names the option that sets the
+ * service's origin, for the message when it redirects.
+ */
+export async function requestText(config, url, { option, ...init } = {}) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), config.timeoutMs);
     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.
-        const response = await fetch(url, { ...init, signal, redirect: init.redirect === 'manual' ? 'manual' : 'error' });
+        // Never follow redirects: they could carry token-bearing POST bodies (or credentials) elsewhere.
+        // 'manual' surfaces the 3xx, which is refused here unless the caller asked for it.
+        const response = await fetch(url, { ...init, signal, redirect: 'manual' });
+        if (init.redirect !== 'manual' && REDIRECT_STATUSES.has(response.status) && response.headers.has('location')) {
+            await response.body?.cancel().catch(() => undefined);
+            throw redirectError(config, url, response, option);
+        }
         return { response, text: await readBoundedBody(response, signal) };
     }
     catch (error) {
         if (error instanceof NetworkError)
             throw error;
+        // Fetch refuses a header value (a token with a newline) before sending anything. Its message holds the value.
+        if (error instanceof TypeError && error.cause === undefined && /header/i.test(error.message)) {
+            throw Object.assign(new Error('A request header contains characters HTTP does not allow, so nothing was sent.'), { code: 'INVALID_ARGUMENT' });
+        }
         if (init.signal?.aborted) {
             throw new NetworkError('Request cancelled.', 'CANCELLED', error);
         }

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

@@ -7,6 +7,8 @@ import type { CliConfig } from './config.js';
 export type OneToolExecuteResponse = {
     success: boolean;
     error?: string;
+    /** `scan_unassessed`: the scanner ran but could not assess the target. */
+    code?: string;
     data?: {
         toolRunId?: string;
         status?: string;