url-cleaner/README.md

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

iOS Shortcut Integration

For iPhone and iPad users, we provide a convenient iOS Shortcut that integrates directly with the system share sheet, allowing you to clean URLs from any app with just a tap.

Installation

Get it from the iCloud link: https://www.icloud.com/shortcuts/8e8fdf8350f249e488ce1fdbeab4b8b3 When you open the link, iOS will prompt you to install the shortcut, simply tap Add Shortcut to complete the installation.

The shortcut file is also available in this repository as Clean URLs.shortcut for reference.

First Use & Permissions

When you first share a URL using the shortcut, iOS will display a privacy protection dialog:

Allow "Clean URLs" to send 1 item to "url-cleaner.m5r.workers.dev"?

This might allow "Clean URLs" to share this content with "url-cleaner.m5r.workers.dev" and potentially other websites.

Options:

• Don't Allow - Blocks the request (shortcut won't work)
• Allow Once - Permits this single request only
• Always Allow - Remembers your choice for future uses (recommended)

What this means: iOS is asking permission for the shortcut to send your shared URL to the URL cleaner service. This is exactly what you want - the shortcut needs to send the URL to be cleaned. Choose "Always Allow" for the best experience.

How to Use

1. Share a URL from any app (Safari, Twitter, Reddit, Messages, etc.)
2. Find "Clean URLs" in the share sheet (may be in the "More" section initially)
3. Tap the shortcut - it will clean the URL and copy the result to your clipboard
4. Paste the cleaned URL wherever you need it

Troubleshooting

Shortcut not appearing in share sheet?

• Look in the "More" section (scroll right in the bottom row)
• Open Shortcuts app → Settings → Share Sheet → ensure "Clean URLs" is enabled

Getting permission denied errors?

• Open Shortcuts app → find "Clean URLs" → tap the details icon (ⓘ) → Privacy
• Under "Allow Get Contents of URL to use", ensure the apps you're sharing from are allowed
• You can grant permission to specific apps or choose "Always Allow"

Cleaned URL not copying to clipboard?

• Open Shortcuts app → find "Clean URLs" → tap the details icon (ⓘ) → Privacy
• Ensure clipboard access is enabled for the shortcut

API

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

• Same 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