@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/cli/registry-doctor.mjs

@@ -0,0 +1,125 @@
+import { registryCapabilityFor, REGISTRY_CAPABILITIES_VERSION } from "../lib/registry-capabilities.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+const REGISTRY_DOCTOR_SCHEMA = 'whoisleuth.cli.registry-doctor';
+const REGISTRY_DOCTOR_VERSION = 1;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function status(value) {
+    return typeof value === 'string'
+        ? value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').trim().toLowerCase().slice(0, 40) || 'unavailable'
+        : 'unavailable';
+}
+function expectedWhois(profile) {
+    if (profile === 'iana-referral')
+        return 'allowed';
+    if (profile === 'registry-policy-restricted' || profile === 'source-ip-authorization-required')
+        return 'permission_required';
+    return 'unsupported';
+}
+function sourceAlignment(expected, observed) {
+    const successful = ['complete', 'partial', 'success'].includes(observed);
+    const constrained = ['disabled', 'skipped', 'unsupported'].includes(observed);
+    if (expected === 'allowed')
+        return successful ? 'observed' : 'investigate';
+    if (successful)
+        return 'unexpected_observation';
+    return constrained ? 'expected_constraint' : 'investigate';
+}
+function normalizedObjectIdentifier(parsed) {
+    const candidate = parsed.handle ?? parsed.objectIdentifier ?? parsed.registryObjectId ?? parsed.id;
+    return typeof candidate === 'string' && candidate.trim() ? 'observed' : 'not_observed';
+}
+function buildRegistryDoctorReport(raw, generatedAt = new Date().toISOString()) {
+    const document = parseSavedLookupDocument(raw, { label: 'Registry doctor input' });
+    const capability = registryCapabilityFor(document.registrableDomain);
+    if (!capability)
+        throw new CliUsageError('Registry doctor could not resolve a capability profile for this domain.');
+    const diagnostics = record(document.diagnostics);
+    const rdap = record(document.rdap);
+    const whois = record(document.whois);
+    const rdapParsed = record(rdap.parsed);
+    const whoisParsed = record(whois.parsed);
+    const sourceInputs = [
+        {
+            source: 'rdap',
+            expected: capability.rdapAccessProfile === 'iana-bootstrap' ? 'allowed' : 'unsupported',
+            observed: status(record(diagnostics.rdap).status),
+            parsed: rdapParsed,
+        },
+        {
+            source: 'whois',
+            expected: expectedWhois(capability.whoisAccessProfile),
+            observed: status(record(diagnostics.whois).status),
+            parsed: whoisParsed,
+        },
+    ];
+    const sources = sourceInputs.map((source) => ({
+        source: source.source,
+        expected: source.expected,
+        observed: source.observed,
+        alignment: sourceAlignment(source.expected, source.observed),
+        normalizedFields: Object.keys(source.parsed).length,
+        objectIdentifier: normalizedObjectIdentifier(source.parsed),
+        limitation: capability.limitation.slice(0, 500),
+    }));
+    const recommendations = [
+        ...sources.filter((source) => source.alignment === 'investigate').map((source) => (source.expected === 'allowed'
+            ? `Review ${source.source.toUpperCase()} source health, transport attempts, and fixture coverage; the catalogue expected collection to be available.`
+            : `Review the ${source.source.toUpperCase()} result and capability profile; the observed state did not match the declared access constraint.`)),
+        ...sources.filter((source) => source.alignment === 'unexpected_observation').map((source) => (`Review why ${source.source.toUpperCase()} produced normalized evidence despite the declared ${source.expected.replaceAll('_', ' ')} access profile.`)),
+        ...sources.filter((source) => source.alignment === 'observed' && source.objectIdentifier === 'not_observed').map((source) => (`${source.source.toUpperCase()} succeeded without a retained registry object identifier; this can be a valid publication omission and should remain unknown rather than an error.`)),
+    ].slice(0, 12);
+    return {
+        schema: REGISTRY_DOCTOR_SCHEMA,
+        version: REGISTRY_DOCTOR_VERSION,
+        generatedAt,
+        domain: document.registrableDomain,
+        suffix: capability.suffixes[0] || document.registrableDomain.split('.').at(-1) || '',
+        catalogueVersion: REGISTRY_CAPABILITIES_VERSION,
+        profile: {
+            id: capability.id,
+            explicitSuffixProfile: capability.explicitSuffixProfile,
+            coverageState: capability.coverageState,
+        },
+        sources,
+        summary: {
+            investigate: sources.filter((source) => source.alignment === 'investigate' || source.alignment === 'unexpected_observation').length,
+            expectedConstraints: sources.filter((source) => source.alignment === 'expected_constraint').length,
+            observed: sources.filter((source) => source.alignment === 'observed').length,
+        },
+        recommendations,
+        limitations: [
+            'This diagnostic compares one saved observation with the local reviewed capability catalogue and makes no registry, registrar, RDAP, or WHOIS request.',
+            'A catalogue alignment does not prove live reachability, parser completeness, current registry policy, registration, availability, ownership, safety, or maliciousness.',
+            'A missing registry object identifier can be a publication characteristic. It remains not observed and is not converted into a collection failure.',
+            'Use fixture-based maintenance checks before changing a registry parser or access profile; automated tests must not contact live registries.',
+        ],
+    };
+}
+function formatRegistryDoctorReport(report) {
+    const output = [
+        'Registry compatibility diagnostic',
+        `Domain             ${report.domain}`,
+        `Profile            ${report.profile.id}${report.profile.explicitSuffixProfile ? ' (explicit)' : ' (default)'}`,
+        `Review items       ${report.summary.investigate}`,
+        '',
+    ];
+    for (const source of report.sources) {
+        output.push(`${source.source.toUpperCase()} [${source.alignment.replaceAll('_', ' ')}]`);
+        output.push(`  Expected: ${source.expected.replaceAll('_', ' ')}`);
+        output.push(`  Observed: ${source.observed.replaceAll('_', ' ')}`);
+        output.push(`  Object identifier: ${source.objectIdentifier.replaceAll('_', ' ')}`);
+    }
+    if (report.recommendations.length) {
+        output.push('', 'Recommendations:');
+        for (const item of report.recommendations)
+            output.push(`  - ${item}`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of report.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { REGISTRY_DOCTOR_SCHEMA, REGISTRY_DOCTOR_VERSION, buildRegistryDoctorReport, formatRegistryDoctorReport, };

package/cli/registry-support.mjs

@@ -1,6 +1,6 @@
 import { registryStandardsCoverageSnapshot, } from "../lib/registry-capabilities.mjs";
 const REGISTRY_SUPPORT_SCHEMA = 'whoisleuth.cli.registry-support';
-const REGISTRY_SUPPORT_SCHEMA_VERSION = 2;
+const REGISTRY_SUPPORT_SCHEMA_VERSION = 3;
 const REGISTRY_STANDARDS_COVERAGE_SCHEMA = 'whoisleuth.registry-standards-coverage';
 const MAX_REGISTRY_SUPPORT_TEXT_LENGTH = 2048;
 const MAX_REGISTRY_SUPPORT_REFERENCES = 20;
@@ -100,9 +100,6 @@ function buildRegistrySupportDocument(requestedInput, capability, catalogueVersi
                 encodingProfile: boundedText(capability.whoisEncodingProfile, 'unknown', 64),
                 parserProfile: boundedText(capability.whoisParserProfile, 'unknown', 128),
             },
-            fallbackProfile: capability.fallbackProfile
-                ? boundedText(capability.fallbackProfile, 'unknown', 128)
-                : null,
         },
         verification: {
             fixtureScenarios: boundedList(capability.fixtureScenarios, 'token'),

package/cli/risk-calibration.mjs

@@ -1,11 +1,13 @@
 import { Buffer } from 'node:buffer';
 import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { ANALYST_REVIEW_REASON_VALUES, analystInteroperabilityTags } from "../lib/analyst-taxonomy.mjs";
 import { CliUsageError } from "./arguments.mjs";
 import { RISK_MUTATION_TYPES, RISK_REVIEW_THRESHOLD } from "../lib/risk-scoring.mjs";
 export const RISK_CALIBRATION_DATASET_SCHEMA = 'whoisleuth.risk-calibration-dataset';
-export const RISK_CALIBRATION_DATASET_VERSION = 1;
+export const RISK_CALIBRATION_DATASET_VERSION = 2;
+export const SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS = Object.freeze([1, RISK_CALIBRATION_DATASET_VERSION]);
 export const RISK_CALIBRATION_REPORT_SCHEMA = 'whoisleuth.cli.risk-calibration';
-export const RISK_CALIBRATION_REPORT_VERSION = 1;
+export const RISK_CALIBRATION_REPORT_VERSION = 2;
 export const MAX_RISK_CALIBRATION_INPUT_BYTES = 2 * 1024 * 1024;
 export const MAX_RISK_CALIBRATION_RECORDS = 500;
 export const MAX_RISK_CALIBRATION_STRING_LENGTH = 256;
@@ -24,8 +26,10 @@ const AVAILABILITY_STATES = new Set(['registered', 'for_sale', 'expiring', 'avai
 const ACTIVITY_STATES = new Set(['active', 'parked', 'unreachable', 'no_site']);
 const BOOLEAN_FIELDS = [
     'faviconMatch', 'faviconNearMatch', 'reusesOfficialAssets', 'hasPasswordField',
-    'hasMx', 'hasSpf', 'hasDmarc', 'privacyProtected',
+    'hasMx', 'hasSpf', 'hasDmarc', 'privacyProtected', 'hasExternalFormAction',
+    'idnReferenceMatch', 'pageBaselineMatch', 'hasActiveBrandProfile',
 ];
+const REVIEW_REASON_CODES = ANALYST_REVIEW_REASON_VALUES;
 const MUTATION_TYPES = new Set(RISK_MUTATION_TYPES);
 function object(value, field) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -109,6 +113,17 @@ function projectEvidence(value, field) {
             throw new CliUsageError(`${field}.activityStatus is unsupported.`);
         result.activityStatus = activity;
     }
+    if (source.scanDepth !== null && source.scanDepth !== undefined) {
+        const depth = boundedString(source.scanDepth, `${field}.scanDepth`, 16);
+        if (depth !== 'fast' && depth !== 'deep')
+            throw new CliUsageError(`${field}.scanDepth must be fast or deep.`);
+        Object.assign(result, { scanDepth: depth });
+    }
+    if (source.observedAt !== null && source.observedAt !== undefined) {
+        const observedAt = optionalTimestamp(source.observedAt, `${field}.observedAt`);
+        if (observedAt)
+            Object.assign(result, { observedAt });
+    }
     if (source.phishingLanguageMatch !== null && source.phishingLanguageMatch !== undefined) {
         result.phishingLanguageMatch = boundedString(source.phishingLanguageMatch, `${field}.phishingLanguageMatch`);
     }
@@ -164,8 +179,13 @@ export function parseRiskCalibrationDataset(text) {
         throw new CliUsageError('Risk calibration input must be valid JSON.');
     }
     const document = object(parsed, 'Risk calibration input');
-    if (document.schema !== RISK_CALIBRATION_DATASET_SCHEMA || document.version !== RISK_CALIBRATION_DATASET_VERSION) {
-        throw new CliUsageError(`Risk calibration input must use ${RISK_CALIBRATION_DATASET_SCHEMA} version ${RISK_CALIBRATION_DATASET_VERSION}.`);
+    const documentVersion = typeof document.version === 'number' && Number.isInteger(document.version)
+        ? document.version
+        : null;
+    if (document.schema !== RISK_CALIBRATION_DATASET_SCHEMA
+        || documentVersion === null
+        || !SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS.includes(documentVersion)) {
+        throw new CliUsageError(`Risk calibration input must use ${RISK_CALIBRATION_DATASET_SCHEMA} version ${SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS.join(' or ')}.`);
     }
     if (!Array.isArray(document.records) || !document.records.length) {
         throw new CliUsageError('Risk calibration input must contain a non-empty records array.');
@@ -187,22 +207,39 @@ export function parseRiskCalibrationDataset(text) {
         const analystDisposition = boundedString(record.analystDisposition, `${prefix}.analystDisposition`, 32);
         if (!DISPOSITIONS.has(analystDisposition))
             throw new CliUsageError(`${prefix}.analystDisposition is unsupported.`);
+        let reviewReasonCode;
+        if (record.reviewReasonCode !== null && record.reviewReasonCode !== undefined) {
+            reviewReasonCode = boundedString(record.reviewReasonCode, `${prefix}.reviewReasonCode`, 64);
+            if (!REVIEW_REASON_CODES.has(reviewReasonCode))
+                throw new CliUsageError(`${prefix}.reviewReasonCode is unsupported.`);
+        }
         return {
             id,
             domain,
             analystDisposition: analystDisposition,
+            ...(reviewReasonCode ? { reviewReasonCode } : {}),
             evidence: projectEvidence(record.evidence, `${prefix}.evidence`),
         };
     });
     return {
         schema: RISK_CALIBRATION_DATASET_SCHEMA,
-        version: RISK_CALIBRATION_DATASET_VERSION,
+        version: documentVersion,
         records,
     };
 }
 function ratio(numerator, denominator) {
     return denominator ? Number((numerator / denominator).toFixed(4)) : null;
 }
+function wilson95(successes, total) {
+    if (!total)
+        return null;
+    const z = 1.96;
+    const proportion = successes / total;
+    const denominator = 1 + (z * z) / total;
+    const center = (proportion + (z * z) / (2 * total)) / denominator;
+    const margin = (z * Math.sqrt((proportion * (1 - proportion) + (z * z) / (4 * total)) / total)) / denominator;
+    return { lower: Number(Math.max(0, center - margin).toFixed(4)), upper: Number(Math.min(1, center + margin).toFixed(4)) };
+}
 function metricsForThreshold(records, threshold) {
     let truePositive = 0;
     let falsePositive = 0;
@@ -217,16 +254,30 @@ function metricsForThreshold(records, threshold) {
         else
             flagged ? falsePositive += 1 : trueNegative += 1;
     }
+    const precision = ratio(truePositive, truePositive + falsePositive);
+    const recall = ratio(truePositive, truePositive + falseNegative);
+    const specificity = ratio(trueNegative, trueNegative + falsePositive);
     return {
         threshold,
         truePositive,
         falsePositive,
         trueNegative,
         falseNegative,
-        precision: ratio(truePositive, truePositive + falsePositive),
-        recall: ratio(truePositive, truePositive + falseNegative),
-        specificity: ratio(trueNegative, trueNegative + falsePositive),
+        precision,
+        recall,
+        specificity,
         falsePositiveRate: ratio(falsePositive, falsePositive + trueNegative),
+        f1: precision === null || recall === null || precision + recall === 0
+            ? null
+            : Number(((2 * precision * recall) / (precision + recall)).toFixed(4)),
+        balancedAccuracy: recall === null || specificity === null
+            ? null
+            : Number(((recall + specificity) / 2).toFixed(4)),
+        confidence95: {
+            precision: wilson95(truePositive, truePositive + falsePositive),
+            recall: wilson95(truePositive, truePositive + falseNegative),
+            specificity: wilson95(trueNegative, trueNegative + falsePositive),
+        },
     };
 }
 function metricClass(disposition) {
@@ -254,6 +305,8 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
             id: record.id,
             domain: record.domain,
             analystDisposition: record.analystDisposition,
+            reviewReasonCode: record.reviewReasonCode ?? null,
+            interoperabilityTags: analystInteroperabilityTags(record.analystDisposition, record.reviewReasonCode),
             metricClass: classification,
             includedInMetrics,
             exclusionReason: includedInMetrics
@@ -273,6 +326,52 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
     const positive = records.filter((record) => record.metricClass === 'positive' && record.score !== null).length;
     const negative = records.filter((record) => record.metricClass === 'negative' && record.score !== null).length;
     const excluded = records.length - positive - negative;
+    const strata = [];
+    const appendStrata = (dimension, values) => {
+        for (const [value, members] of [...values].sort(([left], [right]) => left.localeCompare(right))) {
+            const sampleCount = members.filter((member) => member.includedInMetrics).length;
+            strata.push({
+                dimension,
+                value,
+                sampleCount,
+                insufficientSample: sampleCount < 20,
+                metrics: metricsForThreshold(members, options.reviewThreshold),
+            });
+        }
+    };
+    const byDepth = new Map();
+    const byReason = new Map();
+    for (let index = 0; index < dataset.records.length; index += 1) {
+        const source = dataset.records[index];
+        const scored = records[index];
+        if (!source || !scored)
+            continue;
+        const depth = source.evidence.scanDepth === 'deep' || source.evidence.scanDepth === 'fast' ? source.evidence.scanDepth : 'unknown';
+        byDepth.set(depth, [...(byDepth.get(depth) ?? []), scored]);
+        const reason = source.reviewReasonCode ?? 'not_recorded';
+        byReason.set(reason, [...(byReason.get(reason) ?? []), scored]);
+    }
+    appendStrata('scan_depth', byDepth);
+    appendStrata('review_reason', byReason);
+    let scoresChanged = 0;
+    let bandsChanged = 0;
+    let thresholdClassificationsChanged = 0;
+    if (options.explainPreviousRiskScore) {
+        for (let index = 0; index < dataset.records.length; index += 1) {
+            const source = dataset.records[index];
+            const current = records[index];
+            if (!source || !current)
+                continue;
+            const previous = options.explainPreviousRiskScore(source.evidence);
+            if (previous?.score !== current.score)
+                scoresChanged += 1;
+            if (scoreBand(previous?.score ?? null) !== current.band)
+                bandsChanged += 1;
+            if (((previous?.score ?? -1) >= options.reviewThreshold) !== ((current.score ?? -1) >= options.reviewThreshold)) {
+                thresholdClassificationsChanged += 1;
+            }
+        }
+    }
     return {
         schema: RISK_CALIBRATION_REPORT_SCHEMA,
         version: RISK_CALIBRATION_REPORT_VERSION,
@@ -282,6 +381,15 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
         currentReviewThreshold: options.reviewThreshold,
         summary: { total: records.length, positive, negative, excluded, scoreBands: bands },
         thresholds: RISK_CALIBRATION_THRESHOLDS.map((threshold) => metricsForThreshold(records, threshold)),
+        strata,
+        modelComparison: {
+            available: Boolean(options.explainPreviousRiskScore),
+            previousModelVersion: options.explainPreviousRiskScore ? options.previousModelVersion ?? null : null,
+            currentModelVersion: options.modelVersion,
+            scoresChanged,
+            bandsChanged,
+            thresholdClassificationsChanged,
+        },
         records,
         interpretation: {
             authority: 'analyst_context_only',