# Cartões de aprovação do VoiceOver para ações de agentes

Um cartão de aprovação é uma decisão de segurança, não uma interrupção decorativa. Se um usuário do VoiceOver não consegue identificar o processo que fez a solicitação, o destino real, a ação e o escopo antes dos botões, o cartão pede consentimento sem fornecer os fatos necessários para concedê-lo.

Já vi equipes chamarem um prompt de «acessível» porque o VoiceOver chegava a um botão Aprovar. Isso é um padrão baixo e perigoso. Uma pessoa pode ativar um controle que não entende. Para ações de agentes, essa falha tem consequências reais: uma única aprovação pode enviar uma solicitação usando uma credencial armazenada ou abrir uma sessão SSH em uma máquina que o próprio agente não é confiável para descrever.

## O cartão precisa declarar a decisão antes de oferecer controles

A primeira fala útil deve identificar a decisão, e todos os fatos necessários para tomá-la precisam aparecer antes de Aprovar e Negar. Um bom cartão apresenta primeiro um resumo curto ao VoiceOver e depois expõe os detalhes em uma ordem estável. Ele não obriga a pessoa a procurar informações em uma disposição visual que só faz sentido quando ela consegue enxergar espaçamento, selos ou cores.

Use esta ordem:

1. Por que o cartão apareceu: um novo processo de agente solicita autorização, ou uma credencial protegida exige confirmação para esta chamada.
2. Quem está solicitando: o nome do processo, o caminho do executável quando for útil e sua autoridade de assinatura de código.
3. Onde ele quer agir: o protocolo e o destino concreto.
4. O que ele quer fazer: o método HTTP e o formato da solicitação, ou o comando SSH e o alvo.
5. O que a decisão concede: esta chamada, este processo em execução até ser encerrado ou um único uso de credencial protegida.

Essa sequência corresponde à decisão que um operador cuidadoso toma. A procedência responde quem está solicitando. O destino responde onde a consequência ocorrerá. A ação responde o que será alterado. O escopo responde por quanto tempo a permissão continuará válida. Colocar os botões antes dessa sequência transforma o cartão em um teste de reflexo.

Mantenha o resumo inicial curto o suficiente para ser ouvido de uma vez. Por exemplo:

```
Authorization requested. Signed process: Acme Development, agent-helper.
HTTPS request to api.example.net. POST /v1/releases.
This approval allows this process until it exits.
```

Os detalhes expandidos devem aparecer imediatamente depois do resumo, antes dos controles. Não os esconda atrás de um triângulo de expansão sem rótulo nem obrigue o usuário a entrar em outra tela para descobrir o host. Um cartão compacto pode recolher campos de baixa consequência, mas não pode recolher o destino nem a própria operação.

As WAI-ARIA Authoring Practices da W3C descrevem um diálogo modal como uma interação contida, com um rótulo, gerenciamento adequado de foco e uma forma explícita de fechá-lo. Essa orientação também vale quando o aplicativo usa controles nativos do macOS em vez de ARIA na web. Um prompt modal que anuncia apenas seu título cumpriu a parte mais restrita do padrão, mas falhou na decisão real.

## A identidade do processo é uma evidência, não uma autorização

A assinatura de um processo informa ao usuário quem criou ou assinou o código que está pedindo acesso. Ela não informa se a solicitação é apropriada. Trate-a como uma evidência que aparece no início do cartão e torne o restante da solicitação impossível de confundir com essa identidade.

O campo de identidade precisa ter uma forma estável e falada. Comece pela autoridade de assinatura, pois ela oferece um ponto de referência significativo quando vários processos auxiliares têm nomes de arquivo parecidos. Depois, informe o nome do processo. Inclua um caminho somente quando ele resolver uma ambiguidade, como no caso de uma compilação local de desenvolvimento e uma compilação instalada com o mesmo nome. Um caminho longo deve ficar na região de detalhes, onde o VoiceOver possa lê-lo linha por linha.

Evite expressões vagas como «agente confiável» ou um selo verde de «verificado». Essas frases comprimem várias afirmações diferentes em uma indicação visual tranquilizadora. Um processo pode ter uma assinatura válida e ainda carregar um prompt malformado, uma fonte de instruções comprometida ou uma solicitação direcionada à conta errada. Os usuários precisam da procedência, não de um veredito criado pela interface.

Um resumo da solicitação pode dizer:

```
Requesting process
Signing authority: Example Software LLC
Process: deploy-helper
Details: /Applications/Deploy Helper.app/Contents/MacOS/deploy-helper
```

Apresente esse conteúdo como um único grupo rotulado, cujos filhos sigam a mesma ordem. Não repita a autoridade de assinatura em um subtítulo, um selo e uma dica de acessibilidade. A repetição torna a saída do VoiceOver cansativa, e o usuário começa a ignorar justamente a frase que você queria que ele percebesse.

Há outra armadilha aqui: o nome de um processo pode mudar. Um invasor pode chamar um executável de «release-agent» e esperar que a pessoa não leia além disso. A autoridade de assinatura é mais difícil de imitar, mas ainda assim não pode autorizar o destino. O cartão nunca deve apresentar a identidade como se ela garantisse a solicitação. Diga «solicitado por» ou «assinado por» e descreva a ação em frases separadas.

Para processos locais de desenvolvimento sem assinatura, declare essa condição de forma direta. Não use um eufemismo como «compilação pessoal». Se o produto permitir a solicitação, o usuário poderá decidir se um processo sem assinatura merece uma concessão para a sessão. Esconder a condição não elimina o atrito; apenas adia esse atrito até depois de um erro.

## Um destino precisa de um nome que os usuários possam inspecionar

Um cartão precisa falar o destino como um endpoint ou host específico, porque categorias e ícones não conseguem informar para onde as credenciais serão enviadas. HTTP e SSH precisam de resumos diferentes, mas ambos precisam indicar um lado remoto concreto antes de qualquer controle de aprovação.

Para HTTP, leia o protocolo, o host, o método e um caminho que preserve a consequência. `POST api.example.net/v1/releases` diz muito mais do que «Serviço de releases». Se a porta for diferente da usual, inclua-a. Se a solicitação seguir um redirecionamento, não descreva apenas o host original e deixe o host final para uma surpresa posterior. Resolva o destino antes de pedir consentimento ou peça consentimento novamente quando a resolução alterar o host remoto.

Para SSH, leia o host ou alias, o usuário quando isso afetar o privilégio e o comando. `ops@build-03.example.net: systemctl restart worker` fornece uma decisão que a pessoa pode tomar. «Comando SSH» não fornece. Se um alias for expandido por meio de um arquivo de configuração, mostre o host resolvido no resumo principal e mantenha o alias nos detalhes. As pessoas muitas vezes reconhecem primeiro o apelido e depois a máquina real; elas precisam dos dois.

O DNS merece a mesma cautela. Um nome de host é a identidade voltada para as pessoas. Um endereço IP pode complementá-lo, especialmente em uma solicitação suspeita ou incomum, mas não deve substituí-lo e transformar toda aprovação em um teste de memória. Se um sistema não conseguir resolver um destino, o prompt deve informar que não conseguiu resolvê-lo. Não deve inventar confiança usando um rótulo antigo armazenado em cache.

Não dependa de um rótulo vermelho de produção, de um triângulo de alerta ou de uma coluna à esquerda para distinguir destinos. Esses recursos podem ajudar na leitura visual, mas não podem carregar o significado. Coloque o nome do ambiente em texto se você tiver uma fonte confiável para ele e fale também o host. Os rótulos de ambiente mudam. Os hosts informam ao usuário para onde a conexão vai.

Uma representação acessível e concisa se parece com esta:

```
Destination
Protocol: HTTPS
Host: billing.example.net
Request: PATCH /v2/subscriptions/4821
Credential: billing-service token
```

O rótulo da credencial deve aparecer depois do destino e da ação, não antes. O usuário deve saber o que a credencial fará antes de decidir se ela merece ser usada. Nunca fale o valor do token, nem mesmo em um rótulo exclusivo de acessibilidade. A tecnologia assistiva faz parte da interface do usuário, não é um canal privado paralelo para segredos.

## A redação precisa preservar o motivo para aprovar ou negar

A redação deve remover o material secreto e manter as partes da solicitação que alteram a decisão. As equipes frequentemente fazem o contrário. Escondem todos os parâmetros e dizem que protegeram a privacidade, enquanto o cartão de aprovação fica vago demais para impedir uma ação indevida.

Sempre suprima tokens bearer, senhas, material de chaves privadas, cookies, cabeçalhos de autorização, URLs assinadas e valores completos de campos que possam conter dados pessoais ou financeiros. Mascarar apenas o meio de um token geralmente é teatro. Um segredo parcial ainda pode ajudar um invasor a correlacionar ou reconstruir uma credencial e também incentiva os designers a expor demais nos registros.

Mantenha a estrutura. Para uma solicitação HTTP, mostre o método, o host, o caminho, o tipo de conteúdo, o tamanho do corpo quando ele fornecer uma noção útil de escala e os nomes dos campos sensíveis. Para um comando, mostre o executável, os argumentos, os arquivos ou serviços de destino e um marcador explícito para os argumentos redigidos. Uma pessoa que decide se deve enviar uma fatura precisa ouvir que a solicitação contém `recipient`, `amount` e `currency`; ela não precisa do endereço do destinatário nem do próprio valor se a política tratar esses dados como sensíveis.

Compare estes dois resumos falados:

```
POST request with protected details.
```

```
POST api.example.net/v1/payouts.
JSON fields: destination account redacted, amount redacted, currency visible.
This call uses the finance credential.
```

A segunda versão não revela os valores secretos, mas informa ao usuário que o agente está tentando fazer um pagamento, e não uma consulta de status inofensiva. Essa distinção é o objetivo de uma tela de consentimento.

Não crie um botão «mostrar segredo» dentro de um prompt de aprovação. O usuário pode precisar de mais contexto, mas a resposta é uma representação mais segura, não uma saída casual das barreiras do cofre. Se um operador realmente precisar inspecionar um valor protegido, encaminhe-o para um fluxo separado, com autenticação deliberada e regras de acesso claras. O cartão de aprovação deve continuar sendo uma superfície de decisão, não um navegador de segredos.

A redação também precisa sobreviver à cópia, à saída de acessibilidade e à projeção para auditoria. Se o rótulo visível disser «token redigido», mas o valor de acessibilidade do elemento contiver o cabeçalho original, o VoiceOver terá se tornado um caminho de exfiltração. Teste todas as representações do campo: texto visível, rótulo de acessibilidade, valor de acessibilidade, texto de ajuda, comportamento de copiar para a área de transferência e entrada no diário.

## A árvore de acessibilidade do diálogo deve refletir a decisão

O VoiceOver segue semântica de acessibilidade, não o caminho visual imaginado pelo designer. Construa a árvore de acessibilidade na mesma ordem da decisão e verifique-a com o leitor de tela, sem presumir que a disposição visual determina a navegação.

Use um contêiner real de diálogo ou alerta, com um título acessível e conciso como «Aprovação necessária». Mova o foco para dentro do diálogo quando ele abrir. O foco inicial deve ficar no resumo da decisão ou no primeiro campo de identidade, não em Aprovar. Se o sistema mover o foco diretamente para o botão padrão, ele criará um caminho rápido para um clique desinformado e obrigará o usuário a voltar pelo diálogo para entendê-lo.

Os controles nativos do macOS já fornecem grande parte do comportamento que as visualizações personalizadas precisam recriar. Mantenha a superfície nativa sempre que possível: texto estático para fatos, um controle de expansão padrão para detalhes opcionais, uma caixa de seleção somente quando o usuário puder alterar uma opção claramente explicada e botões comuns com rótulos distintos. Assim, um inspetor de acessibilidade terá mais chance de expor uma árvore que corresponda à interface.

A ordem pretendida deve ser legível como um esboço simples:

```
Dialog: Approval required
  Summary: New agent process requests authorization
  Group: Requesting process
    Static text: Signing authority, Example Software LLC
    Static text: Process, deploy-helper
  Group: Destination
    Static text: HTTPS, api.example.net
  Group: Requested action
    Static text: POST /v1/releases
  Group: Scope
    Static text: Approval lasts until this process exits
  Disclosure button: More redacted details, collapsed
  Button: Deny request
  Button: Approve this process
```

Este é um artefato de aceitação, não uma sugestão para colocar cada frase em um único rótulo de acessibilidade. Os grupos oferecem pontos de referência. O texto estático dentro de cada grupo oferece um lugar para o usuário retornar. A ordem deve permanecer estável, esteja o controle de detalhes recolhido ou expandido.

Dê nomes completos aos botões. «Aprovar» é fraco quando mais de um prompt de aprovação pode interromper o trabalho. «Aprovar este processo» e «Negar solicitação» continuam claros quando o VoiceOver os lê isoladamente. Se o cartão oferecer uma aprovação para uma única chamada e uma aprovação para a sessão, informe essa diferença no texto do botão ou na descrição acessível imediatamente anterior. Dois botões chamados «Permitir» com legendas visuais diferentes são um erro de design.

As orientações de acessibilidade da Apple para macOS pedem que os aplicativos forneçam rótulos, funções, valores e descrições que transmitam a finalidade de um controle. A palavra «finalidade» importa aqui. Um campo chamado «Destino» pode ter rótulo, função e valor, mas ainda obrigar o usuário a deduzir se ele nomeia um host, uma conta, um arquivo ou um comando. Prefira rótulos que tragam o substantivo ausente: «Host SSH», «Solicitação HTTP», «Credencial usada» e «Duração da aprovação».

Não anuncie uma parede de texto quando o diálogo abrir. Usuários do VoiceOver precisam de um ponto de partida claro, não de um parágrafo que impeça a interrupção e a inspeção de um item. Coloque o resumo curto na região do título ou logo depois dele e permita que os comandos normais de leitura percorram os fatos. Anuncie uma vez e em linguagem simples as mudanças importantes, como uma solicitação negada ou uma aprovação que expira quando o processo é encerrado.

## Cor e layout não podem carregar o alerta

Um cartão de aprovação passa no teste básico de acessibilidade somente quando uma pessoa consegue tomar a mesma decisão usando a ordem falada e os controles do teclado que usaria olhando para ele. Esse teste encontra mais do que falhas de contraste de cor. Ele identifica suposições ocultas sobre colunas, posição de ícones, foco padrão e agrupamento visual.

Faça este exercício com uma pessoa que use o VoiceOver regularmente, não apenas com um desenvolvedor que saiba onde cada elemento está. Inicie um novo processo de agente. Ative o VoiceOver. Mantenha o ponteiro longe dos controles. Peça à pessoa que responda a quatro perguntas antes de aprovar ou negar: quem fez a solicitação, onde ela atuará, o que fará e por quanto tempo a aprovação durará.

Depois, peça que ela execute esta sequência:

1. Encontre a aprovação recebida sem ajuda de uma pessoa que possa enxergar.
2. Leia a identidade do processo, o destino, a ação e o escopo nessa ordem.
3. Expanda os detalhes e identifique quais valores a interface redigiu.
4. Negue a solicitação, acione uma nova solicitação e aprove-a.
5. Confirme o que aconteceu depois de cada escolha e onde encontrar a ação registrada.

Registre a sequência realmente falada, incluindo rótulos repetidos, campos ignorados e saltos de foco. Uma avaliação visual pode não perceber uma ordem de acessibilidade ruim, porque o revisor vê a disposição pretendida e preenche as lacunas inconscientemente. Gravações da fala e transcrições escritas tornam o defeito difícil de contestar.

Teste estes casos separadamente:

- Um processo de agente assinado solicita a primeira aprovação da sessão.
- Um processo local sem assinatura faz a mesma solicitação.
- Uma credencial protegida exige confirmação para uma chamada depois que uma aprovação de sessão já existe.
- Uma solicitação contém cabeçalhos ou campos do corpo redigidos.
- Duas solicitações chegam próximas uma da outra, e o primeiro cartão desaparece depois da negação.

O último caso revela uma falha comum. Os desenvolvedores usam uma única visualização reutilizável e atualizam seus rótulos no lugar. Uma pessoa que está olhando percebe a mudança no cartão. O VoiceOver pode manter o foco em um botão enquanto o processo, o host e a ação por trás dele mudam. Trate uma solicitação materialmente diferente como um novo diálogo, com um novo resumo e um novo evento de foco. Nunca permita que um botão Aprovar existente adquira silenciosamente outro significado.

Teste também as configurações de movimento reduzido e texto ampliado. Essas configurações não alteram diretamente a semântica do VoiceOver, mas frequentemente acionam um código de layout alternativo. Se um layout compacto mover o texto do escopo para baixo dos botões ou remover um rótulo para economizar espaço, os usuários perderão informação justamente quando a configuração deles exigir uma interface mais tolerante.

## A aprovação da sessão precisa de um limite visível

Uma concessão de sessão só é segura quando a pessoa consegue saber exatamente qual processo em execução a recebeu e quando essa concessão termina. «Lembrar minha escolha» é a linguagem errada para um agente, porque soa como uma preferência duradoura, enquanto a decisão real deve estar vinculada à vida útil de um único processo.

Declare o limite no cartão: «Esta aprovação permite chamadas deste processo até que ele seja encerrado». Coloque essa informação depois da descrição da ação, onde ela responde à pergunta seguinte mais natural. Se o processo for encerrado e uma substituição for iniciada, mostre o cartão novamente. Um novo processo pode ter o mesmo nome de exibição, mas não recebeu a decisão anterior.

A autorização por sessão do Sallyport faz isso por padrão, e seu cartão de aprovação começa pela autoridade de assinatura de código do processo. Esse é um ponto de partida útil, mas o cartão ainda precisa tornar o destino, a ação e a duração igualmente claros para uma pessoa que usa o VoiceOver.

A aprovação por chamada tem outra finalidade. Use-a para credenciais individuais em que cada uso tenha uma consequência independente, como um pagamento, uma exclusão em produção ou um comando SSH que altere o estado de um serviço. A confirmação precisa declarar esse fato: «Esta credencial exige aprovação a cada uso». Não esconda a condição em uma tela de configurações para depois surpreender o usuário com um prompt extra.

Evite a recomendação popular de colocar todas as decisões atrás de um único botão amplo «permitir este agente». As pessoas gostam dele porque mantém o trabalho autônomo em andamento. Ele também transforma identidade, alvo e duração em uma promessa de que o agente se comportará. Essa promessa não tem um significado de segurança útil quando o agente segue outra instrução ou chega a outro serviço. Uma concessão de sessão limitada, combinada com confirmação seletiva por chamada, pede que a pessoa avalie uma solicitação real.

A barreira do cofre fica fora dessa escolha. Quando o cofre está bloqueado, o sistema deve negar as ações diretamente, em vez de apresentar um cartão de aprovação que sugira que um clique pode contornar o bloqueio. Uma ação do Touch ID pode desbloquear ou confirmar quando o produto oferecer esse recurso, mas a interface falada precisa dizer qual evento ocorreu. «Aprovado» e «cofre desbloqueado» são mudanças de estado diferentes e nunca devem compartilhar um anúncio ambíguo.

## Os registros de auditoria precisam permitir reconstruir uma decisão depois

Um fluxo de aprovação fica incompleto se o operador não consegue descobrir depois qual solicitação aprovou, qual ação veio em seguida e se o registro foi alterado. O cartão imediato cuida do consentimento. A trilha de auditoria cuida da discussão que surge depois, muitas vezes quando ninguém se lembra do que apareceu na tela.

Mantenha o evento da sessão e o evento da ação individual separados. Um registro de sessão deve identificar a execução do agente, sua decisão de autorização e a revogação ou o encerramento. Um registro de atividade deve identificar cada chamada HTTP ou SSH, seu destino, sua operação, seu resultado e as mesmas regras de redação usadas na visualização de aprovação. Misturar tudo em uma entrada vaga «agente permitido» elimina a ligação entre consentimento e consequência.

Para um diário criptografado com encadeamento por hash, a verificação deve ser uma ação separada e inspecionável. O formato esperado é simples:

```
$ sp audit verify
Verifying encrypted audit log...
Chain verified: 184 records
Result: valid
```

A quantidade exata de registros varia, mas o comando deve informar ao operador se a verificação foi concluída ou falhou e deve falhar de modo explícito quando encontrar uma cadeia quebrada. Verificar o texto cifrado é importante porque um revisor pode conferir a integridade do registro sem primeiro desbloquear o cofre apenas para ler as evidências de auditoria. Isso não prova que uma ação aprovada foi sensata. Prova que a sequência retida não foi alterada silenciosamente.

Construa o cartão de aprovação e os diários a partir do mesmo vocabulário de eventos. Se o cartão disser «solicitação HTTPS para billing.example.net» enquanto o diário a chamar de «operação remota 12», o usuário não conseguirá associar a decisão ao registro. Reutilize o destino, a ação, a identidade do processo, o escopo e as categorias de redação, mesmo que cada superfície os apresente com um nível diferente de detalhe.

Ofereça aos usuários do VoiceOver um caminho igualmente direto até o registro. Depois da aprovação ou negação, anuncie o resultado e forneça um caminho rotulado para a entrada de sessão ou atividade relevante. Não faça um ponto colorido de status carregar a prova de que uma ação ocorreu. Quem ouve «Solicitação negada. Registro de atividade disponível» pode conferir o resultado depois sem reconstruir a interface de memória.

## As regressões de acessibilidade pertencem ao conjunto de testes de segurança

Trate a sequência falada de aprovação como um contrato de segurança e teste-a sempre que o cartão, o canal de ação ou o modelo de identidade mudar. Um snapshot que confirme a existência de um título e dois botões não detectará um destino que foi movido para baixo dos controles nem um campo redigido que vazou por meio de um valor de acessibilidade.

Mantenha um pequeno conjunto de fixtures com solicitações intencionalmente difíceis: uma autoridade de assinatura longa, um processo sem assinatura, um nome de host internacionalizado, uma porta não padrão, um redirecionamento para outro host, um alias SSH e um corpo com nomes de campos sensíveis. Cada fixture deve produzir um esquema de acessibilidade esperado e uma representação esperada no diário. Quando um designer alterar o layout visual, compare essas saídas antes de considerar o trabalho concluído.

Uma revisão prática faz quatro perguntas diretas. Um usuário do VoiceOver consegue identificar o executável e o assinante? Consegue identificar o destino remoto final? Consegue distinguir entre esta chamada e a duração deste processo? Consegue aprovar ou negar e ouvir um resultado claro depois? Se alguma resposta depender de enxergar cor, espaçamento ou um ícone, o prompt ainda tem um defeito de segurança.

Faça o primeiro teste com a credencial de maior consequência e a solicitação menos cooperativa permitida pelo produto. Um GET amigável para um host conhecido faz qualquer cartão de aprovação parecer bom. O pedido que revela o design é o de um processo assinado desconhecido tentando modificar um serviço real, com partes do corpo redigidas. É nesse ponto que a redação, a ordem e o comportamento do foco permitem que uma pessoa exerça controle ou a reduzam a clicar em uma barreira.