Referência de API

📚 Referência de API

Referência da API pública do SDK e do contrato REST do backend que o SDK espera.

🔒 O gkas_solution produzido por buildSolution() é um token opaco. Seu conteúdo e formato são intencionalmente não documentados. O seu app o repassa ao seu backend, e o seu backend o repassa inalterado ao checkaccessxe. Você nunca lê, monta ou interpreta esse token.

---

API pública (io.guardiankey.gkas)

GuardianKeyGkas

O ponto de entrada. Construa‑o com a factory para que o provedor de identidade da plataforma, os coletores e a engine HTTP sejam ligados.

class GuardianKeyGkas {
    companion object {
        fun create(config: GkasSdkConfig, platform: PlatformContext): GuardianKeyGkas
    }

    suspend fun fetchConfig(): GkasConfig
    suspend fun buildSolution(config: GkasConfig, fieldValue: String): String  // gkas_solution opaco
    suspend fun login(request: LoginRequest): LoginResult
}

Método	Descrição
fetchConfig()	GET /config. Retorna GkasConfig (salt, once, time, url, policy).
buildSolution(config, fieldValue)	Coleta sinais e resolve a identidade, retorna o gkas_solution (string Base64 opaca). fieldValue é o usuário desta tentativa.
login(request)	POST /login. Retorna um LoginResult normalizado.

Configuração e modelos

data class GkasSdkConfig(
    val backendBaseUrl: String,   // backend REST, sem barra no final
    val httpTimeoutMs: Long = 8000,
    val debug: Boolean = false,
)

@Serializable
data class GkasConfig(
    val url: String,
    val salt: String,
    val once: String,             // nonce de uso único
    val time: String,
    val policy: GkasPolicy = GkasPolicy(),
)

@Serializable
data class GkasPolicy(
    val tiers: List<String> = listOf("software", "uuid"),  // cascata de identidade
    val user_verification: String = "preferred",
)

data class LoginRequest(
    val username: String,
    val password: String,
    val gkasSolution: String,     // resultado de buildSolution() — opaco, repasse como está
    val config: GkasConfig,       // o mesmo GkasConfig retornado por fetchConfig()
)

sealed interface LoginResult {
    data class Allowed(val raw: String) : LoginResult
    data class Blocked(val reason: String?, val raw: String) : LoginResult
    data class Error(val message: String) : LoginResult
}

GkasConfig é retornado por fetchConfig() e repassado diretamente para buildSolution() e LoginRequest — você não o constrói manualmente. O campo policy.tiers é o que dirige o comportamento de identidade (prompt biométrico vs. silencioso).

PlatformContext

Bag de dependências específicas da plataforma (expect/actual):

• Android: PlatformContext(context: Context, activityProvider: () -> FragmentActivity? = { null }). O activityProvider é usado pelo tier biométrico para hospedar o BiometricPrompt.
• iOS: PlatformContext() — vazio (stubs).

GkasTouchTracker (Android)

object no qual o app alimenta eventos de toque brutos:

GkasTouchTracker.feed(event: MotionEvent)   // chame em Activity.dispatchTouchEvent

Registra apenas características comportamentais dos toques — nunca o conteúdo digitado.

---

Contrato do backend

O SDK fala apenas com o seu backend. O seu backend guarda as credenciais GuardianKey e chama checkaccessxe no servidor. Dois endpoints são exigidos (mais um health check opcional).

GET /config

Gera e persiste um once de uso único e retorna as entradas do challenge + policy:

{
  "url":  "https://seu-backend.exemplo.com/api/login",
  "salt": "demo_salt",
  "once": "<nonce>",
  "time": "<unix ts>",
  "policy": { "tiers": ["biometric","software","uuid"], "user_verification": "preferred" }
}

policy.tiers define qual identidade o SDK usa (biometric / só software / uuid).

POST /login

Corpo da requisição (enviado pelo SDK):

{
  "username": "alice",
  "password": "secret",
  "gkas_solution": "<token opaco>",
  "url": "...", "salt": "...", "once": "...", "time": "..."
}

O backend deve:

1. Validar o once (existe, não expirado, não reutilizado) e consumi‑lo.
2. Decidir o flag de tentativa — attempt = "0" quando a senha está correta, "1" caso contrário.
3. Chamar checkaccessxe($username, "", $url, $salt, $once, $time, $gkas_solution, $attempt), repassando o gkas_solution inalterado.
4. Retornar uma decisão normalizada:

{
  "decision": "ALLOW" | "BLOCK",
  "attempt": "0",
  "gk_raw": { /* resposta bruta do checkaccessxe */ }
}

O SDK mapeia decision para LoginResult: ALLOW → Allowed, BLOCK → Blocked (com um reason opcional), qualquer outra coisa / falha de rede → Error.

GET /health (opcional)

{ "status": "ok" } — smoke test.

O backend repassa o gkas_solution ao checkaccessxe inalterado via frontend_data, então nenhuma mudança na guardiankey.class.php de referência é necessária.