chore: merge main into feat/signature-posture
main now carries #964 at skill version 29, so this branch moves to 30. Regenerate the product catalog, conformance manifest, skill digest and package metadata on top of it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -25,6 +25,7 @@ import type {
|
||||
JavaScriptSourceMapOriginal,
|
||||
} from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
import { analyzeJavaScriptJsonModule } from "./JavaScriptJsonModules.js";
|
||||
import { htmlArtifactReferences } from "../../domain/javascript/htmlArtifactReferences.js";
|
||||
|
||||
interface MutableArtifactAnalysis {
|
||||
readonly files: AnalyzedJavaScriptArtifactFile[];
|
||||
@@ -205,26 +206,13 @@ const parseHtmlScripts = (
|
||||
path: string,
|
||||
text: string,
|
||||
): JavaScriptHtmlScriptObservation[] => {
|
||||
const scripts: JavaScriptHtmlScriptObservation[] = [];
|
||||
const baseHref = htmlBaseHref(text);
|
||||
const pattern = /<script\b[^>]*\bsrc\s*=\s*(["'])([^"']+)\1[^>]*>/giu;
|
||||
for (const match of text.matchAll(pattern)) {
|
||||
const script = match[2];
|
||||
if (script === undefined) continue;
|
||||
const start = match.index;
|
||||
scripts.push({
|
||||
html_path: path,
|
||||
script_path: script,
|
||||
base_href: baseHref,
|
||||
location: rangeForOffsets(text, start, start + match[0].length),
|
||||
});
|
||||
}
|
||||
return scripts;
|
||||
};
|
||||
|
||||
const htmlBaseHref = (text: string): string | null => {
|
||||
const match = /<base\b[^>]*\bhref\s*=\s*(["'])([^"']+)\1[^>]*>/iu.exec(text);
|
||||
return match?.[2] ?? null;
|
||||
const { scripts, baseHref } = htmlArtifactReferences(text);
|
||||
return scripts.map(({ scriptPath, startOffset, endOffset }) => ({
|
||||
html_path: path,
|
||||
script_path: scriptPath,
|
||||
base_href: baseHref,
|
||||
location: rangeForOffsets(text, startOffset, endOffset),
|
||||
}));
|
||||
};
|
||||
|
||||
const parseSourceMap = (
|
||||
|
||||
@@ -5,7 +5,10 @@ import {
|
||||
linkElectronRoleToAsset,
|
||||
type JavaScriptArtifactGraphContext,
|
||||
} from "./JavaScriptArtifactGraphContext.js";
|
||||
import { artifactObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
|
||||
import {
|
||||
artifactObservationEvidence,
|
||||
staticInferenceEvidence,
|
||||
} from "./JavaScriptArtifactGraphEvidence.js";
|
||||
import { completeApplicationCoverage } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
|
||||
import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
|
||||
|
||||
@@ -57,7 +60,32 @@ export const addJavaScriptHtmlRoles = (
|
||||
htmlBaseHref: script.base_href,
|
||||
});
|
||||
const resolvedPath = resolution.resolved_path;
|
||||
if (resolvedPath === null) continue;
|
||||
if (resolvedPath === null) {
|
||||
context.accumulator.addNode({
|
||||
kind: role.kind,
|
||||
identity: role.identity,
|
||||
observations: [
|
||||
{
|
||||
label: script.script_path,
|
||||
properties: {
|
||||
mechanism: "html-script-reference",
|
||||
script_path: script.script_path,
|
||||
base_href: script.base_href,
|
||||
...resolution,
|
||||
},
|
||||
evidence: staticInferenceEvidence({
|
||||
sha256: html.sha256,
|
||||
path: html.path,
|
||||
range: script.location,
|
||||
operation: "resolve-html-script-reference",
|
||||
coverage: completeApplicationCoverage(),
|
||||
limitations: resolution.limitations,
|
||||
}),
|
||||
},
|
||||
],
|
||||
});
|
||||
continue;
|
||||
}
|
||||
const resolved = context.fileNodes.get(resolvedPath);
|
||||
if (resolved === undefined) continue;
|
||||
addStaticInferenceEdge(context, {
|
||||
|
||||
@@ -676,3 +676,52 @@ const file = (
|
||||
? { included: false, reason: "invalid-utf8" }
|
||||
: { included: true, value: text },
|
||||
});
|
||||
|
||||
describe("exact HTML resource resolution", () => {
|
||||
it.each([
|
||||
["extension", ["app.js"]],
|
||||
["directory index", ["app/index.js"]],
|
||||
["directory package", ["app/package.json", "app/entry.js"]],
|
||||
] as const)("does not infer a file from %s fallback", (_name, paths) => {
|
||||
const files = fileMap([
|
||||
file("index.html", "root"),
|
||||
...paths.map((path) =>
|
||||
file(
|
||||
path,
|
||||
"root",
|
||||
path.endsWith("package.json") ? '{"main":"entry.js"}' : "",
|
||||
),
|
||||
),
|
||||
]);
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "./app",
|
||||
sourcePath: "index.html",
|
||||
context: "html-reference",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({ resolution_status: "not-found", resolved_path: null });
|
||||
});
|
||||
|
||||
it("prefers an exact extensionless resource and retains URL suffix handling", () => {
|
||||
const files = fileMap([
|
||||
file("renderer/index.html", "root"),
|
||||
file("assets/app", "root"),
|
||||
file("assets/app.js", "root"),
|
||||
file("assets/app/index.js", "root"),
|
||||
]);
|
||||
expect(
|
||||
resolve({
|
||||
declaredPath: "./app?cache=1#v2",
|
||||
sourcePath: "renderer/index.html",
|
||||
context: "html-reference",
|
||||
htmlBaseHref: "/assets/",
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({
|
||||
declared_path: "./app?cache=1#v2",
|
||||
resolution_status: "resolved",
|
||||
resolved_path: "assets/app",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -86,13 +86,25 @@ const resolvePackagePath = (
|
||||
input: ResolveArtifactPathInput,
|
||||
packageChain: ReadonlySet<string>,
|
||||
mode: "full" | "files-and-index" = "full",
|
||||
exportsTargetUrl = false,
|
||||
): ArtifactPathResolution => {
|
||||
const rejected = rejectDeclaration(input);
|
||||
if (rejected !== null) return rejected;
|
||||
const candidate = contextualCandidate(input);
|
||||
const candidate = contextualCandidate(input, exportsTargetUrl);
|
||||
if (typeof candidate !== "string") return candidate;
|
||||
const confined = confineCandidate(input, candidate);
|
||||
if (typeof confined !== "string") return confined;
|
||||
if (input.context === "html-reference")
|
||||
return outcome(
|
||||
input,
|
||||
resolveFileCandidates(input, [confined]) ?? {
|
||||
resolvedPath: null,
|
||||
status: "not-found",
|
||||
limitations: [
|
||||
`The exact HTML resource ${confined} was not found among the selected application files.`,
|
||||
],
|
||||
},
|
||||
);
|
||||
const resolved =
|
||||
mode === "files-and-index"
|
||||
? (resolveFileCandidates(input, [
|
||||
@@ -124,11 +136,13 @@ const rejectDeclaration = (
|
||||
|
||||
const contextualCandidate = (
|
||||
input: ResolveArtifactPathInput,
|
||||
exportsTargetUrl: boolean,
|
||||
): string | ArtifactPathResolution => {
|
||||
const { context } = input;
|
||||
const declared =
|
||||
let declared =
|
||||
context === "html-reference" ||
|
||||
context === "url-reference" ||
|
||||
exportsTargetUrl ||
|
||||
(context === "module-specifier" && input.moduleKind !== "require")
|
||||
? stripQueryAndFragment(input.declaredPath)
|
||||
: input.declaredPath;
|
||||
@@ -146,6 +160,24 @@ const contextualCandidate = (
|
||||
return unresolvedOutcome(input, "external", [
|
||||
"URL schemes and protocol-relative URLs are outside this local artifact path context.",
|
||||
]);
|
||||
// Exports targets use URL paths for both loaders; legacy main fields remain literal.
|
||||
if (
|
||||
exportsTargetUrl ||
|
||||
(context === "module-specifier" && input.moduleKind !== "require")
|
||||
) {
|
||||
try {
|
||||
declared = decodeURIComponent(declared);
|
||||
} catch (cause: unknown) {
|
||||
void cause;
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"The module URL path contains malformed percent encoding.",
|
||||
]);
|
||||
}
|
||||
if (declared.includes("\0"))
|
||||
return unresolvedOutcome(input, "rejected", [
|
||||
"The decoded module URL path contains NUL.",
|
||||
]);
|
||||
}
|
||||
const relative = declared.startsWith("/") ? declared.slice(1) : declared;
|
||||
return declared.startsWith("/")
|
||||
? relative
|
||||
@@ -317,6 +349,12 @@ const resolveCandidate = (
|
||||
`Directory package metadata ${packagePath} is not valid package JSON.`,
|
||||
],
|
||||
};
|
||||
if (main.status === "rejected")
|
||||
return {
|
||||
resolvedPath: null,
|
||||
status: "rejected",
|
||||
limitations: [`Package metadata ${packagePath}: ${main.limitation}`],
|
||||
};
|
||||
if (main.status === "unmatched")
|
||||
return {
|
||||
resolvedPath: null,
|
||||
@@ -353,7 +391,9 @@ const resolveCandidate = (
|
||||
if (index !== null) return index;
|
||||
}
|
||||
// Preserve recursive artifact package lookup only after legacy file/index fallbacks.
|
||||
return candidateOutcome(resolvePackagePath(entryInput, chain));
|
||||
return candidateOutcome(
|
||||
resolvePackagePath(entryInput, chain, "full", main.source === "exports"),
|
||||
);
|
||||
};
|
||||
|
||||
const candidateOutcome = (
|
||||
@@ -408,6 +448,7 @@ const packageEntry = (
|
||||
}
|
||||
| { readonly status: "missing" }
|
||||
| { readonly status: "invalid" }
|
||||
| { readonly status: "rejected"; readonly limitation: string }
|
||||
| { readonly status: "unmatched"; readonly declared: readonly string[] } => {
|
||||
try {
|
||||
const value: unknown = JSON.parse(text);
|
||||
@@ -439,26 +480,53 @@ const packageExport = (
|
||||
value: unknown,
|
||||
moduleKind: ResolveArtifactPathInput["moduleKind"],
|
||||
): PackageExportOutcome => {
|
||||
if (typeof value === "string") return packagePathValue(value);
|
||||
if (typeof value !== "object" || value === null || Array.isArray(value))
|
||||
return { status: "invalid" };
|
||||
const root = Reflect.get(value, ".") ?? value;
|
||||
if (typeof root === "string") return packagePathValue(root);
|
||||
if (typeof root !== "object" || root === null || Array.isArray(root))
|
||||
return { status: "invalid" };
|
||||
const root =
|
||||
typeof value === "object" && value !== null && Object.hasOwn(value, ".")
|
||||
? Reflect.get(value, ".")
|
||||
: value;
|
||||
const flattened = exportTargets(root, packageExportConditions(moduleKind));
|
||||
if (flattened.kind === "invalid") return { status: "invalid" };
|
||||
if (flattened.kind === "invalid")
|
||||
return { status: "rejected", limitation: flattened.limitation };
|
||||
const first =
|
||||
flattened.kind === "unmatched" ? undefined : flattened.values[0];
|
||||
return first === undefined
|
||||
? { status: "unmatched", declared: Object.keys(root) }
|
||||
? {
|
||||
status: "unmatched",
|
||||
declared:
|
||||
typeof root === "object" && root !== null ? Object.keys(root) : [],
|
||||
}
|
||||
: { status: "value", value: first };
|
||||
};
|
||||
|
||||
type ExportTargets =
|
||||
| { readonly kind: "targets"; readonly values: readonly string[] }
|
||||
| { readonly kind: "unmatched" }
|
||||
| { readonly kind: "invalid" };
|
||||
| { readonly kind: "invalid"; readonly limitation: string };
|
||||
|
||||
const invalidExportTarget = (
|
||||
value: unknown,
|
||||
reason: string,
|
||||
): ExportTargets => ({
|
||||
kind: "invalid",
|
||||
limitation: `The package exports target ${JSON.stringify(value) ?? String(value)} ${reason}.`,
|
||||
});
|
||||
|
||||
// Node checks raw target segments before URL normalization. Compare encoded
|
||||
// segment names here; full URL decoding follows array target selection.
|
||||
const forbiddenExportSegment = (value: string): string | undefined =>
|
||||
value
|
||||
.slice(2)
|
||||
.split(/[\\/]/u)
|
||||
.find((raw) => {
|
||||
const segment = raw.replace(/%[0-9a-f]{2}/giu, (encoded) =>
|
||||
String.fromCharCode(Number.parseInt(encoded.slice(1), 16)),
|
||||
);
|
||||
return (
|
||||
segment === "." ||
|
||||
segment === ".." ||
|
||||
segment.toLowerCase() === "node_modules"
|
||||
);
|
||||
});
|
||||
|
||||
/**
|
||||
* Resolve a target in Node's declared order. Explicit null blocks an active
|
||||
@@ -470,26 +538,39 @@ const exportTargets = (
|
||||
value: unknown,
|
||||
conditions: ReadonlySet<string>,
|
||||
): ExportTargets => {
|
||||
if (typeof value === "string")
|
||||
return value.startsWith("./")
|
||||
if (typeof value === "string") {
|
||||
if (!value.startsWith("./"))
|
||||
return invalidExportTarget(value, 'must start with "./"');
|
||||
const forbidden = forbiddenExportSegment(value);
|
||||
return forbidden === undefined
|
||||
? { kind: "targets", values: [value] }
|
||||
: { kind: "invalid" };
|
||||
: invalidExportTarget(
|
||||
value,
|
||||
`contains forbidden path segment ${JSON.stringify(forbidden)} before URL normalization`,
|
||||
);
|
||||
}
|
||||
if (value === null) return { kind: "targets", values: [] };
|
||||
if (Array.isArray(value)) {
|
||||
let invalid = false;
|
||||
let invalid: string | null = null;
|
||||
for (const entry of value) {
|
||||
const nested = exportTargets(entry, conditions);
|
||||
if (nested.kind === "invalid") {
|
||||
invalid = true;
|
||||
invalid = nested.limitation;
|
||||
continue;
|
||||
}
|
||||
if (nested.kind === "unmatched") continue;
|
||||
invalid = false;
|
||||
invalid = null;
|
||||
if (nested.values.length > 0) return nested;
|
||||
}
|
||||
return invalid ? { kind: "invalid" } : { kind: "targets", values: [] };
|
||||
return invalid === null
|
||||
? { kind: "targets", values: [] }
|
||||
: { kind: "invalid", limitation: invalid };
|
||||
}
|
||||
if (typeof value !== "object") return { kind: "invalid" };
|
||||
if (typeof value !== "object")
|
||||
return invalidExportTarget(
|
||||
value,
|
||||
"must be a relative string, object, array, or null",
|
||||
);
|
||||
for (const [condition, target] of Object.entries(value)) {
|
||||
if (!conditions.has(condition)) continue;
|
||||
const nested = exportTargets(target, conditions);
|
||||
@@ -516,7 +597,7 @@ const packageExportConditions = (
|
||||
|
||||
type PackageExportOutcome =
|
||||
| { readonly status: "value"; readonly value: string }
|
||||
| { readonly status: "invalid" }
|
||||
| { readonly status: "rejected"; readonly limitation: string }
|
||||
| { readonly status: "unmatched"; readonly declared: readonly string[] };
|
||||
|
||||
const packagePathValue = (
|
||||
|
||||
@@ -1,7 +1,14 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { execFile } from "node:child_process";
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
|
||||
import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js";
|
||||
import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
|
||||
import { analyzeJavaScriptApplication } from "./JavaScriptApplicationService.js";
|
||||
import { javascriptApplicationAnalysisResultSchema } from "../../domain/javascript/javascriptApplicationAnalysis.js";
|
||||
|
||||
const filesFor = (paths: readonly string[]) =>
|
||||
new Map<string, JavaScriptArtifactFile>(
|
||||
@@ -84,3 +91,241 @@ describe("module specifier punctuation", () => {
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe("ESM module URL decoding", () => {
|
||||
it.each([
|
||||
["./plain.mjs", "plain.mjs"],
|
||||
["./space%20name.mjs", "space name.mjs"],
|
||||
["./pr%C3%A9load.mjs", "préload.mjs"],
|
||||
["./name%3F%23.mjs", "name?#.mjs"],
|
||||
["./percent%2520.mjs?cache=1#v2", "percent%20.mjs"],
|
||||
])(
|
||||
"points %s imports to the file loaded by Node",
|
||||
async (specifier, target) => {
|
||||
const root = await createTestTempDirectory("rea-module-url-");
|
||||
const main = join(root, "main.mjs");
|
||||
await writeFile(
|
||||
main,
|
||||
`import value from ${JSON.stringify(specifier)}; console.log(value);`,
|
||||
);
|
||||
await writeFile(
|
||||
join(root, target),
|
||||
`export default ${JSON.stringify(target)};`,
|
||||
);
|
||||
const encoded = specifier.slice(2).split("?", 1)[0]?.split("#", 1)[0];
|
||||
if (encoded !== undefined && encoded !== target)
|
||||
await writeFile(join(root, encoded), 'export default "encoded decoy";');
|
||||
const native = await promisify(execFile)(process.execPath, [main], {
|
||||
timeout: 5_000,
|
||||
});
|
||||
expect(native.stdout.trim()).toBe(target);
|
||||
|
||||
const result = await analyzeJavaScriptApplication({
|
||||
input_path: root,
|
||||
format: "directory",
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
if (!result.ok) throw result.error;
|
||||
const { graph } = javascriptApplicationAnalysisResultSchema.parse(
|
||||
result.value.normalized_result,
|
||||
);
|
||||
const imports = graph.edges.filter(
|
||||
(edge) =>
|
||||
edge.relation === "imports" &&
|
||||
edge.properties.specifier === specifier,
|
||||
);
|
||||
expect(imports.length).toBeGreaterThan(0);
|
||||
for (const edge of imports)
|
||||
expect(edge.properties.resolved_path).toBe(target);
|
||||
},
|
||||
);
|
||||
|
||||
it("preserves CommonJS literal percent names", () => {
|
||||
expect(
|
||||
resolveArtifactPathByContext({
|
||||
declaredPath: "./space%20name.cjs",
|
||||
sourcePath: "app/main.js",
|
||||
context: "module-specifier",
|
||||
moduleKind: "require",
|
||||
files: filesFor(["app/space%20name.cjs", "app/space name.cjs"]),
|
||||
}),
|
||||
).toMatchObject({
|
||||
resolved_path: "app/space%20name.cjs",
|
||||
resolution_status: "resolved",
|
||||
});
|
||||
});
|
||||
|
||||
it.each(["./invalid%.mjs", "./invalid%C3.mjs", "./nul%00.mjs"])(
|
||||
"rejects malformed or NUL URL %s",
|
||||
(declaredPath) => {
|
||||
expect(
|
||||
resolveArtifactPathByContext({
|
||||
declaredPath,
|
||||
sourcePath: "app/main.js",
|
||||
context: "module-specifier",
|
||||
moduleKind: "import",
|
||||
files: filesFor([`app/${declaredPath.slice(2)}`]),
|
||||
}),
|
||||
).toMatchObject({ resolved_path: null, resolution_status: "rejected" });
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
const packageEntryUrlCases = [
|
||||
["exports", "./actual%20file.cjs", "actual file.cjs"],
|
||||
["exports", "./actual.cjs?variant", "actual.cjs"],
|
||||
["exports", "./actual.cjs#variant", "actual.cjs"],
|
||||
["exports", "./actual%23file.cjs", "actual#file.cjs"],
|
||||
["exports", "./actual%3Ffile.cjs", "actual?file.cjs"],
|
||||
["exports", "./actual%252Ffile.cjs", "actual%2Ffile.cjs"],
|
||||
["exports", "./actual.cjs", "actual.cjs"],
|
||||
["main", "./actual%20file.cjs", "actual%20file.cjs"],
|
||||
["main", "./actual?file.cjs", "actual?file.cjs"],
|
||||
["main", "./actual#file.cjs", "actual#file.cjs"],
|
||||
] as const;
|
||||
|
||||
describe("package exports URL paths", () => {
|
||||
it.each(
|
||||
(["import", "require"] as const).flatMap((moduleKind) =>
|
||||
packageEntryUrlCases.map(([field, declaredPath, target]) => ({
|
||||
moduleKind,
|
||||
field,
|
||||
declaredPath,
|
||||
target,
|
||||
})),
|
||||
),
|
||||
)(
|
||||
"matches Node $moduleKind for $field $declaredPath",
|
||||
async ({ moduleKind, field, declaredPath, target }) => {
|
||||
const root = await createTestTempDirectory("rea-package-export-url-");
|
||||
const packageRoot = join(root, "node_modules", "fixture");
|
||||
await mkdir(packageRoot, { recursive: true });
|
||||
await writeFile(
|
||||
join(packageRoot, "package.json"),
|
||||
JSON.stringify({
|
||||
name: "fixture",
|
||||
[field]: declaredPath,
|
||||
}),
|
||||
);
|
||||
await writeFile(
|
||||
join(packageRoot, target),
|
||||
`module.exports=${JSON.stringify(target)};`,
|
||||
);
|
||||
const literal = declaredPath.slice(2).split("?", 1)[0]?.split("#", 1)[0];
|
||||
if (literal !== undefined && literal !== target)
|
||||
await writeFile(
|
||||
join(packageRoot, literal),
|
||||
'module.exports="literal decoy";',
|
||||
);
|
||||
const main = join(
|
||||
root,
|
||||
moduleKind === "import" ? "main.mjs" : "main.cjs",
|
||||
);
|
||||
await writeFile(
|
||||
main,
|
||||
moduleKind === "import"
|
||||
? 'import value from "fixture"; console.log(value);'
|
||||
: 'console.log(require("fixture"));',
|
||||
);
|
||||
const native = await promisify(execFile)(process.execPath, [main], {
|
||||
timeout: 5_000,
|
||||
});
|
||||
expect(native.stdout.trim()).toBe(target);
|
||||
const result = await analyzeJavaScriptApplication({
|
||||
input_path: root,
|
||||
format: "directory",
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
if (!result.ok) throw result.error;
|
||||
const { graph } = javascriptApplicationAnalysisResultSchema.parse(
|
||||
result.value.normalized_result,
|
||||
);
|
||||
const imports = graph.edges.filter(
|
||||
(edge) =>
|
||||
edge.relation === "imports" &&
|
||||
edge.properties.specifier === "fixture",
|
||||
);
|
||||
expect(imports.length).toBeGreaterThan(0);
|
||||
for (const edge of imports)
|
||||
expect(edge.properties.resolved_path).toBe(
|
||||
`node_modules/fixture/${target}`,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
it.each(
|
||||
(["import", "require"] as const).flatMap((moduleKind) =>
|
||||
[
|
||||
"./actual%file.cjs",
|
||||
"./actual%E0%A4file.cjs",
|
||||
"./actual%00file.cjs",
|
||||
"./actual%2Ffile.cjs",
|
||||
"./actual%5Cfile.cjs",
|
||||
"./actual%2Efile.cjs",
|
||||
"./../../../../escape.cjs",
|
||||
].map((declaredPath) => ({ moduleKind, declaredPath })),
|
||||
),
|
||||
)(
|
||||
"rejects $moduleKind URL $declaredPath without borrowing a literal decoy",
|
||||
({ moduleKind, declaredPath }) => {
|
||||
const packagePath = "app/node_modules/fixture/package.json";
|
||||
const files = filesFor([
|
||||
packagePath,
|
||||
`app/node_modules/fixture/${declaredPath.slice(2)}`,
|
||||
]);
|
||||
const metadata = files.get(packagePath);
|
||||
if (metadata === undefined) throw new Error("Missing fixture metadata");
|
||||
files.set(packagePath, {
|
||||
...metadata,
|
||||
kind: "package-json",
|
||||
text: {
|
||||
included: true,
|
||||
value: JSON.stringify({ exports: declaredPath }),
|
||||
},
|
||||
});
|
||||
expect(
|
||||
resolveArtifactPathByContext({
|
||||
declaredPath: "fixture",
|
||||
sourcePath: "app/main.js",
|
||||
context: "module-specifier",
|
||||
moduleKind,
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({ resolved_path: null, resolution_status: "rejected" });
|
||||
},
|
||||
);
|
||||
|
||||
it.each(["import", "require"] as const)(
|
||||
"keeps %s exports inside their inventoried container",
|
||||
(moduleKind) => {
|
||||
const packagePath = "app/node_modules/fixture/package.json";
|
||||
const target = "app/node_modules/fixture/actual file.cjs";
|
||||
const files = filesFor([packagePath, target]);
|
||||
const metadata = files.get(packagePath);
|
||||
const crossContainer = files.get(target);
|
||||
if (metadata === undefined || crossContainer === undefined)
|
||||
throw new Error("Missing fixture files");
|
||||
files.set(packagePath, {
|
||||
...metadata,
|
||||
kind: "package-json",
|
||||
text: {
|
||||
included: true,
|
||||
value: '{"exports":"./actual%20file.cjs"}',
|
||||
},
|
||||
});
|
||||
files.set(target, {
|
||||
...crossContainer,
|
||||
container_sha256: "c".repeat(64),
|
||||
});
|
||||
expect(
|
||||
resolveArtifactPathByContext({
|
||||
declaredPath: "fixture",
|
||||
sourcePath: "app/main.js",
|
||||
context: "module-specifier",
|
||||
moduleKind,
|
||||
files,
|
||||
}),
|
||||
).toMatchObject({ resolved_path: null, resolution_status: "not-found" });
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
import { z } from "incur";
|
||||
|
||||
import { runProviderAnalysis } from "../composition/directAnalysis.js";
|
||||
import { CLI_COMMANDS } from "../cliCommandNames.js";
|
||||
import { parseCliJsonInput } from "../cliJsonInput.js";
|
||||
import { logCliCommand } from "../cliLogging.js";
|
||||
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
|
||||
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
import { projectInputIssues } from "../domain/inputIssueProjection.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { nativeCallObservationInputSchema } from "../domain/native/nativeCallObservation.js";
|
||||
import type { Logger } from "../logger.js";
|
||||
import type { CliInstance } from "./types.js";
|
||||
|
||||
const OPERATION = "observe_native_calls";
|
||||
|
||||
/** `observe-native-calls <path> <input-json>`: the MCP input object as JSON. */
|
||||
export const registerNativeCallCommands = (
|
||||
cli: CliInstance,
|
||||
logger: Logger,
|
||||
): void => {
|
||||
cli.command(CLI_COMMANDS.observeNativeCalls, {
|
||||
description:
|
||||
"Launch a Mach-O under LLDB and record entries into selected functions or Objective-C methods",
|
||||
args: z.object({
|
||||
path: z.string().describe("Mach-O or app path"),
|
||||
inputJson: z
|
||||
.string()
|
||||
.describe(
|
||||
"Inline JSON or a JSON file path: breakpoints, arguments, environment, duration_ms, max_events, argument_registers, backtrace_frames",
|
||||
),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.observeNativeCalls, async () => {
|
||||
const input = await parseCliJsonInput(args.inputJson, OPERATION);
|
||||
if (!input.ok) return input.error;
|
||||
const parsed = nativeCallObservationInputSchema.safeParse(input.value);
|
||||
if (!parsed.success)
|
||||
return {
|
||||
error: "Analysis failed",
|
||||
...projectAnalysisError(
|
||||
new AnalysisInputError(
|
||||
OPERATION,
|
||||
undefined,
|
||||
projectInputIssues(parsed.error.issues, input.value),
|
||||
),
|
||||
),
|
||||
};
|
||||
return runProviderAnalysis(
|
||||
args.path,
|
||||
OPERATION,
|
||||
z.record(z.string(), jsonValueSchema).parse(parsed.data),
|
||||
logger,
|
||||
);
|
||||
}),
|
||||
});
|
||||
};
|
||||
@@ -20,6 +20,7 @@ import { swiftSymbolsSchema } from "../contracts/native/nativeToolContracts.js";
|
||||
import type { Logger } from "../logger.js";
|
||||
import { isReferenceSourceImportCliFailure } from "./referenceSourceImportStatus.js";
|
||||
import type { CliInstance } from "./types.js";
|
||||
import { registerNativeCallCommands } from "./nativeCallCommands.js";
|
||||
|
||||
export const registerUtilityCommands = (
|
||||
cli: CliInstance,
|
||||
@@ -28,6 +29,7 @@ export const registerUtilityCommands = (
|
||||
): void => {
|
||||
registerCapabilityCommands(cli, logger);
|
||||
registerNativeCommands(cli, logger);
|
||||
registerNativeCallCommands(cli, logger);
|
||||
for (const [command, operation] of [
|
||||
[CLI_COMMANDS.observeNativeUi, "observe_native_ui"],
|
||||
[CLI_COMMANDS.captureNativeUiScenario, "capture_native_ui_scenario"],
|
||||
|
||||
@@ -51,6 +51,7 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
importManagedReconstruction: "import-managed-reconstruction",
|
||||
projectManagedApplicationGraph: "project-managed-application-graph",
|
||||
observeNativeUi: "observe-native-ui",
|
||||
observeNativeCalls: "observe-native-calls",
|
||||
captureNativeUiScenario: "capture-native-ui-scenario",
|
||||
inspectMacho: "inspect-macho",
|
||||
inspectSignature: "inspect-signature",
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { z } from "zod";
|
||||
import { nativeCallObservationInputSchema } from "../../domain/native/nativeCallObservation.js";
|
||||
import {
|
||||
nativeUiObservationInputSchema,
|
||||
nativeUiScenarioInputSchema,
|
||||
@@ -22,6 +23,19 @@ const examples: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
|
||||
steps: [{ kind: "wait", milliseconds: 100 }],
|
||||
},
|
||||
demangle_swift: { symbols: ["$s4Test3fooyyF"] },
|
||||
observe_native_calls: {
|
||||
breakpoints: [
|
||||
{
|
||||
kind: "objc-method",
|
||||
class_name: "NSURLSession",
|
||||
selector: "dataTaskWithRequest:completionHandler:",
|
||||
},
|
||||
{ kind: "function", name: "open", module: "libsystem_kernel.dylib" },
|
||||
],
|
||||
arguments: ["--help"],
|
||||
duration_ms: 5000,
|
||||
backtrace_frames: 4,
|
||||
},
|
||||
};
|
||||
|
||||
const native = <Name extends string, Schema extends z.ZodObject>(
|
||||
@@ -71,6 +85,11 @@ export const NATIVE_TOOL_CONTRACTS = [
|
||||
"Run selected-element press, increment/decrement scroll, AXValue text entry and bounded wait steps in one exact native app window. Returns ordered before/after captures and action/capture failures. Actions can change app data, network activity and persistent state; application state is left as-is and restoration is not attempted.",
|
||||
nativeUiScenarioInputSchema,
|
||||
),
|
||||
native(
|
||||
"observe_native_calls",
|
||||
"Launch the active Mach-O as an owned process under LLDB and record each entry into caller-selected functions or Objective-C methods: thread, module, symbol, load and file address, raw argument registers, selector, receiver class and optional caller frames. Every hit auto-continues. No expression is evaluated and no other process is attached. The process is killed when max_events or duration_ms is reached; exit status, captured stdout/stderr, unresolved breakpoints and limitations are returned inline. The process runs with the current user's permissions and may change files, show UI or use the network. A hardened-runtime target needs the get-task-allow entitlement.",
|
||||
nativeCallObservationInputSchema,
|
||||
),
|
||||
native(
|
||||
"inspect_macho",
|
||||
"Inspect Mach-O slices, load commands, imports, exports, dependencies, build metadata, segments, sections, permissions, and exact command provenance without launching Hopper.",
|
||||
|
||||
@@ -180,6 +180,15 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
mayDiscardData: true,
|
||||
idempotent: false,
|
||||
}),
|
||||
// The owned process can change files, show UI and use the network.
|
||||
observe_native_calls: effects({
|
||||
mutatesSession: true,
|
||||
writesFilesystem: true,
|
||||
launchesProcess: true,
|
||||
accessesNetwork: true,
|
||||
changesUiState: true,
|
||||
idempotent: false,
|
||||
}),
|
||||
inspect_macho: nativeEvidence,
|
||||
inspect_signature: nativeEvidence,
|
||||
inspect_plist: nativeEvidence,
|
||||
|
||||
@@ -4,6 +4,7 @@ import { nativeLoadImageSchema } from "../domain/native/nativeLoadImage.js";
|
||||
import { nativeUiResultSchema } from "../domain/native/nativeUiObservation.js";
|
||||
import { nativeValueTraceSchema } from "../domain/native/nativeValueTrace.js";
|
||||
import { nativeDataTypeSchema } from "../domain/native/nativeDataType.js";
|
||||
import { nativeCallObservationResultSchema } from "../domain/native/nativeCallObservation.js";
|
||||
import {
|
||||
nativeInstructionSchema,
|
||||
nativeCallTargetsSchema,
|
||||
@@ -322,6 +323,7 @@ export const enhancedOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
export const nativeOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
observe_native_ui: resultOf(nativeUiResultSchema),
|
||||
capture_native_ui_scenario: resultOf(nativeUiResultSchema),
|
||||
observe_native_calls: resultOf(nativeCallObservationResultSchema),
|
||||
inspect_macho: resultOf(inspectMachoSchema),
|
||||
inspect_signature: resultOf(inspectSignatureSchema),
|
||||
inspect_plist: resultOf(inspectPlistSchema),
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { htmlArtifactReferences } from "./htmlArtifactReferences.js";
|
||||
|
||||
it.each([
|
||||
['<script data-src="decoy.js"></script>', []],
|
||||
['<script x:src="decoy.js"></script>', []],
|
||||
[`<script title='src="decoy.js"'></script>`, []],
|
||||
["<script src=actual.js></script>", ["actual.js"]],
|
||||
['<script title=">" src="actual.js"></script>', ["actual.js"]],
|
||||
['<SCRIPT SRC="actual.js"></SCRIPT>', ["actual.js"]],
|
||||
["<script src='actual.js'></script>", ["actual.js"]],
|
||||
['<script data-src="decoy.js" src="actual.js"></script>', ["actual.js"]],
|
||||
['<script src="actual.js" src="decoy.js"></script>', ["actual.js"]],
|
||||
['<script src="" src="decoy.js"></script>', []],
|
||||
['<script src="actual.js"></script>', ["actual.js"]],
|
||||
['<!-- <script src="decoy.js"></script> -->', []],
|
||||
['<textarea><script src="decoy.js"></script></textarea>', []],
|
||||
['<style><script src="decoy.js"></script></style>', []],
|
||||
[`<script>const text = '<script src="decoy.js">';</script>`, []],
|
||||
[
|
||||
'<template><base href="decoy/"><script src="decoy.js"></script></template>',
|
||||
[],
|
||||
],
|
||||
['<svg><script src="decoy.js"></script></svg>', []],
|
||||
[
|
||||
'<svg><foreignObject><script src="actual.js"></script></foreignObject></svg>',
|
||||
["actual.js"],
|
||||
],
|
||||
// The existing extraction contract does not classify script MIME types.
|
||||
['<script type="application/json" src="actual.js"></script>', ["actual.js"]],
|
||||
])("extracts document references from %s", (text, expected) => {
|
||||
expect(
|
||||
htmlArtifactReferences(text).scripts.map(({ scriptPath }) => scriptPath),
|
||||
).toEqual(expected);
|
||||
});
|
||||
|
||||
it("retains exact opening-tag offsets rather than the script body", () => {
|
||||
const opening = '<script\n title=">" src=actual.js>';
|
||||
const prefix = "<!doctype html>\n\n";
|
||||
const text = `${prefix}${opening}ignored body</script>`;
|
||||
expect(htmlArtifactReferences(text)).toEqual({
|
||||
baseHref: null,
|
||||
scripts: [
|
||||
{
|
||||
scriptPath: "actual.js",
|
||||
startOffset: prefix.length,
|
||||
endOffset: prefix.length + opening.length,
|
||||
},
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
['<base data-href="decoy/"><base href=actual/>', "actual/"],
|
||||
['<base href="actual/" href="decoy/"><base href="later/">', "actual/"],
|
||||
['<base href=""><base href="decoy/">', ""],
|
||||
['<template><base href="decoy/"></template><base href="actual/">', "actual/"],
|
||||
['<!-- <base href="decoy/"> --><base title=">" href="actual/">', "actual/"],
|
||||
])("selects the first real base href from %s", (text, expected) => {
|
||||
expect(htmlArtifactReferences(text).baseHref).toBe(expected);
|
||||
});
|
||||
|
||||
it("traverses deep valid document content without recursive stack growth", () => {
|
||||
const depth = 12_000;
|
||||
const text = `${"<div>".repeat(depth)}<script src=actual.js></script>${"</div>".repeat(depth)}`;
|
||||
expect(
|
||||
htmlArtifactReferences(text).scripts.map(({ scriptPath }) => scriptPath),
|
||||
).toEqual(["actual.js"]);
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
import {
|
||||
defaultTreeAdapter,
|
||||
parse,
|
||||
type DefaultTreeAdapterTypes,
|
||||
} from "parse5";
|
||||
|
||||
interface HtmlScriptReference {
|
||||
readonly scriptPath: string;
|
||||
readonly startOffset: number;
|
||||
readonly endOffset: number;
|
||||
}
|
||||
|
||||
/** Extract inert HTML script references and the first document base href. */
|
||||
export const htmlArtifactReferences = (
|
||||
text: string,
|
||||
): {
|
||||
readonly baseHref: string | null;
|
||||
readonly scripts: readonly HtmlScriptReference[];
|
||||
} => {
|
||||
const pending: DefaultTreeAdapterTypes.Node[] = [
|
||||
parse(text, { sourceCodeLocationInfo: true }),
|
||||
];
|
||||
const scripts: HtmlScriptReference[] = [];
|
||||
let baseHref: string | null = null;
|
||||
while (pending.length > 0) {
|
||||
const node = pending.pop();
|
||||
if (node === undefined) continue;
|
||||
if (
|
||||
defaultTreeAdapter.isElementNode(node) &&
|
||||
node.namespaceURI === "http://www.w3.org/1999/xhtml"
|
||||
) {
|
||||
if (node.tagName === "base" && baseHref === null) {
|
||||
const href = node.attrs.find(({ name }) => name === "href");
|
||||
if (href !== undefined) baseHref = href.value;
|
||||
}
|
||||
if (node.tagName === "script") {
|
||||
const src = node.attrs.find(({ name }) => name === "src");
|
||||
const location = node.sourceCodeLocation?.startTag;
|
||||
if (src !== undefined && src.value !== "" && location !== undefined) {
|
||||
scripts.push({
|
||||
scriptPath: src.value,
|
||||
startOffset: location.startOffset,
|
||||
endOffset: location.endOffset,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
// Template content belongs to a separate inert document fragment. Only
|
||||
// traverse the actual document children, without recursion on deep input.
|
||||
if ("childNodes" in node) {
|
||||
for (const child of node.childNodes.toReversed()) pending.push(child);
|
||||
}
|
||||
}
|
||||
return { baseHref, scripts };
|
||||
};
|
||||
@@ -0,0 +1,198 @@
|
||||
import { z } from "zod";
|
||||
|
||||
const hexSchema = z.string().regex(/^0x[0-9a-f]+$/u);
|
||||
/** Objective-C class names and selectors never contain spaces or brackets. */
|
||||
const objcName = z
|
||||
.string()
|
||||
.min(1)
|
||||
.regex(/^[^\s[\]]+$/u, "Use the bare name without spaces or brackets");
|
||||
|
||||
const functionBreakpoint = {
|
||||
kind: z.literal("function"),
|
||||
name: z
|
||||
.string()
|
||||
.min(1)
|
||||
.describe(
|
||||
"Exact symbol name, such as `open`, a C++ or mangled Swift symbol, or `-[NSString length]`.",
|
||||
),
|
||||
};
|
||||
|
||||
const objcMethodBreakpoint = {
|
||||
kind: z.literal("objc-method"),
|
||||
selector: objcName.describe(
|
||||
"Selector such as `dataTaskWithRequest:completionHandler:`.",
|
||||
),
|
||||
};
|
||||
|
||||
/** One function or Objective-C method whose entries are observed. */
|
||||
export const nativeCallBreakpointSchema = z.discriminatedUnion("kind", [
|
||||
z.strictObject({
|
||||
...functionBreakpoint,
|
||||
module: z
|
||||
.string()
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe(
|
||||
"Image file name that defines the symbol, such as `libsystem_kernel.dylib`; omit to match every image.",
|
||||
),
|
||||
}),
|
||||
z.strictObject({
|
||||
...objcMethodBreakpoint,
|
||||
class_name: objcName
|
||||
.optional()
|
||||
.describe("Implementing class; omit to match every class."),
|
||||
method_type: z.enum(["instance", "class", "any"]).default("any"),
|
||||
}),
|
||||
]);
|
||||
|
||||
/**
|
||||
* Launch the active Mach-O as an owned process under LLDB and observe calls.
|
||||
* Duration and event bounds keep runtime observation finite.
|
||||
*/
|
||||
export const nativeCallObservationInputSchema = z.strictObject({
|
||||
breakpoints: z.array(nativeCallBreakpointSchema).min(1),
|
||||
arguments: z.array(z.string()).default([]),
|
||||
environment: z
|
||||
.record(
|
||||
z
|
||||
.string()
|
||||
.min(1)
|
||||
.regex(/^[^=\0]+$/u, "Environment names cannot contain '=' or NUL"),
|
||||
z.string().regex(/^[^\0]*$/u, "Environment values cannot contain NUL"),
|
||||
)
|
||||
.default({})
|
||||
.describe("Overrides on top of the environment REA runs with."),
|
||||
working_directory: z.string().min(1).optional(),
|
||||
duration_ms: z
|
||||
.number()
|
||||
.int()
|
||||
.min(100)
|
||||
.max(600_000)
|
||||
.default(10_000)
|
||||
.describe(
|
||||
"Observation window; the process is killed if it is still running.",
|
||||
),
|
||||
max_events: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(100_000)
|
||||
.default(1_000)
|
||||
.describe(
|
||||
"Stop observing and kill the process after this many recorded entries.",
|
||||
),
|
||||
argument_registers: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.max(8)
|
||||
.default(4)
|
||||
.describe(
|
||||
"Integer argument registers to record per entry (arm64 has 8, x86_64 has 6).",
|
||||
),
|
||||
backtrace_frames: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.max(64)
|
||||
.default(0)
|
||||
.describe("Caller frames to record per entry."),
|
||||
});
|
||||
|
||||
export type NativeCallObservationInput = z.infer<
|
||||
typeof nativeCallObservationInputSchema
|
||||
>;
|
||||
|
||||
/** A code address with the image and symbol LLDB attributes to it. */
|
||||
export const nativeCodeLocationSchema = z.strictObject({
|
||||
load_address: hexSchema,
|
||||
file_address: hexSchema.nullable(),
|
||||
module: z.string().nullable(),
|
||||
module_path: z.string().nullable(),
|
||||
symbol: z.string().nullable(),
|
||||
});
|
||||
|
||||
/** One observed entry into a requested function or method. */
|
||||
export const nativeCallEventSchema = z.strictObject({
|
||||
sequence: z.number().int().nonnegative(),
|
||||
elapsed_ms: z.number().nonnegative(),
|
||||
thread_id: z.number().int().nonnegative(),
|
||||
breakpoint_index: z.number().int().nonnegative(),
|
||||
...nativeCodeLocationSchema.shape,
|
||||
/** Dynamic class of an instance-method receiver, read without running code. */
|
||||
receiver_class: z.string().nullable(),
|
||||
/** Selector string read from the `_cmd` register of an Objective-C method. */
|
||||
selector: z.string().nullable(),
|
||||
registers: z.array(z.strictObject({ name: z.string(), value: hexSchema })),
|
||||
backtrace: z.array(nativeCodeLocationSchema),
|
||||
});
|
||||
|
||||
const capturedOutputSchema = z.strictObject({
|
||||
text: z.string(),
|
||||
bytes: z.number().int().nonnegative(),
|
||||
truncated: z.boolean(),
|
||||
});
|
||||
|
||||
/** Observed calls, the process lifecycle, and breakpoint resolution. */
|
||||
export const nativeCallObservationResultSchema = z.strictObject({
|
||||
target: z.strictObject({
|
||||
path: z.string(),
|
||||
sha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
||||
architecture: z.string(),
|
||||
arguments: z.array(z.string()),
|
||||
working_directory: z.string().nullable(),
|
||||
}),
|
||||
debugger: z.strictObject({
|
||||
path: z.string(),
|
||||
sha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
||||
version: z.string().nullable(),
|
||||
}),
|
||||
process: z.strictObject({
|
||||
pid: z.number().int().positive(),
|
||||
outcome: z.enum([
|
||||
"exited",
|
||||
"duration-elapsed",
|
||||
"event-limit",
|
||||
"stop-limit",
|
||||
]),
|
||||
exit_status: z.number().int().nullable(),
|
||||
exit_description: z.string().nullable(),
|
||||
/** REA confirmed the process is gone when observation ended. */
|
||||
terminated: z.boolean(),
|
||||
elapsed_ms: z.number().nonnegative(),
|
||||
stdout: capturedOutputSchema,
|
||||
stderr: capturedOutputSchema,
|
||||
/** Signal and exception stops LLDB reported; the process continued past each. */
|
||||
other_stops: z.array(z.string()),
|
||||
}),
|
||||
breakpoints: z.array(
|
||||
z.strictObject({
|
||||
index: z.number().int().nonnegative(),
|
||||
request: z.discriminatedUnion("kind", [
|
||||
z.strictObject({
|
||||
...functionBreakpoint,
|
||||
module: z.string().nullable(),
|
||||
}),
|
||||
z.strictObject({
|
||||
...objcMethodBreakpoint,
|
||||
class_name: z.string().nullable(),
|
||||
method_type: z.enum(["instance", "class", "any"]),
|
||||
}),
|
||||
]),
|
||||
location_count: z.number().int().nonnegative(),
|
||||
locations: z.array(nativeCodeLocationSchema),
|
||||
}),
|
||||
),
|
||||
events: z.array(nativeCallEventSchema),
|
||||
coverage: z.strictObject({
|
||||
status: z.enum(["complete", "partial"]),
|
||||
event_limit_reached: z.boolean(),
|
||||
/** Requests that matched no code in any image loaded while observing. */
|
||||
unresolved_breakpoints: z.array(z.number().int().nonnegative()),
|
||||
}),
|
||||
limitations: z.array(z.string()),
|
||||
});
|
||||
|
||||
export type NativeCallObservationResult = z.infer<
|
||||
typeof nativeCallObservationResultSchema
|
||||
>;
|
||||
@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
|
||||
serverSdkVersion: "2.3.1",
|
||||
clientSdkVersion: "2.3.1",
|
||||
coreSdkVersion: "2.3.1",
|
||||
skillVersion: "29",
|
||||
skillVersion: "30",
|
||||
} as const;
|
||||
|
||||
@@ -124,7 +124,8 @@ const ALLOWED_TOOLS = new Set([
|
||||
"vtool",
|
||||
]);
|
||||
|
||||
const resolveXcrunTool = async (
|
||||
/** Locate an Xcode tool through `xcrun --find` and pin its executable digest. */
|
||||
export const resolveXcrunTool = async (
|
||||
tool: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<ResolvedTool, NativeCommandFailure>> => {
|
||||
|
||||
@@ -0,0 +1,400 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { open, readFile, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisTimeoutError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import {
|
||||
nativeCallEventSchema,
|
||||
nativeCodeLocationSchema,
|
||||
type NativeCallObservationInput,
|
||||
} from "../domain/native/nativeCallObservation.js";
|
||||
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import { safeParseJson } from "../domain/safeJson.js";
|
||||
import { execFileOutput } from "../process/ExecFileOutput.js";
|
||||
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
|
||||
import { resolveXcrunTool, type ResolvedTool } from "./CommandRunner.js";
|
||||
|
||||
const OPERATION = "observe_native_calls";
|
||||
const PROVIDER = "native-macos";
|
||||
/** Captured target output kept per stream; the rest is counted, not stored. */
|
||||
const MAX_OUTPUT_BYTES = 1024 * 1024;
|
||||
/** LLDB startup, symbol loading and teardown beyond the observation window. */
|
||||
const DEADLINE_GRACE_MS = 60_000;
|
||||
const DIAGNOSTIC_BYTES = 16 * 1024;
|
||||
|
||||
const BRIDGE = fileURLToPath(
|
||||
new URL("../../bridge/native/rea_lldb_tracer.py", import.meta.url),
|
||||
);
|
||||
|
||||
/** JSON the LLDB bridge writes after a completed run. */
|
||||
const tracedSchema = z.strictObject({
|
||||
status: z.literal("traced"),
|
||||
version: z.string(),
|
||||
pid: z.number().int().positive(),
|
||||
outcome: z.enum(["exited", "duration-elapsed", "event-limit", "stop-limit"]),
|
||||
exit_status: z.number().int().nullable(),
|
||||
exit_description: z.string().nullable(),
|
||||
killed: z.boolean(),
|
||||
terminated: z.boolean(),
|
||||
elapsed_ms: z.number().nonnegative(),
|
||||
breakpoints: z.array(
|
||||
z.strictObject({
|
||||
index: z.number().int().nonnegative(),
|
||||
location_count: z.number().int().nonnegative(),
|
||||
locations: z.array(nativeCodeLocationSchema),
|
||||
}),
|
||||
),
|
||||
events: z.array(nativeCallEventSchema),
|
||||
other_stops: z.array(z.string()),
|
||||
});
|
||||
|
||||
const tracerOutputSchema = z.discriminatedUnion("status", [
|
||||
tracedSchema,
|
||||
z.strictObject({
|
||||
status: z.enum(["target-error", "launch-error", "tracer-error"]),
|
||||
error: z.string().nullable(),
|
||||
}),
|
||||
]);
|
||||
|
||||
/** Bounded text of one target output stream. */
|
||||
export interface CapturedOutput {
|
||||
readonly text: string;
|
||||
readonly bytes: number;
|
||||
readonly truncated: boolean;
|
||||
}
|
||||
|
||||
/** One completed LLDB observation, before projection into the result contract. */
|
||||
export interface NativeCallTrace {
|
||||
readonly debugger: ResolvedTool & { readonly version: string | null };
|
||||
readonly run: z.infer<typeof tracedSchema>;
|
||||
readonly stdout: CapturedOutput;
|
||||
readonly stderr: CapturedOutput;
|
||||
/** REA confirmed the traced process no longer exists. */
|
||||
readonly terminated: boolean;
|
||||
}
|
||||
|
||||
/** Launch one owned process under a debugger and record calls. */
|
||||
export interface NativeCallTracer {
|
||||
trace(
|
||||
request: {
|
||||
readonly executable: string;
|
||||
readonly architecture: string;
|
||||
readonly input: NativeCallObservationInput;
|
||||
},
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<NativeCallTrace, AnalysisError>>;
|
||||
}
|
||||
|
||||
/** Remediation for a target LLDB may not debug. */
|
||||
const ATTACH_REMEDIATION =
|
||||
"Allow debugging for this user (Developer Tools access: `DevToolsSecurity -enable`, or membership in the _developer group). A hardened-runtime target is debuggable only with the com.apple.security.get-task-allow entitlement; see inspect_signature's debugger-attach facet.";
|
||||
|
||||
/** Production tracer: `lldb --batch` running the REA LLDB bridge. */
|
||||
export class LldbCallTracer implements NativeCallTracer {
|
||||
async trace(
|
||||
request: Parameters<NativeCallTracer["trace"]>[0],
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<NativeCallTrace, AnalysisError>> {
|
||||
const lldb = await resolveXcrunTool("lldb", signal);
|
||||
if (!lldb.ok)
|
||||
return err(
|
||||
lldb.error.reason === "cancelled"
|
||||
? new AnalysisCancelledError(OPERATION)
|
||||
: new AnalysisCapabilityUnavailableError(
|
||||
PROVIDER,
|
||||
OPERATION,
|
||||
"LLDB from Xcode or the Command Line Tools is not available",
|
||||
),
|
||||
);
|
||||
const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });
|
||||
try {
|
||||
return await this.#run(lldb.value, root.path, request, signal);
|
||||
} finally {
|
||||
await root.close();
|
||||
}
|
||||
}
|
||||
|
||||
async #run(
|
||||
lldb: ResolvedTool,
|
||||
directory: string,
|
||||
request: Parameters<NativeCallTracer["trace"]>[0],
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<NativeCallTrace, AnalysisError>> {
|
||||
const paths = {
|
||||
config: join(directory, "config.json"),
|
||||
result: join(directory, "result.json"),
|
||||
pid: join(directory, "pid"),
|
||||
stdout: join(directory, "stdout"),
|
||||
stderr: join(directory, "stderr"),
|
||||
};
|
||||
const { input } = request;
|
||||
await writeFile(
|
||||
paths.config,
|
||||
JSON.stringify({
|
||||
executable: request.executable,
|
||||
architecture: request.architecture,
|
||||
arguments: input.arguments,
|
||||
environment: input.environment,
|
||||
working_directory: input.working_directory ?? null,
|
||||
breakpoints: input.breakpoints.map((breakpoint) =>
|
||||
breakpoint.kind === "function"
|
||||
? { ...breakpoint, module: breakpoint.module ?? null }
|
||||
: { ...breakpoint, class_name: breakpoint.class_name ?? null },
|
||||
),
|
||||
duration_ms: input.duration_ms,
|
||||
max_events: input.max_events,
|
||||
argument_registers: input.argument_registers,
|
||||
backtrace_frames: input.backtrace_frames,
|
||||
stdout_path: paths.stdout,
|
||||
stderr_path: paths.stderr,
|
||||
result_path: paths.result,
|
||||
pid_path: paths.pid,
|
||||
}),
|
||||
{ mode: 0o600 },
|
||||
);
|
||||
const exited = await runLldb(
|
||||
lldb.path,
|
||||
[
|
||||
"--batch",
|
||||
"--no-lldbinit",
|
||||
"--no-use-colors",
|
||||
"-o",
|
||||
`command script import ${quote(BRIDGE)}`,
|
||||
"-o",
|
||||
`rea_trace ${paths.config}`,
|
||||
],
|
||||
{
|
||||
deadlineMs: input.duration_ms + DEADLINE_GRACE_MS,
|
||||
...(signal === undefined ? {} : { signal }),
|
||||
},
|
||||
);
|
||||
const terminated = await ensureTerminated(paths.pid, request.executable);
|
||||
if (exited.kind === "cancelled")
|
||||
return err(new AnalysisCancelledError(OPERATION));
|
||||
if (exited.kind === "timeout")
|
||||
return err(
|
||||
new AnalysisTimeoutError(
|
||||
OPERATION,
|
||||
input.duration_ms + DEADLINE_GRACE_MS,
|
||||
),
|
||||
);
|
||||
const output = await readTracerOutput(paths.result);
|
||||
if (output === undefined)
|
||||
return err(
|
||||
new ProviderAdapterError(PROVIDER, OPERATION, {
|
||||
diagnostics: {
|
||||
reason: "LLDB exited without a tracer result",
|
||||
exit_code: exited.exitCode,
|
||||
lldb_output: exited.output,
|
||||
},
|
||||
}),
|
||||
);
|
||||
if (output.status !== "traced") return err(tracerFailure(output));
|
||||
return ok({
|
||||
debugger: { ...lldb, version: output.version },
|
||||
run: output,
|
||||
stdout: await capturedOutput(paths.stdout),
|
||||
stderr: await capturedOutput(paths.stderr),
|
||||
terminated,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/** LLDB command arguments are quoted; the bridge path is REA's own install path. */
|
||||
const quote = (value: string): string =>
|
||||
`"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
|
||||
|
||||
const tracerFailure = (output: {
|
||||
readonly status: "target-error" | "launch-error" | "tracer-error";
|
||||
readonly error: string | null;
|
||||
}): AnalysisError => {
|
||||
const message = output.error ?? "no LLDB error text";
|
||||
if (output.status === "tracer-error")
|
||||
return new ProviderAdapterError(PROVIDER, OPERATION, {
|
||||
diagnostics: { reason: `LLDB bridge failed: ${message}` },
|
||||
});
|
||||
if (output.status === "target-error")
|
||||
return new AnalysisCapabilityUnavailableError(
|
||||
PROVIDER,
|
||||
OPERATION,
|
||||
`lldb-target-unloadable: ${message}`,
|
||||
);
|
||||
// debugserver reports denied task access as an attach failure.
|
||||
return /attach|not allowed|permission|denied|debugserver/iu.test(message)
|
||||
? new AnalysisCapabilityUnavailableError(
|
||||
PROVIDER,
|
||||
OPERATION,
|
||||
`debugger-attach-denied: ${message}`,
|
||||
{ userMessage: ATTACH_REMEDIATION },
|
||||
)
|
||||
: new AnalysisCapabilityUnavailableError(
|
||||
PROVIDER,
|
||||
OPERATION,
|
||||
`launch-failed: ${message}`,
|
||||
);
|
||||
};
|
||||
|
||||
const readTracerOutput = async (
|
||||
path: string,
|
||||
): Promise<z.infer<typeof tracerOutputSchema> | undefined> => {
|
||||
let text: string;
|
||||
try {
|
||||
text = await readFile(path, "utf8");
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
const parsed = safeParseJson(text);
|
||||
if (!parsed.ok) return undefined;
|
||||
const output = tracerOutputSchema.safeParse(parsed.value);
|
||||
return output.success ? output.data : undefined;
|
||||
};
|
||||
|
||||
const capturedOutput = async (path: string): Promise<CapturedOutput> => {
|
||||
let handle;
|
||||
try {
|
||||
handle = await open(path, "r");
|
||||
} catch {
|
||||
return { text: "", bytes: 0, truncated: false };
|
||||
}
|
||||
try {
|
||||
const { size } = await handle.stat();
|
||||
const buffer = Buffer.alloc(Math.min(size, MAX_OUTPUT_BYTES));
|
||||
const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
|
||||
return {
|
||||
text: buffer.subarray(0, bytesRead).toString("utf8"),
|
||||
bytes: size,
|
||||
truncated: size > MAX_OUTPUT_BYTES,
|
||||
};
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
};
|
||||
|
||||
type LldbExit =
|
||||
| {
|
||||
readonly kind: "exited";
|
||||
readonly exitCode: number | null;
|
||||
readonly output: string;
|
||||
}
|
||||
| { readonly kind: "cancelled" }
|
||||
| { readonly kind: "timeout" };
|
||||
|
||||
/** Run LLDB in its own process group so cancellation can stop it and debugserver. */
|
||||
const runLldb = (
|
||||
executable: string,
|
||||
arguments_: readonly string[],
|
||||
options: { readonly signal?: AbortSignal; readonly deadlineMs: number },
|
||||
): Promise<LldbExit> =>
|
||||
new Promise((resolve) => {
|
||||
if (options.signal?.aborted === true) {
|
||||
resolve({ kind: "cancelled" });
|
||||
return;
|
||||
}
|
||||
const child = spawn(executable, [...arguments_], {
|
||||
shell: false,
|
||||
detached: true,
|
||||
stdio: ["ignore", "pipe", "pipe"],
|
||||
});
|
||||
let output = "";
|
||||
let stopped: "cancelled" | "timeout" | undefined;
|
||||
const keep = (chunk: Buffer): void => {
|
||||
output = (output + chunk.toString("utf8")).slice(-DIAGNOSTIC_BYTES);
|
||||
};
|
||||
child.stdout.on("data", keep);
|
||||
child.stderr.on("data", keep);
|
||||
const kill = (reason: "cancelled" | "timeout"): void => {
|
||||
stopped ??= reason;
|
||||
if (child.pid !== undefined)
|
||||
try {
|
||||
process.kill(-child.pid, "SIGKILL");
|
||||
} catch {
|
||||
// The group already exited.
|
||||
}
|
||||
};
|
||||
const timer = setTimeout(() => {
|
||||
kill("timeout");
|
||||
}, options.deadlineMs);
|
||||
const onAbort = (): void => {
|
||||
kill("cancelled");
|
||||
};
|
||||
options.signal?.addEventListener("abort", onAbort, { once: true });
|
||||
const finish = (exitCode: number | null): void => {
|
||||
clearTimeout(timer);
|
||||
options.signal?.removeEventListener("abort", onAbort);
|
||||
resolve(
|
||||
stopped === undefined
|
||||
? { kind: "exited", exitCode, output }
|
||||
: { kind: stopped },
|
||||
);
|
||||
};
|
||||
child.on("error", () => {
|
||||
finish(null);
|
||||
});
|
||||
child.on("close", (code) => {
|
||||
finish(code);
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* debugserver kills the traced process when LLDB exits. Confirm it, and kill a
|
||||
* survivor only when its executable is still the traced one.
|
||||
*/
|
||||
const ensureTerminated = async (
|
||||
pidPath: string,
|
||||
executable: string,
|
||||
): Promise<boolean> => {
|
||||
let pid: number;
|
||||
try {
|
||||
pid = Number.parseInt(await readFile(pidPath, "utf8"), 10);
|
||||
} catch {
|
||||
// LLDB never launched the target.
|
||||
return true;
|
||||
}
|
||||
if (!Number.isSafeInteger(pid) || pid <= 0) return false;
|
||||
for (let attempt = 0; attempt < 20; attempt++) {
|
||||
if (!alive(pid)) return true;
|
||||
if (attempt === 10 && (await commandOf(pid)) === executable)
|
||||
try {
|
||||
process.kill(pid, "SIGKILL");
|
||||
} catch {
|
||||
// It exited between the checks.
|
||||
}
|
||||
await new Promise((resolve) => setTimeout(resolve, 100));
|
||||
}
|
||||
return !alive(pid);
|
||||
};
|
||||
|
||||
const alive = (pid: number): boolean => {
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
return true;
|
||||
} catch (cause: unknown) {
|
||||
return !(
|
||||
cause instanceof Error &&
|
||||
"code" in cause &&
|
||||
cause.code === "ESRCH"
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
const commandOf = async (pid: number): Promise<string | undefined> => {
|
||||
try {
|
||||
const { stdout } = await execFileOutput(
|
||||
"/bin/ps",
|
||||
["-o", "comm=", "-p", String(pid)],
|
||||
{ timeout: 5_000 },
|
||||
);
|
||||
return stdout.trim();
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,182 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { open } from "node:fs/promises";
|
||||
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisInputError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import {
|
||||
nativeCallObservationInputSchema,
|
||||
nativeCallObservationResultSchema,
|
||||
type NativeCallObservationInput,
|
||||
type NativeCallObservationResult,
|
||||
} from "../domain/native/nativeCallObservation.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import type { NativeCallTrace, NativeCallTracer } from "./LldbCallTracer.js";
|
||||
|
||||
const OPERATION = "observe_native_calls";
|
||||
|
||||
/** What every call observation leaves unobserved or approximated. */
|
||||
export const NATIVE_CALL_OBSERVATION_LIMITATIONS = [
|
||||
"Only entries are observed; return values, floating-point and stack-passed arguments are not captured.",
|
||||
"Registers are the raw integer argument registers at entry. For Objective-C methods the first two hold the receiver and the selector.",
|
||||
"Receiver classes come from LLDB's Objective-C runtime reader without running target code; they are null for class methods and for receivers LLDB cannot classify.",
|
||||
"Calls that never reach a symbol's entry, such as inlined code or objc_direct methods called directly, are not observed.",
|
||||
"The target is launched directly under LLDB, not through LaunchServices; LLDB disables ASLR for it, so load addresses can equal file addresses.",
|
||||
"The observation window is checked about once a second, and recording pauses the process at every entry, which slows it.",
|
||||
] as const;
|
||||
|
||||
/** Launch the active Mach-O under LLDB, record requested call entries, then stop it. */
|
||||
export const observeNativeCalls = async (
|
||||
target: BinaryTarget,
|
||||
parameters: Readonly<Record<string, JsonValue>>,
|
||||
tracer: NativeCallTracer,
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<NativeCallObservationResult, AnalysisError>> => {
|
||||
if (target.kind !== "executable" || target.format !== "mach-o")
|
||||
return err(
|
||||
new AnalysisCapabilityUnavailableError(
|
||||
"native-macos",
|
||||
OPERATION,
|
||||
"Native call observation launches a Mach-O executable; the active target is not one",
|
||||
),
|
||||
);
|
||||
const parsed = nativeCallObservationInputSchema.safeParse(parameters);
|
||||
if (!parsed.success)
|
||||
return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
|
||||
// Observe the bytes the session's other Evidence describes.
|
||||
if ((await fileSha256(target.path, signal)) !== target.sha256)
|
||||
return err(
|
||||
new EvidenceIntegrityError(
|
||||
"Native call observation target digest changed after session binding",
|
||||
),
|
||||
);
|
||||
if (signal?.aborted === true)
|
||||
return err(new AnalysisCancelledError(OPERATION));
|
||||
const traced = await tracer.trace(
|
||||
{
|
||||
executable: target.path,
|
||||
architecture: target.architecture,
|
||||
input: parsed.data,
|
||||
},
|
||||
signal,
|
||||
);
|
||||
if (!traced.ok) return traced;
|
||||
return ok(projectNativeCalls(target, parsed.data, traced.value));
|
||||
};
|
||||
|
||||
/** Join the request, the tracer's run and REA's own checks into the result contract. */
|
||||
export const projectNativeCalls = (
|
||||
target: Pick<BinaryTarget, "path" | "sha256"> & {
|
||||
readonly architecture: string;
|
||||
},
|
||||
input: NativeCallObservationInput,
|
||||
trace: NativeCallTrace,
|
||||
): NativeCallObservationResult => {
|
||||
const { run } = trace;
|
||||
const unresolved = run.breakpoints
|
||||
.filter(({ location_count: count }) => count === 0)
|
||||
.map(({ index }) => index);
|
||||
const eventLimit = run.outcome === "event-limit";
|
||||
const partial =
|
||||
eventLimit || run.outcome === "stop-limit" || unresolved.length > 0;
|
||||
return nativeCallObservationResultSchema.parse({
|
||||
target: {
|
||||
path: target.path,
|
||||
sha256: target.sha256,
|
||||
architecture: target.architecture,
|
||||
arguments: input.arguments,
|
||||
working_directory: input.working_directory ?? null,
|
||||
},
|
||||
debugger: trace.debugger,
|
||||
process: {
|
||||
pid: run.pid,
|
||||
outcome: run.outcome,
|
||||
exit_status: run.exit_status,
|
||||
exit_description: run.exit_description,
|
||||
terminated: run.terminated && trace.terminated,
|
||||
elapsed_ms: run.elapsed_ms,
|
||||
stdout: trace.stdout,
|
||||
stderr: trace.stderr,
|
||||
other_stops: run.other_stops,
|
||||
},
|
||||
breakpoints: input.breakpoints.map((request, index) => ({
|
||||
index,
|
||||
request:
|
||||
request.kind === "function"
|
||||
? { ...request, module: request.module ?? null }
|
||||
: { ...request, class_name: request.class_name ?? null },
|
||||
location_count: run.breakpoints[index]?.location_count ?? 0,
|
||||
locations: run.breakpoints[index]?.locations ?? [],
|
||||
})),
|
||||
events: run.events,
|
||||
coverage: {
|
||||
status: partial ? "partial" : "complete",
|
||||
event_limit_reached: eventLimit,
|
||||
unresolved_breakpoints: unresolved,
|
||||
},
|
||||
limitations: [
|
||||
...NATIVE_CALL_OBSERVATION_LIMITATIONS,
|
||||
...(eventLimit
|
||||
? [
|
||||
`Observation stopped at max_events (${input.max_events}); later calls were not recorded and the process was killed.`,
|
||||
]
|
||||
: []),
|
||||
...(run.outcome === "duration-elapsed"
|
||||
? [
|
||||
`The process was still running after duration_ms (${input.duration_ms}) and was killed.`,
|
||||
]
|
||||
: []),
|
||||
...(run.outcome === "stop-limit"
|
||||
? [
|
||||
"Observation stopped after repeated signal or exception stops; the process was killed.",
|
||||
]
|
||||
: []),
|
||||
...(unresolved.length === 0
|
||||
? []
|
||||
: [
|
||||
`Breakpoints ${unresolved.join(", ")} matched no code in any image loaded while observing; their calls could not be observed.`,
|
||||
]),
|
||||
...(run.breakpoints.some(
|
||||
({ location_count: count, locations }) => locations.length < count,
|
||||
)
|
||||
? [
|
||||
"Breakpoints with many matching locations list only the first 64; location_count gives the total.",
|
||||
]
|
||||
: []),
|
||||
...(trace.stdout.truncated || trace.stderr.truncated
|
||||
? ["Target output beyond 1 MiB per stream is counted but not kept."]
|
||||
: []),
|
||||
...(run.terminated && trace.terminated
|
||||
? []
|
||||
: [
|
||||
`REA could not confirm that process ${run.pid} exited; check for it before relying on host state.`,
|
||||
]),
|
||||
],
|
||||
});
|
||||
};
|
||||
|
||||
const fileSha256 = async (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<string> => {
|
||||
const handle = await open(path, "r");
|
||||
try {
|
||||
const hash = createHash("sha256");
|
||||
const buffer = new Uint8Array(1024 * 1024);
|
||||
for (;;) {
|
||||
signal?.throwIfAborted();
|
||||
const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
|
||||
if (bytesRead === 0) break;
|
||||
hash.update(buffer.subarray(0, bytesRead));
|
||||
}
|
||||
return hash.digest("hex");
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
};
|
||||
@@ -5,6 +5,8 @@ import {
|
||||
export { NATIVE_MACOS_PROVIDER_IDENTITY } from "./NativeMacOSProviderMetadata.js";
|
||||
import { inspectAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
|
||||
import { observeNativeUi } from "./NativeUiObservation.js";
|
||||
import { LldbCallTracer, type NativeCallTracer } from "./LldbCallTracer.js";
|
||||
import { observeNativeCalls } from "./NativeCallObservation.js";
|
||||
import { dirname, isAbsolute, resolve } from "node:path";
|
||||
import { open, realpath, stat } from "node:fs/promises";
|
||||
|
||||
@@ -80,6 +82,7 @@ export class NativeMacOSProvider implements AnalysisProvider {
|
||||
constructor(
|
||||
private readonly runner: NativeCommandRunner = new XcrunCommandRunner(),
|
||||
platform: NodeJS.Platform = process.platform,
|
||||
private readonly tracer: NativeCallTracer = new LldbCallTracer(),
|
||||
) {
|
||||
this.#capabilities = nativeMacOSCapabilities(platform);
|
||||
}
|
||||
@@ -93,7 +96,7 @@ export class NativeMacOSProvider implements AnalysisProvider {
|
||||
}
|
||||
|
||||
createClient(target: BinaryTarget): AnalysisClient {
|
||||
return new NativeMacOSClient(target, this.runner);
|
||||
return new NativeMacOSClient(target, this.runner, this.tracer);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -101,6 +104,7 @@ class NativeMacOSClient implements AnalysisClient {
|
||||
constructor(
|
||||
private readonly target: BinaryTarget,
|
||||
private readonly runner: NativeCommandRunner,
|
||||
private readonly tracer: NativeCallTracer,
|
||||
) {}
|
||||
|
||||
async execute(
|
||||
@@ -165,6 +169,22 @@ class NativeMacOSClient implements AnalysisClient {
|
||||
"Operation is not implemented by native macOS tools.",
|
||||
),
|
||||
);
|
||||
if (operation === "observe_native_calls") {
|
||||
const result = await observeNativeCalls(
|
||||
this.target,
|
||||
parameters,
|
||||
this.tracer,
|
||||
options?.signal,
|
||||
);
|
||||
return result.ok
|
||||
? ok(
|
||||
createAnalysisExecution(result.value, IDENTITY, {
|
||||
limitations: result.value.limitations,
|
||||
locations: [{ kind: "artifact-path", path: this.target.path }],
|
||||
}),
|
||||
)
|
||||
: result;
|
||||
}
|
||||
if (
|
||||
operation === "observe_native_ui" ||
|
||||
operation === "capture_native_ui_scenario"
|
||||
@@ -220,6 +240,7 @@ class NativeMacOSClient implements AnalysisClient {
|
||||
switch (operation) {
|
||||
case "observe_native_ui":
|
||||
case "capture_native_ui_scenario":
|
||||
case "observe_native_calls":
|
||||
return Promise.resolve(
|
||||
err(
|
||||
new AnalysisCapabilityUnavailableError(
|
||||
|
||||
@@ -12,6 +12,12 @@ export const NATIVE_MACOS_PROVIDER_IDENTITY: ProviderIdentity = Object.freeze({
|
||||
});
|
||||
const IDENTITY = NATIVE_MACOS_PROVIDER_IDENTITY;
|
||||
|
||||
/** Operations whose target process can show UI, use the network and write files. */
|
||||
const OWNED_PROCESS_OPERATIONS: ReadonlySet<string> = new Set([
|
||||
"capture_native_ui_scenario",
|
||||
"observe_native_calls",
|
||||
]);
|
||||
|
||||
/** Declare native host coverage without creating a command runner. */
|
||||
export const nativeMacOSCapabilities = (
|
||||
platform: NodeJS.Platform = process.platform,
|
||||
@@ -36,10 +42,10 @@ export const nativeMacOSCapabilities = (
|
||||
effects: Object.freeze({
|
||||
mutatesArtifact: false,
|
||||
launchesProcess: contract.name !== "inspect_native_dispatch_metadata",
|
||||
mayShowUi: contract.name === "capture_native_ui_scenario",
|
||||
mayAccessNetwork: contract.name === "capture_native_ui_scenario",
|
||||
mayShowUi: OWNED_PROCESS_OPERATIONS.has(contract.name),
|
||||
mayAccessNetwork: OWNED_PROCESS_OPERATIONS.has(contract.name),
|
||||
mayWriteFilesystem:
|
||||
contract.name === "capture_native_ui_scenario" ||
|
||||
OWNED_PROCESS_OPERATIONS.has(contract.name) ||
|
||||
contract.name === "observe_native_ui",
|
||||
changesPermissions: false,
|
||||
requiresRoot: false,
|
||||
|
||||
Reference in New Issue
Block a user