Hiizap Desktop SDK 1.3.0

SDK proprietário para Node.js >=22 e processo principal do Electron com esse runtime. Valida licenças na API HTTPS Hiizap, verifica certificados Ed25519, mantém tolerância offline assinada e baixa atualizações com tamanho, SHA-256 e manifesto Ed25519 verificados. Não executa nem instala binários.

Instalação e uso

Instale com npm install --save-exact @hiizap/[email protected]. Documentação: https://doc.hiizap.com. Leia KEYRING-MIGRATION.md para o contrato de assinatura, exemplos, erros e transição de assinantes. O pacote inclui JavaScript CommonJS, declarações TypeScript e a chave pública do servidor; importa tanto com require quanto com import.

import { HiizapDesktopSDK, HiizapSDKError } from '@hiizap/desktop-sdk';
import path from 'node:path';

// No Electron: use app.getPath('userData') em uma pasta exclusiva deste aplicativo.
const sdk = new HiizapDesktopSDK({
  productSlug: 'meu-produto',
  currentVersion: '1.0.0',
  platform: 'windows-x64',
  cacheFilePath: path.join(diretorioPrivadoDoAplicativo, 'hiizap', 'license.cache'),
});

try {
  const { source, certificate } = await sdk.validateLicense(chaveInformadaPeloComprador);
  if (!certificate.valid) {
    bloquearRecursosLicenciados(certificate.error);
  } else {
    habilitarRecursosLicenciados({ offline: source === 'offline' });
    if (source === 'online' && certificate.update_available) {
      mostrarTextoDaAtualizacao(certificate.changelog_html ?? '');
      // Após consentimento no aplicativo, escolha um caminho novo absoluto.
      const arquivo = await sdk.downloadUpdate(certificate, caminhoNovoDoInstalador);
      // Aplicativo decide instalação, assinatura nativa e elevação quando necessárias.
    }
  }
} catch (error) {
  bloquearRecursosLicenciados(error instanceof HiizapSDKError ? error.code : 'SDK_ERROR');
}

As funções de interface no exemplo pertencem ao aplicativo integrador. Mostre changelog como TEXTO; o campo changelog_html não foi sanitizado para HTML. Não envie licenças, certificados completos ou URLs de download a logs/telemetria. Guarde a licença no cofre do sistema; ela precisa ser fornecida novamente para abrir o cache. Qualquer exceção deve bloquear acesso. Valide ao iniciar e periodicamente durante uso prolongado; uma chamada não protege uma sessão indefinida.

Contrato

• validateLicense(key): Promise<ValidationResult> devolve { source, certificate }. certificate.valid === false é uma negativa assinada. Erros lançam HiizapSDKError com código sem credenciais.
• downloadUpdate(certificate, absoluteDestination): Promise<string> aceita apenas o último certificado online retornado por esta instância. Baixa em streaming para .partial, confere manifesto/plataforma/tamanho/hash e publica por hard link atômico sem sobrescrever. O diretório deve existir, ser privado e permitir hard links no mesmo filesystem. FAT, compartilhamentos ou políticas que proíbem links podem falhar com DOWNLOAD_FAILED. Uma falha exige nova validação para obter outra URL de uso único.
• verifyUpdateBinary(absolutePath, certificate): Promise<boolean> verifica um arquivo contra manifesto assinado e hash sem carregar todo o arquivo na memória. Comprova integridade/autoria do release, não validade atual da licença.
• getHardwareId(): string expõe somente SHA-256 do identificador, nunca seu valor original.

O construtor posicional (slug, version, platform, cachePath) continua disponível. O retorno de validação agora envolve certificate; verifyUpdateBinary agora é assíncrono e recebe o certificado completo. O esboço anterior não era um pacote operacional. Caches e HWIDs anteriores não são migrados: exige primeira validação online após atualização desse esboço.

Rede, cache e identidade

API padrão: https://api.hiizap.com/v1/client. TLS permanece validado pelo Node; redirects são recusados; User-Agent explícito evita a incompatibilidade observada com clientes genéricos na Cloudflare. JSON limitado a 64 KiB, validação 15 s, download 5 min e tamanho máximo 1 GiB. requestTimeoutMs, downloadTimeoutMs e maxDownloadBytes permitem limites positivos explícitos. Sem retry automático ou fallback em HTTP, inclusive 429/5xx.

Somente falhas transitórias reconhecidas de conexão/DNS/timeout permitem cache. Certificado vinculado ao produto, hash da licença, dispositivo e nonce; prazo offline assinado nunca é prorrogado. Negativas assinadas substituem autorizações antigas. Offline remove a capacidade de baixar. AES-256-GCM usa IV aleatório e chave derivada da licença de 256 bits, produto e dispositivo. Escrita atômica, fsync e modo0600; pasta nova0700 em Unix. Use uma única instância/processo por caminho; concorrência entre processos exige coordenação pelo integrador.

Windows consulta MachineGuid com reg.exe sem shell e prazo de5s; Linux usa machine-id; macOS usa IOPlatformUUID via ioreg sem pipeline shell. São identidades de instalação/plataforma: reinstalação pode alterar e clonagem pode repetir. Se indisponíveis, falha com HARDWARE_ID_UNAVAILABLE, sem inventar ID volátil. hardwareIdProvider permite adaptador confiável retornando64 caracteres hexadecimais minúsculos. Não permita que conteúdo remoto escolha ID/opções.

apiUrl, publicKeyPem, fetch e now servem para outro deployment/adaptadores confiáveis/testes. apiUrl exige HTTPS e caminho do protocolo. Nova chave pública exige distribuição confiável de nova versão; a API não pode fornecer uma chave para aceitar sua própria assinatura.

Desenvolvimento

npm ci --ignore-scripts
npm test
npm audit
npm pack

Windows e Linux recebem testes nativos nesta fase. macOS requer execução em hardware macOS. Não é um SDK Rust/Tauri nativo: Tauri precisaria de processo Node separado ou implementação específica. A integração e os instaladores do seu aplicativo exigem testes próprios. Consulte SECURITY.md e https://doc.hiizap.com/guias/testes/ para limites e critérios de validação.

Identificador técnico do produto — contrato v1

productSlug/product_slug é uma string ASCII exata de 1 a 80 caracteres: letras a–z, números e segmentos separados por um único hífen. Exemplos válidos: a, 0, 01, meu-produto. São inválidos: aa--bb, aa-, _produto, maiúsculas, espaços, Unicode e valores de outro tipo. Não há trim, conversão de número para string, aliases ou troca automática de identidade. Copie a identidade fornecida pelo responsável pelo produto; não a deduza da pasta ou do nome comercial.

A versão 1.0.1 corrige a divergência com a API. Identidades válidas existentes mantêm vínculos, opções/cache e assinatura. Configuração inválida falha antes de chamar a API: INVALID_OPTIONS no Desktop ou HIIZAP_INVALID_CONFIG no PHP. Não troque a chave da licença, a chave pública, TLS ou o produto por tentativa e erro.

Em WordPress, produtos que embutem a mesma classe v1 devem coordenar a atualização: a primeira cópia carregada fornece a implementação. Misturar 1.0.0 e 1.0.1 pode manter a regra antiga naquela requisição; esta correção não remove a guarda de classe nem cria outro namespace de cache.

Diagnóstico de atualização independente — contrato v1

A API pode retornar um certificado assinado com valid=true, update_available=false e update_error quando a consulta, o link ou os metadados de atualização não estiverem disponíveis. Os códigos são UPDATE_METADATA_TOO_LARGE, UPDATE_METADATA_INVALID, UPDATE_LOOKUP_FAILED e UPDATE_LINK_UNAVAILABLE. Esse campo é diagnóstico; a autorização continua dependendo de valid e de todas as verificações do SDK. Sem atualização disponível não há URL autorizada para baixar.

O envelope HTTP continua limitado a 65.536 bytes. Não aumente o teto para contornar notas extensas e não decodifique o payload para autorizar sem assinatura. O backend verifica orçamento da publicação e a resposta exata em tempo de validação. Falha da validação da licença ou de assinatura continua bloqueante. Esta correção não separa ainda todos os limites de binário/manifesto do resultado da licença (F03).

Autorização e elegibilidade de atualização

A biblioteca verifica primeiro o envelope original, assinatura, identidade e validade da licença. Depois deriva a elegibilidade do update. Um manifesto incompatível retorna licença válida, update_available=false e update_error, sem URL ou campos de instalação. Diagnósticos locais são decisões da biblioteca sobre o envelope verificado, não novos campos assinados pelo servidor. O cache continua guardando o envelope original e repetindo as verificações; nunca assine ou reutilize o objeto derivado como prova criptográfica.

Falha de assinatura do envelope, vínculo incorreto, revogação, expiração e erros de validação continuam bloqueantes. Apenas erros da atualização, depois da licença verificada, deixam a versão instalada autorizada. Falha no download não autoriza instalar um pacote incompleto; preserve o estado da versão atual e informe erro de atualização.

UPDATE_SIZE_LIMIT, UPDATE_PLATFORM_UNSUPPORTED, UPDATE_VERSION_INELIGIBLE, UPDATE_REQUIREMENTS_UNSUPPORTED e UPDATE_MANIFEST_REJECTED distinguem a recusa. Requisitos legados min_runtime_version não vazios impedem o update até haver suporte ao contrato estruturado. Essa retenção é exclusiva do campo legado; o contrato estruturado usa schema 1 e manifesto V2. Nenhuma mudança de identidade, cache, licença ou limite de ativações deve ser usada para contornar a recusa.

Versões — hiizap.semver.v1

Use a versão real instalada, canônica e sem normalização: MAJOR.MINOR.PATCH, pré-lançamento e build opcionais. O protocolo limita o texto a 30 caracteres ASCII e cada número do core a 9007199254740991. Identificadores numéricos de pré-lançamento são comparados por dígitos, sem conversão para float; não podem ter zeros iniciais. Build pode conter zeros iniciais e não muda a precedência.

1.0.0-alpha.1 é válido; 1.0.0-01, v1.0.0, espaços, intervalos e identificadores vazios são inválidos. Não remova build/prefixo ou troque versão silenciosamente: a assinatura do manifesto vincula a string exata publicada. Uma versão inválida na configuração é recusada; uma versão inválida de update não autoriza instalação e preserva uma licença que tenha passado na validação independente. As cópias embutidas PHP precisam ser coordenadas: a primeira classe v1 carregada mantém a implementação.

Compatibilidade de atualização — schema 1

A biblioteca anuncia compatibility_version=1 e informa ambiente estruturado: runtimes, os e arch. A string runtime_version continua diagnóstico, não regra. Node/Electron vêm do processo confiável; PHP/WordPress vêm das APIs nativas. WordPress estável X.Y vira X.Y.0 apenas na informação de runtime; isso não normaliza versão de produto. Ambiente desconhecido não autoriza atualização restrita.

Releases restritas usam RELEASE_V2 e SHA-256 de uma tupla canônica de requisitos; a assinatura liga produto, versão, plataforma, hash/tamanho do arquivo e digest de requisitos. Remover requisitos ou mudar a política sem nova assinatura impede a instalação. O SDK confere a política localmente e novamente no download. A licença é validada independentemente e permanece bloqueante se inválida.

A API escolhe a release estável compatível mais recente, podendo oferecer uma anterior à mais nova. Clientes antigos recebem apenas V1 sem requisitos estruturados; requisitos legados min_runtime_version continuam retidos sem interpretação. Downloads comprados têm autoridade comercial própria: esta política descreve OTA pelo SDK, não atesta qualquer ambiente onde um comprador instale manualmente.

O ambiente informado não é atestação de hardware nem autorização. Administrador ou processo comprometido pode alterar o cliente. O adaptador environmentProvider do Desktop é exclusivo do host confiável/testes; nunca o alimente com parâmetros de renderer, navegador ou usuário. SO/arquiteturas expressos no contrato não significam execução real validada em todos eles. Requisitos declarados não substituem testes do binário e do instalador.

Negociação de confiança em1.2

As capacidades são declaradas a partir das raízes locais; o servidor preserva o assinante compatível para versões anteriores. Consulte KEYRING-MIGRATION.md antes de remover confiança, trocar o perfil ou incorporar cópias simultâneas. Nenhuma chave privada é distribuída pelo SDK.

Diagnóstico desde1.3

Códigos anteriores preservados; categoria, status HTTP e request ID sanitizado disponíveis nos erros. Leia DIAGNOSTICS.md e o exemplo na pasta examples. Sem retry novo ou mudança na política de autorização.