rea-agents 4.0.1 → 5.0.0

package/dist/domain/apple/appleApplication.js

@@ -0,0 +1,277 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { appleBundleSchema, appleComponentSchema, applicationRoots, detectBundles, isMachOFormat, isSidecar, isWithin, platformsOf, } from "./appleBundleAnatomy.js";
+import { parseArtifactInventoryEvidence } from "../artifactInventoryEvidence.js";
+import { evidenceSchema } from "../evidence.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const pathSchema = z.string().min(1);
+const APPLE_ROOT_FORMATS = ["ipa", "directory", "zip", "dmg"];
+/** Authenticated artifact inventory pages projected as one Apple application. */
+export const appleApplicationProjectionInputSchema = z.strictObject({
+    inventory_evidence: z.array(evidenceSchema).min(1),
+});
+/** Deterministic, execution-free Apple application inventory projection. */
+export const appleApplicationProjectionResultSchema = z.strictObject({
+    projection_id: prefixedDigestSchema("aap"),
+    root_sha256: digestSchema,
+    root_format: z.enum(APPLE_ROOT_FORMATS),
+    platforms: z.array(z.enum(["ios", "macos"])),
+    source_evidence_ids: z.array(evidenceIdSchema).min(1),
+    application_roots: z.array(pathSchema),
+    bundles: z.array(appleBundleSchema),
+    components: z.strictObject({
+        bundle_metadata: z.array(appleComponentSchema),
+        executables: z.array(appleComponentSchema),
+        frameworks: z.array(appleComponentSchema),
+        native_libraries: z.array(appleComponentSchema),
+        javascript: z.array(appleComponentSchema),
+        signing: z.array(appleComponentSchema),
+        privileged_helpers: z.array(appleComponentSchema),
+        launchd_plists: z.array(appleComponentSchema.extend({ domain: z.enum(["agent", "daemon"]) })),
+        helpers: z.array(appleComponentSchema),
+    }),
+    symlinks: z.array(pathSchema),
+    runtime_families: z.array(z.enum([
+        "native",
+        "swift-objective-c",
+        "javascript",
+        "react-native",
+        "flutter",
+        "unity",
+    ])),
+    bridge_candidates: z.array(z.strictObject({
+        source_path: pathSchema,
+        native_path: pathSchema,
+        basis: z.enum([
+            "javascript-and-native-content",
+            "react-native-convention",
+            "flutter-convention",
+            "unity-convention",
+        ]),
+    })),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inventory", "partial"]),
+        inventory_complete: z.boolean(),
+    }),
+    limitations: z.array(z.string().min(1)),
+});
+/** Project exact Apple application paths and hashes without parsing or executing target code. */
+export const projectAppleApplication = (input) => {
+    const parsed = appleApplicationProjectionInputSchema.parse(input);
+    const { evidence, inventory } = parseArtifactInventoryEvidence(parsed.inventory_evidence);
+    const rootFormat = appleRootFormat(inventory.manifest.root_format);
+    const nodes = new Map(inventory.nodes.map((node) => [node.artifact_id, node]));
+    const entries = inventory.occurrences
+        .filter(({ logical_path: path }) => path !== ".")
+        .map((occurrence) => {
+        if (occurrence.artifact_id === null)
+            return {
+                path: occurrence.logical_path,
+                kind: occurrence.entry_kind,
+                component: undefined,
+            };
+        const node = nodes.get(occurrence.artifact_id);
+        if (node === undefined)
+            throw new TypeError("Apple application occurrence has no artifact node");
+        return {
+            path: occurrence.logical_path,
+            kind: occurrence.entry_kind,
+            component: {
+                path: occurrence.logical_path,
+                artifact_id: node.artifact_id,
+                sha256: node.sha256,
+                format: node.format,
+            },
+        };
+    });
+    const inventoried = entries.flatMap(({ component }) => component === undefined ? [] : [component]);
+    const roots = applicationRoots(entries, {
+        name: evidence[0]?.subject?.name ?? "",
+        format: rootFormat,
+    });
+    const { all, unattributed } = attributeComponents(inventoried, roots, rootFormat);
+    const bundles = detectBundles(entries, roots);
+    const classified = classifyComponents(entries, all, roots);
+    const runtimeFamilies = identifyRuntimeFamilies(all);
+    const bridgeProjection = identifyBridgeCandidates(classified.javascript, deduplicateComponents([
+        ...classified.executables,
+        ...classified.native_libraries,
+    ]), roots);
+    const uninventoriedImage = rootFormat === "dmg" && inventory.occurrences.length === 1;
+    const complete = inventory.complete && !uninventoriedImage;
+    const limitations = projectionLimitations({
+        complete: inventory.complete,
+        uninventoriedImage,
+        roots,
+        bundles,
+        sidecars: entries.some(({ path }) => isSidecar(path)),
+        symlinks: entries.some(({ kind }) => kind === "symlink"),
+        unattributed,
+    });
+    const withoutId = {
+        root_sha256: inventory.manifest.root_sha256,
+        root_format: rootFormat,
+        platforms: platformsOf(bundles),
+        source_evidence_ids: evidence
+            .map(({ evidence_id: id }) => id)
+            .sort(compare),
+        application_roots: roots,
+        bundles,
+        components: classified,
+        symlinks: entries
+            .filter(({ kind }) => kind === "symlink")
+            .map(({ path }) => path)
+            .sort(compare),
+        runtime_families: runtimeFamilies,
+        bridge_candidates: bridgeProjection.candidates,
+        coverage: {
+            status: complete
+                ? "complete-within-inventory"
+                : "partial",
+            inventory_complete: inventory.complete,
+        },
+        limitations,
+    };
+    return appleApplicationProjectionResultSchema.parse({
+        ...withoutId,
+        projection_id: `aap_${digest(withoutId)}`,
+    });
+};
+/**
+ * IPA projection keeps every archive component, as before. Directory, ZIP,
+ * and DMG inventories can hold installers and other siblings, so only
+ * components inside an application root are attributed to it.
+ */
+const attributeComponents = (inventoried, roots, rootFormat) => {
+    if (rootFormat === "ipa")
+        return { all: [...inventoried], unattributed: 0 };
+    const visible = inventoried.filter(({ path }) => !isSidecar(path));
+    const all = visible.filter(({ path }) => roots.some((root) => isWithin(path, root)));
+    return { all, unattributed: visible.length - all.length };
+};
+const appleRootFormat = (format) => {
+    const root = APPLE_ROOT_FORMATS.find((candidate) => candidate === format);
+    if (root === undefined)
+        throw new TypeError(`Apple application projection requires IPA, directory, ZIP, or DMG inventory Evidence (got ${format})`);
+    return root;
+};
+const classifyComponents = (entries, all, roots) => {
+    const withinApp = (path) => roots.some((root) => isWithin(path, root));
+    const anatomy = (pattern) => entries.flatMap(({ path, kind, component }) => kind === "file" &&
+        component !== undefined &&
+        !isSidecar(path) &&
+        withinApp(path) &&
+        pattern.test(path)
+        ? [component]
+        : []);
+    return {
+        bundle_metadata: all.filter(({ path }) => /(?:^|\/)Info\.plist$/u.test(path)),
+        executables: all.filter(({ path, format }) => withinApp(path) && isMachOFormat(format)),
+        frameworks: all.filter(({ path }) => /\.framework\//u.test(path)),
+        native_libraries: all.filter(({ path }) => /\.(?:dylib|so)$/iu.test(path)),
+        javascript: all.filter(({ format }) => format === "javascript-bundle"),
+        signing: all.filter(({ path }) => /(?:^|\/)(?:embedded\.(?:mobileprovision|provisionprofile)|_CodeSignature\/CodeResources)$/u.test(path)),
+        privileged_helpers: anatomy(/(?:^|\/)Contents\/Library\/LaunchServices\/[^/]+$/u),
+        launchd_plists: anatomy(/(?:^|\/)Contents\/Library\/Launch(?:Agents|Daemons)\/[^/]+\.plist$/u).map((component) => ({
+            ...component,
+            domain: component.path.includes("/LaunchDaemons/")
+                ? "daemon"
+                : "agent",
+        })),
+        helpers: anatomy(/(?:^|\/)Contents\/Helpers\/[^/]+$/u),
+    };
+};
+const deduplicateComponents = (values) => [...new Map(values.map((value) => [value.path, value])).values()].sort((left, right) => compare(left.path, right.path));
+const identifyRuntimeFamilies = (all) => {
+    const paths = all.map(({ path }) => path.toLowerCase());
+    const families = new Set();
+    if (all.some(({ format }) => ["mach-o", "mach-o-universal"].includes(format)))
+        families.add("native");
+    if (paths.some((path) => /\.(?:dylib|framework\/[^/]+)$/u.test(path)))
+        families.add("swift-objective-c");
+    if (all.some(({ format }) => format === "javascript-bundle"))
+        families.add("javascript");
+    if (paths.some((path) => path.includes("reactnative") ||
+        path.includes("react.framework") ||
+        path.includes("hermes")))
+        families.add("react-native");
+    if (paths.some((path) => path.includes("flutter.framework") || path.includes("app.framework")))
+        families.add("flutter");
+    if (paths.some((path) => path.includes("unityframework.framework")))
+        families.add("unity");
+    return [...families].sort(compare);
+};
+/** Pair scripts and native code only within the same application root. */
+const identifyBridgeCandidates = (scripts, native, roots) => {
+    const owner = (path) => roots.find((root) => isWithin(path, root)) ?? null;
+    return {
+        candidates: scripts.flatMap((script) => {
+            const root = owner(script.path);
+            return native
+                .filter(({ path }) => owner(path) === root)
+                .map((item) => ({
+                source_path: script.path,
+                native_path: item.path,
+                basis: bridgeBasis(item.path),
+            }));
+        }),
+    };
+};
+const bridgeBasis = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.includes("react"))
+        return "react-native-convention";
+    if (lower.includes("flutter") || lower.includes("app.framework"))
+        return "flutter-convention";
+    if (lower.includes("unity"))
+        return "unity-convention";
+    return "javascript-and-native-content";
+};
+const projectionLimitations = (facts) => [
+    ...(!facts.complete
+        ? ["Source inventory pages are incomplete; absence is unknown."]
+        : []),
+    ...(facts.uninventoriedImage
+        ? [
+            "The DMG's contents were not inventoried on this host; bundle absence is unknown.",
+        ]
+        : []),
+    ...(facts.roots.length === 0
+        ? [
+            "No application bundle (Payload/*.app or *.app/Contents) was present in the supplied inventory pages.",
+        ]
+        : []),
+    ...(facts.bundles.some(({ layout, info_plist_path: plist }) => layout === "versioned-framework" && plist === null)
+        ? [
+            "A versioned framework has several version directories or no Versions/*/Resources/Info.plist; the Info.plist that Versions/Current selects is unknown because symlink targets are not inventoried.",
+        ]
+        : []),
+    ...(facts.symlinks
+        ? [
+            "Symlinks are reported by path only; their targets are not inventoried, so bundles are reported at their real paths.",
+        ]
+        : []),
+    ...(facts.unattributed > 0
+        ? [
+            `${facts.unattributed} inventoried entries outside every application root are not attributed to the application.`,
+        ]
+        : []),
+    ...(facts.sidecars
+        ? [
+            "AppleDouble sidecar entries (._* files and __MACOSX/) describe neighbouring files and are excluded from bundle roles.",
+        ]
+        : []),
+    "Bundle roles follow path conventions. Read each info_plist_path with inspect_plist for CFBundleExecutable, identifiers, and declared services.",
+    "Bundle identifiers and signing claims require dedicated plist and CMS parsing; this projection reports only exact paths and hashes.",
+    "Bridge candidates are path-based hypotheses, not observed runtime calls.",
+];
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Apple application projection is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};

package/dist/domain/{appleAssetCatalog.js → apple/appleAssetCatalog.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
-import { AnalysisOutputError } from "./errors.js";
+import { jsonValueSchema } from "../jsonValue.js";
+import { AnalysisOutputError } from "../analysisErrorCore.js";
 /** Caller-controlled page bounds for compiled Apple asset metadata. */
 export const appleAssetCatalogInputSchema = z.strictObject({
     offset: z.number().int().min(0).default(0),

package/dist/domain/apple/appleBundleAnatomy.js

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { digestSchema, prefixedDigestSchema } from "../digests.js";
+const pathSchema = z.string().min(1);
+const BUNDLE_EXTENSION = /\.(?:app|appex|xpc|framework|systemextension|dext|bundle|plugin|qlgenerator|mdimporter)$/iu;
+const MACH_O_FORMATS = ["mach-o", "mach-o-universal"];
+/** One inventoried file or directory with its content identity. */
+export const appleComponentSchema = z.strictObject({
+    path: pathSchema,
+    artifact_id: prefixedDigestSchema("art"),
+    sha256: digestSchema,
+    format: z.string().min(1),
+});
+/** One application root or nested bundle classified by path convention. */
+export const appleBundleSchema = z.strictObject({
+    path: pathSchema,
+    parent_path: pathSchema.nullable(),
+    layout: z.enum(["shallow", "macos-deep", "versioned-framework"]),
+    role: z.enum([
+        "application",
+        "app-extension",
+        "xpc-service",
+        "framework",
+        "login-item",
+        "system-extension",
+        "driver-extension",
+        "plug-in",
+        "resource-bundle",
+        "bundle",
+        "helper-application",
+        "nested-application",
+    ]),
+    role_basis: z.literal("path-convention"),
+    info_plist_path: pathSchema.nullable(),
+    executable_candidates: z.array(pathSchema),
+    signing_paths: z.array(pathSchema),
+});
+/** Report whether an inventory format is a thin or universal Mach-O. */
+export const isMachOFormat = (format) => MACH_O_FORMATS.includes(format);
+/** AppleDouble metadata written beside archived files (`._name`, `__MACOSX/`). */
+export const isSidecar = (path) => {
+    const segments = path.split("/");
+    return (segments.includes("__MACOSX") || (segments.at(-1) ?? "").startsWith("._"));
+};
+export const isWithin = (path, root) => root === "." || path === root || path.startsWith(`${root}/`);
+/**
+ * Outermost iOS (`Payload/X.app`) and macOS (`X.app/Contents/…`) applications.
+ * An inventoried `.app` directory is its own root, `.`.
+ */
+export const applicationRoots = (entries, subject) => {
+    // A selected `.app` directory is the application, even when its inventory
+    // is partial or lacks Contents/; coverage and limitations describe that.
+    if (subject.format === "directory" && /\.app$/iu.test(subject.name))
+        return ["."];
+    const found = new Set();
+    for (const { path } of entries) {
+        if (isSidecar(path))
+            continue;
+        const ios = /^(Payload\/[^/]+\.app)(?:\/|$)/u.exec(path);
+        if (ios?.[1] !== undefined) {
+            found.add(ios[1]);
+            continue;
+        }
+        const segments = path.split("/");
+        const index = segments.findIndex((segment, position) => /\.app$/iu.test(segment) && segments[position + 1] === "Contents");
+        if (index >= 0)
+            found.add(segments.slice(0, index + 1).join("/"));
+    }
+    const roots = [...found];
+    return roots
+        .filter((root) => !roots.some((other) => other !== root && isWithin(root, other)))
+        .sort(compare);
+};
+export const detectBundles = (entries, roots) => {
+    const paths = new Set(roots);
+    for (const { path, kind } of entries) {
+        if (isSidecar(path))
+            continue;
+        const root = roots.find((candidate) => isWithin(path, candidate));
+        if (root === undefined)
+            continue;
+        const segments = path.split("/");
+        const start = root === "." ? 0 : root.split("/").length;
+        for (let index = start; index < segments.length; index++) {
+            const segment = segments[index] ?? "";
+            const leaf = index === segments.length - 1;
+            // A symlink or file named like a bundle has no observed contents.
+            if (BUNDLE_EXTENSION.test(segment) && (!leaf || kind === "directory"))
+                paths.add(segments.slice(0, index + 1).join("/"));
+        }
+    }
+    const tree = indexTree(entries);
+    return [...paths].sort(compare).map((path) => {
+        const layout = bundleLayout(path, tree);
+        return {
+            path,
+            parent_path: enclosingBundle(path, paths),
+            layout,
+            role: roots.includes(path) ? "application" : bundleRole(path),
+            role_basis: "path-convention",
+            info_plist_path: infoPlistPath(path, layout, tree),
+            executable_candidates: executableCandidates(path, layout, tree),
+            signing_paths: signingPaths(path, layout, tree),
+        };
+    });
+};
+const indexTree = (entries) => {
+    const children = new Map();
+    const files = new Map();
+    const directories = new Set();
+    for (const { path, kind, component } of entries) {
+        if (isSidecar(path))
+            continue;
+        if (kind === "file" && component !== undefined)
+            files.set(path, component);
+        if (kind === "directory")
+            directories.add(path);
+        const segments = path.split("/");
+        let parent = "";
+        for (const segment of segments) {
+            const names = children.get(parent) ?? new Set();
+            names.add(segment);
+            children.set(parent, names);
+            parent = joinPath(parent, segment);
+            if (parent !== path)
+                directories.add(parent);
+        }
+    }
+    return { children, files, directories };
+};
+const joinPath = (directory, name) => directory === "" ? name : `${directory}/${name}`;
+const directoryOf = (bundle) => (bundle === "." ? "" : bundle);
+const enclosingBundle = (path, bundles) => {
+    if (path === ".")
+        return null;
+    const segments = path.split("/");
+    for (let length = segments.length - 1; length > 0; length--) {
+        const candidate = segments.slice(0, length).join("/");
+        if (bundles.has(candidate))
+            return candidate;
+    }
+    return bundles.has(".") ? "." : null;
+};
+const bundleLayout = (bundle, tree) => {
+    const names = tree.children.get(directoryOf(bundle));
+    if (names?.has("Contents") === true)
+        return "macos-deep";
+    if (names?.has("Versions") === true)
+        return "versioned-framework";
+    return "shallow";
+};
+const bundleRole = (bundle) => {
+    const segments = bundle.split("/");
+    const name = (segments.at(-1) ?? "").toLowerCase();
+    const container = segments.at(-2);
+    if (name.endsWith(".appex"))
+        return "app-extension";
+    if (name.endsWith(".xpc"))
+        return "xpc-service";
+    if (name.endsWith(".framework"))
+        return "framework";
+    if (name.endsWith(".systemextension"))
+        return "system-extension";
+    if (name.endsWith(".dext"))
+        return "driver-extension";
+    if (name.endsWith(".bundle")) {
+        if (container === "PlugIns")
+            return "plug-in";
+        return container === "Resources" ? "resource-bundle" : "bundle";
+    }
+    if (!name.endsWith(".app"))
+        return "plug-in";
+    if (container === "LoginItems" && segments.at(-3) === "Library")
+        return "login-item";
+    if (container === "Helpers")
+        return "helper-application";
+    return "nested-application";
+};
+/** Files directly inside one directory; nested bundles are deeper paths. */
+const directFiles = (directory, tree) => [...(tree.children.get(directory) ?? [])]
+    .map((name) => joinPath(directory, name))
+    .filter((path) => tree.files.has(path))
+    .sort(compare);
+/** Content directories; `Versions/Current` is a symlink outside the inventory. */
+const contentDirectories = (bundle, layout, tree) => {
+    const directory = directoryOf(bundle);
+    if (layout === "macos-deep")
+        return [joinPath(directory, "Contents")];
+    if (layout === "shallow")
+        return [directory];
+    const versions = joinPath(directory, "Versions");
+    // Only real version directories count: Current is a symlink, and files
+    // such as .DS_Store are not versions.
+    return [...(tree.children.get(versions) ?? [])]
+        .filter((version) => version !== "Current")
+        .map((version) => joinPath(versions, version))
+        .filter((version) => tree.directories.has(version))
+        .sort(compare);
+};
+const infoPlistPath = (bundle, layout, tree) => {
+    const directories = contentDirectories(bundle, layout, tree);
+    // With several real versions, Versions/Current (a symlink outside the
+    // inventory) decides which plist applies, so the plist stays unknown.
+    if (directories.length !== 1)
+        return null;
+    const candidates = directories
+        .map((directory) => joinPath(directory, layout === "versioned-framework"
+        ? "Resources/Info.plist"
+        : "Info.plist"))
+        .filter((path) => tree.files.has(path));
+    return candidates.length === 1 ? (candidates[0] ?? null) : null;
+};
+const executableCandidates = (bundle, layout, tree) => contentDirectories(bundle, layout, tree)
+    .flatMap((directory) => directFiles(layout === "macos-deep" ? joinPath(directory, "MacOS") : directory, tree))
+    .filter((path) => MACH_O_FORMATS.includes(tree.files.get(path)?.format ?? ""));
+const signingPaths = (bundle, layout, tree) => contentDirectories(bundle, layout, tree)
+    .flatMap((directory) => [
+    joinPath(directory, "_CodeSignature/CodeResources"),
+    joinPath(directory, "embedded.provisionprofile"),
+    joinPath(directory, "embedded.mobileprovision"),
+])
+    .filter((path) => tree.files.has(path))
+    .sort(compare);
+/** Platforms of application roots whose layout was observed, not assumed. */
+export const platformsOf = (bundles) => [
+    ...new Set(bundles.flatMap(({ role, layout, info_plist_path: plist }) => {
+        if (role !== "application")
+            return [];
+        if (layout === "macos-deep")
+            return ["macos"];
+        // An empty or partial root has no Contents/ either; require Info.plist.
+        if (layout === "shallow" && plist !== null)
+            return ["ios"];
+        return [];
+    })),
+].sort(compare);
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;