Consult the host's mail policy on preview and attachment routes

[MACscr]

Problem

#84 / #86 put the preview and attachment routes behind Authenticate and canManageMails(). That answers "may this user use the mail log at all?", which is the same question every Resource, Page and Widget asks — but the controllers still resolve the mail by id and serve it:

$mail = $mailModel::findOrFail($request->route('mail'));

return response($mail->html, …);

Hosts that need a second answer — "may this user see this mail?" — have no hook. In a multi-tenant application every user who may open the mail log can read any tenant's mail, and download its attachments, by changing the id in the URL. Wrapping the routes in extra middleware from the host is possible but means re-declaring Mails::routes() and its middleware by hand, which is exactly the class of drift #84 was written to prevent.

Most applications are not multi-tenant and do not need that second answer.

Fix

When the host has registered a policy for the mail model, both controllers authorize the view ability for the authenticated user against the requested mail before serving it:

if (Gate::getPolicyFor($mail) !== null) {
    Gate::authorize('view', $mail);
}

• Hosts without a policy are unaffected — Gate::getPolicyFor() returns null and nothing changes.
• Hosts with a policy get the same per-record rule on the raw routes that they already apply in their own resources. The policy receives the authenticated user and that mail.
• canManageMails() keeps its role as the coarse gate; this runs after it, inside the same middleware stack.

The README section on canManageMails() now documents the policy hook with a tenant example, and states that applications which never register a policy are unchanged.

Tests

Two cases in tests/MailRouteSecurityTest.php using an AllowSpecificUserPolicy fixture. The same mail is forbidden for one user and served for another, on both the preview and an attachment download. Hosts that do not register a policy are covered by the existing route tests, which still pass with no policy registered.

[Casmo]

What is the DenyOddMailPolicy class testing exactly? There is no Gate check for the $user.

[MACscr]

The even/odd fixture was only a deterministic allow/deny, so it never looked at $user. That made it look like the routes were not actually authorizing the authenticated user.

Most apps are not multi-tenant and never register a mail policy. For those, canManageMails() is still the only check and these routes are unchanged. A host that does need a per-mail rule registers a policy, and view then receives that user and that mail.

The fixture is now AllowSpecificUserPolicy: the same mail is forbidden for one user and served for another, on both the preview and the attachment download.