[WAL-1183] feat(mobile): Add biometric key-use authorization

[szijpeter]

Intent

Add opt-in, immutable key-use authorization for newly created mobile wallet signing keys. BiometricCurrentSet requires OS-enforced biometric authorization for every private-key signing operation, binds the key to the current biometric enrollment set, and fails closed when the requested combination cannot be enforced.

This is key-use authorization, not wallet/app unlock. It does not rotate or reclassify existing keys.

What changed

• Added algorithm-neutral None and BiometricCurrentSet policy contracts, localized prompt configuration, stable protected-key failures, and capability/backing metadata.
• Wired the policy through the existing Signum-backed AndroidKey and IosKey implementations using biometric-only, auth-per-use protection with a zero timeout and current-set enrollment binding.
• Extended platform key generation and preflight inputs so unsupported protected requests are rejected before any software or unprotected fallback can be created.
• Persisted requested/effective per-key policy and effective hardware backing, including a migration that classifies existing rows as None without inventing backing metadata.
• Revalidated protected keys on reload, made custom stores opt into policy-metadata persistence, and resolved Android prompt hosts without retaining stale activities.
• Added Kotlin and Swift configuration, capability, key metadata, and failure surfaces while retaining legacy generator behavior for None only.
• Updated Kotlin/Swift documentation and added focused migration, persistence, capability, failure-mapping, bridge, and operator-driven mobile coverage.

Supported combinations

Platform	None	BiometricCurrentSet
Android	Existing mobile provider behavior: P-256/P-384/P-521/RSA in Android Keystore; Ed25519/secp256k1 software fallback	P-256 only, with an interactive FragmentActivity and enrolled BIOMETRIC_STRONG; Android Keystore auth-per-use and current-set invalidation
iOS	Existing mobile provider behavior: P-256/P-384/P-521/RSA in Keychain/Secure Enclave where configured; Ed25519/secp256k1 software fallback	P-256 only on a qualifying physical device, backed by Secure Enclave with biometric-current-set private-key use

Other protected key-type combinations return an explicit unsupported result and never fall back to software storage. RSA3072 and RSA4096 remain outside the current mobile provider's existing algorithm support.

Compatibility and caveats

• None remains the default. Existing configuration and legacy (KeyType) -> Key generators retain their unprotected behavior; legacy generators are not interpreted as supporting protected requests.
• Existing database rows migrate to None, and changing a wallet default affects future keys only. Existing keys are neither replaced nor reclassified.
• The operating system owns the biometric UI. Prompt reason and cancellation text are host-configurable and passed through Signum.
• The pinned Signum version may collapse cancellation, lockout, and related prompt failures into one structured AuthorizationFailed outcome; exception messages and numeric codes are not parsed.
• Android hardware backing is reported only from effective platform key information; no StrongBox preference is presented as proof of StrongBox use.
• Physical iOS Secure Enclave/Face ID/Touch ID signing could not be exercised in the available environment. The Android operator-driven success/cancel prompt cases were exercised on an enrolled API 37 emulator; a physical-iOS device run remains required before removing this draft caveat.

Explicit non-goals

Wallet launch/PIN handling, app unlock, action-scoped or batch authorization, existing-key rotation/migration (WAL-749/WAL-999), remote/HSM signing (WAL-998), wallet/key attestation (WAL-1060), and the broader typed-error redesign (WAL-1066) remain out of scope.

The use of platform biometrics, Keystore, Keychain, or Secure Enclave does not establish WSCD, LoA High, ISO 18045, EUDI, or HAIP certification.

Breaking changes

Existing None source call sites remain compatible through defaults and overloads. The KMP binary ABI changes through expanded configuration, metadata, and store-capability surfaces, so precompiled consumers must rebuild against the updated artifacts. Swift callers with exhaustive switches over WalletError must handle the new .keyUseAuthorization case.

[linear-code]

WAL-1183

WAL-1207

WAL-1209

WAL-1208

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4ea8f4d4-d5e0-493d-a636-0d44d075fb5e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud