@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/external-observation-mapping.mjs

@@ -1,6 +1,6 @@
 import { domainToASCII } from 'node:url';
-import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
-import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, parseExternalFindingsDocument, } from "../packages/interchange/external-findings-import.mjs";
+import { compareCodeUnits, exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, parseExternalFindingsDocument, retainExternalFindingLimitations, } from "../packages/interchange/external-findings-import.mjs";
 export const EXTERNAL_OBSERVATION_MAPPING_SCHEMA = 'whoisleuth.external-observation-mapping';
 export const EXTERNAL_OBSERVATION_MAPPING_VERSION = 1;
 export const MAX_EXTERNAL_OBSERVATION_MAPPING_BYTES = 4 * 1024 * 1024;
@@ -49,9 +49,9 @@ function domain(value, label) {
 function limitations(value) {
     if (value === undefined)
         return Object.freeze([]);
-    if (!Array.isArray(value) || value.length > 8)
-        throw new TypeError('profile.limitations must contain no more than 8 entries.');
-    return Object.freeze([...new Set(value.map((entry, index) => requireBoundedString(entry, `profile.limitations[${index}]`, 240)))]);
+    if (!Array.isArray(value) || value.length > MAX_EXTERNAL_FINDING_LIMITATIONS)
+        throw new TypeError(`profile.limitations must contain no more than ${MAX_EXTERNAL_FINDING_LIMITATIONS} entries.`);
+    return Object.freeze([...new Set(value.map((entry, index) => requireBoundedString(entry, `profile.limitations[${index}]`, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH)))]);
 }
 export function mapExternalObservations(inputRaw) {
     const input = requireRecord(inputRaw, 'External observation mapping');
@@ -112,7 +112,7 @@ export function mapExternalObservations(inputRaw) {
                 : null,
             structuredObservation: null,
         });
-    }).sort((left, right) => left.domain.localeCompare(right.domain) || left.observedAt.localeCompare(right.observedAt) || left.summary.localeCompare(right.summary));
+    }).sort((left, right) => compareCodeUnits(left.domain, right.domain) || compareCodeUnits(left.observedAt, right.observedAt) || compareCodeUnits(left.summary, right.summary));
     const selected = [];
     const seen = new Set();
     const domainCounts = new Map();
@@ -140,11 +140,10 @@ export function mapExternalObservations(inputRaw) {
         source,
         findings: selected.map((finding) => ({
             ...finding,
-            limitations: [
-                ...finding.limitations,
+            limitations: retainExternalFindingLimitations(finding.limitations, [
                 `Mapped locally with declarative profile ${profile.id} version ${profile.version}; the profile does not verify the upstream field semantics.`,
-                ...(truncated ? ['The supplied records exceeded the browser import boundary; only the first deterministic bounded findings were retained.'] : []),
-            ].slice(0, 8),
+                ...(truncated ? [`The supplied records exceeded the browser import boundary; ${selected.length} of ${seen.size} unique findings were retained in deterministic order.`] : []),
+            ]),
         })),
     };
     return parseExternalFindingsDocument(document);

package/cli/formatters/terminal-command-formats.mjs

@@ -168,6 +168,12 @@ function formatTerminalPosture(document) {
         `Dependencies   ${dependencies.length} observed · ${dmarcAuthorizations.length} DMARC reporting destination${dmarcAuthorizations.length === 1 ? '' : 's'} checked`,
         '',
     ];
+    for (const value of dmarcAuthorizations.slice(0, 10)) {
+        const item = terminalRecord(value);
+        lines.push(`Reporting      ${safeTerminalValue(item.destination)} · ${safeTerminalValue(item.reportType)} · ${item.state === 'self' ? 'same organisational scope' : safeTerminalValue(item.state).replaceAll('_', ' ')}`);
+        if (item.error)
+            lines.push(`  Detail       ${safeTerminalValue(item.error)}`);
+    }
     for (const value of checks) {
         const item = terminalRecord(value);
         lines.push(`[${safeTerminalValue(item.status, 'info').toUpperCase()}] ${safeTerminalValue(item.label)}: ${safeTerminalValue(item.summary)}`);

package/cli/formatters/terminal-lookup.mjs

@@ -1,6 +1,8 @@
 import { registryAccessProfileLabel } from "../registry-access.mjs";
-import { technologyEvidenceRoles, } from "../../lib/technology-evidence-role.mjs";
+import { dnsAddressFamilyEvidence } from "../../packages/evidence/dns-query-outcome.mjs";
+import { appendTechnologyLines } from "./terminal-technology.mjs";
 import { appendDeliveryMetadataLines, appendPublicationMetadataLines } from "./terminal-metadata.mjs";
+import { securityPostureReview, summarizeSecurityPostureReview } from "../../lib/website-security-posture.mjs";
 import { appendSection, boundedTerminalComponent, boundedTerminalList, boundedTerminalWithSuffix, MAX_TLS_TERMINAL_ALT_NAMES, MAX_TLS_TERMINAL_PURPOSES, safeTerminalValue, terminalCount, terminalCountSummary, terminalDisplayCount, terminalRecord, titleCase, } from "./terminal-shared.mjs";
 const MAX_LOOKUP_TERMINAL_RECORDS = 5;
 const MAX_LOOKUP_TERMINAL_NAMES = 5;
@@ -10,13 +12,6 @@ const MAX_LOOKUP_TERMINAL_LIMITATIONS = 3;
 const MAX_LOOKUP_TERMINAL_CIDRS = 5;
 const MAX_LOOKUP_TERMINAL_FINDINGS = 5;
 const MAX_LOOKUP_TERMINAL_ABUSE_ROUTES = 6;
-function terminalTechnologyRoleNames(findings, role) {
-    const names = findings
-        .filter((finding) => technologyEvidenceRoles(finding).includes(role))
-        .slice(0, 6)
-        .map((finding) => safeTerminalValue(terminalRecord(finding).name, 'Unnamed indicator'));
-    return names.length ? boundedTerminalList(names, Math.max(0, findings.filter((finding) => technologyEvidenceRoles(finding).includes(role)).length - names.length)) : 'None retained';
-}
 function formatLookupDnsRecord(value) {
     if (typeof value === 'string' || typeof value === 'number')
         return safeTerminalValue(value);
@@ -244,6 +239,11 @@ function formatTerminalLookup(document, { detail = 'standard' } = {}) {
         targetLines.push(`Input host     ${safeTerminalValue(document.inputHostname)}`);
         targetLines.push(`Registry query ${safeTerminalValue(document.registrableDomain)}`);
     }
+    if (availability.observationHostname) {
+        targetLines.push(`DNS/TLS/web    ${safeTerminalValue(availability.observationHostname)}`);
+    }
+    if (availability.webObservationMode === 'selected_url')
+        targetLines.push('Website scope  Explicitly selected URL; query omitted from provenance');
     if (availability.applicable) {
         targetLines.push(`Availability   ${titleCase(availability.state)}`);
         targetLines.push(`Confidence     ${titleCase(availability.confidence)}`);
@@ -320,6 +320,11 @@ function formatTerminalLookup(document, { detail = 'standard' } = {}) {
         if (Object.keys(dns).length) {
             dnsLines.push(`Evidence       ${titleCase(dns.status)}`);
             dnsLines.push(`Completeness   ${dns.complete === true ? 'Complete' : 'Incomplete'}`);
+            for (const family of ['a', 'aaaa']) {
+                const evidence = dnsAddressFamilyEvidence(dns, family);
+                if (evidence.value)
+                    dnsLines.push(`${family.toUpperCase().padEnd(14)} ${safeTerminalValue(evidence.value)}`);
+            }
             const recordTypes = [
                 ['a', 'A'], ['aaaa', 'AAAA'], ['cname', 'CNAME'], ['ns', 'NS'],
                 ['mx', 'MX'], ['spf', 'SPF'], ['dmarc', 'DMARC'], ['caa', 'CAA'],
@@ -486,7 +491,7 @@ function formatTerminalLookup(document, { detail = 'standard' } = {}) {
         const technology = terminalRecord(availability.technologyProfile);
         const browserLibraries = terminalRecord(technology.browserLibraryProfile);
         const posture = terminalRecord(availability.securityPosture);
-        const postureSummary = terminalRecord(posture.summary);
+        const postureReview = summarizeSecurityPostureReview(posture.findings);
         const pageIdentity = terminalRecord(availability.pageIdentity);
         const pageRole = terminalRecord(availability.pageRoleProfile);
         const clientBehavior = terminalRecord(availability.clientBehaviorProfile);
@@ -578,47 +583,20 @@ function formatTerminalLookup(document, { detail = 'standard' } = {}) {
             if (detail !== 'summary' && visible.length)
                 websiteLines.push(`Declarations   ${safeTerminalValue(visible.join('; '))}`);
         }
-        if (technology.status || technology.source === 'derived') {
-            const findings = Array.isArray(technology.findings) ? technology.findings : [];
-            websiteLines.push(`Technology     ${titleCase(technology.status)} · ${findings.length} indicator${findings.length === 1 ? '' : 's'}`);
-            const visible = findings.slice(0, 6).map((finding) => {
-                const item = terminalRecord(finding);
-                const qualifiers = [item.category, item.confidence ? `${item.confidence} signature strength` : null].filter(Boolean).map((value) => safeTerminalValue(value));
-                return `${safeTerminalValue(item.name, 'Unnamed indicator')}${qualifiers.length ? ` (${qualifiers.join(', ')})` : ''}`;
-            });
-            if (detail !== 'summary' && visible.length) {
-                const omitted = findings.length - visible.length;
-                websiteLines.push(`Indicators     ${safeTerminalValue(`${visible.join('; ')}${omitted > 0 ? `; +${omitted} more` : ''}`)}`);
-            }
-            if (detail !== 'summary') {
-                const nameservers = Array.isArray(availability.nameservers)
-                    ? availability.nameservers.slice(0, MAX_LOOKUP_TERMINAL_NAMES).map((value) => safeTerminalValue(value))
-                    : [];
-                websiteLines.push(`Nameservers   ${nameservers.length ? boundedTerminalList(nameservers, Math.max(0, availability.nameservers.length - nameservers.length)) : 'Unavailable'} · identity does not establish operator or web-host ownership`);
-                websiteLines.push(`Observed edge  ${terminalTechnologyRoleNames(findings, 'observed_edge')}`);
-                websiteLines.push(`App platform   ${terminalTechnologyRoleNames(findings, 'application_platform')}`);
-                websiteLines.push(`Framework/run  ${terminalTechnologyRoleNames(findings, 'framework_runtime')}`);
-                websiteLines.push(`Embedded deps  ${terminalTechnologyRoleNames(findings, 'embedded_dependency')}`);
-                websiteLines.push('Origin host    Not established from retained evidence');
-            }
-            if (detail !== 'summary' && (browserLibraries.profileVersion === 1 || browserLibraries.source === 'derived')) {
-                const libraries = Array.isArray(browserLibraries.findings) ? browserLibraries.findings : [];
-                const advisoryMatches = libraries.filter((finding) => terminalCount(terminalRecord(finding).advisoryCount) > 0).length;
-                websiteLines.push(`JS libraries   ${titleCase(browserLibraries.status)} · ${libraries.length} apparent · `
-                    + `${advisoryMatches} with catalogue advisory match${advisoryMatches === 1 ? '' : 'es'}`);
-            }
-        }
+        appendTechnologyLines(websiteLines, {
+            technology, libraries: browserLibraries, nameservers: availability.nameservers,
+            generatedAt: document.generatedAt, detail,
+        });
         if (posture.status || posture.source === 'derived') {
             websiteLines.push(`Posture        ${titleCase(posture.status)}`);
-            if (detail !== 'summary' && Object.keys(postureSummary).length)
-                websiteLines.push(`Posture counts ${terminalCount(postureSummary.observed)} observed · `
-                    + `${terminalCount(postureSummary.potentialExposure)} potential exposure · `
-                    + `${terminalCount(postureSummary.observedAbsence)} observed absence · `
-                    + `${terminalCount(postureSummary.unavailable)} unavailable`);
+            if (detail !== 'summary' && Array.isArray(posture.findings))
+                websiteLines.push(`Posture checks Needs review ${postureReview.needsReview} · `
+                    + `Other findings ${postureReview.otherFindings} · `
+                    + `Could not assess ${postureReview.unavailable}`);
             if (detail === 'verbose' && positiveSourceStatus(posture.status)) {
                 const findings = boundedFindingLabels(posture.findings, (finding) => {
-                    const state = finding.state ? ` (${titleCase(finding.state)})` : '';
-                    return `${safeTerminalValue(finding.label, 'Unlabelled finding')}${state}`;
+                    const review = securityPostureReview(finding);
+                    return `${safeTerminalValue(finding.label, 'Unlabelled finding')}${review.label ? ` (${review.label})` : ''}`;
                 });
                 if (findings)
                     websiteLines.push(`Posture labels ${findings}`);

package/cli/formatters/terminal-shared.mjs

@@ -6,7 +6,9 @@ const MAX_TLS_TERMINAL_PURPOSES = 8;
 // through soft hyphens, combining grapheme joiners, variation selectors, tag
 // characters, bidi controls, or other zero-width formatting code points.
 const TERMINAL_DEFAULT_IGNORABLE_RE = /\p{Default_Ignorable_Code_Point}/gu;
-function safeTerminalValue(value, fallback = '—') {
+function safeTerminalValue(value, fallback = '—', maximum = MAX_TERMINAL_VALUE_LENGTH) {
+    if (!Number.isSafeInteger(maximum) || maximum < 1)
+        throw new TypeError('Terminal text requires a positive finite character bound.');
     if (value === null || value === undefined || value === '')
         return fallback;
     const normalized = String(value)
@@ -16,8 +18,8 @@ function safeTerminalValue(value, fallback = '—') {
         .trim();
     if (!normalized)
         return fallback;
-    return normalized.length > MAX_TERMINAL_VALUE_LENGTH
-        ? `${normalized.slice(0, MAX_TERMINAL_VALUE_LENGTH - 1)}…`
+    return normalized.length > maximum
+        ? `${normalized.slice(0, maximum - 1)}…`
         : normalized;
 }
 function boundedTerminalList(values, omitted) {

package/cli/formatters/terminal-technology.mjs

@@ -0,0 +1,114 @@
+import { MAX_EVIDENCE_PER_TECHNOLOGY, MAX_LIBRARY_FINDINGS, MAX_TECHNOLOGY_FINDINGS, } from "../../lib/lookup-child-profile-contract.mjs";
+import { TECHNOLOGY_EVIDENCE_ROLE_ORDER, technologyEvidenceRoles, } from "../../lib/technology-evidence-role.mjs";
+import { MAX_OBSERVATION_LIMITATIONS, readObservationTime } from "../../packages/evidence/observation.mjs";
+import { boundedTerminalList, safeTerminalValue, terminalCount, terminalRecord, titleCase } from "./terminal-shared.mjs";
+const ROLE_LABELS = {
+    observed_edge: 'Observed edge',
+    application_platform: 'App platform',
+    framework_runtime: 'Framework/run',
+    embedded_dependency: 'Embedded deps',
+};
+const SUMMARY_FINDINGS = 6;
+const SUMMARY_NAMESERVERS = 5;
+function observationLine(label, value, generatedAt) {
+    const time = readObservationTime(value, generatedAt);
+    if (!time.observedAt)
+        return `${label.padEnd(15)}Observed time unavailable`;
+    const age = time.ageDays === null ? 'age unavailable'
+        : time.ageDays === 0 ? 'less than a day old at output generation'
+            : `${time.ageDays} day${time.ageDays === 1 ? '' : 's'} old at output generation`;
+    return `${label.padEnd(15)}${time.observedAt} · ${age}`;
+}
+function appendLimitations(lines, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const limitation of value.slice(0, MAX_OBSERVATION_LIMITATIONS)) {
+        lines.push(`  Limit        ${safeTerminalValue(limitation)}`);
+    }
+}
+/** Presents admitted source records; it never collects or infers a hidden origin. */
+export function appendTechnologyLines(lines, input) {
+    const { technology, libraries, nameservers, generatedAt, detail } = input;
+    if (!technology.status && technology.source !== 'derived')
+        return;
+    const suppliedFindings = Array.isArray(technology.findings) ? technology.findings : [];
+    const findings = suppliedFindings.slice(0, MAX_TECHNOLOGY_FINDINGS).map((value) => {
+        const finding = terminalRecord(value);
+        return { finding, roles: technologyEvidenceRoles(finding) };
+    });
+    lines.push(`Technology     ${titleCase(technology.status)} · ${findings.length} indicator${findings.length === 1 ? '' : 's'}`);
+    if (suppliedFindings.length > findings.length)
+        lines.push('Technology     Additional findings exceed the admitted profile limit');
+    if (detail === 'summary')
+        return;
+    lines.push(observationLine('Tech observed', technology.observedAt, generatedAt));
+    if (detail === 'standard' && findings.length) {
+        const visible = findings.slice(0, SUMMARY_FINDINGS).map(({ finding }) => {
+            const qualifiers = [finding.category, finding.confidence ? `${safeTerminalValue(finding.confidence)} signature strength` : null]
+                .filter(Boolean).map((value) => safeTerminalValue(value));
+            return `${safeTerminalValue(finding.name, 'Unnamed indicator')}${qualifiers.length ? ` (${qualifiers.join(', ')})` : ''}`;
+        });
+        lines.push(`Indicators     ${boundedTerminalList(visible, findings.length - visible.length)}`);
+    }
+    const retainedNameservers = Array.isArray(nameservers) ? nameservers : [];
+    const visibleNameservers = retainedNameservers.slice(0, SUMMARY_NAMESERVERS).map((value) => safeTerminalValue(value));
+    lines.push(`Nameservers   ${visibleNameservers.length ? boundedTerminalList(visibleNameservers, retainedNameservers.length - visibleNameservers.length) : 'Unavailable'} · identity does not establish operator or web-host ownership`);
+    for (const role of TECHNOLOGY_EVIDENCE_ROLE_ORDER) {
+        const matching = findings.filter((item) => item.roles.includes(role));
+        const names = matching.slice(0, SUMMARY_FINDINGS).map(({ finding }) => safeTerminalValue(finding.name, 'Unnamed indicator'));
+        lines.push(`${ROLE_LABELS[role].padEnd(15)}${names.length ? boundedTerminalList(names, matching.length - names.length) : 'None retained'}`);
+    }
+    lines.push('Origin host    Not established from retained evidence');
+    if (detail === 'verbose') {
+        for (const { finding, roles } of findings) {
+            lines.push(`Indicator      ${safeTerminalValue(finding.name, 'Unnamed indicator')}`);
+            lines.push(`  Role         ${roles.map((role) => ROLE_LABELS[role]).join(', ') || 'Not retained'}`);
+            lines.push(`  Strength     ${safeTerminalValue(finding.confidence, 'Unknown')} signature strength`);
+            const suppliedEvidence = Array.isArray(finding.evidence) ? finding.evidence : [];
+            const evidence = suppliedEvidence.slice(0, MAX_EVIDENCE_PER_TECHNOLOGY);
+            if (!evidence.length)
+                lines.push('  Signal       No detailed signal was retained');
+            for (const value of evidence) {
+                const item = terminalRecord(value);
+                if (typeof item.source !== 'string' || !item.source.trim()
+                    || typeof item.description !== 'string' || !item.description.trim()) {
+                    lines.push('  Signal       Incomplete retained signal record');
+                    continue;
+                }
+                const role = TECHNOLOGY_EVIDENCE_ROLE_ORDER.find((candidate) => candidate === item.role);
+                lines.push(`  Source       ${safeTerminalValue(item.source, 'Not retained')} · ${role ? ROLE_LABELS[role] : 'Role not retained'}`);
+                lines.push(`  Signal       ${safeTerminalValue(item.description, 'Not retained')}`);
+            }
+            if (suppliedEvidence.length > evidence.length)
+                lines.push('  Limit        Additional signals exceed the admitted profile limit');
+        }
+        appendLimitations(lines, technology.limitations);
+    }
+    if (libraries.profileVersion !== 1 && libraries.profileVersion !== 2 && libraries.source !== 'derived')
+        return;
+    const suppliedLibraries = Array.isArray(libraries.findings) ? libraries.findings : [];
+    const libraryFindings = suppliedLibraries.slice(0, MAX_LIBRARY_FINDINGS).map(terminalRecord);
+    const advisoryMatches = libraryFindings.filter((finding) => terminalCount(finding.advisoryCount) > 0).length;
+    lines.push(`JS libraries   ${titleCase(libraries.status)} · ${libraryFindings.length} apparent · ${advisoryMatches} with catalogue advisory match${advisoryMatches === 1 ? '' : 'es'}`);
+    lines.push(observationLine('Lib observed', libraries.observedAt, generatedAt));
+    if (suppliedLibraries.length > libraryFindings.length)
+        lines.push('JS libraries   Additional findings exceed the admitted profile limit');
+    if (detail !== 'verbose')
+        return;
+    const catalogue = terminalRecord(libraries.catalog);
+    lines.push(`Catalogue      ${safeTerminalValue(catalogue.name, 'Component catalogue')} · ${safeTerminalValue(catalogue.version, 'Version unavailable')}`);
+    for (const library of libraryFindings) {
+        lines.push(`Library        ${safeTerminalValue(library.name, 'Unnamed library')} · ${safeTerminalValue(library.apparentVersion, 'Version unavailable')}`);
+        const methods = Array.isArray(library.detectionMethods) ? library.detectionMethods.slice(0, 4).map((value) => safeTerminalValue(value)) : [];
+        lines.push(`  Detected by  ${methods.join(', ') || 'Not retained'}`);
+        lines.push(`  Advisories   ${terminalCount(library.advisoryCount)} catalogue matches`);
+        if (library.highestSeverity)
+            lines.push(`  Severity     ${safeTerminalValue(library.highestSeverity)}`);
+        for (const [field, label] of [['advisoryIdentifiers', 'Identifier'], ['knownExploitedIdentifiers', 'Known exploited']]) {
+            const values = Array.isArray(library[field]) ? library[field] : [];
+            for (const value of values.slice(0, 16))
+                lines.push(`  ${label.padEnd(15)} ${safeTerminalValue(value)}`);
+        }
+    }
+    appendLimitations(lines, libraries.limitations);
+}

package/cli/history-arguments.mjs

@@ -0,0 +1,39 @@
+import {} from "./command-argument-grammar.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { terminalOptions, jsonOutput, parseTwoFileComparisonArguments, uniqueSources, } from "./argument-values.mjs";
+function parseDiffArguments(parsed) {
+    const compared = parseTwoFileComparisonArguments(parsed, 'diff');
+    const leftSessionId = parsed.optionValue('--left-session');
+    const rightSessionId = parsed.optionValue('--right-session');
+    for (const [option, value] of [
+        ['--left-session', leftSessionId],
+        ['--right-session', rightSessionId],
+    ]) {
+        if (value !== null && !/^[A-Za-z0-9_-]{1,128}$/u.test(value)) {
+            throw new CliUsageError(`${option} requires one bounded saved-session ID.`);
+        }
+    }
+    return { action: 'diff', ...compared, leftSessionId, rightSessionId };
+}
+export const HISTORY_ARGUMENT_PARSERS = Object.freeze({
+    diff: parseDiffArguments,
+    reconcile: (parsed) => ({
+        action: 'reconcile',
+        sources: uniqueSources(parsed, 'reconcile'),
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    }),
+    timeline: (parsed) => ({
+        action: 'timeline',
+        sources: uniqueSources(parsed, 'timeline'),
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    }),
+    export: (parsed) => ({
+        action: 'export',
+        source: parsed.positionalValue('source'),
+        format: parsed.hasOption('--markdown') ? 'markdown' : parsed.hasOption('--html') ? 'html' : 'json',
+        compact: parsed.hasOption('--compact'),
+        includeAttribution: !parsed.hasOption('--no-attribution'),
+    }),
+});

package/cli/history-command-definitions.mjs

@@ -0,0 +1,88 @@
+import { LOOKUP_EVIDENCE_SCHEMA_VERSION, V1_PUBLIC_LOOKUP_EVIDENCE_SCHEMA_VERSION } from "../packages/contracts/lookup-evidence.mjs";
+import { PUBLISHED_V2_LOOKUP_EVIDENCE_VERSIONS, positional, OPTIONAL_FILE_POSITIONAL, constraint, EMPTY_CONSTRAINTS, commandSeed } from "./command-definition.mjs";
+export const HISTORY_COMMAND_DEFINITIONS = Object.freeze({
+    diff: commandSeed({
+        reference: {
+            description: 'Compare an earlier and later artefact from the same retained Lookup, Bulk-session, or domain-portfolio family.',
+            example: 'whoisleuth diff earlier.json later.json --json',
+            boundary: 'Comparison is offline: the left input is earlier and the right input is later. Inputs must belong to the same supported family. Saved Lookups can describe the same or different domains; same-domain comparisons preserve observation times and collection uncertainty. For a multi-session Bulk export, --left-session selects a session from the left file and --right-session selects one from the right; missing, unavailable, equal, and different evidence remain separate states.',
+        },
+        collection: { scope: 'Reads two compatible retained artefacts capped at 8 MiB each and retains no source paths.' },
+        summary: 'Compare two compatible retained artefacts',
+        options: ['--left-session', '--right-session', '--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('sources', 'file', 2, 2)]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'history',
+        networkEffect: 'offline',
+        common: true,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.lookup-diff']),
+        primaryArtefacts: Object.freeze(['Retained-evidence comparison']),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    reconcile: commandSeed({
+        reference: {
+            description: 'Reconcile bounded values across independently labelled observations of one domain.',
+            example: 'whoisleuth reconcile office.json mobile.json external.json --json',
+            boundary: 'The command is offline, accepts 2 to 5 saved observations for one domain, and never treats labels as proof of network independence or majority agreement as truth.',
+        },
+        collection: { scope: 'Reads 2 to 5 saved observations for one domain, capped at 32 MiB in total.' },
+        summary: 'Reconcile independently labelled observations',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('sources', 'file', 2, 5)]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'history',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.lookup-reconciliation']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    timeline: commandSeed({
+        reference: {
+            description: 'Build an ordered same-domain history from saved Lookup observations.',
+            example: 'whoisleuth timeline first.json second.json latest.json --json',
+            boundary: 'The command is offline, accepts 2 to 20 bounded inputs for one domain, retains no filenames or raw registry payloads, and does not treat changed collection conditions as a domain change.',
+        },
+        collection: { scope: 'Reads 2 to 20 saved observations for one domain, capped at 32 MiB in total.' },
+        summary: 'Build same-domain history from saved lookups',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('sources', 'file', 2, 20)]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'history',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.lookup-timeline']),
+        primaryArtefacts: Object.freeze(['Bounded retained-observation timeline']),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    export: commandSeed({
+        reference: {
+            description: 'Convert one saved lookup into a versioned evidence report.',
+            example: 'whoisleuth export lookup.json --markdown',
+            boundary: `Saved Lookup versions 1 and 2 are capped at 8 MiB and scanned for duplicate keys, the prototype-sensitive __proto__ key, and bounded nesting, key, value, and per-container counts before parsing. Current schema-${LOOKUP_EVIDENCE_SCHEMA_VERSION} exports preserve evidence-source attribution and limitations; published v2 schemas ${PUBLISHED_V2_LOOKUP_EVIDENCE_VERSIONS} and exact v1 schema ${V1_PUBLIC_LOOKUP_EVIDENCE_SCHEMA_VERSION} remain readable, while other historical and unreleased shapes are unsupported. Markdown and HTML include a presentation-only generator footer unless --no-attribution is selected; JSON retains bounded generator provenance. Compact output intentionally omits raw registry payloads.`,
+        },
+        collection: { scope: 'Reads one saved Lookup and writes one bounded report.' },
+        summary: 'Convert a lookup to an evidence report',
+        options: ['--markdown', '--html', '--compact', '--no-attribution'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'mutually_exclusive', options: ['--markdown', '--html'] }),
+            constraint({ kind: 'excludes_all', option: '--compact', excludedOptions: ['--markdown', '--html'] }),
+            constraint({ kind: 'requires_any', option: '--no-attribution', requiredOptions: ['--markdown', '--html'] }),
+        ]),
+        handlerOwner: 'history',
+        networkEffect: 'offline',
+        common: true,
+        schemaIdentifiers: Object.freeze(['whoisleuth.lookup-evidence']),
+        primaryArtefacts: Object.freeze(['Portable evidence report']),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze(['JSON']),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/indicator-set-command.mjs

@@ -0,0 +1,33 @@
+import { buildManagedIndicatorRevision, managedIndicatorState, parseManagedIndicatorJson, readManagedIndicatorSet } from "../packages/interchange/managed-indicator-set.mjs";
+import { exportManagedIndicators } from "../packages/interchange/managed-indicator-export.mjs";
+import { MAX_MANAGED_INDICATOR_PLAN_BYTES, MAX_MANAGED_INDICATOR_SET_BYTES } from "../packages/contracts/analyst-interchange.mjs";
+import { formatJsonDocument } from "./formatters/json.mjs";
+import { safeTerminalValue } from "./formatters/terminal.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+export async function runIndicatorSetCommand(args, dependencies, context) {
+    context.setFailureLabel('Indicator revision');
+    const raw = dependencies.readArtifactInput ? await dependencies.readArtifactInput(args.source)
+        : await context.readInput(args.source, args.operation === 'revise' ? MAX_MANAGED_INDICATOR_PLAN_BYTES : MAX_MANAGED_INDICATOR_SET_BYTES, 'Indicator input');
+    const input = parseManagedIndicatorJson(raw, args.operation === 'revise');
+    const now = context.now();
+    const revision = args.operation === 'revise' ? await buildManagedIndicatorRevision(input, now) : null;
+    const manifest = revision?.manifest ?? await readManagedIndicatorSet(input);
+    dependencies.signal?.throwIfAborted();
+    if (args.quiet)
+        return EXIT_CODES.SUCCESS;
+    if (args.operation === 'stix' || args.operation === 'misp')
+        context.writeStdout((await exportManagedIndicators(manifest, args.operation)).content);
+    else if (args.output === 'json')
+        context.writeStdout(formatJsonDocument(manifest));
+    else {
+        const lines = [`${safeTerminalValue(manifest.name)} · revision ${manifest.revision}`, `Set ${manifest.id}`, `Content digest ${manifest.integrity.digestSha256}`,
+            'Content verified; authorship and earlier revisions are not authenticated.'];
+        if (revision)
+            lines.push(`Changes: ${revision.changes.length} · unchanged: ${revision.unchanged} · excluded candidates: ${revision.exclusions.length}`);
+        for (const entry of manifest.entries)
+            lines.push(`${entry.domain} · ${managedIndicatorState(entry, now)} · ${entry.id}`, `  Review expires ${entry.expiresAt} · source observed ${entry.observation.observedAt ?? 'time unavailable'}`, `  ${safeTerminalValue(entry.reviewBasis)}`);
+        lines.push('Save the manifest for the next revision. Nothing was submitted or applied.');
+        context.writeStdout(context.terminal(`${lines.join('\n')}\n`, args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}

package/cli/inline-command-families.mjs

@@ -1,46 +1,6 @@
-const SUPPORT_INLINE_COMMANDS = Object.freeze([
-    'completion',
-    'commands',
-    'manual',
-    'doctor',
-    'registry-support',
-    'registry-doctor',
-    'registry-cohort',
-    'registry-scaffold',
-    'risk-calibrate',
-    'lookalike-calibrate',
-]);
-const REVIEW_INLINE_COMMANDS = Object.freeze([
-    'verify-artifact',
-    'interchange-report',
-    'source-report',
-    'compare',
-    'page-compare',
-    'mail-review',
-    'mail-headers',
-    'review-evidence',
-    'brief',
-    'case-pack',
-]);
-const ASSURANCE_INLINE_COMMANDS = Object.freeze([
-    'manifest',
-    'map-observations',
-    'oam-export',
-    'domain-control',
-    'assurance',
-    'change-packet',
-    'sharing-review',
-    'ct-intake',
-]);
-const WORKFLOW_INLINE_COMMANDS = Object.freeze([
-    'monitor-once',
-    'workflow-plan',
-    'workflow-run',
-]);
-const HISTORY_INLINE_COMMANDS = Object.freeze([
-    'diff',
-    'reconcile',
-    'timeline',
-    'export',
-]);
-export { ASSURANCE_INLINE_COMMANDS, HISTORY_INLINE_COMMANDS, REVIEW_INLINE_COMMANDS, SUPPORT_INLINE_COMMANDS, WORKFLOW_INLINE_COMMANDS, };
+import { inlineCommandsFor } from "./command-reference.mjs";
+export const SUPPORT_INLINE_COMMANDS = inlineCommandsFor('support');
+export const REVIEW_INLINE_COMMANDS = inlineCommandsFor('review');
+export const ASSURANCE_INLINE_COMMANDS = inlineCommandsFor('assurance');
+export const WORKFLOW_INLINE_COMMANDS = inlineCommandsFor('workflow');
+export const HISTORY_INLINE_COMMANDS = inlineCommandsFor('history');

package/cli/inline-command-runner.mjs

@@ -1,35 +1,8 @@
-import { CLI_COMMANDS, commandDefinition } from "./command-reference.mjs";
-import { ASSURANCE_INLINE_COMMANDS, HISTORY_INLINE_COMMANDS, REVIEW_INLINE_COMMANDS, SUPPORT_INLINE_COMMANDS, WORKFLOW_INLINE_COMMANDS, } from "./inline-command-families.mjs";
-const FAMILY_COMMANDS = Object.freeze([
-    Object.freeze({ family: 'support', commands: SUPPORT_INLINE_COMMANDS }),
-    Object.freeze({ family: 'review', commands: REVIEW_INLINE_COMMANDS }),
-    Object.freeze({ family: 'assurance', commands: ASSURANCE_INLINE_COMMANDS }),
-    Object.freeze({ family: 'workflow', commands: WORKFLOW_INLINE_COMMANDS }),
-    Object.freeze({ family: 'history', commands: HISTORY_INLINE_COMMANDS }),
-]);
-function buildInlineCommandOwnership() {
-    const ownership = new Map();
-    for (const { family, commands } of FAMILY_COMMANDS) {
-        for (const command of commands) {
-            if (ownership.has(command))
-                throw new Error(`Inline CLI command ${command} has more than one command-family owner.`);
-            ownership.set(command, family);
-        }
-    }
-    return ownership;
-}
-const INLINE_COMMAND_OWNERSHIP = buildInlineCommandOwnership();
-const INLINE_CLI_COMMANDS = Object.freeze(CLI_COMMANDS.filter((command) => commandDefinition(command).execution.handlerOwner === 'inline'));
-function validateInlineCommandOwnership() {
-    const missing = INLINE_CLI_COMMANDS.filter((command) => !INLINE_COMMAND_OWNERSHIP.has(command));
-    const unexpected = [...INLINE_COMMAND_OWNERSHIP.keys()].filter((command) => !INLINE_CLI_COMMANDS.includes(command));
-    if (missing.length || unexpected.length) {
-        throw new Error(`Inline CLI command-family ownership is inconsistent (missing: ${missing.join(', ') || 'none'}; unexpected: ${unexpected.join(', ') || 'none'}).`);
-    }
-}
-validateInlineCommandOwnership();
+import { CLI_COMMANDS, INLINE_COMMAND_FAMILIES, inlineCommandFamily, inlineCommandsFor, } from "./command-reference.mjs";
+const FAMILY_COMMANDS = Object.freeze(INLINE_COMMAND_FAMILIES.map(family => Object.freeze({ family, commands: inlineCommandsFor(family) })));
+const INLINE_CLI_COMMANDS = Object.freeze(CLI_COMMANDS.filter((command) => inlineCommandFamily(command) !== null));
 async function runInlineCommand(args, dependencies, context) {
-    const family = INLINE_COMMAND_OWNERSHIP.get(args.action);
+    const family = inlineCommandFamily(args.action);
     if (family === 'support') {
         const { runSupportCommand } = await import("./support-command-runner.mjs");
         return runSupportCommand(args, dependencies, context);

package/cli/input.mjs

@@ -64,7 +64,7 @@ export async function readCliTextInput(source, stdin, options) {
             if (error instanceof CliUsageError)
                 throw error;
             const message = error instanceof Error ? error.message : `${options.label} could not be read.`;
-            throw new CliUsageError(message);
+            throw new CliUsageError(message, error instanceof TypeError ? 'invalid_input' : 'input_unavailable');
         }
     }
     if (!stdin || stdin.isTTY)
@@ -142,7 +142,7 @@ export async function readCliHeaderInput(source, stdin, options) {
             if (error instanceof CliUsageError || options.signal?.aborted)
                 throw error;
             const message = error instanceof Error ? error.message : `${options.label} could not be read.`;
-            throw new CliUsageError(message);
+            throw new CliUsageError(message, error instanceof TypeError ? 'invalid_input' : 'input_unavailable');
         }
         finally {
             await handle?.close();