@slicedearth/whoisleuth-cli 2.5.1 → 2.7.0

package/packages/evidence/dmarc-policy-context.mjs

@@ -0,0 +1,80 @@
+import { isValidAsciiHostname } from "../contracts/domain-name.mjs";
+import { normalizeExplicitIsoTimestamp } from "./observation.mjs";
+export const MAX_DMARC_DISCOVERY_OWNERS = 8;
+function closedRecord(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+        || Reflect.ownKeys(value).length !== keys.length)
+        throw new TypeError('DMARC policy context has an invalid structure.');
+    const result = {};
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !('value' in descriptor))
+            throw new TypeError('DMARC policy context requires ordinary data fields.');
+        result[key] = descriptor.value;
+    }
+    return result;
+}
+function owner(value) {
+    return typeof value === 'string' && value.length <= 253
+        && isValidAsciiHostname(value, { requireDot: false, requireLowercase: true });
+}
+function time(value) {
+    if (value === null)
+        return null;
+    const normalized = typeof value === 'string' && value.length <= 64 ? normalizeExplicitIsoTimestamp(value) : null;
+    if (normalized === null)
+        throw new TypeError('DMARC policy context has an invalid observation time.');
+    return normalized;
+}
+/** Current opted-in review only; absent historical context is never reconstructed. */
+export function normalizeDmarcPolicyContext(value, expectedDomain) {
+    if (value === undefined)
+        return undefined;
+    const input = closedRecord(value, ['version', 'source', 'relation', 'complete', 'owner', 'observedAt', 'policy', 'subdomainPolicy', 'nonexistentPolicy', 'psd', 'testMode', 'discovery']);
+    if (input.version !== 1 || input.source !== 'recursive_dns_txt' || typeof input.complete !== 'boolean'
+        || typeof input.relation !== 'string' || !['exact', 'inherited', 'undetermined'].includes(input.relation)
+        || !Array.isArray(input.discovery) || input.discovery.length < 1 || input.discovery.length > MAX_DMARC_DISCOVERY_OWNERS) {
+        throw new TypeError('DMARC policy context has an unsupported version or discovery state.');
+    }
+    const discovery = [];
+    for (let index = 0; index < input.discovery.length; index++) {
+        const entry = Object.getOwnPropertyDescriptor(input.discovery, String(index));
+        if (!entry?.enumerable || !('value' in entry))
+            throw new TypeError('DMARC discovery requires ordinary entries.');
+        const row = closedRecord(entry.value, ['owner', 'state', 'observedAt']);
+        if (!owner(row.owner) || typeof row.state !== 'string' || !['observed', 'not_found', 'invalid', 'unavailable'].includes(row.state)) {
+            throw new TypeError('DMARC discovery has an invalid owner or state.');
+        }
+        discovery.push(Object.freeze({ owner: row.owner, state: row.state, observedAt: time(row.observedAt) }));
+    }
+    if (new Set(discovery.map(row => row.owner)).size !== discovery.length
+        || (expectedDomain !== undefined && discovery[0].owner !== expectedDomain)
+        || discovery.some((row, index) => index > 0 && !discovery[index - 1].owner.endsWith(`.${row.owner}`))
+        || (input.complete && discovery.some(row => row.state === 'unavailable'))) {
+        throw new TypeError('DMARC discovery does not match one bounded owner walk.');
+    }
+    const observedAt = time(input.observedAt);
+    if (input.relation === 'undetermined') {
+        if ([input.owner, observedAt, input.policy, input.subdomainPolicy, input.nonexistentPolicy, input.psd, input.testMode].some(field => field !== null)) {
+            throw new TypeError('Undetermined DMARC policy must not declare a selected policy.');
+        }
+    }
+    else {
+        const selected = discovery.find(row => row.owner === input.owner);
+        if (!input.complete || !owner(input.owner) || !selected || selected.state !== 'observed' || selected.observedAt !== observedAt
+            || (input.relation === 'exact') !== (input.owner === discovery[0].owner)
+            || [input.policy, input.subdomainPolicy, input.nonexistentPolicy].some(field => typeof field !== 'string' || !['none', 'quarantine', 'reject'].includes(field))
+            || typeof input.psd !== 'string' || !['u', 'n', 'y'].includes(input.psd) || typeof input.testMode !== 'boolean') {
+            throw new TypeError('DMARC policy does not match a complete selected observation.');
+        }
+    }
+    return Object.freeze({
+        version: 1, source: 'recursive_dns_txt', relation: input.relation,
+        complete: input.complete, owner: input.owner, observedAt,
+        policy: input.policy, subdomainPolicy: input.subdomainPolicy,
+        nonexistentPolicy: input.nonexistentPolicy,
+        psd: input.psd, testMode: input.testMode,
+        discovery: Object.freeze(discovery),
+    });
+}

package/packages/evidence/image-regions.mjs

@@ -5,6 +5,21 @@ export const MAX_EVIDENCE_IMAGE_PIXELS = 16 * 1024 * 1024;
 export const MAX_EVIDENCE_IMAGE_DIMENSION = 10_000;
 // Each selected region emits at most four solid rectangles; no nested effects.
 export const MAX_EVIDENCE_IMAGE_REGIONS = 64;
+export function readImageDerivationDeclaration(raw) {
+    const value = exact(raw, ['method', 'source', 'operations'], 'Image derivation declaration');
+    if (value.method !== 'png-regions-v1')
+        throw new TypeError('This image derivation method is unsupported.');
+    const operations = Array.from(array(value.operations, 'Image operations', 2, 1), operation => enumeration(operation, ['redact', 'outline'], 'Image operation'));
+    if (new Set(operations).size !== operations.length)
+        throw new TypeError('Image operations must be unique.');
+    return Object.freeze({ method: value.method, source: readRetainedFileReference(value.source), operations: Object.freeze(operations) });
+}
+/** Retain the immediate parent's fingerprint, without identifiers or region coordinates. */
+export function declareImageDerivation(raw) {
+    const derivation = readImageDerivation(raw);
+    const operations = ['redact', 'outline'].filter(kind => derivation.plan.regions.some(region => region.kind === kind));
+    return readImageDerivationDeclaration({ method: derivation.method, source: derivation.source, operations });
+}
 export function readEvidenceImageDimensions(width, height) {
     const result = {
         width: integer(width, 'Image width', 1, MAX_EVIDENCE_IMAGE_DIMENSION),

package/packages/evidence/lookup-collection-receipt.mjs

@@ -0,0 +1,140 @@
+// A bounded account of one completed Lookup operation. This records collector
+// execution, not proof of network delivery, independent verification or history.
+export const LOOKUP_SOURCE_IDS = Object.freeze([
+    'rdap', 'whois', 'domain_evidence', 'reverse_dns', 'registrar_rdap',
+    'network_context', 'security_txt', 'external_intelligence',
+    'malware_host_intelligence', 'malware_ioc_intelligence',
+]);
+export const LOOKUP_SOURCE_STATES = Object.freeze([
+    'success', 'partial', 'not_found', 'skipped', 'error', 'unsupported',
+    'not_applicable', 'unavailable', 'rate_limited', 'complete', 'disabled', 'stale',
+]);
+export const LOOKUP_COLLECTION_RECEIPT_VERSION = 1;
+export const LOOKUP_CHOICE_KEYS = Object.freeze([
+    'securityTxt', 'externalIntelligence', 'malwareHostIntelligence', 'malwareIocIntelligence',
+]);
+export const LOOKUP_CHOICE_SOURCES = Object.freeze({
+    securityTxt: 'security_txt', externalIntelligence: 'external_intelligence',
+    malwareHostIntelligence: 'malware_host_intelligence', malwareIocIntelligence: 'malware_ioc_intelligence',
+});
+const ADMISSIONS = ['admitted', 'disabled', 'unsupported', 'not_applicable', 'prerequisite_unavailable', 'unknown'];
+function fields(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Collection receipt must contain ordinary objects.');
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new TypeError('Collection receipt must contain ordinary objects.');
+    const own = Reflect.ownKeys(value);
+    if (own.length !== keys.length || own.some(key => typeof key !== 'string' || !keys.includes(key))) {
+        throw new TypeError('Collection receipt contains an unsupported field set.');
+    }
+    const output = {};
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !('value' in descriptor))
+            throw new TypeError('Collection receipt contains an invalid field.');
+        output[key] = descriptor.value;
+    }
+    return output;
+}
+function oneOf(value, options) {
+    if (typeof value !== 'string' || !options.includes(value))
+        throw new TypeError('Collection receipt contains an invalid state.');
+    return value;
+}
+function quality(value) {
+    if (value !== null && typeof value !== 'boolean')
+        throw new TypeError('Collection receipt quality must be explicit or unknown.');
+    return value;
+}
+export function lookupCollectionChoices(input) {
+    return Object.freeze({
+        securityTxt: input.securityTxt === true,
+        externalIntelligence: input.externalIntelligence === true,
+        malwareHostIntelligence: input.malwareHostIntelligence === true,
+        malwareIocIntelligence: input.malwareIocIntelligence === true,
+    });
+}
+/** Absence is historical unknown, never reconstructed as a negative choice. */
+export function parseLookupCollectionReceipt(raw) {
+    if (raw === undefined)
+        return null;
+    const value = fields(raw, ['version', 'requestedDepth', 'targetClass', 'webSelection', 'originalChoices', 'sources']);
+    if (value.version !== LOOKUP_COLLECTION_RECEIPT_VERSION)
+        throw new TypeError('Collection receipt version is unsupported.');
+    const choices = fields(value.originalChoices, LOOKUP_CHOICE_KEYS);
+    if (Object.values(choices).some(choice => typeof choice !== 'boolean'))
+        throw new TypeError('Collection receipt choices must be explicit.');
+    const requestedDepth = oneOf(value.requestedDepth, ['fast', 'deep']);
+    const targetClass = oneOf(value.targetClass, ['domain', 'ipv4', 'ipv6', 'asn']);
+    const webSelection = oneOf(value.webSelection, ['hostname', 'selected_url', 'not_applicable']);
+    if ((targetClass !== 'domain' && webSelection !== 'not_applicable') || (webSelection === 'selected_url' && requestedDepth !== 'deep')) {
+        throw new TypeError('Collection receipt target and web selection disagree.');
+    }
+    if (!Array.isArray(value.sources) || Object.getPrototypeOf(value.sources) !== Array.prototype
+        || value.sources.length !== LOOKUP_SOURCE_IDS.length
+        || Reflect.ownKeys(value.sources).length !== LOOKUP_SOURCE_IDS.length + 1)
+        throw new TypeError('Collection receipt source inventory is invalid.');
+    const bySource = new Map();
+    for (let index = 0; index < LOOKUP_SOURCE_IDS.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(value.sources, String(index));
+        if (!descriptor?.enumerable || !('value' in descriptor))
+            throw new TypeError('Collection receipt source entry is invalid.');
+        const row = fields(descriptor.value, ['source', 'intent', 'admission', 'attempt', 'settlement', 'complete', 'truncated']);
+        const source = oneOf(row.source, LOOKUP_SOURCE_IDS);
+        if (bySource.has(source))
+            throw new TypeError('Collection receipt source is duplicated.');
+        const attempt = oneOf(row.attempt, ['started', 'not_started', 'unknown']);
+        const admission = oneOf(row.admission, ADMISSIONS);
+        const complete = quality(row.complete), truncated = quality(row.truncated);
+        const intent = oneOf(row.intent, ['requested', 'not_requested']);
+        const settlement = oneOf(row.settlement, [...LOOKUP_SOURCE_STATES, 'unknown']);
+        if (attempt === 'started' && admission !== 'admitted'
+            || attempt === 'started' && intent !== 'requested'
+            || attempt !== 'started' && (complete !== null || truncated !== null)
+            || attempt === 'not_started' && settlement !== 'unknown'
+            || complete === true && !['success', 'complete', 'not_found'].includes(settlement)
+            || complete === true && truncated === true)
+            throw new TypeError('Collection receipt execution and quality disagree.');
+        bySource.set(source, Object.freeze({
+            source, intent, admission, attempt, settlement, complete, truncated,
+        }));
+    }
+    for (const choice of LOOKUP_CHOICE_KEYS) {
+        if ((bySource.get(LOOKUP_CHOICE_SOURCES[choice]).intent === 'requested') !== choices[choice]) {
+            throw new TypeError('Collection receipt choice and source intent disagree.');
+        }
+    }
+    return Object.freeze({ version: LOOKUP_COLLECTION_RECEIPT_VERSION, requestedDepth, targetClass, webSelection,
+        originalChoices: lookupCollectionChoices(choices),
+        sources: Object.freeze(LOOKUP_SOURCE_IDS.map(source => bySource.get(source))),
+    });
+}
+/** Bind a validated execution account to this submission's pre-filter choices.
+ * A browser may omit an ineligible optional request; the server cannot know
+ * which unchecked/disabled control led to that omission. Do not invent why. */
+export function bindLookupCollectionChoices(raw, originalChoices) {
+    const receipt = parseLookupCollectionReceipt(raw);
+    if (!receipt)
+        return null;
+    const choices = fields(originalChoices, LOOKUP_CHOICE_KEYS);
+    if (Object.values(choices).some(choice => typeof choice !== 'boolean'))
+        throw new TypeError('Collection receipt choices must be explicit.');
+    const sources = receipt.sources.map(row => {
+        const choice = LOOKUP_CHOICE_KEYS.find(key => LOOKUP_CHOICE_SOURCES[key] === row.source);
+        if (!choice || choices[choice] === receipt.originalChoices[choice])
+            return { ...row };
+        if (receipt.originalChoices[choice] || choices[choice] !== true || row.attempt !== 'not_started') {
+            throw new TypeError('Collection receipt does not match the submitted choices.');
+        }
+        return { ...row, intent: 'requested', admission: 'unknown' };
+    });
+    const bound = { ...receipt, originalChoices: lookupCollectionChoices(choices), sources };
+    parseLookupCollectionReceipt(bound);
+    return bound;
+}
+/** Stable, payload-free material comparison. Parsing also removes key order as a difference. */
+export function lookupCollectionReceiptIdentity(raw) {
+    const receipt = parseLookupCollectionReceipt(raw);
+    return receipt ? JSON.stringify(receipt) : null;
+}

package/packages/evidence/lookup-collection-review.mjs

@@ -0,0 +1,74 @@
+import { LOOKUP_CHOICE_KEYS, LOOKUP_CHOICE_SOURCES, parseLookupCollectionReceipt } from "./lookup-collection-receipt.mjs";
+export const LOOKUP_SOURCE_LABELS = Object.freeze({
+    rdap: 'Registry RDAP', whois: 'WHOIS chain', domain_evidence: 'Domain evidence',
+    reverse_dns: 'Reverse DNS', registrar_rdap: 'Registrar RDAP', network_context: 'Network context',
+    security_txt: 'security.txt', external_intelligence: 'Archived web intelligence',
+    malware_host_intelligence: 'Malware host intelligence', malware_ioc_intelligence: 'Malware infrastructure intelligence',
+});
+const ADMISSION_LABELS = Object.freeze({
+    admitted: 'Admitted', disabled: 'Disabled by policy', unsupported: 'Unsupported', not_applicable: 'Not applicable',
+    prerequisite_unavailable: 'Required earlier evidence unavailable', unknown: 'Admission not recorded',
+});
+const ATTEMPT_LABELS = Object.freeze({ started: 'Collector started', not_started: 'Collector not started', unknown: 'Collector start unknown' });
+/** Inert guidance from recorded states, never an admission or retry decision. */
+export function lookupSourceStateExplanation(state, source, receipt) {
+    if (receipt && receipt.source === source && receipt.attempt === 'not_started') {
+        if (receipt.intent === 'not_requested')
+            return 'Not requested in this Lookup. Select it explicitly in a new Lookup if needed.';
+        if (receipt.admission === 'disabled')
+            return 'Collection was disabled by policy. Retrying does not change that policy.';
+        if (receipt.admission === 'prerequisite_unavailable')
+            return 'Required earlier evidence was unavailable, so this collector did not start. Review that source first.';
+        if (receipt.admission === 'not_applicable')
+            return 'This collector did not apply to the submitted target or mode.';
+        if (receipt.admission === 'unsupported')
+            return 'Collection was not supported for this target; retrying unchanged inputs will not add evidence.';
+    }
+    switch (state) {
+        case 'success':
+        case 'complete':
+            return 'Collection completed within this source’s scope. Review its observations and time below.';
+        case 'not_found':
+            return 'This source returned no matching record. Its authority and search scope determine what that means.';
+        case 'partial':
+        case 'inconclusive':
+            return 'Evidence is incomplete or inconclusive. Missing fields remain unknown; a later retry may help if source conditions change.';
+        case 'error':
+        case 'unavailable':
+            return 'Usable evidence was not obtained. This is not an absence finding; retry may help after the reported problem changes.';
+        case 'rate_limited':
+            return 'The source reported a rate limit. Wait for its permitted retry window; no reset time is assumed.';
+        case 'unsupported':
+            return source === 'rdap' || source === 'whois'
+                ? 'No applicable service was recorded by registry policy or discovery. Retrying unchanged discovery may not add evidence.'
+                : 'This source does not support the target or request. Use an applicable source rather than repeating the same request.';
+        case 'skipped':
+            return 'This source was not queried under the selected mode or access policy. Review its source details before requesting it again.';
+        case 'disabled':
+            return 'Collection was disabled by policy. Retrying does not change that policy.';
+        case 'not_applicable':
+            return 'This source does not apply to the submitted target or mode.';
+        case 'stale':
+            return 'Retained evidence is out of date for this review. A deliberate refresh may provide a newer observation.';
+        default:
+            return 'The source outcome was not retained. Its request history and retry usefulness are unknown.';
+    }
+}
+/** One presentation of the closed receipt vocabulary for browser and terminal. */
+export function lookupCollectionReceiptReview(raw) {
+    const receipt = parseLookupCollectionReceipt(raw);
+    if (!receipt)
+        return null;
+    return {
+        receipt,
+        selection: `${receipt.requestedDepth === 'deep' ? 'Deep' : 'Fast'} Lookup · ${receipt.webSelection === 'selected_url'
+            ? 'selected URL' : receipt.webSelection === 'hostname' ? 'hostname' : 'no web target'}`,
+        choices: LOOKUP_CHOICE_KEYS.map(choice => ({ label: LOOKUP_SOURCE_LABELS[LOOKUP_CHOICE_SOURCES[choice]], selected: receipt.originalChoices[choice] })),
+        sources: receipt.sources.map(row => ({
+            id: row.source, label: LOOKUP_SOURCE_LABELS[row.source],
+            summary: `${row.intent === 'requested' ? 'Requested' : 'Not requested'} · ${ADMISSION_LABELS[row.admission]} · ${ATTEMPT_LABELS[row.attempt]}`,
+            outcome: `Source result: ${row.settlement.replaceAll('_', ' ')} · ${row.complete === null ? 'completeness unknown' : row.complete ? 'complete' : 'not complete'} · ${row.truncated === null ? 'truncation unknown' : row.truncated ? 'truncated' : 'not truncated'}`,
+            explanation: lookupSourceStateExplanation(row.settlement, row.source, row),
+        })),
+    };
+}

package/packages/evidence/record-identity.mjs

@@ -1,6 +1,7 @@
 // Shared collision-resistant identities for bounded, already normalised records.
 // Platform cryptography remains the owner of signatures and authentication.
 export const MAX_IDENTITY_DIGEST_BYTES = 1024 * 1024;
+export const MAX_INCREMENTAL_DIGEST_BYTES = 256 * 1024 * 1024;
 const SHA256_CONSTANTS = Object.freeze([
     0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
     0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
@@ -14,27 +15,21 @@ const SHA256_CONSTANTS = Object.freeze([
 function rotateRight(value, bits) {
     return (value >>> bits) | (value << (32 - bits));
 }
-export function sha256IdentityHex(bytes) {
-    if (bytes.byteLength > MAX_IDENTITY_DIGEST_BYTES)
-        throw new RangeError('Record identity exceeds its byte limit.');
-    // This digest is a collision-resistant record identity, not a password,
-    // signature, MAC, or substitute for the platform cryptography used there.
-    const paddedLength = Math.ceil((bytes.byteLength + 9) / 64) * 64;
-    const padded = new Uint8Array(paddedLength);
-    padded.set(bytes);
-    padded[bytes.byteLength] = 0x80;
-    const view = new DataView(padded.buffer);
-    const bitLength = bytes.byteLength * 8;
-    view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x1_0000_0000), false);
-    view.setUint32(paddedLength - 4, bitLength >>> 0, false);
+/** Incremental content identity only; never authentication or publisher proof. */
+export function createIncrementalSha256(maximumBytes = MAX_IDENTITY_DIGEST_BYTES) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0 || maximumBytes > MAX_INCREMENTAL_DIGEST_BYTES)
+        throw new RangeError('Content identity has an invalid byte limit.');
     const state = new Uint32Array([
         0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
     ]);
     const words = new Uint32Array(64);
-    for (let offset = 0; offset < paddedLength; offset += 64) {
+    const pending = new Uint8Array(64);
+    let pendingBytes = 0, totalBytes = 0, finished = false;
+    function block(bytes, offset) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset + offset, 64);
         for (let index = 0; index < 16; index += 1)
-            words[index] = view.getUint32(offset + index * 4, false);
+            words[index] = view.getUint32(index * 4, false);
         for (let index = 16; index < 64; index += 1) {
             const left = words[index - 15];
             const right = words[index - 2];
@@ -68,5 +63,54 @@ export function sha256IdentityHex(bytes) {
         state[6] = (state[6] + g) >>> 0;
         state[7] = (state[7] + h) >>> 0;
     }
-    return [...state].map((value) => value.toString(16).padStart(8, '0')).join('');
+    return Object.freeze({
+        update(bytes) {
+            if (finished)
+                throw new Error('Content identity is already finalised.');
+            if (!(bytes instanceof Uint8Array) || bytes.byteLength > maximumBytes - totalBytes)
+                throw new RangeError('Content identity exceeds its byte limit.');
+            totalBytes += bytes.byteLength;
+            let offset = 0;
+            if (pendingBytes) {
+                const length = Math.min(64 - pendingBytes, bytes.byteLength);
+                pending.set(bytes.subarray(0, length), pendingBytes);
+                pendingBytes += length;
+                offset += length;
+                if (pendingBytes === 64) {
+                    block(pending, 0);
+                    pendingBytes = 0;
+                }
+            }
+            while (offset + 64 <= bytes.byteLength) {
+                block(bytes, offset);
+                offset += 64;
+            }
+            if (offset < bytes.byteLength) {
+                pending.set(bytes.subarray(offset), 0);
+                pendingBytes = bytes.byteLength - offset;
+            }
+        },
+        digestHex() {
+            if (finished)
+                throw new Error('Content identity is already finalised.');
+            finished = true;
+            const padding = new Uint8Array(pendingBytes < 56 ? 64 : 128);
+            padding.set(pending.subarray(0, pendingBytes));
+            padding[pendingBytes] = 0x80;
+            const view = new DataView(padding.buffer), bits = totalBytes * 8;
+            view.setUint32(padding.length - 8, Math.floor(bits / 0x1_0000_0000), false);
+            view.setUint32(padding.length - 4, bits >>> 0, false);
+            block(padding, 0);
+            if (padding.length === 128)
+                block(padding, 64);
+            return [...state].map(value => value.toString(16).padStart(8, '0')).join('');
+        },
+    });
+}
+export function sha256IdentityHex(bytes) {
+    if (bytes.byteLength > MAX_IDENTITY_DIGEST_BYTES)
+        throw new RangeError('Record identity exceeds its byte limit.');
+    const digest = createIncrementalSha256();
+    digest.update(bytes);
+    return digest.digestHex();
 }

package/packages/evidence/technology-evidence-role.mjs

@@ -0,0 +1,51 @@
+const TECHNOLOGY_EVIDENCE_ROLE_ORDER = Object.freeze([
+    'observed_edge',
+    'application_platform',
+    'framework_runtime',
+    'embedded_dependency',
+]);
+const TECHNOLOGY_EVIDENCE_ROLE_SET = new Set(TECHNOLOGY_EVIDENCE_ROLE_ORDER);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function technologyEvidenceRoles(value) {
+    const finding = record(value);
+    const roles = new Set();
+    let hasExplicitRole = false;
+    for (const role of Array.isArray(finding.roles) ? finding.roles.slice(0, 4) : []) {
+        if (typeof role === 'string' && TECHNOLOGY_EVIDENCE_ROLE_SET.has(role)) {
+            roles.add(role);
+            hasExplicitRole = true;
+        }
+    }
+    const evidenceValues = Array.isArray(finding.evidence) ? finding.evidence.slice(0, 4) : [];
+    for (const evidenceValue of evidenceValues) {
+        const evidence = record(evidenceValue);
+        if (typeof evidence.role === 'string'
+            && TECHNOLOGY_EVIDENCE_ROLE_SET.has(evidence.role)) {
+            roles.add(evidence.role);
+            hasExplicitRole = true;
+        }
+    }
+    if (!hasExplicitRole) {
+        const resourceOriginOnly = evidenceValues.length > 0
+            && evidenceValues.every((evidence) => (String(record(evidence).source).toLowerCase() === 'resource origin'));
+        if (evidenceValues.some((evidence) => String(record(evidence).source).toLowerCase() === 'resource origin')) {
+            roles.add('embedded_dependency');
+        }
+        if (!resourceOriginOnly) {
+            const category = String(finding.category).toLowerCase();
+            if (category === 'delivery platform')
+                roles.add('observed_edge');
+            else if (['application runtime', 'web framework', 'static site generator', 'web server'].includes(category)) {
+                roles.add('framework_runtime');
+            }
+            else
+                roles.add('application_platform');
+        }
+    }
+    return TECHNOLOGY_EVIDENCE_ROLE_ORDER.filter((role) => roles.has(role));
+}
+export { TECHNOLOGY_EVIDENCE_ROLE_ORDER, technologyEvidenceRoles, };

package/packages/interchange/external-findings-import.mjs

@@ -7,6 +7,7 @@ import { sha256IdentityHex } from "../evidence/record-identity.mjs";
 import { MAX_RESPONSE_LABEL_LENGTH, MAX_RESPONSE_VALUE_LENGTH, MAX_RESPONSE_LIMITATION_LENGTH, normalizeCaseEvidencePins, normalizeCaseSightings, } from "../cases/case-response-model.mjs";
 import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_IMPORT_BYTES, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, } from "../contracts/external-observation-interchange.mjs";
 import { hasUnsafeRetainedText } from "./retained-text.mjs";
+import { readInfrastructureObservation } from "../investigation/infrastructure-observation.mjs";
 export { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_IMPORT_BYTES, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, };
 export const EXTERNAL_FINDING_CATEGORIES = [
     'certificate',
@@ -33,6 +34,7 @@ const FINDING_KEYS = new Set([
     'limitations',
     'reference',
     'structuredObservation',
+    'infrastructureObservation',
 ]);
 const STRUCTURED_OBSERVATION_KEYS = new Set([
     'sourceSchema',
@@ -185,14 +187,14 @@ function structuredObservation(value, index) {
 function findingKey(finding, sourceName) {
     return canonicalArtifactJsonV2({ sourceName, finding });
 }
-export function parseExternalFindingsDocument(value) {
+export function parseExternalFindingsDocument(value, observeOrigin) {
     const root = record(value);
     if (!root || !hasOnlyKeys(root, ROOT_KEYS)) {
         throw new Error('External findings must use the documented object shape without additional top-level fields.');
     }
     if (root.schema !== EXTERNAL_FINDINGS_SCHEMA
-        || root.schemaVersion !== EXTERNAL_FINDINGS_VERSION) {
-        throw new Error(`External findings must use ${EXTERNAL_FINDINGS_SCHEMA} schema version ${EXTERNAL_FINDINGS_VERSION}.`);
+        || (root.schemaVersion !== 4 && root.schemaVersion !== 5)) {
+        throw new Error(`External findings must use ${EXTERNAL_FINDINGS_SCHEMA} schema version 4 or 5.`);
     }
     const sourceValue = record(root.source);
     if (!sourceValue || !hasOnlyKeys(sourceValue, SOURCE_KEYS)) {
@@ -207,7 +209,8 @@ export function parseExternalFindingsDocument(value) {
         throw new Error(`External findings must contain between 1 and ${MAX_EXTERNAL_FINDINGS} findings.`);
     }
     const normalized = [];
-    const seen = new Set();
+    let retainedBytes = new TextEncoder().encode(JSON.stringify({ schema: root.schema, schemaVersion: root.schemaVersion, source, findings: [] })).byteLength + 1;
+    const seen = new Map();
     const domainCounts = new Map();
     for (const [index, raw] of root.findings.entries()) {
         const item = record(raw);
@@ -228,7 +231,7 @@ export function parseExternalFindingsDocument(value) {
         if (evidenceClass !== 'deployment_observation' && evidenceClass !== 'provider_report') {
             throw new Error(`Finding ${index + 1} evidence class is unsupported.`);
         }
-        const finding = {
+        let finding = {
             domain,
             category: item.category,
             evidenceClass,
@@ -239,10 +242,28 @@ export function parseExternalFindingsDocument(value) {
             reference: optionalText(item.reference, 500, `Finding ${index + 1} reference`),
             structuredObservation: structuredObservation(item.structuredObservation, index),
         };
+        if (Object.hasOwn(item, 'infrastructureObservation')) {
+            if (root.schemaVersion !== 5)
+                throw new TypeError('Infrastructure observations require external-findings version 5.');
+            const infrastructureObservation = readInfrastructureObservation(item.infrastructureObservation);
+            if (infrastructureObservation.target !== domain || infrastructureObservation.observedAt !== finding.observedAt)
+                throw new TypeError('Infrastructure snapshot must match its finding target and observation time.');
+            if (finding.structuredObservation)
+                throw new TypeError('Infrastructure snapshots cannot also declare a single structured observation.');
+            finding = { ...finding, infrastructureObservation };
+        }
+        if (root.schemaVersion === 5) {
+            retainedBytes += new TextEncoder().encode(JSON.stringify(finding)).byteLength + 1;
+            if (retainedBytes > MAX_EXTERNAL_FINDINGS_IMPORT_BYTES)
+                throw new TypeError('External findings exceed the retained aggregate byte bound.');
+        }
         const key = findingKey(finding, source.name);
-        if (seen.has(key))
+        const previous = seen.get(key);
+        if (previous) {
+            observeOrigin?.(previous, index);
             continue;
-        seen.add(key);
+        }
+        seen.set(key, finding);
         const count = (domainCounts.get(domain) ?? 0) + 1;
         if (count > MAX_EXTERNAL_FINDINGS_PER_DOMAIN) {
             throw new Error(`External findings exceed the ${MAX_EXTERNAL_FINDINGS_PER_DOMAIN}-finding per-domain limit.`);
@@ -252,17 +273,20 @@ export function parseExternalFindingsDocument(value) {
             throw new Error(`External findings exceed the ${MAX_EXTERNAL_FINDING_DOMAINS}-domain limit.`);
         }
         normalized.push(finding);
+        observeOrigin?.(finding, index);
     }
     if (!normalized.length)
         throw new Error('External findings did not contain a unique valid finding.');
     return {
         schema: EXTERNAL_FINDINGS_SCHEMA,
-        schemaVersion: EXTERNAL_FINDINGS_VERSION,
+        schemaVersion: root.schemaVersion,
         source,
         findings: normalized,
     };
 }
 export function serializeExternalFindingsDocument(value) {
+    if (record(value)?.schemaVersion === 5)
+        return `${JSON.stringify(parseExternalFindingsDocument(value))}\n`;
     const serialised = JSON.stringify(value, null, 2);
     if (typeof serialised !== 'string') {
         throw new TypeError('External findings must be JSON-serialisable.');
@@ -294,6 +318,12 @@ function alreadyRetained(recordValue, projection) {
     });
 }
 function structuredPinFields(finding) {
+    if (finding.infrastructureObservation)
+        return {
+            field: 'infrastructure.snapshot', category: 'infrastructure',
+            sourceSchema: { collection: 'external_observations', schema: finding.infrastructureObservation.schema, version: finding.infrastructureObservation.version },
+            infrastructureObservation: finding.infrastructureObservation,
+        };
     const observation = finding.structuredObservation;
     if (!observation)
         return {};
@@ -348,6 +378,7 @@ export function externalFindingCaseProjection(finding, source) {
     const omittedLimitations = finding.limitations.filter((item) => !sourceLimitations.includes(item)).length;
     const pin = normalizeCaseEvidencePins([{
             ...structuredPinFields(finding),
+            observationHostname: finding.domain,
             importContentSha256: identitySha256,
             label: `External ${finding.category} finding`,
             value,
@@ -428,17 +459,6 @@ export function mergeExternalFindingsIntoCases(current, document, now = new Date
         duplicatesSkipped,
     };
 }
-function targetedFinding(finding, caseDomain) {
-    if (finding.domain === caseDomain)
-        return finding;
-    const prefix = `Captured hostname ${finding.domain}. `;
-    const maximumSummaryLength = MAX_EXTERNAL_FINDING_SUMMARY_LENGTH;
-    const remaining = maximumSummaryLength - prefix.length;
-    const summary = remaining > 1 && finding.summary.length > remaining
-        ? `${prefix}${finding.summary.slice(0, remaining - 1).trimEnd()}…`
-        : `${prefix}${finding.summary}`;
-    return { ...finding, domain: caseDomain, summary };
-}
 export function externalFindingsCaseTargets(document, caseDomain) {
     if (canonicalRegistrableDomain(caseDomain) !== caseDomain) {
         throw new Error('The selected Case does not have a canonical registrable-domain identity.');
@@ -468,8 +488,7 @@ export function mergeExternalFindingsIntoCase(current, caseId, document, now = n
     let record = selected;
     let findingsAdded = 0;
     let duplicatesSkipped = 0;
-    for (const original of document.findings) {
-        const finding = targetedFinding(original, selected.domain);
+    for (const finding of document.findings) {
         const merged = mergeExternalFindingIntoCase(cases, selected.id, finding, document.source, now);
         cases = merged.cases;
         record = merged.record;

package/packages/interchange/json-output.mjs

@@ -0,0 +1,14 @@
+const TERMINAL_UNSAFE_JSON_RE = /[\u007f-\u009f\u2028\u2029]|\p{Default_Ignorable_Code_Point}/gu;
+function jsonUnicodeEscape(value) {
+    const codePoint = value.codePointAt(0);
+    if (codePoint <= 0xffff)
+        return `\\u${codePoint.toString(16).padStart(4, '0')}`;
+    const offset = codePoint - 0x10000;
+    const high = 0xd800 + (offset >> 10);
+    const low = 0xdc00 + (offset & 0x3ff);
+    return `\\u${high.toString(16).padStart(4, '0')}\\u${low.toString(16).padStart(4, '0')}`;
+}
+/** Escape display controls without changing the parsed JSON values. */
+export function terminalSafeJson(value, space) {
+    return JSON.stringify(value, null, space).replace(TERMINAL_UNSAFE_JSON_RE, jsonUnicodeEscape);
+}