# Instalar e restaurar arquivos .wuapp

Empacote, verifique, instale, monte e atualize uma app com assinatura e grants definidos pelo host.

Esta página descreve o WU Framework `4.0.0`. Consulte o [guia de migração para Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/) 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.

<span id="preparar-el-paquete"></span>

<span class="section-anchor" id="section-1"></span>

## Preparar o pacote

```sh
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](/pt/docs/cli/pack/) para opções, formato e erros.

<span id="instalar-y-montar"></span>

<span class="section-anchor" id="section-2"></span>

## Instalar e montar

```js
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.

<span id="restaurar-actualizar-y-retirar"></span>

<span class="section-anchor" id="section-3"></span>

## Restaurar, atualizar e remover

```js
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.

<span id="integridad-y-reemplazo-en-40"></span>

<span class="section-anchor" id="section-4"></span>

## 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.