455 lines
15 KiB
TypeScript
455 lines
15 KiB
TypeScript
import { basename } from "node:path";
|
|
import { z } from "zod";
|
|
|
|
import { digestCanonicalValue } from "./canonicalDigest.js";
|
|
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
|
|
import { nulFreeStringSchema } from "./localPath.js";
|
|
|
|
import {
|
|
analysisProfileSchema,
|
|
type AnalysisProfileCommitment,
|
|
} from "./analysisProfile.js";
|
|
import {
|
|
BINARY_ARCHITECTURES,
|
|
type BinaryArchitecture,
|
|
type BinaryTarget,
|
|
} from "./binaryTargetTypes.js";
|
|
import {
|
|
jsonObjectSchema,
|
|
jsonValueSchema,
|
|
jsonValueValidationIssue,
|
|
jsonValueValidationSteps,
|
|
type JsonValue,
|
|
} from "./jsonValue.js";
|
|
import {
|
|
freezeJsonSnapshot,
|
|
isImmutableJsonSnapshot,
|
|
} from "./immutableJson.js";
|
|
import { digestSchema } from "./../domain/digests.js";
|
|
import { prefixedDigestSchema } from "./../domain/digests.js";
|
|
import {
|
|
relationshipCoverageSchema,
|
|
type RelationshipCoverage,
|
|
} from "./relationshipCoverage.js";
|
|
|
|
/** Provider identity schema shared by evidence-bearing persistence formats. */
|
|
export const providerSchema = z.strictObject({
|
|
id: z.string().min(1),
|
|
name: z.string().min(1),
|
|
version: z.string().nullable(),
|
|
});
|
|
const subjectFormatSchema = z.enum([
|
|
"hopper",
|
|
"analysis-database",
|
|
"mach-o",
|
|
"elf",
|
|
"pe",
|
|
"dos-mz",
|
|
"dos-com",
|
|
"raw-binary",
|
|
"zip",
|
|
"ipa",
|
|
"apk",
|
|
"msix",
|
|
"appx",
|
|
"hap",
|
|
"hsp",
|
|
"app-pack",
|
|
"asar",
|
|
"ines",
|
|
"dmg",
|
|
"pkg",
|
|
"plist",
|
|
"javascript",
|
|
"source-map",
|
|
"directory",
|
|
"file",
|
|
"unknown",
|
|
"mach-o-universal",
|
|
"javascript-bundle",
|
|
"entitlements",
|
|
]);
|
|
const subjectBaseSchema = z.strictObject({
|
|
name: z.string().min(1),
|
|
digest: z.strictObject({ sha256: digestSchema }),
|
|
local_path: nulFreeStringSchema,
|
|
});
|
|
// The format owns the architecture claim, including nested Evidence subjects.
|
|
const subjectSchema = z.discriminatedUnion("format", [
|
|
subjectBaseSchema.extend({
|
|
format: subjectFormatSchema.exclude(["raw-binary"]),
|
|
architecture: z.enum(BINARY_ARCHITECTURES).exclude(["6502"]).nullable(),
|
|
}),
|
|
subjectBaseSchema.extend({
|
|
format: z.literal("raw-binary"),
|
|
architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
|
|
}),
|
|
]);
|
|
/** Source location attached to an evidence observation. */
|
|
/** Source-location schema shared by evidence-bearing persistence formats. */
|
|
export const evidenceLocationSchema = z.discriminatedUnion("kind", [
|
|
z.strictObject({ kind: z.literal("address"), address: z.string().min(1) }),
|
|
z.strictObject({
|
|
kind: z.literal("address-range"),
|
|
start: z.string().min(1),
|
|
end: z.string().min(1),
|
|
}),
|
|
z.strictObject({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
|
|
z.strictObject({
|
|
kind: z.literal("file-offset"),
|
|
offset: z.number().int().min(0),
|
|
}),
|
|
z.strictObject({
|
|
kind: z.literal("file-offset-range"),
|
|
start: z.number().int().min(0),
|
|
end: z.number().int().min(0),
|
|
}),
|
|
]);
|
|
|
|
const evidenceAuthoritySchema = z.enum([
|
|
"shipped-artifact",
|
|
"controlled-replay",
|
|
"historical-reference",
|
|
"external-service",
|
|
"analyst-inference",
|
|
]);
|
|
|
|
const executionEnvironmentSchema = z.strictObject({
|
|
id: z.string().min(1),
|
|
platform: z.string().min(1),
|
|
architecture: z.string().min(1),
|
|
isolation: z.enum(["none", "process", "container", "virtual-machine"]),
|
|
});
|
|
|
|
const evidenceBaseSchema = z
|
|
.object({
|
|
evidence_id: prefixedDigestSchema("ev"),
|
|
subject: subjectSchema.nullable(),
|
|
provider: providerSchema,
|
|
analysis_profile: analysisProfileSchema.nullable(),
|
|
predicate_type: z.string().min(1),
|
|
operation: z.string().min(1),
|
|
parameters: jsonObjectSchema,
|
|
raw_result: jsonValueSchema.nullable(),
|
|
normalized_result: jsonValueSchema,
|
|
confidence: z.enum(["observed", "derived", "inferred"]),
|
|
authority: evidenceAuthoritySchema,
|
|
environment: executionEnvironmentSchema.nullable(),
|
|
limitations: z.array(z.string()),
|
|
relationship_coverage: relationshipCoverageSchema.nullable().default(null),
|
|
locations: z.array(evidenceLocationSchema),
|
|
evidence_links: z.array(prefixedDigestSchema("ev")),
|
|
})
|
|
.strict();
|
|
|
|
/** Require a reported analysis profile to identify the observation provider. */
|
|
export const validateAnalysisProfileProvider = (
|
|
evidence: Pick<
|
|
z.infer<typeof evidenceBaseSchema>,
|
|
"analysis_profile" | "provider"
|
|
>,
|
|
context: z.RefinementCtx,
|
|
): void => {
|
|
const profile = evidence.analysis_profile;
|
|
if (
|
|
profile !== null &&
|
|
(profile.provider.id !== evidence.provider.id ||
|
|
profile.provider.name !== evidence.provider.name ||
|
|
profile.provider.version !== evidence.provider.version)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["analysis_profile", "provider"],
|
|
message: "Analysis profile provider does not match Evidence provider",
|
|
});
|
|
};
|
|
|
|
/** Strict, provider-neutral record for one successful public observation. */
|
|
export const evidenceSchema = evidenceBaseSchema.superRefine(
|
|
validateAnalysisProfileProvider,
|
|
);
|
|
|
|
const authenticatedEvidenceSchema = evidenceSchema.superRefine(
|
|
(evidence, context) => {
|
|
const { evidence_id: evidenceId, ...withoutId } = evidence;
|
|
if (computeEvidenceId(withoutId) !== evidenceId)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["evidence_id"],
|
|
message: "Evidence semantic identifier does not match its record",
|
|
});
|
|
},
|
|
);
|
|
|
|
/** Complete observation whose normalized payload retains its operation-specific type. */
|
|
type EvidenceSchemaValue = z.infer<typeof evidenceSchema>;
|
|
export type Evidence<Result extends JsonValue = JsonValue> =
|
|
EvidenceSchemaValue & {
|
|
readonly normalized_result: Result;
|
|
};
|
|
const immutableEvidenceSnapshots = new WeakMap<object, Evidence>();
|
|
const immutableResultSchema = z
|
|
.custom<JsonValue>(isImmutableJsonSnapshot)
|
|
.superRefine((value, context) => {
|
|
const issue = jsonValueValidationIssue(value);
|
|
if (issue !== undefined)
|
|
context.addIssue({ code: "custom", message: issue });
|
|
});
|
|
export type EvidenceLocation = z.infer<typeof evidenceLocationSchema>;
|
|
|
|
/** Candidate local artifact identity validated by the Evidence subject schema. */
|
|
export interface EvidenceSubjectTarget {
|
|
readonly path: string;
|
|
readonly sha256: string;
|
|
readonly format: z.infer<typeof subjectSchema>["format"];
|
|
readonly architecture?: BinaryArchitecture;
|
|
}
|
|
|
|
/** Rebind a matching immutable artifact subject to the caller's selected path. */
|
|
export const rebindEvidenceSubjectTargetPath = (
|
|
subject: EvidenceSubjectTarget,
|
|
target: EvidenceSubjectTarget,
|
|
): EvidenceSubjectTarget =>
|
|
subject.sha256 === target.sha256 &&
|
|
subject.format === target.format &&
|
|
(subject.architecture ?? null) === (target.architecture ?? null)
|
|
? { ...subject, path: target.path }
|
|
: subject;
|
|
|
|
type EvidenceAuthority = z.infer<typeof evidenceAuthoritySchema>;
|
|
type ExecutionEnvironment = z.infer<typeof executionEnvironmentSchema>;
|
|
|
|
export interface EvidenceProvider {
|
|
readonly id: string;
|
|
readonly name: string;
|
|
readonly version: string | null;
|
|
}
|
|
|
|
export interface EvidenceObservation {
|
|
readonly predicateType?: string;
|
|
readonly operation: string;
|
|
readonly parameters: Readonly<Record<string, JsonValue>>;
|
|
readonly result: JsonValue;
|
|
readonly analysisProfile?: AnalysisProfileCommitment;
|
|
readonly rawResult?: JsonValue;
|
|
readonly confidence?: "observed" | "derived" | "inferred";
|
|
readonly authority?: EvidenceAuthority;
|
|
readonly environment?: ExecutionEnvironment | null;
|
|
readonly limitations?: readonly string[];
|
|
readonly relationshipCoverage?: RelationshipCoverage;
|
|
/** Reason the subject identity is unavailable, when no target identity is supplied. */
|
|
readonly subjectUnavailableReason?: string;
|
|
readonly locations?: readonly EvidenceLocation[];
|
|
readonly evidenceLinks?: readonly string[];
|
|
}
|
|
|
|
type EvidenceWithoutId = Omit<EvidenceSchemaValue, "evidence_id">;
|
|
|
|
const semanticProjection = (evidence: EvidenceWithoutId): JsonValue => ({
|
|
subject:
|
|
evidence.subject === null
|
|
? null
|
|
: {
|
|
digest: evidence.subject.digest,
|
|
format: evidence.subject.format,
|
|
architecture: evidence.subject.architecture,
|
|
},
|
|
provider: evidence.provider,
|
|
analysis_profile: evidence.analysis_profile,
|
|
predicate_type: evidence.predicate_type,
|
|
operation: evidence.operation,
|
|
parameters: evidence.parameters,
|
|
raw_result: evidence.raw_result,
|
|
normalized_result: evidence.normalized_result,
|
|
confidence: evidence.confidence,
|
|
authority: evidence.authority,
|
|
environment: evidence.environment,
|
|
limitations: evidence.limitations,
|
|
...(evidence.relationship_coverage === null
|
|
? {}
|
|
: { relationship_coverage: evidence.relationship_coverage }),
|
|
locations: evidence.locations,
|
|
evidence_links: evidence.evidence_links,
|
|
});
|
|
|
|
/** Hash semantic content, including raw results and excluding display-subject fields. */
|
|
const computeEvidenceId = (evidence: EvidenceWithoutId): string =>
|
|
`ev_${digestCanonicalValue(semanticProjection(evidence), "Evidence")}`;
|
|
|
|
/** Parse evidence and reject a syntactically valid but tampered semantic ID. */
|
|
export const parseEvidence = (input: unknown): Evidence => {
|
|
const immutable =
|
|
typeof input === "object" && input !== null
|
|
? immutableEvidenceSnapshots.get(input)
|
|
: undefined;
|
|
if (immutable !== undefined) return immutable;
|
|
return authenticatedEvidenceSchema.parse(input);
|
|
};
|
|
|
|
/** Authenticate and seal a ledger-owned snapshot; external mutable values are copied first. */
|
|
export const immutableEvidence = (input: unknown): Evidence =>
|
|
rememberImmutableEvidence(parseEvidence(input));
|
|
|
|
/** Rebind display path metadata when an authenticated record names this target. */
|
|
export const rebindEvidenceToTargetPath = (
|
|
evidence: Evidence,
|
|
target: EvidenceSubjectTarget,
|
|
): Evidence => {
|
|
const subject = evidence.subject;
|
|
if (subject === null) return evidence;
|
|
const rebound = rebindEvidenceSubjectTargetPath(
|
|
{
|
|
path: subject.local_path,
|
|
sha256: subject.digest.sha256,
|
|
format: subject.format,
|
|
...(subject.architecture === null
|
|
? {}
|
|
: { architecture: subject.architecture }),
|
|
},
|
|
target,
|
|
);
|
|
if (rebound.path === subject.local_path) return evidence;
|
|
const reboundSubject = subjectSchema.parse({
|
|
...subject,
|
|
name: basename(target.path) || "artifact",
|
|
local_path: target.path,
|
|
});
|
|
const reboundEvidence = { ...evidence, subject: reboundSubject };
|
|
if (!isImmutableEvidence(evidence)) return immutableEvidence(reboundEvidence);
|
|
|
|
// The original authenticated Evidence owns immutable payloads. Only the
|
|
// small display subject and envelope are new, so preserve those payloads
|
|
// without reparsing a potentially large analysis result.
|
|
Object.freeze(reboundSubject.digest);
|
|
Object.freeze(reboundSubject);
|
|
Object.freeze(reboundEvidence);
|
|
immutableEvidenceSnapshots.set(reboundEvidence, reboundEvidence);
|
|
return reboundEvidence;
|
|
};
|
|
|
|
/** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */
|
|
export const isImmutableEvidence = (evidence: Evidence): boolean =>
|
|
immutableEvidenceSnapshots.has(evidence);
|
|
|
|
const rememberImmutableEvidence = (evidence: Evidence): Evidence => {
|
|
freezeJsonSnapshot(evidence);
|
|
immutableEvidenceSnapshots.set(evidence, evidence);
|
|
return evidence;
|
|
};
|
|
|
|
/** Build deterministic Evidence from an immutable artifact subject. */
|
|
export const createEvidence = (
|
|
target: EvidenceSubjectTarget | BinaryTarget | undefined,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservation,
|
|
): Evidence => {
|
|
const { normalized, sharedResult } = normalizeEvidenceObservation(
|
|
target,
|
|
provider,
|
|
observation,
|
|
);
|
|
const evidence = {
|
|
...normalized,
|
|
evidence_id: computeEvidenceId(normalized),
|
|
};
|
|
return sharedResult ? rememberImmutableEvidence(evidence) : evidence;
|
|
};
|
|
|
|
/** Create Evidence from owned immutable JSON while exposing cooperative computation steps. */
|
|
export function* createImmutableEvidenceSteps(
|
|
target: EvidenceSubjectTarget | BinaryTarget | undefined,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservation,
|
|
): Generator<void, Evidence> {
|
|
if (!isImmutableJsonSnapshot(observation.result))
|
|
throw new TypeError(
|
|
"Cooperative Evidence requires an authenticated immutable result",
|
|
);
|
|
// The envelope parser below retains its usual diagnostics, using the completed
|
|
// immutable validation rather than traversing the payload synchronously again.
|
|
yield* jsonValueValidationSteps(observation.result);
|
|
const { normalized } = normalizeEvidenceObservation(
|
|
target,
|
|
provider,
|
|
observation,
|
|
);
|
|
const digest = yield* canonicalJsonDigestSteps(
|
|
semanticProjection(normalized),
|
|
);
|
|
return rememberImmutableEvidence({
|
|
...normalized,
|
|
evidence_id: `ev_${digest}`,
|
|
});
|
|
}
|
|
|
|
const normalizeEvidenceObservation = (
|
|
target: EvidenceSubjectTarget | BinaryTarget | undefined,
|
|
provider: EvidenceProvider,
|
|
observation: EvidenceObservation,
|
|
) => {
|
|
const subject =
|
|
target === undefined
|
|
? null
|
|
: {
|
|
name: basename(target.path) || "artifact",
|
|
digest: { sha256: target.sha256 },
|
|
format: target.format,
|
|
architecture: target.architecture ?? null,
|
|
local_path: target.path,
|
|
};
|
|
const semantic = {
|
|
subject:
|
|
subject === null
|
|
? null
|
|
: {
|
|
digest: subject.digest,
|
|
format: subject.format,
|
|
architecture: subject.architecture,
|
|
},
|
|
provider: {
|
|
id: provider.id,
|
|
name: provider.name,
|
|
version: provider.version,
|
|
},
|
|
analysis_profile: observation.analysisProfile ?? null,
|
|
predicate_type: observation.predicateType ?? "rea.analysis",
|
|
operation: observation.operation,
|
|
parameters: observation.parameters,
|
|
raw_result: observation.rawResult ?? null,
|
|
normalized_result: observation.result,
|
|
confidence: observation.confidence ?? "observed",
|
|
authority: observation.authority ?? "shipped-artifact",
|
|
environment: observation.environment ?? null,
|
|
limitations: [
|
|
...(target === undefined
|
|
? [
|
|
observation.subjectUnavailableReason ??
|
|
"Artifact identity is unavailable for this observation.",
|
|
]
|
|
: []),
|
|
...(observation.limitations ?? []),
|
|
],
|
|
...(observation.relationshipCoverage === undefined
|
|
? { relationship_coverage: null }
|
|
: { relationship_coverage: observation.relationshipCoverage }),
|
|
locations: [...(observation.locations ?? [])],
|
|
evidence_links: [...(observation.evidenceLinks ?? [])],
|
|
} satisfies JsonValue;
|
|
const sharedResult =
|
|
typeof observation.result === "object" &&
|
|
observation.result !== null &&
|
|
isImmutableJsonSnapshot(observation.result);
|
|
const selectedSchema = sharedResult
|
|
? evidenceSchema.safeExtend({ normalized_result: immutableResultSchema })
|
|
: evidenceSchema;
|
|
const normalized = selectedSchema.parse({
|
|
...semantic,
|
|
evidence_id: `ev_${"0".repeat(64)}`,
|
|
subject,
|
|
});
|
|
// The envelope has already been parsed into an independent snapshot. Only
|
|
// its derived identifier changes here; parsing again clones the full payload
|
|
// and recomputes the same digest while the previous snapshot is still live.
|
|
return { normalized, sharedResult };
|
|
};
|