google / google/webcrypto.dart

[Android JCA] Design Android JCA backend opt-in and packaging

Open
#372 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.