# CyberCore Signing Protocol (CCSP/1)

O **CyberCore Signing Protocol (CCSP)** é o protocolo padrão para comunicação local entre aplicações web rodando no navegador e o agente desktop **CyberCore Signer**.

A versão inicial descrita neste documento é a **CCSP/1**.

---

## 1. Princípios de Segurança

1. **Isolamento de Rede:** O servidor local escuta exclusivamente no endereço de loopback `127.0.0.1` (porta padrão `21325`), impedindo qualquer acesso a partir da rede local (LAN) ou externa (WAN).
2. **Controle Estrito de Origem (CORS):** O agente valida cabeçalhos `Origin` e responde apenas a pré-voos `OPTIONS` com origens autorizadas.
3. **Registro e Autorização de Aplicações:** Nenhuma aplicação desconhecida tem acesso a certificados ou assinaturas. Ao tentar conectar pela primeira vez, uma caixa de diálogo nativa solicita aprovação explícita do usuário.
4. **Confirmação Visual da Assinatura:** Toda operação de assinatura exige confirmação manual na interface gráfica, exibindo a aplicação solicitante, o hash do documento e o certificado selecionado.
5. **Proteção Contra Ataques de Replay:** Toda requisição deve conter um `nonce` UUID único com validação temporal (`expires_at` ou `timestamp`). Requisições com nonces repetidos são sumariamente rejeitadas (`REPLAY_DETECTED`).
6. **Privacidade Criptográfica:** Apenas o **digest (hash)** do documento é enviado ao agente. O documento completo nunca sai da aplicação web e a chave privada nunca sai do dispositivo/computador do usuário.

---

## 2. Endpoints do Protocolo (CCSP/1)

### 2.1 `GET /ccsp/v1/status`
Verifica se o agente está instalado, em execução e pronto para operações.

#### Resposta de Sucesso (200 OK)
```json
{
  "version": "1",
  "status": "ready",
  "agent": "CyberCore Signer",
  "agent_version": "0.1.0",
  "os": "Windows 11",
  "timestamp": "2026-10-08T19:40:00Z"
}
```

---

### 2.2 `GET /ccsp/v1/certificates`
Retorna a lista de certificados digitais atualmente disponíveis e aptos para assinatura.

#### Headers / Parâmetros
- `X-CyberCore-AppId`: UUID da aplicação autorizada (ou query param `?application_id=uuid`).
- `Origin`: Origem web autorizada.

#### Resposta de Sucesso (200 OK)
```json
{
  "version": "1",
  "status": "success",
  "certificates": [
    {
      "id": "win-4340656a",
      "alias": "CLAUDIO SILVA:12345678900",
      "common_name": "CLAUDIO SILVA:12345678900",
      "subject_dn": "CN=CLAUDIO SILVA:12345678900, OU=Autenticado por AR, O=ICP-Brasil, C=BR",
      "issuer_dn": "CN=AC SERPRO v5, O=ICP-Brasil, C=BR",
      "type": "A3",
      "provider_id": "provider-win-store",
      "device_name": "Token / Smart Card (Windows CAPI/CNG)",
      "valid_from": "2024-05-10T12:00:00Z",
      "valid_to": "2027-05-10T12:00:00Z",
      "serial_number": "72910482910482019482",
      "can_sign": true,
      "status": "AVAILABLE"
    }
  ]
}
```

---

### 2.3 `POST /ccsp/v1/authorize`
Handshake inicial de uma nova aplicação web para solicitar autorização ao usuário.

#### Requisição
```json
{
  "version": "1",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Portal Assinaturas Jurídicas"
}
```

#### Resposta (200 OK)
```json
{
  "version": "1",
  "status": "authorized",
  "application_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

---

### 2.4 `POST /ccsp/v1/sign`
Executa a assinatura digital do digest informado (PDF, XML, documentos ou arquivos gerais).

#### Requisição
```json
{
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "sign",
  "algorithm": "SHA256withRSA",
  "digest": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
  "certificate_hint": "win-4340656a",
  "document_name": "contrato_locacao.pdf",
  "document_type": "PDF",
  "nonce": "c4ca4238a0b923820dcc509a6f75849b",
  "expires_at": "2026-10-08T19:45:00Z"
}
```

#### Resposta de Sucesso (200 OK)
```json
{
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "signed",
  "signature": "MEUCIQDq...base64...",
  "certificate": "MIIFazC...base64...",
  "certificate_chain": [
    "MIIFazC...base64...",
    "MIIEazC...base64..."
  ],
  "algorithm": "SHA256withRSA",
  "subject_name": "CLAUDIO SILVA",
  "subject_cpf_cnpj": "12345678900",
  "document_name": "contrato_locacao.pdf",
  "document_type": "PDF"
}
```

---

### 2.5 `POST /ccsp/v1/authenticate`
Executa o login / autenticação digital segura de um usuário em sistemas web via desafio criptográfico (Challenge-Response ICP-Brasil).

#### Requisição
```json
{
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "authenticate",
  "challenge": "server-session-challenge-nonce-2026",
  "certificate_hint": "win-4340656a",
  "purpose": "AUTHENTICATION",
  "nonce": "c4ca4238a0b923820dcc509a6f75849b",
  "expires_at": "2026-10-08T19:45:00Z"
}
```

#### Resposta de Sucesso (200 OK)
```json
{
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "authenticated",
  "signature": "MEUCIQDq...base64...",
  "certificate": "MIIFazC...base64...",
  "certificate_chain": [
    "MIIFazC...base64..."
  ],
  "algorithm": "SHA256withRSA",
  "subject_name": "CLAUDIO SILVA",
  "subject_cpf_cnpj": "12345678900",
  "document_type": "AUTH_CHALLENGE"
}
```

#### Resposta de Erro (400/403/404)
```json
{
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "error",
  "error_code": "USER_CANCELLED",
  "message": "Operação de assinatura cancelada pelo usuário."
}
```

---

## 3. Tabela de Códigos de Erro Estruturados

| Código | Significado |
|---|---|
| `CERTIFICATE_NOT_FOUND` | Certificado indicado no hint não foi encontrado. |
| `CERTIFICATE_EXPIRED` | O certificado selecionado está fora do período de vigência. |
| `CERTIFICATE_INVALID` | O certificado é inválido ou corrompido. |
| `PRIVATE_KEY_NOT_AVAILABLE` | Chave privada inacessível ou ausente. |
| `TOKEN_NOT_FOUND` | Nenhum dispositivo ou leitor compatível foi localizado. |
| `TOKEN_REMOVED` | Dispositivo de hardware foi removido durante a assinatura. |
| `PIN_REQUIRED` | PIN obrigatório para liberar chave privada em PKCS#11. |
| `PIN_INCORRECT` | PIN digitado está incorreto. |
| `PKCS11_ERROR` | Falha no middleware PKCS#11 do fabricante. |
| `SIGNATURE_FAILED` | Erro durante a geração da assinatura digital. |
| `APPLICATION_NOT_AUTHORIZED` | Aplicação não autorizada ou recusada pelo usuário. |
| `REQUEST_EXPIRED` | A data/hora de validade da requisição expirou. |
| `REPLAY_DETECTED` | O nonce informado já foi processado anteriormente. |
| `INVALID_ORIGIN` | O cabeçalho Origin não corresponde ao cadastro da aplicação. |
| `UNSUPPORTED_ALGORITHM` | Algoritmo não suportado (ex: diferente de SHA256withRSA). |
| `USER_CANCELLED` | O usuário clicou em Cancelar ou fechou a janela de confirmação. |
| `PROVIDER_NOT_AVAILABLE` | O provedor criptográfico necessário está inativo no SO. |
| `COMMUNICATION_ERROR` | Erro interno no agente de comunicação local. |