@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/packages/analysis/risk-scoring.mjs

@@ -0,0 +1,348 @@
+import { calibrateExternalIntelligenceRisk } from "./external-intelligence-risk.mjs";
+import { buildScoreEvidenceQuality, } from "./scoring-evidence-quality.mjs";
+const RISK_STATES = new Set(['registered', 'for_sale', 'expiring']);
+const STATE_LABELS = Object.freeze({
+    for_sale: 'for sale',
+    expiring: 'expiring/pending delete',
+    registered: 'registered',
+});
+// Version 9 requires form-scoped password/destination evidence. Older page-wide
+// flags never establish that a password control belongs to an external form.
+export const RISK_MODEL_VERSION = 9;
+export const RISK_REVIEW_THRESHOLD = 70;
+const CURRENT_RISK_MODEL = Object.freeze({
+    modelVersion: RISK_MODEL_VERSION,
+    includePageBaselineMatch: false,
+    requireFormAttribution: true,
+});
+const RISK_MODEL_V8 = Object.freeze({ modelVersion: 8, includePageBaselineMatch: false, requireFormAttribution: false });
+const RISK_MODEL_V7 = Object.freeze({
+    modelVersion: 7,
+    includePageBaselineMatch: true,
+    requireFormAttribution: false,
+});
+const RISK_STATE_BASE = Object.freeze({
+    registered: 6,
+    for_sale: 4,
+    expiring: 5,
+});
+const FAMILY_CAPS = Object.freeze({
+    'domain-resemblance': 20,
+    'brand-presentation': 24,
+    'credential-lure': 18,
+    'external-intelligence': 18,
+    'operational-support': 12,
+});
+const REMOVABLE_RISK_FAMILY_MAP = Object.freeze({
+    'brand-presentation': true,
+    'credential-lure': true,
+    'domain-resemblance': true,
+    'external-intelligence': true,
+    'operational-support': true,
+});
+const REMOVABLE_RISK_FAMILIES = Object.freeze(Object.keys(REMOVABLE_RISK_FAMILY_MAP));
+const HIGH_CONTEXT_MUTATIONS = new Set([
+    'unicode_homoglyph',
+    'unicode_homoglyph_depth_2',
+    'dictionary',
+    'dictionary_token_replacement',
+]);
+const MEDIUM_CONTEXT_MUTATIONS = new Set(['ascii_homoglyph', 'bitsquatting', 'tld_embedding', 'tld_typo', 'tld_substitution']);
+const LOW_CONTEXT_MUTATIONS = new Set([
+    'character_addition',
+    'character_omission',
+    'character_duplication',
+    'character_transposition',
+    'pluralization',
+    'www_prefix',
+    'hyphenation',
+    'separator_omission',
+    'word_reordering',
+    'keyboard_substitution',
+    'keyboard_insertion',
+    'vowel_swap',
+]);
+export const RISK_MUTATION_TYPES = Object.freeze([
+    ...HIGH_CONTEXT_MUTATIONS,
+    ...MEDIUM_CONTEXT_MUTATIONS,
+    ...LOW_CONTEXT_MUTATIONS,
+]);
+export function normalizeRiskModelVersion(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= 1000 ? value : null;
+}
+function formatAge(days) {
+    if (days < 60)
+        return `${Math.round(days)}d old`;
+    const years = days / 365.25;
+    return years < 1 ? `${Math.round(days / 30)}mo old` : `${years.toFixed(1)}y old`;
+}
+function mutationContext(mutationTypes) {
+    if (!Array.isArray(mutationTypes))
+        return null;
+    const bounded = mutationTypes.slice(0, 30);
+    if (bounded.some((value) => typeof value === 'string' && HIGH_CONTEXT_MUTATIONS.has(value))) {
+        return { label: 'High-similarity or phishing-term candidate context', delta: 18 };
+    }
+    if (bounded.some((value) => typeof value === 'string' && MEDIUM_CONTEXT_MUTATIONS.has(value))) {
+        return { label: 'Lookalike candidate context', delta: 12 };
+    }
+    if (bounded.some((value) => typeof value === 'string' && LOW_CONTEXT_MUTATIONS.has(value))) {
+        return { label: 'Generated variation candidate context', delta: 8 };
+    }
+    return null;
+}
+function hasBoolean(value) {
+    return typeof value === 'boolean';
+}
+function scoreQuality(input) {
+    const observedFamilies = ['registration'];
+    const expectedFamilies = ['registration', 'operational-support'];
+    if (Array.isArray(input.mutationTypes) || hasBoolean(input.idnReferenceMatch))
+        observedFamilies.push('domain-resemblance');
+    if (input.hasActiveBrandProfile === true)
+        expectedFamilies.push('domain-resemblance', 'brand-presentation');
+    if ([input.faviconMatch, input.faviconNearMatch, input.reusesOfficialAssets, input.pageBaselineMatch].some(hasBoolean)) {
+        observedFamilies.push('brand-presentation');
+    }
+    if ([input.hasPasswordField, input.hasExternalFormAction, input.hasExternalPasswordForm].some(hasBoolean) || typeof input.phishingLanguageMatch === 'string') {
+        observedFamilies.push('credential-lure');
+    }
+    if (calibrateExternalIntelligenceRisk(input.threatIntelligence, input.domain).eligibleProviderCount > 0) {
+        observedFamilies.push('external-intelligence');
+    }
+    if ([input.hasMx, input.hasSpf, input.hasDmarc].some(hasBoolean)
+        || typeof input.activityStatus === 'string'
+        || typeof input.domainAgeDays === 'number')
+        observedFamilies.push('operational-support');
+    if (input.scanDepth === 'deep')
+        expectedFamilies.push('credential-lure');
+    return buildScoreEvidenceQuality(input, {
+        expectedDepth: 'deep',
+        observedFamilies,
+        expectedFamilies,
+    });
+}
+// Risk prioritizes a registered lookalike/typosquat domain for analyst review.
+// It is a heuristic indicator, never a maliciousness or safety verdict.
+function explainRiskScoreInternal(input, excludedFamily, model) {
+    const state = input.availability ?? input.state;
+    if (typeof state !== 'string' || !RISK_STATES.has(state))
+        return null;
+    const factors = [];
+    const familyTotals = new Map();
+    const add = (family, label, requestedDelta) => {
+        if (family === excludedFamily)
+            return 0;
+        const current = familyTotals.get(family) ?? 0;
+        const cap = FAMILY_CAPS[family] ?? Number.POSITIVE_INFINITY;
+        const delta = Math.max(0, Math.min(requestedDelta, Math.max(0, cap - current)));
+        const capped = delta !== requestedDelta;
+        factors.push({ family, label: capped ? `${label} (family cap reached)` : label, delta });
+        familyTotals.set(family, current + delta);
+        return delta;
+    };
+    add('registration', `Base context for “${STATE_LABELS[state] ?? state}”`, RISK_STATE_BASE[state] ?? 0);
+    const mutation = mutationContext(input.mutationTypes);
+    if (mutation)
+        add('domain-resemblance', mutation.label, mutation.delta);
+    if (input.idnReferenceMatch === true)
+        add('domain-resemblance', 'IDN skeleton matches an official Brand Profile domain', 20);
+    if (input.faviconMatch === true)
+        add('brand-presentation', 'Favicon matches an official Brand Profile site', 18);
+    else if (input.faviconNearMatch === true)
+        add('brand-presentation', 'Favicon resembles an official Brand Profile site', 14);
+    if (input.reusesOfficialAssets === true)
+        add('brand-presentation', 'Official asset-host relationship observed', 6);
+    if (model.includePageBaselineMatch && input.pageBaselineMatch === true) {
+        add('brand-presentation', 'Multiple independently compared page-identity components match the official baseline', 14);
+    }
+    if (typeof input.phishingLanguageMatch === 'string' && input.phishingLanguageMatch.trim()) {
+        add('credential-lure', 'Suspicious urgency language observed', 8);
+    }
+    if (model.requireFormAttribution ? input.hasExternalPasswordForm === true : input.hasPasswordField === true && input.hasExternalFormAction === true) {
+        add('credential-lure', model.requireFormAttribution ? 'Password form declares an external destination' : 'Password form submits to an external origin', 10);
+    }
+    else if (input.hasPasswordField === true) {
+        add('credential-lure', 'Login/password form present', 5);
+    }
+    else if (input.hasExternalFormAction === true) {
+        add('credential-lure', 'External form destination observed without a password field', 0);
+    }
+    const external = calibrateExternalIntelligenceRisk(input.threatIntelligence, input.domain);
+    if (external.factor)
+        add('external-intelligence', external.factor.label, external.contribution);
+    const primaryFamilies = ['domain-resemblance', 'brand-presentation', 'credential-lure', 'external-intelligence']
+        .filter((family) => (familyTotals.get(family) ?? 0) > 0);
+    if (primaryFamilies.length >= 2) {
+        add('corroboration', `Corroborating context across ${primaryFamilies.length} independent evidence families`, primaryFamilies.length >= 3 ? 18 : 10);
+    }
+    const hasIndependentContext = primaryFamilies.length > 0;
+    const supporting = (label, delta) => {
+        add('operational-support', hasIndependentContext ? label : `${label}; neutral without independent suspicious context`, hasIndependentContext ? delta : 0);
+    };
+    if (input.activityStatus === 'active')
+        supporting('Active website observed', 4);
+    if (input.hasMx === true)
+        supporting('Mail server configured', 4);
+    if (input.hasSpf === true && input.hasDmarc === true)
+        supporting('SPF and DMARC records present', 1);
+    else if (input.hasSpf === true || input.hasDmarc === true)
+        supporting('SPF or DMARC record present', 0);
+    if (typeof input.domainAgeDays === 'number' && Number.isFinite(input.domainAgeDays) && input.domainAgeDays >= 0) {
+        if (input.domainAgeDays < 90)
+            supporting(`Recently registered (${formatAge(input.domainAgeDays)})`, 6);
+        else if (input.domainAgeDays < 365)
+            supporting(`Registered under a year ago (${formatAge(input.domainAgeDays)})`, 2);
+    }
+    if (typeof input.privacyProtected === 'boolean') {
+        add('registration', 'Registration privacy is neutral context', 0);
+    }
+    const rawScore = Math.round(factors.reduce((total, factor) => total + factor.delta, 0));
+    const score = Math.max(0, Math.min(100, rawScore));
+    const familyOrder = [
+        'registration', 'domain-resemblance', 'brand-presentation', 'credential-lure',
+        'external-intelligence', 'corroboration', 'operational-support',
+    ];
+    return {
+        modelVersion: model.modelVersion,
+        score,
+        rawScore,
+        capped: score !== rawScore,
+        factors,
+        families: familyOrder
+            .filter((id) => familyTotals.has(id))
+            .map((id) => ({ id, contribution: familyTotals.get(id) ?? 0, cap: FAMILY_CAPS[id] ?? null })),
+        evidenceQuality: scoreQuality(input),
+    };
+}
+export function explainRiskScore(input) {
+    return explainRiskScoreInternal(input, null, CURRENT_RISK_MODEL);
+}
+export function buildRiskScoreSensitivity(input) {
+    const baseline = explainRiskScoreInternal(input, null, CURRENT_RISK_MODEL);
+    if (!baseline)
+        return null;
+    const removableFamilies = REMOVABLE_RISK_FAMILIES
+        .filter((family) => baseline.families.some((item) => item.id === family && item.contribution > 0));
+    const scenarios = removableFamilies.map((excludedFamily) => {
+        const result = explainRiskScoreInternal(input, excludedFamily, CURRENT_RISK_MODEL);
+        const score = result?.score ?? baseline.score;
+        return Object.freeze({ excludedFamily, score, difference: score - baseline.score });
+    }).sort((left, right) => left.score - right.score || left.excludedFamily.localeCompare(right.excludedFamily));
+    const minimumScenarioScore = scenarios[0]?.score ?? baseline.score;
+    const thresholdState = baseline.score < RISK_REVIEW_THRESHOLD
+        ? 'below'
+        : minimumScenarioScore < RISK_REVIEW_THRESHOLD ? 'crosses' : 'stable_above';
+    return Object.freeze({
+        version: 1,
+        baselineScore: baseline.score,
+        reviewThreshold: RISK_REVIEW_THRESHOLD,
+        minimumScenarioScore,
+        thresholdState,
+        scenarios: Object.freeze(scenarios),
+        limitations: Object.freeze([
+            'Each scenario removes one observed evidence family and recalculates family caps and corroboration; it does not predict missing evidence.',
+            'The sensitivity review qualifies prioritisation only and does not determine maliciousness, safety, ownership, or intent.',
+        ]),
+    });
+}
+export function computeRiskScore(input) {
+    return explainRiskScore(input)?.score ?? null;
+}
+// Retained only for deterministic offline comparison of reviewed calibration
+// datasets. Runtime lookups always use the current model above.
+export function explainRiskScoreV7(input) {
+    return explainRiskScoreInternal(input, null, RISK_MODEL_V7);
+}
+export function explainRiskScoreV8(input) {
+    return explainRiskScoreInternal(input, null, RISK_MODEL_V8);
+}
+// Retained only for deterministic offline comparison of reviewed calibration
+// datasets. Runtime lookups always use the current model above.
+export function explainRiskScoreV6(input) {
+    const state = input.availability ?? input.state;
+    if (typeof state !== 'string' || !RISK_STATES.has(state))
+        return null;
+    const legacyBase = { registered: 10, for_sale: 5, expiring: 8 };
+    const factors = [];
+    const totals = new Map();
+    const add = (family, label, delta) => {
+        factors.push({ family, label, delta });
+        totals.set(family, (totals.get(family) ?? 0) + delta);
+    };
+    add('registration', `Base score for “${STATE_LABELS[state] ?? state}”`, legacyBase[state] ?? 0);
+    const contextual = new Set();
+    const context = mutationContext(input.mutationTypes);
+    if (context) {
+        add('domain-resemblance', context.label, context.delta);
+        contextual.add('domain-resemblance');
+    }
+    if (input.faviconMatch === true) {
+        add('brand-presentation', 'Favicon matches an official Brand Profile site', 18);
+        contextual.add('brand-presentation');
+    }
+    else if (input.faviconNearMatch === true) {
+        add('brand-presentation', 'Favicon resembles an official Brand Profile site', 14);
+        contextual.add('brand-presentation');
+    }
+    if (input.reusesOfficialAssets === true) {
+        add('brand-presentation', 'Official asset-host relationship observed', 6);
+        contextual.add('brand-presentation');
+    }
+    if (typeof input.phishingLanguageMatch === 'string' && input.phishingLanguageMatch.trim()) {
+        add('credential-lure', 'Suspicious urgency language observed', 8);
+        contextual.add('credential-lure');
+    }
+    if (input.hasPasswordField === true) {
+        add('credential-lure', 'Login/password form present', 5);
+        contextual.add('credential-lure');
+    }
+    if (contextual.size >= 2)
+        add('corroboration', `Corroborating context across ${contextual.size} distinct evidence families`, contextual.size >= 3 ? 20 : 10);
+    const external = calibrateExternalIntelligenceRisk(input.threatIntelligence, input.domain);
+    if (external.factor)
+        add('external-intelligence', external.factor.label, external.contribution);
+    if (input.activityStatus === 'active')
+        add('operational-support', 'Active site in use', 8);
+    if (input.hasMx === true)
+        add('operational-support', 'Mail server configured', 8);
+    if (input.hasSpf === true && input.hasDmarc === true)
+        add('operational-support', 'SPF and DMARC records present', 3);
+    else if (input.hasSpf === true || input.hasDmarc === true)
+        add('operational-support', 'SPF or DMARC record present', 1);
+    if (input.privacyProtected === true)
+        add('registration', 'WHOIS privacy protected', 3);
+    if (typeof input.domainAgeDays === 'number' && Number.isFinite(input.domainAgeDays) && input.domainAgeDays >= 0) {
+        if (input.domainAgeDays < 90)
+            add('operational-support', `Recently registered (${formatAge(input.domainAgeDays)})`, 10);
+        else if (input.domainAgeDays < 365)
+            add('operational-support', `Registered under a year ago (${formatAge(input.domainAgeDays)})`, 4);
+    }
+    const rawScore = Math.round(factors.reduce((total, factor) => total + factor.delta, 0));
+    const score = Math.max(0, Math.min(100, rawScore));
+    return {
+        modelVersion: 6,
+        score,
+        rawScore,
+        capped: score !== rawScore,
+        factors,
+        families: [...totals].map(([id, contribution]) => ({ id, contribution, cap: null })),
+        evidenceQuality: scoreQuality(input),
+    };
+}
+export function riskTone(score) {
+    if (score === null)
+        return 'neutral';
+    if (score >= RISK_REVIEW_THRESHOLD)
+        return 'danger';
+    if (score >= 40)
+        return 'warn';
+    return 'neutral';
+}
+export function formatScoreBreakdown(explained, separator = '\n') {
+    if (!explained)
+        return '';
+    const parts = explained.factors.map((factor) => `${factor.label} ${factor.delta >= 0 ? '+' : ''}${Math.round(factor.delta)}`);
+    parts.push(`Total ${explained.score} · Risk model v${explained.modelVersion} · evidence ${explained.evidenceQuality.state}`);
+    return parts.join(separator);
+}

package/packages/analysis/scoring-evidence-quality.mjs

@@ -0,0 +1,107 @@
+export const SCORE_EVIDENCE_QUALITY_VERSION = 1;
+const MAX_SOURCES = 24;
+const MAX_FAMILIES = 12;
+const SOURCE_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/u;
+const COMPLETE_STATES = new Set(['complete', 'not_found', 'success']);
+const LIMITED_STATES = new Set(['partial', 'unknown']);
+const UNAVAILABLE_STATES = new Set(['error', 'rate_limited', 'unavailable']);
+const SKIPPED_STATES = new Set(['skipped', 'unsupported']);
+const ACCEPTED_SOURCE_STATES = new Set([
+    ...COMPLETE_STATES,
+    ...LIMITED_STATES,
+    ...UNAVAILABLE_STATES,
+    ...SKIPPED_STATES,
+]);
+function boundedFamilyList(value) {
+    const output = new Set();
+    for (const item of value.slice(0, MAX_FAMILIES * 2)) {
+        const normalized = String(item).trim().toLowerCase().replace(/[^a-z0-9_-]+/gu, '-').slice(0, 64);
+        if (SOURCE_ID_RE.test(normalized))
+            output.add(normalized);
+        if (output.size >= MAX_FAMILIES)
+            break;
+    }
+    return [...output].sort();
+}
+function sourceCoverage(value) {
+    if (!Array.isArray(value))
+        return [];
+    const output = [];
+    const seen = new Set();
+    for (const candidate of value.slice(0, MAX_SOURCES * 4)) {
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+            continue;
+        const item = candidate;
+        const source = typeof item.source === 'string' ? item.source.trim().toLowerCase() : '';
+        const state = typeof item.state === 'string' ? item.state.trim().toLowerCase() : '';
+        if (!SOURCE_ID_RE.test(source) || seen.has(source))
+            continue;
+        if (!ACCEPTED_SOURCE_STATES.has(state))
+            continue;
+        seen.add(source);
+        output.push({ source, state });
+        if (output.length >= MAX_SOURCES)
+            break;
+    }
+    return output;
+}
+function scanDepth(value) {
+    return value === 'deep' || value === 'fast' ? value : 'unknown';
+}
+function observedFreshness(value) {
+    if (typeof value !== 'string' || value.length > 64)
+        return 'unknown';
+    return Number.isFinite(Date.parse(value)) ? 'observed' : 'unknown';
+}
+export function buildScoreEvidenceQuality(input, options) {
+    const depth = scanDepth(input.scanDepth);
+    const coverage = sourceCoverage(input.sourceCoverage);
+    const completeSources = coverage.filter((item) => COMPLETE_STATES.has(item.state)).length;
+    const limitedSources = coverage.filter((item) => LIMITED_STATES.has(item.state)).length;
+    const unavailableSources = coverage.filter((item) => UNAVAILABLE_STATES.has(item.state)).length;
+    const skippedSources = coverage.filter((item) => SKIPPED_STATES.has(item.state)).length;
+    const observedFamilies = boundedFamilyList(options.observedFamilies ?? []);
+    const expectedFamilies = boundedFamilyList(options.expectedFamilies ?? []);
+    const observedSet = new Set(observedFamilies);
+    const missingFamilies = expectedFamilies.filter((family) => !observedSet.has(family));
+    const limitations = [];
+    let state = 'complete';
+    if (!coverage.length || depth === 'unknown')
+        state = 'unknown';
+    else if (unavailableSources || limitedSources)
+        state = 'partial';
+    else if (options.expectedDepth === 'deep' && depth !== 'deep')
+        state = 'limited';
+    if (missingFamilies.length && state === 'complete')
+        state = 'limited';
+    if (options.expectedDepth === 'deep' && depth !== 'deep') {
+        limitations.push('A fast or unknown-depth observation does not evaluate every website and mail scoring family.');
+    }
+    if (limitedSources || unavailableSources) {
+        limitations.push('One or more score-relevant sources were partial, unavailable, or indeterminate.');
+    }
+    if (skippedSources) {
+        limitations.push('One or more reported sources were skipped or unsupported and did not contribute to the score.');
+    }
+    if (!coverage.length)
+        limitations.push('Source-level coverage was not supplied with this score.');
+    if (missingFamilies.length)
+        limitations.push(`No usable observation was supplied for: ${missingFamilies.join(', ')}.`);
+    const boundedLimitations = [
+        ...limitations.slice(0, 5),
+        'Evidence coverage qualifies the score; it never adds points or turns missing evidence into a negative finding.',
+    ];
+    return Object.freeze({
+        version: SCORE_EVIDENCE_QUALITY_VERSION,
+        state,
+        scanDepth: depth,
+        freshness: observedFreshness(input.observedAt),
+        completeSources,
+        limitedSources,
+        unavailableSources,
+        skippedSources,
+        observedFamilies: Object.freeze(observedFamilies),
+        missingFamilies: Object.freeze(missingFamilies),
+        limitations: Object.freeze(boundedLimitations),
+    });
+}

package/packages/analysis/semantic-version.mjs

@@ -0,0 +1,54 @@
+// Dependency-free semantic-version validation shared by release tooling,
+// runtime identity, and the frontend build. Callers provide a bounded label so
+// errors retain their local context without reimplementing SemVer parsing.
+export const MAX_SEMANTIC_VERSION_LENGTH = 128;
+function fail(label, detail) {
+    throw new TypeError(`${label} ${detail}`);
+}
+function validateIdentifierList(value, label, kind, forbidNumericLeadingZero) {
+    const identifiers = value.split('.');
+    if (identifiers.some((identifier) => identifier.length === 0)) {
+        fail(label, `${kind} contains an empty identifier.`);
+    }
+    for (const identifier of identifiers) {
+        if (!/^[0-9A-Za-z-]+$/u.test(identifier)) {
+            fail(label, `${kind} contains an invalid identifier.`);
+        }
+        if (forbidNumericLeadingZero && /^[0-9]+$/u.test(identifier) && identifier.length > 1 && identifier.startsWith('0')) {
+            fail(label, `${kind} numeric identifiers must not contain leading zeroes.`);
+        }
+    }
+}
+export function normalizeBoundedSemanticVersion(value, label = 'Semantic') {
+    if (typeof value !== 'string'
+        || value.length === 0
+        || value.length > MAX_SEMANTIC_VERSION_LENGTH
+        || value.trim() !== value) {
+        fail(label, 'version must be a bounded semantic-version string.');
+    }
+    const buildParts = value.split('+');
+    if (buildParts.length > 2)
+        fail(label, 'version contains more than one build-metadata separator.');
+    const [precedence, buildMetadata] = buildParts;
+    if (!precedence)
+        fail(label, 'version must include numeric precedence.');
+    const prereleaseSeparator = precedence.indexOf('-');
+    const core = prereleaseSeparator === -1 ? precedence : precedence.slice(0, prereleaseSeparator);
+    const prerelease = prereleaseSeparator === -1 ? undefined : precedence.slice(prereleaseSeparator + 1);
+    const coreParts = core.split('.');
+    if (coreParts.length !== 3 || coreParts.some((part) => !/^(?:0|[1-9][0-9]*)$/u.test(part))) {
+        fail(label, 'version must contain major, minor, and patch numbers without leading zeroes.');
+    }
+    if (prerelease !== undefined)
+        validateIdentifierList(prerelease, label, 'prerelease', true);
+    if (buildMetadata !== undefined)
+        validateIdentifierList(buildMetadata, label, 'build metadata', false);
+    return value;
+}
+export function normalizeBoundedStableSemanticVersion(value, label = 'Stable semantic') {
+    const version = normalizeBoundedSemanticVersion(value, label);
+    if (version.includes('-') || version.includes('+')) {
+        fail(label, 'version must not include prerelease or build identifiers.');
+    }
+    return version;
+}

package/packages/analysis/threat-intelligence-types.mjs

@@ -0,0 +1,75 @@
+// Provider-neutral types shared by threat-intelligence and curated connector
+// manifests, fixture harnesses, normalizers, and result builders.
+export const THREAT_INTELLIGENCE_SCHEMA = 'whoisleuth.threat-intelligence-result';
+export const THREAT_INTELLIGENCE_CONTRACT_VERSION = 1;
+export const THREAT_INTELLIGENCE_ENVELOPE_VERSION = 1;
+export const THREAT_INTELLIGENCE_TARGET_EXPOSURES = Object.freeze([
+    'registrable_domain', 'hostname', 'origin', 'full_url',
+]);
+export const THREAT_INTELLIGENCE_CAPABILITIES = Object.freeze([
+    'domain_lookup', 'url_lookup', 'indicator_search',
+]);
+export const THREAT_INTELLIGENCE_CATEGORIES = Object.freeze([
+    'phishing',
+    'malware',
+    'spam',
+    'suspicious',
+    'abuse',
+    'unknown',
+]);
+export const THREAT_INTELLIGENCE_SEVERITIES = Object.freeze([
+    'critical',
+    'high',
+    'medium',
+    'low',
+    'unknown',
+]);
+export const THREAT_INTELLIGENCE_CONFIDENCES = Object.freeze([
+    'high',
+    'medium',
+    'low',
+    'unknown',
+]);
+export const THREAT_INTELLIGENCE_RESULT_STATES = Object.freeze([
+    'success',
+    'partial',
+    'not_found',
+    'unsupported',
+    'skipped',
+    'rate_limited',
+    'unavailable',
+    'error',
+]);
+export const CURATED_CONNECTOR_KINDS = Object.freeze(['discovery', 'enrichment']);
+export const CURATED_CONNECTOR_COLLECTIONS = Object.freeze(['passive', 'active', 'third_party']);
+export const CURATED_CONNECTOR_CREDENTIAL_MODES = Object.freeze(['none', 'optional', 'required']);
+export const CURATED_CONNECTOR_ENTITY_VALUES = Object.freeze([
+    'domain', 'hostname', 'url', 'ipv4', 'ipv6', 'asn', 'certificate',
+]);
+export const CURATED_CONNECTOR_RELATIONSHIP_TYPES = Object.freeze([
+    'domain_resolves_to_ip', 'domain_uses_nameserver', 'domain_uses_mail_server',
+    'domain_presented_certificate', 'certificate_names_domain', 'ip_hosts_domain',
+    'domain_related_to_domain',
+]);
+export const CURATED_CONNECTOR_RELATIONSHIP_CLASSIFICATIONS = Object.freeze(['direct', 'normalized', 'derived']);
+export const CURATED_CONNECTOR_TARGET_EXPOSURES = Object.freeze({
+    domain: Object.freeze(['registrable_domain']),
+    hostname: Object.freeze(['hostname']),
+    url: THREAT_INTELLIGENCE_TARGET_EXPOSURES,
+    ipv4: Object.freeze(['ip_address']),
+    ipv6: Object.freeze(['ip_address']),
+    asn: Object.freeze(['asn']),
+    certificate: Object.freeze(['certificate_fingerprint']),
+});
+function relationshipEndpoints(from, to) {
+    return Object.freeze({ from: Object.freeze(from), to: Object.freeze(to) });
+}
+export const CURATED_CONNECTOR_RELATIONSHIP_ENDPOINTS = Object.freeze({
+    domain_resolves_to_ip: relationshipEndpoints(['domain', 'hostname'], ['ipv4', 'ipv6']),
+    domain_uses_nameserver: relationshipEndpoints(['domain'], ['hostname']),
+    domain_uses_mail_server: relationshipEndpoints(['domain'], ['hostname']),
+    domain_presented_certificate: relationshipEndpoints(['domain', 'hostname'], ['certificate']),
+    certificate_names_domain: relationshipEndpoints(['certificate'], ['domain', 'hostname']),
+    ip_hosts_domain: relationshipEndpoints(['ipv4', 'ipv6'], ['domain', 'hostname']),
+    domain_related_to_domain: relationshipEndpoints(['domain', 'hostname'], ['domain', 'hostname']),
+});