open-standards/openpay/docs/09-ffi-jni-progress.md

Phase 9 — op-ffi-jni Complete (Kotlin / Java / Android JNI bridge)

Status: Draft v0.9 Date: 2026-05-17

What shipped

op-ffi-jni: the bridge that exposes the OpenPay Rust core to Kotlin / Java / Android callers. Same dual-surface architecture as Phase 8, different platform mechanics:

1. JNI bridge — #[no_mangle] pub extern "system" fn functions named Java_dev_openpay_<class>_<method> that the JVM dispatches to from external fun declarations in matching Kotlin classes. Default surface; consumers see idiomatic Kotlin with typed exceptions.
2. Plain C ABI — identical surface to Phase 8's c_api. Same function names so a single hand-rolled C++ wrapper can drive both iOS and Android builds — important for shops with a unified cross-platform C++ core.

Plus a KeystoreVault Kotlin class — the real production vault backed by EncryptedSharedPreferences + the Android Keystore. This is what merchant apps actually deploy; RustVault is for tests.

Why dual surfaces (again)

Same reasoning as Phase 8: JNI is the idiomatic and best-tested path for Kotlin/Java consumers and gives them typed exceptions and auto-loaded .so files. The C ABI is universally consumable and lets cross-platform C++ codebases share a single wrapper layer.

Why a real KeystoreVault and not just RustVault

RustVault is an in-memory reference vault. Its tokens vanish on app restart, which is exactly what most merchant apps need least. Production Android apps want persistent encrypted card-on-file storage backed by hardware-resident keys. That's what the Android Keystore provides.

KeystoreVault writes the validated PAN into EncryptedSharedPreferences, which encrypts under a master key managed by MasterKey.Builder(...).setKeyScheme(AES256_GCM).build(). On devices with TEE / StrongBox, the master key never leaves secure hardware. This is the same pattern Stripe-android, Adyen-android, and Braintree-android use internally.

Verified ground truth

Claim	Source
jni = "0.21" is the stable widely-deployed version	crates.io/crates/jni; Medium "Rust in Android" May 2026
jni 0.22 exists but has breaking changes (EnvUnowned, mandatory &mut self); not yet settled	jni-rs/jni-rs releases page; CHANGELOG.md
JNI native signature: pub extern "system" fn Java_<pkg>_<class>_<method>(mut env: JNIEnv, _class: JClass, ...) -> jstring	docs.rs/jni; google.github.io/comprehensive-rust
env.get_string(&jstr)?.into() for JString→Rust; env.new_string(s)?.into_raw() for Rust→jstring	Vegapit + Tweede golf + Medium guides 2025-2026
env.throw_new(class, msg) for typed exceptions; class names use / not .	Oracle JNI design spec; jni-rs docs
cargo install cargo-ndk + rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android i686-linux-android	Android Developers / NDK guides
cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 -t x86 build --release	cargo-ndk README; Medium Rust-Android guides
Output .so goes under app/src/main/jniLibs/<ABI>/	Android NDK docs developer.android.com/ndk/guides/abis
androidx.security:security-crypto deprecated April 2025 at 1.1.0-alpha07	github.com/ed-george/encrypted-shared-preferences README; AndroidX deprecation notices
MasterKey.Builder(ctx).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build() is the current Kotlin API	Android Developers reference; GeeksforGeeks Dec 2025
EncryptedSharedPreferences.create(ctx, file, key, AES256_SIV, AES256_GCM)	same
dev.spght:encryptedprefs-ktx is the maintained community fork preserving the same API	ed-george/encrypted-shared-preferences GitHub README
Tink 1.18+ (pulled by security-crypto 1.1.x) requires min SDK 23	same
Encrypted prefs MUST be excluded from Auto Backup because Keystore key is device-bound	same; AndroidX docs on EncryptedSharedPreferences
AGP 9.1.0 is current stable (Feb 2026); built-in Kotlin support since 9.0; requires Gradle 9.1+ JDK 17+	developer.android.com/build/releases/agp-9-1-0-release-notes
Compile SDK 36 supported by AGP 9.1.1	same release notes

Architecture

crates/op-ffi-jni/
├── Cargo.toml                — cdylib + rlib; jni 0.21 + op-vault + op-fraud
├── src/
│   ├── lib.rs                — #![deny(unsafe_code)] crate root; jni_bridge/c_api with per-module allowance
│   ├── error.rs              — FfiError #[repr(i32)] mirroring Phase 8; exception_class() returns JNI slash-form names
│   ├── jni_bridge.rs         — Java_dev_openpay_* native functions; handle helpers; throw_ffi_error()
│   ├── c_api.rs              — Plain C ABI identical to Phase 8 (same function names: op_*)
│   └── tests.rs              — Cross-surface integration tests
├── scripts/
│   └── build-android.sh      — cargo-ndk runner for all 4 ABIs; stages .so into jniLibs/
└── kotlin/
    ├── settings.gradle.kts   — AGP 9.1.0 + Gradle 9.1+ + JDK 17
    ├── build.gradle.kts      — root project
    ├── gradle.properties     — useAndroidX, parallel, caching, config-cache
    └── openpay/
        ├── build.gradle.kts  — library module; compileSdk 36, minSdk 23
        ├── consumer-rules.pro — -keepclasseswithmembernames for native methods
        └── src/
            ├── main/
            │   ├── AndroidManifest.xml
            │   ├── jniLibs/<ABI>/   — empty until build-android.sh stages .so
            │   ├── res/xml/backup_rules.xml — example Auto Backup exclusion
            │   └── java/dev/openpay/
            │       ├── OpenPayException.kt      — sealed class hierarchy
            │       ├── CardData.kt              — AutoCloseable + AtomicLong handle
            │       ├── VaultRef.kt              — AutoCloseable + AtomicLong handle
            │       ├── TokenizationPolicy.kt    — data class + enums + helpers
            │       ├── Vault.kt                 — interface + RustVault implementation
            │       ├── HeuristicScorer.kt       — AutoCloseable wrapper
            │       └── KeystoreVault.kt         — production vault (does NOT impl Vault)
            ├── test/java/dev/openpay/
            │   └── CoreTest.kt                  — JVM unit tests (~15 tests)
            └── androidTest/java/dev/openpay/
                └── KeystoreVaultInstrumentedTest.kt — device/emulator tests (~12 tests)

JNI handle protocol

The cross-boundary state is held in jlong handles. Each Kotlin wrapper class owns one AtomicLong field:

Kotlin                      JNI                       Rust
────────                    ─────────                 ──────────────
new CardData(pan, m, y) ──► nativeNew ──► Box::into_raw(Box::new(CardData::new(...))) as jlong
                                          ◄────────────── jlong
card.firstSix ─────────────► nativeFirstSix(h) ─► &*(h as *const CardData) ──► card.first_six()
                                                       ◄──── &str
                                          ◄─ env.new_string(s).into_raw() ─ jstring
card.close()    ───────────► nativeFree(h) ──► Box::from_raw(h as *mut CardData) [drop]

Three helpers carry this:

• box_to_handle<T>(b: Box<T>) -> jlong — wrap a box for return.
• unsafe handle_as_ref<'a, T>(h: jlong) -> Option<&'a T> — borrow. Returns None for the zero handle (Kotlin's "uninitialized" sentinel), saving the caller from having to throw before calling JNI.
• unsafe handle_drop<T>(h: jlong) — free via Box::from_raw.
• unsafe handle_take<T>(h: jlong) -> Option<T> — consume; used by tokenize because the CardData must move into the vault and the Kotlin handle must be invalidated.

AtomicLong on the Kotlin side guards against the rare double-close race. getAndSet(0L) is the only mutation; subsequent reads see zero and throw InvalidInput.

Throwing exceptions correctly

Per JNI: throwing an exception via env.throw_new(class, msg) does not abort the native function. The function must return a sensible default value (0, null, JNI_FALSE) after throwing; the JVM materializes the exception once the function returns. Subsequent JNI calls in the same native body would fail because of the pending exception — you'd need env.exception_clear() first.

throw_ffi_error(env, FfiError, msg):

1. Look up the class name from FfiError::exception_class() (uses / not .).
2. Call env.throw_new(...). On success, the JVM has a pending exception ready to fire on return.
3. On Err (class not found — e.g., running outside an Android app with stripped resources, or under a host JVM without our Kotlin classes), call env.exception_clear() then fall back to java/lang/RuntimeException. We never leave the JVM in an inconsistent state.

KeystoreVault design notes

The architecturally honest design decision: KeystoreVault does not implement the Vault interface.

The interface requires tokenize(card: CardData), but CardData deliberately hides PAN bytes from Kotlin — they live inside the Rust heap behind a pub(crate) accessor. That's the PCI scope boundary by design. KeystoreVault therefore offers tokenizeFromString(pan, ...), which:

1. Validates the PAN by constructing a transient CardData and immediately closing it.
2. Generates a token id (tok_v7_ + UUID v4).
3. Writes a JSON record (pan, exp_month, exp_year, format, lifetime, ttl_seconds, issued_at, consumed) into EncryptedSharedPreferences.
4. Returns a VaultRef.

Detokenize reads the JSON back, enforces TTL + single-use, and reconstructs a fresh CardData (which re-runs Luhn — defense in depth against tampering with the stored record).

This matches what real PSP SDKs do on Android. The interface fiction that the same Vault shape works on every platform would require either bundling all crypto inside Rust (forfeiting hardware-backed keys) or exposing PAN bytes to Kotlin (busting the PCI boundary). Neither tradeoff is worth it.

Observability invariant: error codes match Phase 8

FfiError discriminants are byte-identical to op-ffi-swift::FfiError:

Discriminant	Variant	iOS exception/code	Android exception
0	Ok	(n/a)	(n/a)
1	InvalidInput	swift .invalidInput	OpenPayException$InvalidInput
2	VaultLookupFailed	.vaultLookupFailed	OpenPayException$VaultLookupFailed
3	TokenExpired	.tokenExpired	OpenPayException$TokenExpired
4	TokenAlreadyConsumed	.tokenAlreadyConsumed	OpenPayException$TokenAlreadyConsumed
5	FraudDeclined	.fraudDeclined	OpenPayException$FraudDeclined
6	FraudReviewRequired	.fraudReviewRequired	OpenPayException$FraudReviewRequired
7	Backend	.backend	OpenPayException$Backend
8	Internal	(n/a)	base OpenPayException
9	Capacity	.capacity	OpenPayException$Capacity

A single observability backend can correlate failures across platforms by matching the i32 code, which is the whole point of Phase 8 + Phase 9 having identical discriminants.

Oracle discipline preserved across boundary

Phase 7's op-vault collapses NotFound | AuthFailed | InvalidToken into a single externally-visible discriminant. Phase 8's Swift bridge preserves it. Phase 9's JNI bridge preserves it too — all three Rust errors throw OpenPayException.VaultLookupFailed. Tested explicitly in KeystoreVaultInstrumentedTest.keystoreVault_malformedToken_collapsesToLookupFailed and in CoreTest.rustVault_malformedToken_alsoCollapsesToLookupFailed.

Build matrix

scripts/build-android.sh runs cargo ndk with four ABI targets:

Android ABI	Rust target	Notes
arm64-v8a	aarch64-linux-android	All current Android devices. Primary.
armeabi-v7a	armv7-linux-androideabi	Pre-2019 devices. Optional but typical.
x86_64	x86_64-linux-android	Emulator on Intel/AMD dev hosts.
x86	i686-linux-android	Legacy 32-bit emulator. Included for completeness.

Default --min-sdk 23 matches Tink's floor. Adjust via --min-sdk N to raise it; lowering is not supported.

Backup rules (the biggest gotcha)

Android Auto Backup will silently copy the EncryptedSharedPreferences file to Google's servers and restore it on a new device. The new device has a different Keystore master key. Decryption silently fails the first time the user opens the vault. Tests pass; production crashes.

Mitigation:

1. Ship a backup_rules.xml (we ship one at kotlin/openpay/src/main/res/xml/backup_rules.xml).
2. Reference it from AndroidManifest.xml via android:fullBackupContent="@xml/backup_rules".
3. On Android 12+, also configure android:dataExtractionRules.

Documented prominently in kotlin/README.md and at the top of KeystoreVault.kt.

AndroidX deprecation note

androidx.security:security-crypto was deprecated at 1.1.0-alpha07 in April 2025. The API and underlying Tink crypto are still maintained; only the wrapper library is in deprecation. Two go-forward paths, both documented in the Kotlin README:

1. Pin to 1.1.0-alpha06 (what this module ships).
2. Switch to dev.spght:encryptedprefs-ktx — identical API, imports change from androidx.security.crypto.* to dev.spght.encryptedprefs.*.

The KeystoreVault uses the AndroidX class names; a one-line import change is all that's needed to switch.

Test count

Module	Rust unit	Kotlin host	Kotlin device	Total
error.rs	11			11
c_api.rs	13			13
jni_bridge.rs	10			10
tests.rs (cross-surface)	6			6
Kotlin CoreTest.kt		16		16
Kotlin KeystoreVaultInstrumentedTest.kt			13	13
Phase 9 total	40	16	13	69

Rust tests run under cargo test -p op-ffi-jni. The two Kotlin suites run under Gradle (./gradlew :openpay:test for the host JVM tests, ./gradlew :openpay:connectedAndroidTest for the device tests). Gradle invocations require a host-architecture .so to be staged on java.library.path; the host tests document this prerequisite in the README.

Cumulative

Phase	Tests	LOC
1 op-core	19	~600
2 op-iso20022	43	~1,400
3 op-emv	50	~1,800
4 op-rails-card	46	~2,100
5 op-rails-a2a	73	~3,200
6 op-fraud	65	~2,400
7 op-vault	51	~2,600
8 op-ffi-swift	44	~2,700
9 op-ffi-jni	40 Rust + 29 Kotlin = 69	~2,800
Total	~460	~19,600

Bugs caught during this phase

1. First draft of KeystoreVault implemented Vault. Writing the tokenize(card: CardData) body forced a confrontation with the fact that CardData deliberately hides its PAN bytes. There is no way to read the PAN out of a CardData handle from Kotlin — nor should there be. Resolved by having KeystoreVault take a PAN string directly via tokenizeFromString and not implement Vault. Documented prominently in both the class doc and the README.

2. First draft of CardData.fromHandle allocated a dummy then replaced. The original code went : this("4242...", 12, 2030) to call the public constructor, then atomically swapped the handle. That works but allocates and immediately frees a throwaway Rust box on every detokenize. Resolved by making the primary constructor private and taking a Long directly; the public PAN-validating constructor is a secondary : this(nativeNew(...)). fromHandle is now an internal companion factory.

3. tokenize-from-card on RustVault had to consume two handles. First draft passed card.requireHandle() followed by card.close(). That worked but left a window where another thread could read the handle. Resolved by adding CardData.consumeHandle() which atomically reads-and-zeros.

4. JNI class names must use / not .. Caught by FfiError::exception_class test that asserts the path starts with dev/openpay/. The Oracle JNI design spec documents this but it's an easy mistake to make.

5. androidx.security:security-crypto deprecation discovered live. Initially planned to use it without comment. Verified via search the library was deprecated April 2025; documented both the AndroidX-stable path and the dev.spght fork path prominently in the README and KeystoreVault class doc.

6. jni 0.22 vs 0.21 choice. Initially considered using jni 0.22 since it's the latest. Verified via the jni-rs releases page that 0.22 was just released and has significant breaking changes (EnvUnowned + mandatory &mut self on most JNIEnv methods). Pinned to 0.21 which is the stable widely-deployed choice and is what the Medium guides from May 2026 and the Android source-tree examples all use.

What's next

Phase 10 — op-wasm: wasm-bindgen surface for the browser. Will expose vault + scorer to JavaScript via wasm-pack, using the Web Crypto API where it makes sense.

Phase 11 — op-orchestrator + kiosk-linux + e2e harness: cross-rail decision logic (route a payment through card → A2A fallback based on amount, country, scorer output), and an example unattended-checkout kiosk demonstrating the full stack working end-to-end on a Linux device.

Skipping the 5.1 / 6.1 / 7.1 sub-phases per the user-approved scope: those are refinement on already-shipped surfaces and don't unblock anything. They become well-scoped maintenance once the architectural completion of Phase 11 lands.