Come distribuire in sicurezza le policy consapevoli dell'attore

Cosa può andare storto quando distribuisci policy consapevoli dell'attore?

Una policy consapevole dell'attore cambia il modo in cui la tua applicazione risponde in base a chi o a cosa sta agendo. Se fatta bene, offre alle persone un'esperienza fluida, dà agli agenti legittimi un percorso strutturato e aggiunge attrito solo dove serve. Se fatta male, blocca utenti reali, rompe integrazioni da cui i tuoi clienti dipendono e genera ticket di supporto che nessuno sa spiegare.

La differenza raramente sta nella logica della policy. Sta nella distribuzione. (Per il modello di policy in sé, vedi progettare policy a livello di applicazione per persone e agenti AI.) Questa guida descrive un processo graduale che i team possono seguire per qualsiasi route: osserva, visualizza in anteprima, applica a una porzione, poi espandi. Ogni fase ha un criterio di uscita chiaro e un modo rapido per tornare indietro.

Le tre modalità

Pensa a ogni policy come se operasse in una delle tre modalità per route:

• Osserva. Le classificazioni vengono registrate. L'applicazione risponde esattamente come farebbe senza di esse.
• Anteprima. La policy viene valutata e la sua decisione viene registrata, ma non applicata. Puoi vedere cosa sarebbe successo.
• Applica. La decisione viene applicata alle richieste reali.

La modalità appartiene alla coppia route-policy, non all'intera applicazione. Le tue pagine di documentazione possono essere in applicazione mentre il checkout è ancora in osservazione.

Passo 1: Osserva finché non conosci la tua baseline

Inizia con ogni route in modalità osservazione. Raccogli, come minimo:

• la route e il metodo,
• la classe dell'attore (Human, Human + AI, Agent o Unknown) e la sua base (verified, declared, inferred o unknown), come definito in la nostra tassonomia per il traffico delle applicazioni,
• lo stato della risposta e un indicatore semplice di esito per la route, come "account creato" o "la ricerca ha restituito risultati".

Esegui il monitoraggio abbastanza a lungo da coprire i cicli settimanali normali e qualsiasi rilascio effettuato in quel periodo. Poi annota la tua baseline per ogni route che ti interessa: la combinazione di classi, il tasso di Unknown e il tasso di esito per classe. Confronterai tutto ciò che segue con questi numeri.

Criterio di uscita: puoi descrivere, per ogni route candidata, chi la usa e in che modo gli esiti differiscono per classe.

Passo 2: Scrivi la policy come dati

Le policy sono più facili da rivedere, testare e rollbackare quando sono dati invece di if sparsi.

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",
  },
];

Ogni policy ha un fallback esplicito. È l'azione usata per i risultati Unknown, per i timeout e per qualsiasi caso non coperto da una regola. Sceglierlo in modo deliberato è la singola decisione di sicurezza più importante dell'intero processo.

Passo 3: Valuta in un solo punto

Una singola funzione di valutazione mantiene il comportamento coerente tra le modalità.

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;
}

Poi applica la modalità:

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;
}

Il bucket stabile significa che la stessa sessione o lo stesso client resta dentro o fuori dal sottoinsieme applicato, così le persone non vedono il comportamento cambiare da una richiesta all'altra.

Passo 4: Come misuri i falsi positivi prima dell'applicazione?

Sposta una route in anteprima. Ora ogni richiesta registra la decisione che avrebbe ricevuto. È qui che capisci se la policy è corretta.

Un falso positivo è una richiesta che la policy limiterebbe ma che avrebbe dovuto essere consentita. Non puoi misurarlo solo dalle classificazioni, perché la classificazione è ciò che stai testando. Misuralo rispetto a segnali indipendenti di uso legittimo:

• la richiesta ha completato un flusso normale e riuscito, come un utente autenticato che salva il proprio lavoro,
• il client è una nota integrazione partner o un operatore verificato che hai concordato di servire,
• ticket di supporto o segnalazioni degli utenti fanno riferimento alla route interessata,
• una revisione manuale di un campione di richieste che sarebbero state limitate.

Rivedi un campione a mano. Leggere venti richieste reali che la policy avrebbe sfidato è il modo più rapido per trovare una regola troppo ampia.

Criterio di uscita: il gruppo di richieste che sarebbero state limitate è dominato da traffico che intendi davvero limitare, e hai una spiegazione per ogni categoria di falso positivo che hai trovato.

Passo 5: Applica a una porzione

Passa la route ad applicazione con un piccolo enforcePercent. Mantieni la porzione abbastanza piccola da far sì che un errore impatti poche richieste e abbastanza grande da produrre un segnale misurabile entro un giorno o due.

Monitora le stesse metriche che hai impostato come baseline:

• tasso di esito per classe sulla route,
• tassi di errore e di completamento della sfida,
• volume di supporto che menziona la route,
• latenza, poiché la valutazione si trova sul percorso della richiesta.

Se gli esiti per il traffico Human calano nella porzione applicata rispetto al resto, fermati e indaga prima di espandere.

Passo 6: Espandi gradualmente

Aumenta la porzione a passi, per esempio da una piccola quota a un quarto, poi la metà, poi tutto il traffico, fermandoti a ogni passaggio abbastanza a lungo da vedere un ciclo normale. L'espansione è noiosa quando le fasi precedenti sono state eseguite bene. È questo l'obiettivo.

Scegliere i fallback e il comportamento in caso di errore

Decidi in anticipo cosa succede quando l'evidenza manca o la valutazione non può essere eseguita.

• Fail open significa che la richiesta prosegue come farebbe senza il contesto dell'attore. Usalo per route a basso rischio come pagine pubbliche, documentazione ed endpoint di catalogo in sola lettura.
• Fail closed significa che si applica il tuo controllo più forte già esistente, come una nuova autenticazione o una coda di revisione. Usalo per azioni ad alto impatto in cui hai già un controllo di questo tipo.

Non lasciare mai che un timeout o un errore producano un risultato Human. L'evidenza mancante è Unknown, e Unknown prende il fallback della route. Il nostro articolo su perché Unknown è un risultato valido quando si classifica il traffico AI spiega perché questa regola è importante.

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]);
}

Come fai a rollbackare rapidamente una policy?

Il rollback dovrebbe essere una modifica di configurazione, non un deploy. Conserva le policy in un archivio che il tuo team possa modificare rapidamente e rendi istantanee queste azioni:

1. Riporta una route in anteprima, così interrompi l'applicazione mantenendo la misurazione.
2. Porta enforcePercent a zero.
3. Disabilita una singola regola senza toccare le altre.

Registra ogni modifica della policy con chi l'ha effettuata e quando. Quando gli esiti cambiano, la prima domanda è sempre cosa è cambiato.

Evita decisioni con conseguenze sulle persone

Le classificazioni degli attori descrivono evidenze su un'interazione. Non sono un giudizio su una persona. Non usare una classe inferred come unico fondamento per decisioni che incidono sul lavoro, sul credito, sull'istruzione, sull'abitazione o sull'accesso a servizi essenziali di qualcuno. Per questi flussi, usa il contesto dell'attore per scegliere un processo, per esempio il rinvio a revisione umana, invece di decidere un esito.

Comunica prima di applicare

Le policy che incidono sui client automatizzati incidono anche sulle persone e sulle aziende che li gestiscono. Un po' di comunicazione evita molto lavoro di supporto:

1. Pubblica le tue regole per l'accesso automatizzato. Indica quali route sono aperte, quali limiti si applicano e come i client possono identificarsi con richieste firmate usando HTTP Message Signatures (RFC 9421) e la bozza del protocollo IETF Web Bot Auth.
2. Avvisa in anticipo partner e integratori. Se un'integrazione nota rientra in una porzione limitata durante l'anteprima, contatta il relativo responsabile prima di applicare.
3. Restituisci risposte utili. Quando una policy limita o sfida una richiesta, rispondi con un codice di stato chiaro, come 429 Too Many Requests con Retry-After, e un link alla tua documentazione. Un corpo leggibile dalle macchine nel formato Problem Details offre ai client automatizzati una ragione strutturata. Gli agenti ben costruiti si adattano quando capiscono il perché.
4. Dai al tuo team di supporto le evidenze. Quando arriva un ticket su una richiesta bloccata, il supporto deve poter consultare la route, la classe, la base e la decisione della policy senza chiedere a engineering.

I team che annunciano i cambiamenti e li spiegano vedono molte meno sorprese rispetto ai team che modificano le regole in silenzio, e i client che si adattano diventano più facili da riconoscere nel tempo.

Una checklist per ogni route

• Baseline registrata per combinazione di classi, tasso di Unknown ed esiti.
• Policy scritta come dati con un fallback esplicito.
• Anteprima eseguita, campione revisionato, categorie di falsi positivi spiegate.
• Applicazione avviata su una piccola porzione con metriche monitorate.
• Comportamento in caso di errore scelto: fail open o fail closed.
• Rollback testato prima dell'espansione.

Dove si inserisce Proof of Actor

Proof of Actor è progettato attorno a questo processo. L'osservazione è l'impostazione predefinita, ogni risultato porta con sé la propria base e le policy di Route sono tue da definire e applicare nel tuo codice, route per route. Detect, Understand, Route: in quest'ordine.

Per affrontare una distribuzione sulla tua applicazione insieme al nostro team, richiedi l'accesso anticipato. Per il flusso decisionale end to end, leggi Come funziona Proof of Actor.

Fonti

• RFC 6585: Additional HTTP Status Codes, Section 4: il codice di stato 429 Too Many Requests
• RFC 9110: HTTP Semantics, Retry-After: come comunicare ai client quando riprovare
• RFC 9457: Problem Details for HTTP APIs: corpi di errore leggibili dalle macchine
• RFC 9421: HTTP Message Signatures: come i client automatizzati firmano le richieste
• draft-ietf-webbotauth-httpsig-protocol: bozza IETF Web Bot Auth per il traffico automatizzato firmato (lavoro in corso a novembre 2026)