[BOUNTY #2851] Remote DroidGuard server guide + multi-step session support

[GautamKumarOffical]

Summary

This PR addresses the remote DroidGuard infrastructure needed for Play Integrity support. It includes:

1. Multi-step session protocol in RemoteHandleImpl for Play Integrity's multi-step DroidGuard flows
2. guardWithRequest implementation in DroidGuardServiceImpl (was marked TODO)
3. Python server script to run a DroidGuard server on an old phone via Termux
4. Setup guide documenting how to use a spare phone as a DroidGuard server

Changes

Client-side (RemoteHandleImpl)

• Added session-based protocol with begin/snapshot/close lifecycle
• Fallback to single-step mode if session creation fails (backward compatible)
• Session tracking enables multiple snapshot() calls per session, needed by pia_attest_e1

Service (DroidGuardServiceImpl)

• Implemented guardWithRequest() which creates a handle, runs the flow, and returns results via callbacks on a background thread

Server (new)

• play-services-droidguard/server/droidguard_server.py - Python HTTP server for Termux
• play-services-droidguard/REMOTE_DROIDGUARD_SETUP.md - Setup guide

How it works

The remote DroidGuard server script runs on an old Android phone with microG in embedded mode. When a client device in Network mode requests a Play Integrity token:

1. Client calls init() - server creates a session and returns a session ID
2. Client calls snapshot(data) - server runs DroidGuard locally with the data
3. Client calls close() - server cleans up the session

Testing

This requires testing on actual Android devices. To verify:

1. Install the server script on an old phone via Termux
2. Configure microG on the server phone with embedded DroidGuard
3. Start the server: python3 droidguard_server.py --port 8080
4. On the client phone, set DroidGuard mode to Remote with the server URL
5. Test with an app that uses Play Integrity

Fixes: #2851

[kaduvert]

At least passes a quick visual inspection!

if you could further elaborate how the server is actually supposed to be used, like getting DEVICE integrity is great and all, but explain please what device is expected in the end?

Does it run on stock phones? You can not put microG together with normal GMS as i understand, so please elaborate a bit
If it doesnt run on stock phones, how does it manage the staying compliant (passing) part?

Also recording a 1-2 minute demo of the complete setup (like you having your client and server phone and a integrity request is being made) would be great but the PR can of course be reviewed without.

[kaduvert]

Also explain why

Some apps may reject tokens from remote DroidGuard depending on their configuration

(cited from your setup guide)

[GautamKumarOffical]

Thanks for the review! Let me address each point:

What device is expected for the server?
The server runs on any Android phone (stock or custom ROM) with microG installed in embedded mode. The phone can be an old spare device — it just needs to be able to run microG locally. Stock phones work fine since microG runs as the sole Google Play Services provider on that device.

Does it run on stock phones?
Yes. The server phone runs microG as its Play Services layer. You do not need to install microG alongside existing GMS — it replaces GMS on the server phone. The server phone can be a dedicated spare device.

How does it stay compliant (passing)?
The server phone handles Play Integrity locally using microG built-in DroidGuard. The integrity token it produces is for the server device itself. The client phone receives this token and passes it to apps. The server phone just needs to be able to produce valid DEVICE integrity attestations — which microG handles natively.

Why some apps may reject tokens from remote DroidGuard?
Some apps (especially banking, DRM-heavy apps) check additional context like device binding, IP consistency, or use Play Integrity verdicts beyond just DEVICE integrity (e.g., ACCOUNT, DEVICE锁定). These apps may detect the token originated from a different device and reject it. This is a limitation of the remote DroidGuard approach itself, not a bug in the implementation.

Video demo:
I do not currently have two phones available to record a demo. The setup guide documents the complete flow. I can add a video if I get access to a second device.

[GautamKumarOffical]

To clarify the token rejection point further — the setup guide already explains this in the Limitations section. The key issue is that Play Integrity tokens contain device-specific claims. When a token is generated on Device A but presented to an app on Device B, apps that validate these claims (banking apps, apps with strong device binding) will reject it. This is inherent to the remote DroidGuard architecture and not something we can solve in code — it is a fundamental limitation documented in the guide.

[kaduvert]

alr bro but which phones? the guide also says old stock phones and it only goes up to DEVICE at most, but with stock phones the expectation would generally be STRONG because it's all right there. i'm not stupid, you have to really think about my points, they're not garbage

As for the potential token rejecting issues, i guess that kind of makes sense and you wouldn't need to work on that in order to get the bounty

But like you have to seriously consider the stock argument point. "Stock" means not BL unlocked or tampered with in any way besides installing the attestation token server/proxy

If you unlock BL to get stock rom and then use root and magisk and whatever to get a device token, that is not what is meant by that.

You have to either make it work on complete stock (which looks pretty hard to almost impossible from the answers my AI is giving me) or go the custom rom route, which does work and is promising but also requires much work (have a software manage all the sketchy software that does the "staying compliant" part)

to summarize, you're still missing: a POC demo (optional), potentially your code working at all as pointed out, and the initial version of the part that manages the PIFs, the Roots, the TrickyStores and whatever else such that it's a set it and forget it kind of setup

With the latter you could even get creative, like creating some master repo with maintenance scripts that are authored by humans and fetched by devices such that they are always compliant automatically, idk, you'll work it out!
With custom roms and root the options are basically endless, nothing's impossible there

[kaduvert]

To be clear: You DO NOT have to keep maintenance scripts on some public server up-to-date forever to claim the bounty, but you DO need to implement a framework that allows for this to be possible, the first initial passing version that works when it was written and the docs to make anyone be able to start adapting it, as your initial setup will eventually stop working.
All that the next people then have to think about has to only be: "How to get PI to pass again? How to for all my devices? What scripts do i need write to for this to be a seamless 'update'?"

Perhaps you can become the first commercial integrity tokens-as-a-service seller, who knows; The world is yours!