Personal access key for the SkySparkle server and first-launch guide

The SkySparkle server no longer has a shared public address: each user
creates a key in their account at skysparkle.cc and the app connects to
https://skysparkle.cc/dns/<key>. The key is entered in Settings under the
server or in the new two-page guide shown on first launch. Without a key
the home screen shows a hint and the service explains why it did not start.
This commit is contained in:
2026-11-16 10:54:48 +02:00
parent 3b4d9b049b
commit 92dfd31faf
13 changed files with 426 additions and 10 deletions
@@ -106,7 +106,10 @@ class DohVpnService : VpnService() {
if (provider.url.toHttpUrlOrNull()?.isHttps != true) {
Log.e(TAG, "Server address is not a valid HTTPS URL, not starting")
stopSession()
showAlert(R.string.alert_bad_url_title, R.string.alert_bad_url_text)
showAlert(
R.string.alert_bad_url_title,
if (provider.id == Providers.DEFAULT_ID) R.string.alert_no_key_text else R.string.alert_bad_url_text,
)
stopSelf()
return
}
@@ -143,7 +143,8 @@ fun HomeScreen(
// The server is picked in Settings; this screen is composed anew each time it is shown
val selected = remember { prefs.resolve() }
val canConnect = selected.id != Providers.CUSTOM_ID || selected.url.toHttpUrlOrNull()?.isHttps == true
val canConnect = selected.url.toHttpUrlOrNull()?.isHttps == true
val needsKey = selected.id == Providers.DEFAULT_ID && !canConnect
val shown = active ?: selected
val usesHttp3 = shown.http3 && Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE
@@ -223,6 +224,14 @@ fun HomeScreen(
onToggle = ::toggle,
onOpenServers = onOpenServers,
)
if (needsKey && !running) {
HintCard(
text = stringResource(R.string.key_needed),
icon = R.drawable.ic_alert,
tint = Palette.Accent,
action = { TextButton(onClick = onOpenServers) { Text(stringResource(R.string.key_add)) } },
)
}
PrivateDnsWarning(privateDnsHost, prefs)
}
val stats: @Composable () -> Unit = {
@@ -33,9 +33,12 @@ import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.MutableState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.Saver
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.painterResource
@@ -60,7 +63,9 @@ class MainActivity : ComponentActivity() {
// There is no Surface at the root, so text and icons without an explicit color
// would fall back to black and disappear on the dark background
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface) {
AppShell()
// First launch: the guide explains the access key before the app opens
var onboarded by rememberSaveable { mutableStateOf(Prefs(this@MainActivity).onboardingDone) }
if (onboarded) AppShell() else OnboardingScreen(onDone = { onboarded = true })
}
}
}
@@ -0,0 +1,200 @@
package cc.skysparkle.sparkledns
import androidx.activity.compose.BackHandler
import androidx.compose.animation.AnimatedContent
import androidx.compose.animation.fadeIn
import androidx.compose.animation.fadeOut
import androidx.compose.animation.slideInHorizontally
import androidx.compose.animation.slideOutHorizontally
import androidx.compose.animation.togetherWith
import androidx.compose.foundation.Image
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.navigationBarsPadding
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.statusBarsPadding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.widthIn
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
// Shown once on first launch: what the app does, then how to get the personal access key
// for the Skysparkle server. Skipping leaves the key empty; other servers stay available.
@Composable
fun OnboardingScreen(onDone: () -> Unit) {
val context = LocalContext.current
val prefs = remember { Prefs(context) }
var page by rememberSaveable { mutableIntStateOf(0) }
var keyInput by rememberSaveable { mutableStateOf(prefs.skysparkleKey) }
val keyValid = SkysparkleKey.parse(keyInput) != null
fun finish(useKey: Boolean) {
if (useKey) {
prefs.skysparkleKey = SkysparkleKey.parse(keyInput) ?: ""
prefs.providerId = Providers.DEFAULT_ID
}
prefs.onboardingDone = true
onDone()
}
BackHandler(enabled = page > 0) { page-- }
Box(
Modifier
.fillMaxSize()
.background(Palette.Bg)
.statusBarsPadding()
.navigationBarsPadding()
.imePadding(),
contentAlignment = Alignment.TopCenter,
) {
Column(
Modifier
.widthIn(max = 520.dp)
.fillMaxSize()
.padding(horizontal = 24.dp, vertical = 20.dp),
) {
Dots(count = 2, current = page)
AnimatedContent(
targetState = page,
transitionSpec = {
val forward = targetState > initialState
(fadeIn(Motion.enterFade) + slideInHorizontally(Motion.slide) { if (forward) it / 4 else -it / 4 }) togetherWith
(fadeOut(Motion.exitFade) + slideOutHorizontally(Motion.slide) { if (forward) -it / 4 else it / 4 })
},
modifier = Modifier.weight(1f),
label = "onboarding",
) { current ->
Column(
Modifier
.fillMaxSize()
.verticalScroll(rememberScrollState())
.padding(top = 40.dp, bottom = 16.dp),
verticalArrangement = Arrangement.spacedBy(14.dp),
) {
if (current == 0) {
Image(
bitmap = AppLogo.get(context),
contentDescription = null,
modifier = Modifier
.size(72.dp)
.clip(RoundedCornerShape(20.dp)),
)
Spacer(Modifier.height(8.dp))
Title(stringResource(R.string.onb_welcome_title))
Body(stringResource(R.string.onb_welcome_text))
Spacer(Modifier.height(8.dp))
Step(1, stringResource(R.string.onb_point_encrypt))
Step(2, stringResource(R.string.onb_point_block))
Step(3, stringResource(R.string.onb_point_independent))
} else {
Title(stringResource(R.string.onb_key_title))
Body(stringResource(R.string.onb_key_text))
Spacer(Modifier.height(4.dp))
Step(1, stringResource(R.string.onb_key_step1))
Step(2, stringResource(R.string.onb_key_step2))
Step(3, stringResource(R.string.onb_key_step3))
Spacer(Modifier.height(4.dp))
Column(Modifier.fillMaxWidth().appCard().padding(top = 16.dp)) {
KeyField(
value = keyInput,
valid = keyValid,
onChange = { keyInput = it },
onGetKey = { openUrl(context, SkysparkleKey.SIGNUP_URL) },
)
}
}
}
}
if (page == 0) {
Button(
onClick = { page = 1 },
shape = RoundedCornerShape(16.dp),
modifier = Modifier.fillMaxWidth().height(52.dp),
) { Text(stringResource(R.string.onb_next), fontWeight = FontWeight.Bold) }
} else {
Button(
onClick = { finish(useKey = true) },
enabled = keyValid,
shape = RoundedCornerShape(16.dp),
modifier = Modifier.fillMaxWidth().height(52.dp),
) { Text(stringResource(R.string.onb_done), fontWeight = FontWeight.Bold) }
TextButton(onClick = { finish(useKey = false) }, modifier = Modifier.fillMaxWidth()) {
Text(stringResource(R.string.onb_skip), color = Palette.Fg3)
}
}
}
}
}
@Composable
private fun Title(text: String) {
Text(text, color = Palette.Fg, fontSize = 30.sp, lineHeight = 34.sp, fontWeight = FontWeight.ExtraBold, letterSpacing = (-0.5).sp)
}
@Composable
private fun Body(text: String) {
Text(text, color = Palette.Fg2, fontSize = 16.sp, lineHeight = 23.sp)
}
@Composable
private fun Step(number: Int, text: String) {
Row(verticalAlignment = Alignment.Top) {
Box(
Modifier
.size(26.dp)
.clip(CircleShape)
.background(Palette.AccentSoft),
contentAlignment = Alignment.Center,
) {
Text(number.toString(), color = Palette.Accent, fontSize = 13.sp, fontWeight = FontWeight.Bold)
}
Spacer(Modifier.width(12.dp))
Text(text, color = Palette.Fg, fontSize = 15.sp, lineHeight = 21.sp, modifier = Modifier.padding(top = 2.dp))
}
}
@Composable
private fun Dots(count: Int, current: Int) {
Row(horizontalArrangement = Arrangement.spacedBy(6.dp)) {
repeat(count) { i ->
Box(
Modifier
.height(4.dp)
.width(if (i == current) 22.dp else 10.dp)
.clip(CircleShape)
.background(if (i == current) Palette.Accent else Palette.Track),
)
}
}
}
@@ -21,6 +21,16 @@ class Prefs(context: Context) {
get() = sp.getBoolean(KEY_HTTP3, false)
set(value) = sp.edit().putBoolean(KEY_HTTP3, value).apply()
// Access key for the Skysparkle server, created in the account at skysparkle.cc
var skysparkleKey: String
get() = sp.getString(KEY_SKYSPARKLE, null) ?: ""
set(value) = sp.edit().putString(KEY_SKYSPARKLE, value).apply()
// The first-launch guide was finished or skipped
var onboardingDone: Boolean
get() = sp.getBoolean(KEY_ONBOARDING, false)
set(value) = sp.edit().putBoolean(KEY_ONBOARDING, value).apply()
var excludedApps: Set<String>
get() = sp.getStringSet(KEY_EXCLUDED, null)?.toSet() ?: emptySet()
set(value) = sp.edit().putStringSet(KEY_EXCLUDED, value).apply()
@@ -48,12 +58,14 @@ class Prefs(context: Context) {
get() = sp.getString(KEY_PRIVATE_DNS, null) ?: ""
set(value) = sp.edit().putString(KEY_PRIVATE_DNS, value).apply()
fun resolve(): DohProvider =
if (providerId == Providers.CUSTOM_ID) {
// Without a key the Skysparkle entry has an empty address, so it cannot connect
fun resolve(): DohProvider = when (providerId) {
Providers.CUSTOM_ID ->
DohProvider(Providers.CUSTOM_ID, "Custom", customUrl.trim(), parseIps(customBootstrap), customHttp3)
} else {
Providers.byId(providerId)
else -> Providers.byId(providerId).let {
if (it.id == Providers.DEFAULT_ID) it.copy(url = SkysparkleKey.url(skysparkleKey)) else it
}
}
private companion object {
const val KEY_PROVIDER = "provider"
@@ -61,6 +73,8 @@ class Prefs(context: Context) {
const val KEY_BOOTSTRAP = "custom_bootstrap"
const val KEY_HTTP3 = "custom_http3"
const val KEY_EXCLUDED = "excluded_apps"
const val KEY_SKYSPARKLE = "skysparkle_key"
const val KEY_ONBOARDING = "onboarding_done"
const val KEY_HINTS = "dismissed_hints"
const val KEY_PRIVATE_DNS = "dismissed_private_dns"
const val KEY_UPDATE_INTERVAL = "update_interval"
@@ -18,8 +18,9 @@ object Providers {
// Servers ship with the app; new ones arrive with app updates
val builtIn = listOf(
// The address is personal: Prefs.resolve() adds the access key from skysparkle.cc
DohProvider(
"skysparkle", "SkySparkle", "https://skysparkle.cc/dns-query",
"skysparkle", "SkySparkle", SkysparkleKey.BASE_URL,
http3 = true, policy = "https://skysparkle.cc/privacy?lang=en",
),
DohProvider(
@@ -58,6 +59,24 @@ object Providers {
fun byId(id: String): DohProvider = builtIn.firstOrNull { it.id == id } ?: default
}
// Personal access keys for the Skysparkle server. Each account at skysparkle.cc creates its own
// keys; the server answers only /dns/<key>, there is no shared public address.
object SkysparkleKey {
const val BASE_URL = "https://skysparkle.cc/dns/"
const val SIGNUP_URL = "https://skysparkle.cc/login#register"
private val KEY = Regex("^[A-Za-z0-9_-]{24}$")
private val IN_URL = Regex("/dns/([A-Za-z0-9_-]{24})(?:[/?#].*)?$")
// Accepts the key itself or the whole address copied from the account page
fun parse(input: String): String? {
val text = input.trim()
if (KEY.matches(text)) return text
return IN_URL.find(text)?.groupValues?.get(1)
}
fun url(key: String): String = parse(key)?.let { BASE_URL + it } ?: ""
}
fun parseIps(raw: String): List<String> =
raw.split(',', ';', ' ').map { it.trim() }.filter { it.isNotEmpty() }
@@ -71,6 +71,7 @@ fun SettingsScreen(
var customUrl by remember { mutableStateOf(prefs.customUrl) }
var customBootstrap by remember { mutableStateOf(prefs.customBootstrap) }
var customHttp3 by remember { mutableStateOf(prefs.customHttp3) }
var keyInput by remember { mutableStateOf(prefs.skysparkleKey) }
var testResult by rememberSaveable(stateSaver = TestResultSaver) { mutableStateOf<TestResult?>(null) }
var shownResult by rememberSaveable(stateSaver = TestResultSaver) { mutableStateOf<TestResult?>(null) } // kept while the card animates out
var testing by remember { mutableStateOf(false) }
@@ -78,8 +79,9 @@ fun SettingsScreen(
val isCustom = selected == Providers.CUSTOM_ID
val customValid = remember(customUrl) { customUrl.trim().toHttpUrlOrNull()?.isHttps == true }
val canConnect = !isCustom || customValid
val selectedProvider = remember(selected, customUrl, customBootstrap, customHttp3) { prefs.resolve() }
val keyValid = remember(keyInput) { SkysparkleKey.parse(keyInput) != null }
val selectedProvider = remember(selected, customUrl, customBootstrap, customHttp3, keyInput) { prefs.resolve() }
val canConnect = selectedProvider.url.toHttpUrlOrNull()?.isHttps == true
// Picking a server never touches a live connection; switching is an explicit action
val pendingSwitch = active?.let { it != selectedProvider && canConnect } == true
@@ -123,6 +125,21 @@ fun SettingsScreen(
onDonate = provider.donate?.let { url -> { openUrl(context, url) } },
onClick = { select(provider.id) },
)
if (provider.id == Providers.DEFAULT_ID) {
AnimatedVisibility(visible = selected == Providers.DEFAULT_ID, enter = Motion.expandIn, exit = Motion.collapseOut) {
KeyField(
value = keyInput,
valid = keyValid,
onChange = {
keyInput = it
// Saved as the bare key, also when the whole address was pasted
prefs.skysparkleKey = SkysparkleKey.parse(it) ?: it.trim()
testResult = null
},
onGetKey = { openUrl(context, SkysparkleKey.SIGNUP_URL) },
)
}
}
}
ListDivider()
ServerRow(
@@ -252,6 +269,35 @@ fun SettingsScreen(
}
}
// Access key for the Skysparkle server, with a link to the account page where keys are made
@Composable
internal fun KeyField(value: String, valid: Boolean, onChange: (String) -> Unit, onGetKey: () -> Unit, modifier: Modifier = Modifier) {
val showError = value.isNotBlank() && !valid
Column(
modifier.padding(start = 16.dp, end = 16.dp, bottom = 16.dp),
verticalArrangement = Arrangement.spacedBy(6.dp),
) {
OutlinedTextField(
value = value,
onValueChange = onChange,
label = { Text(stringResource(R.string.key_label)) },
singleLine = true,
isError = showError,
shape = RoundedCornerShape(14.dp),
keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri, imeAction = ImeAction.Done),
modifier = Modifier.fillMaxWidth(),
)
Text(
stringResource(if (showError) R.string.key_invalid else R.string.key_hint),
color = if (showError) Palette.Blocked else Palette.Fg3,
fontSize = 12.sp,
)
OutlinedButton(onClick = onGetKey, shape = RoundedCornerShape(14.dp)) {
Text(stringResource(R.string.key_get))
}
}
}
@Composable
private fun ServerRow(
title: String,