Skip to content

api-results.md

Latest commit

 

History

History
96 lines (72 loc) · 5.92 KB

api-results.md

File metadata and controls

96 lines (72 loc) · 5.92 KB
Raw

Public API, Configuration, and Result Handling

The public API is exposed from com.vpl.verifiedpluginload.api and result models from com.vpl.verifiedpluginload.model.

Configuration

VerifiedPluginLoadConfig fields:

Field Default Constraint and meaning
storageDirectory Required Private directory for trust-list and user-trust state.
trustListUrlPrefixes Empty Zero to eight unique HTTPS prefixes. Credentials, query strings, and fragments are rejected.
trustListJsonSuffix Null Relative JSON path; required exactly when prefixes are present.
trustListSignatureSuffix Null Relative detached-signature path; required exactly when prefixes are present.
networkTimeoutMillis 5000 From 1000 through 30000 milliseconds; used for connect and read timeouts.
maxTrustListBytes 1048576 From 1024 through 4194304 bytes.

Prefixes are trimmed and trailing slashes are removed. Suffixes are trimmed, leading slashes are removed, and absolute paths, authorities, fragments, and . or .. path segments are rejected.

Instance creation

  • VerifiedPluginLoadFactory.create(context, config) creates an independent instance.
  • VerifiedPluginLoadRegistry.configure(context, config) creates and stores the process-wide instance used by get().
  • VerifiedPluginLoadRegistry.get(context) returns the configured instance or creates a local-only default instance under filesDir/verified-plugin-load.
  • clearForTests() clears only the process-wide reference; it does not delete persisted files.

Hosts with a final native-load guard should use the registry so every stage observes the same store and configuration.

Inspection APIs

  • inspectInstalledPackage(packageName) reads Android package metadata and current/history signing certificates.
  • inspectApkFile(apkFile) reads an archive before installation.
  • PluginVerificationResult.isLoadAllowed is true only for TRUSTED.
  • toLoadAuthorization() returns null unless the result is trusted and contains a package name, APK path, and at least one current certificate.

Important result fields include package identity, all and current certificate hashes, signature history flags, matched author/key information, trust source, selected trust-list source/version, and a diagnostic.

Initialization result

InitializationResult reports:

Field Meaning
trustListSource CURRENT, PREVIOUS, or BUILTIN source selected after verification.
trustListVersion Version of the selected list, when available.
diagnostic Most relevant initialization condition.
userTrustRecoveredFromCorruption Whether the user-trust store recovered after detecting invalid current data.

TrustListSource.UNAVAILABLE is part of the model enum but is not currently emitted by VerifiedPluginLoadImpl; the implementation selects a verified current, previous, or bundled list, or propagates an initialization failure.

Refresh result

Status Meaning Recommended handling
UPDATED A downloaded pair was verified and installed. Continue with the returned version.
NOT_MODIFIED The single configured origin returned HTTP 304. Continue with the local list.
NOT_CONFIGURED Remote fields were intentionally omitted. Continue with the local or bundled list.
REJECTED_SIGNATURE No accepted candidate had a valid detached signature. Keep the existing list; record a security-relevant update failure.
REJECTED_SCHEMA Signed or downloaded content failed strict parsing. Keep the existing list; correct the published payload.
REJECTED_ROLLBACK A candidate version was below the active baseline. Keep the existing list; investigate mirror consistency.
NETWORK_ERROR Mirrors did not return a usable response. Keep the existing list and retry later.
STORAGE_ERROR Valid content could not be staged or installed, or another non-network internal failure occurred. Keep the existing list and surface an operational error.

message is diagnostic text and should not be used as a stable programmatic identifier.

Trust actions

Status Meaning
SUCCESS The requested trust mutation was persisted.
NOT_FOUND A revoke target was already absent.
INVALID_AUTHOR_UUID The supplied author identifier is not a valid UUID.
INVALID_KEY_HASH The supplied fingerprint is malformed or incomplete.
AUTHOR_NOT_REGISTERED Author trust was requested for an author absent from the active list.
AUTHOR_NOT_TRUSTABLE The author is registered but not eligible for author-level trust or has no active certificate.
KEY_BANNED Direct trust was requested for a certificate currently marked banned.
STORAGE_ERROR The mutation could not be persisted.

Every TrustActionResult includes the resulting or current UserTrustSnapshot. Only SUCCESS proves a requested addition was stored. For revocation, SUCCESS and NOT_FOUND both mean the target is absent.

Verification diagnostics

Diagnostic Meaning
NONE No higher-priority diagnostic applies.
PACKAGE_NOT_FOUND Android could not resolve the installed package.
APK_UNREADABLE An archive path was absent or unreadable.
APK_UNSIGNED No current signing certificate was available.
SIGNATURE_EXTRACTION_FAILED Package-manager or certificate extraction failed.
TRUST_LIST_FALLBACK_TO_BUILTIN Local current/previous data was unavailable and the bundled pair was selected.
TRUST_LIST_UPDATE_FAILED The most recent update attempt failed.
TRUST_LIST_EXPIRED The selected list is past its declared expiry.
USER_TRUST_STORE_RECOVERED Current user-trust data was invalid and recovery was used or attempted.
NOT_INITIALIZED Reserved diagnostic value for integrations that need to represent an uninitialized state.

Diagnostics provide context and never grant load permission.