Hoe je actorbewuste beleidsregels veilig uitrolt

Wat kan er misgaan als je actorbewuste beleidsregels uitrolt?

Een actorbewust beleidsregel verandert hoe je applicatie reageert op basis van wie of wat handelt. Goed gedaan geeft het mensen een soepele ervaring, geeft het legitieme agents een gestructureerde route en voegt het alleen wrijving toe waar dat nodig is. Slecht gedaan sluit het echte gebruikers uit, breekt het integraties waarop je klanten vertrouwen en creëert het supporttickets die niemand kan verklaren.

Het verschil zit zelden in de beleidslogica. Het zit in de uitrol. (Zie voor het beleidsmodel zelf het ontwerpen van app-level beleidsregels voor mensen en AI-agents.) Deze gids beschrijft een gefaseerd proces dat teams voor elke route kunnen volgen: observeren, vooraf bekijken, afdwingen voor een deel, en dan uitbreiden. Elke fase heeft een duidelijk uitstapcriterium en een snelle manier om terug te gaan.

De drie modi

Zie elk beleid als iets dat per route in een van drie modi draait:

• Observeren. Classificaties worden vastgelegd. De applicatie reageert precies zoals zonder die classificaties.
• Vooraf bekijken. Het beleid wordt geëvalueerd en de beslissing wordt vastgelegd, maar niet toegepast. Je ziet wat er zou zijn gebeurd.
• Afdwingen. De beslissing wordt toegepast op echte verzoeken.

De modus hoort bij de combinatie van route en beleid, niet bij de hele applicatie. Je documentatiepagina's kunnen worden afgedwongen terwijl je checkout nog steeds wordt geobserveerd.

Stap 1: Observeer tot je je basislijn kent

Begin met elke route in observatiemodus. Verzamel ten minste:

• de route en methode,
• de actorclassificatie (Human, Human + AI, Agent of Unknown) en de basis ervan (verified, declared, inferred of unknown), zoals gedefinieerd in onze taxonomie voor applicatieverkeer,
• de responsstatus en een eenvoudige uitkomstmarkering voor de route, zoals "account aangemaakt" of "zoekopdracht gaf resultaten terug".

Laat het lang genoeg draaien om normale wekelijkse cycli en elke release die je in die periode uitbrengt te dekken. Noteer daarna je basislijn voor elke route die je belangrijk vindt: de klassensamenstelling, het Unknown-percentage en het uitkomstpercentage per klasse. Je vergelijkt alles wat volgt met deze cijfers.

Uitstapcriterium: je kunt voor elke kandidaatroute beschrijven wie deze gebruikt en hoe uitkomsten per klasse verschillen.

Stap 2: Schrijf het beleid als data

Beleidsregels zijn makkelijker te beoordelen, testen en terug te draaien wanneer ze data zijn in plaats van verspreide if-statements.

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

Elk beleid heeft een expliciete fallback. Dat is de actie die wordt gebruikt voor Unknown-resultaten, voor time-outs en voor elke situatie die door geen enkele regel wordt gedekt. Die bewust kiezen is de belangrijkste veiligheidsbeslissing in het hele proces.

Stap 3: Evalueer op één plek

Eén evaluatiefunctie houdt het gedrag consistent over alle modi.

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

Pas daarna de modus toe:

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

De stabiele bucket betekent dat dezelfde sessie of client binnen of buiten het afgedwongen deel blijft, zodat mensen geen gedrag zien omslaan tussen verzoeken.

Stap 4: Hoe meet je false positives voordat je afdwingt?

Zet één route om naar vooraf bekijken. Nu legt elk verzoek de beslissing vast die het zou hebben gekregen. Hier leer je of het beleid klopt.

Een false positive is een verzoek dat het beleid zou beperken, maar dat wel had moeten worden toegestaan. Je kunt dit niet alleen uit classificaties meten, omdat de classificatie juist is wat je test. Meet het tegen onafhankelijke signalen van legitiem gebruik:

• het verzoek doorliep een normale succesvolle flow, zoals een ingelogde gebruiker die werk opslaat,
• de client is een bekende partnerintegratie of een geverifieerde operator die je hebt afgesproken te bedienen,
• supporttickets of meldingen van gebruikers verwijzen naar de getroffen route,
• een handmatige beoordeling van een steekproef van verzoeken die anders beperkt zouden worden.

Beoordeel een steekproef met de hand. Twintig echte verzoeken lezen die het beleid zou hebben uitgedaagd, is de snelste manier om een regel te vinden die te breed is.

Uitstapcriterium: de set die anders beperkt zou worden, wordt vooral gevormd door verkeer dat je daadwerkelijk wilt beperken, en je hebt een verklaring voor elke categorie false positive die je hebt gevonden.

Stap 5: Dwing af voor een deel

Schakel de route om naar afdwingen met een kleine enforcePercent. Houd het deel klein genoeg zodat een fout weinig verzoeken raakt en groot genoeg om binnen een dag of twee een meetbaar signaal op te leveren.

Bewaar dezelfde metrics die je als basislijn hebt vastgelegd:

• uitkomstpercentage per klasse op de route,
• fout- en voltooiingspercentages voor challenges,
• supportvolume dat de route noemt,
• latency, omdat evaluatie op het requestpad staat.

Als uitkomsten voor Human-verkeer dalen in het afgedwongen deel ten opzichte van de rest, stop dan en onderzoek het voordat je verder uitbreidt.

Stap 6: Breid geleidelijk uit

Vergroot het deel in stappen, bijvoorbeeld van een klein aandeel naar een kwart, dan de helft, dan al het verkeer, en houd bij elke stap lang genoeg stil om een normale cyclus te zien. Uitbreiding is saai als de eerdere fasen goed zijn gedaan. Dat is het doel.

Kiezen van fallbacks en foutgedrag

Bepaal vooraf wat er gebeurt wanneer de bewijsvoering ontbreekt of de evaluatie niet kan draaien.

• Fail open betekent dat het verzoek verdergaat alsof er geen actorcontext is. Gebruik dit voor routes met laag risico, zoals publieke pagina's, documentatie en read-only cataloguseindpunten.
• Fail closed betekent dat je bestaande sterkere controle wordt toegepast, zoals opnieuw authenticeren of een review-wachtrij. Gebruik dit voor acties met grote impact waar je zo'n controle al hebt.

Laat nooit een time-out of fout een Human-resultaat opleveren. Ontbrekend bewijs is Unknown, en Unknown gebruikt de fallback van de route. Ons bericht over waarom Unknown een geldig resultaat is bij het classificeren van AI-verkeer legt uit waarom deze regel belangrijk is.

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

Hoe draai je een beleid snel terug?

Rollback moet een configuratiewijziging zijn, geen deploy. Bewaar beleidsregels in een opslag die je team snel kan bewerken, en maak deze acties direct:

1. Zet een route terug naar vooraf bekijken, waardoor afdwingen stopt terwijl de meting blijft lopen.
2. Zet enforcePercent op nul.
3. Schakel één regel uit zonder de andere aan te raken.

Leg elke beleidswijziging vast, met wie die heeft gemaakt en wanneer. Als uitkomsten verschuiven, is de eerste vraag altijd wat er is veranderd.

Vermijd beslissingen met gevolgen over mensen

Actorclassificaties beschrijven bewijs over een interactie. Het zijn geen oordelen over een persoon. Gebruik een inferred klasse niet als enige basis voor beslissingen die iemands werk, krediet, opleiding, huisvesting of toegang tot essentiële diensten beïnvloeden. Gebruik voor die stromen actorcontext om een proces te kiezen, bijvoorbeeld routering naar menselijke review, in plaats van om een uitkomst te bepalen.

Communiceer voordat je afdwingt

Beleid dat geautomatiseerde clients raakt, raakt ook de mensen en bedrijven die ze gebruiken. Een beetje communicatie voorkomt veel supportwerk:

1. Publiceer je regels voor geautomatiseerde toegang. Geef aan welke routes open zijn, welke limieten gelden en hoe clients zichzelf kunnen identificeren met ondertekende verzoeken via HTTP Message Signatures (RFC 9421) en de IETF Web Bot Auth protocol draft.
2. Informeer partners en integrators vooraf. Als een bekende integratie tijdens vooraf bekijken in een beperkt deel terechtkomt, neem contact op met de eigenaar voordat je gaat afdwingen.
3. Geef bruikbare responses terug. Wanneer een beleid een verzoek beperkt of uitdaagt, reageer dan met een duidelijke statuscode, zoals 429 Too Many Requests met Retry-After, en een link naar je documentatie. Een machineleesbare body in het Problem Details-formaat geeft geautomatiseerde clients een gestructureerde reden. Goed gebouwde agents passen zich aan wanneer ze begrijpen waarom.
4. Geef je supportteam het bewijs. Wanneer er een ticket binnenkomt over een geblokkeerd verzoek, moet support de route, de klasse, de basis en de beleidsbeslissing kunnen opzoeken zonder engineering te hoeven vragen.

Teams die wijzigingen aankondigen en uitleggen, zien veel minder verrassingen dan teams die regels stilletjes omschakelen, en de clients die zich aanpassen worden na verloop van tijd makkelijker te herkennen.

Een checklist voor elke route

• Basislijn vastgelegd voor klassensamenstelling, Unknown-percentage en uitkomsten.
• Beleid als data geschreven met een expliciete fallback.
• Vooraf bekeken, steekproef beoordeeld, categorieën false positives uitgelegd.
• Afdwingen gestart op een klein deel met gemonitorde metrics.
• Foutgedrag gekozen: fail open of fail closed.
• Rollback getest vóór uitbreiding.

Waar Proof of Actor past

Proof of Actor is ontworpen rond dit proces. Observatie is de standaard, elk resultaat draagt zijn basis, en Route-beleidsregels definieer en dwing je af in je eigen code, route voor route. Detect, Understand, Route: in die volgorde.

Om samen met ons team een uitrol op je eigen applicatie door te nemen, vraag vroege toegang aan. Lees voor de beslissingsstroom van begin tot eind Hoe Proof of Actor werkt.

Bronnen

• RFC 6585: Additional HTTP Status Codes, Section 4: de 429 Too Many Requests-statuscode
• RFC 9110: HTTP Semantics, Retry-After: clients vertellen wanneer ze opnieuw moeten proberen
• RFC 9457: Problem Details for HTTP APIs: machineleesbare fout-bodies
• RFC 9421: HTTP Message Signatures: hoe geautomatiseerde clients verzoeken ondertekenen
• draft-ietf-webbotauth-httpsig-protocol: IETF Web Bot Auth draft voor ondertekend geautomatiseerd verkeer (work in progress as of November 2026)