create-nevela 0.7.1 → 0.9.1

package/template/laravel/src/Http/ResourceRequest.php

@@ -6,8 +6,11 @@ use Illuminate\Foundation\Http\FormRequest;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Schema;
 use Illuminate\Support\Facades\Validator as Validation;
+use Illuminate\Validation\Rules\Exists;
 use Illuminate\Validation\Rules\Unique;
 use Illuminate\Validation\Validator;
+use Nevela\Laravel\Support\Html;
+use Nevela\Laravel\Support\Slug;
 
 /**
  * Base for generated resource requests.
@@ -31,9 +34,139 @@ abstract class ResourceRequest extends FormRequest
     /** @return array<string, string> field => column */
     abstract protected function columns(): array;
 
+    /**
+     * Fields that hold rich text. A generated request with any says which.
+     *
+     * @return list<string>
+     */
+    protected function rich(): array
+    {
+        return [];
+    }
+
+    /**
+     * What a field is when a create leaves it out. A generated request with any says which.
+     *
+     * @return array<string, mixed> field => value
+     */
+    protected function defaults(): array
+    {
+        return [];
+    }
+
+    /**
+     * Fields made from another when a create leaves them empty: a slug from a title. A
+     * generated request with any says which, and where to look for the ones taken.
+     *
+     * @return array<string, array{from: string, table: string, column: string}>
+     */
+    protected function made(): array
+    {
+        return [];
+    }
+
+    /**
+     * Fill what a create left empty and can be made, and keep a later save from emptying
+     * it: once made, a slug is an address, and an address doesn't move.
+     *
+     * @param  array<string, mixed>  $values  by column
+     * @param  array<string, true>  $taken  Values made for earlier rows of the same batch
+     * @return array<string, mixed>
+     */
+    private function make(array $values, bool $creating, array &$taken = []): array
+    {
+        $columns = $this->columns();
+        foreach ($this->made() as $definition) {
+            $column = $definition['column'];
+            $empty = ! isset($values[$column]) || $values[$column] === '';
+            if (! $empty) {
+                $taken[(string) $values[$column]] = true;
+            } elseif ($creating) {
+                $values[$column] = Slug::free($definition['table'], $column, (string) ($values[$columns[$definition['from']] ?? ''] ?? ''), $taken);
+            } else {
+                unset($values[$column]);
+            }
+        }
+
+        return $values;
+    }
+
+    /**
+     * A create from some of the fields only: a public form's, where nobody is asked who
+     * they are and so only what the descriptor lists is taken.
+     *
+     * The rules are this request's own. A key that isn't listed is refused the way an
+     * unknown one is, and a field left out takes its default, or is left to the column.
+     *
+     * @param  list<string>  $fields  The fields that may be sent
+     * @param  array<string, mixed>  $input
+     * @return array{values: array<string, mixed>, issues: list<array{path: string, message: string}>}
+     */
+    public function forFields(array $fields, array $input): array
+    {
+        $input = self::cleaned($this->rich(), $input) + $input;
+        $issues = [];
+        foreach (array_keys($input) as $key) {
+            if (! in_array($key, $fields, true)) {
+                $issues[] = ['path' => (string) $key, 'message' => 'Unknown field.'];
+            }
+        }
+        $validator = Validation::make($input, array_intersect_key(self::withoutTrashed($this->rules()), array_flip($fields)));
+        if ($validator->fails()) {
+            self::explainTrashed($validator, $input);
+            array_push($issues, ...FlareErrors::issues($validator->errors()->toArray()));
+        }
+        if ($issues !== []) {
+            return ['values' => [], 'issues' => $issues];
+        }
+
+        $validated = $validator->validated();
+        $defaults = $this->defaults();
+        $values = [];
+        foreach ($this->columns() as $field => $column) {
+            if (array_key_exists($field, $validated)) {
+                $values[$column] = $validated[$field];
+            } elseif (array_key_exists($field, $defaults)) {
+                $values[$column] = $defaults[$field];
+            }
+        }
+
+        return ['values' => $this->make($values, true), 'issues' => []];
+    }
+
+    /**
+     * Rich text is cleaned before anything looks at it: what is checked for being there,
+     * and for being short enough, is the HTML that would be stored.
+     */
+    protected function prepareForValidation(): void
+    {
+        $this->merge(self::cleaned($this->rich(), $this->all()));
+    }
+
+    /**
+     * @param  list<string>  $fields
+     * @param  array<string, mixed>  $input
+     * @return array<string, mixed> The fields that were sent as text, cleaned. One with nothing left to read is empty.
+     */
+    private static function cleaned(array $fields, array $input): array
+    {
+        $clean = [];
+        foreach ($fields as $field) {
+            if (is_string($input[$field] ?? null)) {
+                $html = Html::clean($input[$field]);
+                $clean[$field] = $html === '' ? null : $html;
+            }
+        }
+
+        return $clean;
+    }
+
+    /** Tables known to have a trash. Only "yes" is remembered: the column can arrive with a migration. */
+    private static array $trashes = [];
+
     protected function validationRules()
     {
-        $rules = parent::validationRules();
+        $rules = self::withoutTrashed(parent::validationRules());
         if (! $this->isMethod('PATCH')) {
             return $rules;
         }
@@ -57,9 +190,36 @@ abstract class ResourceRequest extends FormRequest
         });
     }
 
+    /**
+     * A relation points at a record that is there, and one in the trash is not: nothing
+     * lists it and its own page answers 404. Laravel's exists rule looks at the table,
+     * where a deleted record still is, so it is told to leave those out.
+     *
+     * @param  array<string, mixed>  $rules
+     * @return array<string, mixed>
+     */
+    private static function withoutTrashed(array $rules): array
+    {
+        foreach ($rules as $set) {
+            foreach (is_array($set) ? $set : [] as $rule) {
+                if (! $rule instanceof Exists) {
+                    continue;
+                }
+                // "exists:categories,id": the rule keeps its table to itself.
+                $table = (string) strtok(substr((string) $rule, strlen('exists:')), ',');
+                if (self::$trashes[$table] ?? (Schema::hasColumn($table, 'deleted_at') && (self::$trashes[$table] = true))) {
+                    $rule->withoutTrashed();
+                }
+            }
+        }
+
+        return $rules;
+    }
+
     /**
      * A unique value can be held by a record nobody can see: one in the trash. "Already
      * taken" would send someone looking through a list it isn't in, so say where it is.
+     * The same goes for a relation to a record that is in the trash.
      *
      * @param  array<string, mixed>  $data
      * @return list<array{path: string, message: string}> The messages that were replaced
@@ -82,6 +242,25 @@ abstract class ResourceRequest extends FormRequest
             $validator->errors()->add($field, $message);
             $replaced[] = ['path' => (string) $field, 'message' => $message];
         }
+        foreach ($validator->failed() as $field => $rules) {
+            // And for a failed exists rule: the table and the column, then what else it asked.
+            [$table, $column] = array_pad($rules['Exists'] ?? [], 2, null);
+            $value = $data[$field] ?? null;
+            if (! is_string($table) || ! is_string($column) || ! is_scalar($value) || ! (self::$trashes[$table] ?? false)) {
+                continue;
+            }
+            try {
+                $trashed = DB::table($table)->where($column, $value)->whereNotNull('deleted_at')->exists();
+            } catch (\Throwable) {
+                continue; // not something that could be an id at all
+            }
+            if ($trashed) {
+                $message = 'This one is in the trash. Restore it, or choose another.';
+                $validator->errors()->forget($field);
+                $validator->errors()->add($field, $message);
+                $replaced[] = ['path' => (string) $field, 'message' => $message];
+            }
+        }
 
         return $replaced;
     }
@@ -101,8 +280,9 @@ abstract class ResourceRequest extends FormRequest
      */
     public function many(array $rows): array
     {
-        $rules = $this->rules();
+        $rules = self::withoutTrashed($this->rules());
         $columns = $this->columns();
+        $defaults = $this->defaults();
         $known = array_keys($columns);
         $computed = array_map(fn (string $field) => $field.'File', $known);
         $unique = array_keys(array_filter($rules, fn ($rule) => is_array($rule) && array_filter($rule, fn ($one) => $one instanceof Unique) !== []));
@@ -110,6 +290,7 @@ abstract class ResourceRequest extends FormRequest
         $values = [];
         $problems = [];
         $taken = [];
+        $made = [];
         foreach (array_values($rows) as $index => $row) {
             $number = $index + 1;
             if (! is_array($row) || array_is_list($row)) {
@@ -124,6 +305,7 @@ abstract class ResourceRequest extends FormRequest
                     $issues[] = ['path' => (string) $key, 'message' => 'Unknown field.'];
                 }
             }
+            $row = self::cleaned($this->rich(), $row) + $row;
             $validator = Validation::make($row, $rules);
             if ($validator->fails()) {
                 self::explainTrashed($validator, $row);
@@ -152,9 +334,12 @@ abstract class ResourceRequest extends FormRequest
             foreach ($columns as $field => $column) {
                 if (array_key_exists($field, $validated)) {
                     $mapped[$column] = $validated[$field];
+                } elseif (array_key_exists($field, $defaults)) {
+                    $mapped[$column] = $defaults[$field];
                 }
             }
-            $values[] = $mapped;
+            // Two rows with one title get two slugs: what was made for an earlier row is remembered.
+            $values[] = $this->make($mapped, true, $made);
         }
 
         return ['values' => $values, 'problems' => $problems];
@@ -164,15 +349,19 @@ abstract class ResourceRequest extends FormRequest
     public function values(): array
     {
         $validated = $this->validated();
+        $defaults = $this->defaults();
         $values = [];
         foreach ($this->columns() as $field => $column) {
             if (array_key_exists($field, $validated)) {
                 $values[$column] = $validated[$field];
+            } elseif (array_key_exists($field, $defaults) && ! $this->isMethod('PATCH')) {
+                // Left out of a create, or of a replace, it is what it usually is.
+                $values[$column] = $defaults[$field];
             } elseif ($this->isMethod('PUT')) {
                 $values[$column] = null;
             }
         }
 
-        return $values;
+        return $this->make($values, $this->isMethod('POST'));
     }
 }

package/template/laravel/src/Http/TrashController.php

@@ -6,6 +6,7 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Key;
 use Nevela\Laravel\Trash\Trash;
 use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
@@ -92,7 +93,7 @@ final class TrashController
     public function restore(string $slug, string $id): JsonResponse
     {
         ['descriptor' => $descriptor, 'model' => $model] = $this->resource($slug);
-        $record = $model::onlyTrashed()->find($id) ?? throw new NotFoundHttpException("No deleted {$this->noun($descriptor)} with that id.");
+        $record = $this->deleted($model, $id) ?? throw new NotFoundHttpException("No deleted {$this->noun($descriptor)} with that id.");
         if (! Trash::may('restore', $record)) {
             throw new AccessDeniedHttpException("You don't have access to this.");
         }
@@ -119,7 +120,7 @@ final class TrashController
     public function destroy(string $slug, string $id): JsonResponse|Response
     {
         ['descriptor' => $descriptor, 'model' => $model] = $this->resource($slug);
-        $record = $model::onlyTrashed()->find($id) ?? throw new NotFoundHttpException("No deleted {$this->noun($descriptor)} with that id.");
+        $record = $this->deleted($model, $id) ?? throw new NotFoundHttpException("No deleted {$this->noun($descriptor)} with that id.");
         if (! Trash::may('forceDelete', $record)) {
             throw new AccessDeniedHttpException("You don't have access to this.");
         }
@@ -167,6 +168,22 @@ final class TrashController
         return $resource;
     }
 
+    /**
+     * The deleted record with this id, if there is one.
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $model
+     */
+    private function deleted(string $model, string $id): ?\Illuminate\Database\Eloquent\Model
+    {
+        // Where ids are integers, something that isn't one is nobody's id. Asked anyway,
+        // some databases answer with an error instead of with nothing.
+        if (! Key::fits($model, $id)) {
+            return null;
+        }
+
+        return $model::onlyTrashed()->find($id);
+    }
+
     private function noun(Descriptor $descriptor): string
     {
         return strtolower($descriptor->label);

package/template/laravel/src/Http/UploadController.php

@@ -14,6 +14,7 @@ use Nevela\Laravel\Models\Upload;
 use Nevela\Laravel\Nevela;
 use Nevela\Laravel\Support\Descriptor;
 use Nevela\Laravel\Support\Field;
+use Nevela\Laravel\Support\Key;
 use Symfony\Component\HttpFoundation\Response;
 
 /**
@@ -110,7 +111,8 @@ final class UploadController
     public function show(string $path): Response
     {
         // A key is letters, digits, dashes, dots and slashes. Anything else was never one.
-        if ($path === '' || str_contains($path, '..') || ! preg_match('#^[A-Za-z0-9][A-Za-z0-9._/-]*$#', $path)) {
+        // And a private file's key is not an address, whoever has it.
+        if ($path === '' || str_contains($path, '..') || ! preg_match('#^[A-Za-z0-9][A-Za-z0-9._/-]*$#', $path) || Uploads::isPrivate($path)) {
             abort(404);
         }
         $cache ='public, max-age=31536000, immutable';
@@ -152,6 +154,45 @@ final class UploadController
         ]);
     }
 
+    /**
+     * A private file, to someone who may view the record it belongs to.
+     *
+     *   GET {prefix}/_nevela/private/{slug}/{id}/{field}
+     *
+     * The address names the record and the field, and the file is found from them: there
+     * is no key in it to pass around. It is never to be kept by a cache on the way.
+     */
+    public function download(string $slug, string $id, string $field): Response
+    {
+        $descriptor = null;
+        foreach (Nevela::all() as $candidate) {
+            if ($candidate->slug === $slug) {
+                $descriptor = $candidate;
+            }
+        }
+        $definition = $descriptor?->fields[$field] ?? null;
+        $model = 'App\\Models\\'.($descriptor?->name ?? '');
+        if ($descriptor === null || $definition === null || $definition->kind !== 'file' || ! $definition->private || ! class_exists($model) || ! Key::fits($model, $id)) {
+            abort(404);
+        }
+        // A record in the trash is found by nobody here: trashing it exposes nothing.
+        $record = $model::query()->find($id) ?? abort(404);
+        Gate::authorize('view', $record);
+
+        $key = $record->getAttribute($definition->column());
+        $upload = Uploads::isPrivate($key) ? Upload::query()->where('key', $key)->first() : null;
+        $disk = $upload === null ? null : Storage::disk($upload->disk);
+        if ($upload === null || $disk === null || ! $disk->exists(Uploads::privatePath($key))) {
+            abort(404);
+        }
+
+        return $disk->response(Uploads::privatePath($key), $upload->name, [
+            'Content-Type' => $upload->mime,
+            'Cache-Control' => 'private, no-store',
+            'X-Content-Type-Options' => 'nosniff',
+        ], 'attachment');
+    }
+
     private static function refuse(int $status, string $message): JsonResponse
     {
         return response()->json(['error' => $message], $status);

package/template/laravel/src/Media/Uploads.php

@@ -22,6 +22,15 @@ use Throwable;
  */
 final class Uploads
 {
+    /** Who uploaded a file that came in through a public form and hasn't been used in a create yet. */
+    public const UNCLAIMED = 'public:unclaimed';
+
+    /** And one that has: it belongs to a record now, like any other. */
+    public const CLAIMED = 'public';
+
+    /** What every private file's key starts with. */
+    public const PRIVATE_PREFIX = 'private/';
+
     /** @var array<string, Upload|null> Rows already looked up in this request, by key. */
     private static array $loaded = [];
 
@@ -30,6 +39,27 @@ final class Uploads
         return (string) config('nevela.uploads.disk', 'public');
     }
 
+    /** Where private files are kept: a disk the web server doesn't serve. */
+    public static function privateDisk(): string
+    {
+        return (string) config('nevela.uploads.private_disk', 'local');
+    }
+
+    /**
+     * Whether a key is a private file's. It is said by the key itself, so that nothing
+     * which hands out files by key has to look anything up to know it must not.
+     */
+    public static function isPrivate(?string $key): bool
+    {
+        return is_string($key) && str_starts_with($key, self::PRIVATE_PREFIX);
+    }
+
+    /** Where a private file is on its disk, beside the originals Nevela keeps there. */
+    public static function privatePath(string $key): string
+    {
+        return 'nevela/'.$key;
+    }
+
     public static function maxBytes(): int
     {
         return (int) config('nevela.uploads.max_bytes', 10 * 1024 * 1024);
@@ -73,6 +103,23 @@ final class Uploads
         ];
         $profile = self::profile($field->profile);
 
+        // A private file is stored as it came, where the web server doesn't reach. Nothing
+        // is made from it: a thumbnail would be a copy of it on a disk anyone can read.
+        if ($field->private) {
+            $key = self::PRIVATE_PREFIX."{$base}.{$extension}";
+            self::write(Storage::disk(self::privateDisk()), self::privatePath($key), $bytes);
+            $size = str_starts_with($mime, 'image/') ? @getimagesizefromstring($bytes) : false;
+
+            return self::remember(Upload::create(['disk' => self::privateDisk()] + $row + [
+                'key' => $key,
+                'mime' => $mime,
+                'size' => strlen($bytes),
+                'width' => $size ? $size[0] : null,
+                'height' => $size ? $size[1] : null,
+                'optimised' => false,
+            ]));
+        }
+
         if ($field->isImage() && in_array($mime, ImageOptimizer::OPTIMISABLE, true)) {
             $written = [];
             $originals = Storage::disk((string) config('nevela.uploads.originals_disk', 'local'));
@@ -193,6 +240,11 @@ final class Uploads
             return null;
         }
         $upload = self::find($key);
+        // A private file has no address of its own. It is fetched through the record it
+        // belongs to (see privateRef), by someone who may view that record.
+        if (self::isPrivate($key)) {
+            return ['key' => $key, 'url' => null, 'private' => true, 'name' => $upload?->name, 'mime' => $upload?->mime, 'size' => $upload?->size];
+        }
         if ($upload === null) {
             return ['key' => $key, 'url' => self::url($key)];
         }
@@ -219,6 +271,65 @@ final class Uploads
         ];
     }
 
+    /**
+     * A private file as a record shows it: what it is, and the address it is fetched from,
+     * which names the record and the field and never the key.
+     *
+     * @return array<string, mixed>|null
+     */
+    public static function privateRef(?string $key, string $slug, mixed $id, string $field): ?array
+    {
+        $ref = self::ref($key);
+        if ($ref === null || ! self::isPrivate($key)) {
+            return $ref;
+        }
+
+        return ['url' => route('nevela.private.show', ['slug' => $slug, 'id' => $id, 'field' => $field])] + $ref;
+    }
+
+    /**
+     * Remove a private file for good: from its disk, and the record of it. For when the
+     * record it belonged to has been removed for good.
+     */
+    public static function discard(string $key): void
+    {
+        if (! self::isPrivate($key)) {
+            return;
+        }
+        $upload = Upload::query()->where('key', $key)->first();
+        Storage::disk($upload?->disk ?? self::privateDisk())->delete(self::privatePath($key));
+        $upload?->delete();
+        unset(self::$loaded[$key]);
+    }
+
+    /**
+     * Remove what visitors uploaded and never used: a form that was started and left.
+     * Each such file waits an hour for its create (PublicController::CLAIM_SECONDS), and
+     * goes after that, with anything that was made from it.
+     *
+     * @return int How many were removed
+     */
+    public static function purgeUnclaimed(int $olderThanSeconds = 3600): int
+    {
+        $removed = 0;
+        Upload::query()->where('uploaded_by', self::UNCLAIMED)->where('created_at', '<', now()->subSeconds($olderThanSeconds))->orderBy('id')
+            ->chunkById(200, function ($uploads) use (&$removed) {
+                foreach ($uploads as $upload) {
+                    $disk = Storage::disk($upload->disk);
+                    $disk->delete(self::isPrivate($upload->key) ? self::privatePath($upload->key) : $upload->key);
+                    $disk->delete(array_column($upload->renditions ?? [], 'key'));
+                    if ($upload->original_key !== null) {
+                        Storage::disk((string) config('nevela.uploads.originals_disk', 'local'))->delete($upload->original_key);
+                    }
+                    unset(self::$loaded[$upload->key]);
+                    $upload->delete();
+                    $removed++;
+                }
+            });
+
+        return $removed;
+    }
+
     public static function forget(): void
     {
         self::$loaded = [];

package/template/laravel/src/Nevela.php

@@ -7,6 +7,7 @@ use Illuminate\Database\UniqueConstraintViolationException;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
 use InvalidArgumentException;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Support\Descriptor;
@@ -21,7 +22,7 @@ use Nevela\Laravel\Support\Naming;
 final class Nevela
 {
     /** Written by `pnpm release`; the same number as the repository's git tag. */
-    public const VERSION = '0.7.1';
+    public const VERSION = '0.9.1';
 
     /** @var array<string, Descriptor> */
     private static array $descriptors = [];
@@ -76,7 +77,18 @@ final class Nevela
      */
     public static function list(Builder $query, string $name, Request $request, string $resourceClass): JsonResponse
     {
-        $resource = self::resource($name);
+        return self::listFor($query, self::resource($name), $request, $resourceClass);
+    }
+
+    /**
+     * The same, for a descriptor that was handed over and not looked up: the public list
+     * is the resource with only the fields anyone may see, so nothing else can be sorted,
+     * filtered or searched by.
+     *
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     */
+    public static function listFor(Builder $query, Descriptor $resource, Request $request, string $resourceClass): JsonResponse
+    {
         $list = ListQuery::parse($resource, $request->query(), (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
         if (! $list->ok()) {
             return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
@@ -124,12 +136,59 @@ final class Nevela
         }
 
         foreach ($list->filters as $filter) {
+            if (isset($filter['state'])) {
+                // Published: its time has come. Scheduled: it has one, still to come. Draft: it has none.
+                match ($filter['state']) {
+                    'draft' => $query->whereNull($filter['column']),
+                    'scheduled' => $query->where($filter['column'], '>', now()),
+                    default => $query->whereNotNull($filter['column'])->where($filter['column'], '<=', now()),
+                };
+
+                continue;
+            }
+            if (isset($filter['confirmed'])) {
+                $filter['confirmed'] ? $query->whereNotNull($filter['column']) : $query->whereNull($filter['column']);
+
+                continue;
+            }
+            $field = $resource->fields[$filter['field']] ?? null;
+            if ($filter['value'] !== null && $field?->kind === 'belongsTo' && ! self::couldBeId((string) $field->target, (string) $filter['value'])) {
+                // Nothing belongs to a record that can't exist. Asked anyway, some databases
+                // answer a number column given letters with an error instead of with no rows.
+                $query->whereRaw('1 = 0');
+
+                continue;
+            }
             $filter['value'] === null
                 ? $query->whereNull($filter['column'])
                 : $query->where($filter['column'], $filter['value']);
         }
     }
 
+    /**
+     * A count is of the people who are really there: where a resource's form asks for an
+     * address to be proved, the ones who haven't yet are left out. The list still shows
+     * them, marked.
+     */
+    private static function proved(Builder $query, Descriptor $resource): void
+    {
+        if ($resource->public?->confirm !== null && method_exists($query->getModel(), 'scopeConfirmed')) {
+            $query->confirmed();
+        }
+    }
+
+    /** Whether a value has the shape of one of a resource's ids: digits, or a UUID. */
+    private static function couldBeId(string $name, string $value): bool
+    {
+        try {
+            $integers = self::resource($name)->idType === 'int';
+        } catch (InvalidArgumentException) {
+            return true; // not a resource this app describes: its ids are its own business
+        }
+
+        return $integers ? preg_match('/^[0-9]{1,18}$/', $value) === 1 : Str::isUuid($value);
+    }
+
     /**
      * GET /{slug}/_insights?unit=day|week|month&q&filter[field] → { total, unit, series, breakdown }.
      *
@@ -154,6 +213,7 @@ final class Nevela
             return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
         }
         self::narrow($query, $resource, $list);
+        self::proved($query, $resource);
         $base = fn () => (clone $query)->reorder();
 
         // Counted per day by the database, one grouped query over the created_at index,
@@ -288,6 +348,7 @@ final class Nevela
         $now = now();
         $since = $now->copy()->subDays($days);
         $before = $now->copy()->subDays($days * 2);
+        self::proved($query, $resource);
         $base = fn () => (clone $query)->reorder();
 
         $values = [];
@@ -318,6 +379,26 @@ final class Nevela
         return Uploads::ref($key);
     }
 
+    /**
+     * The same for a private file: what it is, and the address it is fetched from by
+     * someone who may view the record, which names the record and never the file's key.
+     *
+     * @return array<string, mixed>|null
+     */
+    public static function privateFile(?string $key, string $slug, mixed $id, string $field): ?array
+    {
+        return Uploads::privateRef($key, $slug, $id, $field);
+    }
+
+    /**
+     * A rich text field's HTML, as it is safe to show: only the tags and attributes in
+     * config('nevela.rich_text'). Generated API resources send every rich text field through it.
+     */
+    public static function html(?string $html): ?string
+    {
+        return $html === null ? null : Support\Html::clean($html);
+    }
+
     /** Whether a request is one Nevela answers (so errors use Flare's shape). */
     public static function handles(Request $request): bool
     {