google / google/webcrypto.dart
[Android JCA] Design Android JCA backend opt-in and packaging
- Dominant language
- Dart
- Stars
- 116
- Forks
- 110
- Avg merge
- 6d 8h
- Merged PRs (30d)
- 9
Description
## Problem
The `android-jca-branch` imports `impl_jni` whenever `dart.library.ffi` is true, so JNI replaces FFI on Android and desktop native targets. Independently, `hook/build.dart` builds and registers `libwebcrypto.so` for every code-asset target. A JCA test build therefore still packages this package's BoringSSL library.
The core `package:webcrypto` pubspec does not require Flutter. `package:jni` 1.0.0 requires Flutter 3.35.6 or newer and registers platform plugins, so keeping JNI in the core dependency graph would change which applications can depend on `package:webcrypto`.
Runtime registration and native-asset packaging need separate controls. Registering a Dart backend cannot stop the build hook from packaging `libwebcrypto.so`; the build must know whether the application selected a JCA-only Android configuration.
Draft PR #326 changes native linking and adds BoringSSL symbol tree shaking. If it lands, measure whether a JCA-only build still emits a native asset instead of treating symbol removal as asset omission.
## Candidate Package Split
- Put the JNI/JCA implementation and `package:jni` dependency in a companion `package:webcrypto_jca` package.
- Expose a supported backend interface and registration hook from `package:webcrypto`.
- Require each isolate to register the JCA backend before its first Web Crypto operation.
- Add an explicit Android build setting that tells the `webcrypto` build hook when it may omit `libwebcrypto.so`.
- Keep PBKDF2 #357 unchanged until this design establishes whether a helper or FFI fallback can ship.
Maintainers still need to decide whether to use this package split.
## Decisions Needed
- Decide whether JNI belongs in `package:webcrypto` or a Flutter-only companion package.
- Decide whether the prototype may use version-locked private `package:webcrypto/src/...` imports, or whether `package:webcrypto` must expose a supported backend interface and registration hook first.
- Define registration, repeated-registration, and per-isolate behavior.
- Choose the build setting, such as a build-hook user define, that permits omission of `libwebcrypto.so` only for an Android JCA build.
- Define how the build confirms that the companion package is present before it omits BoringSSL, and how runtime reports missing registration.
- Decide whether JCA opt-in must exclude FFI or may keep an FFI fallback for PBKDF2.
## Validation Required
- Add build-hook tests for the default build, Android JCA opt-in, invalid setting values, and non-Android targets.
- Compare release APK/AAB contents and size with the default FFI build.
- Repeat the native-asset check with #326 if its link-hook changes land first.
- Test initialization, repeated registration, and independent isolate registration.
- Verify that live JCA key wrappers remain isolate-unsendable.
- Run the complete shared Android TestRunner through the public opt-in path.
Related: #296, #326, #357
Contributor guide
Research direction
Start with hook/build.dart and the android-jca-branch behavior described in the issue, then review related issues #296, #326, and #357. Compare the candidate package split and opt-in decisions against the listed build-hook, isolate, packaging, and Android TestRunner validation requirements. Done means the maintainers have selected the design and those validation cases are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, dart, flutter
- Domain
- build-system, mobile-dev, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100