Skip to content

trust-model.md

Latest commit

 

History

History
88 lines (54 loc) · 5.78 KB

trust-model.md

File metadata and controls

88 lines (54 loc) · 5.78 KB
Raw

Trust Model and Security Boundaries

VPL answers one question: whether the current signing certificate set of an APK is acceptable under the signed trust list and the user's explicit trust records. It does not determine whether a plugin is bug-free, compatible, or harmless.

Decision priority

VPL evaluates current APK signing certificates in this order:

  1. Signature extraction must succeed and at least one current certificate must exist.
  2. If any current certificate is globally banned, the result is BANNED.
  3. If a current active certificate belongs to an author explicitly trusted by the user, the result is TRUSTED with source AUTHOR.
  4. If any current certificate was explicitly trusted by the user, the result is TRUSTED with source KEY.
  5. If a current certificate is listed as active, the result is PENDING_TRUST.
  6. Otherwise, a correctly signed but unknown APK is UNTRUSTED.

A ban therefore overrides both author and certificate trust. This also applies to multi-signed APKs: one banned current signer blocks the package even if another current signer is trusted.

Historical signing certificates are retained in allSignatures and signatureDetails for diagnostics. They do not authorize the APK; trust decisions use only current certificates.

Status semantics

TRUSTED

The current package is accepted through either an explicit author decision or an explicit certificate decision. The result can create a PluginLoadAuthorization, but the authorization remains only a pre-launch snapshot. The host must re-inspect at the final loading boundary.

PENDING_TRUST

At least one current certificate is registered as active, but the user has not trusted its author or concrete certificate. The host may display author details and request an explicit decision.

confidence controls author-level eligibility in the current implementation:

  • 0: the author is registered but trustAuthor() rejects author-level trust.
  • 1: the author is eligible for explicit author trust; hosts should present a stronger warning.
  • 2: the author is eligible for explicit author trust with the normal confirmation path.

These values are input to host policy and UI. They never override a ban and do not represent a guarantee that plugin code is safe.

UNTRUSTED

The APK has a readable current certificate, but no current certificate is recognized as active or banned. The host should block it by default. If the host offers direct certificate trust, it must identify the exact current fingerprint and present a clear warning that no registered publisher identity was established.

BANNED

At least one current certificate is marked banned by the signed trust list. The host must block loading and must not offer author or certificate trust as a bypass.

VERIFICATION_FAILED

VPL could not obtain a usable current signing certificate. Examples include a missing package, unreadable archive, unsigned APK, or package-manager extraction failure. The host must block loading and must not convert this state into an untrusted-plugin confirmation.

Author trust and certificate trust

Author trust follows the signed list: it accepts that author's current certificates while they remain active. It is useful when a known publisher legitimately rotates certificates and the signed list is updated.

Certificate trust is narrower: it accepts one exact current certificate, including an otherwise unknown certificate. A later signed list may associate that certificate with an author without changing the original trust source. Only a global ban supersedes it.

Hosts may impose additional policy on certificate trust. For example, a launcher can require a separate setting before TrustSource.KEY is permitted, while continuing to allow author trust.

Diagnostics are not permissions

VerificationDiagnostic describes context such as trust-list expiry, fallback, update failure, or user-store recovery. It does not override the status.

An expired trust list currently produces TRUST_LIST_EXPIRED but remains usable for decisions. This fail-operational behavior avoids disabling all plugins when updates are temporarily unavailable. Hosts should expose or log the condition and retry updates, while continuing to enforce any bans present in the selected signed list.

Similarly, falling back to the bundled list or failing a remote update does not automatically trust a plugin. The normal certificate rules still apply.

What VPL protects

  • Trust-list modification or network substitution without the compiled Ed25519 root key.
  • Acceptance of malformed, ambiguous, oversized, or unsupported trust-list data.
  • Network rollback below the active valid local or bundled list version during normal operation.
  • User trust overriding a globally banned current certificate.
  • Historical certificates authorizing a package after signer rotation.
  • Corruption of the current trust-list or user-trust file when a valid previous snapshot exists.
  • Accidental use of an authorization after the package identity changed, when the host performs the required final comparison.

Non-goals

VPL does not claim to protect against:

  • A compromised host launcher or a host that ignores VPL results.
  • Root-level modification, runtime memory injection, or replacement of the executing process.
  • Rollback guarantees across complete application-data deletion or restoration of an older full data backup.
  • Malicious code signed by a certificate the user chose to trust.
  • Vulnerabilities, privacy problems, data loss, or compatibility defects inside a trusted plugin.
  • Native paths or environment values that the host does not bind to a verified package.
  • Secure plugin discovery, UI design, process isolation, sandboxing, or native loading itself.

The host must define any stronger device-compromise or plugin-sandboxing threat model separately.