From 3f4953bfae3f8ed7caece0b7a1b8cbc09cb8eb88 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 08:38:29 +0800 Subject: [PATCH] feat(android)!: require integrity_check on a JNI library integrity failure (#11624) * feat(android)!: require integrity_check on a JNI library integrity failure A JNI library failure is now a tagged union: kind integrity carries a required integrity_check, and no other kind carries one. The producer builds it from the reader failure, whose integrity constructor requires the check since #11505. Also drop the stale "evidence produced before this field" clause from the electron_semantics comment; earlier Evidence revisions are refused. BREAKING CHANGE: Android JNI Evidence whose library failure has kind "integrity" must name integrity_check. Records written before #11191 that lack it no longer parse; recreate them. Refs #10510 * test(android): check the JNI failure union in its JSON Schema and the unnamed-check refusal Exclude integrity from the other failure kinds with excludedValues, so the JSON Schema conversion declares the exclusion that a bare refine dropped. The test checks the converted schema against the same valid and malformed records, and drives an integrity read failure with an explicitly undefined check: the read is refused, the reader is closed and every checkpoint parses. --- src/android/AndroidJniLibraries.ts | 32 ++++++---- src/domain/android/androidJniBindings.ts | 26 +++++--- .../javascriptApplicationAnalysis.ts | 7 +- .../android/androidJniLibraries.test.ts | 64 ++++++++++++++++++- 4 files changed, 105 insertions(+), 24 deletions(-) diff --git a/src/android/AndroidJniLibraries.ts b/src/android/AndroidJniLibraries.ts index 311ae93e33..1eafb9f410 100644 --- a/src/android/AndroidJniLibraries.ts +++ b/src/android/AndroidJniLibraries.ts @@ -24,6 +24,7 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js"; import { errorMessage } from "../kernel/errorMessage.js"; +import { invariantViolation } from "../domain/internalInvariant.js"; /** Bounds cover the live library buffer, completed scan work and retained JSON separately. */ export const ANDROID_JNI_LIBRARY_LIMITS = Object.freeze({ @@ -38,6 +39,25 @@ export interface AndroidJniLibraries { readonly inventory: AndroidJniReport["library_inventory"]; } +/** A library read failure, with the reader check an `integrity` failure names. */ +const jniReadFailure = ( + cause: unknown, +): NonNullable => { + const message = errorMessage(cause); + if (!(cause instanceof ArtifactReaderFailure)) return { kind: "io", message }; + if (cause.reason !== "integrity") return { kind: cause.reason, message }; + if (cause.integrityCheck === undefined) + throw invariantViolation( + "An integrity reader failure reached the JNI inventory without its check.", + { cause }, + ); + return { + kind: "integrity", + message, + integrity_check: cause.integrityCheck, + }; +}; + /** Read each exact ZIP occurrence once from the provider's immutable admitted APK. */ export const readAndroidJniLibraries = async (input: { readonly snapshot: string; @@ -203,17 +223,7 @@ export const readAndroidJniLibraries = async (input: { observation = { ...identity, facts: null, - failure: { - kind: - cause instanceof ArtifactReaderFailure - ? cause.reason - : "io", - message: errorMessage(cause), - ...(cause instanceof ArtifactReaderFailure && - cause.integrityCheck !== undefined - ? { integrity_check: cause.integrityCheck } - : {}), - }, + failure: jniReadFailure(cause), }; } } diff --git a/src/domain/android/androidJniBindings.ts b/src/domain/android/androidJniBindings.ts index f111430aeb..85079aa951 100644 --- a/src/domain/android/androidJniBindings.ts +++ b/src/domain/android/androidJniBindings.ts @@ -1,5 +1,6 @@ import { ARTIFACT_INTEGRITY_CHECKS } from "../artifactOperationError.js"; import { coverageStatusSchema } from "../coverage.js"; +import { excludedValues } from "../schemaConstraints.js"; import { z } from "zod"; import { androidManifestSplitsSchema, @@ -65,15 +66,24 @@ export const androidJniLibraryIdentitySchema = z.strictObject({ compressed_size: count.nullable(), }); /** - * Why one selected library has no facts. `integrity_check` names the reader - * check an `integrity` failure violated; Evidence recorded before this field - * has no check, which means the check is unknown. + * Why one selected library has no facts. An `integrity` failure names the + * reader check it violated in `integrity_check`; no other kind carries one. */ -const androidJniLibraryFailureSchema = z.strictObject({ - kind: z.string(), - message: z.string(), - integrity_check: z.enum(ARTIFACT_INTEGRITY_CHECKS).exactOptional(), -}); +const androidJniLibraryFailureSchema = z.union([ + z.strictObject({ + kind: z.literal("integrity"), + message: z.string(), + integrity_check: z.enum(ARTIFACT_INTEGRITY_CHECKS), + }), + z.strictObject({ + kind: excludedValues( + z.string(), + ["integrity"], + "an integrity failure names its integrity_check", + ), + message: z.string(), + }), +]); export const androidJniLibrarySchema = androidJniLibraryIdentitySchema.extend({ abi_compatibility: z.enum(["consistent", "mismatch", "unknown"]), byte_order: z.enum(["little", "big"]).nullable(), diff --git a/src/domain/javascript/javascriptApplicationAnalysis.ts b/src/domain/javascript/javascriptApplicationAnalysis.ts index aab8c9029b..4ddaf70ee8 100644 --- a/src/domain/javascript/javascriptApplicationAnalysis.ts +++ b/src/domain/javascript/javascriptApplicationAnalysis.ts @@ -67,10 +67,9 @@ const electronBoundarySummarySchema = z.strictObject({ * sources were not fully examined or reported, for example after the result * budget ran out; counts from those sources are unknown, not zero. * - * Absent when no retained fact names an Electron module, or in evidence - * produced before this field existed. Absence is unknown rather than proof - * that the application has no Electron surface: unread sources, failed - * analysis, and dynamic module names can hide one. + * Absent when no retained fact names an Electron module. Absence is unknown + * rather than proof that the application has no Electron surface: unread + * sources, failed analysis, and dynamic module names can hide one. */ electron_semantics: z.enum(["recovered", "partial", "empty"]).exactOptional(), }); diff --git a/tests/boundary/android/androidJniLibraries.test.ts b/tests/boundary/android/androidJniLibraries.test.ts index 8ff33d07c7..a51368d7f1 100644 --- a/tests/boundary/android/androidJniLibraries.test.ts +++ b/tests/boundary/android/androidJniLibraries.test.ts @@ -3,6 +3,8 @@ import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { Uint8ArrayReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js"; import { expect, it, onTestFinished, vi } from "vitest"; +import { Ajv2020 } from "ajv/dist/2020.js"; +import { z } from "zod"; import { readAndroidJniLibraries, ANDROID_JNI_LIBRARY_LIMITS, @@ -24,7 +26,12 @@ import { import { androidPartialObservationSchema } from "../../../src/domain/android/androidPartialObservation.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { jniElfFixture } from "../../fixtures/android/jniElf.js"; -import { ZipArtifactReader } from "../../../src/resources/index.js"; +import { + ArtifactReaderFailure, + ZipArtifactReader, +} from "../../../src/resources/index.js"; +import { InternalInvariantError } from "../../../src/domain/internalInvariant.js"; +import type { ArtifactReaderFailureReason } from "../../../src/resources/ArtifactReader.js"; const OPERATION = "inspect_android_jni_bindings"; const LIBRARY = "lib/arm64-v8a/libfixture.so"; @@ -264,11 +271,66 @@ it("names the reader check when a selected library fails an integrity check", as inventory: result.inventory, }).libraries[0]?.failure, ).toEqual(failure); + // An integrity failure without its check, or a check on another kind, is + // refused by the runtime schema and by its JSON Schema conversion. + const library = result.libraries[0]; + const checkpoint = (failure: unknown) => ({ + scan_state: "completed", + libraries: [{ ...library, failure }], + inventory: result.inventory, + }); + const advertised = new Ajv2020({ strict: false }).compile( + z.toJSONSchema(androidJniLibraryCheckpointSchema, { io: "output" }), + ); + expect(advertised(checkpoint(failure))).toBe(true); + for (const malformed of [ + { kind: "integrity", message: "x" }, + { kind: "io", message: "x", integrity_check: "entry-metadata" }, + ]) { + expect( + androidJniLibraryCheckpointSchema.safeParse(checkpoint(malformed)) + .success, + ).toBe(false); + expect(advertised(checkpoint(malformed))).toBe(false); + } } finally { entries.mockRestore(); } }); +it("refuses an integrity read failure that names no check and releases the reader", async () => { + const source = await fixture(); + // Only the non-literal rebuild constructor can carry an explicit undefined check. + const reason: ArtifactReaderFailureReason = "integrity"; + const open = vi.spyOn(ZipArtifactReader.prototype, "open").mockRejectedValue( + new ArtifactReaderFailure(reason, "unnamed check", { + integrityCheck: undefined, + }), + ); + const close = vi.spyOn(ZipArtifactReader.prototype, "close"); + const observations: AndroidJniLibraryCheckpoint[] = []; + try { + const failure = await read(source, {}, undefined, undefined, (checkpoint) => + observations.push(checkpoint), + ).catch((cause: unknown) => cause); + expect(failure).toBeInstanceOf(Error); + expect( + failure instanceof Error && + [failure, failure.cause].some( + (error) => error instanceof InternalInvariantError, + ), + ).toBe(true); + expect(close).toHaveBeenCalled(); + for (const checkpoint of observations) + expect( + androidJniLibraryCheckpointSchema.safeParse(checkpoint).success, + ).toBe(true); + } finally { + open.mockRestore(); + close.mockRestore(); + } +}); + it("retains the live reader after failed close and gates the next read on its cleanup retry", async () => { const source = await fixture(); const originalClose = ZipArtifactReader.prototype.close;