feat(rules): let rules act on who the User-Agent says it is

[cport1]

Companion to WebDecoy/app#498, which adds the registry exporter.

The gap

The docs describe branching on ai_scraper_category === 'training_crawler' and blocking at CRITICAL. RuleContext exposed ip, path, method, userAgent, headers, enrichment, the Web Bot Auth verdict and edge — no agent classification, and no registry in the SDK at all (zero occurrences of GPTBot anywhere in packages/).

So the headline policy of this product category — block AI training crawlers, allow search crawlers — was documented and unimplementable.

API

import { WebDecoy, bots, filter } from '@webdecoy/node';

bots({ categories: ['training_crawler'] })      // no AI training on my content
bots({ ai: true, allow: ['perplexitybot'] })    // all AI, minus one
bots({ agents: ['gptbot', 'ClaudeBot'], action: 'THROTTLE' })

filter({ expression: 'bot.ai and not bot.respects_robots' })

New filter namespace: bot.known, bot.ai, bot.category, bot.name, bot.id, bot.organization, bot.score, bot.respects_robots.

ai: true covers the four AI categories and deliberately excludes search_crawler — blocking Googlebot would deindex the customer's site.

Generated, not hand-written

registry.generated.ts comes from pkg/agents via the exporter; parity-vectors.generated.json records what Go's MatchUserAgent answers for 360 User-Agents, and parity.test.ts replays every one.

Order is load-bearing. Verified the parity test fails on reorder: sorting alphabetically makes applebot shadow applebot-extended, silently reclassifying Apple's AI training crawler.

What this deliberately cannot do

It matches a self-declared User-Agent. That is correct for this policy — GPTBot and ClaudeBot identify honestly, and the decision is about a cooperative agent's access, not about catching a liar. Anything spoofing Chrome passes through, and the docs say so in a caution block.

It is not a threat signal and does not pretend to be: BotRule reports confidence: 70, not the 100 a tripwire reports, because a tripwire proves behaviour while this repeats a claim.

Safety choices

• allow[] applies before every other clause — an SEO outage from a mis-scoped rule costs more than a scraper getting through
• an empty config is inert, not default-deny
• the UA cache is bounded and clears wholesale on overflow: the key is client-controlled, so an unbounded map would be a memory-exhaustion vector

Verification

• 233 tests pass across all 4 packages, uncached (turbo test --force)
• check:edge passes — still edge-runtime compatible
• +28 KB source, 37.7 KB gzipped bundle total