@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/packages/analysis/analyst-taxonomy.mjs

@@ -0,0 +1,40 @@
+// Deliberately small interoperability projection over reviewed MISP
+// taxonomies. WHOISleuth retains its own bounded workflow vocabulary and
+// derives machine tags only when an analyst-owned disposition and reason make
+// the mapping unambiguous. These tags never alter collection or scoring.
+const ANALYST_REVIEW_REASONS = Object.freeze([
+    Object.freeze({ value: '', label: 'Not recorded' }),
+    Object.freeze({ value: 'authorized_or_owned', label: 'Authorised or owned domain' }),
+    Object.freeze({ value: 'shared_infrastructure', label: 'Shared infrastructure explained the signal' }),
+    Object.freeze({ value: 'generic_platform_or_template', label: 'Generic platform or template' }),
+    Object.freeze({ value: 'parked_or_reseller', label: 'Parking or reseller page' }),
+    Object.freeze({ value: 'insufficient_evidence', label: 'Insufficient evidence' }),
+    Object.freeze({ value: 'legitimate_third_party', label: 'Legitimate third party' }),
+    Object.freeze({ value: 'confirmed_credential_abuse', label: 'Confirmed credential abuse' }),
+    Object.freeze({ value: 'confirmed_malware', label: 'Confirmed malware' }),
+    Object.freeze({ value: 'other_reviewed', label: 'Other reviewed reason' }),
+]);
+const ANALYST_REVIEW_REASON_VALUES = new Set(ANALYST_REVIEW_REASONS.map(({ value }) => value).filter(Boolean));
+const MISP_TAXONOMY_REFERENCES = Object.freeze([
+    Object.freeze({ namespace: 'domain-abuse', version: 2, sourceSha256: '5fcfb44742daac97061726faaaadd2ce6b7eac55306acaae3d30c3882d18f991', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/domain-abuse/machinetag.json' }),
+    Object.freeze({ namespace: 'estimative-language', version: 5, sourceSha256: '1010927d396f66f7cc58a229ebb8af6ad2cdc0250ad5f8ce3b1bd9aacf5ab4da', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/estimative-language/machinetag.json' }),
+    Object.freeze({ namespace: 'event-assessment', version: 2, sourceSha256: '39291bdd50e1b2975a93e33e396f42b398178015580a84402bc3d8d549dd721e', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/event-assessment/machinetag.json' }),
+    Object.freeze({ namespace: 'false-positive', version: 7, sourceSha256: 'ffc8d35ae36eb1d39f33611d1090793021f2bfe3b4b31ae41631e22cf544a2fb', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/false-positive/machinetag.json' }),
+    Object.freeze({ namespace: 'phishing', version: 5, sourceSha256: '8628ebe4d5935216a7b006a4d975669c4ae1a554ef8ed78ffaadd62f763d7263', sourceUrl: 'https://github.com/MISP/misp-taxonomies/blob/main/phishing/machinetag.json' }),
+]);
+function analystInteroperabilityTags(disposition, reviewReasonCode) {
+    const tags = new Set();
+    if (disposition === 'false_positive')
+        tags.add('false-positive:confirmed="true"');
+    if ((disposition === 'false_positive' || disposition === 'expected')
+        && ['authorized_or_owned', 'shared_infrastructure', 'generic_platform_or_template', 'parked_or_reseller', 'legitimate_third_party'].includes(String(reviewReasonCode)))
+        tags.add('false-positive:risk="high"');
+    if (reviewReasonCode === 'insufficient_evidence') {
+        tags.add('estimative-language:confidence-in-analytic-judgment="low"');
+    }
+    if (disposition === 'confirmed_abuse' && reviewReasonCode === 'confirmed_credential_abuse') {
+        tags.add('phishing:techniques="fake-website"');
+    }
+    return [...tags].sort();
+}
+export { ANALYST_REVIEW_REASONS, ANALYST_REVIEW_REASON_VALUES, MISP_TAXONOMY_REFERENCES, analystInteroperabilityTags, };

package/packages/analysis/bounded-json.mjs

@@ -0,0 +1,330 @@
+export const MAX_BOUNDED_JSON_DEPTH = 48;
+export const MAX_BOUNDED_JSON_KEYS = 50_000;
+export const MAX_BOUNDED_JSON_VALUES = 100_000;
+export const MAX_BOUNDED_JSON_CONTAINER_ITEMS = 10_000;
+export const UNSAFE_JSON_OBJECT_KEYS = Object.freeze(['__proto__']);
+/** Aggregate work allowed by a separately enforced UTF-8 byte budget. */
+export function boundedJsonLimitsForBytes(maximumBytes) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 1) {
+        throw new TypeError('The JSON byte budget must be a positive safe integer.');
+    }
+    // A member needs at least five bytes (comma, two quotes, colon, value).
+    // Values need at least two bytes each, apart from a scalar root or the last
+    // array item. These upper bounds do not depend on a model's current fields.
+    // Nesting and individual-container limits remain independently bounded.
+    return {
+        maximumKeys: Math.floor(maximumBytes / 5),
+        maximumValues: Math.ceil(maximumBytes / 2),
+        // Decoded text is a lower bound on its UTF-8 JSON representation. Checking
+        // it before stringify also prevents an oversized string allocation.
+        maximumStringCodeUnits: maximumBytes,
+    };
+}
+function syntaxError() {
+    throw new TypeError('Artefact input is not valid JSON.');
+}
+export function isSafeJsonObjectKey(value) {
+    return !UNSAFE_JSON_OBJECT_KEYS.includes(value);
+}
+export function assertBoundedJsonStructure(value, label = 'JSON value', limits = {}) {
+    const maximumDepth = limits.maximumDepth ?? MAX_BOUNDED_JSON_DEPTH;
+    const maximumKeys = limits.maximumKeys ?? MAX_BOUNDED_JSON_KEYS;
+    const maximumValues = limits.maximumValues ?? MAX_BOUNDED_JSON_VALUES;
+    const maximumContainerItems = limits.maximumContainerItems ?? MAX_BOUNDED_JSON_CONTAINER_ITEMS;
+    let keys = 0;
+    let values = 0;
+    let stringCodeUnits = 0;
+    const ancestors = new Set();
+    const text = (value) => {
+        stringCodeUnits += value.length;
+        if (limits.maximumStringCodeUnits !== undefined && stringCodeUnits > limits.maximumStringCodeUnits) {
+            throw new TypeError(`${label} exceeds the aggregate text limit.`);
+        }
+    };
+    const visit = (current, depth) => {
+        values += 1;
+        if (values > maximumValues) {
+            throw new TypeError(`${label} exceeds the ${maximumValues}-value limit.`);
+        }
+        if (depth > maximumDepth) {
+            throw new TypeError(`${label} exceeds the ${maximumDepth}-level nesting limit.`);
+        }
+        if (typeof current === 'string') {
+            text(current);
+            return;
+        }
+        if (current === null || typeof current === 'boolean')
+            return;
+        if (typeof current === 'number') {
+            if (!Number.isFinite(current))
+                throw new TypeError(`${label} contains a non-JSON number.`);
+            return;
+        }
+        if (typeof current !== 'object')
+            throw new TypeError(`${label} contains a non-JSON value.`);
+        if (ancestors.has(current))
+            throw new TypeError(`${label} contains a cyclic object reference.`);
+        let prototype;
+        let ownKeys;
+        let descriptors;
+        try {
+            prototype = Object.getPrototypeOf(current);
+            ownKeys = Reflect.ownKeys(current);
+            descriptors = Object.getOwnPropertyDescriptors(current);
+        }
+        catch {
+            throw new TypeError(`${label} could not be inspected safely.`);
+        }
+        if (ownKeys.some((key) => typeof key !== 'string')) {
+            throw new TypeError(`${label} contains a symbol key.`);
+        }
+        if (ownKeys.some((key) => {
+            const descriptor = descriptors[String(key)];
+            return !descriptor || !Object.hasOwn(descriptor, 'value');
+        })) {
+            throw new TypeError(`${label} contains an accessor property.`);
+        }
+        ancestors.add(current);
+        if (Array.isArray(current)) {
+            if (prototype !== Array.prototype) {
+                throw new TypeError(`${label} contains an array with a custom prototype.`);
+            }
+            const length = descriptors.length?.value;
+            if (!Number.isSafeInteger(length) || length < 0 || length > maximumContainerItems) {
+                throw new TypeError(`${label} contains a container with more than ${maximumContainerItems} items.`);
+            }
+            const indexes = ownKeys.filter((key) => key !== 'length');
+            if (indexes.length !== length
+                || indexes.some((key, index) => key !== String(index) || descriptors[key]?.enumerable !== true)) {
+                throw new TypeError(`${label} contains a sparse, extended, or non-enumerable array.`);
+            }
+            for (const key of indexes)
+                visit(descriptors[key].value, depth + 1);
+        }
+        else {
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new TypeError(`${label} contains an object with a custom prototype.`);
+            }
+            const objectKeys = ownKeys;
+            if (objectKeys.length > maximumContainerItems) {
+                throw new TypeError(`${label} contains a container with more than ${maximumContainerItems} items.`);
+            }
+            if (objectKeys.some((key) => descriptors[key]?.enumerable !== true)) {
+                throw new TypeError(`${label} contains a non-enumerable object property.`);
+            }
+            keys += objectKeys.length;
+            if (keys > maximumKeys) {
+                throw new TypeError(`${label} exceeds the ${maximumKeys}-key limit.`);
+            }
+            for (const key of objectKeys) {
+                if (!isSafeJsonObjectKey(key))
+                    throw new TypeError(`${label} contains an unsafe object key.`);
+                text(key);
+                visit(descriptors[key].value, depth + 1);
+            }
+        }
+        ancestors.delete(current);
+    };
+    visit(value, 0);
+}
+export function scanBoundedJson(raw, limits = {}, observeString) {
+    const maximumDepth = limits.maximumDepth ?? MAX_BOUNDED_JSON_DEPTH;
+    const maximumKeys = limits.maximumKeys ?? MAX_BOUNDED_JSON_KEYS;
+    const maximumValues = limits.maximumValues ?? MAX_BOUNDED_JSON_VALUES;
+    const maximumContainerItems = limits.maximumContainerItems ?? MAX_BOUNDED_JSON_CONTAINER_ITEMS;
+    let index = 0;
+    let keys = 0;
+    let values = 0;
+    let stringCodeUnits = 0;
+    const whitespace = () => {
+        while (index < raw.length) {
+            const code = raw.charCodeAt(index);
+            if (code !== 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d)
+                break;
+            index += 1;
+        }
+    };
+    const stringToken = () => {
+        const start = index;
+        index += 1;
+        while (index < raw.length) {
+            const character = raw[index];
+            if (character === '"') {
+                index += 1;
+                let value;
+                try {
+                    value = JSON.parse(raw.slice(start, index));
+                }
+                catch {
+                    syntaxError();
+                }
+                stringCodeUnits += value.length;
+                if (limits.maximumStringCodeUnits !== undefined && stringCodeUnits > limits.maximumStringCodeUnits) {
+                    throw new TypeError('Artefact JSON exceeds the aggregate text limit.');
+                }
+                return { value, offset: start };
+            }
+            if (character === '\\') {
+                index += 1;
+                if (index >= raw.length)
+                    syntaxError();
+                if (raw[index] === 'u') {
+                    if (!/^[a-fA-F0-9]{4}$/u.test(raw.slice(index + 1, index + 5)))
+                        syntaxError();
+                    index += 5;
+                }
+                else {
+                    if (!/["\\/bfnrt]/u.test(raw[index]))
+                        syntaxError();
+                    index += 1;
+                }
+                continue;
+            }
+            if (character.charCodeAt(0) <= 0x1f)
+                syntaxError();
+            index += 1;
+        }
+        return syntaxError();
+    };
+    const literal = (token) => {
+        if (raw.slice(index, index + token.length) !== token)
+            syntaxError();
+        index += token.length;
+    };
+    const number = () => {
+        const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u.exec(raw.slice(index));
+        if (!match)
+            syntaxError();
+        if (!Number.isFinite(Number(match[0]))) {
+            throw new TypeError('Artefact JSON contains a non-finite number.');
+        }
+        index += match[0].length;
+    };
+    const value = (depth, propertyKey) => {
+        values += 1;
+        if (values > maximumValues) {
+            throw new TypeError(`Artefact JSON exceeds the ${maximumValues}-value limit.`);
+        }
+        if (depth > maximumDepth) {
+            throw new TypeError(`Artefact JSON exceeds the ${maximumDepth}-level nesting limit.`);
+        }
+        whitespace();
+        const character = raw[index];
+        if (character === '"') {
+            const parsedString = stringToken();
+            observeString?.({ ...parsedString, kind: 'value', ...(propertyKey === undefined ? {} : { propertyKey }) });
+            return;
+        }
+        if (character === '{') {
+            index += 1;
+            whitespace();
+            const seen = new Set();
+            if (raw[index] === '}') {
+                index += 1;
+                return;
+            }
+            while (index < raw.length) {
+                if (raw[index] !== '"')
+                    syntaxError();
+                const parsedKey = stringToken();
+                const key = parsedKey.value;
+                if (seen.size >= maximumContainerItems) {
+                    throw new TypeError(`Artefact JSON contains a container with more than ${maximumContainerItems} items.`);
+                }
+                keys += 1;
+                if (keys > maximumKeys) {
+                    throw new TypeError(`Artefact JSON exceeds the ${maximumKeys}-key limit.`);
+                }
+                if (seen.has(key))
+                    throw new TypeError('Artefact JSON contains a duplicate object key.');
+                if (!isSafeJsonObjectKey(key))
+                    throw new TypeError('Artefact JSON contains an unsafe object key.');
+                seen.add(key);
+                observeString?.({ ...parsedKey, kind: 'key' });
+                whitespace();
+                if (raw[index] !== ':')
+                    syntaxError();
+                index += 1;
+                value(depth + 1, key);
+                whitespace();
+                if (raw[index] === '}') {
+                    index += 1;
+                    return;
+                }
+                if (raw[index] !== ',')
+                    syntaxError();
+                index += 1;
+                whitespace();
+            }
+            syntaxError();
+        }
+        if (character === '[') {
+            index += 1;
+            whitespace();
+            if (raw[index] === ']') {
+                index += 1;
+                return;
+            }
+            let items = 0;
+            while (index < raw.length) {
+                items += 1;
+                if (items > maximumContainerItems) {
+                    throw new TypeError(`Artefact JSON contains a container with more than ${maximumContainerItems} items.`);
+                }
+                value(depth + 1);
+                whitespace();
+                if (raw[index] === ']') {
+                    index += 1;
+                    return;
+                }
+                if (raw[index] !== ',')
+                    syntaxError();
+                index += 1;
+                whitespace();
+            }
+            syntaxError();
+        }
+        if (character === 't') {
+            literal('true');
+            return;
+        }
+        if (character === 'f') {
+            literal('false');
+            return;
+        }
+        if (character === 'n') {
+            literal('null');
+            return;
+        }
+        number();
+    };
+    whitespace();
+    value(0);
+    whitespace();
+    if (index !== raw.length)
+        syntaxError();
+}
+export function parseBoundedJson(raw, options) {
+    const label = options.label ?? 'Artefact input';
+    if (typeof raw !== 'string')
+        throw new TypeError(`${label} must be UTF-8 JSON text.`);
+    const bytes = new TextEncoder().encode(raw).byteLength;
+    if (bytes < 1 || bytes > options.maximumBytes) {
+        throw new TypeError(`${label} must be between 1 byte and ${options.maximumBytes} bytes.`);
+    }
+    scanBoundedJson(raw, options.limits);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return syntaxError();
+    }
+}
+export function parseBoundedJsonObject(raw, options) {
+    const label = options.label ?? 'Artefact input';
+    const parsed = parseBoundedJson(raw, options);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new TypeError(`${label} must contain one JSON object.`);
+    }
+    return parsed;
+}

package/packages/analysis/candidate-provenance-bounds.mjs

@@ -0,0 +1,4 @@
+// Browser-safe bounds shared by candidate discovery responses and the
+// Discover-to-Bulk handoff. These are provenance labels, not domain names;
+// they remain bounded independently of the target-domain contract.
+export const MAX_CANDIDATE_SOURCE_LENGTH = 253;

package/packages/analysis/cli-argument-grammar.mjs

@@ -0,0 +1,216 @@
+export class CliGrammarError extends Error {
+    constructor(message) { super(message); this.name = 'CliGrammarError'; }
+}
+function humanList(values, conjunction = 'or') {
+    if (values.length < 2)
+        return values[0] ?? '';
+    if (values.length === 2)
+        return `${values[0]} ${conjunction} ${values[1]}`;
+    return `${values.slice(0, -1).join(', ')}, ${conjunction} ${values.at(-1)}`;
+}
+function valueError(specification) {
+    if (specification.valueKind === 'file') {
+        return new CliGrammarError(`${specification.option} requires one bounded file path.`);
+    }
+    if (specification.valueKind === 'integer') {
+        const baseRange = specification.integerRanges[0];
+        return new CliGrammarError(baseRange
+            ? `${specification.option} requires an integer from ${baseRange.minimum} to ${baseRange.maximum}.`
+            : `${specification.option} requires one bounded integer.`);
+    }
+    if (specification.values.length > 0) {
+        return new CliGrammarError(`${specification.option} requires ${humanList(specification.values)}.`);
+    }
+    return new CliGrammarError(`${specification.option} requires one bounded value.`);
+}
+function parseTokens(grammar, argv) {
+    const specificationByOption = new Map(grammar.options.map((specification) => [specification.option, specification]));
+    const options = new Map();
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--') {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (!argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        const specification = specificationByOption.get(argument);
+        if (!specification || specification.metaAction !== null) {
+            throw new CliGrammarError(`Unknown option "${argument}".`);
+        }
+        const existing = options.get(argument);
+        if (existing && specification.occurrence === 'once') {
+            throw new CliGrammarError(`${argument} may be supplied only once.`);
+        }
+        if (existing && specification.occurrence === 'idempotent')
+            continue;
+        let value = '';
+        if (specification.arity === 1) {
+            const candidate = argv[++index];
+            if (candidate === undefined || candidate === ''
+                || (!specification.acceptsOptionLikeValue && candidate.startsWith('-'))) {
+                throw valueError(specification);
+            }
+            value = candidate;
+        }
+        if (existing)
+            existing.push(value);
+        else
+            options.set(argument, [value]);
+    }
+    return { options, positionals };
+}
+function selectedIntegerRange(specification, options) {
+    return specification.integerRanges
+        .filter((range) => range.whenOptionPresent === null || options.has(range.whenOptionPresent))
+        .at(-1) ?? null;
+}
+function validateOptionValues(command, grammar, options) {
+    for (const specification of grammar.options) {
+        const values = options.get(specification.option);
+        if (!values || specification.arity === 0)
+            continue;
+        if (specification.valueKind === 'enum') {
+            if (values.some((value) => !specification.values.includes(value)))
+                throw valueError(specification);
+            continue;
+        }
+        if (specification.valueKind === 'integer') {
+            const range = selectedIntegerRange(specification, options);
+            if (!range)
+                throw new Error(`Integer option ${command} ${specification.option} has no applicable range.`);
+            for (const value of values) {
+                if (!/^\d+$/u.test(value))
+                    throw valueError(specification);
+                const parsed = Number(value);
+                if (!Number.isSafeInteger(parsed) || parsed < range.minimum || parsed > range.maximum) {
+                    throw new CliGrammarError(`${specification.option} must be from ${range.minimum} to ${range.maximum}.`);
+                }
+            }
+            continue;
+        }
+        if (specification.valueKind === 'policy_list') {
+            for (const value of values) {
+                const policies = [...new Set(value.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean))];
+                if (!policies.length || policies.some((policy) => !specification.values.includes(policy))) {
+                    throw new CliGrammarError(`${specification.option} for ${command} supports: ${specification.values.join(', ')}.`);
+                }
+            }
+        }
+    }
+}
+function allocatePositionals(command, grammar, rawPositionals) {
+    const specifications = grammar.positionals;
+    const maximum = specifications.reduce((sum, specification) => sum + specification.maximum, 0);
+    if (rawPositionals.length > maximum) {
+        throw new CliGrammarError(`${command} accepts at most ${maximum} positional value${maximum === 1 ? '' : 's'}.`);
+    }
+    const allocated = {};
+    let offset = 0;
+    for (const [specificationIndex, specification] of specifications.entries()) {
+        const remainingMinimum = specifications.slice(specificationIndex + 1)
+            .reduce((sum, later) => sum + later.minimum, 0);
+        const available = Math.max(0, rawPositionals.length - offset - remainingMinimum);
+        const count = Math.min(specification.maximum, available);
+        const values = Object.freeze(rawPositionals.slice(offset, offset + count));
+        offset += count;
+        if (values.length < specification.minimum) {
+            throw new CliGrammarError(`${command} requires ${specification.minimum} ${specification.name} value${specification.minimum === 1 ? '' : 's'}.`);
+        }
+        if (specification.valueKind === 'enum'
+            && values.some((value) => !specification.values.includes(value))) {
+            throw new CliGrammarError(`${command} ${specification.name} must be ${humanList(specification.values)}.`);
+        }
+        allocated[specification.name] = values;
+    }
+    return Object.freeze(allocated);
+}
+function present(options, option) {
+    return options.has(option);
+}
+function validateConstraint(command, constraint, options) {
+    if (constraint.kind === 'required') {
+        const missing = constraint.options.filter((option) => !present(options, option));
+        if (missing.length > 0)
+            throw new CliGrammarError(`${command} requires ${missing.join(', ')}.`);
+        return;
+    }
+    if (constraint.kind === 'mutually_exclusive') {
+        const selected = constraint.options.filter((option) => present(options, option));
+        if (selected.length > 1) {
+            throw new CliGrammarError(`${selected.join(' and ')} are mutually exclusive and may be supplied only once.`);
+        }
+        return;
+    }
+    if (constraint.kind === 'excludes_all') {
+        if (!present(options, constraint.option))
+            return;
+        const selected = constraint.excludedOptions.filter((option) => present(options, option));
+        if (selected.length > 0) {
+            throw new CliGrammarError(`${constraint.option} cannot be combined with ${selected.join(', ')}.`);
+        }
+        return;
+    }
+    if (constraint.kind === 'value_excludes') {
+        if (!options.get(constraint.option)?.includes(constraint.value))
+            return;
+        const selected = constraint.excludedOptions.filter((option) => present(options, option));
+        if (selected.length > 0) {
+            throw new CliGrammarError(`${constraint.option} ${constraint.value} cannot be combined with ${selected.join(', ')}.`);
+        }
+        return;
+    }
+    if (!present(options, constraint.option))
+        return;
+    const selected = constraint.requiredOptions.filter((option) => present(options, option));
+    if (constraint.kind === 'requires_all' && selected.length !== constraint.requiredOptions.length) {
+        throw new CliGrammarError(`${constraint.option} requires ${constraint.requiredOptions.join(' and ')}.`);
+    }
+    if (constraint.kind === 'requires_any' && selected.length === 0) {
+        throw new CliGrammarError(`${constraint.option} requires ${constraint.requiredOptions.join(' or ')}.`);
+    }
+}
+function validatePositionalRequirements(grammar, allocated, options) {
+    for (const specification of grammar.positionals) {
+        if (specification.requiredWhenOptions.some((option) => options.has(option))
+            && (allocated[specification.name]?.length ?? 0) === 0) {
+            throw new CliGrammarError(`${specification.requiredWhenOptions.join(' or ')} requires a positional ${specification.name}.`);
+        }
+    }
+}
+function freezeOptions(options) {
+    return new Map([...options].map(([option, values]) => [option, Object.freeze([...values])]));
+}
+export function parseCliGrammar(command, grammar, argv) {
+    const parsed = parseTokens(grammar, argv);
+    const options = freezeOptions(parsed.options);
+    validateOptionValues(command, grammar, options);
+    const allocated = allocatePositionals(command, grammar, parsed.positionals);
+    validatePositionalRequirements(grammar, allocated, options);
+    for (const constraint of grammar.constraints) {
+        validateConstraint(command, constraint, options);
+    }
+    for (const option of ['--config', '--profile']) {
+        const specification = grammar.options.find((candidate) => candidate.option === option);
+        if (specification?.scope === 'common' && options.has(option)) {
+            throw new CliGrammarError(`${option} must be resolved before command parsing.`);
+        }
+    }
+    const allPositionals = Object.freeze([...parsed.positionals]);
+    return Object.freeze({
+        command,
+        allPositionals,
+        hasOption: (option) => options.has(option),
+        optionValue: (option) => options.get(option)?.at(-1) ?? null,
+        optionValues: (option) => options.get(option) ?? Object.freeze([]),
+        integerOption: (option) => {
+            const value = options.get(option)?.at(-1);
+            return value === undefined ? null : Number(value);
+        },
+        positionalValue: (name) => allocated[name]?.[0] ?? null,
+        positionalValues: (name) => allocated[name] ?? Object.freeze([]),
+    });
+}

package/packages/analysis/ct-query.mjs

@@ -0,0 +1,27 @@
+const MAX_CT_QUERY_LENGTH = 200;
+const CT_QUERY_ERROR_CODE = 'INVALID_CT_QUERY';
+const CT_QUERY_ERROR_MESSAGE = `Certificate Transparency query must be at most ${MAX_CT_QUERY_LENGTH} characters and contain no control or invisible formatting characters.`;
+const UNSAFE_QUERY_CHARACTER_RE = /[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/u;
+class CtQueryError extends Error {
+    code = CT_QUERY_ERROR_CODE;
+    constructor() {
+        super(CT_QUERY_ERROR_MESSAGE);
+        this.name = 'CtQueryError';
+    }
+}
+function normalizeCtQuery(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value !== 'string'
+        || value.length > MAX_CT_QUERY_LENGTH
+        || UNSAFE_QUERY_CHARACTER_RE.test(value)) {
+        throw new CtQueryError();
+    }
+    return value.trim();
+}
+function isCtQueryError(value) {
+    return value instanceof Error
+        && 'code' in value
+        && value.code === CT_QUERY_ERROR_CODE;
+}
+export { CT_QUERY_ERROR_CODE, CT_QUERY_ERROR_MESSAGE, CtQueryError, isCtQueryError, MAX_CT_QUERY_LENGTH, normalizeCtQuery, };

package/packages/analysis/ct-response-bounds.mjs

@@ -0,0 +1,9 @@
+// Shared response-contract bounds for certificate-log search. The collector
+// and browser normalizer import these values so a valid backend response is
+// not accidentally clipped by a stale client-side mirror.
+export const MAX_CT_RESPONSE_RESULTS = 500;
+export const MAX_CT_RESPONSE_HOSTNAMES_PER_MATCH = 50;
+export const MAX_CT_RESPONSE_TIMESTAMP_LENGTH = 64;
+export const MAX_CT_RESPONSE_CERTIFICATE_GROUPS = 100;
+export const MAX_CT_RESPONSE_DOMAINS_PER_GROUP = 20;
+export const MAX_CT_RESPONSE_HOSTNAMES_PER_GROUP = 30;