feat: initial commit - cybercore signer desktop agent

docs/authentication-login.md

@@ -0,0 +1,71 @@
+# 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.