@next-buildr/payload 2.0.1 → 3.0.0-rc.0

package/dist/plugin/hooks/author-code.test.js

@@ -0,0 +1,285 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRegistryMeta, p, s, } from '@next-buildr/core';
+import { sqliteAdapter } from '@payloadcms/db-sqlite';
+import { buildConfig, getPayload } from 'payload';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { authorCodePermitted } from '../access.js';
+import { buildrPlugin } from '../index.js';
+import { resolveOptions } from '../options.js';
+import { BUILDR_WRITE } from '../write-guard.js';
+import { processLayout } from './process-layout.js';
+// Author code (ADR-026) is a server-side capability: the plugin `authorCode` option, resolved per
+// request, enforced on every write of a layout (the hook, the save endpoint, templates).
+const widget = {
+    type: 'buildr/widget',
+    version: 1,
+    label: 'Widget',
+    category: 'content',
+    props: {
+        title: p.text({ label: 'Title', default: 'Hello' }),
+        html: p.textarea({ format: 'html' }),
+    },
+    contentCategories: ['flow'],
+    styles: { groups: [] },
+    runtime: 'shared',
+    slots: {},
+};
+const page = {
+    ...widget,
+    type: 'buildr/page',
+    label: 'Page',
+    props: {},
+    capabilities: { root: true },
+    slots: { default: {} },
+};
+const meta = createRegistryMeta({ components: [page, widget] });
+const withAuthor = (extra, props = {}) => ({
+    schemaVersion: 1,
+    root: 'root',
+    nodes: {
+        root: { id: 'root', type: 'buildr/page', slots: { default: ['widget0001'] } },
+        widget0001: {
+            id: 'widget0001',
+            type: 'buildr/widget',
+            props: { title: s('a'), ...props },
+            ...extra,
+        },
+    },
+    components: { 'buildr/page': 1, 'buildr/widget': 1 },
+});
+const RED = { customCss: '& { color: red }' };
+const BLUE = { customCss: '& { color: blue }' };
+const HTML = { html: s('<p>x</p>') };
+const codes = (result) => result.ok ? [] : result.diagnostics.map((diagnostic) => diagnostic.code);
+describe('processLayout and author code', () => {
+    const limits = { maxNodes: 5000, maxBytes: 2_000_000 };
+    const registry = { meta };
+    it.each([
+        ['custom CSS', withAuthor(RED)],
+        ['classes', withAuthor({ classes: ['x'] })],
+        ['attributes', withAuthor({ attributes: { 'data-x': '1' } })],
+        ['an HTML prop', withAuthor({}, HTML)],
+    ])('rejects %s unless the request may write author code', (_name, doc) => {
+        expect(codes(processLayout(doc, { limits, registry }))).toEqual(['author.not-permitted']);
+        expect(codes(processLayout(doc, { limits, registry, allowAuthorCode: false }))).toEqual([
+            'author.not-permitted',
+        ]);
+        expect(processLayout(doc, { limits, registry, allowAuthorCode: true }).ok).toBe(true);
+    });
+    it('accepts a document without author code', () => {
+        expect(processLayout(withAuthor({}), { limits, registry }).ok).toBe(true);
+    });
+    it('still checks the code itself when it is permitted', () => {
+        const bad = withAuthor({ customCss: '@import "x";' });
+        expect(codes(processLayout(bad, { limits, registry, allowAuthorCode: true }))).toEqual([
+            'author.invalid',
+        ]);
+    });
+    it('lets stored author code be saved unchanged and removed, never added or changed', () => {
+        const stored = withAuthor(RED, HTML);
+        const options = { limits, registry, previous: stored };
+        expect(processLayout(stored, options).ok).toBe(true);
+        // removed
+        expect(processLayout(withAuthor({}), options).ok).toBe(true);
+        // changed or added
+        expect(codes(processLayout(withAuthor(BLUE, HTML), options))).toEqual(['author.not-permitted']);
+        expect(codes(processLayout(withAuthor(RED, { html: s('<p>y</p>') }), options))).toEqual([
+            'author.not-permitted',
+        ]);
+        expect(codes(processLayout(withAuthor({ ...RED, classes: ['c'] }, HTML), options))).toEqual([
+            'author.not-permitted',
+        ]);
+        // nothing stored, or a stored value that is not a document, excuses nothing
+        expect(codes(processLayout(stored, { limits, registry, previous: withAuthor({}, {}) }))).toEqual(['author.not-permitted']);
+        expect(codes(processLayout(stored, { limits, registry, previous: 'nonsense' }))).toEqual([
+            'author.not-permitted',
+        ]);
+        expect(codes(processLayout(stored, { limits, registry, previous: undefined }))).toEqual([
+            'author.not-permitted',
+        ]);
+    });
+});
+describe('processLayout without a registry', () => {
+    // With no registry the html props of a component are unknown; the names Text uses are still guarded.
+    const limits = { maxNodes: 5000, maxBytes: 2_000_000 };
+    it.each([
+        ['an html prop', withAuthor({}, HTML)],
+        ['mode html', withAuthor({}, { mode: s('html') })],
+        ['html and mode html', withAuthor({}, { mode: s('html'), ...HTML })],
+        ['a bound html prop', withAuthor({}, { html: { kind: 'binding', path: 'page.title' } })],
+    ])('rejects %s unless the request may write author code', (_name, doc) => {
+        expect(codes(processLayout(doc, { limits }))).toEqual(['author.not-permitted']);
+        expect(codes(processLayout(doc, { limits, allowAuthorCode: false }))).toEqual([
+            'author.not-permitted',
+        ]);
+        expect(processLayout(doc, { limits, allowAuthorCode: true }).ok).toBe(true);
+    });
+    it('still rejects node fields, and accepts a plain document or a plain Text mode', () => {
+        expect(codes(processLayout(withAuthor(RED), { limits }))).toEqual(['author.not-permitted']);
+        expect(processLayout(withAuthor({}), { limits }).ok).toBe(true);
+        expect(processLayout(withAuthor({}, { mode: s('plain') }), { limits }).ok).toBe(true);
+    });
+    it('lets stored html be saved unchanged and removed, never added or changed', () => {
+        const stored = withAuthor({}, { mode: s('html'), ...HTML });
+        const options = { limits, previous: stored };
+        expect(processLayout(stored, options).ok).toBe(true);
+        expect(processLayout(withAuthor({}, { mode: s('plain') }), options).ok).toBe(true);
+        expect(codes(processLayout(withAuthor({}, { mode: s('html'), html: s('<p>y</p>') }), options))).toEqual(['author.not-permitted']);
+        expect(codes(processLayout(withAuthor({}, { mode: s('html') }), { limits }))).toEqual([
+            'author.not-permitted',
+        ]);
+        expect(codes(processLayout(stored, { limits, previous: withAuthor({}, { title: s('x') }) }))).toEqual(['author.not-permitted']);
+    });
+});
+describe('the authorCode option needs a registry', () => {
+    it('refuses anything but false at startup, like forms', () => {
+        expect(() => buildrPlugin({ collections: {}, authorCode: true })).toThrow(/registry/);
+        expect(() => buildrPlugin({ collections: {}, authorCode: () => true })).toThrow(/registry/);
+        expect(() => buildrPlugin({ collections: {}, authorCode: false })).not.toThrow();
+        expect(() => buildrPlugin({ collections: {} })).not.toThrow();
+        expect(() => buildrPlugin({ collections: {}, registry: { meta }, authorCode: true })).not.toThrow();
+    });
+});
+describe('authorCodePermitted', () => {
+    const req = (user) => ({ user });
+    const apiKey = req({ _strategy: 'api-key' });
+    it('is off by default and for anything but exactly true', async () => {
+        expect(resolveOptions({ collections: {} }).authorCode).toBe(false);
+        const off = { authorCode: false };
+        expect(await authorCodePermitted(off, req({ id: 1 }))).toBe(false);
+        const truthy = { authorCode: (() => 'yes') };
+        expect(await authorCodePermitted(truthy, req({ id: 1 }))).toBe(false);
+        expect(await authorCodePermitted({ authorCode: () => Promise.reject(new Error('x')) }, req())).toBe(false);
+    });
+    it('follows a boolean or a function of the request, and never grants an API key', async () => {
+        expect(await authorCodePermitted({ authorCode: true }, req({ id: 1 }))).toBe(true);
+        const admin = {
+            authorCode: ({ req }) => req.user?.role === 'admin',
+        };
+        expect(await authorCodePermitted(admin, req({ role: 'admin' }))).toBe(true);
+        expect(await authorCodePermitted(admin, req({ role: 'editor' }))).toBe(false);
+        expect(await authorCodePermitted(admin, req())).toBe(false);
+        expect(await authorCodePermitted({ authorCode: true }, apiKey)).toBe(false);
+        expect(await authorCodePermitted({ authorCode: async () => true }, apiKey)).toBe(false);
+    });
+});
+describe('the layout hook and author code', () => {
+    let dir;
+    let payload;
+    beforeAll(async () => {
+        dir = mkdtempSync(join(tmpdir(), 'buildr-payload-author-'));
+        const config = buildConfig({
+            secret: 'test-secret',
+            collections: [
+                {
+                    slug: 'pages',
+                    fields: [{ name: 'title', type: 'text' }],
+                    versions: { drafts: { autosave: true } },
+                },
+            ],
+            db: sqliteAdapter({ client: { url: `file:${join(dir, 'db.sqlite')}` } }),
+            plugins: [
+                buildrPlugin({
+                    collections: { pages: { context: 'page' } },
+                    registry: { meta },
+                    // Trusted only for requests that say so, as a host would decide from `req.user`.
+                    authorCode: ({ req }) => req.context['trusted'] === true,
+                }),
+            ],
+            typescript: { autoGenerate: false },
+        });
+        payload = await getPayload({ config, key: 'author-code' });
+    });
+    afterAll(() => {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Windows keeps the database file open a moment longer.
+        }
+    });
+    const write = (payload, data, id, trusted = false) => id === undefined
+        ? payload.create({ collection: 'pages', data, draft: true, context: { trusted } })
+        : payload.update({
+            collection: 'pages',
+            id,
+            data,
+            draft: true,
+            context: { [BUILDR_WRITE]: true, trusted },
+        });
+    // The message of the field error a rejected write carries ("layout" is all the top-level message says).
+    const fieldError = async (write) => {
+        const error = (await write.then(() => undefined, (caught) => caught));
+        return error?.data?.errors?.[0]?.message ?? '(the write was accepted)';
+    };
+    const nodeOf = async (payload, id) => (await payload.findByID({ collection: 'pages', id, draft: true })).layout.nodes['widget0001'];
+    it('rejects author code on create and on update for a request the option does not allow', async () => {
+        const off = payload;
+        await expect(fieldError(write(off, { title: 'A', layout: withAuthor(RED) }))).resolves.toMatch(/author code/i);
+        const doc = await write(off, { title: 'B' });
+        await expect(fieldError(write(off, { layout: withAuthor({}, HTML) }, doc.id))).resolves.toMatch(/author code/i);
+        expect(await nodeOf(off, doc.id)).toBeUndefined();
+        // Without author code the same save goes through.
+        await write(off, { layout: withAuthor({}) }, doc.id);
+        expect(await nodeOf(off, doc.id)).toBeDefined();
+    });
+    it('resolves the option per request and keeps stored author code saveable', async () => {
+        const trusting = payload;
+        await expect(fieldError(write(trusting, { title: 'C', layout: withAuthor(RED) }))).resolves.toMatch(/author code/i);
+        const doc = await write(trusting, { title: 'D', layout: withAuthor(RED) }, undefined, true);
+        expect((await nodeOf(trusting, doc.id))?.customCss).toBe(RED.customCss);
+        // Unchanged author code is saved without the capability (an edit elsewhere in the page).
+        await write(trusting, { layout: withAuthor(RED, { title: s('renamed') }) }, doc.id);
+        expect((await nodeOf(trusting, doc.id))?.customCss).toBe(RED.customCss);
+        // A change is not.
+        await expect(fieldError(write(trusting, { layout: withAuthor(BLUE) }, doc.id))).resolves.toMatch(/author code/i);
+        // A trusted request may change it, and anyone may remove it.
+        await write(trusting, { layout: withAuthor(BLUE) }, doc.id, true);
+        expect((await nodeOf(trusting, doc.id))?.customCss).toBe(BLUE.customCss);
+        await write(trusting, { layout: withAuthor({}) }, doc.id);
+        expect((await nodeOf(trusting, doc.id))?.customCss).toBeUndefined();
+    });
+    it('does not copy author code through duplicate, and does not restore it through restoreVersion', async () => {
+        const source = await write(payload, { title: 'E', layout: withAuthor(RED, HTML) }, undefined, true);
+        // A duplicate is a new document: the source's author code is not "already stored" for it.
+        await expect(fieldError(payload.duplicate({
+            collection: 'pages',
+            id: source.id,
+            draft: true,
+            context: { trusted: false },
+        }))).resolves.toMatch(/author code/i);
+        const all = await payload.find({
+            collection: 'pages',
+            draft: true,
+            limit: 100,
+            pagination: false,
+        });
+        expect(all.docs.filter((doc) => doc['title'] === 'E')).toHaveLength(1);
+        // A trusted request may duplicate it.
+        const trusted = await payload.duplicate({
+            collection: 'pages',
+            id: source.id,
+            draft: true,
+            context: { trusted: true },
+        });
+        expect((await nodeOf(payload, trusted.id))?.customCss).toBe(RED.customCss);
+        // restoreVersion by an untrusted request keeps the stored layout (the write guard), so code
+        // that a later trusted save removed does not come back.
+        await write(payload, { layout: withAuthor({}) }, source.id, true);
+        const versions = await payload.findVersions({
+            collection: 'pages',
+            where: { parent: { equals: source.id } },
+            sort: 'createdAt',
+            limit: 20,
+        });
+        const withCode = versions.docs.find((version) => version.version.layout?.nodes['widget0001']?.customCss !==
+            undefined);
+        expect(withCode).toBeDefined();
+        await payload
+            .restoreVersion({ collection: 'pages', id: String(withCode?.id), draft: true })
+            .catch(() => undefined);
+        expect((await nodeOf(payload, source.id))?.customCss).toBeUndefined();
+    });
+});

package/dist/plugin/hooks/layout-hook.d.ts

@@ -5,5 +5,5 @@ import type { ResolvedOptions } from '../options.ts';
  * builder keeps the stored value, which is not re-validated), then `processLayout` for the writes
  * that are allowed to change it. Invalid documents are rejected with a field error the admin shows.
  */
-export declare const layoutHook: (options: Pick<ResolvedOptions, 'registry' | 'limits'>) => FieldHook;
+export declare const layoutHook: (options: Pick<ResolvedOptions, 'registry' | 'limits' | 'authorCode'>) => FieldHook;
 //# sourceMappingURL=layout-hook.d.ts.map

package/dist/plugin/hooks/layout-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout-hook.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/layout-hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIrD;;;;GAIG;AACH,eAAO,MAAM,UAAU,YACX,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,QAAQ,CAAC,KAAG,SAsBxD,CAAC"}
+{"version":3,"file":"layout-hook.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/layout-hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,SAAS,CAAC;AAG1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIrD;;;;GAIG;AACH,eAAO,MAAM,UAAU,YACX,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAC,KAAG,SAgCvE,CAAC"}

package/dist/plugin/hooks/layout-hook.js

@@ -1,4 +1,5 @@
 import { ValidationError } from 'payload';
+import { authorCodePermitted } from '../access.js';
 import { configuredLocales } from '../locales.js';
 import { BUILDR_WRITE, writeGuard } from '../write-guard.js';
 import { describeDiagnostics, processLayout } from './process-layout.js';
@@ -7,7 +8,7 @@ import { describeDiagnostics, processLayout } from './process-layout.js';
  * builder keeps the stored value, which is not re-validated), then `processLayout` for the writes
  * that are allowed to change it. Invalid documents are rejected with a field error the admin shows.
  */
-export const layoutHook = (options) => (args) => {
+export const layoutHook = (options) => async (args) => {
     const guarded = writeGuard('layout')(args);
     const accepted = args.operation === 'create' || args.req.context[BUILDR_WRITE] === true;
     if (!accepted)
@@ -16,8 +17,17 @@ export const layoutHook = (options) => (args) => {
     if (args.operation === 'update' && guarded === undefined)
         return undefined;
     const result = processLayout(guarded, {
-        ...options,
+        registry: options.registry,
+        limits: options.limits,
         locales: configuredLocales(args.req.payload.config),
+        // Author code (ADR-026) needs the host's permission for this request; what is already
+        // stored can be saved unchanged without it.
+        allowAuthorCode: await authorCodePermitted(options, args.req),
+        // A new document has no stored layout. On a duplicate Payload hands over the source document
+        // as `originalDoc`; trusting it would copy another document's author code without the permission.
+        previous: args.operation === 'create'
+            ? undefined
+            : args.originalDoc?.['layout'],
     });
     if (!result.ok) {
         throw new ValidationError({

package/dist/plugin/hooks/process-layout.d.ts

@@ -9,6 +9,16 @@ export interface ProcessLayoutOptions {
     };
     /** The languages of the site: an `l10n` key outside them is reported (a warning, kept). */
     readonly locales?: LocaleConfig | undefined;
+    /**
+     * Whether this request may write author code (ADR-026), as `authorCodePermitted` resolved it (not the `authorCode` option itself).
+     * Absent means no.
+     */
+    readonly allowAuthorCode?: boolean | undefined;
+    /**
+     * The layout as it is stored now. Without `allowAuthorCode`, author code on a node is accepted only
+     * when this document's node with the same id carries exactly the same.
+     */
+    readonly previous?: unknown;
 }
 export type ProcessedLayout = {
     readonly ok: true;

package/dist/plugin/hooks/process-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-layout.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/process-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,KAAK,eAAe,EAGpB,KAAK,UAAU,EACf,KAAK,cAAc,EAMpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC9F;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE,2EAA2E;AAC3E,eAAO,MAAM,cAAc,WAAY,oBAAoB,CAAC,QAAQ,CAAC,KAAG,cAItE,CAAC;AAOH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAyC5F;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAO9E"}
+{"version":3,"file":"process-layout.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/process-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,KAAK,eAAe,EAIpB,KAAK,UAAU,EACf,KAAK,cAAc,EASpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC9F;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE,2EAA2E;AAC3E,eAAO,MAAM,cAAc,WAAY,oBAAoB,CAAC,QAAQ,CAAC,KAAG,cAItE,CAAC;AAOH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAoE5F;AAoFD,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAO9E"}

package/dist/plugin/hooks/process-layout.js

@@ -1,4 +1,4 @@
-import { createEmptyDocument, DEFAULT_DOCUMENT_LIMITS, migrateComponents, migrateDocument, parseDocument, validateDocument, } from '@next-buildr/core';
+import { checkAuthorCode, createEmptyDocument, DEFAULT_DOCUMENT_LIMITS, htmlPropNames, migrateComponents, migrateDocument, parseDocument, validateDocument, } from '@next-buildr/core';
 /** The limits of the plugin can only tighten the defaults of the model. */
 export const documentLimits = (limits) => ({
     ...DEFAULT_DOCUMENT_LIMITS,
@@ -55,8 +55,101 @@ export function processLayout(value, options) {
             return { ok: false, diagnostics: errors };
         warnings.push(...result.issues);
     }
+    // Author code (ADR-026) is checked on every write, with the capability the host resolved for
+    // this request. Without it, a node may carry only the author code it already carried in the
+    // stored document: adding or changing any is rejected, so data written while the capability was
+    // on can still be saved unchanged (and removed), but nothing new gets in.
+    const author = checkAuthorCode(doc, { authorCode: options.allowAuthorCode === true }, registry?.meta);
+    const before = previousNodes(options.previous);
+    const authorErrors = author.filter((issue) => issue.severity === 'error' &&
+        !(issue.code === 'author.not-permitted' &&
+            unchangedAuthorCode(doc, before, issue.details?.['nodeId'], registry?.meta)));
+    // Without a registry the html props of a component are unknown, so `checkAuthorCode` cannot see
+    // them. Fail closed on the names Text uses: an `html` prop, or `mode: 'html'`, may not be added or
+    // changed by a request that may not write author code.
+    if (registry === undefined && options.allowAuthorCode !== true) {
+        authorErrors.push(...unregisteredHtmlErrors(doc, before));
+    }
+    if (authorErrors.length > 0)
+        return { ok: false, diagnostics: authorErrors };
+    warnings.push(...author.filter((issue) => issue.severity !== 'error'));
     return { ok: true, doc, warnings };
 }
+/** The nodes of a stored layout, or none when it is absent or not shaped like a document. */
+function previousNodes(previous) {
+    if (typeof previous !== 'object' || previous === null)
+        return {};
+    const nodes = previous.nodes;
+    return typeof nodes === 'object' && nodes !== null && !Array.isArray(nodes)
+        ? nodes
+        : {};
+}
+/** Key-order independent text form of a JSON value, for comparing. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** A node's author code only: its three node fields and the values of its HTML props. */
+function authorPart(node, meta) {
+    const props = Object.fromEntries(htmlPropNames(meta?.get(node.type))
+        .filter((name) => node.props !== undefined && Object.hasOwn(node.props, name))
+        .map((name) => [name, node.props?.[name]]));
+    return canonical({
+        customCss: node.customCss,
+        classes: node.classes,
+        attributes: node.attributes,
+        props,
+    });
+}
+/** The props that could carry author HTML when no registry says which ones do: `html`, and `mode` when it is `'html'`. */
+function unregisteredHtmlPart(node) {
+    const props = node.props;
+    if (props === undefined)
+        return undefined;
+    const html = Object.hasOwn(props, 'html') ? props['html'] : undefined;
+    const mode = Object.hasOwn(props, 'mode') ? props['mode'] : undefined;
+    const htmlMode = mode !== undefined && canonical(mode).includes('"html"');
+    if (html === undefined && !htmlMode)
+        return undefined;
+    return canonical({ html, mode: htmlMode ? mode : undefined });
+}
+/** One `author.not-permitted` error per node whose possible HTML differs from the stored node of the same id and type. */
+function unregisteredHtmlErrors(doc, before) {
+    const out = [];
+    for (const [id, node] of Object.entries(doc.nodes)) {
+        const now = unregisteredHtmlPart(node);
+        if (now === undefined)
+            continue;
+        const was = Object.hasOwn(before, id) ? before[id] : undefined;
+        if (was !== undefined && was.type === node.type && unregisteredHtmlPart(was) === now)
+            continue;
+        out.push({
+            code: 'author.not-permitted',
+            message: `Node "${id}" carries HTML (an "html" prop or mode "html"), which this host does not allow.`,
+            severity: 'error',
+            path: ['nodes', id],
+            details: { nodeId: id },
+        });
+    }
+    return out;
+}
+/** Whether `nodeId` carries exactly the author code it carried in the stored document. */
+function unchangedAuthorCode(doc, before, nodeId, meta) {
+    if (typeof nodeId !== 'string')
+        return false;
+    const now = Object.hasOwn(doc.nodes, nodeId) ? doc.nodes[nodeId] : undefined;
+    const was = Object.hasOwn(before, nodeId) ? before[nodeId] : undefined;
+    if (now === undefined || was === undefined || was.type !== now.type)
+        return false;
+    return authorPart(now, meta) === authorPart(was, meta);
+}
 /** A readable one-line-per-problem message for the admin UI (`code` and, when known, where). */
 export function describeDiagnostics(diagnostics) {
     return diagnostics

package/dist/plugin/hooks/read-layout.d.ts

@@ -13,5 +13,5 @@ export type ReadLayout = {
  * read-only when a component was written by newer code than this build knows (ADR-014).
  * Validation is not repeated here: a stored document was validated when it was written.
  */
-export declare function readLayout(value: unknown, options: ProcessLayoutOptions): ReadLayout;
+export declare function readLayout(value: unknown, options: Pick<ProcessLayoutOptions, 'registry' | 'limits'>): ReadLayout;
 //# sourceMappingURL=read-layout.d.ts.map

package/dist/plugin/hooks/read-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-layout.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/read-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAKhB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,UAAU,CA6BpF"}
+{"version":3,"file":"read-layout.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/read-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAKhB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,UAAU,GAAG,QAAQ,CAAC,GACzD,UAAU,CA6BZ"}

package/dist/plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,MAAM,EAAE,MAAM,SAAS,CAAC;AAahE,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/F,YAAY,EACV,UAAU,EACV,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOhD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAoG/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,MAAM,EAAE,MAAM,SAAS,CAAC;AAchE,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/F,YAAY,EACV,UAAU,EACV,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOhD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAyH/D"}

package/dist/plugin/index.js

@@ -2,6 +2,7 @@ import { formSubmissionsCollection } from './collections/form-submissions.js';
 import { templatesCollection } from './collections/templates.js';
 import { buildrEndpoints } from './endpoints/index.js';
 import { buildrFields, RESERVED_FIELDS, RESERVED_MCP_FIELDS, TEMPLATES_COLLECTION, } from './fields.js';
+import { createCaptchaGate, createTurnstileVerifier } from './forms/captcha.js';
 import { isAllowedRecipient } from './forms/notify.js';
 import { createMemoryRateLimiter } from './forms/rate-limit.js';
 import { layoutHook } from './hooks/layout-hook.js';
@@ -28,6 +29,11 @@ export function buildrPlugin(input) {
     if (forms.enabled && options.registry === undefined) {
         throw new Error('buildrPlugin: forms need the "registry" option (the form schema is derived from it)');
     }
+    // Author code is checked against the registry's html props (ADR-026); without one only a coarse
+    // name check runs, so anything but `false` is refused rather than half enforced.
+    if (options.authorCode !== false && options.registry === undefined) {
+        throw new Error('buildrPlugin: authorCode needs the "registry" option (the HTML props it checks are read from it)');
+    }
     const stray = forms.notifyTo.find((address) => !isAllowedRecipient(address, forms.notifyAllowlist));
     if (stray !== undefined) {
         throw new Error(`buildrPlugin: forms.notifyTo "${stray}" is not in forms.notifyAllowlist`);
@@ -38,6 +44,19 @@ export function buildrPlugin(input) {
     const writeLimiter = options.mcp.enabled
         ? (options.mcp.rateLimiter ?? createMemoryRateLimiter(options.mcp.rateLimit))
         : undefined;
+    const hostRateLimiter = forms.rateLimiter;
+    const captcha = forms.captcha === undefined
+        ? undefined
+        : {
+            verifier: createTurnstileVerifier({
+                secretKey: forms.captcha.secretKey,
+            }),
+            rateLimiter: hostRateLimiter
+                ? { hit: (key) => hostRateLimiter.hit(`captcha:${key}`) }
+                : createMemoryRateLimiter({ ...forms.rateLimit, failClosed: true }),
+            gate: createCaptchaGate(forms.captcha.maxInFlight),
+            hostnames: forms.captcha.hostnames,
+        };
     return (config) => {
         const collections = config.collections ?? [];
         const authSlugs = collections.filter((c) => Boolean(c.auth)).map((c) => c.slug);
@@ -76,7 +95,7 @@ export function buildrPlugin(input) {
             ...config,
             endpoints: [
                 ...(config.endpoints ?? []),
-                ...buildrEndpoints({ options, rateLimiter, writeLimiter }),
+                ...buildrEndpoints({ options, rateLimiter, writeLimiter, captcha }),
             ],
             collections: [
                 ...collections.map((collection) => {

package/dist/plugin/options.d.ts

@@ -36,6 +36,16 @@ export declare const optionsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     forms: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
+        captcha: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodDefault<z.ZodLiteral<"turnstile">>;
+            secretKey: z.ZodString;
+            hostnames: z.ZodArray<z.ZodString>;
+            maxInFlight: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        clientIp: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            header: z.ZodString;
+            hops: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodCustom<(req: PayloadRequest) => string | undefined, (req: PayloadRequest) => string | undefined>]>>;
         notifyAllowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
         notifyTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
         rateLimit: z.ZodDefault<z.ZodObject<{
@@ -44,6 +54,7 @@ export declare const optionsSchema: z.ZodObject<{
         }, z.core.$strip>>;
         rateLimiter: z.ZodOptional<z.ZodCustom<RateLimiter, RateLimiter>>;
     }, z.core.$strip>>;
+    authorCode: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<AccessFn, AccessFn>]>>;
     access: z.ZodDefault<z.ZodObject<{
         edit: z.ZodOptional<z.ZodCustom<AccessFn, AccessFn>>;
         publish: z.ZodOptional<z.ZodCustom<AccessFn, AccessFn>>;

package/dist/plugin/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/plugin/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKzD,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B;AACD,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAExE,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACvD;AAoBD,eAAO,MAAM,aAAa;;;;;;;;;8CAdT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqHjD,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE7D,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,eAAe,CAS1E"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/plugin/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKzD,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B;AACD,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAExE,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACvD;AAoBD,eAAO,MAAM,aAAa;;;;;;;;;8CAdT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;8CAqEhC,cAAc,KAAK,MAAM,GAAG,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmGtD,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE7D,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,eAAe,CAY1E"}

package/dist/plugin/options.js

@@ -39,6 +39,35 @@ export const optionsSchema = z.object({
         .object({
         /** Adds `buildr-form-submissions` and the public submission endpoint (needs `registry`). */
         enabled: z.boolean().default(false),
+        captcha: z
+            .object({
+            provider: z.literal('turnstile').default('turnstile'),
+            secretKey: z.string().min(1),
+            hostnames: z
+                .array(z
+                .string()
+                .max(253)
+                .regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/)
+                .refine((value) => value === value.trim(), 'must be a hostname'))
+                .min(1),
+            maxInFlight: z.number().int().min(1).max(1024).default(16),
+        })
+            .strict()
+            .optional(),
+        clientIp: z
+            .union([
+            z
+                .object({
+                header: z
+                    .string()
+                    .regex(/^[a-z0-9-]{1,64}$/)
+                    .refine((value) => value === value.trim(), 'must be a header name'),
+                hops: z.number().int().positive().default(1),
+            })
+                .strict(),
+            fn(),
+        ])
+            .optional(),
         /** Who a notification may go to: exact addresses or domains (`@example.com`). */
         notifyAllowlist: z.array(z.string()).default([]),
         /** Notified about every submission; each must match `notifyAllowlist`. */
@@ -56,6 +85,18 @@ export const optionsSchema = z.object({
             value !== null &&
             typeof value.hit === 'function', 'must be a rate limiter')
             .optional(),
+    })
+        .superRefine((forms, ctx) => {
+        if (forms.captcha === undefined)
+            return;
+        if (!forms.enabled)
+            ctx.addIssue({ code: 'custom', path: ['captcha'], message: 'requires forms.enabled' });
+        if (forms.clientIp === undefined)
+            ctx.addIssue({
+                code: 'custom',
+                path: ['clientIp'],
+                message: 'required with forms.captcha',
+            });
     })
         .default({
         enabled: false,
@@ -63,6 +104,13 @@ export const optionsSchema = z.object({
         notifyTo: [],
         rateLimit: { limit: 5, windowMs: 60_000 },
     }),
+    /**
+     * Whether author code (ADR-026: custom CSS, classes, attributes and Text HTML) may be saved:
+     * `true`, `false` (the default) or a function that decides per request, like `access.*`. It is
+     * never granted to API-key requests. Without it a save that adds or changes author code is
+     * rejected; author code already stored can still be saved unchanged.
+     */
+    authorCode: z.union([z.boolean(), fn()]).default(false),
     access: z
         .object({
         edit: fn().optional(),
@@ -115,7 +163,7 @@ export function resolveOptions(input) {
     const parsed = optionsSchema.safeParse(input);
     if (!parsed.success) {
         const problems = parsed.error.issues
-            .map((issue) => `  - ${issue.path.join('.') || '(options)'}: ${issue.message}`)
+            .map((issue) => `  - ${issue.path.join('.') || '(options)'}: ${issue.code === 'unrecognized_keys' && issue.path[0] === 'forms' && (issue.path[1] === 'captcha' || issue.path[1] === 'clientIp') ? 'unrecognized option' : issue.message}`)
             .join('\n');
         throw new Error(`buildrPlugin: invalid options\n${problems}`);
     }