Permissions-Policy: converter entre cabeçalho e atributo allow

O que é Permissions Policy

Permissions Policy é como uma página declara quais recursos do navegador ela e o que ela incorpora podem usar: câmera, microfone, geolocalização, tela cheia, solicitações de pagamento e algumas dezenas de outros. Substituiu o Feature Policy e é entregue de duas maneiras: como cabeçalho de resposta Permissions-Policy, cobrindo o documento inteiro, e como atributo allow num iframe específico, cobrindo só aquele quadro.

Os dois estão definidos na mesma especificação do W3C e expressam a mesma ideia: um nome de recurso seguido de uma lista de origens que podem usá-lo. O que passa despercebido com facilidade é que a especificação escreve essa lista em duas gramáticas diferentes, uma para cada mecanismo de entrega, e elas não se parecem.

Este conversor recebe qualquer uma das duas formas e produz a outra, e depois nomeia cada diferença que aplicou. É uma ferramenta de tradução, não um gerador de políticas: ela não decide qual deveria ser a sua política e não opina sobre quais recursos convém restringir.

Como usar

1. Diga de qual das duas formas você está partindo. Um atributo allow de iframe ou o valor de um cabeçalho Permissions-Policy. O analisador segue a gramática da que você escolher, então um cabeçalho colado como atributo será apontado como errado em vez de aceito em silêncio.
2. Cole só o valor. Sem o nome do atributo, sem as aspas em volta e sem o nome do campo nem os dois-pontos do cabeçalho: apenas o que fica dentro. Os botões de exemplo carregam cinco políticas, cada uma escolhida para mostrar uma parte diferente das duas gramáticas.
3. Leia as duas saídas e os três painéis abaixo delas. Um lista o que o analisador encontrou no que você digitou. Outro lista o que não sobrevive à viagem até um cabeçalho. E outro nomeia as quatro diferenças entre as gramáticas, para você ver quais se aplicaram à sua política.

Quatro diferenças entre as duas gramáticas

A seção 5.1 da especificação dá ao atributo uma gramática ABNF própria; a 5.2 diz que o cabeçalho é, em vez disso, um dicionário de Structured Fields. O resultado é que allow="geolocation 'self' https://example.com" e Permissions-Policy: geolocation=(self "https://example.com") são a mesma política escrita de duas maneiras, e quatro coisas mudam entre elas.

As aspas se invertem. As palavras-chave vêm entre aspas no atributo e soltas no cabeçalho; com as origens é o contrário, soltas no atributo e como strings entre aspas no cabeçalho. O separador também muda: ponto e vírgula entre diretivas no atributo, vírgula no cabeçalho, porque os membros de um dicionário são separados por vírgula. E bloquear um recurso é a palavra-chave none no atributo mas um par de parênteses vazios no cabeçalho: a palavra não aparece em cabeçalho nenhum.

A quarta é a que merece cuidado, porque inverte o sentido em silêncio em vez de falhar. Um recurso escrito sem nada depois significa o oposto em cada gramática. Parênteses vazios num cabeçalho são uma lista sem origens: ninguém. Um nome sozinho num atributo não está vazio de forma alguma: a seção 5.1 diz que a lista então equivale a 'src', ou seja, a origem do que aquele iframe carregar. Converta um no outro sem perceber e um recurso bloqueado passa a ser permitido.

Limitações honestas

Há uma coisa que um atributo consegue dizer e um cabeçalho não. A palavra-chave 'src' significa a origem do documento indicado no atributo src do iframe, e um cabeçalho de resposta não está preso a iframe nenhum, então não há a que se referir. A especificação é sutil aqui e vale ler devagar: a seção 4 diz que a palavra-chave pode aparecer no texto das listas tanto em cabeçalhos quanto em atributos, portanto não é erro de sintaxe, e a seção 9 só a resolve quando lhe é dada uma origem de destino. Num cabeçalho ela é analisada e depois não faz nada. Esta ferramenta aponta isso como perda e não como erro, porque é o que a especificação descreve.

Com os nomes de recurso acontece o mesmo. A seção 5.2 diz que, se um membro do dicionário não nomear um recurso que o navegador suporte, o membro é ignorado no processamento. Um erro de digitação num cabeçalho não gera aviso em lugar nenhum: a diretiva simplesmente não faz nada. Este conversor verifica se o nome está escrito de forma legal — letras, dígitos e hifens —, mas de propósito não carrega uma lista de recursos suportados, porque essa lista muda entre navegadores e versões e uma cópia desatualizada seria pior que nenhuma.

E mais uma coisa. A especificação cita a RFC 8941 para a gramática do cabeçalho, e a RFC 9651 substituiu esse documento em 2024. A nova versão acrescenta dois tipos de dados que este cabeçalho não usa, move a gramática para um apêndice informativo e refina o tratamento de falhas de análise; não muda nada quanto a dicionários, tokens ou listas entre parênteses. Ou seja, a citação está desatualizada e o comportamento não — e vale dizer isso inteiro, porque qualquer das duas metades sozinha engana.

Por que é grátis?

São dois analisadores pequenos e dois serializadores, e o seu navegador roda todos enquanto você digita. Nenhum servidor entra na história, então não há nada a medir nem conta a criar.

Nada é enviado. A política que você colar fica nesta aba.