Bifrost

https://github.com/zacharee/samloaderkotlin
Admin
Bifrost is a cross-platform firmware downloader for Samsung devices with a graphical UI built using...
Tokens:8,799
Snippets:56
Trust Score:10
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Retrieve Binary File Info with Kotlin

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Use this function to get firmware file metadata like path, size, and CRC32. It includes retry logic for IMEI validation and handles version exceptions.

```kotlin
object Request {
    // Retrieve binary file info with retry logic for IMEI validation
    suspend fun retrieveBinaryFileInfo(
        fw: String,
        model: String,
        region: String,
        imeiSerial: String,
        onFinish: suspend (String) -> Unit,
        onVersionException: (suspend (VersionException, BinaryFileInfo?) -> Unit)? = null,
        shouldReportError: suspend (Exception) -> Boolean = { true },
    ): BinaryFileInfo?

    // Generate logic check for firmware validation
    fun getLogicCheck(input: String, nonce: String): String

    // Create binary init request XML for download authorization
    fun createBinaryInit(
        fileName: String,
        nonce: String,
        fw: String,
        modelType: String,
        region: String,
    ): String
}

// BinaryFileInfo data class
data class BinaryFileInfo(
    val path: String,          // Server path to firmware
    val fileName: String,      // Encrypted filename (e.g., "SM-G998B_...enc4")
    val size: Long,            // File size in bytes
    val crc32: Long?,
    val v4Key: Pair<ByteArray, String>?,
    val fwVer: String,         // Firmware version string
    val modelType: String,     // Device model type
    val logicVal: String,      // Logic value for key generation
)

// Example: Retrieving firmware file information
val info = Request.retrieveBinaryFileInfo(
    fw = "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1",
    model = "SM-G998B",
    region = "DBT",
    imeiSerial = "",
    onFinish = { status -> println(status) },
    onVersionException = { exception, info ->
        println("Version mismatch: ${exception.message}")
    }
)

info?.let {
    println("File: ${it.fileName}")
    println("Size: ${it.size / 1024 / 1024} MB")
    println("Path: ${it.path}")
}
```

--------------------------------

### Build Desktop Binary with Gradle (Windows)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Build the desktop binary using the gradlew command. This command is for Windows.

```bash
.\gradlew.bat :desktop:build
```

--------------------------------

### Build Desktop Binary with Gradle (macOS/Linux)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Build the desktop binary using the gradlew command. This command is for macOS and Linux.

```bash
./gradlew :desktop:build
```

--------------------------------

### Build and Package Application

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Use Gradle and Conveyor to build the application for desktop and Android platforms.

```bash
# Desktop - Run debug build
./gradlew :desktop:run

# Desktop - Build for specific platform using Conveyor
./gradlew :desktop:build
conveyor -Kapp.machines=windows.amd64 make windows-zip
conveyor -Kapp.machines=linux.amd64 make debian-package
conveyor -Kapp.machines=mac.amd64 make unnotarized-mac-zip

# Android - Build APK
./gradlew :android:build
# Output: android/build/outputs/apk/debug/android-debug.apk

# ARM64 variants
conveyor -Kapp.machines=windows.arm64 make windows-zip
conveyor -Kapp.machines=linux.arm64 make linux-tarball
conveyor -Kapp.machines=mac.arm64 make unnotarized-mac-zip
```

--------------------------------

### Build Desktop Binary with Conveyor (Windows ARM64)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build a Windows zip binary for ARM64 systems using Conveyor.

```bash
conveyor -Kapp.machines=windows.arm64 make windows-zip
```

--------------------------------

### Run Desktop Debug Binary with Gradle (Windows)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Execute the :desktop:run Gradle task to launch a debug version of the desktop application. This command is for Windows.

```bash
.\gradlew :desktop:run
```

--------------------------------

### Build Desktop Binary with Conveyor (Windows x86)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build a Windows zip binary for Intel/AMD (x86) systems using Conveyor.

```bash
conveyor -Kapp.machines=windows.amd64 make windows-zip
```

--------------------------------

### Run Desktop Debug Binary with Gradle

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Execute the :desktop:run Gradle task to launch a debug version of the desktop application. This command is for macOS and Linux.

```bash
./gradlew :desktop:run
```

--------------------------------

### Build Desktop Binary with Conveyor (macOS Apple Silicon)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build an unnotarized macOS zip binary for Apple Silicon Macs using Conveyor.

```bash
conveyor -Kapp.machines=mac.arm64 make unnotarized-mac-zip
```

--------------------------------

### Build Desktop Binary with Conveyor (macOS Intel)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build an unnotarized macOS zip binary for Intel Macs using Conveyor.

```bash
conveyor -Kapp.machines=mac.amd64 make unnotarized-mac-zip
```

--------------------------------

### Build and Running Commands

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Commands for building and running the application on various platforms using Gradle and Conveyor.

```APIDOC
## Building and Running

Build commands for different platforms using Gradle and Conveyor.

### Desktop

- **Run debug build**: `./gradlew :desktop:run`
- **Build for specific platform using Conveyor**: `./gradlew :desktop:build`
  - `conveyor -Kapp.machines=windows.amd64 make windows-zip`
  - `conveyor -Kapp.machines=linux.amd64 make debian-package`
  - `conveyor -Kapp.machines=mac.amd64 make unnotarized-mac-zip`

### Android

- **Build APK**: `./gradlew :android:build`
  - Output: `android/build/outputs/apk/debug/android-debug.apk`

### ARM64 Variants

- `conveyor -Kapp.machines=windows.arm64 make windows-zip`
- `conveyor -Kapp.machines=linux.arm64 make linux-tarball`
- `conveyor -Kapp.machines=mac.arm64 make unnotarized-mac-zip`
```

--------------------------------

### Build Desktop Binary with Conveyor (Linux x86)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build a Linux tarball for Intel/AMD (x86) systems using Conveyor.

```bash
conveyor -Kapp.machines=linux.amd64 make linux-tarball
```

--------------------------------

### Build Desktop Binary with Conveyor (Linux ARM64)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build a Linux tarball for ARM64 systems using Conveyor.

```bash
conveyor -Kapp.machines=linux.arm64 make linux-tarball
```

--------------------------------

### Build Desktop Binary with Conveyor (Debian ARM64)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build a Debian package for ARM64 systems using Conveyor.

```bash
conveyor -Kapp.machines=linux.arm64 make debian-package
```

--------------------------------

### Build Desktop Binary with Conveyor (Debian x86)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Use this command to build a Debian package for Intel/AMD (x86) systems using Conveyor.

```bash
conveyor -Kapp.machines=linux.amd64 make debian-package
```

--------------------------------

### Build Android Debug APK with Gradle (Windows)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Build the Android debug APK using the gradlew command. This command is for Windows.

```bash
gradlew :android:build
```

--------------------------------

### Manage Application Settings

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Configure application preferences via BifrostSettings. These settings can be observed as StateFlow for use in Jetpack Compose.

```kotlin
object BifrostSettings {
    object Keys {
        val useMicaEffect: SettingsKey.Boolean<Boolean>          // Windows Mica effect
        val useVibrancyEffect: SettingsKey.Boolean<Boolean>      // macOS vibrancy
        val allowLowercaseCharacters: SettingsKey.Boolean<Boolean>
        val autoDeleteEncryptedFirmware: SettingsKey.Boolean<Boolean>
        val enableDecryptKeySave: SettingsKey.Boolean<Boolean>   // Save decryption key
        val useFileFramework: SettingsKey.Boolean<Boolean>       // Android file access
    }

    val settings: ObservableSettings
}

// Example: Configuring application settings
BifrostSettings.Keys.autoDeleteEncryptedFirmware(true)  // Auto-delete .enc files
BifrostSettings.Keys.enableDecryptKeySave(true)         // Save keys for offline decrypt
BifrostSettings.Keys.allowLowercaseCharacters(false)    // Force uppercase model/region

// Read settings
val autoDelete = BifrostSettings.Keys.autoDeleteEncryptedFirmware()
println("Auto-delete encrypted files: $autoDelete")

// Use as StateFlow in Compose
@Composable
fun SettingsScreen() {
    val autoDelete by BifrostSettings.Keys.autoDeleteEncryptedFirmware
        .collectAsMutableState()

    Switch(
        checked = autoDelete,
        onCheckedChange = { BifrostSettings.Keys.autoDeleteEncryptedFirmware(it) }
    )
}
```

--------------------------------

### Orchestrate Firmware Download Workflow

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Use the Downloader object to manage the complete firmware download process. It handles version checking, downloading, verification, and decryption. Ensure DownloadModel is properly initialized before calling.

```kotlin
object Downloader {
    // Start download process with model state
    suspend fun onDownload(
        model: DownloadModel,
        confirmCallback: DownloadErrorCallback,
    )

    // Fetch latest firmware version for model
    suspend fun onFetch(model: DownloadModel)
}

// DownloadModel holds download state
class DownloadModel : BaseModel("download_model") {
    val model: MutableStateFlow<String>      // Device model (e.g., "SM-G998B")
    val region: MutableStateFlow<String>     // Region CSC (e.g., "DBT")
    val fw: MutableStateFlow<String>         // Firmware version string
    val manual: MutableStateFlow<Boolean>    // Manual firmware input mode
    val progress: MutableStateFlow<Pair<Long, Long>>  // (current, total) bytes
    val speed: MutableStateFlow<Long>        // Download speed in bytes/sec
    val statusText: MutableStateFlow<String> // Current operation status
    val changelog: MutableStateFlow<Changelog?> // Firmware changelog
}

// Example: Complete download workflow
val downloadModel = DownloadModel()
downloadModel.model.value = "SM-G998B"
downloadModel.region.value = "DBT"

// Fetch latest firmware version
Downloader.onFetch(downloadModel)
println("Found firmware: ${downloadModel.fw.value}")
println("Android: ${downloadModel.osCode.value}")

// Start download
Downloader.onDownload(downloadModel, object : Downloader.DownloadErrorCallback {
    override fun onError(info: Downloader.DownloadErrorInfo) {
        println("Error: ${info.message}")
        // Handle version mismatch - can accept or cancel
        // info.callback.onAccept() to continue anyway
        // info.callback.onCancel() to abort
    }
})
```

--------------------------------

### Build Android Debug APK with Gradle (macOS/Linux)

Source: https://github.com/zacharee/samloaderkotlin/blob/master/README.md

Build the Android debug APK using the gradlew command. This command is for macOS and Linux.

```bash
./gradlew :android:build
```

--------------------------------

### Binary File Information Request

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Retrieves firmware metadata including path, size, CRC32, and decryption keys from the server.

```APIDOC
## POST /retrieveBinaryFileInfo

### Description
Retrieves binary file information for a specific firmware version, model, and region. Includes retry logic for IMEI validation.

### Method
POST

### Parameters
#### Request Body
- **fw** (String) - Required - Firmware version string
- **model** (String) - Required - Device model identifier
- **region** (String) - Required - Region code
- **imeiSerial** (String) - Required - IMEI or Serial number for validation

### Response
#### Success Response (200)
- **path** (String) - Server path to firmware
- **fileName** (String) - Encrypted filename
- **size** (Long) - File size in bytes
- **crc32** (Long) - CRC32 checksum
- **v4Key** (Pair<ByteArray, String>) - Decryption key for enc4 files
- **fwVer** (String) - Firmware version string
- **modelType** (String) - Device model type
- **logicVal** (String) - Logic value for key generation
```

--------------------------------

### Application Settings API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Manages application preferences and configuration settings.

```APIDOC
## Application Settings

The `BifrostSettings` object manages application preferences and configuration.

### Keys

- **useMicaEffect** (SettingsKey.Boolean<Boolean>): Enables or disables Windows Mica effect.
- **useVibrancyEffect** (SettingsKey.Boolean<Boolean>): Enables or disables macOS vibrancy effect.
- **allowLowercaseCharacters** (SettingsKey.Boolean<Boolean>): Allows or disallows lowercase characters in model/region.
- **autoDeleteEncryptedFirmware** (SettingsKey.Boolean<Boolean>): Enables or disables auto-deletion of encrypted firmware files (.enc).
- **enableDecryptKeySave** (SettingsKey.Boolean<Boolean>): Enables or disables saving decryption keys.
- **useFileFramework** (SettingsKey.Boolean<Boolean>): Enables or disables the Android file access framework.

### Usage

- **Setting a value**: `BifrostSettings.Keys.keyName(value)`
- **Reading a value**: `BifrostSettings.Keys.keyName()`
- **Observing changes**: Settings can be collected as `StateFlow` for reactive UI updates.

### Example Usage

```kotlin
// Configuring application settings
BifrostSettings.Keys.autoDeleteEncryptedFirmware(true)  // Auto-delete .enc files
BifrostSettings.Keys.enableDecryptKeySave(true)         // Save keys for offline decrypt
BifrostSettings.Keys.allowLowercaseCharacters(false)    // Force uppercase model/region

// Read settings
val autoDelete = BifrostSettings.Keys.autoDeleteEncryptedFirmware()
println("Auto-delete encrypted files: $autoDelete")

// Use as StateFlow in Compose
@Composable
fun SettingsScreen() {
    val autoDelete by BifrostSettings.Keys.autoDeleteEncryptedFirmware
        .collectAsMutableState()

    Switch(
        checked = autoDelete,
        onCheckedChange = { BifrostSettings.Keys.autoDeleteEncryptedFirmware(it) }
    )
}
```
```

--------------------------------

### Downloader API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Handles the firmware download workflow including version checking and file downloading.

```APIDOC
## Downloader.onFetch

### Description
Fetches the latest firmware version information for a specific device model and region.

### Method
Suspend Function

### Parameters
#### Request Body
- **model** (DownloadModel) - Required - The model state containing device model, region, and firmware details.

## Downloader.onDownload

### Description
Starts the firmware download process based on the provided model state.

### Method
Suspend Function

### Parameters
#### Request Body
- **model** (DownloadModel) - Required - The model state containing download configuration.
- **confirmCallback** (DownloadErrorCallback) - Required - Callback to handle errors or version mismatches.
```

--------------------------------

### FusClient - Core API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

The FusClient object manages all communications with Samsung's firmware update servers, handling authentication, session management, and file downloads through the NeoFUS protocol.

```APIDOC
## FusClient - Core API

### Description
Manages communications with Samsung's firmware update servers, handling authentication, session management, and file downloads via the NeoFUS protocol.

### Methods

#### `getNonce()`
- **Description**: Retrieves the current nonce, generating one if necessary.
- **Returns**: `String` - The current nonce.

#### `makeReq(request: Request, data: String = "", signature: String? = null)`
- **Description**: Makes an authenticated request to Samsung servers.
- **Parameters**:
  - **request** (`Request`) - The type of request to make (e.g., `GENERATE_NONCE`, `BINARY_INFORM`).
  - **data** (`String`) - Optional data payload for the request.
  - **signature** (`String?`) - Optional signature for the request.
- **Returns**: `String` - The XML response body as text.

#### `downloadFile(fileName: String, start: Long = 0, size: Long, dest: IPlatformFile, progressCallback: suspend (current: Long, max: Long, bps: Long) -> Unit)`
- **Description**: Downloads a firmware file with progress tracking.
- **Parameters**:
  - **fileName** (`String`) - The name of the file to download.
  - **start** (`Long`) - The starting byte offset for the download (defaults to 0).
  - **size** (`Long`) - The total size of the file to download.
  - **dest** (`IPlatformFile`) - The destination for the downloaded file.
  - **progressCallback** (`suspend (current: Long, max: Long, bps: Long) -> Unit`) - A callback function to report download progress.
- **Returns**: `String?` - The MD5 hash of the downloaded file, or null if an error occurred.

### Request Example
```kotlin
// Example: Making a binary inform request
val requestXml = Request.createBinaryInform(
    fw = "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1",
    model = "SM-G998B",
    region = "DBT",
    nonce = FusClient.getNonce()
)
val response = FusClient.makeReq(FusClient.Request.BINARY_INFORM, requestXml)
```
```

--------------------------------

### VersionFetch API and Usage

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Retrieves firmware version information and history for specific device models and regions. The hybrid approach is recommended for obtaining the most accurate latest firmware version.

```kotlin
object VersionFetch {
    // Get latest firmware version using hybrid approach (smart history + legacy)
    suspend fun hybridGetLatestVersion(
        model: String,
        region: String
    ): FetchResult.VersionFetchResult

    // Get latest version from Samsung's version.xml endpoint
    suspend fun getLatestVersion(
        model: String,
        region: String
    ): FetchResult.VersionFetchResult

    // Fetch full firmware history from Samsung
    suspend fun performHistoryRequest(
        model: String,
        region: String,
    ): Document

    // Parse history document into structured data
    fun parseHistoryInfos(historyDoc: Document): List<SmartBinaryInfo>
}

// Example: Fetching latest firmware version
val result = VersionFetch.hybridGetLatestVersion(
    model = "SM-G998B",  // Galaxy S21 Ultra
    region = "DBT"       // Germany
)

when {
    result.error != null -> println("Error: ${result.error.message}")
    else -> {
        println("Latest firmware: ${result.versionCode}")
        // Output: "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1"
        println("Android version: ${result.androidVersion}")
        // Output: "Android 13"
    }
}
```

--------------------------------

### Retrieve Firmware History

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Use the History object to fetch the complete firmware version history for a specific device model and region. This allows for downloading older firmware versions. Initialize HistoryModel with model and region.

```kotlin
object History {
    // Fetch firmware history for model/region
    suspend fun onFetch(model: HistoryModel)
}

// HistoryInfo data class
data class HistoryInfo(
    val date: LocalDate?,
    val androidVersion: String?,
    val firmwareString: String
)

// SmartBinaryInfo from Samsung's history API
data class SmartBinaryInfo(
    val index: Int?,
    val sequence: Int,
    val modelName: String,
    val displayName: String?,
    val swVersion: String,
    val displayVersion: String?,
    val localCode: String,
    val osName: String?,
    val openDate: String?,
    // ... additional fields
)

// Example: Fetching firmware history
val historyModel = HistoryModel()
historyModel.model.value = "SM-G998B"
historyModel.region.value = "DBT"

History.onFetch(historyModel)

historyModel.historyItems.value.forEach { item ->
    println("${item.date}: ${item.firmwareString} (${item.androidVersion})")
}
// Output:
// 2023/11/15: G998BXXU5CVK1/.../... (Android 13)
// 2023/09/20: G998BXXU5CVJ3/.../... (Android 13)
// 2023/07/10: G998BXXU5CVH2/.../... (Android 13)
```

--------------------------------

### History API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Retrieves historical firmware versions for a specific device.

```APIDOC
## History.onFetch

### Description
Fetches the complete firmware version history for a given device model and region.

### Method
Suspend Function

### Parameters
#### Request Body
- **model** (HistoryModel) - Required - The model state containing device identifiers to fetch history for.
```

--------------------------------

### FusClient API and Usage

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Manages communication with Samsung servers, including nonce generation, authenticated requests, and file downloads. Use the Request enum to specify the target endpoint for binary operations.

```kotlin
// FusClient handles Samsung server communication
object FusClient {
    enum class Request(val value: String, val cloud: Boolean) {
        GENERATE_NONCE("NF_SmartDownloadGenerateNonce.do", false),
        BINARY_INFORM("NF_SmartDownloadBinaryInform.do", false),
        BINARY_INIT("NF_SmartDownloadBinaryInitForMass.do", false),
        HISTORY("SmartHistory.do", false),
    }

    // Get current nonce (generates if needed)
    suspend fun getNonce(): String

    // Make authenticated request to Samsung servers
    // Returns XML response body as text
    suspend fun makeReq(
        request: Request,
        data: String = "",
        signature: String? = null
    ): String

    // Download firmware file with progress tracking
    suspend fun downloadFile(
        fileName: String,
        start: Long = 0,
        size: Long,
        dest: IPlatformFile,
        progressCallback: suspend (current: Long, max: Long, bps: Long) -> Unit,
    ): String?  // Returns MD5 hash
}

// Example: Making a binary inform request
val requestXml = Request.createBinaryInform(
    fw = "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1",
    model = "SM-G998B",
    region = "DBT",
    nonce = FusClient.getNonce()
)
val response = FusClient.makeReq(FusClient.Request.BINARY_INFORM, requestXml)
```

--------------------------------

### Version Fetching API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

The VersionFetch object retrieves the latest firmware version and firmware history for a device model and region combination.

```APIDOC
## Version Fetching API

### Description
Retrieves the latest firmware version and firmware history for a given device model and region.

### Methods

#### `hybridGetLatestVersion(model: String, region: String)`
- **Description**: Gets the latest firmware version using a hybrid approach (smart history + legacy).
- **Parameters**:
  - **model** (`String`) - The device model (e.g., "SM-G998B").
  - **region** (`String`) - The device region (e.g., "DBT").
- **Returns**: `FetchResult.VersionFetchResult` - The result of the version fetch operation.

#### `getLatestVersion(model: String, region: String)`
- **Description**: Fetches the latest firmware version directly from Samsung's `version.xml` endpoint.
- **Parameters**:
  - **model** (`String`) - The device model.
  - **region** (`String`) - The device region.
- **Returns**: `FetchResult.VersionFetchResult` - The result of the version fetch operation.

#### `performHistoryRequest(model: String, region: String)`
- **Description**: Fetches the full firmware history from Samsung.
- **Parameters**:
  - **model** (`String`) - The device model.
  - **region** (`String`) - The device region.
- **Returns**: `Document` - The firmware history document.

#### `parseHistoryInfos(historyDoc: Document)`
- **Description**: Parses a firmware history document into structured data.
- **Parameters**:
  - **historyDoc** (`Document`) - The firmware history document to parse.
- **Returns**: `List<SmartBinaryInfo>` - A list of structured firmware history information.

### Request Example
```kotlin
// Example: Fetching latest firmware version
val result = VersionFetch.hybridGetLatestVersion(
    model = "SM-G998B",  // Galaxy S21 Ultra
    region = "DBT"       // Germany
)

when {
    result.error != null -> println("Error: ${result.error.message}")
    else -> {
        println("Latest firmware: ${result.versionCode}")
        // Output: "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1"
        println("Android version: ${result.androidVersion}")
        // Output: "Android 13"
    }
}
```
```

--------------------------------

### Generate V2 Decryption Key with Kotlin

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Generates the decryption key for older enc2 firmware formats using an MD5 hash of the region, model, and version. The key string is also returned.

```kotlin
object CryptUtils {
    // Generate decryption key for enc2 format
    // Key = MD5("region:model:version")
    fun getV2Key(
        version: String,
        model: String,
        region: String
    ): Pair<ByteArray, String>

    // Retrieve decryption key for enc4 format (requires server request)
    suspend fun getV4Key(
        version: String,
        model: String,
        region: String,
        imeiSerial: String,
        tries: Int = 0
    ): Pair<ByteArray, String>?

    // Decrypt firmware file with progress callback
    suspend fun decryptProgress(
        inf: Source,
        outf: Sink,
        key: ByteArray,
        length: Long,
        chunkSize: Int = DEFAULT_CHUNK_SIZE,
        progressCallback: suspend (current: Long, max: Long, bps: Long) -> Unit,
    )

    // Verify file integrity
    suspend fun checkCrc32(
        enc: Source?,
        encSize: Long,
        expected: Long,
        progressCallback: suspend (current: Long, max: Long, bps: Long) -> Unit,
    ): Boolean

    suspend fun checkMD5(md5: String, updateFile: Source?): Boolean
}

// Example: Decrypting enc2 firmware file
val (key, keyString) = CryptUtils.getV2Key(
    version = "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1",
    model = "SM-G998B",
    region = "DBT"
)
// keyString = "DBT:SM-G998B:G998BXXU5CVK1/G998BOXM5CVK1/..."

CryptUtils.decryptProgress(
    inf = encryptedFile.openInputStream(),
    outf = decryptedFile.openOutputStream(),
    key = key,
    length = encryptedFile.getLength(),
) { current, max, bps ->
    val percent = (current * 100 / max)
    val speedMBps = bps / 1024 / 1024
    println("Decrypting: $percent% at $speedMBps MB/s")
}
```

--------------------------------

### Decryption Utilities

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Utilities for generating decryption keys and decrypting firmware files using enc2 and enc4 formats.

```APIDOC
## POST /getV2Key

### Description
Generates a decryption key for enc2 format firmware.

### Method
POST

### Parameters
#### Request Body
- **version** (String) - Required - Firmware version
- **model** (String) - Required - Device model
- **region** (String) - Required - Region code

### Response
#### Success Response (200)
- **key** (Pair<ByteArray, String>) - Decryption key pair

## POST /getV4Key

### Description
Retrieves a decryption key for enc4 format firmware from the server.

### Method
POST

### Parameters
#### Request Body
- **version** (String) - Required - Firmware version
- **model** (String) - Required - Device model
- **region** (String) - Required - Region code
- **imeiSerial** (String) - Required - IMEI or Serial number

### Response
#### Success Response (200)
- **key** (Pair<ByteArray, String>) - Decryption key pair
```

--------------------------------

### Decrypt Encrypted Firmware Files

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Utilize the Decrypter object for decrypting firmware files. It supports direct file input or opening a file picker. Ensure the input file has a .enc2 or .enc4 extension.

```kotlin
object Decrypter {
    // Decrypt a firmware file
    suspend fun onDecrypt(model: DecryptModel)

    // Open file picker for encrypted file
    suspend fun onOpenFile(model: DecryptModel)

    // Process file input (validates .enc2 or .enc4 extension)
    fun handleFileInput(model: DecryptModel, info: DecryptFileInfo?)
}

// DecryptModel holds decryption state
class DecryptModel : BaseModel("decrypt_model") {
    val model: MutableStateFlow<String>      // Device model
    val region: MutableStateFlow<String>     // Region CSC
    val fw: MutableStateFlow<String>         // Firmware version
    val fileToDecrypt: MutableStateFlow<DecryptFileInfo?> // Input/output files
    val decryptionKey: MutableStateFlow<String> // Optional manual key
    val progress: MutableStateFlow<Pair<Long, Long>>
    val speed: MutableStateFlow<Long>
}

// Example: Decrypting a previously downloaded file
val decryptModel = DecryptModel()
dedecryptModel.model.value = "SM-G998B"
dedecryptModel.region.value = "DBT"
dedecryptModel.fw.value = "G998BXXU5CVK1/G998BOXM5CVK1/G998BXXU5CVK1/G998BXXU5CVK1"

// Set input file (must end in .enc2 or .enc4)
dedecryptModel.fileToDecrypt.value = DecryptFileInfo(
    encFile = platformFile("/path/to/firmware.enc4"),
    decFile = platformFile("/path/to/firmware.zip")
)

// Optional: Provide decryption key directly (skips server request)
// decryptModel.decryptionKey.value = "your-decryption-key"

Decrypter.onDecrypt(decryptModel)
```

--------------------------------

### Generate Test IMEIs

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Generate valid test IMEIs using TAC codes retrieved from the IMEIDatabase. The IMEIDatabase provides mappings based on device models.

```kotlin
data object IMEIGenerator {
    // Generate valid IMEIs for given TAC codes
    fun makeImeisForTacs(tacs: Set<String>): List<String>
}

data object IMEIDatabase {
    val DUMMY_SERIALS = arrayOf("123456", "012345", "011111", "005555", "020202")

    // Get TACs for a specific model
    fun mapByModel(model: String?): Flow<Set<String>?>
}

// Example: Generating test IMEIs for a device model
val tacs = IMEIDatabase.mapByModel("SM-G998B").first()
tacs?.let {
    val imeis = IMEIGenerator.makeImeisForTacs(it)
    println("Generated ${imeis.size} test IMEIs")
    imeis.take(3).forEach { imei -> println(imei) }
}
// Output:
// Generated 10 test IMEIs
// 353256101234560
// 353256101234577
// 353256012345674
```

--------------------------------

### IMEI Generation API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Utilities for generating valid test IMEIs using TAC (Type Allocation Code) data.

```APIDOC
## IMEI Generation

The `IMEIGenerator` generates valid test IMEIs from TAC (Type Allocation Code) database for firmware requests.

### Functions

- **IMEIGenerator.makeImeisForTacs(tacs: Set<String>)**: Generates a list of valid IMEIs for the given TAC codes.
- **IMEIDatabase.mapByModel(model: String?)**: Returns a Flow of a Set of TAC codes for a specific device model.

### Constants

- **IMEIDatabase.DUMMY_SERIALS**: An array of dummy serial numbers used for IMEI generation.

### Example Usage

```kotlin
// Example: Generating test IMEIs for a device model
val tacs = IMEIDatabase.mapByModel("SM-G998B").first()
tacs?.let {
    val imeis = IMEIGenerator.makeImeisForTacs(it)
    println("Generated ${imeis.size} test IMEIs")
    imeis.take(3).forEach { imei -> println(imei) }
}
```
```

--------------------------------

### Decrypter API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Provides functionality to decrypt encrypted firmware files (.enc2 or .enc4).

```APIDOC
## Decrypter.onDecrypt

### Description
Decrypts a firmware file based on the configuration in the DecryptModel.

### Method
Suspend Function

### Parameters
#### Request Body
- **model** (DecryptModel) - Required - The model state containing file paths and decryption keys.

## Decrypter.handleFileInput

### Description
Processes and validates file input for decryption.

### Method
Function

### Parameters
#### Request Body
- **model** (DecryptModel) - Required - The decryption model.
- **info** (DecryptFileInfo) - Optional - File information for the encrypted file.
```

--------------------------------

### Query Samsung CSC Database

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Use the CSCDB object to search for region codes, countries, and carriers. The CSCItem data class defines the structure of the returned database entries.

```kotlin
data object CSCDB {
    // Get all CSC items
    fun getAll(): List<CSCItem>

    // Search by country name
    fun findForCountryQuery(query: String): List<CSCItem>

    // Search by CSC code
    fun findForCscQuery(query: String): List<CSCItem>

    // Search by carrier name
    fun findForCarrierQuery(query: String): List<CSCItem>

    // General search across all fields
    fun findForGeneralQuery(query: String, items: Set<CSCItem>): List<CSCItem>
}

data class CSCItem(
    val code: String,           // CSC code (e.g., "DBT")
    val countries: List<String>, // Country codes (e.g., ["DE"])
    val carriers: List<String>?  // Carrier names (e.g., ["T-Mobile"])
)

// Example: Finding CSC codes for Germany
val germanCscs = CSCDB.findForCountryQuery("Germany")
germanCscs.forEach { csc ->
    println("${csc.code}: ${csc.countries.joinToString()} - ${csc.carriers?.joinToString()}")
}
// Output:
// DBT: DE - null (Unlocked)
// DTM: DE - T-Mobile
// VD2: DE - Vodafone
```

--------------------------------

### CSC Database API

Source: https://context7.com/zacharee/samloaderkotlin/llms.txt

Provides access to a searchable database of Samsung region codes (CSC) with associated countries and carriers.

```APIDOC
## CSC Database

The `CSCDB` data object provides a searchable database of Samsung region codes (CSC) with associated countries and carriers.

### Functions

- **getAll()**: Returns a list of all `CSCItem` objects.
- **findForCountryQuery(query: String)**: Searches for `CSCItem` objects by country name.
- **findForCscQuery(query: String)**: Searches for `CSCItem` objects by CSC code.
- **findForCarrierQuery(query: String)**: Searches for `CSCItem` objects by carrier name.
- **findForGeneralQuery(query: String, items: Set<CSCItem>)**: Performs a general search across all fields of `CSCItem` objects.

### Data Structures

#### CSCItem

- **code** (String) - The CSC code (e.g., "DBT").
- **countries** (List<String>) - A list of country codes (e.g., ["DE"]).
- **carriers** (List<String>?)- An optional list of carrier names (e.g., ["T-Mobile"]).

### Example Usage

```kotlin
// Example: Finding CSC codes for Germany
val germanCscs = CSCDB.findForCountryQuery("Germany")
germanCscs.forEach { csc ->
    println("${csc.code}: ${csc.countries.joinToString()} - ${csc.carriers?.joinToString()}")
}
```
```
Tokens:
Raw