@slicedearth/whoisleuth-cli 1.45.0 → 1.47.4

package/lib/risk-calibration-summary.mjs

@@ -0,0 +1,338 @@
+import { ANALYST_REVIEW_REASON_VALUES } from "./analyst-taxonomy.mjs";
+import { scanBoundedJson } from "./bounded-json.mjs";
+import { RISK_REVIEW_THRESHOLD } from "./risk-scoring.mjs";
+export const RISK_CALIBRATION_SUMMARY_SCHEMA = 'whoisleuth.cli.risk-calibration';
+export const RISK_CALIBRATION_SUMMARY_VERSION = 3;
+export const RISK_CALIBRATION_SUMMARY_MAX_BYTES = 512 * 1024;
+export const RISK_CALIBRATION_SUMMARY_MAX_RECORDS = 500;
+export const RISK_CALIBRATION_SUMMARY_MIN_STRATUM_SAMPLE = 20;
+export const RISK_CALIBRATION_SUMMARY_THRESHOLDS = Object.freeze([...new Set([40, 50, 60, RISK_REVIEW_THRESHOLD, 80, 90])].sort((left, right) => left - right));
+export const RISK_CALIBRATION_SUMMARY_INTERPRETATION = 'This offline replay compares heuristic Risk scores with analyst dispositions. It does not prove maliciousness or safety.';
+const ROOT_KEYS = new Set([
+    'schema', 'version', 'mode', 'generatedAt', 'dataset', 'riskModelVersion',
+    'currentReviewThreshold', 'summary', 'thresholds', 'strata',
+    'modelComparison', 'privacy', 'interpretation',
+]);
+const DATASET_KEYS = new Set(['schema', 'version', 'recordCount']);
+const SUMMARY_KEYS = new Set(['total', 'positive', 'negative', 'excluded', 'scoreBands']);
+const SCORE_BAND_KEYS = new Set(['not_scored', '0_39', '40_69', '70_100']);
+const METRIC_KEYS = new Set([
+    'threshold', 'truePositive', 'falsePositive', 'trueNegative', 'falseNegative',
+    'precision', 'recall', 'specificity', 'falsePositiveRate', 'f1',
+    'balancedAccuracy', 'confidence95',
+]);
+const CONFIDENCE_KEYS = new Set(['precision', 'recall', 'specificity']);
+const INTERVAL_KEYS = new Set(['lower', 'upper']);
+const STRATUM_KEYS = new Set(['dimension', 'value', 'sampleCount', 'insufficientSample', 'metrics']);
+const MODEL_COMPARISON_KEYS = new Set([
+    'available', 'previousModelVersion', 'currentModelVersion', 'scoresChanged',
+    'bandsChanged', 'thresholdClassificationsChanged',
+]);
+const PRIVACY_KEYS = new Set(['targetsRetained', 'identifiersRetained', 'rawEvidenceRetained']);
+const INTERPRETATION_KEYS = new Set(['authority', 'statement', 'automaticTuning', 'networkRequests', 'persisted']);
+const REVIEW_REASON_VALUES = new Set([...ANALYST_REVIEW_REASON_VALUES, 'not_recorded']);
+const SCAN_DEPTH_VALUES = new Set(['deep', 'fast', 'unknown']);
+const CONTROL_RE = /[\x00-\x1f\x7f]/u;
+function object(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object.`);
+    return value;
+}
+function exactKeys(value, expected, label) {
+    const keys = Object.keys(value);
+    if (keys.length !== expected.size || keys.some((key) => !expected.has(key))) {
+        throw new Error(`${label} contains unsupported or missing fields.`);
+    }
+}
+function boundedCount(value, label, maximum = RISK_CALIBRATION_SUMMARY_MAX_RECORDS) {
+    if (!Number.isSafeInteger(value) || Number(value) < 0 || Number(value) > maximum) {
+        throw new Error(`${label} must be a bounded non-negative integer.`);
+    }
+    return Number(value);
+}
+function modelVersion(value, label) {
+    if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 100) {
+        throw new Error(`${label} must be a supported positive model version.`);
+    }
+    return Number(value);
+}
+function canonicalTimestamp(value, label) {
+    if (typeof value !== 'string' || value.length > 64 || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`${label} must be a valid date and time.`);
+    }
+    const canonical = new Date(value).toISOString();
+    if (canonical !== value)
+        throw new Error(`${label} must use canonical UTC ISO-8601 form.`);
+    return canonical;
+}
+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 Object.freeze({
+        lower: Number(Math.max(0, center - margin).toFixed(4)),
+        upper: Number(Math.min(1, center + margin).toFixed(4)),
+    });
+}
+function exactRatio(value, expected, label) {
+    if (value !== expected)
+        throw new Error(`${label} is inconsistent with the retained confusion counts.`);
+    return expected;
+}
+function interval(value, expected, label) {
+    if (expected === null) {
+        if (value !== null)
+            throw new Error(`${label} must be null when its denominator is zero.`);
+        return null;
+    }
+    const candidate = object(value, label);
+    exactKeys(candidate, INTERVAL_KEYS, label);
+    if (candidate.lower !== expected.lower || candidate.upper !== expected.upper) {
+        throw new Error(`${label} is inconsistent with the retained confusion counts.`);
+    }
+    return Object.freeze({ lower: expected.lower, upper: expected.upper });
+}
+function thresholdMetrics(value, label, expectedThreshold, expectedTotal, expectedPositive = null, expectedNegative = null) {
+    const metric = object(value, label);
+    exactKeys(metric, METRIC_KEYS, label);
+    if (metric.threshold !== expectedThreshold)
+        throw new Error(`${label} has an unexpected threshold.`);
+    const truePositive = boundedCount(metric.truePositive, `${label} true-positive count`, expectedTotal);
+    const falseNegative = boundedCount(metric.falseNegative, `${label} false-negative count`, expectedTotal);
+    const trueNegative = boundedCount(metric.trueNegative, `${label} true-negative count`, expectedTotal);
+    const falsePositive = boundedCount(metric.falsePositive, `${label} false-positive count`, expectedTotal);
+    if (truePositive + falsePositive + trueNegative + falseNegative !== expectedTotal
+        || (expectedPositive !== null && truePositive + falseNegative !== expectedPositive)
+        || (expectedNegative !== null && trueNegative + falsePositive !== expectedNegative)) {
+        throw new Error(`${label} has inconsistent class counts.`);
+    }
+    const precision = ratio(truePositive, truePositive + falsePositive);
+    const recall = ratio(truePositive, truePositive + falseNegative);
+    const specificity = ratio(trueNegative, trueNegative + falsePositive);
+    const falsePositiveRate = ratio(falsePositive, falsePositive + trueNegative);
+    const f1 = precision === null || recall === null || precision + recall === 0
+        ? null
+        : Number(((2 * precision * recall) / (precision + recall)).toFixed(4));
+    const balancedAccuracy = recall === null || specificity === null
+        ? null
+        : Number(((recall + specificity) / 2).toFixed(4));
+    const confidence = object(metric.confidence95, `${label} confidence intervals`);
+    exactKeys(confidence, CONFIDENCE_KEYS, `${label} confidence intervals`);
+    return Object.freeze({
+        threshold: expectedThreshold,
+        truePositive,
+        falsePositive,
+        trueNegative,
+        falseNegative,
+        precision: exactRatio(metric.precision, precision, `${label} precision`),
+        recall: exactRatio(metric.recall, recall, `${label} recall`),
+        specificity: exactRatio(metric.specificity, specificity, `${label} specificity`),
+        falsePositiveRate: exactRatio(metric.falsePositiveRate, falsePositiveRate, `${label} false-positive rate`),
+        f1: exactRatio(metric.f1, f1, `${label} F1`),
+        balancedAccuracy: exactRatio(metric.balancedAccuracy, balancedAccuracy, `${label} balanced accuracy`),
+        confidence95: Object.freeze({
+            precision: interval(confidence.precision, wilson95(truePositive, truePositive + falsePositive), `${label} precision interval`),
+            recall: interval(confidence.recall, wilson95(truePositive, truePositive + falseNegative), `${label} recall interval`),
+            specificity: interval(confidence.specificity, wilson95(trueNegative, trueNegative + falsePositive), `${label} specificity interval`),
+        }),
+    });
+}
+export function parseRiskCalibrationSummaryReport(raw) {
+    if (typeof raw !== 'string')
+        throw new Error('Risk calibration summary must be JSON text.');
+    const bytes = new TextEncoder().encode(raw).byteLength;
+    if (bytes < 1 || bytes > RISK_CALIBRATION_SUMMARY_MAX_BYTES) {
+        throw new Error(`Risk calibration summary must be between 1 byte and ${RISK_CALIBRATION_SUMMARY_MAX_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        const withoutBom = raw.replace(/^\uFEFF/u, '');
+        scanBoundedJson(withoutBom);
+        parsed = JSON.parse(withoutBom);
+    }
+    catch (reason) {
+        const message = reason instanceof Error
+            ? reason.message.replace(/^Artefact (?:input|JSON)/u, 'Risk calibration summary')
+            : 'Risk calibration summary is not valid JSON.';
+        throw new Error(message);
+    }
+    const root = object(parsed, 'Risk calibration summary');
+    exactKeys(root, ROOT_KEYS, 'Risk calibration summary');
+    if (root.schema !== RISK_CALIBRATION_SUMMARY_SCHEMA
+        || root.version !== RISK_CALIBRATION_SUMMARY_VERSION
+        || root.mode !== 'summary') {
+        throw new Error('Risk calibration summary has an unsupported schema, version, or mode.');
+    }
+    const dataset = object(root.dataset, 'Risk calibration dataset metadata');
+    exactKeys(dataset, DATASET_KEYS, 'Risk calibration dataset metadata');
+    if (dataset.schema !== 'whoisleuth.risk-calibration-dataset' || (dataset.version !== 1 && dataset.version !== 2)) {
+        throw new Error('Risk calibration dataset metadata has an unsupported schema or version.');
+    }
+    const recordCount = boundedCount(dataset.recordCount, 'Risk calibration dataset record count');
+    if (recordCount < 1)
+        throw new Error('Risk calibration dataset metadata must describe at least one record.');
+    const riskModelVersion = modelVersion(root.riskModelVersion, 'Risk model version');
+    if (!RISK_CALIBRATION_SUMMARY_THRESHOLDS.includes(Number(root.currentReviewThreshold))) {
+        throw new Error('Current review threshold is not part of the fixed calibration threshold set.');
+    }
+    const currentReviewThreshold = Number(root.currentReviewThreshold);
+    const rawSummary = object(root.summary, 'Risk calibration summary counts');
+    exactKeys(rawSummary, SUMMARY_KEYS, 'Risk calibration summary counts');
+    const total = boundedCount(rawSummary.total, 'Total record count');
+    const positive = boundedCount(rawSummary.positive, 'Positive label count', total);
+    const negative = boundedCount(rawSummary.negative, 'Negative label count', total);
+    const excluded = boundedCount(rawSummary.excluded, 'Excluded label count', total);
+    if (total !== recordCount || positive + negative + excluded !== total) {
+        throw new Error('Risk calibration summary label counts are inconsistent.');
+    }
+    const rawBands = object(rawSummary.scoreBands, 'Risk calibration score bands');
+    exactKeys(rawBands, SCORE_BAND_KEYS, 'Risk calibration score bands');
+    const scoreBands = Object.freeze({
+        not_scored: boundedCount(rawBands.not_scored, 'Not-scored count', total),
+        '0_39': boundedCount(rawBands['0_39'], 'Low-band count', total),
+        '40_69': boundedCount(rawBands['40_69'], 'Review-band count', total),
+        '70_100': boundedCount(rawBands['70_100'], 'High-band count', total),
+    });
+    if (Object.values(scoreBands).reduce((sum, count) => sum + count, 0) !== total) {
+        throw new Error('Risk calibration score-band counts are inconsistent.');
+    }
+    if (scoreBands.not_scored > excluded) {
+        throw new Error('Risk calibration not-scored count cannot exceed excluded labels.');
+    }
+    if (!Array.isArray(root.thresholds) || root.thresholds.length !== RISK_CALIBRATION_SUMMARY_THRESHOLDS.length) {
+        throw new Error('Risk calibration summary must contain the fixed threshold set exactly once.');
+    }
+    const thresholds = Object.freeze(root.thresholds.map((value, index) => thresholdMetrics(value, `Threshold ${index + 1}`, RISK_CALIBRATION_SUMMARY_THRESHOLDS[index], positive + negative, positive, negative)));
+    if (!Array.isArray(root.strata) || root.strata.length > 32) {
+        throw new Error('Risk calibration strata must be a bounded array.');
+    }
+    const seenStrata = new Set();
+    const strata = Object.freeze(root.strata.map((value, index) => {
+        const label = `Stratum ${index + 1}`;
+        const stratum = object(value, label);
+        exactKeys(stratum, STRATUM_KEYS, label);
+        if (stratum.dimension !== 'review_reason' && stratum.dimension !== 'scan_depth') {
+            throw new Error(`${label} has an unsupported dimension.`);
+        }
+        if (typeof stratum.value !== 'string' || !stratum.value || stratum.value.length > 64 || CONTROL_RE.test(stratum.value)) {
+            throw new Error(`${label} has an invalid value.`);
+        }
+        const allowedValues = stratum.dimension === 'review_reason' ? REVIEW_REASON_VALUES : SCAN_DEPTH_VALUES;
+        if (!allowedValues.has(stratum.value))
+            throw new Error(`${label} has an unsupported value.`);
+        const key = `${stratum.dimension}\u0000${stratum.value}`;
+        if (seenStrata.has(key))
+            throw new Error(`${label} is duplicated.`);
+        seenStrata.add(key);
+        const sampleCount = boundedCount(stratum.sampleCount, `${label} sample count`, positive + negative);
+        if (stratum.insufficientSample !== (sampleCount < RISK_CALIBRATION_SUMMARY_MIN_STRATUM_SAMPLE)) {
+            throw new Error(`${label} has an inconsistent sample-sufficiency state.`);
+        }
+        return Object.freeze({
+            dimension: stratum.dimension,
+            value: stratum.value,
+            sampleCount,
+            insufficientSample: stratum.insufficientSample,
+            metrics: thresholdMetrics(stratum.metrics, `${label} metrics`, currentReviewThreshold, sampleCount),
+        });
+    }));
+    for (const dimension of ['review_reason', 'scan_depth']) {
+        const dimensionTotal = strata
+            .filter((stratum) => stratum.dimension === dimension)
+            .reduce((sum, stratum) => sum + stratum.sampleCount, 0);
+        if (dimensionTotal !== positive + negative) {
+            throw new Error(`Risk calibration ${dimension.replace('_', '-')} strata do not cover every included label exactly once.`);
+        }
+    }
+    const comparison = object(root.modelComparison, 'Risk model comparison');
+    exactKeys(comparison, MODEL_COMPARISON_KEYS, 'Risk model comparison');
+    if (typeof comparison.available !== 'boolean')
+        throw new Error('Risk model comparison availability must be true or false.');
+    const currentModelVersion = modelVersion(comparison.currentModelVersion, 'Compared current model version');
+    if (currentModelVersion !== riskModelVersion)
+        throw new Error('Risk model comparison does not match the report model version.');
+    const previousModelVersion = comparison.previousModelVersion === null
+        ? null
+        : modelVersion(comparison.previousModelVersion, 'Compared previous model version');
+    const scoresChanged = boundedCount(comparison.scoresChanged, 'Changed-score count', total);
+    const bandsChanged = boundedCount(comparison.bandsChanged, 'Changed-band count', total);
+    const thresholdClassificationsChanged = boundedCount(comparison.thresholdClassificationsChanged, 'Changed-threshold count', total);
+    if ((!comparison.available && (previousModelVersion !== null || scoresChanged || bandsChanged || thresholdClassificationsChanged))
+        || (comparison.available && previousModelVersion === null)
+        || bandsChanged > scoresChanged
+        || thresholdClassificationsChanged > scoresChanged) {
+        throw new Error('Risk model comparison availability and counts are inconsistent.');
+    }
+    const privacy = object(root.privacy, 'Risk calibration privacy declaration');
+    exactKeys(privacy, PRIVACY_KEYS, 'Risk calibration privacy declaration');
+    if (privacy.targetsRetained !== 0 || privacy.identifiersRetained !== 0 || privacy.rawEvidenceRetained !== 0) {
+        throw new Error('Risk calibration summary must retain zero targets, identifiers, and raw evidence.');
+    }
+    const interpretation = object(root.interpretation, 'Risk calibration interpretation');
+    exactKeys(interpretation, INTERPRETATION_KEYS, 'Risk calibration interpretation');
+    if (interpretation.authority !== 'analyst_context_only'
+        || interpretation.statement !== RISK_CALIBRATION_SUMMARY_INTERPRETATION
+        || interpretation.automaticTuning !== false
+        || interpretation.networkRequests !== false
+        || interpretation.persisted !== false) {
+        throw new Error('Risk calibration interpretation is inconsistent with the offline diagnostic boundary.');
+    }
+    return Object.freeze({
+        schema: RISK_CALIBRATION_SUMMARY_SCHEMA,
+        version: RISK_CALIBRATION_SUMMARY_VERSION,
+        mode: 'summary',
+        generatedAt: canonicalTimestamp(root.generatedAt, 'Risk calibration generation time'),
+        dataset: Object.freeze({
+            schema: 'whoisleuth.risk-calibration-dataset',
+            version: dataset.version,
+            recordCount,
+        }),
+        riskModelVersion,
+        currentReviewThreshold,
+        summary: Object.freeze({ total, positive, negative, excluded, scoreBands }),
+        thresholds,
+        strata,
+        modelComparison: Object.freeze({
+            available: comparison.available,
+            previousModelVersion,
+            currentModelVersion,
+            scoresChanged,
+            bandsChanged,
+            thresholdClassificationsChanged,
+        }),
+        privacy: Object.freeze({ targetsRetained: 0, identifiersRetained: 0, rawEvidenceRetained: 0 }),
+        interpretation: Object.freeze({
+            authority: 'analyst_context_only',
+            statement: RISK_CALIBRATION_SUMMARY_INTERPRETATION,
+            automaticTuning: false,
+            networkRequests: false,
+            persisted: false,
+        }),
+    });
+}
+export function buildRiskCalibrationSummaryReport(source) {
+    const report = object(source, 'Risk calibration report');
+    const projected = {
+        schema: RISK_CALIBRATION_SUMMARY_SCHEMA,
+        version: RISK_CALIBRATION_SUMMARY_VERSION,
+        mode: 'summary',
+        generatedAt: report.generatedAt,
+        dataset: report.dataset,
+        riskModelVersion: report.riskModelVersion,
+        currentReviewThreshold: report.currentReviewThreshold,
+        summary: report.summary,
+        thresholds: report.thresholds,
+        strata: report.strata,
+        modelComparison: report.modelComparison,
+        privacy: { targetsRetained: 0, identifiersRetained: 0, rawEvidenceRetained: 0 },
+        interpretation: report.interpretation,
+    };
+    return parseRiskCalibrationSummaryReport(JSON.stringify(projected));
+}

package/lib/rpki-evidence.mjs

@@ -65,14 +65,13 @@ function reviewRpkiRoute(input) {
             limitations: baseLimitations,
         });
     }
-    const truncated = rows.length > MAX_RPKI_RECORDS;
+    const inputTruncated = rows.length > MAX_RPKI_RECORDS;
     const normalized = rows.slice(0, MAX_RPKI_RECORDS).map(normalizeAuthorization);
     const rejectedCount = normalized.filter((item) => item === null).length + Math.max(0, rows.length - MAX_RPKI_RECORDS);
     const authorizations = normalized.filter((item) => item !== null);
     const covering = authorizations.filter((item) => prefixContains(item.parsedPrefix, route));
-    const matches = covering
+    const evaluated = covering
         .sort((left, right) => right.parsedPrefix.length - left.parsedPrefix.length || left.asn - right.asn)
-        .slice(0, MAX_RPKI_MATCHES)
         .map((item) => Object.freeze({
         prefix: item.prefix,
         maxLength: item.maxLength,
@@ -81,13 +80,15 @@ function reviewRpkiRoute(input) {
             : route.length > item.maxLength ? 'max_length_exceeded'
                 : 'valid',
     }));
-    const matchingAuthorizationCount = matches.filter((item) => item.state === 'valid').length;
+    const matchingAuthorizationCount = evaluated.filter((item) => item.state === 'valid').length;
+    const matches = evaluated.slice(0, MAX_RPKI_MATCHES);
+    const incompleteInput = inputTruncated || rejectedCount > 0;
     const state = covering.length === 0
-        ? 'not_found'
+        ? incompleteInput ? 'partial' : 'not_found'
         : matchingAuthorizationCount > 0
-            ? truncated || rejectedCount > 0 || covering.length > MAX_RPKI_MATCHES ? 'partial'
+            ? incompleteInput || covering.length > MAX_RPKI_MATCHES ? 'partial'
                 : 'valid'
-            : 'invalid';
+            : incompleteInput || covering.length > MAX_RPKI_MATCHES ? 'partial' : 'invalid';
     return Object.freeze({
         schema: RPKI_EVIDENCE_SCHEMA,
         version: RPKI_EVIDENCE_VERSION,
@@ -97,7 +98,7 @@ function reviewRpkiRoute(input) {
         coveringAuthorizationCount: covering.length,
         matchingAuthorizationCount,
         rejectedCount,
-        truncated,
+        truncated: inputTruncated || covering.length > MAX_RPKI_MATCHES,
         matches: Object.freeze(matches),
         limitations: baseLimitations,
     });

package/lib/safe-fetch.mjs

@@ -25,6 +25,7 @@ import { Agent, fetch as undiciFetch } from 'undici';
 import { MAX_OUTBOUND_REDIRECTS } from "./outbound-request-bounds.mjs";
 const MAX_REDIRECTS = MAX_OUTBOUND_REDIRECTS;
 const MAX_SAFE_FETCH_URL_LENGTH = 4096;
+const MAX_SAFE_FETCH_ADDRESS_CANDIDATES = 64;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 async function defaultSafeFetchRequest(url, options) {
     // TypeScript's DOM and undici fetch declarations model equivalent web
@@ -195,6 +196,33 @@ function isPrivateAddress(ip) {
         return isPrivateIpv6(ip);
     return true; // not a recognizable IP literal - fail closed
 }
+function normalizePublicAddressCandidates(value, hostname) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error(`No DNS records for ${hostname}`);
+    if (value.length > MAX_SAFE_FETCH_ADDRESS_CANDIDATES) {
+        throw new Error(`Refusing to fetch ${hostname}: DNS returned too many address candidates`);
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw new Error(`Refusing to fetch ${hostname}: DNS returned an invalid address record`);
+        }
+        const { address, family } = item;
+        if (typeof address !== 'string' || (family !== 4 && family !== 6) || net.isIP(address) !== family) {
+            throw new Error(`Refusing to fetch ${hostname}: DNS returned an invalid address record`);
+        }
+        if (isPrivateAddress(address)) {
+            throw new Error(`Refusing to fetch ${hostname}: resolves to a private/reserved address (${address})`);
+        }
+        const key = `${family}:${address}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            normalized.push({ address, family });
+        }
+    }
+    return normalized;
+}
 // Resolves the hostname and returns every address it maps to, having
 // verified all of them are public. Throws (fails closed) if any address is
 // private/reserved, or if there are no records at all.
@@ -206,14 +234,7 @@ async function resolvePublicAddresses(hostname) {
     catch (err) {
         throw new Error(`DNS resolution failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`);
     }
-    if (records.length === 0)
-        throw new Error(`No DNS records for ${hostname}`);
-    for (const { address } of records) {
-        if (isPrivateAddress(address)) {
-            throw new Error(`Refusing to fetch ${hostname}: resolves to a private/reserved address (${address})`);
-        }
-    }
-    return records;
+    return normalizePublicAddressCandidates(records, hostname);
 }
 // A per-request undici Agent whose connections are pinned to the given,
 // already-validated address(es) - overriding the `lookup` function used at
@@ -261,6 +282,12 @@ function normalizedFetchUrl(value) {
         throw new Error('Refusing to fetch an oversized URL');
     return normalized;
 }
+function resolutionHostname(parsed) {
+    const hostname = parsed.hostname;
+    return hostname.startsWith('[') && hostname.endsWith(']')
+        ? hostname.slice(1, -1)
+        : hostname;
+}
 function boundedDuration(value) {
     return Math.max(0, Math.min(120_000, Math.round(Number(value) || 0)));
 }
@@ -274,6 +301,24 @@ async function closeDispatcher(dispatcher) {
         // Cleanup must never replace the request result or its more useful error.
     }
 }
+function abortError(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    const error = new Error('The outbound request was aborted.');
+    error.name = 'AbortError';
+    return error;
+}
+async function raceWithSignal(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        throw abortError(signal);
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(abortError(signal));
+        signal.addEventListener('abort', abort, { once: true });
+        void promise.then((value) => { signal.removeEventListener('abort', abort); resolve(value); }, (error) => { signal.removeEventListener('abort', abort); reject(error); });
+    });
+}
 // Detailed form of the shared safe request engine. It follows redirects
 // manually under the same DNS validation and connection-pinning policy as
 // safeFetch(), while retaining a bounded hop trace for consumers that need
@@ -300,7 +345,11 @@ async function safeFetchDetailed(url, options = {}, dependencies = {}) {
     let redirectCount = 0;
     while (true) {
         const parsed = new URL(currentUrl);
-        const records = await resolveAddresses(parsed.hostname);
+        const hostname = resolutionHostname(parsed);
+        const signal = options.signal ?? null;
+        const records = normalizePublicAddressCandidates(await raceWithSignal(resolveAddresses(hostname), signal), hostname);
+        if (signal?.aborted)
+            throw abortError(signal);
         const dispatcher = makeDispatcher(records);
         const hopStartedAt = now();
         // `dispatcher` is a supported undici extension used to pin the connection.
@@ -449,4 +498,4 @@ async function readBytesCapped(res, maxBytes) {
     reader.cancel().catch(() => { });
     return { bytes: Buffer.concat(chunks), truncated, bytesRead: received };
 }
-export { MAX_REDIRECTS, MAX_SAFE_FETCH_URL_LENGTH, safeFetch, safeFetchDetailed, readTextCapped, readBytesCapped, isPrivateAddress, resolvePublicAddresses, };
+export { MAX_REDIRECTS, MAX_SAFE_FETCH_URL_LENGTH, MAX_SAFE_FETCH_ADDRESS_CANDIDATES, safeFetch, safeFetchDetailed, readTextCapped, readBytesCapped, isPrivateAddress, resolvePublicAddresses, };

package/lib/security-txt.mjs

@@ -61,6 +61,23 @@ function normalizedPublishedUri(value, schemes) {
 function normalizedHttpsUrl(value) {
     return normalizedPublishedUri(value, HTTPS_PROTOCOLS);
 }
+function normalizedCanonicalComparisonUrl(value) {
+    if (!value || value.length > MAX_SECURITY_TXT_URL_LENGTH || URI_CONTROL_CHARACTER_RE.test(value))
+        return null;
+    try {
+        const url = new URL(value.trim());
+        if (url.protocol !== 'https:' || !url.hostname || url.username || url.password)
+            return null;
+        // A fragment is never part of the retrieval URI. Preserve the query only
+        // for the transient RFC 9116 Canonical comparison; retained values remain
+        // query-free under the existing privacy-minimised output contract.
+        url.hash = '';
+        return url.toString().slice(0, MAX_SECURITY_TXT_URL_LENGTH);
+    }
+    catch {
+        return null;
+    }
+}
 function eligibleHttpsFetchUrl(value) {
     if (!value || value.length > MAX_SECURITY_TXT_URL_LENGTH || URI_CONTROL_CHARACTER_RE.test(value))
         return null;
@@ -113,6 +130,7 @@ function parseSecurityTxt(text, options = {}) {
     const policies = [];
     const encryption = [];
     const canonical = [];
+    const canonicalComparison = [];
     const preferredLanguages = [];
     const expires = [];
     for (const rawLine of lines.slice(0, MAX_SECURITY_TXT_LINES)) {
@@ -157,8 +175,11 @@ function parseSecurityTxt(text, options = {}) {
         }
         else if (field === 'canonical') {
             normalized = normalizedHttpsUrl(value);
-            if (normalized)
+            const comparisonValue = normalizedCanonicalComparisonUrl(value);
+            if (normalized && comparisonValue) {
                 canonical.push(normalized);
+                canonicalComparison.push(comparisonValue);
+            }
             else
                 malformedCount += 1;
         }
@@ -187,8 +208,10 @@ function parseSecurityTxt(text, options = {}) {
         .some((entry) => entry.truncated);
     const expiresAt = expires.length === 1 ? expires[0] : null;
     const finalUrl = options.finalUrl ? normalizedHttpsUrl(options.finalUrl) : null;
-    const canonicalMatches = boundedCanonical.values.length && finalUrl
-        ? boundedCanonical.values.some((value) => value.toLowerCase() === finalUrl.toLowerCase())
+    const finalComparisonUrl = options.finalUrl ? normalizedCanonicalComparisonUrl(options.finalUrl) : null;
+    const canonicalMatches = boundedCanonical.values.length && finalUrl && finalComparisonUrl
+        ? canonicalComparison.slice(0, MAX_SECURITY_TXT_VALUES)
+            .some((value) => value.toLowerCase() === finalComparisonUrl.toLowerCase())
         : null;
     const stale = Boolean(expiresAt && Date.parse(expiresAt) <= (options.now ?? Date.now()));
     const requiredMalformed = boundedContacts.values.length === 0 || expires.length !== 1;

package/lib/service-binding-dns.mjs

@@ -450,16 +450,21 @@ function defaultTcpExchange(query, resolver, options) {
         const chunks = [];
         let totalLength = 0;
         let settled = false;
+        let hardDeadline = null;
         const finish = (error, response) => {
             if (settled)
                 return;
             settled = true;
+            if (hardDeadline)
+                clearTimeout(hardDeadline);
             socket.destroy();
             if (error)
                 reject(error);
             else
                 resolve(response);
         };
+        hardDeadline = setTimeout(() => finish(new ServiceBindingDnsError('DNS TCP query timed out', 'ETIMEOUT')), options.timeoutMs);
+        hardDeadline.unref();
         socket.setTimeout(options.timeoutMs, () => finish(new ServiceBindingDnsError('DNS TCP query timed out', 'ETIMEOUT')));
         socket.once('error', (error) => finish(error));
         socket.on('data', (chunk) => {
@@ -605,4 +610,4 @@ async function resolveServiceBindingRecords(nameValue, type, options = {}) {
         .slice(0, MAX_ERROR_LENGTH);
     throw new ServiceBindingDnsError(detail || 'DNS query failed', 'EDNSFAIL');
 }
-export { DNS_TIMEOUT_MS as SERVICE_BINDING_DNS_TIMEOUT_MS, HTTPS_TYPE, MAX_SERVICE_BINDING_RECORDS, SVCB_TYPE, ServiceBindingDnsError, buildServiceBindingDnsQuery, formatIpv6, parseResolverEndpoint, parseServiceBindingDnsResponse, resolveServiceBindingRecords, };
+export { DNS_TIMEOUT_MS as SERVICE_BINDING_DNS_TIMEOUT_MS, HTTPS_TYPE, MAX_DNS_MESSAGE_BYTES, MAX_SERVICE_BINDING_RECORDS, SVCB_TYPE, ServiceBindingDnsError, buildServiceBindingDnsQuery, defaultTcpExchange, formatIpv6, parseResolverEndpoint, parseServiceBindingDnsResponse, resolveServiceBindingRecords, };