@slicedearth/whoisleuth-cli 1.39.1 → 1.45.0

package/cli/external-observation-mapping.mjs

@@ -0,0 +1,162 @@
+import { domainToASCII } from 'node:url';
+import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
+import { EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, parseExternalFindingsDocument, } from "../frontend/src/lib/analysis/external-findings-import.js";
+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;
+export const MAX_EXTERNAL_OBSERVATION_RECORDS = 500;
+const ROOT_KEYS = new Set(['schema', 'version', 'source', 'profile', 'records']);
+const SOURCE_KEYS = new Set(['name', 'reference', 'collectedAt']);
+const PROFILE_KEYS = new Set([
+    'id', 'version', 'domainField', 'summaryField', 'observedAtField', 'referenceField',
+    'completenessField', 'category', 'evidenceClass', 'limitations',
+]);
+const PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*){0,7}$/u;
+const FORBIDDEN_PATH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+const COMPLETENESS = new Set(['complete', 'inconclusive', 'partial', 'unknown']);
+const CATEGORIES = new Set(EXTERNAL_FINDING_CATEGORIES);
+function optionalText(value, label, maximum) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    return requireBoundedString(value, label, maximum);
+}
+function path(value, label, optional = false) {
+    if (optional && (value === undefined || value === null || value === ''))
+        return null;
+    const candidate = requireBoundedString(value, label, 200);
+    if (!PATH_RE.test(candidate) || candidate.split('.').some((segment) => FORBIDDEN_PATH_SEGMENTS.has(segment))) {
+        throw new TypeError(`${label} must be a safe bounded dotted field path.`);
+    }
+    return candidate;
+}
+function readPath(value, fieldPath) {
+    let current = value;
+    for (const segment of fieldPath.split('.')) {
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function domain(value, label) {
+    const supplied = requireBoundedString(value, label, 253).trim().toLowerCase().replace(/^\*\./u, '').replace(/\.$/u, '');
+    const ascii = domainToASCII(supplied).toLowerCase();
+    if (!ascii || ascii.length > 253 || !ascii.includes('.') || ascii.split('.').some((part) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(part))) {
+        throw new TypeError(`${label} must resolve to a valid DNS name.`);
+    }
+    return ascii;
+}
+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)))]);
+}
+export function mapExternalObservations(inputRaw) {
+    const input = requireRecord(inputRaw, 'External observation mapping');
+    if (input.schema !== EXTERNAL_OBSERVATION_MAPPING_SCHEMA || input.version !== EXTERNAL_OBSERVATION_MAPPING_VERSION) {
+        throw new TypeError(`External observation mapping must use ${EXTERNAL_OBSERVATION_MAPPING_SCHEMA} version ${EXTERNAL_OBSERVATION_MAPPING_VERSION}.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'External observation mapping');
+    const sourceInput = requireRecord(input.source, 'source');
+    exactKeys(sourceInput, SOURCE_KEYS, 'source');
+    const profileInput = requireRecord(input.profile, 'profile');
+    exactKeys(profileInput, PROFILE_KEYS, 'profile');
+    const profile = Object.freeze({
+        id: requireBoundedString(profileInput.id, 'profile.id', 80),
+        version: Number(profileInput.version),
+        domainField: path(profileInput.domainField, 'profile.domainField'),
+        summaryField: path(profileInput.summaryField, 'profile.summaryField'),
+        observedAtField: path(profileInput.observedAtField, 'profile.observedAtField'),
+        referenceField: path(profileInput.referenceField, 'profile.referenceField', true),
+        completenessField: path(profileInput.completenessField, 'profile.completenessField', true),
+        category: profileInput.category,
+        evidenceClass: profileInput.evidenceClass,
+        limitations: limitations(profileInput.limitations),
+    });
+    if (!Number.isSafeInteger(profile.version) || profile.version < 1 || profile.version > 1_000)
+        throw new TypeError('profile.version is invalid.');
+    if (typeof profile.category !== 'string' || !CATEGORIES.has(profile.category))
+        throw new TypeError('profile.category is unsupported.');
+    if (profile.evidenceClass !== 'deployment_observation' && profile.evidenceClass !== 'provider_report')
+        throw new TypeError('profile.evidenceClass is unsupported.');
+    if (!Array.isArray(input.records) || input.records.length < 1 || input.records.length > MAX_EXTERNAL_OBSERVATION_RECORDS) {
+        throw new TypeError(`records must contain between 1 and ${MAX_EXTERNAL_OBSERVATION_RECORDS} entries.`);
+    }
+    const source = Object.freeze({
+        name: requireBoundedString(sourceInput.name, 'source.name', 80),
+        reference: optionalText(sourceInput.reference, 'source.reference', 500),
+        collectedAt: sourceInput.collectedAt === null || sourceInput.collectedAt === undefined
+            ? null
+            : requireIsoTimestamp(sourceInput.collectedAt, 'source.collectedAt'),
+    });
+    const candidates = input.records.map((record, index) => {
+        const domainValue = domain(readPath(record, profile.domainField), `records[${index}].${profile.domainField}`);
+        const summary = requireBoundedString(readPath(record, profile.summaryField), `records[${index}].${profile.summaryField}`, 900);
+        const observedAt = requireIsoTimestamp(readPath(record, profile.observedAtField), `records[${index}].${profile.observedAtField}`);
+        const completenessValue = profile.completenessField ? readPath(record, profile.completenessField) : 'unknown';
+        if (typeof completenessValue !== 'string' || !COMPLETENESS.has(completenessValue)) {
+            throw new TypeError(`records[${index}] completeness is unsupported.`);
+        }
+        return Object.freeze({
+            domain: domainValue,
+            category: profile.category,
+            evidenceClass: profile.evidenceClass,
+            summary,
+            observedAt,
+            completeness: completenessValue,
+            limitations: profile.limitations,
+            reference: profile.referenceField
+                ? optionalText(readPath(record, profile.referenceField), `records[${index}].${profile.referenceField}`, 500)
+                : null,
+            structuredObservation: null,
+        });
+    }).sort((left, right) => left.domain.localeCompare(right.domain) || left.observedAt.localeCompare(right.observedAt) || left.summary.localeCompare(right.summary));
+    const selected = [];
+    const seen = new Set();
+    const domainCounts = new Map();
+    const domains = new Set();
+    for (const finding of candidates) {
+        const key = `${finding.domain}\u0000${finding.category}\u0000${finding.summary}\u0000${finding.observedAt}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (!domains.has(finding.domain) && domains.size >= MAX_EXTERNAL_FINDING_DOMAINS)
+            continue;
+        const count = domainCounts.get(finding.domain) ?? 0;
+        if (count >= MAX_EXTERNAL_FINDINGS_PER_DOMAIN)
+            continue;
+        if (selected.length >= MAX_EXTERNAL_FINDINGS)
+            continue;
+        domains.add(finding.domain);
+        domainCounts.set(finding.domain, count + 1);
+        selected.push(finding);
+    }
+    const truncated = selected.length < seen.size;
+    const document = {
+        schema: 'whoisleuth.external-findings',
+        schemaVersion: 3,
+        source,
+        findings: selected.map((finding) => ({
+            ...finding,
+            limitations: [
+                ...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),
+        })),
+    };
+    return parseExternalFindingsDocument(document);
+}
+export function formatExternalObservationMapping(document) {
+    return [
+        'External observation mapping',
+        `Source    ${document.source.name}`,
+        `Findings  ${document.findings.length}`,
+        `Domains   ${new Set(document.findings.map((finding) => finding.domain)).size}`,
+        '',
+        'The JSON form can be deliberately imported through the Console external-findings workflow.',
+        '',
+    ].join('\n');
+}

package/cli/fail-policy.mjs

@@ -0,0 +1,64 @@
+import { lookupStrictExitFindings } from "./strict-exit.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const CLI_FAIL_POLICIES = ['source-failure', 'inconclusive', 'danger', 'material-drift'];
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export function parseCliFailPolicies(value) {
+    if (typeof value !== 'string' || !value || value.length > 100)
+        throw new CliUsageError('--fail-on requires a comma-separated policy list.');
+    const policies = [...new Set(value.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean))];
+    if (!policies.length || policies.some((item) => !CLI_FAIL_POLICIES.includes(item))) {
+        throw new CliUsageError(`--fail-on supports: ${CLI_FAIL_POLICIES.join(', ')}.`);
+    }
+    return policies;
+}
+function availabilityStates(document) {
+    const direct = String(record(document.availability).state || '').toLowerCase();
+    const results = Array.isArray(document.results) ? document.results : [];
+    const resultStates = results.flatMap((value) => {
+        const item = record(value);
+        const state = item.availabilityState ?? record(item.availability).state;
+        return typeof state === 'string' ? [state.toLowerCase()] : [];
+    });
+    return [direct, ...resultStates].filter(Boolean);
+}
+export function evaluateCliFailPolicies(document, policies) {
+    const root = record(document);
+    const findings = [];
+    for (const policy of policies) {
+        if (policy === 'source-failure') {
+            const resultDocuments = Array.isArray(root.results) ? root.results.map(record).filter((item) => Object.keys(record(item.diagnostics)).length) : [];
+            const sourceFindings = Object.keys(record(root.diagnostics)).length
+                ? lookupStrictExitFindings(root)
+                : resultDocuments.flatMap((item) => lookupStrictExitFindings(item));
+            const collection = record(root.collection);
+            const summary = record(root.summary);
+            const failed = Number(collection.failed ?? summary.failed ?? 0);
+            if (sourceFindings.length || failed > 0)
+                findings.push({ policy, reason: `${sourceFindings.length + failed} failed or incomplete collection state(s)` });
+        }
+        else if (policy === 'inconclusive') {
+            const count = availabilityStates(root).filter((state) => ['unknown', 'inconclusive', 'partial', 'unavailable'].includes(state)).length;
+            if (count)
+                findings.push({ policy, reason: `${count} authority or availability state(s) remained inconclusive` });
+        }
+        else if (policy === 'danger') {
+            const risk = Number(record(root.risk).score ?? root.riskScore);
+            const severity = String(root.severity || record(root.review).severity || '').toLowerCase();
+            if ((Number.isFinite(risk) && risk >= 70) || severity === 'danger' || severity === 'critical') {
+                findings.push({ policy, reason: Number.isFinite(risk) ? `risk score ${risk} met the 70 review threshold` : `explicit ${severity} severity was present` });
+            }
+        }
+        else {
+            const summary = record(record(root.flightRecorder).summary);
+            const unexpected = Number(summary.unexpectedChanges ?? 0);
+            if (unexpected > 0)
+                findings.push({ policy, reason: `${unexpected} unexpected complete observation change(s)` });
+        }
+    }
+    return findings;
+}
+export function formatFailPolicyNotice(findings) {
+    return `Failure policy matched: ${findings.map((item) => `${item.policy} (${item.reason})`).join('; ')}.\n`;
+}

package/cli/formatters/html.mjs

@@ -66,4 +66,4 @@ function formatLookupEvidenceHtml(document) {
 </html>
 `;
 }
-export { escapeHtml, formatLookupEvidenceHtml };
+export { formatLookupEvidenceHtml };

package/cli/formatters/json.mjs

@@ -10,11 +10,11 @@ const CLI_HTTP_SCHEMA = 'whoisleuth.cli.http';
 const CLI_TLS_SCHEMA = 'whoisleuth.cli.tls';
 const CLI_COMPARE_SCHEMA = 'whoisleuth.cli.compare';
 const CLI_LOOKUP_SCHEMA_VERSION = 1;
-const CLI_BULK_SCHEMA_VERSION = 2;
+const CLI_BULK_SCHEMA_VERSION = 3;
 const CLI_CT_SEARCH_SCHEMA_VERSION = 1;
 const CLI_DISCOVER_SCHEMA_VERSION = 2;
 const CLI_POSTURE_SCHEMA_VERSION = 1;
-const CLI_HTTP_SCHEMA_VERSION = 1;
+const CLI_HTTP_SCHEMA_VERSION = 2;
 const CLI_TLS_SCHEMA_VERSION = 1;
 const CLI_COMPARE_SCHEMA_VERSION = 3;
 function buildCliLookupDocument(query, classified, result, generatedAt = new Date().toISOString(), mode = 'fast', collectionContext = {}) {
@@ -25,6 +25,7 @@ function buildCliLookupDocument(query, classified, result, generatedAt = new Dat
         ? collectionContext.vantageLabel
         : null;
     return {
+        ...result,
         schema: CLI_LOOKUP_SCHEMA,
         version: CLI_LOOKUP_SCHEMA_VERSION,
         generatedAt,
@@ -40,7 +41,6 @@ function buildCliLookupDocument(query, classified, result, generatedAt = new Dat
                 ...(vantageLabel ? { vantageLabel } : {}),
             },
         } : {}),
-        ...result,
     };
 }
 function formatJsonDocument(document) {
@@ -105,15 +105,21 @@ function buildCliCompareDocument(result, generatedAt = new Date().toISOString())
     return { ...result, schema: CLI_COMPARE_SCHEMA, version: CLI_COMPARE_SCHEMA_VERSION, generatedAt };
 }
 function bulkJsonItem(item, metadata) {
+    const provenance = {
+        observedAt: item.observedAt ?? null,
+        collectionOrigin: item.collectionOrigin ?? 'current_run',
+    };
     if (!item.ok) {
         return {
             schema: CLI_BULK_ITEM_SCHEMA, version: CLI_BULK_SCHEMA_VERSION, generatedAt: metadata.generatedAt,
+            ...provenance,
             index: item.index, query: item.query, ok: false, error: item.error,
         };
     }
     const result = item.result;
     return {
         schema: CLI_BULK_ITEM_SCHEMA, version: CLI_BULK_SCHEMA_VERSION, generatedAt: metadata.generatedAt,
+        ...provenance,
         index: item.index, query: item.query, ok: true,
         type: item.classified.type,
         inputHostname: item.classified.inputHostname,
@@ -142,6 +148,8 @@ function buildCliBulkDocument(items, metadata) {
     };
 }
 function formatJsonLines(items, metadata) {
-    return `${items.map((item) => JSON.stringify(bulkJsonItem(item, metadata))).join('\n')}\n`;
+    return items.length
+        ? `${items.map((item) => JSON.stringify(bulkJsonItem(item, metadata))).join('\n')}\n`
+        : '';
 }
 export { CLI_BULK_ITEM_SCHEMA, CLI_BULK_SCHEMA, CLI_BULK_SCHEMA_VERSION, CLI_COMPARE_SCHEMA, CLI_COMPARE_SCHEMA_VERSION, CLI_CT_SEARCH_SCHEMA, CLI_CT_SEARCH_SCHEMA_VERSION, CLI_DISCOVER_ITEM_SCHEMA, CLI_DISCOVER_SCHEMA, CLI_DISCOVER_SCHEMA_VERSION, CLI_HTTP_SCHEMA, CLI_HTTP_SCHEMA_VERSION, CLI_POSTURE_SCHEMA, CLI_POSTURE_SCHEMA_VERSION, CLI_TLS_SCHEMA, CLI_TLS_SCHEMA_VERSION, CLI_LOOKUP_SCHEMA, CLI_LOOKUP_SCHEMA_VERSION, buildCliBulkDocument, buildCliCompareDocument, buildCliCtSearchDocument, buildCliDiscoverDocument, buildCliHttpDocument, buildCliLookupDocument, buildCliPostureDocument, buildCliTlsDocument, bulkJsonItem, discoverJsonItem, formatDiscoverDomainList, formatDiscoverJsonLines, formatJsonDocument, formatJsonLines, };

package/cli/formatters/terminal.mjs

@@ -431,7 +431,7 @@ function formatTerminalHttp(document) {
     const lines = [
         `Domain         ${safeTerminalValue(document.domain)}`,
         `Probe          ${titleCase(document.probeStatus)}`,
-        `Activity       ${titleCase(document.activityStatus)}`,
+        `Assessment     ${titleCase(document.assessment ?? document.activityStatus)}`,
         `Evidence       ${titleCase(http.status)}`,
         `Final URL      ${safeTerminalValue(http.finalUrl)}`,
         `HTTP status    ${safeTerminalValue(response.status)}`,

package/cli/http.mjs

@@ -17,7 +17,8 @@ function buildHttpProbeResult(domain, probe) {
     return {
         domain,
         probeStatus: status,
-        activityStatus: status === 'fetched' || status === 'responded' ? 'active' : 'unreachable',
+        assessment: status === 'fetched' || status === 'responded' ? 'active' : 'inconclusive',
+        activityStatus: status === 'fetched' || status === 'responded' ? 'active' : null,
         detail: boundedDetail(input.detail),
         http: input.http && typeof input.http === 'object' && !Array.isArray(input.http)
             ? input.http

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-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/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');
+}