Integração com o CaraCore Seed

Visão geral para desenvolvedores que integram a validação de licenças aos próprios programas.

Autenticação na versão 0.1.5

A API local é protegida. As operações administrativas exigem sessão ADMIN e proteção CSRF; as operações destinadas a cada programa licenciado exigem o token associado à licença. O Host é verificado em todas as rotas, e o token CSRF é renovado após login e troca de senha. Não trate a API como aberta nem compartilhe tokens. A versão 0.1.3, que não exigia autenticação, foi substituída e não deve ser usada.

Na atualização de instalações antigas, licenças existentes podem precisar de emissão ou rotação do token de API para usar os endpoints protegidos. Faça backup antes de atualizar e preserve o banco e as chaves de assinatura; os bancos 0.1.3/0.1.4 e assinaturas RSA anteriores são compatíveis.

Onde consultar a API

A versão 0.1.5 escolhe uma porta local disponível ao iniciar. Leia o número em %APPDATA%\CaraCore Seed\server\server.port e abra http://127.0.0.1:<porta>/swagger-ui. O serviço fica no loopback; não é exposto à rede local. A interface e a especificação OpenAPI são servidas localmente, sem CDN ou validador remoto.

Use o Swagger local como referência para as rotas, parâmetros, autenticação e respostas disponíveis na versão instalada.

Verifique a assinatura offline

A assinatura da licença usa SHA256withRSA. A chave pública está em security/license-public.pem. O programa cliente pode verificar a assinatura sem consultar a API ou a internet, desde que tenha os bytes exatos assinados e a assinatura codificada em Base64.

A resposta da API inclui signedPayload, o texto UTF-8 exato assinado, signature em Base64 e signatureAlgorithm igual a SHA256withRSA. Verifique os bytes UTF-8 de signedPayload sem reconstruir ou reserializar o conteúdo; a forma canônica assinada foi mantida para compatibilidade com licenças anteriores.

Java

import java.nio.file.Files;
import java.nio.file.Path;
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

byte[] payloadBytes = obterBytesExatosDoPayloadAssinado();
byte[] assinatura = Base64.getDecoder().decode(assinaturaBase64);

String pem = Files.readString(Path.of("security/license-public.pem"));
String base64Key = pem
    .replace("-----BEGIN PUBLIC KEY-----", "")
    .replace("-----END PUBLIC KEY-----", "")
    .replaceAll("\\s", "");
byte[] keyBytes = Base64.getDecoder().decode(base64Key);
PublicKey chave = KeyFactory.getInstance("RSA")
    .generatePublic(new X509EncodedKeySpec(keyBytes));

Signature verifier = Signature.getInstance("SHA256withRSA");
verifier.initVerify(chave);
verifier.update(payloadBytes);
boolean assinaturaValida = verifier.verify(assinatura);

Python (pacote `cryptography`)

from base64 import b64decode
from pathlib import Path
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

payload_bytes = obter_bytes_exatos_do_payload_assinado()
assinatura = b64decode(assinatura_base64, validate=True)
chave = serialization.load_pem_public_key(
    Path("security/license-public.pem").read_bytes()
)

chave.verify(
    assinatura,
    payload_bytes,
    padding.PKCS1v15(),
    hashes.SHA256(),
)
# Se verify() terminar sem InvalidSignature, a assinatura confere.

Uma assinatura válida confirma que os bytes foram assinados com a chave privada correspondente. O cliente também deve verificar validade, produto, cliente e limites conforme os campos definidos pelo Seed e pelas regras do seu próprio programa. Proteja a chave privada: perder security/license-private.pem impede emitir novas licenças compatíveis.

Sinal periódico (heartbeat)

O programa licenciado pode enviar um sinal periódico de uso à API local. Os campos conhecidos incluem usuariosAtivos (quantidade de usuários ativos), status (estado do programa) e timestamp (data e hora do registro). Confira no Swagger da instalação o endpoint, os tipos, os valores aceitos e eventuais campos obrigatórios.

{
  "usuariosAtivos": 12,
  "status": "<estado aceito pela API>",
  "timestamp": "<data e hora aceitas pela API>"
}