* refactor(apple): group artifact producers and verification * test(apple): run affected native plist CLI regressions
404 lines
13 KiB
TypeScript
404 lines
13 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
|
|
import canonicalize from "canonicalize";
|
|
import { z } from "zod";
|
|
|
|
import {
|
|
appleBundleSchema,
|
|
appleComponentSchema,
|
|
applicationRoots,
|
|
detectBundles,
|
|
isMachOFormat,
|
|
isSidecar,
|
|
isWithin,
|
|
platformsOf,
|
|
type AppleInventoryEntry,
|
|
} 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"] as const;
|
|
|
|
/** 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)),
|
|
});
|
|
|
|
export type AppleApplicationProjectionInput = z.infer<
|
|
typeof appleApplicationProjectionInputSchema
|
|
>;
|
|
export type AppleApplicationProjectionResult = z.infer<
|
|
typeof appleApplicationProjectionResultSchema
|
|
>;
|
|
|
|
type Component = z.infer<typeof appleComponentSchema>;
|
|
type RootFormat = (typeof APPLE_ROOT_FORMATS)[number];
|
|
|
|
/** Project exact Apple application paths and hashes without parsing or executing target code. */
|
|
export const projectAppleApplication = (
|
|
input: AppleApplicationProjectionInput,
|
|
): AppleApplicationProjectionResult => {
|
|
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: AppleInventoryEntry[] = 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" as const)
|
|
: ("partial" as const),
|
|
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: readonly Component[],
|
|
roots: readonly string[],
|
|
rootFormat: RootFormat,
|
|
): { readonly all: Component[]; readonly unattributed: number } => {
|
|
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: string): RootFormat => {
|
|
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: readonly AppleInventoryEntry[],
|
|
all: readonly Component[],
|
|
roots: readonly string[],
|
|
) => {
|
|
const withinApp = (path: string): boolean =>
|
|
roots.some((root) => isWithin(path, root));
|
|
const anatomy = (pattern: RegExp): Component[] =>
|
|
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" as const)
|
|
: ("agent" as const),
|
|
})),
|
|
helpers: anatomy(/(?:^|\/)Contents\/Helpers\/[^/]+$/u),
|
|
};
|
|
};
|
|
|
|
const deduplicateComponents = (values: readonly Component[]): Component[] =>
|
|
[...new Map(values.map((value) => [value.path, value])).values()].sort(
|
|
(left, right) => compare(left.path, right.path),
|
|
);
|
|
|
|
const identifyRuntimeFamilies = (all: readonly Component[]) => {
|
|
const paths = all.map(({ path }) => path.toLowerCase());
|
|
const families = new Set<
|
|
z.infer<
|
|
typeof appleApplicationProjectionResultSchema
|
|
>["runtime_families"][number]
|
|
>();
|
|
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: readonly Component[],
|
|
native: readonly Component[],
|
|
roots: readonly string[],
|
|
) => {
|
|
const owner = (path: string): string | null =>
|
|
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: string,
|
|
):
|
|
| "javascript-and-native-content"
|
|
| "react-native-convention"
|
|
| "flutter-convention"
|
|
| "unity-convention" => {
|
|
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: {
|
|
readonly complete: boolean;
|
|
readonly uninventoriedImage: boolean;
|
|
readonly roots: readonly string[];
|
|
readonly bundles: readonly z.infer<typeof appleBundleSchema>[];
|
|
readonly sidecars: boolean;
|
|
readonly symlinks: boolean;
|
|
readonly unattributed: number;
|
|
}): string[] => [
|
|
...(!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: string, right: string): number =>
|
|
left < right ? -1 : left > right ? 1 : 0;
|
|
const digest = (value: unknown): string => {
|
|
const encoded = canonicalize(value);
|
|
if (encoded === undefined)
|
|
throw new TypeError("Apple application projection is not canonical JSON");
|
|
return createHash("sha256").update(encoded).digest("hex");
|
|
};
|