@slicedearth/whoisleuth-cli 1.43.0 → 1.47.4

package/lib/availability.mjs

@@ -115,18 +115,17 @@ const PRIVACY_MARKERS = [
     /not disclosed/i,
     /withheld for privacy/i,
 ];
-// Only ever called after a lookup has already succeeded (this runs inside
-// checkDomainAvailability once RDAP or WHOIS has returned real data), so a
-// missing/empty registrant here isn't "we don't know" - it means the
-// registry gave us a response with no usable contact in it, which for
-// sourcing purposes (can I reach this owner from this data alone?) is the
-// same practical answer as an explicit privacy-proxy service: no.
+// Explicit privacy/redaction markers establish a positive privacy signal.
+// Usable public contact data establishes a negative one. A missing or blank
+// contact can instead reflect registry policy, access tier, parser coverage,
+// or ordinary omission, so it remains inconclusive rather than being promoted
+// to an affirmative privacy claim.
 function isPrivacyProtected(registrant) {
     if (!registrant)
-        return true;
+        return null;
     const blob = [registrant.name, registrant.org, registrant.email].filter(Boolean).join(' ');
     if (!blob)
-        return true; // record exists but every contact field is blank - that's redaction
+        return null;
     return PRIVACY_MARKERS.some((re) => re.test(blob));
 }
 // RDAP Lookup retains a bounded multi-value contact inventory, but Bulk and
@@ -197,7 +196,10 @@ async function checkDnsDelegation(domain, { resolver = dns.resolveNs } = {}) {
 // domain has "no site": transient DNS/TLS/network failures, a slow origin, or
 // an HTTP error can all produce the same null body. Keeping that distinction
 // avoids turning an inconclusive probe into a false inactivity claim.
-async function fetchHomepage(domain, { fetcher = safeFetchDetailed } = {}) {
+async function fetchHomepage(domain, { fetcher = safeFetchDetailed, timeoutMs = HOMEPAGE_FETCH_TIMEOUT_MS } = {}) {
+    const requestTimeoutMs = Number.isInteger(timeoutMs) && timeoutMs >= 10 && timeoutMs <= HOMEPAGE_FETCH_TIMEOUT_MS
+        ? timeoutMs
+        : HOMEPAGE_FETCH_TIMEOUT_MS;
     const headers = whoisleuthRequestHeaders();
     const failures = [];
     const probeStartedAt = Date.now();
@@ -205,7 +207,7 @@ async function fetchHomepage(domain, { fetcher = safeFetchDetailed } = {}) {
         const requestUrl = `${scheme}://${domain}`;
         const attemptStartedAt = Date.now();
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), HOMEPAGE_FETCH_TIMEOUT_MS);
+        const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
         try {
             const fetched = await fetcher(requestUrl, { signal: controller.signal, headers });
             const fetchedResponse = fetched instanceof Response ? fetched : fetched.response;
@@ -274,7 +276,7 @@ async function fetchHomepage(domain, { fetcher = safeFetchDetailed } = {}) {
         catch (err) {
             const error = errorRecord(err);
             const reason = error.name === 'AbortError'
-                ? 'timed out after 6 seconds'
+                ? `timed out after ${requestTimeoutMs} milliseconds`
                 : nonEmptyErrorMessage(err, 'request failed')
                     .replace(/[\u0000-\u001f\u007f]+/g, ' ')
                     .slice(0, 180);
@@ -733,4 +735,4 @@ async function checkDomainAvailability(domain, options = {}) {
         hasDmarc: dnsIntelligence.hasDmarc,
     };
 }
-export { checkDomainAvailability, checkDnsDelegation, fetchHomepage, deriveWebsiteActivity, forSaleRedirectSignal, parseRegistryDate as parseWhoisDate, };
+export { checkDomainAvailability, checkDnsDelegation, fetchHomepage, isPrivacyProtected, deriveWebsiteActivity, forSaleRedirectSignal, parseRegistryDate as parseWhoisDate, };

package/lib/bounded-file.mjs

@@ -0,0 +1,82 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+const MAX_BOUNDED_FILE_BYTES = 64 * 1024 * 1024;
+function boundedSize(value, fallback) {
+    return Number.isSafeInteger(value) && Number(value) >= 0 && Number(value) <= MAX_BOUNDED_FILE_BYTES
+        ? Number(value)
+        : fallback;
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason instanceof Error
+        ? signal.reason
+        : new DOMException('The operation was aborted.', 'AbortError');
+}
+export async function readBoundedRegularFile(filePath, options, dependencies = {}) {
+    const label = options.label?.trim().slice(0, 120) || 'Input file';
+    const maximumBytes = boundedSize(options.maximumBytes, 0);
+    const minimumBytes = boundedSize(options.minimumBytes, 0);
+    if (maximumBytes < 1 || minimumBytes > maximumBytes) {
+        throw new TypeError(`${label} has an invalid byte boundary.`);
+    }
+    const expectedBytes = options.expectedBytes === null || options.expectedBytes === undefined
+        ? null
+        : boundedSize(options.expectedBytes, -1);
+    if (expectedBytes !== null && (expectedBytes < minimumBytes || expectedBytes > maximumBytes)) {
+        throw new TypeError(`${label} expected size is outside its byte boundary.`);
+    }
+    throwIfAborted(options.signal);
+    // Non-blocking open prevents a named pipe from stalling the process before
+    // the descriptor can be classified. Final-component symlinks remain denied
+    // unless an analyst-facing input explicitly opts in; artefacts resolved
+    // inside a verified directory must retain the default confinement boundary.
+    const flags = constants.O_RDONLY
+        | constants.O_NONBLOCK
+        | (options.allowSymbolicLink ? 0 : constants.O_NOFOLLOW);
+    const handle = await (dependencies.openFile ?? open)(filePath, flags);
+    try {
+        throwIfAborted(options.signal);
+        const before = await handle.stat();
+        throwIfAborted(options.signal);
+        if (!before.isFile())
+            throw new TypeError(`${label} must be a regular file.`);
+        if (before.size < minimumBytes)
+            throw new TypeError(`${label} is smaller than its ${minimumBytes}-byte minimum.`);
+        if (before.size > maximumBytes)
+            throw new TypeError(`${label} exceeds its ${maximumBytes}-byte maximum.`);
+        if (expectedBytes !== null && before.size !== expectedBytes) {
+            throw new TypeError(`${label} size does not match its declared size.`);
+        }
+        // Read from the already-opened descriptor and reserve only one sentinel
+        // byte beyond the admitted size. A concurrent append is detected without
+        // allocating from an attacker-controlled post-stat file length.
+        const storage = Buffer.allocUnsafe(Math.min(maximumBytes + 1, before.size + 1));
+        let offset = 0;
+        while (offset < storage.length) {
+            throwIfAborted(options.signal);
+            const { bytesRead } = await handle.read(storage, offset, storage.length - offset, null);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        throwIfAborted(options.signal);
+        const after = await handle.stat();
+        throwIfAborted(options.signal);
+        if (offset > maximumBytes
+            || after.size !== before.size
+            || offset !== after.size
+            || after.mtimeMs !== before.mtimeMs
+            || after.ctimeMs !== before.ctimeMs) {
+            throw new TypeError(`${label} changed while it was being read.`);
+        }
+        return Buffer.from(storage.subarray(0, offset));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readBoundedRegularTextFile(filePath, options, dependencies = {}) {
+    return (await readBoundedRegularFile(filePath, options, dependencies)).toString('utf8');
+}
+export { MAX_BOUNDED_FILE_BYTES };

package/lib/bounded-json-response.mjs

@@ -0,0 +1,170 @@
+// Environment-neutral browser/server JSON response boundary. It enforces a
+// declared and streamed byte ceiling before parsing and can apply one deadline
+// across both the fetch and body-read phases.
+export const SMALL_JSON_RESPONSE_BYTES = 64 * 1024;
+export const STANDARD_JSON_RESPONSE_BYTES = 2 * 1024 * 1024;
+export const LARGE_JSON_RESPONSE_BYTES = 8 * 1024 * 1024;
+export const DEFAULT_JSON_RESPONSE_TIMEOUT_MS = 40_000;
+const MAX_JSON_RESPONSE_TIMEOUT_MS = 120_000;
+export class BoundedJsonResponseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'BoundedJsonResponseError';
+        this.code = code;
+    }
+}
+async function raceWithAbort(promise, signal, onLateResolution) {
+    if (signal.aborted)
+        throw signal.reason ?? new Error('Request aborted.');
+    return new Promise((resolve, reject) => {
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            reject(signal.reason ?? new Error('Request aborted.'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            if (aborted) {
+                void Promise.resolve(onLateResolution?.(value)).catch(() => { });
+                return;
+            }
+            resolve(value);
+        }, (cause) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(cause);
+        });
+    });
+}
+function boundedPositiveInteger(value, fallback, maximum) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(1, Math.min(maximum, Math.round(value)))
+        : fallback;
+}
+export async function readJsonResponseCapped(response, maximumBytes = STANDARD_JSON_RESPONSE_BYTES, signal, validateRawJson) {
+    const maxBytes = boundedPositiveInteger(maximumBytes, STANDARD_JSON_RESPONSE_BYTES, LARGE_JSON_RESPONSE_BYTES);
+    const declared = response.headers.get('content-length');
+    if (declared && /^\d+$/u.test(declared)) {
+        const bytes = Number(declared);
+        if (!Number.isSafeInteger(bytes) || bytes > maxBytes) {
+            await response.body?.cancel().catch(() => { });
+            throw new BoundedJsonResponseError('response_too_large', `JSON response exceeded ${maxBytes} bytes.`);
+        }
+    }
+    if (!response.body)
+        return null;
+    const reader = response.body.getReader();
+    const cancelOnAbort = () => { void reader.cancel(signal?.reason).catch(() => { }); };
+    signal?.addEventListener('abort', cancelOnAbort, { once: true });
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const read = reader.read();
+            const { done, value } = signal ? await raceWithAbort(read, signal) : await read;
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => { });
+                throw new BoundedJsonResponseError('response_too_large', `JSON response exceeded ${maxBytes} bytes.`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', cancelOnAbort);
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    let raw;
+    try {
+        raw = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new BoundedJsonResponseError('invalid_json', 'Response body was not valid UTF-8.');
+    }
+    try {
+        validateRawJson?.(raw);
+    }
+    catch {
+        throw new BoundedJsonResponseError('invalid_json', 'Response body did not satisfy the bounded JSON structure contract.');
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new BoundedJsonResponseError('invalid_json', 'Response body was not valid JSON.');
+    }
+}
+export async function requestJsonCapped(input, init = {}, options = {}) {
+    const timeoutMs = boundedPositiveInteger(options.timeoutMs, DEFAULT_JSON_RESPONSE_TIMEOUT_MS, MAX_JSON_RESPONSE_TIMEOUT_MS);
+    const controller = new AbortController();
+    const upstreamSignal = init.signal;
+    const forwardAbort = () => controller.abort(upstreamSignal?.reason);
+    if (upstreamSignal?.aborted)
+        forwardAbort();
+    else
+        upstreamSignal?.addEventListener('abort', forwardAbort, { once: true });
+    const timeoutReason = Object.freeze({ type: 'bounded-json-timeout' });
+    const timeout = setTimeout(() => controller.abort(timeoutReason), timeoutMs);
+    try {
+        if (controller.signal.aborted) {
+            throw new BoundedJsonResponseError('aborted', 'Request was cancelled.');
+        }
+        const fetchRequest = (options.fetchImpl ?? fetch)(input, {
+            ...init,
+            signal: controller.signal,
+        });
+        const response = await raceWithAbort(fetchRequest, controller.signal, async (lateResponse) => lateResponse.body?.cancel().catch(() => { }));
+        const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+        const plausibleJson = !contentType
+            || contentType.includes('application/json')
+            || contentType.includes('+json');
+        if (options.allowNonJsonErrorResponse !== false && !response.ok && !plausibleJson) {
+            await response.body?.cancel().catch(() => { });
+            return { response, body: null };
+        }
+        let body;
+        try {
+            body = await readJsonResponseCapped(response, options.maximumBytes, controller.signal, options.validateRawJson);
+        }
+        catch (cause) {
+            // Reverse proxies and hosting adapters can replace an upstream JSON
+            // error with a bounded HTML or plain-text response. Preserve the HTTP
+            // status so callers can apply retry and generic error handling, while
+            // continuing to require valid JSON for successful responses.
+            if (options.allowNonJsonErrorResponse !== false
+                && !response.ok
+                && cause instanceof BoundedJsonResponseError
+                && cause.code === 'invalid_json') {
+                body = null;
+            }
+            else {
+                throw cause;
+            }
+        }
+        return { response, body };
+    }
+    catch (cause) {
+        if (controller.signal.aborted) {
+            const timedOut = controller.signal.reason === timeoutReason;
+            throw new BoundedJsonResponseError(timedOut ? 'timeout' : 'aborted', timedOut ? `Request timed out after ${timeoutMs} ms.` : 'Request was cancelled.');
+        }
+        if (cause instanceof BoundedJsonResponseError)
+            throw cause;
+        throw cause;
+    }
+    finally {
+        clearTimeout(timeout);
+        upstreamSignal?.removeEventListener('abort', forwardAbort);
+    }
+}

package/lib/bounded-json.mjs

@@ -0,0 +1,249 @@
+export const MAX_BOUNDED_JSON_DEPTH = 48;
+export const MAX_BOUNDED_JSON_KEYS = 50_000;
+export const MAX_BOUNDED_JSON_VALUES = 100_000;
+export const MAX_BOUNDED_JSON_CONTAINER_ITEMS = 10_000;
+export const UNSAFE_JSON_OBJECT_KEYS = Object.freeze(['__proto__']);
+function syntaxError() {
+    throw new TypeError('Artefact input is not valid JSON.');
+}
+export function isSafeJsonObjectKey(value) {
+    return !UNSAFE_JSON_OBJECT_KEYS.includes(value);
+}
+export function assertBoundedJsonStructure(value, label = 'JSON value', limits = {}) {
+    const maximumDepth = limits.maximumDepth ?? MAX_BOUNDED_JSON_DEPTH;
+    const maximumKeys = limits.maximumKeys ?? MAX_BOUNDED_JSON_KEYS;
+    const maximumValues = limits.maximumValues ?? MAX_BOUNDED_JSON_VALUES;
+    const maximumContainerItems = limits.maximumContainerItems ?? MAX_BOUNDED_JSON_CONTAINER_ITEMS;
+    let keys = 0;
+    let values = 0;
+    const ancestors = new Set();
+    const visit = (current, depth) => {
+        values += 1;
+        if (values > maximumValues) {
+            throw new TypeError(`${label} exceeds the ${maximumValues}-value limit.`);
+        }
+        if (depth > maximumDepth) {
+            throw new TypeError(`${label} exceeds the ${maximumDepth}-level nesting limit.`);
+        }
+        if (current === null || typeof current === 'string' || typeof current === 'boolean')
+            return;
+        if (typeof current === 'number') {
+            if (!Number.isFinite(current))
+                throw new TypeError(`${label} contains a non-JSON number.`);
+            return;
+        }
+        if (typeof current !== 'object')
+            throw new TypeError(`${label} contains a non-JSON value.`);
+        if (ancestors.has(current))
+            throw new TypeError(`${label} contains a cyclic object reference.`);
+        ancestors.add(current);
+        if (Array.isArray(current)) {
+            if (current.length > maximumContainerItems) {
+                throw new TypeError(`${label} contains a container with more than ${maximumContainerItems} items.`);
+            }
+            for (const item of current)
+                visit(item, depth + 1);
+        }
+        else {
+            const entries = Object.entries(current);
+            if (entries.length > maximumContainerItems) {
+                throw new TypeError(`${label} contains a container with more than ${maximumContainerItems} items.`);
+            }
+            keys += entries.length;
+            if (keys > maximumKeys) {
+                throw new TypeError(`${label} exceeds the ${maximumKeys}-key limit.`);
+            }
+            for (const [key, item] of entries) {
+                if (!isSafeJsonObjectKey(key))
+                    throw new TypeError(`${label} contains an unsafe object key.`);
+                visit(item, depth + 1);
+            }
+        }
+        ancestors.delete(current);
+    };
+    visit(value, 0);
+}
+export function scanBoundedJson(raw, limits = {}) {
+    const maximumDepth = limits.maximumDepth ?? MAX_BOUNDED_JSON_DEPTH;
+    const maximumKeys = limits.maximumKeys ?? MAX_BOUNDED_JSON_KEYS;
+    const maximumValues = limits.maximumValues ?? MAX_BOUNDED_JSON_VALUES;
+    const maximumContainerItems = limits.maximumContainerItems ?? MAX_BOUNDED_JSON_CONTAINER_ITEMS;
+    let index = 0;
+    let keys = 0;
+    let values = 0;
+    const whitespace = () => {
+        while (index < raw.length && /[\t\n\r ]/u.test(raw[index]))
+            index += 1;
+    };
+    const stringToken = () => {
+        const start = index;
+        index += 1;
+        while (index < raw.length) {
+            const character = raw[index];
+            if (character === '"') {
+                index += 1;
+                try {
+                    return JSON.parse(raw.slice(start, index));
+                }
+                catch {
+                    syntaxError();
+                }
+            }
+            if (character === '\\') {
+                index += 1;
+                if (index >= raw.length)
+                    syntaxError();
+                if (raw[index] === 'u') {
+                    if (!/^[a-fA-F0-9]{4}$/u.test(raw.slice(index + 1, index + 5)))
+                        syntaxError();
+                    index += 5;
+                }
+                else {
+                    if (!/["\\/bfnrt]/u.test(raw[index]))
+                        syntaxError();
+                    index += 1;
+                }
+                continue;
+            }
+            if (character.charCodeAt(0) <= 0x1f)
+                syntaxError();
+            index += 1;
+        }
+        return syntaxError();
+    };
+    const literal = (token) => {
+        if (raw.slice(index, index + token.length) !== token)
+            syntaxError();
+        index += token.length;
+    };
+    const number = () => {
+        const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u.exec(raw.slice(index));
+        if (!match)
+            syntaxError();
+        if (!Number.isFinite(Number(match[0]))) {
+            throw new TypeError('Artefact JSON contains a non-finite number.');
+        }
+        index += match[0].length;
+    };
+    const value = (depth) => {
+        values += 1;
+        if (values > maximumValues) {
+            throw new TypeError(`Artefact JSON exceeds the ${maximumValues}-value limit.`);
+        }
+        if (depth > maximumDepth) {
+            throw new TypeError(`Artefact JSON exceeds the ${maximumDepth}-level nesting limit.`);
+        }
+        whitespace();
+        const character = raw[index];
+        if (character === '"') {
+            stringToken();
+            return;
+        }
+        if (character === '{') {
+            index += 1;
+            whitespace();
+            const seen = new Set();
+            if (raw[index] === '}') {
+                index += 1;
+                return;
+            }
+            while (index < raw.length) {
+                if (raw[index] !== '"')
+                    syntaxError();
+                const key = stringToken();
+                if (seen.size >= maximumContainerItems) {
+                    throw new TypeError(`Artefact JSON contains a container with more than ${maximumContainerItems} items.`);
+                }
+                keys += 1;
+                if (keys > maximumKeys) {
+                    throw new TypeError(`Artefact JSON exceeds the ${maximumKeys}-key limit.`);
+                }
+                if (seen.has(key))
+                    throw new TypeError('Artefact JSON contains a duplicate object key.');
+                if (!isSafeJsonObjectKey(key))
+                    throw new TypeError('Artefact JSON contains an unsafe object key.');
+                seen.add(key);
+                whitespace();
+                if (raw[index] !== ':')
+                    syntaxError();
+                index += 1;
+                value(depth + 1);
+                whitespace();
+                if (raw[index] === '}') {
+                    index += 1;
+                    return;
+                }
+                if (raw[index] !== ',')
+                    syntaxError();
+                index += 1;
+                whitespace();
+            }
+            syntaxError();
+        }
+        if (character === '[') {
+            index += 1;
+            whitespace();
+            if (raw[index] === ']') {
+                index += 1;
+                return;
+            }
+            let items = 0;
+            while (index < raw.length) {
+                items += 1;
+                if (items > maximumContainerItems) {
+                    throw new TypeError(`Artefact JSON contains a container with more than ${maximumContainerItems} items.`);
+                }
+                value(depth + 1);
+                whitespace();
+                if (raw[index] === ']') {
+                    index += 1;
+                    return;
+                }
+                if (raw[index] !== ',')
+                    syntaxError();
+                index += 1;
+                whitespace();
+            }
+            syntaxError();
+        }
+        if (character === 't') {
+            literal('true');
+            return;
+        }
+        if (character === 'f') {
+            literal('false');
+            return;
+        }
+        if (character === 'n') {
+            literal('null');
+            return;
+        }
+        number();
+    };
+    whitespace();
+    value(0);
+    whitespace();
+    if (index !== raw.length)
+        syntaxError();
+}
+export function parseBoundedJsonObject(raw, options) {
+    const label = options.label ?? 'Artefact input';
+    if (typeof raw !== 'string')
+        throw new TypeError(`${label} must be UTF-8 JSON text.`);
+    const bytes = new TextEncoder().encode(raw).byteLength;
+    if (bytes < 1 || bytes > options.maximumBytes) {
+        throw new TypeError(`${label} must be between 1 byte and ${options.maximumBytes} bytes.`);
+    }
+    scanBoundedJson(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        syntaxError();
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new TypeError(`${label} must contain one JSON object.`);
+    }
+    return parsed;
+}