heyaibi/s4

Purpose and Runtime

S4 is a fully offline Android backup application for converting BIP-39 wallet entropy into threshold SLIP-39 paper mnemonic shares and restoring it later. It targets Android API 26–37 and uses Kotlin, Jetpack Compose, Material 3, Navigation Compose, NDK/CMake, and JNI. No backend or network service is part of the architecture.

Entry point: app/src/main/java/com/s4/MainActivity.kt. Android packaging and security constraints, including no network permission and backup restrictions, are in app/src/main/AndroidManifest.xml.

Application Navigation and Screen Boundary

MainActivity owns the Compose navigation graph and app-level secure-screen behavior. Routes separate the principal workflows: Split, Restore, results, and Recovery Guide.

• app/src/main/java/com/s4/navigation/Routes.kt

• app/src/main/java/com/s4/ui/SplitScreen.kt

• app/src/main/java/com/s4/ui/RestoreScreen.kt

UI state is memory-only: secret-bearing form values are not intended for persisted saved-state or disk storage. Result screens retain an in-memory session until completion, then discard it.

Split Workflow

The Split screen collects either BIP-39 mnemonic words or raw entropy, an optional BIP-39 passphrase, and threshold/count parameters. SplitViewModel validates and orchestrates the conversion pipeline:

1. parse or generate entropy;

2. derive/display a fingerprint;

3. call SLIP-39 native generation;

4. expose stable mnemonic shares and an optional recovery guide.

• app/src/main/java/com/s4/ui/SplitViewModel.kt

• app/src/main/java/com/s4/model/SplitParams.kt

• app/src/main/java/com/s4/ui/SplitResultScreen.kt

The app shards entropy, not the PBKDF2 wallet seed. The BIP-39 passphrase remains separate from shares by design.

Restore Workflow

Restore accepts one share per line, supports SLIP-39 word completion, parses and validates shares, then combines a qualifying threshold into entropy. That entropy is converted back to BIP-39 words and fingerprinted; the entered passphrase can be verified against the expected fingerprint.

• app/src/main/java/com/s4/ui/RestoreScreen.kt

• app/src/main/java/com/s4/crypto/ShareCodec.kt

• app/src/main/java/com/s4/ui/WordCompletion.kt

Errors at this boundary include malformed/checksum-invalid shares, insufficient shares, and incompatible share sets; these are surfaced through Kotlin exception types rather than leaking native details.

Kotlin Crypto Domain Layer

Kotlin provides the application-facing crypto API, input/result shaping, exception handling, and wordlist access. BIP-39 handles entropy-to-mnemonic conversion, seed derivation, and SHA-256 fingerprinting. SLIP-39 and Shamir wrappers bridge to the native implementation.

• app/src/main/java/com/s4/bip39/Bip39.kt

• app/src/main/java/com/s4/crypto/Slip39.kt

• app/src/main/java/com/s4/crypto/Shamir.kt

Static BIP-39 and SLIP-39 vocabularies are bundled locally in app/src/main/resources/wordlist.txt and app/src/main/resources/slip39-wordlist.txt.

Native Cryptography Boundary

Cryptographic splitting and combination execute in vendored C libraries compiled through CMake/Android NDK. Thin JNI facades define the Kotlin/native boundary. SLIP-39 uses a single configured group and native randomness is supplied from Android SecureRandom through callbacks.

• app/src/main/cpp/CMakeLists.txt

• app/src/main/cpp/slip39_jni.cpp

• app/src/main/cpp/shamir_jni.cpp

Vendored primitives and algorithms reside under app/src/main/cpp/bc-slip39, app/src/main/cpp/bc-shamir, and app/src/main/cpp/bc-crypto-base; this avoids OpenSSL and external crypto services.

Recovery and Device Provisioning

The Recovery Guide produces durable, plain-language recovery instructions based on the active split session, including the requirement to preserve the BIP-39 passphrase separately.

• app/src/main/java/com/s4/guide/RecoveryGuide.kt

• app/src/main/java/com/s4/ui/RecoveryGuideScreen.kt

Outside the app, one-shot ADB provisioning hardens the dedicated phone, installs specified APKs with checksum verification, disables radios/bloatware, and configures prerequisites for the anti-forensics deployment model.

• airgap/airgap.sh

• airgap/apps.json

• airgap/packages.txt