@slicedearth/whoisleuth-cli 1.32.0

package/cli/artifact-verify.mjs

@@ -0,0 +1,210 @@
+import { Buffer } from 'node:buffer';
+import { CASE_RESPONSE_PACKET_SCHEMA, CASE_RESPONSE_PACKET_VERSION, verifyCaseResponsePacketIntegrity, } from "../frontend/src/lib/analysis/case-response-packet.js";
+import { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION, } from "../frontend/src/lib/analysis/acquisition-decision-packet.js";
+import { BULK_DOMAIN_COMPARISON_SCHEMA, BULK_DOMAIN_COMPARISON_VERSION, } from "../frontend/src/lib/analysis/bulk-domain-comparison.js";
+import { BULK_MAIL_EXPOSURE_SCHEMA, BULK_MAIL_EXPOSURE_VERSION, } from "../frontend/src/lib/analysis/bulk-mail-exposure.js";
+import { BULK_REVIEW_MANIFEST_SCHEMA, BULK_REVIEW_MANIFEST_VERSION, } from "../frontend/src/lib/analysis/bulk-review-export.js";
+import { decryptWorkspaceArchive, inspectEncryptedWorkspaceArchive, isEncryptedWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive-crypto.js";
+import { WORKSPACE_ARCHIVE_SCHEMA, readWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive.js";
+import { sha256ArtifactDigest } from "../frontend/src/lib/analysis/artifact-integrity.js";
+export const OFFLINE_ARTIFACT_VERIFICATION_SCHEMA = 'whoisleuth.offline-artifact-verification';
+export const OFFLINE_ARTIFACT_VERIFICATION_VERSION = 1;
+export const MAX_OFFLINE_ARTIFACT_BYTES = 15 * 1024 * 1024;
+export const MAX_OFFLINE_PASSPHRASE_FILE_BYTES = 1024;
+const SIGNED_ARTIFACT_VERSIONS = Object.freeze({
+    [ACQUISITION_DECISION_PACKET_SCHEMA]: new Set([ACQUISITION_DECISION_PACKET_VERSION]),
+    [BULK_DOMAIN_COMPARISON_SCHEMA]: new Set([BULK_DOMAIN_COMPARISON_VERSION]),
+    [BULK_MAIL_EXPOSURE_SCHEMA]: new Set([BULK_MAIL_EXPOSURE_VERSION]),
+    [BULK_REVIEW_MANIFEST_SCHEMA]: new Set([BULK_REVIEW_MANIFEST_VERSION]),
+});
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseJson(raw) {
+    if (typeof raw !== 'string')
+        throw new TypeError('Artifact input must be UTF-8 JSON text.');
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (bytes === 0 || bytes > MAX_OFFLINE_ARTIFACT_BYTES) {
+        throw new TypeError(`Artifact input must be between 1 byte and ${MAX_OFFLINE_ARTIFACT_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TypeError('Artifact input is not valid JSON.');
+    }
+    const value = record(parsed);
+    if (!value)
+        throw new TypeError('Artifact input must contain one JSON object.');
+    return value;
+}
+function artifactVersion(value) {
+    if (!Number.isSafeInteger(value.version) || Number(value.version) < 1 || Number(value.version) > 1000) {
+        throw new TypeError('Artifact version is missing or invalid.');
+    }
+    return Number(value.version);
+}
+function inputBytes(raw) {
+    return Buffer.byteLength(raw, 'utf8');
+}
+function archiveReport(raw, archive, encrypted, ciphertextBytes) {
+    return Object.freeze({
+        schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
+        version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+        artifact: Object.freeze({
+            kind: encrypted ? 'encrypted_workspace_archive' : 'workspace_archive',
+            schema: WORKSPACE_ARCHIVE_SCHEMA,
+            version: archive.version,
+        }),
+        state: 'verified',
+        valid: true,
+        checks: Object.freeze({
+            structure: 'verified',
+            contentIntegrity: 'verified',
+            authenticatedEncryption: encrypted ? 'verified' : 'not_applicable',
+        }),
+        summary: Object.freeze({
+            inputBytes: inputBytes(raw),
+            sectionCount: archive.sections.length,
+            recordCount: archive.sections.reduce((sum, section) => sum + section.recordCount, 0),
+            ciphertextBytes,
+        }),
+        limitations: Object.freeze([
+            'Verification checks the retained file against its declared versioned integrity contract; it does not establish that the original observations were accurate or remain current.',
+        ]),
+    });
+}
+async function verifySignedArtifact(raw, value, schema, version) {
+    const supported = SIGNED_ARTIFACT_VERSIONS[schema];
+    if (!supported?.has(version)) {
+        throw new TypeError('This signed review-artifact schema or version is not supported.');
+    }
+    const integrity = record(value.integrity);
+    if (!integrity
+        || integrity.algorithm !== 'SHA-256'
+        || typeof integrity.digestSha256 !== 'string'
+        || !/^sha256:[a-f0-9]{64}$/u.test(integrity.digestSha256)) {
+        throw new TypeError('The signed review artifact has a missing or malformed integrity envelope.');
+    }
+    const { integrity: _integrity, ...unsigned } = value;
+    if (await sha256ArtifactDigest(unsigned) !== integrity.digestSha256) {
+        throw new TypeError('The signed review artifact failed its SHA-256 integrity check.');
+    }
+    return Object.freeze({
+        schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
+        version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+        artifact: Object.freeze({ kind: 'signed_review_artifact', schema, version }),
+        state: 'verified',
+        valid: true,
+        checks: Object.freeze({
+            structure: 'verified',
+            contentIntegrity: 'verified',
+            authenticatedEncryption: 'not_applicable',
+        }),
+        summary: Object.freeze({
+            inputBytes: inputBytes(raw),
+            sectionCount: null,
+            recordCount: null,
+            ciphertextBytes: null,
+        }),
+        limitations: Object.freeze([
+            'Digest verification detects changes to this exported artifact; it does not authenticate the analyst, collection source, or truth of the retained statements.',
+        ]),
+    });
+}
+export async function verifyOfflineArtifact(raw, options = {}) {
+    const value = parseJson(raw);
+    if (isEncryptedWorkspaceArchive(value)) {
+        const inspected = inspectEncryptedWorkspaceArchive(value);
+        if (!options.passphrase) {
+            return Object.freeze({
+                schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
+                version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+                artifact: Object.freeze({
+                    kind: 'encrypted_workspace_archive',
+                    schema: String(value.schema),
+                    version: artifactVersion(value),
+                }),
+                state: 'envelope_valid',
+                valid: true,
+                checks: Object.freeze({
+                    structure: 'verified',
+                    contentIntegrity: 'not_checked',
+                    authenticatedEncryption: 'not_checked',
+                }),
+                summary: Object.freeze({
+                    inputBytes: inputBytes(raw),
+                    sectionCount: null,
+                    recordCount: null,
+                    ciphertextBytes: inspected.ciphertextBytes,
+                }),
+                limitations: Object.freeze([
+                    'The encrypted envelope is structurally valid, but its authenticated ciphertext and inner workspace checksums were not verified because no passphrase was supplied.',
+                    'Pass a separate bounded passphrase file to perform authenticated decryption without placing the passphrase in command history.',
+                ]),
+            });
+        }
+        const decrypted = await decryptWorkspaceArchive(value, options.passphrase);
+        const archive = await readWorkspaceArchive(decrypted);
+        return archiveReport(raw, archive, true, inspected.ciphertextBytes);
+    }
+    const schema = typeof value.schema === 'string' ? value.schema : '';
+    const version = artifactVersion(value);
+    if (schema === WORKSPACE_ARCHIVE_SCHEMA) {
+        return archiveReport(raw, await readWorkspaceArchive(value), false, null);
+    }
+    if (schema === CASE_RESPONSE_PACKET_SCHEMA) {
+        if (version !== CASE_RESPONSE_PACKET_VERSION) {
+            throw new TypeError('This case-response packet version is not supported.');
+        }
+        const integrity = record(value.integrity);
+        if (!integrity || !await verifyCaseResponsePacketIntegrity(value)) {
+            throw new TypeError('The case-response packet failed its manifest integrity check.');
+        }
+        return Object.freeze({
+            schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
+            version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+            artifact: Object.freeze({ kind: 'case_response_packet', schema, version }),
+            state: 'verified',
+            valid: true,
+            checks: Object.freeze({
+                structure: 'verified',
+                contentIntegrity: 'verified',
+                authenticatedEncryption: 'not_applicable',
+            }),
+            summary: Object.freeze({
+                inputBytes: inputBytes(raw),
+                sectionCount: null,
+                recordCount: null,
+                ciphertextBytes: null,
+            }),
+            limitations: Object.freeze([
+                'Packet digest verification detects changes after export; it does not authenticate the analyst, recipient, or truth of the retained observations.',
+            ]),
+        });
+    }
+    return verifySignedArtifact(raw, value, schema, version);
+}
+export function formatOfflineArtifactVerification(report) {
+    const lines = [
+        'WHOISleuth offline artifact verification',
+        `Artifact: ${report.artifact.kind} · ${report.artifact.schema} v${report.artifact.version}`,
+        `State: ${report.state}`,
+        `Structure: ${report.checks.structure}`,
+        `Content integrity: ${report.checks.contentIntegrity}`,
+        `Authenticated encryption: ${report.checks.authenticatedEncryption}`,
+        `Input bytes: ${report.summary.inputBytes}`,
+    ];
+    if (report.summary.sectionCount !== null)
+        lines.push(`Sections: ${report.summary.sectionCount}`);
+    if (report.summary.recordCount !== null)
+        lines.push(`Records: ${report.summary.recordCount}`);
+    if (report.summary.ciphertextBytes !== null)
+        lines.push(`Ciphertext bytes: ${report.summary.ciphertextBytes}`);
+    for (const limitation of report.limitations)
+        lines.push(`Limitation: ${limitation}`);
+    return `${lines.join('\n')}\n`;
+}

package/cli/bulk-checkpoint.mjs

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { CliUsageError } from "./errors.mjs";
+import { writePrivateFile } from "./output-file.mjs";
+export const CLI_BULK_CHECKPOINT_SCHEMA = 'whoisleuth.cli.bulk-checkpoint';
+export const CLI_BULK_CHECKPOINT_VERSION = 1;
+export const MAX_BULK_CHECKPOINT_BYTES = 16 * 1024 * 1024;
+const MAX_CHECKPOINT_JSON_DEPTH = 12;
+const MAX_CHECKPOINT_OBJECT_KEYS = 256;
+const MAX_CHECKPOINT_ARRAY_ITEMS = 1_024;
+const MAX_CHECKPOINT_STRING_LENGTH = 32_768;
+const COMPACT_RESULT_KEYS = new Set(['availability', 'diagnostics']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function checkpointDigest(queries, deep) {
+    return createHash('sha256')
+        .update(deep ? 'deep\n' : 'fast\n')
+        .update(queries.join('\n'))
+        .digest('hex');
+}
+function validTimestamp(value) {
+    return typeof value === 'string' && value.length <= 64 && Number.isFinite(Date.parse(value));
+}
+function isBoundedCheckpointJson(value, depth = 0) {
+    if (depth > MAX_CHECKPOINT_JSON_DEPTH)
+        return false;
+    if (value === null || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value === 'string')
+        return value.length <= MAX_CHECKPOINT_STRING_LENGTH;
+    if (Array.isArray(value)) {
+        return value.length <= MAX_CHECKPOINT_ARRAY_ITEMS
+            && value.every((item) => isBoundedCheckpointJson(item, depth + 1));
+    }
+    const object = record(value);
+    if (!object)
+        return false;
+    const entries = Object.entries(object);
+    return entries.length <= MAX_CHECKPOINT_OBJECT_KEYS
+        && entries.every(([key, item]) => key.length <= 128 && isBoundedCheckpointJson(item, depth + 1));
+}
+function normalizeCompactResult(value) {
+    const result = record(value);
+    if (!result || !isBoundedCheckpointJson(result))
+        return null;
+    const keys = Object.keys(result);
+    if (keys.length !== COMPACT_RESULT_KEYS.size || keys.some((key) => !COMPACT_RESULT_KEYS.has(key)))
+        return null;
+    if (!record(result.availability) || !record(result.diagnostics))
+        return null;
+    return result;
+}
+function normalizeCheckpointResult(value, queries, classifyQuery) {
+    const item = record(value);
+    const index = item?.index;
+    if (!Number.isSafeInteger(index) || Number(index) < 0 || Number(index) >= queries.length)
+        return null;
+    const query = queries[Number(index)];
+    if (typeof item?.query !== 'string' || item.query !== query)
+        return null;
+    if (item.ok === false) {
+        if (typeof item.error !== 'string' || !item.error || item.error.length > 300)
+            return null;
+        return { index: Number(index), query, ok: false, error: item.error };
+    }
+    const result = normalizeCompactResult(item.result);
+    if (item.ok !== true || !result)
+        return null;
+    const classified = classifyQuery(query);
+    const storedClassified = record(item.classified);
+    if (storedClassified?.type !== classified.type || storedClassified.value !== classified.value)
+        return null;
+    return { index: Number(index), query, ok: true, classified, result };
+}
+function parseBulkCheckpoint(text, options) {
+    if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > MAX_BULK_CHECKPOINT_BYTES) {
+        throw new CliUsageError(`Bulk checkpoint input is limited to ${MAX_BULK_CHECKPOINT_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('Bulk checkpoint must be valid JSON.');
+    }
+    const document = record(parsed);
+    const expectedDigest = checkpointDigest(options.queries, options.deep);
+    if (document?.schema !== CLI_BULK_CHECKPOINT_SCHEMA || document.version !== CLI_BULK_CHECKPOINT_VERSION) {
+        throw new CliUsageError(`Bulk checkpoint must use ${CLI_BULK_CHECKPOINT_SCHEMA} version ${CLI_BULK_CHECKPOINT_VERSION}.`);
+    }
+    if (document.mode !== (options.deep ? 'deep' : 'fast')
+        || document.inputDigestSha256 !== expectedDigest
+        || document.queryCount !== options.queries.length) {
+        throw new CliUsageError('Bulk checkpoint does not match the current input or scan mode.');
+    }
+    if (!validTimestamp(document.startedAt) || !validTimestamp(document.updatedAt) || !Array.isArray(document.results)) {
+        throw new CliUsageError('Bulk checkpoint metadata is invalid.');
+    }
+    const results = [];
+    const seen = new Set();
+    for (const candidate of document.results.slice(0, options.queries.length + 1)) {
+        const result = normalizeCheckpointResult(candidate, options.queries, options.classifyQuery);
+        if (!result || seen.has(result.index))
+            throw new CliUsageError('Bulk checkpoint contains an invalid or duplicate result.');
+        seen.add(result.index);
+        results.push(result);
+    }
+    return {
+        schema: CLI_BULK_CHECKPOINT_SCHEMA,
+        version: CLI_BULK_CHECKPOINT_VERSION,
+        mode: options.deep ? 'deep' : 'fast',
+        inputDigestSha256: expectedDigest,
+        queryCount: options.queries.length,
+        startedAt: new Date(document.startedAt).toISOString(),
+        updatedAt: new Date(document.updatedAt).toISOString(),
+        results: results.sort((left, right) => left.index - right.index),
+    };
+}
+async function readCheckpointFile(path) {
+    const handle = await open(path, 'r');
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile() || stats.size > MAX_BULK_CHECKPOINT_BYTES) {
+            throw new CliUsageError(`Bulk checkpoint input is limited to ${MAX_BULK_CHECKPOINT_BYTES} bytes.`);
+        }
+        return await handle.readFile({ encoding: 'utf8' });
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function checkpointFileExists(path) {
+    try {
+        const handle = await open(path, 'r');
+        await handle.close();
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error ? error.code : null;
+        if (code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function createBulkCheckpointWriter(options) {
+    const now = options.now || (() => new Date().toISOString());
+    const exists = await checkpointFileExists(options.path);
+    if (options.resume && !exists)
+        throw new CliUsageError('Bulk checkpoint does not exist; remove --resume to start a new checkpoint.');
+    if (!options.resume && exists)
+        throw new CliUsageError('Bulk checkpoint already exists; use --resume or choose another path.');
+    const resumed = options.resume
+        ? parseBulkCheckpoint(await readCheckpointFile(options.path), options)
+        : null;
+    const startedAt = resumed?.startedAt || now();
+    const results = new Map((resumed?.results || []).map((item) => [item.index, item]));
+    let chain = Promise.resolve();
+    let writeFailure = null;
+    let created = resumed !== null;
+    function document() {
+        const updatedAt = now();
+        return {
+            schema: CLI_BULK_CHECKPOINT_SCHEMA,
+            version: CLI_BULK_CHECKPOINT_VERSION,
+            mode: options.deep ? 'deep' : 'fast',
+            inputDigestSha256: checkpointDigest(options.queries, options.deep),
+            queryCount: options.queries.length,
+            startedAt,
+            updatedAt,
+            results: [...results.values()].sort((left, right) => left.index - right.index),
+        };
+    }
+    function scheduleWrite() {
+        chain = chain.then(async () => {
+            if (writeFailure)
+                return;
+            try {
+                const content = `${JSON.stringify(document(), null, 2)}\n`;
+                if (Buffer.byteLength(content, 'utf8') > MAX_BULK_CHECKPOINT_BYTES) {
+                    throw new CliUsageError(`Bulk checkpoints are limited to ${MAX_BULK_CHECKPOINT_BYTES} bytes.`);
+                }
+                await writePrivateFile(options.path, content, {
+                    force: created,
+                    existingFileMessage: 'Bulk checkpoint already exists; use --resume or choose another path.',
+                });
+                created = true;
+            }
+            catch (error) {
+                writeFailure = error;
+            }
+        });
+    }
+    if (!resumed)
+        scheduleWrite();
+    return Object.freeze({
+        initialResults: Object.freeze([...results.values()].sort((left, right) => left.index - right.index)),
+        record(result) {
+            const normalized = normalizeCheckpointResult(result, options.queries, options.classifyQuery);
+            if (!normalized) {
+                writeFailure ||= new CliUsageError('Bulk checkpoint result is not a bounded compact lookup result.');
+                return;
+            }
+            results.set(normalized.index, normalized);
+            scheduleWrite();
+        },
+        async flush() {
+            await chain;
+            if (writeFailure)
+                throw writeFailure;
+        },
+    });
+}
+export { createBulkCheckpointWriter, parseBulkCheckpoint, };

package/cli/bulk-command-runner.mjs

@@ -0,0 +1,109 @@
+import { createReadStream } from 'node:fs';
+import { classifyQuery } from "../lib/classify.mjs";
+import { runUnifiedLookup } from "../lib/lookup.mjs";
+import { createBulkCheckpointWriter } from "./bulk-checkpoint.mjs";
+import { MAX_BULK_INPUT_BYTES, parseBulkQueries, readTextStreamBounded, runBulkLookups, } from "./bulk.mjs";
+import { formatBulkCsv, formatBulkDomainList, selectBulkItems } from "./bulk-output.mjs";
+import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+import { buildCliBulkDocument, formatJsonDocument, formatJsonLines } from "./formatters/json.mjs";
+import { formatTerminalBulk } from "./formatters/terminal.mjs";
+import { createCliProgressEvents } from "./progress-events.mjs";
+async function runBulkCommand(args, dependencies, context) {
+    const eventProgress = createCliProgressEvents(context.stderr, {
+        command: 'bulk',
+        enabled: args.events,
+        ...(dependencies.now ? { now: dependencies.now } : {}),
+    });
+    context.setEventProgress(eventProgress);
+    eventProgress.emit({ event: 'started' });
+    let input;
+    try {
+        input = dependencies.readBulkInput
+            ? await dependencies.readBulkInput(args.source)
+            : await readTextStreamBounded(args.source
+                ? createReadStream(args.source, { highWaterMark: 64 * 1024 })
+                : dependencies.stdin || process.stdin, MAX_BULK_INPUT_BYTES);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read bulk input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    const parsed = parseBulkQueries(input, { deep: args.deep });
+    const classify = dependencies.classifyQuery || classifyQuery;
+    const checkpointWriter = dependencies.createBulkCheckpointWriter || createBulkCheckpointWriter;
+    const checkpoint = args.checkpoint
+        ? await checkpointWriter({
+            path: args.checkpoint,
+            queries: parsed.queries,
+            deep: args.deep,
+            resume: args.resume,
+            classifyQuery: classify,
+            ...(dependencies.now ? { now: dependencies.now } : {}),
+        })
+        : null;
+    const indicator = context.beginProgress(`Collecting 0 of ${parsed.queries.length} targets`);
+    let completed = checkpoint?.initialResults.length || 0;
+    if (completed)
+        indicator.update(`Resumed ${completed} of ${parsed.queries.length} targets`);
+    let items;
+    let checkpointFailure = null;
+    try {
+        items = await runBulkLookups(parsed.queries, {
+            deep: args.deep,
+            concurrency: args.concurrency,
+            classifyQuery: classify,
+            runUnifiedLookup: dependencies.runUnifiedLookup || runUnifiedLookup,
+            ...(checkpoint ? { initialResults: checkpoint.initialResults } : {}),
+            ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+            onItemSettled: (item) => {
+                completed += 1;
+                indicator.update(`Collected ${completed} of ${parsed.queries.length} targets`);
+                eventProgress.emit({ event: 'item_settled', index: item.index, ok: item.ok });
+                checkpoint?.record(item);
+            },
+        });
+    }
+    finally {
+        context.endProgress();
+        try {
+            await checkpoint?.flush();
+        }
+        catch (error) {
+            checkpointFailure = error;
+        }
+    }
+    const metadata = {
+        deep: args.deep,
+        duplicates: parsed.duplicates,
+        generatedAt: context.now(),
+        collectedTotal: items.length,
+        filter: args.filter,
+    };
+    const selectedItems = selectBulkItems(items, args.filter);
+    if (!args.quiet) {
+        if (args.output === 'json')
+            context.writeStdout(formatJsonDocument(buildCliBulkDocument(selectedItems, metadata)));
+        else if (args.output === 'jsonl')
+            context.writeStdout(formatJsonLines(selectedItems, metadata));
+        else if (args.output === 'csv')
+            context.writeStdout(formatBulkCsv(selectedItems));
+        else if (args.output === 'domains')
+            context.writeStdout(formatBulkDomainList(selectedItems));
+        else
+            context.writeStdout(context.terminal(formatTerminalBulk(selectedItems, metadata), args.color));
+    }
+    if (checkpointFailure) {
+        eventProgress.emit({ event: 'warning', state: 'checkpoint_unavailable' });
+        if (!eventProgress.enabled) {
+            context.writeStderr(`Checkpoint warning: ${boundedCliErrorMessage(checkpointFailure, 'Checkpoint could not be written')}. Completed output is still available.\n`);
+        }
+    }
+    const exitCode = checkpointFailure || items.some((item) => !item.ok)
+        ? EXIT_CODES.PARTIAL_FAILURE
+        : EXIT_CODES.SUCCESS;
+    eventProgress.emit({ event: 'completed', exitCode });
+    return exitCode;
+}
+export { runBulkCommand };

package/cli/bulk-output.mjs

@@ -0,0 +1,112 @@
+import { cliCsvCell } from "./csv.mjs";
+const REGISTERED_STATES = new Set(['expiring', 'for_sale', 'registered']);
+const MAX_DNS_VALUES_PER_TYPE = 100;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maximum = 500) {
+    return typeof value === 'string'
+        ? value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        : '';
+}
+function availabilityState(item) {
+    return item.ok ? boundedText(record(record(item.result).availability).state, 40).toLowerCase() : '';
+}
+function selectBulkItems(items, filter) {
+    if (filter === 'all')
+        return [...items];
+    return items.filter((item) => {
+        if (!item.ok)
+            return filter === 'inconclusive';
+        const state = availabilityState(item);
+        return filter === 'registered' ? REGISTERED_STATES.has(state) : state === 'unknown';
+    });
+}
+function stringValues(value) {
+    if (!Array.isArray(value))
+        return [];
+    const output = new Set();
+    for (const candidate of value.slice(0, MAX_DNS_VALUES_PER_TYPE * 2)) {
+        const normalized = boundedText(candidate, 500);
+        if (normalized)
+            output.add(normalized);
+        if (output.size >= MAX_DNS_VALUES_PER_TYPE)
+            break;
+    }
+    return [...output];
+}
+function mxValues(value) {
+    if (!Array.isArray(value))
+        return [];
+    const output = new Set();
+    for (const candidate of value.slice(0, MAX_DNS_VALUES_PER_TYPE * 2)) {
+        const item = record(candidate);
+        const exchange = boundedText(item.exchange ?? item.host ?? candidate, 253).replace(/\.$/u, '').toLowerCase();
+        const priority = Number.isInteger(item.priority) ? Number(item.priority) : null;
+        if (exchange)
+            output.add(priority === null ? exchange : `${priority} ${exchange}`);
+        if (output.size >= MAX_DNS_VALUES_PER_TYPE)
+            break;
+    }
+    return [...output];
+}
+function bulkDnsSummary(item) {
+    if (!item.ok) {
+        return {
+            status: 'unavailable', a: [], aaaa: [], ns: [], mx: [],
+            hasNullMx: null, hasSpf: null, hasDmarc: null,
+        };
+    }
+    const availability = record(record(item.result).availability);
+    const dns = record(availability.dns);
+    const records = record(dns.records);
+    return {
+        status: boundedText(dns.status, 40) || 'unavailable',
+        a: stringValues(records.a),
+        aaaa: stringValues(records.aaaa),
+        ns: stringValues(records.ns),
+        mx: mxValues(records.mx),
+        hasNullMx: typeof availability.hasNullMx === 'boolean' ? availability.hasNullMx : null,
+        hasSpf: typeof availability.hasSpf === 'boolean' ? availability.hasSpf : null,
+        hasDmarc: typeof availability.hasDmarc === 'boolean' ? availability.hasDmarc : null,
+    };
+}
+function booleanCell(value) {
+    return value === null ? 'unknown' : value ? 'observed' : 'not_observed';
+}
+function formatBulkCsv(items) {
+    const header = [
+        'query', 'domain', 'outcome', 'availability', 'confidence', 'dns_status',
+        'a', 'aaaa', 'ns', 'mx', 'null_mx', 'spf', 'dmarc', 'error',
+    ];
+    const rows = items.map((item) => {
+        const availability = item.ok ? record(record(item.result).availability) : {};
+        const dns = bulkDnsSummary(item);
+        return [
+            item.query,
+            item.ok && item.classified.type === 'domain' ? item.classified.registrableDomain || item.classified.value : '',
+            item.ok ? 'complete' : 'error',
+            item.ok ? boundedText(availability.state, 40) || 'unknown' : 'unknown',
+            item.ok ? boundedText(availability.confidence, 40) || 'unknown' : 'unknown',
+            dns.status,
+            dns.a,
+            dns.aaaa,
+            dns.ns,
+            dns.mx,
+            booleanCell(dns.hasNullMx),
+            booleanCell(dns.hasSpf),
+            booleanCell(dns.hasDmarc),
+            item.ok ? '' : item.error,
+        ].map(cliCsvCell).join(',');
+    });
+    return `${[header.join(','), ...rows].join('\n')}\n`;
+}
+function formatBulkDomainList(items) {
+    const values = items.flatMap((item) => item.ok && item.classified.type === 'domain'
+        ? [item.classified.registrableDomain || item.classified.value]
+        : []);
+    return values.length ? `${[...new Set(values)].join('\n')}\n` : '';
+}
+export { REGISTERED_STATES, availabilityState, bulkDnsSummary, formatBulkCsv, formatBulkDomainList, selectBulkItems, };