@slicedearth/whoisleuth-cli 1.32.0

package/lib/bounded-contract-normalizers.mjs

@@ -0,0 +1,61 @@
+// Shared strict primitives for internal evidence contracts. These helpers do
+// not infer missing values and keep every string, object, enum, and counter
+// bounded before a provider or connector result reaches its public model.
+export function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function boundedString(value, maxLength) {
+    if (typeof value !== 'string' || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const normalized = value.trim().replace(/\s+/gu, ' ');
+    return normalized ? normalized.slice(0, maxLength) : null;
+}
+export function strictBoundedString(value, maxLength) {
+    if (typeof value !== 'string'
+        || value.length > maxLength
+        || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const normalized = value.trim().replace(/\s+/gu, ' ');
+    return normalized && normalized.length <= maxLength ? normalized : null;
+}
+export function isoTimestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
+}
+export function boundedHttpsUrl(value, maxLength) {
+    const raw = strictBoundedString(value, maxLength);
+    if (!raw)
+        return null;
+    try {
+        const parsed = new URL(raw);
+        if (parsed.protocol !== 'https:' || parsed.username || parsed.password)
+            return null;
+        const normalized = parsed.toString();
+        return normalized.length <= maxLength ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function exactKeys(value, allowed, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} must be an object`);
+    const unknown = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknown)
+        throw new TypeError(`${label} contains an unknown field: ${unknown}`);
+}
+export function enumValue(value, allowed, label) {
+    if (typeof value !== 'string' || !allowed.has(value)) {
+        throw new TypeError(`${label} is invalid`);
+    }
+    return value;
+}
+export function boundedInteger(value, minimum, maximum, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)
+        || value < minimum || value > maximum) {
+        throw new TypeError(`${label} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}

package/lib/browser-library-profile.mjs

@@ -0,0 +1,310 @@
+// Passive browser-library identification over the capped HTML body already
+// collected by an eligible deep lookup. The matcher uses a pinned, reviewed
+// projection of Retire.js's browser catalogue and never fetches referenced
+// scripts. Upstream URLs, filenames, inline bodies, and catalogue expressions
+// are treated as untrusted inputs and are not retained in the result.
+import { createHash } from 'node:crypto';
+import { RETIRE_BROWSER_CATALOG } from "./generated/retire-browser-catalog.mjs";
+import { createObservation } from "./observation.mjs";
+import { MAX_INLINE_SCRIPT_CHARS, MAX_INLINE_SCRIPT_TOTAL_CHARS, MAX_SCRIPT_ELEMENTS, MAX_STATIC_HTML_CHARS, analyzeStaticHtml, } from "./static-html-analysis.mjs";
+const BROWSER_LIBRARY_PROFILE_VERSION = 1;
+const MAX_LIBRARY_HTML_CHARS = MAX_STATIC_HTML_CHARS;
+const MAX_LIBRARY_FINDINGS = 16;
+const MAX_ADVISORY_IDENTIFIERS = 16;
+const MAX_WEAKNESS_CLASSES = 12;
+const MAX_MATCHES_PER_PATTERN = 4;
+const MAX_VERSION_LENGTH = 64;
+const COMPONENT_RE = /^[a-z0-9._-]{1,80}$/i;
+const VERSION_RE = /^[0-9][0-9.a-z_-]{0,63}$/i;
+const CVE_RE = /^CVE-[0-9X-]+$/;
+const GHSA_RE = /^GHSA-[A-Z0-9-]+$/;
+const CWE_RE = /^CWE-[0-9]+$/;
+const SEVERITY_WEIGHT = Object.freeze({
+    none: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+});
+const CATALOG_COMPONENTS = RETIRE_BROWSER_CATALOG.components;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedStringArray(value, limit, pattern) {
+    const output = [];
+    for (const item of (Array.isArray(value) ? value : []).slice(0, limit)) {
+        if (typeof item !== 'string' || item.length === 0 || item.length > 80 || !pattern.test(item))
+            continue;
+        output.push(item);
+    }
+    return output;
+}
+function comparableVersionPart(value) {
+    if (value === undefined)
+        return 0;
+    return /^[0-9]+$/.test(value) ? Number.parseInt(value, 10) : value;
+}
+// Retire.js uses a deliberately small dotted/dashed version comparator rather
+// than a package-manager-specific semantic-version parser. Keeping the same
+// comparison contract makes the pinned catalogue thresholds deterministic.
+function isAtOrAbove(left, right) {
+    const leftParts = left.split(/[.-]/g);
+    const rightParts = right.split(/[.-]/g);
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPart = comparableVersionPart(leftParts[index]);
+        const rightPart = comparableVersionPart(rightParts[index]);
+        if (typeof leftPart !== typeof rightPart)
+            return typeof leftPart === 'number';
+        if (leftPart > rightPart)
+            return true;
+        if (leftPart < rightPart)
+            return false;
+    }
+    return true;
+}
+function matchingVulnerabilities(component, version) {
+    const vulnerabilities = Array.isArray(component.vulnerabilities) ? component.vulnerabilities : [];
+    const matched = [];
+    for (const rawVulnerability of vulnerabilities) {
+        const vulnerability = record(rawVulnerability);
+        if (typeof vulnerability.below !== 'string' || !VERSION_RE.test(vulnerability.below))
+            continue;
+        if (isAtOrAbove(version, vulnerability.below))
+            continue;
+        if (typeof vulnerability.atOrAbove === 'string'
+            && VERSION_RE.test(vulnerability.atOrAbove)
+            && !isAtOrAbove(version, vulnerability.atOrAbove))
+            continue;
+        if (Array.isArray(vulnerability.excludes) && vulnerability.excludes.includes(version))
+            continue;
+        matched.push(vulnerability);
+    }
+    return matched;
+}
+function matchPattern(pattern, value) {
+    if (typeof pattern !== 'string' || pattern.length === 0 || pattern.length > 2_048)
+        return [];
+    let expression;
+    try {
+        expression = new RegExp(pattern, 'g');
+    }
+    catch {
+        return [];
+    }
+    const matches = [];
+    let match;
+    while ((match = expression.exec(value)) && matches.length < MAX_MATCHES_PER_PATTERN) {
+        if (typeof match[1] === 'string' && VERSION_RE.test(match[1]))
+            matches.push(match[1]);
+        if (match[0] === '')
+            expression.lastIndex += 1;
+    }
+    return matches;
+}
+function matchReplacementPattern(pattern, value) {
+    if (typeof pattern !== 'string' || pattern.length === 0 || pattern.length > 2_048)
+        return [];
+    const descriptor = /^\/(.*[^\\])\/([^/]+)\/$/.exec(pattern);
+    const expressionSource = descriptor?.[1];
+    const replacement = descriptor?.[2];
+    if (!expressionSource || replacement === undefined)
+        return [];
+    let expression;
+    try {
+        expression = new RegExp(expressionSource, 'g');
+    }
+    catch {
+        return [];
+    }
+    const matches = [];
+    let match;
+    while ((match = expression.exec(value)) && matches.length < MAX_MATCHES_PER_PATTERN) {
+        const replaced = match[0].replace(new RegExp(expressionSource), replacement).replace(/(?:\.|-)?min$/i, '');
+        if (VERSION_RE.test(replaced))
+            matches.push(replaced);
+        if (match[0] === '')
+            expression.lastIndex += 1;
+    }
+    return matches;
+}
+function addDetected(detected, component, version, method) {
+    const normalizedVersion = version.replace(/(?:\.|-)?min$/i, '').slice(0, MAX_VERSION_LENGTH);
+    if (!COMPONENT_RE.test(component) || !VERSION_RE.test(normalizedVersion))
+        return;
+    const key = `${component}\u0000${normalizedVersion}`;
+    const existing = detected.get(key);
+    if (existing) {
+        existing.detections.add(method);
+        return;
+    }
+    if (detected.size >= MAX_LIBRARY_FINDINGS * 4)
+        return;
+    detected.set(key, { component, version: normalizedVersion, detections: new Set([method]) });
+}
+function scanExtractor(detected, extractorName, value, method) {
+    for (const [componentName, rawComponent] of Object.entries(CATALOG_COMPONENTS)) {
+        const component = record(rawComponent);
+        const extractors = record(component.extractors);
+        const patterns = Array.isArray(extractors[extractorName]) ? extractors[extractorName] : [];
+        for (const pattern of patterns.slice(0, 64)) {
+            for (const version of matchPattern(pattern, value))
+                addDetected(detected, componentName, version, method);
+        }
+    }
+}
+function scanFilename(detected, reference) {
+    const filename = (reference.replace(/\\/g, '/').split('/').pop() || '').split(/[?#]/, 1)[0];
+    if (!filename)
+        return;
+    for (const [componentName, rawComponent] of Object.entries(CATALOG_COMPONENTS)) {
+        const component = record(rawComponent);
+        const extractors = record(component.extractors);
+        const patterns = Array.isArray(extractors.filename) ? extractors.filename : [];
+        for (const pattern of patterns.slice(0, 64)) {
+            if (typeof pattern !== 'string' || pattern.length > 2_048)
+                continue;
+            for (const version of matchPattern(`^(?:${pattern})$`, filename)) {
+                addDetected(detected, componentName, version, 'script filename');
+            }
+        }
+    }
+}
+function scanInlineContent(detected, content) {
+    const normalized = content.replace(/\r\n?|\n/g, '\n');
+    const digest = createHash('sha1').update(normalized).digest('hex');
+    scanExtractor(detected, 'filecontent', normalized, 'inline signature');
+    for (const [componentName, rawComponent] of Object.entries(CATALOG_COMPONENTS)) {
+        const component = record(rawComponent);
+        const extractors = record(component.extractors);
+        const replacementPatterns = Array.isArray(extractors.filecontentreplace) ? extractors.filecontentreplace : [];
+        for (const pattern of replacementPatterns.slice(0, 64)) {
+            for (const version of matchReplacementPattern(pattern, normalized)) {
+                addDetected(detected, componentName, version, 'inline signature');
+            }
+        }
+        const hashes = record(extractors.hashes);
+        const version = hashes[digest];
+        if (typeof version === 'string')
+            addDetected(detected, componentName, version, 'inline hash');
+    }
+}
+function severity(value) {
+    return typeof value === 'string' && Object.hasOwn(SEVERITY_WEIGHT, value)
+        ? value
+        : null;
+}
+function findingFromDetection(detected) {
+    const component = record(CATALOG_COMPONENTS[detected.component]);
+    const vulnerabilities = matchingVulnerabilities(component, detected.version);
+    let highestSeverity = null;
+    const identifiers = new Set();
+    const weaknesses = new Set();
+    for (const vulnerability of vulnerabilities) {
+        const candidateSeverity = severity(vulnerability.severity);
+        if (candidateSeverity
+            && (!highestSeverity || SEVERITY_WEIGHT[candidateSeverity] > SEVERITY_WEIGHT[highestSeverity]))
+            highestSeverity = candidateSeverity;
+        const vulnerabilityIdentifiers = record(vulnerability.identifiers);
+        for (const cve of boundedStringArray(vulnerabilityIdentifiers.CVE, 16, CVE_RE)) {
+            if (identifiers.size < MAX_ADVISORY_IDENTIFIERS)
+                identifiers.add(cve);
+        }
+        if (typeof vulnerabilityIdentifiers.githubID === 'string'
+            && GHSA_RE.test(vulnerabilityIdentifiers.githubID)
+            && identifiers.size < MAX_ADVISORY_IDENTIFIERS)
+            identifiers.add(vulnerabilityIdentifiers.githubID.toUpperCase());
+        for (const cwe of boundedStringArray(vulnerability.cwe, 16, CWE_RE)) {
+            if (weaknesses.size < MAX_WEAKNESS_CLASSES)
+                weaknesses.add(cwe);
+        }
+    }
+    return {
+        id: detected.component,
+        name: detected.component,
+        apparentVersion: detected.version,
+        detectionMethods: [...detected.detections].sort(),
+        advisoryCount: vulnerabilities.length,
+        highestSeverity,
+        advisoryIdentifiers: [...identifiers].sort(),
+        weaknessClasses: [...weaknesses].sort(),
+    };
+}
+function analyzeBrowserLibraries(input = {}) {
+    const htmlAnalysis = input.htmlAnalysis ?? analyzeStaticHtml(input.html);
+    const detected = new Map();
+    let referencesExamined = 0;
+    let inlineScriptsExamined = 0;
+    for (const script of htmlAnalysis.scripts) {
+        if (script.reference) {
+            referencesExamined += 1;
+            scanExtractor(detected, 'uri', script.reference, 'script URL');
+            scanFilename(detected, script.reference);
+        }
+        else if (script.inlineContent && script.mediaType !== 'application/ld+json') {
+            inlineScriptsExamined += 1;
+            scanInlineContent(detected, script.inlineContent);
+        }
+    }
+    const allFindings = [...detected.values()]
+        .map(findingFromDetection)
+        .sort((left, right) => ((right.highestSeverity ? SEVERITY_WEIGHT[right.highestSeverity] : -1)
+        - (left.highestSeverity ? SEVERITY_WEIGHT[left.highestSeverity] : -1)
+        || right.advisoryCount - left.advisoryCount
+        || left.name.localeCompare(right.name)
+        || left.apparentVersion.localeCompare(right.apparentVersion)));
+    const findingLimitReached = allFindings.length > MAX_LIBRARY_FINDINGS;
+    const truncated = input.sourceTruncated === true
+        || htmlAnalysis.inputLimitReached
+        || htmlAnalysis.tagLimitReached
+        || htmlAnalysis.scriptLimitReached
+        || htmlAnalysis.inlineLimitReached
+        || findingLimitReached;
+    const limitations = [
+        'Library versions are inferred from passive static signatures and may be absent, transformed, or misleading.',
+        'A catalogue advisory match identifies a component version associated with a published advisory; it does not establish reachability or exploitability.',
+        'Referenced scripts are not fetched, executed, or retained, and unmatched scripts are not evidence that no library is present.',
+    ];
+    if (input.sourceTruncated === true)
+        limitations.push('The captured homepage body was truncated, so script evidence may be incomplete.');
+    if (htmlAnalysis.inputLimitReached)
+        limitations.push(`Only the first ${MAX_LIBRARY_HTML_CHARS} HTML characters were evaluated.`);
+    if (htmlAnalysis.tagLimitReached)
+        limitations.push('Static HTML tokenization reached its tag or attribute boundary.');
+    if (htmlAnalysis.scriptLimitReached)
+        limitations.push(`Only the first ${MAX_SCRIPT_ELEMENTS} script elements were evaluated.`);
+    if (htmlAnalysis.inlineLimitReached)
+        limitations.push(`Inline script evaluation reached its ${MAX_INLINE_SCRIPT_TOTAL_CHARS}-character cumulative boundary.`);
+    if (findingLimitReached)
+        limitations.push(`Only the first ${MAX_LIBRARY_FINDINGS} library findings were retained.`);
+    return {
+        profileVersion: BROWSER_LIBRARY_PROFILE_VERSION,
+        catalog: {
+            name: 'Retire.js',
+            version: RETIRE_BROWSER_CATALOG.catalogVersion,
+            sourceRevision: RETIRE_BROWSER_CATALOG.sourceRevision,
+        },
+        ...createObservation({
+            status: truncated ? 'partial' : 'success',
+            observedAt: input.observedAt,
+            scanMode: 'deep',
+            source: 'derived',
+            complete: !truncated,
+            truncated,
+            limitations,
+            diagnostics: {
+                scriptsExamined: htmlAnalysis.scripts.length,
+                referencesExamined,
+                inlineScriptsExamined,
+                inlineCharactersExamined: htmlAnalysis.inlineCharactersExamined,
+                catalogComponents: Object.keys(CATALOG_COMPONENTS).length,
+                findings: allFindings.length,
+                advisoryMatches: allFindings.reduce((sum, finding) => sum + finding.advisoryCount, 0),
+            },
+        }),
+        findings: allFindings.slice(0, MAX_LIBRARY_FINDINGS),
+    };
+}
+export { BROWSER_LIBRARY_PROFILE_VERSION, MAX_INLINE_SCRIPT_CHARS, MAX_INLINE_SCRIPT_TOTAL_CHARS, MAX_LIBRARY_FINDINGS, MAX_LIBRARY_HTML_CHARS, MAX_SCRIPT_ELEMENTS, analyzeBrowserLibraries, };

package/lib/bulk-comparison-evidence.mjs

@@ -0,0 +1,83 @@
+// Bounded comparison-only evidence for compact Deep Bulk responses. The
+// complete technology and TLS observations remain transient and separately
+// attributed; this projection retains only stable identifiers and source
+// health needed for analyst-controlled comparisons.
+export const BULK_COMPARISON_EVIDENCE_VERSION = 1;
+export const MAX_BULK_TECHNOLOGY_IDS = 12;
+export const MAX_BULK_TLS_ISSUER_LENGTH = 240;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
+const TECHNOLOGY_ID_RE = /^[a-z0-9][a-z0-9_-]{0,79}$/u;
+const SHA256_RE = /^[a-f0-9]{64}$/iu;
+const STATES = new Set(['error', 'not_found', 'partial', 'success', 'unavailable']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maximum) {
+    return typeof value === 'string' && value.length <= maximum && !CONTROL_RE.test(value)
+        ? value.replace(/\s+/gu, ' ').trim()
+        : '';
+}
+function state(value) {
+    const normalized = boundedText(value, 40).toLowerCase();
+    return STATES.has(normalized)
+        ? normalized
+        : 'unavailable';
+}
+function technologyIds(value) {
+    if (!Array.isArray(value))
+        return { ids: [], truncated: false };
+    const output = new Set();
+    let truncated = value.length > MAX_BULK_TECHNOLOGY_IDS;
+    for (const candidate of value.slice(0, MAX_BULK_TECHNOLOGY_IDS * 4)) {
+        const id = boundedText(record(candidate).id, 80).toLowerCase();
+        if (!TECHNOLOGY_ID_RE.test(id) || output.has(id))
+            continue;
+        if (output.size >= MAX_BULK_TECHNOLOGY_IDS)
+            truncated = true;
+        else
+            output.add(id);
+    }
+    return { ids: [...output].sort(), truncated };
+}
+function issuerLabel(value) {
+    const issuer = record(value);
+    const values = [
+        ...(Array.isArray(issuer.commonNames) ? issuer.commonNames : []),
+        ...(Array.isArray(issuer.organizations) ? issuer.organizations : []),
+    ]
+        .slice(0, 8)
+        .map((candidate) => boundedText(candidate, 160))
+        .filter(Boolean);
+    const label = [...new Set(values)].join(' · ');
+    return label ? label.slice(0, MAX_BULK_TLS_ISSUER_LENGTH) : null;
+}
+export function buildBulkComparisonEvidence(availabilityValue) {
+    const availability = record(availabilityValue);
+    const technology = record(availability.technologyProfile);
+    const technologyState = state(technology.status);
+    const technologyUsable = ['success', 'partial'].includes(technologyState);
+    const technologyFindings = technologyUsable
+        ? technologyIds(technology.findings)
+        : { ids: [], truncated: false };
+    const tls = record(availability.tls);
+    const tlsState = state(tls.status);
+    const tlsUsable = ['success', 'partial'].includes(tlsState);
+    const certificate = record(tls.certificate);
+    const publicKey = record(certificate.publicKey);
+    const spki = boundedText(publicKey.fingerprintSha256, 64);
+    return {
+        version: BULK_COMPARISON_EVIDENCE_VERSION,
+        technology: {
+            state: technologyState,
+            ids: technologyFindings.ids,
+            truncated: technologyUsable && (technology.truncated === true || technologyFindings.truncated),
+        },
+        tls: {
+            state: tlsState,
+            issuerLabel: tlsUsable ? issuerLabel(certificate.issuer) : null,
+            spkiSha256: tlsUsable && SHA256_RE.test(spki) ? spki.toLowerCase() : null,
+        },
+    };
+}

package/lib/classify.mjs

@@ -0,0 +1,93 @@
+// Query classification - shared by both the Express server and the Netlify
+// Functions so a domain/IP/ASN query is always parsed identically wherever
+// this code runs. Every classified value eventually reaches a raw protocol
+// call - a WHOIS TCP socket write (lib/whois.mts), a DNS query, an RDAP/
+// MTA-STS fetch URL - and none of those downstream call sites re-validate
+// syntax, so this is the one place responsible for rejecting anything that
+// isn't actually safe to hand to them.
+//
+// Domains are classified to their *registrable* domain via the Public Suffix
+// List (tldts). Registries only publish RDAP/WHOIS records at the registrable-
+// domain level, so a lookup for `login.example.com` must query `example.com` -
+// otherwise an arbitrary subdomain's RDAP 404 would be misread as "available
+// to register" when the underlying registration plainly exists. Both the
+// original input hostname and the resolved registrable domain are returned so
+// callers can look up the latter while still showing the user what they typed.
+import { isIP } from 'node:net';
+import { parse } from 'tldts';
+// A CR/LF here would let one query become multiple lines once it reaches
+// lib/whois.mts's raw `socket.write(query + '\r\n')` - a normal URL-encoded
+// query string (?q=example.com%0D%0AHELP) decodes back into literal control
+// characters before this function ever sees them, so this has to be
+// checked explicitly, before any other parsing, rather than assumed away.
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+// 32-bit ASN ceiling (RFC 6793 four-octet ASNs). AS0 and AS4294967295 are
+// reserved but syntactically valid; anything above is not an ASN at all.
+const MAX_ASN = 4294967295;
+// A registrable-domain label: LDH (letter/digit/hyphen), 1-63 characters, no
+// leading or trailing hyphen. tldts already rejects empty labels, over-long
+// labels, leading/trailing hyphens, and public-suffix-only inputs (all yield
+// a null registrable domain) - but it does NOT reject underscores, so this is
+// the explicit backstop that catches `foo_bar.com` and makes the full rule
+// checkable in one place.
+function isValidRegistrableLabel(label) {
+    return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label);
+}
+function classifyQuery(raw) {
+    const trimmed = raw.trim();
+    if (CONTROL_CHAR_RE.test(trimmed)) {
+        throw new Error('Query contains control characters, which are not valid in a domain, IP, or ASN.');
+    }
+    // Strip a scheme and any path/query/fragment. A single terminal root dot
+    // (`example.com.`, the fully-qualified form) is normalized away, but more
+    // than one is malformed - a valid name has at most one root label.
+    const withoutScheme = trimmed.replace(/^[a-z]+:\/\//i, '').split(/[/?#]/)[0] ?? '';
+    if (withoutScheme.endsWith('..')) {
+        throw new Error(`"${trimmed}" has more than one terminal dot.`);
+    }
+    const q = withoutScheme.replace(/\.$/, '');
+    // net.isIP is Node's own IP-address parser - stricter and more correct
+    // than a hand-rolled regex (rejects out-of-range IPv4 octets, malformed
+    // IPv6 groupings, etc.) and handles both families in one call.
+    const ipVersion = isIP(q);
+    if (ipVersion === 4)
+        return { type: 'ipv4', value: q };
+    if (ipVersion === 6)
+        return { type: 'ipv6', value: q };
+    const asnMatch = q.match(/^AS(\d+)$/i) || q.match(/^(\d+)$/);
+    if (asnMatch) {
+        const num = Number(asnMatch[1]);
+        if (!Number.isInteger(num) || num < 0 || num > MAX_ASN) {
+            throw new Error(`"${trimmed}" is not a valid ASN (must be an integer 0-${MAX_ASN}).`);
+        }
+        return { type: 'asn', value: `AS${num}` };
+    }
+    // Domain: IDNA-normalize via the WHATWG URL parser (punycode-encodes an
+    // internationalized name, strips a stray port), then resolve the registrable
+    // domain via the Public Suffix List.
+    let inputHostname;
+    try {
+        inputHostname = new URL(`https://${q}`).hostname.toLowerCase();
+    }
+    catch {
+        inputHostname = '';
+    }
+    if (!inputHostname || !inputHostname.includes('.') || inputHostname.length > 253) {
+        throw new Error(`"${trimmed}" is not a valid domain, IP, or ASN.`);
+    }
+    const registrableDomain = parse(inputHostname).domain;
+    if (!registrableDomain) {
+        throw new Error(`"${trimmed}" is not a registrable domain (no public-suffix match).`);
+    }
+    if (!registrableDomain.split('.').every(isValidRegistrableLabel)) {
+        throw new Error(`"${trimmed}" contains an invalid domain label (underscores, empty, or malformed labels are not registrable).`);
+    }
+    return {
+        type: 'domain',
+        value: registrableDomain,
+        inputHostname,
+        registrableDomain,
+        isSubdomain: inputHostname !== registrableDomain,
+    };
+}
+export { classifyQuery, MAX_ASN };

package/lib/client-behavior-profile.mjs

@@ -0,0 +1,83 @@
+// Static client-side behaviour indicators derived from the existing bounded
+// HTML tokenizer pass. Scripts are never fetched or executed. Only fixed
+// indicator identifiers, descriptions, evidence classes, and bounded counts
+// leave this module; script references and contents are discarded.
+import { createObservation } from "./observation.mjs";
+import { analyzeStaticHtml, } from "./static-html-analysis.mjs";
+const CLIENT_BEHAVIOR_PROFILE_VERSION = 1;
+const MAX_CLIENT_BEHAVIOR_INDICATORS = 12;
+const MAX_INDICATOR_OCCURRENCES = 999;
+function boundedOccurrences(value) {
+    return Math.max(1, Math.min(MAX_INDICATOR_OCCURRENCES, value));
+}
+function patternCount(value, pattern) {
+    let count = 0;
+    for (const _match of value.matchAll(pattern)) {
+        count += 1;
+        if (count >= MAX_INDICATOR_OCCURRENCES)
+            break;
+    }
+    return count;
+}
+function analyzeClientBehavior(input = {}) {
+    const htmlAnalysis = input.htmlAnalysis ?? analyzeStaticHtml(input.html);
+    const markup = htmlAnalysis.markup;
+    const inlineScripts = htmlAnalysis.scripts
+        .filter((script) => script.reference === null)
+        .map((script) => script.inlineContent)
+        .join('\n');
+    const indicators = [];
+    function add(id, label, evidenceClass, occurrences, explanation) {
+        if (occurrences <= 0 || indicators.length >= MAX_CLIENT_BEHAVIOR_INDICATORS)
+            return;
+        indicators.push({ id, label, evidenceClass, occurrences: boundedOccurrences(occurrences), explanation });
+    }
+    add('inline_event_handlers', 'Inline event handlers', 'static_markup', patternCount(markup, /\son[a-z]{2,24}="/gu), 'Inline HTML event-handler attributes were observed.');
+    add('client_navigation', 'Client-side navigation', 'inline_script', patternCount(inlineScripts, /\b(?:history\.(?:pushState|replaceState)|location\.(?:assign|replace)|window\.location)\b/gu), 'Inline script contains a client-side navigation API.');
+    add('form_interception', 'Form interception', 'inline_script', patternCount(inlineScripts, /(?:addEventListener\s*\(\s*['"]submit['"]|\.onsubmit\s*=|preventDefault\s*\()/gu), 'Inline script contains a form-submission or default-action interception marker.');
+    add('service_worker', 'Service worker registration', 'inline_script', patternCount(inlineScripts, /\bnavigator\.serviceWorker\.register\s*\(/gu), 'Inline script contains a service-worker registration call.');
+    add('browser_storage', 'Browser storage access', 'inline_script', patternCount(inlineScripts, /\b(?:localStorage|sessionStorage|indexedDB)\b/gu), 'Inline script references a browser-local storage API.');
+    add('clipboard_access', 'Clipboard access', 'inline_script', patternCount(inlineScripts, /\bnavigator\.clipboard\b/gu), 'Inline script references the browser clipboard API.');
+    add('dynamic_code_evaluation', 'Dynamic code evaluation', 'inline_script', patternCount(inlineScripts, /(?:\beval\s*\(|\bnew\s+Function\s*\()/gu), 'Inline script contains a dynamic code-evaluation API.');
+    add('browser_fingerprinting', 'Browser fingerprinting surfaces', 'inline_script', patternCount(inlineScripts, /(?:toDataURL\s*\(|getImageData\s*\(|AudioContext\b|WEBGL_debug_renderer_info\b)/gu), 'Inline script references an API commonly used in browser-fingerprint calculations.');
+    add('persistent_connection', 'Persistent client connection', 'inline_script', patternCount(inlineScripts, /\b(?:WebSocket|EventSource)\s*\(/gu), 'Inline script contains a persistent browser-connection constructor.');
+    const sourceTruncated = input.sourceTruncated === true;
+    const truncated = sourceTruncated
+        || htmlAnalysis.inputLimitReached
+        || htmlAnalysis.tagLimitReached
+        || htmlAnalysis.scriptLimitReached
+        || htmlAnalysis.inlineLimitReached;
+    const limitations = [
+        'Indicators come only from bounded static markup and retained inline-script prefixes; referenced scripts are not fetched and no code is executed.',
+        'An observed API or handler can be normal application behaviour and does not establish vulnerability, tracking, credential theft, maliciousness, reachability, or execution.',
+        'No script contents, script references, paths, queries, hashes, arbitrary attributes, or matched source fragments are retained.',
+        'No indicator means only that the bounded retained static evidence did not match this fixed catalogue.',
+    ];
+    if (truncated)
+        limitations.push('The captured page or static script/token boundaries were reached, so behaviour indicators may be incomplete.');
+    return {
+        clientBehaviorProfileVersion: CLIENT_BEHAVIOR_PROFILE_VERSION,
+        ...createObservation({
+            status: truncated ? 'partial' : 'success',
+            observedAt: input.observedAt,
+            scanMode: 'deep',
+            source: 'derived',
+            complete: !truncated,
+            truncated,
+            limitations,
+            diagnostics: {
+                indicatorsObserved: indicators.length,
+                scriptElementsExamined: htmlAnalysis.scripts.length,
+                inlineCharactersExamined: htmlAnalysis.inlineCharactersExamined,
+            },
+        }),
+        scriptSummary: {
+            elementsObserved: htmlAnalysis.scripts.length,
+            referencedScripts: htmlAnalysis.scripts.filter((script) => script.reference !== null).length,
+            inlineScripts: htmlAnalysis.scripts.filter((script) => script.reference === null).length,
+            moduleScripts: htmlAnalysis.scripts.filter((script) => script.mediaType === 'module').length,
+        },
+        indicators,
+    };
+}
+export { CLIENT_BEHAVIOR_PROFILE_VERSION, MAX_CLIENT_BEHAVIOR_INDICATORS, analyzeClientBehavior, };