Files
rea/src/domain/firmware/firmwareAnalysis.ts
T

164 lines
5.0 KiB
TypeScript

import { z } from "zod";
import { isAbsolute } from "node:path";
import { digestSchema } from "../digests.js";
import { jsonValueSchema, type JsonValue } from "../jsonValue.js";
import { localPathStringSchema } from "../localPath.js";
const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
const range = z.strictObject({ offset: bytes, length: bytes.positive() });
const target = {
path: localPathStringSchema
.refine(isAbsolute, {
message:
"path must be an absolute local filesystem path (for example /tmp/firmware.bin or C:\\firmware\\firmware.bin)",
})
.describe(
"Absolute local firmware file; never executed. Relative paths are rejected.",
),
};
/** Explicit firmware inspection and extraction intent, independent of engines. */
export const firmwareInputSchemas = {
inspect_firmware_regions: z.strictObject(target),
extract_firmware: z.strictObject({
...target,
output_directory: localPathStringSchema
.refine(isAbsolute, {
message: "output_directory must be an absolute local filesystem path",
})
.describe("Absolute, absent output directory; parent must exist"),
range: range
.optional()
.describe("Explicit file-byte interval; omit to extract the whole file"),
max_depth: z
.number()
.int()
.min(1)
.max(10)
.default(3)
.describe("Extraction depth; reaching it yields partial analysis"),
max_output_bytes: z
.number()
.int()
.min(1)
.max(512 * 1024 * 1024)
.default(256 * 1024 * 1024)
.describe(
"Staging file-byte budget, checked during extraction; transient overshoot is possible",
),
max_output_files: z
.number()
.int()
.min(1)
.max(100_000)
.default(10_000)
.describe("Staging entry budget, including directories and links"),
}),
} as const;
/** Supported firmware operations. */
export type FirmwareOperation = keyof typeof firmwareInputSchemas;
/** Correlated, validated firmware request. */
export type FirmwareRequest = {
[Name in FirmwareOperation]: {
operation: Name;
input: z.infer<(typeof firmwareInputSchemas)[Name]>;
};
}[FirmwareOperation];
/** Validate the operation with its exact input contract. */
export const firmwareRequestSchema = z.discriminatedUnion("operation", [
z.strictObject({
operation: z.literal("inspect_firmware_regions"),
input: firmwareInputSchemas.inspect_firmware_regions,
}),
z.strictObject({
operation: z.literal("extract_firmware"),
input: firmwareInputSchemas.extract_firmware,
}),
]);
const engine = z.strictObject({
name: z.string(),
version: z.string(),
executable_path: z.string(),
executable_sha256: digestSchema,
source_revision: z.null(),
worker_count: z.literal(1),
});
const selection = z.strictObject({ ...range.shape, sha256: digestSchema });
const chunk = z.strictObject({
input_path: z.string(),
provider_id: z.string(),
range,
handler: z.string().nullable(),
encrypted: z.boolean().nullable(),
root_file_range: range.nullable(),
});
/** Completed firmware result retained when private-runtime cleanup cannot be confirmed. */
export interface FirmwarePartialObservation {
readonly kind: "firmware";
readonly result: JsonValue;
/** Completed producer data, artifact identity and analysis metadata. */
readonly provenance?: JsonValue;
}
/** Portable results retain reported boundaries, unknowns and extraction lineage. */
export const firmwareResultSchemas = {
inspect_firmware_regions: z.strictObject({
engine,
input_size: bytes,
regions: z.array(
z.strictObject({
provider_id: z.string(),
offset: bytes,
reported_size: bytes,
signature: z.string(),
description: z.string(),
reported_confidence: z.number().int().min(0).max(255),
size_basis: z.literal("provider_reported_validation_unknown"),
}),
),
coverage: z.literal("signature_scan"),
}),
extract_firmware: z.strictObject({
engine,
selection,
output_directory: z.string(),
coverage: z.enum(["complete", "partial"]),
files: z.array(
z.strictObject({
relative_path: z.string(),
path: z.string(),
size: bytes,
sha256: digestSchema,
reported_sha256: digestSchema.nullable(),
mime_type: z.string().nullable(),
analysis_depth: bytes.nullable(),
runtime_address: z.null(),
original_file_range: z.null(),
}),
),
unpublished_entries: z.array(
z.strictObject({
relative_path: z.string(),
kind: z.enum(["symlink", "special"]),
link_target: z.string().nullable(),
}),
),
chunks: z.array(chunk),
derivations: z.array(
z.strictObject({
parent_path: z.string(),
child_path: z.string(),
provider_blob_id: z.string(),
handler: z.string().nullable(),
parent_file_range: range.nullable(),
}),
),
depth_limited_paths: z.array(z.string()),
diagnostics: z.array(jsonValueSchema),
published_bytes: bytes,
}),
} as const;