Standalone App Guide — Public Client + PKCE

A integrates with the official Android SDK and is the recommended path, and B walks through a complete AppAuth-Android 0.11.1 integration that you implement yourself, from registration to sign-out. Steps 1 to 7 explain each decision, step 8 helps you find where a login fails, and step 9 puts everything into one Kotlin sample. If you move to a different AppAuth version, compile and test the sample again. A 는 공식 Android SDK 로 연동하는 권장 방법이고, B 는 등록부터 로그아웃까지 AppAuth-Android 0.11.1 연동 전체를 직접 구현하는 방법입니다. 1~7단계는 단계별 판단 기준, 8단계는 로그인이 어디서 실패하는지 찾는 방법, 9단계는 전체를 담은 Kotlin 샘플입니다. 다른 AppAuth 버전으로 바꾸면 샘플을 다시 컴파일하고 테스트하세요.

A. Integrate with the SDK (recommended) A. SDK 로 연동(권장)

The official Android SDK com.github.banstorm:altscodex-aos-sdk applies the rules described in B for you. It is published on JitPack under the MIT license, and the source is at github.com/banstorm/altscodex-aos-sdk. Use the client_id and redirect URI you registered in section 1, exactly as registered. 공식 Android SDK com.github.banstorm:altscodex-aos-sdk 는 B 에서 설명하는 규칙을 대신 처리합니다. JitPack 으로 배포되며 MIT 라이선스이고, 소스는 github.com/banstorm/altscodex-aos-sdk 에 있습니다. 1절에서 등록한 client_id 와 redirect URI 를 등록한 값 그대로 씁니다.

Install 설치

Add the JitPack repository and the dependency. appAuthRedirectScheme is the scheme part only of the redirect URI. The SDK requires minSdk 26 and brings in AppAuth-Android 0.11.1 as an api dependency, so you do not need to add AppAuth separately. JitPack 저장소와 의존성을 추가합니다. appAuthRedirectScheme 에는 redirect URI 의 스킴 부분만 넣습니다. SDK 는 minSdk 26 이상이 필요하고 AppAuth-Android 0.11.1 을 api 의존성으로 함께 가져오므로 AppAuth 를 따로 추가할 필요가 없습니다.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
android {
    defaultConfig {
        minSdk = 26
        // Scheme part only of the redirect URI (com.example.app:/callback becomes com.example.app)
        manifestPlaceholders["appAuthRedirectScheme"] = "com.example.app"
    }
}

dependencies {
    implementation("com.github.banstorm:altscodex-aos-sdk:0.1.0") // includes AppAuth-Android 0.11.1
}

Usage 사용 예

Create one AltsCodexAuth per app and reuse it. Register the result launcher in onCreate every time, so the result still arrives after the Activity is recreated or the process restarts. Show every AuthResult case to the user instead of ignoring it. AltsCodexAuth 는 앱당 하나만 만들어 재사용합니다. 결과 런처는 onCreate 에서 매번 등록해야 Activity 가 다시 만들어지거나 프로세스가 재시작된 뒤에도 결과를 받습니다. AuthResult 는 경우마다 사용자에게 알리고, 조용히 무시하지 마세요.

import com.altscodex.sdk.*
// Android and AndroidX imports omitted.

class App : Application() { // register as android:name in AndroidManifest.xml
    val auth by lazy {
        AltsCodexAuth(this, AltsCodexConfig(clientId = "YOUR_CLIENT_ID", redirectUri = "com.example.app:/callback"))
    }
}

class MainActivity : AppCompatActivity() {
    private val auth get() = (application as App).auth
    private lateinit var launcher: ActivityResultLauncher<Intent>

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        launcher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) {
            lifecycleScope.launch {
                when (val r = auth.handleResult(it.data)) {
                    is AuthResult.Success -> showSignedIn(r.session.slot.nickname)
                    AuthResult.Cancelled -> showMessage("Sign-in cancelled")
                    AuthResult.Denied -> showMessage("Access was declined")
                    AuthResult.Expired -> showMessage("Sign-in took too long. Please try again.")
                    // r.stage is safe to log. StaleCallback: an older sign-in returned, the newer one is still pending.
                    is AuthResult.Failed -> if (r.stage != Stage.StaleCallback) showMessage("Sign-in failed (${r.stage})")
                }
            }
        }
    }

    fun signIn() = lifecycleScope.launch {
        try { launcher.launch(auth.loginIntent()) } catch (e: AltsCodexException) { showMessage("Could not start sign-in (${e.stage})") }
    }

    suspend fun callApi() {
        val session = try { auth.session() } catch (e: AltsCodexException) {
            showMessage("Network error. Please try again."); return // the session is kept, retry later
        }
        if (session == null) { signIn(); return } // signed out or refresh rejected: sign in again
        myApi.get(bearerToken = session.accessToken) // refreshed first when it expires within a minute
    }

    fun signOut() = lifecycleScope.launch {
        val result = auth.signOut() // removes the local session first, even offline
        if (!result.serverRevoked) showMessage("Signed out on this device. Server revocation was not confirmed.")
    }
}

API API

What the SDK handles for you SDK 가 대신 처리하는 것

The SDK creates state and the PKCE S256 verifier and challenge, and keeps a single pending sign-in that is consumed once, so the callback is matched even after a process restart. It never exchanges the same code twice, because the authorization code is valid for 60 seconds and once only. It checks the types of the slot fields before trusting them. The session is encrypted with an AES-GCM key held in the Android Keystore and stored in a file excluded from backup, so no extra manifest backup rules are needed. Only one refresh runs at a time, the rotated refresh token is stored together with the new access token, and a refresh response that arrives after sign-out is discarded. Sign-out revokes the refresh token on the server. The logger receives only stages and presence, type and result values. Tokens, codes, state and PKCE verifiers are never passed to it. SDK 는 state 와 PKCE S256 verifier·challenge 를 만들고, 대기 중인 로그인을 하나만 두어 한 번만 소비하므로 프로세스가 재시작돼도 콜백을 대조합니다. 인가 코드는 60초 동안 한 번만 유효하므로 같은 코드를 다시 교환하지 않습니다. slot 필드는 타입을 확인한 뒤에만 씁니다. 세션은 Android Keystore 의 AES-GCM 키로 암호화해 백업 제외 파일에 저장하므로 매니페스트에 백업 규칙을 따로 넣지 않아도 됩니다. 갱신은 한 번에 하나만 실행하고, 회전된 refresh token 을 새 access token 과 함께 저장하며, 로그아웃 뒤 늦게 도착한 갱신 응답은 버립니다. 로그아웃 시 서버에서 refresh token 을 폐기합니다. 로거에는 단계와 존재 여부·타입·결과 값만 전달되고, 토큰·코드·state·PKCE verifier 는 절대 전달되지 않습니다.

If you need to control each step yourself, for example to use a different AppAuth version, follow B below. 다른 AppAuth 버전을 쓰는 등 각 단계를 직접 제어해야 하면 아래 B 를 따르세요.

B. Implement directly with AppAuth B. AppAuth 로 직접 구현

1. Registration values 1. 등록 값

• Use the client_id of the public client you registered in section 1. It is the only credential the app contains. 1절에서 등록한 공개 클라이언트의 client_id 를 씁니다. 앱에 들어가는 자격 정보는 이것 하나뿐입니다.
• The redirect URI in the app must match the registered value character for character. com.example.app:/callback (one slash, no host) and com.example.app://callback (host callback) are different URIs. 앱의 redirect URI 는 등록한 값과 한 글자도 다르지 않게 일치해야 합니다. com.example.app:/callback(슬래시 하나, host 없음)과 com.example.app://callback(host 가 callback)은 서로 다른 URI 입니다.
• Even if the developer center shows a client_secret for your application, do not put it in the app. 개발자센터에 client_secret 이 표시되더라도 앱에 넣지 않습니다.
• To change the redirect URI later, open My Applications → Edit. redirect URI 를 바꾸려면 My Applications → Edit 에서 수정합니다.

2. Gradle setup 2. Gradle 설정

appAuthRedirectScheme is the scheme part only (com.example.app), not the full redirect URI. AppAuth registers a redirect receiver for that scheme in the merged manifest. appAuthRedirectScheme 에는 redirect URI 전체가 아니라 스킴 부분(com.example.app)만 넣습니다. AppAuth 가 병합된 매니페스트에 이 스킴의 리다이렉트 수신 Activity 를 등록합니다.

// app/build.gradle.kts — flutter_appauth and AppAuth-Android both read this placeholder
android {
    defaultConfig {
        manifestPlaceholders["appAuthRedirectScheme"] = "com.example.app"
    }
}

dependencies {
    implementation("net.openid:appauth:0.11.1") // native Android only
}

Exclude the token store and the pending login request from backup. Set android:allowBackup="false", or exclude those files with android:dataExtractionRules (Android 12+) and android:fullBackupContent. 토큰 저장소와 대기 중인 로그인 요청은 백업에서 제외하세요. android:allowBackup="false" 로 끄거나, android:dataExtractionRules(Android 12 이상)와 android:fullBackupContent 로 해당 파일을 제외합니다.

3. Login request 3. 로그인 요청

• Load the configuration with discovery (AuthorizationServiceConfiguration.fetchFromIssuer, issuer https://api.altscodex.com), then build an AuthorizationRequest with ResponseTypeValues.CODE. 디스커버리(AuthorizationServiceConfiguration.fetchFromIssuer, issuer https://api.altscodex.com)로 설정을 읽고, ResponseTypeValues.CODE 로 AuthorizationRequest 를 만듭니다.
• AppAuth generates state, the PKCE code_verifier and the S256 code_challenge automatically. Do not replace them with your own values. AppAuth 가 state, PKCE code_verifier, S256 code_challenge 를 자동으로 만듭니다. 직접 만든 값으로 바꾸지 마세요.
• Do not request the openid scope or any other scope. AltsCodex issues no id_token. openid scope 나 다른 scope 를 요청하지 마세요. AltsCodex 는 id_token 을 발급하지 않습니다.
• Open the login page with getAuthorizationRequestIntent, which uses Custom Tabs or the default browser. Never use a WebView (see section 8). 로그인 화면은 Custom Tabs 또는 기본 브라우저를 쓰는 getAuthorizationRequestIntent 로 엽니다. WebView 는 쓰지 마세요(8절 참고).
• Before launching, save the pending request (AuthorizationRequest.jsonSerializeString()) and its start time in secure storage, so the app can still match the callback after its process is killed. 브라우저를 열기 전에 대기 요청(AuthorizationRequest.jsonSerializeString())과 시작 시각을 보안 저장소에 저장합니다. 그래야 앱 프로세스가 종료된 뒤에도 콜백을 대조할 수 있습니다.

4. Handling the callback 4. 콜백 처리

• Register the ActivityResultLauncher in onCreate every time, so the result still arrives after the Activity is recreated or the process restarts. ActivityResultLauncher 는 onCreate 에서 매번 등록하세요. 그래야 Activity 가 재생성되거나 프로세스가 다시 시작돼도 결과를 받습니다.
• Never return silently. A null result or AuthorizationException.GeneralErrors.USER_CANCELED_AUTH_FLOW means the user cancelled. AuthorizationRequestErrors.ACCESS_DENIED means the user declined. Any other AuthorizationException, including a failed token exchange, is an error. Show each outcome and offer a new login. 조용히 return 하지 마세요. 결과가 null 이거나 AuthorizationException.GeneralErrors.USER_CANCELED_AUTH_FLOW 이면 사용자 취소입니다. AuthorizationRequestErrors.ACCESS_DENIED 는 사용자가 동의를 거부한 경우입니다. 토큰 교환 실패를 포함한 그 밖의 AuthorizationException 은 오류입니다. 각 결과를 안내하고 새 로그인을 시작할 수 있게 하세요.
• Check that the response belongs to the current pending request (same state). If it belongs to an older request, ignore it without clearing the newer pending request. 응답이 현재 대기 요청의 것인지(state 일치) 확인하세요. 이전 요청의 응답이면 무시하되, 더 새로운 대기 요청은 지우지 않습니다.
• An authorization code is valid for 60 seconds and can be used once. Do not exchange a code you already know is stale, and never retry the exchange with the same code. If the exchange returns invalid_grant, start a new login. 인가 코드는 60초 동안 한 번만 쓸 수 있습니다. 만료된 것이 확실한 코드는 교환하지 말고, 같은 코드로 교환을 재시도하지 마세요. 교환이 invalid_grant 를 반환하면 새 로그인을 시작합니다.
• Three time limits are separate. The time the user spends on the login page, the app's own timeout for a pending request, and the 60-second code lifetime. The sample uses a 10-minute pending timeout as an example of an app policy. AltsCodex does not impose it. 세 가지 시간 제한은 서로 별개입니다. 사용자가 로그인 화면에 머무는 시간, 앱이 대기 요청에 두는 제한 시간, 코드의 60초 수명입니다. 샘플의 대기 요청 10분 제한은 앱 자체 정책 예시이며 AltsCodex 가 정한 값이 아닙니다.
• After a process restart, restore the pending request with AuthorizationRequest.jsonDeserialize(...). AppAuth's own authorization Activity also restores its request from saved state. 프로세스가 다시 시작되면 AuthorizationRequest.jsonDeserialize(...) 로 대기 요청을 복원합니다. AppAuth 의 인가 Activity 도 저장된 상태에서 자기 요청을 복원합니다.
• Optional hardening. Validate the URI that actually arrived, not the stored request.redirectUri. Receive the redirect in your own exported Activity, reject it unless the scheme and path match, there is no host or fragment, no query key repeats, state is present, and exactly one of code or error is present. Then forward it to net.openid.appauth.RedirectUriReceiverActivity and make that Activity non-exported in your manifest. 선택 보강. 저장된 request.redirectUri 가 아니라 실제로 들어온 URI 를 검증하세요. 직접 만든 exported Activity 로 리다이렉트를 받고, 스킴·경로가 일치하고 host·fragment 가 없으며 query 키가 중복되지 않고 state 가 있고 code 와 error 중 정확히 하나만 있을 때만 통과시킵니다. 그 뒤 net.openid.appauth.RedirectUriReceiverActivity 로 넘기고, 매니페스트에서 그 Activity 를 non-exported 로 바꿉니다.

5. Token response and slot 5. 토큰 응답과 slot

The first code exchange and every refresh return the same shape. slot is always present in both. 최초 코드 교환과 모든 리프레시는 같은 형태로 응답합니다. 두 경우 모두 slot 이 항상 포함됩니다.

• Parse the string once more with JSONObject. org.json returns integers as Int or Long and larger numbers as Double. The helper slotId(value: Any?): String? in the sample accepts a non-blank string or a non-negative Int/Long and returns its decimal string, so 42 and "42" become the same ID. It returns null for Double, Boolean, objects and null, and the caller treats null as a failed login. The 512-character limit on string IDs is an example of an app policy. 문자열을 JSONObject 로 한 번 더 파싱합니다. org.json 은 정수를 Int 또는 Long 으로, 그보다 큰 수는 Double 로 돌려줍니다. 샘플의 도우미 slotId(value: Any?): String? 는 공백이 아닌 문자열과 음수가 아닌 Int·Long 만 받아 십진 문자열로 바꾸므로 42 와 "42" 는 같은 ID 가 됩니다. Double·Boolean·객체·null 은 null 을 반환하고, 호출자는 이를 로그인 실패로 처리합니다. 문자열 ID 512자 제한은 앱 자체 정책 예시입니다.
• Do not use getString() or toString() as validation. They turn objects, booleans, null and rounded floating-point values into strings that look valid. getString() 이나 toString() 을 검증 대신 쓰지 마세요. 객체·Boolean·null·반올림된 부동소수 값까지 정상처럼 보이는 문자열로 바꿉니다.
• Check token_nickname separately with as? String. Do not let the ID compatibility rule hide a nickname type error. token_nickname 은 as? String 으로 따로 검사합니다. ID 호환 처리로 닉네임 타입 오류를 덮지 마세요.
• Before showing the user as signed in, confirm that the access and refresh tokens are present, token_type is Bearer, the expiry time is in the future, slot parses with valid field types, and the session was written to storage. 로그인 완료로 표시하기 전에 access·refresh 토큰 존재, token_type 이 Bearer 인지, 만료 시각이 미래인지, slot 이 파싱되고 필드 타입이 맞는지, 세션이 저장소에 기록됐는지 확인합니다.

6. Persistent login and refresh rotation 6. 로그인 유지와 리프레시 회전

• Store the access token, refresh token, absolute expiry time and slot ID as one record in storage encrypted with an Android Keystore key (for example an AES-GCM key from the Keystore and an atomically written file). Replace the whole record in a single write. access token, refresh token, 만료 시각(절대 시각), slot ID 를 하나의 레코드로 Android Keystore 키로 암호화한 저장소(예: Keystore 의 AES-GCM 키 + 원자적으로 쓰는 파일)에 저장합니다. 레코드 전체를 한 번의 쓰기로 교체하세요.
• Run at most one refresh at a time. Other callers wait and reuse its result. If two refreshes send the same refresh token at once, only one succeeds and the other gets invalid_grant because the token was already rotated. 리프레시는 한 번에 하나만 실행하고, 다른 호출은 기다렸다가 그 결과를 씁니다. 같은 refresh token 으로 두 리프레시가 동시에 나가면 하나만 성공하고 나머지는 이미 회전된 토큰이라 invalid_grant 를 받습니다.
• A network failure keeps the stored session so the app can retry later. invalid_grant means the refresh token expired, was revoked or was already rotated, so clear the session and ask the user to sign in again. 네트워크 실패면 저장된 세션을 유지하고 나중에 재시도합니다. invalid_grant 는 refresh token 이 만료·폐기됐거나 이미 회전됐다는 뜻이므로 세션을 지우고 다시 로그인하게 합니다.
• If the user signs out while a refresh is in flight, drop the late response. Check that the slot.id in the refresh response matches the stored one. 리프레시 도중 사용자가 로그아웃했다면 늦게 도착한 응답은 버립니다. 리프레시 응답의 slot.id 가 저장된 값과 같은지 확인하세요.
• Keep "a stored session the app can retry" separate from "features the user may use". Whether your app requires sign-in before any feature works is your product decision, not an AltsCodex requirement. "재시도할 수 있는 저장 세션"과 "사용자에게 허용할 기능"은 따로 관리하세요. 모든 기능 전에 로그인을 요구할지는 앱의 제품 정책이며 AltsCodex 의 요구사항이 아닙니다.

7. Sign out 7. 로그아웃

1. Delete the local session first. The UI switches to signed-out immediately, without waiting for the network. 먼저 로컬 세션을 지웁니다. 네트워크 응답을 기다리지 않고 UI 를 바로 로그아웃 상태로 바꿉니다.
2. Then call the revocation endpoint (section 6) with token, token_type_hint and client_id, form-urlencoded. If the request fails, tell the user they are signed out on this device but the server revocation was not confirmed. 그다음 revoke 엔드포인트(6절)에 token, token_type_hint, client_id 를 form-urlencoded 로 보냅니다. 요청이 실패하면 이 기기에서는 로그아웃됐지만 서버 폐기는 확인되지 않았다고 안내하세요.
3. The AltsCodex session in the browser is separate and stays signed in. Seeing the "Continue" screen on the next login is expected and is not a failure or a sign that the app's tokens came back. 브라우저의 AltsCodex 세션은 별개이며 로그인 상태로 남습니다. 다음 로그인에서 "Continue" 화면이 뜨는 것은 정상이며, 실패나 앱 토큰이 되살아났다는 뜻이 아닙니다.

8. Diagnostics and FAQ 8. 진단과 FAQ

Log only the stage, whether a value is present, its type and the validation result. A safe log line looks like this. 로그에는 단계, 값의 존재 여부, 타입, 검증 결과만 남깁니다. 안전한 로그는 다음과 같습니다.

stage=TokenValidation accessPresent=true idType=number nicknameType=string

9. Kotlin sample 9. Kotlin 샘플

The sample covers steps 1 to 7. It needs AppAuth-Android 0.11.1 and kotlinx-coroutines. Connect SecureStore to Keystore-backed storage and map AuthResult to your own UI and error types. 샘플은 1~7단계를 모두 담고 있으며 AppAuth-Android 0.11.1 과 kotlinx-coroutines 가 필요합니다. SecureStore 는 Keystore 기반 저장소에 연결하고, AuthResult 는 앱의 UI·오류 타입에 맞게 연결하세요.

// AltsCodex sign-in with AppAuth-Android 0.11.1 and kotlinx-coroutines.
// Connect SecureStore to Keystore-backed storage and AuthResult to your UI.
import android.content.*
import android.net.Uri
import kotlinx.coroutines.*
import kotlinx.coroutines.sync.*
import net.openid.appauth.*
import org.json.*
import java.net.*
import kotlin.coroutines.*

// 1. Registration values. Public client: client_id only, never a client_secret.
const val CLIENT_ID = "YOUR_CLIENT_ID"
val REDIRECT_URI: Uri = Uri.parse("com.example.app:/callback") // exactly as registered
val ISSUER: Uri = Uri.parse("https://api.altscodex.com")
const val PENDING_TTL_MS = 10 * 60_000L // app policy example, not a provider limit

data class Session(val accessToken: String, val refreshToken: String,
                   val expiresAt: Long, val slotId: String, val nickname: String)

sealed class AuthResult {
    data class Success(val session: Session) : AuthResult()
    object Cancelled : AuthResult()                     // user closed the browser
    object Denied : AuthResult()                        // error=access_denied
    object Expired : AuthResult()                       // pending request too old
    data class Failed(val stage: String) : AuthResult() // a stage name, never a token
}

// Storage encrypted with an Android Keystore key (AES-GCM key + atomic file), excluded from backup.
// Each put is one commit. put(key, null) removes the key.
interface SecureStore { fun get(key: String): String?; fun put(key: String, value: String?) }

// 5. Accept a non-blank string or a non-negative Int/Long without loss. Reject Double,
// Boolean, objects and null instead of coercing them with toString().
// The 512-character limit is an app policy example.
fun slotId(value: Any?): String? = when (value) {
    is String -> value.takeIf { it.isNotBlank() && it.length <= 512 }
    is Int -> value.takeIf { it >= 0 }?.toString()
    is Long -> value.takeIf { it >= 0 }?.toString()
    else -> null
}

// 4. Optional hardening: run this in your own redirect Activity before forwarding the
// URI to AppAuth. AppAuth still checks that state matches the pending request.
fun isWellFormedCallback(uri: Uri): Boolean {
    if (uri.scheme != REDIRECT_URI.scheme || uri.encodedAuthority != null ||
        uri.path != REDIRECT_URI.path || uri.encodedFragment != null) return false
    val names = uri.queryParameterNames
    if (uri.encodedQuery?.split('&')?.size != names.size) return false // duplicate keys
    val value = when {
        "code" in names && "error" !in names -> uri.getQueryParameter("code")
        "error" in names && "code" !in names -> uri.getQueryParameter("error")
        else -> null                                                // both or neither
    }
    return !uri.getQueryParameter("state").isNullOrBlank() && !value.isNullOrBlank()
}

class AltsCodexAuth(context: Context, private val store: SecureStore) {
    private val service = AuthorizationService(context)
    private val refreshLock = Mutex()
    private var config: AuthorizationServiceConfiguration? = null
    @Volatile private var generation = 0 // bumped on sign-out so late responses are dropped

    // 3. Login request. AppAuth creates state and the PKCE S256 verifier and challenge.
    suspend fun createLoginIntent(): Intent {
        val request = AuthorizationRequest.Builder(
            discover(), CLIENT_ID, ResponseTypeValues.CODE, REDIRECT_URI
        ).build() // no openid scope: AltsCodex issues no id_token
        // Save before launching, so a restarted process can still match the callback.
        store.put("pending", JSONObject().put("request", request.jsonSerializeString())
            .put("startedAt", System.currentTimeMillis()).toString())
        return service.getAuthorizationRequestIntent(request) // Custom Tabs, never a WebView
    }

    // 4. Callback. Call from an ActivityResultLauncher registered in onCreate.
    suspend fun handleResult(data: Intent?): AuthResult {
        val pending = store.get("pending")?.let { JSONObject(it) }
            ?: return AuthResult.Failed("NoPendingRequest")
        val request = AuthorizationRequest.jsonDeserialize(pending.getString("request"))
        if (data == null) return clearPending(AuthResult.Cancelled)
        AuthorizationException.fromIntent(data)?.let { ex ->
            return clearPending(when (ex) {
                AuthorizationException.GeneralErrors.USER_CANCELED_AUTH_FLOW -> AuthResult.Cancelled
                AuthorizationException.AuthorizationRequestErrors.ACCESS_DENIED -> AuthResult.Denied
                else -> AuthResult.Failed("Authorization")
            })
        }
        val response = AuthorizationResponse.fromIntent(data)
            ?: return clearPending(AuthResult.Failed("NoAuthorizationResponse"))
        // A callback for an older request must not cancel the newer pending request.
        if (response.request.state != request.state) return AuthResult.Failed("StaleCallback")
        if (System.currentTimeMillis() - pending.getLong("startedAt") > PENDING_TTL_MS) {
            return clearPending(AuthResult.Expired) // do not exchange a code we know is stale
        }
        store.put("pending", null) // the code is single-use, so consume the pending request once
        return try {
            val session = parseTokens(tokenRequest(response.createTokenExchangeRequest()))
                ?: return AuthResult.Failed("TokenValidation")
            store.put("session", session.toJson()) // signed in only after this write succeeds
            AuthResult.Success(session)
        } catch (e: AuthorizationException) {
            // invalid_grant: the code expired (60 s) or was used. Start a new login.
            AuthResult.Failed(if (e == AuthorizationException.TokenRequestErrors.INVALID_GRANT)
                "CodeExpiredOrUsed" else "TokenExchange")
        }
    }

    // 6. Returns a valid session, or null when the user must sign in again.
    // Throws AuthorizationException on network errors: keep the session and retry later.
    suspend fun freshSession(): Session? = refreshLock.withLock { // one refresh at a time
        val current = store.get("session")?.let { sessionFromJson(it) } ?: return null
        if (current.expiresAt - 60_000 > System.currentTimeMillis()) return current
        val startedIn = generation
        val tokens = try {
            tokenRequest(TokenRequest.Builder(discover(), CLIENT_ID)
                .setGrantType(GrantTypeValues.REFRESH_TOKEN)
                .setRefreshToken(current.refreshToken).build())
        } catch (e: AuthorizationException) {
            if (e != AuthorizationException.TokenRequestErrors.INVALID_GRANT) throw e
            store.put("session", null) // expired, revoked, or already rotated elsewhere
            return null
        }
        if (startedIn != generation) return null // signed out while refreshing: drop it
        val next = parseTokens(tokens)?.takeIf { it.slotId == current.slotId }
        store.put("session", next?.toJson()) // new access and refresh tokens together
        next
    }

    // 7. Sign out locally first, then revoke. Returns false when the server revocation
    // was not confirmed. The browser's AltsCodex session is not affected.
    suspend fun signOut(): Boolean {
        val session = store.get("session")?.let { sessionFromJson(it) }
        generation++
        store.put("session", null); store.put("pending", null)
        if (session == null) return true
        return withContext(Dispatchers.IO) { runCatching { revoke(session.refreshToken) }.isSuccess }
    }

    // 5. Validate before trusting. On Android, additionalParameters["slot"] is a JSON string.
    private fun parseTokens(t: TokenResponse): Session? {
        val access = t.accessToken ?: return null
        val refresh = t.refreshToken ?: return null
        if (!"Bearer".equals(t.tokenType, ignoreCase = true)) return null
        val expiresAt = t.accessTokenExpirationTime
            ?.takeIf { it > System.currentTimeMillis() } ?: return null
        val slot = try { JSONObject(t.additionalParameters["slot"] ?: return null) }
            catch (e: JSONException) { return null }
        val id = slotId(slot.opt("id")) ?: return null
        val nickname = slot.opt("token_nickname") as? String ?: return null
        return Session(access, refresh, expiresAt, id, nickname)
    }

    private fun clearPending(result: AuthResult): AuthResult =
        result.also { store.put("pending", null) }

    private suspend fun discover(): AuthorizationServiceConfiguration = config
        ?: suspendCancellableCoroutine { cont ->
            AuthorizationServiceConfiguration.fetchFromIssuer(ISSUER) { cfg, ex ->
                if (cfg != null) cont.resume(cfg)
                else cont.resumeWithException(ex ?: AuthorizationException.GeneralErrors.NETWORK_ERROR)
            }
        }.also { config = it }

    private suspend fun tokenRequest(request: TokenRequest): TokenResponse =
        suspendCancellableCoroutine { cont ->
            service.performTokenRequest(request) { response, ex ->
                if (response != null) cont.resume(response)
                else cont.resumeWithException(ex ?: AuthorizationException.GeneralErrors.SERVER_ERROR)
            }
        }

    private fun revoke(token: String) {
        val body = listOf("token" to token, "token_type_hint" to "refresh_token", "client_id" to CLIENT_ID)
            .joinToString("&") { (k, v) -> k + "=" + URLEncoder.encode(v, "UTF-8") }
        val conn = URL("https://api.altscodex.com/v1/oauth2/revoke").openConnection() as HttpURLConnection
        try {
            conn.requestMethod = "POST"; conn.doOutput = true
            conn.connectTimeout = 10_000; conn.readTimeout = 10_000
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded")
            conn.outputStream.use { it.write(body.toByteArray()) }
            check(conn.responseCode == 200)
        } finally { conn.disconnect() }
    }

    private fun Session.toJson() = JSONObject().put("access", accessToken)
        .put("refresh", refreshToken).put("expiresAt", expiresAt)
        .put("slotId", slotId).put("nickname", nickname).toString()

    private fun sessionFromJson(s: String) = JSONObject(s).run {
        Session(getString("access"), getString("refresh"), getLong("expiresAt"),
            getString("slotId"), getString("nickname"))
    }
}

// Usage in an Activity:
// val launcher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) {
//     lifecycleScope.launch { render(auth.handleResult(it.data)) } }
// lifecycleScope.launch { launcher.launch(auth.createLoginIntent()) }