@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/packages/investigation/evidence-coverage-ledger.mjs

@@ -1,4 +1,5 @@
-const MAX_ENTRIES = 24;
+export const MAX_EVIDENCE_COVERAGE_ENTRIES = 24;
+const MAX_ENTRIES = MAX_EVIDENCE_COVERAGE_ENTRIES;
 const MAX_ID_LENGTH = 64;
 const MAX_LABEL_LENGTH = 120;
 const MAX_LIMITATIONS = 8;
@@ -330,6 +331,13 @@ export function buildLookupEvidenceCoverageLedger(input) {
     const providers = Array.isArray(input.threatIntelligenceProviders)
         ? input.threatIntelligenceProviders
         : [];
+    if (Array.isArray(input.threatIntelligenceWithheld) && input.threatIntelligenceWithheld.length) {
+        items.push({
+            id: 'external-withheld', label: 'Withheld external-intelligence records', category: 'external',
+            status: 'unsupported', complete: false,
+            limitations: ['Some provider data was unsupported, unbound, malformed or over-limit. Withheld records are not evidence of no findings and cannot contribute to Risk.'],
+        });
+    }
     for (const [providerIndex, providerValue] of providers.entries()) {
         if (items.length >= MAX_ENTRIES)
             break;

package/packages/investigation/har-intake.mjs

@@ -0,0 +1,68 @@
+import { parseBoundedJsonObject, boundedJsonLimitsForBytes } from "../analysis/bounded-json.mjs";
+import { parseCredentialFreeHttpUrl } from "../evidence/lookup-target.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { MAX_MESSAGE_INTAKE_BYTES, MAX_INTAKE_URL_LENGTH } from "../contracts/message-intake.mjs";
+import { MAX_HAR_ENTRIES, HAR_TIMING_PHASES } from "../contracts/har-review.mjs";
+import { createIntakeReport } from "./intake-report.mjs";
+import { createLinkIntake } from "./link-intake.mjs";
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const milliseconds = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER ? value : null;
+function mimeCategory(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return 'unknown';
+    const mime = raw.split(';', 1)[0].trim().toLowerCase();
+    if (['text/html', 'application/xhtml+xml'].includes(mime))
+        return 'html';
+    if (['text/javascript', 'application/javascript', 'application/ecmascript', 'text/ecmascript'].includes(mime))
+        return 'script';
+    if (mime === 'application/json' || mime.endsWith('+json'))
+        return 'json';
+    if (['application/xml', 'text/xml'].includes(mime) || mime.endsWith('+xml'))
+        return 'xml';
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('font/') || mime.includes('font'))
+        return 'font';
+    if (mime.startsWith('audio/') || mime.startsWith('video/'))
+        return 'media';
+    if (mime.startsWith('text/'))
+        return 'text';
+    return mime === 'application/octet-stream' ? 'binary' : 'other';
+}
+/** Retain declared request sequence, not cookies, headers, bodies or replay authority. */
+export async function reviewHarInput(bytes, reviewedAt) {
+    const base = await createIntakeReport(bytes, 'har', reviewedAt);
+    const root = parseBoundedJsonObject(new TextDecoder('utf-8', { fatal: true }).decode(bytes), { label: 'HAR input', maximumBytes: MAX_MESSAGE_INTAKE_BYTES,
+        limits: { ...boundedJsonLimitsForBytes(MAX_MESSAGE_INTAKE_BYTES), maximumContainerItems: MAX_HAR_ENTRIES } });
+    const log = record(root.log);
+    if (log.version !== '1.2' || !Array.isArray(log.entries) || log.entries.length > MAX_HAR_ENTRIES)
+        throw new TypeError('Select a HAR 1.2 archive within the entry review bound.');
+    const links = createLinkIntake(), entries = [];
+    let invalidEntries = 0;
+    for (const [index, raw] of log.entries.entries()) {
+        const entry = record(raw), request = record(entry.request), response = record(entry.response), content = record(response.content), timing = record(entry.timings);
+        if (!Object.keys(request).length || !Object.keys(response).length) {
+            invalidEntries++;
+            continue;
+        }
+        const url = parseCredentialFreeHttpUrl(request.url, MAX_INTAKE_URL_LENGTH);
+        const method = typeof request.method === 'string' ? request.method.toUpperCase() : null;
+        const resource = typeof entry._resourceType === 'string' ? entry._resourceType.toLowerCase() : null;
+        entries.push({ sequence: index + 1, startedAt: typeof entry.startedDateTime === 'string' ? normalizeExplicitIsoTimestamp(entry.startedDateTime) : null,
+            origin: url?.origin ?? null,
+            method: method === null ? 'unknown' : ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH', 'CONNECT', 'TRACE'].includes(method) ? method : 'other',
+            status: typeof response.status === 'number' && Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? response.status : null,
+            durationMs: milliseconds(entry.time), mimeCategory: mimeCategory(content.mimeType),
+            timings: Object.fromEntries(HAR_TIMING_PHASES.map(phase => [phase, milliseconds(timing[phase])])),
+            resourceType: resource === null ? 'unknown' : ['document', 'script', 'stylesheet', 'image', 'font', 'media', 'xhr', 'fetch', 'ping', 'websocket'].includes(resource) ? resource : 'other',
+            reportedFailure: typeof entry._error === 'string' && Boolean(entry._error) });
+        // Queries may carry access tokens or account identifiers. Even transient
+        // destination actions from this archive contain only its origin.
+        if (url)
+            links.add(url.origin, 'har_request');
+    }
+    const extracted = links.result();
+    return { targets: extracted.targets, report: { ...base, links: extracted.links, harReview: { entries, invalidEntries },
+            coverage: { ...base.coverage, state: invalidEntries || extracted.bounded || extracted.rejected ? 'partial' : 'reviewed', reviewedParts: entries.length,
+                rejectedLinks: extracted.rejected, boundsReached: [...extracted.limitations, ...(extracted.bounded ? ['Destination list; the admitted request timeline remains available'] : [])] } } };
+}

package/packages/investigation/identity-event-intake.mjs

@@ -0,0 +1,131 @@
+import { parseBoundedJson, boundedJsonLimitsForBytes } from "../analysis/bounded-json.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { exact, exactOptional } from "../evidence/artifact-structure.mjs";
+import { MAX_MESSAGE_INTAKE_BYTES } from "../contracts/message-intake.mjs";
+import { IDENTITY_EVENTS_INPUT_SCHEMA, IDENTITY_EVENTS_INPUT_VERSION, MAX_IDENTITY_EVENTS } from "../contracts/identity-events.mjs";
+import { createIntakeReport } from "./intake-report.mjs";
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const instant = (value) => typeof value === 'string' ? normalizeExplicitIsoTimestamp(value) : null;
+const guid = (value) => typeof value === 'string' && /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/iu.test(value) ? value.toLowerCase() : null;
+function applicationId(value, provider) {
+    return provider === 'entra' ? guid(value) : typeof value === 'string' && /^0oa[a-z\d]{17}$/iu.test(value) ? value : null;
+}
+function protocol(value) {
+    switch (value) {
+        case 'oAuth2': return 'oauth2';
+        case 'deviceCode': return 'device_code';
+        case 'saml20': return 'saml';
+        case 'wsFederation': return 'ws_federation';
+        case 'ropc': return 'password_grant';
+        default: return 'unknown';
+    }
+}
+function eventKind(value) {
+    switch (value) {
+        case 'user.authentication.sso': return 'application_access';
+        case 'user.session.start': return 'session_start';
+        case 'user.authentication.auth_via_mfa':
+        case 'user.authentication.verify': return 'credential_check';
+        case 'app.oauth2.consent.grant': return 'consent';
+        default: return 'other';
+    }
+}
+/** IDs are replaced in memory; actor labels are meaningful only within this file. */
+function extractEvents(input, provider) {
+    const actors = new Map(), events = [];
+    let invalidEvents = 0;
+    const actor = (value) => {
+        if (typeof value !== 'string' || !value || value.length > 240)
+            return null;
+        let label = actors.get(value);
+        if (!label) {
+            label = `Actor ${actors.size + 1}`;
+            actors.set(value, label);
+        }
+        return label;
+    };
+    for (const [index, value] of input.entries()) {
+        const row = record(value);
+        if (provider === 'entra') {
+            if (!Object.hasOwn(row, 'createdDateTime') || !Object.hasOwn(row, 'status')) {
+                invalidEvents++;
+                continue;
+            }
+            const app = applicationId(row.appId, provider), code = record(row.status).errorCode;
+            events.push({ sequence: index + 1, actorLabel: actor(row.userId), applicationIds: app ? [app] : [], tenantId: guid(row.resourceTenantId),
+                // A client category (for example Browser) is not an authentication protocol.
+                protocol: protocol(row.authenticationProtocol), kind: 'sign_in', occurredAt: instant(row.createdDateTime),
+                result: typeof code === 'number' && Number.isSafeInteger(code) && code >= 0 ? code === 0 ? 'success' : 'failure' : 'unknown' });
+        }
+        else {
+            if (typeof row.eventType !== 'string' || !Object.hasOwn(row, 'published')) {
+                invalidEvents++;
+                continue;
+            }
+            const targets = Array.isArray(row.target) ? row.target : [];
+            const apps = targets.filter(target => record(target).type === 'AppInstance').map(target => applicationId(record(target).id, provider)).filter((id) => id !== null);
+            const outcome = record(row.outcome).result;
+            events.push({ sequence: index + 1, actorLabel: actor(record(row.actor).id), applicationIds: [...new Set(apps)], tenantId: null,
+                protocol: 'unknown', kind: eventKind(row.eventType), occurredAt: instant(row.published),
+                result: outcome === 'SUCCESS' ? 'success' : outcome === 'FAILURE' ? 'failure' : outcome === 'DENY' ? 'denied' : outcome === 'CHALLENGE' ? 'challenge' : 'unknown' });
+        }
+    }
+    return { events, invalidEvents };
+}
+export function readIdentityMatchScope(raw, provider) {
+    const source = exact(raw, ['applicationId', 'tenantId', 'actorLabel', 'startedAt', 'endedAt'], 'Identity comparison scope');
+    const app = applicationId(source.applicationId, provider), tenant = source.tenantId === null ? null : guid(source.tenantId);
+    const start = instant(source.startedAt), end = instant(source.endedAt);
+    if (!app || !start || !end || Date.parse(end) < Date.parse(start) || source.tenantId !== null && !tenant
+        || source.actorLabel !== null && (typeof source.actorLabel !== 'string' || !/^Actor [1-9]\d{0,4}$/u.test(source.actorLabel))) {
+        throw new TypeError('Select a valid application ID, explicit-timezone interval, and optional retained tenant or file-local actor label.');
+    }
+    return { applicationId: app, tenantId: tenant, actorLabel: source.actorLabel, startedAt: start, endedAt: end };
+}
+/** Exact supplied-field corroboration, not a causal or account-compromise judgement. */
+export function compareIdentityEvents(review, rawScope) {
+    const scope = readIdentityMatchScope(rawScope, review.provider);
+    const compare = (selected, supplied) => selected === null ? 'not_selected' : supplied === null ? 'unavailable' : selected === supplied ? 'matched' : 'different';
+    return { ...review, comparison: { scope, events: review.events.map(event => {
+                const application = !event.applicationIds.length ? 'unavailable' : event.applicationIds.includes(scope.applicationId) ? 'matched' : 'different';
+                const tenant = compare(scope.tenantId, event.tenantId), actor = compare(scope.actorLabel, event.actorLabel);
+                const time = !event.occurredAt ? 'unavailable' : Date.parse(event.occurredAt) >= Date.parse(scope.startedAt) && Date.parse(event.occurredAt) <= Date.parse(scope.endedAt) ? 'matched' : 'different';
+                const fields = [application, tenant, actor, time];
+                return { sequence: event.sequence, application, tenant, actor, time,
+                    state: fields.includes('different') ? 'different' : fields.includes('unavailable') ? 'incomplete' : 'matched' };
+            }) } };
+}
+export async function reviewIdentityEventInput(bytes, reviewedAt) {
+    const base = await createIntakeReport(bytes, 'identity', reviewedAt);
+    const parsed = parseBoundedJson(new TextDecoder('utf-8', { fatal: true }).decode(bytes), { label: 'Identity event input', maximumBytes: MAX_MESSAGE_INTAKE_BYTES,
+        limits: { ...boundedJsonLimitsForBytes(MAX_MESSAGE_INTAKE_BYTES), maximumContainerItems: MAX_IDENTITY_EVENTS } });
+    const root = record(parsed);
+    let provider, input, match = null;
+    if (Object.hasOwn(root, 'schema')) {
+        exactOptional(root, ['schema', 'version', 'provider', 'events'], ['match'], 'Identity event input');
+        if (root.schema !== IDENTITY_EVENTS_INPUT_SCHEMA || root.version !== IDENTITY_EVENTS_INPUT_VERSION || !['entra', 'okta'].includes(String(root.provider)))
+            throw new TypeError('Unsupported identity event input schema, version or provider.');
+        provider = root.provider;
+        input = root.events;
+        match = root.match ?? null;
+    }
+    else if (Array.isArray(parsed)) {
+        provider = 'okta';
+        input = parsed;
+    }
+    else {
+        provider = 'entra';
+        input = root.value;
+    }
+    if (!Array.isArray(input) || input.length > MAX_IDENTITY_EVENTS)
+        throw new TypeError('Select a sign-in value array, a System Log array, or a versioned identity event input.');
+    const extracted = extractEvents(input, provider);
+    if (input.length && !extracted.events.length)
+        throw new TypeError('No supported identity event records were found.');
+    let identityEventReview = { provider, ...extracted, sourceHasMore: typeof root['@odata.nextLink'] === 'string' && Boolean(root['@odata.nextLink']), comparison: null };
+    if (match !== null)
+        identityEventReview = compareIdentityEvents(identityEventReview, match);
+    return { targets: [], report: { ...base, identityEventReview, coverage: { ...base.coverage,
+                state: identityEventReview.invalidEvents || identityEventReview.sourceHasMore ? 'partial' : 'reviewed', reviewedParts: identityEventReview.events.length,
+                boundsReached: identityEventReview.sourceHasMore ? ['The selected export declares another page; it was not requested'] : [] } } };
+}

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/intake-report.mjs

@@ -0,0 +1,19 @@
+import { sha256ArtifactBytes } from "../evidence/artifact-integrity.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { MESSAGE_INTAKE_KINDS, MESSAGE_INTAKE_SCHEMA, MESSAGE_INTAKE_VERSION, MAX_MESSAGE_INTAKE_BYTES } from "../contracts/message-intake.mjs";
+export function assertMessageBytes(bytes) {
+    if (!(bytes instanceof Uint8Array) || !(bytes.buffer instanceof ArrayBuffer) || !bytes.byteLength || bytes.byteLength > MAX_MESSAGE_INTAKE_BYTES) {
+        throw new TypeError('Select one non-empty input of at most 16 MiB. No input was retained.');
+    }
+}
+export async function createIntakeReport(bytes, kind, reviewedAt) {
+    assertMessageBytes(bytes);
+    const instant = normalizeExplicitIsoTimestamp(reviewedAt);
+    if (!instant || !MESSAGE_INTAKE_KINDS.includes(kind))
+        throw new TypeError('Input review requires a supported format and a timestamp with an explicit timezone.');
+    return { schema: MESSAGE_INTAKE_SCHEMA, schemaVersion: MESSAGE_INTAKE_VERSION, reviewedAt: instant,
+        source: { kind, digestSha256: await sha256ArtifactBytes(bytes), byteLength: bytes.byteLength },
+        coverage: { state: 'reviewed', reviewedParts: 0, unreviewedAttachments: 0, rejectedLinks: 0, boundsReached: [] },
+        identities: [], authenticationClaims: [], authenticationReview: { headers: [], omittedHeaders: 0 }, messageParts: [],
+        links: [], actionHints: [], identityRecovery: { reportedActions: [], nextSteps: [] } };
+}

package/packages/investigation/investigation-manifest.mjs

@@ -1,5 +1,5 @@
-import { boundedJsonLimitsForBytes, parseBoundedJson, parseBoundedJsonObject } from "../../lib/bounded-json.mjs";
-import { normalizeBoundedSemanticVersion } from "../../lib/semantic-version.mjs";
+import { boundedJsonLimitsForBytes, parseBoundedJson, parseBoundedJsonObject } from "../analysis/bounded-json.mjs";
+import { normalizeBoundedSemanticVersion } from "../analysis/semantic-version.mjs";
 import { canonicalArtifactJsonV2, sha256ArtifactBytes, sha256ArtifactDigestV2, SORTED_JSON_V2 } from "../evidence/artifact-integrity.mjs";
 import { array, digest, enumeration, exact, fail, integer, iso, strings, text, validateIntegrity } from "../evidence/artifact-structure.mjs";
 import { SELECTED_FILE_MEDIA_TYPES as INVESTIGATION_FILE_MEDIA_TYPES } from "../contracts/selected-file-limits.mjs";

package/packages/investigation/link-intake.mjs

@@ -0,0 +1,179 @@
+import { canonicalRegistrableDomain } from "../analysis/registrable-domain.mjs";
+import { parseCredentialFreeHttpUrl } from "../evidence/lookup-target.mjs";
+import { MAX_INTAKE_LINKS, MAX_INTAKE_URL_LENGTH, MAX_EMBEDDED_LINK_DEPTH, MAX_AUTH_SCOPES } from "../contracts/message-intake.mjs";
+const EXCLUDED_INPUTS = {
+    malformed: 'Malformed or overlong links were not reviewed',
+    credentials: 'Links containing credentials were not reviewed',
+    protocol: 'Non-HTTP(S) links were not reviewed',
+    port: 'Links using non-default ports were not reviewed',
+    host: 'IP-address or non-registrable-host links were not reviewed',
+    qrNetwork: 'QR network settings were not interpreted',
+    qrContact: 'QR contact details were not interpreted',
+    qrProtocol: 'QR non-HTTP(S) payloads were not interpreted',
+    qrHost: 'QR hostnames without an HTTP(S) scheme were not offered for collection',
+    qrText: 'QR text without an HTTP(S) link was not interpreted',
+};
+const AUTH_KEYS = ['client_id', 'scope', 'redirect_uri', 'response_type', 'prompt'];
+const EMBEDDED_KEYS = new Set(['url', 'u', 'target', 'redirect', 'redirect_uri', 'redirect_url', 'return', 'returnurl', 'continue', 'next', 'dest', 'destination']);
+const safeIdentifier = (value) => value && /^[a-zA-Z0-9._~:-]{1,160}$/u.test(value) ? value : null;
+const tokens = (value) => (value ?? '').split(/\s+/u).filter(Boolean);
+export function reviewAuthorisationLink(url) {
+    const params = url.searchParams;
+    const authorisation = params.has('client_id') && (params.has('scope') || params.has('response_type') || params.has('redirect_uri'));
+    const device = /\/(?:device|devicecode|devicelogin)(?:\/|$)/iu.test(url.pathname);
+    if (!authorisation && !device)
+        return null;
+    const duplicateParameters = AUTH_KEYS.filter(key => params.getAll(key).length > 1);
+    const single = (key) => duplicateParameters.includes(key) ? null : params.get(key);
+    const scopes = tokens(single('scope'));
+    const retainedScopes = scopes.filter(scope => /^[a-zA-Z0-9._:/-]{1,160}$/u.test(scope)).slice(0, MAX_AUTH_SCOPES);
+    const redirect = parseCredentialFreeHttpUrl(single('redirect_uri'), MAX_INTAKE_URL_LENGTH);
+    const responseTypes = tokens(single('response_type')).filter(value => ['code', 'token', 'id_token', 'none'].includes(value));
+    const prompt = tokens(single('prompt')).filter(value => ['none', 'login', 'consent', 'select_account', 'create'].includes(value));
+    return {
+        kind: authorisation ? 'authorisation_parameters' : 'device_code_reference',
+        clientId: safeIdentifier(single('client_id')), scopes: retainedScopes,
+        redirectOrigin: redirect?.origin ?? null, responseTypes, prompt, duplicateParameters,
+        omittedParameters: scopes.length !== retainedScopes.length || (params.has('client_id') && !safeIdentifier(single('client_id')))
+            || (params.has('redirect_uri') && !redirect) || tokens(single('response_type')).length !== responseTypes.length
+            || tokens(single('prompt')).length !== prompt.length,
+    };
+}
+export function refangIntakeUrl(raw) {
+    // Only the scheme and authority are defanged. Path/query/fragment bytes may be
+    // significant to an exact supplied target, even when they resemble defanging.
+    return raw.replace(/^(https?|hxxps?)(?::|\[:\])\/\/([^/?#]*)/iu, (_match, scheme, authority) => `${scheme.toLowerCase().replace('hxxp', 'http')}://${authority.replace(/\[\.\]|\(\.\)/gu, '.')}`);
+}
+const HTTP_PREFIX = /^(?:https?|hxxps?)(?::|\[:\])\/\//iu;
+function proseUrl(value) {
+    // Prose delimiters are not part of a URL; balanced path brackets are. Direct
+    // supplied links bypass this text-scanning cleanup entirely.
+    let result = value.replace(/[.,;!?]+$/u, '');
+    let round = 0, square = 0;
+    for (const char of result) {
+        if (char === '(')
+            round++;
+        else if (char === ')')
+            round--;
+        else if (char === '[')
+            square++;
+        else if (char === ']')
+            square--;
+    }
+    for (;;) {
+        const end = result.at(-1);
+        if (end === ')' && round < 0)
+            round++;
+        else if (end === ']' && square < 0)
+            square++;
+        else
+            return result;
+        result = result.slice(0, -1).replace(/[.,;!?]+$/u, '');
+    }
+}
+function displayedHost(value) {
+    const bounded = value.trim();
+    if (bounded.length > MAX_INTAKE_URL_LENGTH || /\s/u.test(bounded))
+        return null;
+    const parsed = parseCredentialFreeHttpUrl(refangIntakeUrl(HTTP_PREFIX.test(bounded) ? bounded : `https://${bounded}`), MAX_INTAKE_URL_LENGTH);
+    return parsed && canonicalRegistrableDomain(parsed.hostname) ? parsed.hostname : null;
+}
+/** No resolution or request occurs here; embedded targets remain supplied text. */
+export function createLinkIntake() {
+    const links = [], targets = [];
+    const seen = new Set();
+    const exclusions = new Map();
+    let rejected = 0, bounded = false;
+    function exclude(reason, isLink = true) {
+        if (isLink)
+            rejected++;
+        exclusions.set(reason, (exclusions.get(reason) ?? 0) + 1);
+    }
+    function add(raw, source, displayed = '', parentId = null, depth = 0, location) {
+        if (links.length >= MAX_INTAKE_LINKS) {
+            bounded = true;
+            return;
+        }
+        const value = refangIntakeUrl(raw.trim());
+        const url = parseCredentialFreeHttpUrl(value, MAX_INTAKE_URL_LENGTH);
+        if (!url) {
+            let reason = 'malformed';
+            if (value.length <= MAX_INTAKE_URL_LENGTH && !/[\x00-\x20\x7f]/u.test(value)) {
+                try {
+                    const parsed = new URL(value);
+                    if (!['http:', 'https:'].includes(parsed.protocol))
+                        reason = 'protocol';
+                    else if (parsed.username || parsed.password)
+                        reason = 'credentials';
+                }
+                catch { /* Retain only the fixed malformed-input category. */ }
+            }
+            exclude(reason);
+            return;
+        }
+        if (url.port) {
+            exclude('port');
+            return;
+        }
+        if (!canonicalRegistrableDomain(url.hostname)) {
+            exclude('host');
+            return;
+        }
+        const shown = displayedHost(displayed);
+        const key = JSON.stringify([url.href, source, parentId, shown, location ?? null]);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const id = `link-${links.length + 1}`;
+        links.push({ id, origin: url.origin, hostname: url.hostname, registrationDomain: canonicalRegistrableDomain(url.hostname),
+            source, ...(location ? { location } : {}), parentId, displayedHostname: shown, displayedDestination: shown ? shown === url.hostname ? 'same_host' : 'different_host' : 'not_a_hostname',
+            hasPrivateLocation: url.pathname !== '/' || Boolean(url.search || url.hash), authorisation: reviewAuthorisationLink(url) });
+        targets.push({ id, exactUrl: url.href });
+        for (const [name, value] of url.searchParams) {
+            if (!EMBEDDED_KEYS.has(name.toLowerCase()) || !HTTP_PREFIX.test(value))
+                continue;
+            if (depth >= MAX_EMBEDDED_LINK_DEPTH) {
+                bounded = true;
+                continue;
+            }
+            add(value, 'embedded_parameter', '', id, depth + 1, location);
+        }
+    }
+    function addText(text, source = 'text', location) {
+        // The caller admits bytes before this scan; iteration stops at the work bound.
+        for (const match of text.matchAll(/(?:https?|hxxps?)(?::|\[:\])\/\/[^\s<>"'`]+/giu)) {
+            add(match[0].length > MAX_INTAKE_URL_LENGTH ? match[0] : proseUrl(match[0]), source, '', null, 0, location);
+            if (links.length >= MAX_INTAKE_LINKS) {
+                bounded = true;
+                break;
+            }
+        }
+    }
+    function addQr(text, source = 'qr', location) {
+        const value = refangIntakeUrl(text.trim());
+        const scheme = /^([a-z][a-z0-9+.-]*):/iu.exec(value)?.[1]?.toLowerCase();
+        if (/^WIFI:/iu.test(value)) {
+            exclude('qrNetwork', false);
+            return;
+        }
+        if (/^(?:BEGIN:VCARD|MECARD:)/iu.test(value)) {
+            exclude('qrContact', false);
+            return;
+        }
+        if (scheme && !['http', 'https'].includes(scheme)) {
+            exclude('qrProtocol', false);
+            return;
+        }
+        if (!/(?:https?|hxxps?):\/\//iu.test(value)) {
+            exclude(displayedHost(value) ? 'qrHost' : 'qrText', false);
+            return;
+        }
+        addText(value, source, location);
+    }
+    return { add, addText, addQr, result: () => ({ links: [...links], targets: [...targets], rejected, bounded,
+            limitations: Object.keys(EXCLUDED_INPUTS).flatMap(reason => {
+                const count = exclusions.get(reason);
+                return count ? [`${EXCLUDED_INPUTS[reason]} (${count}).`] : [];
+            }),
+        }) };
+}

package/packages/investigation/lookup-asset-graph.mjs

@@ -1,7 +1,7 @@
 import { LOOKUP_ASSET_GRAPH_SCHEMA, LOOKUP_ASSET_GRAPH_VERSION, MAX_LOOKUP_ASSET_LIMITATIONS, } from "../contracts/investigation-portability.mjs";
 import { MAX_PROFILE_VALUES } from "../contracts/workspace-portability.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
-import { canonicalRegistrableDomain } from "../../lib/registrable-domain.mjs";
+import { canonicalRegistrableDomain } from "../analysis/registrable-domain.mjs";
 import { createGraphInputReader, graphInputIsIncomplete } from "./lookup-asset-graph-inputs.mjs";
 export { LOOKUP_ASSET_GRAPH_SCHEMA, LOOKUP_ASSET_GRAPH_VERSION };
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;