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:
Kaoru0822
2026-10-08 06:20:14 +00:00
co-authored by Claude Opus 5.5
43 changed files with 3058 additions and 73 deletions
@@ -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" });
},
);
});
+57
View File
@@ -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,
);
}),
});
};
+2
View File
@@ -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"],
+1
View File
@@ -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.",
+9
View File
@@ -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,
+2
View File
@@ -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&#46;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&#47;" 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 };
};
+198
View File
@@ -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
>;
+1 -1
View File
@@ -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;
+2 -1
View File
@@ -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>> => {
+400
View File
@@ -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;
}
};
+182
View File
@@ -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();
}
};
+22 -1
View File
@@ -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(
+9 -3
View File
@@ -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,