@slicedearth/whoisleuth-cli 1.32.2 → 1.36.1

package/docs/cli.md

@@ -8,7 +8,9 @@ hosted WHOISleuth deployment.
 source location. It groups commands by investigation, discovery, saved-evidence,
 integrity, and calibration workflows. `whoisleuth <command> --help` displays the
 command's purpose, focused invocation, example, and collection boundary without
-printing the full command list. Packaged copies include `LICENSE`, `NOTICE`, and
+printing the full command list. `whoisleuth commands --json` exposes those same
+contracts as a stable local catalogue for wrappers and terminal tooling.
+Packaged copies include `LICENSE`, `NOTICE`, and
 `TRADEMARKS.md` alongside the CLI documentation.
 
 ## Installation
@@ -17,11 +19,18 @@ Public releases require Node.js 24 or later and install the `whoisleuth`
 command:
 
 ```bash
-npm exec --yes --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
-npm install --global @slicedearth/whoisleuth-cli
+npm exec --yes --ignore-scripts --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
+npm install --global --ignore-scripts @slicedearth/whoisleuth-cli
 whoisleuth doctor
 ```
 
+Update and verify an existing global installation with:
+
+```bash
+npm install --global --ignore-scripts @slicedearth/whoisleuth-cli@latest
+whoisleuth --version
+```
+
 The scoped package and application share one semantic version. The package runs
 locally and does not call the hosted WHOISleuth deployment. Networked commands
 contact only the sources described by their collection profile; offline review,
@@ -34,6 +43,7 @@ node bin/whoisleuth.mts lookup example.com
 node bin/whoisleuth.mts lookup AS13335 --json
 printf 'example.com\n' | node bin/whoisleuth.mts lookup --json
 node bin/whoisleuth.mts lookup example.com --deep
+node bin/whoisleuth.mts lookup example.com --deep --plan --json
 node bin/whoisleuth.mts lookup example.com --deep --summary
 node bin/whoisleuth.mts lookup example.com --deep --verbose
 node bin/whoisleuth.mts lookup example.com --deep --markdown --output lookup.md
@@ -41,6 +51,7 @@ node bin/whoisleuth.mts lookup example.com --deep --json --strict-exit --events
 cat domains.txt | node bin/whoisleuth.mts bulk --jsonl
 node bin/whoisleuth.mts bulk domains.txt --csv --registered-only
 node bin/whoisleuth.mts bulk domains.txt --domains --inconclusive-only
+node bin/whoisleuth.mts bulk domains.txt --queries --errors-only
 node bin/whoisleuth.mts bulk domains.txt --concurrency 4
 node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json
 node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json --resume
@@ -55,6 +66,7 @@ node bin/whoisleuth.mts tls example.com --json
 node bin/whoisleuth.mts registry-support example.uk --json
 node bin/whoisleuth.mts risk-calibrate calibration.json --json
 node bin/whoisleuth.mts verify-artifact workspace.json --json
+node bin/whoisleuth.mts verify-artifact lookup.json --json
 node bin/whoisleuth.mts verify-artifact workspace-encrypted.json --passphrase-file passphrase.txt --json
 node bin/whoisleuth.mts source-report lookup.json --json
 node bin/whoisleuth.mts inspect-archive workspace.json --json
@@ -65,13 +77,19 @@ node bin/whoisleuth.mts lookup example.com --deep --json > lookup.json
 node bin/whoisleuth.mts compare lookup.json --json
 node bin/whoisleuth.mts page-compare official.json candidate.json --json
 node bin/whoisleuth.mts mail-review bulk.json --json
+node bin/whoisleuth.mts review-evidence dnssec-evidence.json --json
+node bin/whoisleuth.mts domain-control domain-control-input.json --json
+node bin/whoisleuth.mts workflow-plan domain-triage example.test --json
 node bin/whoisleuth.mts diff first-lookup.json second-lookup.json --json
+node bin/whoisleuth.mts timeline first-observation.json second-observation.json latest-observation.json --json
 node bin/whoisleuth.mts export lookup.json > evidence.json
 node bin/whoisleuth.mts export lookup.json --markdown > evidence.md
 node bin/whoisleuth.mts export lookup.json --html > evidence.html
 node bin/whoisleuth.mts doctor
 node bin/whoisleuth.mts doctor --network --json
+node bin/whoisleuth.mts commands --json
 node bin/whoisleuth.mts completion zsh
+node bin/whoisleuth.mts completion powershell
 node bin/whoisleuth.mts manual | man -l -
 ```
 
@@ -87,10 +105,13 @@ npm run cli:package:check
 
 The check includes only the executable, reachable TypeScript modules, CLI
 guide, licence, notices, and trademark terms. It excludes application routes,
-deployment adapters, tests, and development tools. Its generated manifest stays
-private. Release-candidate assembly is a separate explicit operation and never
-publishes from a developer checkout. Use the scoped package name; an unqualified
-`npx whoisleuth` is not this project.
+deployment adapters, tests, and development tools. Direct runtime dependencies
+are pinned to the exact versions exercised by the reviewed repository lockfile.
+The package and its dependencies require no lifecycle scripts, so the install
+examples disable them explicitly.
+Its generated manifest stays private. Release-candidate assembly is a separate
+explicit operation and never publishes from a developer checkout. Use the
+scoped package name; an unqualified `npx whoisleuth` is not this project.
 
 Lookup defaults to the conservative fast profile. `--deep` must be requested
 explicitly and can add bounded WHOIS, DNS, website, TLS, registrar RDAP, and
@@ -104,6 +125,14 @@ up to five normalized PTR names; JSON retains up to eight. PTR names are
 operator-published routing context, not proof of hosting control or ownership.
 Fast lookups do not run this query.
 
+`lookup --plan` performs classification and prints a versioned preflight without
+starting collection. It lists the normalized target, selected fast or deep
+mode, planned source families, conditional operations, and the data each family
+may receive. The plan cannot predict live feature configuration, cache state,
+redirects, referrals, source availability, or an exact request count. It can be
+combined with `--json`, but not with report, detail, strict-exit, progress-event,
+or quiet options.
+
 Only one query is accepted by `lookup`. Multiple-input processing belongs to
 the explicit `bulk` command rather than being silently inferred by `lookup`.
 Standard input is capped at 4 KiB and must contain one non-empty line.
@@ -114,32 +143,49 @@ request. Its output is described below.
 
 `doctor` is offline by default. It checks the Node runtime, platform, terminal
 capabilities, and availability of offline command families. `doctor --network`
-adds bounded public-DNS and WHOIS port 43 checks against fixed diagnostic
-infrastructure. It retains only state and a bounded explanation, not resolved
-addresses or response content. A failed optional network check returns the
-partial-failure exit code rather than claiming that all CLI collection is
-unavailable.
-
-`completion bash`, `completion zsh`, and `completion fish` print static shell
-completion scripts to stdout. The command does not edit a shell profile or make
-a network request. Review the generated script before sourcing it or placing it
-in the relevant shell completion directory. `manual` prints a generated roff
-manual page and likewise changes no local configuration.
+adds independent bounded public-DNS, HTTPS/RDAP bootstrap, and WHOIS port 43
+checks against fixed IANA diagnostic infrastructure. The three probes run
+within the same per-probe ceiling so one stalled transport does not block the
+others. The report retains only state, HTTP status, and a bounded explanation,
+not resolved addresses or response content. A failed optional network check
+returns the partial-failure exit code rather than claiming that all CLI
+collection is unavailable.
+
+`completion bash`, `completion zsh`, `completion fish`, and `completion
+powershell` print static shell completion scripts to stdout. The command does
+not edit a shell profile or make a network request. Review the generated script
+before sourcing it or placing it in the relevant shell completion directory.
+`manual` prints a generated roff manual page and likewise changes no local
+configuration.
+
+`commands` prints the installed command catalogue without running collection or
+reading evidence. `commands --json` emits version 1 of the
+`whoisleuth.cli.command-catalogue` schema, including each command's usage,
+example, declared collection mode, collection scope, and boundary. This is the
+supported discovery contract for local wrappers; it is not a permission grant
+or a substitute for focused help.
+
+Focused command help and the generated manual classify every operation as
+offline or networked and state the relevant target, input, and concurrency
+ceiling. These labels describe observable behavior rather than granting
+authorization. The packaged `DISCLOSURE` defines the intended defensive scope;
+operators remain responsible for law, provider terms, and authorization.
 
 ## Deployment boundary
 
-The CLI is a local repository tool. The serverless deployment publishes only
-`frontend/build` and packages functions only from `netlify/functions`, so
-`bin/` and `cli/` are not part of the hosted static site or function bundle.
-Both the application root and the assembled CLI package remain private and are
-not published to the public npm registry.
+The CLI runs locally. The serverless deployment publishes only `frontend/build`
+and packages functions only from `netlify/functions`, so `bin/` and `cli/` are
+not part of the hosted static site or function bundle. The application root and
+ordinary package-check candidate remain private. Explicitly reviewed CLI
+release candidates can be published under the scoped public package described
+in the installation section.
 
 Commands that query RDAP, WHOIS, DNS, HTTP, TLS, or Certificate Transparency do
 so directly from the machine running the CLI. They do not use the hosted login,
 hosted session, or deployment usage controls; upstream providers can see and
 rate-limit the local machine's network address. Offline `discover`, `compare`,
-`page-compare`, `mail-review`, `diff`, `risk-calibrate`, `verify-artifact`, `source-report`, `export`,
-`completion`, and `manual` operations make no network requests. Commands write
+`page-compare`, `mail-review`, `review-evidence`, `domain-control`, `workflow-plan`, `diff`, `timeline`, `risk-calibrate`, `verify-artifact`, `source-report`, `export`,
+`commands`, `completion`, and `manual` operations make no network requests. Commands write
 to stdout unless the analyst deliberately selects a local output file.
 
 ## Output
@@ -266,6 +312,15 @@ registration, DNS, page identity, mail, certificate, and relationship fields,
 keeps missing and unavailable evidence distinct, and makes no ownership or
 maliciousness inference. The output records both original observation times.
 
+`timeline <observation.json> <observation.json> [...]` accepts from 2 to 20
+saved Lookup documents for one domain, orders them by their validated
+observation times, and compares each adjacent pair offline. The 32 MiB aggregate
+input ceiling is enforced while files are read and again by the timeline
+builder. Output retains normalized field states and observation times but no
+input filenames or raw registry payloads. A difference can reflect a domain
+change or changed collection conditions, so the command makes no current-state,
+ownership, intent, safety, or maliciousness conclusion.
+
 When diagnostics version 5, 6, 7, or 8 reports a documented registry collection
 constraint, terminal output also shows the suffix, WHOIS and RDAP access
 profiles, and the bounded limitation. This is static access-policy context: it
@@ -286,7 +341,7 @@ machine access is not evidence that a domain is unregistered or safe.
 This release supports `lookup`, `bulk`, `ct-search`, `discover`, `discover-scan`, `posture`,
 `http`, `tls`, `registry-support`, `risk-calibrate`, `verify-artifact`,
 `inspect-archive`, `sign-artifact`, `verify-signature`, `source-report`,
-`compare`, `page-compare`, `mail-review`, `diff`, `export`, `doctor`, `completion`, and `manual`. Additional command families
+`compare`, `page-compare`, `mail-review`, `review-evidence`, `domain-control`, `workflow-plan`, `diff`, `timeline`, `export`, `doctor`, `commands`, `completion`, and `manual`. Additional command families
 are added as separate bounded increments rather than exposing incomplete
 aliases.
 
@@ -296,13 +351,13 @@ aliases.
 catalogue for one domain or suffix. It distinguishes an explicit
 fixture-backed or access-documented suffix profile from the generic IANA
 discovery profile and reports the RDAP and WHOIS discovery/access paths,
-WHOIS query and parser profiles, any bounded fallback, fixture scenarios,
+WHOIS query and parser profiles, fixture scenarios,
 verification references, documentation references, and the catalogue's
 limitation. The same document includes a dated, official-source aggregate of
 generic, generic-restricted, sponsored, and infrastructure RDAP coverage. That
 snapshot is separate from the suffix profile and from live reachability.
 
-Terminal output is bounded and control-safe. `--json` emits version 2 of the
+Terminal output is bounded and control-safe. `--json` emits version 3 of the
 `whoisleuth.cli.registry-support` schema. Unknown but syntactically valid
 suffixes retain the generic `discovery_only` profile; malformed input exits
 with code 2. The command never probes a registry or tests current reachability.
@@ -385,7 +440,11 @@ Risk model.
 evidence contents. Input is capped at 15 MiB. It currently recognises ordinary
 and encrypted workspace archives, case-response packets, acquisition-decision
 exports, domain-comparison exports, Bulk mail-exposure exports, and Bulk review
-manifests.
+manifests. It also validates the bounded versioned structure of saved CLI
+Lookup JSON. Because saved Lookup documents do not embed a checksum or
+signature, that result is reported as `structure_valid` with content integrity
+explicitly unchecked. Saved Lookup validation retains its stricter 8 MiB
+document ceiling.
 
 For an ordinary workspace archive, the command validates the versioned
 structure, section byte counts, record counts, and per-section checksums. For a
@@ -469,19 +528,25 @@ deep mode.
 
 Bulk uses the shared compact lookup response, so it does not retain raw RDAP
 objects or WHOIS response bodies. `--json` returns one bounded collection;
-`--jsonl` emits one self-contained versioned item per line. Version 2 adds a
+`--jsonl` emits one self-contained versioned item per line. `--domains` emits
+only successfully normalized domain names, while `--queries` preserves the
+selected bounded input queries and is suitable for an exact retry queue.
+Version 2 adds a
 bounded `dnsSummary` projection for observed A, AAAA, NS, and MX records plus
 null MX, SPF, and DMARC state. `--csv` writes fixed columns for automation,
-including the DNS summaries and explicit outcome; `--domains` writes only the
-normalized retained domain names for a subsequent command.
-
-`--registered-only` and `--inconclusive-only` are mutually exclusive output
-filters. The first retains registered, for-sale, and expiring authority-aware
-states. The second retains unknown authority states and failed rows. Filtering
-does not change collection and never converts an unavailable or failed source
-into an unregistered result. Machine documents record collected and emitted
-counts. A mixture of successful and failed queries exits with code 4 while
-preserving every collected result before output filtering.
+including the DNS summaries and explicit outcome.
+
+`--registered-only`, `--inconclusive-only`, and `--errors-only` are mutually
+exclusive output filters. The first retains registered, for-sale, and expiring
+authority-aware states. The second retains unknown authority states and failed
+rows. The third retains only rows whose lookup operation failed, which is useful
+for producing an exact retry queue without treating an inconclusive successful
+lookup as an operational error. Filtering does not change collection and never
+converts an unavailable or failed source into an unregistered result. Machine
+documents record collected and emitted counts. A mixture of successful and
+failed queries exits with code 4 while preserving every collected result before
+output filtering. For example, `bulk domains.txt --queries --errors-only`
+produces only the exact failed inputs while retaining the partial-failure exit.
 
 ## Certificate Transparency search
 
@@ -492,11 +557,15 @@ does not call the hosted WHOISleuth deployment. Quote a multi-word keyword so
 the shell passes it as one argument.
 
 Terminal output summarizes certificate rows, observed hostnames, canonical
-registrable-domain matches, observation times, and completeness. It shows at
-most 100 matches and five hostnames per match, with explicit omission notes.
-`--json` returns the complete bounded structured result in the versioned
-`whoisleuth.cli.ct-search` schema. CT observations do not prove that a website
-is active or malicious.
+registrable-domain matches, observation times, bounded certificate-issuance
+groups, and completeness. An issuance group contains names observed together
+in one public certificate record; a cross-domain group is a review lead, not
+an attribution or ownership finding. Terminal output shows at most 100 matches
+and five hostnames per match, with explicit omission notes. `--json` returns
+the complete bounded structured result in the versioned
+`whoisleuth.cli.ct-search` schema. The certificate-group cap is reported
+separately from the registrable-domain result cap. CT observations do not prove
+that a website is active or malicious.
 
 ## Lookalike discovery
 
@@ -729,6 +798,92 @@ The command makes no DNS or SMTP request and retains no source path. It does
 not test message acceptance, relay behavior, mailbox existence, catch-all
 behavior, SMTP banners, or whether a mail server is rogue, safe, or malicious.
 
+An analyst may add a bounded `tlsaEvidence` object to a version-2 Bulk item for
+offline DANE review. It must name the exact `_25._tcp.<mx-host>` service, and
+that host must occur in the same item's retained MX evidence. A certificate
+association match is complete only when `dnssecState` is `validated`. TLSA
+usages 0 and 1 additionally require `pkixValidationState: "validated"`.
+Usages 0 and 2 compare against the bounded `authorityMaterials` array; usages
+1 and 3 compare against the supplied leaf certificate or SPKI. Mismatched
+service names, missing certificate roles, unvalidated prerequisites, malformed
+material, and truncation remain invalid, partial, or untrusted rather than
+becoming a DANE match.
+
+## Offline supplied-evidence review
+
+`review-evidence [evidence.json]` accepts one version-1 JSON input and performs
+only deterministic local parsing, comparison, or request planning. Input is
+capped at 16 MiB. The command never retrieves DNS, opens SMTP, contacts an
+RDAP server, submits a resolver query, or looks up an address in a hosted
+GeoIP service.
+
+Supported input schemas are:
+
+- `whoisleuth.dnssec-evidence-input`: compares bounded DS and DNSKEY records,
+  recalculates DNSKEY key tags and supported DS digests, and reviews supplied
+  RRSIG validity windows at `observedAt`. `consistent` describes only the
+  supplied DS/DNSKEY relationship. It does not authenticate a chain to a root
+  trust anchor, validate RRSIG cryptography, or prove that a missing record is
+  absent.
+- `whoisleuth.tlsa-evidence-input`: binds TLSA records to one explicit
+  `_port._transport.hostname` service and compares supplied leaf or authority
+  certificate/SPKI bytes. `matched` requires independently validated DNSSEC;
+  PKIX-TA and PKIX-EE usages also require an independently validated PKIX path.
+  The command does not retrieve the certificate or negotiate STARTTLS.
+- `whoisleuth.rdap-search-input`: normalizes a supplied RDAP search-help
+  response and prepares an exact supported reverse-search request without
+  sending it.
+- `whoisleuth.rpki-route-input`: compares a route prefix and origin ASN with a
+  bounded analyst-supplied VRP set.
+- `whoisleuth.local-geoip-query`: queries an analyst-supplied bounded prefix
+  database whose source, version, and licence metadata remain in the result.
+- `whoisleuth.encrypted-dns-plan-input`: validates an explicitly reviewed
+  encrypted-DNS provider contract and prepares a bounded query plan. It does
+  not execute the plan.
+
+The common output is `whoisleuth.cli.offline-evidence-review` version 1. It
+retains the nested result's explicit state and limitations. A locally
+consistent relationship is not converted into a claim about current
+publication, ownership, safety, or maliciousness.
+
+## Domain control manifests
+
+`domain-control [input.json]` builds or reviews a bounded desired-state
+manifest without making a request or changing configuration. A manifest input
+uses `whoisleuth.domain-control-manifest-input` version 1, includes an expiry,
+and may record expected nameservers, DS, MX, CAA, TLS issuer, TLS SPKI
+fingerprint, registrar-lock preference, and a renewal-review date for up to 100
+domains. Empty fields mean unconfigured; they do not require a record to be
+absent.
+
+The emitted `whoisleuth.domain-control-manifest` version 1 is normalized and
+protected by a canonical SHA-256 digest. It can also be passed to
+`sign-artifact` for an optional local Ed25519 signature. Integrity and
+signature verification detect changes and authenticate possession of the
+selected key; neither establishes that the desired state is correct.
+
+A review input uses `whoisleuth.domain-control-review-input` version 1 and
+contains one manifest plus separately attributed observations. Only a complete
+`observed` field may produce `drift`. Partial, unavailable, unsupported, and
+missing observations remain inconclusive, and unrelated observations are
+counted but ignored. The review performs no DNS, RDAP, HTTP, TLS, SMTP, or
+registrar request.
+
+## Fixed investigation plans
+
+`workflow-plan <recipe> <domain|brand>` turns one of four fixed recipes into a
+versioned `whoisleuth.cli.investigation-plan` document. Supported recipes are
+`domain-triage`, `lookalike-review`, `owned-domain-review`, and
+`historical-comparison`. Each step names an existing CLI command, carries its
+arguments as a JSON array, declares whether it is offline or networked, and
+marks network-disclosure or analyst-selection approval gates.
+
+The command is plan-only. It does not execute a step, construct a shell script,
+interpret a placeholder as a file path, read an artifact, make a request,
+change a case, or submit evidence. Analysts deliberately run selected commands
+after reviewing their collection boundaries. This provides repeatable
+domain-specific workflows without an arbitrary automation or plugin surface.
+
 ## Optional local rendered capture
 
 `packages/web-capture` is a private repo-local Playwright package, not part of

package/frontend/src/lib/analysis/bulk-domain-comparison.js

@@ -151,7 +151,7 @@ function freshness(observedAt, now) {
 export function buildBulkDomainComparison(leftRaw, rightRaw, observedAtRaw = null, options = {}) {
     const left = normalizeBulkSessionResult(leftRaw);
     const right = normalizeBulkSessionResult(rightRaw);
-    if (!left || !right || left.domain === right.domain)
+    if (!left || !right || (left.domain === right.domain && !options.allowSameDomain))
         return null;
     const observedAt = timestamp(observedAtRaw);
     const registry = context(left, right, 'Registry and registrar evidence', ['rdap', 'availability'], observedAt, options);
@@ -214,11 +214,17 @@ export function buildBulkDomainComparison(leftRaw, rightRaw, observedAtRaw = nul
         freshness: freshness(observedAt, options.now ?? Date.now()),
         rows,
         counts,
-        limitations: [
-            'This compares compact settled evidence already present in Bulk and makes no new request.',
-            'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
-            'Equality does not establish common ownership, infrastructure control, intent, safety, or maliciousness.',
-        ],
+        limitations: options.allowSameDomain
+            ? [
+                'This compares normalized evidence already present in two saved observations for the same domain and makes no new request.',
+                'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
+                'An observed difference can reflect changed collection conditions and does not by itself establish current state, ownership, intent, safety, or maliciousness.',
+            ]
+            : [
+                'This compares compact settled evidence already present in Bulk and makes no new request.',
+                'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
+                'Equality does not establish common ownership, infrastructure control, intent, safety, or maliciousness.',
+            ],
     };
 }
 export async function buildBulkDomainComparisonExport(comparisonRaw, generatedAtRaw = new Date().toISOString()) {

package/frontend/src/lib/analysis/bulk-retry-plan.js

@@ -1,13 +1,7 @@
 import { normalizeBulkSessionResult, } from "./bulk-session-model.js";
+import { limitedBulkSources } from "./bulk-source-coverage.js";
 export const MAX_BULK_RETRY_ROWS = 200;
 export const BULK_REVIEW_STALE_AFTER_DAYS = 7;
-const LIMITED_STATES = new Set([
-    'error',
-    'partial',
-    'skipped',
-    'unavailable',
-    'unsupported',
-]);
 function freshness(value, now = Date.now()) {
     if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) {
         return { observedAt: null, ageDays: null, state: 'unknown' };
@@ -21,9 +15,7 @@ function freshness(value, now = Date.now()) {
     };
 }
 function retryRow(value, isStale) {
-    const limitedSources = value.sourceCoverage
-        .filter((item) => LIMITED_STATES.has(item.state))
-        .map((item) => item.source)
+    const limitedSources = limitedBulkSources(value.domain, value.sourceCoverage)
         .sort()
         .slice(0, 12);
     const reasons = [];
@@ -56,6 +48,7 @@ export function buildBulkRetryPlan(values, mode, observedAtRaw = null, now = Dat
             'This repeats the selected lookup profile; the current API does not request only one upstream source.',
             `Evidence is marked stale after ${BULK_REVIEW_STALE_AFTER_DAYS} days for review purposes; this is a local observation age, not an upstream record age.`,
             'Optional third-party intelligence providers are not contacted by Bulk.',
+            'Sources deliberately skipped by the selected scan profile or deployment policy do not independently trigger a retry.',
             'A retry can remain partial or fail and does not convert unavailable evidence into absence.',
         ],
     };

package/frontend/src/lib/analysis/bulk-source-coverage.js

@@ -0,0 +1,76 @@
+// Authority-aware interpretation for compact Bulk source observations. Raw
+// source states remain unchanged; this layer only decides whether an observed
+// limitation was unexpected for the registry's published service paths.
+import { registryCapabilityFor } from "../../../../lib/registry-capabilities.mjs";
+const MAX_SOURCE_OBSERVATIONS = 32;
+const MAX_SOURCE_TEXT_LENGTH = 40;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
+const LIMITED_SOURCE_STATES = new Set([
+    'error',
+    'failed',
+    'inconclusive',
+    'partial',
+    'rate_limited',
+    'unavailable',
+    'unsupported',
+]);
+function text(value) {
+    return typeof value === 'string'
+        && value.length <= MAX_SOURCE_TEXT_LENGTH
+        && !CONTROL_RE.test(value)
+        ? value.trim().toLowerCase()
+        : '';
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function observations(value) {
+    return Array.isArray(value)
+        ? value.slice(0, MAX_SOURCE_OBSERVATIONS).flatMap((entry) => {
+            const item = record(entry);
+            const source = text(item?.source);
+            const state = text(item?.state);
+            return source && state ? [{ source, state }] : [];
+        })
+        : [];
+}
+function expectedUnsupportedSources(domain) {
+    const capability = registryCapabilityFor(domain);
+    if (!capability)
+        return new Set();
+    const expected = new Set();
+    if (capability.rdapAccessProfile === 'no-iana-service')
+        expected.add('rdap');
+    if (capability.whoisAccessProfile === 'no-iana-service')
+        expected.add('whois');
+    return expected;
+}
+export function isExpectedUnsupportedBulkSource(domain, observation) {
+    const source = text(observation.source);
+    const state = text(observation.state);
+    return state === 'unsupported' && expectedUnsupportedSources(domain).has(source);
+}
+export function limitedBulkSources(domain, coverage) {
+    const expectedUnsupported = expectedUnsupportedSources(domain);
+    return observations(coverage)
+        .filter(({ source, state }) => (LIMITED_SOURCE_STATES.has(state)
+        && !(state === 'unsupported' && expectedUnsupported.has(source))))
+        .map(({ source }) => source);
+}
+export function classifyBulkSourceCoverage(domain, coverage) {
+    const retained = observations(coverage);
+    if (!retained.length)
+        return 'unrecorded';
+    return limitedBulkSources(domain, retained).length ? 'limited' : 'complete';
+}
+export function describeBulkSourceCoverage(domain, observation) {
+    const source = text(observation.source);
+    const state = text(observation.state);
+    if (!source || !state)
+        return 'unrecorded source';
+    return isExpectedUnsupportedBulkSource(domain, observation)
+        ? `${source}: unsupported (no IANA-published service)`
+        : `${source}: ${state}`;
+}

package/frontend/src/lib/analysis/http-summary.js

@@ -3,10 +3,11 @@
 // connection attempts. Bulk/watchlist/case records deliberately keep only this
 // smaller derived shape: no paths, queries, header values, attempt errors, or
 // redirect inventories.
+import { MAX_HTTP_EVIDENCE_REDIRECTS } from "../../../../lib/http-evidence-bounds.mjs";
 export const HTTP_SUMMARY_VERSION = 1;
 export const MAX_HTTP_SUMMARY_ORIGIN_LENGTH = 300;
 export const MAX_HTTP_SUMMARY_CONTENT_TYPE_LENGTH = 100;
-export const MAX_HTTP_SUMMARY_REDIRECTS = 5;
+export const MAX_HTTP_SUMMARY_REDIRECTS = MAX_HTTP_EVIDENCE_REDIRECTS;
 export const MAX_HTTP_SECURITY_HEADER_INPUTS = 20;
 export const HTTP_SECURITY_HEADER_TOKENS = Object.freeze([
     'content-security-policy',

package/frontend/src/lib/analysis/utils.js

@@ -1,5 +1,6 @@
 // Browser-safe analysis helpers shared by the Svelte tools.
 import { serializeCsvCell, serializeCsvRows } from "../../../../lib/csv.mjs";
+import { hammingDistanceHex, isInformativePerceptualHash, isPerceptualHash, } from "../../../../lib/perceptual-hash-comparison.mjs";
 // Deliberately conservative (no +tags, no comments, no quoted local parts) -
 // this only gates whether a WHOIS/RDAP-sourced string is safe to drop into a
 // mailto: URI as the recipient, not a general email validator. mailto:
@@ -38,47 +39,13 @@ export function entityDisplayName(value) {
         .slice(0, MAX_ENTITY_DISPLAY_LENGTH);
     return normalized || null;
 }
-// Hamming distance (0-64) between two 16-hex perceptual dHash strings (see
-// lib/perceptual-hash.mts), or null if either isn't a well-formed hash. Smaller
-// = more visually similar. Shared by the brand-profile near-match check and
-// bulk favicon clustering; mirrors the backend's hammingDistanceHex. The two
-// implementations target separate Node and browser execution boundaries.
-const HEX_HASH_RE = /^[0-9a-f]{16}$/;
-export 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) {
-        let diff = parseInt(a.charAt(i), 16) ^ parseInt(b.charAt(i), 16);
-        while (diff) {
-            distance += diff & 1;
-            diff >>= 1;
-        }
-    }
-    return distance;
-}
+export { hammingDistanceHex };
 // A dHash carries usable structure only when its set-bit count is away from
-// the degenerate extremes - a near-all-zero (or near-all-one) hash comes from
-// a solid/monotonic icon and collides with every other such icon (see
-// lib/perceptual-hash.mts's MIN_INFORMATIVE_BITS, mirrored here). Generation
-// already rejects these, but this is re-checked at every comparison so a
-// degenerate hash saved into a Brand Profile before that guard existed can't
-// keep producing false near-matches.
-const MIN_INFORMATIVE_HASH_BITS = 10;
+// the degenerate extremes. The shared browser-safe contract applies the same
+// threshold during generation and comparison, including for older retained
+// profile values.
 export function isInformativeFaviconHash(hex) {
-    if (typeof hex !== 'string' || !HEX_HASH_RE.test(hex))
-        return false;
-    let bits = 0;
-    for (let i = 0; i < 16; i += 1) {
-        let n = parseInt(hex.charAt(i), 16);
-        while (n) {
-            bits += n & 1;
-            n >>= 1;
-        }
-    }
-    return bits >= MIN_INFORMATIVE_HASH_BITS && bits <= 64 - MIN_INFORMATIVE_HASH_BITS;
+    return isInformativePerceptualHash(hex);
 }
 function faviconRecord(value) {
     const record = plainRecord(value);
@@ -87,7 +54,7 @@ function faviconRecord(value) {
     const faviconHash = typeof record.faviconHash === 'string' && record.faviconHash
         ? record.faviconHash
         : null;
-    const faviconPHash = typeof record.faviconPHash === 'string' && HEX_HASH_RE.test(record.faviconPHash)
+    const faviconPHash = isPerceptualHash(record.faviconPHash)
         ? record.faviconPHash
         : null;
     return faviconHash || faviconPHash