Skip to content

X402 Proxy Template: Add bot management filtering support#952

Merged
deloreyj merged 3 commits intocloudflare:mainfrom
CameronWhiteside:x402/agentic-setup-improvements
Feb 4, 2026
Merged

X402 Proxy Template: Add bot management filtering support#952
deloreyj merged 3 commits intocloudflare:mainfrom
CameronWhiteside:x402/agentic-setup-improvements

Conversation

@CameronWhiteside
Copy link
Contributor

@CameronWhiteside CameronWhiteside commented Feb 3, 2026

Description

Adds optional Bot Management Filtering to x402-proxy-template. When enabled (requires Bot Management for Enterprise), allows:

  • Humans (bot score > threshold) to access protected routes for FREE
  • Excepted bots (by detection ID) to access protected routes for FREE
  • All other bot traffic must pay

Changes

  • Add bot_score_threshold and except_detection_ids config options to protected patterns
  • Create src/bot-management/ directory with isolated filtering logic
  • Add bot reference registry for AI agent setup (Google, Microsoft, OpenAI, Anthropic, Perplexity, Meta)
  • Update AGENTS.md with Bot Management Filtering setup flow
  • Simplify wrangler.jsonc to single Bot Management example
    Non-Bot Management users can ignore the entire src/bot-management/ directory.

Checklist

  • Template Metadata
    • template directory ends with -template
    • "cloudflare" section of package.json is populated
    • template preview image uploaded to Images
    • README is populated and uses <!-- dash-content-start --> and <!-- dash-content-end --> to designate the Dash readme preview
    • .gitignore file exists
    • package.json contains a deploy command
    • package.json contains private: true and no version field

Example package.json

"private": true,
"cloudflare": {
  "label": "Worker + D1 Database",
  "products": [
    "Workers",
    "D1"
  ],
  "categories": [
    "storage"
  ],
  "docs_url": "https://developers.cloudflare.com/d1/",
  "preview_image_url": "https://imagedelivery.net/wSMYJvS3Xw-n339CbDyDIA/cb7cb0a9-6102-4822-633c-b76b7bb25900/public"
}

@CameronWhiteside CameronWhiteside force-pushed the x402/agentic-setup-improvements branch from e03b809 to 280136a Compare February 3, 2026 21:05
@CameronWhiteside
feat(x402-proxy-template): add Bot Management Filtering support
f78414a 
Adds optional Bot Management Filtering to x402-proxy-template. When enabled
(requires Bot Management for Enterprise), allows:

- Humans (bot score > threshold) to access protected routes for FREE
- Excepted bots (by detection ID) to access protected routes for FREE
- All other bot traffic must pay

Changes:
- Add bot_score_threshold and except_detection_ids config options
- Create src/bot-management/ directory with isolated filtering logic
- Add bot reference registry for AI agent setup
- Update AGENTS.md with Bot Management Filtering setup flow
- Simplify wrangler.jsonc examples

Non-Bot Management users can ignore the entire src/bot-management/ directory.
@CameronWhiteside CameronWhiteside force-pushed the x402/agentic-setup-improvements branch from 280136a to f78414a Compare February 3, 2026 21:09
@github-actions
Copy link
Contributor

github-actions bot commented Feb 3, 2026

Preview link not generated: you must be on a branch, not on a fork.
Collaborators may enable previews for this pull request by attaching the allow preview label.
If you are already a collaborator, please create a branch rather than forking.

@deloreyj deloreyj added the allow preview allows for preview links on forks label Feb 4, 2026
@github-actions
Copy link
Contributor

github-actions bot commented Feb 4, 2026

Dashboard preview link

@github-actions
Copy link
Contributor

github-actions bot commented Feb 4, 2026

Dashboard preview link

edevil
edevil reviewed Feb 4, 2026
View reviewed changes
x402-proxy-template/src/bot-management/index.ts Outdated
return false;
}

const botScore = botManagement.score ?? 99; // Default to human if no score
Copy link
Contributor

@edevil edevil Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default above for no botManagement is to always require payment. Yet here, if for some reason we don't have a score, we default to human (no payment). Is this intended?

Copy link
Contributor Author

@CameronWhiteside CameronWhiteside Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the catch - it would be best to default to always require payment.

That way, it would match the behavior of the proxy template when there is no bot management configuration at all.

I've added a console.warn for this this scenario, and removed the fallback to 99.

@CameronWhiteside
fix: require payment when bot score is missing
aef7920 
If botManagement data is present but score is undefined/null,
fall back to requiring payment instead of defaulting to 99 (human).

This ensures consistent 'safe default' behavior - when we can't
evaluate bot status, we require payment.

Addresses review feedback from @edevil
@github-actions
Copy link
Contributor

github-actions bot commented Feb 4, 2026

Dashboard preview link

@deloreyj deloreyj merged commit 30d1642 into cloudflare:main Feb 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@deloreyj deloreyj deloreyj approved these changes

+1 more reviewer

@edevil edevil edevil left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

allow preview allows for preview links on forks

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@CameronWhiteside @edevil @deloreyj