@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/lib/lookup-response-contract.mjs

@@ -1,346 +0,0 @@
-// Shared HTTP response boundary for the unified Lookup API.
-//
-// The backend owns the evidence collectors, but an HTTP response is still an
-// untrusted value when it reaches the browser. This module keeps the response
-// envelope typed and validates the small set of fields the Lookup controller
-// relies on before any evidence is derived or rendered. Nested source records
-// stay separately attributed and additive; their own normalizers remain the
-// authority for source-specific fields.
-const INVALID_LOOKUP_RESPONSE = 'INVALID_LOOKUP_RESPONSE';
-const INVALID_LOOKUP_RESPONSE_MESSAGE = 'Lookup returned an invalid response.';
-const INVALID_COMPACT_LOOKUP_RESPONSE = 'INVALID_COMPACT_LOOKUP_RESPONSE';
-const INVALID_COMPACT_LOOKUP_RESPONSE_MESSAGE = 'Bulk lookup returned an invalid response.';
-const MAX_LOOKUP_RESPONSE_QUERY_LENGTH = 4096;
-const MAX_LOOKUP_RESPONSE_HOST_LENGTH = 253;
-const MAX_LOOKUP_RESPONSE_TOP_LEVEL_KEYS = 32;
-const MAX_LOOKUP_RESPONSE_ERROR_LENGTH = 240;
-const MAX_COMPACT_LOOKUP_RESPONSE_TOP_LEVEL_KEYS = 8;
-const MAX_COMPACT_LOOKUP_AVAILABILITY_KEYS = 128;
-const MAX_COMPACT_LOOKUP_DIAGNOSTIC_KEYS = 16;
-const MAX_COMPACT_BULK_TECHNOLOGY_IDS = 12;
-const MAX_THREAT_INTELLIGENCE_PROVIDERS = 10;
-const MAX_LOOKUP_TIMING_MS = 120_000;
-const MAX_LOOKUP_TIMING_SOURCES = 10;
-const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/u;
-const QUERY_TYPES = new Set(['domain', 'ipv4', 'ipv6', 'asn']);
-const COMPACT_AVAILABILITY_STATES = new Set([
-    'available',
-    'expiring',
-    'for_sale',
-    'registered',
-    'unknown',
-]);
-const COMPACT_CONFIDENCE_LEVELS = new Set(['high', 'low', 'medium']);
-const COMPACT_AVAILABILITY_DIAGNOSTIC_STATES = new Set(['complete', 'disabled', 'error']);
-const COMPACT_BULK_COMPARISON_STATES = new Set([
-    'error',
-    'not_found',
-    'partial',
-    'success',
-    'unavailable',
-]);
-const COMPACT_BULK_TECHNOLOGY_ID_RE = /^[a-z0-9][a-z0-9_-]{0,79}$/u;
-const SHA256_RE = /^[a-f0-9]{64}$/u;
-const LOOKUP_TIMING_SOURCES = new Set([
-    'rdap',
-    'whois',
-    'domain_evidence',
-    'reverse_dns',
-    'registrar_rdap',
-    'network_context',
-    'security_txt',
-    'external_intelligence',
-    'malware_host_intelligence',
-    'malware_ioc_intelligence',
-]);
-const LOOKUP_TIMING_OUTCOMES = new Set(['fulfilled', 'rejected']);
-const EMPTY_RECORD = Object.freeze({});
-function isJsonObject(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-function record(value) {
-    return isJsonObject(value) ? value : EMPTY_RECORD;
-}
-function optionalBoundedText(value, maxLength) {
-    return value === undefined || (typeof value === 'string'
-        && value.length <= maxLength
-        && !CONTROL_CHAR_RE.test(value));
-}
-function normalizedDomain(value) {
-    if (typeof value !== 'string'
-        || !value.trim()
-        || value.length > MAX_LOOKUP_RESPONSE_HOST_LENGTH
-        || CONTROL_CHAR_RE.test(value)
-        || /[\s/?#@\\:]/u.test(value)) {
-        return null;
-    }
-    try {
-        const parsed = new URL(`https://${value.trim().replace(/\.$/u, '')}/`);
-        const hostname = parsed.hostname.toLowerCase().replace(/\.$/u, '');
-        const labels = hostname.split('.');
-        return labels.length >= 2
-            && hostname.length <= MAX_LOOKUP_RESPONSE_HOST_LENGTH
-            && labels.every((label) => (label.length <= 63
-                && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(label)))
-            ? hostname
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-function compactDomainMatches(value, expectedDomain) {
-    const domain = normalizedDomain(value);
-    const expected = normalizedDomain(expectedDomain);
-    return Boolean(domain && expected && (domain === expected || expected.endsWith(`.${domain}`)));
-}
-function validCompactBulkComparison(value) {
-    if (!isJsonObject(value)
-        || Object.keys(value).length > 3
-        || value.version !== 1
-        || !isJsonObject(value.technology)
-        || Object.keys(value.technology).length > 3
-        || typeof value.technology.state !== 'string'
-        || !COMPACT_BULK_COMPARISON_STATES.has(value.technology.state)
-        || !Array.isArray(value.technology.ids)
-        || value.technology.ids.length > MAX_COMPACT_BULK_TECHNOLOGY_IDS
-        || typeof value.technology.truncated !== 'boolean'
-        || !isJsonObject(value.tls)
-        || Object.keys(value.tls).length > 3
-        || typeof value.tls.state !== 'string'
-        || !COMPACT_BULK_COMPARISON_STATES.has(value.tls.state)
-        || (value.tls.issuerLabel !== null && !optionalBoundedText(value.tls.issuerLabel, 240))
-        || (value.tls.spkiSha256 !== null
-            && (typeof value.tls.spkiSha256 !== 'string' || !SHA256_RE.test(value.tls.spkiSha256)))) {
-        return false;
-    }
-    const ids = value.technology.ids;
-    return ids.every((id) => typeof id === 'string' && COMPACT_BULK_TECHNOLOGY_ID_RE.test(id))
-        && new Set(ids).size === ids.length;
-}
-function invalidLookupResponse() {
-    return {
-        ok: false,
-        errorCode: INVALID_LOOKUP_RESPONSE,
-        error: INVALID_LOOKUP_RESPONSE_MESSAGE,
-    };
-}
-function invalidCompactLookupResponse() {
-    return {
-        ok: false,
-        errorCode: INVALID_COMPACT_LOOKUP_RESPONSE,
-        error: INVALID_COMPACT_LOOKUP_RESPONSE_MESSAGE,
-    };
-}
-function parseLookupHttpResponse(value) {
-    if (!isJsonObject(value) || Object.keys(value).length > MAX_LOOKUP_RESPONSE_TOP_LEVEL_KEYS) {
-        return invalidLookupResponse();
-    }
-    if (typeof value.query !== 'string'
-        || !value.query.trim()
-        || value.query.length > MAX_LOOKUP_RESPONSE_QUERY_LENGTH
-        || CONTROL_CHAR_RE.test(value.query)
-        || typeof value.type !== 'string'
-        || !QUERY_TYPES.has(value.type)
-        || !isJsonObject(value.rdap)
-        || !isJsonObject(value.whois)
-        || !isJsonObject(value.availability)
-        || !isJsonObject(value.diagnostics)
-        || !optionalBoundedText(value.inputHostname, MAX_LOOKUP_RESPONSE_HOST_LENGTH)
-        || !optionalBoundedText(value.registrableDomain, MAX_LOOKUP_RESPONSE_HOST_LENGTH)
-        || (value.isSubdomain !== undefined && typeof value.isSubdomain !== 'boolean')) {
-        return invalidLookupResponse();
-    }
-    for (const key of ['reverseDns', 'networkContext', 'securityTxt', 'sslbl', 'threatIntelligence', 'registryInsights']) {
-        const section = value[key];
-        if (section !== undefined && !isJsonObject(section))
-            return invalidLookupResponse();
-    }
-    return { ok: true, value: value };
-}
-function parseCompactLookupHttpResponse(value, expectedDomain) {
-    if (!isJsonObject(value) || Object.keys(value).length > MAX_COMPACT_LOOKUP_RESPONSE_TOP_LEVEL_KEYS) {
-        return invalidCompactLookupResponse();
-    }
-    const availability = value.availability;
-    const diagnostics = value.diagnostics;
-    if (!isJsonObject(availability)
-        || Object.keys(availability).length > MAX_COMPACT_LOOKUP_AVAILABILITY_KEYS
-        || availability.applicable !== true
-        || !compactDomainMatches(availability.domain, expectedDomain)
-        || typeof availability.state !== 'string'
-        || !COMPACT_AVAILABILITY_STATES.has(availability.state)
-        || typeof availability.confidence !== 'string'
-        || !COMPACT_CONFIDENCE_LEVELS.has(availability.confidence)
-        || (availability.deepScanComplete !== undefined && typeof availability.deepScanComplete !== 'boolean')
-        || (availability.bulkComparison !== undefined
-            && !validCompactBulkComparison(availability.bulkComparison))
-        || (value.query !== undefined && !compactDomainMatches(value.query, expectedDomain))
-        || (value.type !== undefined && value.type !== 'domain')
-        || (value.inputHostname !== undefined && !compactDomainMatches(value.inputHostname, expectedDomain))
-        || (value.registrableDomain !== undefined
-            && normalizedDomain(value.registrableDomain) !== normalizedDomain(availability.domain))
-        || (value.isSubdomain !== undefined && typeof value.isSubdomain !== 'boolean')
-        || !isJsonObject(diagnostics)
-        || Object.keys(diagnostics).length > MAX_COMPACT_LOOKUP_DIAGNOSTIC_KEYS
-        || diagnostics.version !== 7
-        || !isJsonObject(diagnostics.rdap)
-        || !isJsonObject(diagnostics.whois)
-        || !isJsonObject(diagnostics.availability)
-        || typeof diagnostics.availability.status !== 'string'
-        || !COMPACT_AVAILABILITY_DIAGNOSTIC_STATES.has(diagnostics.availability.status)) {
-        return invalidCompactLookupResponse();
-    }
-    return { ok: true, value: value };
-}
-function lookupHttpErrorMessage(value, status) {
-    const source = record(value);
-    const message = typeof source.error === 'string'
-        ? source.error
-            .replace(/[\u0000-\u001f\u007f]+/gu, ' ')
-            .replace(/\s+/gu, ' ')
-            .trim()
-            .slice(0, MAX_LOOKUP_RESPONSE_ERROR_LENGTH)
-        : '';
-    return message || `Lookup failed (${status})`;
-}
-function isBoundedTimingMs(value, totalMs) {
-    return Number.isInteger(value)
-        && Number(value) >= 0
-        && Number(value) <= totalMs
-        && Number(value) <= MAX_LOOKUP_TIMING_MS;
-}
-function normalizeLookupTiming(value) {
-    if (!isJsonObject(value)
-        || value.version !== 1
-        || !Number.isInteger(value.totalMs)
-        || Number(value.totalMs) < 0
-        || Number(value.totalMs) > MAX_LOOKUP_TIMING_MS
-        || !Array.isArray(value.sources)
-        || value.sources.length > MAX_LOOKUP_TIMING_SOURCES) {
-        return null;
-    }
-    const totalMs = Number(value.totalMs);
-    const seen = new Set();
-    const sources = [];
-    for (const candidate of value.sources) {
-        if (!isJsonObject(candidate)
-            || typeof candidate.source !== 'string'
-            || !LOOKUP_TIMING_SOURCES.has(candidate.source)
-            || seen.has(candidate.source)
-            || typeof candidate.outcome !== 'string'
-            || !LOOKUP_TIMING_OUTCOMES.has(candidate.outcome)
-            || !isBoundedTimingMs(candidate.durationMs, totalMs)
-            || !isBoundedTimingMs(candidate.completedAfterMs, totalMs)
-            || Number(candidate.durationMs) > Number(candidate.completedAfterMs)) {
-            return null;
-        }
-        const source = candidate.source;
-        seen.add(source);
-        sources.push({
-            source,
-            outcome: candidate.outcome,
-            durationMs: Number(candidate.durationMs),
-            completedAfterMs: Number(candidate.completedAfterMs),
-        });
-    }
-    return {
-        version: 1,
-        totalMs,
-        sources,
-    };
-}
-function createLookupHttpResponse(query, classified, result) {
-    return {
-        ...result,
-        query,
-        type: classified.type,
-        inputHostname: classified.inputHostname,
-        registrableDomain: classified.registrableDomain,
-        isSubdomain: classified.isSubdomain,
-    };
-}
-function createLookupViewModel(response) {
-    const availability = record(response?.availability);
-    const rdap = record(response?.rdap);
-    const registrarRdap = record(rdap.registrarRdap);
-    const whois = record(response?.whois);
-    const diagnostics = record(response?.diagnostics);
-    const reverseDns = record(response?.reverseDns);
-    const observedNetworkContext = record(response?.networkContext);
-    const registryInsights = record(response?.registryInsights);
-    const securityTxt = record(response?.securityTxt);
-    const sslbl = record(response?.sslbl);
-    const threatIntelligence = record(response?.threatIntelligence);
-    const providers = Array.isArray(threatIntelligence.providers)
-        ? threatIntelligence.providers
-            .filter(isJsonObject)
-            .slice(0, MAX_THREAT_INTELLIGENCE_PROVIDERS)
-        : [];
-    const dnsEvidence = record(availability.dns);
-    const httpEvidence = record(availability.http);
-    const httpResponse = record(httpEvidence.response);
-    const tlsEvidence = record(availability.tls);
-    const tlsCertificate = record(tlsEvidence.certificate);
-    const pageIdentity = record(availability.pageIdentity);
-    const pageOpenGraph = record(pageIdentity.openGraph);
-    const pageResources = record(pageIdentity.resources);
-    const securityPosture = record(availability.securityPosture);
-    return {
-        availability,
-        rdap,
-        registrarRdap,
-        registrarRdapParsed: record(registrarRdap.parsed),
-        whois,
-        rdapParsed: record(rdap.parsed),
-        whoisParsed: record(whois.parsed),
-        diagnostics,
-        timing: normalizeLookupTiming(diagnostics.timing),
-        registryAccess: record(diagnostics.registryAccess),
-        registryInsights,
-        reverseDns,
-        reverseDnsRecords: record(reverseDns.records),
-        observedNetworkContext,
-        observedNetworkEndpoint: record(observedNetworkContext.endpoint),
-        observedNetworkRdap: record(observedNetworkContext.rdap),
-        observedNetwork: record(observedNetworkContext.network),
-        securityTxt,
-        sslbl,
-        threatIntelligence,
-        threatIntelligenceProviders: providers,
-        dnsEvidence,
-        dnsRecords: record(dnsEvidence.records),
-        httpEvidence,
-        httpResponse,
-        httpSecurityHeaders: record(httpResponse.securityHeaders),
-        tlsEvidence,
-        tlsCertificate,
-        tlsSubject: record(tlsCertificate.subject),
-        tlsIssuer: record(tlsCertificate.issuer),
-        tlsAltNames: record(tlsCertificate.subjectAltNames),
-        tlsPublicKey: record(tlsCertificate.publicKey),
-        tlsCipher: record(tlsEvidence.cipher),
-        tlsAuthorization: record(tlsEvidence.authorization),
-        tlsHostname: record(tlsEvidence.hostname),
-        tlsValidity: record(tlsEvidence.validity),
-        tlsDiagnostics: record(tlsEvidence.diagnostics),
-        pageIdentity,
-        pageCanonical: record(pageIdentity.canonical),
-        pageMetaRefresh: record(pageIdentity.metaRefresh),
-        pageOpenGraph,
-        pageOpenGraphUrl: record(pageOpenGraph.url),
-        pageForms: record(pageIdentity.forms),
-        pageResources,
-        pageResourceTypes: record(pageResources.byType),
-        pageDownloads: record(pageIdentity.downloads),
-        pageFingerprints: record(pageIdentity.fingerprints),
-        credentialSurfaceProfile: record(availability.credentialSurfaceProfile),
-        structuredDataIdentity: record(availability.structuredDataIdentity),
-        technologyProfile: record(availability.technologyProfile),
-        pageRoleProfile: record(availability.pageRoleProfile),
-        clientBehaviorProfile: record(availability.clientBehaviorProfile),
-        securityPosture,
-        securityPostureSummary: record(securityPosture.summary),
-    };
-}
-export { INVALID_COMPACT_LOOKUP_RESPONSE, INVALID_COMPACT_LOOKUP_RESPONSE_MESSAGE, INVALID_LOOKUP_RESPONSE, INVALID_LOOKUP_RESPONSE_MESSAGE, MAX_COMPACT_LOOKUP_AVAILABILITY_KEYS, MAX_COMPACT_LOOKUP_DIAGNOSTIC_KEYS, MAX_COMPACT_LOOKUP_RESPONSE_TOP_LEVEL_KEYS, MAX_LOOKUP_RESPONSE_ERROR_LENGTH, MAX_LOOKUP_RESPONSE_HOST_LENGTH, MAX_LOOKUP_RESPONSE_QUERY_LENGTH, MAX_LOOKUP_RESPONSE_TOP_LEVEL_KEYS, MAX_LOOKUP_TIMING_MS, MAX_LOOKUP_TIMING_SOURCES, MAX_THREAT_INTELLIGENCE_PROVIDERS, createLookupHttpResponse, createLookupViewModel, isJsonObject, lookupHttpErrorMessage, normalizeLookupTiming, parseCompactLookupHttpResponse, parseLookupHttpResponse, record as lookupRecord, };

package/lib/observation.mjs

@@ -1,114 +0,0 @@
-// Compact provenance envelope for network-derived evidence. Type-specific
-// payloads remain beside this object; the envelope only standardizes source
-// health, timing, completeness, truncation, and bounded limitations.
-const OBSERVATION_VERSION = 1;
-const STATUSES = new Set([
-    'success',
-    'partial',
-    'not_found',
-    'skipped',
-    'error',
-    'unsupported',
-    'not_applicable',
-]);
-const SCAN_MODES = new Set(['fast', 'deep']);
-const MAX_LIMITATIONS = 10;
-const MAX_LIMITATION_LENGTH = 300;
-const MAX_DIAGNOSTICS = 20;
-const MAX_DIAGNOSTIC_KEY = 40;
-const MAX_DIAGNOSTIC_STRING = 240;
-const MAX_DURATION_MS = 120_000;
-function isObservationStatus(value) {
-    return typeof value === 'string' && STATUSES.has(value);
-}
-function isScanMode(value) {
-    return typeof value === 'string' && SCAN_MODES.has(value);
-}
-function safeString(value, maxLength) {
-    if (typeof value !== 'string')
-        return null;
-    const normalized = value.trim().replace(/[\u0000-\u001f\u007f]/g, ' ');
-    return normalized ? normalized.slice(0, maxLength) : null;
-}
-function isoTimestamp(value) {
-    if (typeof value !== 'string' || value.length > 64 || /[\u0000-\u001f\u007f]/.test(value))
-        return null;
-    const time = Date.parse(value);
-    return Number.isFinite(time) ? new Date(time).toISOString() : null;
-}
-function normalizeDiagnosticValue(value) {
-    if (typeof value === 'boolean')
-        return value;
-    if (typeof value === 'number')
-        return Number.isFinite(value) ? value : null;
-    if (typeof value === 'string')
-        return safeString(value, MAX_DIAGNOSTIC_STRING);
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return null;
-    const record = value;
-    const output = {};
-    for (const field of ['status', 'error', 'detail', 'truncated', 'discarded', 'count']) {
-        if (!Object.prototype.hasOwnProperty.call(record, field))
-            continue;
-        const normalized = normalizeDiagnosticValue(record[field]);
-        if (normalized !== null)
-            output[field] = normalized;
-    }
-    return Object.keys(output).length ? output : null;
-}
-function normalizeDiagnostics(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return {};
-    const record = value;
-    const output = {};
-    for (const key of Object.keys(record).sort().slice(0, MAX_DIAGNOSTICS)) {
-        if (!key || key.length > MAX_DIAGNOSTIC_KEY || !/^[a-z0-9_-]+$/i.test(key))
-            continue;
-        const normalized = normalizeDiagnosticValue(record[key]);
-        if (normalized !== null)
-            output[key] = normalized;
-    }
-    return output;
-}
-function createObservation(input = {}) {
-    const status = isObservationStatus(input.status) ? input.status : 'error';
-    const source = safeString(input.source, 40) || 'unknown';
-    const observedAt = isoTimestamp(input.observedAt) || new Date().toISOString();
-    const duration = Number(input.durationMs);
-    const limitations = [...new Set((Array.isArray(input.limitations) ? input.limitations : [])
-            .map((item) => safeString(item, MAX_LIMITATION_LENGTH))
-            .filter((item) => item !== null))]
-        .slice(0, MAX_LIMITATIONS);
-    return {
-        version: OBSERVATION_VERSION,
-        status,
-        observedAt,
-        scanMode: isScanMode(input.scanMode) ? input.scanMode : null,
-        source,
-        durationMs: Number.isFinite(duration) ? Math.max(0, Math.min(MAX_DURATION_MS, Math.round(duration))) : null,
-        complete: input.complete === true,
-        truncated: input.truncated === true,
-        limitations,
-        diagnostics: normalizeDiagnostics(input.diagnostics),
-    };
-}
-function readObservationEnvelope(value) {
-    if (value === undefined || value === null)
-        return { state: 'absent', observation: null };
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return { state: 'invalid', observation: null };
-    const record = value;
-    if (typeof record.version === 'number'
-        && Number.isInteger(record.version)
-        && record.version > OBSERVATION_VERSION) {
-        return { state: 'unsupported', observation: null };
-    }
-    if (record.version !== OBSERVATION_VERSION
-        || !isObservationStatus(record.status)
-        || !safeString(record.source, 40)
-        || !isoTimestamp(record.observedAt)) {
-        return { state: 'invalid', observation: null };
-    }
-    return { state: 'supported', observation: createObservation(record) };
-}
-export { OBSERVATION_VERSION, createObservation, readObservationEnvelope, };