Grant

Type-safe permission management for Kotlin Multiplatform — Android & iOS

Documentation · Quick start · Why Grant? · Demo app

Grant handles the permission edge cases that simple wrappers miss: silent deadlocks, Android process death, iOS Info.plist crashes, partial media/location access, and hardware service state. The API is logic-first — request permissions from a ViewModel or repository with no Activity, Fragment, or lifecycle binding.

class CameraViewModel(grantManager: GrantManager) : ViewModel() {
    val cameraGrant = GrantHandler(grantManager, AppGrant.CAMERA, viewModelScope)

    fun onCaptureClick() = viewModelScope.launch {
        if (cameraGrant.requestSuspend() == GrantStatus.GRANTED) {
            cameraEngine.start()
        }
    }
}

@Composable
fun CameraScreen(viewModel: CameraViewModel) {
    GrantDialog(handler = viewModel.cameraGrant)   // renders rationale / settings-guide dialogs (Material 3)

    Button(onClick = viewModel::onCaptureClick) { Text("Start camera") }
}

Requirements: Android 8.0+ (API 26) · iOS 13+ · Kotlin 2.x · JVM 17

• Logic-first API — works in ViewModels, repositories, or composables. No Activity or Fragment references, no lifecycle binding.
• iOS framework isolation — Contacts, Calendar, Motion, Bluetooth, and background location live in opt-in modules. Frameworks you don't use are never linked, so Apple's static scanner never demands phantom NSUsageDescription keys.
• iOS crash guard — validates Info.plist keys before requesting, turning the classic SIGABRT production crash into a clear error.
• Android process-death recovery — a request in flight survives system-initiated process death via SavedStateHandle, with no timeouts.
• Deadlock-free by construction — reentrant locking plus a withTimeout test policy that converts silent deadlocks into failing tests.
• 19 built-in permissions — Camera, Gallery (incl. Android 14 partial access), Location (incl. "Approximate"-only), Bluetooth, Local Network (Android 17), and more — plus RawPermission for anything the library doesn't ship yet.
• Service-state checks — one call answers both "is the permission granted?" and "is GPS/Bluetooth actually on?".
• Material 3 dialogs — optional grant-compose module renders the rationale and settings-guide flow out of the box.
• Heavily tested — 2,100+ test executions across Android and iOS targets on every build, including concurrency-stress, regression, and process-death suites.

Grant is published to Maven Central. Add the core module, plus only the optional modules you use:

// shared/build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.brewkits:grant-core:2.3.0")

            // Optional
            implementation("dev.brewkits:grant-compose:2.3.0")          // Compose dialogs (Material 3)
            implementation("dev.brewkits:grant-core-koin:2.3.0")        // Koin DI integration

            // Optional per-permission modules. Omitting a module means its iOS
            // framework is never linked — no phantom NSUsageDescription keys.
            implementation("dev.brewkits:grant-contacts:2.3.0")         // Contacts (iOS CNContactStore)
            implementation("dev.brewkits:grant-calendar:2.3.0")         // Calendar (iOS EventKit)
            implementation("dev.brewkits:grant-motion:2.3.0")           // Motion (iOS CoreMotion)
            implementation("dev.brewkits:grant-bluetooth:2.3.0")        // Bluetooth (iOS CoreBluetooth)
            implementation("dev.brewkits:grant-location-always:2.3.0")  // Background "always" location (iOS)
        }
    }
}

Android needs no setup: Grant ships a self-contained transparent Activity, so request() opens the system dialog from anywhere. Prefer your own ActivityResultLauncher? Register it once with grantManager.setLauncher(...) and Grant uses it instead.

iOS needs one call per optional module at app startup:

// AppDelegate / @main entry point
GrantContacts.shared.initialize()        // if you added grant-contacts
GrantCalendar.shared.initialize()        // if you added grant-calendar
GrantMotion.shared.initialize()          // if you added grant-motion
GrantBluetooth.shared.initialize()       // if you added grant-bluetooth
GrantLocationAlways.shared.initialize()  // if you added grant-location-always

[!WARNING] 2.3.0 — grant-compose no longer ships an iosX64 target. Compose Multiplatform 1.11 stopped publishing iosX64 artifacts. All other modules keep iosX64; Intel-Mac-simulator consumers of grant-compose should stay on 2.2.3. Details in the Migration Guide.

[!NOTE] Migrating from v1.x? Contacts, Calendar, Motion, Bluetooth, and background location are now opt-in modules: add the artifact and call initialize() on iOS. Android needs no code changes. Projects that also target Web/Desktop should isolate Grant behind a mobileMain source set — see Dependency Management.

GrantHandler runs the full state machine for one permission — request, rationale, permanent denial, settings guide — and exposes it as a StateFlow your UI can render:

class CameraViewModel(grantManager: GrantManager) : ViewModel() {
    val cameraGrant = GrantHandler(
        grantManager = grantManager,
        grant = AppGrant.CAMERA,
        scope = viewModelScope,
        eventListener = object : GrantEventListener {
            override fun onGranted(grant: GrantPermission, status: GrantStatus) {
                analytics.track("camera_permission_granted")
            }
        }
    )

    // Suspend until the flow resolves…
    suspend fun startCapture() {
        if (cameraGrant.requestSuspend() == GrantStatus.GRANTED) cameraEngine.start()
    }

    // …or consume it reactively.
    val captureFlow = cameraGrant.requestFlow()
        .filter { it == GrantStatus.GRANTED }
        .onEach { cameraEngine.start() }
}

val scanFlow = grantFlow {
    val btStatus = bluetoothHandler.requestSuspend()
    if (btStatus == GrantStatus.GRANTED) {
        locationHandler.requestSuspend()   // needed for BLE scanning on some Android versions
    }
}

A granted location permission is useless with GPS turned off. GrantAndServiceChecker answers both questions in one call:

fun startTracking() {
    viewModelScope.launch {
        when (checker.checkLocationReady()) {
            is LocationReadyStatus.Ready           -> sensor.start()
            is LocationReadyStatus.ServiceDisabled -> uiState.showEnableGps()
            is LocationReadyStatus.GrantDenied     -> requestPermission()
            is LocationReadyStatus.BothRequired    -> uiState.showBothPrompts()
        }
    }
}

Most KMP permission libraries are thin wrappers around the native APIs. Grant is built around the failure modes those wrappers hit in production:

19 built-in permissions across Camera, Microphone, Gallery, Storage, Location, Notifications, Bluetooth, Contacts, Calendar, Motion, Exact Alarms, Nearby Wi-Fi, and Local Network — anything else via RawPermission.

Contributions are welcome — see CONTRIBUTING.md. Run ./gradlew :grant-core:allTests before submitting a PR.

Apache License 2.0 — see LICENSE.