@slicedearth/whoisleuth-cli 1.34.0 → 1.36.1

package/lib/evidence-export.mjs

@@ -1,7 +1,9 @@
 import { compareRdapPublications, compareRegistrySources } from "./registry-comparison.mjs";
 import { buildRegistryInsights } from "./registry-insights.mjs";
+import { WHOISLEUTH_SOURCE_REPOSITORY_URL } from "./project-metadata.mjs";
+import { normalizeBoundedSemanticVersion } from "./semantic-version.mjs";
 export const LOOKUP_EVIDENCE_SCHEMA = 'whoisleuth.lookup-evidence';
-export const LOOKUP_EVIDENCE_SCHEMA_VERSION = 23;
+export const LOOKUP_EVIDENCE_SCHEMA_VERSION = 24;
 const REGISTRAR_RDAP_STATUSES = new Set([
     'success', 'partial', 'error', 'unsupported', 'not_found', 'skipped', 'disabled',
 ]);
@@ -37,6 +39,14 @@ function boundedTimestamp(value) {
     const time = Date.parse(text);
     return Number.isFinite(time) ? new Date(time).toISOString() : null;
 }
+function boundedSemanticVersion(value) {
+    try {
+        return normalizeBoundedSemanticVersion(value, 'Evidence application');
+    }
+    catch {
+        return null;
+    }
+}
 function boundedEndpoint(value) {
     const text = boundedString(value, 2048);
     if (!text)
@@ -359,7 +369,7 @@ function registrarPublicationComparison(body, registryParsed) {
     });
 }
 export function buildLookupEvidence(response, options = {}) {
-    const { generatedAt = new Date().toISOString(), idnAnalysis = null } = options;
+    const { generatedAt = new Date().toISOString(), idnAnalysis = null, applicationVersion = null } = options;
     const body = recordOrNull(response) || {};
     const rdap = recordOrNull(body.rdap);
     const whois = recordOrNull(body.whois);
@@ -389,7 +399,11 @@ export function buildLookupEvidence(response, options = {}) {
         schema: LOOKUP_EVIDENCE_SCHEMA,
         schemaVersion: LOOKUP_EVIDENCE_SCHEMA_VERSION,
         generatedAt,
-        application: { name: 'WHOISleuth' },
+        application: {
+            name: 'WHOISleuth',
+            version: boundedSemanticVersion(applicationVersion),
+            projectUrl: WHOISLEUTH_SOURCE_REPOSITORY_URL,
+        },
         query: {
             submitted: body.query || null,
             type: body.type || null,

package/lib/evidence-report.mjs

@@ -89,6 +89,7 @@ function reportField(label, value, fallback = 'Not reported') {
 }
 function buildLookupEvidenceReport(document, options = {}) {
     const report = objectOrEmpty(document);
+    const application = objectOrEmpty(report.application);
     const query = objectOrEmpty(report.query);
     const diagnostics = objectOrEmpty(report.diagnostics);
     const rdapDiagnostics = objectOrEmpty(diagnostics.rdap);
@@ -300,6 +301,8 @@ function buildLookupEvidenceReport(document, options = {}) {
         notice: 'Human-readable summary. The versioned JSON export remains the full-fidelity evidence package; raw RDAP JSON and WHOIS response bodies are deliberately omitted here.',
         metadata: [
             reportField('Generated', report.generatedAt),
+            reportField('Generator', application.version ? `${application.name || 'WHOISleuth'} ${application.version}` : application.name || 'WHOISleuth'),
+            reportField('Project', application.projectUrl),
             reportField('Report contract', `${cleanReportText(report.schema)} v${cleanReportText(report.schemaVersion)}`),
         ],
         query: [

package/lib/favicon.mjs

@@ -14,14 +14,9 @@
 //            adds coverage without weakening the exact tier.
 import * as crypto from 'node:crypto';
 import { safeFetch, readBytesCapped } from "./safe-fetch.mjs";
+import { whoisleuthRequestHeaders } from "./outbound-identity.mjs";
 import { faviconPerceptualHash } from "./perceptual-hash.mjs";
-const MAX_FAVICON_BYTES = 200000; // generous for a favicon, small enough to bound memory
-const FAVICON_FETCH_TIMEOUT_MS = 5000;
-// Bounds worst-case work when a (possibly hostile) page declares many icon
-// links - we try candidates in priority order and stop at the first that
-// yields hashable bytes, so this only bites on pages where every earlier
-// candidate fails.
-const MAX_FAVICON_CANDIDATES = 4;
+import { FAVICON_FETCH_TIMEOUT_MS, MAX_FAVICON_BYTES, MAX_FAVICON_CANDIDATES, } from "./outbound-request-bounds.mjs";
 // Extracts favicon URLs declared in the page's own <link rel="...icon..."> tags
 // (resolved to absolute URLs against the page origin), in preference order:
 // standard "icon"/"shortcut icon" first, then "apple-touch-icon". Many modern
@@ -129,7 +124,7 @@ function buildFaviconCandidates(domain, html = '') {
     return candidates.slice(0, MAX_FAVICON_CANDIDATES);
 }
 async function fetchFaviconHash(domain, { html = '' } = {}) {
-    const headers = { 'User-Agent': 'Mozilla/5.0 (compatible; DomainStatusChecker/1.0)' };
+    const headers = whoisleuthRequestHeaders();
     const candidates = buildFaviconCandidates(domain, html);
     for (const url of candidates) {
         // eslint-disable-next-line no-await-in-loop

package/lib/html-signals.mjs

@@ -10,6 +10,7 @@ import { analyzeClientBehavior } from "./client-behavior-profile.mjs";
 import { createObservation } from "./observation.mjs";
 import { createPageFingerprints } from "./page-fingerprints.mjs";
 import { analyzePageRole } from "./page-role-profile.mjs";
+import { analyzeCspMetaPolicies } from "./response-policy.mjs";
 import { analyzeStaticHtml } from "./static-html-analysis.mjs";
 import { analyzeStructuredDataIdentity } from "./structured-data-identity.mjs";
 import { analyzeWebsiteTechnology } from "./website-technology.mjs";
@@ -642,6 +643,9 @@ function extractHtmlSignals(html, domain, options = {}) {
             ? pageIdentity.forms.externalActionOrigins.length > 0
             : null,
         externalAssetHosts: extractExternalAssetHosts(html, domain),
+        cspMetaPolicy: htmlAnalysis
+            ? analyzeCspMetaPolicies(htmlAnalysis.cspMetaPolicies, htmlAnalysis.cspMetaLimitReached)
+            : null,
         pageIdentity,
         credentialSurfaceProfile: includeCredentialSurfaceProfile && htmlAnalysis ? analyzeCredentialSurfaceProfile({
             htmlAnalysis,

package/lib/http-evidence-bounds.mjs

@@ -0,0 +1,4 @@
+// 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.
+export const MAX_HTTP_EVIDENCE_REDIRECTS = 5;

package/lib/http-intelligence.mjs

@@ -3,8 +3,9 @@
 // converts the shared safe-fetch trace and selected response metadata into an
 // additive evidence object suitable for API responses and exports.
 import { createObservation } from "./observation.mjs";
+import { MAX_HTTP_EVIDENCE_REDIRECTS } from "./http-evidence-bounds.mjs";
 const MAX_HTTP_PROVENANCE_URL = 2048;
-const MAX_HTTP_REDIRECTS = 5;
+const MAX_HTTP_REDIRECTS = MAX_HTTP_EVIDENCE_REDIRECTS;
 const MAX_HTTP_ATTEMPTS = 2;
 const MAX_HTTP_ERROR_LENGTH = 180;
 const MAX_HTTP_HEADER_LENGTH = 1024;

package/lib/ip-prefix.mjs

@@ -0,0 +1,54 @@
+import { isIP } from 'node:net';
+function ipv4Value(value) {
+    return value.split('.').reduce((total, part) => (total << 8n) | BigInt(Number(part)), 0n);
+}
+function ipv6Parts(value) {
+    if (value.includes('.'))
+        return null;
+    const halves = value.toLowerCase().split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] ? halves[0].split(':') : [];
+    const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    if (left.some((part) => !/^[0-9a-f]{1,4}$/u.test(part))
+        || right.some((part) => !/^[0-9a-f]{1,4}$/u.test(part)))
+        return null;
+    const missing = 8 - left.length - right.length;
+    if (halves.length === 1 && missing !== 0 || halves.length === 2 && missing < 1)
+        return null;
+    return [...left, ...Array(missing).fill('0'), ...right].map((part) => Number.parseInt(part, 16));
+}
+function ipValue(value, family) {
+    if (family === 4)
+        return ipv4Value(value);
+    const parts = ipv6Parts(value);
+    return parts?.reduce((total, part) => (total << 16n) | BigInt(part), 0n) ?? null;
+}
+function parseIpPrefix(value) {
+    if (typeof value !== 'string' || value.length > 96 || /[\s%\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const [addressValue, lengthValue, ...rest] = value.toLowerCase().split('/');
+    if (!addressValue || rest.length > 0)
+        return null;
+    const family = isIP(addressValue);
+    if (family !== 4 && family !== 6)
+        return null;
+    const maximum = family === 4 ? 32 : 128;
+    if (lengthValue !== undefined && !/^\d{1,3}$/u.test(lengthValue))
+        return null;
+    const length = lengthValue === undefined ? maximum : Number(lengthValue);
+    if (!Number.isInteger(length) || length < 0 || length > maximum)
+        return null;
+    const numeric = ipValue(addressValue, family);
+    if (numeric === null)
+        return null;
+    const full = (1n << BigInt(maximum)) - 1n;
+    const mask = length === 0 ? 0n : (full << BigInt(maximum - length)) & full;
+    return Object.freeze({ family, address: addressValue, length, value: numeric & mask, mask });
+}
+function prefixContains(container, candidate) {
+    return container.family === candidate.family
+        && container.length <= candidate.length
+        && (candidate.value & container.mask) === container.value;
+}
+export { parseIpPrefix, prefixContains };

package/lib/local-geoip-evidence.mjs

@@ -0,0 +1,89 @@
+import { isIP } from 'node:net';
+import { parseIpPrefix, prefixContains } from "./ip-prefix.mjs";
+const LOCAL_GEOIP_SCHEMA = 'whoisleuth.local-geoip-evidence';
+const LOCAL_GEOIP_VERSION = 1;
+const MAX_GEOIP_RECORDS = 100_000;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function boundedText(value, maximum) {
+    if (typeof value !== 'string' || value.length > maximum || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    return value.replace(/\s+/gu, ' ').trim() || null;
+}
+function normalizeGeoIpEntry(value) {
+    const source = record(value);
+    const parsedNetwork = parseIpPrefix(source?.network ?? source?.cidr);
+    if (!source || !parsedNetwork)
+        return null;
+    const country = boundedText(source.countryCode ?? source.country, 2)?.toUpperCase() ?? null;
+    if (country !== null && !/^[A-Z]{2}$/u.test(country))
+        return null;
+    const asnValue = source.asn === null || source.asn === undefined ? null : Number(String(source.asn).replace(/^AS/iu, ''));
+    if (asnValue !== null && (!Number.isInteger(asnValue) || asnValue < 0 || asnValue > 4_294_967_295))
+        return null;
+    return Object.freeze({
+        network: `${parsedNetwork.address}/${parsedNetwork.length}`,
+        parsedNetwork,
+        countryCode: country,
+        region: boundedText(source.region, 120),
+        city: boundedText(source.city, 120),
+        asn: asnValue,
+        asName: boundedText(source.asName ?? source.organization, 240),
+    });
+}
+function buildLocalGeoIpDatabase(value) {
+    const source = record(value);
+    const sourceLabel = boundedText(source?.sourceLabel, 120);
+    const databaseVersion = boundedText(source?.databaseVersion, 80);
+    const license = boundedText(source?.license, 240);
+    const rows = Array.isArray(source?.records) ? source.records : null;
+    if (!sourceLabel || !databaseVersion || !license || !rows) {
+        throw new TypeError('A local GeoIP database requires bounded source, version, licence, and record fields.');
+    }
+    const truncated = rows.length > MAX_GEOIP_RECORDS;
+    const normalized = rows.slice(0, MAX_GEOIP_RECORDS).map(normalizeGeoIpEntry);
+    const records = normalized.filter((item) => item !== null)
+        .sort((left, right) => right.parsedNetwork.length - left.parsedNetwork.length);
+    return Object.freeze({
+        sourceLabel,
+        databaseVersion,
+        license,
+        records: Object.freeze(records),
+        rejectedCount: normalized.length - records.length + Math.max(0, rows.length - MAX_GEOIP_RECORDS),
+        truncated,
+    });
+}
+function lookupLocalGeoIp(database, address) {
+    const normalized = typeof address === 'string' ? address.trim().toLowerCase() : '';
+    const family = isIP(normalized);
+    const target = family === 4 || family === 6 ? parseIpPrefix(normalized) : null;
+    if (!target) {
+        return Object.freeze({ state: 'invalid', address: null, match: null, source: null, limitations: Object.freeze([]) });
+    }
+    const match = database.records.find((item) => prefixContains(item.parsedNetwork, target)) ?? null;
+    return Object.freeze({
+        state: match ? database.truncated || database.rejectedCount > 0 ? 'partial' : 'matched' : 'not_found',
+        address: normalized,
+        match: match ? Object.freeze({
+            network: match.network,
+            countryCode: match.countryCode,
+            region: match.region,
+            city: match.city,
+            asn: match.asn,
+            asName: match.asName,
+        }) : null,
+        source: Object.freeze({
+            label: database.sourceLabel,
+            version: database.databaseVersion,
+            license: database.license,
+        }),
+        limitations: Object.freeze([
+            'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
+            'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
+        ]),
+    });
+}
+export { LOCAL_GEOIP_SCHEMA, LOCAL_GEOIP_VERSION, MAX_GEOIP_RECORDS, buildLocalGeoIpDatabase, lookupLocalGeoIp, };

package/lib/outbound-identity.mjs

@@ -0,0 +1,9 @@
+import packageDocument from '../package.json' with { type: 'json' };
+import { WHOISLEUTH_PROJECT_URL, WHOISLEUTH_REQUEST_POLICY_URL, } from "./project-metadata.mjs";
+import { normalizeBoundedSemanticVersion } from "./semantic-version.mjs";
+export { WHOISLEUTH_PROJECT_URL, WHOISLEUTH_REQUEST_POLICY_URL };
+export const WHOISLEUTH_USER_AGENT_VERSION = normalizeBoundedSemanticVersion(packageDocument.version, 'Application manifest');
+export const WHOISLEUTH_USER_AGENT = `WHOISleuth/${WHOISLEUTH_USER_AGENT_VERSION} (+${WHOISLEUTH_REQUEST_POLICY_URL})`;
+export function whoisleuthRequestHeaders(headers = {}) {
+    return { ...headers, 'User-Agent': WHOISLEUTH_USER_AGENT };
+}

package/lib/outbound-request-bounds.mjs

@@ -0,0 +1,9 @@
+// Shared declarative limits for direct website observation. Runtime collectors
+// and the public request-policy page import these values so operator-facing
+// disclosures cannot drift from the enforced request boundaries.
+export const MAX_OUTBOUND_REDIRECTS = 5;
+export const HOMEPAGE_FETCH_TIMEOUT_MS = 6_000;
+export const MAX_HOMEPAGE_BYTES = 300_000;
+export const FAVICON_FETCH_TIMEOUT_MS = 5_000;
+export const MAX_FAVICON_BYTES = 200_000;
+export const MAX_FAVICON_CANDIDATES = 4;

package/lib/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/lib/perceptual-hash.mjs

@@ -21,6 +21,7 @@
 // case, while staying cheap (no DCT). Output is 16 lowercase hex chars;
 // similarity is the Hamming distance between two such strings.
 import * as zlib from 'node:zlib';
+import { hammingDistanceHex, isInformativePerceptualHash, } from "./perceptual-hash-comparison.mjs";
 // Bound the decode work on attacker-controlled image bytes. Real favicons top
 // out around 256x256; anything claiming to be larger is refused rather than
 // decoded (it would also never be a legitimate favicon to compare against).
@@ -371,21 +372,11 @@ function grayscaleGrid(image, cols, rows) {
 // (callers fall back to the exact hash) rather than a collision-prone one.
 // isInformativeHash re-checks this at comparison time too, since a Brand
 // Profile saved before this guard existed may already hold a degenerate hash.
-const MIN_INFORMATIVE_BITS = 10;
-function popcountHex(hex) {
-    let bits = 0;
-    for (let i = 0; i < hex.length; i += 1)
-        bits += POPCOUNT[parseInt(hex.charAt(i), 16)] ?? 0;
-    return bits;
-}
 function isInformativeHash(hex) {
-    if (typeof hex !== 'string' || !HEX_HASH_RE.test(hex))
-        return false;
-    const bits = popcountHex(hex);
-    return bits >= MIN_INFORMATIVE_BITS && bits <= 64 - MIN_INFORMATIVE_BITS;
+    return isInformativePerceptualHash(hex);
 }
 // 64-bit dHash over a 9x8 grid -> 16 hex chars, or null when the resulting
-// hash is degenerate (see MIN_INFORMATIVE_BITS). Each row contributes 8 bits:
+// hash is degenerate (see the shared comparison contract). Each row contributes 8 bits:
 // bit set when a cell is brighter than its right-hand neighbour.
 function dHash(image) {
     const cols = 9;
@@ -429,23 +420,4 @@ function faviconPerceptualHash(buf) {
 // produced by the optional local capture package. Keep the generic name as an
 // alias so the evidence contract does not imply that a screenshot is a favicon.
 const imagePerceptualHash = faviconPerceptualHash;
-const HEX_HASH_RE = /^[0-9a-f]{16}$/;
-const POPCOUNT = new Uint8Array(16);
-for (let i = 0; i < 16; i += 1)
-    POPCOUNT[i] = (i & 1) + ((i >> 1) & 1) + ((i >> 2) & 1) + ((i >> 3) & 1);
-/**
- * Hamming distance (0-64) between two 16-hex dHash strings, or null if either
- * isn't a well-formed hash. Smaller = more visually similar.
- */
-function hammingDistanceHex(a, b) {
-    if (typeof a !== 'string' || typeof b !== 'string')
-        return null;
-    if (!HEX_HASH_RE.test(a) || !HEX_HASH_RE.test(b))
-        return null;
-    let distance = 0;
-    for (let i = 0; i < 16; i += 1) {
-        distance += POPCOUNT[parseInt(a.charAt(i), 16) ^ parseInt(b.charAt(i), 16)] ?? 0;
-    }
-    return distance;
-}
 export { faviconPerceptualHash, hammingDistanceHex, imagePerceptualHash };

package/lib/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://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/lib/provider-policy-admission.mjs

@@ -0,0 +1,49 @@
+export const PROVIDER_POLICY_MAX_REVIEW_AGE_DAYS = 180;
+export const DEPLOYMENT_PURPOSES = ['personal', 'internal', 'commercial'];
+function deploymentPurpose(value) {
+    const normalized = String(value ?? '').trim().toLowerCase();
+    return DEPLOYMENT_PURPOSES.includes(normalized)
+        ? normalized
+        : null;
+}
+export function providerPolicyAdmission(terms, env = process.env, now = Date.now()) {
+    const source = env && typeof env === 'object' ? env : {};
+    const purpose = deploymentPurpose(source.WHOISLEUTH_DEPLOYMENT_PURPOSE);
+    const reviewedAt = Date.parse(terms.reviewedAt);
+    const reviewAgeDays = Number.isFinite(reviewedAt)
+        ? Math.max(0, Math.floor((now - reviewedAt) / 86_400_000))
+        : null;
+    if (!purpose) {
+        return {
+            allowed: false,
+            purpose: null,
+            reviewAgeDays,
+            reason: 'Optional intelligence requires WHOISLEUTH_DEPLOYMENT_PURPOSE=personal, internal, or commercial.',
+        };
+    }
+    if (reviewAgeDays === null || reviewAgeDays > PROVIDER_POLICY_MAX_REVIEW_AGE_DAYS) {
+        return {
+            allowed: false,
+            purpose,
+            reviewAgeDays,
+            reason: `Optional intelligence provider policy review is older than ${PROVIDER_POLICY_MAX_REVIEW_AGE_DAYS} days or invalid.`,
+        };
+    }
+    if (terms.commercialUse === 'unknown') {
+        return {
+            allowed: false,
+            purpose,
+            reviewAgeDays,
+            reason: 'Optional intelligence commercial-use permission is unknown.',
+        };
+    }
+    if (terms.commercialUse === 'restricted' && purpose !== 'personal') {
+        return {
+            allowed: false,
+            purpose,
+            reviewAgeDays,
+            reason: `Optional intelligence is classified as restricted for the declared ${purpose} deployment purpose.`,
+        };
+    }
+    return { allowed: true, purpose, reviewAgeDays, reason: null };
+}

package/lib/rdap-search-workbench.mjs

@@ -0,0 +1,157 @@
+const RDAP_SEARCH_WORKBENCH_SCHEMA = 'whoisleuth.rdap-search-workbench';
+const RDAP_SEARCH_WORKBENCH_VERSION = 1;
+const MAX_HELP_ENTRIES = 64;
+const MAX_QUERY_VALUE_LENGTH = 254;
+const SEARCHABLE_RESOURCE_TYPES = new Set(['domains', 'nameservers', 'entities', 'ips', 'autnums']);
+const RELATED_RESOURCE_TYPES = new Set(['domains', 'nameservers', 'entities', 'ips', 'autnums']);
+const RECOGNIZED_PROPERTIES = new Set(['handle', 'fn', 'email', 'role']);
+const SENSITIVE_PROPERTIES = new Set(['fn', 'email']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function boundedToken(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim().toLowerCase();
+    if (!normalized || normalized.length > 48 || !/^[a-z][a-z0-9_-]*$/u.test(normalized))
+        return null;
+    return normalized;
+}
+function declarationKey(value) {
+    return `${value.searchableResourceType}:${value.relatedResourceType}:${value.property}`;
+}
+function emptySummary(state, limitation, rejectedCount = 0) {
+    return Object.freeze({
+        schema: RDAP_SEARCH_WORKBENCH_SCHEMA,
+        version: RDAP_SEARCH_WORKBENCH_VERSION,
+        state,
+        capabilities: Object.freeze([]),
+        rejectedCount,
+        truncated: false,
+        limitations: Object.freeze([limitation]),
+    });
+}
+function normalizeRdapSearchHelp(value) {
+    const document = record(value);
+    if (!document)
+        return emptySummary('invalid', 'The RDAP help response was not an object.');
+    const raw = document.reverse_search_properties;
+    if (raw === undefined) {
+        return emptySummary('unsupported', 'The help response did not advertise reverse-search properties.');
+    }
+    if (!Array.isArray(raw)) {
+        return emptySummary('invalid', 'The advertised reverse-search properties were malformed.', 1);
+    }
+    const capabilities = [];
+    const seen = new Set();
+    let rejectedCount = 0;
+    const truncated = raw.length > MAX_HELP_ENTRIES;
+    for (const entry of raw.slice(0, MAX_HELP_ENTRIES)) {
+        const candidate = record(entry);
+        const searchableResourceType = boundedToken(candidate?.searchableResourceType);
+        const relatedResourceType = boundedToken(candidate?.relatedResourceType);
+        const property = boundedToken(candidate?.property);
+        if (!searchableResourceType || !relatedResourceType || !property) {
+            rejectedCount += 1;
+            continue;
+        }
+        const declaration = { searchableResourceType, relatedResourceType, property };
+        const key = declarationKey(declaration);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const supported = SEARCHABLE_RESOURCE_TYPES.has(searchableResourceType)
+            && RELATED_RESOURCE_TYPES.has(relatedResourceType)
+            && RECOGNIZED_PROPERTIES.has(property);
+        capabilities.push(Object.freeze({
+            ...declaration,
+            state: supported ? 'supported' : 'unsupported',
+            disclosure: SENSITIVE_PROPERTIES.has(property) ? 'contact' : 'identifier',
+            limitation: supported ? null : 'The server advertised a tuple that this release does not construct.',
+        }));
+    }
+    if (truncated)
+        rejectedCount += raw.length - MAX_HELP_ENTRIES;
+    const supportedCount = capabilities.filter((entry) => entry.state === 'supported').length;
+    const limitations = [];
+    if (truncated)
+        limitations.push(`Only the first ${MAX_HELP_ENTRIES} advertised properties were reviewed.`);
+    if (rejectedCount > 0)
+        limitations.push(`${rejectedCount} malformed or excess properties were not used.`);
+    if (capabilities.some((entry) => entry.state === 'unsupported')) {
+        limitations.push('Unrecognized advertised tuples remain visible but cannot be planned by this release.');
+    }
+    if (supportedCount === 0)
+        limitations.push('No supported reverse-search tuple was advertised.');
+    return Object.freeze({
+        schema: RDAP_SEARCH_WORKBENCH_SCHEMA,
+        version: RDAP_SEARCH_WORKBENCH_VERSION,
+        state: supportedCount === 0 ? 'unsupported' : limitations.length > 0 ? 'partial' : 'supported',
+        capabilities: Object.freeze(capabilities),
+        rejectedCount,
+        truncated,
+        limitations: Object.freeze(limitations),
+    });
+}
+function normalizeQueryValue(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    if (!normalized || normalized.length > MAX_QUERY_VALUE_LENGTH)
+        return null;
+    if (/[\x00-\x1f\x7f]/u.test(normalized))
+        return null;
+    return normalized;
+}
+function planRdapReverseSearch(help, requested) {
+    const searchableResourceType = boundedToken(requested.searchableResourceType);
+    const relatedResourceType = boundedToken(requested.relatedResourceType);
+    const property = boundedToken(requested.property);
+    const value = normalizeQueryValue(requested.value);
+    if (!searchableResourceType || !relatedResourceType || !property || !value) {
+        return Object.freeze({
+            schema: RDAP_SEARCH_WORKBENCH_SCHEMA,
+            version: RDAP_SEARCH_WORKBENCH_VERSION,
+            state: 'invalid',
+            requestPath: null,
+            query: null,
+            disclosure: null,
+            limitation: 'The requested resource types, property, or value were invalid or outside the supported bounds.',
+        });
+    }
+    const capability = help.capabilities.find((entry) => (entry.state === 'supported'
+        && entry.searchableResourceType === searchableResourceType
+        && entry.relatedResourceType === relatedResourceType
+        && entry.property === property));
+    if (!capability) {
+        return Object.freeze({
+            schema: RDAP_SEARCH_WORKBENCH_SCHEMA,
+            version: RDAP_SEARCH_WORKBENCH_VERSION,
+            state: 'unsupported',
+            requestPath: null,
+            query: null,
+            disclosure: null,
+            limitation: 'The supplied help response did not advertise this exact reverse-search tuple.',
+        });
+    }
+    const parameter = `${relatedResourceType}_${property}`;
+    const contactDisclosure = capability.disclosure === 'contact';
+    return Object.freeze({
+        schema: RDAP_SEARCH_WORKBENCH_SCHEMA,
+        version: RDAP_SEARCH_WORKBENCH_VERSION,
+        state: 'ready',
+        requestPath: `/${searchableResourceType}`,
+        query: Object.freeze({ [parameter]: value }),
+        disclosure: Object.freeze({
+            class: capability.disclosure,
+            summary: contactDisclosure
+                ? `Would disclose the supplied ${property} contact value to the selected RDAP server.`
+                : `Would disclose the supplied ${property} identifier to the selected RDAP server.`,
+            requiresApproval: true,
+        }),
+        limitation: 'This is an offline request plan. It neither sends the query nor establishes result authority, completeness, or currentness.',
+    });
+}
+export { MAX_HELP_ENTRIES, MAX_QUERY_VALUE_LENGTH, RDAP_SEARCH_WORKBENCH_SCHEMA, RDAP_SEARCH_WORKBENCH_VERSION, normalizeRdapSearchHelp, planRdapReverseSearch, };

package/lib/rdap.mjs

@@ -4,11 +4,16 @@ import { fetchRdapFromBasesWithParser, fetchRdapRecordWithParser, } from "./rdap
 import { normalizeRdapEvents, parseRdap, summarizeLifecycle, } from "./rdap-normalization.mjs";
 import { fetchRegistrarRdapRecordWithParser, selectRegistrarRdapLink, } from "./rdap-registrar.mjs";
 import { fetchRdapWithTimeout, } from "./rdap-transport.mjs";
+import { registryServiceAdmissionFor } from "./registry-capabilities.mjs";
 async function fetchRdapFromBases(type, value, bases, fetchUpstream = fetchRdapWithTimeout) {
     return fetchRdapFromBasesWithParser(type, value, bases, parseRdap, fetchUpstream);
 }
-async function fetchRdapRecord(type, value) {
-    return fetchRdapRecordWithParser(type, value, parseRdap);
+async function fetchRdapRecord(type, value, options = {}) {
+    if (type === 'domain' && registryServiceAdmissionFor(value, 'rdap')?.allowed === false) {
+        return null;
+    }
+    const fetchRecord = options.fetchRecord ?? fetchRdapRecordWithParser;
+    return fetchRecord(type, value, parseRdap);
 }
 async function fetchRegistrarRdapRecord(domain, registryRecord, options = {}) {
     return fetchRegistrarRdapRecordWithParser(domain, registryRecord, parseRdap, options);