@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/packages/comparison/comparison-ledger-json.mjs

@@ -0,0 +1,80 @@
+// Bounded deterministic JSON projection shared by browser and CLI comparison paths.
+const MAX_COLLECTION_SCAN = 256;
+const MAX_DEPTH = 8;
+const MAX_SCALAR_LENGTH = 2_000;
+const MAX_TRAVERSAL_NODES = 1_024;
+const MAX_SERIALISED_LENGTH = 8_192;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function boundedJsonString(value, state) {
+    if (value.length > MAX_SCALAR_LENGTH)
+        state.truncated = true;
+    return JSON.stringify(value.slice(0, MAX_SCALAR_LENGTH));
+}
+function stableJson(value, depth, state) {
+    if (depth > MAX_DEPTH) {
+        state.truncated = true;
+        return '"[bounded depth]"';
+    }
+    if (state.nodes >= MAX_TRAVERSAL_NODES) {
+        state.truncated = true;
+        return '"[bounded traversal]"';
+    }
+    state.nodes += 1;
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return boundedJsonString(value, state);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (Array.isArray(value)) {
+        const values = [];
+        const limit = Math.min(value.length, MAX_COLLECTION_SCAN);
+        for (let index = 0; index < limit && state.nodes < MAX_TRAVERSAL_NODES; index += 1) {
+            values.push(stableJson(value[index], depth + 1, state));
+        }
+        if (values.length < value.length)
+            state.truncated = true;
+        return `[${values.join(',')}]`;
+    }
+    const item = record(value);
+    if (!item)
+        return 'null';
+    const keys = [];
+    for (const key in item) {
+        if (!Object.hasOwn(item, key))
+            continue;
+        if (keys.length >= MAX_COLLECTION_SCAN) {
+            state.truncated = true;
+            break;
+        }
+        keys.push(key);
+    }
+    keys.sort();
+    const values = [];
+    for (const key of keys) {
+        if (state.nodes >= MAX_TRAVERSAL_NODES) {
+            state.truncated = true;
+            break;
+        }
+        values.push(`${boundedJsonString(key, state)}:${stableJson(item[key], depth + 1, state)}`);
+    }
+    if (values.length < keys.length)
+        state.truncated = true;
+    return `{${values.join(',')}}`;
+}
+export function projectComparisonLedgerJson(value) {
+    const state = { truncated: false, nodes: 0 };
+    const serialised = stableJson(value, 0, state);
+    if (serialised.length > MAX_SERIALISED_LENGTH)
+        state.truncated = true;
+    return Object.freeze({ value: serialised.slice(0, MAX_SERIALISED_LENGTH), truncated: state.truncated });
+}
+export function stableComparisonLedgerJson(value) {
+    return projectComparisonLedgerJson(value).value;
+}

package/packages/comparison/comparison-ledger-serialization.mjs

@@ -0,0 +1,52 @@
+// Stable comparison-ledger identifiers and safe local destinations are runtime-neutral.
+const CONTROL_RE = /[\u0000-\u001f\u007f]/gu;
+const MAX_ID_PARTS = 32;
+const MAX_ID_PART_LENGTH = 500;
+function stableHash(value) {
+    let first = 0x811c9dc5;
+    let second = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        first ^= code;
+        first = Math.imul(first, 0x01000193);
+        second = (second + code) | 0;
+        second = (second + (second << 10)) | 0;
+        second ^= second >>> 6;
+    }
+    second = (second + (second << 3)) | 0;
+    second ^= second >>> 11;
+    second = (second + (second << 15)) | 0;
+    return `${(first >>> 0).toString(36).padStart(7, '0')}${(second >>> 0).toString(36).padStart(7, '0')}`;
+}
+export function stableComparisonLedgerId(prefix, parts) {
+    const encoded = parts.slice(0, MAX_ID_PARTS).map((part) => {
+        let value = '';
+        try {
+            value = part === null || part === undefined || ['string', 'number', 'boolean', 'bigint'].includes(typeof part)
+                ? String(part ?? '')
+                : Object.prototype.toString.call(part);
+        }
+        catch {
+            value = '[unreadable]';
+        }
+        const bounded = value.slice(0, MAX_ID_PART_LENGTH);
+        const typed = `${typeof part}:${value.length}:${bounded}`;
+        return `${typed.length}:${typed}`;
+    }).join('');
+    const material = `${parts.length}:${encoded}`;
+    return `${prefix.slice(0, 64)}-${stableHash(material)}`;
+}
+export function safeComparisonLedgerHref(value) {
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+        return '';
+    const href = String(value).replace(CONTROL_RE, ' ').replace(/\s+/gu, ' ').trim().slice(0, 500).trim();
+    if (!href.startsWith('/') || href.startsWith('//') || href.includes('\\'))
+        return '';
+    try {
+        const base = new URL('https://comparison-ledger.invalid/');
+        return new URL(href, base).origin === base.origin ? href : '';
+    }
+    catch {
+        return '';
+    }
+}

package/packages/comparison/favicon-similarity.mjs

@@ -0,0 +1,78 @@
+import { hammingDistanceHex, isInformativePerceptualHash, isPerceptualHash, } from "../../lib/perceptual-hash-comparison.mjs";
+function plainRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function faviconRecord(value) {
+    const record = plainRecord(value);
+    if (!record || typeof record.domain !== 'string')
+        return null;
+    const faviconHash = typeof record.faviconHash === 'string' && record.faviconHash
+        ? record.faviconHash
+        : null;
+    const faviconPHash = isPerceptualHash(record.faviconPHash)
+        ? record.faviconPHash
+        : null;
+    return faviconHash || faviconPHash
+        ? { domain: record.domain, faviconHash, faviconPHash }
+        : null;
+}
+export function groupBySimilarFavicon(records, maxDistance) {
+    const items = Array.isArray(records)
+        ? records.map(faviconRecord).filter((record) => record !== null)
+        : [];
+    const parent = items.map((_, index) => index);
+    const find = (value) => {
+        let root = value;
+        while ((parent[root] ?? root) !== root)
+            root = parent[root] ?? root;
+        while ((parent[value] ?? value) !== root) {
+            const next = parent[value] ?? value;
+            parent[value] = root;
+            value = next;
+        }
+        return root;
+    };
+    const union = (left, right) => {
+        const leftRoot = find(left);
+        const rightRoot = find(right);
+        if (leftRoot !== rightRoot)
+            parent[leftRoot] = rightRoot;
+    };
+    const firstByHash = new Map();
+    items.forEach((item, index) => {
+        if (!item.faviconHash)
+            return;
+        const existing = firstByHash.get(item.faviconHash);
+        if (existing !== undefined)
+            union(index, existing);
+        else
+            firstByHash.set(item.faviconHash, index);
+    });
+    const withPerceptualHash = [];
+    items.forEach((item, index) => {
+        if (isInformativePerceptualHash(item.faviconPHash)) {
+            withPerceptualHash.push({ index, hash: item.faviconPHash });
+        }
+    });
+    for (let leftIndex = 0; leftIndex < withPerceptualHash.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < withPerceptualHash.length; rightIndex += 1) {
+            const left = withPerceptualHash[leftIndex];
+            const right = withPerceptualHash[rightIndex];
+            if (!left || !right)
+                continue;
+            const distance = hammingDistanceHex(left.hash, right.hash);
+            if (distance !== null && distance <= maxDistance)
+                union(left.index, right.index);
+        }
+    }
+    const groups = new Map();
+    items.forEach((item, index) => {
+        const root = find(index);
+        if (!groups.has(root))
+            groups.set(root, []);
+        groups.get(root)?.push(item.domain);
+    });
+    return [...groups.values()].filter((domains) => domains.length >= 2);
+}

package/{frontend/src/lib/analysis/page-similarity.js → packages/comparison/page-similarity.mjs}

@@ -2,9 +2,10 @@
 // module deliberately reports each component independently: it does not
 // produce an aggregate similarity score, risk factor, or maliciousness
 // verdict. Inputs pass through the strict baseline normalizer before use.
-import { normalizePageBaseline } from "./page-baseline.js";
-import { hammingDistanceHex } from "./utils.js";
-export const PAGE_COMPARISON_VERSION = 3;
+import { normalizePageBaseline } from "../workspace/page-baseline.mjs";
+import { hammingDistanceHex } from "../../lib/perceptual-hash-comparison.mjs";
+import { PAGE_COMPARISON_VERSION } from "../contracts/offline-comparison.mjs";
+export { PAGE_COMPARISON_VERSION };
 function component(id, label, method, status, outcome, detail, partial) {
     return { id, label, method, status, outcome, detail, partial, sharedValues: [] };
 }

package/{frontend/src/lib/analysis/relationship-evidence.js → packages/comparison/relationship-evidence.mjs}

@@ -3,11 +3,10 @@
 // proof of common ownership, coordination, intent, or maliciousness. This
 // module deliberately produces no aggregate score and is never a persistence
 // boundary.
-import { normalizeDomain } from "./case-model.js";
-import { groupBySimilarFavicon } from "./utils.js";
-export const RELATIONSHIP_EVIDENCE_VERSION = 2;
-export const TLS_RELATIONSHIP_PROFILE_VERSION = 2;
-export const SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS = Object.freeze([1, TLS_RELATIONSHIP_PROFILE_VERSION]);
+import { normalizeDomain } from "../cases/case-model.mjs";
+import { groupBySimilarFavicon } from "./favicon-similarity.mjs";
+import { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, } from "../contracts/offline-comparison.mjs";
+export { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, };
 export const MAX_RELATIONSHIP_ROWS = 2000;
 export const MAX_RELATIONSHIP_GROUPS = 100;
 export const MAX_RELATIONSHIP_DOMAINS = 50;
@@ -93,7 +92,7 @@ function tlsCertificateFingerprint(availability) {
     const certificate = record(tls?.certificate);
     const fingerprint = certificate?.fingerprintSha256;
     const status = tls?.status;
-    if (tls?.source !== 'tls' || !SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS.includes(Number(tls?.profileVersion))
+    if (tls?.source !== 'tls' || !SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS.some((version) => version === Number(tls?.profileVersion))
         || typeof status !== 'string' || !['success', 'partial'].includes(status) || typeof fingerprint !== 'string'
         || fingerprint.length !== 64 || !CERTIFICATE_SHA_RE.test(fingerprint))
         return null;
@@ -240,7 +239,7 @@ export function buildScanRelationships(rawRows) {
         }
     }
     for (const [value, domains] of officialAssets)
-        output.push(group('official_asset', 'Official asset relationship', 'Configured-domain host match', value, [...domains].sort(), 'One or more pages loaded an asset from this configured official domain or its subdomain.'));
+        output.push(group('official_asset', 'Official asset host match', 'Configured-domain host match', value, [...domains].sort(), 'One or more pages loaded an asset from this configured official domain or its subdomain.'));
     const order = new Map(['nameserver_set', 'ip_address', 'certificate', 'tracking_identifier', 'favicon', 'official_asset']
         .map((value, index) => [value, index]));
     output.sort((left, right) => (Number(order.get(left.type)) - Number(order.get(right.type))) || left.value.localeCompare(right.value) || left.domains.join('|').localeCompare(right.domains.join('|')));

package/packages/contracts/analyst-review-state-contract.mjs

@@ -0,0 +1,61 @@
+/**
+ * Bounded analyst Review Item schema metadata and shared value types.
+ *
+ * Lifecycle behaviour is owned by packages/monitoring/analyst-review-state.mts.
+ * This dependency-free contract module lets storage and lifecycle registries
+ * depend only on declared shapes, versions, and limits.
+ */
+export const ANALYST_REVIEW_STATE_SCHEMA = 'whoisleuth.analyst-review-state';
+export const ANALYST_REVIEW_STATE_SCHEMA_VERSION = 1;
+export const ANALYST_REVIEW_STATE_SUPPORTED_VERSIONS = Object.freeze([ANALYST_REVIEW_STATE_SCHEMA_VERSION]);
+/** Internal IndexedDB revision; it is deliberately independent of the public document version. */
+export const ANALYST_REVIEW_STATE_BROWSER_STORAGE_REVISION = 2;
+export const MAX_ANALYST_REVIEW_STATE_RECORDS = 500;
+export const MAX_ANALYST_REVIEW_STATE_BYTES = 512 * 1024;
+export const MAX_ANALYST_REVIEW_RATIONALE_LENGTH = 1_000;
+export const MAX_ANALYST_REVIEW_ASSOCIATIONS = 20;
+export const MAX_ANALYST_REVIEW_HISTORY = 8;
+export const MAX_ANALYST_REVIEW_ITEMS = 500;
+export const MAX_ANALYST_REVIEW_IDENTITY_BYTES = 1024 * 1024;
+export const ANALYST_REVIEW_KINDS = Object.freeze([
+    'case',
+    'case_action',
+    'observed_effect_review',
+    'evidence_gap',
+    'watchlist_change',
+    'bulk_session',
+    'comparison',
+    'suppression',
+    'change_window',
+    'desired_posture',
+    'certificate',
+    'incomplete_packet',
+    'detection_rule',
+    'orphaned_state',
+]);
+export const ANALYST_REVIEW_EVIDENCE_FAMILIES = Object.freeze([
+    'case',
+    'registration',
+    'dns',
+    'routing',
+    'http',
+    'certificate_transparency',
+    'live_tls',
+    'caa',
+    'certificate_identity',
+    'comparison',
+    'desired_posture',
+    'suppression',
+    'change_window',
+    'relationship',
+    'bulk',
+    'rule',
+    'packet',
+]);
+export const ANALYST_REVIEW_DISPOSITIONS = Object.freeze(['open', 'expected', 'suppressed', 'resolved']);
+export const ANALYST_REVIEW_DISPOSITION_OPTIONS = Object.freeze([
+    { value: 'open', label: 'Open' },
+    { value: 'expected', label: 'Expected' },
+    { value: 'suppressed', label: 'Suppressed' },
+    { value: 'resolved', label: 'Resolved' },
+]);

package/packages/contracts/analyst-review-state.mjs

@@ -0,0 +1,50 @@
+import { defineSchemaCompatibility } from "./schema-compatibility.mjs";
+import { buildExtractedLifecycleFamilyV2 } from "./extracted-domain-lifecycle.mjs";
+import { defineSchemaLifecycleFamily } from "./schema-lifecycle.mjs";
+import { ANALYST_REVIEW_STATE_SCHEMA, ANALYST_REVIEW_STATE_SCHEMA_VERSION, ANALYST_REVIEW_STATE_SUPPORTED_VERSIONS, MAX_ANALYST_REVIEW_STATE_BYTES, } from "./analyst-review-state-contract.mjs";
+export * from "./analyst-review-state-contract.mjs";
+export const ANALYST_REVIEW_STATE_CONTRACT_OWNER = 'packages/contracts/analyst-review-state.mts';
+export const ANALYST_REVIEW_STATE_COMPATIBILITY = defineSchemaCompatibility({
+    id: 'browser.analyst-review-state',
+    kind: 'browser_store',
+    schema: ANALYST_REVIEW_STATE_SCHEMA,
+    currentVersion: ANALYST_REVIEW_STATE_SCHEMA_VERSION,
+    supportedVersions: ANALYST_REVIEW_STATE_SUPPORTED_VERSIONS,
+    acceptsUnversionedLegacy: false,
+    futureVersionBehavior: 'preserve_without_write',
+    migration: 'exact_current_only',
+    writeSemantics: 'optimistic_replace',
+    byteBudget: MAX_ANALYST_REVIEW_STATE_BYTES,
+    owner: ANALYST_REVIEW_STATE_CONTRACT_OWNER,
+    note: 'Bounded analyst-authored lifecycle overlay. Material evidence changes, expiry, and incomplete evidence reopen review without rewriting source evidence or losing earlier rationale.',
+});
+export const ANALYST_REVIEW_STATE_LIFECYCLE_FAMILY = defineSchemaLifecycleFamily(buildExtractedLifecycleFamilyV2({
+    id: 'analyst-review-state',
+    owner: ANALYST_REVIEW_STATE_CONTRACT_OWNER,
+    serializerModule: 'packages/monitoring/analyst-review-state.mts',
+    serializerExportName: 'serialiseAnalystReviewStateJson',
+    plane: 'browser',
+    projection: 'browser_export',
+    retention: 'operator_controlled_output',
+    includedCategories: ['subject-identity', 'material-fingerprint', 'analyst-disposition', 'rationale', 'review-times', 'case-and-campaign-references'],
+    excludedCategories: ['raw-upstream-responses', 'expanded-contacts', 'complete-query-urls', 'credentials', 'cookies', 'certificate-transparency-history'],
+    formats: [{
+            descriptor: ANALYST_REVIEW_STATE_COMPATIBILITY,
+            lifecycleSchema: ANALYST_REVIEW_STATE_SCHEMA,
+            requiredKeys: ['schema', 'version', 'records'],
+            optionalKeys: [],
+            hook: {
+                module: 'packages/monitoring/analyst-review-state.mts',
+                exportName: 'normalizeAnalystReviewStateStore',
+                role: 'normaliser',
+                runtime: 'shared',
+            },
+            fixtures: [{
+                    id: 'analyst-review-state-v1',
+                    path: 'test/fixtures/extracted-domain-lifecycle/analyst-review-state-v1.json',
+                    bytes: 663,
+                    sha256: 'af0b191a79a50ef28f82975d181bdd3f7ba0bf7245cf4fc2b3adb84603d8dae6',
+                    version: ANALYST_REVIEW_STATE_SCHEMA_VERSION,
+                }],
+        }],
+}));