@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/analysis/cli-argument-grammar.mjs

@@ -0,0 +1,216 @@
+export class CliGrammarError extends Error {
+    constructor(message) { super(message); this.name = 'CliGrammarError'; }
+}
+function humanList(values, conjunction = 'or') {
+    if (values.length < 2)
+        return values[0] ?? '';
+    if (values.length === 2)
+        return `${values[0]} ${conjunction} ${values[1]}`;
+    return `${values.slice(0, -1).join(', ')}, ${conjunction} ${values.at(-1)}`;
+}
+function valueError(specification) {
+    if (specification.valueKind === 'file') {
+        return new CliGrammarError(`${specification.option} requires one bounded file path.`);
+    }
+    if (specification.valueKind === 'integer') {
+        const baseRange = specification.integerRanges[0];
+        return new CliGrammarError(baseRange
+            ? `${specification.option} requires an integer from ${baseRange.minimum} to ${baseRange.maximum}.`
+            : `${specification.option} requires one bounded integer.`);
+    }
+    if (specification.values.length > 0) {
+        return new CliGrammarError(`${specification.option} requires ${humanList(specification.values)}.`);
+    }
+    return new CliGrammarError(`${specification.option} requires one bounded value.`);
+}
+function parseTokens(grammar, argv) {
+    const specificationByOption = new Map(grammar.options.map((specification) => [specification.option, specification]));
+    const options = new Map();
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--') {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (!argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        const specification = specificationByOption.get(argument);
+        if (!specification || specification.metaAction !== null) {
+            throw new CliGrammarError(`Unknown option "${argument}".`);
+        }
+        const existing = options.get(argument);
+        if (existing && specification.occurrence === 'once') {
+            throw new CliGrammarError(`${argument} may be supplied only once.`);
+        }
+        if (existing && specification.occurrence === 'idempotent')
+            continue;
+        let value = '';
+        if (specification.arity === 1) {
+            const candidate = argv[++index];
+            if (candidate === undefined || candidate === ''
+                || (!specification.acceptsOptionLikeValue && candidate.startsWith('-'))) {
+                throw valueError(specification);
+            }
+            value = candidate;
+        }
+        if (existing)
+            existing.push(value);
+        else
+            options.set(argument, [value]);
+    }
+    return { options, positionals };
+}
+function selectedIntegerRange(specification, options) {
+    return specification.integerRanges
+        .filter((range) => range.whenOptionPresent === null || options.has(range.whenOptionPresent))
+        .at(-1) ?? null;
+}
+function validateOptionValues(command, grammar, options) {
+    for (const specification of grammar.options) {
+        const values = options.get(specification.option);
+        if (!values || specification.arity === 0)
+            continue;
+        if (specification.valueKind === 'enum') {
+            if (values.some((value) => !specification.values.includes(value)))
+                throw valueError(specification);
+            continue;
+        }
+        if (specification.valueKind === 'integer') {
+            const range = selectedIntegerRange(specification, options);
+            if (!range)
+                throw new Error(`Integer option ${command} ${specification.option} has no applicable range.`);
+            for (const value of values) {
+                if (!/^\d+$/u.test(value))
+                    throw valueError(specification);
+                const parsed = Number(value);
+                if (!Number.isSafeInteger(parsed) || parsed < range.minimum || parsed > range.maximum) {
+                    throw new CliGrammarError(`${specification.option} must be from ${range.minimum} to ${range.maximum}.`);
+                }
+            }
+            continue;
+        }
+        if (specification.valueKind === 'policy_list') {
+            for (const value of values) {
+                const policies = [...new Set(value.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean))];
+                if (!policies.length || policies.some((policy) => !specification.values.includes(policy))) {
+                    throw new CliGrammarError(`${specification.option} for ${command} supports: ${specification.values.join(', ')}.`);
+                }
+            }
+        }
+    }
+}
+function allocatePositionals(command, grammar, rawPositionals) {
+    const specifications = grammar.positionals;
+    const maximum = specifications.reduce((sum, specification) => sum + specification.maximum, 0);
+    if (rawPositionals.length > maximum) {
+        throw new CliGrammarError(`${command} accepts at most ${maximum} positional value${maximum === 1 ? '' : 's'}.`);
+    }
+    const allocated = {};
+    let offset = 0;
+    for (const [specificationIndex, specification] of specifications.entries()) {
+        const remainingMinimum = specifications.slice(specificationIndex + 1)
+            .reduce((sum, later) => sum + later.minimum, 0);
+        const available = Math.max(0, rawPositionals.length - offset - remainingMinimum);
+        const count = Math.min(specification.maximum, available);
+        const values = Object.freeze(rawPositionals.slice(offset, offset + count));
+        offset += count;
+        if (values.length < specification.minimum) {
+            throw new CliGrammarError(`${command} requires ${specification.minimum} ${specification.name} value${specification.minimum === 1 ? '' : 's'}.`);
+        }
+        if (specification.valueKind === 'enum'
+            && values.some((value) => !specification.values.includes(value))) {
+            throw new CliGrammarError(`${command} ${specification.name} must be ${humanList(specification.values)}.`);
+        }
+        allocated[specification.name] = values;
+    }
+    return Object.freeze(allocated);
+}
+function present(options, option) {
+    return options.has(option);
+}
+function validateConstraint(command, constraint, options) {
+    if (constraint.kind === 'required') {
+        const missing = constraint.options.filter((option) => !present(options, option));
+        if (missing.length > 0)
+            throw new CliGrammarError(`${command} requires ${missing.join(', ')}.`);
+        return;
+    }
+    if (constraint.kind === 'mutually_exclusive') {
+        const selected = constraint.options.filter((option) => present(options, option));
+        if (selected.length > 1) {
+            throw new CliGrammarError(`${selected.join(' and ')} are mutually exclusive and may be supplied only once.`);
+        }
+        return;
+    }
+    if (constraint.kind === 'excludes_all') {
+        if (!present(options, constraint.option))
+            return;
+        const selected = constraint.excludedOptions.filter((option) => present(options, option));
+        if (selected.length > 0) {
+            throw new CliGrammarError(`${constraint.option} cannot be combined with ${selected.join(', ')}.`);
+        }
+        return;
+    }
+    if (constraint.kind === 'value_excludes') {
+        if (!options.get(constraint.option)?.includes(constraint.value))
+            return;
+        const selected = constraint.excludedOptions.filter((option) => present(options, option));
+        if (selected.length > 0) {
+            throw new CliGrammarError(`${constraint.option} ${constraint.value} cannot be combined with ${selected.join(', ')}.`);
+        }
+        return;
+    }
+    if (!present(options, constraint.option))
+        return;
+    const selected = constraint.requiredOptions.filter((option) => present(options, option));
+    if (constraint.kind === 'requires_all' && selected.length !== constraint.requiredOptions.length) {
+        throw new CliGrammarError(`${constraint.option} requires ${constraint.requiredOptions.join(' and ')}.`);
+    }
+    if (constraint.kind === 'requires_any' && selected.length === 0) {
+        throw new CliGrammarError(`${constraint.option} requires ${constraint.requiredOptions.join(' or ')}.`);
+    }
+}
+function validatePositionalRequirements(grammar, allocated, options) {
+    for (const specification of grammar.positionals) {
+        if (specification.requiredWhenOptions.some((option) => options.has(option))
+            && (allocated[specification.name]?.length ?? 0) === 0) {
+            throw new CliGrammarError(`${specification.requiredWhenOptions.join(' or ')} requires a positional ${specification.name}.`);
+        }
+    }
+}
+function freezeOptions(options) {
+    return new Map([...options].map(([option, values]) => [option, Object.freeze([...values])]));
+}
+export function parseCliGrammar(command, grammar, argv) {
+    const parsed = parseTokens(grammar, argv);
+    const options = freezeOptions(parsed.options);
+    validateOptionValues(command, grammar, options);
+    const allocated = allocatePositionals(command, grammar, parsed.positionals);
+    validatePositionalRequirements(grammar, allocated, options);
+    for (const constraint of grammar.constraints) {
+        validateConstraint(command, constraint, options);
+    }
+    for (const option of ['--config', '--profile']) {
+        const specification = grammar.options.find((candidate) => candidate.option === option);
+        if (specification?.scope === 'common' && options.has(option)) {
+            throw new CliGrammarError(`${option} must be resolved before command parsing.`);
+        }
+    }
+    const allPositionals = Object.freeze([...parsed.positionals]);
+    return Object.freeze({
+        command,
+        allPositionals,
+        hasOption: (option) => options.has(option),
+        optionValue: (option) => options.get(option)?.at(-1) ?? null,
+        optionValues: (option) => options.get(option) ?? Object.freeze([]),
+        integerOption: (option) => {
+            const value = options.get(option)?.at(-1);
+            return value === undefined ? null : Number(value);
+        },
+        positionalValue: (name) => allocated[name]?.[0] ?? null,
+        positionalValues: (name) => allocated[name] ?? Object.freeze([]),
+    });
+}

package/packages/analysis/ct-query.mjs

@@ -0,0 +1,27 @@
+const MAX_CT_QUERY_LENGTH = 200;
+const CT_QUERY_ERROR_CODE = 'INVALID_CT_QUERY';
+const CT_QUERY_ERROR_MESSAGE = `Certificate Transparency query must be at most ${MAX_CT_QUERY_LENGTH} characters and contain no control or invisible formatting characters.`;
+const UNSAFE_QUERY_CHARACTER_RE = /[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/u;
+class CtQueryError extends Error {
+    code = CT_QUERY_ERROR_CODE;
+    constructor() {
+        super(CT_QUERY_ERROR_MESSAGE);
+        this.name = 'CtQueryError';
+    }
+}
+function normalizeCtQuery(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value !== 'string'
+        || value.length > MAX_CT_QUERY_LENGTH
+        || UNSAFE_QUERY_CHARACTER_RE.test(value)) {
+        throw new CtQueryError();
+    }
+    return value.trim();
+}
+function isCtQueryError(value) {
+    return value instanceof Error
+        && 'code' in value
+        && value.code === CT_QUERY_ERROR_CODE;
+}
+export { CT_QUERY_ERROR_CODE, CT_QUERY_ERROR_MESSAGE, CtQueryError, isCtQueryError, MAX_CT_QUERY_LENGTH, normalizeCtQuery, };

package/packages/analysis/ct-response-bounds.mjs

@@ -0,0 +1,9 @@
+// Shared response-contract bounds for certificate-log search. The collector
+// and browser normalizer import these values so a valid backend response is
+// not accidentally clipped by a stale client-side mirror.
+export const MAX_CT_RESPONSE_RESULTS = 500;
+export const MAX_CT_RESPONSE_HOSTNAMES_PER_MATCH = 50;
+export const MAX_CT_RESPONSE_TIMESTAMP_LENGTH = 64;
+export const MAX_CT_RESPONSE_CERTIFICATE_GROUPS = 100;
+export const MAX_CT_RESPONSE_DOMAINS_PER_GROUP = 20;
+export const MAX_CT_RESPONSE_HOSTNAMES_PER_GROUP = 30;

package/packages/analysis/external-intelligence-risk.mjs

@@ -0,0 +1,124 @@
+// Converts already-returned, separately attributed external observations into
+// a conservative Risk contribution. Unknown providers and lone publisher
+// families never contribute. Two adapters operated by the same publisher are
+// deliberately one corroboration source, even when their datasets differ.
+export const EXTERNAL_INTELLIGENCE_CALIBRATION_VERSION = 1;
+export const EXTERNAL_INTELLIGENCE_RECENT_DAYS = 90;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MAX_CLOCK_SKEW_MS = DAY_MS;
+const MAX_PROVIDERS = 10;
+const MAX_FINDINGS_PER_PROVIDER = 100;
+const POSITIVE_STATES = new Set(['success', 'partial']);
+const QUALIFYING_CATEGORIES = new Set(['phishing', 'malware']);
+// Only built-in provider IDs can affect the built-in score. The two community
+// malware datasets share one publisher family and therefore cannot corroborate
+// one another by themselves.
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { canonicalRegistrableDomain } from "./registrable-domain.mjs";
+import { THREAT_INTELLIGENCE_CONTRACT_VERSION, THREAT_INTELLIGENCE_ENVELOPE_VERSION, THREAT_INTELLIGENCE_SCHEMA, } from "./threat-intelligence-types.mjs";
+const PUBLISHER_FAMILIES = Object.freeze({
+    urlscan_search: 'archived-scan-publisher',
+    urlhaus_host: 'community-malware-publisher',
+    threatfox_domain_ioc: 'community-malware-publisher',
+});
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function timestamp(value) {
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    return normalized ? Date.parse(normalized) : null;
+}
+function providerEvidence(value, expectedDomain) {
+    const provider = record(value);
+    const identity = record(provider?.provider);
+    const observation = record(provider?.observation);
+    const target = record(provider?.target);
+    const providerId = typeof identity?.id === 'string' ? identity.id : '';
+    const publisherFamily = Object.hasOwn(PUBLISHER_FAMILIES, providerId)
+        ? PUBLISHER_FAMILIES[providerId]
+        : null;
+    if (provider?.schema !== THREAT_INTELLIGENCE_SCHEMA
+        || provider.version !== THREAT_INTELLIGENCE_CONTRACT_VERSION
+        || target?.type !== 'domain'
+        || target.exposure !== 'registrable_domain'
+        || target.value !== expectedDomain
+        || !publisherFamily
+        || typeof provider?.state !== 'string'
+        || !POSITIVE_STATES.has(provider.state)
+        || !Array.isArray(provider.findings))
+        return null;
+    const observedAt = timestamp(observation?.observedAt);
+    let latestFindingAt = null;
+    let qualifyingFindings = 0;
+    for (const item of provider.findings.slice(0, MAX_FINDINGS_PER_PROVIDER)) {
+        const finding = record(item);
+        if (!finding || typeof finding.category !== 'string' || !QUALIFYING_CATEGORIES.has(finding.category))
+            continue;
+        const firstObservedAt = timestamp(finding.firstObservedAt);
+        const lastObservedAt = timestamp(finding.lastObservedAt);
+        if (firstObservedAt !== null && lastObservedAt !== null && firstObservedAt > lastObservedAt)
+            continue;
+        qualifyingFindings += 1;
+        const candidate = lastObservedAt ?? firstObservedAt;
+        if (candidate !== null && (latestFindingAt === null || candidate > latestFindingAt))
+            latestFindingAt = candidate;
+    }
+    if (!qualifyingFindings)
+        return null;
+    let ageDays = null;
+    if (observedAt !== null && latestFindingAt !== null && latestFindingAt <= observedAt + MAX_CLOCK_SKEW_MS) {
+        ageDays = Math.max(0, Math.floor((observedAt - latestFindingAt) / DAY_MS));
+    }
+    return {
+        providerId,
+        publisherFamily,
+        qualifyingFindings,
+        lastObservedAt: latestFindingAt === null ? null : new Date(latestFindingAt).toISOString(),
+        ageDays,
+        recent: ageDays !== null && ageDays <= EXTERNAL_INTELLIGENCE_RECENT_DAYS,
+    };
+}
+export function calibrateExternalIntelligenceRisk(value, expectedDomainValue) {
+    const envelope = record(value);
+    const expectedDomain = canonicalRegistrableDomain(expectedDomainValue);
+    const providers = expectedDomain
+        && envelope?.version === THREAT_INTELLIGENCE_ENVELOPE_VERSION
+        && Array.isArray(envelope.providers)
+        ? envelope.providers.slice(0, MAX_PROVIDERS)
+        : [];
+    const byProvider = new Map();
+    for (const item of providers) {
+        const evidence = providerEvidence(item, expectedDomain ?? '');
+        if (!evidence || byProvider.has(evidence.providerId))
+            continue;
+        byProvider.set(evidence.providerId, evidence);
+    }
+    const sources = [...byProvider.values()].sort((a, b) => a.providerId.localeCompare(b.providerId));
+    const publisherFamilies = new Set(sources.map((source) => source.publisherFamily));
+    const recentPublisherFamilies = new Set(sources.filter((source) => source.recent).map((source) => source.publisherFamily));
+    const knownAges = sources.map((source) => source.ageDays).filter((age) => age !== null);
+    const independentPublisherCount = publisherFamilies.size;
+    const recentPublisherCount = recentPublisherFamilies.size;
+    let contribution = 0;
+    let factor = null;
+    if (independentPublisherCount >= 2) {
+        contribution = recentPublisherCount >= 2 ? 18 : 10;
+        factor = {
+            label: recentPublisherCount >= 2
+                ? 'Corroborated recent external phishing/malware records'
+                : 'Corroborated external phishing/malware records',
+            delta: contribution,
+        };
+    }
+    return {
+        version: EXTERNAL_INTELLIGENCE_CALIBRATION_VERSION,
+        contribution,
+        factor,
+        eligibleProviderCount: sources.length,
+        independentPublisherCount,
+        recentPublisherCount,
+        freshestAgeDays: knownAges.length ? Math.min(...knownAges) : null,
+        unknownAgeProviderCount: sources.filter((source) => source.ageDays === null).length,
+        sources,
+    };
+}

package/packages/analysis/http-evidence-bounds.mjs

@@ -0,0 +1,8 @@
+// Browser-safe bounds for the rich HTTP evidence contract and its compact
+// browser-local projection. Both producers and consumers import these values
+// so valid retained evidence is not rejected by a stale projection.
+import { MAX_OUTBOUND_HTTP_URL_CHARACTERS } from "../contracts/http-url.mjs";
+export const MAX_HTTP_EVIDENCE_REDIRECTS = 5;
+export const MAX_HTTP_ATTEMPTS = 2;
+export const MAX_HTTP_PROVENANCE_URL = MAX_OUTBOUND_HTTP_URL_CHARACTERS;
+export const MAX_HTTP_ERROR_LENGTH = 180;

package/packages/analysis/lookup-network-evidence-bounds.mjs

@@ -0,0 +1,10 @@
+// Browser-safe collection bounds shared by the network evidence producers,
+// the Lookup response trust boundary, and the display projection.
+export const MAX_LOOKUP_DNS_RECORDS_PER_TYPE = 16;
+export const MAX_LOOKUP_REVERSE_DNS_PTR_RECORDS = 8;
+export const TLS_PROFILE_VERSION = 3;
+export const MAX_LOOKUP_TLS_CHAIN_CERTIFICATES = 8;
+export const MAX_LOOKUP_TLS_ALT_NAMES = 50;
+export const MAX_LOOKUP_TLS_NAME_VALUES = 4;
+export const MAX_LOOKUP_TLS_FINDINGS = 5;
+export const MAX_LOOKUP_TLS_CERTIFICATE_POLICIES = 16;

package/packages/analysis/opportunity-scoring.mjs

@@ -0,0 +1,107 @@
+import { buildScoreEvidenceQuality, } from "./scoring-evidence-quality.mjs";
+export const OPPORTUNITY_MODEL_VERSION = 2;
+export const OPPORTUNITY_REVIEW_THRESHOLD = 70;
+const STATE_BASE = Object.freeze({
+    available: 82,
+    for_sale: 70,
+    expiring: 52,
+    registered: 22,
+});
+const STATE_LABELS = Object.freeze({
+    available: 'available',
+    for_sale: 'registered with a sale signal',
+    expiring: 'registered in a lifecycle transition',
+    registered: 'registered',
+});
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function formatAge(days) {
+    if (days < 60)
+        return `${Math.max(0, 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 addFactor(factors, dimensions, family, label, delta) {
+    factors.push({ family, label, delta });
+    dimensions.set(family, (dimensions.get(family) ?? 0) + delta);
+}
+export function normalizeOpportunityModelVersion(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= 1000 ? value : null;
+}
+// Opportunity is acquisition readiness, not price, value, eligibility, or a
+// prediction that a registration will lapse. It uses only bounded evidence
+// already collected for the current lookup.
+export function explainOpportunityScore(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const input = value;
+    const state = input.availability ?? input.state;
+    if (typeof state !== 'string' || !Object.hasOwn(STATE_BASE, state))
+        return null;
+    const factors = [];
+    const dimensions = new Map();
+    addFactor(factors, dimensions, 'registration', `Base readiness for “${STATE_LABELS[state] ?? state}”`, STATE_BASE[state] ?? 0);
+    if (input.confidence === 'high')
+        addFactor(factors, dimensions, 'registration', 'High-confidence registration decision', 8);
+    else if (input.confidence === 'medium')
+        addFactor(factors, dimensions, 'registration', 'Medium-confidence registration decision', 3);
+    else if (input.confidence === 'low')
+        addFactor(factors, dimensions, 'registration', 'Low-confidence registration decision', -8);
+    if (state === 'for_sale')
+        addFactor(factors, dimensions, 'listing', 'Bounded sale signal observed; listing remains unverified', 6);
+    else if (input.activityStatus === 'parked')
+        addFactor(factors, dimensions, 'listing', 'Parked page observed without a verified sale offer', 3);
+    else if (state === 'registered' && input.activityStatus === 'active') {
+        addFactor(factors, dimensions, 'listing', 'Active website suggests an in-use registration', -12);
+    }
+    if (input.hasPublicRegistrantContact === true) {
+        addFactor(factors, dimensions, 'contactability', 'Public registrant contact route observed; acquisition suitability is not established', 10);
+    }
+    const expiresInDays = finite(input.expiresInDays);
+    if (state === 'registered' && expiresInDays !== null && expiresInDays >= 0 && expiresInDays < 30) {
+        addFactor(factors, dimensions, 'lifecycle', 'Published expiry is within 30 days; release is not implied', 4);
+    }
+    if (typeof input.privacyProtected === 'boolean') {
+        addFactor(factors, dimensions, 'contactability', 'Registration privacy is neutral; it does not establish contactability', 0);
+    }
+    const ageDays = finite(input.domainAgeDays);
+    if (ageDays !== null && ageDays >= 0) {
+        addFactor(factors, dimensions, 'registration', `Domain age (${formatAge(ageDays)}) is context only`, 0);
+    }
+    const rawScore = Math.round(factors.reduce((total, factor) => total + factor.delta, 0));
+    const score = Math.max(0, Math.min(100, rawScore));
+    const dimensionLabels = {
+        registration: 'Registration certainty',
+        listing: 'Listing readiness',
+        contactability: 'Contactability',
+        lifecycle: 'Lifecycle timing',
+    };
+    const observedFamilies = [...dimensions.keys()];
+    const evidenceQuality = buildScoreEvidenceQuality(input, {
+        expectedDepth: 'fast',
+        observedFamilies,
+        expectedFamilies: ['registration'],
+    });
+    return {
+        modelVersion: OPPORTUNITY_MODEL_VERSION,
+        score,
+        rawScore,
+        capped: score !== rawScore,
+        factors,
+        dimensions: [...dimensions.entries()].map(([id, contribution]) => ({ id, label: dimensionLabels[id], contribution })),
+        evidenceQuality,
+    };
+}
+export function computeOpportunityScore(value) {
+    return explainOpportunityScore(value)?.score ?? null;
+}
+export function opportunityTone(score) {
+    if (score === null)
+        return 'neutral';
+    if (score >= OPPORTUNITY_REVIEW_THRESHOLD)
+        return 'good';
+    if (score >= 40)
+        return 'neutral';
+    return 'warn';
+}

package/packages/analysis/perceptual-hash-comparison.mjs

@@ -0,0 +1,34 @@
+// Browser-safe comparison contract for the 64-bit perceptual hashes produced
+// by the bounded image decoder. Keeping comparison and informativeness here
+// prevents Node and browser consumers from drifting into different matches.
+export const PERCEPTUAL_HASH_HEX_RE = /^[0-9a-f]{16}$/u;
+export const MIN_INFORMATIVE_HASH_BITS = 10;
+const POPCOUNT = new Uint8Array(16);
+for (let index = 0; index < POPCOUNT.length; index += 1) {
+    POPCOUNT[index] = (index & 1) + ((index >> 1) & 1) + ((index >> 2) & 1) + ((index >> 3) & 1);
+}
+export function isPerceptualHash(value) {
+    return typeof value === 'string' && PERCEPTUAL_HASH_HEX_RE.test(value);
+}
+function popcountHex(hex) {
+    let bits = 0;
+    for (let index = 0; index < hex.length; index += 1) {
+        bits += POPCOUNT[parseInt(hex.charAt(index), 16)] ?? 0;
+    }
+    return bits;
+}
+export function isInformativePerceptualHash(value) {
+    if (!isPerceptualHash(value))
+        return false;
+    const bits = popcountHex(value);
+    return bits >= MIN_INFORMATIVE_HASH_BITS && bits <= 64 - MIN_INFORMATIVE_HASH_BITS;
+}
+export function hammingDistanceHex(left, right) {
+    if (!isPerceptualHash(left) || !isPerceptualHash(right))
+        return null;
+    let distance = 0;
+    for (let index = 0; index < 16; index += 1) {
+        distance += POPCOUNT[parseInt(left.charAt(index), 16) ^ parseInt(right.charAt(index), 16)] ?? 0;
+    }
+    return distance;
+}

package/packages/analysis/portable-generator.mjs

@@ -0,0 +1,29 @@
+import { WHOISLEUTH_SOURCE_REPOSITORY_URL, } from "./project-metadata.mjs";
+import { normalizeBoundedSemanticVersion } from "./semantic-version.mjs";
+const URI_LABEL_UNSAFE_GLOBAL_RE = /[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/gu;
+const URI_LABEL_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:(?:\/\/|[^\s])/u;
+export function isUriShapedLabel(value) {
+    if (typeof value !== 'string')
+        return false;
+    const candidate = value.replace(URI_LABEL_UNSAFE_GLOBAL_RE, '').trim();
+    return URI_LABEL_SCHEME_RE.test(candidate);
+}
+export function buildPortableGeneratorMetadata(applicationVersion) {
+    let version = null;
+    if (applicationVersion !== null && applicationVersion !== undefined && applicationVersion !== '') {
+        try {
+            version = normalizeBoundedSemanticVersion(applicationVersion, 'Portable report application');
+        }
+        catch {
+            version = null;
+        }
+    }
+    return Object.freeze({
+        name: 'WHOISleuth',
+        version,
+        projectUrl: WHOISLEUTH_SOURCE_REPOSITORY_URL,
+    });
+}
+export function portableGeneratorAttribution(generator) {
+    return `Generated with ${generator.name}${generator.version ? ` ${generator.version}` : ''} · Source: ${generator.projectUrl}`;
+}

package/packages/analysis/project-metadata.mjs

@@ -0,0 +1,8 @@
+// Browser-safe public project metadata shared by request identity, package
+// verification, canonical URLs, structured data, and public policy pages.
+export const WHOISLEUTH_SITE_ORIGIN = 'https://www.whoisleuth.com';
+export const WHOISLEUTH_PROJECT_URL = `${WHOISLEUTH_SITE_ORIGIN}/`;
+export const WHOISLEUTH_REQUEST_POLICY_URL = `${WHOISLEUTH_SITE_ORIGIN}/request-policy`;
+export const WHOISLEUTH_SOURCE_REPOSITORY_URL = 'https://github.com/slicedearth/whoisleuth';
+export const WHOISLEUTH_SOURCE_REPOSITORY_GIT_URL = `git+${WHOISLEUTH_SOURCE_REPOSITORY_URL}.git`;
+export const WHOISLEUTH_SOURCE_ISSUES_URL = `${WHOISLEUTH_SOURCE_REPOSITORY_URL}/issues`;

package/packages/analysis/registrable-domain.mjs

@@ -0,0 +1,56 @@
+import { getDomain, getPublicSuffix } from 'tldts';
+import { isValidAsciiDomainName } from "../contracts/domain-name.mjs";
+import { MAX_DOMAIN_NAME_LENGTH, MAX_DOMAIN_LABEL_LENGTH } from "../contracts/domain-name.mjs";
+// Reserve the shortest generated name and its separating dot.
+export const MAX_DISCOVERY_SUFFIX_LENGTH = MAX_DOMAIN_NAME_LENGTH - 2;
+/** ICANN suffix rules for a plain ASCII hostname; private suffixes do not change identity. */
+export function publicSuffixForAsciiHostname(value) {
+    if (!isValidAsciiDomainName(value, { requireDot: false, requireLowercase: true }))
+        return null;
+    return getPublicSuffix(value);
+}
+/** Preserve reserved single labels; compound suffixes must match the local ICANN suffix rules. */
+export function normalizeDiscoverySuffix(raw) {
+    if (typeof raw !== 'string' || raw.length > MAX_DISCOVERY_SUFFIX_LENGTH + 1 || /[\u0000-\u001f\u007f]/u.test(raw))
+        return null;
+    const value = raw.trim().toLowerCase().replace(/^\./u, '');
+    if (!value || value.length > MAX_DISCOVERY_SUFFIX_LENGTH)
+        return null;
+    if (value.length <= MAX_DOMAIN_LABEL_LENGTH && /^[a-z]{2,}$/u.test(value))
+        return value;
+    return value.includes('.') && publicSuffixForAsciiHostname(value) === value ? value : null;
+}
+// Returns one canonical registrable-domain identity for an already public DNS
+// hostname. Callers retain the original hostname separately when subdomain
+// context matters; authority, evidence binding and scoring use this value.
+export function canonicalRegistrableDomain(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed || /[\u0000-\u001f\u007f]/u.test(trimmed))
+        return null;
+    const withoutScheme = trimmed.replace(/^[a-z]+:\/\//iu, '').split(/[/?#]/u)[0] ?? '';
+    if (withoutScheme.endsWith('..'))
+        return null;
+    const candidate = withoutScheme.replace(/\.$/u, '');
+    if (!candidate)
+        return null;
+    let hostname;
+    try {
+        hostname = new URL(`https://${candidate}/`).hostname.toLowerCase().replace(/\.$/u, '');
+    }
+    catch {
+        return null;
+    }
+    if (!isValidAsciiDomainName(hostname, { requireDot: true, requireLowercase: true }))
+        return null;
+    // Keep this boundary identical to classifyQuery() and the collection
+    // runtime: registrable identity follows the ICANN Public Suffix List, while
+    // privately operated suffixes remain ordinary host context.
+    const domain = getDomain(hostname);
+    return domain
+        && isValidAsciiDomainName(domain, { requireDot: true, requireLowercase: true })
+        && (hostname === domain || hostname.endsWith(`.${domain}`))
+        ? domain
+        : null;
+}