@vigilbase/cli 0.1.4 → 0.2.1

package/dist/local/cloudflare-checkup/prompts.js

@@ -0,0 +1,139 @@
+/**
+ * Prompts and confirmations of local checkups.
+ *
+ * Every prompt goes to stderr, so `--json` keeps stdout one JSON object. On a
+ * terminal, answers are typed at a visible prompt. Without one, only the email
+ * verification reads its answers (the work email without `--email`, and the
+ * emailed code) from piped stdin, one line each, so a script can write the code
+ * once it sees the prompt; every other question needs a flag (`--yes`,
+ * `--account-id`). What is read is never echoed in errors.
+ */
+import { createInterface } from 'node:readline/promises';
+import { LocalCheckupError } from './errors.js';
+/** One piped answer is at most this long (an email address is at most 254 bytes). */
+export const MAX_ANSWER_BYTES = 256;
+function isTty(stream) {
+    return Boolean(stream && stream.isTTY);
+}
+export function hasInteractiveInput(stdin) {
+    return isTty(stdin);
+}
+/**
+ * A visible one-line prompt on a TTY (account picker, confirmations): the
+ * trimmed answer, or null when the input ended (Ctrl-D) before one.
+ */
+export async function promptLine(io, label) {
+    if (!isTty(io.stdin)) {
+        throw new LocalCheckupError('CONFIRMATION_REQUIRED', 'No terminal is available for this prompt.', { hint: 'Run the command in a terminal, or pass the answer as a flag (--account-id, --yes).' });
+    }
+    if (io.stdin.readableEnded)
+        return null;
+    const rl = createInterface({ input: io.stdin, output: io.stderr, terminal: false });
+    // readline's question() never settles once the input ends; the interface's 'close' does.
+    const ended = new Promise((resolve) => rl.once('close', () => resolve(null)));
+    try {
+        const answer = await Promise.race([rl.question(label).catch(() => null), ended]);
+        if (answer !== null)
+            return answer.trim();
+        // Ctrl-D leaves the cursor on the prompt line.
+        io.stderr.write('\n');
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * One line of piped input, without consuming the next one: whatever follows
+ * the newline is pushed back onto the stream for the next prompt. Bytes past
+ * `MAX_ANSWER_BYTES` are dropped up to the newline, so an overlong line comes
+ * back too long and fails validation. Null at the end of the input.
+ */
+export function readPipedLine(stdin) {
+    const stream = stdin;
+    if (stream.readableEnded)
+        return Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+        let kept = Buffer.alloc(0);
+        let settled = false;
+        const finish = (error, line, rest) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.removeListener('readable', onReadable);
+            stream.removeListener('end', onEnd);
+            stream.removeListener('error', onError);
+            if (rest && rest.byteLength > 0)
+                stream.unshift(rest);
+            if (error)
+                reject(error);
+            else
+                resolve(line === null ? null : line.toString('utf8').replace(/\r$/, ''));
+        };
+        const onReadable = () => {
+            let chunk;
+            while (!settled && (chunk = stream.read()) !== null) {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+                const newline = bytes.indexOf(0x0a);
+                const head = newline >= 0 ? bytes.subarray(0, newline) : bytes;
+                if (kept.byteLength <= MAX_ANSWER_BYTES)
+                    kept = Buffer.concat([kept, head.subarray(0, MAX_ANSWER_BYTES + 1 - kept.byteLength)]);
+                if (newline >= 0)
+                    finish(null, kept, bytes.subarray(newline + 1));
+            }
+        };
+        const onEnd = () => finish(null, kept.byteLength > 0 ? kept : null);
+        const onError = (error) => finish(error, null);
+        stream.on('readable', onReadable);
+        stream.on('end', onEnd);
+        stream.on('error', onError);
+        onReadable();
+    });
+}
+/**
+ * A visible prompt for the email verification. On a terminal it is
+ * `promptLine`; without one the label still goes to stderr and the answer is
+ * one line of piped stdin. Null when the input ended without an answer.
+ */
+export async function promptAnswer(io, label) {
+    if (isTty(io.stdin))
+        return promptLine(io, label);
+    io.stderr.write(label);
+    const line = io.stdin ? await readPipedLine(io.stdin) : null;
+    // A piped answer is not echoed by a terminal; end the prompt line.
+    io.stderr.write('\n');
+    return line === null ? null : line.trim();
+}
+/**
+ * `[y/N]` upload confirmation: an explicit `y` is required. `--yes` (or its
+ * alias `--confirm`) answers yes; without a terminal and without them it is
+ * CONFIRMATION_REQUIRED.
+ */
+export async function confirmUpload(io, question, options) {
+    if (options.isConfirmed) {
+        io.stderr.write(`${question} [y/N] y (${options.flag ?? '--yes'})\n`);
+        return true;
+    }
+    if (!isTty(io.stdin)) {
+        throw new LocalCheckupError('CONFIRMATION_REQUIRED', 'Uploading needs confirmation, and no terminal is available to ask.');
+    }
+    const answer = await promptLine(io, `${question} [y/N] `);
+    if (answer === null)
+        throw inputEnded('Uploading needs confirmation, and the input ended before an answer.');
+    return /^y(?:es)?$/i.test(answer);
+}
+/**
+ * `[Y/n]` question where Enter means yes (installing cf). The caller handles
+ * `--yes` and the no-terminal case; an input that ends before an answer is
+ * CONFIRMATION_REQUIRED.
+ */
+export async function confirmDefaultYes(io, question) {
+    const answer = await promptLine(io, `${question} [Y/n] `);
+    if (answer === null)
+        throw inputEnded('The question needs an answer, and the input ended before one.');
+    return answer === '' || /^y(?:es)?$/i.test(answer);
+}
+/** Ctrl-D at a confirmation: nothing was confirmed. */
+function inputEnded(message) {
+    return new LocalCheckupError('CONFIRMATION_REQUIRED', message, { hint: 'Run the same command again and answer the question, or add --yes.' });
+}

package/dist/local/cloudflare-checkup/rate-budget.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cloudflare request budget (spec §F5).
+ *
+ * Cloudflare allows 1,200 API requests per user per rolling 5 minutes, shared
+ * with the user's dashboard; going over blocks every API call for 5 minutes.
+ * The default spends at most 900 per rolling 5 minutes (configurable 100 to
+ * 1,100). A token bucket with capacity `burst` that refills at
+ * `(limit − burst) / 300 s` never admits more than `limit` calls in any
+ * 300-second window: at most `burst` from the full bucket plus the refill.
+ * Local `--version` and `--dry-run` calls are free.
+ */
+export declare const DEFAULT_REQUESTS_PER_5MIN = 900;
+export declare const MIN_REQUESTS_PER_5MIN = 100;
+export declare const MAX_REQUESTS_PER_5MIN = 1100;
+export declare const BUDGET_BURST = 8;
+export declare const BUDGET_WINDOW_MS = 300000;
+export type Clock = {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+export declare const systemClock: Clock;
+export declare function parseRequestBudget(raw: string | undefined): number;
+export declare class RequestBudget {
+    readonly limit: number;
+    private readonly clock;
+    readonly burst: number;
+    private tokens;
+    private updatedAt;
+    private readonly refillPerMs;
+    private queue;
+    constructor(limit?: number, clock?: Clock, burst?: number);
+    private refill;
+    /** Tokens available now (fractional). */
+    available(): number;
+    /** Wait for one request slot. Callers are served in order. */
+    acquire(): Promise<void>;
+    /** Seconds the bucket needs for `requests` calls, ignoring network latency. */
+    estimateSeconds(requests: number): number;
+}
+/** Seconds a full bucket needs to admit `requests` calls at `limit` per 5 minutes. */
+export declare function estimateBudgetSeconds(limit: number, requests: number, burst?: number): number;

package/dist/local/cloudflare-checkup/rate-budget.js

@@ -0,0 +1,79 @@
+/**
+ * Cloudflare request budget (spec §F5).
+ *
+ * Cloudflare allows 1,200 API requests per user per rolling 5 minutes, shared
+ * with the user's dashboard; going over blocks every API call for 5 minutes.
+ * The default spends at most 900 per rolling 5 minutes (configurable 100 to
+ * 1,100). A token bucket with capacity `burst` that refills at
+ * `(limit − burst) / 300 s` never admits more than `limit` calls in any
+ * 300-second window: at most `burst` from the full bucket plus the refill.
+ * Local `--version` and `--dry-run` calls are free.
+ */
+export const DEFAULT_REQUESTS_PER_5MIN = 900;
+export const MIN_REQUESTS_PER_5MIN = 100;
+export const MAX_REQUESTS_PER_5MIN = 1_100;
+export const BUDGET_BURST = 8;
+export const BUDGET_WINDOW_MS = 300_000;
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export function parseRequestBudget(raw) {
+    if (raw === undefined)
+        return DEFAULT_REQUESTS_PER_5MIN;
+    const value = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < MIN_REQUESTS_PER_5MIN || value > MAX_REQUESTS_PER_5MIN) {
+        throw new Error(`--max-requests-per-5min must be an integer between ${MIN_REQUESTS_PER_5MIN} and ${MAX_REQUESTS_PER_5MIN}.`);
+    }
+    return value;
+}
+export class RequestBudget {
+    limit;
+    clock;
+    burst;
+    tokens;
+    updatedAt;
+    refillPerMs;
+    queue = Promise.resolve();
+    constructor(limit = DEFAULT_REQUESTS_PER_5MIN, clock = systemClock, burst = BUDGET_BURST) {
+        this.limit = limit;
+        this.clock = clock;
+        this.burst = burst;
+        if (!(limit > burst))
+            throw new Error('The request budget must exceed the burst size.');
+        this.tokens = burst;
+        this.updatedAt = clock.now();
+        this.refillPerMs = (limit - burst) / BUDGET_WINDOW_MS;
+    }
+    refill() {
+        const now = this.clock.now();
+        this.tokens = Math.min(this.burst, this.tokens + (now - this.updatedAt) * this.refillPerMs);
+        this.updatedAt = now;
+    }
+    /** Tokens available now (fractional). */
+    available() {
+        this.refill();
+        return this.tokens;
+    }
+    /** Wait for one request slot. Callers are served in order. */
+    acquire() {
+        const next = this.queue.then(async () => {
+            this.refill();
+            while (this.tokens < 1) {
+                await this.clock.sleep(Math.max(1, Math.ceil((1 - this.tokens) / this.refillPerMs)));
+                this.refill();
+            }
+            this.tokens -= 1;
+        });
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    /** Seconds the bucket needs for `requests` calls, ignoring network latency. */
+    estimateSeconds(requests) {
+        return estimateBudgetSeconds(this.limit, requests, this.burst);
+    }
+}
+/** Seconds a full bucket needs to admit `requests` calls at `limit` per 5 minutes. */
+export function estimateBudgetSeconds(limit, requests, burst = BUDGET_BURST) {
+    return Math.max(0, ((requests - burst) * BUDGET_WINDOW_MS) / (limit - burst) / 1000);
+}

package/dist/local/cloudflare-checkup/snapshot-file.d.ts

@@ -0,0 +1,52 @@
+import { type CloudflareCheckupSnapshotV1, type SnapshotEntry } from './contract.js';
+import { LocalCheckupError } from './errors.js';
+export declare function sha256Hex(bytes: Uint8Array | string): string;
+/** Write the snapshot; refuses an existing file unless `overwrite` (atomic rename). */
+export declare function writeSnapshotFile(path: string, text: string, options: {
+    overwrite: boolean;
+}): Promise<{
+    bytes: number;
+    sha256: string;
+}>;
+export type LoadedSnapshot = {
+    path: string;
+    bytes: Buffer;
+    sha256: string;
+    snapshot: CloudflareCheckupSnapshotV1;
+};
+/** Map a failed contract parse to the CLI error (no values, issue codes only). */
+export declare function snapshotParseError(issues: ReadonlyArray<{
+    code?: string;
+    message?: string;
+    path?: ReadonlyArray<PropertyKey>;
+    params?: unknown;
+}>): LocalCheckupError;
+/** Read, hash and validate a snapshot file against the vendored contract. */
+export declare function loadSnapshotFile(path: string): Promise<LoadedSnapshot>;
+export type EntryCounts = {
+    total: number;
+    ok: number;
+    httpError: number;
+    notCollected: number;
+    collectionFailed: number;
+};
+export declare function countEntries(entries: readonly SnapshotEntry[]): EntryCounts;
+export type EntryKindCounts = Record<string, {
+    total: number;
+    ok: number;
+    httpError: number;
+    notCollected: number;
+    collectionFailed: number;
+}>;
+export declare function countEntriesByKind(entries: readonly SnapshotEntry[]): EntryKindCounts;
+/** Counts of every free-text or identifying category the snapshot carries (`inspect`). */
+export type DataCategories = {
+    memberEmails: number;
+    accessRuleValues: number;
+    dnsHostnames: number;
+    pseudonymizedIps: number;
+    ruleDescriptions: number;
+};
+export declare function dataCategories(snapshot: CloudflareCheckupSnapshotV1): DataCategories;
+export declare function zoneCount(snapshot: CloudflareCheckupSnapshotV1): number;
+export declare function accountName(snapshot: CloudflareCheckupSnapshotV1): string | null;

package/dist/local/cloudflare-checkup/snapshot-file.js

@@ -0,0 +1,185 @@
+/**
+ * Snapshot files (spec §F7).
+ *
+ * Both modes write the bytes to a `wx` 0600 temp file in the same directory
+ * first, so `--out` never holds a partial snapshot. The default mode publishes
+ * it with `link(2)`, which never replaces an existing file (deviation from
+ * §F7's direct `open(path, 'wx')`; on filesystems without hard links it falls
+ * back to that, removing the file if the write fails). `--overwrite` renames
+ * the temp file over the target. `submit` uploads the exact bytes of the file
+ * the user inspected.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { link, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { CloudflareCheckupSnapshotV1Schema, SNAPSHOT_LIMITS, SNAPSHOT_SCHEMA_VERSION, expandRuleRuns, snapshotIssueList, snapshotRejectReason, } from './contract.js';
+import { LocalCheckupError } from './errors.js';
+export function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** `link(2)` errors from filesystems without hard links (FAT/exFAT, some SMB mounts). */
+const NO_HARD_LINK_CODES = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS']);
+/** Create `path` exclusively (0600), write and fsync; a partially written file is removed. */
+async function writeExclusive(path, bytes) {
+    // no-dd-sa:javascript-node-security/detect-non-literal-fs-filename — the user's --out path; created exclusively, never followed.
+    const handle = await open(path, 'wx', 0o600);
+    try {
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        // This process created the file (`wx`), so removing it cannot touch anyone else's data.
+        await rm(path, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** Give the complete temp file its final name without ever replacing an existing file. */
+async function publishExclusive(temp, path, bytes) {
+    try {
+        await link(temp, path);
+    }
+    catch (error) {
+        if (!NO_HARD_LINK_CODES.has(error.code ?? ''))
+            throw error;
+        await writeExclusive(path, bytes);
+    }
+}
+/** Write the snapshot; refuses an existing file unless `overwrite` (atomic rename). */
+export async function writeSnapshotFile(path, text, options) {
+    const bytes = Buffer.from(text, 'utf8');
+    if (options.overwrite) {
+        const existing = await stat(path).catch(() => null);
+        if (existing && !existing.isFile())
+            throw new Error('--out must name a regular file.');
+    }
+    const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        await writeExclusive(temp, bytes);
+        if (options.overwrite)
+            await rename(temp, path);
+        else
+            await publishExclusive(temp, path, bytes);
+    }
+    catch (error) {
+        const code = error.code;
+        if (!options.overwrite && code === 'EEXIST') {
+            throw new LocalCheckupError('OUTPUT_EXISTS', 'The --out file already exists; it was not modified.');
+        }
+        throw new Error(`Could not write the snapshot file (${code ?? 'error'}).`);
+    }
+    finally {
+        // A no-op after rename; drops the temp name after link.
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+    return { bytes: bytes.byteLength, sha256: sha256Hex(bytes) };
+}
+/** Map a failed contract parse to the CLI error (no values, issue codes only). */
+export function snapshotParseError(issues) {
+    const reason = snapshotRejectReason(issues);
+    const codes = [...new Set(snapshotIssueList(issues).map((issue) => issue.code))].slice(0, 5).join(', ');
+    if (reason === 'secret_like_value') {
+        return new LocalCheckupError('SNAPSHOT_SECRET_LIKE_VALUE', 'The snapshot contains a value that looks like a credential, so it will not be written or uploaded.');
+    }
+    return new LocalCheckupError('SNAPSHOT_INVALID', `The snapshot does not match ${SNAPSHOT_SCHEMA_VERSION} (${codes || 'invalid'}).`);
+}
+/** Read, hash and validate a snapshot file against the vendored contract. */
+export async function loadSnapshotFile(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info || !info.isFile())
+        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file does not exist or is not a regular file.');
+    if (info.size > SNAPSHOT_LIMITS.maxBytes) {
+        throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', `The snapshot is larger than the ${SNAPSHOT_LIMITS.maxBytes / 1024 / 1024} MiB contract limit.`);
+    }
+    // no-dd-sa:javascript-node-security/detect-non-literal-fs-filename — the user's own snapshot path.
+    const bytes = await readFile(path);
+    if (bytes.byteLength > SNAPSHOT_LIMITS.maxBytes)
+        throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', 'The snapshot is larger than the contract limit.');
+    let raw;
+    try {
+        raw = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file is not valid JSON.');
+    }
+    const parsed = CloudflareCheckupSnapshotV1Schema.safeParse(raw);
+    if (!parsed.success)
+        throw snapshotParseError(parsed.error.issues);
+    return { path, bytes, sha256: sha256Hex(bytes), snapshot: parsed.data };
+}
+export function countEntries(entries) {
+    const counts = { total: entries.length, ok: 0, httpError: 0, notCollected: 0, collectionFailed: 0 };
+    for (const entry of entries) {
+        const result = entry.result;
+        if (result.ok)
+            counts.ok++;
+        else if (result.reason === 'http_error')
+            counts.httpError++;
+        else if (result.reason === 'not_collected')
+            counts.notCollected++;
+        else
+            counts.collectionFailed++;
+    }
+    return counts;
+}
+export function countEntriesByKind(entries) {
+    const byKind = {};
+    for (const entry of entries) {
+        byKind[entry.kind] ??= { total: 0, ok: 0, httpError: 0, notCollected: 0, collectionFailed: 0 };
+        const counts = byKind[entry.kind];
+        const result = entry.result;
+        counts.total++;
+        if (result.ok)
+            counts.ok++;
+        else if (result.reason === 'http_error')
+            counts.httpError++;
+        else if (result.reason === 'not_collected')
+            counts.notCollected++;
+        else
+            counts.collectionFailed++;
+    }
+    return byKind;
+}
+export function dataCategories(snapshot) {
+    const categories = { memberEmails: 0, accessRuleValues: 0, dnsHostnames: 0, pseudonymizedIps: 0, ruleDescriptions: 0 };
+    const ips = new Set();
+    for (const entry of snapshot.entries) {
+        if (!entry.result.ok)
+            continue;
+        switch (entry.kind) {
+            case 'account_members':
+                categories.memberEmails += entry.result.data.filter((member) => member.email !== undefined).length;
+                break;
+            case 'account_access_rules':
+            case 'zone_access_rules':
+                categories.accessRuleValues += entry.result.data.filter((rule) => rule.configuration?.value !== undefined).length;
+                break;
+            case 'zone_dns_records':
+                for (const record of entry.result.data) {
+                    if (record.name !== undefined)
+                        categories.dnsHostnames++;
+                    ips.add(record.content);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    categories.pseudonymizedIps = ips.size;
+    for (const runs of Object.values(snapshot.ruleBodies)) {
+        categories.ruleDescriptions += expandRuleRuns(runs).filter((rule) => rule.description !== undefined || rule.ref !== undefined).length;
+    }
+    return categories;
+}
+export function zoneCount(snapshot) {
+    const zones = snapshot.entries.find((entry) => entry.kind === 'zones');
+    return zones && zones.kind === 'zones' ? zones.result.data.length : 0;
+}
+export function accountName(snapshot) {
+    const account = snapshot.entries.find((entry) => entry.kind === 'account');
+    return account && account.kind === 'account' && account.result.ok ? account.result.data.name : null;
+}

package/dist/local/cloudflare-checkup/submit-client.d.ts

@@ -0,0 +1,112 @@
+import { type LocalAvailabilityResponse, type LocalRequestBody, type LocalRequestResponse, type LocalSessionResponse, type LocalVerifyBody, type LocalVerifyResponse } from './contract.js';
+/**
+ * `GET local-session`. The account is chosen in the CLI and bound by the
+ * uploaded snapshot, so `accountId` is `null` until then; runs created before
+ * that change still carry their bound account.
+ */
+export type LocalSession = LocalSessionResponse['session'];
+/** `GET local-session/availability`: local checkups are on, with the oldest CLI and the snapshots vigilbase.com accepts. */
+export type LocalAvailability = LocalAvailabilityResponse;
+/** `POST local-session/request`: the token naming the run that awaits its emailed code. */
+export type PendingVerification = LocalRequestResponse['verification'];
+/** `POST local-session/verify`: the session code for the upload (kept in memory only). */
+export type VerifiedSession = LocalVerifyResponse['session'];
+export declare const GET_TIMEOUT_MS = 30000;
+/** The availability check is skipped (the run goes on) when vigilbase.com does not answer it within this. */
+export declare const AVAILABILITY_TIMEOUT_MS = 10000;
+export declare const POST_TIMEOUT_MS = 120000;
+export declare const MAX_SUBMIT_RESPONSE_BYTES: number;
+export declare const POST_RETRY_DELAYS_MS: readonly [2000, 5000];
+/** A verify that failed on the network or with a 503 is sent once more, after this pause. */
+export declare const VERIFY_RETRY_DELAYS_MS: readonly [2000];
+/** True for http(s) loopback origins (local development), the only ones besides production that `--base-url` accepts. */
+export declare function isLoopbackOrigin(origin: string): boolean;
+/**
+ * The submit origin. Only `https://vigilbase.com` and loopback origins are
+ * accepted; there is no `*.vigilbase.com` wildcard (other subdomains are
+ * different services). Environment variables are never consulted.
+ */
+export declare function resolveSubmitOrigin(explicit: string | undefined): string;
+export type LocalClientOptions = {
+    origin: string;
+    cliVersion: string;
+    userAgent: string;
+    /** Overrides every request timeout (`--timeout`). */
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable for tests; the global `fetch` (looked up per request) otherwise. */
+    fetch?: typeof fetch;
+};
+export type SubmitClientOptions = LocalClientOptions & {
+    code: string;
+};
+/**
+ * The results page from an upload response, as printable ASCII (`URL.href`
+ * percent-encodes everything else), or undefined when it is not a plain
+ * http(s) URL. The caller decides whether to open it (same origin only).
+ */
+export declare function trustedResultsUrl(raw: string | undefined): string | undefined;
+/** Shared transport: CLI headers, no redirects, bounded responses, CLI-authored network errors. */
+declare abstract class LocalHttpClient {
+    protected readonly options: LocalClientOptions;
+    constructor(options: LocalClientOptions);
+    protected sleep(ms: number): Promise<void>;
+    protected headers(extra?: Record<string, string>): Record<string, string>;
+    protected request(path: string, init: RequestInit, timeoutMs: number): Promise<{
+        response: Response;
+        text: string;
+    }>;
+}
+/**
+ * The requests before the session code, without a bearer: the availability
+ * check and the email verification. A code request is never retried: a
+ * repeated request would send a second email. A verify that failed on the
+ * network (or timed out) or with a 503 is sent once more, after 2 s, with the
+ * same token and code: One counts only wrong codes, and the right code
+ * verified again mints the next session code, as a renewal does. Only when
+ * the lost answer was to a wrong code does the retry cost a second try.
+ */
+export declare class VerificationClient extends LocalHttpClient {
+    private postJson;
+    /**
+     * `GET local-session/availability`, before the email is asked for: what
+     * vigilbase.com accepts, or null when it gave no usable answer (a 404 from a
+     * server without the route, a network error, a timeout, a challenge or any
+     * other response), and the run goes on as before. Throws LOCAL_MODE_DISABLED
+     * when it answers that local checkups are switched off. Never retried.
+     */
+    availability(): Promise<LocalAvailability | null>;
+    /** `POST local-session/request`: vigilbase.com emails a 6-digit code and returns the token for it. */
+    requestCode(body: LocalRequestBody): Promise<PendingVerification>;
+    /** `POST local-session/verify`: trades the token and the emailed code for a session code (the next one on every call). */
+    verifyCode(body: LocalVerifyBody): Promise<VerifiedSession>;
+}
+export type UploadResult = {
+    replayed: boolean;
+    snapshotSha256: string;
+    provenance: Record<string, unknown>;
+    report: Record<string, unknown>;
+    /** The results page, when vigilbase.com returned one (see `trustedResultsUrl`). */
+    resultsUrl?: string;
+};
+export declare class SubmitClient extends LocalHttpClient {
+    private readonly code;
+    constructor(options: SubmitClientOptions);
+    private bearer;
+    /** `GET local-session`: the bound account (or null), masked requester, expiry and accepted limits. */
+    getSession(): Promise<LocalSession>;
+    /**
+     * `POST local-session/snapshot` with the exact file bytes. 503 and network
+     * errors are retried twice (after 2 s, then 5 s) with the same bytes, which
+     * the server treats idempotently. Challenges are never retried.
+     */
+    postSnapshot(bytes: Buffer, sha256: string): Promise<UploadResult>;
+}
+/** Refuse a server (its session, or its availability answer) that requires a newer CLI, or does not accept this schema version. */
+export declare function assertServerAccepts(server: Pick<LocalSession, 'accepts' | 'minCliVersion'>, cliVersion: string, schemaVersion: string): void;
+/**
+ * The masked address as the server masks it (first character, `***`, the
+ * domain); any other text from the server is replaced by `fallback`.
+ */
+export declare function displayRequester(requester: string, fallback?: string): string;
+export {};