@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/packages/investigation/lookup-claim-readiness.mjs

@@ -21,6 +21,24 @@ export const LOOKUP_CLAIM_REQUIREMENT_IDS = [
     'reviewed-case-recipient',
     'authoritative-rdap',
 ];
+const CLAIM_QUESTIONS = Object.freeze({
+    'registration-state': 'What does the registration authority establish?',
+    'current-web-observation': 'What was the website doing at the observed time?',
+    'brand-resemblance': 'Does the observed page resemble the reviewed Brand?',
+    'controlled-change': 'Which registration and DNS dependencies need review?',
+    'incident-response': 'What evidence and recipient route support a response?',
+    'network-context': 'What does the authoritative network record establish?',
+});
+/** A presentation of existing readiness, not a new verdict or collection plan. */
+export function lookupQuestionsNeedingEvidence(readiness) {
+    return readiness.entries.filter((entry) => entry.state !== 'ready').map((entry) => ({
+        id: entry.id,
+        question: CLAIM_QUESTIONS[entry.id],
+        href: entry.href,
+        requirements: entry.requirements.filter((requirement) => requirement.state !== 'complete'),
+        limitations: entry.limitations,
+    }));
+}
 const MAX_TEXT = 320;
 const MAX_DIAGNOSTICS = 12;
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;

package/packages/investigation/lookup-investigation-brief.mjs

@@ -40,7 +40,7 @@ export function buildLookupInvestigationBrief(input) {
     const limitedSources = input.quality.entries
         .filter((entry) => entry.state !== 'complete')
         .map((entry) => `${entry.label}: ${entry.statusLabel}`);
-    const graphKinds = uniqueText(input.graph.edges.map((edge) => edge.label), 12);
+    const graphKinds = uniqueText(input.graph.edges.map((edge) => edge.label), 64);
     const brief = Object.freeze({
         schema: LOOKUP_INVESTIGATION_BRIEF_SCHEMA,
         schemaVersion: LOOKUP_INVESTIGATION_BRIEF_VERSION,
@@ -66,10 +66,10 @@ export function buildLookupInvestigationBrief(input) {
             kinds: Object.freeze(graphKinds),
         }),
         limitations: Object.freeze(uniqueText([
-            ...limitedSources,
-            ...input.graph.limitations,
             'This brief is a deterministic organisation of collected and derived evidence, not an attribution, ownership, safety, availability, or maliciousness conclusion.',
             'Analyst assertions, hypotheses, and decisions must remain separate from observed evidence.',
+            ...input.graph.limitations,
+            ...limitedSources,
         ])),
     });
     if (new TextEncoder().encode(JSON.stringify(brief)).byteLength > MAX_LOOKUP_INVESTIGATION_BRIEF_BYTES) {

package/packages/investigation/lookup-task-guidance.mjs

@@ -0,0 +1,58 @@
+export const LOOKUP_GUIDANCE_TASKS = Object.freeze([
+    'general',
+    'acquisition',
+    'brand',
+    'incident',
+    'owned',
+]);
+const GUIDANCE = Object.freeze({
+    general: Object.freeze({
+        task: 'general',
+        label: 'General investigation',
+        recommendation: 'fast',
+        reason: 'Fast starts with authority-aware registration and availability evidence before a broader collection is justified.',
+        requestExplanation: 'Fast requests the existing lower-request authority and RDAP registration path and omits WHOIS, DNS, HTTP, TLS, network-context, and optional intelligence branches.',
+        limitation: 'A Fast result can still be partial, unavailable, or inconclusive. Use Deep only when the question needs the additional source families.',
+    }),
+    brand: Object.freeze({
+        task: 'brand',
+        label: 'Brand review',
+        recommendation: 'deep',
+        reason: 'Deep provides the existing source-qualified web, DNS, TLS, registration, and relationship context used by brand review.',
+        requestExplanation: 'Deep requests the existing registry RDAP, WHOIS, domain evidence, registrar RDAP, DNS, HTTP, TLS, and network-context branches. Optional intelligence sources receive data only when separately selected.',
+        limitation: 'Deep is broader, not complete or authoritative for every question. Missing and conflicting sources remain explicit.',
+    }),
+    acquisition: Object.freeze({
+        task: 'acquisition',
+        label: 'Acquisition review',
+        recommendation: 'deep',
+        reason: 'Deep provides the existing bounded registration, web, DNS, TLS, and uncertainty context expected by acquisition review.',
+        requestExplanation: 'Deep uses the existing request budget and source branches. It does not appraise a domain, contact a seller, or establish clean title or legal sufficiency.',
+        limitation: 'The recommendation organises due diligence; it does not make an acquisition recommendation or guarantee completeness.',
+    }),
+    incident: Object.freeze({
+        task: 'incident',
+        label: 'Incident response',
+        recommendation: 'deep',
+        reason: 'Deep collects the web, DNS, TLS, registration, and network evidence needed to review an incident and choose a response route.',
+        requestExplanation: 'Deep requests the existing source branches. It does not submit a report, test a published contact, or establish responsibility for the observed content.',
+        limitation: 'Collection supports review; it does not determine maliciousness or authorise a response.',
+    }),
+    owned: Object.freeze({
+        task: 'owned',
+        label: 'Owned-domain posture',
+        recommendation: 'deep',
+        reason: 'Deep collects the current registration, DNS, TLS, mail, and web observations needed for a source-by-source posture review.',
+        requestExplanation: 'Deep uses the existing bounded source branches. Retained baselines remain separate and must be compared using their observation times and source states.',
+        limitation: 'A changed or missing observation does not by itself establish compromise, remediation, or control.',
+    }),
+});
+export const LOOKUP_TASK_VIEWS = Object.freeze(LOOKUP_GUIDANCE_TASKS.map((task) => Object.freeze({
+    id: task,
+    label: GUIDANCE[task].label,
+})));
+export function lookupTaskGuidance(task) {
+    return typeof task === 'string' && LOOKUP_GUIDANCE_TASKS.includes(task)
+        ? GUIDANCE[task]
+        : GUIDANCE.general;
+}

package/packages/monitoring/analyst-review-state.mjs

@@ -1,3 +1,5 @@
+import { sha256IdentityHex } from "../evidence/record-identity.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
 /**
  * Canonical, framework-independent analyst review identity and lifecycle.
  *
@@ -7,7 +9,12 @@
  */
 import { ANALYST_REVIEW_DISPOSITIONS, ANALYST_REVIEW_EVIDENCE_FAMILIES, ANALYST_REVIEW_STATE_SCHEMA, ANALYST_REVIEW_STATE_SCHEMA_VERSION, MAX_ANALYST_REVIEW_ASSOCIATIONS, MAX_ANALYST_REVIEW_HISTORY, MAX_ANALYST_REVIEW_IDENTITY_BYTES, MAX_ANALYST_REVIEW_ITEMS, MAX_ANALYST_REVIEW_RATIONALE_LENGTH, MAX_ANALYST_REVIEW_STATE_BYTES, MAX_ANALYST_REVIEW_STATE_RECORDS, } from "../contracts/analyst-review-state-contract.mjs";
 export * from "../contracts/analyst-review-state-contract.mjs";
+export { ANALYST_REVIEW_AGING_AFTER_DAYS, ANALYST_REVIEW_STALE_AFTER_DAYS, analystReviewAgeAt } from "../evidence/review-age.mjs";
+export function analystReviewCanResolve(item) {
+    return item.completeness === 'complete' && (item.age === 'current' || item.age === 'aging');
+}
 const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
+const RATIONALE_INPUT_CONTROL_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u;
 const SAFE_REFERENCE_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
 const SAFE_SUBJECT_RE = /^review:[a-z0-9_]{1,40}:[a-f0-9]{64}$/u;
 const SAFE_FINGERPRINT_RE = /^material:[a-f0-9]{64}$/u;
@@ -122,28 +129,24 @@ export function assertAnalystReviewInputGraph(value) {
         }
     }
 }
-function boundedText(value, maximum, label, required = true) {
-    if (typeof value !== 'string' || value.length > maximum * 4 || CONTROL_RE.test(value)) {
-        if (!required && (value === null || value === undefined || value === ''))
-            return '';
+function boundedRationale(value, label, formInput = false) {
+    const maximum = MAX_ANALYST_REVIEW_RATIONALE_LENGTH;
+    const controls = formInput ? RATIONALE_INPUT_CONTROL_RE : CONTROL_RE;
+    if (typeof value !== 'string' || value.length > maximum * 4 || controls.test(value)) {
         throw inputError(`${label} is invalid`);
     }
+    // Forms may contain ordinary line breaks; stored rationale remains single-line.
     const normalized = value.replace(/\s+/gu, ' ').trim();
-    if ((required && !normalized) || normalized.length > maximum)
+    if (!normalized || normalized.length > maximum)
         throw inputError(`${label} is invalid`);
     return normalized;
 }
 function timestamp(value, label, nullable = false) {
     if (nullable && (value === null || value === undefined || value === ''))
         return null;
-    if (typeof value !== 'string' || value.length > 64 || CONTROL_RE.test(value))
-        throw inputError(`${label} is invalid`);
-    const parsed = Date.parse(value);
-    if (!Number.isFinite(parsed))
-        throw inputError(`${label} must use an explicit valid date and time`);
-    const normalized = new Date(parsed).toISOString();
-    if (!/(?:Z|[+-]\d{2}:\d{2})$/u.test(value))
-        throw inputError(`${label} must use an explicit timezone`);
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    if (!normalized)
+        throw inputError(`${label} must use an explicit valid date, time and timezone`);
     return normalized;
 }
 function referenceList(value, label) {
@@ -181,7 +184,7 @@ function normalizeSnapshot(raw, label) {
     const normalized = {
         reviewedFingerprint: fingerprint(value.reviewedFingerprint, `${label}.reviewedFingerprint`),
         disposition: normalizedDisposition,
-        rationale: boundedText(value.rationale, MAX_ANALYST_REVIEW_RATIONALE_LENGTH, `${label}.rationale`),
+        rationale: boundedRationale(value.rationale, `${label}.rationale`),
         reviewedAt: timestamp(value.reviewedAt, `${label}.reviewedAt`),
         reviewDueAt: timestamp(value.reviewDueAt, `${label}.reviewDueAt`, true),
         expiresAt: timestamp(value.expiresAt, `${label}.expiresAt`, true),
@@ -278,7 +281,7 @@ export function normalizeAnalystReviewStateStore(raw) {
         records,
     };
     if (byteLength(JSON.stringify(store)) > MAX_ANALYST_REVIEW_STATE_BYTES) {
-        throw new Error('Analyst review state exceeds the 512 KiB browser-local storage limit.');
+        throw new Error('Analyst review state exceeds the 512 KiB workspace storage limit.');
     }
     return store;
 }
@@ -323,75 +326,8 @@ export function canonicalAnalystReviewIdentityJson(parts) {
     }
     return source;
 }
-const SHA256_CONSTANTS = Object.freeze([
-    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
-    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
-    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
-    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
-    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
-    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
-    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
-    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
-]);
-function rotateRight(value, bits) {
-    return (value >>> bits) | (value << (32 - bits));
-}
-function sha256Hex(bytes) {
-    // 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);
-    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) {
-        for (let index = 0; index < 16; index += 1)
-            words[index] = view.getUint32(offset + index * 4, false);
-        for (let index = 16; index < 64; index += 1) {
-            const left = words[index - 15];
-            const right = words[index - 2];
-            const sigma0 = rotateRight(left, 7) ^ rotateRight(left, 18) ^ (left >>> 3);
-            const sigma1 = rotateRight(right, 17) ^ rotateRight(right, 19) ^ (right >>> 10);
-            words[index] = (words[index - 16] + sigma0 + words[index - 7] + sigma1) >>> 0;
-        }
-        let [a, b, c, d, e, f, g, h] = state;
-        for (let index = 0; index < 64; index += 1) {
-            const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
-            const choice = (e & f) ^ (~e & g);
-            const first = (h + sum1 + choice + SHA256_CONSTANTS[index] + words[index]) >>> 0;
-            const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
-            const majority = (a & b) ^ (a & c) ^ (b & c);
-            const second = (sum0 + majority) >>> 0;
-            h = g;
-            g = f;
-            f = e;
-            e = (d + first) >>> 0;
-            d = c;
-            c = b;
-            b = a;
-            a = (first + second) >>> 0;
-        }
-        state[0] = (state[0] + a) >>> 0;
-        state[1] = (state[1] + b) >>> 0;
-        state[2] = (state[2] + c) >>> 0;
-        state[3] = (state[3] + d) >>> 0;
-        state[4] = (state[4] + e) >>> 0;
-        state[5] = (state[5] + f) >>> 0;
-        state[6] = (state[6] + g) >>> 0;
-        state[7] = (state[7] + h) >>> 0;
-    }
-    return [...state].map((value) => value.toString(16).padStart(8, '0')).join('');
-}
 function stableHash(parts) {
-    return sha256Hex(new TextEncoder().encode(canonicalAnalystReviewIdentityJson(parts)));
+    return sha256IdentityHex(new TextEncoder().encode(canonicalAnalystReviewIdentityJson(parts)));
 }
 export function analystReviewSubjectKey(evidenceFamily, stableParts) {
     if (!FAMILY_VALUES.has(evidenceFamily))
@@ -421,6 +357,11 @@ function snapshotIdentity(snapshot) {
         snapshot.expiresAt,
     ]);
 }
+export function analystReviewDecisionIdentity(subjectKey, snapshot) {
+    if (!SAFE_SUBJECT_RE.test(subjectKey))
+        throw inputError('Review subject identity is invalid');
+    return `decision:${stableHash([subjectKey, snapshotIdentity(snapshot)])}`;
+}
 function mergedReviewHistory(current, other) {
     const currentIdentity = snapshotIdentity(currentSnapshot(current));
     const byIdentity = new Map();
@@ -445,10 +386,10 @@ export function setAnalystReviewDecision(raw, item, input) {
     }
     if (!DISPOSITION_VALUES.has(input.disposition))
         throw new TypeError('Choose a valid Review Item disposition.');
-    if (input.disposition === 'resolved' && (item.completeness !== 'complete' || item.age === 'stale')) {
-        throw new Error('Partial, inconclusive, or stale evidence cannot resolve a Review Item. Refresh or attach current complete evidence first.');
+    if (input.disposition === 'resolved' && !analystReviewCanResolve(item)) {
+        throw new Error('Partial, inconclusive, stale or undated evidence cannot resolve a Review Item. Refresh or attach current complete evidence first.');
     }
-    const rationale = boundedText(input.rationale, MAX_ANALYST_REVIEW_RATIONALE_LENGTH, 'rationale');
+    const rationale = boundedRationale(input.rationale, 'rationale', true);
     const reviewedAt = timestamp(input.reviewedAt ?? new Date().toISOString(), 'reviewedAt');
     const expiresAt = timestamp(input.expiresAt, 'expiresAt', true);
     const reviewDueAt = timestamp(input.reviewDueAt, 'reviewDueAt', true);
@@ -492,7 +433,14 @@ export function analystReviewLifecycle(item, raw, nowRaw = new Date().toISOStrin
     if (!decision) {
         return { state: 'open', effectiveDisposition: 'open', decision: null, reason: 'No analyst lifecycle decision is retained.', expired: false, invalidated: false, recurred: false, reviewDue: false };
     }
-    const now = timestamp(nowRaw, 'now');
+    const now = normalizeExplicitIsoTimestamp(nowRaw);
+    if (!now || Date.parse(now) < Date.parse(decision.reviewedAt)) {
+        return {
+            state: 'invalidated', effectiveDisposition: 'open', decision,
+            reason: 'The review clock is unavailable or earlier than the retained decision. Its disposition cannot hide current work.',
+            expired: false, invalidated: true, recurred: decision.disposition !== 'open', reviewDue: false,
+        };
+    }
     const invalidated = decision.reviewedFingerprint !== item.materialFingerprint;
     const expired = decision.expiresAt !== null && Date.parse(decision.expiresAt) <= Date.parse(now);
     const reviewDue = decision.reviewDueAt !== null && Date.parse(decision.reviewDueAt) <= Date.parse(now);
@@ -518,10 +466,10 @@ export function analystReviewLifecycle(item, raw, nowRaw = new Date().toISOStrin
             expired: false, invalidated: false, recurred: true, reviewDue: true,
         };
     }
-    if (decision.disposition === 'resolved' && (item.completeness !== 'complete' || item.age === 'stale')) {
+    if (decision.disposition === 'resolved' && !analystReviewCanResolve(item)) {
         return {
             state: 'invalidated', effectiveDisposition: 'open', decision,
-            reason: 'The current evidence is partial, inconclusive, or stale, so the retained resolved decision cannot close this item.',
+            reason: 'The current evidence is partial, inconclusive, stale or undated, so the retained resolved decision cannot close this item.',
             expired: false, invalidated: true, recurred: true, reviewDue,
         };
     }
@@ -607,7 +555,7 @@ function normalizeDevelopmentSnapshot(raw, label) {
     return {
         reviewedFingerprint: developmentFingerprint(value.reviewedFingerprint, `${label}.reviewedFingerprint`),
         disposition: disposition(value.disposition, `${label}.disposition`),
-        rationale: boundedText(value.rationale, MAX_ANALYST_REVIEW_RATIONALE_LENGTH, `${label}.rationale`),
+        rationale: boundedRationale(value.rationale, `${label}.rationale`),
         reviewedAt,
         reviewDueAt: reviewDueAt && Date.parse(reviewDueAt) > Date.parse(reviewedAt) ? reviewDueAt : null,
         expiresAt: expiresAt && Date.parse(expiresAt) > Date.parse(reviewedAt) ? expiresAt : null,