@slicedearth/whoisleuth-cli 1.36.1 → 1.43.0

package/cli/investigation-manifest.mjs

@@ -0,0 +1,113 @@
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { canonicalArtifactJson, sha256ArtifactDigest, } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { recordOrNull, requireBoundedString, requireIsoTimestamp, } from "../lib/bounded-contract-normalizers.mjs";
+import { normalizeBoundedSemanticVersion } from "../lib/semantic-version.mjs";
+export const INVESTIGATION_MANIFEST_SCHEMA = 'whoisleuth.investigation-manifest';
+export const INVESTIGATION_MANIFEST_VERSION = 1;
+export const MAX_INVESTIGATION_MANIFEST_ARTIFACTS = 16;
+export const MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES = 15 * 1024 * 1024;
+export const MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES = 32 * 1024 * 1024;
+const SHA256_RE = /^sha256:[a-f0-9]{64}$/u;
+function digest(value) {
+    return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+function artifactVersion(value) {
+    const candidate = value.version ?? value.schemaVersion;
+    return Number.isSafeInteger(candidate) && Number(candidate) > 0 && Number(candidate) <= 1_000
+        ? Number(candidate)
+        : null;
+}
+export async function buildInvestigationManifest(input, generatedAtValue, applicationVersionValue) {
+    if (!Array.isArray(input.artifacts)
+        || input.artifacts.length < 1
+        || input.artifacts.length > MAX_INVESTIGATION_MANIFEST_ARTIFACTS) {
+        throw new TypeError(`A manifest requires between 1 and ${MAX_INVESTIGATION_MANIFEST_ARTIFACTS} JSON artefacts.`);
+    }
+    const generatedAt = requireIsoTimestamp(generatedAtValue, 'generatedAt');
+    const workflow = requireBoundedString(input.workflow, 'workflow', 160);
+    const applicationVersion = normalizeBoundedSemanticVersion(applicationVersionValue, 'Application');
+    const configurationDigestSha256 = input.configurationDigestSha256;
+    if (configurationDigestSha256 !== null && !SHA256_RE.test(configurationDigestSha256)) {
+        throw new TypeError('configurationDigestSha256 must be a sha256: hexadecimal digest.');
+    }
+    let totalBytes = 0;
+    const artifacts = input.artifacts.map((artifact, index) => {
+        if (typeof artifact.content !== 'string')
+            throw new TypeError(`Artifact ${index + 1} must be UTF-8 JSON text.`);
+        const byteLength = Buffer.byteLength(artifact.content, 'utf8');
+        totalBytes += byteLength;
+        if (byteLength < 1 || byteLength > MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES) {
+            throw new TypeError(`Artifact ${index + 1} must be between 1 byte and ${MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES} bytes.`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(artifact.content);
+        }
+        catch {
+            throw new TypeError(`Artifact ${index + 1} must be valid JSON.`);
+        }
+        const value = recordOrNull(parsed);
+        if (!value)
+            throw new TypeError(`Artifact ${index + 1} must contain one JSON object.`);
+        const schema = value.schema === undefined
+            ? null
+            : requireBoundedString(value.schema, `Artifact ${index + 1} schema`, 160);
+        const canonical = canonicalArtifactJson(value);
+        const contentDigestSha256 = digest(artifact.content);
+        return Object.freeze({
+            sequence: index + 1,
+            id: `artifact-${index + 1}`,
+            schema,
+            version: artifactVersion(value),
+            byteLength,
+            contentDigestSha256,
+            canonicalDigestSha256: digest(canonical),
+        });
+    });
+    if (totalBytes > MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES) {
+        throw new TypeError(`Manifest artefacts exceed the ${MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES}-byte combined limit.`);
+    }
+    const unsigned = Object.freeze({
+        schema: INVESTIGATION_MANIFEST_SCHEMA,
+        version: INVESTIGATION_MANIFEST_VERSION,
+        generatedAt,
+        application: Object.freeze({ name: 'WHOISleuth CLI', version: applicationVersion }),
+        workflow,
+        configuration: Object.freeze({ digestSha256: configurationDigestSha256 }),
+        artifacts: Object.freeze(artifacts),
+        steps: Object.freeze(artifacts.map((artifact) => Object.freeze({
+            sequence: artifact.sequence,
+            artifactId: artifact.id,
+            contentDigestSha256: artifact.contentDigestSha256,
+        }))),
+        summary: Object.freeze({ artifactCount: artifacts.length, totalBytes }),
+        limitations: Object.freeze([
+            'The manifest records ordered content digests, schema metadata, tool version, and an optional configuration digest; it deliberately omits source file paths and content values.',
+            'Reproduction still depends on access to the exact input artefacts, compatible source services, and any separately retained configuration represented by the supplied digest.',
+            'Matching digests establish content identity, not the accuracy, provenance, or current validity of an observation.',
+        ]),
+    });
+    return Object.freeze({
+        ...unsigned,
+        integrity: Object.freeze({ algorithm: 'SHA-256', digestSha256: await sha256ArtifactDigest(unsigned) }),
+    });
+}
+export function formatInvestigationManifest(manifest) {
+    const lines = [
+        'Investigation manifest',
+        `Workflow       ${manifest.workflow}`,
+        `Tool version   ${manifest.application.version}`,
+        `Artifacts      ${manifest.summary.artifactCount}`,
+        `Total bytes    ${manifest.summary.totalBytes}`,
+        `Configuration  ${manifest.configuration.digestSha256 ?? 'not supplied'}`,
+        `Integrity      ${manifest.integrity.digestSha256}`,
+        '',
+        'Ordered artefacts:',
+    ];
+    for (const artifact of manifest.artifacts) {
+        lines.push(`  ${artifact.sequence}. ${artifact.schema ?? 'unversioned JSON'}${artifact.version ? ` v${artifact.version}` : ''} · ${artifact.contentDigestSha256}`);
+    }
+    lines.push('', 'No source file paths or artefact contents are retained in this manifest.', '');
+    return lines.join('\n');
+}

package/cli/investigation-plan.mjs

@@ -15,7 +15,7 @@ const RECIPES = Object.freeze({
         steps: (domain) => Object.freeze([
             step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
             step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Select the reviewed lookup file; the plan never guesses a path.'),
-            step('verify', 'Verify the exported artifact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
+            step('verify', 'Verify the exported artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
         ]),
     }),
     'lookalike-review': Object.freeze({
@@ -89,7 +89,7 @@ export function buildInvestigationPlan(recipeId, subjectValue, generatedAtValue
         limitations: Object.freeze([
             'This document is a fixed plan. It does not execute commands, expand placeholders, make requests, read files, change cases, or submit reports.',
             'Network steps require deliberate execution and disclose the selected target to the sources described by that command.',
-            'Analyst-selection steps require reviewed local artifacts; placeholders are never interpreted as file paths by this planner.',
+            'Analyst-selection steps require reviewed local artefacts; placeholders are never interpreted as file paths by this planner.',
         ]),
     });
 }

package/cli/investigation-run.mjs

@@ -0,0 +1,112 @@
+import { Buffer } from 'node:buffer';
+import { buildInvestigationPlan, } from "./investigation-plan.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const CLI_INVESTIGATION_RUN_SCHEMA = 'whoisleuth.cli.investigation-run';
+export const CLI_INVESTIGATION_RUN_VERSION = 1;
+export const MAX_INVESTIGATION_RUN_BYTES = 24 * 1024 * 1024;
+function boundedResult(value) {
+    if (Buffer.byteLength(value, 'utf8') > MAX_INVESTIGATION_RUN_BYTES) {
+        throw new CliUsageError(`Investigation step output is limited to ${MAX_INVESTIGATION_RUN_BYTES} bytes.`);
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, '').slice(0, MAX_INVESTIGATION_RUN_BYTES);
+    }
+}
+function parseResumeState(input, recipe, subject) {
+    if (!input)
+        return [];
+    if (Buffer.byteLength(input, 'utf8') > MAX_INVESTIGATION_RUN_BYTES)
+        throw new CliUsageError('Investigation resume state exceeds the 24 MiB limit.');
+    let parsed;
+    try {
+        parsed = JSON.parse(input.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('Investigation resume state must be valid JSON.');
+    }
+    const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    if (root.schema !== CLI_INVESTIGATION_RUN_SCHEMA || root.version !== CLI_INVESTIGATION_RUN_VERSION || root.recipe !== recipe || root.subject !== subject || !Array.isArray(root.completedSteps)) {
+        throw new CliUsageError('Investigation resume state must match this versioned recipe and subject.');
+    }
+    return root.completedSteps.slice(0, 16).flatMap((value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return [];
+        const item = value;
+        if (typeof item.id !== 'string' || typeof item.command !== 'string' || !Array.isArray(item.arguments) || !['offline', 'network'].includes(String(item.mode)) || !Number.isSafeInteger(item.exitCode))
+            return [];
+        return [Object.freeze({
+                id: item.id,
+                command: item.command,
+                arguments: Object.freeze(item.arguments.filter((entry) => typeof entry === 'string').slice(0, 32)),
+                mode: item.mode,
+                exitCode: Number(item.exitCode),
+                result: item.result,
+            })];
+    });
+}
+export async function runInvestigationRecipe(recipe, subjectValue, options) {
+    const plan = buildInvestigationPlan(recipe, subjectValue, options.generatedAt);
+    const prior = parseResumeState(options.resumeInput, recipe, plan.subject);
+    const allowedStepIds = new Set(plan.steps.map((step) => step.id));
+    if (prior.some((step) => !allowedStepIds.has(step.id)))
+        throw new CliUsageError('Investigation resume state contains a step outside the fixed recipe.');
+    const completed = [...prior];
+    let state = 'complete';
+    let currentStep = null;
+    for (const step of plan.steps) {
+        if (completed.some((item) => item.id === step.id))
+            continue;
+        currentStep = step;
+        if (step.arguments.some((argument) => /^<[^>]+>$/u.test(argument))) {
+            state = 'awaiting_analyst_selection';
+            break;
+        }
+        if (step.mode === 'network' && !options.approveNetwork) {
+            state = 'awaiting_network_approval';
+            break;
+        }
+        const result = await options.execute(step.command, step.arguments);
+        completed.push(Object.freeze({
+            id: step.id,
+            command: step.command,
+            arguments: step.arguments,
+            mode: step.mode,
+            exitCode: result.exitCode,
+            result: boundedResult(result.stdout),
+        }));
+        if (result.exitCode !== 0 && result.exitCode !== 2) {
+            state = 'step_failed';
+            break;
+        }
+        currentStep = null;
+    }
+    return Object.freeze({
+        schema: CLI_INVESTIGATION_RUN_SCHEMA,
+        version: CLI_INVESTIGATION_RUN_VERSION,
+        generatedAt: options.generatedAt,
+        recipe,
+        subject: plan.subject,
+        state,
+        networkApprovedForThisRun: options.approveNetwork,
+        completedSteps: Object.freeze(completed),
+        currentStep,
+        limitations: Object.freeze([
+            'Only commands and arguments from the installed fixed recipe can execute; no shell, script, arbitrary command, or enforcement action is accepted.',
+            'Network steps run only with --approve-network for the current invocation. Analyst-selection placeholders always pause and are never interpreted as paths or values.',
+            'A resume file is a local checkpoint, not proof that prior evidence remains current or that a human reviewed each stored result.',
+        ]),
+    });
+}
+export function formatInvestigationRun(document) {
+    return [
+        `Investigation run: ${document.recipe}`,
+        `Subject    ${document.subject}`,
+        `State      ${document.state.replaceAll('_', ' ')}`,
+        `Completed  ${document.completedSteps.length}`,
+        ...(document.currentStep ? [`Next       ${document.currentStep.label}`, `Approval   ${document.currentStep.approval.replaceAll('_', ' ')}`] : []),
+        '',
+    ].join('\n');
+}

package/cli/local-mmdb-review.mjs

@@ -0,0 +1,76 @@
+import { stat } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { open } from 'maxmind';
+import { formatIpPrefix, parseIpPrefix } from "../lib/ip-prefix.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const LOCAL_MMDB_QUERY_SCHEMA = 'whoisleuth.local-mmdb-query';
+export const MAX_LOCAL_MMDB_BYTES = 512 * 1024 * 1024;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function boundedText(value, maximum) {
+    return typeof value === 'string' && value.length <= maximum && !/[\u0000-\u001f\u007f]/u.test(value)
+        ? value.replace(/\s+/gu, ' ').trim() || null
+        : null;
+}
+function names(value) {
+    const source = record(value);
+    return boundedText(source.en, 120);
+}
+export async function reviewLocalMmdb(input, databasePath) {
+    const address = boundedText(input.address, 64)?.toLowerCase() ?? '';
+    const sourceLabel = boundedText(input.sourceLabel, 120);
+    const databaseVersion = boundedText(input.databaseVersion, 80);
+    const license = boundedText(input.license, 240);
+    if (!isIP(address))
+        throw new CliUsageError('Local MMDB review requires one valid IP address.');
+    if (!sourceLabel || !databaseVersion || !license) {
+        throw new CliUsageError('Local MMDB review requires bounded sourceLabel, databaseVersion, and licence metadata.');
+    }
+    let info;
+    try {
+        info = await stat(databasePath);
+    }
+    catch {
+        throw new CliUsageError('The supplied MMDB file could not be read.');
+    }
+    if (!info.isFile() || info.size <= 0 || info.size > MAX_LOCAL_MMDB_BYTES) {
+        throw new CliUsageError(`The supplied MMDB must be a file no larger than ${MAX_LOCAL_MMDB_BYTES} bytes.`);
+    }
+    let reader;
+    try {
+        reader = await open(databasePath, { cache: { max: 1_000 } });
+    }
+    catch {
+        throw new CliUsageError('The supplied file is not a readable MaxMind DB database.');
+    }
+    const [rawMatch, prefixLength] = reader.getWithPrefixLength(address);
+    const match = record(rawMatch);
+    const traits = record(match.traits);
+    const country = record(match.country);
+    const registeredCountry = record(match.registered_country);
+    const subdivisions = Array.isArray(match.subdivisions) ? match.subdivisions : [];
+    const subdivision = record(subdivisions[0]);
+    const city = record(match.city);
+    const asnValue = match.autonomous_system_number ?? traits.autonomous_system_number;
+    const asn = typeof asnValue === 'number' && Number.isSafeInteger(asnValue) && asnValue >= 0 ? asnValue : null;
+    const prefix = parseIpPrefix(`${address}/${prefixLength}`);
+    return Object.freeze({
+        state: rawMatch ? 'matched' : 'not_found',
+        address,
+        match: rawMatch ? Object.freeze({
+            network: prefix ? formatIpPrefix(prefix) : null,
+            countryCode: boundedText(country.iso_code ?? registeredCountry.iso_code, 2)?.toUpperCase() ?? null,
+            region: names(subdivision.names) ?? boundedText(subdivision.iso_code, 120),
+            city: names(city.names),
+            asn,
+            asName: boundedText(match.autonomous_system_organization ?? traits.autonomous_system_organization, 240),
+        }) : null,
+        source: Object.freeze({ label: sourceLabel, version: databaseVersion, license }),
+        limitations: Object.freeze([
+            'This CLI-only result comes from an analyst-supplied local MMDB file. WHOISleuth does not bundle, download, update, license, or transmit the database.',
+            'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
+            'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
+        ]),
+    });
+}

package/cli/lookalike-calibration.mjs

@@ -0,0 +1,121 @@
+import { Buffer } from 'node:buffer';
+const LOOKALIKE_CALIBRATION_INPUT_SCHEMA = 'whoisleuth.lookalike-calibration-input';
+const LOOKALIKE_CALIBRATION_SCHEMA = 'whoisleuth.lookalike-calibration';
+const LOOKALIKE_CALIBRATION_VERSION = 1;
+const MAX_LOOKALIKE_CALIBRATION_BYTES = 2 * 1024 * 1024;
+const MAX_LOOKALIKE_CALIBRATION_RECORDS = 5_000;
+const MIN_LOOKALIKE_CALIBRATION_SAMPLE = 20;
+const DISPOSITIONS = ['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action'];
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function token(value, field) {
+    if (typeof value !== 'string')
+        throw new TypeError(`${field} must be text.`);
+    const normalized = value.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]{0,79}$/u.test(normalized))
+        throw new TypeError(`${field} must be a bounded identifier.`);
+    return normalized;
+}
+function ratio(value, total) {
+    return total ? Number((value / total).toFixed(4)) : 0;
+}
+function emptyCounts() {
+    return { suspicious: 0, confirmed_abuse: 0, false_positive: 0, expected: 0, closed_no_action: 0 };
+}
+function buildLookalikeCalibration(raw, generatedAt = new Date().toISOString()) {
+    if (Buffer.byteLength(raw, 'utf8') > MAX_LOOKALIKE_CALIBRATION_BYTES) {
+        throw new TypeError(`Lookalike calibration input is limited to ${MAX_LOOKALIKE_CALIBRATION_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TypeError('Lookalike calibration input must be valid JSON.');
+    }
+    const input = record(parsed);
+    if (input.schema !== LOOKALIKE_CALIBRATION_INPUT_SCHEMA || input.version !== LOOKALIKE_CALIBRATION_VERSION) {
+        throw new TypeError(`Lookalike calibration input must use ${LOOKALIKE_CALIBRATION_INPUT_SCHEMA} version ${LOOKALIKE_CALIBRATION_VERSION}.`);
+    }
+    if (!Array.isArray(input.records) || input.records.length < 1 || input.records.length > MAX_LOOKALIKE_CALIBRATION_RECORDS) {
+        throw new TypeError(`Lookalike calibration input must contain from 1 to ${MAX_LOOKALIKE_CALIBRATION_RECORDS} reviewed records.`);
+    }
+    const ids = new Set();
+    const familyCounts = new Map();
+    const totalCounts = emptyCounts();
+    for (let index = 0; index < input.records.length; index++) {
+        const item = record(input.records[index]);
+        const id = token(item.id, `records[${index}].id`);
+        if (ids.has(id))
+            throw new TypeError(`Lookalike calibration record id "${id}" is duplicated.`);
+        ids.add(id);
+        if (typeof item.disposition !== 'string' || !DISPOSITIONS.includes(item.disposition)) {
+            throw new TypeError(`records[${index}].disposition is not a supported reviewed disposition.`);
+        }
+        const disposition = item.disposition;
+        if (!Array.isArray(item.mutationFamilies) || item.mutationFamilies.length < 1 || item.mutationFamilies.length > 12) {
+            throw new TypeError(`records[${index}].mutationFamilies must contain from 1 to 12 identifiers.`);
+        }
+        const families = [...new Set(item.mutationFamilies.map((value) => token(value, `records[${index}].mutationFamilies`)))];
+        totalCounts[disposition] += 1;
+        for (const family of families) {
+            const counts = familyCounts.get(family) || emptyCounts();
+            counts[disposition] += 1;
+            familyCounts.set(family, counts);
+        }
+    }
+    const families = [...familyCounts.entries()].map(([id, dispositions]) => {
+        const reviewedCandidates = Object.values(dispositions).reduce((sum, count) => sum + count, 0);
+        return {
+            id,
+            reviewedCandidates,
+            sampleState: reviewedCandidates >= MIN_LOOKALIKE_CALIBRATION_SAMPLE ? 'reviewed' : 'insufficient',
+            dispositions,
+            reviewLeadRate: ratio(dispositions.suspicious + dispositions.confirmed_abuse, reviewedCandidates),
+            falsePositiveRate: ratio(dispositions.false_positive, reviewedCandidates),
+        };
+    }).sort((left, right) => right.reviewedCandidates - left.reviewedCandidates || left.id.localeCompare(right.id));
+    const reviewedCandidates = input.records.length;
+    return {
+        schema: LOOKALIKE_CALIBRATION_SCHEMA,
+        version: LOOKALIKE_CALIBRATION_VERSION,
+        generatedAt,
+        summary: {
+            reviewedCandidates,
+            mutationFamilies: families.length,
+            sampleState: reviewedCandidates >= MIN_LOOKALIKE_CALIBRATION_SAMPLE ? 'reviewed' : 'insufficient',
+            reviewLeadRate: ratio(totalCounts.suspicious + totalCounts.confirmed_abuse, reviewedCandidates),
+            falsePositiveRate: ratio(totalCounts.false_positive, reviewedCandidates),
+            expectedRate: ratio(totalCounts.expected, reviewedCandidates),
+        },
+        families,
+        privacy: { candidateIdsRetained: 0, domainsRetained: 0, notesRetained: 0 },
+        limitations: [
+            'This offline report summarises analyst dispositions for the supplied reviewed sample and never changes mutation generation, ordering, Risk, or filtering automatically.',
+            'Suspicious and confirmed-abuse dispositions are counted as review leads, not proof of maliciousness; expected and false-positive dispositions are not proof of safety.',
+            `A family remains an insufficient sample below ${MIN_LOOKALIKE_CALIBRATION_SAMPLE} reviewed candidates, and even larger local samples may not generalize across brands, languages, registries, or time.`,
+            'Candidate identifiers, domains, notes, and evidence are intentionally omitted from output. Retain the reviewed source dataset under an appropriate local privacy policy.',
+        ],
+    };
+}
+function formatLookalikeCalibration(report) {
+    const output = [
+        'Lookalike review-yield calibration',
+        `Reviewed candidates ${report.summary.reviewedCandidates}`,
+        `Mutation families   ${report.summary.mutationFamilies}`,
+        `Sample state        ${report.summary.sampleState}`,
+        `Review-lead rate    ${(report.summary.reviewLeadRate * 100).toFixed(1)}%`,
+        `False-positive rate ${(report.summary.falsePositiveRate * 100).toFixed(1)}%`,
+        '',
+    ];
+    for (const family of report.families) {
+        output.push(`${family.id} [${family.sampleState}]`);
+        output.push(`  ${family.reviewedCandidates} reviewed · ${(family.reviewLeadRate * 100).toFixed(1)}% review leads · ${(family.falsePositiveRate * 100).toFixed(1)}% false positives`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of report.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { LOOKALIKE_CALIBRATION_INPUT_SCHEMA, LOOKALIKE_CALIBRATION_SCHEMA, LOOKALIKE_CALIBRATION_VERSION, MAX_LOOKALIKE_CALIBRATION_BYTES, MAX_LOOKALIKE_CALIBRATION_RECORDS, MIN_LOOKALIKE_CALIBRATION_SAMPLE, buildLookalikeCalibration, formatLookalikeCalibration, };

package/cli/lookup-brief.mjs

@@ -0,0 +1,116 @@
+import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+export const CLI_LOOKUP_BRIEF_SCHEMA = 'whoisleuth.cli.lookup-brief';
+export const CLI_LOOKUP_BRIEF_VERSION = 2;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function text(value, maximum = 300) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum);
+    return normalized || null;
+}
+function sourceState(value) {
+    return text(value, 40)?.toLowerCase() ?? 'unavailable';
+}
+export function buildCliLookupBrief(input, generatedAt = new Date().toISOString()) {
+    const document = parseSavedLookupDocument(input, { label: 'Lookup brief input' });
+    const diagnostics = record(document.diagnostics);
+    const availability = record(document.availability);
+    const rdap = record(record(document.rdap).parsed);
+    const whois = record(record(document.whois).parsed);
+    const preferred = Object.keys(rdap).length ? rdap : whois;
+    const sources = ['rdap', 'whois', 'availability', 'dns', 'http', 'tls'].map((id) => {
+        const nested = id === 'dns' || id === 'http' || id === 'tls' ? record(availability[id]) : record(diagnostics[id]);
+        return Object.freeze({ id, state: sourceState(nested.status ?? nested.state), observedAt: text(nested.observedAt ?? nested.fetchedAt ?? nested.queriedAt, 64) });
+    });
+    const facts = [
+        ['Registration state', availability.state, 'Authority-aware availability'],
+        ['Registrar', record(preferred.registrar).name ?? preferred.registrar, Object.keys(rdap).length ? 'Registry RDAP' : 'WHOIS'],
+        ['Created', record(preferred.lifecycle).createdIso ?? preferred.createdDateIso, Object.keys(rdap).length ? 'Registry RDAP' : 'WHOIS'],
+        ['Expires', record(preferred.lifecycle).expiryIso ?? preferred.expiryDateIso, Object.keys(rdap).length ? 'Registry RDAP' : 'WHOIS'],
+        ['Website activity', availability.activityStatus, 'HTTP'],
+        ['Page title', availability.pageTitle, 'Static page identity'],
+    ].flatMap(([label, value, source]) => {
+        const normalized = text(value);
+        return normalized ? [Object.freeze({ label: String(label), value: normalized, source: String(source) })] : [];
+    });
+    const incomplete = sources.filter((item) => !['complete', 'success'].includes(item.state));
+    const analysis = record(document.analysis);
+    const contradictions = [analysis.registryComparison, document.registryComparison, document.registrarPublicationComparison]
+        .flatMap((value) => Array.isArray(record(value).fields) ? record(value).fields : [])
+        .flatMap((value) => {
+        const item = record(value);
+        return item.status === 'conflict' ? [text(item.label, 120) ?? 'Registration publication conflict'] : [];
+    }).slice(0, 16);
+    const actionPlan = [
+        ...(contradictions.length ? [{
+                id: 'registration-publication-review',
+                action: 'Review the separately attributed registration publications before relying on the conflicting fields.',
+                reason: `${contradictions.length} conflicting publication field${contradictions.length === 1 ? '' : 's'} were retained.`,
+                expectedOutcome: 'Establish which observation is current, authoritative, or still unresolved.',
+                evidence: 'registry publication comparison',
+            }] : []),
+        ...(incomplete.length ? [{
+                id: 'source-state-review',
+                action: `Refresh or explain the ${incomplete.map((item) => item.id).join(', ')} source state before treating missing values as meaningful.`,
+                reason: 'At least one source was not complete in the saved observation.',
+                expectedOutcome: 'Determine whether each limitation is transient, persistent, or expected for that source.',
+                evidence: 'source health',
+            }] : []),
+        ...(document.mode === 'fast' ? [{
+                id: 'collection-depth-review',
+                action: 'Run a deliberate Deep lookup if DNS, HTTP, TLS, page, or network evidence is required.',
+                reason: 'The saved observation used the intentionally narrower Fast contract.',
+                expectedOutcome: 'Collect the explicitly selected additional source classes without implying that unavailable evidence is absent.',
+                evidence: 'collection mode',
+            }] : []),
+        {
+            id: 'case-evidence-review',
+            action: 'Pin only the facts needed for the decision and keep analyst hypotheses separate from observations.',
+            reason: 'The brief organises one observation but does not create an analyst decision.',
+            expectedOutcome: 'Preserve a reviewable boundary between observed facts, hypotheses, unknowns, and decisions.',
+            evidence: 'case workflow',
+        },
+    ].slice(0, 6).map((item) => Object.freeze(item));
+    const recommendedActions = actionPlan.map((item) => item.action);
+    return Object.freeze({
+        schema: CLI_LOOKUP_BRIEF_SCHEMA,
+        version: CLI_LOOKUP_BRIEF_VERSION,
+        generatedAt,
+        target: document.registrableDomain,
+        observedAt: document.generatedAt,
+        mode: document.mode,
+        facts: Object.freeze(facts),
+        sourceHealth: Object.freeze(sources),
+        contradictions: Object.freeze(contradictions),
+        unknowns: Object.freeze(incomplete.map((item) => `${item.id}: ${item.state}`)),
+        actionPlan: Object.freeze(actionPlan),
+        recommendedActions: Object.freeze(recommendedActions.slice(0, 6)),
+        limitations: Object.freeze([
+            'This brief is derived from one saved Lookup and makes no request.',
+            'It organises bounded facts and uncertainty but does not create an analyst assertion, decide maliciousness, or establish current state.',
+            'Raw registry, provider, HTTP and page payloads are excluded.',
+        ]),
+    });
+}
+export function formatCliLookupBrief(document) {
+    return [
+        `Lookup brief: ${document.target}`,
+        `Observed  ${document.observedAt}`,
+        `Mode      ${document.mode}`,
+        '',
+        'Verified facts',
+        ...(document.facts.length ? document.facts.map((item) => `  ${item.label}: ${item.value} (${item.source})`) : ['  No bounded fact was available.']),
+        '',
+        'Unknown or incomplete',
+        ...(document.unknowns.length ? document.unknowns.map((item) => `  ${item}`) : ['  No incomplete source state was identified.']),
+        '',
+        'Recommended manual actions',
+        ...document.actionPlan.flatMap((item, index) => [
+            `  ${index + 1}. ${item.action}`,
+            `     Expected outcome: ${item.expectedOutcome}`,
+        ]),
+        '',
+    ].join('\n');
+}

package/cli/lookup-command-runner.mjs

@@ -11,6 +11,8 @@ import { formatTerminalLookup } from "./formatters/terminal.mjs";
 import { buildCliLookupPlan, formatCliLookupPlan } from "./lookup-plan.mjs";
 import { createCliProgressEvents } from "./progress-events.mjs";
 import { lookupStrictExitFindings } from "./strict-exit.mjs";
+import { evaluateCliFailPolicies, formatFailPolicyNotice } from "./fail-policy.mjs";
+import { formatCliJunit } from "./ci-report.mjs";
 async function runLookupCommand(args, dependencies, context) {
     const eventProgress = createCliProgressEvents(context.stderr, {
         command: 'lookup',
@@ -68,10 +70,15 @@ async function runLookupCommand(args, dependencies, context) {
         context.endProgress();
     }
     const now = context.now();
-    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast');
+    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast', {
+        ...(args.observerLabel ? { observerLabel: args.observerLabel } : {}),
+        ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
+    });
     if (!args.quiet) {
         if (args.output === 'json')
             context.writeStdout(formatJsonDocument(document));
+        else if (args.output === 'junit')
+            context.writeStdout(formatCliJunit(document));
         else if (args.output === 'markdown' || args.output === 'html') {
             const loadEvidence = dependencies.loadEvidenceExport || (() => import("../lib/evidence-export.mjs"));
             const evidenceModule = await loadEvidence();
@@ -85,10 +92,13 @@ async function runLookupCommand(args, dependencies, context) {
         }
     }
     const strictFindings = args.strictExit ? lookupStrictExitFindings(document) : [];
-    const exitCode = strictFindings.length ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+    const policyFindings = evaluateCliFailPolicies(document, args.failOn || []);
+    const exitCode = strictFindings.length || policyFindings.length ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
     if (strictFindings.length && !args.events) {
         context.writeStderr(`Strict exit: ${strictFindings.length} requested source state${strictFindings.length === 1 ? '' : 's'} were incomplete.\n`);
     }
+    if (policyFindings.length && !args.events)
+        context.writeStderr(formatFailPolicyNotice(policyFindings));
     eventProgress.emit({ event: 'completed', exitCode });
     return exitCode;
 }