@vigilbase/cli 0.1.4 → 0.2.1

package/dist/local/cloudflare-checkup/cf/allowlist.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The frozen allowlist of read-only cf command templates (spec §F4).
+ *
+ * argv only ever comes from these templates. Interpolated values are
+ * re-validated (32-hex IDs, the 19 zone setting IDs, integer pages), every API
+ * template carries `--quiet` and profile mode appends `--profile <p>`. No
+ * template has a confirmation-skipping, local-mode or request-body flag;
+ * `run-cf.ts` refuses such argv at spawn time as a second guard. `per_page`
+ * values equal the scanner's, so page boundaries and API order match live runs.
+ *
+ * The offline preflight runs each template with `--dry-run` and placeholder
+ * IDs. In cf beta.13 the dry-run object is a literal emitted by each generated
+ * handler, so the preflight is a command-name → API-path mapping check only:
+ * it detects renamed or remapped commands but does not prove the real request
+ * target. Scrubbing base-URL variables from the child env is that control.
+ */
+import { type CollectableKind, type ZoneSettingId } from '../contract.js';
+export declare const DEFAULT_PROFILE = "vigilbase-checkup";
+/** Template IDs: every collectable kind plus account selection (`accounts list`). */
+export type TemplateId = CollectableKind | 'account_selection';
+export type Paging = {
+    kind: 'single';
+}
+/** `--page N` until an empty page; `maxPages` data pages. */
+ | {
+    kind: 'pages';
+    perPage: number;
+    maxPages: number;
+}
+/** Cursor-only list printed without its cursor: one call, `possibly_truncated` at the threshold. */
+ | {
+    kind: 'one_call';
+    perPage: number;
+};
+export type TemplateIds = {
+    accountId?: string;
+    zoneId?: string;
+    rulesetId?: string;
+    settingId?: ZoneSettingId;
+    page?: number;
+};
+type TemplateSpec = {
+    /** Command words, then fixed arguments; `{Z}`, `{R}`, `{S}` and `{N}` are interpolated. */
+    args: readonly string[];
+    /** Expected dry-run path below `https://api.cloudflare.com/client/v4`; `{A}` is the account. */
+    path: string;
+    /** Expected dry-run query; `{A}`/`{N}` are interpolated. Absent when cf prints none. */
+    query?: Readonly<Record<string, string | number | boolean>>;
+    paging: Paging;
+    output: 'array' | 'object';
+    scope: 'account' | 'zone' | 'setting' | 'ruleset';
+};
+export declare const TEMPLATES: Readonly<Record<TemplateId, TemplateSpec>>;
+export declare const TEMPLATE_IDS: TemplateId[];
+export type ProfileArgs = {
+    authMode: 'profile' | 'env' | 'default';
+    profile: string;
+};
+export declare function validateProfileName(profile: string): string;
+/** The exact argv for one call. Throws (a programming error) on any invalid interpolation. */
+export declare function buildArgv(id: TemplateId, ids: TemplateIds, auth: ProfileArgs, options?: {
+    dryRun?: boolean;
+}): string[];
+export type PreflightCheck = {
+    id: TemplateId;
+    settingId?: ZoneSettingId;
+    argv: string[];
+    expectedPath: string;
+    expectedQuery?: Record<string, unknown>;
+};
+/** One dry-run per template (one per zone setting), with placeholder IDs. */
+export declare function preflightChecks(auth: ProfileArgs, only?: readonly TemplateId[]): PreflightCheck[];
+export declare const PREFLIGHT_ACCOUNT_ID: string;
+/** True when a dry-run object maps to `GET` and exactly the expected path and query. */
+export declare function dryRunMatches(stdout: string, check: PreflightCheck): boolean;
+/** Kinds whose mismatch aborts collection with CF_ALLOWLIST_MISMATCH. */
+export declare const CRITICAL_TEMPLATES: readonly TemplateId[];
+/** Display form of every template, with placeholders, for `collect --dry-run`. */
+export declare function templateDisplay(id: TemplateId, auth: ProfileArgs): string[];
+/** The other cf argv the CLI uses: version, the serial whoami, and the login and logout commands. */
+export declare function versionArgv(): string[];
+export declare function whoamiArgv(auth: ProfileArgs): string[];
+/** `cf auth create <p> [--no-browser] --scopes …` (re-authenticates an existing profile). */
+export declare function loginArgv(profile: string, scopes: readonly string[], options: {
+    noBrowser: boolean;
+}): string[];
+/**
+ * `cf auth delete <p>` (logout). In cf 1.0.0-beta.13 it takes only the name:
+ * it refuses `--profile` and a shell API token, fails when the profile does
+ * not exist, removes the profile's directory bindings, logs the profile out
+ * and deletes its stored credentials. It has no confirmation prompt.
+ */
+export declare function logoutArgv(profile: string): string[];
+export {};

package/dist/local/cloudflare-checkup/cf/allowlist.js

@@ -0,0 +1,183 @@
+/**
+ * The frozen allowlist of read-only cf command templates (spec §F4).
+ *
+ * argv only ever comes from these templates. Interpolated values are
+ * re-validated (32-hex IDs, the 19 zone setting IDs, integer pages), every API
+ * template carries `--quiet` and profile mode appends `--profile <p>`. No
+ * template has a confirmation-skipping, local-mode or request-body flag;
+ * `run-cf.ts` refuses such argv at spawn time as a second guard. `per_page`
+ * values equal the scanner's, so page boundaries and API order match live runs.
+ *
+ * The offline preflight runs each template with `--dry-run` and placeholder
+ * IDs. In cf beta.13 the dry-run object is a literal emitted by each generated
+ * handler, so the preflight is a command-name → API-path mapping check only:
+ * it detects renamed or remapped commands but does not prove the real request
+ * target. Scrubbing base-URL variables from the child env is that control.
+ */
+import { ZONE_SETTING_IDS } from '../contract.js';
+const HEX32 = /^[0-9a-f]{32}$/;
+const PLACEHOLDER_ID = '0'.repeat(32);
+// Spec: ^[A-Za-z0-9_-]{1,64}$, minus a leading '-' so a name can never be parsed by cf as a flag.
+const PROFILE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
+export const DEFAULT_PROFILE = 'vigilbase-checkup';
+const pages = (perPage, maxPages = 50) => ({ kind: 'pages', perPage, maxPages });
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+export const TEMPLATES = deepFreeze({
+    account_selection: { args: ['accounts', 'list', '--per-page', '50', '--page', '{N}'], path: '/accounts', query: { page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    account: { args: ['accounts', 'get'], path: '/accounts/{A}', paging: { kind: 'single' }, output: 'object', scope: 'account' },
+    zones: { args: ['zones', 'list', '--account-id', '{A}', '--per-page', '50', '--page', '{N}'], path: '/zones', query: { 'account.id': '{A}', page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    account_members: { args: ['accounts', 'members', 'list', '--per-page', '50', '--page', '{N}'], path: '/accounts/{A}/members', query: { page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    account_rulesets: { args: ['rulesets', 'list', '--per-page', '100'], path: '/accounts/{A}/rulesets', query: { per_page: 100 }, paging: { kind: 'one_call', perPage: 100 }, output: 'array', scope: 'account' },
+    account_access_rules: { args: ['firewall', 'access-rules', 'list', '--per-page', '50', '--page', '{N}'], path: '/accounts/{A}/firewall/access_rules/rules', query: { page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    access_apps: { args: ['zero-trust', 'access', 'applications', 'list', '--per-page', '50', '--page', '{N}'], path: '/accounts/{A}/access/apps', query: { page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    access_identity_providers: { args: ['zero-trust', 'identity-providers', 'list', '--per-page', '50', '--page', '{N}'], path: '/accounts/{A}/access/identity_providers', query: { page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    access_service_tokens: { args: ['zero-trust', 'access', 'service-tokens', 'list', '--per-page', '50', '--page', '{N}'], path: '/accounts/{A}/access/service_tokens', query: { page: '{N}', per_page: 50 }, paging: pages(50), output: 'array', scope: 'account' },
+    gateway_rules: { args: ['zero-trust', 'gateway', 'rules', 'list'], path: '/accounts/{A}/gateway/rules', query: {}, paging: { kind: 'single' }, output: 'array', scope: 'account' },
+    gateway_locations: { args: ['zero-trust', 'gateway', 'locations', 'list'], path: '/accounts/{A}/gateway/locations', query: {}, paging: { kind: 'single' }, output: 'array', scope: 'account' },
+    // Substitute for GET /cfd_tunnel (no cf command in beta.13); response equivalence is launch gate 1.
+    cfd_tunnels: { args: ['tunnels', 'list', '--tun-types', 'cfd_tunnel', '--is-deleted', 'false', '--per-page', '50', '--page', '{N}'], path: '/accounts/{A}/tunnels', query: { is_deleted: false, tun_types: 'cfd_tunnel', per_page: 50, page: '{N}' }, paging: pages(50), output: 'array', scope: 'account' },
+    zone_setting: { args: ['zones', 'settings', 'get', '{S}', '--zone', '{Z}'], path: '/zones/{Z}/settings/{S}', paging: { kind: 'single' }, output: 'object', scope: 'setting' },
+    zone_dnssec: { args: ['dns', 'dnssec', 'get', '--zone', '{Z}'], path: '/zones/{Z}/dnssec', paging: { kind: 'single' }, output: 'object', scope: 'zone' },
+    zone_dns_records: { args: ['dns', 'records', 'list', '--zone', '{Z}', '--per-page', '100', '--page', '{N}'], path: '/zones/{Z}/dns_records', query: { page: '{N}', per_page: 100 }, paging: pages(100, 100), output: 'array', scope: 'zone' },
+    zone_universal_ssl: { args: ['ssl', 'universal', 'settings', 'get', '--zone', '{Z}'], path: '/zones/{Z}/ssl/universal/settings', paging: { kind: 'single' }, output: 'object', scope: 'zone' },
+    zone_total_tls: { args: ['acm', 'total-tls', 'get', '--zone', '{Z}'], path: '/zones/{Z}/acm/total_tls', paging: { kind: 'single' }, output: 'object', scope: 'zone' },
+    zone_rulesets: { args: ['rulesets', 'list', '--zone', '{Z}', '--per-page', '100'], path: '/zones/{Z}/rulesets', query: { per_page: 100 }, paging: { kind: 'one_call', perPage: 100 }, output: 'array', scope: 'zone' },
+    zone_ruleset: { args: ['rulesets', 'get', '{R}', '--zone', '{Z}'], path: '/zones/{Z}/rulesets/{R}', paging: { kind: 'single' }, output: 'object', scope: 'ruleset' },
+    zone_access_rules: { args: ['firewall', 'access-rules', 'list', '--zone', '{Z}', '--per-page', '100', '--page', '{N}'], path: '/zones/{Z}/firewall/access_rules/rules', query: { page: '{N}', per_page: 100 }, paging: pages(100), output: 'array', scope: 'zone' },
+    zone_page_rules: { args: ['page-rules', 'list', '--zone', '{Z}'], path: '/zones/{Z}/pagerules', query: {}, paging: { kind: 'single' }, output: 'array', scope: 'zone' },
+    zone_bot_management: { args: ['bot-management', 'get', '--zone', '{Z}'], path: '/zones/{Z}/bot_management', paging: { kind: 'single' }, output: 'object', scope: 'zone' },
+    zone_page_shield: { args: ['client-side-security', 'settings', 'get', '--zone', '{Z}'], path: '/zones/{Z}/page_shield', paging: { kind: 'single' }, output: 'object', scope: 'zone' },
+    zone_schema_validation_settings: { args: ['api-security', 'schema-validation', 'settings', 'get', '--zone', '{Z}'], path: '/zones/{Z}/schema_validation/settings', paging: { kind: 'single' }, output: 'object', scope: 'zone' },
+    zone_schema_validation_schemas: { args: ['api-security', 'schema-validation', 'schemas', 'list', '--zone', '{Z}', '--omit-source', '--per-page', '100', '--page', '{N}'], path: '/zones/{Z}/schema_validation/schemas', query: { page: '{N}', per_page: 100, omit_source: true }, paging: pages(100), output: 'array', scope: 'zone' },
+});
+export const TEMPLATE_IDS = Object.keys(TEMPLATES);
+export function validateProfileName(profile) {
+    if (!PROFILE.test(profile))
+        throw new Error('--profile must be 1-64 letters, digits, "_" or "-", and must not start with "-".');
+    return profile;
+}
+function hex(value, label) {
+    if (value === undefined || !HEX32.test(value))
+        throw new Error(`Invalid ${label} for a cf command.`);
+    return value;
+}
+/** The exact argv for one call. Throws (a programming error) on any invalid interpolation. */
+export function buildArgv(id, ids, auth, options = {}) {
+    const spec = TEMPLATES[id];
+    const argv = spec.args.map((arg) => {
+        switch (arg) {
+            case '{Z}': return hex(ids.zoneId, 'zone ID');
+            case '{R}': return hex(ids.rulesetId, 'ruleset ID');
+            // Only `zones list --account-id`; every other template gets the account from CLOUDFLARE_ACCOUNT_ID.
+            case '{A}': return hex(ids.accountId, 'account ID');
+            case '{S}':
+                if (!ids.settingId || !ZONE_SETTING_IDS.includes(ids.settingId))
+                    throw new Error('Invalid zone setting ID for a cf command.');
+                return ids.settingId;
+            case '{N}':
+                if (!Number.isSafeInteger(ids.page) || ids.page < 1 || ids.page > 1000)
+                    throw new Error('Invalid page for a cf command.');
+                return String(ids.page);
+            default: return arg;
+        }
+    });
+    argv.push('--quiet');
+    if (auth.authMode === 'profile')
+        argv.push('--profile', validateProfileName(auth.profile));
+    if (options.dryRun)
+        argv.push('--dry-run');
+    return argv;
+}
+function fill(template, values) {
+    return template.replace(/\{([AZRSN])\}/g, (_m, key) => String(values[key]));
+}
+/** One dry-run per template (one per zone setting), with placeholder IDs. */
+export function preflightChecks(auth, only) {
+    const values = { A: PLACEHOLDER_ID, Z: PLACEHOLDER_ID, R: PLACEHOLDER_ID, S: '', N: 1 };
+    const checks = [];
+    for (const id of only ?? TEMPLATE_IDS) {
+        const spec = TEMPLATES[id];
+        const settings = id === 'zone_setting' ? [...ZONE_SETTING_IDS] : [undefined];
+        for (const settingId of settings) {
+            const filled = { ...values, S: settingId ?? '' };
+            const query = spec.query === undefined ? undefined : Object.fromEntries(Object.entries(spec.query)
+                .map(([key, value]) => [key, typeof value === 'string' ? (value === '{N}' ? 1 : fill(value, filled)) : value]));
+            checks.push({
+                id,
+                ...(settingId ? { settingId } : {}),
+                argv: buildArgv(id, { accountId: PLACEHOLDER_ID, zoneId: PLACEHOLDER_ID, rulesetId: PLACEHOLDER_ID, settingId, page: 1 }, auth, { dryRun: true }),
+                expectedPath: fill(spec.path, filled),
+                ...(query ? { expectedQuery: query } : {}),
+            });
+        }
+    }
+    return checks;
+}
+export const PREFLIGHT_ACCOUNT_ID = PLACEHOLDER_ID;
+const API_PREFIX = 'https://api.cloudflare.com/client/v4';
+function sameQuery(actual, expected) {
+    if (expected === undefined)
+        return actual === undefined;
+    if (!actual || typeof actual !== 'object' || Array.isArray(actual))
+        return false;
+    const left = Object.entries(actual).filter(([, value]) => value !== undefined && value !== null);
+    if (left.length !== Object.keys(expected).length)
+        return false;
+    return left.every(([key, value]) => Object.hasOwn(expected, key) && expected[key] === value);
+}
+/** True when a dry-run object maps to `GET` and exactly the expected path and query. */
+export function dryRunMatches(stdout, check) {
+    let printed;
+    try {
+        printed = JSON.parse(stdout);
+    }
+    catch {
+        return false;
+    }
+    if (!printed || typeof printed !== 'object' || Array.isArray(printed))
+        return false;
+    const { method, url, query } = printed;
+    if (method !== 'GET' || typeof url !== 'string' || !url.startsWith(`${API_PREFIX}/`))
+        return false;
+    return url.slice(API_PREFIX.length) === check.expectedPath && sameQuery(query, check.expectedQuery);
+}
+/** Kinds whose mismatch aborts collection with CF_ALLOWLIST_MISMATCH. */
+export const CRITICAL_TEMPLATES = ['account_selection', 'account', 'zones'];
+/** Display form of every template, with placeholders, for `collect --dry-run`. */
+export function templateDisplay(id, auth) {
+    const argv = TEMPLATES[id].args.map((arg) => arg === '{Z}' ? '<ZONE_ID>' : arg === '{R}' ? '<RULESET_ID>' : arg === '{S}' ? '<SETTING_ID>' : arg === '{N}' ? '<PAGE>' : arg === '{A}' ? '<ACCOUNT_ID>' : arg);
+    argv.push('--quiet');
+    if (auth.authMode === 'profile')
+        argv.push('--profile', auth.profile);
+    return argv;
+}
+/** The other cf argv the CLI uses: version, the serial whoami, and the login and logout commands. */
+export function versionArgv() {
+    return ['--version'];
+}
+export function whoamiArgv(auth) {
+    return auth.authMode === 'profile' ? ['auth', 'whoami', '--profile', validateProfileName(auth.profile)] : ['auth', 'whoami'];
+}
+/** `cf auth create <p> [--no-browser] --scopes …` (re-authenticates an existing profile). */
+export function loginArgv(profile, scopes, options) {
+    for (const scope of scopes)
+        if (!/^[a-z0-9_.:-]{1,64}$/.test(scope))
+            throw new Error('Invalid OAuth scope.');
+    return ['auth', 'create', validateProfileName(profile), ...(options.noBrowser ? ['--no-browser'] : []), '--scopes', ...scopes];
+}
+/**
+ * `cf auth delete <p>` (logout). In cf 1.0.0-beta.13 it takes only the name:
+ * it refuses `--profile` and a shell API token, fails when the profile does
+ * not exist, removes the profile's directory bindings, logs the profile out
+ * and deletes its stored credentials. It has no confirmation prompt.
+ */
+export function logoutArgv(profile) {
+    return ['auth', 'delete', validateProfileName(profile)];
+}

package/dist/local/cloudflare-checkup/cf/auth-lifecycle.d.ts

@@ -0,0 +1,112 @@
+import { LocalCheckupError } from '../errors.js';
+import type { RequestBudget, Clock } from '../rate-budget.js';
+import type { CfAuthMode } from './child-env.js';
+import { type CfProcessResult } from './run-cf.js';
+export declare const PRE_EXPIRY_MARGIN_MS = 60000;
+export declare const RATE_LIMIT_PAUSE_MS = 30000;
+export declare const TRANSIENT_RETRY_DELAYS_MS: readonly [1000, 3000];
+export declare const MAX_CF_INVOCATIONS = 6000;
+export type WhoamiSummary = {
+    authenticated: boolean;
+    /** ISO timestamp of the OAuth token expiry, when cf reports a parseable one. */
+    expiresAt?: string;
+    scopes?: string[];
+};
+/** Reduce cf's whoami JSON; email, account names and the credential file path are dropped. */
+export declare function parseWhoami(stdout: string): WhoamiSummary | null;
+export declare function isReadOnlyScope(scope: string): boolean;
+export type DoctorAuth = {
+    source: 'cf_profile' | 'cf_env_token' | 'cf_default_profile';
+    profile: string | null;
+    authenticated: boolean;
+    expiresAt?: string;
+    scopes: 'known' | 'unknown';
+    missingRecommendedScopes?: string[];
+    writeScopeCount?: number;
+};
+export declare function authSourceFor(mode: CfAuthMode): DoctorAuth['source'];
+/**
+ * Doctor's auth view. In env mode cf reports `scopes` and `expiresAt` from the
+ * active profile's stored OAuth file even while the API token is in use, so
+ * both are ignored: API token permissions cannot be introspected.
+ */
+export declare function doctorAuth(summary: WhoamiSummary, mode: CfAuthMode, profile: string): DoctorAuth;
+export declare function authRequiredError(mode: CfAuthMode, message?: string): LocalCheckupError;
+export type CfCallFailure = {
+    kind: 'http';
+    status: number;
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'output_too_large';
+} | {
+    kind: 'command_unavailable';
+} | {
+    kind: 'network';
+} | {
+    kind: 'cf_error';
+} | {
+    kind: 'auth';
+};
+export type CfCallOutcome = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    failure: CfCallFailure;
+};
+export type CfCallOptions = {
+    stdoutCapBytes?: number;
+    /** Sets CLOUDFLARE_ACCOUNT_ID for the call; absent only for account selection. */
+    accountId?: string;
+};
+export type CfInvoke = (argv: readonly string[], options: CfCallOptions) => Promise<CfProcessResult>;
+export type SchedulerOptions = {
+    invoke: CfInvoke;
+    /** One serial `cf auth whoami`; it is invoked only while dispatch is paused. */
+    whoami: () => Promise<CfProcessResult>;
+    budget: RequestBudget;
+    clock: Clock;
+    authMode: CfAuthMode;
+    /** Live children are killed when the run aborts. */
+    terminateAll?: () => Promise<void>;
+    maxInvocations?: number;
+};
+/** Dispatch gate shared by every worker. */
+export declare class CfScheduler {
+    private readonly options;
+    invocations: number;
+    private dispatched;
+    private inFlight;
+    private drainWaiters;
+    private gate;
+    private refreshing;
+    private expiresAtMs;
+    private preExpiryEnabled;
+    /** Dispatch sequence number when the first 429 paused the run. */
+    private rateLimitPauseSeq;
+    private abortError;
+    constructor(options: SchedulerOptions);
+    get aborted(): Error | null;
+    /** The serial whoami (re-read once if it refreshed) before fan-out. Throws CF_AUTH_REQUIRED when cf is not signed in. */
+    start(): Promise<WhoamiSummary>;
+    /** Abort the run: no further dispatches, live children are killed. */
+    abort(error: Error): void;
+    throwIfAborted(): void;
+    /** One cf API call with the §F5 retry policy. */
+    call(argv: readonly string[], options?: CfCallOptions): Promise<CfCallOutcome>;
+    /** Wait for a request slot and an open gate; returns the dispatch sequence number. */
+    private dispatch;
+    private release;
+    private drain;
+    private shouldRefreshBeforeExpiry;
+    /** Close the dispatch gate until `work` (queued after any current gate) finishes. Failures abort the run. */
+    private setGate;
+    /** Pause dispatch, drain in-flight calls, run up to two serial whoami calls, resume. */
+    private refresh;
+    private expiryHasPassed;
+    private setExpiry;
+    private serialWhoami;
+}
+/** `null` for a clean exit; otherwise the classified failure. */
+export declare function toFailure(result: CfProcessResult): CfCallFailure | null;