Host ISO 18013-5 proximity in the SDK instead of piping GATT

[leifj]

What it does

The wrapper exposed Bluetooth as eight bridge methods and let the page drive the mdoc protocol over them. That put device engagement, session keys, the session transcript, chunking and device-response assembly in TypeScript, duplicated the BLE stack across this app, the iOS app and the page, and — the part worth pausing on — meant the page never authenticated the reader. It extracted no certificate chain, verified nothing, and asked nothing about trust. It presented to whatever connected.

This replaces the byte pipe with a session hosted by the SDK, whose proximity stack has been through real-reader interop.

before   reader ──BLE──▶ wrapper ──byte[] as JSON──▶ page (runs the protocol)
after    reader ──BLE──▶ SDK session ──ask/answer──▶ page (consent, signature)

The contract the page has to implement

Two methods to call, four handlers to register. Payloads are UTF-8 JSON in base64 in both directions.

// start a session; resolves with the engagement to put in a QR code
const { mdocUri, mode } = await nativeWrapper.proximityStart({ mode: 'peripheral' })
await nativeWrapper.proximityStop()

// the session then asks the page for what only the page has
nativeWrapper.onRequest('proximity.credentials', async () => [ /* StoredCredential[] */ ])
nativeWrapper.onRequest('proximity.consent',     async ({ docType, requestedClaims, families, readerTrust }) =>
                                                        ({ approved: true, credentialId }))
nativeWrapper.onRequest('proximity.sign',        async ({ credentialId, disclosedClaims, sessionTranscript }) =>
                                                        ({ deviceResponse: base64 }))
nativeWrapper.onRequest('proximity.readerTrust', async ({ x5chain }) => ({ trusted, reason, entityName }))
nativeWrapper.onRequest('proximity.step',        ({ step }) => { /* progress */ })
nativeWrapper.onRequest('proximity.complete',    ({ success }) => { /* terminal */ })

proximity.credentials returns the SDK's StoredCredential shape, which is the same shape the encrypted container already holds, so the page is handing over what it already has rather than converting.

Review points

Ordered by how much I would like an opinion.

1. proximity.readerTrust is still a callback, and the reason is narrower than this PR first claimed. The original comment said an offline session could not make a trust decision at all. Wrong about the SDK: RICAL for readers and VICAL for issuers are both there, with the fail-closed-versus-fall-back distinction. What is true is that the local evaluator is private to SirosWallet, which a flow-free composition does not construct, and the reachable remote half wants a backend base URL the page owns. A composition gap, one small SDK addition from closing. Corrected in the code comment.

2. Which BLE role should be the default? The engagement offers both and this starts one, defaulting to peripheral server. The page historically drove central client. Peripheral server is the role the SDK has the most exposure on. Easy to change; I would rather it be a decision than a default.

3. Eligibility filtering stays in the page. filterEligible is the identity function here, because consumption policy and presentation history live in the page's wallet state. That means the page must not return an exhausted instance from proximity.credentials. Reasonable, or should the policy move too?

4. The old resolve path is left as it is. It interpolates its argument into a single-quoted JavaScript string with no escaping, which is why one caller emitted \n by hand to survive the trip. WebAuthn is its last user and its fields are base64url already, so it works. New code uses base64 JSON. Worth a follow-up rather than widening this diff.

5. The authenticated-channel cost. Resolved. All five native crates are on Maven Central now, so the repository block and the CI token pair are removed. Consuming this wrapper needs only mavenCentral(), verified by a build with every credential removed.

What was verified

ktlintCheck	pass
testDebugUnitTest	pass
assembleDebug	pass
assembleDebugAndroidTest	pass
CI on this branch	pass, including connected tests
resolves with no credentials at all	yes, since the crates reached Central
a build tested on a device	yes, by @yimyitbarek
on a phone, against a reader	not done

CI going green is worth one note beyond the tick: it means the SDK resolves and the app builds against keystore + credentials alone, without the wallet facade and therefore without the engine. That composition was inferred from the module graph before this branch; now it is demonstrated in a real build.

No hardware run against a reader, so the session itself is compile-and-lint verified only, and it cannot be exercised end to end until the page registers the handlers.

One thing worth noting from doing it: no NFC service is declared here, because the SDK's own library manifest already contributes MdocHostApduService, its intent filter and its AID group. My first attempt declared it and the manifest merger rejected the duplicate. So NFC static handover arrives by adding the dependency.

What comes out

Removed	Lines
bluetooth/ — client, server, characteristics, extensions	1,069
debug/ — the two GATT printers	317
eight bluetooth* bridge methods, two mode accessors, shim wrappers	~130

Net 806 lines fewer, and one implementation instead of three.

🤖 Generated with Claude Code

[s-jairl]

As regards to review question 1, this approach seems reasonable - me and @smncd were discussing if this "offline trust validation" (checking if a certificate is signed by a trusted CA) should be performed by the frontend, but considering that the SDK likely already wanna provide this functionality for other users and that this is primarily applicable to offline usecases, the SDK validation is likely the best until the day we pickup WebBLE again.

[tladesignz]

@smncd and @yimyitbarek should have a look at this too, I guess since it affects them very much, too, AFAIU.

[leifj]

@yimyitbarek told me he tested a build for this and it works.

[smncd]

I skimmed this and I have some thoughts about the bridge/interface. Will elaborate on Monday :)