ADR-0002: WebAuthn & zcap-ld

  • Status: Proposto
  • Data: 2026-05-11

1. Contexto

O sistema Gleam-BR utiliza did:key para identidades M2M (Machine-to-Machine) na malha P2P. No entanto, a interação humana (H2M) exige um método de autenticação que seja seguro contra phishing e conveniente (biométrico).

Precisamos integrar humanos na malha sem comprometer a natureza descentralizada e sem expor as chaves privadas dos Agentes diretamente aos navegadores.

2. Decisão

Adotamos a seguinte estrutura para autenticação e autorização humanas na malha:

  1. WebAuthn como Gateway: Utilizar Passkeys (WebAuthn) exclusivamente na camada de borda (Web/Mobile) para autenticar o usuário humano contra o seu respectivo Nó Gateway.
  2. Autorização via zcap-ld: Em vez de manter sessões HTTP tradicionais de cookies/tokens, o sucesso do WebAuthn resultará na geração de uma Invocação de Capability (zcap-ld). O usuário humano assina digitalmente uma delegação para o did:key do Agente na borda.
  3. Atenuação de Poderes: As permissões delegadas via WebAuthn conterão restrições explícitas (como tempos limite de expiração e escopos de comando restritos) para mitigar o risco caso o dispositivo físico do Agente seja comprometido.
  4. Verificação no Core: O pacote shared/gbr_crypto será expandido para validar assinaturas P-256 (comuns em autenticadores WebAuthn) e verificar a cadeia de delegação criptográfica zcap-ld.

3. Consequências

  • Positivas: - Segurança criptográfica de alta resiliência baseada em biometria física (phishing-resistant). - Compatibilidade direta com hardware de segurança em sistemas modernos (iPhone FaceID, Android Fingerprint, Windows Hello). - Mantém o núcleo M2P da malha P2P agnóstico em relação a rotinas web de navegadores.
  • Negativas/Desafios: - Exige processar assinaturas em curvas P-256 via Rustler NIF (em adição à curva Ed25519 nativa). - Complexidade adicional para construir, serializar e transmitir as cadeias de delegação em CBOR ou DAG-CBOR.