@slicedearth/whoisleuth-cli 1.32.0

package/frontend/src/lib/analysis/investigation-guide.js

@@ -0,0 +1,500 @@
+import { normalizeDomain } from "./case-model.js";
+import { parse } from 'tldts';
+export const INVESTIGATION_GUIDE_SCHEMA = 'whoisleuth.investigation-recipe';
+export const INVESTIGATION_GUIDE_VERSION = 4;
+export const INVESTIGATION_GUIDE_LEGACY_VERSION = 1;
+export const INVESTIGATION_GUIDE_EXPORT_VERSION = 3;
+export const INVESTIGATION_GUIDE_SUPPORTED_VERSIONS = [2, 3, INVESTIGATION_GUIDE_VERSION];
+export const INVESTIGATION_GUIDE_EXPORT_SCHEMA = 'whoisleuth.investigation-recipe-summary';
+export const MAX_INVESTIGATION_GUIDE_DOMAIN_LENGTH = 253;
+export const MAX_INVESTIGATION_GUIDE_REVIEW_DOMAINS = 25;
+export const MAX_INVESTIGATION_GUIDE_REVIEW_NOTE_LENGTH = 500;
+export const MAX_INVESTIGATION_GUIDE_TIMESTAMP_LENGTH = 64;
+export const MAX_INVESTIGATION_GUIDE_SERIALIZED_BYTES = 12_288;
+export const MAX_INVESTIGATION_GUIDE_EXPORT_BYTES = 16_384;
+const CONTROL_RE = /[\x00-\x1f\x7f]/u;
+const SAFE_TEMPLATE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/u;
+const GUIDE_STATUSES = new Set(['active', 'paused']);
+const GUIDE_OUTCOMES = new Set(['pending', 'complete', 'partial', 'skipped']);
+function stage(id, workspace, label, detail, expectedEvidence, requestImpact, prerequisite, completionCriteria, instructions, requiresApproval) {
+    return Object.freeze({
+        id,
+        workspace,
+        label,
+        path: `/${workspace}`,
+        detail,
+        expectedEvidence,
+        requestImpact,
+        prerequisite,
+        completionCriteria,
+        instructions: Object.freeze([...instructions]),
+        requiresApproval,
+    });
+}
+function registrableGuideDomain(domain) {
+    return parse(domain).domain || domain;
+}
+function normalizeReviewDomains(values) {
+    if (!Array.isArray(values))
+        return { domains: [], truncated: false };
+    const domains = [];
+    const seen = new Set();
+    let truncated = false;
+    for (const value of values.slice(0, MAX_INVESTIGATION_GUIDE_REVIEW_DOMAINS + 1)) {
+        const domain = normalizeInvestigationGuideDomain(value);
+        if (!domain || seen.has(domain))
+            continue;
+        if (domains.length >= MAX_INVESTIGATION_GUIDE_REVIEW_DOMAINS) {
+            truncated = true;
+            break;
+        }
+        seen.add(domain);
+        domains.push(domain);
+    }
+    if (values.length > MAX_INVESTIGATION_GUIDE_REVIEW_DOMAINS + 1)
+        truncated = true;
+    return { domains, truncated };
+}
+export const INVESTIGATION_RECIPES = Object.freeze([
+    Object.freeze({
+        id: 'brand_sweep',
+        label: 'Brand sweep',
+        summary: 'Define the official brand boundary, discover candidates, triage a bounded set, inspect priority domains, and retain reviewed cases.',
+        targetLabel: 'Official domain',
+        stages: Object.freeze([
+            stage('brands', 'brands', 'Confirm brand profile', 'Review the official domain, allowlists, and brand context before generating candidates.', 'A bounded Brand Profile with the official domain and any reviewed allowlists.', 'Local-only. Opening Brands makes no analysis request.', 'Know the official domain and the brand boundary you intend to assess.', 'The relevant profile is reviewed, or this stage is explicitly skipped with the limitation understood.', ['Open the pre-filled profile form.', 'Add the brand name and any known trusted domains or registrars.', 'Save the profile, then mark this step reviewed.'], false),
+            stage('discover', 'discover', 'Discover candidates', 'Generate bounded permutations and optionally query separately attributed Certificate Transparency observations.', 'A reviewed candidate set with mutation and discovery provenance.', 'Candidate generation is local. Certificate Transparency search is an explicit network action with its own bounded request budget.', 'Confirm the profile boundary and choose the candidate sources you intend to use.', 'Useful candidates are shortlisted, or the result is marked partial or skipped without implying absence.', ['Generate a bounded candidate set from the pre-filled registrable domain.', 'Remove irrelevant candidates and keep only domains worth checking.', 'Send the selected candidates to Bulk. The handoff records the reviewed set and completes this step.'], true),
+            stage('bulk', 'bulk', 'Triage candidates', 'Scan only the candidate set you deliberately hand off and compare explainable domain signals.', 'Bounded fast or deep results with availability, source health, Risk factors, and relationship evidence.', 'Bulk collection makes one or more bounded analysis requests according to the selected depth and candidate count.', 'Review the handoff count, depth, and request implications before starting the scan.', 'Priority candidates are identified and incomplete sources remain visible, or the stage is marked partial.', ['Confirm the candidate queue came from Discover.', 'Choose Fast for registration triage or Deep for compact web and mail evidence.', 'Run the scan, review source limitations, then use Inspect on one priority row.'], true),
+            stage('lookup', 'lookup', 'Inspect priority domain', 'Open a priority candidate for separately attributed deep evidence and source comparison.', 'Registry, registrar, DNS, certificate, HTTP, page-identity, and threat-source observations where supported.', 'Deep Lookup can contact several public services within explicit deadlines and response caps.', 'Choose one candidate based on the triage evidence rather than the score alone.', 'Material evidence and limitations are reviewed; a case may be created only by an explicit analyst action.', ['Choose Inspect in Lookup on a priority Bulk row.', 'Run a Deep lookup for that candidate.', 'Review the source states and evidence, then mark this step reviewed or partial.'], true),
+            stage('monitor', 'monitor', 'Retain reviewed work', 'Create or update an analyst case and choose whether the domain belongs on a watchlist.', 'A bounded case timeline, analyst disposition, and optional compact monitoring baseline.', 'Local case work makes no request. A rescan or hosted-monitor change remains a separate explicit action.', 'Review evidence provenance and avoid converting a heuristic score into a verdict.', 'The analyst records the intended disposition or explicitly skips retention.', ['Open or create the pre-filled case for the inspected candidate.', 'Record an analyst disposition, notes, or follow-up only when supported by the evidence.', 'Mark this step reviewed when the retained record is useful.'], false),
+        ]),
+    }),
+    Object.freeze({
+        id: 'infrastructure_pivot',
+        label: 'Infrastructure pivot',
+        summary: 'Collect one domain, inspect explainable relationships, review connected evidence, and retain only defensible pivots.',
+        targetLabel: 'Starting domain',
+        stages: Object.freeze([
+            stage('lookup', 'lookup', 'Collect starting evidence', 'Run a deliberate deep lookup for the starting domain before evaluating infrastructure links.', 'Separately attributed registry, DNS, certificate, HTTP, and page evidence for the starting domain.', 'Deep Lookup can contact several public services within explicit deadlines and response caps.', 'Confirm the starting domain is in scope and review the deep collection implications.', 'The lookup settles with success, partial, unsupported, or error states preserved.', ['Run the pre-filled lookup in Deep mode.', 'Review DNS, certificate, network, redirect, and page-identity evidence.', 'Mark the step reviewed, or partial if important sources did not settle.'], true),
+            stage('bulk', 'bulk', 'Compare relationships', 'Use a bounded candidate set to inspect nameserver, IP, origin, favicon, tracker, and certificate relationships.', 'Explainable relationship rows with source observations, method, completeness, and truncation limits.', 'Bulk collection makes bounded analysis requests according to the selected candidate count and depth.', 'Prepare a focused candidate set; shared infrastructure alone is not proof of common control.', 'Useful pivots are reviewed with their limitations, or the stage is marked partial when sources are incomplete.', ['The starting domain is pre-filled. Add only domains that are plausible comparison peers.', 'Run a bounded scan and review the Relationships section below the table.', 'Treat shared infrastructure as a pivot, not attribution, then mark the step reviewed.'], true),
+            stage('monitor', 'monitor', 'Retain defensible pivots', 'Review the bounded domain set carried from Bulk and attach only defensible pivots to cases or campaigns without asserting ownership.', 'A bounded review queue plus analyst cases or campaign membership linked to retained source evidence.', 'Local case and campaign edits make no request. Any rescan is a separate explicit action.', 'Keep directly observed relationships separate from analyst conclusions.', 'Only defensible pivots are retained, or retention is explicitly skipped.', ['Review the domains carried from Bulk and open only the cases you intend to retain.', 'Record only relationships you reviewed, including their limitations.', 'Mark this step reviewed, or skip it if nothing is defensible enough to retain.'], false),
+        ]),
+    }),
+    Object.freeze({
+        id: 'new_domain_triage',
+        label: 'New-domain triage',
+        summary: 'Collect a domain, compare it with a focused peer set when useful, and record a reviewable disposition.',
+        targetLabel: 'Domain',
+        stages: Object.freeze([
+            stage('lookup', 'lookup', 'Collect domain evidence', 'Start with separately attributed registry and network evidence for the domain under review.', 'Authority-aware availability plus supported registry, DNS, certificate, HTTP, page, and threat-source observations.', 'Fast and deep Lookup have different request budgets. Collection starts only from the tool action you choose.', 'Confirm the domain is in scope and select the appropriate lookup depth.', 'Available evidence and explicit source failures are reviewed without treating a miss as safety.', ['Confirm the pre-filled domain and choose Fast or Deep.', 'Run the lookup and review source states before interpreting the result.', 'Mark the step reviewed, or partial if important evidence did not settle.'], true),
+            stage('bulk', 'bulk', 'Compare focused peers', 'Optionally compare the domain with a small candidate set to expose relative signals and shared infrastructure.', 'Bounded peer results and relationship evidence with explainable factors.', 'Bulk makes bounded analysis requests according to candidate count and selected depth.', 'Use only a focused, relevant peer set; this stage may be skipped when comparison adds no value.', 'Relevant differences are reviewed, or the stage is marked skipped or partial with the reason retained outside this compact record.', ['The investigated domain is pre-filled. Add only relevant comparison domains.', 'Run a bounded scan and compare registration, activity, Risk factors, and relationships.', 'Mark the step reviewed, partial, or skip it when peer comparison adds no value.'], true),
+            stage('monitor', 'monitor', 'Record disposition', 'Review the bounded domain set carried from Bulk and create or update only the cases that need an analyst decision or follow-up plan.', 'A bounded review queue plus case records with dispositions, notes, evidence history, and optional monitoring intent.', 'Local case editing makes no request. Rescans and hosted-monitor changes remain separate explicit actions.', 'Review source provenance, limitations, and any scoring explanation before deciding.', 'The analyst records the required dispositions or explicitly skips retention; the recipe never decides automatically.', ['Review the domains carried from Bulk and open only the cases that need retention.', 'Record a disposition and any concise evidence-based follow-up for each retained case.', 'Mark the step reviewed when the retained cases reflect your decision.'], false),
+        ]),
+    }),
+]);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function timestamp(value) {
+    if (typeof value !== 'string' || value.length > MAX_INVESTIGATION_GUIDE_TIMESTAMP_LENGTH || CONTROL_RE.test(value))
+        return '';
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : '';
+}
+function nullableTimestamp(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    return timestamp(value) || null;
+}
+function boundedTemplateText(value, maximum, fallback = '') {
+    if (typeof value !== 'string' || value.length > maximum * 4 || CONTROL_RE.test(value))
+        return fallback;
+    return value.replace(/\s+/gu, ' ').trim().slice(0, maximum).trim() || fallback;
+}
+function boundedReviewNote(value) {
+    if (typeof value !== 'string' || value.length > MAX_INVESTIGATION_GUIDE_REVIEW_NOTE_LENGTH * 4)
+        return null;
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+    return normalized ? normalized.slice(0, MAX_INVESTIGATION_GUIDE_REVIEW_NOTE_LENGTH).trim() || null : null;
+}
+function templateInstructions(value, fallback) {
+    if (!Array.isArray(value))
+        return fallback;
+    const instructions = value
+        .slice(0, 6)
+        .map((item) => boundedTemplateText(item, 240))
+        .filter(Boolean);
+    return instructions.length ? instructions : fallback;
+}
+export function normalizeInvestigationGuideTemplateSnapshot(value, requiredRecipeId = null) {
+    const input = record(value);
+    const id = typeof input?.id === 'string' && SAFE_TEMPLATE_ID_RE.test(input.id) ? input.id : '';
+    const recipe = investigationGuideRecipe(input?.recipeId);
+    const label = boundedTemplateText(input?.label, 80);
+    if (!id || !recipe || !label || (requiredRecipeId && recipe.id !== requiredRecipeId))
+        return null;
+    const supplied = new Map();
+    for (const candidate of (Array.isArray(input?.stages) ? input.stages : []).slice(0, recipe.stages.length * 2)) {
+        const item = record(candidate);
+        if (item && typeof item.id === 'string' && !supplied.has(item.id))
+            supplied.set(item.id, item);
+    }
+    const stages = recipe.stages.flatMap((base) => {
+        const item = supplied.get(base.id);
+        if (!item || item.enabled === false)
+            return [];
+        return [{
+                ...base,
+                label: boundedTemplateText(item.label, 100, base.label),
+                detail: boundedTemplateText(item.detail, 400, base.detail),
+                expectedEvidence: boundedTemplateText(item.expectedEvidence, 500, base.expectedEvidence),
+                completionCriteria: boundedTemplateText(item.completionCriteria, 500, base.completionCriteria),
+                instructions: templateInstructions(item.instructions, base.instructions),
+                requiresApproval: base.requiresApproval || item.requiresApproval === true,
+            }];
+    });
+    if (!stages.length)
+        return null;
+    return {
+        id,
+        label,
+        summary: boundedTemplateText(input?.summary, 400, recipe.summary),
+        recipeId: recipe.id,
+        stages,
+    };
+}
+export function investigationGuideStagesForGuide(value) {
+    const guide = record(value);
+    const recipe = investigationGuideRecipe(guide?.recipeId);
+    if (!recipe)
+        return [];
+    return normalizeInvestigationGuideTemplateSnapshot(guide?.template, recipe.id)?.stages || recipe.stages;
+}
+function investigationGuideStageForGuide(value, stageId) {
+    return typeof stageId === 'string'
+        ? investigationGuideStagesForGuide(value).find((candidate) => candidate.id === stageId) || null
+        : null;
+}
+export function investigationGuideStageForGuidePath(value, pathname) {
+    if (typeof pathname !== 'string')
+        return null;
+    return investigationGuideStagesForGuide(value)
+        .find((candidate) => pathname === candidate.path || pathname.startsWith(`${candidate.path}/`)) || null;
+}
+function guideStatus(value) {
+    return typeof value === 'string' && GUIDE_STATUSES.has(value)
+        ? value
+        : 'active';
+}
+function guideOutcome(value) {
+    return typeof value === 'string' && GUIDE_OUTCOMES.has(value)
+        ? value
+        : 'pending';
+}
+/**
+ * The launcher accepts one bare DNS hostname only. Unlike evidence-import
+ * normalization, it does not silently strip a URL, path, port, or userinfo.
+ */
+export function normalizeInvestigationGuideDomain(value) {
+    if (typeof value !== 'string' || value.length > MAX_INVESTIGATION_GUIDE_DOMAIN_LENGTH
+        || /[\x00-\x1f\x7f\s\\/%@:?#]/u.test(value))
+        return '';
+    const trimmed = value.trim();
+    if (!trimmed)
+        return '';
+    return normalizeDomain(trimmed);
+}
+export function investigationGuideRecipe(value) {
+    return typeof value === 'string'
+        ? INVESTIGATION_RECIPES.find((recipe) => recipe.id === value) || null
+        : null;
+}
+export function investigationGuideStagesForRecipe(value) {
+    return investigationGuideRecipe(value)?.stages || [];
+}
+export function investigationGuideStage(value, recipeId = 'new_domain_triage') {
+    return typeof value === 'string'
+        ? investigationGuideStagesForRecipe(recipeId).find((candidate) => candidate.id === value) || null
+        : null;
+}
+export function investigationGuideStageForPath(pathname, recipeId = 'new_domain_triage') {
+    if (typeof pathname !== 'string')
+        return null;
+    return investigationGuideStagesForRecipe(recipeId)
+        .find((candidate) => pathname === candidate.path || pathname.startsWith(`${candidate.path}/`)) || null;
+}
+export function investigationGuideHref(stageId, domain, recipeId = 'new_domain_triage', focusDomain = null) {
+    const stageDefinition = investigationGuideStage(stageId, recipeId);
+    const normalized = normalizeInvestigationGuideDomain(domain);
+    const normalizedFocus = normalizeInvestigationGuideDomain(focusDomain);
+    if (!stageDefinition || !normalized)
+        return '/dashboard';
+    const workingDomain = normalizedFocus || normalized;
+    if (stageDefinition.workspace === 'lookup') {
+        if (recipeId === 'brand_sweep' && !normalizedFocus)
+            return '/bulk#results';
+        return `/lookup?q=${encodeURIComponent(workingDomain)}&depth=deep#query`;
+    }
+    if (stageDefinition.workspace === 'discover')
+        return `/discover?q=${encodeURIComponent(registrableGuideDomain(normalized))}#discovery-seed`;
+    if (stageDefinition.workspace === 'bulk')
+        return `/bulk?investigation=${encodeURIComponent(normalized)}#domains`;
+    if (stageDefinition.workspace === 'monitor')
+        return `/monitor?view=cases&investigation=1&domain=${encodeURIComponent(workingDomain)}#case-review-queue`;
+    if (stageDefinition.workspace === 'brands')
+        return `/brands?new=1&domain=${encodeURIComponent(normalized)}#official-domains`;
+    return stageDefinition.path;
+}
+function createStageProgress(stageDefinition, now) {
+    return { id: stageDefinition.id, outcome: 'pending', approvedAt: null, openedAt: null, reviewNote: null, updatedAt: now };
+}
+export function createInvestigationGuide(domain, recipeId = 'new_domain_triage', now = new Date().toISOString(), templateValue = null) {
+    const normalized = normalizeInvestigationGuideDomain(domain);
+    const recipe = investigationGuideRecipe(recipeId);
+    const createdAt = timestamp(now);
+    if (!normalized || !recipe || !createdAt)
+        return null;
+    const template = templateValue === null || templateValue === undefined
+        ? null
+        : normalizeInvestigationGuideTemplateSnapshot(templateValue, recipe.id);
+    if (templateValue !== null && templateValue !== undefined && !template)
+        return null;
+    const stages = template?.stages || recipe.stages;
+    return {
+        version: INVESTIGATION_GUIDE_VERSION,
+        recipeId: recipe.id,
+        template,
+        domain: normalized,
+        focusDomain: null,
+        reviewDomains: recipe.id === 'brand_sweep' ? [] : [normalized],
+        reviewDomainsTruncated: false,
+        status: 'active',
+        createdAt,
+        updatedAt: createdAt,
+        stages: stages.map((stageDefinition) => createStageProgress(stageDefinition, createdAt)),
+    };
+}
+function parseLegacyGuide(input) {
+    const domain = normalizeInvestigationGuideDomain(input.domain);
+    const createdAt = timestamp(input.createdAt);
+    const updatedAt = timestamp(input.updatedAt);
+    const recipe = investigationGuideRecipe('new_domain_triage');
+    if (!domain || !createdAt || !updatedAt || !recipe)
+        return null;
+    const opened = new Set((Array.isArray(input.visitedStages) ? input.visitedStages : [])
+        .slice(0, recipe.stages.length * 2)
+        .filter((value) => typeof value === 'string'));
+    return {
+        version: INVESTIGATION_GUIDE_VERSION,
+        recipeId: recipe.id,
+        template: null,
+        domain,
+        focusDomain: null,
+        reviewDomains: [domain],
+        reviewDomainsTruncated: false,
+        status: 'active',
+        createdAt,
+        updatedAt,
+        stages: recipe.stages.map((stageDefinition) => ({
+            ...createStageProgress(stageDefinition, updatedAt),
+            openedAt: opened.has(stageDefinition.id) ? updatedAt : null,
+        })),
+    };
+}
+export function parseInvestigationGuide(value) {
+    const input = record(value);
+    if (!input)
+        return null;
+    if (input.version === INVESTIGATION_GUIDE_LEGACY_VERSION)
+        return parseLegacyGuide(input);
+    if (!INVESTIGATION_GUIDE_SUPPORTED_VERSIONS.includes(input.version))
+        return null;
+    const recipe = investigationGuideRecipe(input.recipeId);
+    const domain = normalizeInvestigationGuideDomain(input.domain);
+    const createdAt = timestamp(input.createdAt);
+    const updatedAt = timestamp(input.updatedAt);
+    if (!recipe || !domain || !createdAt || !updatedAt)
+        return null;
+    const supportsTemplate = input.version === 3 || input.version === INVESTIGATION_GUIDE_VERSION;
+    const template = supportsTemplate && input.template !== null && input.template !== undefined
+        ? normalizeInvestigationGuideTemplateSnapshot(input.template, recipe.id)
+        : null;
+    if (supportsTemplate && input.template !== null && input.template !== undefined && !template)
+        return null;
+    const stageDefinitions = template?.stages || recipe.stages;
+    const normalizedReview = normalizeReviewDomains(input.reviewDomains);
+    const reviewDomains = normalizedReview.domains.length
+        ? normalizedReview.domains
+        : recipe.id === 'brand_sweep' ? [] : [domain];
+    const supplied = new Map();
+    for (const candidate of (Array.isArray(input.stages) ? input.stages : []).slice(0, stageDefinitions.length * 2)) {
+        const item = record(candidate);
+        if (item && typeof item.id === 'string' && !supplied.has(item.id))
+            supplied.set(item.id, item);
+    }
+    return {
+        version: INVESTIGATION_GUIDE_VERSION,
+        recipeId: recipe.id,
+        template,
+        domain,
+        focusDomain: recipe.id === 'brand_sweep' ? normalizeInvestigationGuideDomain(input.focusDomain) || null : null,
+        reviewDomains,
+        reviewDomainsTruncated: normalizedReview.truncated || input.reviewDomainsTruncated === true,
+        status: guideStatus(input.status),
+        createdAt,
+        updatedAt,
+        stages: stageDefinitions.map((stageDefinition) => {
+            const item = supplied.get(stageDefinition.id);
+            return {
+                id: stageDefinition.id,
+                outcome: guideOutcome(item?.outcome),
+                approvedAt: nullableTimestamp(item?.approvedAt),
+                openedAt: nullableTimestamp(item?.openedAt),
+                reviewNote: input.version === INVESTIGATION_GUIDE_VERSION ? boundedReviewNote(item?.reviewNote) : null,
+                updatedAt: timestamp(item?.updatedAt) || updatedAt,
+            };
+        }),
+    };
+}
+export function setInvestigationGuideFocusDomain(value, domain, now = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const focusDomain = normalizeInvestigationGuideDomain(domain);
+    const updatedAt = timestamp(now);
+    if (!guide || guide.recipeId !== 'brand_sweep' || !focusDomain || !updatedAt || guide.status === 'paused')
+        return guide;
+    if (guide.focusDomain === focusDomain)
+        return guide;
+    return { ...guide, focusDomain, updatedAt };
+}
+export function setInvestigationGuideReviewDomains(value, domains, now = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const updatedAt = timestamp(now);
+    if (!guide || !updatedAt || guide.status === 'paused')
+        return guide;
+    const reviewDomains = Array.isArray(domains) ? domains : [];
+    const normalized = normalizeReviewDomains(guide.recipeId === 'brand_sweep'
+        ? reviewDomains
+        : [guide.domain, ...reviewDomains]);
+    const reviewDomainsTruncated = normalized.truncated;
+    if (guide.reviewDomainsTruncated === reviewDomainsTruncated
+        && guide.reviewDomains.length === normalized.domains.length
+        && guide.reviewDomains.every((domain, index) => domain === normalized.domains[index]))
+        return guide;
+    return { ...guide, reviewDomains: normalized.domains, reviewDomainsTruncated, updatedAt };
+}
+function updateStage(value, stageId, now, updater) {
+    const guide = parseInvestigationGuide(value);
+    const updatedAt = timestamp(now);
+    const stageDefinition = investigationGuideStageForGuide(guide, stageId);
+    if (!guide || !updatedAt || !stageDefinition)
+        return guide;
+    return {
+        ...guide,
+        updatedAt,
+        stages: guide.stages.map((progress) => progress.id === stageDefinition.id ? updater(progress, updatedAt) : progress),
+    };
+}
+export function visitInvestigationGuide(value, pathname, now = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const stageDefinition = investigationGuideStageForGuidePath(guide, pathname);
+    if (!guide || guide.status === 'paused' || !stageDefinition)
+        return guide;
+    const progress = guide.stages.find((item) => item.id === stageDefinition.id);
+    if (stageDefinition.requiresApproval && !progress?.approvedAt)
+        return guide;
+    if (progress?.openedAt)
+        return guide;
+    return updateStage(guide, stageDefinition.id, now, (current, updatedAt) => ({ ...current, openedAt: updatedAt, updatedAt }));
+}
+export function approveInvestigationGuideStage(value, stageId, now = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const stageDefinition = investigationGuideStageForGuide(guide, stageId);
+    if (!guide || guide.status === 'paused' || !stageDefinition?.requiresApproval)
+        return guide;
+    const progress = guide.stages.find((item) => item.id === stageDefinition.id);
+    if (progress?.approvedAt)
+        return guide;
+    return updateStage(guide, stageDefinition.id, now, (current, updatedAt) => ({ ...current, approvedAt: updatedAt, updatedAt }));
+}
+export function setInvestigationGuideStageOutcome(value, stageId, outcome, now = new Date().toISOString(), reviewNote = null) {
+    const guide = parseInvestigationGuide(value);
+    const normalizedOutcome = guideOutcome(outcome);
+    const normalizedReviewNote = boundedReviewNote(reviewNote);
+    const stageDefinition = investigationGuideStageForGuide(guide, stageId);
+    if (!guide || guide.status === 'paused' || !stageDefinition)
+        return guide;
+    const progress = guide.stages.find((item) => item.id === stageDefinition.id);
+    if (!progress || ((normalizedOutcome === 'complete' || normalizedOutcome === 'partial') && !progress.openedAt))
+        return guide;
+    if ((normalizedOutcome === 'partial' || normalizedOutcome === 'skipped') && !normalizedReviewNote)
+        return guide;
+    const nextReviewNote = normalizedOutcome === 'pending' ? null : normalizedReviewNote;
+    if (progress.outcome === normalizedOutcome && progress.reviewNote === nextReviewNote)
+        return guide;
+    return updateStage(guide, stageDefinition.id, now, (current, updatedAt) => ({
+        ...current,
+        outcome: normalizedOutcome,
+        reviewNote: nextReviewNote,
+        updatedAt,
+    }));
+}
+export function setInvestigationGuideStatus(value, status, now = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const updatedAt = timestamp(now);
+    if (!guide || !updatedAt || typeof status !== 'string' || !GUIDE_STATUSES.has(status))
+        return guide;
+    if (guide.status === status)
+        return guide;
+    return { ...guide, status: status, updatedAt };
+}
+export function restartInvestigationGuide(value, now = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    return guide ? createInvestigationGuide(guide.domain, guide.recipeId, now, guide.template) : null;
+}
+export function buildInvestigationGuideSummary(value, generatedAt = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const recipe = investigationGuideRecipe(guide?.recipeId);
+    const normalizedGeneratedAt = timestamp(generatedAt);
+    if (!guide || !recipe || !normalizedGeneratedAt)
+        return null;
+    const stages = [];
+    for (const stageDefinition of investigationGuideStagesForGuide(guide)) {
+        const progress = guide.stages.find((candidate) => candidate.id === stageDefinition.id);
+        if (!progress)
+            return null;
+        stages.push({
+            id: stageDefinition.id,
+            workspace: stageDefinition.workspace,
+            outcome: progress.outcome,
+            approved: progress.approvedAt !== null,
+            opened: progress.openedAt !== null,
+            reviewNote: progress.reviewNote,
+            updatedAt: progress.updatedAt,
+        });
+    }
+    return {
+        schema: INVESTIGATION_GUIDE_EXPORT_SCHEMA,
+        version: INVESTIGATION_GUIDE_EXPORT_VERSION,
+        generatedAt: normalizedGeneratedAt,
+        recipe: { id: recipe.id, label: recipe.label },
+        template: guide.template ? { id: guide.template.id, label: guide.template.label } : null,
+        target: { type: 'domain', value: guide.domain },
+        status: guide.status,
+        createdAt: guide.createdAt,
+        updatedAt: guide.updatedAt,
+        stages,
+        limitations: [
+            'This compact summary records analyst-controlled recipe progress and bounded stage-review notes only. It contains no raw evidence, case notes, credentials, provider responses, or scan results.',
+            'Opened, approved, complete, partial, and skipped states are analyst workflow markers, not findings or claims about the target.',
+            'The recipe never starts collection, submits a target, exports evidence, or changes a case disposition automatically.',
+        ],
+    };
+}
+export function investigationGuideSummaryFilename(value, generatedAt = new Date().toISOString()) {
+    const guide = parseInvestigationGuide(value);
+    const normalizedGeneratedAt = timestamp(generatedAt);
+    if (!guide || !normalizedGeneratedAt)
+        return 'whoisleuth-investigation-recipe.json';
+    const safeDomain = guide.domain.replace(/[^a-z0-9.-]+/giu, '-').replace(/\.{2,}/gu, '.').slice(0, 120) || 'domain';
+    return `whoisleuth-recipe-${safeDomain}-${normalizedGeneratedAt.replace(/[:.]/gu, '-')}.json`;
+}

package/frontend/src/lib/analysis/investigation-template-model.js

@@ -0,0 +1,144 @@
+import { INVESTIGATION_RECIPES, normalizeInvestigationGuideTemplateSnapshot, } from "./investigation-guide.js";
+export const INVESTIGATION_TEMPLATE_SCHEMA = 'whoisleuth.investigation-templates';
+export const INVESTIGATION_TEMPLATE_VERSION = 1;
+export const MAX_INVESTIGATION_TEMPLATES = 20;
+export const MAX_INVESTIGATION_TEMPLATE_STORE_BYTES = 256 * 1024;
+export const MAX_INVESTIGATION_TEMPLATE_IMPORT_BYTES = 384 * 1024;
+const CONTROL_RE = /[\x00-\x1f\x7f]/u;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function timestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || CONTROL_RE.test(value))
+        return '';
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : '';
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function template(raw) {
+    const value = record(raw);
+    const snapshot = normalizeInvestigationGuideTemplateSnapshot(value);
+    const createdAt = timestamp(value?.createdAt);
+    const updatedAt = timestamp(value?.updatedAt);
+    return snapshot && createdAt && updatedAt
+        ? { ...snapshot, createdAt, updatedAt }
+        : null;
+}
+export function normalizeInvestigationTemplate(raw) {
+    return template(raw);
+}
+export function normalizeInvestigationTemplateStore(raw) {
+    const value = record(raw);
+    if (value?.schema === INVESTIGATION_TEMPLATE_SCHEMA
+        && Number(value.version) > INVESTIGATION_TEMPLATE_VERSION) {
+        throw new Error('This investigation-template collection uses a newer schema and cannot be read safely.');
+    }
+    const source = Array.isArray(raw) ? raw : Array.isArray(value?.templates) ? value.templates : [];
+    const templates = [];
+    const seen = new Set();
+    for (const candidate of source.slice(0, MAX_INVESTIGATION_TEMPLATES * 2)) {
+        const normalized = template(candidate);
+        if (!normalized || seen.has(normalized.id))
+            continue;
+        seen.add(normalized.id);
+        templates.push(normalized);
+    }
+    templates.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    return {
+        schema: INVESTIGATION_TEMPLATE_SCHEMA,
+        version: INVESTIGATION_TEMPLATE_VERSION,
+        templates: templates.slice(0, MAX_INVESTIGATION_TEMPLATES),
+    };
+}
+export function investigationTemplateStoreVersion(raw) {
+    const value = record(raw);
+    return Number.isSafeInteger(value?.version) ? Number(value?.version) : INVESTIGATION_TEMPLATE_VERSION;
+}
+export function serializeInvestigationTemplateStore(raw) {
+    const serialized = JSON.stringify(normalizeInvestigationTemplateStore(raw));
+    if (byteLength(serialized) > MAX_INVESTIGATION_TEMPLATE_STORE_BYTES) {
+        throw new Error('Investigation templates exceed the 256 KiB browser-local limit.');
+    }
+    return serialized;
+}
+export function createInvestigationTemplate(raw, options = {}) {
+    const value = record(raw);
+    const now = timestamp(options.now ?? new Date().toISOString());
+    const recipeId = value?.recipeId;
+    const recipe = INVESTIGATION_RECIPES.find((candidate) => candidate.id === recipeId);
+    const id = typeof value?.id === 'string' && value.id
+        ? value.id
+        : (options.makeId ?? (() => crypto.randomUUID()))();
+    const createdAt = timestamp(value?.createdAt) || now;
+    const candidate = normalizeInvestigationTemplate({
+        ...value,
+        id,
+        recipeId: recipe?.id,
+        createdAt,
+        updatedAt: now,
+    });
+    if (!candidate)
+        throw new Error('The investigation template is incomplete or invalid.');
+    return candidate;
+}
+export function saveInvestigationTemplate(localRaw, candidateRaw) {
+    const candidate = normalizeInvestigationTemplate(candidateRaw);
+    if (!candidate)
+        throw new Error('The investigation template is incomplete or invalid.');
+    const local = normalizeInvestigationTemplateStore(localRaw).templates;
+    return normalizeInvestigationTemplateStore([
+        candidate,
+        ...local.filter((item) => item.id !== candidate.id),
+    ]).templates;
+}
+export function deleteInvestigationTemplate(localRaw, id) {
+    return normalizeInvestigationTemplateStore(localRaw).templates.filter((item) => item.id !== id);
+}
+export function buildInvestigationTemplateExport(raw, generatedAt = new Date().toISOString()) {
+    return {
+        ...normalizeInvestigationTemplateStore(raw),
+        generatedAt: timestamp(generatedAt) || new Date().toISOString(),
+        limitations: [
+            'Templates contain allowlisted WHOISleuth tool steps and analyst-authored guidance only.',
+            'A template cannot run code, start collection, submit evidence, change a case, or bypass a required request approval gate.',
+            'Workflow outcomes are analyst progress markers and are not findings about a target.',
+        ],
+    };
+}
+function strictImport(raw) {
+    const value = record(raw);
+    if (value?.schema !== INVESTIGATION_TEMPLATE_SCHEMA || !Number.isSafeInteger(value.version)) {
+        throw new Error('Expected a versioned WHOISleuth investigation-template export.');
+    }
+    if (Number(value.version) > INVESTIGATION_TEMPLATE_VERSION) {
+        throw new Error('This investigation-template export uses a newer schema and cannot be imported safely.');
+    }
+    if (value.version !== INVESTIGATION_TEMPLATE_VERSION) {
+        throw new Error(`Expected investigation-template schema ${INVESTIGATION_TEMPLATE_VERSION}.`);
+    }
+    return normalizeInvestigationTemplateStore(value).templates;
+}
+export function mergeInvestigationTemplates(localRaw, incomingRaw) {
+    const local = normalizeInvestigationTemplateStore(localRaw).templates;
+    const incoming = strictImport(incomingRaw);
+    const byId = new Map(local.map((item) => [item.id, item]));
+    let added = 0;
+    let updated = 0;
+    for (const item of incoming) {
+        if (byId.has(item.id))
+            updated += 1;
+        else
+            added += 1;
+        byId.set(item.id, item);
+    }
+    const templates = normalizeInvestigationTemplateStore([...byId.values()]).templates;
+    return {
+        templates,
+        added,
+        updated,
+        skipped: Math.max(0, incoming.length - added - updated),
+        pruned: Math.max(0, byId.size - templates.length),
+    };
+}