Specification
The device combines assessments from notaries the user enables. ADV checks developer registration; other notaries can check malware, reproducible builds, consumer practices, or age suitability. Each notary answers its own question. Approval is not a guarantee that an app is safe.
The coordinator is the device’s designated package verifier: the Play Store in the proposed Google deployment, or a privileged reference app on AOSP. It holds the install and owns the community review screen. Google’s Developer Verifier supplies the ADV assessment. This design targets Android 12L through 17 without changes to PackageInstaller; adoption still requires Google or the device builder. The initial reference implementation accepts single-APK sessions and rejects split-APK and multi-package sessions until it can validate their complete contents. The simulator’s files represent single-APK sessions.
Use the existing package verifier
The package manager sends PACKAGE_NEEDS_VERIFICATION and waits for verifyPendingInstall to allow or reject. The coordinator shows its own activity when review is needed. On Google devices, the deployment changes are in two updateable apps: the Play Store and Android Developer Verifier. An ordinary installed app cannot become the designated verifier or call Google’s restricted backport interface. Package verification and timeout API
Keep the two verification paths coordinated
On the legacy path used by older devices, the coordinator can apply the full community policy, including review of an unregistered app. On builds with platform developer verification, including Android 17, the OS also checks ADV independently. Google must coordinate that check with the package verifier, or use the supported policy or bypass mechanism to defer it in community mode. A denial must not race ahead of the review; an unverified developer must not be falsely reported as registered.
Registration and the native installation decision are separate. A platform pass or authorized bypass can permit further checks; a definitive denial cannot be overridden. Failure routing depends on the installer’s target SDK and permissions, not the target APK’s SDK. The simulator models Google’s confirmation for an active advanced-flow allowance in ADV-only mode. Other OS-controlled failure or confirmation flows remain unresolved; community review does not stand in for them. Developer-verification failure routing
The native developer-verification API is documented from version 36.1. Select the path present on the device rather than infer it from the Android version alone. Android 12L–17 is the design target; the current reference app has been exercised on Android 16 and still needs compatibility work and tests for the rest of that range.
Enable a notary through its app
An existing app, such as the Consumer Reporting app or F-Droid client, can declare a notary. Installation makes the declaration discoverable; the user must separately approve the notary and its data access in the coordinator’s settings. ADV remains enabled. Disabling or uninstalling another provider removes it from future checks.
Manifest metadata identifies the provider, protocol version, data requirements, and either an HTTPS endpoint with public signing keys or an explicit bound service. The system coordinator contacts the endpoint directly or calls the service through Binder. The service can use its own account, network client, or local data. It runs under the provider app’s UID and permissions; the coordinator owns the installation dialog.
Trust binds the provider ID to the installed package and accepted signing identity. A name or logo does not prove organization ownership. A provider cannot make itself mandatory, enable itself, or resolve the pending verification request. A provider app that also acts as a store retains its ordinary installation permissions. Optional directories can publish ownership checks, audit criteria, and appeals; they do not replace user consent.
Handle short deadlines and failures
The ordinary verification window defaults to ten seconds; the maximum extension is one hour. Request eleven minutes before starting other work, with rejection as the timeout result. The API returns no acknowledgement: reject on a known request failure, and honor system completion immediately. Use one monotonic deadline covering identity checks, assessment, review, and restarts. Review lasts at most ten minutes and ends before that deadline, leaving time to return the decision. Restarts never renew it. The simulator assumes a timely extension unless its failure option is selected. Package verification and timeout API
Some incremental, v4-signed installs use a short streaming window, normally three seconds, that does not honor the ordinary extension. The simulator conservatively treats incremental mode this way: use already cached, authenticated evidence and allow only unanimous approval; otherwise reject before the deadline. Do not wait for a human or hash an incomplete APK. Approval requires an authenticated mapping from the available install identity to the exact cached APK; without that mapping, reject. AOSP verification deadlines
This is a deadline requirement, not a guarantee that an unchanged OS fails closed. If the verifier crashes or misses the streaming deadline, some builds allow installation by default. Broad fail-closed support requires device policy or installer cooperation. A retry with a complete APK can use the normal review path; the coordinator cannot silently convert another installer’s session.
If a coordinator activity cannot open, post a notification that the user can tap while the complete-APK install waits. Notification permission and background activity rules must be handled for each supported version. If review cannot be completed, reject. The generic installer result never replaces the coordinator’s detailed report.
Decide on the device
Capture the enabled provider configuration and apply these steps in order. Community mode means ADV plus at least one enabled optional provider, even if that provider does not respond. The table applies to effective assessments after exemptions and cache replacement.
- Reject unsupported sessions. For a complete APK, request the timeout extension immediately. For incremental delivery, require an authenticated identity for the exact APK. Reject if the required check cannot proceed.
- Respect the independent platform ADV result where present; a community decision cannot replace a required Google confirmation.
- For a complete APK with only ADV enabled, use the ADV-only baseline below. An authorized advanced-flow allowance still requires confirmation for each unregistered installation.
- Otherwise, collect complete-APK assessments in parallel with an eight-second limit and replace missing results with valid cached evidence when permitted. Incremental installs read only the coordinator’s cache. Omit exempt ADV checks.
- If no checks remain after the ADV exemption, allow this verification step. For incremental delivery, allow only unanimous approval; reject every other result. For complete APKs, apply the table below.
| Assessments from active notaries | Result |
|---|---|
| Every participating notary approves | Allow installation to continue without a community-review prompt. |
| Every participating notary denies or revokes approval | Block installation and show the reasons. |
| Any other combination | Show every assessment; offer Install and Cancel. |
Abstain means the notary has no recommendation. Age 16+ is advice that requires review, not an age check. A missing or invalid effective assessment prevents unanimity. In this proposal, revoked, unregistered, or mismatched ADV registration counts as a denial. An ADV exemption removes that check from the vote; it is not an approval. Android’s other installation permissions and checks still apply.
The coordinator’s review screen names each notary and shows its status, reason, and evidence source. Install applies to this attempt; Cancel or dismissal rejects it and closes the review without an additional notification. For policy denials and expired reviews, the system installer may show only a generic error; the coordinator records the reasons and provides its own report notification.
Keep the ADV-only baseline
With only ADV enabled, complete-APK installs use the announced ADV baseline, subject to the independent platform result. Registered apps proceed. Unregistered apps require advanced-flow setup outside the rejected attempt, followed by a new attempt and per-install confirmation. An active allowance permits that confirmation; it does not change registration. ADB and eligible managed-store installs are exempt from ADV. In community mode, other notaries still apply. ADB exemption from ADV does not imply exemption from the legacy package verifier. Google’s advanced-flow instructions
This baseline assumes the announced worldwide requirements on a certified device. Google’s published guidance does not fully specify offline checks, revoked registration, or reactivation after allowance expiry. The simulator identifies these gaps without inventing outcomes. Limited-distribution authorization and regional rollout rules are outside this example.
Reuse evidence
The legacy hook cannot accept attestations attached by a store. A store must participate as an enabled provider app, returning its own authenticated assessment through the same contract as other notaries. The coordinator can cache those assessments. If a complete-APK check cannot reach a provider, valid evidence for that provider and exact APK can be reused; otherwise the missing assessment requires review. Invalid responses prevent cache fallback.
Each installation applies the policy to the available assessments. If the policy requires review, the user decides again, including when reinstalling the same file. Changing trust settings clears evidence. An updated APK has a new digest and starts a separate check.
Evidence lasts 24 hours in this simulator. The saved-attestation provider route uses evidence issued at hour 0; reading it does not renew its expiry. Prepare evidence without installing, advance time to test expiry, or change the APK to test identity matching. Incremental mode reads only the coordinator’s existing cache. Authentication, IPC, deadlines, and signature checks are simulated.
Provider contract and trust rules
- Registration
- The application metadata org.appfair.notarization.PROVIDER references an XML configuration. Version 1 declares one provider per package: a provider ID, approved data fields, and either an explicit service component or an HTTPS endpoint with accepted signing keys. The provider ID must be unique among enabled providers. The example uses a bound service protected by PACKAGE_VERIFICATION_AGENT; the service must also validate the coordinator’s identity.
- Request
- Version 1 uses the fields shown below: protocol version, request ID, package name, decimal version-code string, APK SHA-256, signing-certificate SHA-256 digests, and requested language. The coordinator derives identity from the install data. No device ID, account, installed-app list, or APK content is included by default. Extra data requires explicit permission; temporary APK access uses a read-only descriptor.
- Response
- Return the provider ID, request ID, exact app identity, verdict, reason code, issue time, and expiry; a localized explanation is optional. Provider verdicts are approve, deny, revoke, abstain, or advisory. Age 16+ is an advisory with minAge set to 16. Unavailable, timeout, stopped, and invalid are coordinator-generated states. Reject unknown versions or verdicts, oversized payloads, mismatched identities, expired evidence, and late callbacks. Display provider text as text, never markup.
- Authentication
- Direct HTTPS assessments require an ECDSA P-256 signature from a key in the accepted provider configuration. Bound-service responses are authenticated through Binder, whether the app uses local data or its own server; these are the app’s assessments and are cached only on that device. A service may also return a portable signed attestation, which requires separate validation against declared issuer keys. Portable evidence binds to app identity and expiry; live responses also bind to the request ID. Reuse never extends the signed expiry.
- Bound service
- Use a versioned AIDL request, callback, and cancel contract. Bind to an explicit component, verify its package and signer, and require the service to authenticate the coordinator. Handle process death and cancellation; ignore duplicate or late results. Never run provider code inside the privileged coordinator or use an activity for background assessment.
- Provider updates
- The previously enabled configuration assesses provider installs and updates. Validate Android signing continuity before accepting an update. New data recipients, keys, or access require renewed approval. If the active provider list or accepted configuration changes during a check, discard its results and restart collection within the original deadline; reject if time runs out. Declared keys can overlap for rotation; retired or revoked keys invalidate dependent evidence.
- Privacy and accountability
- HTTPS adapters send approved fields only to the approved endpoint and reject redirects to other recipients. Provider apps retain their permissions and may correlate requests with an account. Prefix lookups and relays need separate protocol support. Provider-cached attestations can reduce network disclosure. Keep reports on the device; published service metrics must be optional and aggregated. Notaries publish their assessment policies and developer appeal route.
Provider registration and messages
These examples use synthetic identities and timestamps. They define the field-level contract; the reference implementation must fix the canonical signed bytes, signature envelope, limits, and versioned AIDL types before interoperable providers can ship.
AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="org.example.consumerreporting">
<application>
<meta-data android:name="org.appfair.notarization.PROVIDER"
android:resource="@xml/notary" />
<service android:name=".NotaryService" android:exported="true"
android:permission="android.permission.PACKAGE_VERIFICATION_AGENT" />
</application>
</manifest>res/xml/notary.xml
<notary protocolVersion="1" providerId="org.example.consumerreporting"
transport="service" service="org.example.consumerreporting.NotaryService">
<data fields="packageName,versionCode,apkSha256,signingCertificateSha256" />
</notary>Assessment request
{
"protocolVersion": 1,
"requestId": "example-1",
"app": {
"packageName": "org.example.freecalculator",
"versionCode": "1",
"apkSha256": "0000000000000000000000000000000000000000000000000000000000000000",
"signingCertificateSha256": [
"1111111111111111111111111111111111111111111111111111111111111111"
]
},
"language": "en"
}Bound-service response
{
"protocolVersion": 1,
"requestId": "example-1",
"providerId": "org.example.consumerreporting",
"app": {
"packageName": "org.example.freecalculator",
"versionCode": "1",
"apkSha256": "0000000000000000000000000000000000000000000000000000000000000000",
"signingCertificateSha256": [
"1111111111111111111111111111111111111111111111111111111111111111"
]
},
"verdict": "approve",
"reasonCode": "NO_CONCERNS",
"issuedAt": "2026-11-02T18:00:00Z",
"expiresAt": "2026-11-03T18:00:00Z"
}AOSP implementation plan
Adapt the existing package-verifier app to discover providers, implement HTTPS and Binder adapters, and validate evidence. Request the extension immediately and submit at most one decision per live verification ID. Handle completion, cancellation, process restart, and late callbacks without reopening resolved requests. Implement notifications and reports independently of the system installer. In Google’s deployment, update the Play Store coordinator and the ADV app’s backport and platform integrations.
Target Android 12L–17 (API 32–37). The current reference manifest requires API 34; lower that requirement only after auditing APIs and validating on the older images. Test complete and incremental installs, deadline extension, notification delivery, signature checks, expiry, provider changes, and offline reuse. Test native ADV coordination separately: the AOSP fixture does not establish Google integration or compatibility across all releases.
Split APK sets require a canonical identity for the complete set. For incremental installs, establish a trustworthy binding between the available v4 identity and cached evidence before allowing them. Managed profiles may use administrator-controlled provider settings. Other platform protections and post-install scanning remain independent.
This revision replaces the prototype’s compiled registry with provider apps and uses strict unanimity. It caches assessments but does not save installation choices.
Google integration details also use the supplied static APK analysis. Its backport service restricts callers to the Play Store; platform callbacks report complete, incomplete, or bypassed results. That is evidence of integration points, not a public plug-in API or a tested community deployment.