* feat(native): admit raw binaries with caller-supplied architecture and entry * fix(native): honor raw-binary preparation and entry identity * fix(ghidra): stream raw snapshot attestation with cancellation * fix(native): preserve and validate raw lifecycle entries --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
854 lines
27 KiB
TypeScript
854 lines
27 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
|
|
import canonicalize from "canonicalize";
|
|
import { z } from "zod";
|
|
|
|
import {
|
|
compareUnicodeCodePoints,
|
|
compositeKey,
|
|
} from "./unicodeCodePointOrder.js";
|
|
import { localPathStringSchema } from "./localPath.js";
|
|
|
|
import {
|
|
analysisProfileSchema,
|
|
analysisProfilesEqual,
|
|
committedProviderSchema,
|
|
type AnalysisProfileCommitment,
|
|
} from "./analysisProfile.js";
|
|
import {
|
|
BINARY_ARCHITECTURES,
|
|
type BinaryTarget,
|
|
} from "./binaryTargetTypes.js";
|
|
import {
|
|
evidenceBundleForTarget,
|
|
evidenceBundleSchema,
|
|
parseEvidenceBundle,
|
|
parseImmutableEvidenceBundle,
|
|
} from "./evidenceBundle.js";
|
|
import {
|
|
evidenceLocationSchema,
|
|
type Evidence,
|
|
type EvidenceLocation,
|
|
type EvidenceSubjectTarget,
|
|
} from "./evidence.js";
|
|
import {
|
|
jsonObjectSchema,
|
|
jsonValueSchema,
|
|
type JsonValue,
|
|
} from "./jsonValue.js";
|
|
import { digestSchema } from "./../domain/digests.js";
|
|
import { prefixedDigestSchema } from "./../domain/digests.js";
|
|
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
|
|
import { freezeJsonSnapshot } from "./immutableJson.js";
|
|
import { rawBinaryEntryPointSchema } from "./rawBinary.js";
|
|
|
|
const architectureSchema = z.enum(BINARY_ARCHITECTURES);
|
|
const formatSchema = z.enum([
|
|
"analysis-database",
|
|
"mach-o",
|
|
"elf",
|
|
"pe",
|
|
"dos-mz",
|
|
"dos-com",
|
|
"raw-binary",
|
|
"zip",
|
|
"ipa",
|
|
"apk",
|
|
"msix",
|
|
"appx",
|
|
"hap",
|
|
"hsp",
|
|
"app-pack",
|
|
"asar",
|
|
"dmg",
|
|
"pkg",
|
|
"plist",
|
|
"javascript",
|
|
"source-map",
|
|
]);
|
|
const kindSchema = z.enum(["executable", "database", "archive", "artifact"]);
|
|
const subjectSchema = z.object({
|
|
path: localPathStringSchema,
|
|
sha256: digestSchema,
|
|
format: z.enum([
|
|
...formatSchema.options,
|
|
"hopper",
|
|
"directory",
|
|
"file",
|
|
"unknown",
|
|
"mach-o-universal",
|
|
"javascript-bundle",
|
|
"entitlements",
|
|
]),
|
|
architecture: architectureSchema.nullable(),
|
|
});
|
|
const targetIdentitySchema = z.object({
|
|
sha256: digestSchema,
|
|
kind: kindSchema,
|
|
architecture: architectureSchema.nullable(),
|
|
});
|
|
const targetSchema = z.discriminatedUnion("format", [
|
|
targetIdentitySchema.extend({
|
|
format: z.enum(
|
|
formatSchema.options.filter((format) => format !== "raw-binary"),
|
|
),
|
|
}),
|
|
targetIdentitySchema.extend({
|
|
format: z.literal("raw-binary"),
|
|
entry_point: rawBinaryEntryPointSchema,
|
|
}),
|
|
]);
|
|
const bindingSchema = z
|
|
.object({
|
|
provider: committedProviderSchema,
|
|
analysis_profile: analysisProfileSchema,
|
|
})
|
|
.superRefine((binding, context) => {
|
|
if (
|
|
binding.provider.id !== binding.analysis_profile.provider.id ||
|
|
binding.provider.name !== binding.analysis_profile.provider.name ||
|
|
binding.provider.version !== binding.analysis_profile.provider.version
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["provider"],
|
|
message: "Snapshot binding provider does not match analysis profile",
|
|
});
|
|
});
|
|
const entrySchema = z.object({
|
|
query_id: prefixedDigestSchema("query"),
|
|
operation: z.string().min(1),
|
|
parameters: jsonObjectSchema,
|
|
execution: z.object({
|
|
result: jsonValueSchema,
|
|
raw_result: jsonValueSchema.nullable(),
|
|
provider: committedProviderSchema,
|
|
limitations: z.array(z.string()),
|
|
locations: z.array(evidenceLocationSchema),
|
|
subject: subjectSchema.nullable(),
|
|
}),
|
|
});
|
|
const workflowEntrySchema = z.object({
|
|
query_id: prefixedDigestSchema("query"),
|
|
operation: z.string().min(1),
|
|
parameters: jsonObjectSchema,
|
|
execution: z.object({
|
|
result: jsonValueSchema,
|
|
raw_result: jsonValueSchema.nullable(),
|
|
provider: committedProviderSchema,
|
|
analysis_profile: analysisProfileSchema,
|
|
limitations: z.array(z.string()),
|
|
locations: z.array(evidenceLocationSchema),
|
|
subject: subjectSchema.nullable(),
|
|
}),
|
|
});
|
|
|
|
/** Provider- and profile-exact cache of successful immutable analysis calls. */
|
|
export const analysisSnapshotSchema = z.object({
|
|
target: targetSchema,
|
|
binding: bindingSchema,
|
|
entries: z.array(entrySchema),
|
|
workflow_entries: z.array(workflowEntrySchema),
|
|
evidence_bundle: evidenceBundleSchema,
|
|
});
|
|
|
|
export type AnalysisSnapshot = z.infer<typeof analysisSnapshotSchema>;
|
|
export type AnalysisSnapshotEntry = z.infer<typeof entrySchema>;
|
|
export type AnalysisSnapshotWorkflowEntry = z.infer<typeof workflowEntrySchema>;
|
|
export type AnalysisSnapshotTarget = z.infer<typeof targetSchema>;
|
|
export type AnalysisSnapshotBinding = z.infer<typeof bindingSchema>;
|
|
|
|
// These handles only represent entries parsed in this realm. File readers can
|
|
// release their payloads while retaining an authenticated comparison operand.
|
|
const preparedEntryBrand = Symbol("prepared-snapshot-entry");
|
|
export interface PreparedSnapshotEntry {
|
|
readonly [preparedEntryBrand]: true;
|
|
}
|
|
type EntryMetadata = Omit<AnalysisSnapshotEntry, "execution"> & {
|
|
readonly execution: Omit<
|
|
AnalysisSnapshotEntry["execution"],
|
|
"result" | "raw_result"
|
|
>;
|
|
};
|
|
type WorkflowMetadata = Omit<AnalysisSnapshotWorkflowEntry, "execution"> & {
|
|
readonly execution: Omit<
|
|
AnalysisSnapshotWorkflowEntry["execution"],
|
|
"result" | "raw_result"
|
|
>;
|
|
};
|
|
type PreparedEntry =
|
|
| {
|
|
readonly kind: "provider";
|
|
readonly entry: EntryMetadata;
|
|
readonly digest: string;
|
|
}
|
|
| {
|
|
readonly kind: "workflow";
|
|
readonly entry: WorkflowMetadata;
|
|
readonly digest: string;
|
|
};
|
|
const preparedEntries = new WeakMap<PreparedSnapshotEntry, PreparedEntry>();
|
|
|
|
/** Capture a cache entry without retaining a second copy of its full payload. */
|
|
export const prepareSnapshotEntry = (
|
|
input: unknown,
|
|
kind: "provider" | "workflow",
|
|
): PreparedSnapshotEntry => {
|
|
const handle: PreparedSnapshotEntry = Object.freeze({
|
|
[preparedEntryBrand]: true as const,
|
|
});
|
|
if (kind === "provider") {
|
|
const entry = entrySchema.parse(input);
|
|
const { result, raw_result, ...execution } = entry.execution;
|
|
preparedEntries.set(handle, {
|
|
kind,
|
|
entry: { ...entry, execution },
|
|
digest: snapshotContentDigest(result, raw_result, execution),
|
|
});
|
|
} else {
|
|
const entry = workflowEntrySchema.parse(input);
|
|
const { result, raw_result, ...execution } = entry.execution;
|
|
preparedEntries.set(handle, {
|
|
kind,
|
|
entry: { ...entry, execution },
|
|
digest: snapshotContentDigest(result, raw_result, execution),
|
|
});
|
|
}
|
|
return handle;
|
|
};
|
|
|
|
const snapshotFileHeaderSchema = z.object({
|
|
target: targetSchema,
|
|
binding: bindingSchema,
|
|
evidence_bundle: z.unknown(),
|
|
});
|
|
|
|
/** Reconstruct file entries only from fully authenticated matching Evidence. */
|
|
export const parsePreparedAnalysisSnapshot = (
|
|
input: unknown,
|
|
entries: readonly PreparedSnapshotEntry[],
|
|
workflowEntries: readonly PreparedSnapshotEntry[],
|
|
): AnalysisSnapshot => {
|
|
const header = snapshotFileHeaderSchema.parse(input);
|
|
const bundle = parseImmutableEvidenceBundle(header.evidence_bundle);
|
|
const providerRows = entries.map((handle) => {
|
|
const row = preparedEntries.get(handle);
|
|
if (row?.kind !== "provider")
|
|
throw new TypeError(
|
|
"Analysis snapshot entry was not parsed in this realm",
|
|
);
|
|
return row;
|
|
});
|
|
const workflowRows = workflowEntries.map((handle) => {
|
|
const row = preparedEntries.get(handle);
|
|
if (row?.kind !== "workflow")
|
|
throw new TypeError(
|
|
"Analysis snapshot workflow entry was not parsed in this realm",
|
|
);
|
|
return row;
|
|
});
|
|
const restored = sealSnapshot(
|
|
restoreSnapshot(header, bundle, providerRows, workflowRows),
|
|
);
|
|
for (const handle of [...entries, ...workflowEntries])
|
|
preparedEntries.delete(handle);
|
|
return restored;
|
|
};
|
|
|
|
const contentDigest = (value: JsonValue): string => {
|
|
const steps = canonicalJsonDigestSteps(value);
|
|
let step = steps.next();
|
|
while (!step.done) step = steps.next();
|
|
return step.value;
|
|
};
|
|
|
|
const snapshotContentDigest = (
|
|
result: JsonValue,
|
|
rawResult: JsonValue | null,
|
|
execution: Pick<
|
|
AnalysisSnapshotEntry["execution"],
|
|
"limitations" | "locations" | "subject"
|
|
>,
|
|
): string => {
|
|
const metadata = jsonObjectSchema.parse({
|
|
limitations: execution.limitations,
|
|
locations: execution.locations,
|
|
subject:
|
|
execution.subject === null
|
|
? null
|
|
: {
|
|
local_path: execution.subject.path,
|
|
sha256: execution.subject.sha256,
|
|
format: execution.subject.format,
|
|
architecture: execution.subject.architecture,
|
|
},
|
|
});
|
|
return contentDigest({
|
|
...metadata,
|
|
normalized_result: result,
|
|
raw_result: rawResult,
|
|
});
|
|
};
|
|
|
|
const evidenceContentDigest = (evidence: Evidence): string => {
|
|
return contentDigest({
|
|
...jsonObjectSchema.parse(evidenceContentMetadata(evidence)),
|
|
normalized_result: evidence.normalized_result,
|
|
raw_result: evidence.raw_result,
|
|
});
|
|
};
|
|
|
|
interface SnapshotExecution {
|
|
readonly result: JsonValue;
|
|
readonly rawResult: JsonValue | null;
|
|
readonly provider: {
|
|
readonly id: string;
|
|
readonly name: string;
|
|
readonly version: string | null;
|
|
};
|
|
readonly analysisProfile?: AnalysisProfileCommitment;
|
|
readonly limitations: readonly string[];
|
|
readonly locations: readonly EvidenceLocation[];
|
|
readonly subject: EvidenceSubjectTarget | null;
|
|
}
|
|
|
|
const canonicalJson = (value: unknown): string => {
|
|
const json = jsonValueSchema.parse(value);
|
|
const encoded = canonicalize(json);
|
|
if (encoded === undefined)
|
|
throw new TypeError("RFC 8785 canonicalization rejected snapshot data");
|
|
return encoded;
|
|
};
|
|
|
|
/** Project a binary into the path-free identity used for cache invalidation. */
|
|
export const snapshotTarget = (
|
|
target: BinaryTarget,
|
|
): AnalysisSnapshotTarget => {
|
|
const identity = {
|
|
sha256: target.sha256,
|
|
kind: target.kind,
|
|
architecture: target.architecture ?? null,
|
|
};
|
|
return target.format === "raw-binary"
|
|
? { ...identity, format: target.format, entry_point: target.entryPoint }
|
|
: { ...identity, format: target.format };
|
|
};
|
|
|
|
/** Build the immutable provider/profile binding used by a cached snapshot. */
|
|
export const snapshotBinding = (
|
|
profile: AnalysisProfileCommitment,
|
|
): AnalysisSnapshotBinding =>
|
|
bindingSchema.parse({
|
|
provider: profile.provider,
|
|
analysis_profile: profile,
|
|
});
|
|
|
|
/** Compare an open binary with the immutable target identity in a snapshot. */
|
|
export const snapshotMatchesTarget = (
|
|
snapshot: AnalysisSnapshotTarget,
|
|
target: BinaryTarget,
|
|
): boolean =>
|
|
snapshot.sha256 === target.sha256 &&
|
|
snapshot.kind === target.kind &&
|
|
snapshot.format === target.format &&
|
|
snapshot.architecture === (target.architecture ?? null) &&
|
|
(snapshot.format !== "raw-binary" ||
|
|
(target.format === "raw-binary" &&
|
|
snapshot.entry_point === target.entryPoint));
|
|
|
|
/** Compare a snapshot binding with the selected concrete analysis profile. */
|
|
export const snapshotMatchesProfile = (
|
|
binding: AnalysisSnapshotBinding,
|
|
profile: AnalysisProfileCommitment,
|
|
): boolean =>
|
|
binding.provider.id === profile.provider.id &&
|
|
binding.provider.name === profile.provider.name &&
|
|
binding.provider.version === profile.provider.version &&
|
|
analysisProfilesEqual(binding.analysis_profile, profile);
|
|
|
|
/** Require an exact target and selected provider/profile cache partition. */
|
|
export const snapshotMatchesBinding = (
|
|
snapshot: Pick<AnalysisSnapshot, "target" | "binding">,
|
|
target: BinaryTarget,
|
|
profile: AnalysisProfileCommitment,
|
|
): boolean =>
|
|
snapshotMatchesTarget(snapshot.target, target) &&
|
|
snapshotMatchesProfile(snapshot.binding, profile);
|
|
|
|
/** Find exact persisted CLI Evidence without starting an analysis provider. */
|
|
export const snapshotEvidenceForQuery = (
|
|
snapshot: AnalysisSnapshot,
|
|
query: {
|
|
readonly target: BinaryTarget;
|
|
readonly bindingProfile: AnalysisProfileCommitment;
|
|
readonly operation: string;
|
|
readonly parameters: Readonly<Record<string, JsonValue>>;
|
|
readonly provider: SnapshotExecution["provider"];
|
|
readonly evidenceProfile: AnalysisProfileCommitment;
|
|
},
|
|
): Evidence | undefined => {
|
|
const {
|
|
target,
|
|
bindingProfile,
|
|
operation,
|
|
parameters,
|
|
provider,
|
|
evidenceProfile,
|
|
} = query;
|
|
if (!snapshotMatchesBinding(snapshot, target, bindingProfile))
|
|
return undefined;
|
|
const encodedParameters = canonicalJson(parameters);
|
|
const queryId = analysisQueryId(
|
|
snapshot.target,
|
|
snapshot.binding,
|
|
operation,
|
|
parameters,
|
|
);
|
|
const entry = snapshot.entries.find(
|
|
(candidate) => candidate.query_id === queryId,
|
|
);
|
|
const workflowEntry = snapshot.workflow_entries.find(
|
|
(candidate) => candidate.query_id === queryId,
|
|
);
|
|
if (entry === undefined && workflowEntry === undefined) return undefined;
|
|
return snapshot.evidence_bundle.records.find(
|
|
(record) =>
|
|
record.subject?.digest.sha256 === target.sha256 &&
|
|
record.operation === operation &&
|
|
record.provider.id === provider.id &&
|
|
record.provider.name === provider.name &&
|
|
record.provider.version === provider.version &&
|
|
record.analysis_profile !== null &&
|
|
analysisProfilesEqual(record.analysis_profile, evidenceProfile) &&
|
|
canonicalJson(record.parameters) === encodedParameters &&
|
|
((entry !== undefined && evidenceMatchesEntry(record, entry, snapshot)) ||
|
|
(workflowEntry !== undefined &&
|
|
evidenceMatchesWorkflowEntry(record, workflowEntry, snapshot))),
|
|
);
|
|
};
|
|
|
|
/** Create one exact replay record for a derived application workflow result. */
|
|
export const createAnalysisSnapshotWorkflowEntry = (input: {
|
|
readonly target: AnalysisSnapshotTarget;
|
|
readonly binding: AnalysisSnapshotBinding;
|
|
readonly operation: string;
|
|
readonly parameters: Readonly<Record<string, JsonValue>>;
|
|
readonly execution: SnapshotExecution & {
|
|
readonly analysisProfile: AnalysisProfileCommitment;
|
|
};
|
|
}): AnalysisSnapshotWorkflowEntry => {
|
|
const { target, binding, operation, parameters, execution } = input;
|
|
if (
|
|
execution.provider.id !== execution.analysisProfile.provider.id ||
|
|
execution.provider.name !== execution.analysisProfile.provider.name ||
|
|
execution.provider.version !== execution.analysisProfile.provider.version
|
|
)
|
|
throw new TypeError(
|
|
"Workflow snapshot execution provider does not match its profile",
|
|
);
|
|
return {
|
|
query_id: analysisQueryId(target, binding, operation, parameters),
|
|
operation,
|
|
parameters: jsonObjectSchema.parse(parameters),
|
|
execution: {
|
|
result: execution.result,
|
|
raw_result: execution.rawResult,
|
|
provider: execution.analysisProfile.provider,
|
|
analysis_profile: execution.analysisProfile,
|
|
limitations: [...execution.limitations],
|
|
locations: [...execution.locations],
|
|
subject:
|
|
execution.subject === null
|
|
? null
|
|
: {
|
|
...execution.subject,
|
|
architecture: execution.subject.architecture ?? null,
|
|
},
|
|
},
|
|
};
|
|
};
|
|
|
|
const evidenceMatchesEntry = (
|
|
evidence: Evidence,
|
|
entry: AnalysisSnapshotEntry,
|
|
snapshot: Pick<AnalysisSnapshot, "target" | "binding">,
|
|
): boolean =>
|
|
isCorrespondingEvidence(evidence, snapshot) &&
|
|
compositeKey([
|
|
evidenceQueryKey(evidence),
|
|
evidenceContentDigest(evidence),
|
|
]) === entryEvidenceKey(entry, snapshot.binding);
|
|
|
|
/** Compute the stable lookup key for one provider/profile-specific query. */
|
|
export const analysisQueryId = (
|
|
target: AnalysisSnapshotTarget,
|
|
binding: AnalysisSnapshotBinding,
|
|
operation: string,
|
|
parameters: Readonly<Record<string, JsonValue>>,
|
|
): string =>
|
|
`query_${createHash("sha256")
|
|
.update(canonicalJson({ target, binding, operation, parameters }))
|
|
.digest("hex")}`;
|
|
|
|
/** Create one serializable snapshot entry from a successful provider call. */
|
|
export const createAnalysisSnapshotEntry = (input: {
|
|
readonly target: AnalysisSnapshotTarget;
|
|
readonly binding: AnalysisSnapshotBinding;
|
|
readonly operation: string;
|
|
readonly parameters: Readonly<Record<string, JsonValue>>;
|
|
readonly execution: SnapshotExecution;
|
|
}): AnalysisSnapshotEntry => {
|
|
const { target, binding, operation, parameters, execution } = input;
|
|
if (
|
|
execution.analysisProfile === undefined ||
|
|
!snapshotMatchesProfile(binding, execution.analysisProfile) ||
|
|
execution.provider.id !== binding.provider.id ||
|
|
execution.provider.name !== binding.provider.name ||
|
|
execution.provider.version !== binding.provider.version
|
|
)
|
|
throw new TypeError(
|
|
"Snapshot execution does not match its provider/profile binding",
|
|
);
|
|
return {
|
|
query_id: analysisQueryId(target, binding, operation, parameters),
|
|
operation,
|
|
parameters: jsonObjectSchema.parse(parameters),
|
|
execution: {
|
|
result: execution.result,
|
|
raw_result: execution.rawResult,
|
|
provider: binding.provider,
|
|
limitations: [...execution.limitations],
|
|
locations: [...execution.locations],
|
|
subject:
|
|
execution.subject === null
|
|
? null
|
|
: {
|
|
...execution.subject,
|
|
architecture: execution.subject.architecture ?? null,
|
|
},
|
|
},
|
|
};
|
|
};
|
|
|
|
const validatedSnapshots = new WeakMap<object, AnalysisSnapshot>();
|
|
|
|
/** Parse a provider/profile-exact snapshot and verify its entries and evidence. */
|
|
export const parseAnalysisSnapshot = (input: unknown): AnalysisSnapshot => {
|
|
if (typeof input === "object" && input !== null) {
|
|
const owned = validatedSnapshots.get(input);
|
|
if (owned !== undefined) return owned;
|
|
}
|
|
const parsed = analysisSnapshotSchema.parse(input);
|
|
restoreSnapshot(
|
|
parsed,
|
|
parseEvidenceBundle(parsed.evidence_bundle),
|
|
parsed.entries.map((entry) => ({
|
|
kind: "provider",
|
|
entry,
|
|
digest: snapshotContentDigest(
|
|
entry.execution.result,
|
|
entry.execution.raw_result,
|
|
entry.execution,
|
|
),
|
|
})),
|
|
parsed.workflow_entries.map((entry) => ({
|
|
kind: "workflow",
|
|
entry,
|
|
digest: snapshotContentDigest(
|
|
entry.execution.result,
|
|
entry.execution.raw_result,
|
|
entry.execution,
|
|
),
|
|
})),
|
|
);
|
|
return parsed;
|
|
};
|
|
|
|
/** Own an authenticated immutable cache while preserving mutable caller exports. */
|
|
export const immutableAnalysisSnapshot = (input: unknown): AnalysisSnapshot =>
|
|
sealSnapshot(parseAnalysisSnapshot(input));
|
|
|
|
const sealSnapshot = (snapshot: AnalysisSnapshot): AnalysisSnapshot => {
|
|
for (const entry of [...snapshot.entries, ...snapshot.workflow_entries]) {
|
|
freezeJsonSnapshot(entry.execution.result);
|
|
freezeJsonSnapshot(entry.execution.raw_result);
|
|
}
|
|
freezeJsonSnapshot(snapshot);
|
|
validatedSnapshots.set(snapshot, snapshot);
|
|
return snapshot;
|
|
};
|
|
|
|
const restoreSnapshot = (
|
|
header: Pick<AnalysisSnapshot, "target" | "binding">,
|
|
bundle: AnalysisSnapshot["evidence_bundle"],
|
|
providerRows: readonly Extract<PreparedEntry, { kind: "provider" }>[],
|
|
workflowRows: readonly Extract<PreparedEntry, { kind: "workflow" }>[],
|
|
): AnalysisSnapshot => {
|
|
const scopedEvidence = evidenceBundleForTarget(bundle, header.target.sha256);
|
|
if (
|
|
scopedEvidence.records.length !== bundle.records.length ||
|
|
scopedEvidence.unknowns.length !== bundle.unknowns.length
|
|
)
|
|
throw new TypeError(
|
|
"Analysis snapshot evidence contains records for another target",
|
|
);
|
|
if (!hasCanonicalQueryOrder(providerRows.map(({ entry }) => entry)))
|
|
throw new TypeError("Analysis snapshot entries are not canonical");
|
|
if (!hasCanonicalQueryOrder(workflowRows.map(({ entry }) => entry)))
|
|
throw new TypeError("Analysis snapshot workflow entries are not canonical");
|
|
const ids = new Set<string>();
|
|
const corresponding = new Set<string>();
|
|
const matching = new Map<string, Evidence>();
|
|
for (const evidence of bundle.records) {
|
|
if (
|
|
evidence.predicate_type !== "rea.analysis" ||
|
|
evidence.authority !== "shipped-artifact" ||
|
|
evidence.subject?.digest.sha256 !== header.target.sha256 ||
|
|
evidence.analysis_profile === null ||
|
|
(evidence.confidence !== "observed" && evidence.confidence !== "derived")
|
|
)
|
|
continue;
|
|
if (
|
|
evidence.confidence === "observed" &&
|
|
!isCorrespondingEvidence(evidence, header)
|
|
)
|
|
continue;
|
|
const query = compositeKey([
|
|
evidence.confidence,
|
|
evidenceQueryKey(evidence),
|
|
]);
|
|
corresponding.add(query);
|
|
matching.set(
|
|
compositeKey([query, evidenceContentDigest(evidence)]),
|
|
evidence,
|
|
);
|
|
}
|
|
const find = (
|
|
query: string,
|
|
digest: string,
|
|
label: string,
|
|
operation: string,
|
|
): Evidence => {
|
|
const evidence = matching.get(compositeKey([query, digest]));
|
|
if (evidence !== undefined) return evidence;
|
|
throw new TypeError(
|
|
corresponding.has(query)
|
|
? `Analysis snapshot ${label} ${operation} differs from its Evidence record`
|
|
: `Analysis snapshot ${label} ${operation} has no profile-bound Evidence record`,
|
|
);
|
|
};
|
|
const checkId = (
|
|
entry: EntryMetadata | WorkflowMetadata,
|
|
workflow: boolean,
|
|
): void => {
|
|
const expected = analysisQueryId(
|
|
header.target,
|
|
header.binding,
|
|
entry.operation,
|
|
entry.parameters,
|
|
);
|
|
if (entry.query_id !== expected)
|
|
throw new TypeError(
|
|
workflow
|
|
? "Analysis snapshot workflow query identifier does not match"
|
|
: "Analysis snapshot query identifier does not match",
|
|
);
|
|
if (ids.has(entry.query_id))
|
|
throw new TypeError("Analysis snapshot contains duplicate queries");
|
|
ids.add(entry.query_id);
|
|
};
|
|
const entries = providerRows.map(({ entry, digest }) => {
|
|
if (
|
|
entry.execution.provider.id !== header.binding.provider.id ||
|
|
entry.execution.provider.name !== header.binding.provider.name ||
|
|
entry.execution.provider.version !== header.binding.provider.version
|
|
)
|
|
throw new TypeError("Analysis snapshot entry provider does not match");
|
|
checkId(entry, false);
|
|
const evidence = find(
|
|
compositeKey(["observed", entryQueryKey(entry, header.binding)]),
|
|
digest,
|
|
"entry",
|
|
entry.operation,
|
|
);
|
|
return {
|
|
...entry,
|
|
execution: {
|
|
...entry.execution,
|
|
result: evidence.normalized_result,
|
|
raw_result: evidence.raw_result,
|
|
},
|
|
};
|
|
});
|
|
const workflow_entries = workflowRows.map(({ entry, digest }) => {
|
|
const provider = entry.execution.analysis_profile.provider;
|
|
if (
|
|
entry.execution.provider.id !== provider.id ||
|
|
entry.execution.provider.name !== provider.name ||
|
|
entry.execution.provider.version !== provider.version
|
|
)
|
|
throw new TypeError(
|
|
"Analysis snapshot workflow entry provider does not match its profile",
|
|
);
|
|
checkId(entry, true);
|
|
const evidence = find(
|
|
compositeKey(["derived", workflowEntryQueryKey(entry)]),
|
|
digest,
|
|
"workflow entry",
|
|
entry.operation,
|
|
);
|
|
return {
|
|
...entry,
|
|
execution: {
|
|
...entry.execution,
|
|
result: evidence.normalized_result,
|
|
raw_result: evidence.raw_result,
|
|
},
|
|
};
|
|
});
|
|
return {
|
|
target: header.target,
|
|
binding: header.binding,
|
|
entries,
|
|
workflow_entries,
|
|
evidence_bundle: bundle,
|
|
};
|
|
};
|
|
|
|
const hasCanonicalQueryOrder = (
|
|
entries: readonly { readonly query_id: string }[],
|
|
): boolean => {
|
|
let previous: string | undefined;
|
|
for (const { query_id: queryId } of entries) {
|
|
if (
|
|
previous !== undefined &&
|
|
compareUnicodeCodePoints(previous, queryId) > 0
|
|
)
|
|
return false;
|
|
previous = queryId;
|
|
}
|
|
return true;
|
|
};
|
|
|
|
const isCorrespondingEvidence = (
|
|
evidence: Evidence,
|
|
snapshot: Pick<AnalysisSnapshot, "target" | "binding">,
|
|
): boolean =>
|
|
evidence.predicate_type === "rea.analysis" &&
|
|
evidence.confidence === "observed" &&
|
|
evidence.authority === "shipped-artifact" &&
|
|
evidence.subject?.digest.sha256 === snapshot.target.sha256 &&
|
|
evidence.analysis_profile !== null &&
|
|
analysisProfilesEqual(
|
|
evidence.analysis_profile,
|
|
snapshot.binding.analysis_profile,
|
|
);
|
|
|
|
const evidenceQueryKey = (evidence: Evidence): string =>
|
|
contentDigest({
|
|
operation: evidence.operation,
|
|
parameters: evidence.parameters,
|
|
provider: evidence.provider,
|
|
analysis_profile: evidence.analysis_profile,
|
|
});
|
|
|
|
const entryQueryKey = (
|
|
entry: Pick<AnalysisSnapshotEntry, "operation" | "parameters"> & {
|
|
readonly execution: Pick<AnalysisSnapshotEntry["execution"], "provider">;
|
|
},
|
|
binding: AnalysisSnapshotBinding,
|
|
): string =>
|
|
contentDigest({
|
|
operation: entry.operation,
|
|
parameters: entry.parameters,
|
|
provider: entry.execution.provider,
|
|
analysis_profile: binding.analysis_profile,
|
|
});
|
|
|
|
const entryEvidenceKey = (
|
|
entry: AnalysisSnapshotEntry,
|
|
binding: AnalysisSnapshotBinding,
|
|
): string =>
|
|
compositeKey([
|
|
entryQueryKey(entry, binding),
|
|
snapshotContentDigest(
|
|
entry.execution.result,
|
|
entry.execution.raw_result,
|
|
entry.execution,
|
|
),
|
|
]);
|
|
|
|
const workflowEntryQueryKey = (
|
|
entry: Pick<AnalysisSnapshotWorkflowEntry, "operation" | "parameters"> & {
|
|
readonly execution: Pick<
|
|
AnalysisSnapshotWorkflowEntry["execution"],
|
|
"provider" | "analysis_profile"
|
|
>;
|
|
},
|
|
): string =>
|
|
contentDigest({
|
|
operation: entry.operation,
|
|
parameters: entry.parameters,
|
|
provider: entry.execution.provider,
|
|
analysis_profile: entry.execution.analysis_profile,
|
|
});
|
|
|
|
const workflowEntryEvidenceKey = (
|
|
entry: AnalysisSnapshotWorkflowEntry,
|
|
): string =>
|
|
compositeKey([
|
|
workflowEntryQueryKey(entry),
|
|
snapshotContentDigest(
|
|
entry.execution.result,
|
|
entry.execution.raw_result,
|
|
entry.execution,
|
|
),
|
|
]);
|
|
|
|
const isWorkflowEvidence = (
|
|
evidence: Evidence,
|
|
snapshot: Pick<AnalysisSnapshot, "target">,
|
|
entry: AnalysisSnapshotWorkflowEntry,
|
|
): boolean =>
|
|
evidence.predicate_type === "rea.analysis" &&
|
|
evidence.confidence === "derived" &&
|
|
evidence.authority === "shipped-artifact" &&
|
|
evidence.subject?.digest.sha256 === snapshot.target.sha256 &&
|
|
evidence.analysis_profile !== null &&
|
|
analysisProfilesEqual(
|
|
evidence.analysis_profile,
|
|
entry.execution.analysis_profile,
|
|
) &&
|
|
evidence.provider.id === entry.execution.provider.id &&
|
|
evidence.provider.name === entry.execution.provider.name &&
|
|
evidence.provider.version === entry.execution.provider.version;
|
|
|
|
const evidenceMatchesWorkflowEntry = (
|
|
evidence: Evidence,
|
|
entry: AnalysisSnapshotWorkflowEntry,
|
|
snapshot: Pick<AnalysisSnapshot, "target">,
|
|
): boolean =>
|
|
isWorkflowEvidence(evidence, snapshot, entry) &&
|
|
compositeKey([
|
|
evidenceQueryKey(evidence),
|
|
evidenceContentDigest(evidence),
|
|
]) === workflowEntryEvidenceKey(entry);
|
|
|
|
const evidenceContentMetadata = (evidence: Evidence) => ({
|
|
limitations: evidence.limitations,
|
|
locations: evidence.locations,
|
|
subject:
|
|
evidence.subject === null
|
|
? null
|
|
: {
|
|
local_path: evidence.subject.local_path,
|
|
sha256: evidence.subject.digest.sha256,
|
|
format: evidence.subject.format,
|
|
architecture: evidence.subject.architecture,
|
|
},
|
|
});
|
|
|
|
/** Serialize a validated snapshot with byte-stable canonical entry ordering. */
|
|
export const serializeAnalysisSnapshot = (snapshot: AnalysisSnapshot): string =>
|
|
`${canonicalJson(parseAnalysisSnapshot(snapshot))}\n`;
|