127 lines
5.2 KiB
Markdown
127 lines
5.2 KiB
Markdown
# 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>`
|
|
|
|
```bash
|
|
# 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>`
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
npm install
|
|
npm run deploy
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
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
|