create-nevela 0.8.0 → 0.9.2

package/template/laravel/src/Forms/Confirmation.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Request;
+use Nevela\Laravel\Auth\Web;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Trash\Trash;
+
+/**
+ * Proving an address belongs to whoever typed it: the descriptor's "confirm".
+ *
+ *     "create": { "fields": ["email"], "confirm": "email" }
+ *
+ * The record is saved unconfirmed and one link is emailed to the address. Following it
+ * confirms the record. This is for a list people join, where the other checks aren't
+ * enough: an address can be real, take mail and belong to someone who never asked.
+ *
+ * The link is sent through PublicMail::toVisitor(), so its limits apply: signing a
+ * stranger up a hundred times sends them one email.
+ */
+final class Confirmation
+{
+    /** How long an address has to follow its link before the record is removed, in hours. */
+    public static function hours(): int
+    {
+        return max(1, (int) config('nevela.public.confirm.hours', 48));
+    }
+
+    /** What the link carries: only this app could have written it, for this record and this address. */
+    public static function hash(Descriptor $resource, mixed $id, string $address): string
+    {
+        return hash_hmac('sha256', $resource->slug.'|'.$id.'|'.strtolower(trim($address)), 'nevela-confirm|'.config('app.key'));
+    }
+
+    /** The page of the web app that confirms a record when it is opened. */
+    public static function link(Descriptor $resource, mixed $id, string $address, ?Request $request = null): string
+    {
+        return Web::url((string) config('nevela.public.confirm.path', '/confirm'), [
+            'list' => $resource->slug,
+            'id' => (string) $id,
+            'key' => self::hash($resource, $id, $address),
+        ], $request);
+    }
+
+    /** Email the link. False when the address has been written to too often lately, and nothing went. */
+    public static function send(Descriptor $resource, mixed $id, string $address, ?Request $request = null): bool
+    {
+        return PublicMail::toVisitor($address, new ConfirmAddress(
+            (string) config('app.name', 'Nevela'),
+            self::link($resource, $id, $address, $request),
+            self::hours(),
+        ));
+    }
+
+    /**
+     * Remove the records whose link was never followed in time. Run each night with the trash.
+     *
+     * @return array<string, int> How many were removed, by resource name
+     */
+    public static function purge(): array
+    {
+        $removed = [];
+        $cutoff = now()->subHours(self::hours());
+        foreach (Nevela::all() as $resource) {
+            $model = "App\\Models\\{$resource->name}";
+            if ($resource->public?->confirm === null || ! class_exists($model) || ! method_exists($model, 'confirms') || ! $model::confirms()) {
+                continue;
+            }
+            $count = 0;
+            // Whether or not someone put it in the trash meanwhile: it was never anyone's record.
+            $model::query()->withoutGlobalScopes()->whereNull('confirmed_at')->where('created_at', '<', $cutoff)->orderBy((new $model)->getKeyName())
+                ->chunkById(200, function ($records) use (&$count) {
+                    foreach ($records as $record) {
+                        /** @var Model $record */
+                        $count += Trash::purge($record) ? 1 : 0;
+                    }
+                });
+            if ($count > 0) {
+                $removed[$resource->name] = $count;
+            }
+        }
+
+        return $removed;
+    }
+}

package/template/laravel/src/Forms/Disposable.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+/**
+ * Domains that hand out addresses to be thrown away: mailinator.com and its many kin.
+ *
+ * An address there is real for ten minutes, which is long enough to pass every other
+ * check and no use for writing back. The list ships with the package (the public domain
+ * list kept at github.com/disposable-email-domains), and `php artisan nevela:disposable`
+ * fetches the current one into the app's storage, where it is read from in preference.
+ */
+final class Disposable
+{
+    public const SOURCE = 'https://raw.githubusercontent.com/disposable-email-domains/disposable-email-domains/main/disposable_email_blocklist.conf';
+
+    /** @var array<string, true>|null */
+    private static ?array $domains = null;
+
+    /** Whether a domain, or one it is a subdomain of, is on the list. */
+    public static function is(string $domain): bool
+    {
+        $domain = strtolower(trim($domain, " .\t\n\r"));
+        $list = self::domains();
+        // mail.mailinator.com is mailinator.com's too.
+        while ($domain !== '' && str_contains($domain, '.')) {
+            if (isset($list[$domain])) {
+                return true;
+            }
+            $domain = substr($domain, (int) strpos($domain, '.') + 1);
+        }
+
+        return false;
+    }
+
+    /** Where a refreshed list is kept, in the app's own storage. */
+    public static function refreshedPath(): string
+    {
+        return storage_path('app/nevela/disposable-domains.txt');
+    }
+
+    public static function count(): int
+    {
+        return count(self::domains());
+    }
+
+    public static function forget(): void
+    {
+        self::$domains = null;
+    }
+
+    /** @return array<string, true> */
+    private static function domains(): array
+    {
+        if (self::$domains !== null) {
+            return self::$domains;
+        }
+        try {
+            $refreshed = self::refreshedPath();
+        } catch (\Throwable) {
+            $refreshed = null; // no app to have a storage folder: the list is read on its own in a test
+        }
+        $file = $refreshed !== null && is_file($refreshed) ? $refreshed : dirname(__DIR__, 2).'/resources/disposable-domains.txt';
+        $domains = [];
+        foreach (@file($file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) ?: [] as $line) {
+            $line = strtolower(trim($line));
+            if ($line !== '' && $line[0] !== '#') {
+                $domains[$line] = true;
+            }
+        }
+
+        return self::$domains = $domains;
+    }
+}

package/template/laravel/src/Forms/FormBlocks.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+use Throwable;
+
+/**
+ * What a public form turned away, counted by resource, reason and day.
+ *
+ * The dashboard shows it on the resource's page ("Blocked this week: 132"). Without it
+ * a form that is well protected and a form nobody uses look the same from the inside.
+ */
+final class FormBlocks
+{
+    private const TABLE = 'nevela_form_blocks';
+
+    /** What each reason is called where a person reads it. */
+    public const LABELS = [
+        'honeypot' => 'filled the hidden field',
+        'forged' => 'no form token',
+        'too_fast' => 'sent too fast',
+        'expired' => 'form left open too long',
+        'robot' => 'robot check',
+        'hostname' => 'robot check solved on another site',
+        'disposable' => 'throwaway address',
+        'undeliverable' => 'address that takes no mail',
+        'throttled' => 'too many from one address',
+        'unconfigured' => 'robot check not set up',
+        'unreachable' => 'robot check unreachable',
+    ];
+
+    /** One more of this reason, today. Never the reason a request fails: counting is not what the form is for. */
+    public static function record(string $resource, string $reason): void
+    {
+        try {
+            $day = now()->toDateString();
+            $where = ['resource' => $resource, 'reason' => $reason, 'day' => $day];
+            if (DB::table(self::TABLE)->where($where)->increment('count') === 0) {
+                DB::table(self::TABLE)->insert($where + ['id' => (string) Str::uuid(), 'count' => 1]);
+            }
+        } catch (Throwable) {
+            // The table isn't there yet (not migrated), or two requests made today's row at once.
+        }
+    }
+
+    /**
+     * How many were turned away in the last `$days` days, in all and by reason, most first.
+     *
+     * @return array{total: int, days: int, reasons: list<array{reason: string, label: string, count: int}>}
+     */
+    public static function summary(string $resource, int $days = 7): array
+    {
+        $reasons = [];
+        try {
+            if (Schema::hasTable(self::TABLE)) {
+                $rows = DB::table(self::TABLE)
+                    ->where('resource', $resource)
+                    ->where('day', '>', now()->subDays($days)->toDateString())
+                    ->selectRaw('reason, sum(count) as total')
+                    ->groupBy('reason')
+                    ->get();
+                foreach ($rows as $row) {
+                    $reasons[] = ['reason' => (string) $row->reason, 'label' => self::LABELS[$row->reason] ?? (string) $row->reason, 'count' => (int) $row->total];
+                }
+            }
+        } catch (Throwable) {
+            $reasons = [];
+        }
+        usort($reasons, fn (array $a, array $b) => $b['count'] <=> $a['count']);
+
+        return ['total' => array_sum(array_column($reasons, 'count')), 'days' => $days, 'reasons' => $reasons];
+    }
+}

package/template/laravel/src/Forms/FormGuard.php

@@ -0,0 +1,359 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\RateLimiter;
+use Illuminate\Support\Facades\Validator;
+use Nevela\Laravel\Auth\Web;
+use Nevela\Laravel\Support\Descriptor;
+use Throwable;
+
+/**
+ * What stands between a public form and whoever sends it: the descriptor's "protect".
+ *
+ *   "protect": { "turnstile": true, "honeypot": true, "minSeconds": 3, "email": "email" }
+ *
+ * The checks run in this order, cheapest first, before anything is validated or stored:
+ *
+ * 1. the honeypot: a field no person sees has a value;
+ * 2. the time taken: the form came back sooner than a person could fill it in, or its
+ *    token is missing, forged or too old;
+ * 3. Turnstile: Cloudflare, asked by this server, doesn't vouch for the visitor;
+ * 4. the address: its domain takes no mail, or is a throwaway one;
+ * 5. the count for that address: one person, however many networks they send from.
+ *
+ * A resource with no "protect" passes straight through, as before there was any.
+ */
+final class FormGuard
+{
+    /** The form's own token, and Turnstile's, as a form sends them. Neither is a field of the resource. */
+    public const TOKEN = '_form';
+
+    public const TURNSTILE = '_turnstile';
+
+    /** What a person is told when it can't be shown they are one. A person can get this, so it says what to do. */
+    public const NOT_A_PERSON = "We couldn't confirm you're not a robot. Please try again.";
+
+    /**
+     * Names a bot fills in because they look like something a form wants. The first that
+     * isn't a field of the form is used. None is something a browser keeps for a person
+     * (a company, a second address line): filled in for them, it would turn them away.
+     */
+    private const BAIT = ['website', 'homepage', 'url', 'site', 'web'];
+
+    /**
+     * How long a token that was taken is remembered, in seconds, so it can't be taken
+     * again. Cloudflare's are good for 300; past that it refuses them itself.
+     */
+    private const REMEMBERED = 600;
+
+    /** Where a form is built, and never where it is live. */
+    private const LOCAL = ['localhost', '127.0.0.1'];
+
+    /** Asks whether a domain takes mail. Replaced in tests, which have no DNS to ask. @var (callable(string): bool)|null */
+    public static $takesMail = null;
+
+    /**
+     * What a form needs before it is shown: the token to send back, the name of the field
+     * to leave empty, and whether the robot check is on.
+     *
+     * @return array{token: string|null, honeypot: string|null, minSeconds: int, turnstile: bool, action: string|null}
+     */
+    public static function issue(Descriptor $resource): array
+    {
+        $protect = $resource->public?->protect ?? [];
+        $timed = ($protect['honeypot'] ?? false) || ($protect['minSeconds'] ?? 0) > 0;
+
+        return [
+            'token' => $timed ? self::sign($resource->name, now()->getTimestamp()) : null,
+            'honeypot' => ($protect['honeypot'] ?? false) ? self::honeypot($resource) : null,
+            'minSeconds' => (int) ($protect['minSeconds'] ?? 0),
+            // On only where the answer can be checked: see robot().
+            'turnstile' => $robot = ($protect['turnstile'] ?? false) && self::robotCheck() === 'on',
+            // What the widget is rendered with, and Cloudflare hands back: which form the check was for.
+            'action' => $robot ? self::action($resource) : null,
+        ];
+    }
+
+    /**
+     * The name a form's robot check is made under. The widget is given it, Cloudflare
+     * returns it with its answer, and the two must agree: a token solved for one form
+     * can't be spent on another. (Cloudflare allows letters, digits, _ and -, up to 32.)
+     *
+     * A slug longer than that is cut, and ends in a few characters made from the whole of
+     * it: two long slugs that begin alike are still two names.
+     */
+    public static function action(Descriptor $resource): string
+    {
+        $name = (string) preg_replace('/[^A-Za-z0-9_-]/', '-', $resource->slug);
+
+        return strlen($name) <= 32 ? $name : substr($name, 0, 23).'-'.substr(hash('sha256', $resource->slug), 0, 8);
+    }
+
+    /**
+     * The sites a robot check may have been solved on: TURNSTILE_HOSTNAMES, or failing that
+     * the web app's own. A name stands for its subdomains too, as it does on the widget.
+     *
+     * A widget usually lists localhost beside the real site, so the form can be built. This
+     * is what stops a token solved on someone's own machine being spent on the live form:
+     * in production localhost is never accepted, whatever the setting says.
+     *
+     * @return list<string>
+     */
+    public static function hostnames(?Request $request = null): array
+    {
+        $set = config('nevela.public.turnstile.hostnames');
+        $names = array_values(array_filter(array_map(
+            fn ($name) => strtolower(trim((string) $name)),
+            is_array($set) ? $set : explode(',', (string) $set),
+        )));
+        if ($names === []) {
+            $names = [strtolower(Web::host($request))];
+        }
+
+        return app()->environment('production')
+            ? array_values(array_diff($names, self::LOCAL))
+            : array_values(array_unique([...$names, ...self::LOCAL]));
+    }
+
+    /**
+     * Whether the robot check can be made here: "on"; "skipped", in development with no
+     * secret key; or "refusing", in production with something it needs missing. A form that
+     * asks for the check never goes without it quietly.
+     */
+    public static function robotCheck(): string
+    {
+        $production = app()->environment('production');
+        if (self::secret() === '') {
+            return $production ? 'refusing' : 'skipped';
+        }
+
+        return $production && self::hostnames() === [] ? 'refusing' : 'on';
+    }
+
+    /** The field a person never sees, for this form. */
+    public static function honeypot(Descriptor $resource): string
+    {
+        foreach (self::BAIT as $name) {
+            if (! isset($resource->fields[$name])) {
+                return $name;
+            }
+        }
+
+        return '_'.self::BAIT[0];
+    }
+
+    /**
+     * The input without what the guard added to the form: what is left is the resource's own fields.
+     *
+     * @param  array<string, mixed>  $input
+     * @return array<string, mixed>
+     */
+    public static function strip(Descriptor $resource, array $input): array
+    {
+        if (! ($resource->public?->protected() ?? false)) {
+            return $input;
+        }
+        unset($input[self::TOKEN], $input[self::TURNSTILE], $input['cf-turnstile-response'], $input[self::honeypot($resource)]);
+
+        return $input;
+    }
+
+    /**
+     * Whether to turn this one away, and why. Null lets it through to validation.
+     *
+     * @param  array<string, mixed>  $input
+     */
+    public static function check(Descriptor $resource, Request $request, array $input): ?Refusal
+    {
+        $public = $resource->public;
+        if ($public === null || ! $public->protected()) {
+            return null;
+        }
+        $protect = $public->protect;
+
+        if ($protect['honeypot'] && self::filled($input[self::honeypot($resource)] ?? null)) {
+            return new Refusal('honeypot');
+        }
+
+        if ($protect['honeypot'] || $protect['minSeconds'] > 0) {
+            $issued = self::issuedAt($resource->name, $input[self::TOKEN] ?? null);
+            if ($issued === null) {
+                return new Refusal('forged');
+            }
+            $age = now()->getTimestamp() - $issued;
+            if ($age < $protect['minSeconds']) {
+                return new Refusal('too_fast');
+            }
+            // Left open for hours, by a person. The form asks for a new token after every
+            // attempt, so trying again is all they need to do.
+            if ($age > (int) config('nevela.public.form_lifetime', 7200)) {
+                return new Refusal('expired', 422, self::NOT_A_PERSON);
+            }
+        }
+
+        if ($protect['turnstile'] && ($refusal = self::robot($resource, $request, $input)) !== null) {
+            return $refusal;
+        }
+
+        $field = $protect['email'];
+        $address = $field !== null && is_string($input[$field] ?? null) ? strtolower(trim($input[$field])) : null;
+        // An address that isn't one at all is validation's to say, in its own words.
+        if ($address !== null && filter_var($address, FILTER_VALIDATE_EMAIL)) {
+            $domain = substr($address, (int) strrpos($address, '@') + 1);
+            if (Disposable::is($domain)) {
+                return new Refusal('disposable', 422, 'Use an address you keep. This one is from a throwaway service.', $field);
+            }
+            if (! self::takesMail($address, $domain)) {
+                return new Refusal('undeliverable', 422, "This address's domain doesn't receive email. Check the spelling.", $field);
+            }
+
+            // The route's throttle counts a visitor. This counts an address, wherever it is sent from.
+            [$most, $minutes] = array_map('intval', explode(',', $public->createThrottle));
+            $key = "nevela-form:{$resource->slug}:".sha1($address);
+            if (RateLimiter::tooManyAttempts($key, $most)) {
+                return new Refusal('throttled', 429, 'Too many requests. Try again shortly.');
+            }
+            RateLimiter::hit($key, $minutes * 60);
+        }
+
+        return null;
+    }
+
+    /**
+     * Whether Cloudflare vouches for the visitor. It is asked from here, with the secret
+     * only this server has: what the browser says about its own check is not evidence.
+     *
+     * With no secret set the check can't be made. In development it is skipped, so a form
+     * can be built before the keys exist. In production the form is refused outright: a
+     * form that asked for the check and quietly went without would be open, and nobody
+     * would know.
+     *
+     * A yes from Cloudflare says a person solved a check for this widget. It is taken only
+     * if it was solved on this site and for this form: see hostnames() and action().
+     *
+     * @param  array<string, mixed>  $input
+     */
+    private static function robot(Descriptor $resource, Request $request, array $input): ?Refusal
+    {
+        $secret = self::secret();
+        $unconfigured = new Refusal('unconfigured', 503, "This form can't be sent at the moment. Please try again later.");
+        $state = self::robotCheck();
+        if ($state !== 'on') {
+            return $state === 'refusing' ? $unconfigured : null;
+        }
+        $token = $input[self::TURNSTILE] ?? $input['cf-turnstile-response'] ?? null;
+        $failed = new Refusal('robot', 422, self::NOT_A_PERSON);
+        // (Cloudflare's tokens are at most 2048 characters. Anything longer is not one.)
+        if (! is_string($token) || $token === '' || strlen($token) > 2048) {
+            return $failed;
+        }
+        // One this app has already taken. Cloudflare says a token is good once, and has been
+        // seen to say yes to the same one again, so that is kept count of here as well.
+        $taken = 'nevela-turnstile:'.hash('sha256', $token);
+        if (Cache::has($taken)) {
+            return $failed;
+        }
+
+        try {
+            $response = Http::asForm()->timeout(8)->post((string) config('nevela.public.turnstile.verify_url', 'https://challenges.cloudflare.com/turnstile/v0/siteverify'), [
+                'secret' => $secret,
+                'response' => $token,
+                // The visitor's, where the web app passed it on: see Http\PublicThrottle.
+                'remoteip' => $request->ip(),
+            ]);
+        } catch (Throwable) {
+            $response = null;
+        }
+        // Cloudflare not answering is not a yes. The person is asked to try again; nothing is let through.
+        if ($response === null || $response->serverError()) {
+            return new Refusal('unreachable', 503, "We couldn't check the form just now. Please try again in a moment.");
+        }
+
+        // A token is good once: a second use is answered with "timeout-or-duplicate", which is a no.
+        if ($response->json('success') !== true) {
+            return $failed;
+        }
+        // The keys Cloudflare publishes for testing say yes to everything, name no form, and
+        // call every site example.com. Good for building a form. On a live one they are no check at all.
+        if ($response->json('metadata.result_with_testing_key') === true) {
+            return app()->environment('production') ? $unconfigured : null;
+        }
+
+        $solvedOn = strtolower((string) $response->json('hostname'));
+        $expected = self::hostnames($request);
+        $here = false;
+        foreach ($expected as $name) {
+            $here = $here || $solvedOn === $name || str_ends_with($solvedOn, '.'.$name);
+        }
+        if (! $here) {
+            // Most often a setting, not an attack: the site is served from a name this app wasn't told of.
+            logger()->warning("Nevela refused a robot check solved on \"{$solvedOn}\". This app accepts: ".implode(', ', $expected).'. If that is your site, add it to TURNSTILE_HOSTNAMES or correct NEVELA_WEB_URL.');
+
+            return new Refusal('hostname', 422, self::NOT_A_PERSON);
+        }
+
+        if ((string) $response->json('action') !== self::action($resource)) {
+            return $failed;
+        }
+
+        // Taken, once: of two requests that arrive together with the same token, the second
+        // finds it there. (The test keys' one token is everyone's, and is not kept.)
+        return Cache::add($taken, true, self::REMEMBERED) ? null : $failed;
+    }
+
+    public static function secret(): string
+    {
+        return (string) config('nevela.public.turnstile.secret', '');
+    }
+
+    private static function takesMail(string $address, string $domain): bool
+    {
+        if (self::$takesMail !== null) {
+            return (bool) (self::$takesMail)($domain);
+        }
+        // Laravel's own check, which needs PHP's intl extension to read a domain in another script.
+        if (function_exists('idn_to_ascii')) {
+            return Validator::make(['address' => $address], ['address' => 'email:rfc,dns'])->passes();
+        }
+
+        // A domain with no MX record still takes mail at its A record, so either will do.
+        return checkdnsrr($domain.'.', 'MX') || checkdnsrr($domain.'.', 'A') || checkdnsrr($domain.'.', 'AAAA');
+    }
+
+    private static function filled(mixed $value): bool
+    {
+        return is_scalar($value) ? trim((string) $value) !== '' : $value !== null && $value !== [];
+    }
+
+    /** A token that says when this form was handed out, in a way only this app could have written. */
+    private static function sign(string $resource, int $time): string
+    {
+        $payload = rtrim(strtr(base64_encode($resource.'|'.$time), '+/', '-_'), '=');
+
+        return $payload.'.'.hash_hmac('sha256', $payload, self::key());
+    }
+
+    /** When a token was issued, or null when it isn't one of this app's for this form. */
+    private static function issuedAt(string $resource, mixed $token): ?int
+    {
+        if (! is_string($token) || substr_count($token, '.') !== 1) {
+            return null;
+        }
+        [$payload, $signature] = explode('.', $token);
+        if (! hash_equals(hash_hmac('sha256', $payload, self::key()), $signature)) {
+            return null;
+        }
+        [$for, $time] = array_pad(explode('|', (string) base64_decode(strtr($payload, '-_', '+/'), true), 2), 2, '');
+
+        return $for === $resource && ctype_digit($time) ? (int) $time : null;
+    }
+
+    private static function key(): string
+    {
+        return 'nevela-form|'.config('app.key');
+    }
+}

package/template/laravel/src/Forms/OwnerDigest.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Notifications\Notification;
+
+/**
+ * One email for the notices that were held back: "14 more enquiries since 14:05".
+ *
+ * Each is named by its subject and first line, with a link to where it is in the
+ * dashboard. See PublicMail::toOwner().
+ */
+final class OwnerDigest extends Notification implements ShouldQueue
+{
+    use Queueable;
+
+    /** The most a digest lists by name. Beyond it the email says how many more there are. */
+    public const LISTED = 50;
+
+    /**
+     * @param  list<array{subject: string, line: string|null, url: string|null}>  $held
+     * @param  string  $since  The time the first of them arrived: "14:05"
+     */
+    public function __construct(public array $held, public string $since) {}
+
+    /** @return list<string> */
+    public function via(object $notifiable): array
+    {
+        return ['mail'];
+    }
+
+    public function subject(): string
+    {
+        $count = count($this->held);
+
+        return $count === 1 ? "1 more enquiry since {$this->since}" : number_format($count)." more enquiries since {$this->since}";
+    }
+
+    public function toMail(object $notifiable): MailMessage
+    {
+        $message = (new MailMessage)
+            ->subject($this->subject())
+            ->line('These arrived after the hour\'s notices had gone out. Every one of them is in the dashboard.');
+        foreach (array_slice($this->held, 0, self::LISTED) as $row) {
+            $text = '**'.self::plain($row['subject']).'**'.($row['line'] !== null && $row['line'] !== '' ? ': '.self::plain($row['line']) : '');
+            $message->line($row['url'] !== null && $row['url'] !== '' ? "{$text} ([open]({$row['url']}))" : $text);
+        }
+        if (($more = count($this->held) - self::LISTED) > 0) {
+            $message->line("And {$more} more.");
+        }
+
+        return $message;
+    }
+
+    /** What a visitor typed, as words: the email is written in Markdown, and theirs must not be read as any. */
+    private static function plain(string $text): string
+    {
+        return (string) preg_replace('/([\\\\`*_{}\[\]()#+\-.!|<>])/', '\\\\$1', $text);
+    }
+}