@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/frontend/src/lib/analysis/lookup-summary-model.js

@@ -0,0 +1,398 @@
+import { fmtAge, fmtExpiresIn, formatActivityCell, formatPrivacyCell, } from "./scoring.js";
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;
+const MAX_SIGNALS = 12;
+const MAX_PROVENANCE_ITEMS = 8;
+const MAX_PROVENANCE_TEXT = 320;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maximum = 320) {
+    return String(value ?? '')
+        .replace(CONTROL_CHARACTERS, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, maximum);
+}
+function display(value) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    if (Array.isArray(value)) {
+        return value.slice(0, 16).map((item) => boundedText(item, 120)).filter(Boolean).join(', ') || '—';
+    }
+    if (typeof value === 'object') {
+        const item = record(value);
+        return display(item.name || item.org || item.handle || item.domain);
+    }
+    return boundedText(value) || '—';
+}
+function textOrNull(value) {
+    const valueText = typeof value === 'string' ? boundedText(value) : '';
+    return valueText || null;
+}
+function records(value) {
+    return Array.isArray(value)
+        ? value.slice(0, 24).map(record).filter((item) => Object.keys(item).length > 0)
+        : [];
+}
+function textList(value, maximum = MAX_PROVENANCE_ITEMS) {
+    if (!Array.isArray(value))
+        return [];
+    const output = [];
+    const seen = new Set();
+    for (const item of value) {
+        const text = boundedText(item, MAX_PROVENANCE_TEXT);
+        if (!text || seen.has(text))
+            continue;
+        output.push(text);
+        seen.add(text);
+        if (output.length >= maximum)
+            break;
+    }
+    return output;
+}
+function formatDate(value) {
+    if (!value)
+        return '—';
+    const parsed = new Date(String(value));
+    return Number.isNaN(parsed.getTime()) ? boundedText(value) || '—' : parsed.toLocaleString();
+}
+function statusLabel(value) {
+    return boundedText(value, 64).replaceAll('_', ' ') || 'unknown';
+}
+function diagnosticDetail(value) {
+    const source = record(value);
+    const attempts = Array.isArray(source.attempts)
+        ? source.attempts.slice(0, 8).map((attempt) => (statusLabel(record(attempt).outcome))).join(' → ')
+        : '';
+    const parts = [
+        boundedText(source.endpoint, 2_048),
+        source.transportSecurity === 'http' ? 'transport: cleartext HTTP' : '',
+        typeof source.httpStatus === 'number' ? `HTTP ${source.httpStatus}` : '',
+        attempts ? `attempts: ${attempts}` : '',
+        source.resultState ? `result: ${boundedText(source.resultState, 80)}` : '',
+        boundedText(source.errorCode, 120),
+        source.authoritativeHop ? `authoritative: ${display(source.authoritativeHop)}` : '',
+        source.failedHop ? `failed: ${display(source.failedHop)}` : '',
+        source.fetchedAt ? `fetched ${formatDate(source.fetchedAt)}` : '',
+        source.queriedAt ? `queried ${formatDate(source.queriedAt)}` : '',
+    ].filter(Boolean);
+    return boundedText(parts.join(' · '), 2_400) || 'No additional source detail';
+}
+function sourceLabel(value) {
+    return {
+        dns: 'Authoritative DNS delegation',
+        rdap: 'Registry RDAP',
+        whois: 'WHOIS',
+    }[boundedText(value, 32)] || 'No conclusive registration source';
+}
+function sourceObservation(source, diagnostics, fallback) {
+    const sourceId = boundedText(source, 32);
+    const diagnostic = sourceId === 'dns'
+        ? record(diagnostics.availability)
+        : record(diagnostics[sourceId]);
+    return formatDate(diagnostic.fetchedAt
+        || diagnostic.queriedAt
+        || diagnostic.observedAt
+        || fallback);
+}
+function sourceCompleteness(source, diagnostics) {
+    const sourceId = boundedText(source, 32);
+    const diagnostic = sourceId === 'dns'
+        ? record(diagnostics.availability)
+        : record(diagnostics[sourceId]);
+    return statusLabel(diagnostic.status);
+}
+function registryLimitations(availability, rdapParsed, whoisParsed) {
+    const output = [
+        ...textList(availability.limitations),
+        ...textList(whoisParsed.limitations),
+    ];
+    if (rdapParsed.serverTruncated === true) {
+        output.push('The registry declared that the RDAP response omitted some data.');
+        output.push(...textList(rdapParsed.serverTruncationReasons));
+    }
+    return textList(output);
+}
+function comparisonConflicts(value, labels) {
+    const accepted = new Set(labels);
+    return records(record(value).fields)
+        .filter((field) => accepted.has(boundedText(field.label, 120)))
+        .filter((field) => boundedText(field.status, 64) === 'conflict')
+        .map((field) => boundedText(field.assessment
+        || `${display(field.rdapDisplay || field.registryDisplay)} differs from ${display(field.whoisDisplay || field.registrarDisplay)}`, MAX_PROVENANCE_TEXT))
+        .filter(Boolean)
+        .slice(0, MAX_PROVENANCE_ITEMS);
+}
+function factProvenance(input) {
+    return {
+        sources: [sourceLabel(input.source)],
+        observedAt: sourceObservation(input.source, input.diagnostics, input.observedAt),
+        fieldFamilies: input.fields.map((item) => boundedText(item, 160)).filter(Boolean),
+        normalization: boundedText(input.normalization, MAX_PROVENANCE_TEXT),
+        completeness: sourceCompleteness(input.source, input.diagnostics),
+        limitations: textList(input.limitations),
+        conflicts: textList(input.conflicts),
+        decisionImpact: boundedText(input.decisionImpact, MAX_PROVENANCE_TEXT),
+    };
+}
+function pushSignal(signals, signal) {
+    if (signal && signals.length < MAX_SIGNALS)
+        signals.push(signal);
+}
+function buildSignals(availability, profileSignals, idnAnalysis) {
+    const signals = [];
+    const trusted = boundedText(profileSignals.trusted, 80);
+    if (trusted)
+        pushSignal(signals, { label: `Trusted ${trusted}`, tone: 'good' });
+    if (profileSignals.faviconMatch === true) {
+        pushSignal(signals, { label: 'Favicon match', tone: 'danger' });
+    }
+    else if (profileSignals.faviconNearMatch === true) {
+        pushSignal(signals, { label: 'Favicon near-match', tone: 'warn' });
+    }
+    if (profileSignals.reusesOfficialAssets === true) {
+        pushSignal(signals, { label: 'Reuses official assets', tone: 'danger' });
+    }
+    if (availability.hasPasswordField === true) {
+        pushSignal(signals, { label: 'Password field', tone: 'warn' });
+    }
+    const phishingLanguage = textOrNull(availability.phishingLanguageMatch);
+    if (phishingLanguage) {
+        pushSignal(signals, {
+            label: 'Phishing language',
+            tone: 'danger',
+            detail: phishingLanguage,
+        });
+    }
+    if (idnAnalysis.mixedScript === true) {
+        pushSignal(signals, {
+            label: 'Mixed-script IDN',
+            tone: 'warn',
+            detail: 'The Unicode label combines writing scripts.',
+        });
+    }
+    if (Array.isArray(idnAnalysis.referenceMatches) && idnAnalysis.referenceMatches.length > 0) {
+        pushSignal(signals, {
+            label: 'Official-domain skeleton match',
+            tone: 'warn',
+            detail: 'A bounded visual skeleton matches an official domain in the active brand profile.',
+        });
+    }
+    const domainAgeDays = typeof availability.domainAgeDays === 'number'
+        ? availability.domainAgeDays
+        : null;
+    const age = fmtAge(domainAgeDays);
+    if (age)
+        pushSignal(signals, { label: age, tone: 'neutral' });
+    const expiresInDays = typeof availability.expiresInDays === 'number'
+        ? availability.expiresInDays
+        : null;
+    const expiry = fmtExpiresIn(expiresInDays);
+    if (expiry && expiresInDays !== null) {
+        pushSignal(signals, {
+            label: expiry,
+            tone: expiresInDays <= 60 ? 'warn' : 'neutral',
+        });
+    }
+    if (typeof availability.privacyProtected === 'boolean') {
+        pushSignal(signals, {
+            label: formatPrivacyCell(availability.privacyProtected),
+            tone: availability.privacyProtected ? 'warn' : 'good',
+        });
+    }
+    const activityStatus = textOrNull(availability.activityStatus);
+    if (activityStatus) {
+        const detail = textOrNull(availability.websiteProbeDetail);
+        pushSignal(signals, {
+            label: formatActivityCell(activityStatus, availability.hasMx === true, availability.hasSpf === true, availability.hasDmarc === true),
+            tone: activityStatus === 'active'
+                ? 'good'
+                : activityStatus === 'parked'
+                    ? 'warn'
+                    : 'neutral',
+            ...(detail ? { detail } : {}),
+        });
+    }
+    return signals;
+}
+function diagnosticAttempts(value) {
+    return records(value).slice(0, 8).map((attempt) => ({
+        endpoint: boundedText(attempt.endpoint, 2_048) || 'Endpoint not recorded',
+        outcome: statusLabel(attempt.outcome),
+        detail: boundedText(typeof attempt.status === 'number'
+            ? `HTTP ${attempt.status}${attempt.detail ? ` · ${boundedText(attempt.detail, 240)}` : ''}`
+            : attempt.detail, MAX_PROVENANCE_TEXT) || 'No additional attempt detail',
+    }));
+}
+function buildDiagnostics(diagnostics, rdapParsed, whoisParsed, registrarRdap) {
+    const sources = ['rdap', 'whois', 'availability'].map((source) => {
+        const item = record(diagnostics[source]);
+        const status = boundedText(item.status, 64);
+        const isRdap = source === 'rdap';
+        const isWhois = source === 'whois';
+        return {
+            source,
+            status,
+            label: statusLabel(status),
+            detail: diagnosticDetail(item),
+            endpoint: boundedText(item.endpoint, 2_048),
+            route: isRdap
+                ? 'The endpoint was selected through IANA RDAP bootstrap discovery and bounded endpoint failover.'
+                : isWhois
+                    ? 'The response follows the bounded WHOIS registry and referral chain shown below.'
+                    : 'This derived state applies the authority-aware availability rules to the collected registration evidence.',
+            observedAt: formatDate(item.fetchedAt || item.queriedAt || item.observedAt),
+            conformance: isRdap ? textList(rdapParsed.conformance) : [],
+            limitations: isRdap
+                ? registryLimitations({}, rdapParsed, {})
+                : isWhois
+                    ? textList(whoisParsed.limitations)
+                    : [],
+            attempts: diagnosticAttempts(item.attempts),
+        };
+    });
+    if (registrarRdap.status) {
+        const registrarDiagnostic = record(record(diagnostics.rdap).registrar);
+        const status = boundedText(registrarRdap.status || registrarDiagnostic.status, 64);
+        sources.push({
+            source: 'registrar RDAP',
+            status,
+            label: statusLabel(status),
+            detail: diagnosticDetail(registrarDiagnostic),
+            endpoint: boundedText(registrarRdap.endpoint || registrarDiagnostic.endpoint, 2_048),
+            route: 'This is a separately attributed registrar publication discovered from the registry RDAP response.',
+            observedAt: formatDate(registrarRdap.fetchedAt || registrarDiagnostic.fetchedAt),
+            conformance: textList(record(registrarRdap.parsed).conformance),
+            limitations: textList(registrarRdap.limitations),
+            attempts: diagnosticAttempts(registrarRdap.attempt ? [registrarRdap.attempt] : registrarDiagnostic.attempts),
+        });
+    }
+    const reverseDns = record(diagnostics.reverseDns);
+    if (reverseDns.status) {
+        const status = boundedText(reverseDns.status, 64);
+        sources.push({
+            source: 'reverse DNS',
+            status,
+            label: statusLabel(status),
+            detail: diagnosticDetail(reverseDns),
+            endpoint: '',
+            route: 'PTR evidence is non-authoritative context published by the address operator.',
+            observedAt: formatDate(reverseDns.observedAt),
+            conformance: [],
+            limitations: [],
+            attempts: [],
+        });
+    }
+    return sources;
+}
+export function buildLookupSummaryModel(input) {
+    const availability = record(input.availability);
+    const rdapParsed = record(input.rdapParsed);
+    const whoisParsed = record(input.whoisParsed);
+    const diagnostics = record(input.diagnostics);
+    const source = availability.source;
+    const limitations = registryLimitations(availability, rdapParsed, whoisParsed);
+    const registryComparison = input.registryComparison;
+    const registrarPublicationComparison = input.registrarPublicationComparison;
+    return {
+        signals: buildSignals(availability, record(input.profileSignals), record(input.idnAnalysis)),
+        facts: [
+            {
+                label: 'Registration',
+                value: display(availability.state || whoisParsed.registrationStatus),
+                detail: `${display(availability.confidence)} confidence`,
+                provenance: factProvenance({
+                    source,
+                    diagnostics,
+                    observedAt: input.resultObservedAt,
+                    fields: ['RDAP object state', 'WHOIS registration status', 'authoritative DNS delegation'],
+                    normalization: 'Authority-aware registration evidence is normalised into a stable availability state while inconclusive sources remain unknown.',
+                    limitations,
+                    conflicts: comparisonConflicts(registryComparison, ['Registration status']),
+                    decisionImpact: 'This is the authority-aware input to the availability result. This inspector does not recalculate or override that decision.',
+                }),
+            },
+            {
+                label: 'Registrar',
+                value: display(availability.registrar || rdapParsed.registrar || whoisParsed.registrar),
+                detail: display(whoisParsed.registrarUrl),
+                provenance: factProvenance({
+                    source,
+                    diagnostics,
+                    observedAt: input.resultObservedAt,
+                    fields: ['RDAP registrar entity', 'WHOIS Registrar', 'registrar RDAP registrar entity'],
+                    normalization: 'Structured registrar identities are reduced to a bounded display name while each registry, registrar, and WHOIS publication remains separate.',
+                    limitations,
+                    conflicts: [
+                        ...comparisonConflicts(registryComparison, ['Registrar', 'Registrar IANA ID']),
+                        ...comparisonConflicts(registrarPublicationComparison, ['Registrar', 'Registrar IANA ID']),
+                    ],
+                    decisionImpact: 'Registrar identity is investigative and contact context. It does not decide whether the domain exists or establish ownership.',
+                }),
+            },
+            {
+                label: 'Created',
+                value: formatDate(input.createdDate),
+                detail: fmtAge(typeof availability.domainAgeDays === 'number' ? availability.domainAgeDays : null) || 'Registry lifecycle date',
+                provenance: factProvenance({
+                    source,
+                    diagnostics,
+                    observedAt: input.resultObservedAt,
+                    fields: ['RDAP registration event or lifecycle', 'WHOIS creation-date family'],
+                    normalization: 'Recognised lifecycle dates are parsed into an ISO-compatible instant when possible; the original source publication remains authoritative.',
+                    limitations,
+                    conflicts: comparisonConflicts(registryComparison, ['Created']),
+                    decisionImpact: 'Domain age may contribute to an explainable score factor. It does not prove intent, ownership, or continuous operation.',
+                }),
+            },
+            {
+                label: 'Expires',
+                value: formatDate(input.expiresDate),
+                detail: fmtExpiresIn(typeof availability.expiresInDays === 'number' ? availability.expiresInDays : null) || 'Registry lifecycle date',
+                provenance: factProvenance({
+                    source,
+                    diagnostics,
+                    observedAt: input.resultObservedAt,
+                    fields: ['RDAP expiration event or lifecycle', 'WHOIS expiry-date family'],
+                    normalization: 'Recognised expiry dates are parsed into an ISO-compatible instant when possible without predicting deletion or release.',
+                    limitations,
+                    conflicts: comparisonConflicts(registryComparison, ['Expires']),
+                    decisionImpact: 'Expiry proximity may contribute to an explainable opportunity factor. It does not predict renewal, deletion, release, price, or eligibility.',
+                }),
+            },
+            {
+                label: 'Updated',
+                value: formatDate(input.updatedDate),
+                detail: 'Most recent registry change',
+                provenance: factProvenance({
+                    source,
+                    diagnostics,
+                    observedAt: input.resultObservedAt,
+                    fields: ['RDAP last-changed event or lifecycle', 'WHOIS updated-date family'],
+                    normalization: 'Recognised update dates are parsed into an ISO-compatible instant when possible and remain a source-reported lifecycle observation.',
+                    limitations,
+                    conflicts: comparisonConflicts(registryComparison, ['Updated']),
+                    decisionImpact: 'The update date is contextual evidence only and does not establish what changed or whether a website is active.',
+                }),
+            },
+            {
+                label: 'Website',
+                value: display(availability.activityStatus),
+                detail: display(availability.websiteProbeDetail),
+                provenance: {
+                    sources: ['Bounded homepage and favicon observation'],
+                    observedAt: formatDate(input.resultObservedAt),
+                    fieldFamilies: ['HTTP response', 'redirect chain', 'bounded homepage body', 'favicon response'],
+                    normalization: 'Observed responses are classified into active, parked, inactive, or unknown context without executing page scripts.',
+                    completeness: availability.deepScanComplete === false ? 'partial' : 'complete',
+                    limitations: textList(record(availability.http).limitations),
+                    conflicts: [],
+                    decisionImpact: 'Website activity can inform explainable analysis. A failed or missing response never implies inactivity, safety, or domain availability.',
+                },
+            },
+        ],
+        diagnostics: buildDiagnostics(diagnostics, rdapParsed, whoisParsed, record(input.registrarRdap)),
+    };
+}

package/frontend/src/lib/analysis/page-similarity.js

@@ -141,7 +141,7 @@ export function comparePageBaselines(rawReference, rawObserved) {
     if (!reference || !observed)
         return null;
     const components = [
-        digestComponent('normalized_html', 'Normalized HTML', 'Normalized-HTML', reference.normalizedHtml, observed.normalizedHtml),
+        digestComponent('normalized_html', 'Normalised HTML', 'Normalized-HTML', reference.normalizedHtml, observed.normalizedHtml),
         visibleTextComponent(reference.visibleText, observed.visibleText),
         domStructureComponent(reference.domStructure, observed.domStructure),
         formComponent(reference.formStructure, observed.formStructure),

package/frontend/src/lib/analysis/relationship-evidence.js

@@ -206,16 +206,16 @@ export function buildScanRelationships(rawRows) {
     const output = [];
     for (const [value, domains] of nameserverSets)
         if (domains.size >= 2)
-            output.push(group('nameserver_set', 'Shared nameserver set', 'Exact normalized set', value, [...domains].sort(), 'These domains reported the same normalized nameserver set retained by this scan.'));
+            output.push(group('nameserver_set', 'Shared nameserver set', 'Exact normalised set', value, [...domains].sort(), 'These domains reported the same normalised nameserver set retained by this scan.'));
     for (const [value, domains] of addresses)
         if (domains.size >= 2)
-            output.push(group('ip_address', 'Shared IP address', 'Exact normalized address', value, [...domains].sort(), 'These domains resolved to the same IP address in this scan. Shared hosting and CDNs are common.'));
+            output.push(group('ip_address', 'Shared IP address', 'Exact normalised address', value, [...domains].sort(), 'These domains resolved to the same IP address in this scan. Shared hosting and CDNs are common.'));
     for (const [value, domains] of certificates)
         if (domains.size >= 2)
             output.push(group('certificate', 'Shared TLS certificate', 'Exact leaf-certificate SHA-256', value, [...domains].sort(), 'These domains presented the same leaf certificate in this scan. Multi-domain certificates, shared hosting, CDNs, and managed platforms are common.'));
     for (const [value, domains] of identifiers)
         if (domains.size >= 2)
-            output.push(group('tracking_identifier', 'Shared tracking identifier', 'Exact public identifier', value, [...domains].sort(), 'These pages exposed the same recognized public tracking identifier in bounded static HTML.'));
+            output.push(group('tracking_identifier', 'Shared tracking identifier', 'Exact public identifier', value, [...domains].sort(), 'These pages exposed the same recognised public tracking identifier in bounded static HTML.'));
     const faviconRows = rows.slice(0, MAX_FAVICON_ROWS).map(({ domain, observation }) => ({
         domain,
         faviconHash: typeof observation.faviconHash === 'string' && FAVICON_SHA_RE.test(observation.faviconHash)

package/frontend/src/lib/analysis/relationship-observation-model.js

@@ -24,12 +24,12 @@ const TYPES = new Set(RELATIONSHIP_OBSERVATION_TYPES);
 const TYPE_METADATA = Object.freeze({
     nameserver_set: Object.freeze({
         label: 'Shared nameserver set',
-        method: 'Exact normalized set',
-        description: 'These domains reported the same normalized nameserver set. Shared DNS providers are common.',
+        method: 'Exact normalised set',
+        description: 'These domains reported the same normalised nameserver set. Shared DNS providers are common.',
     }),
     ip_address: Object.freeze({
         label: 'Shared IP address',
-        method: 'Exact normalized address',
+        method: 'Exact normalised address',
         description: 'These domains resolved to the same IP address. Shared hosting, CDNs, and managed platforms are common.',
     }),
     certificate: Object.freeze({
@@ -40,7 +40,7 @@ const TYPE_METADATA = Object.freeze({
     tracking_identifier: Object.freeze({
         label: 'Shared tracking identifier',
         method: 'Exact public identifier',
-        description: 'These pages exposed the same recognized public tracking identifier in bounded static HTML.',
+        description: 'These pages exposed the same recognised public tracking identifier in bounded static HTML.',
     }),
     favicon: Object.freeze({
         label: 'Similar favicon',

package/frontend/src/lib/analysis/scoring.js

@@ -1,13 +1,9 @@
 export { RISK_MODEL_VERSION, RISK_REVIEW_THRESHOLD, computeRiskScore, explainRiskScore, formatScoreBreakdown, normalizeRiskModelVersion, riskTone, } from "../../../../lib/risk-scoring.mjs";
-function plainRecord(value) {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : null;
-}
+export { OPPORTUNITY_MODEL_VERSION, OPPORTUNITY_REVIEW_THRESHOLD, computeOpportunityScore, explainOpportunityScore, normalizeOpportunityModelVersion, opportunityTone, } from "../../../../lib/opportunity-scoring.mjs";
 export function fmtAge(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value))
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
         return null;
-    const days = value;
+    const days = Math.round(value);
     if (days < 60)
         return `${days}d old`;
     const years = days / 365.25;
@@ -16,7 +12,7 @@ export function fmtAge(value) {
 export function fmtExpiresIn(value) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return null;
-    const days = value;
+    const days = Math.round(value);
     return days < 0 ? `expired ${Math.abs(days)}d ago` : `expires in ${days}d`;
 }
 export const ACTIVITY_LABELS = {
@@ -39,92 +35,16 @@ export function formatActivityCell(v, hasMx, hasSpf, hasDmarc) {
         ? ACTIVITY_LABELS[v]
         : '—';
     const mailParts = [];
-    if (hasMx)
+    if (hasMx === true)
         mailParts.push('MX');
-    if (hasSpf)
+    if (hasSpf === true)
         mailParts.push('SPF');
-    if (hasDmarc)
+    if (hasDmarc === true)
         mailParts.push('DMARC');
     return mailParts.length ? `${label} · ${mailParts.join('+')}` : label;
 }
-// ---------------------------------------------------------------------------
-// Opportunity score: combines the signals above into one 0-100 number so a
-// large fast-scan result set can be sorted instead of manually scanned.
-// Higher = more actionable (cheap/easy to get), not "more valuable" in an
-// appraisal sense - a parked, aged, publicly-contactable domain scores high
-// because it's an easy approach; an actively-used one scores low because
-// the owner is unlikely to be interested regardless of the domain's worth.
-// ---------------------------------------------------------------------------
-const STATE_BASE_SCORE = {
-    for_sale: 95,
-    expiring: 85,
-    available: 90,
-    registered: 40,
-    unknown: null,
-    error: null,
-};
-const STATE_LABELS = {
-    for_sale: 'for sale',
-    expiring: 'expiring/pending delete',
-    available: 'available',
-    registered: 'registered',
-};
-// Builds the opportunity score alongside a factor-by-factor breakdown (base
-// state score, then each signal's contribution) - the single source of
-// truth computeOpportunityScore() below reads its final number from, and
-// what the score chips' tooltips and the CSV export both render from, so
-// the displayed reasoning can never drift from the actual number.
-export function explainOpportunityScore(value) {
-    const r = plainRecord(value);
-    if (!r)
-        return null;
-    const rawState = r.availability ?? r.state;
-    if (typeof rawState !== 'string')
-        return null;
-    const state = rawState;
-    const base = STATE_BASE_SCORE[state];
-    if (base === null || base === undefined)
-        return null;
-    const factors = [{ label: `Base score for "${STATE_LABELS[state] || state}"`, delta: base }];
-    let score = base;
-    if (r.activityStatus === 'parked') {
-        factors.push({ label: 'Parked/for-sale page', delta: 15 });
-        score += 15;
-    }
-    else if (r.activityStatus === 'no_site') {
-        factors.push({ label: 'No site running', delta: 5 });
-        score += 5;
-    }
-    else if (r.activityStatus === 'active') {
-        factors.push({ label: 'Active site in use', delta: -20 });
-        score -= 20;
-    }
-    if (r.privacyProtected === false) {
-        factors.push({ label: 'Contact info public', delta: 10 });
-        score += 10;
-    }
-    else if (r.privacyProtected === true) {
-        factors.push({ label: 'WHOIS privacy protected', delta: -10 });
-        score -= 10;
-    }
-    if (typeof r.domainAgeDays === 'number') {
-        const ageBonus = Math.min(20, (r.domainAgeDays / 365) * 2);
-        if (ageBonus !== 0) {
-            factors.push({ label: `Domain age (${fmtAge(r.domainAgeDays)})`, delta: ageBonus });
-            score += ageBonus;
-        }
-    }
-    if (state === 'registered' && typeof r.expiresInDays === 'number' && r.expiresInDays >= 0 && r.expiresInDays < 30) {
-        factors.push({ label: 'Expires within 30 days', delta: 10 }); // might lapse soon even though not yet flagged "expiring"
-        score += 10;
-    }
-    return { score: Math.max(0, Math.min(100, Math.round(score))), factors };
-}
-export function computeOpportunityScore(value) {
-    const explained = explainOpportunityScore(value);
-    return explained ? explained.score : null;
-}
 export function scoreTone(score) {
+    // Kept as a compatibility name for existing UI callers.
     if (score === null)
         return 'neutral';
     if (score >= 70)

package/frontend/src/lib/analysis/shortlist-model.js

@@ -2,9 +2,10 @@
 // and downloads; this module owns schema migration, record normalization,
 // import merging, and exact serialized-byte accounting.
 import { compactWatchlistResults } from "./watchlist-history.js";
-import { normalizeRiskModelVersion } from "./scoring.js";
+import { normalizeOpportunityModelVersion, normalizeRiskModelVersion } from "./scoring.js";
 export const SHORTLIST_SCHEMA = 'whoisleuth.shortlist';
-export const SHORTLIST_SCHEMA_VERSION = 2;
+export const SHORTLIST_SCHEMA_VERSION = 3;
+export const SUPPORTED_SHORTLIST_SCHEMA_VERSIONS = Object.freeze([2, SHORTLIST_SCHEMA_VERSION]);
 export const MAX_SHORTLIST_ENTRIES = 500;
 export const MAX_SHORTLIST_INPUTS = MAX_SHORTLIST_ENTRIES * 4;
 export const MAX_SHORTLIST_STORE_BYTES = 1024 * 1024;
@@ -84,6 +85,9 @@ export function normalizeShortlistRecord(raw, options = {}) {
         riskScore,
         riskFactors: factors(value.riskFactors),
         opportunityScore: score(value.opportunityScore),
+        opportunityModelVersion: score(value.opportunityScore) === null
+            ? null
+            : normalizeOpportunityModelVersion(value.opportunityModelVersion),
         savedAt: timestamp(value.savedAt, timestamp(options.fallbackTimestamp, EPOCH)),
     };
 }
@@ -168,8 +172,8 @@ export function mergeShortlistStores(localRaw, importedRaw) {
     if (importedVersion !== null && importedVersion > SHORTLIST_SCHEMA_VERSION) {
         throw new Error(`This shortlist file uses newer schema ${importedVersion}. Update the app before importing it.`);
     }
-    if (importedVersion !== SHORTLIST_SCHEMA_VERSION) {
-        throw new Error(`Expected a WHOISleuth shortlist export using schema ${SHORTLIST_SCHEMA_VERSION}.`);
+    if (importedVersion === null || !SUPPORTED_SHORTLIST_SCHEMA_VERSIONS.includes(importedVersion)) {
+        throw new Error(`Expected a WHOISleuth shortlist export using schema ${SUPPORTED_SHORTLIST_SCHEMA_VERSIONS.join(' or ')}.`);
     }
     const local = normalizeShortlistStore(localRaw).entries;
     const byDomain = new Map(local.map((record) => [record.domain, record]));