@vigilbase/cli/dist/lib/one-error-hints.js

Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.

/**
 * CLI-authored hints for One errors the CLI recognises. They are chosen only
 * from the request (method, route, whether a customer was selected), the HTTP
 * status and One's own error codes. One's free-text messages are never shown:
 * they can describe its configuration.
 */
export const STAFF_CUSTOMER_SCOPE_HINT = 'Vigilbase staff: add --customer-id <uuid>.';
export const PERSONAL_SETTINGS_HINT = 'Personal settings belong to each user, so View-as (--customer-id) cannot read them.';
export const BROWSER_SESSION_HINT = 'Invitations need a One browser session: manage them at https://one.vigilbase.com.';
/** One's security boundary codes that already explain a 403 (apps/one/src/lib/flarehawk/access.ts). */
const SECURITY_ACCESS_CODES = new Set([
    'FLAREHAWK_CUSTOMER_ACCESS_DENIED',
    'FLAREHAWK_ROLE_UNSUPPORTED',
    'FLAREHAWK_ROLE_INSUFFICIENT',
    'FLAREHAWK_ORGANIZATION_REQUIRED',
    'FLAREHAWK_VIEW_AS_REQUIRED',
]);
const RULES = [
    // Staff sessions must name the customer; One answers 400 without one.
    { method: 'GET', route: /^\/api\/support\/tickets$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
    { method: 'GET', route: /^\/api\/services\/cloudflare\/checkups$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
    { method: 'POST', route: /^\/api\/services\/cloudflare\/checkups\/start$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
    { method: 'GET', route: /^\/api\/services\/cloudflare\/workspace(?:\/[a-z-]+)?$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
    // Personal security settings are per user; a View-as read is refused.
    {
        method: 'GET',
        route: /^\/api\/flarehawk\/(?:settings\/(?:lifecycle-emails|broadcast-emails)|integrations\/grants|notifications\/preferences)$/u,
        status: 403,
        hasCustomerScope: true,
        hint: PERSONAL_SETTINGS_HINT,
        excludedCodes: SECURITY_ACCESS_CODES,
    },
    // Identity's management API accepts only One browser sessions, so CLI tokens can't read or send invitations.
    { method: 'GET', route: /^\/api\/auth\/orgs\/invitations$/u, status: 403, hasCustomerScope: false, hint: BROWSER_SESSION_HINT, code: 'browser_session_required' },
    { method: 'POST', route: /^\/api\/auth\/orgs\/invite$/u, status: 403, hasCustomerScope: false, hint: BROWSER_SESSION_HINT, code: 'browser_session_required' },
];
export function oneErrorHint(context) {
    const [pathname = '', query = ''] = context.path.split('?', 2);
    const hasCustomerScope = context.hasCustomerScope ?? new URLSearchParams(query).has('customerId');
    const method = context.method.toUpperCase();
    return RULES.find((rule) => rule.method === method &&
        rule.status === context.status &&
        rule.hasCustomerScope === hasCustomerScope &&
        rule.route.test(pathname) &&
        (rule.code === undefined || rule.code === context.code) &&
        !(context.code !== undefined && rule.excludedCodes?.has(context.code)))?.hint;
}