# Autenticação e Login Digital via CyberCore Signer

Este documento descreve o fluxo de **Login e Autenticação de Usuários com Certificado Digital ICP-Brasil (A1 e A3)** através do agente desktop **CyberCore Signer** e o protocolo **CCSP/1**.

---

## 1. Visão Geral do Modelo de Autenticação

O login por certificado digital no CyberCore Signer adota o padrão de mercado **Challenge-Response Criptográfico**:
1. O backend da sua aplicação web gera um **desafio único (challenge / nonce)** para a sessão atual.
2. A aplicação web solicita a assinatura desse desafio ao **CyberCore Signer** através do SDK JavaScript.
3. O CyberCore Signer apresenta ao usuário na tela nativa do computador uma solicitação visual com destaque de **LOGIN / AUTENTICAÇÃO**:
   - Identifica a aplicação solicitante e a origem;
   - Mostra o certificado selecionado e o titular;
   - Solicita aprovação expressa do usuário (e a digitação do PIN caso seja token ou smart card A3).
4. O CyberCore assina o desafio com a chave privada do certificado local e devolve:
   - A **assinatura digital do desafio**;
   - O **certificado X.509 completo** (DER Base64) e cadeia;
   - O **nome e CPF/CNPJ** do titular extraídos do certificado.
5. O frontend web envia a resposta de volta ao backend, que:
   - Valida criptograficamente a assinatura com a chave pública do certificado recebido;
   - Confirma a validade e cadeia do certificado junto à ICP-Brasil;
   - Localiza o usuário correspondente no banco de dados pelo CPF/CNPJ;
   - Cria a sessão autenticada do usuário no sistema.

---

## 2. Exemplo de Integração Frontend com o SDK

```javascript
import { CyberCoreSigner } from '@cybercore/signer-sdk';

const signer = new CyberCoreSigner({
  applicationName: 'Portal Corporativo'
});

async function realizarLoginComCertificado(certificateId) {
  // 1. Obter desafio único gerado pelo seu backend
  const { challenge } = await fetch('/api/auth/challenge').then(r => r.json());

  // 2. Solicitar autenticação ao CyberCore Signer
  const authResult = await signer.authenticate({
    certificateId: certificateId,
    challenge: challenge
  });

  // 3. Enviar assinatura e certificado ao backend para validação e abertura de sessão
  const sessionResponse = await fetch('/api/auth/login-certificate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      challenge: authResult.challenge,
      signature: authResult.signature,
      certificate: authResult.certificate
    })
  });

  if (sessionResponse.ok) {
    console.log('Usuário autenticado com sucesso:', authResult.subjectName);
    window.location.href = '/dashboard';
  }
}
```

---

## 3. Segurança e Prevenção de Ataques

- **Prevenção de Ataques de Replay:** Cada desafio deve possuir tempo de expiração curto (ex: 60 a 90 segundos) e ser descartado no servidor após uma única tentativa.
- **Proteção da Chave Privada:** A chave privada e o PIN do usuário permanecem exclusivamente sob custódia do hardware/computador local do usuário.
- **Consentimento Explícito:** O CyberCore Signer nunca assina desafios em segundo plano sem a exibição do diálogo e autorização do usuário na tela nativa.