Files
reverse-engineering-anything/src/application/desktop/DesktopApplicationState.ts
T
morluto b51ed4c3ec refactor(kernel): migrate the remaining SHA-256 hex digests to sha256Hex and move isRecord into src/kernel (#11571)
* refactor(kernel): migrate the remaining one-shot SHA-256 hex digests to sha256Hex

* refactor(kernel): move isRecord into src/kernel and replace its inline copies (#11574)

* fix(scripts): import isRecord from src/kernel in the managed manifest parser
2026-11-15 20:53:36 -05:00

617 lines
22 KiB
TypeScript

import { unknownTarget } from "../../domain/targetIdentity.js";
import {
desktopViewPolicy,
desktopViewPolicyInputSchema,
type DesktopViewPolicy,
type DesktopViewPolicyInput,
} from "../../domain/desktop/desktopViewPolicy.js";
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { ArtifactResourceScope } from "../../resources/index.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisInputError,
cancelledBy,
carriedReason,
isAborted,
} from "../../domain/analysisErrorCore.js";
import { analysisErrorWithCancellation } from "../../domain/analysisErrorCancellation.js";
import { analysisErrorWithCleanupDependencies } from "../../domain/analysisErrorCleanup.js";
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
import {
desktopApplicationCaptureSchema,
type DesktopApplicationCapture,
} from "../../domain/desktop/desktopCapture.js";
import type {
DesktopApplicationState,
DesktopStatePath,
} from "../../domain/desktop/desktopState.js";
import { openStateDocument } from "../../domain/desktop/gzipDocument.js";
import { diffStateViews } from "../../domain/desktop/stateChanges.js";
import {
keyfileView,
plainRecord,
SQLITE_SIDECARS,
textualView,
} from "../../domain/desktop/stateFormats.js";
import {
applicationNames,
isApplicationDconfGroup,
roleFacts,
selectedHomePath,
stateReasons,
stateRole,
} from "../../domain/desktop/stateRoles.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
import {
safeParseEvidence,
unsupportedEvidenceFormatError,
} from "../../domain/evidenceValidation.js";
import { isUnsupportedEvidenceFormat } from "../../domain/evidenceFormat.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import { describeValidationFailure } from "../../domain/validationFailure.js";
import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
import { readJsonFile } from "../JsonFiles.js";
import { readZipView } from "./DesktopZipView.js";
import {
withRetainedContent,
type RetainedContent,
} from "./DesktopRetainedContent.js";
import {
indexState,
observedFileAt,
pathVersions,
statePaths,
type StateIndex,
} from "./DesktopStateVersions.js";
import {
DESKTOP_OPERATION,
DESKTOP_PROVIDER,
desktopOperationFailure,
} from "./DesktopCaptureRefusals.js";
import { isRecord } from "../../kernel/isRecord.js";
const OPERATION = "inspect_desktop_application_state";
/**
* Readers for formats that need a tool or worker, supplied by composition. Each
* database is staged with its retained log in a private directory the caller removes.
* Expected format/read failures return an error result. Cancellation throws a typed
* AnalysisCancelledError or ArtifactReaderFailure; cleanup failures retain their owner.
*/
export interface DesktopStateReaders {
readonly sqlite: (
database: string,
signal?: AbortSignal,
policy?: DesktopViewPolicy,
) => Promise<{ ok: true; view: JsonValue } | { ok: false; error: string }>;
readonly dconf: (
database: string,
signal?: AbortSignal,
) => Promise<{ ok: true; text: string } | { ok: false; error: string }>;
}
type Version = DesktopStatePath["versions"][number];
type Change = DesktopStatePath["changes"][number];
const inputError = (userMessage: string, remediationAction: string) =>
new AnalysisInputError(OPERATION, { userMessage, remediationAction }, [
{ path: ["capture"], reason: "invalid_value", message: userMessage },
]);
/** Admit `capture.json` only as complete desktop capture Evidence. */
export const readDesktopCapture = async (
folder: string,
signal: AbortSignal | undefined,
): Promise<{ evidence: Evidence; capture: DesktopApplicationCapture }> => {
const resources = new ArtifactResourceScope();
const outcome = await resources
.run(async () => {
const loaded = await readJsonFile(
join(folder, "capture.json"),
signal,
resources,
OPERATION,
);
if (!loaded.ok) {
if (loaded.error instanceof AnalysisError) throw loaded.error;
throw inputError(
`${join(folder, "capture.json")} could not be read as JSON.`,
"Pass a folder written by capture-desktop-application.",
);
}
const evidence = safeParseEvidence(loaded.value);
// A capture from another format revision is refused with the recreate
// guidance, not reported as some other kind of file.
if (!evidence.ok && isUnsupportedEvidenceFormat(evidence.error))
throw unsupportedEvidenceFormatError(evidence.error);
if (
!evidence.ok ||
evidence.value.operation !== DESKTOP_OPERATION ||
evidence.value.predicate_type !== "rea.desktop-application-capture" ||
evidence.value.provider.id !== DESKTOP_PROVIDER.id ||
evidence.value.provider.version !== DESKTOP_PROVIDER.version
)
throw inputError(
"capture.json is not desktop application capture Evidence.",
"Pass a folder written by capture-desktop-application.",
);
const capture = desktopApplicationCaptureSchema.safeParse(
evidence.value.normalized_result,
);
if (!capture.success)
throw inputError(
`The capture result is malformed (${describeValidationFailure(capture.error)}).`,
"Capture the application again.",
);
return { evidence: evidence.value, capture: capture.data };
})
.then(ok, (cause: unknown) => err(cause));
try {
await resources.close();
} catch (cause: unknown) {
const cleanup = desktopOperationFailure(
cause,
signal,
OPERATION,
"Desktop capture input",
);
if (outcome.ok && !isAborted(signal))
throw cleanup.retainPartialObservation(outcome.value.evidence);
const primary = outcome.ok
? cancelledBy(
OPERATION,
// A completed outcome reaches here only after the caller aborted.
carriedReason(signal?.reason),
).retainPartialObservation(outcome.value.evidence)
: desktopOperationFailure(
outcome.error,
undefined,
OPERATION,
"Desktop capture input",
);
if (!outcome.ok && signal?.aborted)
analysisErrorWithCancellation(primary, cancelledBy(OPERATION, signal));
throw analysisErrorWithCleanupDependencies(primary, cleanup, OPERATION);
}
if (!outcome.ok) {
if (!signal?.aborted) throw outcome.error;
throw analysisErrorWithCancellation(
desktopOperationFailure(
outcome.error,
undefined,
OPERATION,
"Desktop capture input",
),
cancelledBy(OPERATION, signal),
);
}
if (signal?.aborted)
throw cancelledBy(OPERATION, signal).retainPartialObservation(
outcome.value.evidence,
);
return outcome.value;
};
interface ViewContext {
readonly content: RetainedContent;
readonly readers: DesktopStateReaders;
readonly names: ReadonlySet<string>;
readonly signal: AbortSignal | undefined;
readonly index: StateIndex;
readonly policy: DesktopViewPolicy;
}
const dconfGroups = (text: string, names: ReadonlySet<string>) => {
const groups = keyfileView(text);
const application = plainRecord<JsonValue>();
const others: string[] = [];
for (const [group, keys] of Object.entries(groups))
if (isApplicationDconfGroup(group, names)) application[group] = keys;
else others.push(group);
return { groups: application, other_groups: others };
};
/**
* Run a reader on verified bytes written to a private directory. A failed
* removal keeps the directory's owner and is reported with the read's outcome.
*/
const withStaged = async <Value>(
files: readonly { readonly name: string; readonly bytes: Uint8Array }[],
read: (paths: readonly string[]) => Promise<Value>,
): Promise<Value> => {
const root = await PrivateRuntimeRoot.create({
prefix: "rea-desktop-state-",
});
let outcome:
| { readonly kind: "completed"; readonly value: Value }
| { readonly kind: "failed"; readonly cause: unknown };
try {
const paths: string[] = [];
for (const file of files) {
const path = join(root.path, file.name);
await writeFile(path, file.bytes, { mode: 0o600, flag: "wx" });
paths.push(path);
}
outcome = { kind: "completed", value: await read(paths) };
} catch (cause: unknown) {
outcome = { kind: "failed", cause };
}
const resources = new ArtifactResourceScope();
const removed = await resources.release({
kind: "private-runtime-root",
resource: root.path,
root,
});
if (removed.kind === "failed")
throw resources.cleanupFailure(outcome, [removed]);
if (outcome.kind === "failed") throw outcome.cause;
return outcome.value;
};
type ViewOutcome =
| { readonly view: JsonValue; readonly error: null }
| { readonly view: null; readonly error: string };
const failed = (error: string): ViewOutcome => ({ view: null, error });
/** One retained version's verified document, a gzip file's decompressed, with its format already detected. */
interface ReadInput {
readonly path: string;
readonly bytes: Uint8Array;
readonly version: Version;
}
/**
* A sidecar's verified bytes to stage beside the database, or why the
* database cannot be read: reading it without a sidecar it had could hide or
* misstate committed rows.
*/
const sidecarBytes = async (
{ path, version }: Pick<ReadInput, "path" | "version">,
sidecar: (typeof SQLITE_SIDECARS)[number],
context: ViewContext,
): Promise<Result<Buffer | undefined, string>> => {
const { present, sha256 } = observedFileAt(
`${path}${sidecar.suffix}`,
version.checkpoint_index,
context.index,
);
if (present === null)
return err(
`the capture did not record whether the database's ${sidecar.label} existed`,
);
if (present && sha256 === null)
return err(`the database's ${sidecar.label} was not retained`);
if (sha256 === null) return ok(undefined);
const bytes = await context.content.read(sha256, context.signal);
return bytes.ok
? ok(bytes.value)
: err(`the database's ${sidecar.label} ${bytes.error}`);
};
const sqliteView = async (
input: ReadInput,
context: ViewContext,
): Promise<ViewOutcome> => {
const database = observedFileAt(
input.path,
input.version.checkpoint_index,
context.index,
);
if (database.present !== true || database.sha256 !== input.version.sha256)
return failed(
"the capture did not confirm the database's retained version at this checkpoint",
);
// The SQLite reader accepts an inactive rollback journal and refuses a hot one.
const staged = [{ name: "state.db", bytes: input.bytes }];
for (const sidecar of SQLITE_SIDECARS) {
const bytes = await sidecarBytes(input, sidecar, context);
if (!bytes.ok) return failed(bytes.error);
if (bytes.value !== undefined)
staged.push({ name: `state.db${sidecar.suffix}`, bytes: bytes.value });
}
return withStaged(staged, async ([database]) => {
const read = await context.readers.sqlite(
database ?? "",
context.signal,
context.policy,
);
return read.ok ? { view: read.view, error: null } : failed(read.error);
});
};
const dconfView = async (
{ bytes }: ReadInput,
context: ViewContext,
): Promise<ViewOutcome> =>
withStaged([{ name: "user", bytes }], async ([database]) => {
const dump = await context.readers.dconf(database ?? "", context.signal);
return dump.ok
? { view: dconfGroups(dump.text, context.names), error: null }
: failed(dump.error);
});
/** A reader's result as a version's view or view_error. */
const outcomeOf = (read: Result<JsonValue, string>): ViewOutcome =>
read.ok ? { view: read.value, error: null } : failed(read.error);
/** Read one retained version into JSON for its own format. */
const viewOf = async (
input: ReadInput,
context: ViewContext,
): Promise<ViewOutcome> => {
const format = input.version.format ?? "binary";
switch (format) {
case "text":
case "json":
case "keyfile":
case "xml":
return outcomeOf(textualView(format, input.bytes, context.policy));
case "zip":
return outcomeOf(
await readZipView(input.bytes, context.signal, context.policy),
);
case "dconf":
return dconfView(input, context);
case "sqlite":
return sqliteView(input, context);
case "binary":
return { view: null, error: null };
}
};
const EMPTY_CHANGE = {
added: [],
removed: [],
changed: [],
added_count: 0,
removed_count: 0,
changed_count: 0,
complete: true,
};
const changeBetween = (before: Version, after: Version): Change => {
const ends = {
from_index: before.checkpoint_index,
to_index: after.checkpoint_index,
from: before.checkpoint,
to: after.checkpoint,
};
if (!before.present) return { ...ends, kind: "created", ...EMPTY_CHANGE };
if (!after.present) return { ...ends, kind: "deleted", ...EMPTY_CHANGE };
if (
before.view_error !== null ||
after.view_error !== null ||
before.format === null ||
after.format === null
)
return { ...ends, kind: "unreadable", ...EMPTY_CHANGE };
if (before.format !== after.format)
return { ...ends, kind: "format", ...EMPTY_CHANGE };
if (before.format === "binary")
return { ...ends, kind: "content", ...EMPTY_CHANGE };
const difference = diffStateViews(before.format, before.view, after.view);
return {
...ends,
...difference,
added: [...difference.added],
removed: [...difference.removed],
changed: [...difference.changed],
};
};
const readVersion = async (
version: Version,
path: string,
context: ViewContext,
): Promise<void> => {
if (context.signal?.aborted === true)
throw cancelledBy(OPERATION, context.signal);
if (!version.present) return;
if (version.sha256 === null) {
version.view_error = "content not retained";
return;
}
const bytes = await context.content.read(version.sha256, context.signal);
if (!bytes.ok) {
version.view_error = `retained content ${bytes.error}`;
return;
}
const document = openStateDocument(path, bytes.value, context.policy);
version.format = document.format;
if (document.compression !== undefined)
version.compression = document.compression;
const outcome =
"error" in document
? failed(document.error)
: await viewOf({ path, bytes: document.bytes, version }, context);
version.view = outcome.view;
version.view_error = outcome.error;
};
const hasDconfGroups = (version: Version): boolean => {
const view = version.view;
return (
version.format === "dconf" &&
isRecord(view) &&
typeof view.groups === "object" &&
view.groups !== null &&
Object.keys(view.groups).length > 0
);
};
/** Read every version of one path and derive its role and changes. */
const describePath = async (
capture: DesktopApplicationCapture,
path: string,
facts: ReturnType<typeof roleFacts>,
context: ViewContext,
): Promise<DesktopStatePath> => {
const versions = pathVersions(capture, path, context.index);
for (const version of versions) await readVersion(version, path, context);
const reasons = [
...stateReasons(
facts,
path,
(context.index.changes.get(path) ?? []).map((entry) => entry.change),
versions.some(hasDconfGroups),
),
];
const home = capture.host.home;
const role = stateRole(reasons, selectedHomePath(facts, path));
return {
path,
home_path: path.startsWith(`${home}/`) ? path.slice(home.length + 1) : null,
role:
facts.sqliteSidecars?.has(path) === true && role === "unrelated"
? "application_state"
: role,
reasons,
format:
versions.findLast((version) => version.format !== null)?.format ?? null,
versions,
changes: versions
.slice(1)
.map((version, index) =>
changeBetween(versions[index] ?? version, version),
),
};
};
const stateLimitations = (policy: DesktopViewPolicy) => [
"Roles are inferred from state directories, open files, window titles, selected paths and dconf key names; a path can be misattributed.",
"Views cover retained content only; a file that existed before the capture but outside the content roots has no starting view.",
`SQLite views list at most ${String(policy.sqlite_rows)} rows of ${String(policy.sqlite_tables)} ordinary tables, text views ${String(policy.text_lines)} lines and XML views ${String(policy.xml_nodes)} nodes; changes between truncated views, or views with an unread table, are marked incomplete. Increase the corresponding --view-policy budget and retry the same capture; no restart is needed.`,
`Each projected SQLite table view is bounded at sqlite_view_bytes=${String(policy.sqlite_view_bytes)} UTF-8 JSON bytes. A refused table keeps its error; other tables remain readable. Raise sqlite_view_bytes in --view-policy on the next call for that refusal. The separate SQLite worker reply and value/record limits may refuse earlier and are not raised by view policy.`,
`JSON and key file views read files of at most ${String(policy.parsed_bytes)} bytes and JSON nested at most ${String(policy.json_depth)} levels; only numbers JavaScript holds exactly are admitted. Increase parsed_bytes or json_depth in --view-policy for a budget refusal; byte budgets do not change numeric exactness or Evidence nesting.`,
"dconf views keep only groups whose path names the application.",
`Zip views list at most ${String(policy.zip_entries)} entries and read an entry only when unencrypted, stored or deflated, at most ${String(policy.zip_entry_bytes)} bytes and ${String(policy.zip_ratio)} times its compressed size, up to ${String(policy.zip_bytes)} bytes per archive. Increase the corresponding --view-policy budget for a resource refusal; databases and archives inside an archive are not read.`,
`A gzip file's view is its document's, read only when it is at most ${String(policy.zip_entry_bytes)} bytes and at most ${String(policy.zip_ratio)} times the file's size; a database inside one is not read, nor a gzip file inside an archive.`,
];
/** Read a capture folder into the application's state view. */
const inspectState = async (
folder: string,
readers: DesktopStateReaders,
signal: AbortSignal | undefined,
options: DesktopStateViewOptions,
): Promise<Evidence> => {
const policy = desktopViewPolicy(options.viewPolicy);
const { evidence, capture } = await readDesktopCapture(folder, signal);
const names = applicationNames(capture);
const facts = roleFacts(capture);
const index = indexState(capture);
const candidates = statePaths(index);
for (const selected of options.paths ?? [])
if (!candidates.includes(selected))
throw new AnalysisInputError(
OPERATION,
{
userMessage: `Captured path ${JSON.stringify(selected)} was not found.`,
remediationAction:
"Use an exact path from this capture's state view; no current filesystem path is substituted.",
},
[{ path: ["paths"], reason: "invalid_value" }],
);
const paths = await withRetainedContent(
folder,
async (content) => {
const context: ViewContext = {
content,
readers,
names,
signal,
index,
policy,
};
const described: DesktopStatePath[] = [];
for (const path of candidates)
if (options.paths === undefined || options.paths.includes(path))
described.push(await describePath(capture, path, facts, context));
return described;
},
policy.file_bytes,
);
const limitations = [
...stateLimitations(policy),
...(capture.state.state_directories === undefined
? [
"The capture does not record its state directories as walked, so files in a symlinked state directory may be classed as documents.",
]
: []),
];
const result: DesktopApplicationState = {
effective_view_policy: policy,
capture: {
evidence_id: evidence.evidence_id,
home: capture.host.home,
checkpoints: capture.state.checkpoints.map(
(checkpoint) => checkpoint.name,
),
limitations: capture.limitations,
omitted_content: capture.state.omitted_content,
},
application_names: [...names],
paths,
limitations,
};
if (signal?.aborted === true) throw cancelledBy(OPERATION, signal);
return createEvidence(unknownTarget("not-observed"), DESKTOP_PROVIDER, {
predicateType: "rea.desktop-application-state",
operation: OPERATION,
parameters: {
capture_evidence_id: evidence.evidence_id,
...(options.viewPolicy === undefined
? {}
: { view_policy: { ...options.viewPolicy } }),
...(options.paths === undefined ? {} : { paths: [...options.paths] }),
},
result,
confidence: "inferred",
authority: "analyst-inference",
limitations: [...limitations, ...capture.limitations],
});
};
export interface DesktopStateViewOptions {
readonly viewPolicy?: DesktopViewPolicyInput | undefined;
/** Exact original captured paths; omission examines every retained path. */
readonly paths?: readonly string[] | undefined;
}
/** Inspect one capture folder, returning its state view Evidence or a failure. */
export const inspectDesktopApplicationState = async (
folder: string,
readers: DesktopStateReaders,
signal?: AbortSignal,
options: DesktopStateViewOptions = {},
): Promise<Evidence | AnalysisError> => {
try {
const admitted = desktopViewPolicyInputSchema.safeParse(
options.viewPolicy === undefined ? {} : options.viewPolicy,
);
if (!admitted.success)
return analysisInputErrorFromIssues(
OPERATION,
admitted.error.issues,
options.viewPolicy,
);
return await inspectState(folder, readers, signal, {
...options,
...(options.viewPolicy === undefined
? {}
: { viewPolicy: admitted.data }),
});
} catch (cause: unknown) {
return desktopOperationFailure(
cause,
signal,
OPERATION,
"Desktop state view",
);
}
};