@vigilbase/cli
Version:
Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.
113 lines (112 loc) • 6.13 kB
TypeScript
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 {};