The Tracking-Link Bug That Only Breaks Signed URLs

Here's a bug with a great property: it works perfectly for almost every link in your email, and silently breaks exactly the ones that matter most — the signed ones. Verify-email links. Signed download URLs. The links where a single wrong character means Laravel rejects the whole request. I shipped a one-line fix for it today in mail-history, and the why is more interesting than the diff.

The setup: self-hosted click tracking

mail-history does self-hosted open/click tracking. No third-party pixel service — it rewrites your outgoing email's HTML so every <a href> routes through a redirect endpoint first. The redirect records the click, then forwards the user to the real destination.

To survive the round trip, the original URL is encrypted into the tracking link and decrypted on the way out. The rewrite lives in one trait shared by both the Mailable concerns and the injection listener, so the logic exists in exactly one place:

protected function rewriteClickLinks(string $html, string $hash): string
{
    if ($hash === '' || $html === '') {
        return $html;
    }

    $excludePatterns = (array) config('mailhistory.tracking.click.exclude_patterns', ['*unsubscribe*']);

    return (string) preg_replace_callback(
        '/<a\s([^>]*?)href=["\']([^"\']+)["\']/i',
        function ($matches) use ($hash, $excludePatterns) {
            $attributes  = $matches[1];
            $originalUrl = $matches[2]; // <-- the bug lives here

            // skip mailto:/tel:/#/javascript: and excluded patterns...

            $trackingUrl = route('mailhistory.tracking.click', [
                'hash' => $hash,
                'url'  => Crypt::encryptString($originalUrl),
            ]);

            return '<a '.$attributes.'href="'.htmlspecialchars($trackingUrl).'"';
        },
        $html
    );
}

Read that $originalUrl = $matches[2] line again. We're pulling the URL straight out of rendered HTML.

The trap: rendered HTML is escaped HTML

By the time the trait sees the email body, Blade and Laravel's mail templates have already done their job — and part of that job is HTML-escaping attribute values. An ampersand in an href doesn't stay an ampersand. It becomes &.

For a normal link that's invisible, because the browser decodes it right back. But we're not handing this to a browser. We're calling Crypt::encryptString() on the raw captured string. So when Laravel renders a signed URL:

https://example.com/email/verify/1/abc?expires=123&signature=deadbeef

what actually sits in the href attribute is:

https://example.com/email/verify/1/abc?expires=123&amp;signature=deadbeef

We encrypt that — & and all. On click, the redirect decrypts it and forwards the user to a URL whose query string is ?expires=123&signature=deadbeef. Laravel's signed-URL validation recomputes the signature over the query string it sees, which now contains a literal amp; that was never part of what it signed. Verification fails.

The cruel part is the failure mode. Plain marketing links — https://example.com/page — have no query string, no ampersand, nothing to escape, so they pass straight through and look healthy. Everything appears fine in a quick test. It's only the signed URLs, the ones carrying expires and signature separated by &, that quietly die. The bug targets your most security-sensitive links and leaves the rest alone.

The fix: decode before you capture

Decode HTML entities the moment you read the URL, before anything downstream touches it:

// Decode HTML entities (e.g. &amp; -> &) captured from the rendered
// href so signed-URL query strings survive the encrypt/redirect round
// trip. Without this, "?expires=..&amp;signature=.." is redirected
// verbatim and breaks Laravel signature validation.
$originalUrl = html_entity_decode($matches[2], ENT_QUOTES | ENT_HTML5);

ENT_QUOTES | ENT_HTML5 so it handles both quote styles and the full HTML5 entity set, not just the basic four. Now & becomes & before encryption, the decrypted redirect target matches the originally-signed URL byte for byte, and signature validation passes.

One line. The whole bug was a mismatch between where you read a value (rendered, escaped HTML) and what you assumed it was (a raw URL).

Pin it with a test

A one-line fix like this is exactly the kind that gets silently reverted by a future "cleanup" refactor. So it gets a Pest test that asserts the real symptom — the decrypted URL contains a real &, not &:

it('decodes HTML entities in the tracked URL so signed query strings survive', function () {
    // As rendered by Laravel's mail templates, the ampersand in a signed URL
    // is HTML-escaped to &amp; inside the href attribute.
    $email = (new Email)->html(
        '<html><body><a href="https://example.com/email/verify/1/abc?expires=123&amp;signature=deadbeef">Verify</a></body></html>'
    );

    $rewritten = rewriteFixture($email, hash: 'abc123');

    preg_match('/url=([^"&]+)/', $rewritten, $m);
    $decrypted = Crypt::decryptString(urldecode($m[1]));

    expect($decrypted)
        ->toBe('https://example.com/email/verify/1/abc?expires=123&signature=deadbeef')
        ->not->toContain('&amp;');
});

The assertion is doing two jobs: it confirms the happy path (decrypts back to the exact signed URL) and it explicitly forbids the regression (not->toContain('&')). If someone deletes the html_entity_decode call six months from now, this test goes red and tells them why — the comment is right there in the test.

The takeaway

Any time you extract data from rendered HTML and feed it into something that isn't a browser — encryption, signing, a redirect, a webhook — assume it's been entity-escaped and decode first. The browser would have forgiven you. Crypt::encryptString() won't. And when the fix is a single line, spend the extra ten minutes on a test that names the exact failure, because one-liners are the easiest changes for a future cleanup to quietly undo.

推荐订阅源