* fix(artifacts): preserve complete root inventory comparisons * fix(artifacts): declare inventory coverage before comparison * fix(artifacts): preserve traversal omissions and materialization limits * fix(artifacts): preserve coverage declarations and projection scope Remove the duplicate inventory-schema import. Compare original coverage declarations, including field omission, before adapting legacy pages. Require explicit scope for completeness and container-entry coverage for application projections. Source inspection and git diff --check only. Tests, builds and typechecks skipped by explicit user request. GitHub review writes paused globally. * fix(artifacts): require entry coverage for child changes * fix(artifacts): accept source-valid inventory limitations * style(artifacts): format mobile graph projection --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> Co-authored-by: OpenAI Codex <openai-codex@users.noreply.github.com>
456 lines
16 KiB
TypeScript
456 lines
16 KiB
TypeScript
import { z } from "zod";
|
|
|
|
import {
|
|
anatomyNameIs,
|
|
anatomyTailMatches,
|
|
appleBundleSchema,
|
|
appleComponentSchema,
|
|
applicationRoots,
|
|
detectBundles,
|
|
isMachOFormat,
|
|
isSidecar,
|
|
isWithin,
|
|
platformsOf,
|
|
type AppleInventoryEntry,
|
|
} from "./appleBundleAnatomy.js";
|
|
import {
|
|
isSwiftRuntimeLibrary,
|
|
nativeRuntimeConvention,
|
|
} from "../nativeConvention.js";
|
|
import {
|
|
hasCompleteInventoryCoverage,
|
|
parseArtifactInventoryEvidence,
|
|
} from "../artifactInventoryEvidence.js";
|
|
import { evidenceSchema } from "../evidence.js";
|
|
import { digestSchema } from "../digests.js";
|
|
import { prefixedDigestSchema } from "../digests.js";
|
|
import {
|
|
bridgeCandidateCoverageSchema,
|
|
projectCartesianCandidates,
|
|
} from "../bridgeCandidateProjection.js";
|
|
import {
|
|
compareProjectionStrings,
|
|
projectionDigest,
|
|
} from "../mobileApplicationGraphProjection.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",
|
|
]),
|
|
}),
|
|
),
|
|
bridge_candidate_coverage: bridgeCandidateCoverageSchema,
|
|
coverage: z.strictObject({
|
|
status: z.enum(["complete-within-inventory", "partial"]),
|
|
// Count completeness is separate from the declared coverage status.
|
|
inventory_complete: z.boolean(),
|
|
}),
|
|
limitations: z.array(z.string()),
|
|
});
|
|
|
|
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: occurrence.artifact_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 inventoryComplete = hasCompleteInventoryCoverage(
|
|
inventory,
|
|
"container-entries",
|
|
);
|
|
const complete = inventoryComplete && !uninventoriedImage;
|
|
const limitations = [
|
|
...inventory.limitations,
|
|
...projectionLimitations({
|
|
complete: inventoryComplete,
|
|
uninventoriedImage,
|
|
roots,
|
|
bundles,
|
|
sidecars: entries.some(({ path }) => isSidecar(path)),
|
|
symlinks: entries.some(({ kind }) => kind === "symlink"),
|
|
unattributed,
|
|
bridgeCandidateCoverage: bridgeProjection.coverage,
|
|
}),
|
|
];
|
|
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,
|
|
bridge_candidate_coverage: bridgeProjection.coverage,
|
|
coverage: {
|
|
status:
|
|
complete && bridgeProjection.coverage.status === "complete"
|
|
? ("complete-within-inventory" as const)
|
|
: ("partial" as const),
|
|
inventory_complete: inventory.complete,
|
|
},
|
|
limitations,
|
|
};
|
|
return appleApplicationProjectionResultSchema.parse({
|
|
...withoutId,
|
|
projection_id: appleProjectionId(withoutId),
|
|
});
|
|
};
|
|
|
|
/** Identify the complete projection, including source Evidence provenance. */
|
|
export const appleProjectionId = (projection: unknown): string =>
|
|
`aap_${digest(projection)}`;
|
|
|
|
/**
|
|
* AppleDouble sidecars describe neighbouring files and are never components.
|
|
* IPA projection keeps every other 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 } => {
|
|
const visible = inventoried.filter(({ path }) => !isSidecar(path));
|
|
if (rootFormat === "ipa") return { all: visible, unattributed: 0 };
|
|
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 matching = (predicate: (path: string) => boolean): Component[] =>
|
|
entries.flatMap(({ path, kind, component }) =>
|
|
kind === "file" &&
|
|
component !== undefined &&
|
|
!isSidecar(path) &&
|
|
withinApp(path) &&
|
|
predicate(path)
|
|
? [component]
|
|
: [],
|
|
);
|
|
const lastSegment = (path: string): string => path.split("/").at(-1) ?? "";
|
|
return {
|
|
bundle_metadata: all.filter(({ path }) =>
|
|
anatomyNameIs(lastSegment(path), "Info.plist"),
|
|
),
|
|
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 }) =>
|
|
anatomyTailMatches(path, ["_CodeSignature", "CodeResources"]) ||
|
|
anatomyNameIs(lastSegment(path), "embedded.mobileprovision") ||
|
|
anatomyNameIs(lastSegment(path), "embedded.provisionprofile"),
|
|
),
|
|
privileged_helpers: matching((path) =>
|
|
anatomyTailMatches(path, ["Contents", "Library", "LaunchServices", "*"]),
|
|
),
|
|
launchd_plists: matching(
|
|
(path) =>
|
|
path.endsWith(".plist") &&
|
|
(anatomyTailMatches(path, [
|
|
"Contents",
|
|
"Library",
|
|
"LaunchAgents",
|
|
"*",
|
|
]) ||
|
|
anatomyTailMatches(path, [
|
|
"Contents",
|
|
"Library",
|
|
"LaunchDaemons",
|
|
"*",
|
|
])),
|
|
).map((component) => ({
|
|
...component,
|
|
domain: component.path
|
|
.split("/")
|
|
.some((segment) => anatomyNameIs(segment, "LaunchDaemons"))
|
|
? ("daemon" as const)
|
|
: ("agent" as const),
|
|
})),
|
|
helpers: matching((path) =>
|
|
anatomyTailMatches(path, ["Contents", "Helpers", "*"]),
|
|
),
|
|
};
|
|
};
|
|
|
|
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 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 (all.some(({ path }) => isSwiftRuntimeLibrary(path)))
|
|
families.add("swift-objective-c");
|
|
if (all.some(({ format }) => format === "javascript-bundle"))
|
|
families.add("javascript");
|
|
for (const { path } of all) {
|
|
const convention = nativeRuntimeConvention(path);
|
|
if (convention !== null) families.add(convention);
|
|
}
|
|
return [...families].sort(compare);
|
|
};
|
|
|
|
/** Pair scripts and native code within matching application-root groups. */
|
|
const identifyBridgeCandidates = (
|
|
scripts: readonly Component[],
|
|
native: readonly Component[],
|
|
roots: readonly string[],
|
|
) => {
|
|
const owner = (path: string): string | null =>
|
|
roots.find((root) => isWithin(path, root)) ?? null;
|
|
const scriptGroups: { root: string | null; left: Component[] }[] = [];
|
|
for (const script of scripts) {
|
|
const root = owner(script.path);
|
|
const last = scriptGroups.at(-1);
|
|
if (last?.root === root) last.left.push(script);
|
|
else scriptGroups.push({ root, left: [script] });
|
|
}
|
|
const nativeByRoot = new Map<string | null, Component[]>();
|
|
for (const item of native) {
|
|
const root = owner(item.path);
|
|
const scoped = nativeByRoot.get(root) ?? [];
|
|
scoped.push(item);
|
|
nativeByRoot.set(root, scoped);
|
|
}
|
|
const groups = scriptGroups.map(({ root, left }) => ({
|
|
left,
|
|
right: nativeByRoot.get(root) ?? [],
|
|
}));
|
|
return projectCartesianCandidates({
|
|
groups,
|
|
createCandidate: (source_path, item) => ({
|
|
source_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 convention = nativeRuntimeConvention(path);
|
|
if (convention === "react-native") return "react-native-convention";
|
|
if (convention === "flutter") return "flutter-convention";
|
|
if (convention === "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;
|
|
readonly bridgeCandidateCoverage: AppleApplicationProjectionResult["bridge_candidate_coverage"];
|
|
}): string[] => [
|
|
...(!facts.complete
|
|
? ["Source inventory coverage is partial; 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.",
|
|
]
|
|
: []),
|
|
...(facts.bridgeCandidateCoverage.status === "partial"
|
|
? [
|
|
`Bridge candidate pairs exceeded the projection safety budget; ${facts.bridgeCandidateCoverage.omitted_candidates} hypotheses are omitted. Component arrays still include every component from the supplied inventory pages.`,
|
|
]
|
|
: []),
|
|
"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.",
|
|
"Runtime families are inferred from inventory formats and bounded framework path conventions, not observed runtime loading.",
|
|
"Generic framework and dylib paths do not establish Swift or Objective-C; this inventory projection does not decode language metadata.",
|
|
"Bridge candidates are path-based hypotheses, not observed runtime calls.",
|
|
"A bridge basis is inferred from the native path and is repeated for every managed component.",
|
|
];
|
|
|
|
const compare = compareProjectionStrings;
|
|
const digest = (value: unknown): string =>
|
|
projectionDigest(value, "Apple application projection");
|