Como implementar políticas com consciência do ator com segurança

O que pode dar errado quando você implementa políticas com consciência do ator?

Uma policy com consciência do ator muda como sua aplicação responde com base em quem ou no que está agindo. Feita corretamente, ela oferece uma experiência fluida para as pessoas, dá aos agents legítimos um caminho estruturado e adiciona atrito apenas onde isso importa. Feita de forma ruim, ela bloqueia usuários reais, quebra integrações das quais seus clientes dependem e gera tickets de suporte que ninguém consegue explicar.

A diferença raramente está na lógica da policy. Está na implementação. (Para o próprio modelo de policy, veja desenvolvendo policies no nível da app para humanos e agents de IA.) Este guia descreve um processo em etapas que as equipes podem seguir para qualquer route: observar, visualizar, aplicar para uma parte, depois expandir. Cada etapa tem um critério claro de saída e uma forma rápida de voltar.

Os três modos

Pense em cada policy como operando em um de três modos por route:

• Observe. As classificações são registradas. A aplicação responde exatamente como responderia sem elas.
• Preview. A policy é avaliada e sua decisão é registrada, mas não aplicada. Você pode ver o que teria acontecido.
• Enforce. A decisão é aplicada às solicitações reais.

O modo pertence ao par route e policy, não à aplicação inteira. Suas páginas de documentação podem estar em enforce enquanto seu checkout ainda está em observe.

Etapa 1: Observe até conhecer sua linha de base

Comece com cada route no modo observe. Colete, no mínimo:

• a route e o method,
• a classe do actor (Human, Human + AI, Agent ou Unknown) e sua base (verified, declared, inferred ou unknown), conforme definido em nossa taxonomia para tráfego de application,
• o status da resposta e um marcador simples de resultado para a route, como "account created" ou "search returned results".

Execute por tempo suficiente para cobrir os ciclos semanais normais e qualquer release que você publicar nesse período. Depois registre sua linha de base para cada route que importa: a composição de classes, a taxa de Unknown e a taxa de resultado por classe. Você vai comparar tudo o que vier depois com esses números.

Critério de saída: você consegue descrever, para cada route candidata, quem a usa e como os resultados variam por classe.

Etapa 2: Escreva a policy como data

Policies são mais fáceis de revisar, testar e reverter quando são data, e não declarações if espalhadas.

type ActorClass = "human" | "human_ai" | "agent" | "unknown";
type Basis = "verified" | "declared" | "inferred" | "unknown";
type Action = "allow" | "adapt" | "challenge" | "review" | "limit";
type Mode = "observe" | "preview" | "enforce";

interface Rule {
  actor: ActorClass | "*";
  basis?: Basis[];
  action: Action;
}

interface RoutePolicy {
  route: string;
  mode: Mode;
  enforcePercent: number;
  rules: Rule[];
  fallback: Action;
}

export const policies: RoutePolicy[] = [
  {
    route: "GET /api/catalog",
    mode: "preview",
    enforcePercent: 0,
    rules: [
      { actor: "agent", basis: ["verified"], action: "allow" },
      { actor: "agent", basis: ["declared", "inferred"], action: "limit" },
    ],
    fallback: "allow",
  },
];

Toda policy tem um fallback explícito. Essa é a ação usada para resultados Unknown, para timeouts e para qualquer caso que nenhuma regra cubra. Escolhê-lo de forma deliberada é a decisão de segurança mais importante em todo o processo.

Etapa 3: Avalie em um só lugar

Uma única função de avaliação mantém o comportamento consistente entre os modos.

export function decide(policy: RoutePolicy, actor: ActorClass, basis: Basis): Action {
  for (const rule of policy.rules) {
    const actorMatch = rule.actor === "*" || rule.actor === actor;
    const basisMatch = !rule.basis || rule.basis.includes(basis);
    if (actorMatch && basisMatch) return rule.action;
  }
  return policy.fallback;
}

Depois aplique o modo:

export function applyPolicy(policy: RoutePolicy, actor: ActorClass, basis: Basis, requestKey: string) {
  const decision = decide(policy, actor, basis);
  const inSlice = bucket(requestKey) < policy.enforcePercent;
  const enforced = policy.mode === "enforce" && inSlice;
  record({ route: policy.route, mode: policy.mode, actor, basis, decision, enforced });
  return enforced ? decision : "allow";
}

function bucket(key: string): number {
  let h = 0;
  for (const c of key) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return h % 100;
}

O bucket estável significa que a mesma sessão ou cliente permanece dentro ou fora da fatia aplicada, então as pessoas não veem o comportamento alternar entre requests.

Etapa 4: Como você mede falsos positivos antes de aplicar?

Mova uma route para preview. Agora cada request registra a decisão que teria recebido. É aqui que você descobre se a policy está correta.

Um falso positivo é uma request que a policy restringiria, mas que deveria ter sido permitida. Você não consegue medi-lo apenas pelas classificações, porque a classificação é o que você está testando. Meça contra sinais independentes de uso legítimo:

• a request concluiu um fluxo normal e bem-sucedido, como um usuário autenticado salvando trabalho,
• o cliente é uma integração parceira conhecida ou um operador verificado que você concordou em atender,
• tickets de suporte ou relatos de usuários mencionam a route afetada,
• uma revisão manual de uma amostra de requests que seriam restritas.

Revise uma amostra manualmente. Ler vinte requests reais que a policy teria desafiado é a forma mais rápida de encontrar uma regra ampla demais.

Critério de saída: o conjunto que seria restringido é dominado por tráfego que você realmente pretende restringir, e você tem uma explicação para cada categoria de falso positivo encontrada.

Etapa 5: Aplique para uma parte

Alterne a route para enforce com uma pequena enforcePercent. Mantenha a parte pequena o bastante para que um erro afete poucas requests e grande o bastante para produzir um sinal mensurável em um ou dois dias.

Acompanhe as mesmas métricas que você definiu como linha de base:

• taxa de resultado por classe na route,
• taxas de erro e de conclusão de challenge,
• volume de suporte mencionando a route,
• latência, já que a avaliação fica no caminho da request.

Se os resultados para o tráfego Human caírem na parte aplicada em comparação com o restante, pare e investigue antes de expandir.

Etapa 6: Expanda gradualmente

Aumente a parte em etapas, por exemplo de uma fração pequena para um quarto, depois metade, depois todo o tráfego, mantendo cada etapa tempo suficiente para ver um ciclo normal. A expansão é simples quando as etapas anteriores foram feitas bem. Esse é o objetivo.

Escolhendo fallbacks e o comportamento em falha

Decida com antecedência o que acontece quando a evidence está ausente ou a avaliação não consegue ser executada.

• Fail open significa que a request segue como seguiria sem contexto de ator. Use isso para routes de baixo risco, como páginas públicas, documentação e endpoints de catálogo somente leitura.
• Fail closed significa que sua checagem mais forte existente se aplica, como nova autenticação ou uma fila de revisão. Use isso para ações de alto impacto nas quais você já tem esse tipo de checagem.

Nunca deixe um timeout ou erro produzir um resultado Human. Evidence ausente é Unknown, e Unknown usa o fallback da route. Nosso artigo sobre por que Unknown é um resultado válido ao classificar tráfego de IA explica por que essa regra importa.

async function actorWithTimeout(evaluate: () => Promise<{ actor: ActorClass; basis: Basis }>) {
  const timeout = new Promise<{ actor: ActorClass; basis: Basis }>((resolve) =>
    setTimeout(() => resolve({ actor: "unknown", basis: "unknown" }), 150),
  );
  return Promise.race([evaluate(), timeout]);
}

Como você faz rollback de uma policy rapidamente?

Rollback deve ser uma mudança de configuração, não um deploy. Mantenha as policies em um repositório que sua equipe possa editar rapidamente e torne estas ações instantâneas:

1. Coloque uma route de volta em preview, o que interrompe a aplicação enquanto mantém a medição.
2. Defina enforcePercent como zero.
3. Desative uma única regra sem tocar nas outras.

Registre toda mudança de policy com quem a fez e quando. Quando os resultados mudam, a primeira pergunta é sempre o que mudou.

Evite decisões consequenciais sobre pessoas

As classificações de actor descrevem evidence sobre uma interaction. Elas não são um julgamento sobre uma pessoa. Não use uma classe inferred como base única para decisões que afetem emprego, crédito, educação, moradia ou acesso a serviços essenciais de alguém. Para esses fluxos, use o contexto de actor para escolher um processo, por exemplo encaminhar para revisão humana, em vez de decidir um resultado.

Comunique antes de aplicar

Policies que afetam clients automatizados também afetam as pessoas e empresas que os operam. Um pouco de comunicação evita muito trabalho de suporte:

1. Publique suas regras de acesso automatizado. Informe quais routes estão abertas, quais limites se aplicam e como os clients podem se identificar com requests assinadas usando HTTP Message Signatures (RFC 9421) e o rascunho do protocolo IETF Web Bot Auth.
2. Avise parceiros e integradores com antecedência. Se uma integração conhecida cair em uma fatia restrita durante o preview, contate o responsável antes de aplicar.
3. Retorne respostas úteis. Quando uma policy limitar ou desafiar uma request, responda com um status code claro, como 429 Too Many Requests com Retry-After, e um link para sua documentação. Um corpo em formato Problem Details legível por máquina dá aos clients automatizados um motivo estruturado. Agents bem construídos se adaptam quando entendem o porquê.
4. Dê à sua equipe de suporte a evidence. Quando um ticket chegar sobre uma request bloqueada, o suporte deve conseguir consultar a route, a class, a base e a decisão da policy sem acionar a engenharia.

Equipes que anunciam mudanças e as explicam veem muito menos surpresas do que equipes que alteram regras em silêncio, e os clients que se adaptam se tornam mais fáceis de reconhecer com o tempo.

Uma checklist para cada route

• Linha de base registrada para composição de classes, taxa de Unknown e resultados.
• Policy escrita como data com fallback explícito.
• Preview executado, amostra revisada, categorias de falso positivo explicadas.
• Aplicação iniciada em uma parte pequena com métricas monitoradas.
• Comportamento em falha definido: fail open ou fail closed.
• Rollback testado antes da expansão.

Onde Proof of Actor se encaixa

Proof of Actor foi projetado em torno desse processo. A observação é o padrão, todo resultado carrega sua base, e as policies de Route são suas para definir e aplicar no seu próprio código, route por route. Detect, Understand, Route: nessa ordem.

Para conduzir uma implementação na sua própria application com a nossa equipe, solicite acesso antecipado. Para o fluxo de decisão de ponta a ponta, leia Como Proof of Actor funciona.

Fontes

• RFC 6585: Additional HTTP Status Codes, Section 4: o status code 429 Too Many Requests
• RFC 9110: HTTP Semantics, Retry-After: informar aos clients quando tentar novamente
• RFC 9457: Problem Details for HTTP APIs: corpos de erro legíveis por máquina
• RFC 9421: HTTP Message Signatures: como clients automatizados assinam requests
• draft-ietf-webbotauth-httpsig-protocol: rascunho IETF Web Bot Auth para tráfego automatizado assinado (em andamento em novembro de 2026)