create-nevela 0.7.1 → 0.9.1

package/template/laravel/src/Console/DigestCommand.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Nevela\Laravel\Forms\PublicMail;
+
+final class DigestCommand extends Command
+{
+    protected $signature = 'nevela:digest';
+
+    protected $description = 'Send the owner one email for the form notices that were held back in a busy hour';
+
+    public function handle(): int
+    {
+        if (PublicMail::owner() === null) {
+            $this->components->warn('There is nobody to send it to. Set NEVELA_NOTIFY_TO, or the address the app sends mail from.');
+
+            return self::SUCCESS;
+        }
+        $count = PublicMail::digest();
+        $this->components->info($count === 0
+            ? 'No notices are waiting.'
+            : 'Sent one email naming '.number_format($count).' notice(s) to '.PublicMail::owner().'.');
+
+        return self::SUCCESS;
+    }
+}

package/template/laravel/src/Console/DisposableCommand.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Http;
+use Nevela\Laravel\Forms\Disposable;
+use Throwable;
+
+final class DisposableCommand extends Command
+{
+    protected $signature = 'nevela:disposable {--url= : Fetch the list from somewhere else}';
+
+    protected $description = 'Fetch the current list of throwaway email domains a protected form refuses';
+
+    public function handle(): int
+    {
+        $url = (string) ($this->option('url') ?: Disposable::SOURCE);
+        try {
+            $response = Http::timeout(30)->get($url);
+        } catch (Throwable $e) {
+            $this->components->error("Couldn't fetch the list: ".$e->getMessage());
+
+            return self::FAILURE;
+        }
+        $domains = [];
+        foreach (preg_split('/\R/', $response->successful() ? $response->body() : '') ?: [] as $line) {
+            $line = strtolower(trim($line));
+            // One domain a line. Anything else is not the list: an error page, a redirect to a sign-in.
+            if ($line !== '' && $line[0] !== '#' && preg_match('/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/', $line)) {
+                $domains[$line] = true;
+            }
+        }
+        // The list has thousands. A few lines is something else, and would let every throwaway address through.
+        if (count($domains) < 1000) {
+            $this->components->error("What came back from {$url} isn't the list (".count($domains).' domains). The one in use is unchanged.');
+
+            return self::FAILURE;
+        }
+        ksort($domains);
+        $path = Disposable::refreshedPath();
+        is_dir(dirname($path)) || mkdir(dirname($path), 0775, true);
+        file_put_contents($path, implode("\n", array_keys($domains))."\n", LOCK_EX);
+        Disposable::forget();
+        $this->components->info(number_format(count($domains)).' throwaway domains, kept in '.str_replace(base_path().DIRECTORY_SEPARATOR, '', $path).'.');
+
+        return self::SUCCESS;
+    }
+}

package/template/laravel/src/Console/GenerateCommand.php

@@ -28,10 +28,11 @@ final class GenerateCommand extends Command
      * @param  list<string>  $createMigrations  The contents of the table's own migration(s); none for a resource that is new
      * @param  bool  $written  Whether an add_trash_to_… migration exists for the table already
      * @param  bool  $columnExists  Whether the table has deleted_at in the database now
+     * @param  bool  $adopted  Whether the table was there before Nevela: then there may be no migration of that name to read
      */
-    public static function needsTrashMigration(array $createMigrations, bool $written, bool $columnExists): bool
+    public static function needsTrashMigration(array $createMigrations, bool $written, bool $columnExists, bool $adopted = false): bool
     {
-        if ($createMigrations === []) {
+        if ($createMigrations === [] && ! $adopted) {
             return false;
         }
         foreach ($createMigrations as $contents) {
@@ -43,6 +44,27 @@ final class GenerateCommand extends Command
         return $written || ! $columnExists;
     }
 
+    /**
+     * Whether a resource whose form proves an address needs the migration that adds the
+     * column for it: when its table was made without one. A new resource's own migration
+     * has it.
+     *
+     * @param  list<string>  $createMigrations  The contents of the table's own migration(s); none for a resource that is new
+     */
+    public static function needsConfirmMigration(array $createMigrations, bool $adopted = false): bool
+    {
+        if ($createMigrations === []) {
+            return $adopted;
+        }
+        foreach ($createMigrations as $contents) {
+            if (str_contains($contents, 'confirmed_at')) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
     /** Whether the table has the column now. No, where there is no database to ask. */
     private static function hasTrashColumn(string $table): bool
     {
@@ -127,11 +149,16 @@ final class GenerateCommand extends Command
             // resource's own migration, written by the line above, already has the column.
             $made = array_map(fn (string $file) => (string) file_get_contents($file), glob(database_path("migrations/*_create_{$descriptor->table}_table.php")) ?: []);
             $written = (glob(database_path("migrations/*_add_trash_to_{$descriptor->table}_table.php")) ?: []) !== [];
-            if (self::needsTrashMigration($made, $written, self::hasTrashColumn($descriptor->table))) {
+            if (self::needsTrashMigration($made, $written, self::hasTrashColumn($descriptor->table), $descriptor->adopted)) {
                 $files[] = $generator->trashMigrationFile($descriptor);
             }
+            // The same for "confirm" added to a resource whose table is already made.
+            if ($descriptor->public?->confirm !== null && self::needsConfirmMigration($made, $descriptor->adopted)) {
+                $files[] = $generator->confirmMigrationFile($descriptor);
+            }
         }
         $files[] = $generator->routes($all);
+        $files[] = $generator->publicRoutes($all);
         $files[] = $generator->registry($all);
         $files[] = $generator->authConfig((array) config('nevela.auth', []));
 
@@ -168,6 +195,14 @@ final class GenerateCommand extends Command
         if ($edited) {
             $command->components->warn("{$edited} file(s) skipped because you edited their generated block. Move your changes outside it, or rerun with --force.");
         }
+        // A model written before its resource was made public has no scope saying which
+        // records are, and without one none are. Said, so an empty public list isn't a puzzle.
+        foreach ($queue as $descriptor) {
+            $model = base_path("app/Models/{$descriptor->name}.php");
+            if ($descriptor->public?->read !== null && is_file($model) && ! str_contains((string) file_get_contents($model), 'scopePublicQuery')) {
+                $command->components->warn("{$descriptor->name} can be read publicly, but its model doesn't say which records may be, so none are. Add to app/Models/{$descriptor->name}.php: public function scopePublicQuery(\\Illuminate\\Database\\Eloquent\\Builder \$query): void { … }");
+            }
+        }
 
         return self::SUCCESS;
     }

package/template/laravel/src/Console/MakeResourceCommand.php

@@ -15,6 +15,7 @@ final class MakeResourceCommand extends Command
         {--fields= : "name:string, sku:string!, price:money, status:enum(draft|live), notes:text?"}
         {--icon= : Lucide icon name for the dashboard, e.g. package}
         {--group= : Sidebar group in the dashboard}
+        {--id=uuid : What a record\'s id is: uuid, or int for the numbered ids of $table->id()}
         {--force : Overwrite an existing descriptor}
         {--migrate : Run the new migration straight away}
         {--seed= : Fill the new resource with records too (25, or the number you give). Runs the migration first}';
@@ -29,6 +30,7 @@ final class MakeResourceCommand extends Command
                 (string) ($this->option('fields') ?? $this->ask('Fields (e.g. name:string, price:money, active:boolean)')),
                 $this->option('icon'),
                 $this->option('group'),
+                (string) $this->option('id'),
             );
         } catch (InvalidArgumentException $e) {
             $this->components->error($e->getMessage());

package/template/laravel/src/Console/SeedCommand.php

@@ -175,7 +175,9 @@ final class SeedCommand extends Command
             for ($i = $done; $i < min($count, $done + $chunk); $i++) {
                 // Spread over the last 60 days, so the dashboard's "this week" and trend have something to show.
                 $created = date('Y-m-d H:i:s', $now - mt_rand(0, 60 * 86400));
-                $rows[] = ['id' => (string) Str::uuid7()] + Fake::row($resource, $offset + $i + 1, $pools) + ['created_at' => $created, 'updated_at' => $created];
+                // An integer id is the database's to give.
+                $id = $resource->idType === 'int' ? [] : ['id' => (string) Str::uuid7()];
+                $rows[] = $id + Fake::row($resource, $offset + $i + 1, $pools) + ['created_at' => $created, 'updated_at' => $created];
             }
             DB::table($resource->table)->insert($rows);
             $bar->advance(count($rows));

package/template/laravel/src/Console/SetupCommand.php

@@ -16,9 +16,10 @@ final class SetupCommand extends Command
         {--name= : Name for the starter account}
         {--email= : Email for the starter account. Leave out to create no account}
         {--password= : Password for the starter account}
-        {--no-sample-users : Create the starter account only, without the ten sample users}';
+        {--no-sample-users : Create the starter account only, without the ten sample users}
+        {--no-blog : Leave out the blog: the Post resource, its three sample posts and the /blog pages}';
 
-    protected $description = 'Finish setting up a new app: key, Sanctum\'s migration, generated files, migrations, a starter account and sample users';
+    protected $description = 'Finish setting up a new app: key, Sanctum\'s migration, generated files, migrations, the blog, a starter account and sample users';
 
     protected $hidden = true;
 
@@ -39,6 +40,18 @@ final class SetupCommand extends Command
             return self::FAILURE;
         }
 
+        // A blog, as a first resource and a first public page: a Post to write in the
+        // dashboard, /blog to read it at, and three posts so neither is empty. Not having
+        // one is no reason to call the setup failed.
+        if (! $this->option('no-blog')) {
+            // The sample posts are for development: asked for in production they are refused,
+            // which would read as the blog having failed.
+            $blog = $this->call('nevela:blog', app()->environment('production') ? [] : ['--sample' => true]);
+            if ($blog !== self::SUCCESS) {
+                $this->components->warn('The blog could not be set up, so this app has none yet. Everything else is in place. Add it later: php nevela blog');
+            }
+        }
+
         if ($this->option('email')) {
             // The first account in an app is its administrator.
             $status = $this->call('nevela:user', [

package/template/laravel/src/Console/StatusCommand.php

@@ -7,6 +7,7 @@ use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Schema;
 use Nevela\Laravel\Access\ClosedAccounts;
+use Nevela\Laravel\Forms\FormGuard;
 use Nevela\Laravel\Nevela;
 use Nevela\Laravel\Support\DashboardState;
 use Nevela\Laravel\Support\Releases;
@@ -95,6 +96,19 @@ final class StatusCommand extends Command
             }
         }
 
+        // --- public forms ---
+        // A form that asks for the robot check can only make it with the secret key.
+        $checked = array_map(fn ($r) => $r->name, array_values(array_filter($resources, fn ($r) => $r->public?->protect['turnstile'] ?? false)));
+        if ($checked !== []) {
+            $forms = implode(', ', $checked);
+            $row('Robot check (Turnstile)', match (true) {
+                FormGuard::robotCheck() === 'on' => "on for {$forms}, solved on ".implode(', ', FormGuard::hostnames()),
+                FormGuard::secret() === '' && app()->environment('production') => $bad("TURNSTILE_SECRET_KEY is not set, so the form for {$forms} answers 503 to everyone"),
+                FormGuard::secret() === '' => "<fg=yellow>skipped: TURNSTILE_SECRET_KEY is not set, so nothing checks {$forms}. Set it before going live.</>",
+                default => $bad("no site to accept a check from, so the form for {$forms} answers 503 to everyone: set NEVELA_WEB_URL to the site's address, or TURNSTILE_HOSTNAMES"),
+            });
+        }
+
         // --- dashboard ---
         $web = config('nevela.web_path');
         if (! $web || ! is_dir($web)) {

package/template/laravel/src/Console/TrashCommand.php

@@ -3,6 +3,9 @@
 namespace Nevela\Laravel\Console;
 
 use Illuminate\Console\Command;
+use Nevela\Laravel\Forms\Confirmation;
+use Nevela\Laravel\Forms\PublicMail;
+use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Trash\Trash;
 
 final class TrashCommand extends Command
@@ -13,6 +16,20 @@ final class TrashCommand extends Command
 
     public function handle(): int
     {
+        // Files visitors uploaded for a form they never sent. Nothing to do with the trash,
+        // but the same kind of job, on the same night.
+        $unclaimed = Uploads::purgeUnclaimed();
+        if ($unclaimed > 0) {
+            $this->components->info('Removed '.number_format($unclaimed).' file(s) uploaded through a public form and never used.');
+        }
+
+        // People who joined a list and never followed the link that proves their address.
+        $hours = Confirmation::hours();
+        foreach (Confirmation::purge() as $resource => $count) {
+            $this->components->info('Removed '.number_format($count)." {$resource} record(s) whose address wasn't confirmed within {$hours} hours.");
+        }
+        PublicMail::prune();
+
         $days = Trash::days();
         if ($days === null) {
             $this->components->info('Deleted records are kept until someone removes them (nevela.trash.days is off), so there is nothing to do.');

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

@@ -0,0 +1,33 @@
+<?php
+
+namespace Nevela\Laravel\Forms;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Mail\Mailable;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * The email with the link that proves an address: see Confirmation.
+ *
+ * Written like the emails signing in sends, so the two look alike. To say it in your own
+ * words, send your own Mailable with Confirmation::link() in it, through
+ * PublicMail::toVisitor().
+ */
+final class ConfirmAddress extends Mailable
+{
+    use Queueable, SerializesModels;
+
+    public function __construct(public string $app, public string $url, public int $hours) {}
+
+    public function build(): self
+    {
+        $message = (new MailMessage)
+            ->subject("Confirm your email address for {$this->app}")
+            ->line("Someone, we hope you, gave this address to {$this->app}. Confirm it and you're on the list.")
+            ->action('Confirm my address', $this->url)
+            ->line("The link works for {$this->hours} hours. If this wasn't you, do nothing: the address is removed and you won't hear from us again.");
+
+        return $this->subject("Confirm your email address for {$this->app}")->html((string) $message->render());
+    }
+}

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