Merge pull request #228 from kdroidFilter/feat/notarize-api-key

feat(plugin-mac): add notarytool App Store Connect API key auth

Author: kdroidFilter

docs/code-signing.md

@@ -123,15 +123,15 @@ macOS {
 
 ### Notarization
 
-Apple notarization is required for distributing outside the Mac App Store on macOS 10.15+. Two authentication modes are supported (mutually exclusive — App Store Connect API key support is planned):
+Apple notarization is required for distributing outside the Mac App Store on macOS 10.15+. Three authentication modes are supported (mutually exclusive):
 
 #### Mode 1 — Apple ID + app-specific password
 
 ```kotlin
 macOS {
     notarization {
         appleID.set("dev@example.com")
-        password.set("@keychain:AC_PASSWORD")
+        password.set(System.getenv("MAC_NOTARIZATION_PASSWORD"))
         teamID.set("TEAMID")
     }
 }
@@ -142,7 +142,7 @@ Equivalent Gradle properties:
 | Gradle property | Description |
 |-----------------|-------------|
 | `compose.desktop.mac.notarization.appleID` | Apple ID email |
-| `compose.desktop.mac.notarization.password` | App-specific password (or `@keychain:` reference) |
+| `compose.desktop.mac.notarization.password` | App-specific password |
 | `compose.desktop.mac.notarization.teamID` | Apple Team ID |
 
 #### Mode 2 — `notarytool` keychain profile
@@ -173,7 +173,31 @@ Equivalent Gradle properties:
 | `compose.desktop.mac.notarization.keychainProfile` | Profile name created via `store-credentials` |
 | `compose.desktop.mac.notarization.keychainPath` | Optional path to the keychain holding the profile |
 
-> Configuring both modes in the same build is rejected at validation time. Pick one.
+#### Mode 3 — App Store Connect API key
+
+Generate a key in [App Store Connect → Users and Access → Integrations → Team Keys](https://appstoreconnect.apple.com/access/integrations/api), download the `.p8` file once, then reference it:
+
+```kotlin
+macOS {
+    notarization {
+        apiKey.set("/path/to/AuthKey_ABC123.p8")
+        apiKeyId.set("ABC123")          // 10-char Key ID
+        apiIssuer.set("12345678-90ab-cdef-1234-567890abcdef") // Issuer UUID
+    }
+}
+```
+
+Equivalent Gradle properties:
+
+| Gradle property | Description |
+|-----------------|-------------|
+| `compose.desktop.mac.notarization.apiKey` | Path to the `.p8` API key file |
+| `compose.desktop.mac.notarization.apiKeyId` | Key ID (the 10-character identifier) |
+| `compose.desktop.mac.notarization.apiIssuer` | Issuer UUID for the team |
+
+This mode is recommended for CI/CD: API keys can be revoked independently of the Apple ID, support role-based scoping, and are not affected by 2FA.
+
+> Configuring more than one mode in the same build is rejected at validation time. Pick one.
 
 ### CI/CD: macOS Signing
 

docs/targets/macos.md

@@ -264,7 +264,7 @@ macOS {
 
     notarization {
         appleID.set("dev@example.com")
-        password.set("@keychain:AC_PASSWORD")
+        password.set(System.getenv("MAC_NOTARIZATION_PASSWORD"))
         teamID.set("TEAMID")
     }
 }

plugin-build/plugin/src/main/kotlin/io/github/kdroidfilter/nucleus/desktop/application/dsl/MacOSNotarizationSettings.kt

@@ -66,6 +66,41 @@ abstract class MacOSNotarizationSettings {
             set(NucleusProperties.macNotarizationKeychainPath(providers))
         }
 
+    /**
+     * Path to the App Store Connect API key file (`.p8`).
+     * Forwarded to `notarytool` as `--key <path>`.
+     * Mutually exclusive with the apple-id and keychain-profile modes; the trio
+     * [apiKey], [apiKeyId] and [apiIssuer] must all be set together.
+     */
+    @get:Input
+    @get:Optional
+    val apiKey: Property<String> =
+        objects.nullableProperty<String>().apply {
+            set(NucleusProperties.macNotarizationApiKey(providers))
+        }
+
+    /**
+     * App Store Connect API key ID (the 10-character identifier shown in App Store Connect).
+     * Forwarded to `notarytool` as `--key-id <id>`.
+     */
+    @get:Input
+    @get:Optional
+    val apiKeyId: Property<String> =
+        objects.nullableProperty<String>().apply {
+            set(NucleusProperties.macNotarizationApiKeyId(providers))
+        }
+
+    /**
+     * App Store Connect API issuer ID (the team's issuer UUID).
+     * Forwarded to `notarytool` as `--issuer <uuid>`.
+     */
+    @get:Input
+    @get:Optional
+    val apiIssuer: Property<String> =
+        objects.nullableProperty<String>().apply {
+            set(NucleusProperties.macNotarizationApiIssuer(providers))
+        }
+
     @Deprecated("This option is no longer supported and got replaced by teamID", level = DeprecationLevel.ERROR)
     @get:Internal
     val ascProvider: Property<String> =

plugin-build/plugin/src/main/kotlin/io/github/kdroidfilter/nucleus/desktop/application/internal/NucleusProjectProperties.kt

@@ -24,6 +24,9 @@ internal object NucleusProperties {
     internal const val MAC_NOTARIZATION_TEAM_ID_PROVIDER = "compose.desktop.mac.notarization.teamID"
     internal const val MAC_NOTARIZATION_KEYCHAIN_PROFILE = "compose.desktop.mac.notarization.keychainProfile"
     internal const val MAC_NOTARIZATION_KEYCHAIN_PATH = "compose.desktop.mac.notarization.keychainPath"
+    internal const val MAC_NOTARIZATION_API_KEY = "compose.desktop.mac.notarization.apiKey"
+    internal const val MAC_NOTARIZATION_API_KEY_ID = "compose.desktop.mac.notarization.apiKeyId"
+    internal const val MAC_NOTARIZATION_API_ISSUER = "compose.desktop.mac.notarization.apiIssuer"
     internal const val CHECK_JDK_VENDOR = "compose.desktop.packaging.checkJdkVendor"
     internal const val DISABLE_MULTIMODULE_RESOURCES = "org.jetbrains.compose.resources.multimodule.disable"
     internal const val SYNC_RESOURCES_PROPERTY = "compose.ios.resources.sync"
@@ -58,6 +61,15 @@ internal object NucleusProperties {
     @Suppress("MaxLineLength")
     fun macNotarizationKeychainPath(providers: ProviderFactory): Provider<String> = providers.valueOrNull(MAC_NOTARIZATION_KEYCHAIN_PATH)
 
+    @Suppress("MaxLineLength")
+    fun macNotarizationApiKey(providers: ProviderFactory): Provider<String> = providers.valueOrNull(MAC_NOTARIZATION_API_KEY)
+
+    @Suppress("MaxLineLength")
+    fun macNotarizationApiKeyId(providers: ProviderFactory): Provider<String> = providers.valueOrNull(MAC_NOTARIZATION_API_KEY_ID)
+
+    @Suppress("MaxLineLength")
+    fun macNotarizationApiIssuer(providers: ProviderFactory): Provider<String> = providers.valueOrNull(MAC_NOTARIZATION_API_ISSUER)
+
     fun checkJdkVendor(providers: ProviderFactory): Provider<Boolean> = providers.valueOrNull(CHECK_JDK_VENDOR).toBooleanProvider(true)
 
     fun disableMultimoduleResources(providers: ProviderFactory): Provider<Boolean> =

plugin-build/plugin/src/main/kotlin/io/github/kdroidfilter/nucleus/desktop/application/internal/configureJvmApplication.kt

@@ -877,7 +877,11 @@ internal fun JvmApplicationContext.configureCommonNotarizationSettings(notarizat
                 !notarization.password.orNull.isNullOrEmpty() &&
                 !notarization.teamID.orNull.isNullOrEmpty()
         val hasKeychainProfile = !notarization.keychainProfile.orNull.isNullOrEmpty()
-        val configured = hasAppleId || hasKeychainProfile
+        val hasApiKey =
+            !notarization.apiKey.orNull.isNullOrEmpty() &&
+                !notarization.apiKeyId.orNull.isNullOrEmpty() &&
+                !notarization.apiIssuer.orNull.isNullOrEmpty()
+        val configured = hasAppleId || hasKeychainProfile || hasApiKey
         if (!configured) {
             it.logger.info("Notarization skipped: macOS notarization settings are not configured")
         }

plugin-build/plugin/src/main/kotlin/io/github/kdroidfilter/nucleus/desktop/application/internal/validation/ValidatedMacOSNotarizationSettings.kt

@@ -19,8 +19,16 @@ internal sealed class NotarizationAuth {
         val profileName: String,
         val keychainPath: String?,
     ) : NotarizationAuth()
+
+    data class ApiKey(
+        val keyPath: String,
+        val keyId: String,
+        val issuerId: String,
+    ) : NotarizationAuth()
 }
 
+internal data class ValidatedMacOSNotarizationSettings(val auth: NotarizationAuth)
+
 /**
  * Builds the `notarytool` authentication arguments and an optional stdin payload
  * (the Apple ID password is fed via stdin to keep it off the command line).
@@ -38,10 +46,14 @@ internal fun NotarizationAuth.toNotaryToolArgs(): Pair<List<String>, String?> =
                     add(it)
                 }
             } to null
+        is NotarizationAuth.ApiKey ->
+            listOf(
+                "--key", keyPath,
+                "--key-id", keyId,
+                "--issuer", issuerId,
+            ) to null
     }
 
-internal data class ValidatedMacOSNotarizationSettings(val auth: NotarizationAuth)
-
 internal fun MacOSNotarizationSettings?.validate(): ValidatedMacOSNotarizationSettings {
     checkNotNull(this) {
         ERR_NOTARIZATION_SETTINGS_ARE_NOT_PROVIDED
@@ -52,35 +64,55 @@ internal fun MacOSNotarizationSettings?.validate(): ValidatedMacOSNotarizationSe
     val team = teamID.orNull?.takeUnless { it.isEmpty() }
     val profile = keychainProfile.orNull?.takeUnless { it.isEmpty() }
     val keychainPathValue = keychainPath.orNull?.takeUnless { it.isEmpty() }
+    val key = apiKey.orNull?.takeUnless { it.isEmpty() }
+    val keyId = apiKeyId.orNull?.takeUnless { it.isEmpty() }
+    val issuer = apiIssuer.orNull?.takeUnless { it.isEmpty() }
 
     val appleIdMode = appleId != null || pwd != null || team != null
     val keychainMode = profile != null
+    val apiKeyMode = key != null || keyId != null || issuer != null
 
-    check(!(appleIdMode && keychainMode)) {
+    val activeModes = listOf(appleIdMode, keychainMode, apiKeyMode).count { it }
+    check(activeModes <= 1) {
         ERR_MUTUALLY_EXCLUSIVE
     }
-    check(appleIdMode || keychainMode) {
+    check(activeModes == 1) {
         ERR_NO_MODE_CONFIGURED
     }
 
-    return if (profile != null) {
-        ValidatedMacOSNotarizationSettings(
-            NotarizationAuth.KeychainProfile(
-                profileName = profile,
-                keychainPath = keychainPathValue,
-            ),
-        )
-    } else {
-        checkNotNull(appleId) { ERR_APPLE_ID_IS_EMPTY }
-        checkNotNull(pwd) { ERR_PASSWORD_IS_EMPTY }
-        checkNotNull(team) { ERR_TEAM_ID_IS_EMPTY }
-        ValidatedMacOSNotarizationSettings(
-            NotarizationAuth.AppleId(
-                appleID = appleId,
-                password = pwd,
-                teamID = team,
-            ),
-        )
+    return when {
+        apiKeyMode -> {
+            checkNotNull(key) { ERR_API_KEY_IS_EMPTY }
+            checkNotNull(keyId) { ERR_API_KEY_ID_IS_EMPTY }
+            checkNotNull(issuer) { ERR_API_ISSUER_IS_EMPTY }
+            ValidatedMacOSNotarizationSettings(
+                NotarizationAuth.ApiKey(
+                    keyPath = key,
+                    keyId = keyId,
+                    issuerId = issuer,
+                ),
+            )
+        }
+        profile != null -> {
+            ValidatedMacOSNotarizationSettings(
+                NotarizationAuth.KeychainProfile(
+                    profileName = profile,
+                    keychainPath = keychainPathValue,
+                ),
+            )
+        }
+        else -> {
+            checkNotNull(appleId) { ERR_APPLE_ID_IS_EMPTY }
+            checkNotNull(pwd) { ERR_PASSWORD_IS_EMPTY }
+            checkNotNull(team) { ERR_TEAM_ID_IS_EMPTY }
+            ValidatedMacOSNotarizationSettings(
+                NotarizationAuth.AppleId(
+                    appleID = appleId,
+                    password = pwd,
+                    teamID = team,
+                ),
+            )
+        }
     }
 }
 
@@ -95,10 +127,14 @@ private val ERR_NO_MODE_CONFIGURED =
        |     ${NucleusProperties.MAC_NOTARIZATION_TEAM_ID_PROVIDER});
        |  * Keychain profile mode: keychainProfile (created via 'xcrun notarytool store-credentials')
        |    (Gradle property: ${NucleusProperties.MAC_NOTARIZATION_KEYCHAIN_PROFILE});
+       |  * App Store Connect API key mode: apiKey + apiKeyId + apiIssuer
+       |    (Gradle properties: ${NucleusProperties.MAC_NOTARIZATION_API_KEY},
+       |     ${NucleusProperties.MAC_NOTARIZATION_API_KEY_ID},
+       |     ${NucleusProperties.MAC_NOTARIZATION_API_ISSUER});
     """.trimMargin()
 private val ERR_MUTUALLY_EXCLUSIVE =
-    """|$ERR_PREFIX appleID/password/teamID and keychainProfile are mutually exclusive.
-       |Configure only one authentication mode.
+    """|$ERR_PREFIX appleID/keychainProfile/apiKey are mutually exclusive authentication modes.
+       |Configure only one mode at a time.
     """.trimMargin()
 private val ERR_APPLE_ID_IS_EMPTY =
     """|$ERR_PREFIX appleID is null or empty. To specify:
@@ -115,3 +151,18 @@ private val ERR_TEAM_ID_IS_EMPTY =
                |  * Use '${NucleusProperties.MAC_NOTARIZATION_TEAM_ID_PROVIDER}' Gradle property;
                |  * Or use 'nativeDistributions.macOS.notarization.teamID' DSL property;
     """.trimMargin()
+private val ERR_API_KEY_IS_EMPTY =
+    """|$ERR_PREFIX apiKey is null or empty. To specify:
+               |  * Use '${NucleusProperties.MAC_NOTARIZATION_API_KEY}' Gradle property;
+               |  * Or use 'nativeDistributions.macOS.notarization.apiKey' DSL property;
+    """.trimMargin()
+private val ERR_API_KEY_ID_IS_EMPTY =
+    """|$ERR_PREFIX apiKeyId is null or empty. To specify:
+               |  * Use '${NucleusProperties.MAC_NOTARIZATION_API_KEY_ID}' Gradle property;
+               |  * Or use 'nativeDistributions.macOS.notarization.apiKeyId' DSL property;
+    """.trimMargin()
+private val ERR_API_ISSUER_IS_EMPTY =
+    """|$ERR_PREFIX apiIssuer is null or empty. To specify:
+               |  * Use '${NucleusProperties.MAC_NOTARIZATION_API_ISSUER}' Gradle property;
+               |  * Or use 'nativeDistributions.macOS.notarization.apiIssuer' DSL property;
+    """.trimMargin()