@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/{frontend/src/lib/analysis/case-evidence-model.js → packages/cases/case-evidence-model.mjs}

@@ -1,9 +1,10 @@
 // Pure, framework-neutral analyst-case records, evidence histories, bounded
 // record normalization, and analyst updates.
-import { normalizeHttpSummary } from "./http-summary.js";
-import { normalizeOpportunityModelVersion, normalizeRiskModelVersion } from "./scoring.js";
-import { MAX_EVIDENCE_CHANGES, MAX_EVIDENCE_DETAIL_LENGTH, MAX_EVIDENCE_FACTORS, MAX_EVIDENCE_MUTATIONS, MAX_EVIDENCE_NAMESERVERS, MAX_EVIDENCE_SNAPSHOTS_PER_CASE, MAX_EVIDENCE_STRING_LENGTH, MAX_EVIDENCE_TITLE_LENGTH, } from "./case-record-contracts.js";
-import { CONCLUSIVE_AVAILABILITY, DEFAULT_EVIDENCE_SOURCE, EVIDENCE_SOURCE_RANK, EVIDENCE_SOURCE_SET, REGISTERED_LIKE, hashString, isoOrNull, objectRecord, safeId, } from "./case-record-core.js";
+import { normalizeHttpSummary } from "./http-summary.mjs";
+import { normalizeOpportunityModelVersion } from "../../lib/opportunity-scoring.mjs";
+import { normalizeRiskModelVersion } from "../../lib/risk-scoring.mjs";
+import { MAX_EVIDENCE_CHANGES, MAX_EVIDENCE_DETAIL_LENGTH, MAX_EVIDENCE_FACTORS, MAX_EVIDENCE_MUTATIONS, MAX_EVIDENCE_NAMESERVERS, MAX_EVIDENCE_SNAPSHOTS_PER_CASE, MAX_EVIDENCE_STRING_LENGTH, MAX_EVIDENCE_TITLE_LENGTH, } from "./case-record-contracts.mjs";
+import { CONCLUSIVE_AVAILABILITY, DEFAULT_EVIDENCE_SOURCE, EVIDENCE_SOURCE_RANK, EVIDENCE_SOURCE_SET, REGISTERED_LIKE, caseTimestampOrNull, hashString, isoOrNull, normalizeEvidenceHostnameForCase, objectRecord, safeId, } from "./case-record-core.mjs";
 function evidenceString(value, max = MAX_EVIDENCE_STRING_LENGTH) {
     if (value == null)
         return null;
@@ -81,6 +82,12 @@ function dayOf(value) {
     const iso = isoOrNull(value);
     return iso ? iso.slice(0, 10) : null;
 }
+function lifecycleTimestamp(value, sourceVersion) {
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/u.test(value)) {
+        return caseTimestampOrNull(`${value}T00:00:00Z`);
+    }
+    return caseTimestampOrNull(value, sourceVersion);
+}
 // Capture completeness is recorded explicitly, never inferred from whether a
 // boolean happens to be false. 'fast' captures skip the DNS/site/HTML probes;
 // 'deep' evaluates them; 'unknown' is for migrated/imported evidence whose depth
@@ -104,6 +111,7 @@ const DEEP_SIGNAL_FIELDS = [
 // included so captures of differing completeness can never be confused for one
 // another. Deterministic ordering here is what makes the fingerprint stable.
 const MATERIAL_FIELD_ORDER = [
+    'inputHostname',
     'scanDepth',
     'availability', 'confidence', 'riskModelVersion', 'riskScore', 'opportunityModelVersion', 'opportunityScore',
     'riskFactors', 'opportunityFactors',
@@ -114,6 +122,7 @@ const MATERIAL_FIELD_ORDER = [
     'httpCrossOriginRedirect', 'httpHttpsDowngrade', 'httpContentType', 'httpSecurityHeaders',
     'faviconMatch', 'faviconNearMatch', 'reusesOfficialAssets', 'hasPasswordField', 'hasExternalFormAction', 'phishingLanguageMatch',
     'privacyProtected', 'idnReferenceMatch', 'pageBaselineMatch', 'hasActiveBrandProfile',
+    'profileContextState', 'profileContextLimitation',
     'mutationTypes',
 ];
 // The canonical, comparison-safe value of a material field. Registrar casing,
@@ -156,7 +165,7 @@ function isEmptyMaterial(value) {
 }
 // Fields that describe the capture rather than assert evidence, so they never
 // on their own keep an otherwise-empty snapshot alive.
-const NON_EVIDENCE_MATERIAL = new Set(['scanDepth', 'confidence']);
+const NON_EVIDENCE_MATERIAL = new Set(['inputHostname', 'scanDepth', 'confidence']);
 // A snapshot with no material evidence (only timestamps/source/depth, or only a
 // bare confidence/unknown-availability) is dropped rather than added to a
 // timeline.
@@ -172,8 +181,15 @@ function hasMaterialEvidence(snapshot) {
 // Deterministic string form of the material identity, keys in fixed order.
 function canonicalMaterialString(snapshot) {
     const canonical = {};
-    for (const field of MATERIAL_FIELD_ORDER)
-        canonical[field] = materialValue(field, snapshot);
+    for (const field of MATERIAL_FIELD_ORDER) {
+        const value = materialValue(field, snapshot);
+        // Preserve historical fingerprints when the new v14 observation-context
+        // field is absent. A retained hostname is still material and therefore
+        // separates otherwise-identical captures.
+        if (field === 'inputHostname' && value === null)
+            continue;
+        canonical[field] = value;
+    }
     return JSON.stringify(canonical);
 }
 /**
@@ -185,7 +201,7 @@ function canonicalMaterialString(snapshot) {
  * pass a real fallback; the import path deliberately passes an older case
  * timestamp (never "now") so malformed imported evidence can't appear newest.
  * @param {unknown} raw
- * @param {{ source?: string, fallback?: string | null }} [options]
+ * @param {{ source?: string, fallback?: string | null, sourceVersion?: number | null, caseDomain?: string | null }} [options]
  * @returns {CaseEvidenceSnapshot | null}
  */
 export function normalizeSnapshot(raw, options = {}) {
@@ -199,7 +215,12 @@ function buildSnapshot(raw, options) {
     const record = objectRecord(raw);
     const scanDepth = normalizeScanDepth(record.scanDepth);
     const httpSummary = normalizeHttpSummary(record);
+    const acceptsProfileContext = options.sourceVersion === undefined || Number(options.sourceVersion) >= 12;
+    const acceptsInputHostname = options.sourceVersion === undefined || Number(options.sourceVersion) >= 13;
     const fields = {
+        inputHostname: acceptsInputHostname
+            ? normalizeEvidenceHostnameForCase(record.inputHostname, options.caseDomain)
+            : null,
         scanDepth,
         availability: evidenceString(record.availability),
         confidence: evidenceString(record.confidence),
@@ -210,8 +231,8 @@ function buildSnapshot(raw, options) {
         riskFactors: normalizeFactors(record.riskFactors),
         opportunityFactors: normalizeFactors(record.opportunityFactors),
         registrar: evidenceString(record.registrar),
-        createdDate: isoOrNull(record.createdDate),
-        expiryDate: isoOrNull(record.expiryDate),
+        createdDate: lifecycleTimestamp(record.createdDate, options.sourceVersion),
+        expiryDate: lifecycleTimestamp(record.expiryDate, options.sourceVersion),
         nameservers: normalizeNameserverList(record.nameservers),
         hasMx: boolOrNull(record.hasMx),
         hasSpf: boolOrNull(record.hasSpf),
@@ -239,6 +260,12 @@ function buildSnapshot(raw, options) {
         idnReferenceMatch: boolOrNull(record.idnReferenceMatch),
         pageBaselineMatch: boolOrNull(record.pageBaselineMatch),
         hasActiveBrandProfile: boolOrNull(record.hasActiveBrandProfile),
+        profileContextState: acceptsProfileContext && ['loading', 'ready', 'unavailable'].includes(String(record.profileContextState))
+            ? record.profileContextState
+            : null,
+        profileContextLimitation: acceptsProfileContext
+            ? evidenceString(record.profileContextLimitation, MAX_EVIDENCE_DETAIL_LENGTH)
+            : null,
         mutationTypes: normalizeMutationList(record.mutationTypes),
     };
     // A version without an actual risk assessment is orphaned metadata. Drop it
@@ -278,10 +305,10 @@ function buildSnapshot(raw, options) {
     }
     if (!hasMaterialEvidence(fields))
         return null;
-    const capturedAt = isoOrNull(record.capturedAt) || options.fallback || null;
+    const capturedAt = caseTimestampOrNull(record.capturedAt, options.sourceVersion) || options.fallback || null;
     if (!capturedAt)
         return null; // an evidence entry with no placeable time is skipped
-    let firstCapturedAt = isoOrNull(record.firstCapturedAt) || capturedAt;
+    let firstCapturedAt = caseTimestampOrNull(record.firstCapturedAt, options.sourceVersion) || capturedAt;
     if (Date.parse(firstCapturedAt) > Date.parse(capturedAt))
         firstCapturedAt = capturedAt;
     const source = typeof record.source === 'string' && EVIDENCE_SOURCE_SET.has(record.source)
@@ -343,7 +370,7 @@ function compareSnapshotChrono(a, b) {
  * snapshots are retained up to the per-case bound; ids are made unique within
  * the case.
  * @param {unknown} rawList
- * @param {{ source?: string, fallback?: string | null }} [options]
+ * @param {{ source?: string, fallback?: string | null, sourceVersion?: number | null, caseDomain?: string | null }} [options]
  * @returns {CaseEvidenceSnapshot[]}
  */
 export function normalizeEvidenceHistory(rawList, options = {}) {
@@ -453,12 +480,14 @@ function valuesMateriallyEqual(field, previous, current) {
  * in the same observation produced an ordinary material change.
  * @param {CaseEvidenceSnapshot | null | undefined} previous
  * @param {CaseEvidenceSnapshot | null | undefined} current
- * @returns {Array<'scan-depth' | 'risk-model'>}
+ * @returns {Array<'observation-context' | 'opportunity-model' | 'scan-depth' | 'risk-model'>}
  */
 export function caseEvidenceIncomparableReasons(previous, current) {
     if (!previous || !current || previous.fingerprint === current.fingerprint)
         return [];
     const reasons = [];
+    if (previous.inputHostname !== current.inputHostname)
+        reasons.push('observation-context');
     const hasRiskEvidence = previous.riskScore !== null || current.riskScore !== null
         || previous.riskFactors.length > 0 || current.riskFactors.length > 0;
     if (hasRiskEvidence && !riskModelComparable(previous, current))

package/packages/cases/case-investigation-branch-model.mjs

@@ -0,0 +1,132 @@
+import { normalizeExplicitIsoTimestamp, normalizeLegacyIsoTimestamp } from "../evidence/observation.mjs";
+export const MAX_CASE_INVESTIGATION_BRANCHES = 8;
+export const MAX_CASE_BRANCH_NAME_LENGTH = 80;
+export const MAX_CASE_BRANCH_REFERENCES = 12;
+export const CASE_INVESTIGATION_BRANCH_STATES = ['active', 'resolved'];
+const SAFE_ID_RE = /^[A-Za-z0-9_-]{1,64}$/u;
+const CONTROL_REPLACE_RE = /[\u0000-\u001f\u007f]+/gu;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function text(value, maximum) {
+    return typeof value === 'string'
+        ? value.replace(CONTROL_REPLACE_RE, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        : '';
+}
+function iso(value, fallback, options = {}) {
+    return normalizeExplicitIsoTimestamp(value)
+        ?? (options.legacyTimestamps ? normalizeLegacyIsoTimestamp(value) : null)
+        ?? fallback;
+}
+function hash(value) {
+    let output = 2166136261 >>> 0;
+    for (let index = 0; index < value.length; index += 1) {
+        output ^= value.charCodeAt(index);
+        output = Math.imul(output, 16777619);
+    }
+    return (output >>> 0).toString(36);
+}
+function safeId(value, raw) {
+    return typeof value === 'string' && SAFE_ID_RE.test(value) ? value : `branch-${hash(JSON.stringify(raw))}`;
+}
+function freshId() {
+    return typeof globalThis.crypto?.randomUUID === 'function'
+        ? globalThis.crypto.randomUUID()
+        : `branch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function ids(value, valid) {
+    if (!Array.isArray(value))
+        return [];
+    const output = new Set();
+    for (const item of value.slice(0, MAX_CASE_BRANCH_REFERENCES * 2)) {
+        if (typeof item === 'string' && SAFE_ID_RE.test(item) && valid.has(item))
+            output.add(item);
+        if (output.size >= MAX_CASE_BRANCH_REFERENCES)
+            break;
+    }
+    return [...output];
+}
+function normalizeBranch(value, fallback, references, options = {}) {
+    const item = record(value);
+    const name = text(item.name, MAX_CASE_BRANCH_NAME_LENGTH);
+    if (!name)
+        return null;
+    const createdAt = iso(item.createdAt, fallback, options);
+    const branch = Object.freeze({
+        id: safeId(item.id, { name, createdAt }),
+        name,
+        state: item.state === 'resolved' ? 'resolved' : 'active',
+        evidencePinIds: Object.freeze(ids(item.evidencePinIds, references.evidencePinIds)),
+        checkpointIds: Object.freeze(ids(item.checkpointIds, references.checkpointIds)),
+        assertionIds: Object.freeze(ids(item.assertionIds, references.assertionIds)),
+        actionIds: Object.freeze(ids(item.actionIds, references.actionIds)),
+        createdAt,
+        updatedAt: iso(item.updatedAt, createdAt, options),
+    });
+    return branch.evidencePinIds.length || branch.checkpointIds.length || branch.assertionIds.length || branch.actionIds.length
+        ? branch
+        : null;
+}
+export function caseInvestigationBranchReferences(input) {
+    return Object.freeze({
+        evidencePinIds: new Set(input.evidencePins.map((item) => item.id)),
+        checkpointIds: new Set(input.evidencePins.flatMap((item) => item.checkpointId ? [item.checkpointId] : [])),
+        assertionIds: new Set(input.assertions.map((item) => item.id)),
+        actionIds: new Set(input.actions.map((item) => item.id)),
+    });
+}
+export function normalizeCaseInvestigationBranches(value, fallback, references, options = {}) {
+    if (!Array.isArray(value))
+        return [];
+    const byId = new Map();
+    for (const item of value.slice(0, MAX_CASE_INVESTIGATION_BRANCHES * 2)) {
+        const normalized = normalizeBranch(item, fallback, references, options);
+        if (!normalized)
+            continue;
+        const current = byId.get(normalized.id);
+        if (!current || normalized.updatedAt > current.updatedAt)
+            byId.set(normalized.id, normalized);
+    }
+    return [...byId.values()]
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id))
+        .slice(-MAX_CASE_INVESTIGATION_BRANCHES);
+}
+export function appendCaseInvestigationBranch(current, value, now, references) {
+    if (current.length >= MAX_CASE_INVESTIGATION_BRANCHES) {
+        throw new Error(`Each case is limited to ${MAX_CASE_INVESTIGATION_BRANCHES} investigation branches.`);
+    }
+    const item = record(value);
+    const branch = normalizeBranch({ ...item, id: freshId(), createdAt: now, updatedAt: now }, now, references);
+    if (!branch)
+        throw new Error('An investigation branch requires a name and at least one valid case reference.');
+    return normalizeCaseInvestigationBranches([...current, branch], now, references);
+}
+export function updateCaseInvestigationBranch(current, value, now, references) {
+    const patch = record(value);
+    const id = typeof patch.id === 'string' && SAFE_ID_RE.test(patch.id) ? patch.id : '';
+    const index = current.findIndex((item) => item.id === id);
+    if (index < 0)
+        throw new Error('That investigation branch no longer exists.');
+    const existing = current[index];
+    if (!existing)
+        throw new Error('That investigation branch no longer exists.');
+    const normalized = normalizeBranch({
+        ...existing,
+        ...(Object.hasOwn(patch, 'name') ? { name: patch.name } : {}),
+        ...(Object.hasOwn(patch, 'state') ? { state: patch.state } : {}),
+        ...(Object.hasOwn(patch, 'evidencePinIds') ? { evidencePinIds: patch.evidencePinIds } : {}),
+        ...(Object.hasOwn(patch, 'checkpointIds') ? { checkpointIds: patch.checkpointIds } : {}),
+        ...(Object.hasOwn(patch, 'assertionIds') ? { assertionIds: patch.assertionIds } : {}),
+        ...(Object.hasOwn(patch, 'actionIds') ? { actionIds: patch.actionIds } : {}),
+        id,
+        updatedAt: now,
+    }, now, references);
+    if (!normalized)
+        throw new Error('An investigation branch requires a name and at least one valid case reference.');
+    const next = [...current];
+    next[index] = normalized;
+    return normalizeCaseInvestigationBranches(next, now, references);
+}
+export function mergeCaseInvestigationBranches(local, imported, fallback, references) {
+    return normalizeCaseInvestigationBranches([...local, ...imported], fallback, references);
+}