Instalar e restaurar arquivos .wuapp

Esta página descreve o WU Framework 4.0.0. Consulte o guia de migração para Framework 4.0 e CLI 1.2 antes de atualizar um projeto existente.

Um arquivo .wuapp contém uma app construída, seu manifest, arquivos e assinatura opcional. A instalação usa Cache Storage em /@wuapp/<name>@<version>/. É um caminho virtual na origem do host; a assinatura confirma a chave aceita e a integridade verificada, não o isolamento em outra origem.

Preparar o pacote

wu build --native
wu pack --keygen keys/catalog.pem --json
wu pack catalog --version 1.2.0 --sign keys/catalog.pem --out catalog-1.2.0.wuapp
wu serve 4100

Mantenha a chave privada fora do conteúdo público. Copie a JWK pública do resultado para catalog-public-key.json no host. O nome catalog deve existir em dist/wu-manifest.json. Veja wu pack para opções, formato e erros.

Instalar e montar

import { wu } from 'wu-framework/core';
import 'wu-framework/wuapp';

await wu.init({ apps: [] });
const publicKey = await fetch('/catalog-public-key.json').then(r => r.json());
const installed = await wu.wuapps.install('/catalog-1.2.0.wuapp', {
  trust: [publicKey],
  grants: ['events.emit:catalog:*'],
});
const worker = await wu.wuapps.check();
if (!worker.ok) throw new Error(worker.reason);
await wu.mount(installed.name, '#catalog-slot');

Sirva o arquivo e a chave pública por HTTPS ou localhost e crie #catalog-slot no shell. O Service Worker gerado por wu build --native precisa controlar a página; a primeira visita pode exigir recarga. check().ok verifica a existência de um controlador, não se qualquer Service Worker implementa a rota. Verifique também a resposta HTTP da entrada instalada.

source aceita URL, File/Blob, ArrayBuffer, Uint8Array ou objeto analisado. Antes de gravar no cache, a instalação valida estrutura, caminhos, assinatura ECDSA P-256 e SHA-256 de cada arquivo. O host define trust e grants; trust: "any" aceita qualquer chave assinante e allowUnsigned: true permite pacotes sem assinatura. frameworkBase substitui /@modules/ quando os módulos compartilhados ficam em outro caminho.

Restaurar, atualizar e remover

await wu.wuapps.restore();
const inventory = await wu.wuapps.installed();

await wu.unmount('catalog', { force: true });
await wu.wuapps.install('/catalog-1.3.0.wuapp', {
  trust: [publicKey], grants: ['events.emit:catalog:*'],
});
await wu.mount('catalog', '#catalog-slot');

await wu.unmount('catalog', { force: true });
const removed = await wu.wuapps.uninstall('catalog');

restore() registra entradas persistidas e retorna as restauradas; não as monta. installed() lê o índice salvo. Instalar outra versão substitui a anterior; atualizar ou desinstalar uma app montada ou oculta rejeita com WU_WUAPP_MOUNTED. Desmonte completamente primeiro. Os eventos são wuapp:installed e wuapp:uninstalled.

Os erros distinguem WU_WUAPP_INVALID, WU_WUAPP_UNSIGNED, WU_WUAPP_UNTRUSTED, WU_WUAPP_BAD_SIGNATURE, WU_WUAPP_INTEGRITY e WU_WUAPP_NO_CACHE. Salvar o pacote não prova que seus módulos montam: o host ainda precisa dos módulos compartilhados, grants corretos e uma rota atendida pelo worker.

Integridade e substituição no 4.0

O campo type do pacote não determina o MIME: ele é derivado da extensão usando a tabela de wu pack e servido com nosniff. Paths rejeitam segmentos reservados, incluindo __proto__, e o payload assinado é construído sem protótipo.

Instalar sobre um nome registrado pelo host exige { replace: true }; caso contrário, falha com WU_WUAPP_NAME_TAKEN. Atualizar uma app instalada continua permitido após desmontá-la. restore() valida cada entrada persistida e nunca substitui um registro do host.

restore({ grants }) aceita um array de grants ou uma função (entry) => grants definida pelo host. Quando omitido, usa os grants salvos na instalação. Defina essa opção quando não quiser recuperar autoridade do índice de localStorage.