Visão Geral

📱 GuardianKey Mobile SDK

O GuardianKey Mobile SDK leva o Auth Security XE (checkaccessxe) para apps móveis nativos. É uma biblioteca Kotlin Multiplatform (KMP) que você invoca na etapa de login do seu próprio aplicativo Android/iOS — exatamente como faz o app de exemplo de referência. A cada tentativa de login, o SDK coleta informações do dispositivo e do comportamento, monta um token gkas_solution, e o seu backend o repassa ao GuardianKey, que retorna uma decisão de risco (ALLOW / BLOCK).

É o equivalente móvel do coletor web: onde o navegador executa um trecho de JavaScript no formulário de login, o SDK executa a mesma lógica nativamente.

🔒 O conteúdo e o formato do gkas_solution são intencionalmente não documentados — trate‑o como um token opaco. Você nunca precisa ler, montar ou interpretar esse token: o SDK o produz, o seu app o repassa ao seu backend, e o seu backend o repassa inalterado ao checkaccessxe. Esta página e os guias de integração cobrem tudo o que é necessário para integrar; o payload interno é uma caixa‑preta por design.

---

🧩 O que você integra

Peça	Quem fornece	Papel
Mobile SDK (io.guardiankey.gkas)	GuardianKey (este SDK)	Coleta sinais, monta o token gkas_solution, fala com o seu backend.
Seu app (Android/iOS)	Você	Invoca o SDK durante o login e reage à decisão.
Seu backend (REST)	Você	Expõe GET /config e POST /login; chama checkaccessxe no servidor com as suas credenciais GuardianKey.

🔐 As credenciais GuardianKey (key/iv/agentId/…) ficam apenas no seu backend. O app móvel nunca as possui. O app só fala com o seu backend.

---

🔄 Fluxo de login

O SDK expõe três chamadas. Uma tela de login as orquestra em ordem:

        ┌─────────────┐   1. fetchConfig()      ┌──────────────┐
        │   Seu app   │ ──────────────────────▶ │  Seu backend │  GET /config
        │  (UI login) │ ◀────────────────────── │    (REST)    │  → salt, once, time, policy, url
        └─────────────┘   salt/once/time/policy └──────────────┘
              │
              │ 2. buildSolution(config, username)
              │    coleta sinais + resolve identidade → gkas_solution (token opaco)
              ▼
        ┌─────────────┐   3. login(LoginRequest) ┌──────────────┐   checkaccessxe   ┌────────────┐
        │   Seu app   │ ──────────────────────▶  │  Seu backend │ ────────────────▶ │ GuardianKey│
        │             │ ◀──────────────────────  │              │ ◀──────────────── │    XE      │
        └─────────────┘   decisão: ALLOW|BLOCK   └──────────────┘  decisão de risco └────────────┘
              │
              ├─ ALLOW → entra no app (Home)
              └─ BLOCK → permanece no login, mostra a mensagem de bloqueio

1. fetchConfig() — GET /config retorna salt, once (nonce de uso único), time, url e uma policy que diz ao SDK qual tier de identidade usar.
2. buildSolution(config, username) — coleta sinais, resolve a identidade do dispositivo e retorna o gkas_solution (um token opaco). username é o valor do campo vinculado a esta tentativa.
3. login(LoginRequest(...)) — POST /login com as credenciais e o gkas_solution. O backend valida/consome o once, chama checkaccessxe e retorna uma decision normalizada.

---

🪪 Tiers de identidade do dispositivo

O policy.tiers do backend seleciona, em cascata com fallback, como o dispositivo se identifica na tentativa. A única coisa que o integrador precisa saber é o comportamento percebido pelo usuário:

Tier	Experiência do usuário
biometric	Exibe um prompt biométrico (digital/face) durante o login.
software	Silencioso — sem prompt.
uuid	Fallback silencioso quando tiers mais fortes não estão disponíveis.

No iOS os mesmos tiers mapeiam para os mecanismos nativos da plataforma (hoje fornecidos como stubs compiláveis — veja a página de iOS).

---

📦 Sinais coletados

Durante o buildSolution() o SDK reúne uma série de informações do dispositivo e do comportamento (como sinais de biometria/identidade, comportamento de toque, entre outros) e as empacota no token opaco gkas_solution.

O que importa para a integração:

• Best‑effort, nunca bloqueia o login. Cada coletor tolera permissões ausentes ou hardware indisponível — se algo não puder ser lido, é simplesmente omitido e o login prossegue.
• Nenhum conteúdo digitado é capturado (por exemplo, os sinais comportamentais de toque registram dinâmica, não o que o usuário digita).
• Permissões são opcionais. Conceder mais permissões em runtime rende sinais mais ricos, mas negá‑las nunca quebra o fluxo. Veja o guia Android para a lista de permissões.

---

⏭️ Próximos passos

• Integração Android — passo a passo.
• Integração iOS — estado atual e contrato.
• Referência de API — API pública e contrato do backend.