@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/packages/investigation/identity-incident-review.mjs

@@ -0,0 +1,39 @@
+import { array, enumeration, exact } from "../evidence/artifact-structure.mjs";
+import { IDENTITY_ACTIONS } from "../contracts/message-intake.mjs";
+/** Reported actions select recovery guidance; they do not establish compromise. */
+export function reviewIdentityIncident(value) {
+    const input = exact(value, ['reportedActions'], 'Identity incident review');
+    const allowed = IDENTITY_ACTIONS.map(action => action.id);
+    const reportedActions = [...new Set(array(input.reportedActions, 'Reported actions', allowed.length)
+            .map(item => enumeration(item, allowed, 'Reported action')))];
+    const has = (...actions) => actions.some(action => reportedActions.includes(action));
+    const nextSteps = [];
+    const add = (id, title, detail) => nextSteps.push({ id, title, detail });
+    if (reportedActions.length)
+        add('preserve', 'Preserve the message and sign-in timeline', 'Record the reported time and action, retain relevant account audit events and keep the original privately. Use an independently known account portal, not the supplied link.');
+    if (has('entered_password', 'approved_signin', 'entered_device_code')) {
+        add('sessions', 'Review and revoke suspicious account sessions', 'Use the identity provider’s documented response process. Review recent sign-ins, new authentication methods and registered devices; resetting a password alone may not invalidate existing sessions.');
+    }
+    if (has('entered_password'))
+        add('password', 'Change exposed and reused credentials', 'Change the affected password through a trusted route. Review other accounts where the same credential was used, without testing the supplied site.');
+    if (has('granted_consent', 'entered_device_code'))
+        add('grants', 'Review application grants and tokens', 'Identify the application/client ID in account audit records. Revoke unwanted consent and refresh tokens using the provider’s controls; check accessed mail and files and newly created inbox rules.');
+    if (has('executed_command'))
+        add('endpoint', 'Escalate for endpoint containment', 'Stop using the affected device for account recovery. Follow the organisation’s endpoint incident process, preserve the command as inert evidence and use a separate trusted device.');
+    if (has('entered_password', 'approved_signin', 'entered_device_code', 'granted_consent'))
+        add('persistence', 'Check persistence and downstream access', 'Review forwarding rules, delegates, newly authorised applications and affected data. Record the findings independently of public domain evidence.');
+    if (reportedActions.length)
+        add('followup', 'Record recovery actions and a follow-up', 'Track account recovery separately from provider reports and domain availability. A removed page does not show that an account session or application grant was revoked.');
+    return { reportedActions, nextSteps };
+}
+/** A deliberate follow-up request, never a completed recovery or compromise claim. */
+export function identityRecoveryFollowUp(reportedActions, stepId) {
+    const review = reviewIdentityIncident({ reportedActions });
+    const step = review.nextSteps.find(item => item.id === stepId);
+    if (!step)
+        throw new TypeError('Select a recommendation supported by the reported actions.');
+    return {
+        statement: `Requested follow-up: ${step.title}`,
+        rationale: `Conditional analyst request based on reported actions, not independently verified account telemetry. ${step.detail} No recovery action or independent result is established by this request.`,
+    };
+}

package/packages/investigation/incident-sequence-review.mjs

@@ -0,0 +1,58 @@
+import { CASE_PIN_COMPLETENESS } from "../cases/case-response-records.mjs";
+import { MAX_RESPONSE_VALUE_LENGTH, MAX_RESPONSE_LABEL_LENGTH, MAX_RESPONSE_LIMITATIONS, MAX_RESPONSE_LIMITATION_LENGTH } from "../contracts/case-portability.mjs";
+import { CONTEXT_REVIEW_SCHEMA, CONTEXT_REVIEW_VERSION, MAX_CONTEXT_RECORDS } from "../contracts/context-review.mjs";
+import { array, domain, enumeration, exact, HEX_DIGEST_RE, iso, text } from "../evidence/artifact-structure.mjs";
+export { INCIDENT_SEQUENCE_INPUT_SCHEMA, INCIDENT_SEQUENCE_INPUT_VERSION } from "../contracts/context-review.mjs";
+export const INCIDENT_STAGE_KINDS = ['message', 'navigation', 'identity_prompt', 'credential_entry', 'consent', 'browser_instruction', 'clipboard', 'local_execution', 'payment', 'recovery', 'other'];
+export const INCIDENT_STAGE_BASES = ['retained_observation', 'imported_record', 'reported_action'];
+export function readIncidentStages(raw) {
+    const stages = array(raw, 'Incident stages', MAX_CONTEXT_RECORDS).map(value => {
+        const row = exact(value, ['id', 'kind', 'basis', 'description', 'occurredAt', 'hostname', 'source', 'reference', 'referenceSha256', 'completeness', 'limitations'], 'Incident stage');
+        const id = text(row.id, 'Stage ID', 64);
+        if (!/^[A-Za-z0-9_-]+$/u.test(id))
+            throw new TypeError('Stage ID must be a bounded identifier.');
+        iso(row.occurredAt, 'Stage occurrence time', true);
+        if (row.hostname !== null)
+            domain(row.hostname, 'Stage hostname');
+        if (row.referenceSha256 !== null && (typeof row.referenceSha256 !== 'string' || !HEX_DIGEST_RE.test(row.referenceSha256)))
+            throw new TypeError('Stage reference digest must be hexadecimal SHA-256 or null.');
+        return { id, kind: enumeration(row.kind, INCIDENT_STAGE_KINDS, 'Stage kind'), basis: enumeration(row.basis, INCIDENT_STAGE_BASES, 'Stage basis'),
+            description: text(row.description, 'Stage description', MAX_RESPONSE_VALUE_LENGTH), occurredAt: row.occurredAt, hostname: row.hostname,
+            source: text(row.source, 'Stage source', MAX_RESPONSE_LABEL_LENGTH), reference: text(row.reference, 'Stage reference', 500), referenceSha256: row.referenceSha256,
+            completeness: enumeration(row.completeness, CASE_PIN_COMPLETENESS, 'Stage completeness'),
+            limitations: array(row.limitations, 'Stage limitations', MAX_RESPONSE_LIMITATIONS).map(item => text(item, 'Stage limitation', MAX_RESPONSE_LIMITATION_LENGTH)), };
+    });
+    if (new Set(stages.map(row => row.id)).size !== stages.length)
+        throw new TypeError('Incident stage IDs must be unique.');
+    return stages;
+}
+/** Copy the selected pin's provenance without giving it stronger assurance. */
+export function incidentStageFromPin(pin, kind, id) {
+    return readIncidentStages([{ id, kind, basis: 'retained_observation', description: pin.value, occurredAt: pin.observedAt,
+            hostname: pin.observationHostname ?? null, source: pin.source, reference: pin.id, referenceSha256: pin.importContentSha256 ?? null,
+            completeness: pin.truncated === true && pin.completeness === 'complete' ? 'partial' : pin.completeness, limitations: [...pin.limitations],
+        }])[0];
+}
+export function reviewIncidentSequence(raw, reviewedAt) {
+    iso(reviewedAt, 'Review time');
+    const stages = readIncidentStages(raw);
+    const counts = Object.fromEntries(INCIDENT_STAGE_BASES.map(basis => [basis, stages.filter(row => row.basis === basis).length]));
+    let priorTime = null, reversedTimes = 0;
+    for (const row of stages) {
+        if (row.occurredAt === null)
+            continue;
+        const time = Date.parse(row.occurredAt);
+        if (priorTime !== null && time < priorTime)
+            reversedTimes++;
+        priorTime = time;
+    }
+    return { schema: CONTEXT_REVIEW_SCHEMA, version: CONTEXT_REVIEW_VERSION, kind: 'incident_sequence', reviewedAt, title: 'Incident sequence',
+        state: !stages.length || stages.some(row => row.occurredAt === null || row.completeness !== 'complete') || reversedTimes ? 'partial' : 'reviewed',
+        summary: `Analyst-ordered stages: ${stages.length} (retained observations: ${counts.retained_observation}; imported records: ${counts.imported_record}; reported actions: ${counts.reported_action}).${reversedTimes ? ` Timestamp reversals needing review: ${reversedTimes}; the selected order was preserved.` : ''}`,
+        observations: stages.map((row, index) => ({ label: `${index + 1}. ${row.kind.replaceAll('_', ' ')} · ${row.basis.replaceAll('_', ' ')}`,
+            state: row.completeness === 'complete' ? 'reported' : 'partial', detail: `${row.description} · Source completeness: ${row.completeness}.${row.limitations.length ? ` ${row.limitations.join(' ')}` : ''}`,
+            source: `${row.source} · reference ${row.reference}${row.referenceSha256 ? ` · reference SHA-256 ${row.referenceSha256}` : ''}`, observedAt: row.occurredAt, hostname: row.hostname })),
+        nextSteps: ['Compare stages with the selected message and capture records; retain gaps and conflicting source times.', 'Use reported credential entry, consent or local execution to select the relevant account or device recovery review, separately from domain reporting.'],
+        limitations: ['Order is analyst-selected, not proof of causation or a verified attack chain. An instruction, prompt or clipboard attempt does not establish that a person followed it.', 'Sources, occurrence times and reference digests retain their supplied meaning; importing this input does not authenticate them. Unknown times are not replaced by review or save time.'],
+    };
+}

package/packages/investigation/infrastructure-observation.mjs

@@ -0,0 +1,234 @@
+// Source-qualified, privacy-minimised retained infrastructure evidence. No collector
+// or store lives here; supplied observations never initiate network work.
+import { exact, text, enumeration, array, strings, iso, boolean } from "../evidence/artifact-structure.mjs";
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { canonicalIpAddress } from "../contracts/ip-address.mjs";
+import { parseBoundedJson } from "../analysis/bounded-json.mjs";
+import { technologyEvidenceRoles } from "../evidence/technology-evidence-role.mjs";
+import { INFRASTRUCTURE_OBSERVATION_SCHEMA, INFRASTRUCTURE_OBSERVATION_VERSION, MAX_INFRASTRUCTURE_OBSERVATION_BYTES, MAX_INFRASTRUCTURE_HOSTS, MAX_INFRASTRUCTURE_DNS_ROWS, MAX_INFRASTRUCTURE_CERTIFICATES, MAX_INFRASTRUCTURE_ROLES, MAX_INFRASTRUCTURE_SOURCES, MAX_INFRASTRUCTURE_LIMITATIONS, INFRASTRUCTURE_DNS_TYPES, } from "../contracts/external-observation-interchange.mjs";
+export { INFRASTRUCTURE_OBSERVATION_SCHEMA, INFRASTRUCTURE_OBSERVATION_VERSION, MAX_INFRASTRUCTURE_OBSERVATION_BYTES };
+export { MAX_INFRASTRUCTURE_HOSTS, MAX_INFRASTRUCTURE_DNS_ROWS, MAX_INFRASTRUCTURE_CERTIFICATES, MAX_INFRASTRUCTURE_ROLES, INFRASTRUCTURE_DNS_TYPES };
+export const INFRASTRUCTURE_SOURCE_FAMILIES = ['dns', 'certificate_log', 'tls', 'technology', 'ip_registration', 'routing', 'origin_observation', 'analyst'];
+export const INFRASTRUCTURE_PROVIDER_ROLES = ['dns_operator', 'observed_edge', 'application_platform', 'framework_runtime', 'embedded_dependency', 'address_registration', 'routing_origin', 'observed_origin'];
+export function infrastructureCohortLabel(cohort) {
+    switch (cohort.kind) {
+        case 'dns': return `Query ${cohort.queriedName} · owner ${cohort.ownerName} · ${cohort.type} ${cohort.aspect}`;
+        case 'certificate_names': return `Certificate SHA-256 ${cohort.fingerprintSha256}`;
+        case 'provider_role': return `${cohort.subjectType} ${cohort.subject} · ${cohort.role}`;
+    }
+}
+function hostname(raw) {
+    const value = text(raw, 'Infrastructure hostname', 253);
+    if (normalizeDomain(value) !== value)
+        throw new TypeError('Infrastructure hostnames must be exact canonical hostnames.');
+    return value;
+}
+function name(raw) {
+    const value = text(raw, 'Certificate name', 255);
+    hostname(value.startsWith('*.') ? value.slice(2) : value);
+    return value;
+}
+function identifier(raw, label) {
+    const value = text(raw, label, 120);
+    if (!/^[a-zA-Z0-9_-]+$/u.test(value))
+        throw new TypeError(`${label} must use a bounded portable identity.`);
+    return value;
+}
+function unique(values, label, key = value => String(value)) {
+    if (new Set(values.map(key)).size !== values.length)
+        throw new TypeError(`${label} contains duplicate or ambiguous identities.`);
+    return values;
+}
+function at(raw) { iso(raw, 'Infrastructure observation time'); return new Date(raw).toISOString(); }
+function flag(raw) { boolean(raw, 'Infrastructure completeness'); return raw; }
+/** Exact current reader. Old Case pins lacking this field remain unknown, never reconstructed. */
+export function readInfrastructureObservation(raw) {
+    // Bound hostile object traversal before serialisation or parsing work.
+    const root = exact(raw, ['schema', 'version', 'id', 'target', 'observedAt', 'mode', 'scope', 'coverage', 'sources', 'dns', 'certificates', 'roles', 'limitations'], 'Infrastructure snapshot');
+    if (root.schema !== INFRASTRUCTURE_OBSERVATION_SCHEMA || root.version !== INFRASTRUCTURE_OBSERVATION_VERSION)
+        throw new TypeError('Unsupported infrastructure snapshot schema or version.');
+    const scope = exact(root.scope, ['hostnames', 'dnsTypes', 'selection'], 'Infrastructure scope');
+    const selection = enumeration(scope.selection, ['explicit_hosts', 'certificate_names'], 'Selection scope');
+    const hostnames = unique(array(scope.hostnames, 'Selected hostnames', MAX_INFRASTRUCTURE_HOSTS, selection === 'explicit_hosts' ? 1 : 0).map(hostname), 'Selected hostnames');
+    const dnsTypes = unique(array(scope.dnsTypes, 'Selected DNS types', INFRASTRUCTURE_DNS_TYPES.length).map(value => enumeration(value, INFRASTRUCTURE_DNS_TYPES, 'DNS type')), 'Selected DNS types');
+    const coverage = exact(root.coverage, ['state', 'truncated', 'detail'], 'Infrastructure coverage');
+    const sources = unique(array(root.sources, 'Infrastructure sources', MAX_INFRASTRUCTURE_SOURCES, 1).map(rawSource => {
+        const source = exact(rawSource, ['id', 'name', 'family', 'evidenceClass', 'reference'], 'Infrastructure source');
+        const reference = source.reference === null ? null : text(source.reference, 'Source reference', 300);
+        if (reference !== null && /[?#]|\b(?:cookie|password|bearer)\s*[:=]/iu.test(reference))
+            throw new TypeError('Source references must not retain query strings, fragments or credentials.');
+        if (reference?.includes('://')) {
+            let url;
+            try {
+                url = new URL(reference);
+            }
+            catch {
+                throw new TypeError('Source reference URL is invalid.');
+            }
+            if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+                throw new TypeError('Source references cannot retain credentials or unsafe URL schemes.');
+        }
+        return { id: identifier(source.id, 'Source ID'), name: text(source.name, 'Source name', 80), family: enumeration(source.family, INFRASTRUCTURE_SOURCE_FAMILIES, 'Source family'), evidenceClass: enumeration(source.evidenceClass, ['local_observation', 'provider_report'], 'Evidence class'), reference };
+    }), 'Source IDs', value => value.id);
+    const sourceMap = new Map(sources.map(value => [value.id, value]));
+    function sourceId(rawId, families) {
+        const id = identifier(rawId, 'Observation source ID'), source = sourceMap.get(id);
+        if (!source || !families.includes(source.family))
+            throw new TypeError('An observation requires its own matching source family.');
+        return id;
+    }
+    const dns = array(root.dns, 'DNS observations', MAX_INFRASTRUCTURE_DNS_ROWS).map(rawRow => {
+        const row = exact(rawRow, ['sourceId', 'queriedName', 'ownerName', 'type', 'observedAt', 'outcome', 'values', 'complete', 'truncated'], 'DNS observation');
+        const type = enumeration(row.type, INFRASTRUCTURE_DNS_TYPES, 'DNS type');
+        const queriedName = hostname(row.queriedName), ownerName = hostname(row.ownerName);
+        if (!hostnames.includes(queriedName) || !dnsTypes.includes(type))
+            throw new TypeError('DNS observation falls outside its explicit selected scope.');
+        const outcome = enumeration(row.outcome, ['answered', 'no_data', 'nxdomain', 'failed', 'not_checked'], 'DNS outcome');
+        const values = unique(array(row.values, 'DNS record values', 32).map(rawValue => {
+            const value = text(rawValue, 'DNS value', 300);
+            if (type === 'A' || type === 'AAAA') {
+                const address = canonicalIpAddress(value);
+                if (address !== value || (type === 'A') !== !value.includes(':'))
+                    throw new TypeError('DNS address value does not match its type.');
+            }
+            else if (type === 'MX') {
+                const match = /^(\d{1,5}) ([a-z0-9.-]+)$/u.exec(value);
+                if (!match || Number(match[1]) > 65535)
+                    throw new TypeError('MX records require an explicit preference and target.');
+                hostname(match[2]);
+            }
+            else
+                hostname(value);
+            return value;
+        }), 'DNS values');
+        if ((outcome === 'answered') !== (values.length > 0))
+            throw new TypeError('Answered DNS observations require values; other outcomes cannot retain answers.');
+        if (type === 'CNAME' && values.length > 1)
+            throw new TypeError('One CNAME owner cannot have competing alias targets.');
+        return { sourceId: sourceId(row.sourceId, ['dns']), queriedName, ownerName, type, observedAt: at(row.observedAt), outcome, values, complete: flag(row.complete), truncated: flag(row.truncated) };
+    });
+    unique(dns, 'DNS observation identities', row => JSON.stringify([row.sourceId, row.queriedName, row.ownerName, row.type, row.observedAt]));
+    const certificates = array(root.certificates, 'Certificate observations', MAX_INFRASTRUCTURE_CERTIFICATES).map(rawRow => {
+        const row = exact(rawRow, ['sourceId', 'fingerprintSha256', 'observedAt', 'names', 'namesComplete'], 'Certificate observation');
+        const fingerprintSha256 = text(row.fingerprintSha256, 'Certificate digest', 64);
+        if (!/^[a-f0-9]{64}$/u.test(fingerprintSha256))
+            throw new TypeError('Certificate identity requires an exact SHA-256 digest.');
+        return { sourceId: sourceId(row.sourceId, ['tls', 'certificate_log']), fingerprintSha256, observedAt: at(row.observedAt), names: unique(array(row.names, 'Certificate names', MAX_INFRASTRUCTURE_HOSTS, 1).map(name), 'Certificate names'), namesComplete: flag(row.namesComplete) };
+    });
+    unique(certificates, 'Certificate observation identities', row => JSON.stringify([row.sourceId, row.fingerprintSha256, row.observedAt]));
+    const roleFamilies = {
+        dns_operator: ['dns'], observed_edge: ['technology'], application_platform: ['technology'], framework_runtime: ['technology'], embedded_dependency: ['technology'], address_registration: ['ip_registration'], routing_origin: ['routing'], observed_origin: ['origin_observation'],
+    };
+    const roles = array(root.roles, 'Provider role observations', MAX_INFRASTRUCTURE_ROLES).map(rawRow => {
+        const row = exact(rawRow, ['sourceId', 'subject', 'subjectType', 'role', 'providerId', 'providerLabel', 'value', 'observedAt', 'complete'], 'Provider role observation');
+        const subjectType = enumeration(row.subjectType, ['hostname', 'address'], 'Provider subject type');
+        const subject = subjectType === 'hostname' ? hostname(row.subject) : text(row.subject, 'Provider address', 45);
+        if (subjectType === 'address' && canonicalIpAddress(subject) !== subject)
+            throw new TypeError('Provider role address is invalid.');
+        if (subjectType === 'hostname' && !hostnames.includes(subject))
+            throw new TypeError('Provider-role hostname falls outside the selected scope.');
+        const role = enumeration(row.role, INFRASTRUCTURE_PROVIDER_ROLES, 'Provider role');
+        const value = text(row.value, 'Provider role value', 300);
+        if (role === 'routing_origin') {
+            if (subjectType !== 'address' || !/^AS(?:[1-9]\d{0,9})$/u.test(value) || Number(value.slice(2)) > 4_294_967_295)
+                throw new TypeError('Routing evidence requires an address and independently sourced ASN.');
+        }
+        if (role === 'observed_origin' && normalizeDomain(value) !== value && canonicalIpAddress(value) !== value)
+            throw new TypeError('Independently observed origin must retain an exact hostname or address.');
+        return { sourceId: sourceId(row.sourceId, roleFamilies[role]), subject, subjectType, role, providerId: identifier(row.providerId, 'Provider ID'), providerLabel: text(row.providerLabel, 'Provider label', 100), value, observedAt: at(row.observedAt), complete: flag(row.complete) };
+    });
+    unique(roles, 'Provider-role observation identities', row => JSON.stringify([row.sourceId, row.subjectType, row.subject, row.role, row.providerId, row.observedAt]));
+    if (roles.some(row => row.subjectType === 'address' && !dns.some(answer => answer.values.includes(row.subject))))
+        throw new TypeError('Provider-role addresses must have explicit supporting DNS address observations within the snapshot.');
+    const result = { schema: INFRASTRUCTURE_OBSERVATION_SCHEMA, version: INFRASTRUCTURE_OBSERVATION_VERSION, id: identifier(root.id, 'Snapshot ID'), target: hostname(root.target), observedAt: at(root.observedAt), mode: enumeration(root.mode, ['supplied', 'selected_lookup', 'certificate_log'], 'Collection mode'), scope: { hostnames, dnsTypes, selection: enumeration(scope.selection, ['explicit_hosts', 'certificate_names'], 'Selection scope') }, coverage: { state: enumeration(coverage.state, ['complete', 'partial', 'failed'], 'Coverage state'), truncated: flag(coverage.truncated), detail: text(coverage.detail, 'Coverage detail', 500) }, sources, dns, certificates, roles, limitations: unique(strings(root.limitations, 'Infrastructure limitations', MAX_INFRASTRUCTURE_LIMITATIONS, 300), 'Infrastructure limitations') };
+    if ([...dns, ...certificates, ...roles].some(row => row.observedAt > result.observedAt))
+        throw new TypeError('Snapshot time cannot precede one of its retained observations.');
+    if (result.coverage.state === 'complete' && (result.coverage.truncated || dns.some(row => !row.complete || row.truncated || ['failed', 'not_checked'].includes(row.outcome)) || certificates.some(row => !row.namesComplete) || roles.some(row => !row.complete)))
+        throw new TypeError('Complete snapshot coverage cannot contain incomplete observations.');
+    if (result.coverage.state === 'complete' && hostnames.some(host => dnsTypes.some(type => !dns.some(row => row.queriedName === host && row.type === type))))
+        throw new TypeError('Complete DNS coverage requires every explicitly selected host/type pair.');
+    if (new TextEncoder().encode(`${JSON.stringify(result)}\n`).byteLength > MAX_INFRASTRUCTURE_OBSERVATION_BYTES)
+        throw new TypeError('Infrastructure snapshot exceeds its retained byte bound.');
+    return result;
+}
+export function normalizeInfrastructureObservation(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    return readInfrastructureObservation(raw);
+}
+export function parseInfrastructureObservation(raw) {
+    return readInfrastructureObservation(parseBoundedJson(raw, { label: 'Infrastructure snapshot', maximumBytes: MAX_INFRASTRUCTURE_OBSERVATION_BYTES }));
+}
+export function serialiseInfrastructureObservation(raw) { return `${JSON.stringify(readInfrastructureObservation(raw))}\n`; }
+function dnsFactKey(row) { return JSON.stringify([row.sourceId, row.queriedName, row.ownerName, row.type]); }
+function roleFactKey(row) { return JSON.stringify([row.sourceId, row.subjectType, row.subject, row.role]); }
+/** A negative DNS answer has a clock too; a missing row has none. */
+function observationCohorts(snapshot) {
+    const cohorts = new Map();
+    const add = (key, observedAt, complete) => {
+        const cohort = cohorts.get(key) ?? { times: new Set(), complete: true };
+        cohort.times.add(observedAt);
+        cohort.complete &&= complete;
+        cohorts.set(key, cohort);
+    };
+    for (const row of snapshot.dns) {
+        const complete = row.complete && !row.truncated && !['failed', 'not_checked'].includes(row.outcome);
+        add(dnsFactKey(row), row.observedAt, complete);
+        add(JSON.stringify([row.sourceId, row.queriedName, row.ownerName, row.type, 'outcome']), row.observedAt, complete);
+    }
+    for (const row of snapshot.certificates)
+        add(JSON.stringify([row.sourceId, row.fingerprintSha256, 'certificate_names']), row.observedAt, row.namesComplete);
+    for (const row of snapshot.roles)
+        add(roleFactKey(row), row.observedAt, row.complete);
+    return cohorts;
+}
+export function infrastructureObservationFacts(raw) {
+    const snapshot = readInfrastructureObservation(raw);
+    const sources = new Map(snapshot.sources.map(source => [source.id, source]));
+    const facts = [];
+    const dnsCohort = (row, aspect) => ({ kind: 'dns', sourceId: row.sourceId, queriedName: row.queriedName, ownerName: row.ownerName, type: row.type, aspect });
+    for (const row of snapshot.dns)
+        for (const value of row.values)
+            facts.push({ key: dnsFactKey(row), cohort: dnsCohort(row, 'values'), hostname: row.ownerName, family: row.type, value, observedAt: row.observedAt, source: sources.get(row.sourceId), complete: row.complete && !row.truncated });
+    for (const row of snapshot.dns)
+        facts.push({ key: JSON.stringify([row.sourceId, row.queriedName, row.ownerName, row.type, 'outcome']), cohort: dnsCohort(row, 'outcome'), hostname: row.ownerName, family: `${row.type}_outcome`, value: row.outcome, observedAt: row.observedAt, source: sources.get(row.sourceId), complete: row.complete && !row.truncated && !['failed', 'not_checked'].includes(row.outcome) });
+    for (const row of snapshot.certificates)
+        for (const value of row.names)
+            facts.push({ key: JSON.stringify([row.sourceId, row.fingerprintSha256, 'certificate_names']), cohort: { kind: 'certificate_names', sourceId: row.sourceId, fingerprintSha256: row.fingerprintSha256 }, hostname: value, family: 'certificate_names', value, observedAt: row.observedAt, source: sources.get(row.sourceId), complete: row.namesComplete });
+    for (const row of snapshot.roles)
+        facts.push({ key: roleFactKey(row), cohort: { kind: 'provider_role', sourceId: row.sourceId, subjectType: row.subjectType, subject: row.subject, role: row.role }, hostname: row.subject, family: row.role, value: `${row.providerId}: ${row.value}`, observedAt: row.observedAt, source: sources.get(row.sourceId), complete: row.complete });
+    return { snapshot, facts };
+}
+export function compareInfrastructureObservations(earlierRaw, laterRaw) {
+    const earlier = infrastructureObservationFacts(earlierRaw), later = infrastructureObservationFacts(laterRaw);
+    const scope = (row) => JSON.stringify({ target: row.target, mode: row.mode, selection: row.scope.selection, hostnames: [...row.scope.hostnames].sort(), dnsTypes: [...row.scope.dnsTypes].sort(), sources: [...row.sources].sort((a, b) => a.id.localeCompare(b.id)) });
+    const comparable = scope(earlier.snapshot) === scope(later.snapshot) && earlier.snapshot.observedAt < later.snapshot.observedAt;
+    const complete = comparable && [earlier.snapshot, later.snapshot].every(row => row.coverage.state === 'complete' && !row.coverage.truncated);
+    const beforeCohorts = observationCohorts(earlier.snapshot), afterCohorts = observationCohorts(later.snapshot);
+    const groups = new Map();
+    for (const [side, values] of [['before', earlier.facts], ['after', later.facts]])
+        for (const fact of values) {
+            const group = groups.get(fact.key) ?? { cohort: fact.cohort, hostname: fact.hostname, family: fact.family, source: fact.source, before: [], after: [], complete: true };
+            if (fact.hostname < group.hostname)
+                group.hostname = fact.hostname;
+            group[side].push(fact.value);
+            group.complete &&= fact.complete;
+            groups.set(fact.key, group);
+        }
+    const rows = [...groups.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, row]) => {
+        row.before = [...new Set(row.before)].sort();
+        row.after = [...new Set(row.after)].sort();
+        const before = beforeCohorts.get(key), after = afterCohorts.get(key);
+        const beforeTimes = [...before?.times ?? []].sort(), afterTimes = [...after?.times ?? []].sort();
+        // Multiple historical cohorts are retained, not flattened into a fictitious
+        // single response. A later envelope never advances a source observation.
+        const ordered = beforeTimes.length === 1 && afterTimes.length === 1 && beforeTimes[0] < afterTimes[0];
+        row.complete &&= Boolean(before?.complete && after?.complete);
+        const same = JSON.stringify(row.before) === JSON.stringify(row.after);
+        const state = !comparable ? 'incomparable' : !ordered || !complete || !row.complete ? 'unknown' : same ? 'unchanged' : !row.before.length ? 'newly_observed' : !row.after.length ? 'not_returned' : 'changed';
+        return { ...row, beforeTimes, afterTimes, state, detail: state === 'not_returned' ? 'Not returned by this comparable bounded collection; this does not establish disappearance.' : state === 'newly_observed' ? 'Newly present in retained evidence; not necessarily newly created.' : state === 'unknown' ? !ordered ? 'Source observation times are missing, equal, reversed or span multiple cohorts; envelope time cannot establish a temporal change.' : 'Incomplete evidence cannot establish a removal or change.' : state === 'incomparable' ? 'Source, scope, mode or observation ordering differs; no temporal change is inferred.' : 'Source-qualified retained observation comparison.' };
+    });
+    return { state: comparable ? complete && !rows.some(row => row.state === 'unknown') ? 'compared' : 'partial' : 'incomparable', earlier: earlier.snapshot.id, later: later.snapshot.id, rows, limitations: ['No new collection was made. Retained changes do not establish ownership, safety, control or maliciousness.', 'Provider-reported history remains labelled separately from local observations. Empty, failed, limited and changed-source snapshots cannot replace a stronger baseline.'] };
+}
+/** Technology roles reuse the canonical role owner, not a new signature catalogue. */
+export function infrastructureTechnologyRoles(value) { return technologyEvidenceRoles(value); }