VerifiedPluginLoad

VerifiedPluginLoad (VPL) is an Android library for deciding whether an installed or archived plugin APK may supply native code to a host launcher. It verifies APK signing certificates against a signed trust list and records explicit user trust decisions. VPL does not discover plugins, render confirmation UI, or load native libraries.

Security contract

VPL is fail-closed: missing, unreadable, unsigned, banned, or otherwise unverifiable APKs are never reported as loadable. A globally banned current certificate overrides every user decision. Trust-list updates must pass Ed25519 signature, strict schema, and active-version rollback checks.

A successful pre-launch check is not sufficient by itself. The host must inspect the installed package again immediately before consuming its native path and compare the fresh result with the earlier PluginLoadAuthorization. The host is also responsible for keeping every native library path inside the verified package's native library directory.

See Trust model and security boundaries for the complete decision rules and threat model.

Minimal integration

Call VPL from a worker thread or a coroutine running on a non-main dispatcher:

val vpl = VerifiedPluginLoadRegistry.configure(
    context,
    VerifiedPluginLoadConfig(
        storageDirectory = File(context.filesDir, "verified-plugin-load")
    )
)

val initialization = vpl.initialize()
val result = vpl.inspectInstalledPackage(pluginPackageName)

when (result.status) {
    PluginTrustStatus.TRUSTED -> {
        val authorization = requireNotNull(result.toLoadAuthorization())
        // Keep this snapshot in the launch plan. Re-inspect and compare it at the final load point.
    }
    PluginTrustStatus.PENDING_TRUST -> {
        // Show host UI before offering author trust.
    }
    PluginTrustStatus.UNTRUSTED -> {
        // Block by default. A host may offer explicit certificate trust with a strong warning.
    }
    PluginTrustStatus.BANNED,
    PluginTrustStatus.VERIFICATION_FAILED -> {
        // Do not offer a bypass.
    }
}

This configuration uses the signed trust list bundled with VPL. Remote mirrors are optional and must be configured together with their JSON and signature suffixes. The integration guide covers the complete initialization, refresh, confirmation, authorization, and final re-verification flow.

Documentation

• Host integration guide
• Trust model and security boundaries
• Trust-list format, signing, updates, and recovery
• Public API, configuration, and result handling
• Build, test, compatibility, dependencies, and license
• Unresolved project-policy TODOs

Build and test

From this repository:

./gradlew testDebugUnitTest assembleDebug

Android instrumentation tests require a connected API 26 or newer device or emulator:

./gradlew connectedDebugAndroidTest

Third-party libraries and licenses

Runtime dependencies:

• Gson 2.10.1 — Apache License 2.0
• Bouncy Castle bcprov-jdk18on 1.79 — Bouncy Castle Licence (MIT)

Test-only dependencies:

• JUnit 4.13.2 — Eclipse Public License 1.0
• AndroidX Test JUnit 1.2.1 and Runner 1.6.2 — Apache License 2.0

These components remain subject to their respective licenses. See Build, test, compatibility, dependencies, and license for details.

VPL is licensed under the GNU Lesser General Public License v3.0.