@vigilbase/cli/dist/local/cloudflare-checkup/email-verification.d.ts

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

/**
 * Email verification in the CLI: the one command and `submit` start with it.
 *
 * The CLI asks for a work email (or takes `--email`) and POSTs it to
 * `local-session/request`; vigilbase.com creates the checkup and emails a
 * 6-digit code. The CLI asks for the code and POSTs it with the returned
 * verification token to `local-session/verify`, which answers with the
 * session code for the upload. There is no bot check on this path; the server
 * accepts business addresses only and rate-limits per mailbox (`+tag`
 * variants included), per domain, per IP (an IPv6 /64 counts as one) and
 * overall.
 *
 * The address, the emailed code, the token and the session code stay in this
 * process's memory. They are never printed (only the masked address the server
 * returns, `j***@acme.com`), logged, written to disk, put in a URL or JSON
 * output, or passed to cf or npm. The token and the code are kept only so the
 * session can be renewed once when it expires during a long collection.
 */
import type { LocalEmailLocale } from './contract.js';
import { LocalCheckupError } from './errors.js';
import { type PromptIO } from './prompts.js';
import { type VerificationClient } from './submit-client.js';
export declare const EMAIL_PROMPT = "Work email for your results: ";
export declare const CODE_PROMPT = "Code from the email: ";
/** Addresses asked for before giving up (a malformed one, or one vigilbase.com does not accept). */
export declare const MAX_EMAIL_ATTEMPTS = 3;
/** Codes asked for before giving up; One locks a checkup after 5 wrong codes. */
export declare const MAX_CODE_ATTEMPTS = 5;
/**
 * On a terminal, how often the code is asked for again after vigilbase.com did
 * not answer the verify (twice: the client already sent it once more). These
 * are not tries: only a wrong code uses one.
 */
export declare const MAX_UNANSWERED_VERIFIES = 2;
/** One `@` with text on both sides, no spaces or control characters, at most 254 characters. */
export declare function isEmailShaped(value: string): boolean;
/** `--email <address>`: checked before anything runs; the value is never echoed. */
export declare function parseEmailFlag(value: string): string;
/** The six digits of a typed code; `123 456` and `123-456` are accepted too. Null for anything else. */
export declare function normalizeEmailCode(input: string): string | null;
/** The email language from LC_ALL, LC_MESSAGES or LANG (the first one set): `pt*` → pt-PT, `ar*` → ar, else en. */
export declare function emailLocale(env: NodeJS.ProcessEnv): LocalEmailLocale;
/**
 * A verified email and the session code it earned. Private fields keep the
 * token, the emailed code and the session code out of `JSON.stringify` and
 * `util.inspect`.
 */
export declare class VerifiedEmail {
    #private;
    /** The masked address from vigilbase.com, safe to print. */
    readonly requester: string;
    constructor(client: VerificationClient, token: string, emailCode: string, session: {
        code: string;
        requester: string;
        expiresAt: string;
    });
    /** The current session code: in memory only, sent only as the upload's bearer. */
    get sessionCode(): string;
    get expiresAt(): string;
    /** True until `renew` has been used. */
    get renewable(): boolean;
    /**
     * Once per run: verify again with the same token and code, and vigilbase.com
     * mints the next session code for the same checkup (the previous one stops
     * working). It fails once the emailed code expired or the checkup closed.
     */
    renew(): Promise<void>;
    toJSON(): {
        requester: string;
    };
}
/**
 * How the verification asks and reports. The default is the plain prompts
 * (`Work email for your results:` and `Code from the email:`, a visible line or
 * one line of piped stdin) and status lines through `say` and `notice`; the
 * terminal UI brings its own inputs and spinners.
 */
export type EmailVerificationView = {
    /** The address as entered; null when the input ended. */
    askEmail(): Promise<string | null>;
    /** The emailed code as entered; null when the input ended. */
    askCode(): Promise<string | null>;
    /** The code went to `sentTo` (the masked address) and is valid until `expiresAt`. */
    codeSent(sentTo: string, expiresAt: string): void;
    /** Why the next question is asked again. */
    notice(line: string): void;
    /** The code request to vigilbase.com. */
    requesting<T>(work: () => Promise<T>): Promise<T>;
    /** The code check at vigilbase.com. */
    verifying<T>(work: () => Promise<T>): Promise<T>;
    /**
     * A rate-limited code request (VIGILBASE_RATE_LIMITED): true to ask for
     * another address. Asked only without `--email` and while addresses are
     * left; without it the error stops the run (exit 2).
     */
    rateLimited?(error: LocalCheckupError): Promise<boolean>;
};
export type EmailVerificationOptions = {
    client: VerificationClient;
    io: PromptIO;
    locale: LocalEmailLocale;
    /** `--email`, already checked with `parseEmailFlag`; it is never asked for again. */
    email?: string;
    /** A status line ("We emailed a 6-digit code to …"). */
    say(line: string): void;
    /** Why a prompt is asked again (stderr). */
    notice(line: string): void;
    /** Replaces the plain prompts and lines built from `io`, `say` and `notice`. */
    view?: EmailVerificationView;
};
/** vigilbase.com starts one checkup per address every 8 minutes (One's creation budget). No final period. */
export declare const SAME_ADDRESS_WAIT = "The same address can get a new code 8 minutes after the last one";
/**
 * Request a code, then ask for it until vigilbase.com accepts it (up to 5
 * tries; One locks the checkup after 5 wrong codes). A wrong address is asked
 * for again (up to 3), except with `--email`. An expired verification and a
 * rate limit stop with their own codes (VERIFICATION_EXPIRED, and
 * VIGILBASE_RATE_LIMITED with the retry time, exit 2), unless the view offers
 * another address for a rate limit. A verify vigilbase.com did not answer is
 * sent once more by the client; if that fails too, a terminal asks for the
 * code again (twice at most, without using a try), since a new code for the
 * same address would be refused for 8 minutes.
 */
export declare function verifyEmail(options: EmailVerificationOptions): Promise<VerifiedEmail>;