Shade/android/shade-android/ROADMAP-ANDROID.md

Shade Android — Roadmap & Parity Status

This document tracks the M-Cross milestones from docs/V3.5.md and the status of every cross-platform parity sjekkpunkt. The Kotlin port must be byte-for-byte compatible with the TypeScript implementation; this is verified continuously by test-vectors/*.json consumed by both runners.

No "production" label is allowed on Android until M-Cross 2 is green (ratchet + wire 0x02 + storage encryption) and M-Cross 3 is green (streams 0x11). See docs/V3.5.md §Akseptansekriterier.

Milestones

M-Cross 1 — Scaffold ✅

Foundation primitives. All passing in CI.

Sjekkpunkt	Vector	TS test	Kotlin test
1. KDF chain (root + chain ratchet)	kdf-chain.json	✅	✅
2. HKDF labels	hkdf.json	✅	✅
3. X3DH initial root key (3 + 4 DH outputs)	x3dh.json	✅	✅
5. Fingerprint (60-digit safety number)	fingerprint.json	✅	✅

M-Cross 2 — Ratchet & Wire 0x02 ✅

Full ratchet step + binary envelope encoding for both message types.

Sjekkpunkt	Vector	TS test	Kotlin test
4. Ratchet step (encrypt deterministic)	ratchet-step.json	✅	✅
4. Ratchet step (decrypt roundtrip)	ratchet-step.json	✅	✅
6. Wire 0x02 RatchetMessage	wire-format.json	✅	✅
6. Wire 0x02 PreKeyMessage (with OTPK)	wire-format.json	✅	✅
6. Wire 0x02 PreKeyMessage (no OTPK, 0xFFFFFFFF marker)	wire-format.json	✅	✅

The ratchet-step vector exercises every layer that contributes to a ratchet message's wire bytes: kdfRootKey → kdfChainKey → 40-byte header AAD → AES-256-GCM with deterministic nonce. Both implementations recompute each layer and compare against the recorded hex. The decrypt half feeds the recorded ciphertext back through aesGcmDecrypt(messageKey, nonce, aad) and checks the plaintext recovers — proving the AEAD agrees in both directions.

M-Cross 3 — Streams 0x11 ✅

Multi-lane chunk encryption (@shade/streams) ported. KDF labels with embedded NULs match TS byte-for-byte; deterministic (laneId, seq)-derived nonces and the 29-byte chunk AAD agree across runners; wire 0x11 encode/decode is roundtrip-verified.

Sjekkpunkt	Vector	TS test	Kotlin test
deriveStreamKey (HKDF, info shade-stream/v1\0master)	streams.json	✅	✅
deriveLaneKey (HKDF, info shade-stream/v1\0lane\0 ‖ u32_be laneId) — incl. laneId 0xFFFFFFFF	streams.json	✅	✅
buildChunkNonce(laneId, seq) — incl. seq = 2^64 - 2	streams.json	✅	✅
buildChunkAad(streamId, laneId, seq, isLast)	streams.json	✅	✅
Chunk AES-256-GCM encrypt + decrypt (deterministic nonce + AAD)	streams.json	✅	✅
Wire 0x11 envelope encode + decode + type-tag inspector	streams.json	✅	✅

Sequence numbers are unsigned u64 on the wire; the Kotlin port accepts them as Long for the bit pattern (negative-signed-long for values past 2^63 - 1) — this matches the JVM ByteBuffer.putLong behavior and the java.lang.Long.parseUnsignedLong JSON-decoder used in tests.

Pending end-to-end interop test (TS server → Kotlin client over an actual socket) — not gated by vectors but recommended before flipping the "production" label.

M-Cross 4 — Backup, Group, Storage HKDF ✅ (cryptographic layer)

The cryptographic primitives that Kotlin needs to share with TS are now covered. The remaining work is the high-level glue (BackupBlob JSON schema, full SenderKey/GroupSession state-tracking, Android-Keystore storage adapter, scrypt password-KDF) — all per-platform plumbing that doesn't gate vector parity.

Sjekkpunkt	Vector	TS test	Kotlin test
7. Backup v1 HKDF (info="ShadeBackupKey")	backup.json	✅	✅
7. Backup v1 AES-GCM roundtrip (no AAD)	backup.json	✅	✅
Group sender header AAD (u16/u16/u32 length prefixes)	group.json	✅	✅
Group sender-key step: kdfChainKey + AES-GCM + Ed25519 sign(aad ‖ ct)	group.json	✅	✅
Storage HKDF: storageKey (info="shade-storage-v1")	storage-hkdf.json	✅	✅
Storage HKDF: fieldKey (info="shade-field-v1:{table}:{column}")	storage-hkdf.json	✅	✅
Storage HKDF: rowNonce (info="shade-row-nonce-v1:{table}:{pk}")	storage-hkdf.json	✅	✅

Pending sub-tasks (don't gate vector parity):

• scrypt master-key derivation: test-vectors/storage-encryption.json pins scrypt(N=1024, r=8, p=1, dkLen=32) for unit-test config; Tink doesn't ship scrypt. Add Bouncy Castle (org.bouncycastle:bcprov-jdk18on) to the Kotlin module, wrap as CryptoProvider.scrypt(...), then a follow-up vector consumes the full storage-encryption.json end to end.
• argon2id: Both backup.ts and the threat-model docs flag HKDF as a placeholder for a real password KDF. When argon2id is added to CryptoProvider, both ports swap together and the backup vector gets re-pinned.
• Android KeystoreStorage adapter: lives in a sibling Android Library Gradle module that depends on this JVM module. Binds Tink to the Android Keystore + EncryptedSharedPreferences.

Build & Test

This module compiles as a pure-JVM Kotlin library (kotlin("jvm")) so the parity gate can run without an Android SDK installation in CI. The protocol code uses tink:1.15.0 (JVM JAR), java.nio.ByteBuffer, and javax.crypto — no android.* imports.

The Android-specific storage adapter (KeystoreStorage, EncryptedSharedPreferences) will land as a sibling Gradle module (shade-android-keystore) in M-Cross 4 and depend on this one.

# From repo root
cd android
./gradlew :shade-android:test

Requires JDK 17. The Gradle wrapper downloads Gradle 8.10.2 on first run.

Compatibility contract

The Kotlin implementation must produce byte-identical output to the TS reference for:

• KDF chain derivations (root key ratchet, chain key ratchet)
• X3DH shared secrets (3- and 4-DH variants)
• Ratchet message keys + AES-GCM ciphertext (given the same key/plaintext/AAD/nonce)
• Header AAD encoding (40 bytes: dhPublicKey(32) || u32_be(prevCounter) || u32_be(counter))
• Fingerprints (12 × 5-digit groups)
• Binary wire format 0x02 (RatchetMessage + PreKeyMessage)
• Binary wire format 0x11 (StreamChunk) — M-Cross 3
• Storage encryption KDF chain — M-Cross 4

Each is covered by a vector file in /test-vectors/. Adding a new sjekkpunkt: see docs/cross-platform.md.