Como um cartão de aprovação de API mostra o destino real

Um revisor não pode aprovar uma ação HTTP a partir de uma string que apenas parece um destino. O cartão precisa mostrar o destino de solicitação que o transporte realmente usará, depois da análise e antes que as credenciais saiam da máquina.

Isso parece óbvio até que um agente envie HTTPS://API.EXAMPLE.TEST:443/%76%31/../admin, um cliente aceite a URL e a pessoa veja um rótulo encurtado como api.example.test. Um cartão assim não pede consentimento informado. Ele pede que a pessoa confie em um renderizador que pode discordar da pilha HTTP.

A solução não é ensinar aos revisores todos os detalhes da sintaxe de URL. É criar uma única descrição canônica da solicitação, exibi-la de forma clara e garantir que o executor use essa mesma descrição. Esquema, host, porta efetiva, método e caminho são o mínimo. Valores de consulta, redirecionamentos, cabeçalhos controlados pelo chamador e identidade do corpo muitas vezes também precisam aparecer, pois podem alterar a ação de forma igualmente significativa.

Como um cartão de aprovação conquista um sim

Um cartão de aprovação conquista um sim somente quando identifica a ação de rede em termos que o revisor consegue verificar. Um nome de host sozinho é uma afirmação de identidade, não uma descrição da solicitação. POST https://billing.example.test/v1/invoices/481/refund informa muito mais do que billing API ou example.test.

Coloque a linha da ação primeiro, sempre na mesma ordem:

POST https://billing.example.test/v1/invoices/481/refund

Em seguida, coloque logo abaixo os detalhes que alteram o significado:

Authorization: injected from vault entry "billing-production"
Query: dry_run=false
Body: JSON, 214 bytes, sha256: 7b1f...c0a9

Não coloque o valor da credencial, um marcador de autorização ou o nome amigável de uma integração no lugar do destino. Esses rótulos podem ajudar o revisor a reconhecer o contexto, mas não comprovam o destino.

O método deve aparecer na primeira linha porque altera a consequência do mesmo caminho. GET /exports/481 e DELETE /exports/481 não são variações de uma única ação. São ações diferentes e nunca devem ser reduzidas ao mesmo rótulo de aprovação.

O caminho deve aparecer na primeira linha porque normalmente é nele que vive o roteamento da API. Um cartão que exibe api.example.test obriga o revisor a deduzir se o agente está lendo um perfil, criando um token de acesso ou excluindo um projeto. Uma interrupção de aprovação não deve exigir esse esforço.

Canonização é um contrato de exibição, não uma correspondência de permissões

A canonização responde a «O que uma pessoa deve ver para esta solicitação analisada?». Ela não responde a «Quais destinos são permitidos?». As equipes costumam misturar essas funções e acabam criando uma lista de permissões frágil disfarçada de formatação amigável.

Para um cartão de aprovação, crie um registro estruturado do destino depois da análise:

{
  "method": "POST",
  "scheme": "https",
  "host": "api.example.test",
  "port": 443,
  "port_display": null,
  "path": "/v1/invoices/481/refund",
  "query": "dry_run=false",
  "raw_url": "HTTPS://API.EXAMPLE.TEST:443/v1/invoices/481/refund?dry_run=false"
}

O executor deve receber esses mesmos campos, ou uma URL serializada a partir deles. Não analise uma vez para o cartão e depois passe a string original para outra biblioteca. É nessa divisão que uma tela de revisão vira encenação.

A RFC 3986 distingue várias categorias seguras de normalização. Ela trata o esquema e o host como elementos que não diferenciam maiúsculas e minúsculas, recomenda dígitos hexadecimais em maiúsculas nos escapes percentuais e descreve a remoção de segmentos de ponto. Também alerta que o código deve analisar os componentes da URI antes de decodificar octetos com escape percentual, pois decodificar no momento errado pode transformar dados em delimitadores. Esse alerta é uma orientação prática de engenharia, não um detalhe acadêmico da especificação.

Mantenha um segundo registro para a entrada bruta do agente. Ele pertence ao registro de atividades e a uma visão de detalhes para investigações de solicitações incomuns. Não deve disputar com a linha canônica da ação pela atenção do revisor.

Uma regra útil é simples: o cartão exibe uma descrição normalizada, o diário preserva a descrição e a entrada, e as decisões de autorização não usam nenhuma delas como substituta de regras de escopo explícitas. São produtos de dados separados.

Analise primeiro e rejeite entradas que o transporte não consegue explicar

Um analisador de URL faz parte da fronteira de segurança assim que uma pessoa aprova sua saída. Escolha um comportamento de análise para os esquemas de URL aceitos e faça dele a fonte de verdade tanto para a exibição quanto para a execução.

Para APIs HTTP comuns, rejeite entradas ambíguas em vez de tentar ser prestativo. Referências relativas precisam de uma URL base explícita para ter um host. Fragmentos não são enviados em uma solicitação HTTP e não devem aparecer como se influenciassem o servidor. Informações de usuário, como https://[email protected]/, quase sempre induzem ao erro em um fluxo de aprovação de API e devem ser rejeitadas, não ocultadas silenciosamente.

Use um fluxo de análise com um ponto de falha claro:

1. Aceite somente uma URL absoluta http ou https para o canal de API de saída.
2. Analise a URL com a implementação escolhida pelo executor da ação.
3. Rejeite informações de usuário, host ausente, valores de porta malformados, esquemas não compatíveis e escapes percentuais inválidos.
4. Construa a solicitação real a partir dos componentes analisados e dos cabeçalhos aprovados.
5. Renderize o cartão a partir desses componentes e envie exatamente essa solicitação.

Não faça isso manualmente com divisões de strings. O primeiro @, :, /, ? e # não têm o mesmo significado em todas as posições. Autoridades IPv6 precisam de colchetes. Um dois-pontos depois de um colchete pode introduzir uma porta, enquanto os dois-pontos dentro dos colchetes fazem parte do endereço. Um analisador conhece essa distinção; uma expressão regular curta geralmente não.

O WHATWG URL Standard define o comportamento de análise e serialização de URLs, hosts, domínios e endereços IP. Suas orientações de segurança também destacam a confusão que o texto bidirecional pode criar entre host e caminho e recomendam exibir apenas o host nessa situação. Um produto de segurança deve adotar a lição mais rigorosa: manter a autoridade visualmente separada do caminho em todos os cartões, não apenas em strings incomuns.

Se a camada de ação tiver um cliente personalizado, prove que ele concorda com o analisador usando um corpus de testes. Não presuma que duas bibliotecas maduras toleram de forma idêntica espaços, barras invertidas, nomes de host Unicode ou formatos numéricos incomuns de IP. A concordância é uma propriedade que deve ser testada.

Decodifique escapes percentuais sem alterar a rota

A codificação percentual cria o tipo mais perigoso de URL enganosa: uma que parece inofensiva depois de uma decodificação casual, mas significa outra coisa para o roteador, o proxy ou o serviço upstream.

Considere estes caminhos:

/v1/projects/%2E%2E/admin
/v1/projects/%252E%252E/admin
/v1/files/report%2Ffinal

O primeiro contém pontos codificados em percentual. O segundo contém um sinal de porcentagem codificado seguido de 2E, o que não é a mesma entrada. O terceiro contém uma barra codificada dentro de um segmento do caminho. Se uma camada de exibição decodificar os três repetidamente até chegar a uma pontuação legível, poderá mostrar uma estrutura de caminho que o cliente não enviou.

A RFC 3986 oferece um caso seguro restrito: escapes percentuais de caracteres não reservados podem ser decodificados durante a normalização. Caracteres não reservados são letras, dígitos, hífen, ponto, sublinhado e til. Caracteres reservados como /, ?, #, @ e : devem continuar codificados quando sua decodificação alterar limites de componentes ou delimitadores. A RFC também diz que uma implementação não deve codificar ou decodificar a mesma string mais de uma vez.

Isso produz uma boa regra de exibição:

Raw path:       /v1/%75sers/alice%7Eops/report%2Ffinal
Card path:      /v1/users/alice~ops/report%2Ffinal
Wire path:      /v1/users/alice~ops/report%2Ffinal

O cartão torna %75 e %7E legíveis porque representam caracteres não reservados. Mantém %2F visível porque uma barra alteraria a estrutura dos segmentos do caminho. A forma do cartão e a forma enviada pela rede podem diferir de maneira inofensiva, mas devem manter o mesmo significado de roteamento.

Não remova segmentos de ponto depois de decodificar o caminho indiscriminadamente. Analise o caminho em sua estrutura codificada, aplique um procedimento de normalização definido e preserve os escapes que carregam caracteres reservados como dados. Se o serviço downstream aplicar uma ordem de decodificação diferente, isso é um problema de compatibilidade e segurança que merece ser exposto nos testes, não um motivo para o cartão adivinhar.

Um nome de host não é toda a autoridade

A autoridade de um destino HTTP inclui o host e, quando não é padrão, a porta. Omitir a porta faz o cartão de revisão mentir por omissão.

Trate estes destinos como diferentes:

https://api.example.test/v1/keys
https://api.example.test:8443/v1/keys
http://api.example.test/v1/keys

O primeiro normalmente usa a porta 443. O segundo usa a porta 8443. O terceiro usa um esquema diferente e normalmente a porta 80. Um revisor pode aceitar uma chamada de produção por HTTPS e rejeitar uma solicitação para um listener de testes em uma porta personalizada. O cartão precisa permitir essa decisão.

Converta o esquema e o nome do host para minúsculas. Omita a porta somente quando ela for a porta padrão do esquema analisado: 80 para http e 443 para https. Não omita uma porta porque um registro DNS por acaso leva a um local conhecido.

Nomes de domínio internacionalizados exigem o mesmo cuidado. Uma forma Unicode amigável pode ser mais fácil de ler, enquanto a forma usada pelo DNS contém rótulos ASCII. Se você exibir Unicode, mostre também a forma ASCII nos detalhes e use um analisador que aplique um algoritmo definido de processamento de hosts. Não invente sua própria conversão para punycode nem compare strings exibidas para decidir equivalência.

Literais de IP merecem tratamento próprio. Exiba colchetes ao redor de endereços IPv6, preserve uma porta não padrão e identifique o endereço como um literal de IP. Uma solicitação para https://[2001:db8::9]/v1/keys não deve parecer um serviço de produção identificado por nome só porque o agente forneceu um alias agradável em um campo de observação.

Aliases criam outro problema. api.internal, api e 10.0.0.9 podem chegar ao mesmo servidor hoje e divergir depois de uma alteração no DNS. Não reescreva silenciosamente um no outro para fins de aprovação. Mostre a autoridade analisada solicitada pelo cliente. Se o sistema resolver o DNS antes de abrir uma conexão, mostre o endereço selecionado como contexto de conexão e registre-o na trilha de auditoria. A autoridade continua sendo o elemento nomeado pela solicitação HTTP.

O HTTP deixa essa distinção explícita. A RFC 9110 diz que o campo Host fornece informações de host e porta da URI de destino, enquanto HTTP/2 e HTTP/3 podem transportar essas informações em :authority. A RFC 9113 diz que um intermediário que gera Host a partir da autoridade HTTP/2 deve usar :authority, a menos que altere o destino da solicitação. Portanto, um cartão deve tratar um campo de autoridade fornecido pelo chamador como material de roteamento, não como metadado decorativo.

Método e caminho precisam de destaque visual próprio

Coloque o método HTTP, a autoridade e o caminho juntos, pois os revisores leem a ação como uma frase. Depois, dê ao método e aos segmentos perigosos do caminho contraste suficiente para que uma olhada rápida não os transforme em uma URL longa e indistinta.

Este layout funciona porque mantém as partes em uma ordem estável:

DELETE
https://api.example.test/v1/projects/acme/production

Para uma solicitação que altera um objeto, inclua o identificador no caminho visível. Truncar o final de /v1/projects/acme/production para caber no cartão é uma inversão de prioridades. Se o espaço for limitado, trunque primeiro valores de consulta longos ou prévias do corpo, nunca o segmento final do caminho que identifica o destino.

As maiúsculas e minúsculas devem ser preservadas no caminho. A RFC 3986 diz que a sintaxe genérica de URI trata os componentes diferentes do esquema e do host como sensíveis a maiúsculas e minúsculas, salvo indicação contrária do esquema. Muitos frameworks fazem o roteamento dessa forma, mesmo quando uma API específica não faz. Transformar /Admin/DeleteUser em /admin/deleteuser cria uma afirmação sobre uma solicitação que nunca foi feita.

Um caminho de solicitação também pode parecer inofensivo enquanto a consulta altera o efeito:

POST https://api.example.test/v1/invoices/481/refund?dry_run=false
POST https://api.example.test/v1/invoices/481/refund?dry_run=true

Mostre um resumo curto da consulta abaixo da linha da ação quando os parâmetros alterarem escopo, comportamento ou identidade. Para consultas não estruturadas ou muito longas, mostre a consulta codificada completa em uma área expansível de detalhes e um resumo decodificado e ocultado no cartão principal. Nunca decodifique um token até transformá-lo em um segredo legível apenas porque o cartão quer ser amigável.

O corpo da solicitação pode importar ainda mais do que o caminho. Uma aprovação para PATCH /v1/users/alice diz pouco se o corpo puder conceder uma função de administrador. Mostre, no mínimo, o tipo de conteúdo, o tamanho em bytes e um resumo estável. Para formatos estruturados como JSON, uma pequena prévia dos campos alterados pode ajudar, desde que a prévia venha dos mesmos bytes que serão enviados pela rede. Re-serializar um objeto para exibição depois de assinar ou calcular o hash de uma sequência diferente de bytes cria o mesmo problema de divisão que reaparecer ao analisar URLs.

Cabeçalhos e redirecionamentos podem alterar o destino da solicitação

Uma URL canônica não salva um fluxo de aprovação se outro campo da solicitação puder redirecionar a conexão. O cartão precisa restringir esses campos ou exibir seus efeitos.

Comece com Host e :authority. Um cliente HTTP normalmente os deriva da URL de destino. Se uma interface de ação permitir que o chamador os substitua, rejeite a substituição, a menos que o transporte tenha um motivo documentado para aceitá-la. Se você aceitar, a linha de aprovação precisa mostrar tanto o destino da conexão quanto a autoridade solicitada, em termos que uma pessoa possa comparar.

A configuração de proxy merece o mesmo tratamento. Um proxy altera o peer imediato, mas não necessariamente o destino de origem. Não substitua a origem pelo endereço do proxy no cartão. Mostre a origem como a ação aprovada e o proxy como contexto de transporte. Se o proxy puder reescrever campos de destino, trate-o como um componente do executor, com testes, logs e uma decisão de confiança separada.

Redirecionamentos são ações novas quando seu destino muda. Um POST pode se tornar um GET conforme o comportamento do redirecionamento, ou ser reenviado para uma nova autoridade. A aprovação original deve abranger somente o destino original. Antes de seguir um redirecionamento, analise o valor de Location, construa a próxima solicitação proposta, compare esquema, autoridade, método, caminho, consulta e comportamento do corpo e peça uma nova aprovação se algo significativo mudar.

Evite o atalho popular de aprovar um «site» durante toda a execução e tratar todos os redirecionamentos abaixo dele como inofensivos. Isso parece reduzir as interrupções, mas transforma a análise de URL e a política de redirecionamento em uma expansão invisível de privilégios. Se a execução precisar de uma permissão ampla, deixe esse escopo explícito no texto da aprovação em vez de permitir que os redirecionamentos o introduzam de forma indireta.

Coloque a entrada bruta no registro, não na linha de decisão

Uma trilha de auditoria precisa de detalhes suficientes para responder a duas perguntas diferentes: o que o agente solicitou e o que o executor tentou fazer? Uma única string de URL nem sempre responde às duas.

Registre a string bruta da URL exatamente como foi recebida, sujeita às regras de ocultação de segredos. Registre o destino canônico separadamente. Adicione a autoridade final da conexão e o endereço resolvido se o executor tiver feito a resolução. Para HTTP/2 ou HTTP/3, registre a :authority efetiva; para HTTP/1.1, registre o valor efetivo de Host. Registre os saltos de redirecionamento como solicitações tentadas individuais, não como uma nota de rodapé na primeira chamada.

Uma entrada do diário pode ter este formato:

{
  "request_id": "req_01J...",
  "agent_input_url": "HTTPS://API.EXAMPLE.TEST:443/v1/%75sers/alice%7Eops",
  "approved_target": "GET https://api.example.test/v1/users/alice~ops",
  "effective_authority": "api.example.test",
  "effective_port": 443,
  "connection_ip": "203.0.113.42",
  "result": "200"
}

O exemplo usa um intervalo de endereços reservado para documentação no IP de conexão. Em um log real, proteja segredos de consulta, material de autorização e corpos sensíveis antes que os dados cheguem a qualquer registro de longa duração. Um resumo ajuda a relacionar o conteúdo aprovado ao conteúdo executado sem copiar cargas privadas para todas as telas.

A distinção entre entrada bruta e destino canônico é valiosa durante uma investigação. Se um cartão mostrou um caminho normal, mas a entrada bruta continha camadas de codificação, você pode descobrir se houve divergência entre o analisador, o renderizador ou o cliente HTTP. Se armazenou apenas uma URL bonita, perdeu as evidências necessárias para encontrar o defeito.

O diário de atividades e o diário de sessões do Sallyport são projeções de um único log de auditoria criptografado e encadeado por hash. Portanto, a representação do destino deve ser gravada uma vez como parte do registro da ação, em vez de ser reconstruída depois a partir de strings da interface. A verificação offline sp audit verify só é útil se os campos registrados da ação eram honestos no momento da execução.

Teste as divergências que URLs comuns nunca revelam

Os testes unitários importantes não são dez exemplos comuns de https://api.example.test/v1/users. São casos em que uma string bruta, um renderizador de cartões e uma biblioteca de transporte poderiam discordar.

Crie um corpus orientado por tabela que verifique os campos analisados, o destino visível, o destino enviado pela rede e a decisão. Inclua pelo menos estas famílias:

• alterações de maiúsculas e minúsculas no esquema e no host, com portas padrão e não padrão;
• segmentos de ponto e escapes percentuais para caracteres reservados e não reservados;
• sinais de porcentagem e barras codificados, além de sequências de escape malformadas;
• literais IPv6, entrada de host Unicode e informações de usuário que devem ser rejeitadas;
• valores de consulta que alteram o comportamento da ação, além de destinos de redirecionamento em outra autoridade.

Um caso de teste deve tornar explícita a representação esperada:

{
  "input": "HTTPS://API.EXAMPLE.TEST:443/v1/%75sers/alice%7Eops?role=viewer",
  "decision": "approve",
  "card": "GET https://api.example.test/v1/users/alice~ops?role=viewer",
  "wire_url": "https://api.example.test/v1/users/alice~ops?role=viewer"
}

Depois, adicione casos negativos que devem falhar antes da aprovação:

{
  "input": "https://[email protected]/v1/users",
  "decision": "reject",
  "reason": "userinfo is not supported for outbound API actions"
}

Execute o corpus pelo código exato do cliente que abre a conexão. Uma suíte de testes apenas do analisador detecta erros de exibição, mas não comportamentos de transporte, como uma biblioteca normalizar um caminho vazio, inserir uma autoridade padrão ou aplicar suas próprias regras de redirecionamento.

Por fim, teste a interface como um revisor a utiliza. Confirme que o método completo, o host, a porta quando presente e o segmento final do caminho continuam visíveis em tamanhos comuns de janela. A comunicação de segurança falha quando a pessoa precisa passar o mouse, expandir ou rolar a tela para descobrir que uma solicitação exclui dados de produção. O cartão deve tornar a diferença importante visível antes que o botão de aprovação receba foco.

Uma aprovação humana pode ser um controle forte, mas só será tão forte quanto a descrição da solicitação colocada diante da pessoa. Crie essa descrição a partir de componentes analisados, execute esses componentes, preserve a entrada bruta para análise posterior e rejeite ambiguidades em vez de decorá-las.