@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/packages/cases/case-workflow-metadata.mjs

@@ -0,0 +1,217 @@
+// Typed analyst metadata; ordinary tags and assertions are always literal.
+import { MAX_CASE_ASSERTIONS, MAX_RESPONSE_RATIONALE_LENGTH, MAX_CASE_OBJECTIVE_LENGTH } from "../contracts/case-portability.mjs";
+import { caseInvestigationContext, prepareCaseInvestigationContext, parseIncidentUrlContext, normalizeCaseObjective } from "./case-incident-context.mjs";
+import { safeId, makeId } from "./case-record-core.mjs";
+import { array, enumeration, exact, iso, text } from "../evidence/artifact-structure.mjs";
+import { assertWorkspaceInputGraph } from "../workspace/hostile-input.mjs";
+// Preserve the maximum URL previously admitted inside a 21-character label.
+export const MAX_CASE_INCIDENT_TARGET_URL_LENGTH = MAX_RESPONSE_RATIONALE_LENGTH - 21;
+export const MAX_CASE_INCIDENT_TARGETS = 20;
+export const MAX_CASE_INCIDENT_TARGET_HISTORY = MAX_CASE_ASSERTIONS;
+export const CASE_TYPES = Object.freeze([
+    Object.freeze({ id: 'phishing', label: 'Phishing', description: 'Deceptive content or messages intended to obtain credentials or other sensitive information.' }),
+    Object.freeze({ id: 'impersonation', label: 'Impersonation', description: 'A domain, account or page presenting itself as another person or organisation.' }),
+    Object.freeze({ id: 'lookalike_cybersquatting', label: 'Lookalike or cybersquatting', description: 'A domain or account selected for review because it resembles or may exploit another name, brand or identifier.' }),
+    Object.freeze({ id: 'trademark_infringement', label: 'Trademark infringement', description: 'Potential unauthorised trademark use that may cause confusion about source or affiliation.' }),
+    Object.freeze({ id: 'copyright_infringement', label: 'Copyright infringement', description: 'Potential unauthorised copying or distribution of protected material.' }),
+    Object.freeze({ id: 'counterfeit_goods', label: 'Counterfeit goods', description: 'Promotion or sale of goods presented as genuine branded products.' }),
+    Object.freeze({ id: 'scam_fraud', label: 'Scam or fraud', description: 'Deceptive activity intended to obtain money, property or another benefit.' }),
+    Object.freeze({ id: 'malware_distribution', label: 'Malware distribution', description: 'Delivery, hosting or promotion of malicious software.' }),
+    Object.freeze({ id: 'credential_theft', label: 'Credential theft', description: 'Collection, sale or misuse of account credentials.' }),
+    Object.freeze({ id: 'spam_platform_abuse', label: 'Spam or platform abuse', description: 'Unsolicited or abusive platform activity that does not fit a narrower type.' }),
+    Object.freeze({ id: 'privacy_personal_data', label: 'Privacy or personal data', description: 'Potential exposure or misuse of personal information.' }),
+    Object.freeze({ id: 'account_compromise', label: 'Account compromise', description: 'Suspected unauthorised control or use of an account.' }),
+    Object.freeze({ id: 'other', label: 'Other', description: 'A reviewed type not covered by the current taxonomy.' }),
+]);
+const CASE_TYPE_IDS = new Set(CASE_TYPES.map((item) => item.id));
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const CASE_REFERENCE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export function readCaseTypes(value) {
+    assertWorkspaceInputGraph(value, 'Case types');
+    const selected = array(value, 'Case types', CASE_TYPES.length).map(id => {
+        if (typeof id !== 'string' || !CASE_TYPE_IDS.has(id))
+            throw new TypeError('Unknown Case type.');
+        return id;
+    });
+    if (new Set(selected).size !== selected.length)
+        throw new TypeError('Case types must be unique.');
+    return CASE_TYPES.map(item => item.id).filter(id => selected.includes(id));
+}
+export function caseTypeIds(record) {
+    return [...(record.workflowMetadata?.types ?? [])];
+}
+export function caseTypeRecords(record) {
+    const selected = new Set(caseTypeIds(record));
+    return CASE_TYPES.filter((item) => selected.has(item.id));
+}
+export function caseTypeSummary(record) {
+    const labels = caseTypeRecords(record).map((item) => item.label);
+    if (!labels.length)
+        return '';
+    if (labels.length <= 2)
+        return labels.join(' and ');
+    return `${labels.slice(0, 2).join(', ')} and ${labels.length - 2} more`;
+}
+function encodeCaseReference(value, minimumLength) {
+    let remainder = value;
+    let encoded = '';
+    do {
+        encoded = CASE_REFERENCE_ALPHABET[Number(remainder % 32n)] + encoded;
+        remainder /= 32n;
+    } while (remainder > 0n);
+    return encoded.padStart(minimumLength, '0');
+}
+/**
+ * Returns an unambiguous reference derived injectively from the immutable Case
+ * id. UUIDs use their complete 128-bit value. Legacy ids use every UTF-8 byte,
+ * its encoded length and a distinct namespace, so no shared counter or server
+ * is needed and imports retain the same reference.
+ */
+export function caseNumber(caseId) {
+    const id = typeof caseId === 'string' && caseId ? caseId : 'unknown';
+    if (UUID_RE.test(id)) {
+        return `WS-${encodeCaseReference(BigInt(`0x${id.replaceAll('-', '')}`), 26)}`;
+    }
+    const bytes = new TextEncoder().encode(id);
+    let encoded = 0n;
+    for (const byte of bytes)
+        encoded = encoded * 256n + BigInt(byte);
+    return `WS-L${encodeCaseReference(BigInt(bytes.length), 2)}-${encodeCaseReference(encoded, Math.ceil(bytes.length * 8 / 5))}`;
+}
+export function formattedCaseNumber(caseId) {
+    const value = caseNumber(caseId);
+    if (value.startsWith('WS-L'))
+        return value;
+    const separator = value.indexOf('-');
+    const prefix = value.slice(0, separator + 1);
+    const body = value.slice(separator + 1);
+    return `${prefix}${body.match(/.{1,5}/gu)?.join('-') ?? body}`;
+}
+export function normalizeCaseIncidentTargetUrl(value) {
+    if (typeof value !== 'string' || value.length > MAX_CASE_INCIDENT_TARGET_URL_LENGTH || !value.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password)
+        return null;
+    const normalized = parsed.toString();
+    return normalized.length <= MAX_CASE_INCIDENT_TARGET_URL_LENGTH ? normalized : null;
+}
+export { buildCaseIncidentCoverage } from "./case-object-coverage.mjs";
+export function emptyCaseWorkflowMetadata() {
+    return { types: [], incidentTargets: [], investigationContext: null };
+}
+function identifier(value) {
+    const id = safeId(value);
+    if (!id || id !== value)
+        throw new TypeError('Case metadata identity is invalid.');
+    return id;
+}
+/** Strict admission before persistence; no inferred defaults for typed fields. */
+export function readCaseWorkflowMetadata(value, domain) {
+    if (value === undefined)
+        return undefined;
+    assertWorkspaceInputGraph(value, 'Case workflow metadata');
+    const row = exact(value, ['types', 'incidentTargets', 'investigationContext'], 'Case workflow metadata');
+    const types = readCaseTypes(row.types);
+    const incidentTargets = array(row.incidentTargets, 'Incident target history', MAX_CASE_INCIDENT_TARGET_HISTORY).map(raw => {
+        const item = exact(raw, ['id', 'url', 'state', 'createdAt', 'updatedAt'], 'Incident target');
+        const url = normalizeCaseIncidentTargetUrl(item.url);
+        if (!url || url !== item.url)
+            throw new TypeError('Incident target URL is invalid.');
+        iso(item.createdAt, 'Incident target creation time');
+        iso(item.updatedAt, 'Incident target update time');
+        if (Date.parse(item.updatedAt) < Date.parse(item.createdAt))
+            throw new TypeError('Incident target update precedes creation.');
+        return { id: identifier(item.id), url, state: enumeration(item.state, ['open', 'resolved'], 'Incident target state'),
+            createdAt: item.createdAt, updatedAt: item.updatedAt };
+    });
+    if (new Set(incidentTargets.map(item => item.id)).size !== incidentTargets.length)
+        throw new TypeError('Incident target identities must be unique.');
+    let investigationContext = null;
+    if (row.investigationContext !== null) {
+        const item = exact(row.investigationContext, ['id', 'objective', 'incidentUrl', 'urlRetention', 'updatedAt'], 'Incident context');
+        const objective = text(item.objective, 'Investigation objective', MAX_CASE_OBJECTIVE_LENGTH);
+        if (!objective || normalizeCaseObjective(objective) !== objective)
+            throw new TypeError('Investigation objective is invalid.');
+        const parsed = parseIncidentUrlContext(item.incidentUrl);
+        const urlRetention = enumeration(item.urlRetention, ['exact', 'origin_only'], 'Incident URL retention');
+        if (!parsed || parsed.registrableDomain !== domain
+            || item.incidentUrl !== (urlRetention === 'exact' ? parsed.exactUrl : parsed.originUrl)) {
+            throw new TypeError('Incident context URL does not match its Case domain or retention choice.');
+        }
+        iso(item.updatedAt, 'Incident context update time');
+        investigationContext = { id: identifier(item.id), objective, incidentUrl: item.incidentUrl,
+            urlRetention, updatedAt: item.updatedAt };
+    }
+    return { types, incidentTargets, investigationContext };
+}
+/** Mutations use the existing Case save coordinator and compare-and-swap rules. */
+export function updateCaseWorkflowMetadata(current, patch, domain, now) {
+    const next = structuredClone(current);
+    if (patch.caseTypes !== undefined) {
+        if (patch.expectedCaseTypes !== undefined && JSON.stringify(readCaseTypes(patch.expectedCaseTypes)) !== JSON.stringify(current.types)) {
+            throw new Error('The Case types changed after this edit was started. Reopen the Case before saving; your draft was not applied.');
+        }
+        next.types = readCaseTypes(patch.caseTypes);
+    }
+    if (patch.incidentTarget !== undefined) {
+        const url = normalizeCaseIncidentTargetUrl(patch.incidentTarget);
+        if (!url)
+            throw new TypeError('Enter an exact HTTP(S) incident URL without embedded credentials.');
+        if (next.incidentTargets.some(target => target.state === 'open' && target.url === url))
+            throw new Error('That exact incident URL is already active in this Case.');
+        if (next.incidentTargets.filter(target => target.state === 'open').length >= MAX_CASE_INCIDENT_TARGETS)
+            throw new Error(`A Case can retain at most ${MAX_CASE_INCIDENT_TARGETS} active incident links. Resolve one before adding another.`);
+        if (next.incidentTargets.length >= MAX_CASE_INCIDENT_TARGET_HISTORY)
+            throw new Error(`The retained incident link history is full (${MAX_CASE_INCIDENT_TARGET_HISTORY}). Export this Case and open another; no history was removed.`);
+        next.incidentTargets.push({ id: makeId(), url, state: 'open', createdAt: now, updatedAt: now });
+    }
+    if (patch.incidentTargetResolution !== undefined) {
+        const id = identifier(patch.incidentTargetResolution);
+        const target = next.incidentTargets.find(item => item.id === id);
+        if (!target || target.state !== 'open')
+            throw new Error('That incident target is missing or already resolved. Refresh the Case before continuing.');
+        next.incidentTargets = next.incidentTargets.map(item => item.id === id ? { ...item, state: 'resolved', updatedAt: now } : item);
+    }
+    if (patch.investigationContext !== undefined) {
+        assertWorkspaceInputGraph(patch.investigationContext, 'New incident context');
+        const raw = exact(patch.investigationContext, ['objective', 'incidentUrl', 'retainExactUrl'], 'New incident context');
+        if (typeof raw.retainExactUrl !== 'boolean')
+            throw new TypeError('Choose whether to retain the exact incident URL.');
+        next.investigationContext = { ...prepareCaseInvestigationContext({ objective: raw.objective, incidentUrl: raw.incidentUrl, retainExactUrl: raw.retainExactUrl }),
+            id: current.investigationContext?.id ?? makeId(), updatedAt: now };
+    }
+    return readCaseWorkflowMetadata(next, domain);
+}
+/** Add missing targets, retaining the newer state for an existing identity. */
+export function mergeCaseWorkflowMetadata(local, incoming, importNewer, domain) {
+    const targets = new Map(local.incidentTargets.map(target => [target.id, target]));
+    for (const target of incoming.incidentTargets) {
+        const existing = targets.get(target.id);
+        if (existing && (existing.url !== target.url || existing.createdAt !== target.createdAt))
+            throw new TypeError('Imported incident target identity conflicts with retained history. No data was changed.');
+        if (!existing || Date.parse(target.updatedAt) > Date.parse(existing.updatedAt))
+            targets.set(target.id, target);
+    }
+    const left = local.investigationContext, right = incoming.investigationContext;
+    const investigationContext = right && (!left || Date.parse(right.updatedAt) > Date.parse(left.updatedAt)) ? right : left;
+    return readCaseWorkflowMetadata({ types: importNewer ? incoming.types : local.types,
+        incidentTargets: [...targets.values()], investigationContext }, domain);
+}
+export function caseIncidentTargets(record, options = {}) {
+    return (record.workflowMetadata?.incidentTargets ?? [])
+        .filter(target => options.includeResolved || target.state === 'open').map(target => ({ ...target }));
+}
+export function caseResponseIncidentUrls(record) {
+    const urls = new Set(caseIncidentTargets(record).map((target) => target.url));
+    const context = caseInvestigationContext(record);
+    if (context?.urlRetention === 'exact')
+        urls.add(context.incidentUrl);
+    return [...urls].slice(0, MAX_CASE_INCIDENT_TARGETS);
+}

package/packages/cases/case-workflow-migration.mjs

@@ -0,0 +1,43 @@
+// Read legacy text conventions once at the versioned storage/import boundary.
+// Keep the original assertions for references and historical evidence.
+import { CASE_TYPES, normalizeCaseIncidentTargetUrl, readCaseWorkflowMetadata } from "./case-workflow-metadata.mjs";
+import { normalizeTags } from "./case-record-core.mjs";
+import { normalizeCaseObjective, parseIncidentUrlContext } from "./case-incident-context.mjs";
+import { EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION } from "../contracts/case-portability.mjs";
+const TYPE_PREFIX = 'case-type:';
+const TARGET_PREFIX = 'Incident target URL: ';
+const CONTEXT_PREFIX = 'Investigate incident URL: ';
+const OBJECTIVE_PREFIX = 'Objective: ';
+const RETENTION_SEPARATOR = ' | URL retained: ';
+export function readCaseWorkflowFields(raw, domain, assertions, sourceVersion) {
+    const tags = normalizeTags(raw.tags);
+    if (raw.workflowMetadata !== undefined) {
+        if (sourceVersion != null && sourceVersion < EVIDENCE_FOLLOW_UP_CASE_SCHEMA_VERSION)
+            throw new TypeError('Typed workflow metadata requires the current Case schema.');
+        return { tags, workflowMetadata: readCaseWorkflowMetadata(raw.workflowMetadata, domain) };
+    }
+    const types = CASE_TYPES.filter(type => tags.some(tag => tag.toLowerCase() === `${TYPE_PREFIX}${type.id}`)).map(type => type.id);
+    const workflowMetadata = { types, incidentTargets: [], investigationContext: null };
+    for (const assertion of assertions) {
+        if (assertion.statement.startsWith(TARGET_PREFIX)) {
+            const url = normalizeCaseIncidentTargetUrl(assertion.statement.slice(TARGET_PREFIX.length));
+            if (url)
+                workflowMetadata.incidentTargets.push({ id: assertion.id, url, state: assertion.state, createdAt: assertion.createdAt, updatedAt: assertion.updatedAt });
+        }
+        if (assertion.kind !== 'next_step' || assertion.state !== 'open' || !assertion.statement.startsWith(CONTEXT_PREFIX))
+            continue;
+        const parsed = parseIncidentUrlContext(assertion.statement.slice(CONTEXT_PREFIX.length));
+        const rationale = assertion.rationale ?? '';
+        const index = rationale.lastIndexOf(RETENTION_SEPARATOR);
+        const objective = rationale.startsWith(OBJECTIVE_PREFIX) && index > OBJECTIVE_PREFIX.length
+            ? normalizeCaseObjective(rationale.slice(OBJECTIVE_PREFIX.length, index)) : '';
+        const retention = index >= 0 ? rationale.slice(index + RETENTION_SEPARATOR.length) : '';
+        if (!parsed || parsed.registrableDomain !== domain || !objective || (retention !== 'exact' && retention !== 'origin_only'))
+            continue;
+        workflowMetadata.investigationContext = { id: assertion.id, objective, urlRetention: retention,
+            incidentUrl: retention === 'exact' ? parsed.exactUrl : parsed.originUrl, updatedAt: assertion.updatedAt };
+    }
+    // Preserve historical text byte-for-byte where already normalised. Typed
+    // metadata becomes authoritative; subsequent tag edits never change types.
+    return { tags, workflowMetadata: readCaseWorkflowMetadata(workflowMetadata, domain) };
+}

package/packages/cases/http-summary.mjs

@@ -3,7 +3,7 @@
 // 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";
+import { MAX_HTTP_EVIDENCE_REDIRECTS } from "../analysis/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;
@@ -154,6 +154,11 @@ export function normalizeHttpSummary(value) {
         httpSecurityHeaders: securityHeaderTokens(record.httpSecurityHeaders),
     };
 }
+/** A partial body still permits comparison of observed response metadata. */
+export function httpSummaryFieldIsObserved(field, value) {
+    const summary = normalizeHttpSummary(value);
+    return summary !== null && Object.hasOwn(summary, field) && summary[field] !== null;
+}
 export function httpSecurityHeaderLabel(token) {
     const labels = {
         'content-security-policy': 'Content Security Policy',

package/packages/comparison/favicon-similarity.mjs

@@ -1,4 +1,4 @@
-import { hammingDistanceHex, isInformativePerceptualHash, isPerceptualHash, } from "../../lib/perceptual-hash-comparison.mjs";
+import { hammingDistanceHex, isInformativePerceptualHash, isPerceptualHash, } from "../analysis/perceptual-hash-comparison.mjs";
 function plainRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value

package/packages/comparison/page-similarity.mjs

@@ -3,7 +3,7 @@
 // produce an aggregate similarity score, risk factor, or maliciousness
 // verdict. Inputs pass through the strict baseline normalizer before use.
 import { normalizePageBaseline } from "../workspace/page-baseline.mjs";
-import { hammingDistanceHex } from "../../lib/perceptual-hash-comparison.mjs";
+import { hammingDistanceHex } from "../analysis/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) {

package/packages/comparison/relationship-evidence.mjs

@@ -3,11 +3,12 @@
 // proof of common ownership, coordination, intent, or maliciousness. This
 // module deliberately produces no aggregate score and is never a persistence
 // boundary.
-import { normalizeDomain } from "../cases/case-model.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { canonicalPublicIpAddress } from "../evidence/public-address-policy.mjs";
 import { groupBySimilarFavicon } from "./favicon-similarity.mjs";
-import { qualifyRelationshipSources, relationshipSourceEvidence, normalizeRelationshipSourceProjection, unknownRelationshipSource, MAX_RELATIONSHIP_SOURCES_PER_DOMAIN, } from "./relationship-provenance.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, };
+import { qualifyRelationshipSources, relationshipSourceEvidence, normalizeRelationshipSourceProjection, FAVICON_RELATIONSHIP_DESCRIPTION, unknownRelationshipSource, MAX_RELATIONSHIP_SOURCES_PER_DOMAIN, } from "./relationship-provenance.mjs";
+import { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_RELATIONSHIP_EVIDENCE_VERSIONS, RELATIONSHIP_SOURCE_PROVENANCE_VERSION, SUPPORTED_TLS_RELATIONSHIP_PROFILE_VERSIONS, TLS_RELATIONSHIP_PROFILE_VERSION, } from "../contracts/offline-comparison.mjs";
+export { RELATIONSHIP_EVIDENCE_SCHEMA, RELATIONSHIP_EVIDENCE_VERSION, SUPPORTED_RELATIONSHIP_EVIDENCE_VERSIONS, 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;
@@ -217,7 +218,7 @@ export function buildScanRelationships(rawRows) {
     for (const raw of input.slice(0, MAX_RELATIONSHIP_ROWS)) {
         const domain = normalizeDomain(raw?.domain);
         const observation = record(raw?.relationship);
-        if (!domain || raw?.trusted || !observation || ![2, RELATIONSHIP_EVIDENCE_VERSION].some((version) => version === observation.version))
+        if (!domain || raw?.trusted || !observation || !SUPPORTED_RELATIONSHIP_EVIDENCE_VERSIONS.some((version) => version === observation.version))
             continue;
         rows.push({ domain, observation });
         if (observation.truncated === true)
@@ -228,6 +229,7 @@ export function buildScanRelationships(rawRows) {
     const identifiers = new Map();
     const certificates = new Map();
     const officialAssets = new Map();
+    let excludedNonPublicAddresses = 0;
     for (const { domain, observation } of rows) {
         const nameserverSource = Array.isArray(observation.nameservers) ? observation.nameservers : [];
         const addressSource = Array.isArray(observation.ipAddresses) ? observation.ipAddresses : [];
@@ -239,8 +241,16 @@ export function buildScanRelationships(rawRows) {
         const nameservers = nameserverSource.slice(0, MAX_NAMESERVERS_PER_ROW).map(hostname).filter(Boolean);
         if (nameservers.length)
             addBucket(nameserverSets, [...new Set(nameservers)].sort().join(' · '), domain);
-        for (const value of addressSource.slice(0, MAX_IPS_PER_ROW))
-            addBucket(addresses, ipAddress(value), domain);
+        for (const value of addressSource.slice(0, MAX_IPS_PER_ROW)) {
+            const address = ipAddress(value);
+            if (!address)
+                continue;
+            const publicAddress = canonicalPublicIpAddress(address);
+            if (publicAddress)
+                addBucket(addresses, publicAddress, domain);
+            else
+                excludedNonPublicAddresses += 1;
+        }
         for (const value of identifierSource.slice(0, MAX_TRACKING_IDS_PER_ROW)) {
             if (typeof value === 'string' && /^[a-z-]{1,40}:[A-Z0-9-]{1,64}$/.test(value)) {
                 addBucket(identifiers, value, domain);
@@ -288,7 +298,7 @@ export function buildScanRelationships(rawRows) {
                     evidence?.faviconPHash ? `dhash:${evidence.faviconPHash}` : '',
                 ].filter(Boolean).join(',')}`;
             }).join('|');
-            output.push(group('favicon', 'Similar favicon', 'Exact SHA-256 or perceptual dHash distance ≤ 6', '', distinctDomains, 'These domains used an identical or perceptually similar favicon in this scan.', normalizedValue));
+            output.push(group('favicon', 'Connected favicon matches', 'Exact SHA-256 or perceptual dHash distance ≤ 6', '', distinctDomains, FAVICON_RELATIONSHIP_DESCRIPTION, normalizedValue));
         }
     }
     for (const [value, domains] of officialAssets)
@@ -317,7 +327,7 @@ export function buildScanRelationships(rawRows) {
                 const field = ARRAY_RELATIONSHIP_FIELDS[item.type];
                 if (field && Array.isArray(observation[field.field]) && observation[field.field].length > field.maximum)
                     groupTruncated = true;
-                const projection = observation.version === RELATIONSHIP_EVIDENCE_VERSION
+                const projection = Number(observation.version) >= RELATIONSHIP_SOURCE_PROVENANCE_VERSION
                     ? normalizeRelationshipSourceProjection(observation.sourceEvidence) : {};
                 for (const source of projection[item.type] ?? [unknownRelationshipSource()]) {
                     if (contributors.length >= MAX_RELATIONSHIP_DOMAINS * MAX_RELATIONSHIP_SOURCES_PER_DOMAIN)
@@ -331,8 +341,10 @@ export function buildScanRelationships(rawRows) {
     return {
         version: RELATIONSHIP_EVIDENCE_VERSION,
         groups,
+        excludedNonPublicAddresses,
         truncated,
         limitations: [
+            ...(excludedNonPublicAddresses ? [`${excludedNonPublicAddresses} non-public address observations were excluded from public-infrastructure grouping; their DNS answers remain in the scan evidence.`] : []),
             'Shared observations are investigation pivots, not proof of common ownership, coordination, intent, or maliciousness.',
             'Certificate relationships use exact native TLS leaf-certificate SHA-256 values only. Certificate Transparency counts and hostnames are never treated as certificate reuse.',
             'A shared certificate can reflect a multi-domain certificate, shared hosting, CDN, or managed platform and does not establish common control.',

package/packages/comparison/relationship-provenance.mjs

@@ -1,10 +1,16 @@
 // Only the source metadata needed to qualify an observed relationship crosses
 // this boundary. Collection and retention times are never source-time fallbacks.
-import { normalizeDomain } from "../cases/case-model.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { canonicalPublicIpAddress } from "../evidence/public-address-policy.mjs";
 import { normalizeExplicitIsoTimestamp, readObservationEnvelope } from "../evidence/observation.mjs";
 export const RELATIONSHIP_TYPES = Object.freeze([
     'nameserver_set', 'ip_address', 'certificate', 'tracking_identifier', 'favicon', 'official_asset',
 ]);
+export const NON_PUBLIC_RELATIONSHIP_LIMITATION = 'This is an equal non-public DNS answer, not evidence of shared public hosting. Private, loopback, reserved and sinkhole-style answers can recur independently.';
+export const FAVICON_RELATIONSHIP_DESCRIPTION = 'Each domain is connected by exact or bounded perceptual favicon matches, directly or through another member. Not every pair necessarily matches.';
+export function isNonPublicAddressRelationship(type, value) {
+    return type === 'ip_address' && !canonicalPublicIpAddress(value);
+}
 const SOURCES = ['dns', 'tls', 'http', 'page_identity', 'favicon', 'registration_or_dns', 'unknown'];
 const SOURCES_BY_TYPE = {
     nameserver_set: ['dns', 'registration_or_dns'], ip_address: ['dns'], certificate: ['tls'],

package/packages/contracts/analyst-interchange.mjs

@@ -3,9 +3,9 @@ import { buildExtractedLifecycleFamily } from "./extracted-domain-lifecycle.mjs"
 import { defineSchemaLifecycleFamily } from "./schema-lifecycle.mjs";
 export const ANALYST_INTERCHANGE_CONTRACT_OWNER = 'packages/contracts/analyst-interchange.mts';
 export const INVESTIGATION_CACAO_SPEC_VERSION = 'cacao-2.0';
-export const INVESTIGATION_CACAO_PROFILE_VERSION = 2;
-export const INVESTIGATION_CACAO_PROFILE_SEMVER = '2.0.0';
-export const INVESTIGATION_CACAO_SUPPORTED_PROFILE_VERSIONS = [INVESTIGATION_CACAO_PROFILE_VERSION];
+export const INVESTIGATION_CACAO_PROFILE_VERSION = 3;
+export const INVESTIGATION_CACAO_PROFILE_SEMVER = '3.0.0';
+export const INVESTIGATION_CACAO_SUPPORTED_PROFILE_VERSIONS = [2, INVESTIGATION_CACAO_PROFILE_VERSION];
 export const MAX_INVESTIGATION_CACAO_IMPORT_BYTES = 384 * 1024;
 export const BRAND_PROTECTION_OPERATIONS_REPORT_SCHEMA = 'whoisleuth.brand-protection-operations-report';
 export const BRAND_PROTECTION_OPERATIONS_REPORT_VERSION = 2;
@@ -18,6 +18,10 @@ export const STIX_INDICATOR_LIFECYCLE_SCHEMA = 'whoisleuth.internal.stix-indicat
 export const STIX_INDICATOR_EXPORT_VERSION = 2;
 export const MISP_INDICATOR_LIFECYCLE_SCHEMA = 'whoisleuth.internal.misp-indicators';
 export const MISP_INDICATOR_EXPORT_VERSION = 2;
+export const MANAGED_INDICATOR_SET_SCHEMA = 'whoisleuth.managed-indicator-set';
+export const MANAGED_INDICATOR_SET_VERSION = 1;
+export const MAX_MANAGED_INDICATOR_SET_BYTES = 4 * 1024 * 1024;
+export const MAX_MANAGED_INDICATOR_PLAN_BYTES = 16 * 1024 * 1024;
 export const DNS_CHANGE_REHEARSAL_VERSION = 2;
 export const DNS_CHANGE_REHEARSAL_EXPORT_SCHEMA = 'whoisleuth.dns-change-rehearsal';
 export const MAIL_REPORT_SCHEMA = 'whoisleuth.mail-report-review';
@@ -29,20 +33,22 @@ export const MAIL_REPORT_CANONICALIZATION_ROUTES = Object.freeze([
 export const REGISTRATION_DISCLOSURE_PLAN_SCHEMA = 'whoisleuth.registration-disclosure-plan';
 export const REGISTRATION_DISCLOSURE_PLAN_VERSION = 2;
 export const STATIC_PAGE_PATTERN_PACK_SCHEMA = 'whoisleuth.static-page-pattern-pack';
-export const STATIC_PAGE_PATTERN_PACK_VERSION = 2;
+export const STATIC_PAGE_PATTERN_PACK_VERSION = 3;
+export const STATIC_PAGE_PATTERN_PACK_SUPPORTED_VERSIONS = [2, STATIC_PAGE_PATTERN_PACK_VERSION];
 export const MAX_STATIC_PAGE_PATTERN_PACK_BYTES = 256 * 1024;
 export const WEB_CAPTURE_SUMMARY_SCHEMA = 'whoisleuth.web-capture-summary';
 export const WEB_CAPTURE_SUMMARY_VERSION = 1;
 export const WEB_CAPTURE_MANIFEST_SCHEMA = 'whoisleuth.web-capture-manifest';
-export const WEB_CAPTURE_MANIFEST_VERSION = 2;
+export const WEB_CAPTURE_MANIFEST_VERSION = 3;
+export const WEB_CAPTURE_MANIFEST_SUPPORTED_VERSIONS = [2, WEB_CAPTURE_MANIFEST_VERSION];
 export const MAX_WEB_CAPTURE_MANIFEST_BYTES = 1024 * 1024;
 const CACAO_COMPATIBILITY = defineSchemaCompatibility({
     id: 'export.investigation-cacao-profile', kind: 'export', schema: INVESTIGATION_CACAO_SPEC_VERSION,
     currentVersion: INVESTIGATION_CACAO_PROFILE_VERSION, supportedVersions: INVESTIGATION_CACAO_SUPPORTED_PROFILE_VERSIONS,
-    acceptsUnversionedLegacy: false, futureVersionBehavior: 'reject', migration: 'exact_current_only',
+    acceptsUnversionedLegacy: false, futureVersionBehavior: 'reject', migration: 'normalize_to_current',
     writeSemantics: 'non_destructive_merge', byteBudget: MAX_INVESTIGATION_CACAO_IMPORT_BYTES,
     owner: ANALYST_INTERCHANGE_CONTRACT_OWNER,
-    note: 'Restricted CACAO 2.0 profile with a connected linear sequence of manual analyst steps; version 2 adds fixed response recipe identifiers while executable commands, branches, targets, credentials, and arbitrary operations remain rejected.',
+    note: 'Restricted CACAO 2.0 manual profile. Version 3 retains optional lesson-revision provenance; public profile 2 remains readable. Executable commands, branches, targets and credentials remain rejected.',
 });
 const OPERATIONS_REPORT_COMPATIBILITY = defineSchemaCompatibility({
     id: 'export.brand-protection-operations-report', kind: 'export', schema: BRAND_PROTECTION_OPERATIONS_REPORT_SCHEMA,
@@ -72,6 +78,13 @@ const MISP_INDICATORS_COMPATIBILITY = defineSchemaCompatibility({
     writeSemantics: 'read_only', byteBudget: null, owner: ANALYST_INTERCHANGE_CONTRACT_OWNER,
     note: 'Unpublished, non-IDS, non-correlating event for reviewed import. Version 2 omits optional seen times when the source observation time is unknown.',
 });
+export const MANAGED_INDICATOR_SET_COMPATIBILITY = defineSchemaCompatibility({
+    id: 'export.managed-indicator-set', kind: 'export', schema: MANAGED_INDICATOR_SET_SCHEMA,
+    currentVersion: MANAGED_INDICATOR_SET_VERSION, supportedVersions: [MANAGED_INDICATOR_SET_VERSION],
+    acceptsUnversionedLegacy: false, futureVersionBehavior: 'reject', migration: 'exact_current_only',
+    writeSemantics: 'read_only', byteBudget: MAX_MANAGED_INDICATOR_SET_BYTES, owner: ANALYST_INTERCHANGE_CONTRACT_OWNER,
+    note: 'File-backed managed indicator revisions retain original observations, stable identities, explicit renewals and permanent withdrawals. Known predecessors prevent history replacement; content digests do not authenticate authorship or an unavailable earlier chain.',
+});
 const WEB_CAPTURE_SUMMARY_COMPATIBILITY = defineSchemaCompatibility({
     id: 'export.web-capture-summary', kind: 'export', schema: WEB_CAPTURE_SUMMARY_SCHEMA,
     currentVersion: WEB_CAPTURE_SUMMARY_VERSION, supportedVersions: [WEB_CAPTURE_SUMMARY_VERSION],
@@ -81,11 +94,11 @@ const WEB_CAPTURE_SUMMARY_COMPATIBILITY = defineSchemaCompatibility({
 });
 const WEB_CAPTURE_MANIFEST_COMPATIBILITY = defineSchemaCompatibility({
     id: 'export.web-capture-manifest', kind: 'export', schema: WEB_CAPTURE_MANIFEST_SCHEMA,
-    currentVersion: WEB_CAPTURE_MANIFEST_VERSION, supportedVersions: [WEB_CAPTURE_MANIFEST_VERSION],
+    currentVersion: WEB_CAPTURE_MANIFEST_VERSION, supportedVersions: WEB_CAPTURE_MANIFEST_SUPPORTED_VERSIONS,
     acceptsUnversionedLegacy: false, futureVersionBehavior: 'reject', migration: 'read_only',
     writeSemantics: 'read_only', byteBudget: MAX_WEB_CAPTURE_MANIFEST_BYTES,
     owner: ANALYST_INTERCHANGE_CONTRACT_OWNER,
-    note: 'Metadata-only capture manifest; the browser and offline artefact comparison accept the v1.47.4 current-writer version 2.',
+    note: 'Metadata-only capture manifest. Version 3 adds bounded page and dependency observations; version 2 remains readable with those observations unavailable.',
 });
 const DEFENSIVE_MANIFEST_COMPATIBILITY = defineSchemaCompatibility({
     id: 'export.defensive-indicator-manifest', kind: 'export', schema: DEFENSIVE_INDICATOR_MANIFEST_SCHEMA,
@@ -124,11 +137,11 @@ const REGISTRATION_DISCLOSURE_COMPATIBILITY = defineSchemaCompatibility({
 });
 const STATIC_PATTERN_PACK_COMPATIBILITY = defineSchemaCompatibility({
     id: 'export.static-page-pattern-pack', kind: 'export', schema: STATIC_PAGE_PATTERN_PACK_SCHEMA,
-    currentVersion: STATIC_PAGE_PATTERN_PACK_VERSION, supportedVersions: [STATIC_PAGE_PATTERN_PACK_VERSION],
-    acceptsUnversionedLegacy: false, futureVersionBehavior: 'reject', migration: 'exact_current_only',
+    currentVersion: STATIC_PAGE_PATTERN_PACK_VERSION, supportedVersions: STATIC_PAGE_PATTERN_PACK_SUPPORTED_VERSIONS,
+    acceptsUnversionedLegacy: false, futureVersionBehavior: 'reject', migration: 'read_only',
     writeSemantics: 'non_destructive_merge', byteBudget: MAX_STATIC_PAGE_PATTERN_PACK_BYTES,
     owner: ANALYST_INTERCHANGE_CONTRACT_OWNER,
-    note: 'Exact-current bounded page-pattern pack imported by explicit analyst action and merged without executing code or starting collection.',
+    note: 'Versions 2 and 3 remain readable. Version 3 can use attributed password-form destinations; older rules retain their declared meaning. Import remains explicit and does not execute code or start collection.',
 });
 export function serialiseAnalystInterchangeJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
@@ -141,12 +154,17 @@ export const ANALYST_INTERCHANGE_LIFECYCLE_FAMILY = defineSchemaLifecycleFamily(
     includedCategories: ['reviewed-indicators', 'source-identity', 'provenance', 'completeness', 'omitted-counts', 'limitations'],
     excludedCategories: ['credentials', 'cookies', 'message-content', 'raw-upstream-responses', 'expanded-contacts'],
     formats: [
+        { descriptor: MANAGED_INDICATOR_SET_COMPATIBILITY, lifecycleSchema: MANAGED_INDICATOR_SET_SCHEMA,
+            requiredKeys: ['schema', 'version', 'id', 'producerId', 'revisionId', 'name', 'revision', 'createdAt', 'modifiedAt', 'previous', 'entries', 'integrity'], optionalKeys: [],
+            hook: { module: 'packages/interchange/managed-indicator-set.mts', exportName: 'validateManagedIndicatorSet', role: 'structure_validator', runtime: 'shared' },
+            fixtures: [{ id: 'managed-indicator-set-v1', path: `${F}managed-indicator-set-v1.json`, bytes: 1_193, sha256: '3a4ffb7256e696d1f1b3bae14743bb8c03ddeb0922186868e935f5a489ba3985', version: MANAGED_INDICATOR_SET_VERSION }] },
         { descriptor: CACAO_COMPATIBILITY, lifecycleSchema: INVESTIGATION_CACAO_SPEC_VERSION,
             requiredKeys: ['type', 'spec_version', 'id', 'name', 'created', 'modified', 'workflow_start', 'workflow', 'extension_definitions'],
             optionalKeys: ['description', 'playbook_types', 'playbook_activities', 'created_by', 'playbook_extensions', 'agent_definitions', 'x_whoisleuth_profile_version'],
             hook: { module: 'packages/interchange/investigation-playbook-interchange.mts', exportName: 'parseCacaoInvestigationPlaybook', role: 'normaliser', runtime: 'shared' },
             fixtures: [
-                { id: 'investigation-cacao-profile-v2', path: `${F}investigation-cacao-profile-v2.json`, bytes: 4_091, sha256: '7e9a3de6e12b83477690c0c58e03e6efbbb8b0c11fd98dc8470bdb6784d42358', version: INVESTIGATION_CACAO_PROFILE_VERSION },
+                { id: 'investigation-cacao-profile-v2', path: `${F}investigation-cacao-profile-v2.json`, bytes: 4_091, sha256: '7e9a3de6e12b83477690c0c58e03e6efbbb8b0c11fd98dc8470bdb6784d42358', version: 2 },
+                { id: 'investigation-cacao-profile-v3', path: `${F}investigation-cacao-profile-v3.json`, bytes: 4_067, sha256: '608cbb7875c3448ca11f6f8cb2f96ae098e18316532a8f651bbe540ca7f25a2d', version: INVESTIGATION_CACAO_PROFILE_VERSION },
             ] },
         { descriptor: OPERATIONS_REPORT_COMPATIBILITY, lifecycleSchema: BRAND_PROTECTION_OPERATIONS_REPORT_SCHEMA,
             requiredKeys: ['schema', 'version', 'generatedAt', 'window', 'limitations'], optionalKeys: ['sourceState', 'summary', 'counts', 'states', 'actionTypes', 'durations', 'denominators', 'omissions'],
@@ -182,7 +200,8 @@ export const ANALYST_INTERCHANGE_LIFECYCLE_FAMILY = defineSchemaLifecycleFamily(
             requiredKeys: ['schema', 'schemaVersion', 'source', 'captures'], optionalKeys: [],
             hook: { module: 'packages/interchange/web-capture-import.mts', exportName: 'parseWebCaptureManifest', role: 'normaliser', runtime: 'shared' },
             fixtures: [
-                { id: 'web-capture-manifest-v2', path: `${F}web-capture-manifest-v2.json`, bytes: 494, sha256: 'a2208dc956a832d70e37cd9a5929db81d29148856c485e4fd6ce5b123de5b8e6', version: WEB_CAPTURE_MANIFEST_VERSION },
+                { id: 'web-capture-manifest-v2', path: `${F}web-capture-manifest-v2.json`, bytes: 494, sha256: 'a2208dc956a832d70e37cd9a5929db81d29148856c485e4fd6ce5b123de5b8e6', version: 2 },
+                { id: 'web-capture-manifest-v3', path: `${F}web-capture-manifest-v3.json`, bytes: 868, sha256: 'bca4e8cb539ac6035dd44586fa7e27774766a14dadbc4fc73cad2b71dace2ac8', version: WEB_CAPTURE_MANIFEST_VERSION },
             ] },
         { descriptor: DEFENSIVE_MANIFEST_COMPATIBILITY, lifecycleSchema: DEFENSIVE_INDICATOR_MANIFEST_SCHEMA,
             requiredKeys: ['schema', 'version', 'generatedAt'], optionalKeys: ['expiresAt', 'reviewRequired', 'explicitSelection', 'includeWildcards', 'entries', 'indicators', 'exclusions', 'limitations'],
@@ -211,6 +230,7 @@ export const ANALYST_INTERCHANGE_LIFECYCLE_FAMILY = defineSchemaLifecycleFamily(
         { descriptor: STATIC_PATTERN_PACK_COMPATIBILITY, lifecycleSchema: STATIC_PAGE_PATTERN_PACK_SCHEMA,
             requiredKeys: ['schema', 'version', 'id', 'label', 'description', 'evidenceBoundary', 'relationship', 'confidence', 'rules'], optionalKeys: [],
             hook: { module: 'packages/interchange/static-page-pattern-packs.mts', exportName: 'validateStaticPagePatternPack', role: 'structure_validator', runtime: 'shared' },
-            fixtures: [{ id: 'static-page-pattern-pack-v2', path: `${F}static-page-pattern-pack-v2.json`, bytes: 1_094, sha256: 'c409e527850bcb924f5be0708a58c5e2c32d98947c42150f6a79765991c0eb6f', version: STATIC_PAGE_PATTERN_PACK_VERSION }] },
+            fixtures: [{ id: 'static-page-pattern-pack-v2', path: `${F}static-page-pattern-pack-v2.json`, bytes: 1_094, sha256: 'c409e527850bcb924f5be0708a58c5e2c32d98947c42150f6a79765991c0eb6f', version: 2 },
+                { id: 'static-page-pattern-pack-v3', path: `${F}static-page-pattern-pack-v3.json`, bytes: 746, sha256: '5be19b621ad604de8c430191a34fcd2d624b22b8bdf9a5cb2653ef7d1b86c71a', version: 3 }] },
     ],
 }));

package/packages/contracts/candidate-watch-review.mjs

@@ -0,0 +1,54 @@
+import { defineSchemaCompatibility } from "./schema-compatibility.mjs";
+import { defineSchemaLifecycleFamily } from "./schema-lifecycle.mjs";
+import { buildExtractedLifecycleFamily } from "./extracted-domain-lifecycle.mjs";
+import { MAX_WATCHLIST_IMPORT_BYTES } from "./workspace-portability.mjs";
+export const CANDIDATE_WATCH_INPUT_SCHEMA = 'whoisleuth.candidate-watch-input';
+export const CANDIDATE_WATCH_INPUT_VERSION = 1;
+export const CANDIDATE_WATCH_INPUT_COMPATIBILITY = defineSchemaCompatibility({
+    id: 'cli.candidate-watch-input',
+    kind: 'cli_document',
+    schema: CANDIDATE_WATCH_INPUT_SCHEMA,
+    currentVersion: 1,
+    supportedVersions: [1],
+    acceptsUnversionedLegacy: false,
+    futureVersionBehavior: 'reject',
+    migration: 'exact_current_only',
+    writeSemantics: 'read_only',
+    byteBudget: MAX_WATCHLIST_IMPORT_BYTES,
+    owner: 'packages/contracts/candidate-watch-review.mts',
+    note: 'Bounded offline analyst selection and optional portable Watchlist document; no collection or schedule authority.',
+});
+export const CANDIDATE_WATCH_REVIEW_LIFECYCLE_FAMILY = defineSchemaLifecycleFamily(buildExtractedLifecycleFamily({
+    id: 'candidate-watch-review',
+    owner: 'packages/contracts/candidate-watch-review.mts',
+    plane: 'node',
+    projection: 'review_output',
+    retention: 'transient_report',
+    serializerModule: 'cli/formatters/json.mts',
+    serializerExportName: 'formatJsonDocument',
+    includedCategories: ['candidate-provenance', 'analyst-watch-reasons', 'review-priorities'],
+    excludedCategories: ['raw-upstream-payloads', 'credentials', 'cookies', 'query-bearing-urls'],
+    formats: [
+        {
+            descriptor: CANDIDATE_WATCH_INPUT_COMPATIBILITY,
+            lifecycleSchema: CANDIDATE_WATCH_INPUT_SCHEMA,
+            requiredKeys: ['schema', 'version', 'watchlists', 'selection'],
+            optionalKeys: [],
+            hook: {
+                module: 'cli/watchlist-review.mts',
+                exportName: 'parseCandidateWatchInput',
+                role: 'structure_validator',
+                runtime: 'node',
+            },
+            fixtures: [
+                {
+                    id: 'candidate-watch-input-v1',
+                    path: 'test/fixtures/brand-candidate-workflow/candidate-watch-input-v1.json',
+                    bytes: 895,
+                    sha256: '40a0d73e5aa3afc3b6836bb289c79cf9556dd755a5086a9666506b31468b5d3d',
+                    version: 1,
+                },
+            ],
+        },
+    ],
+}));