@slicedearth/whoisleuth-cli 1.39.1 → 1.45.0

package/cli/completion.mjs

@@ -1,32 +1,43 @@
 import { CLI_COMMANDS } from "./arguments.mjs";
 import { INVESTIGATION_PLAN_RECIPES } from "./investigation-plan.mjs";
-const COMMON_OPTIONS = Object.freeze(['--help', '--output', '--force']);
+const COMMON_OPTIONS = Object.freeze(['--help', '--output', '--force', '--config', '--profile']);
 const OPTIONS_BY_COMMAND = Object.freeze({
-    lookup: ['--json', '--markdown', '--html', '--fast', '--deep', '--observer', '--vantage', '--plan', '--summary', '--verbose', '--strict-exit', '--events', '--quiet', '--no-color'],
-    bulk: ['--json', '--jsonl', '--csv', '--domains', '--queries', '--registered-only', '--inconclusive-only', '--errors-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--quiet', '--no-color'],
+    manifest: ['--workflow', '--configuration-digest', '--json', '--quiet', '--no-color'],
+    'map-observations': ['--json', '--quiet', '--no-color'],
+    'oam-export': ['--json', '--quiet', '--no-color'],
+    lookup: ['--json', '--junit', '--markdown', '--html', '--fast', '--deep', '--observer', '--vantage', '--plan', '--summary', '--verbose', '--strict-exit', '--fail-on', '--events', '--quiet', '--no-color'],
+    bulk: ['--json', '--jsonl', '--junit', '--csv', '--domains', '--queries', '--registered-only', '--inconclusive-only', '--errors-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--plan', '--fail-on', '--quiet', '--no-color'],
     'ct-search': ['--json', '--quiet', '--no-color'],
+    'ct-intake': ['--json', '--quiet', '--no-color'],
     discover: ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--snapshot', '--json', '--jsonl', '--domains', '--quiet', '--no-color'],
-    'discover-scan': ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--fast', '--deep', '--scan-limit', '--chunk-size', '--concurrency', '--resolver', '--allowlist', '--checkpoint', '--resume', '--observation-snapshot', '--registered-only', '--inconclusive-only', '--acquisition-only', '--suppressed-only', '--events', '--json', '--jsonl', '--csv', '--domains', '--quiet', '--no-color'],
-    posture: ['--selectors', '--retired-selectors', '--mail-profile', '--json', '--quiet', '--no-color'],
+    'discover-scan': ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--fast', '--deep', '--scan-limit', '--chunk-size', '--concurrency', '--resolver', '--allowlist', '--checkpoint', '--resume', '--observation-snapshot', '--registered-only', '--inconclusive-only', '--acquisition-only', '--suppressed-only', '--events', '--plan', '--fail-on', '--json', '--jsonl', '--csv', '--domains', '--quiet', '--no-color'],
+    posture: ['--selectors', '--retired-selectors', '--mail-profile', '--json', '--sarif', '--owned-domain', '--quiet', '--no-color'],
     http: ['--json', '--quiet', '--no-color'],
     tls: ['--json', '--quiet', '--no-color'],
     'registry-support': ['--json', '--quiet', '--no-color'],
     'registry-doctor': ['--json', '--quiet', '--no-color'],
+    'registry-cohort': ['--json', '--quiet', '--no-color'],
+    'registry-scaffold': ['--profile', '--suffix', '--scenario'],
     'risk-calibrate': ['--json', '--quiet', '--no-color'],
     'lookalike-calibrate': ['--json', '--quiet', '--no-color'],
     'verify-artifact': ['--passphrase-file', '--json', '--quiet', '--no-color'],
-    'inspect-archive': ['--passphrase-file', '--search', '--require-match', '--reveal', '--json', '--quiet', '--no-color'],
+    'inspect-archive': ['--passphrase-file', '--search', '--require-match', '--reveal', '--expect-content-digest', '--json', '--quiet', '--no-color'],
     'sign-artifact': ['--private-key-file'],
     'verify-signature': ['--public-key-file', '--json', '--quiet', '--no-color'],
     'source-report': ['--json', '--quiet', '--no-color'],
     compare: ['--json', '--quiet', '--no-color'],
     'page-compare': ['--json', '--quiet', '--no-color'],
     'mail-review': ['--json', '--quiet', '--no-color'],
-    'review-evidence': ['--mmdb', '--json', '--quiet', '--no-color'],
+    'review-evidence': ['--mmdb', '--json', '--strict-exit', '--quiet', '--no-color'],
+    brief: ['--json', '--quiet', '--no-color'],
+    'case-pack': ['--audience', '--reviewed', '--json', '--quiet', '--no-color'],
     'domain-control': ['--json', '--quiet', '--no-color'],
+    'monitor-once': ['--previous', '--limit', '--concurrency', '--fail-on', '--json', '--junit', '--quiet', '--no-color'],
     assurance: ['--json', '--quiet', '--no-color'],
+    'change-packet': ['--json', '--quiet', '--no-color'],
     'sharing-review': ['--marking', '--recipient-scope', '--purpose', '--human-reviewed', '--personal-data-reviewed', '--redactions-confirmed', '--json', '--quiet', '--no-color'],
     'workflow-plan': ['--json', '--quiet', '--no-color'],
+    'workflow-run': ['--approve-network', '--resume', '--json', '--quiet', '--no-color'],
     diff: ['--json', '--quiet', '--no-color'],
     reconcile: ['--json', '--quiet', '--no-color'],
     timeline: ['--json', '--quiet', '--no-color'],
@@ -37,9 +48,13 @@ const OPTIONS_BY_COMMAND = Object.freeze({
     manual: [],
 });
 const COMMAND_DESCRIPTIONS = Object.freeze({
+    manifest: 'Build an evidence manifest offline',
+    'map-observations': 'Normalise passive DNS observations offline',
+    'oam-export': 'Export an observation-archive map offline',
     lookup: 'Collect one domain, IP, or ASN',
     bulk: 'Run bounded multi-target collection',
     'ct-search': 'Search certificate observations',
+    'ct-intake': 'Normalise certificate observations offline',
     discover: 'Generate lookalike candidates offline',
     'discover-scan': 'Collect a supervised candidate review queue',
     posture: 'Review DNS and mail posture',
@@ -47,6 +62,8 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     tls: 'Inspect one TLS connection',
     'registry-support': 'Explain local registry coverage',
     'registry-doctor': 'Diagnose saved registry collection',
+    'registry-cohort': 'Aggregate target-free registry quality cohorts',
+    'registry-scaffold': 'Create a sanitised registry fixture scaffold',
     'risk-calibrate': 'Replay reviewed Risk labels offline',
     'lookalike-calibrate': 'Summarise reviewed lookalike yield offline',
     'verify-artifact': 'Validate saved evidence offline',
@@ -58,10 +75,15 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     'page-compare': 'Compare saved static page evidence',
     'mail-review': 'Review saved passive mail evidence',
     'review-evidence': 'Review supplied evidence offline',
+    brief: 'Build a decision brief from a saved lookup',
+    'case-pack': 'Build a reviewed case package',
     'domain-control': 'Build or review a domain control manifest',
+    'monitor-once': 'Run one bounded domain control review',
     assurance: 'Review domain change, recovery, or retirement plans',
+    'change-packet': 'Build a reviewed change packet offline',
     'sharing-review': 'Lint an artefact before deliberate sharing',
     'workflow-plan': 'Plan a fixed investigation recipe',
+    'workflow-run': 'Execute approved fixed-recipe steps',
     diff: 'Compare two saved domain lookups',
     reconcile: 'Reconcile independently labelled observations',
     timeline: 'Build same-domain history from saved lookups',
@@ -77,10 +99,12 @@ const VALUE_OPTIONS = Object.freeze({
     '--mail-profile': ['standard', 'defensive-no-mail', 'parked'],
     '--marking': ['clear', 'green', 'amber', 'amber-strict', 'red'],
     '--recipient-scope': ['public', 'community', 'organization', 'named-recipients'],
+    '--audience': ['internal', 'trusted', 'public'],
     '--concurrency': ['1', '2', '3', '4', '5', '6', '7', '8'],
 });
 const FILE_OPTIONS = Object.freeze([
     '--checkpoint',
+    '--config',
     '--allowlist',
     '--dictionary',
     '--output',
@@ -89,10 +113,22 @@ const FILE_OPTIONS = Object.freeze([
     '--public-key-file',
     '--snapshot',
     '--observation-snapshot',
+    '--previous',
+    '--resume',
+]);
+const FILE_POSITIONAL_COMMANDS = new Set([
+    'manifest',
+    'map-observations',
+    'oam-export',
+    'ct-intake',
+    'change-packet',
 ]);
 const TEXT_OPTIONS = Object.freeze([
     '--families',
     '--resolver',
+    '--fail-on',
+    '--expect-content-digest',
+    '--profile',
     '--purpose',
     '--observer',
     '--retired-selectors',
@@ -102,7 +138,7 @@ const TEXT_OPTIONS = Object.freeze([
     '--vantage',
 ]);
 function commandOptions(command) {
-    return [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])].join(' ');
+    return [...COMMON_OPTIONS, ...OPTIONS_BY_COMMAND[command]].join(' ');
 }
 function bashCompletion() {
     const cases = CLI_COMMANDS.map((command) => `    ${command}) options="${commandOptions(command)}" ;;`).join('\n');
@@ -134,6 +170,9 @@ ${valueCases}
 ${cases}
     *) options="--help" ;;
   esac
+  case " ${[...FILE_POSITIONAL_COMMANDS].join(' ')} " in
+    *" \${command} "*) [[ "\${current}" != -* ]] && COMPREPLY=( $(compgen -f -- "\${current}") ) && return ;;
+  esac
   COMPREPLY=( $(compgen -W "\${options}" -- "\${current}") )
 }
 complete -F _whoisleuth_completion whoisleuth
@@ -171,6 +210,10 @@ ${valueCases}
 ${cases}
     *) options=(--help) ;;
   esac
+  if [[ " ${[...FILE_POSITIONAL_COMMANDS].join(' ')} " == *" \${command} "* && "\${words[CURRENT]}" != -* ]]; then
+    _files
+    return
+  fi
   compadd -- \${options[@]}
 }
 if [[ "\${funcstack[1]}" == "_whoisleuth" ]]; then
@@ -181,13 +224,16 @@ fi
 `;
 }
 function fishCompletion() {
-    const commandLines = CLI_COMMANDS.map((command) => (`complete -c whoisleuth -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command] || command}'`));
-    const optionLines = Object.entries(OPTIONS_BY_COMMAND).flatMap(([command, options]) => ([...COMMON_OPTIONS, ...options].map((option) => {
+    const commandLines = CLI_COMMANDS.map((command) => (`complete -c whoisleuth -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command]}'${FILE_POSITIONAL_COMMANDS.has(command) ? ' -F' : ''}`));
+    const optionLine = (condition, option) => {
         const name = option.replace(/^--/u, '');
         const fileValue = FILE_OPTIONS.includes(option);
         const requiresValue = fileValue || [...Object.keys(VALUE_OPTIONS), ...TEXT_OPTIONS].includes(option);
-        return `complete -c whoisleuth -n '__fish_seen_subcommand_from ${command}' -l ${name}${requiresValue ? ' -r' : ''}${fileValue ? ' -F' : ''}`;
-    })));
+        return `complete -c whoisleuth -n '${condition}' -l ${name}${requiresValue ? ' -r' : ''}${fileValue ? ' -F' : ''}`;
+    };
+    const commonCondition = `__fish_seen_subcommand_from ${CLI_COMMANDS.join(' ')}`;
+    const commonOptionLines = COMMON_OPTIONS.map((option) => optionLine(commonCondition, option));
+    const optionLines = Object.entries(OPTIONS_BY_COMMAND).flatMap(([command, options]) => (options.map((option) => optionLine(`__fish_seen_subcommand_from ${command}`, option))));
     const valueLines = Object.entries(VALUE_OPTIONS).flatMap(([option, values]) => (values.map((value) => `complete -c whoisleuth -n '__fish_prev_arg_in ${option}' -a '${value}'`)));
     return `# WHOISleuth fish completion
 complete -c whoisleuth -f
@@ -196,6 +242,7 @@ complete -c whoisleuth -n '__fish_use_subcommand' -l version
 ${commandLines.join('\n')}
 complete -c whoisleuth -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish powershell'
 complete -c whoisleuth -n '__fish_seen_subcommand_from workflow-plan' -a '${INVESTIGATION_PLAN_RECIPES.join(' ')}'
+${commonOptionLines.join('\n')}
 ${optionLines.join('\n')}
 ${valueLines.join('\n')}
 `;
@@ -203,7 +250,7 @@ ${valueLines.join('\n')}
 function powershellCompletion() {
     const commandOptions = Object.fromEntries(CLI_COMMANDS.map((command) => [
         command,
-        [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])],
+        [...COMMON_OPTIONS, ...OPTIONS_BY_COMMAND[command]],
     ]));
     return `# WHOISleuth PowerShell completion
 Register-ArgumentCompleter -Native -CommandName whoisleuth -ScriptBlock {
@@ -217,9 +264,16 @@ ${Object.entries(VALUE_OPTIONS).map(([option, values]) => `    '${option}' = @($
     'completion' = @('bash', 'zsh', 'fish', 'powershell')
     'workflow-plan' = @(${INVESTIGATION_PLAN_RECIPES.map((value) => `'${value}'`).join(', ')})
   }
+  $fileCommands = @(${[...FILE_POSITIONAL_COMMANDS].map((command) => `'${command}'`).join(', ')})
   $elements = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
   $command = if ($elements.Count -gt 1) { $elements[1] } else { '' }
   $previous = if ($elements.Count -gt 1) { $elements[$elements.Count - 1] } else { '' }
+  if ($fileCommands -contains $command -and -not $wordToComplete.StartsWith('-')) {
+    Get-ChildItem -Path "${'$'}wordToComplete*" -File -ErrorAction SilentlyContinue | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_.FullName, $_.Name, 'ProviderItem', $_.FullName)
+    }
+    return
+  }
   $candidates = if ($elements.Count -le 2) {
     @($commands) + @('--help', '--version')
   } elseif ($command -eq 'completion' -and $elements.Count -le 3) {

package/cli/config-profile.mjs

@@ -0,0 +1,183 @@
+import { Buffer } from 'node:buffer';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { CliUsageError } from "./errors.mjs";
+import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
+export const CLI_CONFIG_SCHEMA = 'whoisleuth.cli.config';
+export const CLI_CONFIG_VERSION = 1;
+export const MAX_CLI_CONFIG_BYTES = 64 * 1024;
+const SAFE_BOOLEAN_DEFAULTS = new Set(['--no-color', '--summary', '--verbose', '--fast']);
+const SAFE_VALUE_DEFAULTS = new Set(['--concurrency', '--observer', '--vantage']);
+const OPTION_GROUPS = Object.freeze({
+    '--no-color': 'colour',
+    '--summary': 'detail',
+    '--verbose': 'detail',
+    '--fast': 'scan',
+    '--concurrency': 'concurrency',
+    '--observer': 'observer',
+    '--vantage': 'vantage',
+});
+function validProfileName(value) {
+    return typeof value === 'string' && /^[a-z0-9][a-z0-9_-]{0,39}$/u.test(value);
+}
+function safeArgumentText(value) {
+    if (typeof value !== 'string' || !value || value.length > 253 || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new CliUsageError('CLI profile arguments must be bounded text without control characters.');
+    }
+    return value;
+}
+function validateProfileArguments(value) {
+    if (!Array.isArray(value) || value.length > 16)
+        throw new CliUsageError('Each CLI profile is limited to 16 safe default arguments.');
+    const argumentsList = value.map(safeArgumentText);
+    const validated = [];
+    const groups = new Set();
+    for (let index = 0; index < argumentsList.length; index += 1) {
+        const argument = argumentsList[index];
+        if (SAFE_BOOLEAN_DEFAULTS.has(argument)) {
+            const group = OPTION_GROUPS[argument];
+            if (groups.has(group))
+                throw new CliUsageError(`CLI profile contains conflicting ${group} defaults.`);
+            groups.add(group);
+            validated.push(argument);
+            continue;
+        }
+        if (!SAFE_VALUE_DEFAULTS.has(argument)) {
+            throw new CliUsageError(`CLI profiles cannot set ${argument}. Only presentation labels, fast mode, and bounded concurrency are supported.`);
+        }
+        const next = argumentsList[++index];
+        if (!next || next.startsWith('-'))
+            throw new CliUsageError(`${argument} in a CLI profile requires one value.`);
+        const group = OPTION_GROUPS[argument];
+        if (groups.has(group))
+            throw new CliUsageError(`CLI profile contains duplicate ${group} defaults.`);
+        if (argument === '--concurrency' && (!/^\d+$/u.test(next) || Number(next) < 1 || Number(next) > 8)) {
+            throw new CliUsageError('CLI profile concurrency must be an integer from 1 to 8.');
+        }
+        groups.add(group);
+        validated.push(argument, next);
+    }
+    return validated;
+}
+function parseProfileDocument(input) {
+    if (Buffer.byteLength(input, 'utf8') > MAX_CLI_CONFIG_BYTES)
+        throw new CliUsageError('CLI configuration is limited to 64 KiB.');
+    let parsed;
+    try {
+        parsed = JSON.parse(input.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('CLI configuration must be valid JSON.');
+    }
+    const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    if (root.schema !== CLI_CONFIG_SCHEMA || root.version !== CLI_CONFIG_VERSION || !root.profiles || typeof root.profiles !== 'object' || Array.isArray(root.profiles)) {
+        throw new CliUsageError(`CLI configuration must use ${CLI_CONFIG_SCHEMA} version ${CLI_CONFIG_VERSION}.`);
+    }
+    if (Object.keys(root).some((key) => !['schema', 'version', 'defaultProfile', 'profiles'].includes(key)))
+        throw new CliUsageError('CLI configuration contains an unsupported root field.');
+    if (root.defaultProfile !== undefined && !validProfileName(root.defaultProfile))
+        throw new CliUsageError('CLI configuration defaultProfile is invalid.');
+    const profileEntries = Object.entries(root.profiles);
+    if (profileEntries.length < 1 || profileEntries.length > 20)
+        throw new CliUsageError('CLI configuration requires from 1 to 20 profiles.');
+    const profiles = Object.fromEntries(profileEntries.map(([name, value]) => {
+        if (!validProfileName(name))
+            throw new CliUsageError(`CLI profile name "${name}" is invalid.`);
+        const profile = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+        if (Object.keys(profile).some((key) => key !== 'arguments'))
+            throw new CliUsageError(`CLI profile "${name}" contains an unsupported field.`);
+        return [name, Object.freeze({ arguments: Object.freeze(validateProfileArguments(profile.arguments)) })];
+    }));
+    return Object.freeze({ schema: CLI_CONFIG_SCHEMA, version: CLI_CONFIG_VERSION, ...(root.defaultProfile ? { defaultProfile: root.defaultProfile } : {}), profiles: Object.freeze(profiles) });
+}
+async function readConfigFile(path) {
+    return readBoundedRegularTextFile(path, {
+        maximumBytes: MAX_CLI_CONFIG_BYTES,
+        label: 'CLI configuration',
+        allowSymbolicLink: true,
+    });
+}
+function suppliedGroups(argumentsList) {
+    const groups = new Set();
+    for (const argument of argumentsList) {
+        const group = OPTION_GROUPS[argument];
+        if (group)
+            groups.add(group);
+        if (argument === '--deep')
+            groups.add('scan');
+    }
+    return groups;
+}
+export async function resolveCliProfileArguments(argv, options = {}) {
+    // registry-scaffold owns --profile as the capability template to generate.
+    // Do not reinterpret it as a global CLI-default profile.
+    if (argv[0] === 'registry-scaffold') {
+        if (argv.includes('--config')) {
+            throw new CliUsageError('registry-scaffold does not accept global CLI configuration options.');
+        }
+        return [...argv];
+    }
+    const retained = [];
+    let configPath = null;
+    let profileName = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === undefined)
+            break;
+        if (argument === '--config' || argument === '--profile') {
+            const next = argv[++index];
+            if (!next || next.startsWith('-'))
+                throw new CliUsageError(`${argument} requires one value.`);
+            if (argument === '--config') {
+                if (configPath !== null)
+                    throw new CliUsageError('--config may be supplied only once.');
+                configPath = next;
+            }
+            else {
+                if (profileName !== null)
+                    throw new CliUsageError('--profile may be supplied only once.');
+                if (!validProfileName(next))
+                    throw new CliUsageError('--profile requires a lower-case name of at most 40 characters.');
+                profileName = next;
+            }
+        }
+        else
+            retained.push(argument);
+    }
+    if (!configPath && !profileName)
+        return retained;
+    const environment = options.environment || process.env;
+    const baseDirectory = environment.XDG_CONFIG_HOME || join(options.homeDirectory || homedir(), '.config');
+    const selectedPath = resolve(configPath || join(baseDirectory, 'whoisleuth', 'config.json'));
+    let input;
+    try {
+        input = await (options.readConfig || readConfigFile)(selectedPath);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError('CLI configuration could not be read as a bounded regular file.');
+    }
+    const document = parseProfileDocument(input);
+    const selectedName = profileName || document.defaultProfile;
+    if (!selectedName)
+        throw new CliUsageError('CLI configuration requires --profile or a defaultProfile.');
+    const selected = document.profiles[selectedName];
+    if (!selected)
+        throw new CliUsageError(`CLI profile "${selectedName}" was not found.`);
+    if (!retained.length)
+        throw new CliUsageError('A CLI profile must accompany a command.');
+    const explicitGroups = suppliedGroups(retained.slice(1));
+    const defaults = [];
+    for (let index = 0; index < selected.arguments.length; index += 1) {
+        const argument = selected.arguments[index];
+        const group = OPTION_GROUPS[argument];
+        const hasValue = SAFE_VALUE_DEFAULTS.has(argument);
+        const value = hasValue ? selected.arguments[++index] : undefined;
+        if (explicitGroups.has(group))
+            continue;
+        defaults.push(argument, ...(value ? [value] : []));
+    }
+    return [retained[0], ...defaults, ...retained.slice(1)];
+}
+export { parseProfileDocument };

package/cli/ct-event-intake.mjs

@@ -0,0 +1,159 @@
+import { domainToASCII } from 'node:url';
+import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
+export const CT_EVENT_BATCH_SCHEMA = 'whoisleuth.ct-event-batch';
+export const CT_EVENT_BATCH_VERSION = 1;
+export const MAX_CT_EVENT_INPUT_BYTES = 4 * 1024 * 1024;
+export const MAX_CT_EVENTS = 500;
+export const MAX_CT_EVENT_NAMES = 100;
+export const MAX_CT_EXTERNAL_FINDINGS = 100;
+export const MAX_CT_EXTERNAL_DOMAINS = 25;
+export const MAX_CT_EXTERNAL_FINDINGS_PER_DOMAIN = 20;
+const ROOT_KEYS = new Set(['schema', 'version', 'source', 'events']);
+const SOURCE_KEYS = new Set(['name', 'reference', 'collectedAt']);
+const EVENT_KEYS = new Set([
+    'logId',
+    'observedAt',
+    'certificateSha256',
+    'dnsNames',
+    'issuer',
+    'notAfter',
+    'completeness',
+    'limitations',
+]);
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+function optionalText(value, label, maximum) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    return requireBoundedString(value, label, maximum);
+}
+function domain(value, label) {
+    const supplied = requireBoundedString(value, label, 255).toLowerCase().replace(/^\*\./u, '').replace(/\.$/u, '');
+    const ascii = domainToASCII(supplied).toLowerCase();
+    if (!ascii || ascii.length > 253 || !ascii.includes('.') || ascii.split('.').some((part) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(part))) {
+        throw new TypeError(`${label} must be a valid DNS name.`);
+    }
+    return ascii;
+}
+function boundedLimitations(value, label) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.length > 8)
+        throw new TypeError(`${label} must contain no more than 8 entries.`);
+    return Object.freeze([...new Set(value.map((item, index) => requireBoundedString(item, `${label}[${index}]`, 240)))]);
+}
+export function buildCtEventFindings(inputRaw) {
+    const input = requireRecord(inputRaw, 'Certificate event batch');
+    if (input.schema !== CT_EVENT_BATCH_SCHEMA || input.version !== CT_EVENT_BATCH_VERSION) {
+        throw new TypeError(`Certificate event input must use ${CT_EVENT_BATCH_SCHEMA} version ${CT_EVENT_BATCH_VERSION}.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'Certificate event batch');
+    const sourceInput = requireRecord(input.source, 'source');
+    exactKeys(sourceInput, SOURCE_KEYS, 'source');
+    const source = Object.freeze({
+        name: requireBoundedString(sourceInput.name, 'source.name', 80),
+        reference: optionalText(sourceInput.reference, 'source.reference', 500),
+        collectedAt: sourceInput.collectedAt === null || sourceInput.collectedAt === undefined
+            ? null
+            : requireIsoTimestamp(sourceInput.collectedAt, 'source.collectedAt'),
+    });
+    if (!Array.isArray(input.events) || input.events.length < 1 || input.events.length > MAX_CT_EVENTS) {
+        throw new TypeError(`events must contain between 1 and ${MAX_CT_EVENTS} entries.`);
+    }
+    const candidates = input.events.flatMap((raw, eventIndex) => {
+        const event = requireRecord(raw, `events[${eventIndex}]`);
+        exactKeys(event, EVENT_KEYS, `events[${eventIndex}]`);
+        const logId = requireBoundedString(event.logId, `events[${eventIndex}].logId`, 200);
+        const observedAt = requireIsoTimestamp(event.observedAt, `events[${eventIndex}].observedAt`);
+        const certificateSha256 = requireBoundedString(event.certificateSha256, `events[${eventIndex}].certificateSha256`, 64).toLowerCase();
+        if (!SHA256_RE.test(certificateSha256))
+            throw new TypeError(`events[${eventIndex}].certificateSha256 must be a SHA-256 hexadecimal digest.`);
+        if (!Array.isArray(event.dnsNames) || event.dnsNames.length < 1 || event.dnsNames.length > MAX_CT_EVENT_NAMES) {
+            throw new TypeError(`events[${eventIndex}].dnsNames must contain between 1 and ${MAX_CT_EVENT_NAMES} entries.`);
+        }
+        const names = [...new Set(event.dnsNames.map((name, nameIndex) => domain(name, `events[${eventIndex}].dnsNames[${nameIndex}]`)))].sort();
+        const issuer = optionalText(event.issuer, `events[${eventIndex}].issuer`, 160);
+        const notAfter = event.notAfter === null || event.notAfter === undefined
+            ? null
+            : requireIsoTimestamp(event.notAfter, `events[${eventIndex}].notAfter`);
+        const completeness = event.completeness;
+        if (completeness !== 'complete' && completeness !== 'partial') {
+            throw new TypeError(`events[${eventIndex}].completeness must be complete or partial.`);
+        }
+        const limitations = boundedLimitations(event.limitations, `events[${eventIndex}].limitations`);
+        return names.map((name) => ({
+            domain: name,
+            category: 'certificate',
+            evidenceClass: 'deployment_observation',
+            summary: `Supplied certificate …${certificateSha256.slice(-12)} included ${name} among ${names.length} bounded DNS name${names.length === 1 ? '' : 's'}.`,
+            observedAt,
+            completeness,
+            limitations,
+            reference: `Certificate event ${logId}`,
+            structuredObservation: {
+                sourceSchema: 'whoisleuth.certificate-observation-rows',
+                sourceVersion: 1,
+                field: 'certificateSha256',
+                value: certificateSha256,
+                issuer,
+                notAfter,
+            },
+        }));
+    });
+    const seen = new Set();
+    const unique = candidates
+        .sort((left, right) => left.domain.localeCompare(right.domain)
+        || left.observedAt.localeCompare(right.observedAt)
+        || left.structuredObservation.value.localeCompare(right.structuredObservation.value))
+        .filter((item) => {
+        const key = `${item.domain}\u0000${item.observedAt}\u0000${item.structuredObservation.value}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const domainCounts = new Map();
+    const acceptedDomains = new Set();
+    const selected = [];
+    for (const finding of unique) {
+        if (!acceptedDomains.has(finding.domain) && acceptedDomains.size >= MAX_CT_EXTERNAL_DOMAINS)
+            continue;
+        const domainCount = domainCounts.get(finding.domain) ?? 0;
+        if (domainCount >= MAX_CT_EXTERNAL_FINDINGS_PER_DOMAIN)
+            continue;
+        acceptedDomains.add(finding.domain);
+        domainCounts.set(finding.domain, domainCount + 1);
+        selected.push(finding);
+        if (selected.length >= MAX_CT_EXTERNAL_FINDINGS)
+            break;
+    }
+    const truncated = selected.length < unique.length;
+    const findings = selected.map((finding) => Object.freeze({
+        ...finding,
+        limitations: Object.freeze([
+            ...finding.limitations,
+            'The supplied event is an observation, not proof that the certificate was served by the named domain or that the domain operator requested it.',
+            ...(truncated ? [`The batch contained ${unique.length} unique domain observations; this import preserves the first ${MAX_CT_EXTERNAL_FINDINGS} in deterministic order.`] : []),
+        ].slice(0, 8)),
+    }));
+    return Object.freeze({
+        schema: 'whoisleuth.external-findings',
+        schemaVersion: 3,
+        source,
+        findings: Object.freeze(findings),
+    });
+}
+export function formatCtEventFindings(document) {
+    const domains = new Set(document.findings.map((finding) => finding.domain));
+    const certificates = new Set(document.findings.map((finding) => finding.structuredObservation.value));
+    return [
+        'Certificate event intake',
+        `Source        ${document.source.name}`,
+        `Findings      ${document.findings.length}`,
+        `Domains       ${domains.size}`,
+        `Certificates  ${certificates.size}`,
+        '',
+        'The JSON form can be imported through the Console external-findings workflow.',
+        'A certificate event is a review lead, not proof that the certificate was served or requested by the domain operator.',
+        '',
+    ].join('\n');
+}

package/cli/discovery-observation-snapshot.mjs

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
-import { open } from 'node:fs/promises';
 import { availabilityState, bulkDnsSummary } from "./bulk-output.mjs";
-import { CliUsageError } from "./errors.mjs";
+import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
 import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 export const CLI_DISCOVERY_OBSERVATION_SCHEMA = 'whoisleuth.cli.discovery-observation-snapshot';
 export const CLI_DISCOVERY_OBSERVATION_VERSION = 2;
 export const MAX_DISCOVERY_OBSERVATION_BYTES = 8 * 1024 * 1024;
@@ -158,22 +158,16 @@ function parseObservationSnapshot(text, expectedDigest) {
 }
 async function readExisting(path) {
     try {
-        const handle = await open(path, 'r');
-        try {
-            const metadata = await handle.stat();
-            if (!metadata.isFile() || metadata.size > MAX_DISCOVERY_OBSERVATION_BYTES) {
-                throw new CliUsageError(`Discovery observation snapshots are limited to ${MAX_DISCOVERY_OBSERVATION_BYTES} bytes.`);
-            }
-            return await handle.readFile({ encoding: 'utf8' });
-        }
-        finally {
-            await handle.close();
-        }
+        return await readBoundedRegularTextFile(path, {
+            maximumBytes: MAX_DISCOVERY_OBSERVATION_BYTES,
+            label: 'Discovery observation snapshot',
+            allowSymbolicLink: true,
+        });
     }
     catch (error) {
         if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
             return null;
-        throw error;
+        throw boundedCliInputError(error, 'Discovery observation snapshot');
     }
 }
 function currentAttempt(domain, item, previous, generatedAt, deep) {