@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/README.md

@@ -50,6 +50,7 @@ node bin/whoisleuth.mts --help
 node bin/whoisleuth.mts lookup example.test
 node bin/whoisleuth.mts lookup example.test --deep --summary
 node bin/whoisleuth.mts lookup example.test --deep --plan --json
+node bin/whoisleuth.mts lookup example.test --deep --observer workstation-a --vantage office-egress --json
 node bin/whoisleuth.mts lookup example.test --deep --markdown --output lookup.md
 node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json
 node bin/whoisleuth.mts bulk domains.txt --csv --registered-only
@@ -58,9 +59,16 @@ node bin/whoisleuth.mts discover example.test --dictionary private-terms.txt --s
 node bin/whoisleuth.mts discover-scan example.test --scan-limit 50 --checkpoint candidate-scan.json --json
 node bin/whoisleuth.mts page-compare official.json candidate.json --json
 node bin/whoisleuth.mts mail-review bulk.json --json
+node bin/whoisleuth.mts domain-control domain-control-input.json --json
+node bin/whoisleuth.mts assurance domain-assurance-input.json --json
+node bin/whoisleuth.mts sharing-review response-packet.json --marking amber --recipient-scope organization --purpose 'Reviewed handoff' --human-reviewed --personal-data-reviewed --redactions-confirmed --json
+node bin/whoisleuth.mts workflow-plan domain-triage example.test --json
 node bin/whoisleuth.mts diff first-lookup.json second-lookup.json --json
+node bin/whoisleuth.mts reconcile office.json mobile.json external.json --json
 node bin/whoisleuth.mts timeline first-observation.json second-observation.json latest-observation.json --json
 node bin/whoisleuth.mts registry-support example.test --json
+node bin/whoisleuth.mts registry-doctor lookup.json --json
+node bin/whoisleuth.mts lookalike-calibrate reviewed-candidates.json --json
 node bin/whoisleuth.mts doctor
 node bin/whoisleuth.mts commands --json
 node bin/whoisleuth.mts completion zsh
@@ -95,10 +103,18 @@ cleanup before exiting immediately.
 
 The offline `timeline` command orders 2 to 20 saved Lookup documents for one
 domain and compares each adjacent observation. It retains observation times and
-normalized field states but no input filenames or raw registry payloads.
+normalised field states but no input filenames or raw registry payloads.
 Observed differences remain separate from missing, unavailable, and changed
 collection conditions.
 
+Optional bounded observer and vantage labels let analysts distinguish saved
+collection contexts without changing collection. `reconcile` compares 2 to 5
+same-domain observations while keeping agreement, disagreement, and
+non-comparable evidence separate; the labels are context, not proof of
+independence. `registry-doctor`, `assurance`, `sharing-review`, and
+`lookalike-calibrate` add offline compatibility, change/recovery, sharing, and
+review-yield workflows without contacting the hosted application.
+
 Bulk also supports fixed-column CSV, domain-only or exact-query output,
 registered, inconclusive, and hard-failure output filters, and bounded A, AAAA,
 NS, and MX summaries. Discover
@@ -113,7 +129,8 @@ lookups can be compared across static page, parse5-tokenized DOM structure,
 favicon, technology, and TLS evidence, while saved Bulk output can be reviewed
 for passive MX, null MX, SPF, DMARC, and shared-provider context.
 
-See `docs/cli.md` in the package for the complete command, privacy, output, and
+See `docs/cli.md` in the package for installation and first use, and
+`docs/cli-reference.md` for the complete command, privacy, output, and
 evidence-contract reference. Report suspected vulnerabilities through the
 private channel described in `SECURITY.md`.
 

package/bin/whoisleuth.mjs

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
-import { boundedCliErrorMessage } from "../cli/errors.mjs";
-import { cleanupPendingOutputFilesSync } from "../cli/output-file.mjs";
-import { runCli } from "../cli/runner.mjs";
+import { createRequire } from 'node:module';
 for (const stream of [process.stdout, process.stderr]) {
     stream.on('error', (error) => {
         if (error.code === 'EPIPE')
@@ -9,27 +7,46 @@ for (const stream of [process.stdout, process.stderr]) {
         throw error;
     });
 }
-const cancellation = new AbortController();
-let interruptionCount = 0;
-const interrupt = () => {
-    interruptionCount += 1;
-    if (interruptionCount === 1)
-        cancellation.abort(new DOMException('Aborted', 'AbortError'));
+const argv = process.argv.slice(2);
+if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
+    const require = createRequire(import.meta.url);
+    const metadata = require('../package.json');
+    if (typeof metadata.version !== 'string' || !metadata.version) {
+        process.stderr.write('Internal CLI error: Package version is unavailable.\n');
+        process.exitCode = 70;
+    }
     else {
-        cleanupPendingOutputFilesSync();
-        process.exit(130);
+        process.stdout.write(`${metadata.version}\n`);
     }
-};
-process.on('SIGINT', interrupt);
-runCli(process.argv.slice(2), { signal: cancellation.signal }).then((code) => {
-    if (code === 130) {
+}
+else {
+    const [errorsModule, outputModule, runnerModule] = await Promise.all([
+        import("../cli/errors.mjs"),
+        import("../cli/output-file.mjs"),
+        import("../cli/runner.mjs"),
+    ]);
+    const cancellation = new AbortController();
+    let interruptionCount = 0;
+    const interrupt = () => {
+        interruptionCount += 1;
+        if (interruptionCount === 1)
+            cancellation.abort(new DOMException('Aborted', 'AbortError'));
+        else {
+            outputModule.cleanupPendingOutputFilesSync();
+            process.exit(130);
+        }
+    };
+    process.on('SIGINT', interrupt);
+    runnerModule.runCli(argv, { signal: cancellation.signal }).then((code) => {
+        if (code === 130) {
+            process.removeListener('SIGINT', interrupt);
+            process.exit(130);
+        }
+        process.exitCode = code;
+    }).catch((error) => {
+        process.stderr.write(`Internal CLI error: ${errorsModule.boundedCliErrorMessage(error)}\n`);
+        process.exitCode = 70;
+    }).finally(() => {
         process.removeListener('SIGINT', interrupt);
-        process.exit(130);
-    }
-    process.exitCode = code;
-}).catch((error) => {
-    process.stderr.write(`Internal CLI error: ${boundedCliErrorMessage(error)}\n`);
-    process.exitCode = 70;
-}).finally(() => {
-    process.removeListener('SIGINT', interrupt);
-});
+    });
+}

package/cli/arguments.mjs

@@ -1,5 +1,6 @@
 import { parseInspectArchiveArguments, parseSignArtifactArguments, parseVerifySignatureArguments, } from "./evidence-command-arguments.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { INVESTIGATION_PLAN_RECIPES, } from "./investigation-plan.mjs";
 const MAX_CLI_ARGUMENTS = 32;
 const MAX_CLI_ARGUMENT_LENGTH = 1024;
 const CLI_COMMANDS = [
@@ -16,7 +17,9 @@ const CLI_COMMANDS = [
     'http',
     'tls',
     'registry-support',
+    'registry-doctor',
     'risk-calibrate',
+    'lookalike-calibrate',
     'verify-artifact',
     'inspect-archive',
     'sign-artifact',
@@ -25,7 +28,13 @@ const CLI_COMMANDS = [
     'compare',
     'page-compare',
     'mail-review',
+    'review-evidence',
+    'domain-control',
+    'assurance',
+    'sharing-review',
+    'workflow-plan',
     'diff',
+    'reconcile',
     'timeline',
     'export',
 ];
@@ -128,8 +137,12 @@ function parseCliArgumentsCore(argv) {
         return parseTlsArguments(argv.slice(1));
     if (command === 'registry-support')
         return parseRegistrySupportArguments(argv.slice(1));
+    if (command === 'registry-doctor')
+        return parseRegistryDoctorArguments(argv.slice(1));
     if (command === 'risk-calibrate')
         return parseRiskCalibrateArguments(argv.slice(1));
+    if (command === 'lookalike-calibrate')
+        return parseLookalikeCalibrateArguments(argv.slice(1));
     if (command === 'verify-artifact')
         return parseVerifyArtifactArguments(argv.slice(1));
     if (command === 'inspect-archive')
@@ -146,8 +159,20 @@ function parseCliArgumentsCore(argv) {
         return parsePageCompareArguments(argv.slice(1));
     if (command === 'mail-review')
         return parseMailReviewArguments(argv.slice(1));
+    if (command === 'review-evidence')
+        return parseReviewEvidenceArguments(argv.slice(1));
+    if (command === 'domain-control')
+        return parseDomainControlArguments(argv.slice(1));
+    if (command === 'assurance')
+        return parseAssuranceArguments(argv.slice(1));
+    if (command === 'sharing-review')
+        return parseSharingReviewArguments(argv.slice(1));
+    if (command === 'workflow-plan')
+        return parseWorkflowPlanArguments(argv.slice(1));
     if (command === 'diff')
         return parseDiffArguments(argv.slice(1));
+    if (command === 'reconcile')
+        return parseReconcileArguments(argv.slice(1));
     if (command === 'timeline')
         return parseTimelineArguments(argv.slice(1));
     if (command === 'export')
@@ -163,7 +188,13 @@ function parseCliArgumentsCore(argv) {
     let strictExit = false;
     let events = false;
     let plan = false;
-    for (const argument of argv.slice(1)) {
+    let observerLabel = null;
+    let vantageLabel = null;
+    const lookupArguments = argv.slice(1);
+    for (let index = 0; index < lookupArguments.length; index++) {
+        const argument = lookupArguments[index];
+        if (argument === undefined)
+            break;
         if (argument === '--json') {
             if (output !== 'terminal')
                 throw new CliUsageError('Choose only one output format.');
@@ -207,6 +238,22 @@ function parseCliArgumentsCore(argv) {
                 throw new CliUsageError('--plan may be supplied only once.');
             plan = true;
         }
+        else if (argument === '--observer' || argument === '--vantage') {
+            const isObserver = argument === '--observer';
+            if (isObserver ? observerLabel !== null : vantageLabel !== null) {
+                throw new CliUsageError(`${argument} may be supplied only once.`);
+            }
+            const value = lookupArguments[++index];
+            if (!value || value.startsWith('-'))
+                throw new CliUsageError(`${argument} requires one bounded label.`);
+            const normalized = value.replace(/\s+/gu, ' ').trim();
+            if (!normalized || normalized.length > 80)
+                throw new CliUsageError(`${argument} requires a label of at most 80 characters.`);
+            if (isObserver)
+                observerLabel = normalized;
+            else
+                vantageLabel = normalized;
+        }
         else if (argument === '--quiet')
             quiet = true;
         else if (argument === '--no-color')
@@ -227,7 +274,7 @@ function parseCliArgumentsCore(argv) {
     if (plan && (detailSet || strictExit || events || quiet)) {
         throw new CliUsageError('--plan cannot be combined with detail, strict-exit, event, or quiet options.');
     }
-    return { action: 'lookup', query, output, deep, detail, strictExit, events, plan, quiet, color };
+    return { action: 'lookup', query, output, deep, detail, strictExit, events, plan, observerLabel, vantageLabel, quiet, color };
 }
 function parseCompletionArguments(argv) {
     if (argv.length !== 1 || !['bash', 'zsh', 'fish', 'powershell'].includes(argv[0] || '')) {
@@ -893,6 +940,200 @@ function parseMailReviewArguments(argv) {
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
     return { action: 'mail-review', source, output, quiet, color };
 }
+function parseReviewEvidenceArguments(argv) {
+    let source = null;
+    let mmdbSource = null;
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === undefined)
+            break;
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--mmdb') {
+            const value = argv[++index];
+            if (!value || value.startsWith('-') || mmdbSource !== null)
+                throw new CliUsageError('--mmdb requires one database file and may be supplied only once.');
+            mmdbSource = value;
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else if (source === null)
+            source = argument;
+        else
+            throw new CliUsageError('review-evidence accepts one optional versioned JSON input file.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'review-evidence', source, mmdbSource, output, quiet, color };
+}
+function parseDomainControlArguments(argv) {
+    let source = null;
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (const argument of argv) {
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else if (source === null)
+            source = argument;
+        else
+            throw new CliUsageError('domain-control accepts one optional versioned JSON input file.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'domain-control', source, output, quiet, color };
+}
+function parseAssuranceArguments(argv) {
+    let source = null;
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (const argument of argv) {
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else if (source === null)
+            source = argument;
+        else
+            throw new CliUsageError('assurance accepts one optional versioned JSON input file.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'assurance', source, output, quiet, color };
+}
+function parseSharingReviewArguments(argv) {
+    let source = null;
+    let output = 'terminal';
+    let marking = null;
+    let recipientScope = null;
+    let purpose = null;
+    let humanReviewed = false;
+    let personalDataReviewed = false;
+    let redactionsConfirmed = false;
+    let quiet = false;
+    let color = true;
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        if (argument === undefined)
+            break;
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--marking') {
+            if (marking !== null)
+                throw new CliUsageError('--marking may be supplied only once.');
+            const value = argv[++index];
+            if (!['clear', 'green', 'amber', 'amber-strict', 'red'].includes(value || '')) {
+                throw new CliUsageError('--marking requires clear, green, amber, amber-strict, or red.');
+            }
+            marking = value;
+        }
+        else if (argument === '--recipient-scope') {
+            if (recipientScope !== null)
+                throw new CliUsageError('--recipient-scope may be supplied only once.');
+            const value = argv[++index];
+            if (!['public', 'community', 'organization', 'named-recipients'].includes(value || '')) {
+                throw new CliUsageError('--recipient-scope requires public, community, organization, or named-recipients.');
+            }
+            recipientScope = value;
+        }
+        else if (argument === '--purpose') {
+            if (purpose !== null)
+                throw new CliUsageError('--purpose may be supplied only once.');
+            const value = argv[++index];
+            if (!value || value.startsWith('-'))
+                throw new CliUsageError('--purpose requires one bounded description.');
+            const normalized = value.replace(/\s+/gu, ' ').trim();
+            if (!normalized || normalized.length > 200)
+                throw new CliUsageError('--purpose is limited to 200 characters.');
+            purpose = normalized;
+        }
+        else if (argument === '--human-reviewed')
+            humanReviewed = true;
+        else if (argument === '--personal-data-reviewed')
+            personalDataReviewed = true;
+        else if (argument === '--redactions-confirmed')
+            redactionsConfirmed = true;
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else if (source === null)
+            source = argument;
+        else
+            throw new CliUsageError('sharing-review accepts one optional artefact JSON file.');
+    }
+    if (!marking || !recipientScope || !purpose) {
+        throw new CliUsageError('sharing-review requires --marking, --recipient-scope, and --purpose.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return {
+        action: 'sharing-review', source, output, marking, recipientScope, purpose,
+        humanReviewed, personalDataReviewed, redactionsConfirmed, quiet, color,
+    };
+}
+function parseWorkflowPlanArguments(argv) {
+    const positional = [];
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (const argument of argv) {
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else
+            positional.push(argument);
+    }
+    if (positional.length !== 2)
+        throw new CliUsageError('workflow-plan requires one fixed recipe and one subject.');
+    const recipe = positional[0];
+    if (!INVESTIGATION_PLAN_RECIPES.includes(recipe)) {
+        throw new CliUsageError(`workflow-plan recipe must be one of: ${INVESTIGATION_PLAN_RECIPES.join(', ')}.`);
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'workflow-plan', recipe: recipe, subject: positional[1], output, quiet, color };
+}
 function parseDiffArguments(argv) {
     let leftSource = null;
     let rightSource = null;
@@ -926,6 +1167,36 @@ function parseDiffArguments(argv) {
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
     return { action: 'diff', leftSource, rightSource, output, quiet, color };
 }
+function parseReconcileArguments(argv) {
+    const sources = [];
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (const argument of argv) {
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else
+            sources.push(argument);
+    }
+    if (sources.length < 2 || sources.length > 5) {
+        throw new CliUsageError('reconcile requires from 2 to 5 saved lookup JSON files.');
+    }
+    if (new Set(sources).size !== sources.length) {
+        throw new CliUsageError('reconcile input files must be different.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'reconcile', sources, output, quiet, color };
+}
 function parseTimelineArguments(argv) {
     const sources = [];
     let output = 'terminal';
@@ -982,6 +1253,32 @@ function parseRegistrySupportArguments(argv) {
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
     return { action: 'registry-support', target, output, quiet, color };
 }
+function parseRegistryDoctorArguments(argv) {
+    let source = null;
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (const argument of argv) {
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else if (source === null)
+            source = argument;
+        else
+            throw new CliUsageError('registry-doctor accepts one optional saved Lookup JSON file.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'registry-doctor', source, output, quiet, color };
+}
 function parseRiskCalibrateArguments(argv) {
     let source = null;
     let output = 'terminal';
@@ -1008,6 +1305,32 @@ function parseRiskCalibrateArguments(argv) {
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
     return { action: 'risk-calibrate', source, output, quiet, color };
 }
+function parseLookalikeCalibrateArguments(argv) {
+    let source = null;
+    let output = 'terminal';
+    let quiet = false;
+    let color = true;
+    for (const argument of argv) {
+        if (argument === '--json') {
+            if (output !== 'terminal')
+                throw new CliUsageError('--json may be supplied only once.');
+            output = 'json';
+        }
+        else if (argument === '--quiet')
+            quiet = true;
+        else if (argument === '--no-color')
+            color = false;
+        else if (argument.startsWith('-'))
+            throw new CliUsageError(`Unknown option "${argument}".`);
+        else if (source === null)
+            source = argument;
+        else
+            throw new CliUsageError('lookalike-calibrate accepts one optional reviewed dataset JSON file.');
+    }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    return { action: 'lookalike-calibrate', source, output, quiet, color };
+}
 function parseVerifyArtifactArguments(argv) {
     let source = null;
     let passphraseSource = null;
@@ -1041,7 +1364,7 @@ function parseVerifyArtifactArguments(argv) {
         else if (source === null)
             source = argument;
         else
-            throw new CliUsageError('verify-artifact accepts one optional JSON file. Otherwise pipe one artifact on stdin.');
+            throw new CliUsageError('verify-artifact accepts one optional JSON file. Otherwise pipe one artefact on stdin.');
     }
     if (quiet && output !== 'terminal')
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');