engine-kit 0.0.0-stage → 0.2.0-bootstrap.0

package/kit/sign.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// engine-kit/sign.mjs — assina um artefato de motor e PROVA a assinatura na hora.
+//
+//   node kit/sign.mjs <caminho-do-asset> --engine <motor>
+//   node kit/sign.mjs <caminho-do-asset> --key <caminho-da-chave-privada>
+//
+// Gera, ao lado do asset:
+//   <asset>.sig     — assinatura Ed25519 crua (64 bytes) do SHA-256 do asset
+//   <asset>.sha256  — sidecar de integridade (o kit já exigia; gerar aqui evita esquecer)
+//
+// E, antes de sair, prova o que acabou de fazer: a assinatura valida contra a pública derivada
+// E recusa uma cópia adulterada. Um `.sig` que só é testado no consumidor é um `.sig` que você
+// descobre que está quebrado tarde demais.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { signBlob, verifyBlob, publicKeyHexFromPrivateHex } from "./signature.mjs";
+import { keyPathFor } from "./keystore.mjs";
+
+const die = (msg) => { console.error(`FALHOU: ${msg}`); process.exit(1); };
+
+function parseArgs(argv) {
+  const out = { asset: null, engine: null, key: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--engine") { out.engine = argv[++i]; }
+    else if (argv[i] === "--key") { out.key = argv[++i]; }
+    else if (!out.asset) { out.asset = argv[i]; }
+  }
+  return out;
+}
+
+const { asset, engine, key } = parseArgs(process.argv.slice(2));
+if (!asset) { die("uso: node kit/sign.mjs <asset> (--engine <motor> | --key <caminho>)"); }
+if (!existsSync(asset)) { die(`asset não encontrado: ${asset}`); }
+
+const keyPath = key ?? (engine ? keyPathFor(engine) : null);
+if (!keyPath) { die("informe --engine <motor> ou --key <caminho da chave privada>"); }
+if (!existsSync(keyPath)) {
+  die(`chave privada ausente: ${keyPath}\n       gere com: node kit/gen-key.mjs ${engine ?? "<motor>"}`);
+}
+
+const privateKeyHex = readFileSync(keyPath, "utf8").trim();
+let publicKeyHex;
+try {
+  publicKeyHex = publicKeyHexFromPrivateHex(privateKeyHex);
+} catch (e) {
+  die(`chave privada ilegível em ${keyPath}: ${e.message}`);
+}
+
+const blob = readFileSync(asset);
+const sig = signBlob(blob, privateKeyHex);
+
+// PROVA (as duas metades: aceita o legítimo, recusa o adulterado).
+if (!verifyBlob(blob, sig, publicKeyHex).ok) { die("a assinatura recém-gerada NÃO validou — não publique"); }
+if (verifyBlob(Buffer.concat([blob, Buffer.from("x")]), sig, publicKeyHex).ok) {
+  die("a verificação ACEITOU um artefato adulterado — não publique");
+}
+
+const sha256 = createHash("sha256").update(blob).digest("hex");
+writeFileSync(`${asset}.sig`, sig);
+writeFileSync(`${asset}.sha256`, `${sha256}  ${basename(asset)}\n`, "utf8");
+
+console.log(`asset          : ${asset} (${blob.length} bytes)`);
+console.log(`sha256         : ${sha256}`);
+console.log(`assinatura     : ${asset}.sig (${sig.length} bytes crus)`);
+console.log(`chave pública  : ${publicKeyHex}`);
+console.log("prova          : assinatura VALIDA e artefato adulterado é RECUSADO");

package/kit/signature.mjs

@@ -0,0 +1,106 @@
+// engine-kit/signature.mjs — AUTENTICIDADE: assinatura Ed25519 dos artefatos de motor.
+//
+// Uma implementação, N motores. O SHA256 do kit prova INTEGRIDADE (não corrompeu no caminho);
+// a assinatura prova AUTENTICIDADE (veio de quem tem a chave privada). Sem ela, quem controlar
+// o release serve um artefato trocado e o sha256 sidecar bate — porque o atacante gera os dois.
+//
+// CONTRATO — `ed25519-sha256-raw` (o mesmo que o vox-engine já pratica em produção, para que a
+// migração dele não exija reassinar nada):
+//   • hash-then-sign: assina-se o SHA-256 (32 bytes) do artefato, NÃO o artefato direto;
+//   • o `.sig` é a assinatura Ed25519 CRUA — 64 bytes binários, nunca base64;
+//   • a chave pública é 32 bytes em hex (64 chars), PINADA no manifest do registry;
+//   • a chave privada é 32 bytes em hex, LOCAL (~/.engine-signing/), e nunca entra em CI.
+//
+// Armadilhas do Node que este módulo encapsula (motivo de existir um módulo só para isto):
+//   • `crypto.createSign()/createVerify()` NÃO suportam Ed25519 — só a API estática
+//     `crypto.sign(null, ...)` / `crypto.verify(null, ...)`, com o 1º argumento OBRIGATORIAMENTE
+//     `null` (passar 'ed25519' ou 'sha256' quebra);
+//   • o Node não importa chave Ed25519 crua: exige DER. O envelope SPKI é um prefixo FIXO de
+//     12 bytes + os 32 bytes crus. O PKCS8 privado é um prefixo fixo de 16 bytes + 32 crus.
+//
+// Contrato do kit: NUNCA lança na verificação — devolve { ok:false, reason } para o caller
+// decidir (fail-loud em quem chama, não aqui). A assinatura (lado publisher) SIM lança: ali um
+// erro tem de estourar na cara de quem publica.
+import { createHash, createPublicKey, createPrivateKey, sign as edSign, verify as edVerify, generateKeyPairSync } from "node:crypto";
+/** Algoritmos que o kit sabe verificar. Desconhecido = ABORT, nunca aceite silencioso. */
+export const SUPPORTED_ALGORITHMS = ["ed25519-sha256-raw"];
+export const DEFAULT_ALGORITHM = "ed25519-sha256-raw";
+
+/** Envelope DER fixo de uma chave Ed25519 (RFC 8410): SPKI público e PKCS8 privado. */
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");   // 12 bytes + 32 crus
+const PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex"); // 16 bytes + 32 crus
+
+const RAW_KEY_BYTES = 32;
+export const SIGNATURE_BYTES = 64;
+
+const isHexKey = (s) => /^[0-9a-fA-F]{64}$/.test(String(s ?? ""));
+
+/** Converte a chave PÚBLICA hex (32 bytes) num KeyObject utilizável pelo `crypto.verify`. */
+export function publicKeyFromHex(hex) {
+  if (!isHexKey(hex)) {
+    throw new Error(`chave pública Ed25519 inválida: esperado 64 chars hex (32 bytes), veio ${String(hex ?? "").length}`);
+  }
+  const raw = Buffer.from(hex, "hex");
+  return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: "der", type: "spki" });
+}
+
+/** Converte a chave PRIVADA hex (32 bytes) num KeyObject utilizável pelo `crypto.sign`. */
+export function privateKeyFromHex(hex) {
+  if (!isHexKey(hex)) {
+    throw new Error(`chave privada Ed25519 inválida: esperado 64 chars hex (32 bytes), veio ${String(hex ?? "").length}`);
+  }
+  const raw = Buffer.from(hex, "hex");
+  return createPrivateKey({ key: Buffer.concat([PKCS8_PREFIX, raw]), format: "der", type: "pkcs8" });
+}
+
+/** Gera um par novo. Devolve as duas metades em hex cru (32 bytes cada). */
+export function generateKeyPairHex() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const pub = publicKey.export({ type: "spki", format: "der" }).subarray(SPKI_PREFIX.length);
+  const priv = privateKey.export({ type: "pkcs8", format: "der" }).subarray(PKCS8_PREFIX.length);
+  if (pub.length !== RAW_KEY_BYTES || priv.length !== RAW_KEY_BYTES) {
+    throw new Error(`envelope DER inesperado (pub=${pub.length}B, priv=${priv.length}B) — Node incompatível`);
+  }
+  return { publicKeyHex: pub.toString("hex"), privateKeyHex: priv.toString("hex") };
+}
+
+/** Deriva a chave PÚBLICA (hex cru) a partir da privada — para provar a assinatura aqui mesmo. */
+export function publicKeyHexFromPrivateHex(privateKeyHex) {
+  const pub = createPublicKey(privateKeyFromHex(privateKeyHex));
+  return pub.export({ type: "spki", format: "der" }).subarray(SPKI_PREFIX.length).toString("hex");
+}
+
+/** LADO PUBLISHER: assina o SHA-256 do artefato. Devolve os 64 bytes crus do `.sig`. LANÇA em erro. */
+export function signBlob(blob, privateKeyHex) {
+  const key = privateKeyFromHex(privateKeyHex);
+  const sig = edSign(null, createHash("sha256").update(blob).digest(), key);
+  if (sig.length !== SIGNATURE_BYTES) {
+    throw new Error(`assinatura com tamanho inesperado (${sig.length}B, esperado ${SIGNATURE_BYTES}B)`);
+  }
+  return sig;
+}
+
+/**
+ * LADO CONSUMIDOR: verifica a assinatura de um artefato. FAIL-CLOSED — qualquer dúvida é `false`.
+ * @returns {{ok:true} | {ok:false, reason:string}} nunca lança.
+ */
+export function verifyBlob(blob, signature, publicKeyHex, { algorithm = DEFAULT_ALGORITHM } = {}) {
+  if (!SUPPORTED_ALGORITHMS.includes(algorithm)) {
+    return { ok: false, reason: `algoritmo de assinatura desconhecido "${algorithm}" (suportados: ${SUPPORTED_ALGORITHMS.join(", ")}) → ABORT` };
+  }
+  if (!isHexKey(publicKeyHex)) {
+    return { ok: false, reason: "chave pública ausente/malformada no registry (esperado 64 chars hex) → ABORT" };
+  }
+  const sig = Buffer.isBuffer(signature) ? signature : Buffer.from(signature ?? []);
+  if (sig.length !== SIGNATURE_BYTES) {
+    return { ok: false, reason: `sidecar .sig com ${sig.length} bytes (esperado ${SIGNATURE_BYTES} crus, sem base64) → ABORT` };
+  }
+  try {
+    const key = publicKeyFromHex(publicKeyHex);
+    const digest = createHash("sha256").update(blob).digest();
+    if (edVerify(null, digest, key, sig)) { return { ok: true }; }
+    return { ok: false, reason: "assinatura Ed25519 NÃO confere — artefato não veio de quem detém a chave privada → ABORT" };
+  } catch (e) {
+    return { ok: false, reason: `verificação de assinatura falhou: ${e?.message || e} → ABORT` };
+  }
+}

package/kit/trust.mjs

@@ -0,0 +1,72 @@
+// engine-kit/trust.mjs — RAIZ DE CONFIANÇA local (fecha a circularidade do publicKey).
+//
+// O problema real: a `publicKey` que valida a assinatura vinha do MESMO `manifest.json` que o kit
+// baixa. Quem controla o repo troca o `.tgz`, o `.sig` **e** a chave — e o fail-closed aprova
+// tudo, porque as três coisas vêm da mesma origem. Integridade sem raiz de confiança externa é
+// uma tranca cuja chave está pendurada na porta.
+//
+// O que isto resolve (e o que NÃO resolve, dito na cara):
+//   • RESOLVE — troca de chave DEPOIS da primeira instalação (repo comprometido, release
+//     substituída, rollback com chave nova): a chave fica gravada localmente na primeira vez
+//     (TOFU) e qualquer divergência posterior é ABORT, não aviso.
+//   • RESOLVE — pin explícito: o consumidor pode passar a chave que ele confia (`trustedKeys`),
+//     e aí nem a primeira instalação depende do manifest. É o padrão do vox-engine (chave
+//     embutida no consumidor) trazido para cá, sem obrigar todo consumidor a adotá-lo.
+//   • NÃO RESOLVE — comprometimento ANTERIOR ao primeiro contato: se o repo já estava tomado na
+//     primeira instalação, o TOFU grava a chave do atacante. Só transparência pública (Sigstore/
+//     TUF) fecha isso, e essa é decisão de produto — está registrada, não esquecida.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+// Lido a CADA chamada, não no import: assim um teste (ou um consumidor com HOME próprio) pode
+// isolar a raiz de confiança sem depender da ordem de carregamento dos módulos. Foi a própria
+// suíte que expôs isto — o motor-fake do teste de assinatura gera chave nova a cada execução e
+// ficava preso na confiança da execução anterior.
+const trustDir = () => process.env.ENGINE_KIT_HOME || join(homedir(), ".engine-kit");
+const trustFile = () => join(trustDir(), "trust.json");
+
+function readTrust() {
+  try {
+    const v = JSON.parse(readFileSync(trustFile(), "utf8"));
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Confronta a chave que veio do registry com a raiz de confiança local.
+ * @returns {{ok:true, tofu:boolean} | {ok:false, reason:string}} nunca lança.
+ */
+export function checkTrust(engineName, publicKey, { trustedKeys } = {}) {
+  const pinned = trustedKeys?.[engineName];
+  if (pinned && pinned !== publicKey) {
+    return { ok: false, reason: `${engineName}: chave do registry ≠ chave FIXADA pelo consumidor → ABORT (registry pode estar comprometido)` };
+  }
+
+  const store = readTrust();
+  const known = store[engineName]?.publicKey;
+  if (known && known !== publicKey) {
+    return {
+      ok: false,
+      reason:
+        `${engineName}: a chave pública MUDOU desde a primeira instalação → ABORT. ` +
+        `Rotação legítima exige apagar a entrada em ${trustFile()} de propósito; ` +
+        `se você não rotacionou, o registry pode estar comprometido.`,
+    };
+  }
+  if (known) return { ok: true, tofu: false };
+
+  try {
+    mkdirSync(trustDir(), { recursive: true });
+    store[engineName] = { publicKey, firstSeen: new Date().toISOString(), source: pinned ? "pinned" : "tofu" };
+    writeFileSync(trustFile(), JSON.stringify(store, null, 2));
+  } catch {
+    // Não poder gravar a raiz não pode impedir a instalação — mas também não vira silêncio:
+    // sem gravar, a próxima execução repete o TOFU (e o consumidor vê `tofu:true` de novo).
+  }
+  return { ok: true, tofu: true };
+}
+
+export const trustPath = () => trustFile();

package/kit/update-manifest.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// engine-kit/update-manifest.mjs — patch cirúrgico de UM motor no manifest.json do registry.
+//
+//   node kit/update-manifest.mjs <motor> --version 0.2.0 --public-key <hex> [--repo owner/name]
+//                                        [--asset <template>] [--tag <template>] [--manifest <path>]
+//   node kit/update-manifest.mjs --app <nome> [--version 0.3.0] [--public-key <hex>] [--repo owner/name]
+//                                [--tag <template>] [--asset <template>=<plataforma> ...] [--manifest <path>]
+//
+// Com --app, a entrada é procurada em manifest.apps (aplicativos, que o engine-kit não
+// provisiona). Cada --asset repetido SUBSTITUI a lista de assets, com sidecars
+// '{asset}.sha256' e '{asset}.sig'.
+//
+// Existe para o publish não editar JSON com regex em PowerShell (o caminho clássico para corromper
+// um manifest silenciosamente). Aqui o arquivo é parseado, validado e reescrito — e se o motor não
+// existir, falha alto em vez de criar uma entrada meia-boca.
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const die = (msg) => { console.error(`FALHOU: ${msg}`); process.exit(1); };
+
+const USAGE = "uso: node kit/update-manifest.mjs <motor> --version <x.y.z> [...]\n" +
+              "     node kit/update-manifest.mjs --app <nome> [--version <x.y.z>] [--public-key <hex>] [--repo owner/name]\n" +
+              "                                  [--tag <template>] [--asset <template>=<plataforma> ...] [--manifest <path>]";
+const args = process.argv.slice(2);
+const opt = (flag) => { const i = args.indexOf(flag); return i === -1 ? null : args[i + 1]; };
+const optAll = (flag) => args.flatMap((a, i) => (a === flag ? [args[i + 1]] : []));
+
+const appName = args.includes("--app") ? opt("--app") : null;
+if (args.includes("--app") && (!appName || appName.startsWith("--"))) { die(USAGE); }
+const engineName = appName ? null : args[0];
+if (!appName && (!engineName || engineName.startsWith("--"))) { die(USAGE); }
+
+const manifestPath = opt("--manifest") ?? join(dirname(dirname(fileURLToPath(import.meta.url))), "manifest.json");
+const version = opt("--version");
+const publicKey = opt("--public-key");
+const repo = opt("--repo");
+const asset = opt("--asset");
+const tag = opt("--tag");
+
+if (version && !/^\d+\.\d+\.\d+$/.test(version)) { die(`versão inválida "${version}" (esperado x.y.z)`); }
+if (publicKey && !/^[0-9a-fA-F]{64}$/.test(publicKey)) { die(`publicKey inválida (esperado 64 chars hex, veio ${publicKey.length})`); }
+if (repo && !/^[^/]+\/[^/]+$/.test(repo)) { die(`repo inválido "${repo}" (esperado owner/name)`); }
+
+let manifest;
+try { manifest = JSON.parse(readFileSync(manifestPath, "utf8")); }
+catch (e) { die(`manifest ilegível em ${manifestPath}: ${e.message}`); }
+
+const save = (label, entry) => {
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  console.log(`manifest atualizado: ${manifestPath}`);
+  console.log(JSON.stringify({ name: entry.name, version: entry.version, [label]: entry[label] }, null, 2));
+};
+
+// Aplicativo: a entrada mora em manifest.apps, e o que muda numa release são versão, chave e assets.
+if (appName) {
+  const app = (manifest.apps ?? []).find((a) => a.name === appName);
+  if (!app) {
+    die(`app "${appName}" não existe em manifest.apps de ${manifestPath}.\n` +
+        `       Apps registrados: ${(manifest.apps ?? []).map((a) => a.name).join(", ") || "(nenhum)"}\n` +
+        "       Registre a entrada à mão primeiro — este script ATUALIZA, não inventa descritor.");
+  }
+  if (version) { app.version = version; }
+  if (publicKey) {
+    if (app.release.publicKey && app.release.publicKey.toLowerCase() !== publicKey.toLowerCase()) {
+      console.warn(`AVISO: publicKey de "${appName}" MUDOU — downloads assinados com a chave antiga deixam de conferir.`);
+    }
+    app.release.publicKey = publicKey.toLowerCase();
+    app.release.signatureAlgorithm = "ed25519-sha256-raw";
+    app.release.signatureRequired = true;
+  }
+  if (repo) { app.release.repo = repo; }
+  if (tag) { app.release.tag = tag; }
+  const assets = optAll("--asset");
+  if (assets.length) {
+    // Substitui a lista inteira: uma release é o conjunto de assets dela, não um acréscimo.
+    app.release.assets = assets.map((spec) => {
+      const cut = String(spec ?? "").lastIndexOf("=");
+      if (cut <= 0 || cut === spec.length - 1) { die(`--asset "${spec}" inválido (esperado <template>=<plataforma>)`); }
+      return { name: spec.slice(0, cut), platform: spec.slice(cut + 1), checksum: "{asset}.sha256", signature: "{asset}.sig" };
+    });
+  }
+  save("release", app);
+  process.exit(0);
+}
+
+const engine = (manifest.engines ?? []).find((e) => e.name === engineName);
+if (!engine) {
+  die(`motor "${engineName}" não existe em ${manifestPath}.\n` +
+      `       Motores registrados: ${(manifest.engines ?? []).map((e) => e.name).join(", ") || "(nenhum)"}\n` +
+      "       Registre a entrada à mão primeiro — este script ATUALIZA, não inventa descritor.");
+}
+
+if (version) { engine.version = version; }
+if (publicKey) {
+  // Trocar a chave de um motor já publicado invalida TODAS as releases anteriores dele nos
+  // consumidores que já a pinaram. Se for rotação intencional, é consciente; se não, é acidente.
+  if (engine.install.publicKey && engine.install.publicKey.toLowerCase() !== publicKey.toLowerCase()) {
+    console.warn(`AVISO: publicKey de "${engineName}" MUDOU — releases assinadas com a chave antiga passam a ser recusadas.`);
+  }
+  engine.install.publicKey = publicKey.toLowerCase();
+  engine.install.signatureAlgorithm = "ed25519-sha256-raw";
+  engine.install.signatureRequired = true;
+}
+if (repo) { engine.install.repo = repo; }
+if (asset) { engine.install.asset = asset; }
+if (tag) { engine.install.tag = tag; }
+
+save("install", engine);

package/kit/update.mjs

@@ -0,0 +1,68 @@
+// engine-kit/update.mjs — o próprio kit se atualiza antes de instalar motores.
+//
+// `npx engine-kit` sem versão reusa o pacote que já está na cache do npx: quem rodou uma vez fica preso naquela
+// versão (e no manifest embarcado dela, que é a raiz de confiança do ensure). Por isso o cli consulta a última
+// versão publicada e, por padrão, roda de novo como `npx --yes engine-kit@<última>` com os mesmos argumentos. A
+// versão nova vem do mesmo canal do primeiro `npx` (npm, publicação confiável com proveniência): não é confiança nova.
+//
+// ENGINE_KIT_NO_AUTO_UPDATE=1 desliga: o kit não se troca nem troca motor já instalado, só AVISA da versão nova.
+// ENGINE_KIT_UPDATED_FROM marca o processo relançado, para não entrar em laço.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+export const LATEST_URL = "https://registry.npmjs.org/engine-kit/latest";
+
+export const autoUpdateEnabled = (env = process.env) => !["1", "true", "yes"].includes(String(env.ENGINE_KIT_NO_AUTO_UPDATE ?? "").toLowerCase());
+
+export const ownVersion = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+/** true se `a` é versão estável maior que `b` (x.y.z; pré-release como 0.2.0-bootstrap.0 nunca é alvo). */
+export function isNewer(a, b) {
+  if (!/^\d+\.\d+\.\d+$/.test(a ?? "")) return false;
+  const pa = a.split(".").map(Number), pb = String(b).split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) { if (pa[i] !== pb[i]) return pa[i] > pb[i]; }
+  return /-/.test(b);   // 0.2.0 > 0.2.0-bootstrap.0
+}
+
+async function fetchLatest() {
+  const res = await fetch(LATEST_URL, { signal: AbortSignal.timeout(5000) });
+  if (!res.ok) { throw new Error(`HTTP ${res.status}`); }
+  return (await res.json()).version;
+}
+
+function runLatest(version, args, env) {
+  // npx no Windows é npx.cmd: o spawn de .cmd exige shell. Argumentos aqui são nome de motor e flags simples.
+  const r = spawnSync("npx", ["--yes", `engine-kit@${version}`, ...args], { stdio: "inherit", shell: process.platform === "win32", windowsHide: true, env });
+  return r.error ? { status: 1, error: r.error.message } : { status: r.status ?? 1 };
+}
+
+/**
+ * Decide e, se for o caso, executa a autoatualização. Nunca lança.
+ * @returns {Promise<{action:"none"|"warn"|"relaunched", status?:number, latest?:string, message?:string}>}
+ *          `relaunched` = a versão nova já rodou o comando (o chamador só repassa `status`).
+ */
+export async function selfUpdate(args, { env = process.env, current = ownVersion(), latest = fetchLatest, run = runLatest, log = console.error } = {}) {
+  if (env.ENGINE_KIT_UPDATED_FROM) {
+    log(`engine-kit atualizado: v${env.ENGINE_KIT_UPDATED_FROM} → v${current}`);
+    return { action: "none" };
+  }
+  let v;
+  try { v = await latest(); }
+  catch (e) {
+    log(`aviso: não consegui consultar a versão mais nova do engine-kit (${e.message}); seguindo com v${current}`);
+    return { action: "none" };
+  }
+  if (!isNewer(v, current)) return { action: "none" };
+  if (!autoUpdateEnabled(env)) {
+    const message = `engine-kit v${v} disponível (você roda v${current}); ENGINE_KIT_NO_AUTO_UPDATE ligado — rode npx engine-kit@latest para atualizar`;
+    log(message);
+    return { action: "warn", latest: v, message };
+  }
+  log(`engine-kit v${v} disponível (você roda v${current}) → atualizando`);
+  const r = run(v, args, { ...env, ENGINE_KIT_UPDATED_FROM: current });
+  if (r.error) {
+    log(`aviso: não consegui rodar engine-kit@${v} (${r.error}); seguindo com v${current}`);
+    return { action: "none" };
+  }
+  return { action: "relaunched", status: r.status, latest: v };
+}

package/kit/verify-release.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// engine-kit/verify-release.mjs — prova o CAMINHO REAL depois de publicar.
+//
+//   node kit/verify-release.mjs <motor> [--manifest <path>]
+//   node kit/verify-release.mjs --app <nome> [--manifest <path>]   # aplicativo: TODOS os assets
+//
+// Baixa do release público exatamente o que um consumidor baixaria (asset + .sha256 + .sig),
+// usando as URLs montadas a partir do manifest, e confere as duas garantias:
+//   integridade (sha256 bate)  e  autenticidade (assinatura confere com a publicKey do registry).
+//
+// Por que existe: "publiquei" não é prova. Asset faltando, .sig esquecido, tag errada e artefato
+// do build anterior só aparecem quando um consumidor tenta instalar — em produção. Este passo
+// puxa isso para dentro do publish. Também prova a metade negativa: adulterado é RECUSADO.
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { resolve } from "./resolve.mjs";
+import { verifyBlob, DEFAULT_ALGORITHM } from "./signature.mjs";
+import { findApp, appAssetUrls, verifyAppRelease } from "./app-release.mjs";
+
+const die = (msg) => { console.error(`FALHOU: ${msg}`); process.exit(1); };
+
+const USAGE = "uso: node kit/verify-release.mjs <motor> [--manifest <path>]\n" +
+              "     node kit/verify-release.mjs --app <nome> [--manifest <path>]";
+const args = process.argv.slice(2);
+const opt = (flag) => { const k = args.indexOf(flag); return k === -1 ? null : args[k + 1]; };
+const appName = args.includes("--app") ? opt("--app") : null;
+if (args.includes("--app") && (!appName || appName.startsWith("--"))) { die(USAGE); }
+const engineName = appName ? null : args[0];
+if (!appName && (!engineName || engineName.startsWith("--"))) { die(USAGE); }
+const manifestPath = opt("--manifest") ?? join(dirname(dirname(fileURLToPath(import.meta.url))), "manifest.json");
+
+let manifest;
+try { manifest = JSON.parse(readFileSync(manifestPath, "utf8")); }
+catch (e) { die(`manifest ilegível em ${manifestPath}: ${e.message}`); }
+
+// Aplicativo: não há asset único nem provision — baixa TODOS os assets da entrada, anônimo.
+if (appName) {
+  const f = findApp(manifest, appName);
+  if (!f.ok) { die(f.reason); }
+  const { tag } = appAssetUrls(f.app);
+  console.log(`app            : ${f.app.name} v${f.app.version}`);
+  console.log(`release        : ${f.app.release.repo} @ ${tag}`);
+  if (!f.app.release.publicKey) { console.warn("AVISO: app sem publicKey — integridade será verificada, AUTENTICIDADE não."); }
+  const r = await verifyAppRelease(f.app, { log: (m) => console.log(`  OK  ${m}`) });
+  if (!r.ok) { die(r.reason); }
+  console.log(`\nOK: os ${r.assets.length} assets de ${f.app.name} v${f.app.version} baixam sem login e conferem.`);
+  process.exit(0);
+}
+
+const r = await resolve(engineName, { manifest });
+if (!r.ok) { die(r.reason); }
+const engine = r.engine;
+
+async function grab(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(180000) });
+  if (!res.ok) { throw new Error(`HTTP ${res.status} em ${url}`); }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+console.log(`motor          : ${engine.name} v${engine.version}`);
+console.log(`origem         : ${engine.install.repo}`);
+console.log(`asset          : ${engine.assetUrl}`);
+
+let asset, sha, sig;
+try { asset = await grab(engine.assetUrl); } catch (e) { die(`asset não baixou — ${e.message}`); }
+try { sha = String(await grab(engine.checksumUrl)).trim().split(/\s+/)[0].toLowerCase(); }
+catch (e) { die(`sidecar .sha256 não baixou — ${e.message}`); }
+
+const actual = createHash("sha256").update(asset).digest("hex");
+if (actual !== sha) { die(`SHA256 divergente (release=${sha.slice(0, 12)}… baixado=${actual.slice(0, 12)}…)`); }
+console.log(`sha256         : ${actual} OK`);
+
+const publicKey = engine.install.publicKey;
+if (!publicKey) {
+  if (engine.install.signatureRequired) { die("signatureRequired sem publicKey no manifest — corrija antes de anunciar"); }
+  console.warn("AVISO: motor sem publicKey no registry — integridade verificada, AUTENTICIDADE não.");
+  process.exit(0);
+}
+
+try { sig = await grab(engine.signatureUrl); } catch (e) { die(`sidecar .sig não baixou — ${e.message} (a release saiu SEM assinatura)`); }
+
+const algorithm = engine.install.signatureAlgorithm ?? DEFAULT_ALGORITHM;
+const v = verifyBlob(asset, sig, publicKey, { algorithm });
+if (!v.ok) { die(v.reason); }
+
+// A metade negativa: se um artefato adulterado passasse, a verificação positiva não valeria nada.
+if (verifyBlob(Buffer.concat([asset, Buffer.from([0])]), sig, publicKey, { algorithm }).ok) {
+  die("a verificação ACEITOU um artefato adulterado — contrato quebrado, NÃO anuncie esta release");
+}
+
+console.log(`assinatura     : ${algorithm} OK (e artefato adulterado é RECUSADO)`);
+console.log("\nOK: a release publicada instala pelo caminho real de um consumidor.");