Política para desenvolvedores e diretrizes de segurança

Simon Hangl

Demián Renzulli

Os Apps Isolados da Web (AIWs) oferecem um modelo de segurança que permite que aplicativos da Web acessem recursos avançados, como Direct Sockets e Controlled Frame, que geralmente são restritos na Web padrão "drive-by". Como os IWAs operam em um ambiente de alta confiança, eles precisam obedecer a políticas rígidas de segurança e privacidade. Essas diretrizes foram criadas para garantir que, à medida que a plataforma da Web ganha mais poder, os usuários permaneçam seguros e a integridade do ambiente do navegador seja mantida.

O modelo de confiança da IWA

O núcleo da plataforma IWA é construído em torno de políticas técnicas rigorosas que obrigam os desenvolvedores a manter um alto nível de segurança. Enquanto os apps da Web padrão dependem de um modelo de permissão flexível, as IWAs são assinadas criptograficamente e entregues usando pacotes da Web, o que permite a verificação da origem e da integridade delas.

Em troca dessa identidade verificada, os IWAs ganham acesso a APIs privilegiadas. Para manter essa confiança, os desenvolvedores precisam seguir uma abordagem de segurança em primeiro lugar, aderindo a políticas mais rígidas, incluindo uma Política de Segurança de Conteúdo (CSP) e Tipos confiáveis robustos, que garantem a segurança do usuário mesmo ao usar recursos avançados. Isso significa:

• Transparência:os usuários nunca devem se surpreender com o uso de APIs privilegiadas por um aplicativo.
• Privilégio mínimo:os apps só podem solicitar e usar os recursos específicos necessários para a finalidade declarada.
• Integridade estática:toda a lógica executável precisa estar contida no pacote do app para permitir auditoria de segurança e evitar o sideloading de código malicioso.

Embora as IWAs incluam proteções integradas robustas, como uma Política de Segurança de Conteúdo (CSP) estrita que impede a execução de scripts externos, as restrições técnicas sozinhas não podem reduzir todos os riscos. Mesmo em um ambiente de alta confiança, determinados padrões de implementação ou escolhas de desenvolvedores podem comprometer inadvertidamente a segurança ou a privacidade do usuário. Este guia descreve esses cenários restritos e as políticas que regem o uso de APIs privilegiadas.

Por que essas diretrizes são importantes

Aderir a essas políticas não é apenas uma questão de conformidade, mas também de construir um ecossistema sustentável para aplicativos da Web avançados. Ao seguir estas diretrizes, você garante que seu aplicativo:

• Evita regressões de segurança:impede vulnerabilidades como scripting em vários locais (XSS) e execução remota de código, mantendo a lógica independente.
• Protege a privacidade do usuário:garante que dados sensíveis e acesso ao hardware sejam tratados apenas com intenção e transparência explícitas do usuário.
• Garante a longevidade da plataforma:ajuda a manter os altos padrões de segurança necessários para que a plataforma IWA continue expandindo o conjunto de recursos.

Princípios básicos

Transparência e intenção do usuário

A regra mais fundamental é: não surpreenda o usuário. O comportamento do aplicativo precisa estar alinhado com a finalidade declarada e as expectativas do usuário.

• Fique dentro do escopo: não implemente funcionalidades que vão além da finalidade clara do seu aplicativo.
• Pegada mínima da API:solicite e use apenas o conjunto específico de APIs IWA necessário para alcançar a função principal do app.

Sem sideload de código dinâmico

O modelo de segurança da IWA depende da capacidade dos administradores ou do fornecedor do navegador de verificar toda a lógica executável. Por isso, o pacote de IWA precisa ser independente. A plataforma aplica isso com uma Política de Segurança de Conteúdo (CSP) rigorosa que bloqueia a execução baseada em strings, como eval() e new Function():

script-src 'self' 'wasm-unsafe-eval';
require-trusted-types-for 'script';

Embora a CSP permita que 'wasm-unsafe-eval' ofereça suporte ao WebAssembly, não é permitido burlar o espírito desse limite de segurança.

Práticas estritamente proibidas

• Envio de intérpretes para código remoto:não é permitido incluir um intérprete de código (por exemplo, Python ou Lua compilados para WASM) para baixar e executar scripts externos usando acesso privilegiado à rede, como sockets diretos.
• Lógica carregada remotamente:não use service workers para incorporar código carregado remotamente na origem da IWA.
• Código x dados:embora seja permitido baixar dados (como JSON), baixar qualquer código destinado a ser interpretado ou executado é uma violação direta da política.

O princípio de privilégio mínimo

Sempre use a API menos potente capaz de realizar uma tarefa. As APIs privilegiadas específicas da IWA nunca devem ser usadas como um atalho para ignorar as restrições de segurança ou os prompts do usuário das APIs da Web padrão. A tabela a seguir descreve casos de uso comuns para ajudar você a decidir quando usar APIs da Web tradicionais em vez de recursos específicos da IWA:

Diretrizes específicas da API

As APIs IWA oferecem recursos avançados que geralmente são restritos no navegador. A orientação geral é nunca usar esses recursos privilegiados de uma forma que surpreenda os usuários ou comprometa a confiança e os dados deles.

API Direct Sockets

A API Direct Sockets concede acesso TCP e UDP brutos, incluindo acesso a multicast e rede local.

Permitido

• Suporte a protocolos personalizados:conexão com servidores remotos que usam protocolos personalizados para os quais não existe uma API da Web de nível superior.
• Manutenção de serviços de back-end:conexão a um servidor predefinido e codificado usado especificamente para os serviços de back-end do seu aplicativo.
• Descobrindo hardware essencial:acesso à rede local ou uso de multicast para descobrir hardware específico e relacionado essencial à função do app (por exemplo, um app de edição de vídeo localizando armazenamento conectado à rede).

Não permitido

• Surpreender o usuário:implementar acesso à rede que não é claramente justificado pela funcionalidade principal do app, como um editor de texto que se comunica com dispositivos de rede local.
• Verificação arbitrária de redes:realizar verificações amplas da rede local do usuário (por exemplo, verificação de portas 192.168.1.0/24) para criar um perfil do usuário ou descobrir dispositivos não relacionados.
• Segmentação de dispositivos locais:é estritamente proibido tentar sondar, reconfigurar ou atacar outros dispositivos na rede local.

API Controlled Frame

O elemento <controlledframe> permite a incorporação e a modificação de conteúdo de origem cruzada, incluindo injeção de script e alteração de cabeçalho.

Permitido

• Simplificar interfaces do usuário:incorporar um serviço de terceiros e injetar CSS para ocultar elementos irrelevantes da interface ou oferecer uma experiência mais coesa.
• Mediar a comunicação segura:atuar como um gatekeeper recebendo solicitações da página incorporada com postMessage e retornando apenas dados higienizados e necessários buscados por APIs privilegiadas.

Não permitido

• Roubo de credenciais do usuário:injeção de scripts para capturar senhas, cookies de sessão ou outros dados sensíveis do usuário no conteúdo incorporado.
• Violação dos Termos de Serviço:alterar plataformas incorporadas de maneiras que violam os Termos de Serviço delas, como cliques programáticos em anúncios ou raspagem de dados não autorizada.
• Proxy de acesso privilegiado:criação de um pass-through que dá a conteúdo incorporado não confiável acesso direto ou descontrolado a uma API IWA privilegiada.
• Implementação de IA não controlada:realizar ações em nome de um usuário conectado usando IA sem restrições de caso de uso específicas e transparentes.

Gravação de tela sem restrições

Permite a captura de tela sem os prompts repetidos de permissão do usuário encontrados na Web padrão.

Permitido

• Fornecer funcionalidade principal:usar a captura de tela como parte óbvia do serviço do app, como em recursos de gravação de tutoriais ou reuniões virtuais.
• Garantir a conscientização do usuário:informar claramente aos usuários que a gravação pode ocorrer antes que eles interajam com o aplicativo.

Não permitido

• Gravação dissimulada:captura da tela do usuário sem o conhecimento e consentimento explícitos e prévios dele.
• Violação das regulamentações de privacidade:realizar práticas de gravação que violem as leis de privacidade locais ou internacionais.

WebUSB irrestrita

O WebUSB sem restrições ignora a lista de bloqueio padrão do WebUSB para permitir a interação de baixo nível com dispositivos.

Permitido

• Suporte a hardware proprietário:interação com hardware especializado ou legado para o qual não existe uma API da Web de alto nível, como controladores industriais.

Agora permitido

• Ignorar APIs dedicadas:usar a WebUSB para dispositivos que têm uma API mais específica e restrita, como smart cards (use a API Smart Card) ou armazenamento externo (use a API File System Access).

Gerenciamento de janelas (window.open e window.focus)

As IWAs podem criar pop-ups e janelas de foco sem o gesto do usuário exigido pela Web padrão.

Permitido

• Notificação de conclusão de tarefa:foco na janela do app quando uma tarefa em segundo plano crítica iniciada pelo usuário, como a renderização de um vídeo, é concluída.

Não permitido

• Spam:bombardear o usuário com várias janelas não solicitadas.
• Phishing:abertura de janelas projetadas para imitar caixas de diálogo do sistema ou enganar o usuário.
• Roubo de foco:interromper o usuário roubando o foco de outros aplicativos para eventos não críticos.

Conclusão

A arquitetura de segurança dos apps da Web isolados foi projetada para capacitar os desenvolvedores e manter um ambiente de alta confiança para os usuários. Ao seguir essas diretrizes, você garante que seu aplicativo continue sendo um cidadão responsável do ecossistema IWA. As conclusões mais importantes deste guia incluem:

• Priorize a transparência:o comportamento do aplicativo precisa sempre estar alinhado à finalidade declarada. Nunca implemente funcionalidades que surpreendam ou enganem o usuário.
• Impor integridade do pacote:toda a lógica executável precisa estar independente no pacote de IWA para permitir a verificação estática. É estritamente proibido burlar o modelo de segurança usando sideloading de código dinâmico ou intérpretes remotos.
• Obedeça ao princípio de privilégio mínimo:sempre selecione a API mais restrita disponível para uma determinada tarefa. As APIs IWA privilegiadas só devem ser usadas quando as APIs da Web padrão não são suficientes para a funcionalidade principal do aplicativo.
• Atue como um gatekeeper:ao usar ferramentas poderosas como <controlledframe>, sua IWA precisa atuar como um mediador seguro, e não como um proxy transparente para conteúdo não confiável.

Antes de publicar sua IWA, faça uma auditoria final da implementação perguntando:

1. Estou usando a API mais simples e restrita possível para essa tarefa?
2. Um usuário ficaria surpreso ou se sentiria traído pelo que meu app está fazendo?

Se a resposta à primeira pergunta for "Não" ou à segunda for "Sim", é provável que seu aplicativo esteja violando as políticas de segurança da IWA e possa ser removido.