@slicedearth/whoisleuth-cli 1.43.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
@@ -128,21 +129,26 @@ function isPrivateIpv6(ip) {
         return true; // ::1 (loopback)
     if (g0.startsWith('ff'))
         return true; // multicast ff00::/8
-    // IPv4-mapped (::ffff:0:0/96) and the deprecated IPv4-compatible
-    // (::0:0/96) forms both put the embedded address in the last two groups -
-    // checked on the canonical expanded form above, so it doesn't matter
-    // whether the address was originally written in dotted-decimal or hex.
-    if ([g0, g1, g2, g3, g4].every((g) => g === '0000') && (g5 === 'ffff' || g5 === '0000')) {
+    // IPv4-mapped addresses put the embedded address in the last two groups.
+    // Accept only a mapped public IPv4 target. The deprecated IPv4-compatible
+    // form is rejected below rather than treated as a routable IPv6 address.
+    if ([g0, g1, g2, g3, g4].every((g) => g === '0000') && g5 === 'ffff') {
         const embedded = groupsToIpv4(g6, g7);
         if (embedded && isPrivateIpv4(embedded))
             return true;
+        if (embedded)
+            return false;
     }
+    if ([g0, g1, g2, g3, g4, g5].every((g) => g === '0000'))
+        return true;
     // NAT64 well-known prefix (64:ff9b::/96) - same tail embedding, different
     // prefix; some IPv6-only networks synthesize these to reach IPv4 hosts.
     if (g0 === '0064' && g1 === 'ff9b' && [g2, g3, g4, g5].every((g) => g === '0000')) {
         const embedded = groupsToIpv4(g6, g7);
         if (embedded && isPrivateIpv4(embedded))
             return true;
+        if (embedded)
+            return false;
     }
     // RFC 8215 local-use NAT64 prefix (64:ff9b:1::/48). Unlike the well-known
     // /96 above, operators may choose how IPv4 bits are embedded within this
@@ -150,21 +156,13 @@ function isPrivateIpv6(ip) {
     // rather than attempting to decode one layout and leaving others open.
     if (g0 === '0064' && g1 === 'ff9b' && g2 === '0001')
         return true;
-    // 6to4 (2002::/16) - the embedded IPv4 lives in groups 1-2, not the tail.
-    if (g0 === '2002') {
-        const embedded = groupsToIpv4(g1, g2);
-        if (embedded && isPrivateIpv4(embedded))
-            return true;
-    }
-    // Teredo (2001:0000::/32) carries both a server IPv4 address and an
-    // obfuscated client IPv4 address. Decode both so a transition address
-    // cannot smuggle a private/loopback target past the IPv4 guard.
-    if (g0 === '2001' && g1 === '0000') {
-        const server = groupsToIpv4(g2, g3);
-        const client = groupsToIpv4(((~parseInt(g6, 16)) & 0xffff).toString(16), ((~parseInt(g7, 16)) & 0xffff).toString(16));
-        if ((server && isPrivateIpv4(server)) || (client && isPrivateIpv4(client)))
-            return true;
-    }
+    // Deprecated transition mechanisms are not direct global-unicast targets.
+    // Reject their entire ranges instead of attempting to classify embedded
+    // addresses whose relays and routing behaviour are outside this boundary.
+    if (g0 === '2002')
+        return true; // 6to4 2002::/16
+    if (g0 === '2001' && g1 === '0000')
+        return true; // Teredo 2001::/32
     if (/^fe[89ab][0-9a-f]$/.test(g0))
         return true; // link-local fe80::/10
     if (/^fe[cdef][0-9a-f]$/.test(g0))
@@ -175,11 +173,20 @@ function isPrivateIpv6(ip) {
         return true; // discard-only 100::/64
     if (g0 === '2001' && g1 === '0db8')
         return true; // documentation 2001:db8::/32
+    if (g0 === '3fff' && parseInt(g1, 16) <= 0x0fff)
+        return true; // documentation 3fff::/20
     if (g0 === '2001' && g1 === '0002' && g2 === '0000')
         return true; // benchmarking 2001:2::/48
     if (g0 === '2001' && /^00[1-2][0-9a-f]$/.test(g1))
         return true; // ORCHID/ORCHIDv2
-    return false;
+    // Ordinary publicly routed IPv6 unicast addresses are allocated from
+    // 2000::/3. Treat everything outside that allocation as reserved unless it
+    // matched one of the explicitly supported public transition forms above.
+    // An allow-list boundary is intentional here: newly written or unassigned
+    // address space must not silently become an outbound SSRF target merely
+    // because it was absent from this file's special-purpose exclusions.
+    const firstGroup = parseInt(g0, 16);
+    return !Number.isInteger(firstGroup) || firstGroup < 0x2000 || firstGroup > 0x3fff;
 }
 function isPrivateAddress(ip) {
     const version = net.isIP(ip);
@@ -189,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.
@@ -200,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
@@ -255,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)));
 }
@@ -268,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
@@ -294,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.
@@ -373,13 +428,12 @@ async function readTextCapped(res, maxBytes, options = {}) {
         bytesRead,
         ...(hasher ? { sha256: hasher.digest('hex') } : {}),
     });
-    const reader = res.body && res.body.getReader ? res.body.getReader() : null;
-    if (!reader) {
-        const full = Buffer.from(await res.arrayBuffer());
-        const captured = full.subarray(0, maxBytes);
-        hasher?.update(captured);
-        return result(new TextDecoder().decode(captured), full.length > maxBytes, captured.length);
+    if (res.body === null)
+        return result('', false, 0);
+    if (typeof res.body?.getReader !== 'function') {
+        throw new Error('Response body does not expose a bounded readable stream');
     }
+    const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let text = '';
     let received = 0;
@@ -413,12 +467,12 @@ async function readTextCapped(res, maxBytes, options = {}) {
 // text (a favicon image) - collects raw bytes into a Buffer instead of
 // decoding as UTF-8, which would corrupt non-text bytes.
 async function readBytesCapped(res, maxBytes) {
-    const reader = res.body && res.body.getReader ? res.body.getReader() : null;
-    if (!reader) {
-        const buf = Buffer.from(await res.arrayBuffer());
-        const bytes = buf.subarray(0, maxBytes);
-        return { bytes, truncated: buf.length > maxBytes, bytesRead: bytes.length };
+    if (res.body === null)
+        return { bytes: Buffer.alloc(0), truncated: false, bytesRead: 0 };
+    if (typeof res.body?.getReader !== 'function') {
+        throw new Error('Response body does not expose a bounded readable stream');
     }
+    const reader = res.body.getReader();
     const chunks = [];
     let received = 0;
     let truncated = false;
@@ -444,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, };