cuboutils 0.1.0__tar.gz

cuboutils-0.1.0/LICENSE_FORMAT.md

@@ -0,0 +1,88 @@
+# Formato da licença
+
+O emissor gera um blob JSON UTF-8 assinado com Ed25519. O instalador grava esse blob, sem extensão, em:
+
+```text
+C:\ProgramData\CUBO\-
+```
+
+O caminho de `ProgramData` é obtido pela API `SHGetKnownFolderPath` do Windows, portanto não depende da variável de ambiente `%PROGRAMDATA%` nem de o Windows estar instalado na unidade `C:`.
+
+## Dados assinados
+
+O `payload` possui exatamente três campos:
+
+```json
+{
+  "expires_at": "2027-09-04T23:59:59Z",
+  "machine_id": "HW1-ABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMNOPQRST",
+  "products": ["OutroPrograma", "TQSVigas"]
+}
+```
+
+### `machine_id`
+
+- identifica o computador autorizado;
+- começa com `HW1-`;
+- após o prefixo, possui exatamente 52 caracteres Base32 maiúsculos, usando `A-Z` e `2-7`;
+- é o SHA-256 dos identificadores normalizados do computador, codificado em Base32;
+- não expõe diretamente UUID SMBIOS, serial da placa-mãe ou `MachineGuid`.
+
+### `products`
+
+- é uma lista com pelo menos um produto;
+- é armazenada em ordem lexicográfica e sem duplicatas;
+- cada identificador possui de 1 a 100 caracteres;
+- o primeiro caractere deve ser alfanumérico;
+- os demais podem ser alfanuméricos, ponto, sublinhado ou hífen;
+- diferencia letras maiúsculas de minúsculas.
+
+### `expires_at`
+
+- indica o instante final da validade;
+- usa UTC e não possui microssegundos;
+- segue exatamente o formato `YYYY-MM-DDTHH:MM:SSZ`.
+
+## Envelope armazenado
+
+O arquivo `-` contém exatamente:
+
+```json
+{
+  "payload": "BASE64URL_SEM_PADDING",
+  "signature": "ASSINATURA_ED25519_EM_BASE64URL"
+}
+```
+
+- `payload` é o JSON descrito acima, codificado em Base64URL sem `=` no final;
+- `signature` é a assinatura Ed25519 dos bytes exatos do `payload`, também codificada em Base64URL sem `=`;
+- a assinatura decodificada possui exatamente 64 bytes;
+- o emissor produz JSON compacto, com chaves ordenadas e sem espaços desnecessários;
+- o envelope produzido termina com uma quebra de linha.
+
+O limite é de 4 KiB para o `payload` e 16 KiB para o blob completo.
+
+## Armazenamento
+
+`license.storage.save_license()` grava o blob em `C:\ProgramData\CUBO\-` e aplica os atributos `Hidden` e `System`. Esses atributos apenas reduzem a visibilidade no Explorador de Arquivos; não impedem leitura, cópia ou exclusão.
+
+## Validação
+
+`license` libera um produto somente quando:
+
+1. o blob e o `payload` possuem a estrutura esperada;
+2. a assinatura é válida para a chave pública incorporada;
+3. o `machine_id` assinado coincide com o computador atual;
+4. o produto solicitado aparece em `products`;
+5. a hora atual não ultrapassou `expires_at`.
+
+O arquivo não é criptografado. Qualquer pessoa pode decodificar e ler seu conteúdo, mas uma alteração no `machine_id`, em `products` ou em `expires_at` invalida a assinatura.
+
+## Responsabilidades
+
+- `license.issuer`: monta o `payload` e o assina com a chave privada recebida por argumento;
+- `license.machine`: calcula o código da máquina;
+- `license.storage`: lê e instala o blob;
+- `license.verifier`: valida o blob com a chave pública incorporada.
+
+Durante este teste de conceito, a chave privada está na raiz do repositório. Em produção, ela nunca deve fazer parte do repositório, do instalador ou dos programas consumidores.

cuboutils-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: cuboutils
+Version: 0.1.0
+Summary: Utilitários compartilhados pelos produtos CUBO
+Author: Leonardo Pires Batista
+Author-email: leonardopbatista98@gmail.com
+Keywords: cubo licença atualização
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE_FORMAT.md
+Requires-Dist: cryptography==50.0.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# CuboUtils
+
+Este repositório contém utilitários compartilhados pelos produtos CUBO:
+
+- `license/`: emissão, instalação e validação de licenças;
+- `update_checker/`: consulta da versão mais recente de um produto.
+
+## Licenças
+
+A diferença entre os programas está somente nas operações utilizadas:
+
+- o consumidor chama `verify_installed_license()`;
+- o instalador chama `current_machine_id()` e `save_license()`;
+- o emissor chama `issue_license()` e fornece sua chave privada.
+
+A chave pública fictícia está incorporada em `license/public_key.py`. Durante este teste de conceito, a chave privada correspondente está em `private-key.pem`, na raiz do repositório.
+
+As duas chaves atuais são apenas para desenvolvimento. Antes de qualquer distribuição real, remova `private-key.pem` do repositório e substitua o par por chaves mantidas em um ambiente seguro.
+
+A licença instalada usa o caminho fixo `C:\ProgramData\CUBO\-`. `save_license()` grava o arquivo com os atributos `Hidden` e `System`, enquanto os programas consumidores usam somente a interface de validação.
+
+O formato compartilhado está descrito em `LICENSE_FORMAT.md`, e os exemplos de cada operação estão em `license/README.md`.
+
+## Verificação de versão
+
+O endpoint retorna um único objeto JSON que relaciona cada produto à sua versão mais recente:
+
+```json
+{
+  "TQSVigas": "v1.0.0",
+  "TQSFormas": "v1.0.0"
+}
+```
+
+O utilitário retorna `True` quando a versão informada é igual ou posterior à versão publicada:
+
+```python
+from update_checker import is_latest_version
+
+updated = is_latest_version(
+    endpoint="https://leonardopbatista.github.io/versions/versions.json",
+    product="TQSVigas",
+    version="2027.2.0",
+)
+```
+
+Versões aceitas são sequências numéricas separadas por pontos, com um `v` inicial opcional. A consulta possui timeout padrão de cinco segundos e lança `UpdateCheckError` quando a rede ou a resposta do servidor falha.

cuboutils-0.1.0/README.md

@@ -0,0 +1,47 @@
+# CuboUtils
+
+Este repositório contém utilitários compartilhados pelos produtos CUBO:
+
+- `license/`: emissão, instalação e validação de licenças;
+- `update_checker/`: consulta da versão mais recente de um produto.
+
+## Licenças
+
+A diferença entre os programas está somente nas operações utilizadas:
+
+- o consumidor chama `verify_installed_license()`;
+- o instalador chama `current_machine_id()` e `save_license()`;
+- o emissor chama `issue_license()` e fornece sua chave privada.
+
+A chave pública fictícia está incorporada em `license/public_key.py`. Durante este teste de conceito, a chave privada correspondente está em `private-key.pem`, na raiz do repositório.
+
+As duas chaves atuais são apenas para desenvolvimento. Antes de qualquer distribuição real, remova `private-key.pem` do repositório e substitua o par por chaves mantidas em um ambiente seguro.
+
+A licença instalada usa o caminho fixo `C:\ProgramData\CUBO\-`. `save_license()` grava o arquivo com os atributos `Hidden` e `System`, enquanto os programas consumidores usam somente a interface de validação.
+
+O formato compartilhado está descrito em `LICENSE_FORMAT.md`, e os exemplos de cada operação estão em `license/README.md`.
+
+## Verificação de versão
+
+O endpoint retorna um único objeto JSON que relaciona cada produto à sua versão mais recente:
+
+```json
+{
+  "TQSVigas": "v1.0.0",
+  "TQSFormas": "v1.0.0"
+}
+```
+
+O utilitário retorna `True` quando a versão informada é igual ou posterior à versão publicada:
+
+```python
+from update_checker import is_latest_version
+
+updated = is_latest_version(
+    endpoint="https://leonardopbatista.github.io/versions/versions.json",
+    product="TQSVigas",
+    version="2027.2.0",
+)
+```
+
+Versões aceitas são sequências numéricas separadas por pontos, com um `v` inicial opcional. A consulta possui timeout padrão de cinco segundos e lança `UpdateCheckError` quando a rede ou a resposta do servidor falha.

cuboutils-0.1.0/cuboutils.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: cuboutils
+Version: 0.1.0
+Summary: Utilitários compartilhados pelos produtos CUBO
+Author: Leonardo Pires Batista
+Author-email: leonardopbatista98@gmail.com
+Keywords: cubo licença atualização
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE_FORMAT.md
+Requires-Dist: cryptography==50.0.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# CuboUtils
+
+Este repositório contém utilitários compartilhados pelos produtos CUBO:
+
+- `license/`: emissão, instalação e validação de licenças;
+- `update_checker/`: consulta da versão mais recente de um produto.
+
+## Licenças
+
+A diferença entre os programas está somente nas operações utilizadas:
+
+- o consumidor chama `verify_installed_license()`;
+- o instalador chama `current_machine_id()` e `save_license()`;
+- o emissor chama `issue_license()` e fornece sua chave privada.
+
+A chave pública fictícia está incorporada em `license/public_key.py`. Durante este teste de conceito, a chave privada correspondente está em `private-key.pem`, na raiz do repositório.
+
+As duas chaves atuais são apenas para desenvolvimento. Antes de qualquer distribuição real, remova `private-key.pem` do repositório e substitua o par por chaves mantidas em um ambiente seguro.
+
+A licença instalada usa o caminho fixo `C:\ProgramData\CUBO\-`. `save_license()` grava o arquivo com os atributos `Hidden` e `System`, enquanto os programas consumidores usam somente a interface de validação.
+
+O formato compartilhado está descrito em `LICENSE_FORMAT.md`, e os exemplos de cada operação estão em `license/README.md`.
+
+## Verificação de versão
+
+O endpoint retorna um único objeto JSON que relaciona cada produto à sua versão mais recente:
+
+```json
+{
+  "TQSVigas": "v1.0.0",
+  "TQSFormas": "v1.0.0"
+}
+```
+
+O utilitário retorna `True` quando a versão informada é igual ou posterior à versão publicada:
+
+```python
+from update_checker import is_latest_version
+
+updated = is_latest_version(
+    endpoint="https://leonardopbatista.github.io/versions/versions.json",
+    product="TQSVigas",
+    version="2027.2.0",
+)
+```
+
+Versões aceitas são sequências numéricas separadas por pontos, com um `v` inicial opcional. A consulta possui timeout padrão de cinco segundos e lança `UpdateCheckError` quando a rede ou a resposta do servidor falha.

cuboutils-0.1.0/cuboutils.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE_FORMAT.md
+README.md
+setup.py
+cuboutils.egg-info/PKG-INFO
+cuboutils.egg-info/SOURCES.txt
+cuboutils.egg-info/dependency_links.txt
+cuboutils.egg-info/requires.txt
+cuboutils.egg-info/top_level.txt
+license/__init__.py
+license/contract.py
+license/issuer.py
+license/machine.py
+license/public_key.py
+license/storage.py
+license/verifier.py
+tests/test_license_flow.py
+tests/test_machine.py
+tests/test_storage.py
+tests/test_update_checker.py
+update_checker/__init__.py
+update_checker/checker.py

cuboutils-0.1.0/cuboutils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cuboutils-0.1.0/cuboutils.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography==50.0.1

cuboutils-0.1.0/cuboutils.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+license
+update_checker

cuboutils-0.1.0/license/__init__.py

@@ -0,0 +1,22 @@
+"""Emissão, instalação e validação das licenças dos produtos CUBO."""
+
+from license.contract import LicenseClaims, LicenseContractError
+from license.issuer import issue_license
+from license.machine import MachineFingerprintError, current_machine_id
+from license.storage import LICENSE_PATH, load_license, save_license
+from license.verifier import LicenseStatus, LicenseVerification, verify_installed_license, verify_license
+
+__all__ = [
+    "LICENSE_PATH",
+    "LicenseClaims",
+    "LicenseContractError",
+    "LicenseStatus",
+    "LicenseVerification",
+    "MachineFingerprintError",
+    "current_machine_id",
+    "issue_license",
+    "load_license",
+    "save_license",
+    "verify_installed_license",
+    "verify_license",
+]

cuboutils-0.1.0/license/contract.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+
+MACHINE_ID_PATTERN = re.compile(r"HW1-[A-Z2-7]{52}")
+PRODUCT_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,99}")
+_PAYLOAD_FIELDS = frozenset({"machine_id", "products", "expires_at"})
+_ENVELOPE_FIELDS = frozenset({"payload", "signature"})
+_MAX_BLOB_SIZE = 16 * 1024
+_MAX_PAYLOAD_SIZE = 4 * 1024
+
+
+class LicenseContractError(ValueError):
+    """Indica que uma licença ou seus dados não obedecem ao formato esperado."""
+
+
+@dataclass(frozen=True, slots=True)
+class LicenseClaims:
+    machine_id: str
+    products: tuple[str, ...]
+    expires_at: datetime
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.machine_id, str) or not MACHINE_ID_PATTERN.fullmatch(self.machine_id):
+            raise LicenseContractError("machine_id é inválido.")
+        if not isinstance(self.products, tuple) or not self.products:
+            raise LicenseContractError("products deve ser uma tupla com ao menos um produto.")
+        if any(not isinstance(product, str) or not PRODUCT_PATTERN.fullmatch(product) for product in self.products):
+            raise LicenseContractError("products contém um produto inválido.")
+        if not isinstance(self.expires_at, datetime) or self.expires_at.tzinfo is None or self.expires_at.utcoffset() is None:
+            raise LicenseContractError("expires_at deve possuir fuso horário.")
+        object.__setattr__(self, "products", tuple(sorted(set(self.products))))
+        object.__setattr__(self, "expires_at", self.expires_at.astimezone(timezone.utc).replace(microsecond=0))
+
+    @classmethod
+    def from_payload_bytes(cls, payload_bytes: bytes) -> LicenseClaims:
+        if not payload_bytes or len(payload_bytes) > _MAX_PAYLOAD_SIZE:
+            raise LicenseContractError("O tamanho do payload é inválido.")
+        try:
+            payload = json.loads(payload_bytes.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise LicenseContractError("O payload não contém JSON UTF-8 válido.") from error
+        if not isinstance(payload, dict) or set(payload) != _PAYLOAD_FIELDS:
+            raise LicenseContractError("O payload não possui exatamente os campos esperados.")
+
+        machine_id = payload["machine_id"]
+        products = payload["products"]
+        expires_at = payload["expires_at"]
+        if not isinstance(machine_id, str) or not MACHINE_ID_PATTERN.fullmatch(machine_id):
+            raise LicenseContractError("machine_id é inválido.")
+        if not isinstance(products, list) or not products:
+            raise LicenseContractError("products deve ser uma lista com ao menos um produto.")
+        if any(not isinstance(product, str) or not PRODUCT_PATTERN.fullmatch(product) for product in products):
+            raise LicenseContractError("products contém um produto inválido.")
+        if products != sorted(set(products)):
+            raise LicenseContractError("products deve estar ordenado e sem duplicatas.")
+        if not isinstance(expires_at, str):
+            raise LicenseContractError("expires_at deve ser uma string UTC.")
+        try:
+            parsed_expiration = datetime.strptime(expires_at, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+        except ValueError as error:
+            raise LicenseContractError("expires_at deve usar o formato YYYY-MM-DDTHH:MM:SSZ.") from error
+        return cls(machine_id, tuple(products), parsed_expiration)
+
+    def to_payload_bytes(self) -> bytes:
+        payload = {
+            "machine_id": self.machine_id,
+            "products": list(self.products),
+            "expires_at": self.expires_at.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        }
+        payload_bytes = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        if len(payload_bytes) > _MAX_PAYLOAD_SIZE:
+            raise LicenseContractError("O tamanho do payload é inválido.")
+        return payload_bytes
+
+
+@dataclass(frozen=True, slots=True)
+class LicenseEnvelope:
+    payload: bytes
+    signature: bytes
+
+    @classmethod
+    def from_blob(cls, blob: bytes) -> LicenseEnvelope:
+        if not blob or len(blob) > _MAX_BLOB_SIZE:
+            raise LicenseContractError("O tamanho da licença é inválido.")
+        try:
+            document = json.loads(blob.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise LicenseContractError("A licença não contém JSON UTF-8 válido.") from error
+        if not isinstance(document, dict) or set(document) != _ENVELOPE_FIELDS:
+            raise LicenseContractError("A licença não possui exatamente os campos esperados.")
+        if any(not isinstance(document[field], str) for field in _ENVELOPE_FIELDS):
+            raise LicenseContractError("Os campos da licença devem ser strings.")
+        payload = _base64url_decode(document["payload"], "payload")
+        signature = _base64url_decode(document["signature"], "signature")
+        if not payload or len(payload) > _MAX_PAYLOAD_SIZE:
+            raise LicenseContractError("O tamanho do payload é inválido.")
+        if len(signature) != 64:
+            raise LicenseContractError("A assinatura Ed25519 deve possuir 64 bytes.")
+        return cls(payload, signature)
+
+    def to_blob(self) -> bytes:
+        if not self.payload or len(self.payload) > _MAX_PAYLOAD_SIZE:
+            raise LicenseContractError("O tamanho do payload é inválido.")
+        if len(self.signature) != 64:
+            raise LicenseContractError("A assinatura Ed25519 deve possuir 64 bytes.")
+        document = {
+            "payload": base64.urlsafe_b64encode(self.payload).rstrip(b"=").decode("ascii"),
+            "signature": base64.urlsafe_b64encode(self.signature).rstrip(b"=").decode("ascii"),
+        }
+        blob = json.dumps(document, sort_keys=True, separators=(",", ":")).encode("utf-8") + b"\n"
+        if len(blob) > _MAX_BLOB_SIZE:
+            raise LicenseContractError("O tamanho da licença é inválido.")
+        return blob
+
+
+def _base64url_decode(value: str, field_name: str) -> bytes:
+    if not value or not re.fullmatch(r"[A-Za-z0-9_-]+", value):
+        raise LicenseContractError(f"{field_name} não contém base64url válido.")
+    try:
+        return base64.b64decode(value + "=" * (-len(value) % 4), altchars=b"-_", validate=True)
+    except (ValueError, binascii.Error) as error:
+        raise LicenseContractError(f"{field_name} não contém base64url válido.") from error

cuboutils-0.1.0/license/issuer.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from license.contract import LicenseClaims, LicenseContractError, LicenseEnvelope
+
+
+def issue_license(claims: LicenseClaims, private_key_pem: bytes, password: bytes | None = None) -> bytes:
+    """Assina os dados com uma chave privada fornecida pelo ambiente emissor."""
+    if not isinstance(claims, LicenseClaims):
+        raise TypeError("claims deve ser uma instância de LicenseClaims.")
+    try:
+        private_key = serialization.load_pem_private_key(private_key_pem, password=password)
+    except (TypeError, ValueError) as error:
+        raise LicenseContractError("Não foi possível abrir a chave privada.") from error
+    if not isinstance(private_key, Ed25519PrivateKey):
+        raise LicenseContractError("A chave privada não é Ed25519.")
+    payload = claims.to_payload_bytes()
+    return LicenseEnvelope(payload, private_key.sign(payload)).to_blob()

cuboutils-0.1.0/license/machine.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import subprocess
+import sys
+import winreg
+from collections.abc import Mapping
+
+
+_INVALID_VALUES = frozenset({
+    "",
+    "none",
+    "null",
+    "unknown",
+    "default string",
+    "system serial number",
+    "to be filled by o.e.m.",
+    "not applicable",
+    "not specified",
+    "ffffffff-ffff-ffff-ffff-ffffffffffff",
+    "00000000-0000-0000-0000-000000000000",
+})
+
+
+class MachineFingerprintError(RuntimeError):
+    """Indica que o computador não forneceu identificadores utilizáveis."""
+
+
+def current_machine_id() -> str:
+    """Calcula o identificador HW1 deste computador Windows."""
+    if sys.platform != "win32":
+        raise MachineFingerprintError("A coleta automática de identificadores está disponível apenas no Windows.")
+    return fingerprint_from_identifiers(collect_windows_identifiers())
+
+
+def collect_windows_identifiers() -> dict[str, str]:
+    """Coleta UUID SMBIOS, serial da placa-mãe e MachineGuid localmente."""
+    identifiers = _read_cim_identifiers()
+    machine_guid = _read_machine_guid()
+    if machine_guid:
+        identifiers["machine_guid"] = machine_guid
+    normalized = _normalize_identifiers(identifiers)
+    if not normalized:
+        raise MachineFingerprintError("O Windows não forneceu nenhum identificador de máquina utilizável.")
+    return normalized
+
+
+def fingerprint_from_identifiers(identifiers: Mapping[str, str]) -> str:
+    """Produz um hash determinístico sem expor os identificadores originais."""
+    normalized = _normalize_identifiers(identifiers)
+    if not normalized:
+        raise MachineFingerprintError("Nenhum identificador de máquina utilizável foi informado.")
+    serialized = json.dumps(normalized, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return "HW1-" + base64.b32encode(hashlib.sha256(serialized).digest()).rstrip(b"=").decode("ascii")
+
+
+def _read_cim_identifiers() -> dict[str, str]:
+    script = "$ErrorActionPreference = 'Stop';" + \
+             "$board = Get-CimInstance -ClassName Win32_BaseBoard | Select-Object -First 1;" + \
+             "$system = Get-CimInstance -ClassName Win32_ComputerSystemProduct | Select-Object -First 1;" + \
+             "[PSCustomObject]@{baseboard_serial=$board.SerialNumber;system_uuid=$system.UUID} | ConvertTo-Json -Compress"
+    try:
+        process = subprocess.run(
+            ["powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=15,
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+        content = json.loads(process.stdout)
+    except (OSError, subprocess.SubprocessError, json.JSONDecodeError):
+        return {}
+    if not isinstance(content, dict):
+        return {}
+    return {str(key): str(value) for key, value in content.items() if value is not None}
+
+
+def _read_machine_guid() -> str:
+    try:
+        with winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE,
+            "SOFTWARE\\Microsoft\\Cryptography",
+            0,
+            winreg.KEY_READ | winreg.KEY_WOW64_64KEY,
+        ) as registry_key:
+            value, _value_type = winreg.QueryValueEx(registry_key, "MachineGuid")
+    except OSError:
+        return ""
+    return str(value)
+
+
+def _normalize_identifiers(identifiers: Mapping[str, str]) -> dict[str, str]:
+    normalized: dict[str, str] = {}
+    for raw_name, raw_value in identifiers.items():
+        name = re.sub(r"[^a-z0-9_]+", "_", str(raw_name).strip().casefold()).strip("_")
+        value = " ".join(str(raw_value).strip().casefold().split())
+        compact = re.sub(r"[^a-z0-9]", "", value)
+        repeated_placeholder = len(compact) >= 8 and len(set(compact)) == 1
+        if name and value and value not in _INVALID_VALUES and not repeated_placeholder:
+            normalized[name] = value
+    return dict(sorted(normalized.items()))

cuboutils-0.1.0/license/public_key.py

@@ -0,0 +1,4 @@
+PUBLIC_KEY_PEM = b"""-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAfmREHLhaOuIc4crBxPi4RvWrEedHl4yNid1l9RvRkds=
+-----END PUBLIC KEY-----
+"""

cuboutils-0.1.0/license/storage.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import ctypes
+from pathlib import Path
+from uuid import UUID
+
+
+class _GUID(ctypes.Structure):
+    _fields_ = [
+        ("data1", ctypes.c_uint32),
+        ("data2", ctypes.c_uint16),
+        ("data3", ctypes.c_uint16),
+        ("data4", ctypes.c_ubyte * 8),
+    ]
+
+
+_PROGRAM_DATA_FOLDER_ID = _GUID.from_buffer_copy(UUID("62ab5d82-fdc1-4dc3-a9dd-070d1d495d97").bytes_le)
+_FILE_ATTRIBUTE_HIDDEN = 0x02
+_FILE_ATTRIBUTE_SYSTEM = 0x04
+_INVALID_FILE_ATTRIBUTES = 0xFFFFFFFF
+
+
+def program_data_path() -> Path:
+    """Consulta o caminho real do ProgramData pela API de pastas conhecidas do Windows."""
+    shell32 = ctypes.WinDLL("shell32", use_last_error=True)
+    ole32 = ctypes.WinDLL("ole32", use_last_error=True)
+    get_known_folder_path = shell32.SHGetKnownFolderPath
+    get_known_folder_path.argtypes = [ctypes.POINTER(_GUID), ctypes.c_uint32, ctypes.c_void_p, ctypes.POINTER(ctypes.c_wchar_p)]
+    get_known_folder_path.restype = ctypes.c_long
+    ole32.CoTaskMemFree.argtypes = [ctypes.c_void_p]
+
+    path_pointer = ctypes.c_wchar_p()
+    result = get_known_folder_path(ctypes.byref(_PROGRAM_DATA_FOLDER_ID), 0, None, ctypes.byref(path_pointer))
+    if result != 0:
+        raise OSError(f"O Windows não informou o caminho do ProgramData: HRESULT 0x{result & 0xFFFFFFFF:08X}.")
+    try:
+        return Path(path_pointer.value)
+    finally:
+        ole32.CoTaskMemFree(path_pointer)
+
+
+LICENSE_PATH = program_data_path() / "CUBO" / "-"
+
+
+def load_license() -> bytes:
+    """Lê a licença instalada no caminho padrão do CUBO."""
+    return LICENSE_PATH.read_bytes()
+
+
+def save_license(blob: bytes) -> Path:
+    """Grava o blob recebido e o oculta como arquivo de sistema no Windows."""
+    if not isinstance(blob, bytes) or not blob:
+        raise ValueError("A licença deve conter bytes.")
+    LICENSE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    LICENSE_PATH.write_bytes(blob)
+    _set_hidden_and_system(LICENSE_PATH)
+    return LICENSE_PATH
+
+
+def _set_hidden_and_system(path: Path) -> None:
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    get_attributes = kernel32.GetFileAttributesW
+    get_attributes.argtypes = [ctypes.c_wchar_p]
+    get_attributes.restype = ctypes.c_uint32
+    set_attributes = kernel32.SetFileAttributesW
+    set_attributes.argtypes = [ctypes.c_wchar_p, ctypes.c_uint32]
+    set_attributes.restype = ctypes.c_int
+
+    absolute_path = str(path.resolve())
+    attributes = get_attributes(absolute_path)
+    if attributes == _INVALID_FILE_ATTRIBUTES:
+        raise ctypes.WinError(ctypes.get_last_error())
+    if not set_attributes(absolute_path, attributes | _FILE_ATTRIBUTE_HIDDEN | _FILE_ATTRIBUTE_SYSTEM):
+        raise ctypes.WinError(ctypes.get_last_error())

cuboutils-0.1.0/license/verifier.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import hmac
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import StrEnum
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from license.contract import LicenseClaims, LicenseContractError, LicenseEnvelope
+from license.machine import MachineFingerprintError, current_machine_id
+from license.public_key import PUBLIC_KEY_PEM
+from license.storage import load_license
+
+
+class LicenseStatus(StrEnum):
+    valid = "valid"
+    license_not_found = "license_not_found"
+    license_read_error = "license_read_error"
+    machine_error = "machine_error"
+    malformed = "malformed"
+    invalid_public_key = "invalid_public_key"
+    invalid_signature = "invalid_signature"
+    wrong_machine = "wrong_machine"
+    wrong_product = "wrong_product"
+    expired = "expired"
+
+
+@dataclass(frozen=True, slots=True)
+class LicenseVerification:
+    valid: bool
+    status: LicenseStatus
+    message: str
+    claims: LicenseClaims | None = None
+
+
+def verify_installed_license(product: str, now: datetime | None = None) -> LicenseVerification:
+    """Valida a licença instalada sem expor detalhes de armazenamento ou hardware ao programa."""
+    try:
+        blob = load_license()
+    except FileNotFoundError:
+        return _failure(LicenseStatus.license_not_found, "A licença não está instalada.")
+    except OSError as error:
+        return _failure(LicenseStatus.license_read_error, f"Não foi possível ler a licença: {error}.")
+    try:
+        machine_id = current_machine_id()
+    except MachineFingerprintError as error:
+        return _failure(LicenseStatus.machine_error, str(error))
+    return verify_license(blob, machine_id, product, now)
+
+
+def verify_license(
+    blob: bytes,
+    expected_machine_id: str,
+    product: str,
+    now: datetime | None = None,
+) -> LicenseVerification:
+    """Valida assinatura, computador, produto e vencimento."""
+    try:
+        envelope = LicenseEnvelope.from_blob(blob)
+    except LicenseContractError as error:
+        return _failure(LicenseStatus.malformed, str(error))
+    try:
+        public_key = serialization.load_pem_public_key(PUBLIC_KEY_PEM)
+    except (TypeError, ValueError) as error:
+        return _failure(LicenseStatus.invalid_public_key, f"Não foi possível abrir a chave pública: {error}.")
+    if not isinstance(public_key, Ed25519PublicKey):
+        return _failure(LicenseStatus.invalid_public_key, "A chave pública não é Ed25519.")
+    try:
+        public_key.verify(envelope.signature, envelope.payload)
+    except InvalidSignature:
+        return _failure(LicenseStatus.invalid_signature, "A assinatura da licença é inválida.")
+    try:
+        claims = LicenseClaims.from_payload_bytes(envelope.payload)
+    except LicenseContractError as error:
+        return _failure(LicenseStatus.malformed, str(error))
+    if not hmac.compare_digest(claims.machine_id, expected_machine_id):
+        return _failure(LicenseStatus.wrong_machine, "A licença pertence a outro computador.", claims)
+    if not any(hmac.compare_digest(licensed_product, product) for licensed_product in claims.products):
+        return _failure(LicenseStatus.wrong_product, f"A licença não libera o produto {product}.", claims)
+    current_time = datetime.now(timezone.utc) if now is None else now
+    if current_time.tzinfo is None or current_time.utcoffset() is None:
+        raise ValueError("now deve possuir fuso horário.")
+    if current_time.astimezone(timezone.utc) > claims.expires_at:
+        return _failure(LicenseStatus.expired, "A licença está vencida.", claims)
+    return LicenseVerification(True, LicenseStatus.valid, "Licença válida.", claims)
+
+
+def _failure(status: LicenseStatus, message: str, claims: LicenseClaims | None = None) -> LicenseVerification:
+    return LicenseVerification(False, status, message, claims)

cuboutils-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cuboutils-0.1.0/setup.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from setuptools import find_packages, setup
+
+
+readme = (Path(__file__).parent / "README.md").read_text(encoding="utf-8")
+
+
+setup(
+    name="cuboutils",
+    version="0.1.0",
+    author="Leonardo Pires Batista",
+    author_email="leonardopbatista98@gmail.com",
+    description="Utilitários compartilhados pelos produtos CUBO",
+    long_description=readme,
+    long_description_content_type="text/markdown",
+    keywords="cubo licença atualização",
+    packages=find_packages(exclude=("tests", "tests.*")),
+    python_requires=">=3.12",
+    install_requires=["cryptography==50.0.1"],
+)

cuboutils-0.1.0/tests/test_license_flow.py

@@ -0,0 +1,91 @@
+import base64
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest import TestCase, skipUnless
+from unittest.mock import patch
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from license import LicenseClaims, LicenseStatus, issue_license, verify_installed_license, verify_license
+
+
+MACHINE_ID = "HW1-" + "A" * 52
+OTHER_MACHINE_ID = "HW1-" + "B" * 52
+PRIVATE_KEY_PATH = Path(__file__).resolve().parents[1] / "private-key.pem"
+
+
+def _instant(value: str) -> datetime:
+    return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+
+
+class LicenseFlowTests(TestCase):
+    def setUp(self) -> None:
+        private_key = Ed25519PrivateKey.generate()
+        private_key_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        public_key_pem = private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        public_key_patch = patch("license.verifier.PUBLIC_KEY_PEM", public_key_pem)
+        public_key_patch.start()
+        self.addCleanup(public_key_patch.stop)
+        self.claims = LicenseClaims(MACHINE_ID, ("TQSVigas", "OutroProduto"), _instant("2027-09-04T23:59:59Z"))
+        self.blob = issue_license(self.claims, private_key_pem)
+
+    def test_issued_license_is_accepted_by_verifier(self) -> None:
+        first = verify_license(self.blob, MACHINE_ID, "TQSVigas", _instant("2026-09-20T12:00:00Z"))
+        second = verify_license(self.blob, MACHINE_ID, "OutroProduto", _instant("2026-09-20T12:00:00Z"))
+
+        self.assertTrue(first.valid)
+        self.assertTrue(second.valid)
+        self.assertEqual(first.claims.products, ("OutroProduto", "TQSVigas"))
+
+    def test_consumer_validates_the_installed_license_with_one_call(self) -> None:
+        with patch("license.verifier.load_license", return_value=self.blob), \
+             patch("license.verifier.current_machine_id", return_value=MACHINE_ID):
+            result = verify_installed_license("TQSVigas", _instant("2026-09-20T12:00:00Z"))
+
+        self.assertTrue(result.valid)
+
+    def test_reports_when_license_is_not_installed(self) -> None:
+        with patch("license.verifier.load_license", side_effect=FileNotFoundError):
+            result = verify_installed_license("TQSVigas")
+
+        self.assertEqual(result.status, LicenseStatus.license_not_found)
+
+    def test_rejects_tampered_license(self) -> None:
+        document = json.loads(self.blob)
+        payload = json.loads(base64.urlsafe_b64decode(document["payload"] + "=" * (-len(document["payload"]) % 4)))
+        payload["products"] = ["ProdutoAdulterado"]
+        changed = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+        document["payload"] = base64.urlsafe_b64encode(changed).rstrip(b"=").decode()
+
+        result = verify_license(json.dumps(document).encode(), MACHINE_ID, "ProdutoAdulterado", _instant("2026-09-20T12:00:00Z"))
+
+        self.assertEqual(result.status, LicenseStatus.invalid_signature)
+
+    def test_rejects_wrong_machine_product_and_expiration(self) -> None:
+        wrong_machine = verify_license(self.blob, OTHER_MACHINE_ID, "TQSVigas", _instant("2026-09-20T12:00:00Z"))
+        wrong_product = verify_license(self.blob, MACHINE_ID, "ProdutoSemLicenca", _instant("2026-09-20T12:00:00Z"))
+        expired = verify_license(self.blob, MACHINE_ID, "TQSVigas", _instant("2027-09-05T12:00:00Z"))
+
+        self.assertEqual(wrong_machine.status, LicenseStatus.wrong_machine)
+        self.assertEqual(wrong_product.status, LicenseStatus.wrong_product)
+        self.assertEqual(expired.status, LicenseStatus.expired)
+
+
+@skipUnless(PRIVATE_KEY_PATH.is_file(), "A chave privada local do protótipo não está disponível.")
+class PrototypeKeyPairTests(TestCase):
+    def test_repository_private_key_matches_the_embedded_public_key(self) -> None:
+        claims = LicenseClaims(MACHINE_ID, ("TQSVigas",), _instant("2027-09-04T23:59:59Z"))
+
+        blob = issue_license(claims, PRIVATE_KEY_PATH.read_bytes())
+        result = verify_license(blob, MACHINE_ID, "TQSVigas", _instant("2026-09-20T12:00:00Z"))
+
+        self.assertTrue(result.valid)

cuboutils-0.1.0/tests/test_machine.py

@@ -0,0 +1,24 @@
+from unittest import TestCase
+
+from license import current_machine_id
+from license.machine import MachineFingerprintError, fingerprint_from_identifiers
+
+
+class MachineFingerprintTests(TestCase):
+    def test_is_deterministic_and_hides_source_values(self) -> None:
+        first = fingerprint_from_identifiers({"system_uuid": " ABC-123 ", "baseboard_serial": "Board-456"})
+        second = fingerprint_from_identifiers({"baseboard_serial": "board-456", "system_uuid": "abc-123"})
+
+        self.assertEqual(first, second)
+        self.assertRegex(first, r"^HW1-[A-Z2-7]{52}$")
+        self.assertNotIn("ABC", first)
+        self.assertNotIn("456", first)
+
+    def test_package_exports_the_machine_code(self) -> None:
+        from license.machine import current_machine_id as implementation
+
+        self.assertIs(current_machine_id, implementation)
+
+    def test_rejects_placeholder_identifiers(self) -> None:
+        with self.assertRaises(MachineFingerprintError):
+            fingerprint_from_identifiers({"system_uuid": "00000000-0000-0000-0000-000000000000", "serial": "FFFFFFFF"})

cuboutils-0.1.0/tests/test_storage.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+from unittest import TestCase
+from unittest.mock import patch
+
+from license import save_license
+from license.storage import LICENSE_PATH
+
+
+class LicenseStorageTests(TestCase):
+    def test_uses_the_expected_path(self) -> None:
+        self.assertEqual(LICENSE_PATH.name, "-")
+        self.assertEqual(LICENSE_PATH.parent.name, "CUBO")
+
+    def test_saves_blob_and_applies_windows_attributes(self) -> None:
+        path = Path(r"C:\ProgramData\CUBO\-")
+        with patch("license.storage.LICENSE_PATH", path), patch.object(Path, "mkdir") as make_directory, \
+             patch.object(Path, "write_bytes") as write_bytes, patch("license.storage._set_hidden_and_system") as set_attributes:
+            saved_path = save_license(b"licenca")
+
+        self.assertEqual(saved_path, path)
+        make_directory.assert_called_once_with(parents=True, exist_ok=True)
+        write_bytes.assert_called_once_with(b"licenca")
+        set_attributes.assert_called_once_with(path)

cuboutils-0.1.0/tests/test_update_checker.py

@@ -0,0 +1,56 @@
+import json
+from unittest import TestCase
+from unittest.mock import MagicMock, patch
+
+from update_checker import UpdateCheckError, is_latest_version
+
+
+class UpdateCheckerTests(TestCase):
+    def test_reports_the_latest_version(self) -> None:
+        response = self._response({"TQSVigas": "v2027.2.0", "TQSFormas": "v2027.1.0"})
+
+        with patch("update_checker.checker.urlopen", return_value=response) as open_endpoint:
+            result = is_latest_version("https://updates.example.com/versions.json", "TQSVigas", "2027.2")
+
+        self.assertTrue(result)
+        request = open_endpoint.call_args.args[0]
+        self.assertEqual(request.full_url, "https://updates.example.com/versions.json")
+
+    def test_reports_an_outdated_version(self) -> None:
+        response = self._response({"TQSVigas": "2027.2.0"})
+
+        with patch("update_checker.checker.urlopen", return_value=response):
+            result = is_latest_version("https://updates.example.com/versions.json", "TQSVigas", "2027.1.9")
+
+        self.assertFalse(result)
+
+    def test_accepts_a_version_newer_than_the_published_version(self) -> None:
+        response = self._response({"TQSVigas": "2027.2.0"})
+
+        with patch("update_checker.checker.urlopen", return_value=response):
+            result = is_latest_version("https://updates.example.com/versions.json", "TQSVigas", "2028.1.0")
+
+        self.assertTrue(result)
+
+    def test_rejects_an_insecure_endpoint(self) -> None:
+        with self.assertRaisesRegex(ValueError, "HTTPS"):
+            is_latest_version("http://updates.example.com/versions.json", "TQSVigas", "2027.2.0")
+
+    def test_reports_a_missing_product(self) -> None:
+        response = self._response({"OutroProduto": "2027.2.0"})
+
+        with patch("update_checker.checker.urlopen", return_value=response), self.assertRaises(UpdateCheckError):
+            is_latest_version("https://updates.example.com/versions.json", "TQSVigas", "2027.2.0")
+
+    def test_rejects_an_invalid_published_version(self) -> None:
+        response = self._response({"TQSVigas": "versão inválida"})
+
+        with patch("update_checker.checker.urlopen", return_value=response), self.assertRaises(UpdateCheckError):
+            is_latest_version("https://updates.example.com/versions.json", "TQSVigas", "2027.2.0")
+
+    @staticmethod
+    def _response(versions: dict[str, str]) -> MagicMock:
+        response = MagicMock()
+        response.read.return_value = json.dumps(versions).encode("utf-8")
+        response.__enter__.return_value = response
+        return response

cuboutils-0.1.0/update_checker/__init__.py

@@ -0,0 +1,5 @@
+"""Consulta a versão mais recente dos produtos CUBO."""
+
+from update_checker.checker import UpdateCheckError, is_latest_version
+
+__all__ = ["UpdateCheckError", "is_latest_version"]

cuboutils-0.1.0/update_checker/checker.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+import re
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import Request, urlopen
+
+
+_MAX_RESPONSE_SIZE = 4 * 1024
+_VERSION_PATTERN = re.compile(r"v?\d+(?:\.\d+)*")
+
+
+class UpdateCheckError(RuntimeError):
+    """Indica que não foi possível verificar a versão mais recente."""
+
+
+def is_latest_version(endpoint: str, product: str, version: str, timeout: float = 5.0) -> bool:
+    """Informa se a versão instalada é igual ou posterior à versão publicada."""
+    if not isinstance(product, str) or not product:
+        raise ValueError("product deve ser uma string não vazia.")
+    current_version = _parse_version(version)
+    _validate_endpoint(endpoint)
+    request = Request(endpoint, headers={"Accept": "application/json"})
+
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            content = response.read(_MAX_RESPONSE_SIZE + 1)
+    except (HTTPError, URLError, OSError) as error:
+        raise UpdateCheckError(f"Não foi possível consultar a versão de {product}.") from error
+
+    if len(content) > _MAX_RESPONSE_SIZE:
+        raise UpdateCheckError("A resposta do servidor excede o tamanho permitido.")
+    try:
+        document = json.loads(content.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise UpdateCheckError("O servidor não retornou um JSON UTF-8 válido.") from error
+
+    if not isinstance(document, dict):
+        raise UpdateCheckError("A resposta do servidor deve ser um objeto JSON.")
+    if product not in document:
+        raise UpdateCheckError(f"O produto {product} não foi encontrado na resposta do servidor.")
+    latest_version = document[product]
+    if not isinstance(latest_version, str):
+        raise UpdateCheckError(f"O servidor não retornou uma versão válida para {product}.")
+    try:
+        published_version = _parse_version(latest_version)
+    except ValueError as error:
+        raise UpdateCheckError("O servidor retornou uma versão inválida.") from error
+
+    return current_version >= published_version
+
+
+def _validate_endpoint(endpoint: str) -> None:
+    if not isinstance(endpoint, str):
+        raise TypeError("endpoint deve ser uma string.")
+    parts = urlsplit(endpoint)
+    if parts.scheme.casefold() != "https" or not parts.netloc:
+        raise ValueError("endpoint deve ser uma URL HTTPS válida.")
+
+
+def _parse_version(value: str) -> tuple[int, ...]:
+    if not isinstance(value, str) or not _VERSION_PATTERN.fullmatch(value):
+        raise ValueError("A versão deve conter números separados por pontos e pode começar com v.")
+    parts = [int(part) for part in value.removeprefix("v").split(".")]
+    while len(parts) > 1 and parts[-1] == 0:
+        parts.pop()
+    return tuple(parts)