Link Proxy for YOURLS

Proxy file downloads from selected hosts through YOURLS or a dedicated proxy server, while keeping normal HTML pages as standard redirects.

What This Plugin Does

When a short URL is clicked, the plugin can:

• stream file content instead of redirecting to the final file URL;
• offload file traffic to an external proxy server;
• redirect HTML pages normally (no HTML proxying);
• restrict proxying to an allowlist of target hosts.

This helps when you need controlled download behavior, more privacy for destination URLs, or traffic offloading from your main YOURLS server.

Requirements

• YOURLS 1.9.2+ (plugin was built for this setup)
• PHP 8.0+
• PHP cURL extension (required for local streaming and proxy script fallback)
• Nginx or Apache config only if you enable acceleration mode

Installation

1. Place the plugin folder in: user/plugins/agdev-link-proxy/
2. Ensure the plugin main file is: user/plugins/agdev-link-proxy/plugin.php
3. Open YOURLS Admin -> Manage Plugins and activate Link Proxy.
4. Open plugin settings page: admin/plugins.php?page=link_proxy

Quick Start

Local Mode (no external proxy server)

1. Enable Link Proxy.
2. Add Target domains (one per line or comma-separated), for example:
   • example.com
   • *.example.com
3. Keep Proxy URL and Shared Secret empty.
4. Set timeout / redirect limits as needed.
5. Save settings.

Result: matching file URLs are streamed from your YOURLS server; HTML pages are redirected as normal.

External Proxy Mode (recommended for heavy file traffic)

1. Set Proxy URL (for example https://proxy.example.com).
2. Set Shared Secret.
3. Save settings.
4. Click Download agdev-link-proxy.php on the plugin page.
5. Deploy downloaded agdev-link-proxy.php on your proxy host.
6. Apply the Nginx/Apache snippets shown on the plugin page.

Result: YOURLS redirects clicks to your proxy endpoint (/_lp/<keyword>), and the proxy host serves files.

How It Works

Request Flow in YOURLS

1. Plugin hooks into YOURLS redirect_shorturl.
2. If External Proxy is configured, YOURLS builds a signed proxy URL and sends a 302 to proxy host.
3. If external proxy is not configured:
   • plugin validates host against your allowlist;
   • detects HTML responses and keeps normal redirect behavior;
   • for files, streams content locally (with optional acceleration).

External Proxy Script Flow

agdev-link-proxy.php:

1. accepts requests on /_lp/<keyword>;
2. validates ts + sig (HMAC SHA-256, max skew 600s);
3. expands keyword to long URL through YOURLS API;
4. validates scheme and allowed host;
5. redirects HTML pages to original URL;
6. serves files via:
   • Apache acceleration (mod_proxy rewrite), or
   • Nginx X-Accel-Redirect, or
   • cURL streaming fallback.

Configuration Notes

• Allowed hosts support wildcards like *.example.com.
• Wildcard matches subdomains, not the root domain itself.
• Timeout and Max redirects affect local streaming behavior.
• Apache secret can be rotated from the plugin Tools section.
• The plugin sends no-store headers for proxied responses.

Troubleshooting

• Link Proxy requires the PHP cURL extension: install/enable php-curl.
• Host not allowed: add destination host to Target domains.
• External proxy returns Missing signature / Bad signature: verify Shared Secret matches between YOURLS and deployed agdev-link-proxy.php.
• Nginx/Apache acceleration not working: verify server snippets were applied exactly as shown in plugin page.

Security

• Only HTTP/HTTPS schemes are accepted.
• Host allowlist is enforced before proxying.
• External requests are signed and time-limited.
• Shared secrets should be long and random.

License

MIT License. See LICENSE.