Como repositórios de cookies de agentes mantêm sessões que você não pretendia

Clientes HTTP fazem os cookies parecerem inofensivos, porque os navegadores nos acostumaram a esperá-los. Um agente autônomo muda a consequência. Uma resposta que traz Set-Cookie pode conceder à próxima solicitação uma autorização que o agente nunca pediu, nunca exibiu e talvez mantenha mesmo depois que a credencial original mudar.

Trate um repositório de cookies como um armazenamento de autenticação, não como um detalhe de transporte. Se uma API exige sessões por cookie, dê ao repositório um proprietário nomeado, vida curta e um limite observável. Se não exige, desative-o. Já vi investigações de incidentes demais começarem com alguém insistindo que a solicitação não tinha credencial, enquanto o cliente enviava uma silenciosamente no cabeçalho Cookie.

Um cabeçalho Set-Cookie pode virar uma segunda credencial

Um servidor envia Set-Cookie em uma resposta; um cliente que possui um repositório pode enviar esse valor depois em um cabeçalho Cookie. Quando o valor identifica uma sessão no servidor, ele é uma credencial na prática. O fato de chegar após uma solicitação autenticada não o torna menos capaz de autorizar a próxima.

Isso surpreende as equipes porque elas focam no segredo que forneceram deliberadamente: um token de portador, uma senha de autenticação básica ou uma solicitação assinada. Elas revisam de onde vem esse segredo e se ele chega ao agente. Então, uma biblioteca HTTP aceita um cookie de sessão sem uma linha explícita de código da aplicação. A próxima solicitação pode funcionar depois que o cabeçalho Authorization original desaparecer.

A distinção importante está entre injeção de credencial e continuidade de sessão. A injeção de credencial anexa um segredo conhecido a uma solicitação. A continuidade de sessão permite que o servidor emita um novo segredo e pede que o cliente o repita depois. Ambos podem autorizar trabalho. Normalmente, apenas um deles aparece nos argumentos de chamada de uma ferramenta.

A RFC 6265 descreve essa troca como gerenciamento de estado: o agente de usuário armazena informações de cookies de Set-Cookie e devolve os cookies aplicáveis em Cookie. A redação é propositalmente ampla porque navegadores precisam disso. Um cliente de agente não deve herdar o hábito do navegador de manter estado apenas porque o protocolo HTTP permite.

Um cookie também muda o sentido de uma rotação de token que falhou. Imagine que um agente chame uma API com um token, receba sid=... e depois perca acesso a esse token. Se a API aceitar o cookie de sessão por si só, o agente ainda terá um caminho até a conta. A rotação corrigiu a credencial conhecida, mas não encerrou a sessão emitida. Essa é uma questão de gerenciamento de sessão no servidor e de contenção no cliente. É preciso lidar com ambas.

O cliente decide se existe estado oculto

Set-Cookie não faz nada sozinho. Um cliente precisa escolher retê-lo. Essa escolha pode se esconder em muitos lugares: um cliente HTTP reutilizável, o gerenciador de cookies de uma biblioteca, um adaptador em torno de fetch, um ambiente de testes ou uma implementação de redirecionamento.

Alguns clientes comuns não retêm cookies a menos que você forneça um repositório. Outros os retêm quando o código anexa um manipulador de cookies padrão. Um cliente compartilhado pode, então, tornar o repositório compartilhado por acidente. Não deduza o comportamento pela documentação da API ou pelo fato de uma chamada ter funcionado. Inspecione a construção do cliente e execute uma verificação.

Um teste limpo usa um servidor que você controla ou um endpoint de teste inofensivo. A primeira resposta deve definir um cookie com nome claro, e a segunda solicitação deve informar os cabeçalhos que recebeu. O resultado precisa responder a duas perguntas distintas:

1. O cliente reteve o cookie depois de receber Set-Cookie?
2. O cliente enviou esse cookie em uma solicitação elegível posterior?

Com curl, um arquivo de cookies explícito torna o estado visível:

curl -i -c /tmp/agent-cookie-test.txt https://test.example/session/start
HTTP/1.1 200 OK
Set-Cookie: agent_probe=run-7f3; Path=/; Secure; HttpOnly

curl -i -b /tmp/agent-cookie-test.txt https://test.example/session/echo
HTTP/1.1 200 OK

{"received_cookie":"agent_probe=run-7f3"}

O arquivo é o ponto do exercício. O primeiro comando não pode criar uma sessão oculta, a menos que algo retenha sua resposta. O segundo não pode repetir uma sessão, a menos que receba o arquivo. Se as ferramentas do seu agente derem ao equivalente desse arquivo um local global do processo sem nome, você criou um limite de sessão que ninguém consegue avaliar durante uma revisão.

Repita a verificação usando o caminho exato de execução que seu agente usa, incluindo seu adaptador de solicitações e as configurações de redirecionamento. Um teste direto com curl comprova o curl, não a sua ferramenta. Registre se o repositório começa vazio, onde ele fica e o que o limpa.

Reutilizar entre chamadas é diferente de reutilizar entre execuções

Algumas chamadas dentro de uma tarefa podem precisar compartilhar uma sessão. Reutilizar essa sessão em uma tarefa posterior é outra decisão. Juntar esses dois períodos é como uma pequena conveniência vira autorização persistente.

Use três limites ao avaliar o comportamento. Primeiro, pergunte se uma única solicitação precisa de cookies. Segundo, pergunte se chamadas relacionadas em um processo de agente precisam deles. Terceiro, pergunte se um processo novo, uma tarefa retomada, outra credencial ou outra pessoa deveria herdá-los. Cada resposta positiva precisa de uma razão declarada.

Um repositório em memória, que desaparece com o processo, é mais fácil de conter que um arquivo em um diretório do projeto. Um arquivo pode sobreviver a uma falha, uma nova tentativa, uma cópia do espaço de trabalho ou uma mudança de quem executa a tarefa. Ele também pode parar em um arquivo de suporte ou na saída de status do controle de versão. HttpOnly não protege um arquivo de cookies contra o cliente que o gravou; limita apenas o acesso por scripts do navegador.

Prefiro um repositório novo para cada execução de agente, mesmo quando o mesmo modelo recebe um prompt de acompanhamento. A continuidade da conversa do modelo não é motivo para reter autorização HTTP. Se o acompanhamento realmente precisa da sessão, faça o operador aprovar uma execução continuada sob o mesmo limite nomeado, em vez de deixar silenciosamente a última execução para trás com uma sessão utilizável.

Chamadas concorrentes também precisam de decisão própria. Um repositório compartilhado pode criar comportamento dependente da ordem: a solicitação A recebe um cookie, a solicitação B começa instantes depois e B ganha uma sessão que nunca estabeleceu. Isso torna a reprodução penosa. Dê repositórios separados às tarefas concorrentes, a menos que a API exija uma sessão coordenada e a tarefa a controle explicitamente.

O escopo do cookie não corresponde à segurança que as pessoas imaginam

Os atributos de cookies limitam a entrega, mas não tornam uma sessão inofensiva. Leia-os como instruções de roteamento do servidor para o cliente e então decida se o cliente deve respeitá-los.

Um cookie apenas de host volta ao host exato que o emitiu. Um cookie com Domain=example.com pode voltar a subdomínios elegíveis, como api.example.com e admin.example.com. A RFC 6265 também diz que um agente de usuário rejeita um valor Domain que não corresponda ao domínio do host de origem, mas isso não resolve o erro comum de confiar em todo subdomínio de um domínio corporativo amplo.

Path=/billing limita um cookie a solicitações cujos caminhos correspondem ao caminho do cookie. Ele não impede que um servidor em outro caminho permitido aceite o mesmo cookie se o receber por outra rota, nem substitui verificações de autorização. Não use Path como limite de segurança em discussões de arquitetura. É uma regra de envio do cliente.

Secure diz ao cliente para enviar o cookie apenas por transporte seguro. HttpOnly diz a um navegador para não expô-lo por APIs de script. Ambos são boas práticas, mas nenhum limita retenção, compartilhamento entre tarefas, redirecionamentos ou a capacidade do agente de usar o cookie. SameSite rege principalmente o contexto de sites no navegador; um agente que não é navegador não deve usá-lo como prova de que o comportamento entre sites é seguro.

Há outro erro fácil: registrar cabeçalhos brutos durante a depuração. Um redator que remove Authorization, mas deixa Cookie, não ocultou a autenticação. Registre a presença de um cookie, seu nome, Domain e Path declarados, tipo de expiração e um identificador de correlação irreversível, se precisar de um. Não registre o valor.

Redirecionamentos transformam o teste de cookies em um teste de destino

Um redirecionamento não é apenas uma URL diferente. Ele pode mudar qual servidor vê a próxima solicitação, se as credenciais são mantidas e qual resposta pode definir estado. Teste-o como um fluxo próprio.

Comece com um endpoint que retorna um redirecionamento depois de definir um cookie. Depois, teste cada destino separadamente: o mesmo host, um subdomínio permitido, um subdomínio irmão e um host sem relação. Observe tanto o Cookie de saída quanto o Authorization de saída. Diferentes pilhas HTTP fazem escolhas distintas, e um adaptador pode substituir os padrões.

Uma configuração útil produz um rastreamento curto como este:

request 1  GET https://api.example.test/start
response 1  302 Location: https://api.example.test/next
            Set-Cookie: probe=A; Path=/; Secure
request 2  GET https://api.example.test/next
            Cookie: probe=A
response 2  200

Em seguida, altere apenas o host de Location. Se api.example.test redirecionar para reports.example.test, um cookie apenas de host não deve segui-lo. Um cookie com escopo de Domain pode seguir. Seu teste deve declarar o resultado esperado antes de rodar, porque um rastreamento que surpreende é o objetivo, não um incômodo a encobrir.

Rejeite redirecionamentos entre origens quando o contrato da API não exigir isso. Se precisar segui-los, compare as origens antiga e nova, remova as credenciais da solicitação segundo uma regra explícita e deixe uma resposta nova estabelecer qualquer estado de cookie. Nunca use uma política ampla de redirecionamento automático e suponha que o escopo do cookie salvará você.

Um teste de sessão precisa atravessar credenciais e processos

O teste que encontra o erro caro não é solicitação um, solicitação dois. Ele atravessa os limites que seu modelo operacional afirma impor.

Crie um endpoint inofensivo que emita um cookie apenas depois de receber um rótulo de credencial escolhido. Faça-o retornar o rótulo da sessão em toda solicitação autorizada. Em seguida, execute esta sequência:

1. Inicie a execução A com a credencial A e receba sid=A.
2. Faça uma segunda chamada sem a credencial A, mas com o mesmo repositório.
3. Inicie a execução B com a credencial B e um repositório vazio.
4. Inicie a execução C sem credencial e com qualquer repositório persistido da execução A.
5. Revogue a credencial A ou invalide sua sessão no servidor de teste, então tente novamente o repositório da execução A.

A saída esperada é uma decisão de política, não uma resposta universal. Uma API baseada em cookies pode permitir intencionalmente a segunda chamada dentro da execução A. A execução B não deve ver o estado de A. A execução C deve falhar, a menos que você tenha aprovado a persistência de forma explícita. Após a revogação, o servidor de teste deve rejeitar a sessão antiga se seu modelo de ameaça disser que a rotação de token precisa remover o acesso ativo.

Escreva a expectativa ao lado do teste, em vez de enterrá-la na memória de um desenvolvedor. Uma tabela concisa em um comentário de teste funciona:

run A, same jar, no bearer header: allowed only if session continuation is intended
run B, fresh jar, credential B: must identify as B
run C, persisted jar, no credential: rejected
run A after session invalidation: rejected

Isso revela uma distinção que as equipes costumam confundir: revogar uma credencial inicial e revogar sessões emitidas não são a mesma operação. O responsável pela API precisa invalidar as sessões. O responsável pela ferramenta do agente precisa evitar preservá-las além do período aprovado. Nenhum lado pode supor que o outro cuidou disso.

Desative repositórios implícitos, a menos que a API precise de um

O padrão sensato para uma ação HTTP de agente é não armazenar cookies e não ter cabeçalho Cookie automático. Uma resposta ainda pode conter Set-Cookie; registre que isso ocorreu se o desenho de auditoria permitir, depois descarte-o. A API deve usar sua credencial normal de solicitação na próxima chamada.

Essa recomendação é impopular porque muitas APIs próximas da web funcionam após um endpoint de login apenas quando o cliente mantém um cookie. As pessoas recorrem a um repositório compartilhado porque ele faz demonstrações e testes de integração passarem. Essa é a correção errada quando a API documentada aceita tokens de portador ou outro mecanismo restrito à solicitação. Você está preservando uma autorização invisível para compensar um caminho de integração que não deveria ter escolhido.

Se a API realmente exige cookies, torne o repositório uma capacidade explícita. Quem chama deve selecionar um repositório vazio e nomeado no início da execução, a ferramenta deve informar quando a resposta cria ou substitui um cookie, e o repositório deve desaparecer ao fim. Não deixe um endpoint incluir todos os agentes em uma sessão durável apenas por retornar um cabeçalho.

Uma política mínima pode ser simples o bastante para revisão:

cookie mode: disabled by default
allowed mode: ephemeral per agent run
persistence: prohibited
sharing: prohibited between agent processes
redirects: same-origin only unless the action definition permits another origin
logging: record cookie names and scope, never values

Isso é deliberadamente menos sofisticado que um mecanismo de regras. Uma política de cookies sofisticada ganha exceções até que ninguém consiga dizer qual ação carrega qual estado. Um pequeno conjunto de escolhas dá aos revisores uma resposta concreta.

Audite a transição de estado, não apenas a solicitação

Uma trilha de auditoria que lista URLs e códigos de status perderá o evento mais útil: uma resposta mudou o que chamadas futuras podem fazer. Capture mudanças no estado dos cookies como eventos de primeira classe sem reter o segredo da sessão.

Para cada ação HTTP, o registro deve permitir responder: a solicitação enviou cookies, a resposta definiu ou limpou algum, qual repositório os recebeu, o repositório pertencia a esta execução e houve redirecionamento? Nomes e atributos de cookies geralmente bastam para diagnóstico. Armazene valores apenas se tiver um desenho de segurança convincente para protegê-los e expirá-los, algo de que a maioria das ferramentas de agentes não precisa.

Quando um agente usa Sallyport para ações HTTP, o cofre pode manter a credencial de API configurada fora do agente enquanto a ação é executada. Essa separação só é útil se o cliente HTTP tratar qualquer estado de sessão retornado com a mesma desconfiança, em vez de transformá-lo silenciosamente em outro caminho de credencial.

Os registros de auditoria também precisam de um limite de execução legível para humanos. Se um operador revoga uma execução de agente, deve saber se esse ato impede chamadas futuras apenas pela credencial configurada ou também limpa o estado de sessão associado à execução. Se não limpar, diga isso claramente e torne o estado restante inacessível a um processo posterior.

O primeiro teste que eu adicionaria é intencionalmente simples: um endpoint envia Set-Cookie, o próximo confirma se ele chegou, e um novo processo de agente repete a chamada. Execute-o antes de adicionar novas tentativas, redirecionamentos, compatibilidade com navegadores ou um cache persistente. Se a resposta não estiver clara no rastreamento, seu cliente tem mais autoridade do que sua interface admite.

Autores de API podem tornar agentes mais seguros sem adivinhar

Autores de API devem documentar se cookies são obrigatórios, o que os cria, sua vida útil prevista e como os clientes os invalidam. Uma frase dizendo "use este endpoint após o login" não basta quando o login pode emitir uma sessão que dura mais que a credencial usada para obtê-la.

Ofereça uma alternativa restrita à solicitação sempre que possível. Autenticação de portador, solicitações assinadas ou um token de ação de escopo limitado costumam tornar o comportamento do cliente mais fácil de auditar, porque cada chamada carrega sua autorização às claras. Isso não torna esses mecanismos automaticamente seguros, mas evita um canal extra de repetição oculto na memória do cliente.

Se emitir um cookie de sessão, faça a invalidação de sessão funcionar e teste-a. A rotação de token sem invalidação de sessão deixa operadores com uma falsa sensação desagradável de conclusão. Se aceitar tanto um token de portador quanto um cookie de sessão, defina qual prevalece quando discordarem e exponha essa escolha na saída de diagnóstico.

Não diga a quem cria agentes para imitar navegadores, a menos que seu serviço dependa de fato do comportamento de navegador. Agentes fazem chamadas repetidas e sem supervisão, muitas vezes em tarefas diferentes. O estado de conveniência duradouro de um navegador é um padrão ruim para esse ambiente.

O padrão seguro é um cliente novo, sem sessão memorizada

O suporte a cookies não é ruim; estado sem responsável é. Um repositório de curta duração, selecionado explicitamente, pode ser a forma correta de concluir uma tarefa de API com várias chamadas. Um repositório que aparece porque alguém reutilizou um cliente HTTP é um acidente à espera da nova tentativa, do redirecionamento ou da rotação de credenciais certos.

Torne o limite de sessão visível na interface da ferramenta e no registro de auditoria. Depois prove-o com o teste entre execuções. O rastreamento da solicitação deve permitir que uma pessoa revisora aponte cada caminho de credencial que o agente teve, inclusive os que o servidor tentou devolver.