@slicedearth/whoisleuth-cli 1.47.4 → 2.0.1

package/frontend/src/lib/analysis/lookup-decision-support.js

@@ -1,542 +0,0 @@
-const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;
-const MAX_TEXT = 320;
-const MAX_ENTRIES = 24;
-const MAX_ACTIONS = 6;
-export const MAX_LOOKUP_PRESENTED_ACTIONS = 3;
-const LOOKUP_TASK_EVIDENCE_KINDS = new Set([
-    'delegation', 'dependency', 'dns', 'form', 'http', 'identity', 'mail', 'page',
-    'posture', 'ptr', 'redirect', 'tls',
-]);
-const TASK_ACTION_ID = Object.freeze({
-    acquisition: 'review-acquisition-dependencies',
-    brand: 'review-page-identity',
-    owned: 'review-owned-posture',
-});
-const ACTION_PRIORITY = Object.freeze({
-    high: 0,
-    medium: 1,
-    low: 2,
-});
-const TASK_GUIDANCE = Object.freeze({
-    general: Object.freeze({
-        label: 'General investigation',
-        summary: 'Establish what was observed, which sources agree, and what remains unknown before drawing a conclusion.',
-        questions: Object.freeze([
-            'Which source observations are complete enough to rely on?',
-            'Do registration, infrastructure, certificate, and page identity evidence agree?',
-            'What manual pivot would reduce the most important uncertainty?',
-        ]),
-        prioritySections: Object.freeze(['overview', 'web-evidence', 'registry', 'case-response']),
-    }),
-    acquisition: Object.freeze({
-        label: 'Acquisition review',
-        summary: 'Prioritise registration lifecycle, authority, transfer dependencies, mail, DNS, and services that would need a controlled transition.',
-        questions: Object.freeze([
-            'Is the registration conclusion authoritative and internally consistent?',
-            'Which DNS, mail, certificate, and website dependencies require transition planning?',
-            'Which lifecycle dates are observations rather than guaranteed transfer or deletion dates?',
-        ]),
-        prioritySections: Object.freeze(['overview', 'registry', 'web-evidence', 'case-response']),
-    }),
-    brand: Object.freeze({
-        label: 'Brand review',
-        summary: 'Prioritise declared identity, page similarity, credential surfaces, external destinations, and infrastructure relationships.',
-        questions: Object.freeze([
-            'Does the page claim or resemble a reviewed identity?',
-            'Where do redirects, forms, resources, and trackers cross trust boundaries?',
-            'Which similarities are verified facts and which are only review leads?',
-        ]),
-        prioritySections: Object.freeze(['overview', 'web-evidence', 'external-intelligence', 'case-response']),
-    }),
-    incident: Object.freeze({
-        label: 'Incident response',
-        summary: 'Prioritise current reachability, redirects, certificate state, credential surfaces, warning data, and evidence that can support a reviewed response.',
-        questions: Object.freeze([
-            'What behaviour was observed at the recorded time?',
-            'Which source limitations could change the response decision?',
-            'What evidence and recipient route are ready for a reviewed handoff?',
-        ]),
-        prioritySections: Object.freeze(['overview', 'external-intelligence', 'web-evidence', 'case-response']),
-    }),
-    owned: Object.freeze({
-        label: 'Owned-domain posture',
-        summary: 'Prioritise delegation, mail, certificate, security-policy, lifecycle, and change evidence for a domain under review.',
-        questions: Object.freeze([
-            'Do registry publication and directly observed delegation agree?',
-            'Are mail, certificate, and website controls in the expected state?',
-            'Which incomplete or stale source should be reviewed before recording posture?',
-        ]),
-        prioritySections: Object.freeze(['overview', 'registry', 'web-evidence', 'case-response']),
-    }),
-});
-const TIMING_TO_EVIDENCE = Object.freeze({
-    rdap: Object.freeze(['rdap']),
-    whois: Object.freeze(['whois']),
-    domain_evidence: Object.freeze([
-        'availability',
-        'client-behavior',
-        'dns',
-        'http',
-        'page-identity',
-        'page-role',
-        'security-posture',
-        'sslbl',
-        'technology',
-        'tls',
-    ]),
-    reverse_dns: Object.freeze(['reverse-dns']),
-    registrar_rdap: Object.freeze(['registrar-rdap']),
-    network_context: Object.freeze(['network-context']),
-    security_txt: Object.freeze(['security-txt']),
-    external_intelligence: Object.freeze(['external-intelligence']),
-    malware_host_intelligence: Object.freeze(['malware-host-intelligence']),
-    malware_ioc_intelligence: Object.freeze(['malware-ioc-intelligence']),
-});
-const SUPPORTS = Object.freeze({
-    rdap: Object.freeze(['Registration summary', 'Lifecycle', 'Availability']),
-    whois: Object.freeze(['Registration comparison', 'Contacts', 'Lifecycle']),
-    'registrar-rdap': Object.freeze(['Registration publication comparison']),
-    availability: Object.freeze(['Availability decision', 'Lookup assessment']),
-    dns: Object.freeze(['Delegation', 'Mail posture', 'Service dependencies']),
-    'reverse-dns': Object.freeze(['Observed endpoint context']),
-    'network-context': Object.freeze(['Delivery and routing context']),
-    http: Object.freeze(['Redirects', 'Page collection', 'Website state']),
-    tls: Object.freeze(['Hostname authorisation', 'Certificate scope']),
-    'page-identity': Object.freeze(['Declared page identity', 'Form and resource review']),
-    technology: Object.freeze(['Technology profile']),
-    'security-posture': Object.freeze(['Passive security posture']),
-    'security-txt': Object.freeze(['Security contact route']),
-    sslbl: Object.freeze(['Certificate warning-data comparison']),
-    'external-intelligence': Object.freeze(['Optional external context']),
-});
-const ENDPOINT_CLASS = Object.freeze({
-    rdap: 'Authoritative registry endpoint',
-    whois: 'WHOIS transport',
-    'registrar-rdap': 'Registrar publication endpoint',
-    availability: 'Authority-aware analysis',
-    dns: 'DNS resolver and authorities',
-    'reverse-dns': 'Reverse DNS resolver',
-    'network-context': 'IP RDAP and routing',
-    http: 'Bounded HTTP collection',
-    tls: 'TLS endpoint',
-    'page-identity': 'Static page analysis',
-    technology: 'Derived analysis',
-    'security-posture': 'Derived analysis',
-    'security-txt': 'Selected well-known resource',
-    sslbl: 'Local warning-data snapshot',
-    'external-intelligence': 'Optional external provider',
-});
-const SOURCE_DESCRIPTION = Object.freeze({
-    rdap: 'Structured registration data selected through the registry bootstrap.',
-    whois: 'Referral-aware text registration data collected through the WHOIS service path.',
-    'registrar-rdap': 'A separately attributed registrar publication discovered from registry RDAP.',
-    availability: 'An authority-aware conclusion derived from the enabled registration sources.',
-    dns: 'Point-in-time delegation, address, mail, and service records from bounded DNS collection.',
-    'reverse-dns': 'Operator-published PTR context for an observed public address.',
-    'network-context': 'Point-in-time IP registration and routing context for an observed endpoint.',
-    http: 'A bounded homepage request covering redirects, response metadata, and a capped body prefix.',
-    tls: 'A point-in-time TLS handshake to one validated public address for the requested hostname.',
-    'page-identity': 'Static identity, form, resource, and page-component signals from retained HTML.',
-    technology: 'Curated technology signatures evaluated against already observed page evidence.',
-    'security-posture': 'Passive security controls derived from collected DNS, HTTP, TLS, and page evidence.',
-    'security-txt': 'A bounded request for the selected well-known security contact resource.',
-    sslbl: 'A local comparison against a versioned certificate warning-data snapshot.',
-    'external-intelligence': 'Optional provider context retained with its own source state and limitations.',
-});
-function record(value) {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : {};
-}
-function text(value, maximum = MAX_TEXT) {
-    return String(value ?? '')
-        .replace(CONTROL_CHARACTERS, ' ')
-        .replace(/\s+/gu, ' ')
-        .trim()
-        .slice(0, maximum);
-}
-function idPart(value) {
-    return text(value, 80).toLowerCase().replace(/[^a-z0-9]+/gu, '-').replace(/^-|-$/gu, '');
-}
-function display(value) {
-    const normalized = text(value, 180);
-    return normalized || 'not published';
-}
-function isoDate(value) {
-    if (typeof value !== 'string')
-        return null;
-    const timestamp = Date.parse(value);
-    return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
-}
-function ageDays(value, now) {
-    const current = isoDate(now);
-    if (!value || !current)
-        return null;
-    return Math.max(0, Math.floor((Date.parse(current) - Date.parse(value)) / 86_400_000));
-}
-function taskGuidance(task) {
-    return { task, ...TASK_GUIDANCE[task] };
-}
-function comparisonEntries(comparison, kind) {
-    const output = [];
-    const source = record(comparison);
-    const sourceHealth = record(source.sourceHealth);
-    const fields = Array.isArray(source.fields) ? source.fields.slice(0, 24) : [];
-    for (const item of fields) {
-        const field = record(item);
-        const status = text(field.status, 64);
-        const label = text(field.label, 120) || 'Registration field';
-        const suffix = idPart(label);
-        if (status === 'conflict') {
-            const left = kind === 'registry-whois' ? field.rdapDisplay : field.registryDisplay;
-            const right = kind === 'registry-whois' ? field.whoisDisplay : field.registrarDisplay;
-            output.push({
-                id: `${kind}-${suffix || output.length}`,
-                state: 'conflict',
-                importance: ['Domain', 'Registrar', 'Name servers', 'Statuses'].includes(label) ? 'high' : 'medium',
-                title: `${label} differs between registration sources`,
-                detail: `${display(left)} compared with ${display(right)}.`,
-                sources: kind === 'registry-whois'
-                    ? ['Registry RDAP', 'WHOIS']
-                    : ['Registry RDAP', 'Registrar RDAP'],
-                href: '#registry',
-            });
-            continue;
-        }
-        const unavailableSource = status.startsWith('rdap_')
-            ? 'rdap'
-            : status.startsWith('whois_')
-                ? 'whois'
-                : status.startsWith('registry_')
-                    ? 'registry'
-                    : status.startsWith('registrar_')
-                        ? 'registrar'
-                        : null;
-        const unavailableSourceStatus = unavailableSource
-            ? text(record(sourceHealth[unavailableSource]).status, 64)
-            : null;
-        if ((status.includes('unavailable') || status.includes('incomplete'))
-            && unavailableSourceStatus !== 'unsupported') {
-            output.push({
-                id: `${kind}-${suffix || output.length}-${status}`,
-                state: 'uncertain',
-                importance: 'low',
-                title: `${label} comparison is incomplete`,
-                detail: 'At least one registration source did not provide complete evidence, so no disagreement or equivalence conclusion is available.',
-                sources: kind === 'registry-whois'
-                    ? ['Registry RDAP', 'WHOIS']
-                    : ['Registry RDAP', 'Registrar RDAP'],
-                href: '#registry',
-            });
-        }
-    }
-    return output;
-}
-function hostname(value) {
-    const candidate = typeof value === 'string' ? value : text(record(value).url, 2_048);
-    if (!candidate)
-        return null;
-    try {
-        const url = new URL(/^[a-z][a-z\d+.-]*:\/\//iu.test(candidate) ? candidate : `https://${candidate}`);
-        return url.hostname.toLowerCase().replace(/\.$/u, '');
-    }
-    catch {
-        return null;
-    }
-}
-function sameRegistrableScope(left, right, registrableDomain) {
-    if (left === right)
-        return true;
-    if (!registrableDomain)
-        return false;
-    const belongsToDomain = (value) => (value === registrableDomain || value.endsWith(`.${registrableDomain}`));
-    return belongsToDomain(left) && belongsToDomain(right);
-}
-function identityEntries(input) {
-    const output = [];
-    const requestedHost = hostname(input.requestedHost);
-    const registrableDomain = hostname(input.registrableDomain);
-    const finalHost = hostname(input.finalUrl);
-    const canonicalHost = hostname(input.canonicalUrl);
-    const openGraphHost = hostname(input.openGraphUrl);
-    const tlsAuthorization = record(input.tlsAuthorization);
-    if (tlsAuthorization.authorized === false) {
-        output.push({
-            id: 'tls-hostname-authorization',
-            state: 'conflict',
-            importance: 'high',
-            title: 'The observed certificate did not authorise the requested hostname',
-            detail: text(tlsAuthorization.error, 240) || 'TLS hostname authorisation failed for the requested host.',
-            sources: ['TLS'],
-            href: '#evidence-tls',
-        });
-    }
-    if (requestedHost && finalHost && !sameRegistrableScope(requestedHost, finalHost, registrableDomain)) {
-        output.push({
-            id: 'http-cross-site-final-origin',
-            state: 'conflict',
-            importance: 'medium',
-            title: 'The final website origin is outside the requested domain',
-            detail: `${requestedHost} redirected to ${finalHost}. Review the redirect chain before interpreting identity or control.`,
-            sources: ['HTTP'],
-            href: '#evidence-http',
-        });
-    }
-    if (finalHost && canonicalHost && !sameRegistrableScope(finalHost, canonicalHost, registrableDomain)) {
-        output.push({
-            id: 'page-canonical-origin',
-            state: 'conflict',
-            importance: 'medium',
-            title: 'The declared canonical origin differs from the observed final origin',
-            detail: `${finalHost} served the page while the document declared ${canonicalHost} as canonical.`,
-            sources: ['HTTP', 'HTML'],
-            href: '#evidence-page',
-        });
-    }
-    if (finalHost && openGraphHost && !sameRegistrableScope(finalHost, openGraphHost, registrableDomain)) {
-        output.push({
-            id: 'page-open-graph-origin',
-            state: 'conflict',
-            importance: 'low',
-            title: 'The Open Graph URL points outside the observed final origin',
-            detail: `${finalHost} served the page while Open Graph metadata declared ${openGraphHost}. Publisher metadata is a claim, not identity proof.`,
-            sources: ['HTTP', 'HTML'],
-            href: '#evidence-page',
-        });
-    }
-    return output;
-}
-function certificatePolicyEntries(value) {
-    const review = record(value);
-    const findings = Array.isArray(review.findings) ? review.findings.slice(0, 8) : [];
-    const output = [];
-    for (const item of findings) {
-        const finding = record(item);
-        const id = text(finding.id, 80);
-        const state = text(finding.state, 80);
-        const label = text(finding.label, 120) || 'Certificate policy';
-        if (state === 'apparently_outside_current_policy' || state === 'changed') {
-            output.push({
-                id: `certificate-policy-${id || state}`,
-                state: 'conflict',
-                importance: id === 'expected_spki' ? 'high' : 'medium',
-                title: label,
-                detail: text(finding.detail, 300) || 'Observed certificate context differs from the current reviewed policy context.',
-                sources: Array.isArray(finding.sources) ? finding.sources.map((source) => text(source, 80)).filter(Boolean) : ['DNS', 'TLS'],
-                href: '#evidence-certificate-policy',
-            });
-            continue;
-        }
-        if (state === 'indeterminate' || state === 'no_target_policy_observed') {
-            output.push({
-                id: `certificate-policy-${id || state}`,
-                state: 'uncertain',
-                importance: 'low',
-                title: `${label} is indeterminate`,
-                detail: text(finding.detail, 300) || 'Current evidence does not support a policy comparison.',
-                sources: Array.isArray(finding.sources) ? finding.sources.map((source) => text(source, 80)).filter(Boolean) : ['DNS', 'TLS'],
-                href: '#evidence-certificate-policy',
-            });
-        }
-    }
-    return output;
-}
-function prioritizeEntries(entries, task) {
-    const taskBoost = {
-        general: [],
-        acquisition: ['registry'],
-        brand: ['page', 'http', 'tls'],
-        incident: ['http', 'tls', 'page'],
-        owned: ['registry', 'tls'],
-    };
-    const importance = { high: 0, medium: 1, low: 2 };
-    return [...entries].sort((left, right) => {
-        const leftBoost = taskBoost[task].some((prefix) => left.id.startsWith(prefix)) ? -1 : 0;
-        const rightBoost = taskBoost[task].some((prefix) => right.id.startsWith(prefix)) ? -1 : 0;
-        return importance[left.importance] - importance[right.importance]
-            || leftBoost - rightBoost
-            || left.title.localeCompare(right.title);
-    }).slice(0, 16);
-}
-function normalizedTaskEvidenceKinds(values) {
-    return new Set((values ?? [])
-        .slice(0, 24)
-        .filter((value) => (typeof value === 'string' && LOOKUP_TASK_EVIDENCE_KINDS.has(value))));
-}
-function supportsDecisionDestination(href, evidence) {
-    if (href === '#evidence-tls')
-        return evidence.has('tls');
-    if (href === '#evidence-http')
-        return evidence.has('http') || evidence.has('redirect');
-    if (href === '#evidence-page') {
-        return evidence.has('page') || evidence.has('identity') || evidence.has('form');
-    }
-    if (href === '#evidence-certificate-policy')
-        return evidence.has('tls') || evidence.has('dns');
-    return true;
-}
-function supportsTaskAction(task, targetType, evidence) {
-    if (targetType !== 'domain')
-        return false;
-    const requiredKinds = {
-        acquisition: ['dns', 'mail', 'tls', 'http', 'page', 'dependency'],
-        brand: ['page', 'identity', 'form', 'redirect'],
-        owned: ['delegation', 'mail', 'tls', 'posture'],
-    };
-    return requiredKinds[task]?.some((kind) => evidence.has(kind)) ?? false;
-}
-export function buildLookupDecisionSupport(input) {
-    const availableEvidence = normalizedTaskEvidenceKinds(input.availableEvidence);
-    const entries = prioritizeEntries([
-        ...comparisonEntries(input.registryComparison, 'registry-whois'),
-        ...comparisonEntries(input.registrarPublicationComparison, 'registry-registrar'),
-        ...identityEntries(input),
-        ...certificatePolicyEntries(input.certificatePolicyReview),
-    ], input.task);
-    const actions = [];
-    const firstConflict = entries.find((entry) => entry.state === 'conflict'
-        && supportsDecisionDestination(entry.href, availableEvidence));
-    if (firstConflict) {
-        actions.push({
-            id: 'review-priority-conflict',
-            label: 'Review the highest-priority disagreement',
-            reason: firstConflict.title,
-            expectedOutcome: 'Establish which separately attributed observation is current, authoritative, or still unresolved.',
-            href: firstConflict.href,
-            priority: 'high',
-        });
-    }
-    if (input.refreshPlan.items.length) {
-        actions.push({
-            id: 'review-refresh-options',
-            label: 'Review limited or stale sources',
-            reason: `${input.refreshPlan.items.length} deliberate source refresh option${input.refreshPlan.items.length === 1 ? ' is' : 's are'} available.`,
-            expectedOutcome: 'Determine whether the limitation is transient, persistent, or an expected source constraint.',
-            href: '#evidence-quality',
-            priority: 'medium',
-        });
-    }
-    const firstLimited = input.coverage.entries.find((entry) => entry.manualReviewSuggested);
-    if (firstLimited && !input.refreshPlan.items.some((item) => item.evidenceIds.includes(firstLimited.id))) {
-        actions.push({
-            id: 'inspect-limited-source',
-            label: `Inspect ${firstLimited.label}`,
-            reason: `${firstLimited.statusLabel} evidence may limit downstream conclusions.`,
-            expectedOutcome: `Clarify which conclusions ${firstLimited.label} can and cannot support in its current state.`,
-            href: '#evidence-quality',
-            priority: 'medium',
-        });
-    }
-    if (supportsTaskAction(input.task, input.targetType, availableEvidence) && input.task === 'brand') {
-        actions.push({
-            id: 'review-page-identity',
-            label: 'Review identity and credential evidence',
-            reason: 'Compare declared identity, forms, redirects, and external destinations before making a brand assessment.',
-            expectedOutcome: 'Separate observed identity signals from publisher claims, shared services, and unresolved resemblance leads.',
-            href: '#web-evidence',
-            priority: 'medium',
-        });
-    }
-    else if (supportsTaskAction(input.task, input.targetType, availableEvidence) && input.task === 'acquisition') {
-        actions.push({
-            id: 'review-acquisition-dependencies',
-            label: 'Review transfer dependencies',
-            reason: 'Registration dates alone do not describe the DNS, mail, certificate, and website services that require transition.',
-            expectedOutcome: 'Identify dependencies that must be retained, transferred, replaced, or deliberately retired.',
-            href: '#web-evidence',
-            priority: 'medium',
-        });
-    }
-    else if (supportsTaskAction(input.task, input.targetType, availableEvidence) && input.task === 'owned') {
-        actions.push({
-            id: 'review-owned-posture',
-            label: 'Review delegation and posture evidence',
-            reason: 'Confirm registry publication, authoritative responses, mail, and certificate state together.',
-            expectedOutcome: 'Identify whether observed control state aligns with the reviewed owned-domain baseline.',
-            href: '#web-evidence',
-            priority: 'medium',
-        });
-    }
-    if (input.hasCaseSection) {
-        actions.push({
-            id: 'review-case-handoff',
-            label: 'Record or hand off reviewed evidence',
-            reason: 'Keep observed facts, hypotheses, unknowns, and analyst decisions separate in the case workflow.',
-            expectedOutcome: 'Preserve a reviewable record of what is known, inferred, unresolved, and recommended next.',
-            href: '#case-response',
-            priority: 'low',
-        });
-    }
-    const uniqueActions = [...new Map(actions.map((action) => [action.id, action])).values()].slice(0, MAX_ACTIONS);
-    return {
-        version: 1,
-        guidance: taskGuidance(input.task),
-        entries,
-        actions: uniqueActions,
-        counts: {
-            conflicts: entries.filter((entry) => entry.state === 'conflict').length,
-            uncertainties: entries.filter((entry) => entry.state === 'uncertain').length,
-        },
-    };
-}
-export function projectLookupNextActions(actions, task) {
-    const taskActionId = TASK_ACTION_ID[task];
-    return actions
-        .slice(0, MAX_ACTIONS)
-        .map((action, index) => ({ action, index }))
-        .sort((left, right) => (ACTION_PRIORITY[left.action.priority] - ACTION_PRIORITY[right.action.priority]
-        || Number(right.action.id === taskActionId) - Number(left.action.id === taskActionId)
-        || left.index - right.index))
-        .slice(0, MAX_LOOKUP_PRESENTED_ACTIONS)
-        .map(({ action }) => action);
-}
-function timingByEvidence(timing) {
-    const output = new Map();
-    if (!timing)
-        return output;
-    for (const source of timing.sources) {
-        for (const evidenceId of TIMING_TO_EVIDENCE[source.source]) {
-            output.set(evidenceId, source);
-        }
-    }
-    return output;
-}
-export function buildLookupEvidenceQualityMatrix(input) {
-    const observedAt = isoDate(input.observedAt);
-    const currentAgeDays = ageDays(observedAt, input.now ?? new Date().toISOString());
-    const timings = timingByEvidence(input.timing);
-    const refreshIds = new Set(input.refreshPlan.items.flatMap((item) => item.evidenceIds));
-    const entries = input.coverage.entries.slice(0, MAX_ENTRIES).map((entry) => {
-        const timing = timings.get(entry.id);
-        const entryObservedAt = isoDate(input.observedAtByEvidence?.[entry.id]) ?? observedAt;
-        return {
-            id: entry.id,
-            label: entry.label,
-            category: entry.category,
-            endpointClass: ENDPOINT_CLASS[entry.id] ?? 'Source-specific collection',
-            description: SOURCE_DESCRIPTION[entry.id]
-                ?? 'Source-specific evidence retained with its original state and limitations.',
-            state: entry.state,
-            statusLabel: entry.statusLabel,
-            truncated: entry.truncated,
-            observedAt: entryObservedAt,
-            ageDays: ageDays(entryObservedAt, input.now ?? new Date().toISOString()),
-            durationMs: timing?.durationMs ?? null,
-            timingOutcome: timing?.outcome ?? null,
-            refreshAvailable: refreshIds.has(entry.id),
-            limitations: entry.limitations,
-            supports: SUPPORTS[entry.id] ?? Object.freeze([]),
-        };
-    });
-    return {
-        version: 1,
-        observedAt,
-        totalMs: input.timing?.totalMs ?? null,
-        entries,
-        completeCount: input.coverage.completeCount,
-        limitedCount: input.coverage.limitedCount,
-        stale: input.refreshPlan.stale,
-        ageDays: currentAgeDays,
-        freshnessPolicy: input.refreshPlan.freshnessPolicy,
-    };
-}