create-nevela 0.7.1 → 0.9.1

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);
+    }
+}

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

@@ -0,0 +1,217 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Contracts\Mail\Mailable;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\Notification;
+use Illuminate\Support\Str;
+use Throwable;
+
+/**
+ * The mail a public form causes, with the limits that make it safe to send.
+ *
+ *     PublicMail::toVisitor($message->email, new MessageReceived($message));
+ *     PublicMail::toOwner(new NewMessage($message), line: $message->subject, url: $link);
+ *
+ * A form that writes back to whatever address was typed into it will write to anyone:
+ * type a stranger's address a thousand times and the site has sent them a thousand
+ * emails. So an address is written to at most once an hour and three times a day,
+ * counted across every form, and past that the email is dropped. The record is saved
+ * either way.
+ *
+ * The owner is the other inbox. A burst of submissions would bury the real ones, so only
+ * so many notices go out in an hour. The rest are held, and one email at the top of the
+ * hour names them. Nothing is lost: every record is in the dashboard.
+ *
+ * Both are queued, so a slow mail server doesn't keep a visitor waiting.
+ *
+ * Called while a record is being saved (a model's `created`, inside a transaction), the
+ * counting and the sending wait until the save is committed. A record that is rolled
+ * back sends nothing, and nothing here can spoil the transaction it was called in: on
+ * Postgres one failed statement, such as a lock someone else holds, would abort it all.
+ */
+final class PublicMail
+{
+    private const SENT = 'nevela_public_mail';
+
+    private const HELD = 'nevela_owner_digest';
+
+    /**
+     * Write to an address a form was given. False when it has been written to too often
+     * and this one was dropped. (Inside a transaction that isn't known yet: the answer is
+     * true, and the limit is applied when the transaction commits.)
+     */
+    public static function toVisitor(string $address, Mailable $mail): bool
+    {
+        $address = strtolower(trim($address));
+        if (! filter_var($address, FILTER_VALIDATE_EMAIL)) {
+            return false;
+        }
+        $who = self::fingerprint($address);
+
+        return self::whenSaved(fn () => self::counted("visitor:{$who}", function () use ($address, $mail, $who) {
+            $hour = self::sentSince('visitor', $who, now()->subHour());
+            $day = self::sentSince('visitor', $who, now()->subDay());
+            if ($hour >= (int) config('nevela.public.mail.visitor_per_hour', 1) || $day >= (int) config('nevela.public.mail.visitor_per_day', 3)) {
+                return false;
+            }
+            self::record('visitor', $who);
+            Mail::to($address)->queue($mail);
+
+            return true;
+        }));
+    }
+
+    /**
+     * Tell the owner a form was sent. False when the hour's notices have gone, and this
+     * one waits for the digest.
+     *
+     * @param  string|null  $line  What the digest says of it: a subject, or its first line
+     * @param  string|null  $url  Where in the dashboard it is
+     */
+    public static function toOwner(Mailable $mail, ?string $line = null, ?string $url = null): bool
+    {
+        $to = self::owner();
+        if ($to === null) {
+            return false;
+        }
+
+        return self::whenSaved(fn () => self::counted('owner', function () use ($mail, $line, $url, $to) {
+            if (self::sentSince('owner', 'owner', now()->subHour()) >= (int) config('nevela.public.notify.max_per_hour', 10)) {
+                DB::table(self::HELD)->insert([
+                    'id' => (string) Str::uuid(),
+                    'subject' => Str::limit(self::subjectOf($mail), 250, ''),
+                    'line' => $line === null ? null : Str::limit(trim(preg_replace('/\s+/', ' ', $line) ?? ''), 490),
+                    'url' => $url === null ? null : Str::limit($url, 2040, ''),
+                    'held_at' => now(),
+                ]);
+
+                return false;
+            }
+            self::record('owner', 'owner');
+            Mail::to($to)->queue($mail);
+
+            return true;
+        }));
+    }
+
+    /**
+     * Send what was held, as one email, and forget it. Run at the top of each hour by the
+     * scheduler (`nevela:digest`). Returns how many notices it named.
+     */
+    public static function digest(): int
+    {
+        $to = self::owner();
+        $held = DB::table(self::HELD)->orderBy('held_at')->get();
+        if ($held->isEmpty()) {
+            return 0;
+        }
+        if ($to !== null) {
+            Notification::route('mail', $to)->notify(new OwnerDigest(
+                $held->map(fn ($row) => ['subject' => (string) $row->subject, 'line' => $row->line, 'url' => $row->url])->all(),
+                Carbon::parse($held->first()->held_at)->format('H:i'),
+            ));
+        }
+        DB::table(self::HELD)->whereIn('id', $held->pluck('id')->all())->delete();
+
+        return $held->count();
+    }
+
+    /** Forget who was written to more than a few days ago, and old counts of what was refused. */
+    public static function prune(): void
+    {
+        try {
+            DB::table(self::SENT)->where('sent_at', '<', now()->subDays(2))->delete();
+            DB::table('nevela_form_blocks')->where('day', '<', now()->subDays(90)->toDateString())->delete();
+        } catch (Throwable) {
+            // Not migrated yet.
+        }
+    }
+
+    /** Who a form's notices go to: nevela.public.notify.to, or the address the app sends from. */
+    public static function owner(): ?string
+    {
+        $to = config('nevela.public.notify.to') ?: config('mail.from.address');
+
+        return is_string($to) && filter_var($to, FILTER_VALIDATE_EMAIL) ? $to : null;
+    }
+
+    /** An address as it is counted by: enough to tell it from another, not to read it back. */
+    public static function fingerprint(string $address): string
+    {
+        return hash_hmac('sha256', strtolower(trim($address)), 'nevela-mail|'.config('app.key'));
+    }
+
+    private static function sentSince(string $kind, string $recipient, Carbon $since): int
+    {
+        return DB::table(self::SENT)->where('kind', $kind)->where('recipient', $recipient)->where('sent_at', '>', $since)->count();
+    }
+
+    private static function record(string $kind, string $recipient): void
+    {
+        DB::table(self::SENT)->insert(['id' => (string) Str::uuid(), 'kind' => $kind, 'recipient' => $recipient, 'sent_at' => now()]);
+    }
+
+    /** What an email is headed, for the digest to name it by: its subject, or failing that what it is called. */
+    private static function subjectOf(Mailable $mail): string
+    {
+        try {
+            // Asked of a copy: a mailable that sets its subject in build() must not be built twice.
+            $probe = clone $mail;
+            if (method_exists($probe, 'envelope')) {
+                $subject = $probe->envelope()->subject;
+            } else {
+                if (method_exists($probe, 'build')) {
+                    app()->call([$probe, 'build']);
+                }
+                $subject = $probe->subject ?? null;
+            }
+        } catch (Throwable) {
+            $subject = null;
+        }
+
+        return is_string($subject) && $subject !== '' ? $subject : Str::headline(class_basename($mail));
+    }
+
+    /**
+     * Now, or once the transaction this was called in has committed. Never inside it.
+     *
+     * @param  callable(): bool  $send
+     */
+    private static function whenSaved(callable $send): bool
+    {
+        $sent = null;
+        // Runs at once where there is no transaction to wait for.
+        DB::afterCommit(function () use (&$sent, $send) {
+            $sent = $send();
+        });
+
+        return $sent ?? true;
+    }
+
+    /**
+     * Count and send as one step, so two requests at the same moment can't both be the
+     * last one allowed. Mail is never the reason a form fails: a problem here is reported
+     * and the answer is "not sent".
+     *
+     * @param  callable(): bool  $send
+     */
+    private static function counted(string $name, callable $send): bool
+    {
+        try {
+            try {
+                return (bool) Cache::lock('nevela-mail:'.$name, 10)->block(5, $send);
+            } catch (\Illuminate\Contracts\Cache\LockTimeoutException) {
+                return (bool) $send();
+            }
+        } catch (Throwable $e) {
+            report($e);
+
+            return false;
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Response;
+
+/**
+ * A public form that was turned away, and what its sender is told.
+ *
+ * Which of three it is depends on who could be on the other end. A filled honeypot or a
+ * forged token is a program, and is told it worked: it learns nothing to adjust to. A
+ * failed robot check can happen to a person, so they are told, in a sentence. A problem
+ * with the address they typed is a validation message on that field, like any other.
+ */
+final class Refusal
+{
+    /** Refusals nobody is told about. The answer is the one a success gets, and nothing is stored. */
+    public const SILENT = ['honeypot', 'forged', 'too_fast'];
+
+    public function __construct(
+        public readonly string $reason,
+        public readonly int $status = 422,
+        public readonly string $message = '',
+        public readonly ?string $field = null,
+    ) {}
+
+    public function silent(): bool
+    {
+        return in_array($this->reason, self::SILENT, true);
+    }
+
+    public function response(): JsonResponse|Response
+    {
+        if ($this->silent()) {
+            $response = response()->noContent(201);
+            // Whoever is building the form sees why nothing arrived. A bot in production doesn't.
+            if (config('app.debug')) {
+                $response->header('X-Nevela-Blocked', $this->reason);
+            }
+
+            return $response;
+        }
+        if ($this->field !== null) {
+            return response()->json(['error' => 'Validation failed.', 'issues' => [['path' => $this->field, 'message' => $this->message]]], $this->status);
+        }
+
+        return response()->json(['error' => $this->message, 'code' => strtoupper($this->reason)], $this->status);
+    }
+}