URL Cleaner

A Cloudflare Worker that removes tracking parameters from URLs using the official ClearURLs rule database. Provides the same privacy protection as the ClearURLs browser extension but as a serverless API.

Usage

Clean URLs

API Endpoint: GET /?url=<encoded-url>

# Remove UTM tracking
curl "https://your-worker.workers.dev/?url=https%3A//example.com%3Futm_source%3Dtest"
# Returns: https://example.com

# Clean YouTube URL (preserves video ID, removes tracking)
curl "https://your-worker.workers.dev/?url=https%3A//youtube.com/watch%3Fv%3Dabc%26feature%3Dshare"
# Returns: https://youtube.com/watch?v=abc

# Clean URL with fragments/hash parameters
curl "https://your-worker.workers.dev/?url=https%3A//example.com/page%3Futm_source%3Dtest%23utm_campaign%3Dfragment"
# Returns: https://example.com/page

Purge Cache

API Endpoint: DELETE /?url=<encoded-url>

# Delete cached response for a specific URL
curl -X DELETE "https://your-worker.workers.dev/?url=https%3A//example.com%3Futm_source%3Dtest"
# Returns: Cache entry deleted (200) or Cache entry not found (404)

Features

Official ClearURLs Rules - Uses the same 250+ provider rule database as the ClearURLs browser extension
Live Rule Updates - Automatically fetches and validates rules from ClearURLs API with SHA256 verification
Query & Fragment Cleaning - Removes tracking from both URL parameters (?utm_source=test) and fragments (#utm_campaign=test)
Redirect Following - Unwraps shortened URLs and tracking redirects (up to 5 levels)
Provider-Specific Logic - Domain-specific rules prevent false positives (e.g., TikTok rules won't affect YouTube)
Advanced Pattern Matching - Full regex support with exact ClearURLs compatibility
Response Caching - 1-hour cache using Cloudflare Cache API for improved performance and reduced latency
Cache Management - DELETE endpoint for manual cache purging and testing
Durable Object Storage - 7-day rule caching with automatic refresh and fallback support

Deployment

npm install
npm run deploy

Development

npm run dev     # Start local server at http://localhost:8787
npm test        # Run tests
npm run format  # Format code with Prettier

Architecture

Cloudflare Workers - Serverless edge computing for global performance
Durable Objects - Persistent storage for ClearURLs rule caching with SHA256 validation
TypeScript - Full type safety with generated Cloudflare Workers types
ClearURLs Integration - Official rule database with automatic updates

Rule System

The worker fetches and caches rules from the official ClearURLs API:

Source: https://rules2.clearurls.xyz/data.minify.json
Validation: https://rules2.clearurls.xyz/rules.minify.hash
Cache Duration: 7 days with automatic refresh
Fallback: Uses cached rules if fresh fetch fails

2.9 KiB Raw Blame History