create-nevela 0.7.0 → 0.8.0

package/template/laravel/src/Support/Fake.php

@@ -133,11 +133,25 @@ final class Fake
             'datetime' => $field->unique
                 ? gmdate('Y-m-d H:i:s', self::EPOCH + $number)
                 : date('Y-m-d H:i:s', time() - mt_rand(0, 365 * 86400)),
-            'text' => self::sentence(mt_rand(8, 24)).($field->unique ? " {$number}" : ''),
+            'text' => $field->isRich()
+                ? self::article($field->unique ? " {$number}" : '')
+                : self::sentence(mt_rand(8, 24)).($field->unique ? " {$number}" : ''),
             default => self::string($field, $number, $first, $last, $isPerson),
         };
     }
 
+    /** A few paragraphs with a heading and a list, so a seeded record reads like one somebody wrote. */
+    private static function article(string $suffix): string
+    {
+        $items = implode('', array_map(fn () => '<li>'.ucfirst(self::sentence(mt_rand(3, 6))).'</li>', range(1, 3)));
+
+        return '<p>'.self::sentence(mt_rand(14, 24)).'</p>'
+            .'<h2>'.rtrim(self::sentence(mt_rand(3, 5)), '.').$suffix.'</h2>'
+            .'<p>'.self::sentence(mt_rand(12, 20)).' <strong>'.rtrim(self::sentence(mt_rand(2, 4)), '.').'</strong>, '.lcfirst(self::sentence(mt_rand(6, 10))).'</p>'
+            ."<ul>{$items}</ul>"
+            .'<p>'.self::sentence(mt_rand(10, 18)).'</p>';
+    }
+
     private static function string(Field $field, int $number, string $first, string $last, bool $isPerson): string
     {
         $name = strtolower($field->name);

package/template/laravel/src/Support/Field.php

@@ -14,6 +14,7 @@ final class Field
 
     public const FORMATS = [
         'string' => ['email', 'url', 'tel', 'slug', 'color'],
+        'text' => ['rich'],
         'float' => ['money', 'percent', 'rating'],
         'int' => ['percent', 'rating'],
     ];
@@ -23,7 +24,7 @@ final class Field
 
     /** Shorthand types accepted by --fields, mapped to kind + format. */
     private const ALIASES = [
-        'string' => ['string', null], 'text' => ['text', null],
+        'string' => ['string', null], 'text' => ['text', null], 'richtext' => ['text', 'rich'],
         'email' => ['string', 'email'], 'url' => ['string', 'url'], 'tel' => ['string', 'tel'],
         'slug' => ['string', 'slug'], 'color' => ['string', 'color'],
         'int' => ['int', null], 'integer' => ['int', null],
@@ -40,6 +41,9 @@ final class Field
      * @param  string|null  $target  belongsTo: the resource this points at, e.g. "Category"
      * @param  list<string>  $accept  file: the categories it takes, e.g. ["image"]
      * @param  string|null  $profile  file: the image profile uploads are optimised with (config nevela.uploads.profiles)
+     * @param  int|null  $maxLength  string and text: the most characters it holds, where that isn't the usual 255 or 65,535
+     * @param  bool  $private  file: kept where the web server doesn't reach, and handed only to someone who may view the record
+     * @param  string|int|float|bool|null  $default  What the field is when a create leaves it out. Also the column's default.
      */
     public function __construct(
         public readonly string $name,
@@ -52,6 +56,9 @@ final class Field
         public readonly ?string $target = null,
         public readonly array $accept = [],
         public readonly ?string $profile = null,
+        public readonly ?int $maxLength = null,
+        public readonly bool $private = false,
+        public readonly string|int|float|bool|null $default = null,
     ) {
         if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $name)) {
             throw new InvalidArgumentException("Field \"{$name}\" must be camelCase (e.g. publishedAt).");
@@ -65,6 +72,9 @@ final class Field
         if ($format !== null && ! in_array($format, self::FORMATS[$kind] ?? [], true)) {
             throw new InvalidArgumentException("Format \"{$format}\" is not valid for {$kind} field \"{$name}\".");
         }
+        if ($maxLength !== null && (! in_array($kind, ['string', 'text'], true) || $format === 'color' || $maxLength < 1)) {
+            throw new InvalidArgumentException("\"{$name}\" can't have a length of {$maxLength}: a length is a whole number of 1 or more, on a string or text field.");
+        }
         if ($kind === 'enum' && $options === []) {
             throw new InvalidArgumentException("Enum field \"{$name}\" needs values, e.g. {$name}:enum(draft|published).");
         }
@@ -81,6 +91,25 @@ final class Field
                 throw new InvalidArgumentException("A belongsTo field holds an id, so its name ends in \"Id\": {$name}Id.");
             }
         }
+        if ($default !== null) {
+            $fits = match ($kind) {
+                'string', 'text' => is_string($default) && ! ($kind === 'text' && $format === 'rich'),
+                'int' => is_int($default),
+                'float' => is_int($default) || is_float($default),
+                'boolean' => is_bool($default),
+                'enum' => is_string($default) && in_array($default, $options, true),
+                default => false,
+            };
+            if (! $fits) {
+                throw new InvalidArgumentException("The default of \"{$name}\" has to be a value the field could hold".($kind === 'enum' ? ': one of '.implode(', ', $options).'.' : (in_array($kind, ['string', 'text', 'int', 'float', 'boolean'], true) ? '.' : ", and a {$kind} field can't have one.")));
+            }
+            if ($unique) {
+                throw new InvalidArgumentException("\"{$name}\" is unique, so only one record could ever have its default.");
+            }
+        }
+        if ($private && $kind !== 'file') {
+            throw new InvalidArgumentException("\"{$name}\" can't be private: that is for file fields. Who may see a record's other fields is its policy's to say.");
+        }
         if ($kind === 'file') {
             if ($accept === []) {
                 throw new InvalidArgumentException("File field \"{$name}\" needs what it accepts, e.g. {$name}:image or {$name}:file(pdf|image).");
@@ -103,15 +132,40 @@ final class Field
      * Parse one `name:type` token. Suffix `?` = optional (nullable), `!` = unique; both may be combined.
      *
      *   status:enum(draft|published)
+     *   excerpt:string(500)               a length other than the usual 255
+     *   body:richtext                     formatted text, kept as HTML that has been cleaned
      *   category:belongsTo(Category)      stored as categoryId
      *   image:image                       an optimised image; image:image(product) names a profile
      *   manual:file(pdf|document)         any other upload
+     *   cv:file(pdf|private)              one only those who may view the record can fetch
+     *   status:enum(pending|paid)=pending what it is when a create leaves it out
      *
      * Grit's and Flare's spellings are understood too: see normalise().
      */
     public static function parse(string $token): self
     {
         $written = trim($token);
+        // status:enum(pending|paid)=pending: what the field is when a create leaves it out.
+        $default = null;
+        if (($at = strpos($written, '=')) !== false) {
+            $default = trim(substr($written, $at + 1));
+            $written = rtrim(substr($written, 0, $at));
+        }
+        if ($default !== null) {
+            $field = self::parse($written);
+            $value = match ($field->kind) {
+                'int' => filter_var($default, FILTER_VALIDATE_INT) === false ? $default : (int) $default,
+                'float' => is_numeric($default) ? (float) $default : $default,
+                'boolean' => match (strtolower($default)) {
+                    'true', '1', 'yes' => true,
+                    'false', '0', 'no' => false,
+                    default => $default,
+                },
+                default => $default,
+            };
+
+            return self::fromArray($field->name, ['default' => $value] + $field->toArray());
+        }
         $token = self::normalise($written);
         if (! preg_match('/^([A-Za-z][A-Za-z0-9_]*):([A-Za-z_]+)(?:\(([^)]*)\))?([?!]{0,2})$/', $token, $m)) {
             throw new InvalidArgumentException("Invalid field \"{$written}\". Expected name:type, e.g. price:money, status:enum(draft|live)?, image:image or category:belongsTo(Category).");
@@ -135,14 +189,19 @@ final class Field
             return new self($name, 'file', null, $required, $unique, accept: ['image'], profile: $list[0] ?? null);
         }
         if ($type === 'file') {
-            return new self($name, 'file', null, $required, $unique, accept: $list ?: ['any']);
+            // cv:file(pdf|private): "private" among what it takes is how it is kept, not a kind of file.
+            $accept = array_values(array_diff($list, ['private']));
+
+            return new self($name, 'file', null, $required, $unique, accept: $accept ?: ['any'], private: count($accept) !== count($list));
         }
         if (! isset(self::ALIASES[$type])) {
             throw new InvalidArgumentException("Unknown type \"{$type}\" on \"{$name}\". Use one of: ".implode(', ', array_keys(self::ALIASES)).', enum(a|b), belongsTo(Resource), image, file(pdf|…).');
         }
         [$kind, $format] = self::ALIASES[$type];
+        // excerpt:string(500): a length of its own.
+        $maxLength = in_array($kind, ['string', 'text'], true) && $format !== 'color' && ctype_digit($args) ? (int) $args : null;
 
-        return new self($name, $kind, $format, $required, $unique);
+        return new self($name, $kind, $format, $required, $unique, maxLength: $maxLength);
     }
 
     /**
@@ -183,6 +242,9 @@ final class Field
             $data['target'] ?? null,
             array_values($data['accept'] ?? []),
             $data['profile'] ?? null,
+            isset($data['maxLength']) ? (int) $data['maxLength'] : null,
+            (bool) ($data['private'] ?? false),
+            $data['default'] ?? null,
         );
     }
 
@@ -196,6 +258,9 @@ final class Field
             'target' => $this->target,
             'accept' => $this->accept ?: null,
             'profile' => $this->profile,
+            'maxLength' => $this->maxLength,
+            'private' => $this->private ?: null,
+            'default' => $this->default,
             'required' => $this->required ? null : false,
             'unique' => $this->unique ?: null,
             'label' => $this->label,
@@ -219,6 +284,12 @@ final class Field
         return substr($this->name, 0, -2);
     }
 
+    /** Whether this is text with formatting: written in an editor, kept as HTML, cleaned on the way in and out. */
+    public function isRich(): bool
+    {
+        return $this->kind === 'text' && $this->format === 'rich';
+    }
+
     /** Whether this is a file field that takes images only, and so is optimised and shown as a picture. */
     public function isImage(): bool
     {

package/template/laravel/src/Support/Html.php

@@ -0,0 +1,185 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use DOMDocument;
+use DOMElement;
+use DOMNode;
+use DOMText;
+
+/**
+ * Rich text, made safe to keep and to show.
+ *
+ * What a rich text field receives is whatever was sent: the dashboard's editor, a script,
+ * a CSV file, a visitor's form. None of it is trusted. The HTML is parsed, and written
+ * out again from what was understood, keeping only the tags and attributes on a list
+ * (config: nevela.rich_text). A tag that isn't on it goes and its words stay; a tag whose
+ * contents are not words, such as a script, goes with them.
+ *
+ * The same is done when a record is read, so that HTML which reached the table some other
+ * way (a column adopted from an older app, a row written by hand) is never shown as it is.
+ */
+final class Html
+{
+    /** What the dashboard's editor can make. */
+    public const TAGS = ['p', 'br', 'strong', 'em', 's', 'a', 'h2', 'h3', 'ul', 'ol', 'li', 'blockquote'];
+
+    /** Attributes kept, by tag. A link keeps where it goes and nothing else. */
+    public const ATTRIBUTES = ['a' => ['href']];
+
+    /** Where a link may go. One with no scheme, such as /about, is the site's own and is kept. */
+    public const SCHEMES = ['http', 'https', 'mailto'];
+
+    /** Other spellings of the same thing, as browsers and word processors write them. */
+    private const SAME_AS = ['b' => 'strong', 'i' => 'em', 'strike' => 's', 'del' => 's'];
+
+    /** Removed with everything inside them: what they hold was never text. */
+    private const DROPPED = ['script', 'style', 'iframe', 'object', 'embed', 'noscript', 'template', 'svg', 'math', 'head', 'title', 'textarea', 'select', 'option', 'button', 'audio', 'video', 'canvas', 'applet', 'frame', 'frameset', 'link', 'meta', 'base'];
+
+    /** Tags that sit inside a line of text. Anything else stands on lines of its own. */
+    private const INLINE = ['a', 'strong', 'em', 's', 'b', 'i', 'u', 'strike', 'del', 'ins', 'span', 'code', 'sub', 'sup', 'small', 'mark', 'font', 'br', 'abbr', 'cite', 'q', 'label', 'time', 'img', 'kbd', 'var', 'samp', 'big', 'tt', 'wbr'];
+
+    private const EMPTY = ['br', 'hr', 'img'];
+
+    /**
+     * The HTML with only what the list allows, or an empty string when there is nothing
+     * in it to read: an editor that was opened and left sends `<p><br></p>`.
+     *
+     * @param  array{tags?: list<string>, attributes?: array<string, list<string>>, schemes?: list<string>}|null  $allow  Null for config('nevela.rich_text')
+     */
+    public static function clean(?string $html, ?array $allow = null): string
+    {
+        if ($html === null || trim($html) === '') {
+            return '';
+        }
+        $allow ??= function_exists('config') && function_exists('app') && app()->bound('config') ? (array) config('nevela.rich_text', []) : [];
+        $tags = array_map('strtolower', (array) ($allow['tags'] ?? self::TAGS));
+        $attributes = (array) ($allow['attributes'] ?? self::ATTRIBUTES);
+        $schemes = array_map('strtolower', (array) ($allow['schemes'] ?? self::SCHEMES));
+
+        $document = new DOMDocument;
+        $before = libxml_use_internal_errors(true);
+        // Characters outside ASCII go in as numbered entities: the parser would otherwise
+        // have to guess the encoding, and guesses Latin-1.
+        $document->loadHTML('<html><body>'.mb_encode_numericentity($html, [0x80, 0x10FFFF, 0, 0x1FFFFF], 'UTF-8').'</body></html>');
+        libxml_clear_errors();
+        libxml_use_internal_errors($before);
+
+        $body = $document->getElementsByTagName('body')->item(0);
+        if ($body === null) {
+            return '';
+        }
+        $out = self::top($body, $tags, $attributes, $schemes);
+        $words = trim(html_entity_decode(strip_tags($out), ENT_QUOTES | ENT_HTML5, 'UTF-8'), " \t\n\r\0\x0B\u{A0}");
+
+        return $words === '' && ! str_contains($out, '<img') ? '' : $out;
+    }
+
+    /**
+     * The top of the document, where everything is a paragraph, a heading, a list or a
+     * quote. Text and inline tags found loose there are gathered into paragraphs, so that
+     * plain text from a CSV file or a script is stored as what the editor would have made.
+     * A wrapper that isn't kept, such as a div, is looked into the same way.
+     *
+     * @param  list<string>  $tags
+     * @param  array<string, list<string>>  $attributes
+     * @param  list<string>  $schemes
+     */
+    private static function top(DOMNode $parent, array $tags, array $attributes, array $schemes): string
+    {
+        $paragraph = fn (string $inline) => trim($inline) === '' ? '' : (in_array('p', $tags, true) ? '<p>'.trim($inline).'</p>' : $inline);
+        $out = '';
+        $loose = '';
+        foreach ($parent->childNodes as $node) {
+            $name = $node instanceof DOMElement ? strtolower($node->nodeName) : '';
+            $name = self::SAME_AS[$name] ?? $name;
+            if ($name === '' || in_array($name, self::INLINE, true)) {
+                $loose .= self::write($node, $tags, $attributes, $schemes);
+
+                continue;
+            }
+            $out .= $paragraph($loose);
+            $loose = '';
+            $out .= in_array($name, $tags, true) || in_array($name, self::DROPPED, true)
+                ? self::write($node, $tags, $attributes, $schemes)
+                : self::top($node, $tags, $attributes, $schemes);
+        }
+
+        return $out.$paragraph($loose);
+    }
+
+    /** The words alone, on one line: what a table cell or a search result shows. */
+    public static function text(?string $html, int $limit = 0): string
+    {
+        $text = trim((string) preg_replace('/\s+/u', ' ', html_entity_decode(strip_tags((string) preg_replace('/<(br|\/p|\/h[1-6]|\/li|\/blockquote)\b[^>]*>/i', ' ', (string) $html)), ENT_QUOTES | ENT_HTML5, 'UTF-8')));
+
+        return $limit > 0 && mb_strlen($text) > $limit ? rtrim(mb_substr($text, 0, $limit - 1)).'…' : $text;
+    }
+
+
+    /**
+     * @param  list<string>  $tags
+     * @param  array<string, list<string>>  $attributes
+     * @param  list<string>  $schemes
+     */
+    private static function write(DOMNode $node, array $tags, array $attributes, array $schemes): string
+    {
+        if ($node instanceof DOMText) {
+            return htmlspecialchars($node->nodeValue ?? '', ENT_NOQUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');
+        }
+        if (! $node instanceof DOMElement) {
+            return ''; // a comment, a processing instruction
+        }
+        $name = strtolower($node->nodeName);
+        $name = self::SAME_AS[$name] ?? $name;
+        if (in_array($name, self::DROPPED, true)) {
+            return '';
+        }
+
+        $inner = '';
+        foreach ($node->childNodes as $child) {
+            $inner .= self::write($child, $tags, $attributes, $schemes);
+        }
+        if (! in_array($name, $tags, true)) {
+            // Not a tag to keep, but its words are. Where it stood on its own line, a space keeps them apart.
+            return in_array($name, self::INLINE, true) && $name !== 'br' ? $inner : $inner.' ';
+        }
+
+        $kept = '';
+        foreach ((array) ($attributes[$name] ?? []) as $attribute) {
+            $value = $node->getAttribute($attribute);
+            if ($value === '' || (in_array($attribute, ['href', 'src'], true) && ! self::safe($value, $schemes))) {
+                continue;
+            }
+            $kept .= ' '.$attribute.'="'.htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8').'"';
+        }
+        // A link that goes nowhere is its words.
+        if ($name === 'a' && $kept === '') {
+            return $inner;
+        }
+        // A tag with nothing in it is nothing. Browsers leave these behind: Chrome puts a
+        // list inside the paragraph it was started in, which leaves an empty paragraph
+        // before it once the two are told apart. (A blank line is <p><br></p>, and is kept.)
+        if (! in_array($name, self::EMPTY, true) && trim($inner) === '') {
+            return '';
+        }
+
+        return in_array($name, self::EMPTY, true) ? "<{$name}{$kept}>" : "<{$name}{$kept}>{$inner}</{$name}>";
+    }
+
+    /**
+     * Whether an address is one a link may have. A browser ignores spaces and control
+     * characters inside a scheme, so `java\tscript:` is read here the way it would be there.
+     *
+     * @param  list<string>  $schemes
+     */
+    private static function safe(string $address, array $schemes): bool
+    {
+        $address = (string) preg_replace('/[\x00-\x20\x7F]+/', '', $address);
+        if (! preg_match('/^([a-z][a-z0-9+.\-]*):/i', $address, $m)) {
+            return true; // no scheme: /about, #top, //example.com
+        }
+
+        return in_array(strtolower($m[1]), $schemes, true);
+    }
+}

package/template/laravel/src/Support/PublicAccess.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use InvalidArgumentException;
+
+/**
+ * What of a resource is open to anyone, signed in or not: the descriptor's "public" section.
+ *
+ *   "public": {
+ *     "read":   { "by": "slug", "fields": ["title", "slug", "body", "publishedAt"] },
+ *     "create": { "fields": ["name", "email", "message"], "throttle": "10,1" }
+ *   }
+ *
+ * Nothing is open without it, and nothing beyond what it names: a resource with "read"
+ * alone can't be written to, and a field that isn't listed is never sent or accepted.
+ * Which records can be read is the model's to say, in its publicQuery scope.
+ */
+final class PublicAccess
+{
+    /** Requests a minute, when the section doesn't say: plenty for a page, few for a form. */
+    public const READ_THROTTLE = '60,1';
+
+    public const CREATE_THROTTLE = '10,1';
+
+    /**
+     * @param  list<string>|null  $read  The fields anyone may read, or null when nothing may be
+     * @param  string|null  $by  The unique field one record is fetched by, in place of its id
+     * @param  list<string>|null  $create  The fields anyone may send to create a record, or null when nobody may
+     * @param  list<string>  $middleware  More middleware for these routes: the app's own spam checks
+     */
+    public function __construct(
+        public readonly ?array $read = null,
+        public readonly ?string $by = null,
+        public readonly ?array $create = null,
+        public readonly string $readThrottle = self::READ_THROTTLE,
+        public readonly string $createThrottle = self::CREATE_THROTTLE,
+        public readonly array $middleware = [],
+    ) {
+        foreach ([$readThrottle, $createThrottle] as $throttle) {
+            if (! preg_match('/^[1-9][0-9]*,[1-9][0-9]*$/', $throttle)) {
+                throw new InvalidArgumentException("\"{$throttle}\" is not a throttle. Write how many requests in how many minutes: \"10,1\".");
+            }
+        }
+        if ($read === null && $create === null) {
+            throw new InvalidArgumentException('A "public" section opens something: give it "read", "create" or both.');
+        }
+        foreach ($middleware as $name) {
+            if (! is_string($name) || ! preg_match('/^[A-Za-z0-9_.:,\\\\-]+$/', $name)) {
+                throw new InvalidArgumentException('Public middleware is named as in a route: "honeypot", or "throttle:5,1".');
+            }
+        }
+    }
+
+    /** @param array<string, mixed> $data */
+    public static function fromArray(array $data): self
+    {
+        $read = isset($data['read']) ? (array) $data['read'] : null;
+        $create = isset($data['create']) ? (array) $data['create'] : null;
+
+        return new self(
+            $read === null ? null : array_values(array_map('strval', (array) ($read['fields'] ?? []))),
+            $read['by'] ?? null,
+            $create === null ? null : array_values(array_map('strval', (array) ($create['fields'] ?? []))),
+            (string) ($read['throttle'] ?? self::READ_THROTTLE),
+            (string) ($create['throttle'] ?? self::CREATE_THROTTLE),
+            array_values((array) ($data['middleware'] ?? [])),
+        );
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(): array
+    {
+        return array_filter([
+            'read' => $this->read === null ? null : array_filter([
+                'by' => $this->by,
+                'fields' => $this->read,
+                'throttle' => $this->readThrottle === self::READ_THROTTLE ? null : $this->readThrottle,
+            ], fn ($v) => $v !== null),
+            'create' => $this->create === null ? null : array_filter([
+                'fields' => $this->create,
+                'throttle' => $this->createThrottle === self::CREATE_THROTTLE ? null : $this->createThrottle,
+            ], fn ($v) => $v !== null),
+            'middleware' => $this->middleware ?: null,
+        ], fn ($v) => $v !== null);
+    }
+
+    /**
+     * Checked against the resource's fields, which the section on its own can't know.
+     *
+     * @param  array<string, Field>  $fields
+     *
+     * @throws InvalidArgumentException
+     */
+    public function check(string $resource, array $fields): void
+    {
+        foreach (['read' => $this->read, 'create' => $this->create] as $what => $listed) {
+            if ($listed === null) {
+                continue;
+            }
+            if ($listed === []) {
+                throw new InvalidArgumentException("{$resource}: public {$what} names no fields, so there would be nothing to {$what}.");
+            }
+            foreach ($listed as $field) {
+                if (! isset($fields[$field])) {
+                    throw new InvalidArgumentException("{$resource}: public {$what} lists \"{$field}\", which is not one of its fields.");
+                }
+            }
+        }
+        foreach ($this->read ?? [] as $field) {
+            if ($fields[$field]->private) {
+                throw new InvalidArgumentException("{$resource}: \"{$field}\" is a private file, so it can't be read by anyone who asks.");
+            }
+        }
+        if ($this->by !== null) {
+            if ($this->read === null) {
+                throw new InvalidArgumentException("{$resource}: \"by\" says how one record is read, and nothing is.");
+            }
+            if (! isset($fields[$this->by]) || ! $fields[$this->by]->unique) {
+                throw new InvalidArgumentException("{$resource}: a record is fetched by \"{$this->by}\", which has to be a unique field ({$this->by}:slug!).");
+            }
+        }
+        if ($this->create !== null) {
+            foreach ($fields as $field) {
+                // Left out of the form, a field needs something to be: nothing, or a default.
+                // (A yes/no column is no unless said otherwise.)
+                if ($field->required && $field->default === null && $field->kind !== 'boolean' && ! in_array($field->name, $this->create, true)) {
+                    throw new InvalidArgumentException("{$resource}: \"{$field->name}\" is required and a public create can't send it. List it under create, give it a default, or make it optional.");
+                }
+            }
+        }
+    }
+}

package/template/web/app/api/[...path]/route.ts

@@ -1,11 +1,13 @@
 import type { NextRequest } from "next/server";
-import { API_URL, sessionToken } from "@/lib/laravel";
+import { API_URL, callerHeaders, sessionToken } from "@/lib/laravel";
 
 /**
  * The browser's way to the Laravel API, for the few things a server action can't do:
  *
  * - reading, for the relation picker's search (`/api/categories?q=…`),
- * - showing stored files (`/api/_nevela/files/<key>`), and
+ * - showing stored files (`/api/_nevela/files/<key>`),
+ * - downloading a private one (`/api/_nevela/private/<slug>/<id>/<field>`), which Laravel
+ *   hands only to someone who may view that record, and
  * - uploading one (`PUT /api/_nevela/uploads/<Resource>/<field>`), which needs the
  *   browser's upload progress and is larger than a server action accepts.
  *
@@ -13,6 +15,11 @@ import { API_URL, sessionToken } from "@/lib/laravel";
  * as a Bearer token. Laravel still decides what the person may see or store. Everything
  * else that changes data goes through the server actions, so nothing but an upload is
  * let through here as a write.
+ *
+ * And for a site's visitors, who have no session: what a resource's "public" section
+ * opens (`/api/public/…`). Reading it, a form's create (`POST /api/public/<slug>`) and a
+ * file for that form (`PUT /api/public/_nevela/uploads/<Resource>/<field>`) go through
+ * with no token. Laravel has those routes only for resources whose descriptor opens them.
  */
 export const dynamic = "force-dynamic";
 
@@ -23,7 +30,7 @@ const MAX_UPLOAD_BYTES = 64 * 1024 * 1024;
  * What is passed back from Laravel's answer. Not its length or encoding: fetch() hands
  * over the body already decompressed, so the length Laravel gave may no longer be true.
  */
-const RESPONSE_HEADERS = ["content-type", "cache-control", "etag", "last-modified", "location", "x-content-type-options"];
+const RESPONSE_HEADERS = ["content-type", "content-disposition", "cache-control", "etag", "last-modified", "location", "x-content-type-options"];
 
 type Context = { params: Promise<{ path: string[] }> };
 
@@ -32,11 +39,16 @@ function target(path: string[], search: string): string | null {
   return `${API_URL}/${path.map(encodeURIComponent).join("/")}${search}`;
 }
 
-async function forward(url: string, init: RequestInit, withToken: boolean): Promise<Response> {
+/** Whether an address is under what a resource's "public" section opens. */
+const isPublic = (path: string[]) => path[0] === "public" && path.length > 1;
+
+async function forward(url: string, init: RequestInit, withToken: boolean, forVisitor = false): Promise<Response> {
   const headers = new Headers(init.headers);
   headers.set("Accept", headers.get("Accept") ?? "application/json");
   const token = withToken ? await sessionToken() : undefined;
   if (token) headers.set("Authorization", `Bearer ${token}`);
+  // Whose request this is, so Laravel's throttle counts the visitor and not this server.
+  if (forVisitor) for (const [name, value] of Object.entries(await callerHeaders())) headers.set(name, value);
 
   let upstream: Response;
   try {
@@ -68,17 +80,38 @@ export async function GET(request: NextRequest, context: Context) {
   // a request with no session is told 401; asked as a page, Laravel would try to send it
   // to a sign-in route this app doesn't have. A file is asked for as the browser wants it.
   const accept = isFile ? (request.headers.get("accept") ?? "*/*") : "application/json";
-  return forward(url, { method: "GET", headers: { Accept: accept, ...conditional } }, !isFile);
+  // What is public is the same for everyone, so it is asked for as nobody.
+  return forward(url, { method: "GET", headers: { Accept: accept, ...conditional } }, !isFile && !isPublic(path), isPublic(path));
+}
+
+/**
+ * A visitor's form: a public create. Nothing else is posted this way. A signed-in
+ * person's saves go through the dashboard's server actions.
+ */
+export async function POST(request: NextRequest, context: Context) {
+  const { path } = await context.params;
+  const url = target(path, request.nextUrl.search);
+  if (!url || path.length !== 2 || path[0] !== "public" || path[1].startsWith("_")) {
+    return Response.json({ error: "Only a public form is sent this way. Records are saved through the dashboard." }, { status: 405 });
+  }
+  const length = Number(request.headers.get("content-length") ?? 0);
+  if (length > 1024 * 1024) return Response.json({ error: "That is too much to send." }, { status: 413 });
+  const body = await request.text();
+  if (body.length > 1024 * 1024) return Response.json({ error: "That is too much to send." }, { status: 413 });
+  return forward(url, { method: "POST", body, headers: { "Content-Type": "application/json" } }, false, true);
 }
 
 export async function PUT(request: NextRequest, context: Context) {
   const { path } = await context.params;
   const url = target(path, request.nextUrl.search);
-  if (!url || path[0] !== "_nevela" || path[1] !== "uploads") {
+  // A visitor's file for a public form: /api/public/_nevela/uploads/<Resource>/<field>.
+  const forVisitor = path.length === 5 && path[0] === "public" && path[1] === "_nevela" && path[2] === "uploads";
+  if (!url || !(forVisitor || (path[0] === "_nevela" && path[1] === "uploads"))) {
     return Response.json({ error: "Only uploads are sent this way. Records are saved through the dashboard." }, { status: 405 });
   }
-  // Nothing is read until it is known who is sending it and how much there is.
-  if (!(await sessionToken())) return Response.json({ error: "Sign in first." }, { status: 401 });
+  // Nothing is read until it is known who is sending it and how much there is. (A visitor
+  // is nobody, by design: Laravel takes their file only for a field a public form lists.)
+  if (!forVisitor && !(await sessionToken())) return Response.json({ error: "Sign in first." }, { status: 401 });
   const length = Number(request.headers.get("content-length"));
   if (!Number.isFinite(length) || length <= 0) return Response.json({ error: "The upload didn't say how large it is." }, { status: 411 });
   if (length > MAX_UPLOAD_BYTES) {
@@ -91,5 +124,5 @@ export async function PUT(request: NextRequest, context: Context) {
   if (body.byteLength > MAX_UPLOAD_BYTES) {
     return Response.json({ error: "That file is too large to upload." }, { status: 413 });
   }
-  return forward(url, { method: "PUT", body, headers: { "Content-Type": request.headers.get("content-type") ?? "application/octet-stream" } }, true);
+  return forward(url, { method: "PUT", body, headers: { "Content-Type": request.headers.get("content-type") ?? "application/octet-stream" } }, !forVisitor, forVisitor);
 }