@slicedearth/whoisleuth-cli 2.0.0 → 2.1.0

package/cli/artifact-validation/structure-primitives.mjs

@@ -0,0 +1,105 @@
+const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
+const DIGEST_RE = /^sha256:[a-f0-9]{64}$/u;
+const DOMAIN_RE = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u;
+export const HEX_DIGEST_RE = /^[a-f0-9]{64}$/u;
+export const SEMANTIC_VERSION_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+export function fail(label) {
+    throw new TypeError(`${label} has an unsupported or malformed structure.`);
+}
+export function record(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(label);
+    return value;
+}
+export function exact(value, keys, label) {
+    const source = record(value, label);
+    const actual = Object.keys(source);
+    if (actual.length !== keys.length || actual.some((key) => !keys.includes(key)))
+        fail(label);
+    return source;
+}
+export function exactOptional(value, required, optional, label) {
+    const source = record(value, label);
+    const actual = Object.keys(source);
+    if (required.some((key) => !actual.includes(key))
+        || actual.some((key) => !required.includes(key) && !optional.includes(key)))
+        fail(label);
+    return source;
+}
+export function text(value, label, maximum = 2_000, allowEmpty = false) {
+    if (typeof value !== 'string' || value.length > maximum || CONTROL_RE.test(value) || (!allowEmpty && !value))
+        fail(label);
+    return value;
+}
+export function optionalText(value, label, maximum = 2_000) {
+    if (value !== null)
+        text(value, label, maximum);
+}
+export function iso(value, label, nullable = false) {
+    if (nullable && value === null)
+        return;
+    const candidate = text(value, label, 64);
+    const parsed = Date.parse(candidate);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== candidate)
+        fail(label);
+}
+export function integer(value, label, minimum = 0, maximum = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(value) || Number(value) < minimum || Number(value) > maximum)
+        fail(label);
+    return Number(value);
+}
+export function boolean(value, label) {
+    if (typeof value !== 'boolean')
+        fail(label);
+}
+export function enumeration(value, allowed, label) {
+    if (typeof value !== 'string' || !allowed.includes(value))
+        fail(label);
+    return value;
+}
+export function array(value, label, maximum, minimum = 0) {
+    if (!Array.isArray(value) || value.length < minimum || value.length > maximum)
+        fail(label);
+    return value;
+}
+export function strings(value, label, maximum, textMaximum = 2_000) {
+    const values = array(value, label, maximum);
+    for (const item of values)
+        text(item, label, textMaximum);
+    return values;
+}
+export function digest(value, label) {
+    if (typeof value !== 'string' || !DIGEST_RE.test(value))
+        fail(label);
+}
+export function sameValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+export function domain(value, label) {
+    if (typeof value !== 'string' || !DOMAIN_RE.test(value))
+        fail(label);
+}
+export function absoluteUrl(value, label, protocols) {
+    const candidate = text(value, label, 2_048);
+    try {
+        const parsed = new URL(candidate);
+        if (!protocols.includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash)
+            fail(label);
+        return parsed;
+    }
+    catch {
+        return fail(label);
+    }
+}
+export function nullableRecord(value, label) {
+    if (value !== null)
+        record(value, label);
+}
+export function validateIntegrity(value, label, version, currentVersion) {
+    if (version !== currentVersion)
+        fail(label);
+    const integrity = exact(value, ['algorithm', 'canonicalization', 'digestSha256'], label);
+    if (integrity.algorithm !== 'SHA-256' || integrity.canonicalization !== 'sorted-json-v2')
+        fail(label);
+    digest(integrity.digestSha256, label);
+}

package/cli/artifact-verify.mjs

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { createHash } from 'node:crypto';
 import { parseBoundedJsonObject } from "./bounded-json.mjs";
-import { validateInvestigationCapsuleStructure, validateLookupEvidenceArtifactStructure, validateOfflineArtifactStructure, validateSignedDigestArtifactStructure, } from "./artifact-structure.mjs";
+import { validateInvestigationCapsuleStructure, validateLookupEvidenceArtifactStructure, validateOfflineArtifactStructure, validateSignedDigestArtifactStructure, } from "./offline-artifact-validation.mjs";
 import { verifyCaseResponsePacketIntegrity, } from "../packages/cases/case-response-packet.mjs";
 import { CASE_PORTABILITY_VERIFIER_DISPATCH, CASE_RESPONSE_PACKET_VERSION, CASE_RESPONSE_PACKET_SCHEMA, CLI_CASE_PACK_VERSION, CLI_CASE_PACK_SCHEMA, } from "../packages/contracts/case-portability.mjs";
 import { ACQUISITION_DECISION_PACKET_SCHEMA, BULK_DOMAIN_COMPARISON_SCHEMA, BULK_MAIL_EXPOSURE_SCHEMA, BULK_REVIEW_MANIFEST_SCHEMA, LOOKUP_CLAIM_PASSPORT_SCHEMA, LOOKUP_CLAIM_PASSPORT_VERSION, SUPPORTED_ACQUISITION_DECISION_PACKET_VERSIONS, SUPPORTED_BULK_DOMAIN_COMPARISON_EXPORT_VERSIONS, SUPPORTED_BULK_MAIL_EXPOSURE_EXPORT_VERSIONS, SUPPORTED_BULK_REVIEW_MANIFEST_VERSIONS, } from "../packages/contracts/investigation-portability.mjs";

package/cli/assurance-command-runner.mjs

@@ -0,0 +1,324 @@
+import { Buffer } from 'node:buffer';
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { MAX_ASSURANCE_INPUT_BYTES, buildDomainAssurance, formatDomainAssurance, } from "../lib/domain-assurance.mjs";
+import { MAX_DOMAIN_CHANGE_PACKET_INPUT_BYTES, buildDomainChangePacket, formatDomainChangePacket, } from "../lib/domain-change-packet.mjs";
+import { DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, buildDomainControlFlightRecorder, formatDomainControlFlightRecorder, serializeDomainControlFlightRecorder, } from "../lib/domain-control-flight-recorder.mjs";
+import { DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA, DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, buildDomainControlManifest, formatDomainControlResult, reviewDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
+import { CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, MAX_DOMAIN_CONTROL_REVIEW_JSON_DEPTH, MAX_DOMAIN_CONTROL_REVIEW_JSON_KEYS, MAX_DOMAIN_CONTROL_REVIEW_JSON_VALUES, buildCliDomainControlReview, formatCliDomainControlReview, } from "./domain-control-observations.mjs";
+import { serializeDomainControlManifest } from "../packages/evidence/domain-control-runtime.mjs";
+import { MAX_DOMAIN_CONTROL_REVIEW_COMMAND_BYTES } from "../packages/contracts/domain-control-review.mjs";
+import { MAX_CT_EVENT_INPUT_BYTES, buildCtEventFindings, formatCtEventFindings, } from "./ct-event-intake.mjs";
+import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+import { MAX_EXTERNAL_OBSERVATION_MAPPING_BYTES, formatExternalObservationMapping, mapExternalObservations, } from "./external-observation-mapping.mjs";
+import { formatJsonDocument } from "./formatters/json.mjs";
+import { MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, buildInvestigationManifest, formatInvestigationManifest, } from "./investigation-manifest.mjs";
+import { buildOpenAssetModelBridge, formatOpenAssetModelBridge, } from "./open-asset-model-bridge.mjs";
+import { ASSURANCE_INLINE_COMMANDS } from "./inline-command-families.mjs";
+import { MAX_SHARING_REVIEW_BYTES, buildSharingReview, formatSharingReview, } from "./sharing-review.mjs";
+import { runDiscriminatedCommandHandler } from "./discriminated-command-handlers.mjs";
+async function runManifestCommand(args, dependencies, context) {
+    context.setFailureLabel('Investigation manifest');
+    const artifacts = [];
+    let totalBytes = 0;
+    try {
+        for (const source of args.sources) {
+            const content = dependencies.readDiffInput
+                ? await dependencies.readDiffInput(source)
+                : await context.readInput(source, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, 'Manifest artefact input');
+            totalBytes += Buffer.byteLength(content, 'utf8');
+            if (totalBytes > MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES) {
+                throw new CliUsageError(`Manifest artefacts exceed the ${MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES}-byte combined limit.`);
+            }
+            artifacts.push({ content });
+        }
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read manifest artefact input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    let document;
+    try {
+        document = await buildInvestigationManifest({
+            workflow: args.workflow,
+            configurationDigestSha256: args.configurationDigestSha256,
+            artifacts,
+        }, context.now(), context.packageVersion);
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, 'Investigation manifest input is invalid'));
+    }
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatInvestigationManifest(document), args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+async function runObservationBridgeCommand(args, dependencies, context) {
+    const mapping = args.action === 'map-observations';
+    context.setFailureLabel(mapping ? 'External observation mapping' : 'Open Asset Model export');
+    let input;
+    try {
+        input = dependencies.readArtifactInput
+            ? await dependencies.readArtifactInput(args.source)
+            : await context.readInput(args.source, MAX_EXTERNAL_OBSERVATION_MAPPING_BYTES, mapping ? 'External observation mapping input' : 'Open Asset Model bridge input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read ${mapping ? 'observation mapping' : 'asset bridge'} input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError(`${args.action} requires one versioned JSON file or a document on stdin.`);
+    let parsed;
+    try {
+        scanBoundedJson(input);
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new CliUsageError(`${mapping ? 'External observation mapping' : 'Open Asset Model bridge'} input is not valid bounded JSON without duplicate keys.`);
+    }
+    let document;
+    try {
+        document = mapping
+            ? mapExternalObservations(parsed)
+            : buildOpenAssetModelBridge(parsed, context.now());
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, `${mapping ? 'External observation mapping' : 'Open Asset Model bridge'} input is invalid`));
+    }
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(mapping
+                ? formatExternalObservationMapping(document)
+                : formatOpenAssetModelBridge(document), args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+async function runDomainControlCommand(args, dependencies, context) {
+    context.setFailureLabel('Domain control review');
+    let input;
+    try {
+        input = dependencies.readArtifactInput
+            ? await dependencies.readArtifactInput(args.source)
+            : await context.readInput(args.source, MAX_DOMAIN_CONTROL_REVIEW_COMMAND_BYTES, 'Domain control input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read domain control input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('domain-control requires one JSON file or a document on stdin.');
+    const normalisedInput = input.replace(/^\uFEFF/u, '');
+    let parsed;
+    try {
+        scanBoundedJson(normalisedInput, {
+            maximumDepth: MAX_DOMAIN_CONTROL_REVIEW_JSON_DEPTH,
+            maximumKeys: MAX_DOMAIN_CONTROL_REVIEW_JSON_KEYS,
+            maximumValues: MAX_DOMAIN_CONTROL_REVIEW_JSON_VALUES,
+        });
+        parsed = JSON.parse(normalisedInput);
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : '';
+        if (detail.startsWith('Artefact JSON ')) {
+            throw new CliUsageError(`Domain control input ${detail.slice('Artefact JSON '.length)}`);
+        }
+        throw new CliUsageError('Domain control input is not valid JSON.');
+    }
+    const schema = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed.schema
+        : null;
+    const document = schema === DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA
+        ? buildDomainControlManifest(parsed, context.now())
+        : schema === DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA
+            ? reviewDomainControlManifest(parsed, context.now())
+            : schema === CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA
+                ? buildCliDomainControlReview(input, context.now())
+                : schema === DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA
+                    ? buildDomainControlFlightRecorder(parsed, context.now())
+                    : null;
+    if (!document) {
+        throw new CliUsageError('Domain control input must use a supported manifest, review, saved-Lookup review, or flight-recorder schema.');
+    }
+    const terminalDocument = schema === CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA
+        ? formatCliDomainControlReview(document)
+        : schema === DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA
+            ? formatDomainControlFlightRecorder(document)
+            : formatDomainControlResult(document);
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? schema === DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA
+                ? serializeDomainControlManifest(document)
+                : schema === DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA
+                    ? serializeDomainControlFlightRecorder(document)
+                    : formatJsonDocument(document)
+            : context.terminal(terminalDocument, args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+async function runAssuranceReviewCommand(args, dependencies, context) {
+    context.setFailureLabel('Domain assurance review');
+    let input;
+    try {
+        input = dependencies.readArtifactInput
+            ? await dependencies.readArtifactInput(args.source)
+            : await context.readInput(args.source, MAX_ASSURANCE_INPUT_BYTES, 'Domain assurance input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read domain assurance input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('assurance requires one versioned JSON file or a document on stdin.');
+    let parsed;
+    try {
+        scanBoundedJson(input);
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new CliUsageError('Domain assurance input is not valid bounded JSON without duplicate keys.');
+    }
+    let document;
+    try {
+        document = buildDomainAssurance(parsed, context.now());
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, 'Domain assurance input is invalid'));
+    }
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatDomainAssurance(document), args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+async function runChangePacketCommand(args, dependencies, context) {
+    context.setFailureLabel('Domain change packet');
+    let input;
+    try {
+        input = dependencies.readArtifactInput
+            ? await dependencies.readArtifactInput(args.source)
+            : await context.readInput(args.source, MAX_DOMAIN_CHANGE_PACKET_INPUT_BYTES, 'Domain change packet input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read domain change packet input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('change-packet requires one versioned JSON file or a document on stdin.');
+    let parsed;
+    try {
+        scanBoundedJson(input);
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new CliUsageError('Domain change packet input is not valid bounded JSON without duplicate keys.');
+    }
+    let document;
+    try {
+        document = await buildDomainChangePacket(parsed, context.now());
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, 'Domain change packet input is invalid'));
+    }
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatDomainChangePacket(document), args.color));
+    }
+    return document.gate.pass ? EXIT_CODES.SUCCESS : EXIT_CODES.PARTIAL_FAILURE;
+}
+async function runSharingReviewCommand(args, dependencies, context) {
+    context.setFailureLabel('Evidence sharing review');
+    let input;
+    try {
+        input = dependencies.readArtifactInput
+            ? await dependencies.readArtifactInput(args.source)
+            : await context.readInput(args.source, MAX_SHARING_REVIEW_BYTES, 'Sharing review input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read sharing review input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('sharing-review requires one artefact JSON file or a document on stdin.');
+    let document;
+    try {
+        document = await buildSharingReview(input, {
+            marking: args.marking,
+            recipientScope: args.recipientScope,
+            purpose: args.purpose,
+            humanReviewed: args.humanReviewed,
+            personalDataReviewed: args.personalDataReviewed,
+            redactionsConfirmed: args.redactionsConfirmed,
+        }, context.now());
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, 'Sharing review input is invalid'));
+    }
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatSharingReview(document), args.color));
+    }
+    return document.summary.status === 'blocked' ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+}
+async function runCertificateIntakeCommand(args, dependencies, context) {
+    context.setFailureLabel('Certificate event intake');
+    let input;
+    try {
+        input = dependencies.readArtifactInput
+            ? await dependencies.readArtifactInput(args.source)
+            : await context.readInput(args.source, MAX_CT_EVENT_INPUT_BYTES, 'Certificate event input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read certificate event input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('ct-intake requires one versioned JSON file or a document on stdin.');
+    let parsed;
+    try {
+        scanBoundedJson(input);
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new CliUsageError('Certificate event input is not valid bounded JSON without duplicate keys.');
+    }
+    let document;
+    try {
+        document = buildCtEventFindings(parsed);
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, 'Certificate event input is invalid'));
+    }
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatCtEventFindings(document), args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
+const ASSURANCE_COMMAND_HANDLERS = Object.freeze({
+    'manifest': runManifestCommand,
+    'map-observations': runObservationBridgeCommand,
+    'oam-export': runObservationBridgeCommand,
+    'domain-control': runDomainControlCommand,
+    'assurance': runAssuranceReviewCommand,
+    'change-packet': runChangePacketCommand,
+    'sharing-review': runSharingReviewCommand,
+    'ct-intake': runCertificateIntakeCommand,
+});
+function runAssuranceCommand(args, dependencies, context) {
+    return runDiscriminatedCommandHandler(ASSURANCE_COMMAND_HANDLERS, args, dependencies, context);
+}
+export { ASSURANCE_COMMAND_HANDLERS, runAssuranceCommand };